Merge remote-tracking branch 'upstream/master' into userreg

32 files changed, 2578 insertions, 573 deletions

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 28e5897aa9..da8764fbd4 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -36,6 +36,7 @@ for k, v in pairs({
   ui = true,
   health = true,
   fs = true,
+  secure = true,
 }) do
   vim._submodules[k] = v
 end
@@ -122,7 +123,7 @@ do
   --- (such as the |TUI|) pastes text into the editor.
   ---
   --- Example: To remove ANSI color codes when pasting:
-  --- <pre>
+  --- <pre>lua
   --- vim.paste = (function(overridden)
   ---   return function(lines, phase)
   ---     for i,line in ipairs(lines) do
@@ -167,7 +168,8 @@ do
         local line1 = lines[1]:gsub('(%c)', '\022%1')
         -- nvim_input() is affected by mappings,
         -- so use nvim_feedkeys() with "n" flag to ignore mappings.
-        vim.api.nvim_feedkeys(line1, 'n', true)
+        -- "t" flag is also needed so the pasted text is saved in cmdline history.
+        vim.api.nvim_feedkeys(line1, 'nt', true)
       end
       return true
     end
@@ -278,7 +280,7 @@ end
 --- command.
 ---
 --- Example:
---- <pre>
+--- <pre>lua
 ---   vim.cmd('echo 42')
 ---   vim.cmd([[
 ---     augroup My_group
@@ -389,7 +391,7 @@ end
 ---@param pos2 integer[] (line, column) tuple marking end of region
 ---@param regtype string type of selection, see |setreg()|
 ---@param inclusive boolean indicating whether the selection is end-inclusive
----@return table<integer, {}> region lua table of the form {linenr = {startcol,endcol}}
+---@return table region Table of the form `{linenr = {startcol,endcol}}`
 function vim.region(bufnr, pos1, pos2, regtype, inclusive)
   if not vim.api.nvim_buf_is_loaded(bufnr) then
     vim.fn.bufload(bufnr)
@@ -416,11 +418,16 @@ function vim.region(bufnr, pos1, pos2, regtype, inclusive)
       c2 = c1 + regtype:sub(2)
       -- and adjust for non-ASCII characters
       bufline = vim.api.nvim_buf_get_lines(bufnr, l, l + 1, true)[1]
-      if c1 < #bufline then
+      local utflen = vim.str_utfindex(bufline, #bufline)
+      if c1 <= utflen then
         c1 = vim.str_byteindex(bufline, c1)
+      else
+        c1 = #bufline + 1
       end
-      if c2 < #bufline then
+      if c2 <= utflen then
         c2 = vim.str_byteindex(bufline, c2)
+      else
+        c2 = #bufline + 1
       end
     else
       c1 = (l == pos1[1]) and pos1[2] or 0
@@ -739,7 +746,7 @@ end
 
 ---Prints given arguments in human-readable format.
 ---Example:
----<pre>
+---<pre>lua
 ---  -- Print highlight group Normal and store it's contents in a variable.
 ---  local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
 ---</pre>
diff --git a/runtime/lua/vim/_init_packages.lua b/runtime/lua/vim/_init_packages.lua
index 19c8608732..0c4ee8636d 100644
--- a/runtime/lua/vim/_init_packages.lua
+++ b/runtime/lua/vim/_init_packages.lua
@@ -56,6 +56,9 @@ setmetatable(vim, {
     if vim._submodules[key] then
       t[key] = require('vim.' .. key)
       return t[key]
+    elseif key == 'inspect_pos' or key == 'show_pos' then
+      require('vim._inspector')
+      return t[key]
     elseif vim.startswith(key, 'uri_') then
       local val = require('vim.uri')[key]
       if val ~= nil then
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
new file mode 100644
index 0000000000..f46a525910
--- /dev/null
+++ b/runtime/lua/vim/_inspector.lua
@@ -0,0 +1,238 @@
+---@class InspectorFilter
+---@field syntax boolean include syntax based highlight groups (defaults to true)
+---@field treesitter boolean include treesitter based highlight groups (defaults to true)
+---@field extmarks boolean|"all" include extmarks. When `all`, then extmarks without a `hl_group` will also be included (defaults to true)
+---@field semantic_tokens boolean include semantic tokens (defaults to true)
+local defaults = {
+  syntax = true,
+  treesitter = true,
+  extmarks = true,
+  semantic_tokens = true,
+}
+
+---Get all the items at a given buffer position.
+---
+---Can also be pretty-printed with `:Inspect!`. *:Inspect!*
+---
+---@param bufnr? number defaults to the current buffer
+---@param row? number row to inspect, 0-based. Defaults to the row of the current cursor
+---@param col? number col to inspect, 0-based. Defaults to the col of the current cursor
+---@param filter? InspectorFilter (table|nil) a table with key-value pairs to filter the items
+---               - syntax (boolean): include syntax based highlight groups (defaults to true)
+---               - treesitter (boolean): include treesitter based highlight groups (defaults to true)
+---               - extmarks (boolean|"all"): include extmarks. When `all`, then extmarks without a `hl_group` will also be included (defaults to true)
+---               - semantic_tokens (boolean): include semantic tokens (defaults to true)
+---@return {treesitter:table,syntax:table,extmarks:table,semantic_tokens:table,buffer:number,col:number,row:number} (table) a table with the following key-value pairs. Items are in "traversal order":
+---               - treesitter: a list of treesitter captures
+---               - syntax: a list of syntax groups
+---               - semantic_tokens: a list of semantic tokens
+---               - extmarks: a list of extmarks
+---               - buffer: the buffer used to get the items
+---               - row: the row used to get the items
+---               - col: the col used to get the items
+function vim.inspect_pos(bufnr, row, col, filter)
+  filter = vim.tbl_deep_extend('force', defaults, filter or {})
+
+  bufnr = bufnr or 0
+  if row == nil or col == nil then
+    -- get the row/col from the first window displaying the buffer
+    local win = bufnr == 0 and vim.api.nvim_get_current_win() or vim.fn.bufwinid(bufnr)
+    if win == -1 then
+      error('row/col is required for buffers not visible in a window')
+    end
+    local cursor = vim.api.nvim_win_get_cursor(win)
+    row, col = cursor[1] - 1, cursor[2]
+  end
+  bufnr = bufnr == 0 and vim.api.nvim_get_current_buf() or bufnr
+
+  local results = {
+    treesitter = {},
+    syntax = {},
+    extmarks = {},
+    semantic_tokens = {},
+    buffer = bufnr,
+    row = row,
+    col = col,
+  }
+
+  -- resolve hl links
+  ---@private
+  local function resolve_hl(data)
+    if data.hl_group then
+      local hlid = vim.api.nvim_get_hl_id_by_name(data.hl_group)
+      local name = vim.fn.synIDattr(vim.fn.synIDtrans(hlid), 'name')
+      data.hl_group_link = name
+    end
+    return data
+  end
+
+  -- treesitter
+  if filter.treesitter then
+    for _, capture in pairs(vim.treesitter.get_captures_at_pos(bufnr, row, col)) do
+      capture.hl_group = '@' .. capture.capture
+      table.insert(results.treesitter, resolve_hl(capture))
+    end
+  end
+
+  -- syntax
+  if filter.syntax then
+    for _, i1 in ipairs(vim.fn.synstack(row + 1, col + 1)) do
+      table.insert(results.syntax, resolve_hl({ hl_group = vim.fn.synIDattr(i1, 'name') }))
+    end
+  end
+
+  -- semantic tokens
+  if filter.semantic_tokens then
+    for _, token in ipairs(vim.lsp.semantic_tokens.get_at_pos(bufnr, row, col) or {}) do
+      token.hl_groups = {
+        type = resolve_hl({ hl_group = '@' .. token.type }),
+        modifiers = vim.tbl_map(function(modifier)
+          return resolve_hl({ hl_group = '@' .. modifier })
+        end, token.modifiers or {}),
+      }
+      table.insert(results.semantic_tokens, token)
+    end
+  end
+
+  -- extmarks
+  if filter.extmarks then
+    for ns, nsid in pairs(vim.api.nvim_get_namespaces()) do
+      if ns:find('vim_lsp_semantic_tokens') ~= 1 then
+        local extmarks = vim.api.nvim_buf_get_extmarks(bufnr, nsid, 0, -1, { details = true })
+        for _, extmark in ipairs(extmarks) do
+          extmark = {
+            ns_id = nsid,
+            ns = ns,
+            id = extmark[1],
+            row = extmark[2],
+            col = extmark[3],
+            opts = resolve_hl(extmark[4]),
+          }
+          local end_row = extmark.opts.end_row or extmark.row -- inclusive
+          local end_col = extmark.opts.end_col or (extmark.col + 1) -- exclusive
+          if
+            (filter.extmarks == 'all' or extmark.opts.hl_group) -- filter hl_group
+            and (row >= extmark.row and row <= end_row) -- within the rows of the extmark
+            and (row > extmark.row or col >= extmark.col) -- either not the first row, or in range of the col
+            and (row < end_row or col < end_col) -- either not in the last row or in range of the col
+          then
+            table.insert(results.extmarks, extmark)
+          end
+        end
+      end
+    end
+  end
+  return results
+end
+
+---Show all the items at a given buffer position.
+---
+---Can also be shown with `:Inspect`. *:Inspect*
+---
+---@param bufnr? number defaults to the current buffer
+---@param row? number row to inspect, 0-based. Defaults to the row of the current cursor
+---@param col? number col to inspect, 0-based. Defaults to the col of the current cursor
+---@param filter? InspectorFilter (table|nil) see |vim.inspect_pos()|
+function vim.show_pos(bufnr, row, col, filter)
+  local items = vim.inspect_pos(bufnr, row, col, filter)
+
+  local lines = { {} }
+
+  ---@private
+  local function append(str, hl)
+    table.insert(lines[#lines], { str, hl })
+  end
+
+  ---@private
+  local function nl()
+    table.insert(lines, {})
+  end
+
+  ---@private
+  local function item(data, comment)
+    append('  - ')
+    append(data.hl_group, data.hl_group)
+    append(' ')
+    if data.hl_group ~= data.hl_group_link then
+      append('links to ', 'MoreMsg')
+      append(data.hl_group_link, data.hl_group_link)
+      append(' ')
+    end
+    if comment then
+      append(comment, 'Comment')
+    end
+    nl()
+  end
+
+  -- treesitter
+  if #items.treesitter > 0 then
+    append('Treesitter', 'Title')
+    nl()
+    for _, capture in ipairs(items.treesitter) do
+      item(capture, capture.lang)
+    end
+    nl()
+  end
+
+  if #items.semantic_tokens > 0 then
+    append('Semantic Tokens', 'Title')
+    nl()
+    for _, token in ipairs(items.semantic_tokens) do
+      local client = vim.lsp.get_client_by_id(token.client_id)
+      client = client and (' (' .. client.name .. ')') or ''
+      item(token.hl_groups.type, 'type' .. client)
+      for _, modifier in ipairs(token.hl_groups.modifiers) do
+        item(modifier, 'modifier' .. client)
+      end
+    end
+    nl()
+  end
+
+  -- syntax
+  if #items.syntax > 0 then
+    append('Syntax', 'Title')
+    nl()
+    for _, syn in ipairs(items.syntax) do
+      item(syn)
+    end
+    nl()
+  end
+  -- extmarks
+  if #items.extmarks > 0 then
+    append('Extmarks', 'Title')
+    nl()
+    for _, extmark in ipairs(items.extmarks) do
+      if extmark.opts.hl_group then
+        item(extmark.opts, extmark.ns)
+      else
+        append('  - ')
+        append(extmark.ns, 'Comment')
+        nl()
+      end
+    end
+    nl()
+  end
+
+  if #lines[#lines] == 0 then
+    table.remove(lines)
+  end
+
+  local chunks = {}
+  for _, line in ipairs(lines) do
+    vim.list_extend(chunks, line)
+    table.insert(chunks, { '\n' })
+  end
+  if #chunks == 0 then
+    chunks = {
+      {
+        'No items found at position '
+          .. items.row
+          .. ','
+          .. items.col
+          .. ' in buffer '
+          .. items.buffer,
+      },
+    }
+  end
+  vim.api.nvim_echo(chunks, false, {})
+end
diff --git a/runtime/lua/vim/_meta.lua b/runtime/lua/vim/_meta.lua
index 9c7972873e..104f29c4c0 100644
--- a/runtime/lua/vim/_meta.lua
+++ b/runtime/lua/vim/_meta.lua
@@ -526,7 +526,7 @@ local function create_option_accessor(scope)
 
   return setmetatable({}, {
     __index = function(_, k)
-      return make_option(k, a.nvim_get_option_value(k, { scope = scope }))
+      return make_option(k, a.nvim_get_option_value(k, {}))
     end,
 
     __newindex = function(_, k, v)
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 84091fbf0e..6fd000a029 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -1,7 +1,8 @@
-local if_nil = vim.F.if_nil
+local api, if_nil = vim.api, vim.F.if_nil
 
 local M = {}
 
+---@enum DiagnosticSeverity
 M.severity = {
   ERROR = 1,
   WARN = 2,
@@ -47,11 +48,11 @@ local bufnr_and_namespace_cacher_mt = {
 
 local diagnostic_cache
 do
-  local group = vim.api.nvim_create_augroup('DiagnosticBufWipeout', {})
+  local group = api.nvim_create_augroup('DiagnosticBufWipeout', {})
   diagnostic_cache = setmetatable({}, {
     __index = function(t, bufnr)
       assert(bufnr > 0, 'Invalid buffer number')
-      vim.api.nvim_create_autocmd('BufWipeout', {
+      api.nvim_create_autocmd('BufWipeout', {
         group = group,
         buffer = bufnr,
         callback = function()
@@ -245,25 +246,12 @@ end)()
 ---@private
 local function get_bufnr(bufnr)
   if not bufnr or bufnr == 0 then
-    return vim.api.nvim_get_current_buf()
+    return api.nvim_get_current_buf()
   end
   return bufnr
 end
 
 ---@private
-local function is_disabled(namespace, bufnr)
-  local ns = M.get_namespace(namespace)
-  if ns.disabled then
-    return true
-  end
-
-  if type(diagnostic_disabled[bufnr]) == 'table' then
-    return diagnostic_disabled[bufnr][namespace]
-  end
-  return diagnostic_disabled[bufnr]
-end
-
----@private
 local function diagnostic_lines(diagnostics)
   if not diagnostics then
     return {}
@@ -299,7 +287,7 @@ end
 ---@private
 local function restore_extmarks(bufnr, last)
   for ns, extmarks in pairs(diagnostic_cache_extmarks[bufnr]) do
-    local extmarks_current = vim.api.nvim_buf_get_extmarks(bufnr, ns, 0, -1, { details = true })
+    local extmarks_current = api.nvim_buf_get_extmarks(bufnr, ns, 0, -1, { details = true })
     local found = {}
     for _, extmark in ipairs(extmarks_current) do
       -- nvim_buf_set_lines will move any extmark to the line after the last
@@ -312,7 +300,7 @@ local function restore_extmarks(bufnr, last)
       if not found[extmark[1]] then
         local opts = extmark[4]
         opts.id = extmark[1]
-        pcall(vim.api.nvim_buf_set_extmark, bufnr, ns, extmark[2], extmark[3], opts)
+        pcall(api.nvim_buf_set_extmark, bufnr, ns, extmark[2], extmark[3], opts)
       end
     end
   end
@@ -322,7 +310,7 @@ end
 local function save_extmarks(namespace, bufnr)
   bufnr = get_bufnr(bufnr)
   if not diagnostic_attached_buffers[bufnr] then
-    vim.api.nvim_buf_attach(bufnr, false, {
+    api.nvim_buf_attach(bufnr, false, {
       on_lines = function(_, _, _, _, _, last)
         restore_extmarks(bufnr, last - 1)
       end,
@@ -333,7 +321,7 @@ local function save_extmarks(namespace, bufnr)
     diagnostic_attached_buffers[bufnr] = true
   end
   diagnostic_cache_extmarks[bufnr][namespace] =
-    vim.api.nvim_buf_get_extmarks(bufnr, namespace, 0, -1, { details = true })
+    api.nvim_buf_get_extmarks(bufnr, namespace, 0, -1, { details = true })
 end
 
 local registered_autocmds = {}
@@ -366,8 +354,8 @@ local function schedule_display(namespace, bufnr, args)
 
   local key = make_augroup_key(namespace, bufnr)
   if not registered_autocmds[key] then
-    local group = vim.api.nvim_create_augroup(key, { clear = true })
-    vim.api.nvim_create_autocmd(insert_leave_auto_cmds, {
+    local group = api.nvim_create_augroup(key, { clear = true })
+    api.nvim_create_autocmd(insert_leave_auto_cmds, {
       group = group,
       buffer = bufnr,
       callback = function()
@@ -384,7 +372,7 @@ local function clear_scheduled_display(namespace, bufnr)
   local key = make_augroup_key(namespace, bufnr)
 
   if registered_autocmds[key] then
-    vim.api.nvim_del_augroup_by_name(key)
+    api.nvim_del_augroup_by_name(key)
     registered_autocmds[key] = nil
   end
 end
@@ -399,7 +387,7 @@ local function get_diagnostics(bufnr, opts, clamp)
   -- Memoized results of buf_line_count per bufnr
   local buf_line_count = setmetatable({}, {
     __index = function(t, k)
-      t[k] = vim.api.nvim_buf_line_count(k)
+      t[k] = api.nvim_buf_line_count(k)
       return rawget(t, k)
     end,
   })
@@ -407,7 +395,7 @@ local function get_diagnostics(bufnr, opts, clamp)
   ---@private
   local function add(b, d)
     if not opts.lnum or d.lnum == opts.lnum then
-      if clamp and vim.api.nvim_buf_is_loaded(b) then
+      if clamp and api.nvim_buf_is_loaded(b) then
         local line_count = buf_line_count[b] - 1
         if
           d.lnum > line_count
@@ -428,32 +416,31 @@ local function get_diagnostics(bufnr, opts, clamp)
     end
   end
 
+  ---@private
+  local function add_all_diags(buf, diags)
+    for _, diagnostic in pairs(diags) do
+      add(buf, diagnostic)
+    end
+  end
+
   if namespace == nil and bufnr == nil then
     for b, t in pairs(diagnostic_cache) do
       for _, v in pairs(t) do
-        for _, diagnostic in pairs(v) do
-          add(b, diagnostic)
-        end
+        add_all_diags(b, v)
       end
     end
   elseif namespace == nil then
     bufnr = get_bufnr(bufnr)
     for iter_namespace in pairs(diagnostic_cache[bufnr]) do
-      for _, diagnostic in pairs(diagnostic_cache[bufnr][iter_namespace]) do
-        add(bufnr, diagnostic)
-      end
+      add_all_diags(bufnr, diagnostic_cache[bufnr][iter_namespace])
     end
   elseif bufnr == nil then
     for b, t in pairs(diagnostic_cache) do
-      for _, diagnostic in pairs(t[namespace] or {}) do
-        add(b, diagnostic)
-      end
+      add_all_diags(b, t[namespace] or {})
     end
   else
     bufnr = get_bufnr(bufnr)
-    for _, diagnostic in pairs(diagnostic_cache[bufnr][namespace] or {}) do
-      add(bufnr, diagnostic)
-    end
+    add_all_diags(bufnr, diagnostic_cache[bufnr][namespace] or {})
   end
 
   if opts.severity then
@@ -471,7 +458,7 @@ local function set_list(loclist, opts)
   local winnr = opts.winnr or 0
   local bufnr
   if loclist then
-    bufnr = vim.api.nvim_win_get_buf(winnr)
+    bufnr = api.nvim_win_get_buf(winnr)
   end
   -- Don't clamp line numbers since the quickfix list can already handle line
   -- numbers beyond the end of the buffer
@@ -483,7 +470,7 @@ local function set_list(loclist, opts)
     vim.fn.setqflist({}, ' ', { title = title, items = items })
   end
   if open then
-    vim.api.nvim_command(loclist and 'lopen' or 'botright copen')
+    api.nvim_command(loclist and 'lwindow' or 'botright cwindow')
   end
 end
 
@@ -492,7 +479,7 @@ local function next_diagnostic(position, search_forward, bufnr, opts, namespace)
   position[1] = position[1] - 1
   bufnr = get_bufnr(bufnr)
   local wrap = vim.F.if_nil(opts.wrap, true)
-  local line_count = vim.api.nvim_buf_line_count(bufnr)
+  local line_count = api.nvim_buf_line_count(bufnr)
   local diagnostics =
     get_diagnostics(bufnr, vim.tbl_extend('keep', opts, { namespace = namespace }), true)
   local line_diagnostics = diagnostic_lines(diagnostics)
@@ -506,7 +493,7 @@ local function next_diagnostic(position, search_forward, bufnr, opts, namespace)
       lnum = (lnum + line_count) % line_count
     end
     if line_diagnostics[lnum] and not vim.tbl_isempty(line_diagnostics[lnum]) then
-      local line_length = #vim.api.nvim_buf_get_lines(bufnr, lnum, lnum + 1, true)[1]
+      local line_length = #api.nvim_buf_get_lines(bufnr, lnum, lnum + 1, true)[1]
       local sort_diagnostics, is_next
       if search_forward then
         sort_diagnostics = function(a, b)
@@ -542,17 +529,17 @@ local function diagnostic_move_pos(opts, pos)
   opts = opts or {}
 
   local float = vim.F.if_nil(opts.float, true)
-  local win_id = opts.win_id or vim.api.nvim_get_current_win()
+  local win_id = opts.win_id or api.nvim_get_current_win()
 
   if not pos then
-    vim.api.nvim_echo({ { 'No more valid diagnostics to move to', 'WarningMsg' } }, true, {})
+    api.nvim_echo({ { 'No more valid diagnostics to move to', 'WarningMsg' } }, true, {})
     return
   end
 
-  vim.api.nvim_win_call(win_id, function()
+  api.nvim_win_call(win_id, function()
     -- Save position in the window's jumplist
     vim.cmd("normal! m'")
-    vim.api.nvim_win_set_cursor(win_id, { pos[1] + 1, pos[2] })
+    api.nvim_win_set_cursor(win_id, { pos[1] + 1, pos[2] })
     -- Open folds under the cursor
     vim.cmd('normal! zv')
   end)
@@ -561,7 +548,7 @@ local function diagnostic_move_pos(opts, pos)
     local float_opts = type(float) == 'table' and float or {}
     vim.schedule(function()
       M.open_float(vim.tbl_extend('keep', float_opts, {
-        bufnr = vim.api.nvim_win_get_buf(win_id),
+        bufnr = api.nvim_win_get_buf(win_id),
         scope = 'cursor',
         focus = false,
       }))
@@ -578,12 +565,12 @@ end
 --- followed by namespace configuration, and finally global configuration.
 ---
 --- For example, if a user enables virtual text globally with
---- <pre>
+--- <pre>lua
 ---   vim.diagnostic.config({ virtual_text = true })
 --- </pre>
 ---
 --- and a diagnostic producer sets diagnostics with
---- <pre>
+--- <pre>lua
 ---   vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
 --- </pre>
 ---
@@ -613,16 +600,20 @@ end
 ---                       * spacing: (number) Amount of empty spaces inserted at the beginning
 ---                                  of the virtual text.
 ---                       * prefix: (string) Prepend diagnostic message with prefix.
+---                       * suffix: (string or function) Append diagnostic message with suffix.
+---                                 If a function, it must have the signature (diagnostic) ->
+---                                 string, where {diagnostic} is of type |diagnostic-structure|.
+---                                 This can be used to render an LSP diagnostic error code.
 ---                       * format: (function) A function that takes a diagnostic as input and
 ---                                 returns a string. The return value is the text used to display
 ---                                 the diagnostic. Example:
----                       <pre>
----                       function(diagnostic)
----                         if diagnostic.severity == vim.diagnostic.severity.ERROR then
----                           return string.format("E: %s", diagnostic.message)
+---                       <pre>lua
+---                         function(diagnostic)
+---                           if diagnostic.severity == vim.diagnostic.severity.ERROR then
+---                             return string.format("E: %s", diagnostic.message)
+---                           end
+---                           return diagnostic.message
 ---                         end
----                         return diagnostic.message
----                       end
 ---                       </pre>
 ---       - signs: (default true) Use signs for diagnostics. Options:
 ---                * severity: Only show signs for diagnostics matching the given severity
@@ -666,13 +657,13 @@ function M.config(opts, namespace)
 
   if namespace then
     for bufnr, v in pairs(diagnostic_cache) do
-      if vim.api.nvim_buf_is_loaded(bufnr) and v[namespace] then
+      if api.nvim_buf_is_loaded(bufnr) and v[namespace] then
         M.show(namespace, bufnr)
       end
     end
   else
     for bufnr, v in pairs(diagnostic_cache) do
-      if vim.api.nvim_buf_is_loaded(bufnr) then
+      if api.nvim_buf_is_loaded(bufnr) then
         for ns in pairs(v) do
           M.show(ns, bufnr)
         end
@@ -707,11 +698,11 @@ function M.set(namespace, bufnr, diagnostics, opts)
     set_diagnostic_cache(namespace, bufnr, diagnostics)
   end
 
-  if vim.api.nvim_buf_is_loaded(bufnr) then
+  if api.nvim_buf_is_loaded(bufnr) then
     M.show(namespace, bufnr, nil, opts)
   end
 
-  vim.api.nvim_exec_autocmds('DiagnosticChanged', {
+  api.nvim_exec_autocmds('DiagnosticChanged', {
     modeline = false,
     buffer = bufnr,
     data = { diagnostics = diagnostics },
@@ -726,7 +717,7 @@ function M.get_namespace(namespace)
   vim.validate({ namespace = { namespace, 'n' } })
   if not all_namespaces[namespace] then
     local name
-    for k, v in pairs(vim.api.nvim_get_namespaces()) do
+    for k, v in pairs(api.nvim_get_namespaces()) do
       if namespace == v then
         name = k
         break
@@ -751,6 +742,18 @@ function M.get_namespaces()
   return vim.deepcopy(all_namespaces)
 end
 
+---@class Diagnostic
+---@field buffer number
+---@field lnum number 0-indexed
+---@field end_lnum nil|number 0-indexed
+---@field col number 0-indexed
+---@field end_col nil|number 0-indexed
+---@field severity DiagnosticSeverity
+---@field message string
+---@field source nil|string
+---@field code nil|string
+---@field user_data nil|any arbitrary data plugins can add
+
 --- Get current diagnostics.
 ---
 ---@param bufnr number|nil Buffer number to get diagnostics from. Use 0 for
@@ -759,7 +762,7 @@ end
 ---                        - namespace: (number) Limit diagnostics to the given namespace.
 ---                        - lnum: (number) Limit diagnostics to the given line number.
 ---                        - severity: See |diagnostic-severity|.
----@return table A list of diagnostic items |diagnostic-structure|.
+---@return Diagnostic[] table A list of diagnostic items |diagnostic-structure|.
 function M.get(bufnr, opts)
   vim.validate({
     bufnr = { bufnr, 'n', true },
@@ -771,22 +774,23 @@ end
 
 --- Get the previous diagnostic closest to the cursor position.
 ---
----@param opts table See |vim.diagnostic.goto_next()|
----@return table Previous diagnostic
+---@param opts nil|table See |vim.diagnostic.goto_next()|
+---@return Diagnostic|nil Previous diagnostic
 function M.get_prev(opts)
   opts = opts or {}
 
-  local win_id = opts.win_id or vim.api.nvim_get_current_win()
-  local bufnr = vim.api.nvim_win_get_buf(win_id)
-  local cursor_position = opts.cursor_position or vim.api.nvim_win_get_cursor(win_id)
+  local win_id = opts.win_id or api.nvim_get_current_win()
+  local bufnr = api.nvim_win_get_buf(win_id)
+  local cursor_position = opts.cursor_position or api.nvim_win_get_cursor(win_id)
 
   return next_diagnostic(cursor_position, false, bufnr, opts, opts.namespace)
 end
 
 --- Return the position of the previous diagnostic in the current buffer.
 ---
----@param opts table See |vim.diagnostic.goto_next()|
----@return table Previous diagnostic position as a (row, col) tuple.
+---@param opts table|nil See |vim.diagnostic.goto_next()|
+---@return table|false Previous diagnostic position as a (row, col) tuple or false if there is no
+---                    prior diagnostic
 function M.get_prev_pos(opts)
   local prev = M.get_prev(opts)
   if not prev then
@@ -797,29 +801,30 @@ function M.get_prev_pos(opts)
 end
 
 --- Move to the previous diagnostic in the current buffer.
----@param opts table See |vim.diagnostic.goto_next()|
+---@param opts table|nil See |vim.diagnostic.goto_next()|
 function M.goto_prev(opts)
   return diagnostic_move_pos(opts, M.get_prev_pos(opts))
 end
 
 --- Get the nex