feat(diagnostic)!: filter diagnostics by severity before passing to handlers (#30070)

BREAKING CHANGE: This changes the list of diagnostics that are passed to
a diagnostic handler. If a handler is already filtering by severity
itself then this won't break anything, since the handler's filtering
will become a no-op. But handlers which depend on receiving the full
list of diagnostics may break.

Note that diagnostics are only filtered if the handler's configuration
has the `severity` option set. If `severity` is not set, the handler
still receives the full list of diagnostics.

2 files changed, 9 insertions, 0 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 3437717467..7d97a18437 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -93,6 +93,10 @@ The {opts} table passed to a handler is the full set of configuration options
 values in the table are already resolved (i.e. if a user specifies a
 function for a config option, the function has already been evaluated).
 
+If a diagnostic handler is configured with a "severity" key then the list of
+diagnostics passed to that handler will be filtered using the value of that
+key (see example below).
+
 Nvim provides these handlers by default: "virtual_text", "signs", and
 "underline".
 
@@ -119,6 +123,9 @@ with |vim.notify()|: >lua
     vim.diagnostic.config({
       ["my/notify"] = {
         log_level = vim.log.levels.INFO
+
+        -- This handler will only receive "error" diagnostics.
+        severity = vim.diagnostic.severity.ERROR,
       }
     })
 <
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 181ae317e1..810f40180a 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -68,6 +68,8 @@ DIAGNOSTICS
 
 • The "underline" diagnostics handler sorts diagnostics by severity when using
   the "severity_sort" option.
+• Diagnostics are filtered by severity before being passed to a diagnostic
+  handler |diagnostic-handlers|.
 
 EDITOR