fix(lua): improve annotations for stricter luals diagnostics (neovim#…

…24609)

Problem: luals returns stricter diagnostics with bundled luarc.json
Solution: Improve some function and type annotations:

* use recognized uv.* types 
* disable diagnostic for global `vim` in shared.lua
* docs: don't start comment lines with taglink (otherwise LuaLS will interpret it as a type)
* add type alias for lpeg pattern
* fix return annotation for `vim.secure.trust`
* rename local Range object in vim.version (shadows `Range` in vim.treesitter)
* fix some "missing fields" warnings
* add missing required fields for test functions in eval.lua
* rename lsp meta files for consistency

MAINTAIN.md

@@ -119,7 +119,7 @@ These dependencies are "vendored" (inlined), we must update the sources manually
 * `runtime/lua/vim/inspect.lua`: [inspect.lua](https://github.com/kikito/inspect.lua)
 * `src/nvim/tui/terminfo_defs.h`: terminfo definitions
     * Run `scripts/update_terminfo.sh` to update these definitions.
-* `runtime/lua/vim/lsp/types/protocol.lua`: LSP specification
+* `runtime/lua/vim/lsp/_meta/protocol.lua`: LSP specification
     * Run `scripts/gen_lsp.lua` to update.
 * `src/bit.c`: only for PUC lua: port of `require'bit'` from luajit https://bitop.luajit.org/
 * [treesitter parsers](https://github.com/neovim/neovim/blob/fcc24e43e0b5f9d801a01ff2b8f78ce8c16dd551/cmake.deps/CMakeLists.txt#L197-L210)

runtime/doc/diagnostic.txt

@@ -459,7 +459,7 @@ fromqflist({list})                               *vim.diagnostic.fromqflist()*
     Convert a list of quickfix items to a list of diagnostics.
 
     Parameters: ~
-      • {list}  (table) A list of quickfix items from |getqflist()| or
+      • {list}  table[] List of quickfix items from |getqflist()| or
                 |getloclist()|.
 
     Return: ~

runtime/doc/lsp.txt

@@ -2127,7 +2127,8 @@ request({method}, {params}, {callback}, {notify_reply_callback})
       • {method}                 (string) The invoked LSP method
       • {params}                 (table|nil) Parameters for the invoked LSP
                                  method
-      • {callback}               fun(err: lsp.ResponseError | nil, result: any) Callback to invoke
+      • {callback}               fun(err: lsp.ResponseError | nil, result:
+                                 any) Callback to invoke
       • {notify_reply_callback}  (function|nil) Callback to invoke as soon as
                                  a request is no longer pending
 

runtime/doc/lua.txt

@@ -2073,7 +2073,7 @@ vim.spairs({t})                                                 *vim.spairs()*
       • {t}  (table) Dict-like table
 
     Return: ~
-        iterator over sorted keys and their values
+        (function) iterator over sorted keys and their values
 
     See also: ~
       • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
@@ -3007,10 +3007,9 @@ vim.secure.trust({opts})                                  *vim.secure.trust()*
                 • bufnr (number|nil): Buffer number to update. Mutually
                   exclusive with {path}.
 
-    Return: ~
-        (boolean, string) success, msg:
-        • true and full path of target file if operation was successful
-        • false and error message on failure
+    Return (multiple): ~
+        (boolean) success true if operation was successful
+        (string) msg full path if operation was successful, else error message
 
 
 ==============================================================================

runtime/doc/testing.txt

@@ -31,11 +31,7 @@ Find more information in the file src/testdir/README.txt.
 ==============================================================================
 2. Test functions				*test-functions-details*
 
-test_garbagecollect_now()			 *test_garbagecollect_now()*
-		Like garbagecollect(), but executed right away.  This must
-		only be called directly to avoid any structure to exist
-		internally, and |v:testing| must have been set before calling
-		any function.
+See |test_garbagecollect_now()|.
 
 ==============================================================================
 3. Assert functions				*assert-functions-details*

runtime/lua/vim/_editor.lua

@@ -620,8 +620,8 @@ local on_key_cbs = {}
 ---
 ---@param fn fun(key: string) Function invoked on every key press. |i_CTRL-V|
 ---                   Returning nil removes the callback associated with namespace {ns_id}.
----@param ns_id integer? Namespace ID. If nil or 0, generates and returns a new
----                    |nvim_create_namespace()| id.
+---@param ns_id integer? Namespace ID. If nil or 0, generates and returns a
+---                     new |nvim_create_namespace()| id.
 ---
 ---@return integer Namespace id associated with {fn}. Or count of all callbacks
 ---if on_key() is called without arguments.

runtime/lua/vim/_system.lua

@@ -1,14 +1,13 @@
 local uv = vim.uv
 
 --- @class SystemOpts
---- @field cmd string[]
---- @field stdin string|string[]|true
---- @field stdout fun(err:string, data: string)|false
---- @field stderr fun(err:string, data: string)|false
+--- @field stdin? string|string[]|true
+--- @field stdout? fun(err:string, data: string)|false
+--- @field stderr? fun(err:string, data: string)|false
 --- @field cwd? string
 --- @field env? table<string,string|number>
 --- @field clear_env? boolean
---- @field text boolean?
+--- @field text? boolean
 --- @field timeout? integer Timeout in ms
 --- @field detach? boolean
 
@@ -19,15 +18,14 @@ local uv = vim.uv
 --- @field stderr? string
 
 --- @class SystemState
---- @field handle uv_process_t
---- @field timer uv_timer_t
---- @field pid integer
+--- @field handle? uv.uv_process_t
+--- @field timer?  uv.uv_timer_t
+--- @field pid? integer
 --- @field timeout? integer
---- @field done boolean
---- @field stdin uv_stream_t?
---- @field stdout uv_stream_t?
---- @field stderr uv_stream_t?
---- @field cmd string[]
+--- @field done? boolean
+--- @field stdin? uv.uv_stream_t
+--- @field stdout? uv.uv_stream_t
+--- @field stderr? uv.uv_stream_t
 --- @field result? SystemCompleted
 
 ---@param state SystemState
@@ -128,7 +126,7 @@ function SystemObj:is_closing()
 end
 
 ---@param output function|'false'
----@return uv_stream_t?
+---@return uv.uv_stream_t?
 ---@return function? Handler
 local function setup_output(output)
   if output == nil then
@@ -144,7 +142,7 @@ local function setup_output(output)
 end
 
 ---@param input string|string[]|true|nil
----@return uv_stream_t?
+---@return uv.uv_stream_t?
 ---@return string|string[]?
 local function setup_input(input)
   if not input then
@@ -189,7 +187,7 @@ local function setup_env(env, clear_env)
   return renv
 end
 
---- @param stream uv_stream_t
+--- @param stream uv.uv_stream_t
 --- @param text? boolean
 --- @param bucket string[]
 --- @return fun(err: string?, data: string?)
@@ -217,7 +215,7 @@ local M = {}
 --- @param opts uv.aliases.spawn_options
 --- @param on_exit fun(code: integer, signal: integer)
 --- @param on_error fun()
---- @return uv_process_t, integer
+--- @return uv.uv_process_t, integer
 local function spawn(cmd, opts, on_exit, on_error)
   local handle, pid_or_err = uv.spawn(cmd, opts, on_exit)
   if not handle then

runtime/lua/vim/_watch.lua

@@ -17,7 +17,7 @@ end
 
 --- Stops and closes a libuv |uv_fs_event_t| or |uv_fs_poll_t| handle
 ---
----@param handle (uv_fs_event_t|uv_fs_poll_t) The handle to stop
+---@param handle (uv.uv_fs_event_t|uv.uv_fs_poll_t) The handle to stop
 local function stop(handle)
   local _, stop_err = handle:stop()
   assert(not stop_err, stop_err)
@@ -79,7 +79,7 @@ local default_poll_interval_ms = 2000
 --- @field children? table<string,watch.Watches>
 --- @field cancel? fun()
 --- @field started? boolean
---- @field handle? uv_fs_poll_t
+--- @field handle? uv.uv_fs_poll_t
 
 --- @class watch.PollOpts
 --- @field interval? integer

runtime/lua/vim/diagnostic.lua

@@ -562,8 +562,8 @@ end
 ---@param opts table|nil When omitted or "nil", retrieve the current configuration. Otherwise, a
 ---                      configuration table with the following keys:
 ---       - underline: (default true) Use underline for diagnostics. Options:
----                    * severity: Only underline diagnostics matching the given severity
----                    |diagnostic-severity|
+---                    * severity: Only underline diagnostics matching the given
+---                    severity |diagnostic-severity|
 ---       - virtual_text: (default true) Use virtual text for diagnostics. If multiple diagnostics
 ---                       are set for a namespace, one prefix per diagnostic + the last diagnostic
 ---                       message are shown.
@@ -596,8 +596,8 @@ end
 ---                         end
 ---                       </pre>
 ---       - signs: (default true) Use signs for diagnostics. Options:
----                * severity: Only show signs for diagnostics matching the given severity
----                |diagnostic-severity|
+---                * severity: Only show signs for diagnostics matching the given
+---                severity |diagnostic-severity|
 ---                * priority: (number, default 10) Base priority to use for signs. When
 ---                {severity_sort} is used, the priority of a sign is adjusted based on
 ---                its severity. Otherwise, all signs use the same priority.
@@ -723,17 +723,17 @@ function M.get_namespaces()
 end
 
 ---@class Diagnostic
----@field bufnr integer
+---@field bufnr? integer
 ---@field lnum integer 0-indexed
----@field end_lnum nil|integer 0-indexed
+---@field end_lnum? integer 0-indexed
 ---@field col integer 0-indexed
----@field end_col nil|integer 0-indexed
----@field severity DiagnosticSeverity
+---@field end_col? integer 0-indexed
+---@field severity? DiagnosticSeverity
 ---@field message string
----@field source nil|string
----@field code nil|string
----@field _tags { deprecated: boolean, unnecessary: boolean}
----@field user_data nil|any arbitrary data plugins can add
+---@field source? string
+---@field code? string
+---@field _tags? { deprecated: boolean, unnecessary: boolean}
+---@field user_data? any arbitrary data plugins can add
 
 --- Get current diagnostics.
 ---
@@ -819,13 +819,13 @@ end
 ---
 ---@param opts table|nil Configuration table with the following keys:
 ---         - namespace: (number) Only consider diagnostics from the given namespace.
----         - cursor_position: (cursor position) Cursor position as a (row, col) tuple. See
----                          |nvim_win_get_cursor()|. Defaults to the current cursor position.
+---         - cursor_position: (cursor position) Cursor position as a (row, col) tuple.
+---                          See |nvim_win_get_cursor()|. Defaults to the current cursor position.
 ---         - wrap: (boolean, default true) Whether to loop around file or not. Similar to 'wrapscan'.
 ---         - severity: See |diagnostic-severity|.
 ---         - float: (boolean or table, default true) If "true", call |vim.diagnostic.open_float()|
----                    after moving. If a table, pass the table as the {opts} parameter to
----                    |vim.diagnostic.open_float()|. Unless overridden, the float will show
+---                    after moving. If a table, pass the table as the {opts} parameter
+---                    to |vim.diagnostic.open_float()|. Unless overridden, the float will show
 ---                    diagnostics at the new cursor position (as if "cursor" were passed to
 ---                    the "scope" option).
 ---         - win_id: (number, default 0) Window ID
@@ -1213,8 +1213,8 @@ end
 
 --- Show diagnostics in a floating window.
 ---
----@param opts table|nil Configuration table with the same keys as
----            |vim.lsp.util.open_floating_preview()| in addition to the following:
+---@param opts table|nil Configuration table with the same keys
+---            as |vim.lsp.util.open_floating_preview()| in addition to the following:
 ---            - bufnr: (number) Buffer number to show diagnostics from.
 ---                     Defaults to the current buffer.
 ---            - namespace: (number) Limit diagnostics to the given namespace
@@ -1227,16 +1227,15 @@ end
 ---                   otherwise, a (row, col) tuple.
 ---            - severity_sort: (default false) Sort diagnostics by severity. Overrides the setting
 ---                             from |vim.diagnostic.config()|.
----            - severity: See |diagnostic-severity|. Overrides the setting from
----                        |vim.diagnostic.config()|.
+---            - severity: See |diagnostic-severity|. Overrides the setting
+---                        from |vim.diagnostic.config()|.
 ---            - header: (string or table) String to use as the header for the floating window. If a
 ---                      table, it is interpreted as a [text, hl_group] tuple. Overrides the setting
 ---                      from |vim.diagnostic.config()|.
 ---            - source: (boolean or string) Include the diagnostic source in the message.
 ---                      Use "if_many" to only show sources if there is more than one source of
 ---                      diagnostics in the buffer. Otherwise, any truthy value means to always show
----                      the diagnostic source. Overrides the setting from
----                      |vim.diagnostic.config()|.
+---                      the diagnostic source. Overrides the setting from |vim.diagnostic.config()|.
 ---            - 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.
 ---                      Overrides the setting from |vim.diagnostic.config()|.
@@ -1692,8 +1691,7 @@ end
 
 --- Convert a list of quickfix items to a list of diagnostics.
 ---
----@param list table A list of quickfix items from |getqflist()| or
----            |getloclist()|.
+---@param list table[] List of quickfix items from |getqflist()| or |getloclist()|.
 ---@return Diagnostic[] array of |diagnostic-structure|
 function M.fromqflist(list)
   vim.validate({

runtime/lua/vim/loader.lua

@@ -18,7 +18,7 @@ local M = {}
 ---@class ModuleInfo
 ---@field modpath string Path of the module
 ---@field modname string Name of the module
----@field stat? uv_fs_t File stat of the module path
+---@field stat? uv.uv_fs_t File stat of the module path
 
 ---@alias LoaderStats table<string, {total:number, time:number, [string]:number?}?>
 

runtime/lua/vim/lsp.lua

@@ -364,7 +364,7 @@ do
   --- @field lines string[] snapshot of buffer lines from last didChange
   --- @field lines_tmp string[]
   --- @field pending_changes table[] List of debounced changes in incremental sync mode
-  --- @field timer nil|uv_timer_t uv_timer
+  --- @field timer nil|uv.uv_timer_t uv_timer
   --- @field last_flush nil|number uv.hrtime of the last flush/didChange-notification
   --- @field needs_flush boolean true if buffer updates haven't been sent to clients/servers yet
   --- @field refs integer how many clients are using this group

runtime/lua/vim/lsp/types.lua → runtime/lua/vim/lsp/_meta.lua

@@ -1,4 +1,5 @@
 ---@meta
+error('Cannot require a meta file')
 
 ---@alias lsp-handler fun(err: lsp.ResponseError|nil, result: any, context: lsp.HandlerContext, config: table|nil): any?
 

runtime/lua/vim/lsp/types/protocol.lua → runtime/lua/vim/lsp/_meta/protocol.lua

@@ -1,9 +1,12 @@
 --[[
 This file is autogenerated from scripts/gen_lsp.lua
 Regenerate:
-nvim -l scripts/gen_lsp.lua gen --version 3.18 --runtime/lua/vim/lsp/types/protocol.lua
+nvim -l scripts/gen_lsp.lua gen --version 3.18 --runtime/lua/vim/lsp/_meta/protocol.lua
 --]]
 
+---@meta
+error('Cannot require a meta file')
+
 ---@alias lsp.null nil
 ---@alias uinteger integer
 ---@alias lsp.decimal number

runtime/lua/vim/lsp/_watchfiles.lua

@@ -6,11 +6,13 @@ local lpeg = vim.lpeg
 
 local M = {}
 
+---@alias lpeg userdata
+
 --- Parses the raw pattern into an |lpeg| pattern. LPeg patterns natively support the "this" or "that"
 --- alternative constructions described in the LSP spec that cannot be expressed in a standard Lua pattern.
 ---
 ---@param pattern string The raw glob pattern
----@return userdata An |lpeg| representation of the pattern, or nil if the pattern is invalid.
+---@return lpeg An |lpeg| representation of the pattern, or nil if the pattern is invalid.
 local function parse(pattern)
   local l = lpeg
 
@@ -109,7 +111,7 @@ local to_lsp_change_type = {
 
 --- Default excludes the same as VSCode's `files.watcherExclude` setting.
 --- https://github.com/microsoft/vscode/blob/eef30e7165e19b33daa1e15e92fa34ff4a5df0d3/src/vs/workbench/contrib/files/browser/files.contribution.ts#L261
----@type Lpeg pattern
+---@type lpeg parsed Lpeg pattern
 M._poll_exclude_pattern = parse('**/.git/{objects,subtree-cache}/**')
   + parse('**/node_modules/*/**')
   + parse('**/.hg/store/**')
@@ -132,7 +134,7 @@ function M.register(reg, ctx)
   if not has_capability or not client.workspace_folders then
     return
   end
-  local watch_regs = {} --- @type table<string,{pattern:userdata,kind:integer}>
+  local watch_regs = {} --- @type table<string,{pattern:lpeg,kind:integer}>
   for _, w in ipairs(reg.registerOptions.watchers) do
     local relative_pattern = false
     local glob_patterns = {} --- @type {baseUri:string, pattern: string}[]

runtime/lua/vim/lsp/inlay_hint.lua

@@ -5,8 +5,8 @@ local api = vim.api
 local M = {}
 
 ---@class lsp.inlay_hint.bufstate
----@field version integer
----@field client_hint table<integer, table<integer, lsp.InlayHint[]>> client_id -> (lnum -> hints)
+---@field version? integer
+---@field client_hint? table<integer, table<integer, lsp.InlayHint[]>> client_id -> (lnum -> hints)
 ---@field applied table<integer, integer> Last version of hints applied to this line
 ---@field enabled boolean Whether inlay hints are enabled for this buffer
 ---@type table<integer, lsp.inlay_hint.bufstate>