refactor(lua): improve type annotations

8 files changed, 33 insertions, 353 deletions

diff --git a/runtime/lua/vim/lsp/_dynamic.lua b/runtime/lua/vim/lsp/_dynamic.lua
index 819b03a63a..27113c0e74 100644
--- a/runtime/lua/vim/lsp/_dynamic.lua
+++ b/runtime/lua/vim/lsp/_dynamic.lua
@@ -24,7 +24,6 @@ function M:supports_registration(method)
 end
 
 --- @param registrations lsp.Registration[]
---- @package
 function M:register(registrations)
   -- remove duplicates
   self:unregister(registrations)
@@ -38,7 +37,6 @@ function M:register(registrations)
 end
 
 --- @param unregisterations lsp.Unregistration[]
---- @package
 function M:unregister(unregisterations)
   for _, unreg in ipairs(unregisterations) do
     local method = unreg.method
@@ -58,7 +56,6 @@ end
 --- @param method string
 --- @param opts? {bufnr: integer?}
 --- @return lsp.Registration? (table|nil) the registration if found
---- @package
 function M:get(method, opts)
   opts = opts or {}
   opts.bufnr = opts.bufnr or vim.api.nvim_get_current_buf()
@@ -78,7 +75,6 @@ end
 
 --- @param method string
 --- @param opts? {bufnr: integer?}
---- @package
 function M:supports(method, opts)
   return self:get(method, opts) ~= nil
 end
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
index 327cd19125..d3ff918792 100644
--- a/runtime/lua/vim/lsp/client.lua
+++ b/runtime/lua/vim/lsp/client.lua
@@ -436,7 +436,7 @@ local function ensure_list(x)
   return { x }
 end
 
---- @package
+--- @nodoc
 --- @param config vim.lsp.ClientConfig
 --- @return vim.lsp.Client?
 function Client.create(config)
@@ -535,7 +535,7 @@ function Client:_run_callbacks(cbs, error_id, ...)
   end
 end
 
---- @package
+--- @nodoc
 function Client:initialize()
   local config = self.config
 
@@ -656,7 +656,7 @@ end
 --- @param method string LSP method name.
 --- @param params? table LSP request params.
 --- @param handler? lsp.Handler Response |lsp-handler| for this method.
---- @param bufnr? integer Buffer handle (0 for current).
+--- @param bufnr integer Buffer handle (0 for current).
 --- @return boolean status, integer? request_id {status} is a bool indicating
 --- whether the request was successful. If it is `false`, then it will
 --- always be `false` (the client has shutdown). If it was
@@ -861,7 +861,6 @@ function Client:_is_stopped()
   return self.rpc.is_closing()
 end
 
---- @package
 --- Execute a lsp command, either via client command function (if available)
 --- or via workspace/executeCommand (if supported by the server)
 ---
@@ -906,7 +905,6 @@ function Client:_exec_cmd(command, context, handler, on_unsupported)
   self.request(ms.workspace_executeCommand, params, handler, context.bufnr)
 end
 
---- @package
 --- Default handler for the 'textDocument/didOpen' LSP notification.
 ---
 --- @param bufnr integer Number of the buffer, or 0 for current
@@ -942,7 +940,6 @@ function Client:_text_document_did_open_handler(bufnr)
   end)
 end
 
---- @package
 --- Runs the on_attach function from the client's config if it was defined.
 --- @param bufnr integer Buffer number
 function Client:_on_attach(bufnr)
@@ -1065,7 +1062,6 @@ function Client:_on_exit(code, signal)
   )
 end
 
---- @package
 --- Add a directory to the workspace folders.
 --- @param dir string?
 function Client:_add_workspace_folder(dir)
@@ -1088,7 +1084,6 @@ function Client:_add_workspace_folder(dir)
   vim.list_extend(self.workspace_folders, wf)
 end
 
---- @package
 --- Remove a directory to the workspace folders.
 --- @param dir string?
 function Client:_remove_workspace_folder(dir)
diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
index 38c43893eb..44548fec92 100644
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -646,6 +646,7 @@ M[ms.window_showMessage] = function(_, result, ctx, _)
   if message_type == protocol.MessageType.Error then
     err_message('LSP[', client_name, '] ', message)
   else
+    --- @type string
     local message_type_name = protocol.MessageType[message_type]
     api.nvim_out_write(string.format('LSP[%s][%s] %s\n', client_name, message_type_name, message))
   end
diff --git a/runtime/lua/vim/lsp/log.lua b/runtime/lua/vim/lsp/log.lua
index 9f2bd71158..0438ca84af 100644
--- a/runtime/lua/vim/lsp/log.lua
+++ b/runtime/lua/vim/lsp/log.lua
@@ -9,7 +9,7 @@ local log_levels = vim.log.levels
 --- Can be used to lookup the number from the name or the name from the number.
 --- Levels by name: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "OFF"
 --- Level numbers begin with "TRACE" at 0
---- @type table<string|integer, string|integer>
+--- @type table<string,integer> | table<integer, string>
 --- @nodoc
 log.levels = vim.deepcopy(log_levels)
 
diff --git a/runtime/lua/vim/lsp/protocol.lua b/runtime/lua/vim/lsp/protocol.lua
index 8ac4cc794b..eb18043843 100644
--- a/runtime/lua/vim/lsp/protocol.lua
+++ b/runtime/lua/vim/lsp/protocol.lua
@@ -12,9 +12,6 @@ end
 
 local sysname = vim.uv.os_uname().sysname
 
--- Protocol for the Microsoft Language Server Protocol (mslsp)
-local protocol = {}
-
 local constants = {
   --- @enum lsp.DiagnosticSeverity
   DiagnosticSeverity = {
@@ -46,6 +43,8 @@ local constants = {
     Info = 3,
     -- A log message.
     Log = 4,
+    -- A debug message.
+    Debug = 5,
   },
 
   -- The file event type.
@@ -308,326 +307,18 @@ local constants = {
   },
 }
 
-for k1, v1 in pairs(constants) do
-  local tbl = vim.deepcopy(v1, true)
-  for _, k2 in ipairs(vim.tbl_keys(tbl)) do
-    local v2 = tbl[k2]
-    tbl[v2] = k2
+-- Protocol for the Microsoft Language Server Protocol (mslsp)
+local protocol = {}
+
+--- @diagnostic disable:no-unknown
+for k1, v1 in pairs(vim.deepcopy(constants, true)) do
+  for _, k2 in ipairs(vim.tbl_keys(v1)) do
+    local v2 = v1[k2]
+    v1[v2] = k2
   end
-  protocol[k1] = tbl
+  protocol[k1] = v1
 end
-
---[=[
---Text document specific client capabilities.
-export interface TextDocumentClientCapabilities {
-  synchronization?: {
-    --Whether text document synchronization supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports sending will save notifications.
-    willSave?: boolean;
-    --The client supports sending a will save request and
-    --waits for a response providing text edits which will
-    --be applied to the document before it is saved.
-    willSaveWaitUntil?: boolean;
-    --The client supports did save notifications.
-    didSave?: boolean;
-  }
-  --Capabilities specific to the `textDocument/completion`
-  completion?: {
-    --Whether completion supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports the following `CompletionItem` specific
-    --capabilities.
-    completionItem?: {
-      --The client supports snippets as insert text.
-      --
-      --A snippet can define tab stops and placeholders with `$1`, `$2`
-      --and `${3:foo}`. `$0` defines the final tab stop, it defaults to
-      --the end of the snippet. Placeholders with equal identifiers are linked,
-      --that is typing in one will update others too.
-      snippetSupport?: boolean;
-      --The client supports commit characters on a completion item.
-      commitCharactersSupport?: boolean
-      --The client supports the following content formats for the documentation
-      --property. The order describes the preferred format of the client.
-      documentationFormat?: MarkupKind[];
-      --The client supports the deprecated property on a completion item.
-      deprecatedSupport?: boolean;
-      --The client supports the preselect property on a completion item.
-      preselectSupport?: boolean;
-    }
-    completionItemKind?: {
-      --The completion item kind values the client supports. When this
-      --property exists the client also guarantees that it will
-      --handle values outside its set gracefully and falls back
-      --to a default value when unknown.
-      --
-      --If this property is not present the client only supports
-      --the completion items kinds from `Text` to `Reference` as defined in
-      --the initial version of the protocol.
-      valueSet?: CompletionItemKind[];
-    },
-    --The client supports to send additional context information for a
-    --`textDocument/completion` request.
-    contextSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/hover`
-  hover?: {
-    --Whether hover supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports the follow content formats for the content
-    --property. The order describes the preferred format of the client.
-    contentFormat?: MarkupKind[];
-  };
-  --Capabilities specific to the `textDocument/signatureHelp`
-  signatureHelp?: {
-    --Whether signature help supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports the following `SignatureInformation`
-    --specific properties.
-    signatureInformation?: {
-      --The client supports the follow content formats for the documentation
-      --property. The order describes the preferred format of the client.
-      documentationFormat?: MarkupKind[];
-      --Client capabilities specific to parameter information.
-      parameterInformation?: {
-        --The client supports processing label offsets instead of a
-        --simple label string.
-        --
-        --Since 3.14.0
-        labelOffsetSupport?: boolean;
-      }
-    };
-  };
-  --Capabilities specific to the `textDocument/references`
-  references?: {
-    --Whether references supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/documentHighlight`
-  documentHighlight?: {
-    --Whether document highlight supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/documentSymbol`
-  documentSymbol?: {
-    --Whether document symbol supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --Specific capabilities for the `SymbolKind`.
-    symbolKind?: {
-      --The symbol kind values the client supports. When this
-      --property exists the client also guarantees that it will
-      --handle values outside its set gracefully and falls back
-      --to a default value when unknown.
-      --
-      --If this property is not present the client only supports
-      --the symbol kinds from `File` to `Array` as defined in
-      --the initial version of the protocol.
-      valueSet?: SymbolKind[];
-    }
-    --The client supports hierarchical document symbols.
-    hierarchicalDocumentSymbolSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/formatting`
-  formatting?: {
-    --Whether formatting supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/rangeFormatting`
-  rangeFormatting?: {
-    --Whether range formatting supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/onTypeFormatting`
-  onTypeFormatting?: {
-    --Whether on type formatting supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/declaration`
-  declaration?: {
-    --Whether declaration supports dynamic registration. If this is set to `true`
-    --the client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-    --The client supports additional metadata in the form of declaration links.
-    --
-    --Since 3.14.0
-    linkSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/definition`.
-  --
-  --Since 3.14.0
-  definition?: {
-    --Whether definition supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports additional metadata in the form of definition links.
-    linkSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/typeDefinition`
-  --
-  --Since 3.6.0
-  typeDefinition?: {
-    --Whether typeDefinition supports dynamic registration. If this is set to `true`
-    --the client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-    --The client supports additional metadata in the form of definition links.
-    --
-    --Since 3.14.0
-    linkSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/implementation`.
-  --
-  --Since 3.6.0
-  implementation?: {
-    --Whether implementation supports dynamic registration. If this is set to `true`
-    --the client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-    --The client supports additional metadata in the form of definition links.
-    --
-    --Since 3.14.0
-    linkSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/codeAction`
-  codeAction?: {
-    --Whether code action supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client support code action literals as a valid
-    --response of the `textDocument/codeAction` request.
-    --
-    --Since 3.8.0
-    codeActionLiteralSupport?: {
-      --The code action kind is support with the following value
-      --set.
-      codeActionKind: {
-        --The code action kind values the client supports. When this
-        --property exists the client also guarantees that it will
-        --handle values outside its set gracefully and falls back
-        --to a default value when unknown.
-        valueSet: CodeActionKind[];
-      };
-    };
-  };
-  --Capabilities specific to the `textDocument/codeLens`
-  codeLens?: {
-    --Whether code lens supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/documentLink`
-  documentLink?: {
-    --Whether document link supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/documentColor` and the
-  --`textDocument/colorPresentation` request.
-  --
-  --Since 3.6.0
-  colorProvider?: {
-    --Whether colorProvider supports dynamic registration. If this is set to `true`
-    --the client supports the new `(ColorProviderOptions & TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-  }
-  --Capabilities specific to the `textDocument/rename`
-  rename?: {
-    --Whether rename supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports testing for validity of rename operations
-    --before execution.
-    prepareSupport?: boolean;
-  };
-  --Capabilities specific to `textDocument/publishDiagnostics`.
-  publishDiagnostics?: {
-    --Whether the clients accepts diagnostics with related information.
-    relatedInformation?: boolean;
-    --Client supports the tag property to provide meta data about a diagnostic.
-	  --Clients supporting tags have to handle unknown tags gracefully.
-    --Since 3.15.0
-    tagSupport?: {
-      --The tags supported by this client
-      valueSet: DiagnosticTag[];
-    };
-  };
-  --Capabilities specific to `textDocument/foldingRange` requests.
-  --
-  --Since 3.10.0
-  foldingRange?: {
-    --Whether implementation supports dynamic registration for folding range providers. If this is set to `true`
-    --the client supports the new `(FoldingRangeProviderOptions & TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-    --The maximum number of folding ranges that the client prefers to receive per document. The value serves as a
-    --hint, servers are free to follow the limit.
-    rangeLimit?: number;
-    --If set, the client signals that it only supports folding complete lines. If set, client will
-    --ignore specified `startCharacter` and `endCharacter` properties in a FoldingRange.
-    lineFoldingOnly?: boolean;
-  };
-}
---]=]
-
---[=[
---Workspace specific client capabilities.
-export interface WorkspaceClientCapabilities {
-  --The client supports applying batch edits to the workspace by supporting
-  --the request 'workspace/applyEdit'
-  applyEdit?: boolean;
-  --Capabilities specific to `WorkspaceEdit`s
-  workspaceEdit?: {
-    --The client supports versioned document changes in `WorkspaceEdit`s
-    documentChanges?: boolean;
-    --The resource operations the client supports. Clients should at least
-    --support 'create', 'rename' and 'delete' files and folders.
-    resourceOperations?: ResourceOperationKind[];
-    --The failure handling strategy of a client if applying the workspace edit
-    --fails.
-    failureHandling?: FailureHandlingKind;
-  };
-  --Capabilities specific to the `workspace/didChangeConfiguration` notification.
-  didChangeConfiguration?: {
-    --Did change configuration notification supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `workspace/didChangeWatchedFiles` notification.
-  didChangeWatchedFiles?: {
-    --Did change watched files notification supports dynamic registration. Please note
-    --that the current protocol doesn't support static configuration for file changes
-    --from the server side.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `workspace/symbol` request.
-  symbol?: {
-    --Symbol request supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --Specific capabilities for the `SymbolKind` in the `workspace/symbol` request.
-    symbolKind?: {
-      --The symbol kind values the client supports. When this
-      --property exists the client also guarantees that it will
-      --handle values outside its set gracefully and falls back
-      --to a default value when unknown.
-      --
-      --If this property is not present the client only supports
-      --the symbol kinds from `File` to `Array` as defined in
-      --the initial version of the protocol.
-      valueSet?: SymbolKind[];
-    }
-  };
-  --Capabilities specific to the `workspace/executeCommand` request.
-  executeCommand?: {
-    --Execute command supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --The client has support for workspace folders.
-  --
-  --Since 3.6.0
-  workspaceFolders?: boolean;
-  --The client supports `workspace/configuration` requests.
-  --
-  --Since 3.6.0
-  configuration?: boolean;
-}
---]=]
+--- @diagnostic enable:no-unknown
 
 --- Gets a new ClientCapabilities object describing the LSP client
 --- capabilities.
@@ -1250,14 +941,5 @@ protocol.Methods = {
   --- The `workspace/workspaceFolders` is sent from the server to the client to fetch the open workspace folders.
   workspace_workspaceFolders = 'workspace/workspaceFolders',
 }
-local function freeze(t)
-  return setmetatable({}, {
-    __index = t,
-    __newindex = function()
-      error('cannot modify immutable table')
-    end,
-  })
-end
-protocol.Methods = freeze(protocol.Methods)
 
 return protocol
diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua
index 3c63a12da2..5e2b041a0a 100644
--- a/runtime/lua/vim/lsp/rpc.lua
+++ b/runtime/lua/vim/lsp/rpc.lua
@@ -140,7 +140,7 @@ local client_errors = {
   SERVER_RESULT_CALLBACK_ERROR = 7,
 }
 
---- @type table<string|integer, string|integer>
+--- @type table<string,integer> | table<integer,string>
 --- @nodoc
 M.client_errors = vim.deepcopy(client_errors)
 for k, v in pairs(client_errors) do
@@ -502,7 +502,7 @@ function Client:handle_body(body)
       if decoded.error then
         decoded.error = setmetatable(decoded.error, {
           __tostring = M.format_rpc_error,
-        }) --- @type table
+        })
       end
       self:try_call(
         M.client_errors.SERVER_RESULT_CALLBACK_ERROR,
diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua
index 279956658c..f92c0eb2e6 100644
--- a/runtime/lua/vim/lsp/semantic_tokens.lua
+++ b/runtime/lua/vim/lsp/semantic_tokens.lua
@@ -773,7 +773,6 @@ function M.highlight_token(token, bufnr, client_id, hl_group, opts)
   })
 end
 
---- @package
 --- |lsp-handler| for the method `workspace/semanticTokens/refresh`
 ---
 --- Refresh requests are sent by the server to indicate a project-wide change
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index 088d57b6d6..ae6de591b3 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -238,6 +238,7 @@ end
 ---@param rows integer[] zero-indexed line numbers
 ---@return table<integer, string>|string a table mapping rows to lines
 local function get_lines(bufnr, rows)
+  --- @type integer[]
   rows = type(rows) == 'table' and rows or { rows }
 
   -- This is needed for bufload and bufloaded
@@ -246,7 +247,7 @@ local function get_lines(bufnr, rows)
   end
 
   local function buf_lines()
-    local lines = {}
+    local lines = {} --- @type table<integer,string>
     for _, row in ipairs(rows) do
       lines[row] = (api.nvim_buf_get_lines(bufnr, row, row + 1, false) or { '' })[1]
     end
@@ -274,11 +275,11 @@ local function get_lines(bufnr, rows)
   if not fd then
     return ''
   end
-  local stat = uv.fs_fstat(fd)
-  local data = uv.fs_read(fd, stat.size, 0)
+  local stat = assert(uv.fs_fstat(fd))
+  local data = assert(uv.fs_read(fd, stat.size, 0))
   uv.fs_close(fd)
 
-  local lines = {} -- rows we need to retrieve
+  local lines = {} --- @type table<integer,true|string> rows we need to retrieve
   local need = 0 -- keep track of how many unique rows we need
   for _, row in pairs(rows) do
     if not lines[row] then
@@ -307,7 +308,7 @@ local function get_lines(bufnr, rows)
       lines[i] = ''
     end
   end
-  return lines
+  return lines --[[@as table<integer,string>]]
 end
 
 --- Gets the zero-indexed line from the given buffer.
@@ -322,7 +323,8 @@ local function get_line(bufnr, row)
 end
 
 --- Position is a https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position
----@param offset_encoding string|nil utf-8|utf-16|utf-32
+---@param position lsp.Position
+---@param offset_encoding? string utf-8|utf-16|utf-32
 ---@return integer
 local function get_line_byte_from_position(bufnr, position, offset_encoding)
   -- LSP's line and characters are 0-indexed
@@ -366,6 +368,7 @@ function M.apply_text_edits(text_edits, bufnr, offset_encoding)
 
   -- Fix reversed range and indexing each text_edits
   local index = 0
+  --- @param text_edit lsp.TextEdit
   text_edits = vim.tbl_map(function(text_edit)
     index = index + 1
     text_edit._index = index
@@ -383,6 +386,9 @@ function M.apply_text_edits(text_edits, bufnr, offset_encoding)
   end, text_edits)
 
   -- Sort text_edits
+  ---@param a lsp.TextEdit | { _index: integer }
+  ---@param b lsp.TextEdit | { _index: integer }
+  ---@return boolean
   table.sort(text_edits, function(a, b)
     if a.range.start.line ~= b.range.start.line then
       return a.range.start.line > b.range.start.line
@@ -393,10 +399,11 @@ function M.apply_text_edits(text_edits, bufnr, offset_encoding)
     if a._index ~= b._index then
       return a._index < b._index
     end
+    return false
   end)
 
   -- save and restore local marks since they get deleted by nvim_buf_set_lines
-  local marks = {}
+  local marks = {} --- @type table<string,[integer,integer]>
   for _, m in pairs(vim.fn.getmarklist(bufnr)) do
     if m.mark:match("^'[a-z]$") then
       marks[m.mark:sub(2, 2)] = { m.pos[2], m.pos[3] - 1 } -- api-indexed