refactor(types): more fixes

8 files changed, 84 insertions, 40 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 42577cae2e..189c26bb7a 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1433,9 +1433,6 @@ vim.env                                                              *vim.env*
         print(vim.env.TERM)
 <
 
-    Parameters: ~
-      • {var}  (`string`)
-
 vim.go                                                                *vim.go*
     Get or set global |options|. Like `:setglobal`. Invalid key is an error.
 
@@ -2927,16 +2924,16 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
                  • path: full path of the current item The function should
                    return `true` if the given item is considered a match.
       • {opts}   (`table`) Optional keyword arguments:
-                 • {path} (`string`) Path to begin searching from. If omitted,
-                   the |current-directory| is used.
-                 • {upward} (`boolean`, default: `false`) Search upward
+                 • {path}? (`string`) Path to begin searching from. If
+                   omitted, the |current-directory| is used.
+                 • {upward}? (`boolean`, default: `false`) Search upward
                    through parent directories. Otherwise, search through child
                    directories (recursively).
-                 • {stop} (`string`) Stop searching when this directory is
+                 • {stop}? (`string`) Stop searching when this directory is
                    reached. The directory itself is not searched.
-                 • {type} (`string`) Find only items of the given type. If
+                 • {type}? (`string`) Find only items of the given type. If
                    omitted, all items that match {names} are included.
-                 • {limit} (`number`, default: `1`) Stop the search after
+                 • {limit}? (`number`, default: `1`) Stop the search after
                    finding this many matches. Use `math.huge` to place no
                    limit on the number of matches.
 
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index d14007312e..c588802193 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -275,6 +275,7 @@ do
       for _, line in ipairs(lines) do
         nchars = nchars + line:len()
       end
+      --- @type integer, integer
       local row, col = unpack(vim.api.nvim_win_get_cursor(0))
       local bufline = vim.api.nvim_buf_get_lines(0, row - 1, row, true)[1]
       local firstline = lines[1]
@@ -355,8 +356,11 @@ end
 -- vim.fn.{func}(...)
 ---@nodoc
 vim.fn = setmetatable({}, {
+  --- @param t table<string,function>
+  --- @param key string
+  --- @return function
   __index = function(t, key)
-    local _fn
+    local _fn --- @type function
     if vim.api[key] ~= nil then
       _fn = function()
         error(string.format('Tried to call API function with vim.fn: use vim.api.%s instead', key))
@@ -620,7 +624,7 @@ function vim.notify(msg, level, opts) -- luacheck: no unused args
 end
 
 do
-  local notified = {}
+  local notified = {} --- @type table<string,true>
 
   --- Displays a notification only one time.
   ---
@@ -641,7 +645,7 @@ do
   end
 end
 
-local on_key_cbs = {}
+local on_key_cbs = {} --- @type table<integer,function>
 
 --- Adds Lua function {fn} with namespace id {ns_id} as a listener to every,
 --- yes every, input key.
@@ -711,6 +715,7 @@ end
 --- 2. Can we get it to return things from global namespace even with `print(` in front.
 ---
 --- @param pat string
+--- @return any[], integer
 function vim._expand_pat(pat, env)
   env = env or _G
 
@@ -743,7 +748,7 @@ function vim._expand_pat(pat, env)
     if type(final_env) ~= 'table' then
       return {}, 0
     end
-    local key
+    local key --- @type any
 
     -- Normally, we just have a string
     -- Just attempt to get the string directly from the environment
@@ -785,7 +790,8 @@ function vim._expand_pat(pat, env)
     end
   end
 
-  local keys = {}
+  local keys = {} --- @type table<string,true>
+  --- @param obj table<any,any>
   local function insert_keys(obj)
     for k, _ in pairs(obj) do
       if type(k) == 'string' and string.sub(k, 1, string.len(match_part)) == match_part then
@@ -813,6 +819,7 @@ function vim._expand_pat(pat, env)
 end
 
 --- @param lua_string string
+--- @return (string|string[])[], integer
 vim._expand_pat_get_parts = function(lua_string)
   local parts = {}
 
@@ -870,6 +877,7 @@ vim._expand_pat_get_parts = function(lua_string)
     end
   end
 
+  --- @param val any[]
   parts = vim.tbl_filter(function(val)
     return #val > 0
   end, parts)
@@ -880,7 +888,7 @@ end
 do
   -- Ideally we should just call complete() inside omnifunc, though there are
   -- some bugs, so fake the two-step dance for now.
-  local matches
+  local matches --- @type any[]
 
   --- Omnifunc for completing Lua values from the runtime Lua interpreter,
   --- similar to the builtin completion for the `:lua` command.
diff --git a/runtime/lua/vim/_init_packages.lua b/runtime/lua/vim/_init_packages.lua
index 71ac3bcfcd..d0bb91114e 100644
--- a/runtime/lua/vim/_init_packages.lua
+++ b/runtime/lua/vim/_init_packages.lua
@@ -1,5 +1,5 @@
-local pathtrails = {}
-vim._so_trails = {}
+local pathtrails = {} --- @type table<string,true> ta
+vim._so_trails = {} --- @type string[]
 for s in (package.cpath .. ';'):gmatch('[^;]*;') do
   s = s:sub(1, -2) -- Strip trailing semicolon
   -- Find out path patterns. pathtrail should contain something like
@@ -65,6 +65,7 @@ vim._submodules = {
 
 -- These are for loading runtime modules in the vim namespace lazily.
 setmetatable(vim, {
+  --- @param t table<any,any>
   __index = function(t, key)
     if vim._submodules[key] then
       t[key] = require('vim.' .. key)
@@ -73,6 +74,7 @@ setmetatable(vim, {
       require('vim._inspector')
       return t[key]
     elseif vim.startswith(key, 'uri_') then
+      --- @type any?
       local val = require('vim.uri')[key]
       if val ~= nil then
         -- Expose all `vim.uri` functions on the `vim` module.
diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua
index 8e34ee534c..d61dd2c02f 100644
--- a/runtime/lua/vim/_meta/api_keysets_extra.lua
+++ b/runtime/lua/vim/_meta/api_keysets_extra.lua
@@ -129,7 +129,7 @@ error('Cannot require a meta file')
 --- @field last_set_chan integer
 --- @field type 'string'|'boolean'|'number'
 --- @field default string|boolean|integer
---- @field allow_duplicates boolean
+--- @field allows_duplicates boolean
 
 --- @class vim.api.keyset.parse_cmd.mods
 --- @field filter { force: boolean, pattern: string }
diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index b661ddfb22..60dcf8c64a 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -105,6 +105,10 @@ local key_value_options = {
   winhl = true,
 }
 
+--- @nodoc
+--- @class vim._option.Info : vim.api.keyset.get_option_info
+--- @field metatype 'boolean'|'string'|'number'|'map'|'array'|'set'
+
 --- Convert a vimoption_T style dictionary to the correct OptionType associated with it.
 ---@return string
 local function get_option_metatype(name, info)
@@ -123,8 +127,10 @@ local function get_option_metatype(name, info)
 end
 
 --- @param name string
+--- @return vim._option.Info
 local function get_options_info(name)
   local info = api.nvim_get_option_info2(name, {})
+  --- @cast info vim._option.Info
   info.metatype = get_option_metatype(name, info)
   return info
 end
@@ -139,7 +145,6 @@ end
 --- vim.env.FOO = 'bar'
 --- print(vim.env.TERM)
 --- ```
----@param var string
 vim.env = setmetatable({}, {
   __index = function(_, k)
     local v = vim.fn.getenv(k)
@@ -311,9 +316,15 @@ vim.wo = new_win_opt_accessor()
 --- For information on how to use, see :help vim.opt
 
 --- Preserves the order and does not mutate the original list
+--- @generic T
+--- @param t T[]
+--- @return T[]
 local function remove_duplicate_values(t)
+  --- @type table, table<any,true>
   local result, seen = {}, {}
-  for _, v in ipairs(t) do
+  for _, v in
+    ipairs(t --[[@as any[] ]])
+  do
     if not seen[v] then
       table.insert(result, v)
     end
@@ -324,8 +335,11 @@ local function remove_duplicate_values(t)
   return result
 end
 
--- Check whether the OptionTypes is allowed for vim.opt
--- If it does not match, throw an error which indicates which option causes the error.
+--- Check whether the OptionTypes is allowed for vim.opt
+--- If it does not match, throw an error which indicates which option causes the error.
+--- @param name any
+--- @param value any
+--- @param types string[]
 local function assert_valid_value(name, value, types)
   local type_of_value = type(value)
   for _, valid_type in ipairs(types) do
@@ -352,6 +366,8 @@ local function tbl_merge(left, right)
   return vim.tbl_extend('force', left, right)
 end
 
+--- @param t table<any,any>
+--- @param value any|any[]
 local function tbl_remove(t, value)
   if type(value) == 'string' then
     t[value] = nil
@@ -380,6 +396,8 @@ local to_vim_value = {
   number = passthrough,
   string = passthrough,
 
+  --- @param info vim._option.Info
+  --- @param value string|table<string,true>
   set = function(info, value)
     if type(value) == 'string' then
       return value
@@ -407,6 +425,8 @@ local to_vim_value = {
     end
   end,
 
+  --- @param info vim._option.Info
+  --- @param value string|string[]
   array = function(info, value)
     if type(value) == 'string' then
       return value
@@ -417,6 +437,7 @@ local to_vim_value = {
     return table.concat(value, ',')
   end,
 
+  --- @param value string|table<string,string>
   map = function(_, value)
     if type(value) == 'string' then
       return value
@@ -466,7 +487,8 @@ local to_lua_value = {
     end
 
     -- Handles unescaped commas in a list.
-    if string.find(value, ',,,') then
+    if value:find(',,,') then
+      --- @type string, string
       local left, right = unpack(vim.split(value, ',,,'))
 
       local result = {}
@@ -479,8 +501,9 @@ local to_lua_value = {
       return result
     end
 
-    if string.find(value, ',^,,', 1, true) then
-      local left, right = unpack(vim.split(value, ',^,,', true))
+    if value:find(',^,,', 1, true) then
+      --- @type string, string
+      local left, right = unpack(vim.split(value, ',^,,', { plain = true }))
 
       local result = {}
       vim.list_extend(result, vim.split(left, ','))
@@ -508,22 +531,20 @@ local to_lua_value = {
 
     assert(info.flaglist, 'That is the only one I know how to handle')
 
+    local result = {} --- @type table<string,true>
+
     if info.flaglist and info.commalist then
       local split_value = vim.split(value, ',')
-      local result = {}
       for _, v in ipairs(split_value) do
         result[v] = true
       end
-
-      return result
     else
-      local result = {}
       for i = 1, #value do
         result[value:sub(i, i)] = true
       end
-
-      return result
     end
+
+    return result
   end,
 
   map = function(info, raw_value)
@@ -533,10 +554,11 @@ local to_lua_value = {
 
     assert(info.commalist, 'Only commas are supported currently')
 
-    local result = {}
+    local result = {} --- @type table<string,string>
 
     local comma_split = vim.split(raw_value, ',')
     for _, key_value_str in ipairs(comma_split) do
+      --- @type string, string
       local key, value = unpack(vim.split(key_value_str, ':'))
       key = vim.trim(key)
 
@@ -582,14 +604,21 @@ local function prepend_value(info, current, new)
 end
 
 local add_methods = {
+  --- @param left integer
+  --- @param right integer
   number = function(left, right)
     return left + right
   end,
 
+  --- @param left string
+  --- @param right string
   string = function(left, right)
     return left .. right
   end,
 
+  --- @param left string[]
+  --- @param right string[]
+  --- @return string[]
   array = function(left, right)
     for _, v in ipairs(right) do
       table.insert(left, v)
@@ -610,6 +639,8 @@ local function add_value(info, current, new)
   )
 end
 
+--- @param t table<any,any>
+--- @param val any
 local function remove_one_item(t, val)
   if vim.tbl_islist(t) then
     local remove_index = nil
@@ -628,6 +659,8 @@ local function remove_one_item(t, val)
 end
 
 local remove_methods = {
+  --- @param left integer
+  --- @param right integer
   number = function(left, right)
     return left - right
   end,
@@ -636,6 +669,9 @@ local remove_methods = {
     error('Subtraction not supported for strings.')
   end,
 
+  --- @param left string[]
+  --- @param right string[]
+  --- @return string[]
   array = function(left, right)
     if type(right) == 'string' then
       remove_one_item(left, right)
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index a47b35e991..28a531707f 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -152,25 +152,25 @@ end
 ---
 --- Path to begin searching from. If
 --- omitted, the |current-directory| is used.
---- @field path string
+--- @field path? string
 ---
 --- Search upward through parent directories.
 --- Otherwise, search through child directories (recursively).
 --- (default: `false`)
---- @field upward boolean
+--- @field upward? boolean
 ---
 --- Stop searching when this directory is reached.
 --- The directory itself is not searched.
---- @field stop string
+--- @field stop? string
 ---
 --- Find only items of the given type.
 --- If omitted, all items that match {names} are included.
---- @field type string
+--- @field type? string
 ---
 --- Stop the search after finding this many matches.
 --- Use `math.huge` to place no limit on the number of matches.
 --- (default: `1`)
---- @field limit number
+--- @field limit? number
 
 --- Find files or directories (or other items as specified by `opts.type`) in the given path.
 ---
@@ -229,7 +229,7 @@ function M.find(names, opts)
     names = { names }
   end
 
-  local path = opts.path or vim.uv.cwd()
+  local path = opts.path or assert(vim.uv.cwd())
   local stop = opts.stop
   local limit = opts.limit or 1
 
diff --git a/runtime/lua/vim/loader.lua b/runtime/lua/vim/loader.lua
index 0d708ca1eb..d3d8948654 100644
--- a/runtime/lua/vim/loader.lua
+++ b/runtime/lua/vim/loader.lua
@@ -7,7 +7,7 @@ local loaders = package.loaders
 
 local M = {}
 
----@alias CacheHash {mtime: {nsec: integer, sec: integer}, size: integer, type?: uv.aliases.fs_stat_types}
+---@alias CacheHash {mtime: {nsec: integer, sec: integer}, size: integer, type?: string}
 ---@alias CacheEntry {hash:CacheHash, chunk:string}
 
 --- @class vim.loader.find.Opts
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 18d7c8b13e..6e50b87dd5 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -592,7 +592,8 @@ function vim.spairs(t)
     if keys[i] then
       return keys[i], t[keys[i]]
     end
-  end
+  end,
+    t
 end
 
 --- Tests if `t` is an "array": a table indexed _only_ by integers (potentially non-contiguous).