feat(#2948): add nvim_tree.api.* node classes

Author: alex-courtis

lua/nvim-tree/explorer/init.lua

@@ -530,7 +530,7 @@ function Explorer:place_cursor_on_node()
 end
 
 ---Api.tree.get_nodes
----@return Node
+---@return nvim_tree.api.Node
 function Explorer:get_nodes()
   return self:clone()
 end

lua/nvim-tree/meta.lua

@@ -0,0 +1,59 @@
+---@meta
+
+--
+-- Nodes
+--
+
+---@class (exact) nvim_tree.api.Node: Class
+---@field type "file" | "directory" | "link" uv.fs_stat.result.type
+---@field absolute_path string
+---@field executable boolean
+---@field fs_stat uv.fs_stat.result?
+---@field git_status GitNodeStatus?
+---@field hidden boolean
+---@field name string
+---@field parent nvim_tree.api.DirectoryNode?
+---@field diag_severity lsp.DiagnosticSeverity?
+
+---@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node
+---@field extension string
+
+---@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node
+---@field has_children boolean
+---@field nodes nvim_tree.api.Node[]
+---@field open boolean
+
+---@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
+
+---@class (exact) nvim_tree.api.LinkNode: Class
+---@field link_to string
+---@field fs_stat_target uv.fs_stat.result
+
+---@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
+
+---@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
+
+--
+-- Decorators
+--
+
+---Highlight group range as per nvim-tree.renderer.highlight_*
+---@alias DecoratorHighlightRange "none" | "icon" | "name" | "all"
+
+---Icon position as per renderer.icons.*_placement
+---@alias DecoratorIconPlacement "none" | "before" | "after" | "signcolumn" | "right_align"
+
+---Decorator Constructor Arguments
+---@class (exact) DecoratorArgs
+---@field enabled boolean
+---@field highlight_range DecoratorHighlightRange
+---@field icon_placement DecoratorIconPlacement
+
+--
+-- Types
+--
+
+---A string for rendering, with optional highlight groups to apply to it
+---@class (exact) HighlightedString
+---@field str string
+---@field hl string[]

lua/nvim-tree/node/directory-link.lua

@@ -73,9 +73,9 @@ function DirectoryLinkNode:highlighted_name()
 end
 
 ---Create a sanitized partial copy of a node, populating children recursively.
----@return DirectoryLinkNode cloned
+---@return nvim_tree.api.DirectoryLinkNode cloned
 function DirectoryLinkNode:clone()
-  local clone = DirectoryNode.clone(self) --[[@as DirectoryLinkNode]]
+  local clone = DirectoryNode.clone(self) --[[@as nvim_tree.api.DirectoryLinkNode]]
 
   clone.link_to = self.link_to
   clone.fs_stat_target = self.fs_stat_target

lua/nvim-tree/node/directory.lua

@@ -271,18 +271,19 @@ function DirectoryNode:highlighted_name()
 end
 
 ---Create a sanitized partial copy of a node, populating children recursively.
----@return DirectoryNode cloned
+---@return nvim_tree.api.DirectoryNode cloned
 function DirectoryNode:clone()
-  local clone        = Node.clone(self) --[[@as DirectoryNode]]
+  local clone        = Node.clone(self) --[[@as nvim_tree.api.DirectoryNode]]
 
   clone.has_children = self.has_children
-  clone.group_next   = nil
   clone.nodes        = {}
   clone.open         = self.open
-  clone.hidden_stats = nil
 
+  local clone_child
   for _, child in ipairs(self.nodes) do
-    table.insert(clone.nodes, child:clone())
+    clone_child = child:clone()
+    clone_child.parent = clone
+    table.insert(clone.nodes, clone_child)
   end
 
   return clone

lua/nvim-tree/node/file-link.lua

@@ -58,9 +58,9 @@ function FileLinkNode:highlighted_name()
 end
 
 ---Create a sanitized partial copy of a node
----@return FileLinkNode cloned
+---@return nvim_tree.api.FileLinkNode cloned
 function FileLinkNode:clone()
-  local clone = FileNode.clone(self) --[[@as FileLinkNode]]
+  local clone = FileNode.clone(self) --[[@as nvim_tree.api.FileLinkNode]]
 
   clone.link_to = self.link_to
   clone.fs_stat_target = self.fs_stat_target

lua/nvim-tree/node/file.lua

@@ -94,9 +94,9 @@ function FileNode:highlighted_name()
 end
 
 ---Create a sanitized partial copy of a node
----@return FileNode cloned
+---@return nvim_tree.api.FileNode cloned
 function FileNode:clone()
-  local clone = Node.clone(self) --[[@as FileNode]]
+  local clone = Node.clone(self) --[[@as nvim_tree.api.FileNode]]
 
   clone.extension = self.extension
 

lua/nvim-tree/node/init.lua

@@ -2,6 +2,7 @@ local Class = require("nvim-tree.classic")
 
 ---Abstract Node class.
 ---@class (exact) Node: Class
+---@field uid_node number vim.loop.hrtime() at construction time
 ---@field type "file" | "directory" | "link" uv.fs_stat.result.type
 ---@field explorer Explorer
 ---@field absolute_path string
@@ -11,6 +12,7 @@ local Class = require("nvim-tree.classic")
 ---@field hidden boolean
 ---@field name string
 ---@field parent DirectoryNode?
+---TODO split this into diag_severity and diag_severity_cache_version
 ---@field diag_status DiagStatus?
 ---@field private is_dot boolean cached is_dotfile
 local Node = Class:extend()
@@ -25,6 +27,7 @@ local Node = Class:extend()
 ---@protected
 ---@param args NodeArgs
 function Node:new(args)
+  self.uid_node      = vim.loop.hrtime()
   self.explorer      = args.explorer
   self.absolute_path = args.absolute_path
   self.executable    = false
@@ -112,30 +115,26 @@ end
 
 ---Highlighted name for the node
 ---Empty for base Node
----@return HighlightedString icon
+---@return HighlightedString name
 function Node:highlighted_name()
   return self:highlighted_name_empty()
 end
 
 ---Create a sanitized partial copy of a node, populating children recursively.
----@return Node cloned
+---@return nvim_tree.api.Node cloned
 function Node:clone()
-  ---@type Explorer
-  local explorer_placeholder = nil
-
-  ---@type Node
+  ---@type nvim_tree.api.Node
   local clone = {
+    uid_node      = self.uid_node,
     type          = self.type,
-    explorer      = explorer_placeholder,
     absolute_path = self.absolute_path,
     executable    = self.executable,
     fs_stat       = self.fs_stat,
     git_status    = self.git_status,
     hidden        = self.hidden,
     name          = self.name,
     parent        = nil,
-    diag_status   = nil,
-    is_dot        = self.is_dot,
+    diag_severity = self.diag_status and self.diag_status.value or nil,
   }
 
   return clone

lua/nvim-tree/node/link.lua

@@ -2,7 +2,7 @@ local Class = require("nvim-tree.classic")
 
 ---@class (exact) LinkNode: Class
 ---@field link_to string
----@field protected fs_stat_target uv.fs_stat.result
+---@field fs_stat_target uv.fs_stat.result
 local LinkNode = Class:extend()
 
 ---@class (exact) LinkNodeArgs: NodeArgs

lua/nvim-tree/node/root.lua

@@ -22,4 +22,12 @@ function RootNode:destroy()
   DirectoryNode.destroy(self)
 end
 
+---Create a sanitized partial copy of a node, populating children recursively.
+---@return nvim_tree.api.RootNode cloned
+function RootNode:clone()
+  local clone = DirectoryNode.clone(self) --[[@as nvim_tree.api.RootNode]]
+
+  return clone
+end
+
 return RootNode