chore: add type annotations and resolve LSP warnings (#2555)

* chore: add type annotations to (almost) all functions

* stylua

* Add classes for symlink nodes

* Replace deprecated `@vararg`

* Move node classes to `node` module

* Fix `Symlink*` classes

* add vim and libuv runtime for luals, qualify libuv types

* add scripts/luals-check, not quite ready for CI

* additional nil checks for git/init.lua and git/runner.lua

* additional nil checks for nvim-tree.lua

* wrap vim.cmd-as-a-function calls inside functions

* vim.tbl_filter predicate returns booleans

* Revert "add scripts/luals-check, not quite ready for CI"

This reverts commit c70229cad9.

* Add `MinimalNode` class in `marks` module

* Fix various LSP warnings

* stylua

* Fix `Explorer` class, update related annotations and add necessary checks

* Add missing annotations to `live-filter`

* Add temporary aliases for `uv.*` types

* Resolve remaining LSP warnings

* Revert changes not related to internal types

* Minor adjustments

* Update doc comments style

* Minor adjustments (pt. 2)

---------

Co-authored-by: Alexander Courtis <alex@courtis.org>

lua/nvim-tree/utils.lua

@@ -11,10 +11,15 @@ M.is_wsl = vim.fn.has "wsl" == 1
 -- false for WSL
 M.is_windows = vim.fn.has "win32" == 1 or vim.fn.has "win32unix" == 1
 
+---@param haystack string
+---@param needle string
+---@return boolean
 function M.str_find(haystack, needle)
   return vim.fn.stridx(haystack, needle) ~= -1
 end
 
+---@param path string
+---@return string|uv.uv_fs_t
 function M.read_file(path)
   local fd = vim.loop.fs_open(path, "r", 438)
   if not fd then
@@ -30,15 +35,19 @@ function M.read_file(path)
 end
 
 local path_separator = package.config:sub(1, 1)
+---@param paths string[]
+---@return string
 function M.path_join(paths)
   return table.concat(vim.tbl_map(M.path_remove_trailing, paths), path_separator)
 end
 
+---@param path string
+---@return fun(): string
 function M.path_split(path)
   return path:gmatch("[^" .. path_separator .. "]+" .. path_separator .. "?")
 end
 
----Get the basename of the given path.
+--- Get the basename of the given path.
 ---@param path string
 ---@return string
 function M.path_basename(path)
@@ -50,11 +59,15 @@ function M.path_basename(path)
   return path:sub(i + 1, #path)
 end
 
----Get a path relative to another path.
+--- Get a path relative to another path.
 ---@param path string
----@param relative_to string
+---@param relative_to string|nil
 ---@return string
 function M.path_relative(path, relative_to)
+  if relative_to == nil then
+    return path
+  end
+
   local _, r = path:find(M.path_add_trailing(relative_to), 1, true)
   local p = path
   if r then
@@ -66,6 +79,8 @@ function M.path_relative(path, relative_to)
   return p
 end
 
+---@param path string
+---@return string
 function M.path_add_trailing(path)
   if path:sub(-1) == path_separator then
     return path
@@ -74,6 +89,8 @@ function M.path_add_trailing(path)
   return path .. path_separator
 end
 
+---@param path string
+---@return string
 function M.path_remove_trailing(path)
   local p, _ = path:gsub(path_separator .. "$", "")
   return p
@@ -81,10 +98,12 @@ end
 
 M.path_separator = path_separator
 
--- get the node and index of the node from the tree that matches the predicate.
--- The explored nodes are those displayed on the view.
--- @param nodes list of node
--- @param fn    function(node): boolean
+--- Get the node and index of the node from the tree that matches the predicate.
+--- The explored nodes are those displayed on the view.
+---@param nodes Node[]
+---@param fn fun(node: Node): boolean
+---@return table|nil
+---@return number
 function M.find_node(nodes, fn)
   local node, i = Iterator.builder(nodes)
     :matcher(fn)
@@ -99,6 +118,9 @@ end
 
 -- get the node in the tree state depending on the absolute path of the node
 -- (grouped or hidden too)
+---@param path string
+---@return Node|nil
+---@return number|nil
 function M.get_node_from_path(path)
   local explorer = require("nvim-tree.core").get_explorer()
 
@@ -127,7 +149,9 @@ function M.get_node_from_path(path)
     :iterate()
 end
 
--- get the highest parent of grouped nodes
+--- Get the highest parent of grouped nodes
+---@param node_ Node
+---@return table
 function M.get_parent_of_group(node_)
   local node = node_
   while node.parent and node.parent.group_next do
@@ -136,9 +160,9 @@ function M.get_parent_of_group(node_)
   return node
 end
 
--- return visible nodes indexed by line
--- @param nodes_all list of node
--- @param line_start first index
+--- Return visible nodes indexed by line
+---@param nodes_all Node[]
+---@param line_start number
 ---@return table
 function M.get_nodes_by_line(nodes_all, line_start)
   local nodes_by_line = {}
@@ -192,15 +216,15 @@ function M.rename_loaded_buffers(old_path, new_path)
   end
 end
 
---- @param path string path to file or directory
---- @return boolean
+---@param path string path to file or directory
+---@return boolean
 function M.file_exists(path)
   local _, error = vim.loop.fs_stat(path)
   return error == nil
 end
 
---- @param path string
---- @return string
+---@param path string
+---@return string
 function M.canonical_path(path)
   if M.is_windows and path:match "^%a:" then
     return path:sub(1, 1):upper() .. path:sub(2)
@@ -208,9 +232,9 @@ function M.canonical_path(path)
   return path
 end
 
--- Escapes special characters in string if windows else returns unmodified string.
--- @param path string
--- @return path
+--- Escapes special characters in string if windows else returns unmodified string.
+---@param path string
+---@return string|nil
 function M.escape_special_chars(path)
   if path == nil then
     return path
@@ -218,10 +242,10 @@ function M.escape_special_chars(path)
   return M.is_windows and path:gsub("%(", "\\("):gsub("%)", "\\)") or path
 end
 
--- Create empty sub-tables if not present
--- @param tbl to create empty inside of
--- @param path dot separated string of sub-tables
--- @return table deepest sub-table
+--- Create empty sub-tables if not present
+---@param tbl table to create empty inside of
+---@param path string dot separated string of sub-tables
+---@return table deepest sub-table
 function M.table_create_missing(tbl, path)
   local t = tbl
   for s in string.gmatch(path, "([^%.]+)%.*") do
@@ -236,13 +260,13 @@ end
 
 --- Move a value from src to dst if value is nil on dst.
 --- Remove value from src
---- @param src table to copy from
---- @param src_path string dot separated string of sub-tables
---- @param src_pos string value pos
---- @param dst table to copy to
---- @param dst_path string dot separated string of sub-tables, created when missing
---- @param dst_pos string value pos
---- @param remove boolean
+---@param src table to copy from
+---@param src_path string dot separated string of sub-tables
+---@param src_pos string value pos
+---@param dst table to copy to
+---@param dst_path string dot separated string of sub-tables, created when missing
+---@param dst_pos string value pos
+---@param remove boolean
 function M.move_missing_val(src, src_path, src_pos, dst, dst_path, dst_pos, remove)
   local ok, err = pcall(vim.validate, {
     src = { src, "table" },
@@ -395,7 +419,7 @@ end
 ---Focus node passed as parameter if visible, otherwise focus first visible parent.
 ---If none of the parents is visible focus root.
 ---If node is nil do nothing.
----@param node table|nil node to focus
+---@param node Node|nil node to focus
 function M.focus_node_or_parent(node)
   local explorer = require("nvim-tree.core").get_explorer()
 
@@ -417,6 +441,9 @@ function M.focus_node_or_parent(node)
   end
 end
 
+---@param path string
+---@return integer|nil
+---@return integer|nil
 function M.get_win_buf_from_path(path)
   for _, w in pairs(vim.api.nvim_tabpage_list_wins(0)) do
     local b = vim.api.nvim_win_get_buf(w)
@@ -433,7 +460,9 @@ function M.clear_prompt()
   end
 end
 
--- return a new table with values from array
+--- Return a new table with values from array
+---@param array table
+---@return table
 function M.array_shallow_clone(array)
   local to = {}
   for _, v in ipairs(array) do
@@ -443,9 +472,9 @@ function M.array_shallow_clone(array)
 end
 
 --- Remove and return item from array if present.
---- @param array table
---- @param item any
---- @return any|nil removed
+---@param array table
+---@param item any
+---@return any|nil removed
 function M.array_remove(array, item)
   if not array then
     return nil
@@ -458,20 +487,24 @@ function M.array_remove(array, item)
   end
 end
 
+---@param array table
+---@return table
 function M.array_remove_nils(array)
   return vim.tbl_filter(function(v)
     return v ~= nil
   end, array)
 end
 
+---@param f fun(node: Node|nil)
+---@return function
 function M.inject_node(f)
   return function()
     f(require("nvim-tree.lib").get_node_at_cursor())
   end
 end
 
----Is the buffer named NvimTree_[0-9]+ a tree? filetype is "NvimTree" or not readable file.
----This is cheap, as the readable test should only ever be needed when resuming a vim session.
+--- Is the buffer named NvimTree_[0-9]+ a tree? filetype is "NvimTree" or not readable file.
+--- This is cheap, as the readable test should only ever be needed when resuming a vim session.
 ---@param bufnr number|nil may be 0 or nil for current
 ---@return boolean
 function M.is_nvim_tree_buf(bufnr)