How mfussenegger/nvim-lint works
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)