chore: add type annotations and resolve LSP warnings

lua/nvim-tree.lua

@@ -17,6 +17,31 @@ local open = require "nvim-tree.actions.tree.open"
 local events = require "nvim-tree.events"
 local notify = require "nvim-tree.notify"
 
+---@class ParentNode
+---@field name string
+
+---@class BaseNode
+---@field absolute_path string
+---@field executable boolean
+---@field fs_stat uv_fs_t
+---@field git_status GitStatus|nil
+---@field hidden boolean
+---@field name string
+---@field parent DirNode
+---@field type string
+---@field watcher function|nil
+
+---@class DirNode: BaseNode
+---@field has_children boolean
+---@field group_next Node|nil
+---@field nodes Node[]
+---@field open boolean
+
+---@class FileNode: BaseNode
+---@field extension string
+
+---@alias Node ParentNode|DirNode|FileNode
+
 local _config = {}
 
 local M = {
@@ -79,6 +104,7 @@ function M.change_root(path, bufnr)
   change_dir.fn(vim.fn.fnamemodify(path, ":p:h"))
 end
 
+---@param cwd string|nil
 function M.open_replacing_current_buffer(cwd)
   if view.is_visible() then
     return
@@ -159,10 +185,13 @@ function M.place_cursor_on_node()
   end
 end
 
+---@return table
 function M.get_config()
   return M.config
 end
 
+---@param disable_netrw boolean
+---@param hijack_netrw boolean
 local function manage_netrw(disable_netrw, hijack_netrw)
   if hijack_netrw then
     vim.cmd "silent! autocmd! FileExplorer *"
@@ -174,6 +203,7 @@ local function manage_netrw(disable_netrw, hijack_netrw)
   end
 end
 
+---@param name string|nil
 function M.change_dir(name)
   change_dir.fn(name)
 
@@ -182,6 +212,7 @@ function M.change_dir(name)
   end
 end
 
+---@param opts table
 local function setup_autocommands(opts)
   local augroup_id = vim.api.nvim_create_augroup("NvimTree", { clear = true })
   local function create_nvim_tree_autocmd(name, custom_opts)
@@ -677,9 +708,15 @@ local ACCEPTED_STRINGS = {
   },
 }
 
+---@param conf table
 local function validate_options(conf)
   local msg
 
+  ---@param user any
+  ---@param def any
+  ---@param strs table
+  ---@param types table
+  ---@param prefix string
   local function validate(user, def, strs, types, prefix)
     -- if user's option is not a table there is nothing to do
     if type(user) ~= "table" then
@@ -762,6 +799,7 @@ function M.purge_all_state()
   end
 end
 
+---@param conf table|nil
 function M.setup(conf)
   if vim.fn.has "nvim-0.8" == 0 then
     notify.warn "nvim-tree.lua requires Neovim 0.8 or higher"

lua/nvim-tree/actions/finders/search-node.lua

@@ -4,13 +4,18 @@ local find_file = require("nvim-tree.actions.finders.find-file").fn
 
 local M = {}
 
+---@param search_dir string|nil
+---@param input_path string
+---@return string|nil
 local function search(search_dir, input_path)
   local realpaths_searched = {}
 
   if not search_dir then
     return
   end
 
+  ---@param dir string
+  ---@return string|nil
   local function iter(dir)
     local realpath, path, name, stat, handle, _
 

lua/nvim-tree/actions/fs/copy-paste.lua

@@ -20,6 +20,10 @@ local clipboard = {
   copy = {},
 }
 
+---@param source string
+---@param destination string
+---@return boolean
+---@return string|nil
 local function do_copy(source, destination)
   local source_stats, handle
   local success, errmsg
@@ -81,6 +85,12 @@ local function do_copy(source, destination)
   return true
 end
 
+---@param source string
+---@param dest string
+---@param action_type string
+---@param action_fn fun(source: string, dest: string)
+---@return boolean|nil -- success
+---@return string|nil -- error message
 local function do_single_paste(source, dest, action_type, action_fn)
   local dest_stats
   local success, errmsg, errcode
@@ -140,14 +150,17 @@ local function do_single_paste(source, dest, action_type, action_fn)
   end
 end
 
+---@param node Node
+---@param clip table
 local function toggle(node, clip)
   if node.name == ".." then
     return
   end
   local notify_node = notify.render_path(node.absolute_path)
 
   if utils.array_remove(clip, node) then
-    return notify.info(notify_node .. " removed from clipboard.")
+    notify.info(notify_node .. " removed from clipboard.")
+    return
   end
 
   table.insert(clip, node)
@@ -161,18 +174,23 @@ function M.clear_clipboard()
   renderer.draw()
 end
 
+---@param node Node
 function M.copy(node)
   utils.array_remove(clipboard.cut, node)
   toggle(node, clipboard.copy)
   renderer.draw()
 end
 
+---@param node Node
 function M.cut(node)
   utils.array_remove(clipboard.copy, node)
   toggle(node, clipboard.cut)
   renderer.draw()
 end
 
+---@param node Node
+---@param action_type string
+---@param action_fn fun(source: string, dest: string)
 local function do_paste(node, action_type, action_fn)
   node = lib.get_last_group_node(node)
   if node.name == ".." then
@@ -202,10 +220,14 @@ local function do_paste(node, action_type, action_fn)
 
   clipboard[action_type] = {}
   if not M.config.filesystem_watchers.enable then
-    return reloaders.reload_explorer()
+    reloaders.reload_explorer()
   end
 end
 
+---@param source string
+---@param destination string
+---@return boolean
+---@return string?
 local function do_cut(source, destination)
   log.line("copy_paste", "do_cut '%s' -> '%s'", source, destination)
 
@@ -225,12 +247,13 @@ local function do_cut(source, destination)
   return true
 end
 
+---@param node Node
 function M.paste(node)
   if clipboard.cut[1] ~= nil then
-    return do_paste(node, "cut", do_cut)
+    do_paste(node, "cut", do_cut)
+  else
+    do_paste(node, "copy", do_copy)
   end
-
-  return do_paste(node, "copy", do_copy)
 end
 
 function M.print_clipboard()
@@ -248,9 +271,10 @@ function M.print_clipboard()
     end
   end
 
-  return notify.info(table.concat(content, "\n") .. "\n")
+  notify.info(table.concat(content, "\n") .. "\n")
 end
 
+---@param content string
 local function copy_to_clipboard(content)
   local clipboard_name
   if M.config.actions.use_system_clipboard == true then
@@ -264,28 +288,30 @@ local function copy_to_clipboard(content)
   end
 
   vim.api.nvim_exec_autocmds("TextYankPost", {})
-  return notify.info(string.format("Copied %s to %s clipboard!", content, clipboard_name))
+  notify.info(string.format("Copied %s to %s clipboard!", content, clipboard_name))
 end
 
+---@param node Node
 function M.copy_filename(node)
-  return copy_to_clipboard(node.name)
+  copy_to_clipboard(node.name)
 end
 
+---@param node Node
 function M.copy_path(node)
   local absolute_path = node.absolute_path
   local relative_path = utils.path_relative(absolute_path, core.get_cwd())
   local content = node.nodes ~= nil and utils.path_add_trailing(relative_path) or relative_path
-  return copy_to_clipboard(content)
+  copy_to_clipboard(content)
 end
 
 function M.copy_absolute_path(node)
   local absolute_path = node.absolute_path
   local content = node.nodes ~= nil and utils.path_add_trailing(absolute_path) or absolute_path
-  return copy_to_clipboard(content)
+  copy_to_clipboard(content)
 end
 
----Clipboard text highlight group and position when highlight_clipboard.
----@param node table
+--- Clipboard text highlight group and position when highlight_clipboard.
+---@param node Node
 ---@return HL_POSITION position none when clipboard empty
 ---@return string|nil group only when node present in clipboard
 function M.get_highlight(node)

lua/nvim-tree/actions/fs/create-file.lua

@@ -8,6 +8,7 @@ local find_file = require("nvim-tree.actions.finders.find-file").fn
 
 local M = {}
 
+---@param file string
 local function create_and_notify(file)
   events._dispatch_will_create_file(file)
   local ok, fd = pcall(vim.loop.fs_open, file, "w", 420)
@@ -19,6 +20,8 @@ local function create_and_notify(file)
   events._dispatch_file_created(file)
 end
 
+---@param iter function iterable
+---@return integer
 local function get_num_nodes(iter)
   local i = 0
   for _ in iter do
@@ -27,6 +30,8 @@ local function get_num_nodes(iter)
   return i
 end
 
+---@param node Node
+---@return string
 local function get_containing_folder(node)
   if node.nodes ~= nil then
     return utils.path_add_trailing(node.absolute_path)
@@ -35,6 +40,7 @@ local function get_containing_folder(node)
   return node.absolute_path:sub(0, -node_name_size - 1)
 end
 
+---@param node Node|nil
 function M.fn(node)
   node = node and lib.get_last_group_node(node)
   if not node or node.name == ".." then

lua/nvim-tree/actions/fs/remove-file.lua

@@ -8,6 +8,7 @@ local M = {
   config = {},
 }
 
+---@param windows table
 local function close_windows(windows)
   -- Prevent from closing when the win count equals 1 or 2,
   -- where the win to remove could be the last opened.
@@ -23,6 +24,7 @@ local function close_windows(windows)
   end
 end
 
+---@param absolute_path string
 local function clear_buffer(absolute_path)
   local bufs = vim.fn.getbufinfo { bufloaded = 1, buflisted = 1 }
   for _, buf in pairs(bufs) do
@@ -44,10 +46,13 @@ local function clear_buffer(absolute_path)
   end
 end
 
+---@param cwd string
+---@return boolean|nil
 local function remove_dir(cwd)
   local handle = vim.loop.fs_scandir(cwd)
   if type(handle) == "string" then
-    return notify.error(handle)
+    notify.error(handle)
+    return
   end
 
   while true do
@@ -75,27 +80,30 @@ local function remove_dir(cwd)
 end
 
 --- Remove a node, notify errors, dispatch events
---- @param node table
+---@param node Node
 function M.remove(node)
   local notify_node = notify.render_path(node.absolute_path)
   if node.nodes ~= nil and not node.link_to then
     local success = remove_dir(node.absolute_path)
     if not success then
-      return notify.error("Could not remove " .. notify_node)
+      notify.error("Could not remove " .. notify_node)
+      return
     end
     events._dispatch_folder_removed(node.absolute_path)
   else
     events._dispatch_will_remove_file(node.absolute_path)
     local success = vim.loop.fs_unlink(node.absolute_path)
     if not success then
-      return notify.error("Could not remove " .. notify_node)
+      notify.error("Could not remove " .. notify_node)
+      return
     end
     events._dispatch_file_removed(node.absolute_path)
     clear_buffer(node.absolute_path)
   end
   notify.info(notify_node .. " was properly removed.")
 end
 
+---@param node Node
 function M.fn(node)
   if node.name == ".." then
     return

lua/nvim-tree/actions/fs/rename-file.lua

@@ -20,6 +20,8 @@ local function err_fmt(from, to, reason)
   return string.format("Cannot rename %s -> %s: %s", from, to, reason)
 end
 
+---@param node Node
+---@param to string
 function M.rename(node, to)
   local notify_from = notify.render_path(node.absolute_path)
   local notify_to = notify.render_path(to)
@@ -32,13 +34,16 @@ function M.rename(node, to)
   events._dispatch_will_rename_node(node.absolute_path, to)
   local success, err = vim.loop.fs_rename(node.absolute_path, to)
   if not success then
-    return notify.warn(err_fmt(notify_from, notify_to, err))
+    notify.warn(err_fmt(notify_from, notify_to, err))
+    return
   end
   notify.info(string.format("%s -> %s", notify_from, notify_to))
   utils.rename_loaded_buffers(node.absolute_path, to)
   events._dispatch_node_renamed(node.absolute_path, to)
 end
 
+---@param default_modifier string|nil
+---@return fun(node: Node, modifier: string)
 function M.fn(default_modifier)
   default_modifier = default_modifier or ":t"
 
@@ -53,7 +58,8 @@ function M.fn(default_modifier)
 
     -- support for only specific modifiers have been implemented
     if not ALLOWED_MODIFIERS[modifier] then
-      return notify.warn("Modifier " .. vim.inspect(modifier) .. " is not in allowed list : " .. table.concat(ALLOWED_MODIFIERS, ","))
+      notify.warn("Modifier " .. vim.inspect(modifier) .. " is not in allowed list : " .. table.concat(ALLOWED_MODIFIERS, ","))
+      return
     end
 
     node = lib.get_last_group_node(node)