feat(types): add lua language server type definitions and improve test assertions

Change-Id: I8ce4c0a4950096ff255aa338b6f5588b7c8f6eb9
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

.luarc.json

@@ -1,11 +1,19 @@
 {
   "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
-  "Lua.diagnostics.globals": ["vim"],
+  "Lua.diagnostics.globals": [
+    "vim",
+    "setup",
+    "teardown",
+    "before_each",
+    "after_each",
+    "match",
+    "assert"
+  ],
   "Lua.runtime.version": "LuaJIT",
   "Lua.workspace.checkThirdParty": false,
-  "Lua.workspace.library": ["${3rd}/luv/library"],
+  "Lua.workspace.library": ["${3rd}/luv/library", "lua/claudecode/meta"],
   "Lua.workspace.maxPreload": 2000,
   "Lua.workspace.preloadFileSize": 1000,
   "Lua.telemetry.enable": false,
-  "diagnostics.disable": ["lowercase-global"]
+  "Lua.diagnostics.disable": ["lowercase-global"]
 }

lua/claudecode/init.lua

@@ -60,13 +60,17 @@ M.state = {
   initialized = false,
 }
 
+---@alias ClaudeCode.TerminalOpts { \
+---  split_side?: "left"|"right", \
+---  split_width_percentage?: number, \
+---  provider?: "snacks"|"native", \
+---  show_native_term_exit_tip?: boolean }
+---
+---@alias ClaudeCode.SetupOpts { \
+---  terminal?: ClaudeCode.TerminalOpts }
+---
 --- Set up the plugin with user configuration
----@param opts table|nil Optional configuration table to override defaults.
----@field opts.terminal table|nil Configuration for the terminal module.
----@field opts.terminal.split_side string|nil 'left' or 'right'.
----@field opts.terminal.split_width_percentage number|nil Percentage of screen width (0.0 to 1.0).
----@field opts.terminal.provider string|nil 'snacks' or 'native'.
----@field opts.terminal.show_native_term_exit_tip boolean|nil Show tip for exiting native terminal (default: true).
+---@param opts ClaudeCode.SetupOpts|nil Optional configuration table to override defaults.
 ---@return table The plugin module
 function M.setup(opts)
   opts = opts or {}
@@ -134,7 +138,7 @@ function M.start(show_startup_notification)
   end
 
   M.state.server = server
-  M.state.port = result
+  M.state.port = tonumber(result)
 
   local lockfile = require("claudecode.lockfile")
   local lock_success, lock_result = lockfile.create(M.state.port)

lua/claudecode/meta/vim.lua

@@ -0,0 +1,62 @@
+---@meta vim_api_definitions
+-- This file provides type definitions for parts of the Neovim API
+-- to help the Lua language server (LuaLS) with diagnostics.
+
+---@class vim_log_levels
+---@field NONE number
+---@field ERROR number
+---@field WARN number
+---@field INFO number
+---@field DEBUG number
+---@field TRACE number
+
+---@class vim_log
+---@field levels vim_log_levels
+
+---@class vim_notify_opts
+---@field title string|nil
+---@field icon string|nil
+---@field on_open fun(winid: number)|nil
+---@field on_close fun()|nil
+---@field timeout number|nil
+---@field keep fun()|nil
+---@field plugin string|nil
+---@field hide_from_history boolean|nil
+---@field once boolean|nil
+---@field on_close_timeout number|nil
+
+---@class vim_global_api
+---@field notify fun(msg: string | string[], level?: number, opts?: vim_notify_opts):nil
+---@field log vim_log
+---@field _last_echo table[]? # table of tables, e.g. { {"message", "HighlightGroup"} }
+---@field _last_error string?
+-- Add other vim object definitions here if they cause linting issues
+-- e.g. vim.fn, vim.api, vim.loop, vim.deepcopy, etc.
+
+---@class SpyCall
+---@field vals table[] table of arguments passed to the call
+---@field self any the 'self' object for the call if it was a method
+
+---@class SpyInformation
+---@field calls SpyCall[] A list of calls made to the spy.
+---@field call_count number The number of times the spy has been called.
+-- Add other spy properties if needed e.g. returned, threw
+
+---@class SpyAsserts
+---@field was_called fun(self: SpyAsserts, count?: number):boolean
+---@field was_called_with fun(self: SpyAsserts, ...):boolean
+---@field was_not_called fun(self: SpyAsserts):boolean
+-- Add other spy asserts if needed
+
+---@class SpyableFunction : function
+---@field __call fun(self: SpyableFunction, ...):any
+---@field spy fun(self: SpyableFunction):SpyAsserts Returns an assertion object for the spy.
+---@field calls SpyInformation[]? Information about calls made to the spied function.
+-- Note: In some spy libraries, 'calls' might be directly on the spied function,
+-- or on an object returned by `spy()`. Adjust as per your spy library's specifics.
+-- For busted's default spy, `calls` is often directly on the spied function.
+
+-- This section helps LuaLS understand that 'vim' is a global variable
+-- with the structure defined above. It's for type hinting only and
+-- does not execute or overwrite the actual 'vim' global provided by Neovim.
+---@type vim_global_api

lua/claudecode/server/mock.lua

@@ -18,7 +18,7 @@ M.state = {
 
 --- Find an available port in the given range
 ---@param min number The minimum port number
----@param max number The maximum port number
+---@param _max number The maximum port number
 ---@return number port The selected port
 function M.find_available_port(min, _max)
   -- For mock implementation, just return the minimum port

tests/config_test.lua

@@ -1,8 +1,9 @@
 -- Simple config module tests that don't rely on the vim API
 
 -- Create minimal vim mock
-_G.vim = {
+_G.vim = { ---@type vim_global_api
   deepcopy = function(t)
+    -- Basic deepcopy for testing
     local copy = {}
     for k, v in pairs(t) do
       if type(v) == "table" then
@@ -13,6 +14,17 @@ _G.vim = {
     end
     return copy
   end,
+  notify = function(msg, level, opts) end,
+  log = {
+    levels = {
+      NONE = 0,
+      ERROR = 1,
+      WARN = 2,
+      INFO = 3,
+      DEBUG = 4,
+      TRACE = 5,
+    },
+  },
 
   tbl_deep_extend = function(behavior, ...)
     local result = {}
@@ -45,13 +57,13 @@ describe("Config module", function()
   end)
 
   it("should have default values", function()
-    assert.is_table(config.defaults)
-    assert.is_table(config.defaults.port_range)
-    assert.is_number(config.defaults.port_range.min)
-    assert.is_number(config.defaults.port_range.max)
-    assert.is_boolean(config.defaults.auto_start)
-    assert.is_string(config.defaults.log_level)
-    assert.is_boolean(config.defaults.track_selection)
+    assert(type(config.defaults) == "table")
+    assert(type(config.defaults.port_range) == "table")
+    assert(type(config.defaults.port_range.min) == "number")
+    assert(type(config.defaults.port_range.max) == "number")
+    assert(type(config.defaults.auto_start) == "boolean")
+    assert(type(config.defaults.log_level) == "string")
+    assert(type(config.defaults.track_selection) == "boolean")
   end)
 
   it("should validate valid configuration", function()
@@ -67,7 +79,7 @@ describe("Config module", function()
       return config.validate(valid_config)
     end)
 
-    assert.is_true(success)
+    assert(success == true)
   end)
 
   it("should merge user config with defaults", function()
@@ -78,9 +90,9 @@ describe("Config module", function()
 
     local merged_config = config.apply(user_config)
 
-    assert.is_true(merged_config.auto_start)
-    assert.equals("debug", merged_config.log_level)
-    assert.equals(config.defaults.port_range.min, merged_config.port_range.min)
-    assert.equals(config.defaults.track_selection, merged_config.track_selection)
+    assert(merged_config.auto_start == true)
+    assert("debug" == merged_config.log_level)
+    assert(config.defaults.port_range.min == merged_config.port_range.min)
+    assert(config.defaults.track_selection == merged_config.track_selection)
   end)
 end)

tests/lockfile_test.lua

@@ -4,7 +4,7 @@
 local real_vim = _G.vim
 if not _G.vim then
   -- Create a basic vim mock
-  _G.vim = {
+  _G.vim = { -- Removed ---@type vim_global_api annotation
     fn = {
       expand = function(path)
         return path:gsub("~", "/home/user")
@@ -22,6 +22,17 @@ if not _G.vim then
         return 1
       end,
     },
+    notify = function(msg, level, opts) end,
+    log = {
+      levels = {
+        NONE = 0,
+        ERROR = 1,
+        WARN = 2,
+        INFO = 3,
+        DEBUG = 4,
+        TRACE = 5,
+      },
+    },
     json = {
       encode = function(_obj) -- Prefix unused param with underscore
         return '{"mocked":"json"}'
@@ -107,7 +118,7 @@ describe("Lockfile Module", function()
 
     it("should include the current working directory", function()
       local folders = lockfile.get_workspace_folders()
-      assert.equals("/mock/cwd", folders[1])
+      assert("/mock/cwd" == folders[1])
     end)
 
     it("should work with current Neovim API (get_clients)", function()
@@ -118,9 +129,9 @@ describe("Lockfile Module", function()
       local folders = lockfile.get_workspace_folders()
 
       -- Verify results
-      assert.equals(3, #folders) -- cwd + 2 workspace folders
-      assert.equals("/mock/folder1", folders[2])
-      assert.equals("/mock/folder2", folders[3])
+      assert(3 == #folders) -- cwd + 2 workspace folders
+      assert("/mock/folder1" == folders[2])
+      assert("/mock/folder2" == folders[3])
     end)
 
     it("should work with legacy Neovim API (get_active_clients)", function()
@@ -131,9 +142,9 @@ describe("Lockfile Module", function()
       local folders = lockfile.get_workspace_folders()
 
       -- Verify results
-      assert.equals(3, #folders) -- cwd + 2 workspace folders
-      assert.equals("/mock/folder1", folders[2])
-      assert.equals("/mock/folder2", folders[3])
+      assert(3 == #folders) -- cwd + 2 workspace folders
+      assert("/mock/folder1" == folders[2])
+      assert("/mock/folder2" == folders[3])
     end)
 
     it("should handle duplicate folder paths", function()
@@ -158,7 +169,7 @@ describe("Lockfile Module", function()
       local folders = lockfile.get_workspace_folders()
 
       -- Verify results
-      assert.equals(2, #folders) -- cwd + 1 unique workspace folder
+      assert(2 == #folders) -- cwd + 1 unique workspace folder
     end)
   end)
 end)

tests/selection_test.lua

@@ -185,6 +185,19 @@ if not _G.vim then
         }
       end,
     },
+
+    -- Added notify and log mocks
+    notify = function(msg, level, opts) end,
+    log = {
+      levels = {
+        NONE = 0,
+        ERROR = 1,
+        WARN = 2,
+        INFO = 3,
+        DEBUG = 4,
+        TRACE = 5,
+      },
+    },
   }
 
   -- Initialize with a test buffer
@@ -224,26 +237,26 @@ describe("Selection module", function()
   end)
 
   it("should have the correct initial state", function()
-    assert.is_table(selection.state)
-    assert.is_nil(selection.state.latest_selection)
-    assert.is_false(selection.state.tracking_enabled)
-    assert.is_nil(selection.state.debounce_timer)
-    assert.is_number(selection.state.debounce_ms)
+    assert(type(selection.state) == "table")
+    assert(selection.state.latest_selection == nil)
+    assert(selection.state.tracking_enabled == false)
+    assert(selection.state.debounce_timer == nil)
+    assert(type(selection.state.debounce_ms) == "number")
   end)
 
   it("should enable and disable tracking", function()
     -- Enable tracking
     selection.enable(mock_server)
 
-    assert.is_true(selection.state.tracking_enabled)
-    assert.equals(mock_server, selection.server)
+    assert(selection.state.tracking_enabled == true)
+    assert(mock_server == selection.server)
 
     -- Disable tracking
     selection.disable()
 
-    assert.is_false(selection.state.tracking_enabled)
-    assert.is_nil(selection.server)
-    assert.is_nil(selection.state.latest_selection)
+    assert(selection.state.tracking_enabled == false)
+    assert(selection.server == nil)
+    assert(selection.state.latest_selection == nil)
   end)
 
   it("should get cursor position in normal mode", function()
@@ -261,20 +274,20 @@ describe("Selection module", function()
     -- Restore original function
     _G.vim.api.nvim_win_get_cursor = old_win_get_cursor
 
-    assert.is_table(cursor_pos)
-    assert.equals("", cursor_pos.text)
-    assert.is_string(cursor_pos.filePath)
-    assert.is_string(cursor_pos.fileUrl)
-    assert.is_table(cursor_pos.selection)
-    assert.is_table(cursor_pos.selection.start)
-    assert.is_table(cursor_pos.selection["end"])
+    assert(type(cursor_pos) == "table")
+    assert("" == cursor_pos.text)
+    assert(type(cursor_pos.filePath) == "string")
+    assert(type(cursor_pos.fileUrl) == "string")
+    assert(type(cursor_pos.selection) == "table")
+    assert(type(cursor_pos.selection.start) == "table")
+    assert(type(cursor_pos.selection["end"]) == "table")
 
     -- Check positions - 0-based in selection, source is 1-based from nvim_win_get_cursor
-    assert.equals(1, cursor_pos.selection.start.line) -- Should be 2-1=1
-    assert.equals(3, cursor_pos.selection.start.character)
-    assert.equals(1, cursor_pos.selection["end"].line)
-    assert.equals(3, cursor_pos.selection["end"].character)
-    assert.is_true(cursor_pos.selection.isEmpty)
+    assert(1 == cursor_pos.selection.start.line) -- Should be 2-1=1
+    assert(3 == cursor_pos.selection.start.character)
+    assert(1 == cursor_pos.selection["end"].line)
+    assert(3 == cursor_pos.selection["end"].character)
+    assert(cursor_pos.selection.isEmpty == true)
   end)
 
   it("should detect selection changes", function()
@@ -337,15 +350,15 @@ describe("Selection module", function()
     selection.state.latest_selection = old_selection
 
     -- Test same selection
-    assert.is_false(selection.has_selection_changed(new_selection_same))
+    assert(selection.has_selection_changed(new_selection_same) == false)
 
     -- Test different file
-    assert.is_true(selection.has_selection_changed(new_selection_diff_file))
+    assert(selection.has_selection_changed(new_selection_diff_file) == true)
 
     -- Test different text
-    assert.is_true(selection.has_selection_changed(new_selection_diff_text))
+    assert(selection.has_selection_changed(new_selection_diff_text) == true)
 
     -- Test different position
-    assert.is_true(selection.has_selection_changed(new_selection_diff_pos))
+    assert(selection.has_selection_changed(new_selection_diff_pos) == true)
   end)
 end)