nvim-rulebook 📖

All-around helper for dealing with errors and diagnostics.

Features

Look up official rule documentation
Prettify unwieldy TypeScript error messages. Code blocks in the error message are formatted with prettier or biome if available.
Add inline-comments to ignore rules like // eslint disable-next-line some-rule. Supports previous line, same line, and enclosing lines.
Suppress formatting with inline comments of the respective formatter, such as // prettier-ignore.
Built-in support for more than 50 tools. Thus, this plugin requires zero configuration for most users.

Before error prettification	After error prettification

Supported sources
Installation
Usage
Configuration
- Base configuration
- Customize built-in sources
FAQ
Credits

Supported sources

You easily add a custom source via the plugin configuration. Please consider making a PR to add support for a source if it is missing.

Rule data for built-in support of linters and formatters

Rule lookup

ansible-lint
basedpyright
biome
clang-tidy
eslint
ltex_plus
LTeX
Lua Diagnostics.
markdownlint
pylint
Pyrefly
Pyright
quick-lint-js
Ruff
selene
shellcheck
stylelint
stylelintplus
swiftlint
ts
tsserver
ty
typescript
yamllint

Add ignore comment

alex
ansible-lint
ast-grep
basedpyright
biome
clang-tidy
clippy
codespell (requires setting --ignore-regex to ignore-regex=".*codespell-ignore$")
cspell
editorconfig-checker
EmmyLua
eslint
Harper
LTeX
ltex_plus
Lua Diagnostics. (source name for lua_ls)
markdownlint
mypy
pylint
Pyrefly
Pyright
Ruff
rust-analyzer
selene
shellcheck
spellwarn
stylelint
stylelintplus
swiftlint
Tombi
ts
tsserver
ty
typescript
typos (requires setting default.extend-ignore-re to [default] extend-ignore-re = ["[^\ ]*typos: ignore-line[^\n]*\n"])
vale-ls
vale
woke
yamllint

Suppress formatting

clang-format: c, cpp
prettier: css, html, javascript, javascriptreact, markdown, scss, svelte, typescript, typescriptreact, vue, yaml
ruff / black: python
stylua: lua

Prettify errors

Currently only supports the TypeScript LSP (ts_ls).

Take a look at this file to see how to add prettifiers for other sources. PRs are welcome.

Installation

Requirements

nvim 0.10+
Diagnostics provided by a source that supports Neovim's built-in diagnostics system. (nvim built-in LSP client, efm-langserver or nvim-lint are such sources.)

Recommended for error prettifying

treesitter parsers: TSInstall markdown markdown_inline
a markdown rendering plugin such as render-markdown or markview.nvim
prettier or biome available in PATH.

-- lazy.nvim
{ "chrisgrieser/nvim-rulebook" },

-- packer
use { "chrisgrieser/nvim-rulebook" }

Usage

You can use the commands via lua functions:

require("rulebook").ignoreRule()
require("rulebook").prettifyError()
require("rulebook").yankDiagnosticCode()
require("rulebook").suppressFormatter()
require("rulebook").prettifyError()

-- snippets to create keymaps, for your convenience
vim.keymap.set("n", "<leader>ri", function() require("rulebook").ignoreRule() end)
vim.keymap.set("n", "<leader>rl", function() require("rulebook").lookupRule() end)
vim.keymap.set("n", "<leader>ry", function() require("rulebook").yankDiagnosticCode() end)
vim.keymap.set({ "n", "x" }, "<leader>rf", function() require("rulebook").suppressFormatter() end)

vim.api.nvim_create_autocmd("Filetype", {
	pattern = { "typescript", "javascript" },
	group = vim.api.nvim_create_augroup("rulebook.prettify-ts-error", { clear = true }),
	callback = function(ctx)
		vim.keymap.set(
			"n",
			"<leader>rp",
			function() require("rulebook").prettifyError() end,
			{ buffer = ctx.buf }
		)
	end,
})

Alternatively, you can use the :Rulebook ex-command:

:Rulebook ignoreRule
:Rulebook lookupRule
:Rulebook yankDiagnosticCode
:Rulebook suppressFormatter
:Rulebook prettifyError

Note that :Rulebook suppressFormatter only supports normal mode. To add formatter-ignore comments for a line range, you need to use the lua function require("rulebook").suppressFormatter() from visual mode.

Configuration

Base configuration

The .setup() call is optional. You only need to add a config when you want to add or customize sources.

When adding your own source, you must add the exact, case-sensitive source name (for example, clang-tidy, not clang).

require("rulebook").setup = ({
	-- if no diagnostic is found in the current line, search this many lines forward
	forwSearchLines = 10,

	ignoreComments = {
		shellcheck = {
			comment = "# shellcheck disable=%s",
			location = "prevLine",
			multiRuleIgnore = true,
			multiRuleSeparator = ",",
		},
		-- ... (a full list of sources with builtin support can be found in the README)

		yourCustomSource = { -- exact, case-sensitive source-name
			---@type string|fun(vim.Diagnostic): string if string, "%s" will be replaced with the rule id
			comment = "// disabling-comment %s",

			---@type "prevLine"|"sameLine"|"encloseLine"|"inlineBeforeDiagnostic"|fun(vim.Diagnostic): string
			location = "sameLine",

			-- whether multiple rules can be ignored with one comment, defaults to `false`
			multiRuleIgnore = true,

			-- separator for multiple rule-ids, defaults to ", " (with space)
			multiRuleSeparator = ",",
		}

		-- if location is `encloseLine`, the comment needs to be a list of two strings
		anotherCustomSource = {
			location = "encloseLine",
			comment = { 
				"// disable-rule %s", 
				"// enable-rule %s",
			},
		}
	},

	ruleDocs = {
		selene = "https://kampfkarren.github.io/selene/lints/%s.html"
		-- ... (a full list of sources with builtin support can be found in the README)

		-- Search URL when no documentation definition is available for a
		-- diagnostic source. `%s` will be replaced with the diagnostic source and 
		-- the code/message.
		fallback = "https://www.google.com/search?q=%s",

		-- the key must be named exactly like `diagnostic.source` (case-sensitive!)
		-- * string: `%s` will be replaced with the rule id
		-- * function: will be called with the diagnostic object
		-- * `false`: disable rule docs, will use the fallback
		---@type string|false|fun(diag: vim.Diagnostic): string?
		yourCustomSource = "https://my-docs/%s.hthml",
		anotherCustomSource = function(diag)
			-- ...
			return url
		end,
	}

	suppressFormatter = {
		lua = {
			-- used for normal mode
			ignoreBlock = "-- stylua: ignore",

			---@type "prevLine"|"sameLine"|"encloseLine"|fun(): string
			location = "prevLine",

			-- used for visual mode
			ignoreRange = { "-- stylua: ignore start", "-- stylua: ignore end" },
		},
	}

	prettifyError = {
		---@type fun(vim.Diagnostic): string[]
		typescript = function(diag)
      -- ...
		end,
	}
})

nvim-rulebook uses vim.ui.select, so the appearance of the rule selection can be customized by using a UI plugin like snacks.nvim.

Customize built-in sources

Built-in sources can be customized by overwriting them in the configuration:

-- example: use `disable-line` instead of the default `disable-next-line` for eslint
require("rulebook").setup = {
	ignoreComments = {
		eslint = {
			comment = "// eslint-disable-line %s",
			location = "sameLine",
		},
	},
}

FAQ

How to configure diagnostic providers

This plugin requires that the diagnostic providers (the LSP or a linter integration tool like nvim-lint or efm-langserver) provide the source and code for the diagnostic.

Make sure that the source is named the same in the diagnostic source and in the nvim-rulebook config, including casing.
For nvim-lint, most linters should already be configured out of the box.
For efm-langserver, you have to set lintSource for the source name, and correctly configure the errorformat. Other than %l & %c (line number & column), this requires %n which efm langserver uses to fill in the diagnostic code. You can also use efmls-configs-nvim to configure those linters for you.

Important

Note that vim's errorformat only matches numbers for %n, which means it is not possible to parse diagnostic codes that consist of letters. One such case is the linter selene. To use those linters with nvim-rulebook you need to use nvim-lint which allows more flexible parsing.

-- example: configuring efm langserver for `markdownlint` in `/lsp/efm.lua`
return {
	filetypes = { "markdown" },
	settings = {
		languages = {
			markdown = {
				{
					lintSource = "markdownlint",
					lintCommand = "markdownlint $'{INPUT}'",
					lintStdin = false,
					lintIgnoreExitCode = true,
					lintFormats = {
						"%f:%l:%c MD%n/%m",
						"%f:%l MD%n/%m",
					},
				},
			},
		},
	},
}

How to directly ask an LLM about a rule

To ask an LLM about a rule, use a URL that opens a chat it for ruleDocs.fallback.

For ruleDocs.fallback, the %s placeholder will be replaced with the diagnostic source and the quoted code (or message, if no code is available), both URL-encoded.

-- example to use ChatGPT for rule lookup
require("rulebook").setup = ({
	ruleDocs = {
		fallback = "https://chatgpt.com/?q=Explain%20the%20following%20diagnostic%20error%3A%20%s"

		-- To use `fallback` instead of the builtin rule docs, overwrite the
		-- builtin one with `false`.
		typescript = false,
	}
})

How to display the availability of rule lookup

The function require("rulebook").hasDocs(diag), expects a diagnostic object and returns a boolean whether nvim-rulebook documentation for the respective diagnostic available. One use case for this is to add a visual indicator if there is a rule lookup available for a diagnostic (see vim.diagnostic.config).

vim.diagnostic.config {
	virtual_text = {
		suffix = function(diag) return require("rulebook").hasDocs(diag) and "  " or "" end,
	},
}

Credits

In my day job, I am a sociologist studying the social mechanisms underlying the digital economy. For my PhD project, I investigate the governance of the app economy and how software ecosystems manage the tension between innovation and compatibility. If you are interested in this subject, feel free to get in touch.

chrisgrieser/nvim-rulebook