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.

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()|.