feat(diagnostic): revert default behaviour of goto_next/prev()

Follow-up to #28490

Problem:

The new behaviour of goto_next/prev() of navigating to the next highest
severity doesn't work well when diagnostic providers have different
interpretations of severities. E.g. the user may be blocked from
navigating to a useful LSP warning, due to some linter error.

Solution:

The behaviour of next highest severity is now a hidden option
`_highest = true`. We can revisit how to integrate this behaviour
during the 0.11 cycle.

1 files changed, 35 insertions, 24 deletions

diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index b34541c72e..67ce331891 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -76,7 +76,7 @@ local M = {}
 --- before lower severities (e.g. ERROR is displayed before WARN).
 --- Options:
 ---   - {reverse}? (boolean) Reverse sort order
---- (default: `false)
+--- (default: `false`)
 --- @field severity_sort? boolean|{reverse?:boolean}
 
 --- @class (private) vim.diagnostic.OptsResolved
@@ -812,6 +812,29 @@ local function set_list(loclist, opts)
   end
 end
 
+--- 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.
+--- @param diagnostics vim.Diagnostic[]
+local function filter_highest(diagnostics)
+  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
+
 --- @param position {[1]: integer, [2]: integer}
 --- @param search_forward boolean
 --- @param bufnr integer
@@ -823,29 +846,13 @@ local function next_diagnostic(position, search_forward, bufnr, opts, namespace)
   bufnr = get_bufnr(bufnr)
   local wrap = if_nil(opts.wrap, true)
 
-  local diagnostics =
-    get_diagnostics(bufnr, vim.tbl_extend('keep', opts, { namespace = namespace }), true)
+  local get_opts = vim.deepcopy(opts)
+  get_opts.namespace = get_opts.namespace or namespace
 
-  -- 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)
+  local diagnostics = get_diagnostics(bufnr, get_opts, true)
 
-    -- 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
+  if opts._highest then
+    filter_highest(diagnostics)
   end
 
   local line_diagnostics = diagnostic_lines(diagnostics)
@@ -1191,8 +1198,12 @@ end
 --- (default: `true`)
 --- @field wrap? boolean
 ---
---- See |diagnostic-severity|. If `nil`, go to the diagnostic with the highest severity.
---- @field severity? vim.diagnostic.Severity
+--- See |diagnostic-severity|.
+--- @field severity? vim.diagnostic.SeverityFilter
+---
+--- Go to the diagnostic with the highest severity.
+--- (default: `false`)
+--- @field package _highest? boolean
 ---
 --- If `true`, call |vim.diagnostic.open_float()| after moving.
 --- If a table, pass the table as the {opts} parameter to |vim.diagnostic.open_float()|.