feat(diagnostic): goto functions jump to highest severity (#28490)

When the "severity" option is nil, vim.diagnostic.goto_next() and
vim.diagnostic.goto_prev() jump to the next diagnostic with the highest
severity.

3 files changed, 35 insertions, 5 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index b7d5cb0b2c..32c9959f5a 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -389,8 +389,9 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
                             |nvim_win_get_cursor()|.
       • {wrap}?             (`boolean`, default: `true`) Whether to loop
                             around file or not. Similar to 'wrapscan'.
-      • {severity}          (`vim.diagnostic.Severity`) See
-                            |diagnostic-severity|.
+      • {severity}?         (`vim.diagnostic.Severity`) See
+                            |diagnostic-severity|. If `nil`, go to the
+                            diagnostic with the highest severity.
       • {float}?            (`boolean|vim.diagnostic.Opts.Float`, default:
                             `true`) If `true`, call
                             |vim.diagnostic.open_float()| after moving. If a
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 537542ee46..44d5ea39bf 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -387,6 +387,11 @@ The following changes to existing APIs or features add new behavior.
 • |vim.diagnostic.config()| now accepts a function for the virtual_text.prefix
   option, which allows for rendering e.g., diagnostic severities differently.
 
+• |vim.diagnostic.goto_next()| and |vim.diagnostic.goto_prev()| jump to the
+  diagnostic with the highest severity when the "severity" option is
+  unspecified. To use the old behavior, use: >lua
+    vim.diagnostic.goto_next({ severity = { min = vim.diagnostic.severity.HINT } })
+
 • Defaults:
   • On Windows 'isfname' does not include ":". Drive letters are handled
     correctly without it. (Use |gF| for filepaths suffixed with ":line:col").
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 3321b6ad71..1ae370e9b2 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -820,11 +820,35 @@ local function next_diagnostic(position, search_forward, bufnr, opts, namespace)
   position[1] = position[1] - 1
   bufnr = get_bufnr(bufnr)
   local wrap = if_nil(opts.wrap, true)
-  local line_count = api.nvim_buf_line_count(bufnr)
+
   local diagnostics =
     get_diagnostics(bufnr, vim.tbl_extend('keep', opts, { namespace = namespace }), true)
+
+  -- When severity is unset we jump to the diagnostic with the highest severity. First sort the
+  -- diagnostics by severity. The first diagnostic then contains the highest severity, and we can
+  -- discard all diagnostics with a lower severity.
+  if opts.severity == nil then
+    table.sort(diagnostics, function(a, b)
+      return a.severity < b.severity
+    end)
+
+    -- Find the first diagnostic where the severity does not match the highest severity, and remove
+    -- that element and all subsequent elements from the array
+    local worst = (diagnostics[1] or {}).severity
+    local len = #diagnostics
+    for i = 2, len do
+      if diagnostics[i].severity ~= worst then
+        for j = i, len do
+          diagnostics[j] = nil
+        end
+        break
+      end
+    end
+  end
+
   local line_diagnostics = diagnostic_lines(diagnostics)
 
+  local line_count = api.nvim_buf_line_count(bufnr)
   for i = 0, line_count do
     local offset = i * (search_forward and 1 or -1)
     local lnum = position[1] + offset
@@ -1165,8 +1189,8 @@ end
 --- (default: `true`)
 --- @field wrap? boolean
 ---
---- See |diagnostic-severity|.
---- @field severity vim.diagnostic.Severity
+--- See |diagnostic-severity|. If `nil`, go to the diagnostic with the highest severity.
+--- @field severity? vim.diagnostic.Severity
 ---
 --- If `true`, call |vim.diagnostic.open_float()| after moving.
 --- If a table, pass the table as the {opts} parameter to |vim.diagnostic.open_float()|.