From d26d4a4350e0725d1ae4e9ec22947b200e5ffc42 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Tue, 11 Feb 2025 02:26:51 -0800
Subject: [PATCH 01/36] feat(config): add types

---
 .github/workflows/typecheck.yml               |  20 ++
 lua/neo-tree/defaults.lua                     |   1 +
 .../document_symbols/lib/client_filters.lua   |  21 +-
 lua/neo-tree/types/config.lua                 | 193 ++++++++++++++++++
 lua/neo-tree/types/config/components.lua      | 103 ++++++++++
 lua/neo-tree/ui/popups.lua                    |   2 +
 6 files changed, 332 insertions(+), 8 deletions(-)
 create mode 100644 .github/workflows/typecheck.yml
 create mode 100644 lua/neo-tree/types/config.lua
 create mode 100644 lua/neo-tree/types/config/components.lua

diff --git a/.github/workflows/typecheck.yml b/.github/workflows/typecheck.yml
new file mode 100644
index 000000000..511ed1abd
--- /dev/null
+++ b/.github/workflows/typecheck.yml
@@ -0,0 +1,20 @@
+name: Lua Type Check
+on:
+  pull_request: ~
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Lua Type Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Type Check Code Base
+        uses: mrcjkb/lua-typecheck-action@v0.1.2
+        with:
+          configpath: ".luarc.json"
diff --git a/lua/neo-tree/defaults.lua b/lua/neo-tree/defaults.lua
index 304e496ac..b055ef9a6 100644
--- a/lua/neo-tree/defaults.lua
+++ b/lua/neo-tree/defaults.lua
@@ -1,3 +1,4 @@
+---@type neotree.Config
 local config = {
   -- If a user has a sources list it will replace this one.
   -- Only sources listed here will be loaded.
diff --git a/lua/neo-tree/sources/document_symbols/lib/client_filters.lua b/lua/neo-tree/sources/document_symbols/lib/client_filters.lua
index c46c09a4d..cb1e15807 100644
--- a/lua/neo-tree/sources/document_symbols/lib/client_filters.lua
+++ b/lua/neo-tree/sources/document_symbols/lib/client_filters.lua
@@ -1,15 +1,15 @@
 ---Utilities function to filter the LSP servers
 local utils = require("neo-tree.utils")
 
----@alias neotree.LspRespRaw table<integer,{err: lsp.ResponseError?, result: any}>
+---@alias neotree.lsp.RespRaw table<integer,{err: lsp.ResponseError?, result: any}>
 local M = {}
 
----@alias FilterFn fun(client_name: string): boolean
+---@alias neotree.lsp.Filter fun(client_name: string): boolean
 
 ---Filter clients
 ---@param filter_type "first" | "all"
----@param filter_fn FilterFn
----@param resp neotree.LspRespRaw
+---@param filter_fn neotree.lsp.Filter
+---@param resp neotree.lsp.RespRaw
 ---@return table<string, any>
 local filter_clients = function(filter_type, filter_fn, resp)
   if resp == nil or type(resp) ~= "table" then
@@ -34,7 +34,7 @@ end
 
 ---Filter only allowed clients
 ---@param allow_only string[] the list of clients to keep
----@return FilterFn
+---@return neotree.lsp.Filter
 local allow_only = function(allow_only)
   return function(client_name)
     return vim.tbl_contains(allow_only, client_name)
@@ -43,7 +43,7 @@ end
 
 ---Ignore clients
 ---@param ignore string[] the list of clients to remove
----@return FilterFn
+---@return neotree.lsp.Filter
 local ignore = function(ignore)
   return function(client_name)
     return not vim.tbl_contains(ignore, client_name)
@@ -51,15 +51,20 @@ local ignore = function(ignore)
 end
 
 ---Main entry point for the filter
----@param resp neotree.LspRespRaw
+---@param resp neotree.lsp.RespRaw
 ---@return table<string, any>
 M.filter_resp = function(resp)
   return {}
 end
 
+---@alias neotree.lsp.Filter.Type
+---|"first" # Allow the first that matches
+---|"all" # Allow all that match
+
+---@alias neotree.lsp.ClientFilter neotree.lsp.Filter.Type | { type: neotree.lsp.Filter.Type, fn: neotree.lsp.Filter, allow_only: string[], ignore: string[] }
 ---Setup the filter accordingly to the config
 ---@see neo-tree-document-symbols-source for more details on options that the filter accepts
----@param cfg_flt "first" | "all" | { type: "first" | "all", fn: FilterFn, allow_only: string[], ignore: string[] }
+---@param cfg_flt neotree.lsp.ClientFilter
 M.setup = function(cfg_flt)
   local filter_type = "first"
   local filter_fn = nil
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
new file mode 100644
index 000000000..67bf0cc8a
--- /dev/null
+++ b/lua/neo-tree/types/config.lua
@@ -0,0 +1,193 @@
+---@meta
+
+---@class neotree.Config.MappingOptions
+---@field noremap boolean
+---@field nowait boolean
+
+---@class neotree.Config.Mapping : neotree.Config.MappingOptions
+---@field [1] string
+---@field nowait boolean?
+---@field noremap boolean?
+---@field config table?
+
+---@alias neotree.Config.Window.Mappings table<string, string|neotree.Config.Mapping>
+
+---@class neotree.Config.Source
+---@field window neotree.Config.Source.Window
+---@field renderers neotree.Config.Renderers[]?
+
+---@class neotree.Config.Source.Window
+---@field mappings neotree.Config.Window.Mappings
+
+---@class neotree.Config.SourceSelector.Item
+---@field source string
+---@field padding? integer|{left:integer,right:integer}
+---@field separator? string|{left:string,right:string, override?:string}
+
+---@alias neotree.Config.SourceSelector.Separator.Override
+---|"right"   # When right and left separators meet, only show the right one.
+---|"left"    # When right and left separators meet, only show the left one.
+---|"active"  # Only use the left separator on the left of the active tab, and only the right afterwards.
+---|nil       # Show both separators.
+
+---@class neotree.Config.SourceSelector.Separator
+---@field left string
+---@field right string
+---@field override neotree.Config.SourceSelector.Separator.Override
+
+---@class neotree.Config.SourceSelector
+---@field winbar boolean
+---@field statusline boolean
+---@field show_scrolled_off_parent_node boolean
+---@field sources neotree.Config.SourceSelector.Item[]
+---@field content_layout string? "start"|"end"|"center"
+---@field tabs_layout string? "equal"|"start"|"end"|"center"|"focus"
+---@field truncation_character string
+---@field tabs_min_width integer?
+---@field tabs_max_width integer?
+---@field padding integer?
+---@field separator neotree.Config.SourceSelector.Separator?
+---@field separator_active neotree.Config.SourceSelector.Separator?
+---@field show_separator_on_edge boolean
+---@field highlight_tab string
+---@field highlight_tab_active string
+---@field highlight_background string
+---@field highlight_separator string
+---@field highlight_separator_active string
+
+---@class neotree.Config.GitStatusAsync
+---@field batch_size integer
+---@field batch_delay integer
+---@field max_lines integer
+
+---@class neotree.Config.Window.Size
+---@field height string|number?
+---@field width string|number?
+
+---@class neotree.Config.Window.Popup
+---@field title fun(state:table):string
+---@field size neotree.Config.Window.Size
+---@field border neotree.Config.BorderStyle
+
+---@class neotree.Config.Window
+---@field position string
+---@field width integer
+---@field height integer
+---@field auto_expand_width boolean
+---@field popup neotree.Config.Window.Popup
+---@field same_level boolean
+---@field insert_as "child"|"sibling"
+---@field mapping_options neotree.Config.MappingOptions
+---@field mappings table
+
+---@alias neotree.Config.Cwd "tab"|"window"|"global"
+
+---@class neotree.Config.Filesystem.CwdTarget
+---@field sidebar neotree.Config.Cwd
+---@field current neotree.Config.Cwd
+
+---@class neotree.Config.Filesystem.FilteredItems
+---@field visible boolean
+---@field force_visible_in_empty_folder boolean
+---@field show_hidden_count boolean
+---@field hide_dotfiles boolean
+---@field hide_gitignored boolean
+---@field hide_hidden boolean
+---@field hide_by_name string[]
+---@field hide_by_pattern string[]
+---@field always_show string[]
+---@field always_show_by_pattern string[]
+---@field never_show string[]
+---@field never_show_by_pattern string[]
+
+---@alias neotree.Config.Filesystem.FindArgsHandler fun(cmd:string, path:string, search_term:string, args:string[]):string[]
+
+---@class neotree.Config.Filesystem.FollowCurrentFile
+---@field enabled boolean
+---@field leave_dirs_open boolean
+
+---@alias neotree.Config.HijackNetrwBehavior
+---|"open_default" # opening a directory opens neo-tree with the default window.position.
+---|"open_current" # opening a directory opens neo-tree within the current window.
+---|"disabled" # opening a directory opens neo-tree within the current window.
+
+---@class neotree.Config.Filesystem : neotree.Config.Source
+---@field async_directory_scan "auto"|"always"|"never"
+---@field bind_to_cwd boolean
+---@field cwd_target neotree.Config.Filesystem.CwdTarget
+---@field check_gitignore_in_search boolean
+---@field filtered_items neotree.Config.Filesystem.FilteredItems
+---@field find_by_full_path_words boolean
+---@field find_command string?
+---@field find_args table<string, string[]>|neotree.Config.Filesystem.FindArgsHandler|nil
+---@field group_empty_dirs boolean
+---@field search_limit integer
+---@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
+---@field hijack_netrw_behavior neotree.Config.HijackNetrwBehavior
+---@field use_libuv_file_watcher boolean
+
+---@class neotree.Config.Buffers : neotree.Config.Source
+---@field bind_to_cwd boolean
+---@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
+---@field group_empty_dirs boolean
+---@field show_unloaded boolean
+---@field terminals_first boolean
+
+---@class neotree.Config.GitStatus : neotree.Config.Source
+
+---@class neotree.Config.LspKindDisplay
+---@field icon string
+---@field hl string
+
+---@class neotree.Config.DocumentSymbols : neotree.Config.Source
+---@field follow_cursor boolean
+---@field client_filters neotree.lsp.ClientFilter
+---@field custom_kinds table<integer, string>
+---@field kinds table<string, neotree.Config.LspKindDisplay>
+
+---@class neotree.Config.EventHandler.HandlerResult
+---@field handled boolean
+
+---@class neotree.Config.EventHandler
+---@field event string
+---@field handler fun(table?):neotree.Config.EventHandler.HandlerResult?
+
+---@alias neotree.Config.BorderStyle "NC"|"none"|"rounded"|"shadow"|"single"|"solid"|nil
+
+---@class neotree.Config
+---@field sources string[]?
+---@field add_blank_line_at_top boolean?
+---@field auto_clean_after_session_restore boolean?
+---@field close_if_last_window boolean?
+---@field default_source string?
+---@field enable_diagnostics boolean?
+---@field enable_git_status boolean?
+---@field enable_modified_markers boolean?
+---@field enable_opened_markers boolean?
+---@field enable_refresh_on_write boolean?
+---@field enable_cursor_hijack boolean?
+---@field git_status_async boolean?
+---@field git_status_async_options neotree.Config.GitStatusAsync?
+---@field hide_root_node boolean?
+---@field retain_hidden_root_indent boolean?
+---@field log_level "trace"|"debug"|"info"|"warn"|"error"|"fatal"|nil
+---@field log_to_file boolean?
+---@field open_files_in_last_window boolean?
+---@field open_files_do_not_replace_types string[]?
+---@field open_files_using_relative_paths boolean?
+---@field popup_border_style neotree.Config.BorderStyle
+---@field resize_timer_interval integer?
+---@field sort_case_insensitive boolean?
+---@field sort_function fun(a: any, b: any)?
+---@field use_popups_for_input boolean?
+---@field use_default_mappings boolean?
+---@field source_selector neotree.Config.SourceSelector?
+---@field event_handlers table[]?
+---@field default_component_configs neotree.Config.Components?
+---@field renderers neotree.Config.Renderers[]?
+---@field nesting_rules table[]? -- TODO, merge rework
+---@field commands table<string, fun()>?
+---@field window neotree.Config.Window?
+---@field filesystem neotree.Config.Filesystem?
+---@field buffers neotree.Config.Buffers?
+---@field git_status neotree.Config.GitStatus?
diff --git a/lua/neo-tree/types/config/components.lua b/lua/neo-tree/types/config/components.lua
new file mode 100644
index 000000000..9a6781ffa
--- /dev/null
+++ b/lua/neo-tree/types/config/components.lua
@@ -0,0 +1,103 @@
+---@class neotree.Config.Component.Container
+---@field enable_character_fade boolean
+---@field width string
+---@field right_padding integer
+
+---@class neotree.Config.Component.Indent
+---@field indent_size integer
+---@field padding integer
+---@field with_markers boolean
+---@field indent_marker string
+---@field last_indent_marker string
+---@field highlight string
+---@field with_expanders boolean?
+---@field expander_collapsed string
+---@field expander_expanded string
+---@field expander_highlight string
+
+---@class neotree.Config.Component.Icon
+---@field folder_closed string
+---@field folder_open string
+---@field folder_empty string
+---@field folder_empty_open string
+---@field default string
+---@field highlight string
+---@field provider fun(icon:table, node:table, state:table)
+
+---@class neotree.Config.Component.Modified
+---@field symbol string
+---@field highlight string
+
+---@class neotree.Config.Component.Name
+---@field trailing_slash boolean
+---@field highlight_opened_files boolean|"all"
+---@field use_git_status_colors boolean
+---@field highlight string
+
+---@class neotree.Config.Component.GitStatus.Symbols
+---@field added string
+---@field deleted string
+---@field modified string
+---@field renamed string
+---@field untracked string
+---@field ignored string
+---@field unstaged string
+---@field staged string
+---@field conflict string
+
+---@class neotree.Config.Component.GitStatus
+---@field symbols neotree.Config.Component.GitStatus.Symbols
+---@field align string
+
+---@class neotree.Config.Component.FileSize
+---@field enabled boolean
+---@field width integer
+---@field required_width integer
+
+---@class neotree.Config.Component.Type
+---@field enabled boolean
+---@field width integer
+---@field required_width integer
+
+---@class neotree.Config.Component.LastModified
+---@field enabled boolean
+---@field width integer
+---@field required_width integer
+---@field format string|fun(seconds:number):string
+
+---@class neotree.Config.Component.Created
+---@field enabled boolean
+---@field width integer
+---@field required_width integer
+---@field format string|fun(seconds:number):string
+
+---@class neotree.Config.Component.SymlinkTarget
+---@field enabled boolean
+---@field text_format string
+
+---@class neotree.Config.Components
+---@field container neotree.Config.Component.Container
+---@field indent neotree.Config.Component.Indent
+---@field icon neotree.Config.Component.Icon
+---@field modified neotree.Config.Component.Modified
+---@field name neotree.Config.Component.Name
+---@field git_status neotree.Config.Component.GitStatus
+---@field file_size neotree.Config.Component.FileSize
+---@field type neotree.Config.Component.Type
+---@field last_modified neotree.Config.Component.LastModified
+---@field created neotree.Config.Component.Created
+---@field symlink_target neotree.Config.Component.SymlinkTarget
+
+---@class neotree.Renderer.Container
+---@field content table
+---@field zindex integer?
+---@field align string?
+---@field hide_when_expanded boolean?
+
+---@alias neotree.Renderer.Components table
+
+---@class neotree.Config.Renderers
+---@field directory neotree.Renderer.Components[]
+---@field file neotree.Renderer.Components[]
+---@field message neotree.Renderer.Components[]
+---@field terminal neotree.Renderer.Components[]
diff --git a/lua/neo-tree/ui/popups.lua b/lua/neo-tree/ui/popups.lua
index 2c15d00fd..4a75c4681 100644
--- a/lua/neo-tree/ui/popups.lua
+++ b/lua/neo-tree/ui/popups.lua
@@ -22,6 +22,7 @@ M.popup_options = function(title, min_width, override_options)
   if popup_last_col >= vim.o.columns then
     col = vim.o.columns - popup_last_col
   end
+  ---@type nui_popup_options
   local popup_options = {
     ns_id = highlights.ns_id,
     relative = "cursor",
@@ -34,6 +35,7 @@ M.popup_options = function(title, min_width, override_options)
       text = {
         top = popup_border_text,
       },
+      ---@diagnostic disable-next-line: assign-type-mismatch
       style = popup_border_style,
       highlight = highlights.FLOAT_BORDER,
     },

From 07be10e812cdc12d5bb5d45cc39eaa755edcf873 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Sat, 15 Feb 2025 12:28:16 -0800
Subject: [PATCH 02/36] Reorganize

---
 lua/neo-tree/sources/common/components.lua   |  11 ++
 lua/neo-tree/types/components/components.lua |  19 ++++
 lua/neo-tree/types/config.lua                |   4 +-
 lua/neo-tree/types/config/components.lua     | 103 -------------------
 4 files changed, 32 insertions(+), 105 deletions(-)
 create mode 100644 lua/neo-tree/types/components/components.lua
 delete mode 100644 lua/neo-tree/types/config/components.lua

diff --git a/lua/neo-tree/sources/common/components.lua b/lua/neo-tree/sources/common/components.lua
index a14e220db..94282ce64 100644
--- a/lua/neo-tree/sources/common/components.lua
+++ b/lua/neo-tree/sources/common/components.lua
@@ -25,8 +25,16 @@ local make_two_char = function(symbol)
     return symbol
   end
 end
+
+---@class neotree.Config.Component.Base.Highlight
+---@field highlight string?
+
+---@class neotree.Config.Component.Common.Bufnr : neotree.Config.Component.Base.Highlight
+
+-- Config fields below:
 -- only works in the buffers component, but it's here so we don't have to defined
 -- multple renderers.
+---@param config neotree.Config.Component.Common.Bufnr
 M.bufnr = function(config, node, state)
   local highlight = config.highlight or highlights.BUFFER_NUMBER
   local bufnr = node.extra and node.extra.bufnr
@@ -39,6 +47,9 @@ M.bufnr = function(config, node, state)
   }
 end
 
+---@class neotree.Config.Component.Common.Clipboard : neotree.Config.Component.Base.Highlight
+---@param config neotree.Config.Component.Common.Clipboard
+---@param config neotree.Node
 M.clipboard = function(config, node, state)
   local clipboard = state.clipboard or {}
   local clipboard_state = clipboard[node:get_id()]
diff --git a/lua/neo-tree/types/components/components.lua b/lua/neo-tree/types/components/components.lua
new file mode 100644
index 000000000..d94e7ef52
--- /dev/null
+++ b/lua/neo-tree/types/components/components.lua
@@ -0,0 +1,19 @@
+
+---@class neotree.Config.Renderers
+---@field directory neotree.Renderer.Component[]?
+---@field file neotree.Renderer.Component[]?
+---@field message neotree.Renderer.Component[]?
+---@field terminal neotree.Renderer.Component[]?
+
+---@class neotree.Config.ComponentDefaults
+---@field container neotree.Config.Component.Container
+---@field indent neotree.Config.Component.Indent
+---@field icon neotree.Config.Component.Icon
+---@field modified neotree.Config.Component.Modified
+---@field name neotree.Config.Component.Name
+---@field git_status neotree.Config.Component.GitStatus
+---@field file_size neotree.Config.Component.FileSize
+---@field type neotree.Config.Component.Type
+---@field last_modified neotree.Config.Component.LastModified
+---@field created neotree.Config.Component.Created
+---@field symlink_target neotree.Config.Component.SymlinkTarget
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
index 67bf0cc8a..f4ce4cfd7 100644
--- a/lua/neo-tree/types/config.lua
+++ b/lua/neo-tree/types/config.lua
@@ -183,8 +183,8 @@
 ---@field use_default_mappings boolean?
 ---@field source_selector neotree.Config.SourceSelector?
 ---@field event_handlers table[]?
----@field default_component_configs neotree.Config.Components?
----@field renderers neotree.Config.Renderers[]?
+---@field default_component_configs neotree.Config.ComponentDefaults?
+---@field renderers neotree.Config.Renderers?
 ---@field nesting_rules table[]? -- TODO, merge rework
 ---@field commands table<string, fun()>?
 ---@field window neotree.Config.Window?
diff --git a/lua/neo-tree/types/config/components.lua b/lua/neo-tree/types/config/components.lua
deleted file mode 100644
index 9a6781ffa..000000000
--- a/lua/neo-tree/types/config/components.lua
+++ /dev/null
@@ -1,103 +0,0 @@
----@class neotree.Config.Component.Container
----@field enable_character_fade boolean
----@field width string
----@field right_padding integer
-
----@class neotree.Config.Component.Indent
----@field indent_size integer
----@field padding integer
----@field with_markers boolean
----@field indent_marker string
----@field last_indent_marker string
----@field highlight string
----@field with_expanders boolean?
----@field expander_collapsed string
----@field expander_expanded string
----@field expander_highlight string
-
----@class neotree.Config.Component.Icon
----@field folder_closed string
----@field folder_open string
----@field folder_empty string
----@field folder_empty_open string
----@field default string
----@field highlight string
----@field provider fun(icon:table, node:table, state:table)
-
----@class neotree.Config.Component.Modified
----@field symbol string
----@field highlight string
-
----@class neotree.Config.Component.Name
----@field trailing_slash boolean
----@field highlight_opened_files boolean|"all"
----@field use_git_status_colors boolean
----@field highlight string
-
----@class neotree.Config.Component.GitStatus.Symbols
----@field added string
----@field deleted string
----@field modified string
----@field renamed string
----@field untracked string
----@field ignored string
----@field unstaged string
----@field staged string
----@field conflict string
-
----@class neotree.Config.Component.GitStatus
----@field symbols neotree.Config.Component.GitStatus.Symbols
----@field align string
-
----@class neotree.Config.Component.FileSize
----@field enabled boolean
----@field width integer
----@field required_width integer
-
----@class neotree.Config.Component.Type
----@field enabled boolean
----@field width integer
----@field required_width integer
-
----@class neotree.Config.Component.LastModified
----@field enabled boolean
----@field width integer
----@field required_width integer
----@field format string|fun(seconds:number):string
-
----@class neotree.Config.Component.Created
----@field enabled boolean
----@field width integer
----@field required_width integer
----@field format string|fun(seconds:number):string
-
----@class neotree.Config.Component.SymlinkTarget
----@field enabled boolean
----@field text_format string
-
----@class neotree.Config.Components
----@field container neotree.Config.Component.Container
----@field indent neotree.Config.Component.Indent
----@field icon neotree.Config.Component.Icon
----@field modified neotree.Config.Component.Modified
----@field name neotree.Config.Component.Name
----@field git_status neotree.Config.Component.GitStatus
----@field file_size neotree.Config.Component.FileSize
----@field type neotree.Config.Component.Type
----@field last_modified neotree.Config.Component.LastModified
----@field created neotree.Config.Component.Created
----@field symlink_target neotree.Config.Component.SymlinkTarget
-
----@class neotree.Renderer.Container
----@field content table
----@field zindex integer?
----@field align string?
----@field hide_when_expanded boolean?
-
----@alias neotree.Renderer.Components table
-
----@class neotree.Config.Renderers
----@field directory neotree.Renderer.Components[]
----@field file neotree.Renderer.Components[]
----@field message neotree.Renderer.Components[]
----@field terminal neotree.Renderer.Components[]

From 496772e701105a156d65f2823b582bd6ae8999db Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Sat, 15 Feb 2025 14:34:42 -0800
Subject: [PATCH 03/36] type common containers

---
 lua/neo-tree/sources/common/components.lua | 160 +++++++++++++++++++--
 lua/neo-tree/sources/common/container.lua  |  10 ++
 2 files changed, 162 insertions(+), 8 deletions(-)

diff --git a/lua/neo-tree/sources/common/components.lua b/lua/neo-tree/sources/common/components.lua
index 94282ce64..b300a80f3 100644
--- a/lua/neo-tree/sources/common/components.lua
+++ b/lua/neo-tree/sources/common/components.lua
@@ -16,6 +16,34 @@ local file_nesting = require("neo-tree.sources.common.file-nesting")
 local container = require("neo-tree.sources.common.container")
 local log = require("neo-tree.log")
 
+---@alias neotree.Component.Common._Key
+---|"bufnr"
+---|"clipboard"
+---|"container"
+---|"current_filter"
+---|"diagnostics"
+---|"git_status"
+---|"filtered_by"
+---|"icon"
+---|"modified"
+---|"name"
+---|"indent"
+---|"file_size"
+---|"last_modified"
+---|"created"
+---|"symlink_target"
+---|"type"
+
+---@class neotree.Component.Common Use the neotree.Component.Common.* types to get more specific types.
+---@field [1] neotree.Component.Common._Key
+
+local a = {}
+
+---@class neotree.Render.Node
+---@field text string The text to display.
+---@field highlight string The highlight for the text.
+
+---@type table<neotree.Component.Common._Key,fun(config, node, state):(neotree.Render.Node|neotree.Render.Node[])>
 local M = {}
 
 local make_two_char = function(symbol)
@@ -26,16 +54,19 @@ local make_two_char = function(symbol)
   end
 end
 
----@class neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Base.Highlight
 ---@field highlight string?
 
----@class neotree.Config.Component.Common.Bufnr : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Bufnr : neotree.Config.Component.Base.Highlight
+
+---@class (exact) neotree.Component.Common.Bufnr : neotree.Config.Component.Common.Bufnr
+---@field [1] "bufnr"
 
 -- Config fields below:
 -- only works in the buffers component, but it's here so we don't have to defined
 -- multple renderers.
 ---@param config neotree.Config.Component.Common.Bufnr
-M.bufnr = function(config, node, state)
+M.bufnr = function(config, node, _)
   local highlight = config.highlight or highlights.BUFFER_NUMBER
   local bufnr = node.extra and node.extra.bufnr
   if not bufnr then
@@ -47,9 +78,12 @@ M.bufnr = function(config, node, state)
   }
 end
 
----@class neotree.Config.Component.Common.Clipboard : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Clipboard : neotree.Config.Component.Base.Highlight
+
+---@class (exact) neotree.Component.Common.Clipboard : neotree.Config.Component.Common.Clipboard
+---@field [1] "clipboard"
+
 ---@param config neotree.Config.Component.Common.Clipboard
----@param config neotree.Node
 M.clipboard = function(config, node, state)
   local clipboard = state.clipboard or {}
   local clipboard_state = clipboard[node:get_id()]
@@ -64,7 +98,13 @@ end
 
 M.container = container.render
 
-M.current_filter = function(config, node, state)
+---@class (exact) neotree.Config.Component.Common.CurrentFilter : neotree.Config.Component.Base.Highlight
+
+---@class (exact) neotree.Component.Common.CurrentFilter : neotree.Config.Component.Common.CurrentFilter
+---@field [1] "current_filter"
+
+---@param config neotree.Config.Component.Common.CurrentFilter
+M.current_filter = function(config, node, _)
   local filter = node.search_pattern or ""
   if filter == "" then
     return {}
@@ -124,6 +164,16 @@ local function get_defined_sign(severity)
   return defined
 end
 
+---@class (exact) neotree.Config.Component.Common.Diagnostics : neotree.Config.Component.Base.Highlight
+---@field errors_only boolean?
+---@field hide_when_expanded boolean?
+---@field symbols table<string, string>?
+---@field highlights table<string, string>?
+
+---@class (exact) neotree.Component.Common.Diagnostics : neotree.Config.Component.Common.Diagnostics
+---@field [1] "diagnostics"
+
+---@param config neotree.Config.Component.Common.Diagnostics
 M.diagnostics = function(config, node, state)
   local diag = state.diagnostics_lookup or {}
   local diag_state = utils.index_by_path(diag, node:get_id())
@@ -136,6 +186,7 @@ M.diagnostics = function(config, node, state)
   if config.errors_only and diag_state.severity_number > 1 then
     return {}
   end
+  ---@type string
   local severity = diag_state.severity_string
   local defined = get_defined_sign(severity)
 
@@ -163,6 +214,14 @@ M.diagnostics = function(config, node, state)
   end
 end
 
+---@class (exact) neotree.Config.Component.Common.GitStatus : neotree.Config.Component.Base.Highlight
+---@field hide_when_expanded boolean?
+---@field symbols table<string, string>?
+
+---@class (exact) neotree.Component.Common.GitStatus : neotree.Config.Component.Common.GitStatus
+---@field [1] "git_status"
+
+---@param config neotree.Config.Component.Common.GitStatus
 M.git_status = function(config, node, state)
   local git_status_lookup = state.git_status_lookup
   if config.hide_when_expanded and node.type == "directory" and node:is_expanded() then
@@ -183,6 +242,7 @@ M.git_status = function(config, node, state)
   local symbols = config.symbols or {}
   local change_symbol
   local change_highlt = highlights.FILE_NAME
+  ---@type string?
   local status_symbol = symbols.staged
   local status_highlt = highlights.GIT_STAGED
   if node.type == "directory" and git_status:len() == 1 then
@@ -266,7 +326,10 @@ M.git_status = function(config, node, state)
   end
 end
 
-M.filtered_by = function(config, node, state)
+---@class neotree.Component.Common.FilteredBy
+---@field [1] "filtered_by"
+
+M.filtered_by = function(_, node, _)
   local result = {}
   if type(node.filtered_by) == "table" then
     local fby = node.filtered_by
@@ -301,6 +364,18 @@ M.filtered_by = function(config, node, state)
   return result
 end
 
+---@class (exact) neotree.Config.Component.Common.Icon : neotree.Config.Component.Base.Highlight
+---@field default string The default icon for a node.
+---@field folder_empty string The string to display to represent an empty folder.
+---@field folder_empty_open string The icon to display to represent an empty but open folder.
+---@field folder_open string The icon to display for an open folder.
+---@field folder_closed string The icon to display for a closed folder.
+---@field provider fun(icon, node, state):(neotree.Render.Node|neotree.Render.Node[])
+
+---@class (exact) neotree.Component.Common.Icon : neotree.Config.Component.Common.Icon
+---@field [1] "icon"
+
+---@param config neotree.Config.Component.Common.Icon
 M.icon = function(config, node, state)
   -- calculate default icon
   local icon =
@@ -329,6 +404,13 @@ M.icon = function(config, node, state)
   return icon
 end
 
+---@class (exact) neotree.Config.Component.Common.Modified : neotree.Config.Component.Base.Highlight
+---@field symbol string?
+
+---@class (exact) neotree.Component.Common.Modified : neotree.Config.Component.Common.Modified
+---@field [1] "modified"
+
+---@param config neotree.Config.Component.Common.Modified
 M.modified = function(config, node, state)
   local opened_buffers = state.opened_buffers or {}
   local buf_info = utils.index_by_path(opened_buffers, node.path)
@@ -343,6 +425,16 @@ M.modified = function(config, node, state)
   end
 end
 
+---@class (exact) neotree.Config.Component.Common.Name : neotree.Config.Component.Base.Highlight
+---@field trailing_slash boolean?
+---@field use_git_status_colors boolean?
+---@field highlight_opened_files boolean?
+---@field right_padding integer?
+
+---@class (exact) neotree.Component.Common.Name : neotree.Config.Component.Common.Name
+---@field [1] "name"
+
+---@param config neotree.Config.Component.Common.Name
 M.name = function(config, node, state)
   local highlight = config.highlight or highlights.FILE_NAME
   local text = node.name
@@ -391,6 +483,21 @@ M.name = function(config, node, state)
   }
 end
 
+---@class (exact) neotree.Config.Component.Common.Indent : neotree.Config.Component.Base.Highlight
+---@field expander_collapsed string?
+---@field expander_expanded string?
+---@field expander_highlight boolean?
+---@field indent_marker string?
+---@field indent_size integer?
+---@field last_indent_marker string?
+---@field padding integer?
+---@field with_expanders boolean?
+---@field with_markers integer?
+
+---@class (exact) neotree.Component.Common.Indent : neotree.Config.Component.Common.Indent
+---@field [1] "indent"
+
+---@param config neotree.Config.Component.Common.Indent
 M.indent = function(config, node, state)
   if not state.skip_marker_at_level then
     state.skip_marker_at_level = {}
@@ -479,11 +586,20 @@ local get_header = function(state, label, size)
   if state.sort and state.sort.label == label then
     local icon = state.sort.direction == 1 and "▲" or "▼"
     size = size - 2
+    ---diagnostic here is wrong, printf has arbitrary args.
+    ---@diagnostic disable-next-line: redundant-parameter
     return vim.fn.printf("%" .. size .. "s %s  ", truncate_string(label, size), icon)
   end
   return vim.fn.printf("%" .. size .. "s  ", truncate_string(label, size))
 end
 
+---@class (exact) neotree.Config.Component.Common.FileSize : neotree.Config.Component.Base.Highlight
+---@field width integer?
+
+---@class (exact) neotree.Component.Common.FileSize : neotree.Config.Component.Common.FileSize
+---@field [1] "file_size"
+
+---@param config neotree.Config.Component.Common.FileSize
 M.file_size = function(config, node, state)
   -- Root node gets column labels
   if node:get_depth() == 1 then
@@ -511,6 +627,11 @@ M.file_size = function(config, node, state)
   }
 end
 
+---@class (exact) neotree.Config.Component.Common.Time : neotree.Config.Component.Base.Highlight
+---@field format neotree.DateFormat
+---@field width integer?
+
+---@param config neotree.Config.Component.Common.Time
 local file_time = function(config, node, state, stat_field)
   -- Root node gets column labels
   if node:get_depth() == 1 then
@@ -537,15 +658,30 @@ local file_time = function(config, node, state, stat_field)
   }
 end
 
+---@class (exact) neotree.Component.Common.LastModified : neotree.Config.Component.Common.Time
+---@field [1] "last_modified"
+
+---@param config neotree.Config.Component.Common.Time
 M.last_modified = function(config, node, state)
   return file_time(config, node, state, "mtime")
 end
 
+---@class (exact) neotree.Component.Common.Created : neotree.Config.Component.Common.Time
+---@field [1] "created"
+
+---@param config neotree.Config.Component.Common.Time
 M.created = function(config, node, state)
   return file_time(config, node, state, "birthtime")
 end
 
-M.symlink_target = function(config, node, state)
+---@class (exact) neotree.Config.Component.Common.SymlinkTarget : neotree.Config.Component.Base.Highlight
+---@field text_format string
+
+---@class (exact) neotree.Component.Common.SymlinkTarget : neotree.Config.Component.Common.SymlinkTarget
+---@field [1] "symlink_target"
+
+---@param config neotree.Config.Component.Common.SymlinkTarget
+M.symlink_target = function(config, node, _)
   if node.is_link then
     return {
       text = string.format(config.text_format, node.link_to),
@@ -556,6 +692,14 @@ M.symlink_target = function(config, node, state)
   end
 end
 
+---@class (exact) neotree.Config.Component.Common.Type : neotree.Config.Component.Base.Highlight
+---@field format neotree.DateFormat
+---@field width integer?
+
+---@class (exact) neotree.Component.Common.Type : neotree.Config.Component.Common.Type
+---@field [1] "type"
+
+---@param config neotree.Config.Component.Common.Type
 M.type = function(config, node, state)
   local text = node.ext or node.type
   -- Root node gets column labels
diff --git a/lua/neo-tree/sources/common/container.lua b/lua/neo-tree/sources/common/container.lua
index ac836702a..cf2131fe9 100644
--- a/lua/neo-tree/sources/common/container.lua
+++ b/lua/neo-tree/sources/common/container.lua
@@ -307,6 +307,16 @@ local merge_content = function(context)
   context.wanted_width = math.max(wanted_width, context.wanted_width)
 end
 
+---@class (exact) neotree.Config.Component.Common.Container
+---@field left_padding integer?
+---@field right_padding integer?
+---@field enable_character_fade boolean?
+---@field context neotree.Component[]
+
+---@class (exact) neotree.Component.Common.Container : neotree.Config.Component.Common.Container
+---@field [1] "clipboard"
+
+---@param config neotree.Config.Component.Common.Container
 M.render = function(config, node, state, available_width)
   local context = {
     wanted_width = 0,

From e2e5ddba263a1cea6d1c78a7c48e3c536580a684 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Sat, 15 Feb 2025 14:47:41 -0800
Subject: [PATCH 04/36] add workflows

---
 .github/workflows/.luarc.json   | 18 +++++++++++++++++
 .github/workflows/typecheck.yml | 36 ++++++++++++++++++++++++++++-----
 2 files changed, 49 insertions(+), 5 deletions(-)
 create mode 100644 .github/workflows/.luarc.json

diff --git a/.github/workflows/.luarc.json b/.github/workflows/.luarc.json
new file mode 100644
index 000000000..c330cb0ea
--- /dev/null
+++ b/.github/workflows/.luarc.json
@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
+  "runtime.version": "LuaJIT",
+  "runtime.path": [
+    "lua/?.lua",
+    "lua/?/init.lua"
+  ],
+  "workspace.library": [
+    "/github/workspace/lua/neo-tree/types",
+    "/github/workspace/deps/neodev.nvim/types/stable",
+    "/github/workspace/deps/plenary.nvim/lua",
+    "/github/workspace/deps/nui.nvim/lua",
+    "/github/workspace/deps/nvim-web-devicons/lua",
+    "${3rd}/busted/library"
+  ],
+  "diagnostics.libraryFiles": "Disable",
+  "workspace.checkThirdParty": "Disable"
+}
diff --git a/.github/workflows/typecheck.yml b/.github/workflows/typecheck.yml
index 511ed1abd..e2d2a78fc 100644
--- a/.github/workflows/typecheck.yml
+++ b/.github/workflows/typecheck.yml
@@ -3,18 +3,44 @@ on:
   pull_request: ~
   push:
     branches:
-      - main
+      - '*'
 
 jobs:
   build:
-    name: Lua Type Check
+    name: Type Check Code Base
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+
+      - name: Checkout dependency neodev
+        uses: actions/checkout@v4
+        with:
+          repository: "folke/neodev.nvim"
+          path: "deps/neodev.nvim"
+
+      - name: Checkout dependency plenary
+        uses: actions/checkout@v4
+        with:
+          repository: "nvim-lua/plenary.nvim"
+          path: "deps/plenary.nvim"
+
+      - name: Checkout dependency nvim-web-devicons
+        uses: actions/checkout@v4
+        with:
+          repository: "nvim-tree/nvim-web-devicons"
+          path: "deps/nvim-web-devicons"
+
+      - name: Checkout dependency nui
+        uses: actions/checkout@v4
+        with:
+          repository: "MunifTanjim/nui.nvim"
+          path: "deps/nui.nvim"
 
       - name: Type Check Code Base
-        uses: mrcjkb/lua-typecheck-action@v0.1.2
+        uses: mrcjkb/lua-typecheck-action@v0.1
         with:
-          configpath: ".luarc.json"
+          configpath: .github/workflows/.luarc.json
+          directories: |
+            lua/neo-tree

From 10c31474ee26c91f4eb335f5c771fdb93bd48a02 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Sat, 15 Feb 2025 15:00:13 -0800
Subject: [PATCH 05/36] fix version

---
 .github/workflows/typecheck.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/typecheck.yml b/.github/workflows/typecheck.yml
index e2d2a78fc..8bcf9968d 100644
--- a/.github/workflows/typecheck.yml
+++ b/.github/workflows/typecheck.yml
@@ -39,7 +39,7 @@ jobs:
           path: "deps/nui.nvim"
 
       - name: Type Check Code Base
-        uses: mrcjkb/lua-typecheck-action@v0.1
+        uses: mrcjkb/lua-typecheck-action@v0
         with:
           configpath: .github/workflows/.luarc.json
           directories: |

From 2a113ac02399e8143a58dcfac7bf89ff737e40aa Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Mon, 17 Feb 2025 11:26:58 -0800
Subject: [PATCH 06/36] format defaults.lua and fix types

---
 lua/neo-tree/defaults.lua                    | 168 ++++++++++---------
 lua/neo-tree/sources/common/components.lua   |  11 +-
 lua/neo-tree/sources/common/container.lua    |   2 +-
 lua/neo-tree/types/components/components.lua |  19 ---
 lua/neo-tree/types/config.lua                |  19 +++
 5 files changed, 116 insertions(+), 103 deletions(-)
 delete mode 100644 lua/neo-tree/types/components/components.lua

diff --git a/lua/neo-tree/defaults.lua b/lua/neo-tree/defaults.lua
index b055ef9a6..9dca274f4 100644
--- a/lua/neo-tree/defaults.lua
+++ b/lua/neo-tree/defaults.lua
@@ -12,14 +12,14 @@ local config = {
   },
   add_blank_line_at_top = false, -- Add a blank line at the top of the tree.
   auto_clean_after_session_restore = false, -- Automatically clean up broken neo-tree buffers saved in sessions
-  close_if_last_window = false, -- Close Neo-tree if it is the last window left in the tab
+  close_if_last_window = false,  -- Close Neo-tree if it is the last window left in the tab
   default_source = "filesystem", -- you can choose a specific source `last` here which indicates the last used source
   enable_diagnostics = true,
   enable_git_status = true,
   enable_modified_markers = true, -- Show markers for files with unsaved changes.
   enable_opened_markers = true,   -- Enable tracking of opened files. Required for `components.name.highlight_opened_files`
   enable_refresh_on_write = true, -- Refresh the tree when a file is written. Only used if `use_libuv_file_watcher` is false.
-  enable_cursor_hijack = false, -- If enabled neotree will keep the cursor on the first letter of the filename when moving in the tree.
+  enable_cursor_hijack = false,   -- If enabled, neotree will keep the cursor on the first letter of the filename when moving in the tree.
   git_status_async = true,
   -- These options are for people with VERY large git repos
   git_status_async_options = {
@@ -29,7 +29,7 @@ local config = {
                        -- Anything before this will be used. The last items to be processed are the untracked files.
   },
   hide_root_node = false, -- Hide the root node.
-  retain_hidden_root_indent = false, -- IF the root node is hidden, keep the indentation anyhow. 
+  retain_hidden_root_indent = false, -- IF the root node is hidden, keep the indentation anyhow.
                                      -- This is needed if you use expanders because they render in the indent.
   log_level = "info", -- "trace", "debug", "info", "warn", "error", "fatal"
   log_to_file = false, -- true, false, "/path/to/file.log", use :NeoTreeLogs to show the file
@@ -41,10 +41,10 @@ local config = {
   -- "NC" is a special style that works well with NormalNC set
   popup_border_style = "NC", -- "double", "none", "rounded", "shadow", "single" or "solid"
   resize_timer_interval = 500, -- in ms, needed for containers to redraw right aligned and faded content
-                               -- set to -1 to disable the resize timer entirely
+  --                           -- set to -1 to disable the resize timer entirely
   --                           -- NOTE: this will speed up to 50 ms for 1 second following a resize
   sort_case_insensitive = false, -- used when sorting files and directories in the tree
-  sort_function = nil , -- uses a custom function for sorting files and directories in the tree
+  sort_function = nil,         -- a custom function for sorting files and directories in the tree
   use_popups_for_input = true, -- If false, inputs will use vim.ui.input() instead of custom floats.
   use_default_mappings = true,
   -- source_selector provides clickable tabs to switch between sources.
@@ -52,7 +52,7 @@ local config = {
     winbar = false, -- toggle to show selector on winbar
     statusline = false, -- toggle to show selector on statusline
     show_scrolled_off_parent_node = false, -- this will replace the tabs with the parent path
-                                           -- of the top visible node when scrolled down.
+    -- of the top visible node when scrolled down.
     sources = {
       { source = "filesystem" },
       { source = "buffers" },
@@ -74,7 +74,7 @@ local config = {
     padding = 0, -- can be int or table
     -- padding = { left = 2, right = 0 },
     -- separator = "▕", -- can be string or table, see below
-     separator = { left = "▏", right= "▕" },
+    separator = { left = "▏", right = "▕" },
     -- separator = { left = "/", right = "\\", override = nil },     -- |/  a  \/  b  \/  c  \...
     -- separator = { left = "/", right = "\\", override = "right" }, -- |/  a  \  b  \  c  \...
     -- separator = { left = "/", right = "\\", override = "left" },  -- |/  a  /  b  /  c  /...
@@ -206,7 +206,7 @@ local config = {
       -- then these will never be used.
       default = "*",
       highlight = "NeoTreeFileIcon",
-      provider = function(icon, node, state) -- default icon provider utilizes nvim-web-devicons if available
+      provider = function(icon, node, _) -- default icon provider utilizes nvim-web-devicons if available
         if node.type == "file" or node.type == "terminal" then
           local success, web_devicons = pcall(require, "nvim-web-devicons")
           local name = node.type == "terminal" and "terminal" or node.name
@@ -216,7 +216,7 @@ local config = {
             icon.highlight = hl or icon.highlight
           end
         end
-      end
+      end,
     },
     modified = {
       symbol = "[+] ",
@@ -224,9 +224,9 @@ local config = {
     },
     name = {
       trailing_slash = false,
-      highlight_opened_files = false, -- Requires `enable_opened_markers = true`. 
-                                      -- Take values in { false (no highlight), true (only loaded), 
-                                      -- "all" (both loaded and unloaded)}. For more information,
+      highlight_opened_files = false, -- Requires `enable_opened_markers = true`.
+                                      -- Take values in { false (no highlight), true (only loaded),
+                                      -- "all" (both loaded and unloaded) }. For more information,
                                       -- see the `show_unloaded` config of the `buffers` source.
       use_git_status_colors = true,
       highlight = "NeoTreeFileName",
@@ -234,16 +234,16 @@ local config = {
     git_status = {
       symbols = {
         -- Change type
-        added     = "✚", -- NOTE: you can set any of these to an empty string to not show them
-        deleted   = "✖",
-        modified  = "",
-        renamed   = "󰁕",
+        added = "✚", -- NOTE: you can set any of these to an empty string to not show them
+        deleted = "✖",
+        modified = "",
+        renamed = "󰁕",
         -- Status type
         untracked = "",
-        ignored   = "",
-        unstaged  = "󰄱",
-        staged    = "",
-        conflict  = "",
+        ignored = "",
+        unstaged = "󰄱",
+        staged = "",
+        conflict = "",
       },
       align = "right",
     },
@@ -294,7 +294,13 @@ local config = {
             highlight = "NeoTreeSymbolicLinkTarget",
           },
           { "clipboard", zindex = 10 },
-          { "diagnostics", errors_only = true, zindex = 20, align = "right", hide_when_expanded = true },
+          {
+            "diagnostics",
+            errors_only = true,
+            zindex = 20,
+            align = "right",
+            hide_when_expanded = true,
+          },
           { "git_status", zindex = 10, align = "right", hide_when_expanded = true },
           { "file_size", zindex = 10, align = "right" },
           { "type", zindex = 10, align = "right" },
@@ -311,7 +317,7 @@ local config = {
         content = {
           {
             "name",
-            zindex = 10
+            zindex = 10,
           },
           {
             "symlink_target",
@@ -321,7 +327,7 @@ local config = {
           { "clipboard", zindex = 10 },
           { "bufnr", zindex = 10 },
           { "modified", zindex = 20, align = "right" },
-          { "diagnostics",  zindex = 20, align = "right" },
+          { "diagnostics", zindex = 20, align = "right" },
           { "git_status", zindex = 10, align = "right" },
           { "file_size", zindex = 10, align = "right" },
           { "type", zindex = 10, align = "right" },
@@ -338,8 +344,8 @@ local config = {
       { "indent" },
       { "icon" },
       { "name" },
-      { "bufnr" }
-    }
+      { "bufnr" },
+    },
   },
   nesting_rules = {},
   -- Global custom commands that will be available in all sources (if not overridden in `opts[source_name].commands`)
@@ -369,7 +375,7 @@ local config = {
         width = "50%",
       },
       position = "50%", -- 50% means center it
-      title = function (state) -- format the text that appears at the top of a popup window
+      title = function(state) -- format the text that appears at the top of a popup window
         return "Neo-tree " .. state.name:gsub("^%l", string.upper)
       end,
       -- you can also specify border here, if you want a different setting from
@@ -377,8 +383,8 @@ local config = {
     },
     same_level = false, -- Create and paste/move files/directories on the same level as the directory under cursor (as opposed to within the directory under cursor).
     insert_as = "child", -- Affects how nodes get inserted into the tree during creation/pasting/moving of files if the node under the cursor is a directory:
-                        -- "child":   Insert nodes as children of the directory under cursor.
-                        -- "sibling": Insert nodes  as siblings of the directory under cursor.
+    -- "child":   Insert nodes as children of the directory under cursor.
+    -- "sibling": Insert nodes  as siblings of the directory under cursor.
     -- Mappings for tree window. See `:h neo-tree-mappings` for a list of built-in commands.
     -- You can also create your own commands by providing a function instead of a string.
     mapping_options = {
@@ -387,20 +393,23 @@ local config = {
     },
     mappings = {
       ["<space>"] = {
-          "toggle_node",
-          nowait = false, -- disable `nowait` if you have existing combos starting with this char that you want to use
+        "toggle_node",
+        nowait = false, -- disable `nowait` if you have existing combos starting with this char that you want to use
       },
       ["<2-LeftMouse>"] = "open",
       ["<cr>"] = "open",
       -- ["<cr>"] = { "open", config = { expand_nested_files = true } }, -- expand nested file takes precedence
       ["<esc>"] = "cancel", -- close preview or floating neo-tree window
-      ["P"] = { "toggle_preview", config = {
-        use_float = true,
-        use_image_nvim = false,
-        -- title = "Neo-tree Preview", -- You can define a custom title for the preview floating window.
-      } },
-      ["<C-f>"] = { "scroll_preview", config = {direction = -10} },
-      ["<C-b>"] = { "scroll_preview", config = {direction = 10} },
+      ["P"] = {
+        "toggle_preview",
+        config = {
+          use_float = true,
+          use_image_nvim = false,
+          -- title = "Neo-tree Preview", -- You can define a custom title for the preview floating window.
+        },
+      },
+      ["<C-f>"] = { "scroll_preview", config = { direction = -10 } },
+      ["<C-b>"] = { "scroll_preview", config = { direction = 10 } },
       ["l"] = "focus_preview",
       ["S"] = "open_split",
       -- ["S"] = "split_with_window_picker",
@@ -421,7 +430,7 @@ local config = {
         -- some commands may take optional config options, see `:h neo-tree-mappings` for details
         config = {
           show_path = "none", -- "none", "relative", "absolute"
-        }
+        },
       },
       ["A"] = "add_directory", -- also accepts the config.show_path and config.insert_as options.
       ["d"] = "delete",
@@ -455,7 +464,7 @@ local config = {
         ["[g"] = "prev_git_modified",
         ["]g"] = "next_git_modified",
         ["i"] = "show_file_details", -- see `:h neo-tree-file-actions` for options to customize the window.
-        ["o"] = { "show_help", nowait=false, config = { title = "Order by", prefix_key = "o" }},
+        ["o"] = { "show_help", nowait = false, config = { title = "Order by", prefix_key = "o" } },
         ["oc"] = { "order_by_created", nowait = false },
         ["od"] = { "order_by_diagnostics", nowait = false },
         ["og"] = { "order_by_git_status", nowait = false },
@@ -469,22 +478,22 @@ local config = {
         ["<C-n>"] = "move_cursor_down",
         ["<up>"] = "move_cursor_up",
         ["<C-p>"] = "move_cursor_up",
-        ["<esc>"] = "close"
+        ["<esc>"] = "close",
       },
     },
     async_directory_scan = "auto", -- "auto"   means refreshes are async, but it's synchronous when called from the Neotree commands.
-                                   -- "always" means directory scans are always async.
-                                   -- "never"  means directory scans are never async.
+    -- "always" means directory scans are always async.
+    -- "never"  means directory scans are never async.
     scan_mode = "shallow", -- "shallow": Don't scan into directories to detect possible empty directory a priori
-                           -- "deep": Scan into directories to detect empty or grouped empty directories a priori.
+    -- "deep": Scan into directories to detect empty or grouped empty directories a priori.
     bind_to_cwd = true, -- true creates a 2-way binding between vim's cwd and neo-tree's root
     cwd_target = {
-      sidebar = "tab",   -- sidebar is when position = left or right
-      current = "window" -- current is when position = current
+      sidebar = "tab", -- sidebar is when position = left or right
+      current = "window", -- current is when position = current
     },
     check_gitignore_in_search = true, -- check gitignore status for files/directories when searching
-                                      -- setting this to false will speed up searches, but gitignored
-                                      -- items won't be marked if they are visible.
+    -- setting this to false will speed up searches, but gitignored
+    -- items won't be marked if they are visible.
     -- The renderer section provides the renderers that will be used to render the tree.
     --   The first level is the node type.
     --   For each node type, you can specify a list of components to render.
@@ -500,7 +509,7 @@ local config = {
       hide_hidden = true, -- only works on Windows for hidden files/directories
       hide_by_name = {
         ".DS_Store",
-        "thumbs.db"
+        "thumbs.db",
         --"node_modules",
       },
       hide_by_pattern = { -- uses glob style patterns
@@ -521,16 +530,16 @@ local config = {
         --".null-ls_*",
       },
     },
-    find_by_full_path_words = false,  -- `false` means it only searches the tail of a path.
-                                      -- `true` will change the filter into a full path
-                                      -- search with space as an implicit ".*", so
-                                      -- `fi init`
-                                      -- will match: `./sources/filesystem/init.lua
+    find_by_full_path_words = false, -- `false` means it only searches the tail of a path.
+                                     -- `true` will change the filter into a full path
+                                     -- search with space as an implicit ".*", so
+                                     -- `fi init`
+                                     -- will match: `./sources/filesystem/init.lua
     --find_command = "fd", -- this is determined automatically, you probably don't need to set it
     --find_args = {  -- you can specify extra args to pass to the find command.
     --  fd = {
-      --  "--exclude", ".git",
-      --  "--exclude",  "node_modules"
+    --    "--exclude", ".git",
+    --    "--exclude",  "node_modules"
     --  }
     --},
     ---- or use a function instead of list of strings
@@ -567,7 +576,7 @@ local config = {
                                             -- window like netrw would, regardless of window.position
                           -- "disabled",    -- netrw left alone, neo-tree does not handle opening dirs
     use_libuv_file_watcher = false, -- This will use the OS level file watchers to detect changes
-                                    -- instead of relying on nvim autocmd events.
+    -- instead of relying on nvim autocmd events.
   },
   buffers = {
     bind_to_cwd = true,
@@ -576,17 +585,17 @@ local config = {
       --              -- the current file is changed while the tree is open.
       leave_dirs_open = false, -- `false` closes auto expanded dirs, such as with `:Neotree reveal`
     },
-    group_empty_dirs = true,  -- when true, empty directories will be grouped together
-    show_unloaded = false,    -- When working with sessions, for example, restored but unfocused buffers
-                              -- are mark as "unloaded". Turn this on to view these unloaded buffer.
-    terminals_first = false,  -- when true, terminals will be listed before file buffers
+    group_empty_dirs = true, -- when true, empty directories will be grouped together
+    show_unloaded = false, -- When working with sessions, for example, restored but unfocused buffers
+                           -- are mark as "unloaded". Turn this on to view these unloaded buffer.
+    terminals_first = false, -- when true, terminals will be listed before file buffers
     window = {
       mappings = {
         ["<bs>"] = "navigate_up",
         ["."] = "set_root",
         ["bd"] = "buffer_delete",
         ["i"] = "show_file_details", -- see `:h neo-tree-file-actions` for options to customize the window.
-        ["o"] = { "show_help", nowait=false, config = { title = "Order by", prefix_key = "o" }},
+        ["o"] = { "show_help", nowait = false, config = { title = "Order by", prefix_key = "o" } },
         ["oc"] = { "order_by_created", nowait = false },
         ["od"] = { "order_by_diagnostics", nowait = false },
         ["om"] = { "order_by_modified", nowait = false },
@@ -607,7 +616,7 @@ local config = {
         ["gp"] = "git_push",
         ["gg"] = "git_commit_and_push",
         ["i"] = "show_file_details", -- see `:h neo-tree-file-actions` for options to customize the window.
-        ["o"] = { "show_help", nowait=false, config = { title = "Order by", prefix_key = "o" }},
+        ["o"] = { "show_help", nowait = false, config = { title = "Order by", prefix_key = "o" } },
         ["oc"] = { "order_by_created", nowait = false },
         ["od"] = { "order_by_diagnostics", nowait = false },
         ["om"] = { "order_by_modified", nowait = false },
@@ -622,19 +631,20 @@ local config = {
     client_filters = "first",
     renderers = {
       root = {
-        {"indent"},
-        {"icon", default="C" },
-        {"name", zindex = 10},
+        { "indent" },
+        { "icon", default = "C" },
+        { "name", zindex = 10 },
       },
       symbol = {
-        {"indent", with_expanders = true},
-        {"kind_icon", default="?" },
-        {"container",
-        content = {
-          {"name", zindex = 10},
-          {"kind_name", zindex = 20, align = "right"},
-          }
-        }
+        { "indent", with_expanders = true },
+        { "kind_icon", default = "?" },
+        {
+          "container",
+          content = {
+            { "name", zindex = 10 },
+            { "kind_name", zindex = 20, align = "right" },
+          },
+        },
       },
     },
     window = {
@@ -696,16 +706,16 @@ local config = {
       -- Parameter = { icon = ' ', hl = '@parameter' },
       -- StaticMethod = { icon = '󰠄 ', hl = 'Function' },
       -- Macro = { icon = ' ', hl = 'Macro' },
-    }
+    },
   },
   example = {
     renderers = {
       custom = {
-        {"indent"},
-        {"icon", default="C" },
-        {"custom"},
-        {"name"}
-      }
+        { "indent" },
+        { "icon", default = "C" },
+        { "custom" },
+        { "name" },
+      },
     },
     window = {
       mappings = {
diff --git a/lua/neo-tree/sources/common/components.lua b/lua/neo-tree/sources/common/components.lua
index b300a80f3..105d927e4 100644
--- a/lua/neo-tree/sources/common/components.lua
+++ b/lua/neo-tree/sources/common/components.lua
@@ -428,7 +428,7 @@ end
 ---@class (exact) neotree.Config.Component.Common.Name : neotree.Config.Component.Base.Highlight
 ---@field trailing_slash boolean?
 ---@field use_git_status_colors boolean?
----@field highlight_opened_files boolean?
+---@field highlight_opened_files boolean|"all"?
 ---@field right_padding integer?
 
 ---@class (exact) neotree.Component.Common.Name : neotree.Config.Component.Common.Name
@@ -658,7 +658,9 @@ local file_time = function(config, node, state, stat_field)
   }
 end
 
----@class (exact) neotree.Component.Common.LastModified : neotree.Config.Component.Common.Time
+---@class (exact) neotree.Config.Component.Common.LastModified : neotree.Config.Component.Common.Time
+
+---@class (exact) neotree.Component.Common.LastModified : neotree.Config.Component.Common.LastModified
 ---@field [1] "last_modified"
 
 ---@param config neotree.Config.Component.Common.Time
@@ -666,7 +668,9 @@ M.last_modified = function(config, node, state)
   return file_time(config, node, state, "mtime")
 end
 
----@class (exact) neotree.Component.Common.Created : neotree.Config.Component.Common.Time
+---@class (exact) neotree.Config.Component.Common.Created : neotree.Config.Component.Common.Time
+
+---@class (exact) neotree.Component.Common.Created : neotree.Config.Component.Common.Created
 ---@field [1] "created"
 
 ---@param config neotree.Config.Component.Common.Time
@@ -693,7 +697,6 @@ M.symlink_target = function(config, node, _)
 end
 
 ---@class (exact) neotree.Config.Component.Common.Type : neotree.Config.Component.Base.Highlight
----@field format neotree.DateFormat
 ---@field width integer?
 
 ---@class (exact) neotree.Component.Common.Type : neotree.Config.Component.Common.Type
diff --git a/lua/neo-tree/sources/common/container.lua b/lua/neo-tree/sources/common/container.lua
index cf2131fe9..b171b68ff 100644
--- a/lua/neo-tree/sources/common/container.lua
+++ b/lua/neo-tree/sources/common/container.lua
@@ -311,7 +311,7 @@ end
 ---@field left_padding integer?
 ---@field right_padding integer?
 ---@field enable_character_fade boolean?
----@field context neotree.Component[]
+---@field context neotree.Component[]?
 
 ---@class (exact) neotree.Component.Common.Container : neotree.Config.Component.Common.Container
 ---@field [1] "clipboard"
diff --git a/lua/neo-tree/types/components/components.lua b/lua/neo-tree/types/components/components.lua
deleted file mode 100644
index d94e7ef52..000000000
--- a/lua/neo-tree/types/components/components.lua
+++ /dev/null
@@ -1,19 +0,0 @@
-
----@class neotree.Config.Renderers
----@field directory neotree.Renderer.Component[]?
----@field file neotree.Renderer.Component[]?
----@field message neotree.Renderer.Component[]?
----@field terminal neotree.Renderer.Component[]?
-
----@class neotree.Config.ComponentDefaults
----@field container neotree.Config.Component.Container
----@field indent neotree.Config.Component.Indent
----@field icon neotree.Config.Component.Icon
----@field modified neotree.Config.Component.Modified
----@field name neotree.Config.Component.Name
----@field git_status neotree.Config.Component.GitStatus
----@field file_size neotree.Config.Component.FileSize
----@field type neotree.Config.Component.Type
----@field last_modified neotree.Config.Component.LastModified
----@field created neotree.Config.Component.Created
----@field symlink_target neotree.Config.Component.SymlinkTarget
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
index f4ce4cfd7..e3ebc9872 100644
--- a/lua/neo-tree/types/config.lua
+++ b/lua/neo-tree/types/config.lua
@@ -152,6 +152,25 @@
 ---@field event string
 ---@field handler fun(table?):neotree.Config.EventHandler.HandlerResult?
 
+---@class neotree.Config.Renderers
+---@field directory neotree.Component[]?
+---@field file neotree.Component[]?
+---@field message neotree.Component[]?
+---@field terminal neotree.Component[]?
+
+---@class neotree.Config.ComponentDefaults
+---@field container neotree.Config.Component.Common.Container
+---@field indent neotree.Config.Component.Common.Indent
+---@field icon neotree.Config.Component.Common.Icon
+---@field modified neotree.Config.Component.Common.Modified
+---@field name neotree.Config.Component.Common.Name
+---@field git_status neotree.Config.Component.Common.GitStatus
+---@field file_size neotree.Config.Component.Common.FileSize
+---@field type neotree.Config.Component.Common.Type
+---@field last_modified neotree.Config.Component.Common.LastModified
+---@field created neotree.Config.Component.Common.Created
+---@field symlink_target neotree.Config.Component.Common.SymlinkTarget
+
 ---@alias neotree.Config.BorderStyle "NC"|"none"|"rounded"|"shadow"|"single"|"solid"|nil
 
 ---@class neotree.Config

From 79d2ff392abc33de02c8c19c19642618fe69afd4 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Mon, 17 Feb 2025 11:28:57 -0800
Subject: [PATCH 07/36] comment out example

---
 lua/neo-tree/defaults.lua | 35 ++++++++++++++++++-----------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/lua/neo-tree/defaults.lua b/lua/neo-tree/defaults.lua
index 9dca274f4..6913382f8 100644
--- a/lua/neo-tree/defaults.lua
+++ b/lua/neo-tree/defaults.lua
@@ -708,22 +708,23 @@ local config = {
       -- Macro = { icon = ' ', hl = 'Macro' },
     },
   },
-  example = {
-    renderers = {
-      custom = {
-        { "indent" },
-        { "icon", default = "C" },
-        { "custom" },
-        { "name" },
-      },
-    },
-    window = {
-      mappings = {
-        ["<cr>"] = "toggle_node",
-        ["<C-e>"] = "example_command",
-        ["d"] = "show_debug_info",
-      },
-    },
-  },
+  -- If you want to write your own source for items, this is how it would be configured:
+  -- example = {
+  --   renderers = {
+  --     custom = {
+  --       { "indent" },
+  --       { "icon", default = "C" },
+  --       { "custom" },
+  --       { "name" },
+  --     },
+  --   },
+  --   window = {
+  --     mappings = {
+  --       ["<cr>"] = "toggle_node",
+  --       ["<C-e>"] = "example_command",
+  --       ["d"] = "show_debug_info",
+  --     },
+  --   },
+  -- },
 }
 return config

From e60318737a489a06c3ff41d601ccab1e7ad2d48b Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Mon, 17 Feb 2025 11:29:51 -0800
Subject: [PATCH 08/36] only typecheck defaults

---
 .github/workflows/typecheck.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/typecheck.yml b/.github/workflows/typecheck.yml
index 8bcf9968d..1a2ce4fd7 100644
--- a/.github/workflows/typecheck.yml
+++ b/.github/workflows/typecheck.yml
@@ -43,4 +43,4 @@ jobs:
         with:
           configpath: .github/workflows/.luarc.json
           directories: |
-            lua/neo-tree
+            lua/neo-tree/defaults.lua

From eb83d22f63a466b50c0628effbfd45c2079e211d Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Mon, 17 Feb 2025 12:39:45 -0800
Subject: [PATCH 09/36] use llscheck (wip)

---
 .github/workflows/llscheck.yml  | 41 +++++++++++++++++++++++++++++
 .github/workflows/typecheck.yml | 46 ---------------------------------
 2 files changed, 41 insertions(+), 46 deletions(-)
 create mode 100644 .github/workflows/llscheck.yml
 delete mode 100644 .github/workflows/typecheck.yml

diff --git a/.github/workflows/llscheck.yml b/.github/workflows/llscheck.yml
new file mode 100644
index 000000000..2b1b2a6c4
--- /dev/null
+++ b/.github/workflows/llscheck.yml
@@ -0,0 +1,41 @@
+name: Lua Type Check
+on:
+  pull_request: ~
+  push:
+    branches:
+      - '*'
+
+jobs:
+  llscheck:
+    strategy:
+      matrix:
+        neovim: ["0.8", "0.9", "0.10", "nightly"]
+        lua: ["5.1", "luajit-master"]
+    runs-on: ubuntu-latest
+    name: llscheck
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - uses: luarocks/gh-actions-lua@v10
+      with:
+        luaVersion: ${{matrix.lua}}
+
+    - uses: luarocks/gh-actions-luarocks@v4
+
+    - name: build
+      run: |
+        luarocks install llscheck
+
+    - name: Install lua-language-server
+      uses: jdx/mise-action@v2
+      with:
+        mise_toml: |
+          [tools]
+          neovim = "${{ matrix.neovim }}"
+          lua-language-server = "latest"
+
+    - name: Print Version
+      run: |
+        lua-language-server --version
diff --git a/.github/workflows/typecheck.yml b/.github/workflows/typecheck.yml
deleted file mode 100644
index 1a2ce4fd7..000000000
--- a/.github/workflows/typecheck.yml
+++ /dev/null
@@ -1,46 +0,0 @@
-name: Lua Type Check
-on:
-  pull_request: ~
-  push:
-    branches:
-      - '*'
-
-jobs:
-  build:
-    name: Type Check Code Base
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v4
-
-      - name: Checkout dependency neodev
-        uses: actions/checkout@v4
-        with:
-          repository: "folke/neodev.nvim"
-          path: "deps/neodev.nvim"
-
-      - name: Checkout dependency plenary
-        uses: actions/checkout@v4
-        with:
-          repository: "nvim-lua/plenary.nvim"
-          path: "deps/plenary.nvim"
-
-      - name: Checkout dependency nvim-web-devicons
-        uses: actions/checkout@v4
-        with:
-          repository: "nvim-tree/nvim-web-devicons"
-          path: "deps/nvim-web-devicons"
-
-      - name: Checkout dependency nui
-        uses: actions/checkout@v4
-        with:
-          repository: "MunifTanjim/nui.nvim"
-          path: "deps/nui.nvim"
-
-      - name: Type Check Code Base
-        uses: mrcjkb/lua-typecheck-action@v0
-        with:
-          configpath: .github/workflows/.luarc.json
-          directories: |
-            lua/neo-tree/defaults.lua

From 2243fca99e024e79aac9769695ed6de7f3fab20b Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Mon, 17 Feb 2025 13:43:05 -0800
Subject: [PATCH 10/36] fix version

---
 .github/workflows/.luarc.json  | 3 ++-
 .github/workflows/llscheck.yml | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/.luarc.json b/.github/workflows/.luarc.json
index c330cb0ea..b75b0abed 100644
--- a/.github/workflows/.luarc.json
+++ b/.github/workflows/.luarc.json
@@ -11,7 +11,8 @@
     "/github/workspace/deps/plenary.nvim/lua",
     "/github/workspace/deps/nui.nvim/lua",
     "/github/workspace/deps/nvim-web-devicons/lua",
-    "${3rd}/busted/library"
+    "${3rd}/busted/library",
+    "${VIMRUNTIME}/lua"
   ],
   "diagnostics.libraryFiles": "Disable",
   "workspace.checkThirdParty": "Disable"
diff --git a/.github/workflows/llscheck.yml b/.github/workflows/llscheck.yml
index 2b1b2a6c4..1825e03d9 100644
--- a/.github/workflows/llscheck.yml
+++ b/.github/workflows/llscheck.yml
@@ -22,7 +22,7 @@ jobs:
       with:
         luaVersion: ${{matrix.lua}}
 
-    - uses: luarocks/gh-actions-luarocks@v4
+    - uses: luarocks/gh-actions-luarocks@v5
 
     - name: build
       run: |

From 23a158723b4c836eb1b694893310742503d540aa Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Thu, 20 Feb 2025 12:42:28 -0800
Subject: [PATCH 11/36] reduce versions for llscheck

---
 .github/workflows/llscheck.yml | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/.github/workflows/llscheck.yml b/.github/workflows/llscheck.yml
index 1825e03d9..ddcbd9aa6 100644
--- a/.github/workflows/llscheck.yml
+++ b/.github/workflows/llscheck.yml
@@ -9,7 +9,7 @@ jobs:
   llscheck:
     strategy:
       matrix:
-        neovim: ["0.8", "0.9", "0.10", "nightly"]
+        neovim: ["0.10"]
         lua: ["5.1", "luajit-master"]
     runs-on: ubuntu-latest
     name: llscheck
@@ -35,7 +35,3 @@ jobs:
           [tools]
           neovim = "${{ matrix.neovim }}"
           lua-language-server = "latest"
-
-    - name: Print Version
-      run: |
-        lua-language-server --version

From 64b7a942399fbe1460072a7d8ee99794828b7cdb Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Thu, 20 Feb 2025 12:54:10 -0800
Subject: [PATCH 12/36] Use more makefile

---
 .github/workflows/ci.yml |  3 +-
 Makefile                 | 27 +++++++++++++
 scripts/test.sh          | 85 ----------------------------------------
 3 files changed, 29 insertions(+), 86 deletions(-)
 delete mode 100755 scripts/test.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 45c11c2cb..0fab4b379 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -76,7 +76,8 @@ jobs:
       - name: Run tests
         run: |
           export PATH="${PWD}/build/bin:${PATH}"
-          ./scripts/test.sh
+          make setup
+          make test
 
       # - name: Upload coverage to Codecov
       #   uses: codecov/codecov-action@v2
diff --git a/Makefile b/Makefile
index 58d929166..e18a214c6 100644
--- a/Makefile
+++ b/Makefile
@@ -10,3 +10,30 @@ test-docker:
 .PHONY: format
 format:
 	stylua --glob '*.lua' --glob '!defaults.lua' .
+
+llscheck:
+	llscheck --configpath .github/workflows/.luarc.json .
+
+# Dependencies:
+
+PLUGINS_DIR := ./.dependencies/site/pack/vendor/start
+
+$(PLUGINS_DIR):
+	mkdir -p "$(PLUGINS_DIR)"
+
+.PHONY: nui.nvim nvim-web-devicons plenary.nvim setup
+nui.nvim:
+	git clone https://github.com/MunifTanjim/nui.nvim "$(PLUGINS_DIR)/nui.nvim"
+
+nvim-web-devicons:
+	git clone https://github.com/nvim-tree/nvim-web-devicons "$(PLUGINS_DIR)/nvim-web-devicons"
+
+plenary.nvim:
+	git clone https://github.com/nvim-lua/plenary.nvim "$(PLUGINS_DIR)/plenary.nvim"
+
+setup: | $(PLUGINS_DIR) nui.nvim nvim-web-devicons plenary.nvim
+	@echo "[test] environment ready"
+
+.PHONY: clean
+clean:
+	rm -rf "$(PLUGINS_DIR)"
diff --git a/scripts/test.sh b/scripts/test.sh
deleted file mode 100755
index 16f742e63..000000000
--- a/scripts/test.sh
+++ /dev/null
@@ -1,85 +0,0 @@
-#!/usr/bin/env bash
-
-set -euo pipefail
-
-luacov_dir=""
-
-while [[ $# -gt 0 ]]; do
-  case "${1}" in
-    --clean)
-      shift
-      echo "[test] cleaning up environment"
-      rm -rf ./.testcache
-      echo "[test] envionment cleaned"
-      ;;
-    *)
-      shift
-      ;;
-  esac
-done
-
-function setup_environment() {
-  echo
-  echo "[test] setting up environment"
-  echo
-
-  local plugins_dir="./.testcache/site/pack/vendor/start"
-  if [[ ! -d "${plugins_dir}" ]]; then
-    mkdir -p "${plugins_dir}"
-  fi
-
-  if [[ ! -d "${plugins_dir}/nui.nvim" ]]; then
-    echo "[plugins] nui.nvim: installing..."
-    git clone https://github.com/MunifTanjim/nui.nvim "${plugins_dir}/nui.nvim"
-    echo "[plugins] nui.nvim: installed"
-    echo
-  fi
-
-  if [[ ! -d "${plugins_dir}/nvim-web-devicons" ]]; then
-    echo "[plugins] nvim-web-devicons: installing..."
-    git clone https://github.com/nvim-tree/nvim-web-devicons "${plugins_dir}/nvim-web-devicons"
-    echo "[plugins] nvim-web-devicons: installed"
-    echo
-  fi
-
-  if [[ ! -d "${plugins_dir}/plenary.nvim" ]]; then
-    echo "[plugins] plenary.nvim: installing..."
-    git clone https://github.com/nvim-lua/plenary.nvim "${plugins_dir}/plenary.nvim"
-    # this commit broke luacov
-    #git -C "${plugins_dir}/plenary.nvim" revert --no-commit 9069d14a120cadb4f6825f76821533f2babcab92
-    echo "[plugins] plenary.nvim: installed"
-    echo
-  fi
-
-  echo "[test] environment ready"
-  echo
-}
-
-function luacov_start() {
-  luacov_dir="$(dirname "$(luarocks which luacov 2>/dev/null | head -1)")"
-  if [[ "${luacov_dir}" == "." ]]; then
-    luacov_dir=""
-  fi
-
-  if test -n "${luacov_dir}"; then
-    rm -f luacov.*.out
-    export LUA_PATH=";;${luacov_dir}/?.lua"
-  fi
-}
-
-function luacov_end() {
-  if test -n "${luacov_dir}"; then
-    luacov
-
-    echo
-    tail -n +$(($(grep -n "^Summary$" luacov.report.out | cut -d":" -f1) - 1)) luacov.report.out
-  fi
-}
-
-setup_environment
-
-#luacov_start
-
-make test
-
-#luacov_end

From 410ef58ca0e97cfd7afb14a6edecdd1f9f138c10 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Thu, 20 Feb 2025 13:06:32 -0800
Subject: [PATCH 13/36] allow ci to be manually run

---
 .github/workflows/ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0fab4b379..677166d81 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,6 +7,7 @@ on:
       - v2.x
       - v3.x
   pull_request:
+  workflow_dispatch:
 
 jobs:
   stylua-check:

From 2295b9f2e2fda03ec5a1fffc486f360d4f976f11 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Thu, 20 Feb 2025 13:47:07 -0800
Subject: [PATCH 14/36] update test script

---
 tests/mininit.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/mininit.lua b/tests/mininit.lua
index eba04797e..47f5b2a24 100644
--- a/tests/mininit.lua
+++ b/tests/mininit.lua
@@ -4,7 +4,7 @@ local root_dir = vim.fn.fnamemodify(vim.trim(vim.fn.system("git rev-parse --show
 
 package.path = string.format("%s;%s?.lua;%s?/init.lua", package.path, root_dir, root_dir)
 
-vim.opt.packpath:prepend(string.format("%s", root_dir .. ".testcache/site"))
+vim.opt.packpath:prepend(root_dir .. ".dependencies/site")
 
 vim.opt.rtp = {
   root_dir,

From e963be96322379e8e6b19e06e0a7dbbccf2dfca4 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Thu, 20 Feb 2025 13:47:29 -0800
Subject: [PATCH 15/36] update gitignore

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 6bfe3810b..383ee6daa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,4 +44,5 @@ tags
 
 # Others
 .testcache
+.dependencies
 luacov.*.out

From f6b4fa965afbc109039912bb072ff77590755d8a Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Fri, 21 Feb 2025 14:02:04 -0800
Subject: [PATCH 16/36] Update makefile & workflows, add luvit-meta dependency

---
 .github/workflows/.luarc.json  | 13 ++++++-------
 .github/workflows/llscheck.yml |  5 +++++
 .luarc.json                    | 10 +++++++++-
 Makefile                       | 35 ++++++++++++++++++----------------
 4 files changed, 39 insertions(+), 24 deletions(-)

diff --git a/.github/workflows/.luarc.json b/.github/workflows/.luarc.json
index b75b0abed..c7c5937f3 100644
--- a/.github/workflows/.luarc.json
+++ b/.github/workflows/.luarc.json
@@ -6,13 +6,12 @@
     "lua/?/init.lua"
   ],
   "workspace.library": [
-    "/github/workspace/lua/neo-tree/types",
-    "/github/workspace/deps/neodev.nvim/types/stable",
-    "/github/workspace/deps/plenary.nvim/lua",
-    "/github/workspace/deps/nui.nvim/lua",
-    "/github/workspace/deps/nvim-web-devicons/lua",
-    "${3rd}/busted/library",
-    "${VIMRUNTIME}/lua"
+    "$PWD/lua/",
+    "$PWD/.dependencies/site/pack/vendor/start/plenary.nvim/lua",
+    "$PWD/.dependencies/site/pack/vendor/start/nui.nvim/lua",
+    "$PWD/.dependencies/site/pack/vendor/start/nvim-web-devicons/lua",
+    "$PWD/.dependencies/site/pack/vendor/start/luvit-meta/library",
+    "$VIMRUNTIME/lua"
   ],
   "diagnostics.libraryFiles": "Disable",
   "workspace.checkThirdParty": "Disable"
diff --git a/.github/workflows/llscheck.yml b/.github/workflows/llscheck.yml
index ddcbd9aa6..283b698e4 100644
--- a/.github/workflows/llscheck.yml
+++ b/.github/workflows/llscheck.yml
@@ -35,3 +35,8 @@ jobs:
           [tools]
           neovim = "${{ matrix.neovim }}"
           lua-language-server = "latest"
+
+    - name: Run llscheck
+      continue-on-error: true
+      run: |
+        make llscheck
diff --git a/.luarc.json b/.luarc.json
index c2d33c20a..0c0611745 100644
--- a/.luarc.json
+++ b/.luarc.json
@@ -1,3 +1,11 @@
 {
-  "diagnostics.globals": ["vim"]
+    "diagnostics.libraryFiles": "Disable",
+    "runtime.version": "LuaJIT",
+    "workspace.checkThirdParty": "Disable",
+    "workspace.ignoreDir": [
+        ".dependencies"
+    ],
+    "workspace.library": [
+        "$VIMRUNTIME/lua"
+    ]
 }
diff --git a/Makefile b/Makefile
index e18a214c6..964e8d0b1 100644
--- a/Makefile
+++ b/Makefile
@@ -11,29 +11,32 @@ test-docker:
 format:
 	stylua --glob '*.lua' --glob '!defaults.lua' .
 
-llscheck:
-	llscheck --configpath .github/workflows/.luarc.json .
-
 # Dependencies:
 
-PLUGINS_DIR := ./.dependencies/site/pack/vendor/start
+DEPS := ./.dependencies/site/pack/vendor/start
+
+$(DEPS):
+	mkdir -p "$(DEPS)"
 
-$(PLUGINS_DIR):
-	mkdir -p "$(PLUGINS_DIR)"
+$(DEPS)/nui.nvim: $(DEPS)
+	@test -d "$(DEPS)/nui.nvim" || git clone https://github.com/MunifTanjim/nui.nvim "$(DEPS)/nui.nvim"
 
-.PHONY: nui.nvim nvim-web-devicons plenary.nvim setup
-nui.nvim:
-	git clone https://github.com/MunifTanjim/nui.nvim "$(PLUGINS_DIR)/nui.nvim"
+$(DEPS)/nvim-web-devicons: $(DEPS)
+	@test -d "$(DEPS)/nvim-web-devicons" || git clone https://github.com/nvim-tree/nvim-web-devicons "$(DEPS)/nvim-web-devicons"
 
-nvim-web-devicons:
-	git clone https://github.com/nvim-tree/nvim-web-devicons "$(PLUGINS_DIR)/nvim-web-devicons"
+$(DEPS)/plenary.nvim: $(DEPS)
+	@test -d "$(DEPS)/plenary.nvim" || git clone https://github.com/nvim-lua/plenary.nvim "$(DEPS)/plenary.nvim"
 
-plenary.nvim:
-	git clone https://github.com/nvim-lua/plenary.nvim "$(PLUGINS_DIR)/plenary.nvim"
+$(DEPS)/luvit-meta: $(DEPS)
+	@test -d "$(DEPS)/luvit-meta" || git clone https://github.com/Bilal2453/luvit-meta "$(DEPS)/luvit-meta"
 
-setup: | $(PLUGINS_DIR) nui.nvim nvim-web-devicons plenary.nvim
-	@echo "[test] environment ready"
+setup: $(DEPS)/nui.nvim $(DEPS)/nvim-web-devicons $(DEPS)/plenary.nvim $(DEPS)/luvit-meta
+	@echo "[setup] environment ready"
 
 .PHONY: clean
 clean:
-	rm -rf "$(PLUGINS_DIR)"
+	rm -rf "$(DEPS)"
+
+CONFIGURATION = .github/workflows/.luarc.json
+llscheck: $(DEPS)
+	VIMRUNTIME="`nvim --clean --headless --cmd 'lua io.write(vim.env.VIMRUNTIME)' --cmd 'quit'`" llscheck --configpath $(CONFIGURATION) .

From dead5931a8ed2ca8e24fd61ab7906892f391a0fa Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Fri, 21 Feb 2025 14:08:21 -0800
Subject: [PATCH 17/36] ignore .lua/.luarocks in llscheck

---
 .github/workflows/.luarc.json | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/.luarc.json b/.github/workflows/.luarc.json
index c7c5937f3..d016c24ff 100644
--- a/.github/workflows/.luarc.json
+++ b/.github/workflows/.luarc.json
@@ -1,6 +1,9 @@
 {
-  "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
+  "diagnostics.libraryFiles": "Disable",
   "runtime.version": "LuaJIT",
+  "workspace.checkThirdParty": "Disable",
+  "workspace.ignoreDir": [".dependencies", ".lua", ".luarocks"],
+  "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
   "runtime.path": [
     "lua/?.lua",
     "lua/?/init.lua"
@@ -12,7 +15,5 @@
     "$PWD/.dependencies/site/pack/vendor/start/nvim-web-devicons/lua",
     "$PWD/.dependencies/site/pack/vendor/start/luvit-meta/library",
     "$VIMRUNTIME/lua"
-  ],
-  "diagnostics.libraryFiles": "Disable",
-  "workspace.checkThirdParty": "Disable"
+  ]
 }

From 20201461addd963f4b034902a8158e26d43e4af4 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Fri, 21 Feb 2025 14:09:14 -0800
Subject: [PATCH 18/36] change llscheck config

---
 .github/workflows/llscheck.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/llscheck.yml b/.github/workflows/llscheck.yml
index 283b698e4..30b1f6344 100644
--- a/.github/workflows/llscheck.yml
+++ b/.github/workflows/llscheck.yml
@@ -39,4 +39,4 @@ jobs:
     - name: Run llscheck
       continue-on-error: true
       run: |
-        make llscheck
+        make llscheck CONFIGURATION=.github/workflows/.luarc.json

From fcd7c2adc90da55adf6d117e35e03149e4e4b283 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Fri, 21 Feb 2025 14:11:23 -0800
Subject: [PATCH 19/36] fix llscheck makefile targetg

---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 964e8d0b1..44933f65a 100644
--- a/Makefile
+++ b/Makefile
@@ -38,5 +38,5 @@ clean:
 	rm -rf "$(DEPS)"
 
 CONFIGURATION = .github/workflows/.luarc.json
-llscheck: $(DEPS)
+llscheck: setup
 	VIMRUNTIME="`nvim --clean --headless --cmd 'lua io.write(vim.env.VIMRUNTIME)' --cmd 'quit'`" llscheck --configpath $(CONFIGURATION) .

From 70bc6fc5871100a745a21f4dbdec07f37c7ab778 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Fri, 21 Feb 2025 14:20:32 -0800
Subject: [PATCH 20/36] remove current dir from github workflow luarc

---
 .github/workflows/.luarc.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/.luarc.json b/.github/workflows/.luarc.json
index d016c24ff..385ab9018 100644
--- a/.github/workflows/.luarc.json
+++ b/.github/workflows/.luarc.json
@@ -9,7 +9,6 @@
     "lua/?/init.lua"
   ],
   "workspace.library": [
-    "$PWD/lua/",
     "$PWD/.dependencies/site/pack/vendor/start/plenary.nvim/lua",
     "$PWD/.dependencies/site/pack/vendor/start/nui.nvim/lua",
     "$PWD/.dependencies/site/pack/vendor/start/nvim-web-devicons/lua",

From 0391c6f26c8f2083616ad6cb68ff9b8e11b3a342 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Sat, 22 Feb 2025 00:13:38 -0800
Subject: [PATCH 21/36] refine types

---
 lua/neo-tree/sources/common/components.lua |  6 +++---
 lua/neo-tree/types/config.lua              | 10 +++++-----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/lua/neo-tree/sources/common/components.lua b/lua/neo-tree/sources/common/components.lua
index 105d927e4..9e2eca2b9 100644
--- a/lua/neo-tree/sources/common/components.lua
+++ b/lua/neo-tree/sources/common/components.lua
@@ -370,7 +370,7 @@ end
 ---@field folder_empty_open string The icon to display to represent an empty but open folder.
 ---@field folder_open string The icon to display for an open folder.
 ---@field folder_closed string The icon to display for a closed folder.
----@field provider fun(icon, node, state):(neotree.Render.Node|neotree.Render.Node[])
+---@field provider fun(icon, node, state):(neotree.Render.Node|neotree.Render.Node[]|nil)
 
 ---@class (exact) neotree.Component.Common.Icon : neotree.Config.Component.Common.Icon
 ---@field [1] "icon"
@@ -486,13 +486,13 @@ end
 ---@class (exact) neotree.Config.Component.Common.Indent : neotree.Config.Component.Base.Highlight
 ---@field expander_collapsed string?
 ---@field expander_expanded string?
----@field expander_highlight boolean?
+---@field expander_highlight string?
 ---@field indent_marker string?
 ---@field indent_size integer?
 ---@field last_indent_marker string?
 ---@field padding integer?
 ---@field with_expanders boolean?
----@field with_markers integer?
+---@field with_markers boolean?
 
 ---@class (exact) neotree.Component.Common.Indent : neotree.Config.Component.Common.Indent
 ---@field [1] "indent"
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
index e3ebc9872..4a36002d6 100644
--- a/lua/neo-tree/types/config.lua
+++ b/lua/neo-tree/types/config.lua
@@ -153,10 +153,10 @@
 ---@field handler fun(table?):neotree.Config.EventHandler.HandlerResult?
 
 ---@class neotree.Config.Renderers
----@field directory neotree.Component[]?
----@field file neotree.Component[]?
----@field message neotree.Component[]?
----@field terminal neotree.Component[]?
+---@field directory neotree.Component.Common[]?
+---@field file neotree.Component.Common[]?
+---@field message neotree.Component.Common[]?
+---@field terminal neotree.Component.Common[]?
 
 ---@class neotree.Config.ComponentDefaults
 ---@field container neotree.Config.Component.Common.Container
@@ -204,7 +204,7 @@
 ---@field event_handlers table[]?
 ---@field default_component_configs neotree.Config.ComponentDefaults?
 ---@field renderers neotree.Config.Renderers?
----@field nesting_rules table[]? -- TODO, merge rework
+---@field nesting_rules neotree.FileNesting.Rule[]
 ---@field commands table<string, fun()>?
 ---@field window neotree.Config.Window?
 ---@field filesystem neotree.Config.Filesystem?

From d5f77dacefddce51581a6f4c4b73a5b5e843136a Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Mon, 24 Feb 2025 12:34:21 -0800
Subject: [PATCH 22/36] remove unused highlight fields

---
 lua/neo-tree/sources/common/components.lua | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lua/neo-tree/sources/common/components.lua b/lua/neo-tree/sources/common/components.lua
index 9e2eca2b9..249097f25 100644
--- a/lua/neo-tree/sources/common/components.lua
+++ b/lua/neo-tree/sources/common/components.lua
@@ -164,7 +164,7 @@ local function get_defined_sign(severity)
   return defined
 end
 
----@class (exact) neotree.Config.Component.Common.Diagnostics : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Diagnostics
 ---@field errors_only boolean?
 ---@field hide_when_expanded boolean?
 ---@field symbols table<string, string>?
@@ -696,7 +696,7 @@ M.symlink_target = function(config, node, _)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.Type : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Type
 ---@field width integer?
 
 ---@class (exact) neotree.Component.Common.Type : neotree.Config.Component.Common.Type

From d5f2b044c0eeac600062b5835d4cbe2193f65d57 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Tue, 25 Feb 2025 03:40:53 -0800
Subject: [PATCH 23/36] use lua ls's new check format instead of llscheck

---
 .github/workflows/.luarc-5.1.json              | 18 ++++++++++++++++++
 .../{.luarc.json => .luarc-luajit-master.json} |  0
 .github/workflows/llscheck.yml                 | 15 +++++----------
 Makefile                                       |  4 ++--
 4 files changed, 25 insertions(+), 12 deletions(-)
 create mode 100644 .github/workflows/.luarc-5.1.json
 rename .github/workflows/{.luarc.json => .luarc-luajit-master.json} (100%)

diff --git a/.github/workflows/.luarc-5.1.json b/.github/workflows/.luarc-5.1.json
new file mode 100644
index 000000000..665e0e189
--- /dev/null
+++ b/.github/workflows/.luarc-5.1.json
@@ -0,0 +1,18 @@
+{
+  "diagnostics.libraryFiles": "Disable",
+  "runtime.version": "Lua 5.1",
+  "workspace.checkThirdParty": "Disable",
+  "workspace.ignoreDir": [".dependencies", ".lua", ".luarocks"],
+  "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
+  "runtime.path": [
+    "lua/?.lua",
+    "lua/?/init.lua"
+  ],
+  "workspace.library": [
+    "$PWD/.dependencies/site/pack/vendor/start/plenary.nvim/lua",
+    "$PWD/.dependencies/site/pack/vendor/start/nui.nvim/lua",
+    "$PWD/.dependencies/site/pack/vendor/start/nvim-web-devicons/lua",
+    "$PWD/.dependencies/site/pack/vendor/start/luvit-meta/library",
+    "$VIMRUNTIME/lua"
+  ]
+}
diff --git a/.github/workflows/.luarc.json b/.github/workflows/.luarc-luajit-master.json
similarity index 100%
rename from .github/workflows/.luarc.json
rename to .github/workflows/.luarc-luajit-master.json
diff --git a/.github/workflows/llscheck.yml b/.github/workflows/llscheck.yml
index 30b1f6344..c8043f2f3 100644
--- a/.github/workflows/llscheck.yml
+++ b/.github/workflows/llscheck.yml
@@ -6,13 +6,13 @@ on:
       - '*'
 
 jobs:
-  llscheck:
+  luacheck:
     strategy:
       matrix:
         neovim: ["0.10"]
         lua: ["5.1", "luajit-master"]
     runs-on: ubuntu-latest
-    name: llscheck
+    name: luacheck
 
     steps:
     - name: Checkout
@@ -22,12 +22,6 @@ jobs:
       with:
         luaVersion: ${{matrix.lua}}
 
-    - uses: luarocks/gh-actions-luarocks@v5
-
-    - name: build
-      run: |
-        luarocks install llscheck
-
     - name: Install lua-language-server
       uses: jdx/mise-action@v2
       with:
@@ -36,7 +30,8 @@ jobs:
           neovim = "${{ matrix.neovim }}"
           lua-language-server = "latest"
 
-    - name: Run llscheck
+    - name: Run lua-language-server check
       continue-on-error: true
       run: |
-        make llscheck CONFIGURATION=.github/workflows/.luarc.json
+        LUARC=".github/workflows/.luarc-${{ matrix.lua }}.json"
+        make luacheck CONFIGURATION="$LUARC"
diff --git a/Makefile b/Makefile
index 44933f65a..39abde565 100644
--- a/Makefile
+++ b/Makefile
@@ -38,5 +38,5 @@ clean:
 	rm -rf "$(DEPS)"
 
 CONFIGURATION = .github/workflows/.luarc.json
-llscheck: setup
-	VIMRUNTIME="`nvim --clean --headless --cmd 'lua io.write(vim.env.VIMRUNTIME)' --cmd 'quit'`" llscheck --configpath $(CONFIGURATION) .
+luacheck: setup
+	VIMRUNTIME="`nvim --clean --headless --cmd 'lua io.write(vim.env.VIMRUNTIME)' --cmd 'quit'`" lua-language-server --configpath=$(CONFIGURATION) --check=.

From f13e7ba713373d34e521ead839688655aca356ed Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Tue, 25 Feb 2025 03:46:47 -0800
Subject: [PATCH 24/36] finish a rename

---
 lua/neo-tree/sources/document_symbols/lib/symbols_utils.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lua/neo-tree/sources/document_symbols/lib/symbols_utils.lua b/lua/neo-tree/sources/document_symbols/lib/symbols_utils.lua
index 686e59bee..08f6dd892 100644
--- a/lua/neo-tree/sources/document_symbols/lib/symbols_utils.lua
+++ b/lua/neo-tree/sources/document_symbols/lib/symbols_utils.lua
@@ -127,7 +127,7 @@ local function parse_resp(resp_node, id, state, parent_search_path)
 end
 
 ---Callback function for lsp request
----@param lsp_resp neotree.LspRespRaw the response of the lsp client
+---@param lsp_resp neotree.lsp.RespRaw the response of the lsp client
 ---@param state table the state of the source
 local on_lsp_resp = function(lsp_resp, state)
   if lsp_resp == nil or type(lsp_resp) ~= "table" then

From 379297712cabfadc8104cb8ca010a759fb89702a Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Wed, 26 Feb 2025 13:26:36 -0800
Subject: [PATCH 25/36] update all luarc

---
 .github/workflows/.luarc-5.1.json             | 41 ++++++++++++-------
 .github/workflows/.luarc-luajit-master.json   | 41 ++++++++++++-------
 .../{llscheck.yml => luals-check.yml}         |  5 +--
 .luarc.json                                   | 32 +++++++++++----
 Makefile                                      |  4 +-
 lua/neo-tree.lua                              |  1 +
 lua/neo-tree/events/init.lua                  |  2 +
 lua/neo-tree/events/queue.lua                 |  7 ++++
 lua/neo-tree/setup/init.lua                   |  9 ++--
 lua/neo-tree/types/config.lua                 |  8 +++-
 10 files changed, 102 insertions(+), 48 deletions(-)
 rename .github/workflows/{llscheck.yml => luals-check.yml} (93%)

diff --git a/.github/workflows/.luarc-5.1.json b/.github/workflows/.luarc-5.1.json
index 665e0e189..f99167d46 100644
--- a/.github/workflows/.luarc-5.1.json
+++ b/.github/workflows/.luarc-5.1.json
@@ -1,18 +1,29 @@
 {
-  "diagnostics.libraryFiles": "Disable",
-  "runtime.version": "Lua 5.1",
-  "workspace.checkThirdParty": "Disable",
-  "workspace.ignoreDir": [".dependencies", ".lua", ".luarocks"],
   "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
-  "runtime.path": [
-    "lua/?.lua",
-    "lua/?/init.lua"
-  ],
-  "workspace.library": [
-    "$PWD/.dependencies/site/pack/vendor/start/plenary.nvim/lua",
-    "$PWD/.dependencies/site/pack/vendor/start/nui.nvim/lua",
-    "$PWD/.dependencies/site/pack/vendor/start/nvim-web-devicons/lua",
-    "$PWD/.dependencies/site/pack/vendor/start/luvit-meta/library",
-    "$VIMRUNTIME/lua"
-  ]
+  "diagnostics.libraryFiles": "Disable",
+  "runtime": {
+    "version": "Lua 5.1",
+    "path": [
+      "lua/?.lua",
+      "lua/?/init.lua",
+      "library/?.lua",
+      "library/?/init.lua"
+    ]
+  },
+  "workspace": {
+    "checkThirdParty": "Disable",
+    "library": [
+      "$PWD/.dependencies/site/pack/vendor/start/plenary.nvim",
+      "$PWD/.dependencies/site/pack/vendor/start/nui.nvim",
+      "$PWD/.dependencies/site/pack/vendor/start/nvim-web-devicons",
+      "${3rd}/luassert",
+      "${3rd}/busted",
+      "${3rd}/luv",
+      "$VIMRUNTIME"
+    ],
+    "ignoreDir": [
+      ".dependencies",
+      ".luarocks"
+    ]
+  }
 }
diff --git a/.github/workflows/.luarc-luajit-master.json b/.github/workflows/.luarc-luajit-master.json
index 385ab9018..fffe0872f 100644
--- a/.github/workflows/.luarc-luajit-master.json
+++ b/.github/workflows/.luarc-luajit-master.json
@@ -1,18 +1,29 @@
 {
-  "diagnostics.libraryFiles": "Disable",
-  "runtime.version": "LuaJIT",
-  "workspace.checkThirdParty": "Disable",
-  "workspace.ignoreDir": [".dependencies", ".lua", ".luarocks"],
   "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
-  "runtime.path": [
-    "lua/?.lua",
-    "lua/?/init.lua"
-  ],
-  "workspace.library": [
-    "$PWD/.dependencies/site/pack/vendor/start/plenary.nvim/lua",
-    "$PWD/.dependencies/site/pack/vendor/start/nui.nvim/lua",
-    "$PWD/.dependencies/site/pack/vendor/start/nvim-web-devicons/lua",
-    "$PWD/.dependencies/site/pack/vendor/start/luvit-meta/library",
-    "$VIMRUNTIME/lua"
-  ]
+  "diagnostics.libraryFiles": "Disable",
+  "runtime": {
+    "version": "LuaJIT",
+    "path": [
+      "lua/?.lua",
+      "lua/?/init.lua",
+      "library/?.lua",
+      "library/?/init.lua"
+    ]
+  },
+  "workspace": {
+    "checkThirdParty": "Disable",
+    "library": [
+      "$PWD/.dependencies/site/pack/vendor/start/plenary.nvim",
+      "$PWD/.dependencies/site/pack/vendor/start/nui.nvim",
+      "$PWD/.dependencies/site/pack/vendor/start/nvim-web-devicons",
+      "${3rd}/luassert",
+      "${3rd}/busted",
+      "${3rd}/luv",
+      "$VIMRUNTIME"
+    ],
+    "ignoreDir": [
+      ".dependencies",
+      ".luarocks"
+    ]
+  }
 }
diff --git a/.github/workflows/llscheck.yml b/.github/workflows/luals-check.yml
similarity index 93%
rename from .github/workflows/llscheck.yml
rename to .github/workflows/luals-check.yml
index c8043f2f3..784261573 100644
--- a/.github/workflows/llscheck.yml
+++ b/.github/workflows/luals-check.yml
@@ -1,4 +1,4 @@
-name: Lua Type Check
+name: Lua Language Server Diagnostics
 on:
   pull_request: ~
   push:
@@ -6,13 +6,12 @@ on:
       - '*'
 
 jobs:
-  luacheck:
+  luals-check:
     strategy:
       matrix:
         neovim: ["0.10"]
         lua: ["5.1", "luajit-master"]
     runs-on: ubuntu-latest
-    name: luacheck
 
     steps:
     - name: Checkout
diff --git a/.luarc.json b/.luarc.json
index 0c0611745..fffe0872f 100644
--- a/.luarc.json
+++ b/.luarc.json
@@ -1,11 +1,29 @@
 {
-    "diagnostics.libraryFiles": "Disable",
-    "runtime.version": "LuaJIT",
-    "workspace.checkThirdParty": "Disable",
-    "workspace.ignoreDir": [
-        ".dependencies"
+  "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
+  "diagnostics.libraryFiles": "Disable",
+  "runtime": {
+    "version": "LuaJIT",
+    "path": [
+      "lua/?.lua",
+      "lua/?/init.lua",
+      "library/?.lua",
+      "library/?/init.lua"
+    ]
+  },
+  "workspace": {
+    "checkThirdParty": "Disable",
+    "library": [
+      "$PWD/.dependencies/site/pack/vendor/start/plenary.nvim",
+      "$PWD/.dependencies/site/pack/vendor/start/nui.nvim",
+      "$PWD/.dependencies/site/pack/vendor/start/nvim-web-devicons",
+      "${3rd}/luassert",
+      "${3rd}/busted",
+      "${3rd}/luv",
+      "$VIMRUNTIME"
     ],
-    "workspace.library": [
-        "$VIMRUNTIME/lua"
+    "ignoreDir": [
+      ".dependencies",
+      ".luarocks"
     ]
+  }
 }
diff --git a/Makefile b/Makefile
index 39abde565..ca18388f4 100644
--- a/Makefile
+++ b/Makefile
@@ -37,6 +37,6 @@ setup: $(DEPS)/nui.nvim $(DEPS)/nvim-web-devicons $(DEPS)/plenary.nvim $(DEPS)/l
 clean:
 	rm -rf "$(DEPS)"
 
-CONFIGURATION = .github/workflows/.luarc.json
-luacheck: setup
+CONFIGURATION = .luarc.json
+luals-check: setup
 	VIMRUNTIME="`nvim --clean --headless --cmd 'lua io.write(vim.env.VIMRUNTIME)' --cmd 'quit'`" lua-language-server --configpath=$(CONFIGURATION) --check=.
diff --git a/lua/neo-tree.lua b/lua/neo-tree.lua
index 0e6326b78..0e513cb9f 100644
--- a/lua/neo-tree.lua
+++ b/lua/neo-tree.lua
@@ -9,6 +9,7 @@ M.close_all = function()
   require("neo-tree.command").execute({ action = "close" })
 end
 
+---@type neotree.Config?
 local new_user_config = nil
 
 ---Updates the config of neo-tree using the latest user config passed through setup, if any.
diff --git a/lua/neo-tree/events/init.lua b/lua/neo-tree/events/init.lua
index 1eb099eef..94b0e7e57 100644
--- a/lua/neo-tree/events/init.lua
+++ b/lua/neo-tree/events/init.lua
@@ -3,6 +3,7 @@ local q = require("neo-tree.events.queue")
 local log = require("neo-tree.log")
 local utils = require("neo-tree.utils")
 
+---@class neotree.Event.Functions
 local M = {
   -- Well known event names, you can make up your own
   AFTER_RENDER = "after_render",
@@ -52,6 +53,7 @@ local M = {
   VIM_WIN_ENTER = "vim_win_enter",
 }
 
+---@param event_name neotree.Event
 M.define_autocmd_event = function(event_name, autocmds, debounce_frequency, seed_fn, nested)
   local opts = {
     setup = function()
diff --git a/lua/neo-tree/events/queue.lua b/lua/neo-tree/events/queue.lua
index 6797213b5..5b55363a2 100644
--- a/lua/neo-tree/events/queue.lua
+++ b/lua/neo-tree/events/queue.lua
@@ -6,6 +6,12 @@ local event_queues = {}
 local event_definitions = {}
 local M = {}
 
+---@class neotree.Event.Handler
+---@field event neotree.Event
+---@field handler fun(...)
+---@field id string?
+local a = {}
+
 local validate_event_handler = function(event_handler)
   if type(event_handler) ~= "table" then
     error("Event handler must be a table")
@@ -104,6 +110,7 @@ M.fire_event = function(event, args)
   end
 end
 
+---@param event_handler neotree.Event.Handler
 M.subscribe = function(event_handler)
   validate_event_handler(event_handler)
 
diff --git a/lua/neo-tree/setup/init.lua b/lua/neo-tree/setup/init.lua
index 9ac1e97df..bada73bfa 100644
--- a/lua/neo-tree/setup/init.lua
+++ b/lua/neo-tree/setup/init.lua
@@ -470,6 +470,8 @@ local merge_renderers = function(default_config, source_default_config, user_con
   end
 end
 
+---@param user_config neotree.Config?
+---@return neotree.Config._Full full_config
 M.merge_config = function(user_config)
   local default_config = vim.deepcopy(defaults)
   user_config = vim.deepcopy(user_config or {})
@@ -538,7 +540,7 @@ M.merge_config = function(user_config)
   -- used to either limit the sources that or loaded, or add extra external sources
   local all_sources = {}
   local all_source_names = {}
-  for _, source in ipairs(user_config.sources or default_config.sources) do
+  for _, source in ipairs(user_config.sources or default_config.sources or {}) do
     local parts = utils.split(source, ".")
     local name = parts[#parts]
     local is_internal_ns, is_external_ns = false, false
@@ -624,11 +626,10 @@ M.merge_config = function(user_config)
   end
   --print(vim.inspect(default_config.filesystem))
 
-  -- Moving user_config.sources to user_config.orig_sources
-  user_config.orig_sources = user_config.sources and user_config.sources or {}
+  -- local orig_sources = user_config.sources and user_config.sources or {}
 
   -- apply the users config
-  M.config = vim.tbl_deep_extend("force", default_config, user_config)
+  M.config = vim.tbl_deep_extend("force", default_config, user_config) --[[@as neotree.Config._Full]]
 
   -- RE: 873, fixes issue with invalid source checking by overriding
   -- source table with name table
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
index 4a36002d6..b388dc722 100644
--- a/lua/neo-tree/types/config.lua
+++ b/lua/neo-tree/types/config.lua
@@ -1,4 +1,5 @@
 ---@meta
+---@diagnostic disable:duplicate-doc-field
 
 ---@class neotree.Config.MappingOptions
 ---@field noremap boolean
@@ -78,7 +79,7 @@
 ---@field same_level boolean
 ---@field insert_as "child"|"sibling"
 ---@field mapping_options neotree.Config.MappingOptions
----@field mappings table
+---@field mappings neotree.Config.Mapping[]
 
 ---@alias neotree.Config.Cwd "tab"|"window"|"global"
 
@@ -201,7 +202,7 @@
 ---@field use_popups_for_input boolean?
 ---@field use_default_mappings boolean?
 ---@field source_selector neotree.Config.SourceSelector?
----@field event_handlers table[]?
+---@field event_handlers neotree.Event.Handler[]?
 ---@field default_component_configs neotree.Config.ComponentDefaults?
 ---@field renderers neotree.Config.Renderers?
 ---@field nesting_rules neotree.FileNesting.Rule[]
@@ -210,3 +211,6 @@
 ---@field filesystem neotree.Config.Filesystem?
 ---@field buffers neotree.Config.Buffers?
 ---@field git_status neotree.Config.GitStatus?
+
+---@class neotree.Config._Full : neotree.Config
+---@field prior_windows table<string, integer[]>?

From 9282a80e75faa5940f91f0bf2994f7d55dedf135 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Thu, 27 Feb 2025 12:49:00 -0800
Subject: [PATCH 26/36] fix typo

---
 .github/workflows/luals-check.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/luals-check.yml b/.github/workflows/luals-check.yml
index 784261573..88f72027e 100644
--- a/.github/workflows/luals-check.yml
+++ b/.github/workflows/luals-check.yml
@@ -33,4 +33,4 @@ jobs:
       continue-on-error: true
       run: |
         LUARC=".github/workflows/.luarc-${{ matrix.lua }}.json"
-        make luacheck CONFIGURATION="$LUARC"
+        make luals-check CONFIGURATION="$LUARC"

From 45e2622fb0f226b43fcd59b7190a00b6e4ad4ba3 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Sat, 1 Mar 2025 20:08:16 -0800
Subject: [PATCH 27/36] no need for luvit-meta

---
 Makefile                                   |  5 +---
 lua/neo-tree/sources/common/components.lua | 31 +++++++++++-----------
 lua/neo-tree/sources/common/container.lua  |  4 ++-
 lua/neo-tree/types/config.lua              |  1 -
 4 files changed, 19 insertions(+), 22 deletions(-)

diff --git a/Makefile b/Makefile
index ca18388f4..b31daef7c 100644
--- a/Makefile
+++ b/Makefile
@@ -27,10 +27,7 @@ $(DEPS)/nvim-web-devicons: $(DEPS)
 $(DEPS)/plenary.nvim: $(DEPS)
 	@test -d "$(DEPS)/plenary.nvim" || git clone https://github.com/nvim-lua/plenary.nvim "$(DEPS)/plenary.nvim"
 
-$(DEPS)/luvit-meta: $(DEPS)
-	@test -d "$(DEPS)/luvit-meta" || git clone https://github.com/Bilal2453/luvit-meta "$(DEPS)/luvit-meta"
-
-setup: $(DEPS)/nui.nvim $(DEPS)/nvim-web-devicons $(DEPS)/plenary.nvim $(DEPS)/luvit-meta
+setup: $(DEPS)/nui.nvim $(DEPS)/nvim-web-devicons $(DEPS)/plenary.nvim
 	@echo "[setup] environment ready"
 
 .PHONY: clean
diff --git a/lua/neo-tree/sources/common/components.lua b/lua/neo-tree/sources/common/components.lua
index 249097f25..91ee8e1c0 100644
--- a/lua/neo-tree/sources/common/components.lua
+++ b/lua/neo-tree/sources/common/components.lua
@@ -37,8 +37,6 @@ local log = require("neo-tree.log")
 ---@class neotree.Component.Common Use the neotree.Component.Common.* types to get more specific types.
 ---@field [1] neotree.Component.Common._Key
 
-local a = {}
-
 ---@class neotree.Render.Node
 ---@field text string The text to display.
 ---@field highlight string The highlight for the text.
@@ -54,10 +52,11 @@ local make_two_char = function(symbol)
   end
 end
 
----@class (exact) neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Base
+---@field enabled boolean?
 ---@field highlight string?
 
----@class (exact) neotree.Config.Component.Common.Bufnr : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Bufnr : neotree.Config.Component.Base
 
 ---@class (exact) neotree.Component.Common.Bufnr : neotree.Config.Component.Common.Bufnr
 ---@field [1] "bufnr"
@@ -78,7 +77,7 @@ M.bufnr = function(config, node, _)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.Clipboard : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Clipboard : neotree.Config.Component.Base
 
 ---@class (exact) neotree.Component.Common.Clipboard : neotree.Config.Component.Common.Clipboard
 ---@field [1] "clipboard"
@@ -98,7 +97,7 @@ end
 
 M.container = container.render
 
----@class (exact) neotree.Config.Component.Common.CurrentFilter : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.CurrentFilter : neotree.Config.Component.Base
 
 ---@class (exact) neotree.Component.Common.CurrentFilter : neotree.Config.Component.Common.CurrentFilter
 ---@field [1] "current_filter"
@@ -164,7 +163,7 @@ local function get_defined_sign(severity)
   return defined
 end
 
----@class (exact) neotree.Config.Component.Common.Diagnostics
+---@class (exact) neotree.Config.Component.Common.Diagnostics : neotree.Config.Component.Base
 ---@field errors_only boolean?
 ---@field hide_when_expanded boolean?
 ---@field symbols table<string, string>?
@@ -214,7 +213,7 @@ M.diagnostics = function(config, node, state)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.GitStatus : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.GitStatus : neotree.Config.Component.Base
 ---@field hide_when_expanded boolean?
 ---@field symbols table<string, string>?
 
@@ -364,7 +363,7 @@ M.filtered_by = function(_, node, _)
   return result
 end
 
----@class (exact) neotree.Config.Component.Common.Icon : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Icon : neotree.Config.Component.Base
 ---@field default string The default icon for a node.
 ---@field folder_empty string The string to display to represent an empty folder.
 ---@field folder_empty_open string The icon to display to represent an empty but open folder.
@@ -404,7 +403,7 @@ M.icon = function(config, node, state)
   return icon
 end
 
----@class (exact) neotree.Config.Component.Common.Modified : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Modified : neotree.Config.Component.Base
 ---@field symbol string?
 
 ---@class (exact) neotree.Component.Common.Modified : neotree.Config.Component.Common.Modified
@@ -425,7 +424,7 @@ M.modified = function(config, node, state)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.Name : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Name : neotree.Config.Component.Base
 ---@field trailing_slash boolean?
 ---@field use_git_status_colors boolean?
 ---@field highlight_opened_files boolean|"all"?
@@ -483,7 +482,7 @@ M.name = function(config, node, state)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.Indent : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Indent : neotree.Config.Component.Base
 ---@field expander_collapsed string?
 ---@field expander_expanded string?
 ---@field expander_highlight string?
@@ -593,7 +592,7 @@ local get_header = function(state, label, size)
   return vim.fn.printf("%" .. size .. "s  ", truncate_string(label, size))
 end
 
----@class (exact) neotree.Config.Component.Common.FileSize : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.FileSize : neotree.Config.Component.Base
 ---@field width integer?
 
 ---@class (exact) neotree.Component.Common.FileSize : neotree.Config.Component.Common.FileSize
@@ -627,7 +626,7 @@ M.file_size = function(config, node, state)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.Time : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.Time : neotree.Config.Component.Base
 ---@field format neotree.DateFormat
 ---@field width integer?
 
@@ -678,7 +677,7 @@ M.created = function(config, node, state)
   return file_time(config, node, state, "birthtime")
 end
 
----@class (exact) neotree.Config.Component.Common.SymlinkTarget : neotree.Config.Component.Base.Highlight
+---@class (exact) neotree.Config.Component.Common.SymlinkTarget : neotree.Config.Component.Base
 ---@field text_format string
 
 ---@class (exact) neotree.Component.Common.SymlinkTarget : neotree.Config.Component.Common.SymlinkTarget
@@ -696,7 +695,7 @@ M.symlink_target = function(config, node, _)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.Type
+---@class (exact) neotree.Config.Component.Common.Type : neotree.Config.Component.Base
 ---@field width integer?
 
 ---@class (exact) neotree.Component.Common.Type : neotree.Config.Component.Common.Type
diff --git a/lua/neo-tree/sources/common/container.lua b/lua/neo-tree/sources/common/container.lua
index b171b68ff..63614b467 100644
--- a/lua/neo-tree/sources/common/container.lua
+++ b/lua/neo-tree/sources/common/container.lua
@@ -311,7 +311,9 @@ end
 ---@field left_padding integer?
 ---@field right_padding integer?
 ---@field enable_character_fade boolean?
----@field context neotree.Component[]?
+---@field content neotree.Component[]?
+
+---@alias neotree.Component table
 
 ---@class (exact) neotree.Component.Common.Container : neotree.Config.Component.Common.Container
 ---@field [1] "clipboard"
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
index b388dc722..e0d29d0df 100644
--- a/lua/neo-tree/types/config.lua
+++ b/lua/neo-tree/types/config.lua
@@ -1,5 +1,4 @@
 ---@meta
----@diagnostic disable:duplicate-doc-field
 
 ---@class neotree.Config.MappingOptions
 ---@field noremap boolean

From be91ecc0624215df4930cf43314eafd44874a0ec Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Sun, 2 Mar 2025 04:37:39 -0800
Subject: [PATCH 28/36] type components

---
 lua/neo-tree.lua                              |  1 +
 lua/neo-tree/sources/buffers/components.lua   | 11 +++
 lua/neo-tree/sources/common/components.lua    | 38 +++++------
 .../sources/document_symbols/components.lua   | 28 ++++++++
 .../sources/filesystem/components.lua         | 13 ++++
 .../sources/git_status/components.lua         | 16 +++++
 lua/neo-tree/types/components.lua             | 13 ++++
 lua/neo-tree/types/config.lua                 | 67 +------------------
 lua/neo-tree/types/config/buffers.lua         |  9 +++
 .../types/config/document_symbols.lua         | 12 ++++
 lua/neo-tree/types/config/filesystem.lua      | 48 +++++++++++++
 lua/neo-tree/types/config/git_status.lua      |  4 ++
 lua/neo-tree/types/events.lua                 | 50 ++++++++++++++
 13 files changed, 221 insertions(+), 89 deletions(-)
 create mode 100644 lua/neo-tree/types/components.lua
 create mode 100644 lua/neo-tree/types/config/buffers.lua
 create mode 100644 lua/neo-tree/types/config/document_symbols.lua
 create mode 100644 lua/neo-tree/types/config/filesystem.lua
 create mode 100644 lua/neo-tree/types/config/git_status.lua
 create mode 100644 lua/neo-tree/types/events.lua

diff --git a/lua/neo-tree.lua b/lua/neo-tree.lua
index 0e513cb9f..0a5ce1d4c 100644
--- a/lua/neo-tree.lua
+++ b/lua/neo-tree.lua
@@ -99,6 +99,7 @@ local function try_netrw_hijack(path)
   return false
 end
 
+---@param config neotree.Config
 M.setup = function(config)
   -- merging is deferred until ensure_config
   new_user_config = config
diff --git a/lua/neo-tree/sources/buffers/components.lua b/lua/neo-tree/sources/buffers/components.lua
index 0d6d3b1a5..638cb4afe 100644
--- a/lua/neo-tree/sources/buffers/components.lua
+++ b/lua/neo-tree/sources/buffers/components.lua
@@ -14,8 +14,19 @@ local highlights = require("neo-tree.ui.highlights")
 local common = require("neo-tree.sources.common.components")
 local utils = require("neo-tree.utils")
 
+---@alias neotree.Component.Buffers._Key
+---|"name"
+
+---@class neotree.Component.Buffers
+---@field [1] neotree.Component.Buffers._Key|neotree.Component.Common._Key
+
+---@type table<neotree.Component.Buffers._Key, neotree.Component.Renderer>
 local M = {}
 
+---@class (exact) neotree.Component.Buffers.Name : neotree.Config.Component.Common.Name
+---@field [1] "name"
+
+---@param config neotree.Config.Component.Common.Name
 M.name = function(config, node, state)
   local highlight = config.highlight or highlights.FILE_NAME_OPENED
   local name = node.name
diff --git a/lua/neo-tree/sources/common/components.lua b/lua/neo-tree/sources/common/components.lua
index e62397bd2..49343c8f9 100644
--- a/lua/neo-tree/sources/common/components.lua
+++ b/lua/neo-tree/sources/common/components.lua
@@ -37,11 +37,7 @@ local log = require("neo-tree.log")
 ---@class neotree.Component.Common Use the neotree.Component.Common.* types to get more specific types.
 ---@field [1] neotree.Component.Common._Key
 
----@class neotree.Render.Node
----@field text string The text to display.
----@field highlight string The highlight for the text.
-
----@type table<neotree.Component.Common._Key,fun(config, node, state):(neotree.Render.Node|neotree.Render.Node[])>
+---@type table<neotree.Component.Common._Key, neotree.Component.Renderer>
 local M = {}
 
 local make_two_char = function(symbol)
@@ -52,11 +48,7 @@ local make_two_char = function(symbol)
   end
 end
 
----@class (exact) neotree.Config.Component.Base
----@field enabled boolean?
----@field highlight string?
-
----@class (exact) neotree.Config.Component.Common.Bufnr : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.Bufnr : neotree.Config.Component
 
 ---@class (exact) neotree.Component.Common.Bufnr : neotree.Config.Component.Common.Bufnr
 ---@field [1] "bufnr"
@@ -77,7 +69,7 @@ M.bufnr = function(config, node, _)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.Clipboard : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.Clipboard : neotree.Config.Component
 
 ---@class (exact) neotree.Component.Common.Clipboard : neotree.Config.Component.Common.Clipboard
 ---@field [1] "clipboard"
@@ -97,7 +89,7 @@ end
 
 M.container = container.render
 
----@class (exact) neotree.Config.Component.Common.CurrentFilter : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.CurrentFilter : neotree.Config.Component
 
 ---@class (exact) neotree.Component.Common.CurrentFilter : neotree.Config.Component.Common.CurrentFilter
 ---@field [1] "current_filter"
@@ -163,7 +155,7 @@ local function get_defined_sign(severity)
   return defined
 end
 
----@class (exact) neotree.Config.Component.Common.Diagnostics : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.Diagnostics : neotree.Config.Component
 ---@field errors_only boolean?
 ---@field hide_when_expanded boolean?
 ---@field symbols table<string, string>?
@@ -213,7 +205,7 @@ M.diagnostics = function(config, node, state)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.GitStatus : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.GitStatus : neotree.Config.Component
 ---@field hide_when_expanded boolean?
 ---@field symbols table<string, string>?
 
@@ -363,13 +355,13 @@ M.filtered_by = function(_, node, _)
   return result
 end
 
----@class (exact) neotree.Config.Component.Common.Icon : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.Icon : neotree.Config.Component
 ---@field default string The default icon for a node.
 ---@field folder_empty string The string to display to represent an empty folder.
 ---@field folder_empty_open string The icon to display to represent an empty but open folder.
 ---@field folder_open string The icon to display for an open folder.
 ---@field folder_closed string The icon to display for a closed folder.
----@field provider fun(icon, node, state):(neotree.Render.Node|neotree.Render.Node[]|nil)
+---@field provider neotree.IconProvider?
 
 ---@class (exact) neotree.Component.Common.Icon : neotree.Config.Component.Common.Icon
 ---@field [1] "icon"
@@ -403,7 +395,7 @@ M.icon = function(config, node, state)
   return icon
 end
 
----@class (exact) neotree.Config.Component.Common.Modified : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.Modified : neotree.Config.Component
 ---@field symbol string?
 
 ---@class (exact) neotree.Component.Common.Modified : neotree.Config.Component.Common.Modified
@@ -424,7 +416,7 @@ M.modified = function(config, node, state)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.Name : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.Name : neotree.Config.Component
 ---@field trailing_slash boolean?
 ---@field use_git_status_colors boolean?
 ---@field highlight_opened_files boolean|"all"?
@@ -486,7 +478,7 @@ M.name = function(config, node, state)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.Indent : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.Indent : neotree.Config.Component
 ---@field expander_collapsed string?
 ---@field expander_expanded string?
 ---@field expander_highlight string?
@@ -596,7 +588,7 @@ local get_header = function(state, label, size)
   return vim.fn.printf("%" .. size .. "s  ", truncate_string(label, size))
 end
 
----@class (exact) neotree.Config.Component.Common.FileSize : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.FileSize : neotree.Config.Component
 ---@field width integer?
 
 ---@class (exact) neotree.Component.Common.FileSize : neotree.Config.Component.Common.FileSize
@@ -630,7 +622,7 @@ M.file_size = function(config, node, state)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.Time : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.Time : neotree.Config.Component
 ---@field format neotree.DateFormat
 ---@field width integer?
 
@@ -681,7 +673,7 @@ M.created = function(config, node, state)
   return file_time(config, node, state, "birthtime")
 end
 
----@class (exact) neotree.Config.Component.Common.SymlinkTarget : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.SymlinkTarget : neotree.Config.Component
 ---@field text_format string
 
 ---@class (exact) neotree.Component.Common.SymlinkTarget : neotree.Config.Component.Common.SymlinkTarget
@@ -699,7 +691,7 @@ M.symlink_target = function(config, node, _)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.Type : neotree.Config.Component.Base
+---@class (exact) neotree.Config.Component.Common.Type : neotree.Config.Component
 ---@field width integer?
 
 ---@class (exact) neotree.Component.Common.Type : neotree.Config.Component.Common.Type
diff --git a/lua/neo-tree/sources/document_symbols/components.lua b/lua/neo-tree/sources/document_symbols/components.lua
index b6283e8c5..13b1eacd2 100644
--- a/lua/neo-tree/sources/document_symbols/components.lua
+++ b/lua/neo-tree/sources/document_symbols/components.lua
@@ -13,8 +13,24 @@
 local highlights = require("neo-tree.ui.highlights")
 local common = require("neo-tree.sources.common.components")
 
+---@alias neotree.Component.DocumentSymbols._Key
+---|"kind_icon"
+---|"kind_name"
+---|"name"
+
+---@class neotree.Component.DocumentSymbols Use the neotree.Component.DocumentSymbols.* types to get more specific types.
+---@field [1] neotree.Component.DocumentSymbols._Key|neotree.Component.Common._Key
+
+---@type table<neotree.Component.DocumentSymbols._Key, neotree.Component.Renderer>
 local M = {}
 
+---@class (exact) neotree.Config.Component.DocumentSymbols.KindIcon : neotree.Config.Component
+---@field provider neotree.IconProvider?
+
+---@class (exact) neotree.Component.DocumentSymbols.KindIcon : neotree.Config.Component.DocumentSymbols.KindIcon
+---@field [1] "kind_icon"
+
+---@param config neotree.Config.Component.DocumentSymbols.KindIcon
 M.kind_icon = function(config, node, state)
   local icon = {
     text = node:get_depth() == 1 and "" or node.extra.kind.icon,
@@ -28,6 +44,12 @@ M.kind_icon = function(config, node, state)
   return icon
 end
 
+---@class (exact) neotree.Config.Component.DocumentSymbols.KindName : neotree.Config.Component
+
+---@class (exact) neotree.Component.DocumentSymbols.KindName : neotree.Config.Component.DocumentSymbols.KindName
+---@field [1] "kind_name"
+
+---@param config neotree.Config.Component.DocumentSymbols.KindName
 M.kind_name = function(config, node, state)
   return {
     text = node:get_depth() == 1 and "" or node.extra.kind.name,
@@ -35,6 +57,12 @@ M.kind_name = function(config, node, state)
   }
 end
 
+---@class (exact) neotree.Config.Component.DocumentSymbols.Name : neotree.Config.Component
+
+---@class (exact) neotree.Component.DocumentSymbols.Name : neotree.Config.Component.DocumentSymbols.Name
+---@field [1] "name"
+
+---@param config neotree.Config.Component.DocumentSymbols.Name
 M.name = function(config, node, state)
   return {
     text = node.name,
diff --git a/lua/neo-tree/sources/filesystem/components.lua b/lua/neo-tree/sources/filesystem/components.lua
index d2839aabe..ebe63c4db 100644
--- a/lua/neo-tree/sources/filesystem/components.lua
+++ b/lua/neo-tree/sources/filesystem/components.lua
@@ -14,8 +14,21 @@ local highlights = require("neo-tree.ui.highlights")
 local common = require("neo-tree.sources.common.components")
 local utils = require("neo-tree.utils")
 
+---@alias neotree.Component.Filesystem._Key
+---|"current_filter"
+
+---@class neotree.Component.Filesystem
+---@field [1] neotree.Component.Filesystem._Key|neotree.Component.Common._Key
+
+---@type table<neotree.Component.Filesystem._Key, neotree.Component.Renderer>
 local M = {}
 
+---@class (exact) neotree.Config.Component.Filesystem.CurrentFilter : neotree.Config.Component
+
+---@class (exact) neotree.Component.Filesystem.CurrentFilter : neotree.Config.Component.Filesystem.CurrentFilter
+---@field [1] "current_filter"
+
+---@param config neotree.Config.Component.Filesystem.CurrentFilter
 M.current_filter = function(config, node, state)
   local filter = node.search_pattern or ""
   if filter == "" then
diff --git a/lua/neo-tree/sources/git_status/components.lua b/lua/neo-tree/sources/git_status/components.lua
index 7d1c1f72e..01a72e7a1 100644
--- a/lua/neo-tree/sources/git_status/components.lua
+++ b/lua/neo-tree/sources/git_status/components.lua
@@ -15,6 +15,22 @@ local common = require("neo-tree.sources.common.components")
 
 local M = {}
 
+---@alias neotree.Component.GitStatus._Key
+---|"name"
+
+---@class neotree.Component.GitStatus
+---@field [1] neotree.Component.GitStatus._Key|neotree.Component.Common._Key
+
+---@type table<neotree.Component.GitStatus._Key, neotree.Component.Renderer>
+local M = {}
+
+---@class (exact) neotree.Config.Component.GitStatus.Name : neotree.Config.Component
+---@field use_git_status_colors boolean?
+
+---@class (exact) neotree.Component.GitStatus.Name: neotree.Config.Component.GitStatus.Name
+---@field [1] "current_filter"
+
+---@param config neotree.Config.Component.GitStatus.Name
 M.name = function(config, node, state)
   local highlight = config.highlight or highlights.FILE_NAME_OPENED
   local name = node.name
diff --git a/lua/neo-tree/types/components.lua b/lua/neo-tree/types/components.lua
new file mode 100644
index 000000000..5688c94b1
--- /dev/null
+++ b/lua/neo-tree/types/components.lua
@@ -0,0 +1,13 @@
+---@meta
+
+---@alias neotree.Renderer fun(config: table, node: table, state: table):(neotree.Render.Node|neotree.Render.Node[])
+
+---@class (exact) neotree.Render.Node
+---@field text string The text to display.
+---@field highlight string The highlight for the text.
+
+---@class (exact) neotree.Config.Component
+---@field enabled boolean?
+---@field highlight string?
+
+---@alias neotree.IconProvider fun(icon: table, node: table, state: table):(neotree.Render.Node|neotree.Render.Node[]|nil)
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
index e0d29d0df..07d1ace28 100644
--- a/lua/neo-tree/types/config.lua
+++ b/lua/neo-tree/types/config.lua
@@ -14,7 +14,7 @@
 
 ---@class neotree.Config.Source
 ---@field window neotree.Config.Source.Window
----@field renderers neotree.Config.Renderers[]?
+---@field renderers neotree.Component[]
 
 ---@class neotree.Config.Source.Window
 ---@field mappings neotree.Config.Window.Mappings
@@ -80,71 +80,6 @@
 ---@field mapping_options neotree.Config.MappingOptions
 ---@field mappings neotree.Config.Mapping[]
 
----@alias neotree.Config.Cwd "tab"|"window"|"global"
-
----@class neotree.Config.Filesystem.CwdTarget
----@field sidebar neotree.Config.Cwd
----@field current neotree.Config.Cwd
-
----@class neotree.Config.Filesystem.FilteredItems
----@field visible boolean
----@field force_visible_in_empty_folder boolean
----@field show_hidden_count boolean
----@field hide_dotfiles boolean
----@field hide_gitignored boolean
----@field hide_hidden boolean
----@field hide_by_name string[]
----@field hide_by_pattern string[]
----@field always_show string[]
----@field always_show_by_pattern string[]
----@field never_show string[]
----@field never_show_by_pattern string[]
-
----@alias neotree.Config.Filesystem.FindArgsHandler fun(cmd:string, path:string, search_term:string, args:string[]):string[]
-
----@class neotree.Config.Filesystem.FollowCurrentFile
----@field enabled boolean
----@field leave_dirs_open boolean
-
----@alias neotree.Config.HijackNetrwBehavior
----|"open_default" # opening a directory opens neo-tree with the default window.position.
----|"open_current" # opening a directory opens neo-tree within the current window.
----|"disabled" # opening a directory opens neo-tree within the current window.
-
----@class neotree.Config.Filesystem : neotree.Config.Source
----@field async_directory_scan "auto"|"always"|"never"
----@field bind_to_cwd boolean
----@field cwd_target neotree.Config.Filesystem.CwdTarget
----@field check_gitignore_in_search boolean
----@field filtered_items neotree.Config.Filesystem.FilteredItems
----@field find_by_full_path_words boolean
----@field find_command string?
----@field find_args table<string, string[]>|neotree.Config.Filesystem.FindArgsHandler|nil
----@field group_empty_dirs boolean
----@field search_limit integer
----@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
----@field hijack_netrw_behavior neotree.Config.HijackNetrwBehavior
----@field use_libuv_file_watcher boolean
-
----@class neotree.Config.Buffers : neotree.Config.Source
----@field bind_to_cwd boolean
----@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
----@field group_empty_dirs boolean
----@field show_unloaded boolean
----@field terminals_first boolean
-
----@class neotree.Config.GitStatus : neotree.Config.Source
-
----@class neotree.Config.LspKindDisplay
----@field icon string
----@field hl string
-
----@class neotree.Config.DocumentSymbols : neotree.Config.Source
----@field follow_cursor boolean
----@field client_filters neotree.lsp.ClientFilter
----@field custom_kinds table<integer, string>
----@field kinds table<string, neotree.Config.LspKindDisplay>
-
 ---@class neotree.Config.EventHandler.HandlerResult
 ---@field handled boolean
 
diff --git a/lua/neo-tree/types/config/buffers.lua b/lua/neo-tree/types/config/buffers.lua
new file mode 100644
index 000000000..946840434
--- /dev/null
+++ b/lua/neo-tree/types/config/buffers.lua
@@ -0,0 +1,9 @@
+---@meta
+
+---@class neotree.Config.Buffers : neotree.Config.Source
+---@field bind_to_cwd boolean
+---@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
+---@field group_empty_dirs boolean
+---@field show_unloaded boolean
+---@field terminals_first boolean
+---@field renderers (neotree.Component.Buffers|neotree.Component.Common)[]
diff --git a/lua/neo-tree/types/config/document_symbols.lua b/lua/neo-tree/types/config/document_symbols.lua
new file mode 100644
index 000000000..823f39c58
--- /dev/null
+++ b/lua/neo-tree/types/config/document_symbols.lua
@@ -0,0 +1,12 @@
+---@meta
+
+---@class neotree.Config.LspKindDisplay
+---@field icon string
+---@field hl string
+
+---@class neotree.Config.DocumentSymbols : neotree.Config.Source
+---@field follow_cursor boolean
+---@field client_filters neotree.lsp.ClientFilter
+---@field custom_kinds table<integer, string>
+---@field kinds table<string, neotree.Config.LspKindDisplay>
+---@field renderers (neotree.Component.DocumentSymbols|neotree.Component.Common)[]
diff --git a/lua/neo-tree/types/config/filesystem.lua b/lua/neo-tree/types/config/filesystem.lua
new file mode 100644
index 000000000..2d02513eb
--- /dev/null
+++ b/lua/neo-tree/types/config/filesystem.lua
@@ -0,0 +1,48 @@
+---@meta
+
+---@alias neotree.Config.Cwd "tab"|"window"|"global"
+
+---@class neotree.Config.Filesystem.CwdTarget
+---@field sidebar neotree.Config.Cwd
+---@field current neotree.Config.Cwd
+
+---@class neotree.Config.Filesystem.FilteredItems
+---@field visible boolean
+---@field force_visible_in_empty_folder boolean
+---@field show_hidden_count boolean
+---@field hide_dotfiles boolean
+---@field hide_gitignored boolean
+---@field hide_hidden boolean
+---@field hide_by_name string[]
+---@field hide_by_pattern string[]
+---@field always_show string[]
+---@field always_show_by_pattern string[]
+---@field never_show string[]
+---@field never_show_by_pattern string[]
+
+---@alias neotree.Config.Filesystem.FindArgsHandler fun(cmd:string, path:string, search_term:string, args:string[]):string[]
+
+---@class neotree.Config.Filesystem.FollowCurrentFile
+---@field enabled boolean
+---@field leave_dirs_open boolean
+
+---@alias neotree.Config.HijackNetrwBehavior
+---|"open_default" # opening a directory opens neo-tree with the default window.position.
+---|"open_current" # opening a directory opens neo-tree within the current window.
+---|"disabled" # opening a directory opens neo-tree within the current window.
+
+---@class neotree.Config.Filesystem : neotree.Config.Source
+---@field async_directory_scan "auto"|"always"|"never"
+---@field bind_to_cwd boolean
+---@field cwd_target neotree.Config.Filesystem.CwdTarget
+---@field check_gitignore_in_search boolean
+---@field filtered_items neotree.Config.Filesystem.FilteredItems
+---@field find_by_full_path_words boolean
+---@field find_command string?
+---@field find_args table<string, string[]>|neotree.Config.Filesystem.FindArgsHandler|nil
+---@field group_empty_dirs boolean
+---@field search_limit integer
+---@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
+---@field hijack_netrw_behavior neotree.Config.HijackNetrwBehavior
+---@field use_libuv_file_watcher boolean
+---@field renderers (neotree.Component.Filesystem|neotree.Component.Common)[]
diff --git a/lua/neo-tree/types/config/git_status.lua b/lua/neo-tree/types/config/git_status.lua
new file mode 100644
index 000000000..8f5845b61
--- /dev/null
+++ b/lua/neo-tree/types/config/git_status.lua
@@ -0,0 +1,4 @@
+---@meta
+
+---@class neotree.Config.GitStatus : neotree.Config.Source
+---@field renderers (neotree.Component.GitStatus|neotree.Component.Common)[]
diff --git a/lua/neo-tree/types/events.lua b/lua/neo-tree/types/events.lua
new file mode 100644
index 000000000..52799c9ff
--- /dev/null
+++ b/lua/neo-tree/types/events.lua
@@ -0,0 +1,50 @@
+---@meta
+
+---@enum neotree.Event
+local _ = {
+  AFTER_RENDER = "after_render",
+  BEFORE_FILE_ADD = "before_file_add",
+  BEFORE_FILE_DELETE = "before_file_delete",
+  BEFORE_FILE_MOVE = "before_file_move",
+  BEFORE_FILE_RENAME = "before_file_rename",
+  BEFORE_RENDER = "before_render",
+  FILE_ADDED = "file_added",
+  FILE_DELETED = "file_deleted",
+  FILE_MOVED = "file_moved",
+  FILE_OPENED = "file_opened",
+  FILE_OPEN_REQUESTED = "file_open_requested",
+  FILE_RENAMED = "file_renamed",
+  FS_EVENT = "fs_event",
+  GIT_EVENT = "git_event",
+  GIT_STATUS_CHANGED = "git_status_changed",
+  STATE_CREATED = "state_created",
+  NEO_TREE_BUFFER_ENTER = "neo_tree_buffer_enter",
+  NEO_TREE_BUFFER_LEAVE = "neo_tree_buffer_leave",
+  NEO_TREE_LSP_UPDATE = "neo_tree_lsp_update",
+  NEO_TREE_POPUP_BUFFER_ENTER = "neo_tree_popup_buffer_enter",
+  NEO_TREE_POPUP_BUFFER_LEAVE = "neo_tree_popup_buffer_leave",
+  NEO_TREE_POPUP_INPUT_READY = "neo_tree_popup_input_ready",
+  NEO_TREE_WINDOW_AFTER_CLOSE = "neo_tree_window_after_close",
+  NEO_TREE_WINDOW_AFTER_OPEN = "neo_tree_window_after_open",
+  NEO_TREE_WINDOW_BEFORE_CLOSE = "neo_tree_window_before_close",
+  NEO_TREE_WINDOW_BEFORE_OPEN = "neo_tree_window_before_open",
+  VIM_AFTER_SESSION_LOAD = "vim_after_session_load",
+  VIM_BUFFER_ADDED = "vim_buffer_added",
+  VIM_BUFFER_CHANGED = "vim_buffer_changed",
+  VIM_BUFFER_DELETED = "vim_buffer_deleted",
+  VIM_BUFFER_ENTER = "vim_buffer_enter",
+  VIM_BUFFER_MODIFIED_SET = "vim_buffer_modified_set",
+  VIM_COLORSCHEME = "vim_colorscheme",
+  VIM_CURSOR_MOVED = "vim_cursor_moved",
+  VIM_DIAGNOSTIC_CHANGED = "vim_diagnostic_changed",
+  VIM_DIR_CHANGED = "vim_dir_changed",
+  VIM_INSERT_LEAVE = "vim_insert_leave",
+  VIM_LEAVE = "vim_leave",
+  VIM_LSP_REQUEST = "vim_lsp_request",
+  VIM_RESIZED = "vim_resized",
+  VIM_TAB_CLOSED = "vim_tab_closed",
+  VIM_TERMINAL_ENTER = "vim_terminal_enter",
+  VIM_TEXT_CHANGED_NORMAL = "vim_text_changed_normal",
+  VIM_WIN_CLOSED = "vim_win_closed",
+  VIM_WIN_ENTER = "vim_win_enter",
+}

From 9f1e223d3e0a50c58ca188dcd68d530a7abad047 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Mon, 3 Mar 2025 11:48:20 -0800
Subject: [PATCH 29/36] simplify component types

---
 lua/neo-tree/sources/buffers/components.lua   |   6 +-
 lua/neo-tree/sources/common/components.lua    | 123 ++++++++----------
 lua/neo-tree/sources/common/container.lua     |  13 +-
 .../sources/document_symbols/components.lua   |  26 ++--
 .../sources/filesystem/components.lua         |  10 +-
 .../sources/git_status/components.lua         |  12 +-
 lua/neo-tree/types/components.lua             |   3 +-
 lua/neo-tree/types/config.lua                 |  24 ++--
 lua/neo-tree/types/config/buffers.lua         |   4 +-
 .../types/config/document_symbols.lua         |   6 +-
 lua/neo-tree/types/config/filesystem.lua      |   4 +-
 lua/neo-tree/types/config/git_status.lua      |   4 +-
 12 files changed, 102 insertions(+), 133 deletions(-)

diff --git a/lua/neo-tree/sources/buffers/components.lua b/lua/neo-tree/sources/buffers/components.lua
index 638cb4afe..8a6572959 100644
--- a/lua/neo-tree/sources/buffers/components.lua
+++ b/lua/neo-tree/sources/buffers/components.lua
@@ -20,13 +20,13 @@ local utils = require("neo-tree.utils")
 ---@class neotree.Component.Buffers
 ---@field [1] neotree.Component.Buffers._Key|neotree.Component.Common._Key
 
----@type table<neotree.Component.Buffers._Key, neotree.Component.Renderer>
+---@type table<neotree.Component.Buffers._Key, neotree.Renderer>
 local M = {}
 
----@class (exact) neotree.Component.Buffers.Name : neotree.Config.Component.Common.Name
+---@class (exact) neotree.Component.Buffers.Name : neotree.Component.Common.Name
 ---@field [1] "name"
 
----@param config neotree.Config.Component.Common.Name
+---@param config neotree.Component.Buffers.Name
 M.name = function(config, node, state)
   local highlight = config.highlight or highlights.FILE_NAME_OPENED
   local name = node.name
diff --git a/lua/neo-tree/sources/common/components.lua b/lua/neo-tree/sources/common/components.lua
index 49343c8f9..cb220508d 100644
--- a/lua/neo-tree/sources/common/components.lua
+++ b/lua/neo-tree/sources/common/components.lua
@@ -37,7 +37,7 @@ local log = require("neo-tree.log")
 ---@class neotree.Component.Common Use the neotree.Component.Common.* types to get more specific types.
 ---@field [1] neotree.Component.Common._Key
 
----@type table<neotree.Component.Common._Key, neotree.Component.Renderer>
+---@type table<neotree.Component.Common._Key, neotree.Renderer>
 local M = {}
 
 local make_two_char = function(symbol)
@@ -48,15 +48,13 @@ local make_two_char = function(symbol)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.Bufnr : neotree.Config.Component
-
----@class (exact) neotree.Component.Common.Bufnr : neotree.Config.Component.Common.Bufnr
----@field [1] "bufnr"
+---@class (exact) neotree.Component.Common.Bufnr : neotree.Component
+---@field [1] "bufnr"?
 
 -- Config fields below:
 -- only works in the buffers component, but it's here so we don't have to defined
 -- multple renderers.
----@param config neotree.Config.Component.Common.Bufnr
+---@param config neotree.Component.Common.Bufnr
 M.bufnr = function(config, node, _)
   local highlight = config.highlight or highlights.BUFFER_NUMBER
   local bufnr = node.extra and node.extra.bufnr
@@ -69,12 +67,10 @@ M.bufnr = function(config, node, _)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.Clipboard : neotree.Config.Component
-
----@class (exact) neotree.Component.Common.Clipboard : neotree.Config.Component.Common.Clipboard
----@field [1] "clipboard"
+---@class (exact) neotree.Component.Common.Clipboard : neotree.Component
+---@field [1] "clipboard"?
 
----@param config neotree.Config.Component.Common.Clipboard
+---@param config neotree.Component.Common.Clipboard
 M.clipboard = function(config, node, state)
   local clipboard = state.clipboard or {}
   local clipboard_state = clipboard[node:get_id()]
@@ -87,14 +83,19 @@ M.clipboard = function(config, node, state)
   }
 end
 
-M.container = container.render
+---@class (exact) neotree.Component.Common.Container : neotree.Component
+---@field [1] "container"
+---@field left_padding integer?
+---@field right_padding integer?
+---@field enable_character_fade boolean?
+---@field content (neotree.Component|{zindex: number, align: "left"|"right"|nil})[]?
 
----@class (exact) neotree.Config.Component.Common.CurrentFilter : neotree.Config.Component
+M.container = container.render
 
----@class (exact) neotree.Component.Common.CurrentFilter : neotree.Config.Component.Common.CurrentFilter
+---@class (exact) neotree.Component.Common.CurrentFilter : neotree.Component
 ---@field [1] "current_filter"
 
----@param config neotree.Config.Component.Common.CurrentFilter
+---@param config neotree.Component.Common.CurrentFilter
 M.current_filter = function(config, node, _)
   local filter = node.search_pattern or ""
   if filter == "" then
@@ -155,16 +156,14 @@ local function get_defined_sign(severity)
   return defined
 end
 
----@class (exact) neotree.Config.Component.Common.Diagnostics : neotree.Config.Component
+---@class (exact) neotree.Component.Common.Diagnostics : neotree.Component
+---@field [1] "diagnostics"?
 ---@field errors_only boolean?
 ---@field hide_when_expanded boolean?
 ---@field symbols table<string, string>?
 ---@field highlights table<string, string>?
 
----@class (exact) neotree.Component.Common.Diagnostics : neotree.Config.Component.Common.Diagnostics
----@field [1] "diagnostics"
-
----@param config neotree.Config.Component.Common.Diagnostics
+---@param config neotree.Component.Common.Diagnostics
 M.diagnostics = function(config, node, state)
   local diag = state.diagnostics_lookup or {}
   local diag_state = utils.index_by_path(diag, node:get_id())
@@ -205,14 +204,12 @@ M.diagnostics = function(config, node, state)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.GitStatus : neotree.Config.Component
+---@class (exact) neotree.Component.Common.GitStatus : neotree.Component
+---@field [1] "git_status"?
 ---@field hide_when_expanded boolean?
 ---@field symbols table<string, string>?
 
----@class (exact) neotree.Component.Common.GitStatus : neotree.Config.Component.Common.GitStatus
----@field [1] "git_status"
-
----@param config neotree.Config.Component.Common.GitStatus
+---@param config neotree.Component.Common.GitStatus
 M.git_status = function(config, node, state)
   local git_status_lookup = state.git_status_lookup
   if config.hide_when_expanded and node.type == "directory" and node:is_expanded() then
@@ -355,7 +352,8 @@ M.filtered_by = function(_, node, _)
   return result
 end
 
----@class (exact) neotree.Config.Component.Common.Icon : neotree.Config.Component
+---@class (exact) neotree.Component.Common.Icon : neotree.Component
+---@field [1] "icon"
 ---@field default string The default icon for a node.
 ---@field folder_empty string The string to display to represent an empty folder.
 ---@field folder_empty_open string The icon to display to represent an empty but open folder.
@@ -363,10 +361,7 @@ end
 ---@field folder_closed string The icon to display for a closed folder.
 ---@field provider neotree.IconProvider?
 
----@class (exact) neotree.Component.Common.Icon : neotree.Config.Component.Common.Icon
----@field [1] "icon"
-
----@param config neotree.Config.Component.Common.Icon
+---@param config neotree.Component.Common.Icon
 M.icon = function(config, node, state)
   -- calculate default icon
   local icon =
@@ -395,13 +390,11 @@ M.icon = function(config, node, state)
   return icon
 end
 
----@class (exact) neotree.Config.Component.Common.Modified : neotree.Config.Component
+---@class (exact) neotree.Component.Common.Modified : neotree.Component
+---@field [1] "modified"?
 ---@field symbol string?
 
----@class (exact) neotree.Component.Common.Modified : neotree.Config.Component.Common.Modified
----@field [1] "modified"
-
----@param config neotree.Config.Component.Common.Modified
+---@param config neotree.Component.Common.Modified
 M.modified = function(config, node, state)
   local opened_buffers = state.opened_buffers or {}
   local buf_info = utils.index_by_path(opened_buffers, node.path)
@@ -416,16 +409,14 @@ M.modified = function(config, node, state)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.Name : neotree.Config.Component
+---@class (exact) neotree.Component.Common.Name : neotree.Component
+---@field [1] "name"?
 ---@field trailing_slash boolean?
 ---@field use_git_status_colors boolean?
 ---@field highlight_opened_files boolean|"all"?
 ---@field right_padding integer?
 
----@class (exact) neotree.Component.Common.Name : neotree.Config.Component.Common.Name
----@field [1] "name"
-
----@param config neotree.Config.Component.Common.Name
+---@param config neotree.Component.Common.Name
 M.name = function(config, node, state)
   local highlight = config.highlight or highlights.FILE_NAME
   local text = node.name
@@ -478,7 +469,8 @@ M.name = function(config, node, state)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.Indent : neotree.Config.Component
+---@class (exact) neotree.Component.Common.Indent : neotree.Component
+---@field [1] "indent"?
 ---@field expander_collapsed string?
 ---@field expander_expanded string?
 ---@field expander_highlight string?
@@ -489,10 +481,7 @@ end
 ---@field with_expanders boolean?
 ---@field with_markers boolean?
 
----@class (exact) neotree.Component.Common.Indent : neotree.Config.Component.Common.Indent
----@field [1] "indent"
-
----@param config neotree.Config.Component.Common.Indent
+---@param config neotree.Component.Common.Indent
 M.indent = function(config, node, state)
   if not state.skip_marker_at_level then
     state.skip_marker_at_level = {}
@@ -588,13 +577,11 @@ local get_header = function(state, label, size)
   return vim.fn.printf("%" .. size .. "s  ", truncate_string(label, size))
 end
 
----@class (exact) neotree.Config.Component.Common.FileSize : neotree.Config.Component
+---@class (exact) neotree.Component.Common.FileSize : neotree.Component
+---@field [1] "file_size"?
 ---@field width integer?
 
----@class (exact) neotree.Component.Common.FileSize : neotree.Config.Component.Common.FileSize
----@field [1] "file_size"
-
----@param config neotree.Config.Component.Common.FileSize
+---@param config neotree.Component.Common.FileSize
 M.file_size = function(config, node, state)
   -- Root node gets column labels
   if node:get_depth() == 1 then
@@ -622,11 +609,11 @@ M.file_size = function(config, node, state)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.Time : neotree.Config.Component
+---@class (exact) neotree.Component.Common._Time : neotree.Component
 ---@field format neotree.DateFormat
 ---@field width integer?
 
----@param config neotree.Config.Component.Common.Time
+---@param config neotree.Component.Common._Time
 local file_time = function(config, node, state, stat_field)
   -- Root node gets column labels
   if node:get_depth() == 1 then
@@ -653,33 +640,27 @@ local file_time = function(config, node, state, stat_field)
   }
 end
 
----@class (exact) neotree.Config.Component.Common.LastModified : neotree.Config.Component.Common.Time
+---@class (exact) neotree.Component.Common.LastModified : neotree.Component.Common._Time
+---@field [1] "last_modified"?
 
----@class (exact) neotree.Component.Common.LastModified : neotree.Config.Component.Common.LastModified
----@field [1] "last_modified"
-
----@param config neotree.Config.Component.Common.Time
+---@param config neotree.Component.Common.LastModified
 M.last_modified = function(config, node, state)
   return file_time(config, node, state, "mtime")
 end
 
----@class (exact) neotree.Config.Component.Common.Created : neotree.Config.Component.Common.Time
-
----@class (exact) neotree.Component.Common.Created : neotree.Config.Component.Common.Created
----@field [1] "created"
+---@class (exact) neotree.Component.Common.Created : neotree.Component.Common._Time
+---@field [1] "created"?
 
----@param config neotree.Config.Component.Common.Time
+---@param config neotree.Component.Common.Created
 M.created = function(config, node, state)
   return file_time(config, node, state, "birthtime")
 end
 
----@class (exact) neotree.Config.Component.Common.SymlinkTarget : neotree.Config.Component
+---@class (exact) neotree.Component.Common.SymlinkTarget : neotree.Component
+---@field [1] "symlink_target"?
 ---@field text_format string
 
----@class (exact) neotree.Component.Common.SymlinkTarget : neotree.Config.Component.Common.SymlinkTarget
----@field [1] "symlink_target"
-
----@param config neotree.Config.Component.Common.SymlinkTarget
+---@param config neotree.Component.Common.SymlinkTarget
 M.symlink_target = function(config, node, _)
   if node.is_link then
     return {
@@ -691,13 +672,11 @@ M.symlink_target = function(config, node, _)
   end
 end
 
----@class (exact) neotree.Config.Component.Common.Type : neotree.Config.Component
+---@class (exact) neotree.Component.Common.Type : neotree.Component
+---@field [1] "type"?
 ---@field width integer?
 
----@class (exact) neotree.Component.Common.Type : neotree.Config.Component.Common.Type
----@field [1] "type"
-
----@param config neotree.Config.Component.Common.Type
+---@param config neotree.Component.Common.Type
 M.type = function(config, node, state)
   local text = node.ext or node.type
   -- Root node gets column labels
diff --git a/lua/neo-tree/sources/common/container.lua b/lua/neo-tree/sources/common/container.lua
index 63614b467..74bfab707 100644
--- a/lua/neo-tree/sources/common/container.lua
+++ b/lua/neo-tree/sources/common/container.lua
@@ -307,18 +307,7 @@ local merge_content = function(context)
   context.wanted_width = math.max(wanted_width, context.wanted_width)
 end
 
----@class (exact) neotree.Config.Component.Common.Container
----@field left_padding integer?
----@field right_padding integer?
----@field enable_character_fade boolean?
----@field content neotree.Component[]?
-
----@alias neotree.Component table
-
----@class (exact) neotree.Component.Common.Container : neotree.Config.Component.Common.Container
----@field [1] "clipboard"
-
----@param config neotree.Config.Component.Common.Container
+---@param config neotree.Component.Common.Container
 M.render = function(config, node, state, available_width)
   local context = {
     wanted_width = 0,
diff --git a/lua/neo-tree/sources/document_symbols/components.lua b/lua/neo-tree/sources/document_symbols/components.lua
index 13b1eacd2..bfdcaf22f 100644
--- a/lua/neo-tree/sources/document_symbols/components.lua
+++ b/lua/neo-tree/sources/document_symbols/components.lua
@@ -21,16 +21,14 @@ local common = require("neo-tree.sources.common.components")
 ---@class neotree.Component.DocumentSymbols Use the neotree.Component.DocumentSymbols.* types to get more specific types.
 ---@field [1] neotree.Component.DocumentSymbols._Key|neotree.Component.Common._Key
 
----@type table<neotree.Component.DocumentSymbols._Key, neotree.Component.Renderer>
+---@type table<neotree.Component.DocumentSymbols._Key, neotree.Renderer>
 local M = {}
 
----@class (exact) neotree.Config.Component.DocumentSymbols.KindIcon : neotree.Config.Component
+---@class (exact) neotree.Component.DocumentSymbols.KindIcon : neotree.Component
+---@field [1] "kind_icon"?
 ---@field provider neotree.IconProvider?
 
----@class (exact) neotree.Component.DocumentSymbols.KindIcon : neotree.Config.Component.DocumentSymbols.KindIcon
----@field [1] "kind_icon"
-
----@param config neotree.Config.Component.DocumentSymbols.KindIcon
+---@param config neotree.Component.DocumentSymbols.KindIcon
 M.kind_icon = function(config, node, state)
   local icon = {
     text = node:get_depth() == 1 and "" or node.extra.kind.icon,
@@ -44,12 +42,10 @@ M.kind_icon = function(config, node, state)
   return icon
 end
 
----@class (exact) neotree.Config.Component.DocumentSymbols.KindName : neotree.Config.Component
-
----@class (exact) neotree.Component.DocumentSymbols.KindName : neotree.Config.Component.DocumentSymbols.KindName
----@field [1] "kind_name"
+---@class (exact) neotree.Component.DocumentSymbols.KindName : neotree.Component
+---@field [1] "kind_name"?
 
----@param config neotree.Config.Component.DocumentSymbols.KindName
+---@param config neotree.Component.DocumentSymbols.KindName
 M.kind_name = function(config, node, state)
   return {
     text = node:get_depth() == 1 and "" or node.extra.kind.name,
@@ -57,12 +53,10 @@ M.kind_name = function(config, node, state)
   }
 end
 
----@class (exact) neotree.Config.Component.DocumentSymbols.Name : neotree.Config.Component
-
----@class (exact) neotree.Component.DocumentSymbols.Name : neotree.Config.Component.DocumentSymbols.Name
----@field [1] "name"
+---@class (exact) neotree.Component.DocumentSymbols.Name : neotree.Component.Common.Name
+---@field [1] "name"?
 
----@param config neotree.Config.Component.DocumentSymbols.Name
+---@param config neotree.Component.DocumentSymbols.Name
 M.name = function(config, node, state)
   return {
     text = node.name,
diff --git a/lua/neo-tree/sources/filesystem/components.lua b/lua/neo-tree/sources/filesystem/components.lua
index ebe63c4db..66a6cf125 100644
--- a/lua/neo-tree/sources/filesystem/components.lua
+++ b/lua/neo-tree/sources/filesystem/components.lua
@@ -20,15 +20,13 @@ local utils = require("neo-tree.utils")
 ---@class neotree.Component.Filesystem
 ---@field [1] neotree.Component.Filesystem._Key|neotree.Component.Common._Key
 
----@type table<neotree.Component.Filesystem._Key, neotree.Component.Renderer>
+---@type table<neotree.Component.Filesystem._Key, neotree.Renderer>
 local M = {}
 
----@class (exact) neotree.Config.Component.Filesystem.CurrentFilter : neotree.Config.Component
+---@class (exact) neotree.Component.Filesystem.CurrentFilter : neotree.Component.Common.CurrentFilter
+---@field [1] "current_filter"?
 
----@class (exact) neotree.Component.Filesystem.CurrentFilter : neotree.Config.Component.Filesystem.CurrentFilter
----@field [1] "current_filter"
-
----@param config neotree.Config.Component.Filesystem.CurrentFilter
+---@param config neotree.Component.Filesystem.CurrentFilter
 M.current_filter = function(config, node, state)
   local filter = node.search_pattern or ""
   if filter == "" then
diff --git a/lua/neo-tree/sources/git_status/components.lua b/lua/neo-tree/sources/git_status/components.lua
index 01a72e7a1..4565ad7c8 100644
--- a/lua/neo-tree/sources/git_status/components.lua
+++ b/lua/neo-tree/sources/git_status/components.lua
@@ -13,24 +13,20 @@
 local highlights = require("neo-tree.ui.highlights")
 local common = require("neo-tree.sources.common.components")
 
-local M = {}
-
 ---@alias neotree.Component.GitStatus._Key
 ---|"name"
 
 ---@class neotree.Component.GitStatus
 ---@field [1] neotree.Component.GitStatus._Key|neotree.Component.Common._Key
 
----@type table<neotree.Component.GitStatus._Key, neotree.Component.Renderer>
+---@type table<neotree.Component.GitStatus._Key, neotree.Renderer>
 local M = {}
 
----@class (exact) neotree.Config.Component.GitStatus.Name : neotree.Config.Component
+---@class (exact) neotree.Component.GitStatus.Name : neotree.Component.Common.Name
+---@field [1] "current_filter"?
 ---@field use_git_status_colors boolean?
 
----@class (exact) neotree.Component.GitStatus.Name: neotree.Config.Component.GitStatus.Name
----@field [1] "current_filter"
-
----@param config neotree.Config.Component.GitStatus.Name
+---@param config neotree.Component.GitStatus.Name
 M.name = function(config, node, state)
   local highlight = config.highlight or highlights.FILE_NAME_OPENED
   local name = node.name
diff --git a/lua/neo-tree/types/components.lua b/lua/neo-tree/types/components.lua
index 5688c94b1..cbf66d371 100644
--- a/lua/neo-tree/types/components.lua
+++ b/lua/neo-tree/types/components.lua
@@ -6,7 +6,8 @@
 ---@field text string The text to display.
 ---@field highlight string The highlight for the text.
 
----@class (exact) neotree.Config.Component
+---@class (exact) neotree.Component
+---@field [1] string?
 ---@field enabled boolean?
 ---@field highlight string?
 
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
index 07d1ace28..ce94db874 100644
--- a/lua/neo-tree/types/config.lua
+++ b/lua/neo-tree/types/config.lua
@@ -94,17 +94,17 @@
 ---@field terminal neotree.Component.Common[]?
 
 ---@class neotree.Config.ComponentDefaults
----@field container neotree.Config.Component.Common.Container
----@field indent neotree.Config.Component.Common.Indent
----@field icon neotree.Config.Component.Common.Icon
----@field modified neotree.Config.Component.Common.Modified
----@field name neotree.Config.Component.Common.Name
----@field git_status neotree.Config.Component.Common.GitStatus
----@field file_size neotree.Config.Component.Common.FileSize
----@field type neotree.Config.Component.Common.Type
----@field last_modified neotree.Config.Component.Common.LastModified
----@field created neotree.Config.Component.Common.Created
----@field symlink_target neotree.Config.Component.Common.SymlinkTarget
+---@field container neotree.Component.Common.Container
+---@field indent neotree.Component.Common.Indent
+---@field icon neotree.Component.Common.Icon
+---@field modified neotree.Component.Common.Modified
+---@field name neotree.Component.Common.Name
+---@field git_status neotree.Component.Common.GitStatus
+---@field file_size neotree.Component.Common.FileSize
+---@field type neotree.Component.Common.Type
+---@field last_modified neotree.Component.Common.LastModified
+---@field created neotree.Component.Common.Created
+---@field symlink_target neotree.Component.Common.SymlinkTarget
 
 ---@alias neotree.Config.BorderStyle "NC"|"none"|"rounded"|"shadow"|"single"|"solid"|nil
 
@@ -142,9 +142,11 @@
 ---@field nesting_rules neotree.FileNesting.Rule[]
 ---@field commands table<string, fun()>?
 ---@field window neotree.Config.Window?
+---
 ---@field filesystem neotree.Config.Filesystem?
 ---@field buffers neotree.Config.Buffers?
 ---@field git_status neotree.Config.GitStatus?
+---@field document_symbols neotree.Config.DocumentSymbols?
 
 ---@class neotree.Config._Full : neotree.Config
 ---@field prior_windows table<string, integer[]>?
diff --git a/lua/neo-tree/types/config/buffers.lua b/lua/neo-tree/types/config/buffers.lua
index 946840434..77e19c234 100644
--- a/lua/neo-tree/types/config/buffers.lua
+++ b/lua/neo-tree/types/config/buffers.lua
@@ -1,9 +1,11 @@
 ---@meta
 
+---@class neotree.Config.Buffers.Renderers : neotree.Config.Renderers
+
 ---@class neotree.Config.Buffers : neotree.Config.Source
 ---@field bind_to_cwd boolean
 ---@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
 ---@field group_empty_dirs boolean
 ---@field show_unloaded boolean
 ---@field terminals_first boolean
----@field renderers (neotree.Component.Buffers|neotree.Component.Common)[]
+---@field renderers neotree.Config.Buffers.Renderers?
diff --git a/lua/neo-tree/types/config/document_symbols.lua b/lua/neo-tree/types/config/document_symbols.lua
index 823f39c58..63ea3203d 100644
--- a/lua/neo-tree/types/config/document_symbols.lua
+++ b/lua/neo-tree/types/config/document_symbols.lua
@@ -4,9 +4,13 @@
 ---@field icon string
 ---@field hl string
 
+---@class neotree.Config.DocumentSymbols.Renderers : neotree.Config.Renderers
+---@field root neotree.Component.DocumentSymbols[]
+---@field symbol neotree.Component.DocumentSymbols[]
+
 ---@class neotree.Config.DocumentSymbols : neotree.Config.Source
 ---@field follow_cursor boolean
 ---@field client_filters neotree.lsp.ClientFilter
 ---@field custom_kinds table<integer, string>
 ---@field kinds table<string, neotree.Config.LspKindDisplay>
----@field renderers (neotree.Component.DocumentSymbols|neotree.Component.Common)[]
+---@field renderers neotree.Config.DocumentSymbols.Renderers?
diff --git a/lua/neo-tree/types/config/filesystem.lua b/lua/neo-tree/types/config/filesystem.lua
index 2d02513eb..168f99817 100644
--- a/lua/neo-tree/types/config/filesystem.lua
+++ b/lua/neo-tree/types/config/filesystem.lua
@@ -31,6 +31,8 @@
 ---|"open_current" # opening a directory opens neo-tree within the current window.
 ---|"disabled" # opening a directory opens neo-tree within the current window.
 
+---@class neotree.Config.Filesystem.Renderers : neotree.Config.Renderers
+
 ---@class neotree.Config.Filesystem : neotree.Config.Source
 ---@field async_directory_scan "auto"|"always"|"never"
 ---@field bind_to_cwd boolean
@@ -45,4 +47,4 @@
 ---@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
 ---@field hijack_netrw_behavior neotree.Config.HijackNetrwBehavior
 ---@field use_libuv_file_watcher boolean
----@field renderers (neotree.Component.Filesystem|neotree.Component.Common)[]
+---@field renderers neotree.Config.Filesystem.Renderers?
diff --git a/lua/neo-tree/types/config/git_status.lua b/lua/neo-tree/types/config/git_status.lua
index 8f5845b61..4fa2d8724 100644
--- a/lua/neo-tree/types/config/git_status.lua
+++ b/lua/neo-tree/types/config/git_status.lua
@@ -1,4 +1,6 @@
 ---@meta
 
+---@class neotree.Config.GitStatus.Renderers : neotree.Config.Renderers
+
 ---@class neotree.Config.GitStatus : neotree.Config.Source
----@field renderers (neotree.Component.GitStatus|neotree.Component.Common)[]
+---@field renderers neotree.Config.GitStatus.Renderers?

From b3fc6ced1192957dddbc0e8b88846b52722e3a32 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Tue, 4 Mar 2025 13:06:32 -0800
Subject: [PATCH 30/36] fix component types

---
 lua/neo-tree/sources/buffers/components.lua          | 1 -
 lua/neo-tree/sources/common/components.lua           | 6 +++---
 lua/neo-tree/sources/document_symbols/components.lua | 1 -
 lua/neo-tree/sources/filesystem/components.lua       | 1 -
 4 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/lua/neo-tree/sources/buffers/components.lua b/lua/neo-tree/sources/buffers/components.lua
index 8a6572959..fba3856a6 100644
--- a/lua/neo-tree/sources/buffers/components.lua
+++ b/lua/neo-tree/sources/buffers/components.lua
@@ -24,7 +24,6 @@ local utils = require("neo-tree.utils")
 local M = {}
 
 ---@class (exact) neotree.Component.Buffers.Name : neotree.Component.Common.Name
----@field [1] "name"
 
 ---@param config neotree.Component.Buffers.Name
 M.name = function(config, node, state)
diff --git a/lua/neo-tree/sources/common/components.lua b/lua/neo-tree/sources/common/components.lua
index cb220508d..1e69ca4dc 100644
--- a/lua/neo-tree/sources/common/components.lua
+++ b/lua/neo-tree/sources/common/components.lua
@@ -84,7 +84,7 @@ M.clipboard = function(config, node, state)
 end
 
 ---@class (exact) neotree.Component.Common.Container : neotree.Component
----@field [1] "container"
+---@field [1] "container"?
 ---@field left_padding integer?
 ---@field right_padding integer?
 ---@field enable_character_fade boolean?
@@ -315,7 +315,7 @@ M.git_status = function(config, node, state)
 end
 
 ---@class neotree.Component.Common.FilteredBy
----@field [1] "filtered_by"
+---@field [1] "filtered_by"?
 
 M.filtered_by = function(_, node, _)
   local result = {}
@@ -353,7 +353,7 @@ M.filtered_by = function(_, node, _)
 end
 
 ---@class (exact) neotree.Component.Common.Icon : neotree.Component
----@field [1] "icon"
+---@field [1] "icon"?
 ---@field default string The default icon for a node.
 ---@field folder_empty string The string to display to represent an empty folder.
 ---@field folder_empty_open string The icon to display to represent an empty but open folder.
diff --git a/lua/neo-tree/sources/document_symbols/components.lua b/lua/neo-tree/sources/document_symbols/components.lua
index bfdcaf22f..fed89da67 100644
--- a/lua/neo-tree/sources/document_symbols/components.lua
+++ b/lua/neo-tree/sources/document_symbols/components.lua
@@ -54,7 +54,6 @@ M.kind_name = function(config, node, state)
 end
 
 ---@class (exact) neotree.Component.DocumentSymbols.Name : neotree.Component.Common.Name
----@field [1] "name"?
 
 ---@param config neotree.Component.DocumentSymbols.Name
 M.name = function(config, node, state)
diff --git a/lua/neo-tree/sources/filesystem/components.lua b/lua/neo-tree/sources/filesystem/components.lua
index 66a6cf125..079f11ab6 100644
--- a/lua/neo-tree/sources/filesystem/components.lua
+++ b/lua/neo-tree/sources/filesystem/components.lua
@@ -24,7 +24,6 @@ local utils = require("neo-tree.utils")
 local M = {}
 
 ---@class (exact) neotree.Component.Filesystem.CurrentFilter : neotree.Component.Common.CurrentFilter
----@field [1] "current_filter"?
 
 ---@param config neotree.Component.Filesystem.CurrentFilter
 M.current_filter = function(config, node, state)

From 6d71a3a3d6536609caeee7d4b505992dd8309817 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Tue, 4 Mar 2025 13:31:56 -0800
Subject: [PATCH 31/36] make more fields optional

---
 lua/neo-tree/types/config.lua                 | 72 +++++++++----------
 lua/neo-tree/types/config/buffers.lua         | 10 +--
 .../types/config/document_symbols.lua         | 12 ++--
 lua/neo-tree/types/config/filesystem.lua      | 22 +++---
 4 files changed, 57 insertions(+), 59 deletions(-)

diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
index ce94db874..7a8cd4474 100644
--- a/lua/neo-tree/types/config.lua
+++ b/lua/neo-tree/types/config.lua
@@ -10,14 +10,12 @@
 ---@field noremap boolean?
 ---@field config table?
 
----@alias neotree.Config.Window.Mappings table<string, string|neotree.Config.Mapping>
-
 ---@class neotree.Config.Source
----@field window neotree.Config.Source.Window
----@field renderers neotree.Component[]
+---@field window neotree.Config.Source.Window?
+---@field renderers neotree.Component[]?
 
 ---@class neotree.Config.Source.Window
----@field mappings neotree.Config.Window.Mappings
+---@field mappings table<string, string|neotree.Config.Mapping>
 
 ---@class neotree.Config.SourceSelector.Item
 ---@field source string
@@ -36,10 +34,10 @@
 ---@field override neotree.Config.SourceSelector.Separator.Override
 
 ---@class neotree.Config.SourceSelector
----@field winbar boolean
----@field statusline boolean
----@field show_scrolled_off_parent_node boolean
----@field sources neotree.Config.SourceSelector.Item[]
+---@field winbar boolean?
+---@field statusline boolean?
+---@field show_scrolled_off_parent_node boolean?
+---@field sources neotree.Config.SourceSelector.Item[]?
 ---@field content_layout string? "start"|"end"|"center"
 ---@field tabs_layout string? "equal"|"start"|"end"|"center"|"focus"
 ---@field truncation_character string
@@ -48,17 +46,17 @@
 ---@field padding integer?
 ---@field separator neotree.Config.SourceSelector.Separator?
 ---@field separator_active neotree.Config.SourceSelector.Separator?
----@field show_separator_on_edge boolean
----@field highlight_tab string
----@field highlight_tab_active string
----@field highlight_background string
----@field highlight_separator string
----@field highlight_separator_active string
+---@field show_separator_on_edge boolean?
+---@field highlight_tab string?
+---@field highlight_tab_active string?
+---@field highlight_background string?
+---@field highlight_separator string?
+---@field highlight_separator_active string?
 
 ---@class neotree.Config.GitStatusAsync
----@field batch_size integer
----@field batch_delay integer
----@field max_lines integer
+---@field batch_size integer?
+---@field batch_delay integer?
+---@field max_lines integer?
 
 ---@class neotree.Config.Window.Size
 ---@field height string|number?
@@ -94,21 +92,21 @@
 ---@field terminal neotree.Component.Common[]?
 
 ---@class neotree.Config.ComponentDefaults
----@field container neotree.Component.Common.Container
----@field indent neotree.Component.Common.Indent
----@field icon neotree.Component.Common.Icon
----@field modified neotree.Component.Common.Modified
----@field name neotree.Component.Common.Name
----@field git_status neotree.Component.Common.GitStatus
----@field file_size neotree.Component.Common.FileSize
----@field type neotree.Component.Common.Type
----@field last_modified neotree.Component.Common.LastModified
----@field created neotree.Component.Common.Created
----@field symlink_target neotree.Component.Common.SymlinkTarget
-
----@alias neotree.Config.BorderStyle "NC"|"none"|"rounded"|"shadow"|"single"|"solid"|nil
-
----@class neotree.Config
+---@field container neotree.Component.Common.Container?
+---@field indent neotree.Component.Common.Indent?
+---@field icon neotree.Component.Common.Icon?
+---@field modified neotree.Component.Common.Modified?
+---@field name neotree.Component.Common.Name?
+---@field git_status neotree.Component.Common.GitStatus?
+---@field file_size neotree.Component.Common.FileSize?
+---@field type neotree.Component.Common.Type?
+---@field last_modified neotree.Component.Common.LastModified?
+---@field created neotree.Component.Common.Created?
+---@field symlink_target neotree.Component.Common.SymlinkTarget?
+
+---@alias neotree.Config.BorderStyle "NC"|"none"|"rounded"|"shadow"|"single"|"solid"
+
+---@class (exact) neotree.Config
 ---@field sources string[]?
 ---@field add_blank_line_at_top boolean?
 ---@field auto_clean_after_session_restore boolean?
@@ -125,12 +123,12 @@
 ---@field hide_root_node boolean?
 ---@field retain_hidden_root_indent boolean?
 ---@field log_level "trace"|"debug"|"info"|"warn"|"error"|"fatal"|nil
----@field log_to_file boolean?
+---@field log_to_file boolean|string?
 ---@field open_files_in_last_window boolean?
 ---@field open_files_do_not_replace_types string[]?
 ---@field open_files_using_relative_paths boolean?
----@field popup_border_style neotree.Config.BorderStyle
----@field resize_timer_interval integer?
+---@field popup_border_style neotree.Config.BorderStyle?
+---@field resize_timer_interval integer|-1?
 ---@field sort_case_insensitive boolean?
 ---@field sort_function fun(a: any, b: any)?
 ---@field use_popups_for_input boolean?
@@ -139,7 +137,7 @@
 ---@field event_handlers neotree.Event.Handler[]?
 ---@field default_component_configs neotree.Config.ComponentDefaults?
 ---@field renderers neotree.Config.Renderers?
----@field nesting_rules neotree.FileNesting.Rule[]
+---@field nesting_rules neotree.FileNesting.Rule[]?
 ---@field commands table<string, fun()>?
 ---@field window neotree.Config.Window?
 ---
diff --git a/lua/neo-tree/types/config/buffers.lua b/lua/neo-tree/types/config/buffers.lua
index 77e19c234..c5ed03dbd 100644
--- a/lua/neo-tree/types/config/buffers.lua
+++ b/lua/neo-tree/types/config/buffers.lua
@@ -3,9 +3,9 @@
 ---@class neotree.Config.Buffers.Renderers : neotree.Config.Renderers
 
 ---@class neotree.Config.Buffers : neotree.Config.Source
----@field bind_to_cwd boolean
----@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
----@field group_empty_dirs boolean
----@field show_unloaded boolean
----@field terminals_first boolean
+---@field bind_to_cwd boolean?
+---@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile?
+---@field group_empty_dirs boolean?
+---@field show_unloaded boolean?
+---@field terminals_first boolean?
 ---@field renderers neotree.Config.Buffers.Renderers?
diff --git a/lua/neo-tree/types/config/document_symbols.lua b/lua/neo-tree/types/config/document_symbols.lua
index 63ea3203d..961a2baaf 100644
--- a/lua/neo-tree/types/config/document_symbols.lua
+++ b/lua/neo-tree/types/config/document_symbols.lua
@@ -5,12 +5,12 @@
 ---@field hl string
 
 ---@class neotree.Config.DocumentSymbols.Renderers : neotree.Config.Renderers
----@field root neotree.Component.DocumentSymbols[]
----@field symbol neotree.Component.DocumentSymbols[]
+---@field root neotree.Component.DocumentSymbols[]?
+---@field symbol neotree.Component.DocumentSymbols[]?
 
 ---@class neotree.Config.DocumentSymbols : neotree.Config.Source
----@field follow_cursor boolean
----@field client_filters neotree.lsp.ClientFilter
----@field custom_kinds table<integer, string>
----@field kinds table<string, neotree.Config.LspKindDisplay>
+---@field follow_cursor boolean?
+---@field client_filters neotree.lsp.ClientFilter?
+---@field custom_kinds table<integer, string>?
+---@field kinds table<string, neotree.Config.LspKindDisplay>?
 ---@field renderers neotree.Config.DocumentSymbols.Renderers?
diff --git a/lua/neo-tree/types/config/filesystem.lua b/lua/neo-tree/types/config/filesystem.lua
index 168f99817..b71d7f0b5 100644
--- a/lua/neo-tree/types/config/filesystem.lua
+++ b/lua/neo-tree/types/config/filesystem.lua
@@ -34,17 +34,17 @@
 ---@class neotree.Config.Filesystem.Renderers : neotree.Config.Renderers
 
 ---@class neotree.Config.Filesystem : neotree.Config.Source
----@field async_directory_scan "auto"|"always"|"never"
----@field bind_to_cwd boolean
----@field cwd_target neotree.Config.Filesystem.CwdTarget
----@field check_gitignore_in_search boolean
----@field filtered_items neotree.Config.Filesystem.FilteredItems
----@field find_by_full_path_words boolean
+---@field async_directory_scan "auto"|"always"|"never"|nil
+---@field bind_to_cwd boolean?
+---@field cwd_target neotree.Config.Filesystem.CwdTarget?
+---@field check_gitignore_in_search boolean?
+---@field filtered_items neotree.Config.Filesystem.FilteredItems?
+---@field find_by_full_path_words boolean?
 ---@field find_command string?
 ---@field find_args table<string, string[]>|neotree.Config.Filesystem.FindArgsHandler|nil
----@field group_empty_dirs boolean
----@field search_limit integer
----@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile
----@field hijack_netrw_behavior neotree.Config.HijackNetrwBehavior
----@field use_libuv_file_watcher boolean
+---@field group_empty_dirs boolean?
+---@field search_limit integer?
+---@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile?
+---@field hijack_netrw_behavior neotree.Config.HijackNetrwBehavior?
+---@field use_libuv_file_watcher boolean?
 ---@field renderers neotree.Config.Filesystem.Renderers?

From 0d74570c0b2999c70f1069de43d7fec35fc109d9 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Wed, 5 Mar 2025 02:40:18 -0800
Subject: [PATCH 32/36] update types

---
 lua/neo-tree/events/queue.lua                 |  2 +-
 lua/neo-tree/types/config.lua                 | 48 +++++++++----------
 lua/neo-tree/types/config/buffers.lua         |  2 +-
 .../types/config/document_symbols.lua         |  2 +-
 lua/neo-tree/types/config/filesystem.lua      |  3 +-
 lua/neo-tree/types/config/git_status.lua      |  2 +-
 6 files changed, 30 insertions(+), 29 deletions(-)

diff --git a/lua/neo-tree/events/queue.lua b/lua/neo-tree/events/queue.lua
index 5b55363a2..4dc029b9c 100644
--- a/lua/neo-tree/events/queue.lua
+++ b/lua/neo-tree/events/queue.lua
@@ -7,7 +7,7 @@ local event_definitions = {}
 local M = {}
 
 ---@class neotree.Event.Handler
----@field event neotree.Event
+---@field event neotree.Event|string
 ---@field handler fun(...)
 ---@field id string?
 local a = {}
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
index 7a8cd4474..067d24a73 100644
--- a/lua/neo-tree/types/config.lua
+++ b/lua/neo-tree/types/config.lua
@@ -1,8 +1,8 @@
 ---@meta
 
 ---@class neotree.Config.MappingOptions
----@field noremap boolean
----@field nowait boolean
+---@field noremap boolean?
+---@field nowait boolean?
 
 ---@class neotree.Config.Mapping : neotree.Config.MappingOptions
 ---@field [1] string
@@ -15,12 +15,12 @@
 ---@field renderers neotree.Component[]?
 
 ---@class neotree.Config.Source.Window
----@field mappings table<string, string|neotree.Config.Mapping>
+---@field mappings table<string, string|neotree.Config.Mapping>?
 
 ---@class neotree.Config.SourceSelector.Item
----@field source string
----@field padding? integer|{left:integer,right:integer}
----@field separator? string|{left:string,right:string, override?:string}
+---@field source string?
+---@field padding integer|{left:integer,right:integer}?
+---@field separator string|{left:string,right:string, override?:string}?
 
 ---@alias neotree.Config.SourceSelector.Separator.Override
 ---|"right"   # When right and left separators meet, only show the right one.
@@ -29,9 +29,9 @@
 ---|nil       # Show both separators.
 
 ---@class neotree.Config.SourceSelector.Separator
----@field left string
----@field right string
----@field override neotree.Config.SourceSelector.Separator.Override
+---@field left string?
+---@field right string?
+---@field override neotree.Config.SourceSelector.Separator.Override?
 
 ---@class neotree.Config.SourceSelector
 ---@field winbar boolean?
@@ -63,27 +63,27 @@
 ---@field width string|number?
 
 ---@class neotree.Config.Window.Popup
----@field title fun(state:table):string
----@field size neotree.Config.Window.Size
----@field border neotree.Config.BorderStyle
+---@field title fun(state:table):string?
+---@field size neotree.Config.Window.Size?
+---@field border neotree.Config.BorderStyle?
 
 ---@class neotree.Config.Window
----@field position string
----@field width integer
----@field height integer
----@field auto_expand_width boolean
----@field popup neotree.Config.Window.Popup
----@field same_level boolean
----@field insert_as "child"|"sibling"
----@field mapping_options neotree.Config.MappingOptions
----@field mappings neotree.Config.Mapping[]
+---@field position string?
+---@field width integer?
+---@field height integer?
+---@field auto_expand_width boolean?
+---@field popup neotree.Config.Window.Popup?
+---@field same_level boolean?
+---@field insert_as "child"|"sibling"|nil
+---@field mapping_options neotree.Config.MappingOptions?
+---@field mappings neotree.Config.Mapping[]?
 
 ---@class neotree.Config.EventHandler.HandlerResult
----@field handled boolean
+---@field handled boolean?
 
 ---@class neotree.Config.EventHandler
 ---@field event string
----@field handler fun(table?):neotree.Config.EventHandler.HandlerResult?
+---@field handler fun(table?):(neotree.Config.EventHandler.HandlerResult?)
 
 ---@class neotree.Config.Renderers
 ---@field directory neotree.Component.Common[]?
@@ -146,5 +146,5 @@
 ---@field git_status neotree.Config.GitStatus?
 ---@field document_symbols neotree.Config.DocumentSymbols?
 
----@class neotree.Config._Full : neotree.Config
+---@class (exact) neotree.Config._Full : neotree.Config
 ---@field prior_windows table<string, integer[]>?
diff --git a/lua/neo-tree/types/config/buffers.lua b/lua/neo-tree/types/config/buffers.lua
index c5ed03dbd..9c34f1058 100644
--- a/lua/neo-tree/types/config/buffers.lua
+++ b/lua/neo-tree/types/config/buffers.lua
@@ -2,7 +2,7 @@
 
 ---@class neotree.Config.Buffers.Renderers : neotree.Config.Renderers
 
----@class neotree.Config.Buffers : neotree.Config.Source
+---@class (exact) neotree.Config.Buffers : neotree.Config.Source
 ---@field bind_to_cwd boolean?
 ---@field follow_current_file neotree.Config.Filesystem.FollowCurrentFile?
 ---@field group_empty_dirs boolean?
diff --git a/lua/neo-tree/types/config/document_symbols.lua b/lua/neo-tree/types/config/document_symbols.lua
index 961a2baaf..cd343d4b4 100644
--- a/lua/neo-tree/types/config/document_symbols.lua
+++ b/lua/neo-tree/types/config/document_symbols.lua
@@ -8,7 +8,7 @@
 ---@field root neotree.Component.DocumentSymbols[]?
 ---@field symbol neotree.Component.DocumentSymbols[]?
 
----@class neotree.Config.DocumentSymbols : neotree.Config.Source
+---@class (exact) neotree.Config.DocumentSymbols : neotree.Config.Source
 ---@field follow_cursor boolean?
 ---@field client_filters neotree.lsp.ClientFilter?
 ---@field custom_kinds table<integer, string>?
diff --git a/lua/neo-tree/types/config/filesystem.lua b/lua/neo-tree/types/config/filesystem.lua
index b71d7f0b5..4b999c032 100644
--- a/lua/neo-tree/types/config/filesystem.lua
+++ b/lua/neo-tree/types/config/filesystem.lua
@@ -33,8 +33,9 @@
 
 ---@class neotree.Config.Filesystem.Renderers : neotree.Config.Renderers
 
----@class neotree.Config.Filesystem : neotree.Config.Source
+---@class (exact) neotree.Config.Filesystem : neotree.Config.Source
 ---@field async_directory_scan "auto"|"always"|"never"|nil
+---@field scan_mode "shallow"|"deep"|nil
 ---@field bind_to_cwd boolean?
 ---@field cwd_target neotree.Config.Filesystem.CwdTarget?
 ---@field check_gitignore_in_search boolean?
diff --git a/lua/neo-tree/types/config/git_status.lua b/lua/neo-tree/types/config/git_status.lua
index 4fa2d8724..8a291aa2d 100644
--- a/lua/neo-tree/types/config/git_status.lua
+++ b/lua/neo-tree/types/config/git_status.lua
@@ -2,5 +2,5 @@
 
 ---@class neotree.Config.GitStatus.Renderers : neotree.Config.Renderers
 
----@class neotree.Config.GitStatus : neotree.Config.Source
+---@class (exact) neotree.Config.GitStatus : neotree.Config.Source
 ---@field renderers neotree.Config.GitStatus.Renderers?

From f7713f1c5d237b49301e999d55d4055c1ddd027c Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Wed, 5 Mar 2025 03:09:35 -0800
Subject: [PATCH 33/36] make all config optional

---
 lua/neo-tree/sources/common/filters/init.lua |  1 +
 lua/neo-tree/types/config/filesystem.lua     | 36 +++++++++++---------
 2 files changed, 21 insertions(+), 16 deletions(-)

diff --git a/lua/neo-tree/sources/common/filters/init.lua b/lua/neo-tree/sources/common/filters/init.lua
index 79d0336bd..0c68ebdfa 100644
--- a/lua/neo-tree/sources/common/filters/init.lua
+++ b/lua/neo-tree/sources/common/filters/init.lua
@@ -13,6 +13,7 @@ local fzy = require("neo-tree.sources.common.filters.filter_fzy")
 
 local M = {}
 
+---@enum (key) neotree.FuzzyFinder.Commands
 local cmds = {
   move_cursor_down = function(state, scroll_padding)
     renderer.focus_node(state, nil, true, 1, scroll_padding)
diff --git a/lua/neo-tree/types/config/filesystem.lua b/lua/neo-tree/types/config/filesystem.lua
index 4b999c032..95775023f 100644
--- a/lua/neo-tree/types/config/filesystem.lua
+++ b/lua/neo-tree/types/config/filesystem.lua
@@ -3,28 +3,28 @@
 ---@alias neotree.Config.Cwd "tab"|"window"|"global"
 
 ---@class neotree.Config.Filesystem.CwdTarget
----@field sidebar neotree.Config.Cwd
----@field current neotree.Config.Cwd
+---@field sidebar neotree.Config.Cwd?
+---@field current neotree.Config.Cwd?
 
 ---@class neotree.Config.Filesystem.FilteredItems
----@field visible boolean
----@field force_visible_in_empty_folder boolean
----@field show_hidden_count boolean
----@field hide_dotfiles boolean
----@field hide_gitignored boolean
----@field hide_hidden boolean
----@field hide_by_name string[]
----@field hide_by_pattern string[]
----@field always_show string[]
----@field always_show_by_pattern string[]
----@field never_show string[]
----@field never_show_by_pattern string[]
+---@field visible boolean?
+---@field force_visible_in_empty_folder boolean?
+---@field show_hidden_count boolean?
+---@field hide_dotfiles boolean?
+---@field hide_gitignored boolean?
+---@field hide_hidden boolean?
+---@field hide_by_name string[]?
+---@field hide_by_pattern string[]?
+---@field always_show string[]?
+---@field always_show_by_pattern string[]?
+---@field never_show string[]?
+---@field never_show_by_pattern string[]?
 
 ---@alias neotree.Config.Filesystem.FindArgsHandler fun(cmd:string, path:string, search_term:string, args:string[]):string[]
 
 ---@class neotree.Config.Filesystem.FollowCurrentFile
----@field enabled boolean
----@field leave_dirs_open boolean
+---@field enabled boolean?
+---@field leave_dirs_open boolean?
 
 ---@alias neotree.Config.HijackNetrwBehavior
 ---|"open_default" # opening a directory opens neo-tree with the default window.position.
@@ -33,6 +33,9 @@
 
 ---@class neotree.Config.Filesystem.Renderers : neotree.Config.Renderers
 
+---@class neotree.Config.Filesystem.Window : neotree.Config.Source.Window
+---@field fuzzy_finder_mappings table<string, neotree.FuzzyFinder.Commands|"close">?
+
 ---@class (exact) neotree.Config.Filesystem : neotree.Config.Source
 ---@field async_directory_scan "auto"|"always"|"never"|nil
 ---@field scan_mode "shallow"|"deep"|nil
@@ -49,3 +52,4 @@
 ---@field hijack_netrw_behavior neotree.Config.HijackNetrwBehavior?
 ---@field use_libuv_file_watcher boolean?
 ---@field renderers neotree.Config.Filesystem.Renderers?
+---@field window neotree.Config.Filesystem.Window?

From 1d6326ee43b857fb5eeea3aa4eae51a006a0de57 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Wed, 5 Mar 2025 03:14:54 -0800
Subject: [PATCH 34/36] restore defaults.lua for now

---
 lua/neo-tree/defaults.lua | 185 ++++++++++++++++++--------------------
 1 file changed, 87 insertions(+), 98 deletions(-)

diff --git a/lua/neo-tree/defaults.lua b/lua/neo-tree/defaults.lua
index cee41a873..43546c1d3 100644
--- a/lua/neo-tree/defaults.lua
+++ b/lua/neo-tree/defaults.lua
@@ -12,14 +12,14 @@ local config = {
   },
   add_blank_line_at_top = false, -- Add a blank line at the top of the tree.
   auto_clean_after_session_restore = false, -- Automatically clean up broken neo-tree buffers saved in sessions
-  close_if_last_window = false,  -- Close Neo-tree if it is the last window left in the tab
+  close_if_last_window = false, -- Close Neo-tree if it is the last window left in the tab
   default_source = "filesystem", -- you can choose a specific source `last` here which indicates the last used source
   enable_diagnostics = true,
   enable_git_status = true,
   enable_modified_markers = true, -- Show markers for files with unsaved changes.
   enable_opened_markers = true,   -- Enable tracking of opened files. Required for `components.name.highlight_opened_files`
   enable_refresh_on_write = true, -- Refresh the tree when a file is written. Only used if `use_libuv_file_watcher` is false.
-  enable_cursor_hijack = false,   -- If enabled, neotree will keep the cursor on the first letter of the filename when moving in the tree.
+  enable_cursor_hijack = false, -- If enabled neotree will keep the cursor on the first letter of the filename when moving in the tree.
   git_status_async = true,
   -- These options are for people with VERY large git repos
   git_status_async_options = {
@@ -29,7 +29,7 @@ local config = {
                        -- Anything before this will be used. The last items to be processed are the untracked files.
   },
   hide_root_node = false, -- Hide the root node.
-  retain_hidden_root_indent = false, -- IF the root node is hidden, keep the indentation anyhow.
+  retain_hidden_root_indent = false, -- IF the root node is hidden, keep the indentation anyhow. 
                                      -- This is needed if you use expanders because they render in the indent.
   log_level = "info", -- "trace", "debug", "info", "warn", "error", "fatal"
   log_to_file = false, -- true, false, "/path/to/file.log", use ':lua require("neo-tree").show_logs()' to show the file
@@ -41,10 +41,10 @@ local config = {
   -- "NC" is a special style that works well with NormalNC set
   popup_border_style = "NC", -- "double", "none", "rounded", "shadow", "single" or "solid"
   resize_timer_interval = 500, -- in ms, needed for containers to redraw right aligned and faded content
-  --                           -- set to -1 to disable the resize timer entirely
+                               -- set to -1 to disable the resize timer entirely
   --                           -- NOTE: this will speed up to 50 ms for 1 second following a resize
   sort_case_insensitive = false, -- used when sorting files and directories in the tree
-  sort_function = nil,         -- a custom function for sorting files and directories in the tree
+  sort_function = nil , -- uses a custom function for sorting files and directories in the tree
   use_popups_for_input = true, -- If false, inputs will use vim.ui.input() instead of custom floats.
   use_default_mappings = true,
   -- source_selector provides clickable tabs to switch between sources.
@@ -52,7 +52,7 @@ local config = {
     winbar = false, -- toggle to show selector on winbar
     statusline = false, -- toggle to show selector on statusline
     show_scrolled_off_parent_node = false, -- this will replace the tabs with the parent path
-    -- of the top visible node when scrolled down.
+                                           -- of the top visible node when scrolled down.
     sources = {
       { source = "filesystem" },
       { source = "buffers" },
@@ -74,7 +74,7 @@ local config = {
     padding = 0, -- can be int or table
     -- padding = { left = 2, right = 0 },
     -- separator = "▕", -- can be string or table, see below
-    separator = { left = "▏", right = "▕" },
+     separator = { left = "▏", right= "▕" },
     -- separator = { left = "/", right = "\\", override = nil },     -- |/  a  \/  b  \/  c  \...
     -- separator = { left = "/", right = "\\", override = "right" }, -- |/  a  \  b  \  c  \...
     -- separator = { left = "/", right = "\\", override = "left" },  -- |/  a  /  b  /  c  /...
@@ -206,7 +206,7 @@ local config = {
       -- then these will never be used.
       default = "*",
       highlight = "NeoTreeFileIcon",
-      provider = function(icon, node, _) -- default icon provider utilizes nvim-web-devicons if available
+      provider = function(icon, node, state) -- default icon provider utilizes nvim-web-devicons if available
         if node.type == "file" or node.type == "terminal" then
           local success, web_devicons = pcall(require, "nvim-web-devicons")
           local name = node.type == "terminal" and "terminal" or node.name
@@ -216,7 +216,7 @@ local config = {
             icon.highlight = hl or icon.highlight
           end
         end
-      end,
+      end
     },
     modified = {
       symbol = "[+] ",
@@ -224,9 +224,9 @@ local config = {
     },
     name = {
       trailing_slash = false,
-      highlight_opened_files = false, -- Requires `enable_opened_markers = true`.
-                                      -- Take values in { false (no highlight), true (only loaded),
-                                      -- "all" (both loaded and unloaded) }. For more information,
+      highlight_opened_files = false, -- Requires `enable_opened_markers = true`. 
+                                      -- Take values in { false (no highlight), true (only loaded), 
+                                      -- "all" (both loaded and unloaded)}. For more information,
                                       -- see the `show_unloaded` config of the `buffers` source.
       use_git_status_colors = true,
       highlight = "NeoTreeFileName",
@@ -234,16 +234,16 @@ local config = {
     git_status = {
       symbols = {
         -- Change type
-        added = "✚", -- NOTE: you can set any of these to an empty string to not show them
-        deleted = "✖",
-        modified = "",
-        renamed = "󰁕",
+        added     = "✚", -- NOTE: you can set any of these to an empty string to not show them
+        deleted   = "✖",
+        modified  = "",
+        renamed   = "󰁕",
         -- Status type
         untracked = "",
-        ignored = "",
-        unstaged = "󰄱",
-        staged = "",
-        conflict = "",
+        ignored   = "",
+        unstaged  = "󰄱",
+        staged    = "",
+        conflict  = "",
       },
       align = "right",
     },
@@ -294,13 +294,7 @@ local config = {
             highlight = "NeoTreeSymbolicLinkTarget",
           },
           { "clipboard", zindex = 10 },
-          {
-            "diagnostics",
-            errors_only = true,
-            zindex = 20,
-            align = "right",
-            hide_when_expanded = true,
-          },
+          { "diagnostics", errors_only = true, zindex = 20, align = "right", hide_when_expanded = true },
           { "git_status", zindex = 10, align = "right", hide_when_expanded = true },
           { "file_size", zindex = 10, align = "right" },
           { "type", zindex = 10, align = "right" },
@@ -317,7 +311,7 @@ local config = {
         content = {
           {
             "name",
-            zindex = 10,
+            zindex = 10
           },
           {
             "symlink_target",
@@ -327,7 +321,7 @@ local config = {
           { "clipboard", zindex = 10 },
           { "bufnr", zindex = 10 },
           { "modified", zindex = 20, align = "right" },
-          { "diagnostics", zindex = 20, align = "right" },
+          { "diagnostics",  zindex = 20, align = "right" },
           { "git_status", zindex = 10, align = "right" },
           { "file_size", zindex = 10, align = "right" },
           { "type", zindex = 10, align = "right" },
@@ -344,8 +338,8 @@ local config = {
       { "indent" },
       { "icon" },
       { "name" },
-      { "bufnr" },
-    },
+      { "bufnr" }
+    }
   },
   nesting_rules = {},
   -- Global custom commands that will be available in all sources (if not overridden in `opts[source_name].commands`)
@@ -375,7 +369,7 @@ local config = {
         width = "50%",
       },
       position = "50%", -- 50% means center it
-      title = function(state) -- format the text that appears at the top of a popup window
+      title = function (state) -- format the text that appears at the top of a popup window
         return "Neo-tree " .. state.name:gsub("^%l", string.upper)
       end,
       -- you can also specify border here, if you want a different setting from
@@ -383,8 +377,8 @@ local config = {
     },
     same_level = false, -- Create and paste/move files/directories on the same level as the directory under cursor (as opposed to within the directory under cursor).
     insert_as = "child", -- Affects how nodes get inserted into the tree during creation/pasting/moving of files if the node under the cursor is a directory:
-    -- "child":   Insert nodes as children of the directory under cursor.
-    -- "sibling": Insert nodes  as siblings of the directory under cursor.
+                        -- "child":   Insert nodes as children of the directory under cursor.
+                        -- "sibling": Insert nodes  as siblings of the directory under cursor.
     -- Mappings for tree window. See `:h neo-tree-mappings` for a list of built-in commands.
     -- You can also create your own commands by providing a function instead of a string.
     mapping_options = {
@@ -393,23 +387,20 @@ local config = {
     },
     mappings = {
       ["<space>"] = {
-        "toggle_node",
-        nowait = false, -- disable `nowait` if you have existing combos starting with this char that you want to use
+          "toggle_node",
+          nowait = false, -- disable `nowait` if you have existing combos starting with this char that you want to use
       },
       ["<2-LeftMouse>"] = "open",
       ["<cr>"] = "open",
       -- ["<cr>"] = { "open", config = { expand_nested_files = true } }, -- expand nested file takes precedence
       ["<esc>"] = "cancel", -- close preview or floating neo-tree window
-      ["P"] = {
-        "toggle_preview",
-        config = {
-          use_float = true,
-          use_image_nvim = false,
-          -- title = "Neo-tree Preview", -- You can define a custom title for the preview floating window.
-        },
-      },
-      ["<C-f>"] = { "scroll_preview", config = { direction = -10 } },
-      ["<C-b>"] = { "scroll_preview", config = { direction = 10 } },
+      ["P"] = { "toggle_preview", config = {
+        use_float = true,
+        use_image_nvim = false,
+        -- title = "Neo-tree Preview", -- You can define a custom title for the preview floating window.
+      } },
+      ["<C-f>"] = { "scroll_preview", config = {direction = -10} },
+      ["<C-b>"] = { "scroll_preview", config = {direction = 10} },
       ["l"] = "focus_preview",
       ["S"] = "open_split",
       -- ["S"] = "split_with_window_picker",
@@ -430,7 +421,7 @@ local config = {
         -- some commands may take optional config options, see `:h neo-tree-mappings` for details
         config = {
           show_path = "none", -- "none", "relative", "absolute"
-        },
+        }
       },
       ["A"] = "add_directory", -- also accepts the config.show_path and config.insert_as options.
       ["d"] = "delete",
@@ -478,22 +469,22 @@ local config = {
         ["<C-n>"] = "move_cursor_down",
         ["<up>"] = "move_cursor_up",
         ["<C-p>"] = "move_cursor_up",
-        ["<esc>"] = "close",
+        ["<esc>"] = "close"
       },
     },
     async_directory_scan = "auto", -- "auto"   means refreshes are async, but it's synchronous when called from the Neotree commands.
-    -- "always" means directory scans are always async.
-    -- "never"  means directory scans are never async.
+                                   -- "always" means directory scans are always async.
+                                   -- "never"  means directory scans are never async.
     scan_mode = "shallow", -- "shallow": Don't scan into directories to detect possible empty directory a priori
-    -- "deep": Scan into directories to detect empty or grouped empty directories a priori.
+                           -- "deep": Scan into directories to detect empty or grouped empty directories a priori.
     bind_to_cwd = true, -- true creates a 2-way binding between vim's cwd and neo-tree's root
     cwd_target = {
-      sidebar = "tab", -- sidebar is when position = left or right
-      current = "window", -- current is when position = current
+      sidebar = "tab",   -- sidebar is when position = left or right
+      current = "window" -- current is when position = current
     },
     check_gitignore_in_search = true, -- check gitignore status for files/directories when searching
-    -- setting this to false will speed up searches, but gitignored
-    -- items won't be marked if they are visible.
+                                      -- setting this to false will speed up searches, but gitignored
+                                      -- items won't be marked if they are visible.
     -- The renderer section provides the renderers that will be used to render the tree.
     --   The first level is the node type.
     --   For each node type, you can specify a list of components to render.
@@ -509,7 +500,7 @@ local config = {
       hide_hidden = true, -- only works on Windows for hidden files/directories
       hide_by_name = {
         ".DS_Store",
-        "thumbs.db",
+        "thumbs.db"
         --"node_modules",
       },
       hide_by_pattern = { -- uses glob style patterns
@@ -530,16 +521,16 @@ local config = {
         --".null-ls_*",
       },
     },
-    find_by_full_path_words = false, -- `false` means it only searches the tail of a path.
-                                     -- `true` will change the filter into a full path
-                                     -- search with space as an implicit ".*", so
-                                     -- `fi init`
-                                     -- will match: `./sources/filesystem/init.lua
+    find_by_full_path_words = false,  -- `false` means it only searches the tail of a path.
+                                      -- `true` will change the filter into a full path
+                                      -- search with space as an implicit ".*", so
+                                      -- `fi init`
+                                      -- will match: `./sources/filesystem/init.lua
     --find_command = "fd", -- this is determined automatically, you probably don't need to set it
     --find_args = {  -- you can specify extra args to pass to the find command.
     --  fd = {
-    --    "--exclude", ".git",
-    --    "--exclude",  "node_modules"
+      --  "--exclude", ".git",
+      --  "--exclude",  "node_modules"
     --  }
     --},
     ---- or use a function instead of list of strings
@@ -576,7 +567,7 @@ local config = {
                                             -- window like netrw would, regardless of window.position
                           -- "disabled",    -- netrw left alone, neo-tree does not handle opening dirs
     use_libuv_file_watcher = false, -- This will use the OS level file watchers to detect changes
-    -- instead of relying on nvim autocmd events.
+                                    -- instead of relying on nvim autocmd events.
   },
   buffers = {
     bind_to_cwd = true,
@@ -585,10 +576,10 @@ local config = {
       --              -- the current file is changed while the tree is open.
       leave_dirs_open = false, -- `false` closes auto expanded dirs, such as with `:Neotree reveal`
     },
-    group_empty_dirs = true, -- when true, empty directories will be grouped together
-    show_unloaded = false, -- When working with sessions, for example, restored but unfocused buffers
-                           -- are mark as "unloaded". Turn this on to view these unloaded buffer.
-    terminals_first = false, -- when true, terminals will be listed before file buffers
+    group_empty_dirs = true,  -- when true, empty directories will be grouped together
+    show_unloaded = false,    -- When working with sessions, for example, restored but unfocused buffers
+                              -- are mark as "unloaded". Turn this on to view these unloaded buffer.
+    terminals_first = false,  -- when true, terminals will be listed before file buffers
     window = {
       mappings = {
         ["<bs>"] = "navigate_up",
@@ -634,20 +625,19 @@ local config = {
     client_filters = "first",
     renderers = {
       root = {
-        { "indent" },
-        { "icon", default = "C" },
-        { "name", zindex = 10 },
+        {"indent"},
+        {"icon", default="C" },
+        {"name", zindex = 10},
       },
       symbol = {
-        { "indent", with_expanders = true },
-        { "kind_icon", default = "?" },
-        {
-          "container",
-          content = {
-            { "name", zindex = 10 },
-            { "kind_name", zindex = 20, align = "right" },
-          },
-        },
+        {"indent", with_expanders = true},
+        {"kind_icon", default="?" },
+        {"container",
+        content = {
+          {"name", zindex = 10},
+          {"kind_name", zindex = 20, align = "right"},
+          }
+        }
       },
     },
     window = {
@@ -709,25 +699,24 @@ local config = {
       -- Parameter = { icon = ' ', hl = '@parameter' },
       -- StaticMethod = { icon = '󰠄 ', hl = 'Function' },
       -- Macro = { icon = ' ', hl = 'Macro' },
+    }
+  },
+  example = {
+    renderers = {
+      custom = {
+        {"indent"},
+        {"icon", default="C" },
+        {"custom"},
+        {"name"}
+      }
+    },
+    window = {
+      mappings = {
+        ["<cr>"] = "toggle_node",
+        ["<C-e>"] = "example_command",
+        ["d"] = "show_debug_info",
+      },
     },
   },
-  -- If you want to write your own source for items, this is how it would be configured:
-  -- example = {
-  --   renderers = {
-  --     custom = {
-  --       { "indent" },
-  --       { "icon", default = "C" },
-  --       { "custom" },
-  --       { "name" },
-  --     },
-  --   },
-  --   window = {
-  --     mappings = {
-  --       ["<cr>"] = "toggle_node",
-  --       ["<C-e>"] = "example_command",
-  --       ["d"] = "show_debug_info",
-  --     },
-  --   },
-  -- },
 }
 return config

From 7aee6c51cddd12f00f89e919a982b21af11c48b9 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Wed, 5 Mar 2025 03:30:34 -0800
Subject: [PATCH 35/36] remove unused local

---
 lua/neo-tree/events/queue.lua | 1 -
 1 file changed, 1 deletion(-)

diff --git a/lua/neo-tree/events/queue.lua b/lua/neo-tree/events/queue.lua
index 4dc029b9c..01739e979 100644
--- a/lua/neo-tree/events/queue.lua
+++ b/lua/neo-tree/events/queue.lua
@@ -10,7 +10,6 @@ local M = {}
 ---@field event neotree.Event|string
 ---@field handler fun(...)
 ---@field id string?
-local a = {}
 
 local validate_event_handler = function(event_handler)
   if type(event_handler) ~= "table" then

From 78e23203b5f5c9891de40ecbd72e500efa3bcf99 Mon Sep 17 00:00:00 2001
From: pynappo <pynappo@proton.me>
Date: Wed, 5 Mar 2025 03:49:23 -0800
Subject: [PATCH 36/36] update event type

---
 lua/neo-tree/events/init.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lua/neo-tree/events/init.lua b/lua/neo-tree/events/init.lua
index 94b0e7e57..03fe580a5 100644
--- a/lua/neo-tree/events/init.lua
+++ b/lua/neo-tree/events/init.lua
@@ -53,7 +53,7 @@ local M = {
   VIM_WIN_ENTER = "vim_win_enter",
 }
 
----@param event_name neotree.Event
+---@param event_name neotree.Event|string
 M.define_autocmd_event = function(event_name, autocmds, debounce_frequency, seed_fn, nested)
   local opts = {
     setup = function()