docs: add types for user configuration

.github/workflows/.luarc-5.1.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
+  "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"
+    ]
+  }
+}

.github/workflows/.luarc-luajit-master.json

@@ -0,0 +1,29 @@
+{
+  "$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"
+    ],
+    "ignoreDir": [
+      ".dependencies",
+      ".luarocks"
+    ]
+  }
+}

.github/workflows/ci.yml

@@ -7,6 +7,7 @@ on:
       - v2.x
       - v3.x
   pull_request:
+  workflow_dispatch:
 
 jobs:
   stylua-check:
@@ -76,7 +77,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

.github/workflows/luals-check.yml

@@ -0,0 +1,36 @@
+name: Lua Language Server Diagnostics
+on:
+  pull_request: ~
+  push:
+    branches:
+      - '*'
+
+jobs:
+  luals-check:
+    strategy:
+      matrix:
+        neovim: ["0.10"]
+        lua: ["5.1", "luajit-master"]
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - uses: luarocks/gh-actions-lua@v10
+      with:
+        luaVersion: ${{matrix.lua}}
+
+    - name: Install lua-language-server
+      uses: jdx/mise-action@v2
+      with:
+        mise_toml: |
+          [tools]
+          neovim = "${{ matrix.neovim }}"
+          lua-language-server = "latest"
+
+    - name: Run lua-language-server check
+      continue-on-error: true
+      run: |
+        LUARC=".github/workflows/.luarc-${{ matrix.lua }}.json"
+        make luals-check CONFIGURATION="$LUARC"

.gitignore

@@ -44,4 +44,5 @@ tags
 
 # Others
 .testcache
+.dependencies
 luacov.*.out

.luarc.json

@@ -1,3 +1,29 @@
 {
-  "diagnostics.globals": ["vim"]
+  "$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"
+    ],
+    "ignoreDir": [
+      ".dependencies",
+      ".luarocks"
+    ]
+  }
 }

Makefile

@@ -10,3 +10,30 @@ test-docker:
 .PHONY: format
 format:
 	stylua --glob '*.lua' --glob '!defaults.lua' .
+
+# Dependencies:
+
+DEPS := ./.dependencies/site/pack/vendor/start
+
+$(DEPS):
+	mkdir -p "$(DEPS)"
+
+$(DEPS)/nui.nvim: $(DEPS)
+	@test -d "$(DEPS)/nui.nvim" || git clone https://github.com/MunifTanjim/nui.nvim "$(DEPS)/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"
+
+$(DEPS)/plenary.nvim: $(DEPS)
+	@test -d "$(DEPS)/plenary.nvim" || git clone https://github.com/nvim-lua/plenary.nvim "$(DEPS)/plenary.nvim"
+
+setup: $(DEPS)/nui.nvim $(DEPS)/nvim-web-devicons $(DEPS)/plenary.nvim
+	@echo "[setup] environment ready"
+
+.PHONY: clean
+clean:
+	rm -rf "$(DEPS)"
+
+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=.

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.
@@ -98,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

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.

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|string
 M.define_autocmd_event = function(event_name, autocmds, debounce_frequency, seed_fn, nested)
   local opts = {
     setup = function()

lua/neo-tree/events/queue.lua

@@ -6,6 +6,11 @@ local event_queues = {}
 local event_definitions = {}
 local M = {}
 
+---@class neotree.Event.Handler
+---@field event neotree.Event|string
+---@field handler fun(...)
+---@field id string?
+
 local validate_event_handler = function(event_handler)
   if type(event_handler) ~= "table" then
     error("Event handler must be a table")
@@ -104,6 +109,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)
 

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

lua/neo-tree/sources/buffers/components.lua

@@ -14,8 +14,18 @@ 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.Renderer>
 local M = {}
 
+---@class (exact) neotree.Component.Buffers.Name : neotree.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