The recursive implementation of vim.lsp.diagnostic.get() applied
`diagnostic_vim_to_lsp` twice, and the second time gave wrong
results because of the unexpected format.
Fixes https://github.com/neovim/neovim/issues/15689
These links were actually defined backwards: the highlight groups
actually being used for display are the new "Diagnostic*" groups, so
linking the old "LspDiagnostics*" groups to these does absolutely
nothing, since there is nothing actually being highlighted with the
LspDiagnostics* groups.
These links were made in an attempt to preserve backward compatibility
with existing colorschemes. We could reverse the links to maintain this
preservation, but then that disallows us from actually defining default
values for the new highlight groups.
Instead, just remove the links and be done with the old LspDiagnostics*
highlight groups.
This is not technically a breaking change: the breaking change already
happened in #15585, but this PR just makes that explicit.
## Overview
- Move vim.lsp.diagnostic to vim.diagnostic
- Refactor client ids to diagnostic namespaces
- Update tests
- Write/update documentation and function signatures
Currently, non-LSP diagnostics in Neovim must hook into the LSP subsystem. This
is what e.g. null-ls and nvim-lint do. This is necessary because none of the
diagnostic API is exposed separately from the LSP subsystem.
This commit addresses this by generalizing the diagnostic subsystem beyond the
scope of LSP. The `vim.lsp.diagnostic` module is now simply a specific
diagnostic producer and primarily maintains the interface between LSP clients
and the broader diagnostic API.
The current diagnostic API uses "client ids" which only makes sense in the
context of LSP. We replace "client ids" with standard API namespaces generated
from `nvim_create_namespace`.
This PR is *mostly* backward compatible (so long as plugins are only using the
publicly documented API): LSP diagnostics will continue to work as usual, as
will pseudo-LSP clients like null-ls and nvim-lint. However, the latter can now
use the new interface, which looks something like this:
```lua
-- The namespace *must* be given a name. Anonymous namespaces will not work with diagnostics
local ns = vim.api.nvim_create_namespace("foo")
-- Generate diagnostics
local diagnostics = generate_diagnostics()
-- Set diagnostics for the current buffer
vim.diagnostic.set(ns, diagnostics, bufnr)
```
Some public facing API utility methods were removed and internalized directly in `vim.diagnostic`:
* `vim.lsp.util.diagnostics_to_items`
## API Design
`vim.diagnostic` contains most of the same API as `vim.lsp.diagnostic` with
`client_id` simply replaced with `namespace`, with some differences:
* Generally speaking, functions that modify or add diagnostics require a namespace as their first argument, e.g.
```lua
vim.diagnostic.set({namespace}, {bufnr}, {diagnostics}[, {opts}])
```
while functions that read or query diagnostics do not (although in many cases one may be supplied optionally):
```lua
vim.diagnostic.get({bufnr}[, {namespace}])
```
* We use our own severity levels to decouple `vim.diagnostic` from LSP. These
are designed similarly to `vim.log.levels` and currently include:
```lua
vim.diagnostic.severity.ERROR
vim.diagnostic.severity.WARN
vim.diagnostic.severity.INFO
vim.diagnostic.severity.HINT
```
In practice, these match the LSP diagnostic severity levels exactly, but we
should treat this as an interface and not assume that they are the same. The
"translation" between the two severity types is handled transparently in
`vim.lsp.diagnostic`.
* The actual "diagnostic" data structure is: (**EDIT:** Updated 2021-09-09):
```lua
{
lnum = <number>,
col = <number>,
end_lnum = <number>,
end_col = <number>,
severity = <vim.diagnostic.severity>,
message = <string>
}
```
This differs from the LSP definition of a diagnostic, so we transform them in
the handler functions in vim.lsp.diagnostic.
## Configuration
The `vim.lsp.with` paradigm still works for configuring how LSP diagnostics are
displayed, but this is a specific use-case for the `publishDiagnostics` handler.
Configuration with `vim.diagnostic` is instead done with the
`vim.diagnostic.config` function:
```lua
vim.diagnostic.config({
virtual_text = true,
signs = false,
underline = true,
update_in_insert = true,
severity_sort = false,
}[, namespace])
```
(or alternatively passed directly to `set()` or `show()`.)
When the `namespace` argument is `nil`, settings are set globally (i.e. for
*all* diagnostic namespaces). This is what user's will typically use for their
local configuration. Diagnostic producers can also set configuration options for
their specific namespace, although this is generally discouraged in order to
respect the user's global settings. All of the values in the table passed to
`vim.diagnostic.config()` are resolved in the same way that they are in
`on_publish_diagnostics`; that is, the value can be a boolean, a table, or
a function:
```lua
vim.diagnostic.config({
virtual_text = function(namespace, bufnr)
-- Only enable virtual text in buffer 3
return bufnr == 3
end,
})
```
## Misc Notes
* `vim.diagnostic` currently depends on `vim.lsp.util` for floating window
previews. I think this is okay for now, although ideally we'd want to decouple
these completely.
This generalizes diagnostic handling outside of just the scope of LSP.
LSP clients are now a specific case of a diagnostic producer, but the
diagnostic subsystem is decoupled from the LSP subsystem (or will be,
eventually).
More discussion at [1].
[1]: https://github.com/neovim/neovim/pull/15585
* Simplify rpc encode/decode messages to rpc.send/rcp.receive
* Make missing handlers message throw a warning
* Clean up formatting style in log
* Move all non-RPC loop messages to trace instead of debug
* Add format func option to log to allow newlines in per log entry
Previously, the handler signature was:
function(err, method, params, client_id, bufnr, config)
In order to better support external plugins that wish to extend the
protocol, there is other information which would be advantageous to
forward to the client, such as the original params of the request that
generated the callback.
In order to do this, we would need to break symmetry of the handlers, to
add an additional "params" as the 7th argument.
Instead, this PR changes the signature of the handlers to:
function(err, result, ctx, config)
where ctx (the context) includes params, client_id, and bufnr. This also leaves
flexibility for future use-cases.
BREAKING_CHANGE: changes the signature of the built-in client handlers, requiring
updating handler calls
Declaration, type-definition, and implementation capabilities were
previously disabled if the client received table output from the server
capabilities. The workDoneProgress capability is sent for many servers
for all supported capabilities as part of this table. Default to setting
capability to table instead of false.
The official developer documentation in in :h dev-lua-doc specifies to
use "--@" for special/magic tokens. However, this format is not
consistent with EmmyLua notation (used by some Lua language servers) nor
with the C version of the magic docstring tokens which use three comment
characters.
Further, the code base is currently split between usage of "--@",
"---@", and "--- @". In an effort to remain consistent, change all Lua
magic tokens to use "---@" and update the developer documentation
accordingly.
Add a new function to redraw diagnostics from the current diagnostic
cache, without receiving a "publishDiagnostics" message from the server.
This is already being done in two places in the Lua stdlib, so this
function unifies that functionality in addition to providing it to third
party plugins.
An example use case for this could be a command or key-binding for
toggling diagnostics virtual text. The virtual text configuration option
can be toggled using `vim.lsp.with` followed by
`vim.lsp.diagnostic.redraw()` to immediately redraw the diagnostics
with the updated setting.
The handlers for textDocument/references, textDocument/documentSymbol,
and workspace/symbol open their results in the quickfix list by default
and are not configurable. They are also incompatible with `vim.lsp.with`
as they do not accept a configuration parameter.
Add a `config` parameter to the handler for these three messages which
allows them to be configured with `vim.lsp.with`. Additionally, add a
new configuration option 'loclist' that, when true, causes these
handlers to open their results in the location list rather than the
quickfix list.
Passing `nil` is equivalent to passing 0, i.e. it simply uses the
current buffer number.
This fixes a bug when vim.lsp.diagnostic.disable() is called without
arguments.
Add two new methods to allow diagnostics to be disabled (and re-enabled)
in the current buffer. When diagnostics are disabled they are simply not
displayed to the user, but they are still sent by the server and
processed by the client.
Disabling diagnostics can be helpful in a number of scenarios. For
example, if one is working on a buffer with an overwhelming amount of
diagnostic warnings it can be helpful to simply disable diagnostics
without disabling the LSP client entirely. This also allows users more
flexibility on when and how they may want diagnostic information to be
displayed. For example, some users may not want to display diagnostic
information until after the buffer is first written.
the `textDocument/rangeFormatting` nad `textDocument/formatting` did not
pass bufnr to apply_text_edits, meaning edits were applied to
the user's currently active buffer. This could result in text being
applied to the wrong buffer.
ipairs terminates on the first nil index when iterating over table keys:
for i,k in ipairs( {[1] = 'test', [3] = 'test'} ) do
print(i, k)
end
prints:
1 test
Instead, use pairs which continues iterating over the entire table:
for i,k in pairs( {[1] = 'test', [3] = 'test'} ) do
print(i, k)
end
prints:
1 test
3 test
`return err_message(tostring(err))` caused errors to be printed as
`table: 0x123456789` instead of showing the error code and error
message.
This also removes some `if err` blocks that never got called because at
the end of `handlers.lua` all the handlers are wrapped with logic that
adds generic error handling.
Adds indentation that matches the number prefix to ensure diagnostic
messages spawning multiple lines align.
Before:
Diagnostics:
1. • Variable not in scope: red :: t0 -> t
• Perhaps you meant one of these:
‘rem’ (imported from Prelude), ‘read’ (imported from Prelude),
‘pred’ (imported from Prelude)
2. • Variable not in scope: repeDoubleColon :: [Char] -> t0
• Perhaps you meant ‘replaceDoubleColon’ (line 32)
After:
Diagnostics:
1. • Variable not in scope: red :: t0 -> t
• Perhaps you meant one of these:
‘rem’ (imported from Prelude), ‘read’ (imported from Prelude),
‘pred’ (imported from Prelude)
2. • Variable not in scope: repeDoubleColon :: [Char] -> t0
• Perhaps you meant ‘replaceDoubleColon’ (line 32)
