fix: resolve all remaining LuaLS diagnostics

41 files changed, 177 insertions, 104 deletions

diff --git a/.luarc.json b/.luarc.json
index 2bd57d6973..1a3cd5b378 100644
--- a/.luarc.json
+++ b/.luarc.json
@@ -10,7 +10,8 @@
       "${3rd}/luv/library"
     ],
     "ignoreDir": [
-      "test"
+      "test",
+      "_vim9script.lua"
     ],
     "checkThirdParty": "Disable"
   },
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 3d76c8c0ff..61d90e53c8 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -834,6 +834,12 @@ TSNode:range({include_bytes})                                 *TSNode:range()*
     Parameters: ~
       • {include_bytes}  (`boolean?`)
 
+    Return (multiple): ~
+        (`integer`)
+        (`integer`)
+        (`integer`)
+        (`integer`)
+
 TSNode:sexpr()                                                *TSNode:sexpr()*
     Get an S-expression representing the node as a string.
 
@@ -942,7 +948,7 @@ get_node_range({node_or_range})              *vim.treesitter.get_node_range()*
     Returns the node's range or an unpacked range table
 
     Parameters: ~
-      • {node_or_range}  (`TSNode|table`) Node or table of positions
+      • {node_or_range}  (`TSNode|Range4`) Node or table of positions
 
     Return (multiple): ~
         (`integer`) start_row
@@ -1181,7 +1187,7 @@ inspect({lang})                            *vim.treesitter.language.inspect()*
       • {lang}  (`string`) Language
 
     Return: ~
-        (`table`)
+        (`TSLangInfo`)
 
 register({lang}, {filetype})              *vim.treesitter.language.register()*
     Register a parser named {lang} to be used for {filetype}(s).
diff --git a/runtime/lua/coxpcall.lua b/runtime/lua/coxpcall.lua
index 75e7a43567..43e321eac3 100644
--- a/runtime/lua/coxpcall.lua
+++ b/runtime/lua/coxpcall.lua
@@ -31,22 +31,23 @@ end
 
 -- No need to do anything if pcall and xpcall are already safe.
 if isCoroutineSafe(pcall) and isCoroutineSafe(xpcall) then
-    copcall = pcall
-    coxpcall = xpcall
+    _G.copcall = pcall
+    _G.coxpcall = xpcall
     return { pcall = pcall, xpcall = xpcall, running = coroutine.running }
 end
 
 -------------------------------------------------------------------------------
 -- Implements xpcall with coroutines
 -------------------------------------------------------------------------------
-local performResume, handleReturnValue
+local performResume
 local oldpcall, oldxpcall = pcall, xpcall
 local pack = table.pack or function(...) return {n = select("#", ...), ...} end
 local unpack = table.unpack or unpack
 local running = coroutine.running
+--- @type table<thread,thread>
 local coromap = setmetatable({}, { __mode = "k" })
 
-function handleReturnValue(err, co, status, ...)
+local function handleReturnValue(err, co, status, ...)
     if not status then
         return false, err(debug.traceback(co, (...)), ...)
     end
@@ -61,11 +62,12 @@ function performResume(err, co, ...)
     return handleReturnValue(err, co, coroutine.resume(co, ...))
 end
 
+--- @diagnostic disable-next-line: unused-vararg
 local function id(trace, ...)
     return trace
 end
 
-function coxpcall(f, err, ...)
+function _G.coxpcall(f, err, ...)
     local current = running()
     if not current then
         if err == id then
@@ -88,6 +90,7 @@ function coxpcall(f, err, ...)
     end
 end
 
+--- @param coro? thread
 local function corunning(coro)
   if coro ~= nil then
     assert(type(coro)=="thread", "Bad argument; expected thread, got: "..type(coro))
@@ -105,7 +108,7 @@ end
 -- Implements pcall with coroutines
 -------------------------------------------------------------------------------
 
-function copcall(f, ...)
+function _G.copcall(f, ...)
     return coxpcall(f, id, ...)
 end
 
diff --git a/runtime/lua/man.lua b/runtime/lua/man.lua
index e322a1f680..7485f60978 100644
--- a/runtime/lua/man.lua
+++ b/runtime/lua/man.lua
@@ -201,6 +201,7 @@ local function highlight_man_page()
   api.nvim_buf_set_lines(0, 0, -1, false, lines)
 
   for _, hl in ipairs(hls) do
+    --- @diagnostic disable-next-line: deprecated
     api.nvim_buf_add_highlight(0, -1, HlGroups[hl.attr], hl.row, hl.start, hl.final)
   end
 
diff --git a/runtime/lua/tohtml.lua b/runtime/lua/tohtml.lua
index 1402dfe494..4415a8cdca 100644
--- a/runtime/lua/tohtml.lua
+++ b/runtime/lua/tohtml.lua
@@ -317,7 +317,7 @@ end
 --- @return nil|integer
 local function register_hl(state, hl)
   if type(hl) == 'table' then
-    hl = hl[#hl]
+    hl = hl[#hl] --- @type string|integer
   end
   if type(hl) == 'nil' then
     return
@@ -1162,7 +1162,9 @@ local function extend_pre(out, state)
       s = s .. _pre_text_to_html(state, row)
     end
     local true_line_len = #line + 1
-    for k in pairs(style_line) do
+    for k in
+      pairs(style_line --[[@as table<string,any>]])
+    do
       if type(k) == 'number' and k > true_line_len then
         true_line_len = k
       end
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 4b28b63746..a77ea9bb91 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -425,6 +425,7 @@ local VIM_CMD_ARG_MAX = 20
 --- vim.cmd.colorscheme('blue')
 --- ```
 ---
+---@diagnostic disable-next-line: undefined-doc-param
 ---@param command string|table Command(s) to execute.
 ---                            If a string, executes multiple lines of Vimscript at once. In this
 ---                            case, it is an alias to |nvim_exec2()|, where `opts.output` is set
@@ -441,10 +442,12 @@ vim.cmd = setmetatable({}, {
       return ''
     end
   end,
+  --- @param t table<string,function>
   __index = function(t, command)
     t[command] = function(...)
-      local opts
+      local opts --- @type vim.api.keyset.cmd
       if select('#', ...) == 1 and type(select(1, ...)) == 'table' then
+        --- @type vim.api.keyset.cmd
         opts = select(1, ...)
 
         -- Move indexed positions in opts to opt.args
@@ -455,6 +458,7 @@ vim.cmd = setmetatable({}, {
               break
             end
             opts.args[i] = opts[i]
+            --- @diagnostic disable-next-line: no-unknown
             opts[i] = nil
           end
         end
@@ -529,7 +533,7 @@ function vim.region(bufnr, pos1, pos2, regtype, inclusive)
   end
 
   if pos1[1] > pos2[1] or (pos1[1] == pos2[1] and pos1[2] > pos2[2]) then
-    pos1, pos2 = pos2, pos1
+    pos1, pos2 = pos2, pos1 --- @type [integer, integer], [integer, integer]
   end
 
   -- getpos() may return {0,0,0,0}
@@ -701,6 +705,7 @@ function vim._on_key(buf, typed_buf)
   local discard = false
   for k, v in pairs(on_key_cbs) do
     local fn = v[1]
+    --- @type boolean, any
     local ok, rv = xpcall(function()
       return fn(buf, typed_buf)
     end, debug.traceback)
@@ -828,6 +833,7 @@ function vim.str_utfindex(s, encoding, index, strict_indexing)
     -- Return (multiple): ~
     --     (`integer`) UTF-32 index
     --     (`integer`) UTF-16 index
+    --- @diagnostic disable-next-line: redundant-return-value
     return col32, col16
   end
 
@@ -1000,7 +1006,7 @@ function vim._expand_pat(pat, env)
         or vim.v == final_env and { 'v:', 'var' }
         or { nil, nil }
     )
-    assert(prefix, "Can't resolve final_env")
+    assert(prefix and type, "Can't resolve final_env")
     local vars = vim.fn.getcompletion(prefix .. match_part, type) --- @type string[]
     insert_keys(vim
       .iter(vars)
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
index b0eb1d663b..35063dffca 100644
--- a/runtime/lua/vim/_inspector.lua
+++ b/runtime/lua/vim/_inspector.lua
@@ -1,3 +1,5 @@
+--- @diagnostic disable:no-unknown
+
 --- @class vim._inspector.Filter
 --- @inlinedoc
 ---
@@ -78,6 +80,7 @@ function vim.inspect_pos(bufnr, row, col, filter)
   -- treesitter
   if filter.treesitter then
     for _, capture in pairs(vim.treesitter.get_captures_at_pos(bufnr, row, col)) do
+      --- @diagnostic disable-next-line: inject-field
       capture.hl_group = '@' .. capture.capture .. '.' .. capture.lang
       results.treesitter[#results.treesitter + 1] = resolve_hl(capture)
     end
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index c7d5db60b1..3d10729d23 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -3,6 +3,10 @@
 -- DO NOT EDIT
 error('Cannot require a meta file')
 
+--- This file embeds vimdoc as the function descriptions
+--- so ignore any doc related errors.
+--- @diagnostic disable: undefined-doc-name,luadoc-miss-symbol
+
 vim.api = {}
 
 --- @private
diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index 8338c5ead7..973ad87ee8 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -688,6 +688,7 @@ local function remove_value(info, current, new)
 end
 
 local function create_option_accessor(scope)
+  --- @diagnostic disable-next-line: no-unknown
   local option_mt
 
   local function make_option(name, value)
@@ -696,6 +697,7 @@ local function create_option_accessor(scope)
     if type(value) == 'table' and getmetatable(value) == option_mt then
       assert(name == value._name, "must be the same value, otherwise that's weird.")
 
+      --- @diagnostic disable-next-line: no-unknown
       value = value._value
     end
 
@@ -719,6 +721,7 @@ local function create_option_accessor(scope)
     end,
 
     append = function(self, right)
+      --- @diagnostic disable-next-line: no-unknown
       self._value = add_value(self._info, self._value, right)
       self:_set()
     end,
@@ -728,6 +731,7 @@ local function create_option_accessor(scope)
     end,
 
     prepend = function(self, right)
+      --- @diagnostic disable-next-line: no-unknown
       self._value = prepend_value(self._info, self._value, right)
       self:_set()
     end,
@@ -737,6 +741,7 @@ local function create_option_accessor(scope)
     end,
 
     remove = function(self, right)
+      --- @diagnostic disable-next-line: no-unknown
       self._value = remove_value(self._info, self._value, right)
       self:_set()
     end,
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 2d86fbe38c..2538cd3048 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -891,6 +891,7 @@ local function set_list(loclist, opts)
   if open then
     if not loclist then
       -- First navigate to the diagnostics quickfix list.
+      --- @type integer
       local nr = vim.fn.getqflist({ id = qf_id, nr = 0 }).nr
       api.nvim_command(('silent %dchistory'):format(nr))
 
@@ -2250,18 +2251,24 @@ function M.open_float(opts, ...)
   if not opts.focus_id then
     opts.focus_id = scope
   end
+
+  --- @diagnostic disable-next-line: param-type-mismatch
   local float_bufnr, winnr = vim.lsp.util.open_floating_preview(lines, 'plaintext', opts)
   vim.bo[float_bufnr].path = vim.bo[bufnr].path
+
+  --- @diagnostic disable-next-line: deprecated
+  local add_highlight = api.nvim_buf_add_highlight
+
   for i, hl in ipairs(highlights) do
     local line = lines[i]
     local prefix_len = hl.prefix and hl.prefix.length or 0
     local suffix_len = hl.suffix and hl.suffix.length or 0
     if prefix_len > 0 then
-      api.nvim_buf_add_highlight(float_bufnr, -1, hl.prefix.hlname, i - 1, 0, prefix_len)
+      add_highlight(float_bufnr, -1, hl.prefix.hlname, i - 1, 0, prefix_len)
     end
-    api.nvim_buf_add_highlight(float_bufnr, -1, hl.hlname, i - 1, prefix_len, #line - suffix_len)
+    add_highlight(float_bufnr, -1, hl.hlname, i - 1, prefix_len, #line - suffix_len)
     if suffix_len > 0 then
-      api.nvim_buf_add_highlight(float_bufnr, -1, hl.suffix.hlname, i - 1, #line - suffix_len, -1)
+      add_highlight(float_bufnr, -1, hl.suffix.hlname, i - 1, #line - suffix_len, -1)
     end
   end
 
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index a8f3d18bfa..cc7358ee49 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/runtime/lua/vim/filetype.lua
@@ -732,8 +732,8 @@ local extension = {
   mc = detect.mc,
   quake = 'm3quake',
   m4 = function(path, bufnr)
-    path = path:lower()
-    return not (path:find('html%.m4$') or path:find('fvwm2rc')) and 'm4' or nil
+    local pathl = path:lower()
+    return not (pathl:find('html%.m4$') or pathl:find('fvwm2rc')) and 'm4' or nil
   end,
   eml = 'mail',
   mk = detect.make,
diff --git a/runtime/lua/vim/filetype/detect.lua b/runtime/lua/vim/filetype/detect.lua
index 8f66418733..91c0406dc0 100644
--- a/runtime/lua/vim/filetype/detect.lua
+++ b/runtime/lua/vim/filetype/detect.lua
@@ -881,7 +881,7 @@ end
 --- (refactor of filetype.vim since the patterns are case-insensitive)
 --- @type vim.filetype.mapfn
 function M.log(path, _)
-  path = path:lower()
+  path = path:lower() --- @type string LuaLS bug
   if
     findany(
       path,
@@ -1167,7 +1167,7 @@ end
 --- @type vim.filetype.mapfn
 function M.perl(path, bufnr)
   local dir_name = vim.fs.dirname(path)
-  if fn.expand(path, '%:e') == 't' and (dir_name == 't' or dir_name == 'xt') then
+  if fn.fnamemodify(path, '%:e') == 't' and (dir_name == 't' or dir_name == 'xt') then
     return 'perl'
   end
   local first_line = getline(bufnr, 1)
@@ -1375,7 +1375,7 @@ end
 local udev_rules_pattern = '^%s*udev_rules%s*=%s*"([%^"]+)/*".*'
 --- @type vim.filetype.mapfn
 function M.rules(path)
-  path = path:lower()
+  path = path:lower() --- @type string LuaLS bug
   if
     findany(path, {
       '/etc/udev/.*%.rules$',
@@ -1398,7 +1398,7 @@ function M.rules(path)
     if not ok then
       return 'hog'
     end
-    local dir = fn.expand(path, ':h')
+    local dir = fn.fnamemodify(path, ':h')
     for _, line in ipairs(config_lines) do
       local match = line:match(udev_rules_pattern)
       if match then
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 5940fa4386..8b4242223a 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -546,7 +546,7 @@ local function expand_home(path, sep)
       home = home:sub(1, -2)
     end
 
-    path = home .. path:sub(2)
+    path = home .. path:sub(2) --- @type string
   end
 
   return path
@@ -620,7 +620,7 @@ function M.normalize(path, opts)
 
   -- Expand environment variables if `opts.expand_env` isn't `false`
   if opts.expand_env == nil or opts.expand_env then
-    path = path:gsub('%$([%w_]+)', uv.os_getenv)
+    path = path:gsub('%$([%w_]+)', uv.os_getenv) --- @type string
   end
 
   if win then
diff --git a/runtime/lua/vim/glob.lua b/runtime/lua/vim/glob.lua
index 4f86d5e1ca..242c70d4b2 100644
--- a/runtime/lua/vim/glob.lua
+++ b/runtime/lua/vim/glob.lua
@@ -53,6 +53,7 @@ function M.to_lpeg(pattern)
   end
   -- luacheck: pop
 
+  --- @diagnostic disable-next-line: missing-fields
   local p = P({
     'Pattern',
     Pattern = V('Elem') ^ -1 * V('End'),
diff --git a/runtime/lua/vim/health.lua b/runtime/lua/vim/health.lua
index 3268c82613..a265e2b901 100644
--- a/runtime/lua/vim/health.lua
+++ b/runtime/lua/vim/health.lua
@@ -126,7 +126,7 @@ local function filepath_to_healthcheck(path)
       -- */health/init.lua
       name = vim.fs.dirname(vim.fs.dirname(subpath))
     end
-    name = name:gsub('/', '.')
+    name = assert(name:gsub('/', '.')) --- @type string
 
     func = 'require("' .. name .. '.health").check()'
     filetype = 'l'
@@ -235,7 +235,7 @@ local function format_report_message(status, msg, ...)
     -- Report each suggestion
     for _, v in ipairs(varargs) do
       if v then
-        output = output .. '\n    - ' .. indent_after_line1(v, 6)
+        output = output .. '\n    - ' .. indent_after_line1(v, 6) --- @type string
       end
     end
   end
@@ -445,8 +445,7 @@ function M._check(mods, plugin_names)
 
   -- Quit with 'q' inside healthcheck buffers.
   vim.keymap.set('n', 'q', function()
-    local ok, _ = pcall(vim.cmd.close)
-    if not ok then
+    if not pcall(vim.cmd.close) then
       vim.cmd.bdelete()
     end
   end, { buffer = bufnr, silent = true, noremap = true, nowait = true })
diff --git a/runtime/lua/vim/health/health.lua b/runtime/lua/vim/health/health.lua
index d226f35f9a..dd6fe7f608 100644
--- a/runtime/lua/vim/health/health.lua
+++ b/runtime/lua/vim/health/health.lua
@@ -183,13 +183,16 @@ end
 local function check_rplugin_manifest()
   health.start('Remote Plugins')
 
-  local existing_rplugins = {}
-  for _, item in ipairs(vim.fn['remote#host#PluginsForHost']('python3')) do
+  local existing_rplugins = {} --- @type table<string,string>
+  --- @type {path:string}[]
+  local items = vim.fn['remote#host#PluginsForHost']('python3')
+  for _, item in ipairs(items) do
     existing_rplugins[item.path] = 'python3'
   end
 
   local require_update = false
   local handle_path = function(path)
+    --- @type string[]
     local python_glob = vim.fn.glob(path .. '/rplugin/python*', true, true)
     if vim.tbl_isempty(python_glob) then
       return
@@ -198,6 +201,7 @@ local function check_rplugin_manifest()
     local python_dir = python_glob[1]
     local python_version = vim.fs.basename(python_dir)
 
+    --- @type string[]
     local scripts = vim.fn.glob(python_dir .. '/*.py', true, true)
     vim.list_extend(scripts, vim.fn.glob(python_dir .. '/*/__init__.py', true, true))
 
@@ -227,7 +231,10 @@ local function check_rplugin_manifest()
     end
   end
 
-  for _, path in ipairs(vim.fn.map(vim.split(vim.o.runtimepath, ','), 'resolve(v:val)')) do
+  --- @type string[]
+  local paths = vim.fn.map(vim.split(vim.o.runtimepath, ','), 'resolve(v:val)')
+
+  for _, path in ipairs(paths) do
     handle_path(path)
   end
 
diff --git a/runtime/lua/vim/inspect.lua b/runtime/lua/vim/inspect.lua
index c232f69590..cdf34897d4 100644
--- a/runtime/lua/vim/inspect.lua
+++ b/runtime/lua/vim/inspect.lua
@@ -1,3 +1,4 @@
+--- @diagnostic disable: no-unknown
 local inspect = {
   _VERSION = 'inspect.lua 3.1.0',
   _URL = 'http://github.com/kikito/inspect.lua',
diff --git a/runtime/lua/vim/lsp/_changetracking.lua b/runtime/lua/vim/lsp/_changetracking.lua
index c2ff66b90e..265a74c8fa 100644
--- a/runtime/lua/vim/lsp/_changetracking.lua
+++ b/runtime/lua/vim/lsp/_changetracking.lua
@@ -64,7 +64,7 @@ local state_by_group = setmetatable({}, {
 ---@param client vim.lsp.Client
 ---@return vim.lsp.CTGroup
 local function get_group(client)
-  local allow_inc_sync = vim.F.if_nil(client.flags.allow_incremental_sync, true) --- @type boolean
+  local allow_inc_sync = vim.F.if_nil(client.flags.allow_incremental_sync, true)
   local change_capability = vim.tbl_get(client.server_capabilities, 'textDocumentSync', 'change')
   local sync_kind = change_capability or protocol.TextDocumentSyncKind.None
   if not allow_inc_sync and change_capability == protocol.TextDocumentSyncKind.Incremental then
diff --git a/runtime/lua/vim/lsp/_meta.lua b/runtime/lua/vim/lsp/_meta.lua
index bf693ccc57..589a49c003 100644
--- a/runtime/lua/vim/lsp/_meta.lua
+++ b/runtime/lua/vim/lsp/_meta.lua
@@ -1,8 +1,8 @@
 ---@meta
 error('Cannot require a meta file')
 
----@alias lsp.Handler fun(err: lsp.ResponseError?, result: any, context: lsp.HandlerContext): ...any
----@alias lsp.MultiHandler fun(results: table<integer,{err: lsp.ResponseError?, result: any}>, context: lsp.HandlerContext): ...any
+---@alias lsp.Handler fun(err: lsp.ResponseError?, result: any, context: lsp.HandlerContext, config?: table): ...any
+---@alias lsp.MultiHandler fun(results: table<integer,{err: lsp.ResponseError?, result: any}>, context: lsp.HandlerContext, config?: table): ...any
 
 ---@class lsp.HandlerContext
 ---@field method string
diff --git a/runtime/lua/vim/lsp/_snippet_grammar.lua b/runtime/lua/vim/lsp/_snippet_grammar.lua
index 9318fefcbc..f06d6e9afd 100644
--- a/runtime/lua/vim/lsp/_snippet_grammar.lua
+++ b/runtime/lua/vim/lsp/_snippet_grammar.lua
@@ -127,6 +127,7 @@ local function node(type)
 end
 
 -- stylua: ignore
+--- @diagnostic disable-next-line: missing-fields
 local G = P({
   'snippet';
   snippet = Ct(Cg(
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index c57fdbee18..638a0d0f3f 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -450,10 +450,10 @@ local function range_from_selection(bufnr, mode)
   -- A user can start visual selection at the end and move backwards
   -- Normalize the range to start < end
   if start_row == end_row and end_col < start_col then
-    end_col, start_col = start_col, end_col
+    end_col, start_col = start_col, end_col --- @type integer, integer
   elseif end_row < start_row then
-    start_row, end_row = end_row, start_row
-    start_col, end_col = end_col, start_col
+    start_row, end_row = end_row, start_row --- @type integer, integer
+    start_col, end_col = end_col, start_col --- @type integer, integer
   end
   if mode == 'V' then
     start_col = 1
@@ -553,25 +553,30 @@ function M.format(opts)
 
   --- @param client vim.lsp.Client
   --- @param params lsp.DocumentFormattingParams
-  --- @return lsp.DocumentFormattingParams
+  --- @return lsp.DocumentFormattingParams|lsp.DocumentRangeFormattingParams|lsp.DocumentRangesFormattingParams
   local function set_range(client, params)
-    local to_lsp_range = function(r) ---@return lsp.DocumentRangeFormattingParams|lsp.DocumentRangesFormattingParams
+    ---  @param r {start:[integer,integer],end:[integer, integer]}
+    local function to_lsp_range(r)
       return util.make_given_range_params(r.start, r['end'], bufnr, client.offset_encoding).range
     end
 
+    local ret = params --[[@as lsp.DocumentFormattingParams|lsp.DocumentRangeFormattingParams|lsp.DocumentRangesFormattingParams]]
     if passed_multiple_ranges then
-      params.ranges = vim.tbl_map(to_lsp_range, range)
+      ret = params --[[@as lsp.DocumentRangesFormattingParams]]
+      --- @cast range {start:[integer,integer],end:[integer, integer]}
+      ret.ranges = vim.tbl_map(to_lsp_range, range)
     elseif range then
-      params.range = to_lsp_range(range)
+      ret = params --[[@as lsp.DocumentRangeFormattingParams]]
+      ret.range = to_lsp_range(range)
     end
-    return params
+    return ret
   end
 
   if opts.async then
-    --- @param idx integer
-    --- @param client vim.lsp.Client
+    --- @param idx? integer
+    --- @param client? vim.lsp.Client
     local function do_format(idx, client)
-      if not client then
+      if not idx or not client then
         return
       end
       local params = set_range(client, util.make_formatting_params(opts.formatting_options))
@@ -650,16 +655,16 @@ function M.rename(new_name, opts)
     )[1]
   end
 
-  --- @param idx integer
+  --- @param idx? integer
   --- @param client? vim.lsp.Client
   local function try_use_client(idx, client)
-    if not client then
+    if not idx or not client then
       return
     end
 
     --- @param name string
     local function rename(name)
-      local params = util.make_position_params(win, client.offset_encoding)
+      local params = util.make_position_params(win, client.offset_encoding) --[[@as lsp.RenameParams]]
       params.newName = name
       local handler = client.handlers[ms.textDocument_rename]
         or lsp.handlers[ms.textDocument_rename]
@@ -1229,6 +1234,7 @@ function M.code_action(opts)
   for _, client in ipairs(clients) do
     ---@type lsp.CodeActionParams
     local params
+
     if opts.range then
       assert(type(opts.range) == 'table', 'code_action range must be a table')
       local start = assert(opts.range.start, 'range must have a `start` property')
@@ -1241,6 +1247,9 @@ function M.code_action(opts)
     else
       params = util.make_range_params(win, client.offset_encoding)
     end
+
+    --- @cast params lsp.CodeActionParams
+
     if context.diagnostics then
       params.context = context
     else
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
index a082613bb0..253ccc48f4 100644
--- a/