feat(#2948): extract _meta following nvim pattern

Author: alex-courtis

Makefile

@@ -13,7 +13,7 @@ check: luals
 # subtasks
 #
 luacheck:
-	luacheck -q lua
+	luacheck --codes --quiet lua --exclude-files "**/_meta/**"
 
 # --diagnosis-as-error does not function for workspace, hence we post-process the output
 style-check:

lua/nvim-tree/_meta/aliases.lua

@@ -0,0 +1,19 @@
+---@meta
+error("Cannot require a meta file")
+
+--
+--Internal convenience aliases for api types
+--
+
+--
+--api.lua
+--
+
+---@alias HighlightedString nvim_tree.api.HighlightedString
+
+--
+--api_decorator.lua
+--
+
+---@alias DecoratorHighlightRange nvim_tree.api.decorator.HighlightRange
+---@alias DecoratorIconPlacement nvim_tree.api.decorator.IconPlacement

lua/nvim-tree/_meta/api.lua

@@ -1,15 +1,12 @@
 ---@meta
-error('Cannot require a meta file')
-
--- TODO describe class
--- TODO describe user decorator
+error("Cannot require a meta file")
 
 --
 -- Nodes
 --
 
 ---Base Node, Abstract
----@class (exact) nvim_tree.api.Node: Class
+---@class (exact) nvim_tree.api.Node
 ---@field type "file" | "directory" | "link" uv.fs_stat.result.type
 ---@field absolute_path string
 ---@field executable boolean
@@ -34,7 +31,7 @@ error('Cannot require a meta file')
 ---@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
 
 ---Link mixin
----@class (exact) nvim_tree.api.LinkNode: Class
+---@class (exact) nvim_tree.api.LinkNode
 ---@field link_to string
 ---@field fs_stat_target uv.fs_stat.result
 
@@ -52,9 +49,3 @@ error('Cannot require a meta file')
 ---@class (exact) nvim_tree.api.HighlightedString
 ---@field str string
 ---@field hl string[]
-
---
--- Internal Aliases
---
----@alias HighlightedString nvim_tree.api.HighlightedString
-

lua/nvim-tree/_meta/api_decorator.lua

@@ -1,41 +1,88 @@
 ---@meta
 error('Cannot require a meta file')
 
+local nvim_tree = { api = { decorator = { BaseDecorator = {} } } }
+
 ---Highlight group range as per nvim-tree.renderer.highlight_*
 ---@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all"
 
 ---Icon position as per renderer.icons.*_placement
 ---@alias nvim_tree.api.decorator.IconPlacement "none" | "before" | "after" | "signcolumn" | "right_align"
 
----UserDecorator Constructor Arguments
----@class (exact) nvim_tree.api.decorator.UserDecoratorArgs
+--
+-- BaseDecorator Class, see example implementation below
+--
+
+---User defined decorator to optionally add:
+---  Additional icons
+---  Name highlight group
+---  Node icon override
+---Class must be created via nvim_tree.api.decorator.BaseDecorator:extend()
+---Mandatory constructor  :new()  will be called once per tree render, with no arguments.
+---Constructor must call:
+---  .super.new(self, args)  passing nvim_tree.api.decorator.BaseDecoratorArgs
+---  :define_sign(...)  when using "signcolumn" range
+---@class (exact) nvim_tree.api.decorator.BaseDecorator
+---@field protected enabled boolean
+---@field protected highlight_range nvim_tree.api.decorator.HighlightRange
+---@field protected icon_placement nvim_tree.api.decorator.IconPlacement
+
+---Constructor Arguments
+---@class (exact) nvim_tree.api.decorator.BaseDecoratorArgs
 ---@field enabled boolean
 ---@field highlight_range nvim_tree.api.decorator.HighlightRange
 ---@field icon_placement nvim_tree.api.decorator.IconPlacement
 
+---Use to instantiate your decorator class
+function nvim_tree.api.decorator.BaseDecorator:extend() end
+
+---Super constructor must be called from your constructor
+---BaseDecorator.super.new(self, args)
+---@protected
+---@param self nvim_tree.api.decorator.BaseDecorator your instance
+---@param args nvim_tree.api.decorator.BaseDecoratorArgs
+function nvim_tree.api.decorator.BaseDecorator.new(self, args) end
+
+---Must implement a constructor and call super
+function nvim_tree.api.decorator.BaseDecorator:new() end
+
+---Implement this method to set the node's icon
+---@param node nvim_tree.api.Node
+---@return HighlightedString? icon_node
+function nvim_tree.api.decorator.BaseDecorator:icon_node(node) end
+
+---Implement this method to provide icons and the highlight groups to apply to IconPlacement
+---@param node nvim_tree.api.Node
+---@return HighlightedString[]? icons
+function nvim_tree.api.decorator.BaseDecorator:icons(node) end
+
+---Implement this method to provide one highlight group to apply to HighlightRange
+---@param node nvim_tree.api.Node
+---@return string? highlight_group
+function nvim_tree.api.decorator.BaseDecorator:highlight_group(node) end
+
 
 --
--- Example UserDecorator
+-- Example Decorator
 --
 
-local UserDecorator = require("nvim-tree.renderer.decorator.user")
+local BaseDecorator = require("nvim-tree.api").decorator.BaseDecorator
 
----@class (exact) MyDecorator: UserDecorator
+---@class (exact) MyDecorator: nvim_tree.api.decorator.BaseDecorator
 ---@field private my_icon nvim_tree.api.HighlightedString
-local MyDecorator = UserDecorator:extend()
+local MyDecorator = BaseDecorator:extend()
 
----Constructor
+---Mandatory constructor  :new()  will be called once per tree render, with no arguments.
 function MyDecorator:new()
-
-  ---@type nvim_tree.api.decorator.UserDecoratorArgs
+  ----@type nvim_tree.api.decorator.BaseDecoratorArgs
   local args = {
     enabled         = true,
     highlight_range = "all",
     icon_placement  = "signcolumn",
   }
 
   -- construct super with args
-  MyDecorator.super.new(self, args)
+  BaseDecorator.new(self, args)
 
   -- create your icon once, for convenience
   self.my_icon = { str = "I", hl = { "MyIcon" } }
@@ -45,7 +92,7 @@ function MyDecorator:new()
   self:define_sign(self.my_icon)
 end
 
----Overridde node icon
+---Override node icon
 ---@param node nvim_tree.api.Node
 ---@return nvim_tree.api.HighlightedString? icon_node
 function MyDecorator:icon_node(node)
@@ -79,10 +126,3 @@ function MyDecorator:highlight_group(node)
 end
 
 return MyDecorator
-
---
--- Internal Aliases
---
----@alias DecoratorHighlightRange nvim_tree.api.decorator.HighlightRange
----@alias DecoratorIconPlacement nvim_tree.api.decorator.IconPlacement
-

lua/nvim-tree/api.lua

@@ -39,6 +39,7 @@ local Api = {
   },
   commands = {},
   diagnostics = {},
+  decorator = {},
 }
 
 ---Print error when setup not called.
@@ -311,4 +312,6 @@ Api.commands.get = wrap(function()
   return require("nvim-tree.commands").get()
 end)
 
+Api.decorator.BaseDecorator = require("nvim-tree.renderer.decorator.user") --[[@as nvim_tree.api.decorator.BaseDecorator ]]
+
 return Api

lua/nvim-tree/renderer/builder.lua

@@ -205,7 +205,6 @@ end
 ---@return HighlightedString icon
 ---@return HighlightedString name
 function Builder:icon_name_decorated(node)
-
   -- base case
   local icon = node:highlighted_icon()
   local name = node:highlighted_name()

lua/nvim-tree/renderer/decorator/user.lua

@@ -1,32 +1,20 @@
 local Decorator = require("nvim-tree.renderer.decorator")
 
----Define a Decorator to optionally set:
----  Additional icons
----  Highlight group
----  Node icon
----Mandator constructor  MyDecorator:new()  will be called once per tree render, with no arguments.
----Must call:
----  super passing DecoratorArgs  MyDecorator.super.new(self, args)
----  define_sign when using "signcolumn"
-
 ---@class (exact) UserDecorator: Decorator
 local UserDecorator = Decorator:extend()
 
----Override this method to set the node's icon
 ---@param node nvim_tree.api.Node
 ---@return HighlightedString? icon_node
 function UserDecorator:icon_node(node)
   return self:nop(node)
 end
 
----Override this method to provide icons and the highlight groups to apply to DecoratorIconPlacement
 ---@param node nvim_tree.api.Node
 ---@return HighlightedString[]? icons
 function UserDecorator:icons(node)
   self:nop(node)
 end
 
----Override this method to provide one highlight group to apply to DecoratorRange
 ---@param node nvim_tree.api.Node
 ---@return string? highlight_group
 function UserDecorator:highlight_group(node)