feat(lsp): deprecate severity_limit

Problem:
  `vim.lsp.diagnostic.on_diagnostic` accepts an undocumented severity_limit
  option which is widely used.

Solution:
  Deprecate it in favour of `{min = severity}` used in `vim.diagnostic`.
  Since this is undocumented, the schedule for removal is accelerated to
  0.11.

runtime/doc/lsp.txt

@@ -1384,6 +1384,7 @@ on_diagnostic({_}, {result}, {ctx}, {config})
 <
 
     Parameters: ~
+      • {result}  (`lsp.DocumentDiagnosticReport`)
       • {ctx}     (`lsp.HandlerContext`)
       • {config}  (`table`) Configuration table (see
                   |vim.diagnostic.config()|).

runtime/lua/vim/lsp/diagnostic.lua

@@ -221,6 +221,13 @@ function M.get_namespace(client_id, is_pull)
   end
 end
 
+local function convert_severity(opt)
+  if type(opt) == 'table' and not opt.severity and opt.severity_limit then
+    vim.deprecate('severity_limit', '{min = severity} See vim.diagnostic.severity', '0.11')
+    opt.severity = { min = severity_lsp_to_vim(opt.severity_limit) }
+  end
+end
+
 --- |lsp-handler| for the method "textDocument/publishDiagnostics"
 ---
 --- See |vim.diagnostic.config()| for configuration options. Handler-specific
@@ -267,13 +274,8 @@ function M.on_publish_diagnostics(_, result, ctx, config)
 
   if config then
     for _, opt in pairs(config) do
-      if type(opt) == 'table' then
+      convert_severity(opt)
-        if not opt.severity and opt.severity_limit then
-          opt.severity = { min = severity_lsp_to_vim(opt.severity_limit) }
-        end
-      end
     end
-
     -- Persist configuration to ensure buffer reloads use the same
     -- configuration. To make lsp.with configuration work (See :help
     -- lsp-handler-configuration)
@@ -308,11 +310,14 @@ end
 --- )
 --- ```
 ---
+---@param result lsp.DocumentDiagnosticReport
 ---@param ctx lsp.HandlerContext
 ---@param config table Configuration table (see |vim.diagnostic.config()|).
 function M.on_diagnostic(_, result, ctx, config)
   local client_id = ctx.client_id
-  local uri = ctx.params.textDocument.uri
+  --- @type lsp.DocumentDiagnosticParams
+  local params = ctx.params
+  local uri = params.textDocument.uri
   local fname = vim.uri_to_fname(uri)
 
   if result == nil then
@@ -339,11 +344,8 @@ function M.on_diagnostic(_, result, ctx, config)
 
   if config then
     for _, opt in pairs(config) do
-      if type(opt) == 'table' and not opt.severity and opt.severity_limit then
+      convert_severity(opt)
-        opt.severity = { min = severity_lsp_to_vim(opt.severity_limit) }
-      end
     end
-
     -- Persist configuration to ensure buffer reloads use the same
     -- configuration. To make lsp.with configuration work (See :help
     -- lsp-handler-configuration)
@@ -381,34 +383,28 @@ end
 ---
 ---@param bufnr integer|nil The buffer number
 ---@param line_nr integer|nil The line number
----@param opts table|nil Configuration keys
+---@param opts {severity?:lsp.DiagnosticSeverity}?
----         - severity: (DiagnosticSeverity, default nil)
+---         - severity: (lsp.DiagnosticSeverity)
----             - Only return diagnostics with this severity. Overrides severity_limit
+---             - Only return diagnostics with this severity.
----         - severity_limit: (DiagnosticSeverity, default nil)
----             - Limit severity of diagnostics found. E.g. "Warning" means { "Error", "Warning" } will be valid.
 ---@param client_id integer|nil the client id
 ---@return table Table with map of line number to list of diagnostics.
 ---              Structured: { [1] = {...}, [5] = {.... } }
 ---@private
 function M.get_line_diagnostics(bufnr, line_nr, opts, client_id)
-  opts = opts or {}
+  convert_severity(opts)
-  if opts.severity then
+  local diag_opts = {} --- @type vim.diagnostic.GetOpts
-    opts.severity = severity_lsp_to_vim(opts.severity)
+
-  elseif opts.severity_limit then
+  if opts and opts.severity then
-    opts.severity = { min = severity_lsp_to_vim(opts.severity_limit) }
+    diag_opts.severity = severity_lsp_to_vim(opts.severity)
   end
 
   if client_id then
-    opts.namespace = M.get_namespace(client_id, false)
+    diag_opts.namespace = M.get_namespace(client_id, false)
   end
 
-  if not line_nr then
+  diag_opts.lnum = line_nr or (api.nvim_win_get_cursor(0)[1] - 1)
-    line_nr = vim.api.nvim_win_get_cursor(0)[1] - 1
-  end
 
-  opts.lnum = line_nr
+  return diagnostic_vim_to_lsp(vim.diagnostic.get(bufnr, diag_opts))
-
-  return diagnostic_vim_to_lsp(vim.diagnostic.get(bufnr, opts))
 end
 
 --- Clear diagnostics from pull based clients

test/functional/plugin/lsp/diagnostic_spec.lua

@@ -193,7 +193,7 @@ describe('vim.lsp.diagnostic', function()
           PublishDiagnostics = vim.lsp.with(vim.lsp.diagnostic.on_publish_diagnostics, {
             underline = false,
             virtual_text = {
-              severity_limit = ...
+              severity = { min = ... }
             },
           })
 
@@ -212,11 +212,11 @@ describe('vim.lsp.diagnostic', function()
       end
 
       -- No messages with Error or higher
-      eq(0, get_extmark_count_with_severity('Error'))
+      eq(0, get_extmark_count_with_severity('ERROR'))
 
       -- But now we don't filter it
-      eq(1, get_extmark_count_with_severity('Warning'))
+      eq(1, get_extmark_count_with_severity('WARN'))
-      eq(1, get_extmark_count_with_severity('Hint'))
+      eq(1, get_extmark_count_with_severity('HINT'))
     end)
 
     it('correctly handles UTF-16 offsets', function()