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/explorer/explore.lua

@@ -11,10 +11,17 @@ local Watcher = require "nvim-tree.watcher"
 
 local M = {}
 
+---@param type_ string|nil
+---@param cwd string
+---@return any
 local function get_type_from(type_, cwd)
   return type_ or (vim.loop.fs_stat(cwd) or {}).type
 end
 
+---@param handle uv.uv_fs_t
+---@param cwd string
+---@param node Node
+---@param git_status table
 local function populate_children(handle, cwd, node, git_status)
   local node_ignored = explorer_node.is_git_ignored(node)
   local nodes_by_path = utils.bool_record(node.nodes, "absolute_path")
@@ -53,6 +60,9 @@ local function populate_children(handle, cwd, node, git_status)
   end
 end
 
+---@param node Node
+---@param status table
+---@return Node[]|nil
 function M.explore(node, status)
   local cwd = node.link_to or node.absolute_path
   local handle = vim.loop.fs_scandir(cwd)

lua/nvim-tree/explorer/filters.lua

@@ -5,6 +5,8 @@ local M = {
   exclude_list = {},
 }
 
+---@param path string
+---@return boolean
 local function is_excluded(path)
   for _, node in ipairs(M.exclude_list) do
     if path:match(node) then
@@ -61,10 +63,14 @@ local function buf(path, bufinfo, unloaded_bufnr)
   return true
 end
 
+---@param path string
+---@return boolean
 local function dotfile(path)
   return M.config.filter_dotfiles and utils.path_basename(path):sub(1, 1) == "."
 end
 
+---@param path string
+---@return boolean
 local function custom(path)
   if not M.config.filter_custom then
     return false

lua/nvim-tree/explorer/init.lua

@@ -7,11 +7,20 @@ local M = {}
 M.explore = require("nvim-tree.explorer.explore").explore
 M.reload = require("nvim-tree.explorer.reload").reload
 
+---@class Explorer
+---@field absolute_path string
+---@field nodes Node[]
+---@field open boolean
+
 local Explorer = {}
 Explorer.__index = Explorer
 
+---@param cwd string|nil
+---@return Explorer
 function Explorer.new(cwd)
   cwd = vim.loop.fs_realpath(cwd or vim.loop.cwd())
+
+  ---@class Explorer
   local explorer = setmetatable({
     absolute_path = cwd,
     nodes = {},
@@ -22,12 +31,15 @@ function Explorer.new(cwd)
   return explorer
 end
 
+---@private
+---@param node Node
 function Explorer:_load(node)
   local cwd = node.link_to or node.absolute_path
   local git_status = git.load_project_status(cwd)
   M.explore(node, git_status)
 end
 
+---@param node Node
 function Explorer:expand(node)
   self:_load(node)
 end

lua/nvim-tree/explorer/node-builders.lua

@@ -3,6 +3,10 @@ local watch = require "nvim-tree.explorer.watch"
 
 local M = {}
 
+---@param parent Node
+---@param absolute_path string
+---@param name string
+---@return Node
 function M.folder(parent, absolute_path, name)
   local handle = vim.loop.fs_scandir(absolute_path)
   local has_children = handle and vim.loop.fs_scandir_next(handle) ~= nil
@@ -25,8 +29,8 @@ function M.folder(parent, absolute_path, name)
 end
 
 --- path is an executable file or directory
---- @param absolute_path string
---- @return boolean
+---@param absolute_path string
+---@return boolean|nil
 function M.is_executable(absolute_path)
   if utils.is_windows or utils.is_wsl then
     --- executable detection on windows is buggy and not performant hence it is disabled
@@ -36,6 +40,10 @@ function M.is_executable(absolute_path)
   end
 end
 
+---@param parent Node
+---@param absolute_path string
+---@param name string
+---@return Node
 function M.file(parent, absolute_path, name)
   local ext = string.match(name, ".?[^.]+%.(.*)") or ""
 
@@ -55,6 +63,10 @@ end
 -- links (for instance libr2.so in /usr/lib) and thus even with a C program realpath fails
 -- when it has no real reason to. Maybe there is a reason, but errno is definitely wrong.
 -- So we need to check for link_to ~= nil when adding new links to the main tree
+---@param parent Node
+---@param absolute_path string
+---@param name string
+---@return Node
 function M.link(parent, absolute_path, name)
   --- I dont know if this is needed, because in my understanding, there isn't hard links in windows, but just to be sure i changed it.
   local link_to = vim.loop.fs_realpath(absolute_path)

lua/nvim-tree/explorer/node.lua

@@ -1,14 +1,13 @@
 local M = {}
 
--- node.git_status structure:
--- {
---   file = string | nil,
---   dir = {
---     direct = { string } | nil,
---     indirect = { string } | nil,
---   } | nil,
--- }
+---@class GitStatus
+---@field file string|nil
+---@field dir table|nil
 
+---@param parent_ignored boolean
+---@param status table|nil
+---@param absolute_path string
+---@return GitStatus|nil
 local function get_dir_git_status(parent_ignored, status, absolute_path)
   if parent_ignored then
     return { file = "!!" }
@@ -25,15 +24,24 @@ local function get_dir_git_status(parent_ignored, status, absolute_path)
   end
 end
 
+---@param parent_ignored boolean
+---@param status table
+---@param absolute_path string
+---@return GitStatus
 local function get_git_status(parent_ignored, status, absolute_path)
   local file_status = parent_ignored and "!!" or status.files and status.files[absolute_path]
   return { file = file_status }
 end
 
+---@param node Node
+---@return boolean
 function M.has_one_child_folder(node)
-  return #node.nodes == 1 and node.nodes[1].nodes and vim.loop.fs_access(node.nodes[1].absolute_path, "R")
+  return #node.nodes == 1 and node.nodes[1].nodes and vim.loop.fs_access(node.nodes[1].absolute_path, "R") or false
 end
 
+---@param node Node
+---@param parent_ignored boolean
+---@param status table|nil
 function M.update_git_status(node, parent_ignored, status)
   local get_status
   if node.nodes then
@@ -51,6 +59,8 @@ function M.update_git_status(node, parent_ignored, status)
   end
 end
 
+---@param node Node
+---@return GitStatus|nil
 function M.get_git_status(node)
   local git_status = node and node.git_status
   if not git_status then
@@ -112,10 +122,13 @@ function M.get_git_status(node)
   end
 end
 
+---@param node Node
+---@return boolean
 function M.is_git_ignored(node)
-  return node and node.git_status and node.git_status.file == "!!"
+  return node and node.git_status ~= nil and node.git_status.file == "!!"
 end
 
+---@param node Node
 function M.node_destroy(node)
   if not node then
     return

lua/nvim-tree/explorer/reload.lua

@@ -12,6 +12,10 @@ local Watcher = require "nvim-tree.watcher"
 
 local M = {}
 
+---@param nodes_by_path table
+---@param node_ignored boolean
+---@param status table
+---@return fun(node: Node): table
 local function update_status(nodes_by_path, node_ignored, status)
   return function(node)
     if nodes_by_path[node.absolute_path] then
@@ -21,6 +25,8 @@ local function update_status(nodes_by_path, node_ignored, status)
   end
 end
 
+---@param path string
+---@param callback fun(toplevel: string|nil, project: table|nil)
 local function reload_and_get_git_project(path, callback)
   local toplevel = git.get_toplevel(path)
 
@@ -29,6 +35,9 @@ local function reload_and_get_git_project(path, callback)
   end)
 end
 
+---@param node Node
+---@param project table|nil
+---@param root string|nil
 local function update_parent_statuses(node, project, root)
   while project and node do
     -- step up to the containing project
@@ -58,6 +67,9 @@ local function update_parent_statuses(node, project, root)
   end
 end
 
+---@param node Node
+---@param git_status table
+---@param unloaded_bufnr number|nil
 function M.reload(node, git_status, unloaded_bufnr)
   local cwd = node.link_to or node.absolute_path
   local handle = vim.loop.fs_scandir(cwd)
@@ -143,7 +155,7 @@ function M.reload(node, git_status, unloaded_bufnr)
         return child_names[n.absolute_path]
       else
         explorer_node.node_destroy(n)
-        return nil
+        return false
       end
     end, node.nodes)
   )
@@ -165,7 +177,7 @@ function M.reload(node, git_status, unloaded_bufnr)
 end
 
 ---Refresh contents and git status for a single node
----@param node table
+---@param node Node
 ---@param callback function
 function M.refresh_node(node, callback)
   if type(node) ~= "table" then

lua/nvim-tree/explorer/sorters.lua

@@ -3,8 +3,8 @@ local M = {}
 local C = {}
 
 --- Predefined comparator, defaulting to name
---- @param sorter string as per options
---- @return function
+---@param sorter string as per options
+---@return function
 local function get_comparator(sorter)
   return C[sorter] or C.name
 end
@@ -24,8 +24,8 @@ local function tbl_slice(t, first, last)
 end
 
 ---Evaluate `sort.folders_first` and `sort.files_first`
----@param a table node
----@param b table node
+---@param a Node
+---@param b Node
 ---@return boolean|nil
 local function folders_or_files_first(a, b)
   if not (M.config.sort.folders_first or M.config.sort.files_first) then
@@ -41,6 +41,11 @@ local function folders_or_files_first(a, b)
   end
 end
 
+---@param t table
+---@param first number
+---@param mid number
+---@param last number
+---@param comparator fun(a: Node, b: Node): boolean
 local function merge(t, first, mid, last, comparator)
   local n1 = mid - first + 1
   local n2 = last - mid
@@ -74,6 +79,10 @@ local function merge(t, first, mid, last, comparator)
   end
 end
 
+---@param t table
+---@param first number
+---@param last number
+---@param comparator fun(a: Node, b: Node): boolean
 local function split_merge(t, first, last, comparator)
   if (last - first) < 1 then
     return
@@ -137,6 +146,10 @@ function M.sort(t)
   end
 end
 
+---@param a Node
+---@param b Node
+---@param ignorecase boolean|nil
+---@return boolean
 local function node_comparator_name_ignorecase_or_not(a, b, ignorecase)
   if not (a and b) then
     return true

lua/nvim-tree/explorer/watch.lua

@@ -7,6 +7,8 @@ local M = {
   uid = 0,
 }
 
+---@param path string
+---@return boolean
 local function is_git(path)
   -- If $GIT_DIR is set, consider its value to be equivalent to '.git'.
   -- Expand $GIT_DIR (and `path`) to a full path (see :help filename-modifiers), since
@@ -29,6 +31,8 @@ local IGNORED_PATHS = {
   "/dev",
 }
 
+---@param path string
+---@return boolean
 local function is_folder_ignored(path)
   for _, folder in ipairs(IGNORED_PATHS) do
     if vim.startswith(path, folder) then
@@ -45,18 +49,14 @@ local function is_folder_ignored(path)
   return false
 end
 
+---@param node Node
+---@return Watcher|nil
 function M.create_watcher(node)
   if not M.config.filesystem_watchers.enable or type(node) ~= "table" then
     return nil
   end
 
-  local path
-  if node.type == "link" then
-    path = node.link_to
-  else
-    path = node.absolute_path
-  end
-
+  local path = node.link_to or node.absolute_path
   if is_git(path) or is_folder_ignored(path) then
     return nil
   end