# mfussenegger/nvim-lint architecture

> Architecture diagram of the GitHub repository mfussenegger/nvim-lint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mfussenegger/nvim-lint
- Repository: https://github.com/mfussenegger/nvim-lint

## Overview

##### Project Type & Purpose
- This is an open-source Neovim plugin (“nvim-lint”) written in Lua.
- Its narrow scope: spawn external linters, parse their output, and report diagnostics via Neovim’s built-in `vim.diagnostic` module.

##### File Structure Analysis
- Top-level:
- `.github/` – CI workflows & linter configs.
- `lua/lint/` – core plugin code.
- `lua/lint/linters/` – one file per built-in linter.
- `lua/lint/parser.lua` & `lua/lint/util.lua` – parsing support and utilities.
- `doc/` – user-facing documentation.
- `spec/` – unit tests written for busted (Lua) or small Python snippets.
- `nvim-lint-scm-1.rockspec` – packaging metadata.
- `README.md` – overview, usage, and extensibility guide.

##### README Insights
- Describes how users configure `linters_by_ft`, hook into Neovim autocmds, and register custom linters.
- Emphasizes parser generators (`from_errorformat`, `from_pattern`) and customizing built-ins.
- Lists dozens of built-in linters, each mapping to an external binary.

##### Main Components
a. Neovim Host & Plugin Loader
– The Neovim runtime loads `lua/lint.lua` when required.
b. Lint Core Module (`lua/lint.lua`)
– Registry of linters, public API (`try_lint`, config).
c. Linters Registry (`linters_by_ft`)
– Maps filetypes to one or more linter modules.
d. Individual Linter Modules (`lua/lint/linters/*.lua`)
– Define `cmd`, `args`, `stdin`/`append_fname`, `parser`.
e. Parser Subsystem (`lua/lint/parser.lua`)
– Strategy pattern: `from_errorformat` or `from_pattern` generators.
f. Util Module (`lua/lint/util.lua`)
– Helper functions (wrapping diagnostics, environment handling).
g. External Linter Processes
– Shell commands invoked asynchronously; output captured on stdout/stderr.
h. Neovim Diagnostic API
– Consumes parsed diagnostics; displays virtual text, signs, etc.
i. User Configuration
– `require('lint').linters_by_ft` table & custom linter definitions in user’s `init.lua`.
j. CI & Testing
– `.github/workflows` for linting/tests; `spec/` for busted unit tests.
k. Documentation & Packaging
– `doc/` markdown, rockspec for luarocks packaging.

##### Relationships & Data Flow
- User event (e.g., `BufWritePost`) → autocmd → calls `lint.try_lint()`
- Core module looks up filetype in `linters_by_ft` → iterates configured linters
- For each linter:
- Spawn external process with `cmd + args`
- Output (stdout/stderr)
- Hand off to parser function → list of diagnostic objects
- Pass diagnostics to `vim.diagnostic.set()` via Neovim API → update UI
- Custom linters: user-provided table or function integrated into same registry

##### Architectural Patterns & Principles
- Plugin modularity: separation between core, linters, parser, util
- Registry/Strategy patterns: dynamic linter selection and parsing strategies
- Single Responsibility: each module does one job (spawning vs parsing vs reporting)
- Extensibility: users can override or extend built-ins, register new parsers

##### Technologies & Frameworks
- Lua (plugin code)
- Neovim API (`vim.api`, `vim.diagnostic`)
- External CLI linters (Shell processes)
- Parser generators (`lpeg` optional or Lua patterns)
- busted (unit testing)
- GitHub Actions (CI)
- Luarocks (packaging via `.rockspec`)

- Core Module, Linters Registry, Parser Subsystem, Util Module, External Linter Processes, Neovim API, User Config, CI & Tests
- From User Config → Core Module
- Core Module → Linters Registry → Individual Linter Modules → Spawn Process
- Process output → Parser → Diagnostic API
- Core Module ↔ Util Module
- Plugin Code (e.g., shades of green), External (gray), Neovim API (blue), CI/Tests (orange)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Main Vertical Flow
  UserConfig["User Configuration"]:::external
  UserConfig -->|hook/autocmd| Loader

  Loader["Neovim Host & Plugin Loader\n(lua/lint.lua)"]:::plugin
  Loader --> Core

  Core["Lint Core Module\n(lua/lint.lua)"]:::plugin
  Core --> Registry
  Core ---|uses| Util

  Registry["Linters Registry\n(lua/lint.lua)"]:::plugin
  Registry --> Linters

  Linters["Individual Linter Modules\n(lua/lint/linters/*.lua)"]:::plugin
  Linters -->|spawn cmd| ExtProc

  ExtProc["External Linter Processes"]:::external
  ExtProc -->|output| Parser

  Parser["Parser Subsystem\n(lua/lint/parser.lua)"]:::plugin
  Parser -->|parsed diagnostics| API

  API["Neovim Diagnostic API\n(vim.diagnostic)"]:::neovim

  Core ---|helpers| Util["Util Module\n(lua/lint/util.lua)"]:::plugin

  %% Side Components
  subgraph "CI & Tests"
    CI1["Lint CI\n(.github/workflows/linter.yml)"]:::ci
    CI2["Tests CI\n(.github/workflows/tests.yml)"]:::ci
    Tests["Unit Tests\n(spec/)"]:::ci
    CI1 --> Tests
    CI2 --> Tests
  end

  subgraph "Documentation & Packaging"
    DocDoc["Documentation\n(doc/lint.txt)"]:::doc
    DocReadme["README.md"]:::doc
    Pack["Packaging Metadata\n(nvim-lint-scm-1.rockspec)"]:::doc
    DocDoc --> Core
    DocReadme --> Core
    Pack -->|packaging| Core
  end

  %% Click Events
  click Loader "https://github.com/mfussenegger/nvim-lint/blob/master/lua/lint.lua"
  click Core "https://github.com/mfussenegger/nvim-lint/blob/master/lua/lint.lua"
  click Registry "https://github.com/mfussenegger/nvim-lint/blob/master/lua/lint.lua"
  click Util "https://github.com/mfussenegger/nvim-lint/blob/master/lua/lint/util.lua"
  click Parser "https://github.com/mfussenegger/nvim-lint/blob/master/lua/lint/parser.lua"
  click Linters "https://github.com/mfussenegger/nvim-lint/tree/master/lua/lint/linters"
  click CI1 "https://github.com/mfussenegger/nvim-lint/blob/master/.github/workflows/linter.yml"
  click CI2 "https://github.com/mfussenegger/nvim-lint/blob/master/.github/workflows/tests.yml"
  click Tests "https://github.com/mfussenegger/nvim-lint/tree/master/spec/"
  click DocDoc "https://github.com/mfussenegger/nvim-lint/blob/master/doc/lint.txt"
  click DocReadme "https://github.com/mfussenegger/nvim-lint/blob/master/README.md"
  click Pack "https://github.com/mfussenegger/nvim-lint/blob/master/nvim-lint-scm-1.rockspec"

  %% Styles
  classDef plugin fill:#e0ffe0,stroke:#0a0;
  classDef external fill:#f0f0f0,stroke:#888;
  classDef neovim fill:#e0f0ff,stroke:#00f;
  classDef ci fill:#fff8e0,stroke:#fa0;
  classDef doc fill:#e8e8ff,stroke:#00f;
```
