feat(tests): improve test coverage and add LuaDoc annotations

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

Author: ThomasK33

.github/workflows/test.yml

@@ -43,23 +43,22 @@ jobs:
           luarocks install luacov-reporter-lcov
 
       - name: Run Luacheck
-        run: luacheck lua/ tests/
+        run: luacheck lua/ tests/ --no-unused-args --no-max-line-length
 
       - name: Run tests
         run: |
-          cd tests
-          busted --coverage
+          chmod +x ./run_tests.sh
+          ./run_tests.sh
 
       - name: Generate coverage report
         run: |
-          cd tests
           luacov-console
           luacov-console -r lcov > lcov.info
 
       - name: Upload coverage report
         uses: codecov/codecov-action@c16abc29c95fcf9174b58eb7e1abf4c866893bc8 # v4
         with:
-          files: ./tests/lcov.info
+          files: ./lcov.info
           fail_ci_if_error: false
 
   integration-tests:

.gitignore

@@ -43,6 +43,9 @@ luac.out
 /luacov.*
 /tests/luacov.*
 /tests/lcov.info
+/lcov.info
+luacov.report.out
+luacov.stats.out
 
 # Temporary files
 .DS_Store

flake.nix

@@ -17,13 +17,13 @@
         treefmt = treefmt-nix.lib.evalModule pkgs {
           projectRootFile = "flake.nix";
           programs = {
-            stylua.enable = true; # Lua formatter
-            nixpkgs-fmt.enable = true; # Nix formatter
-            prettier.enable = true; # Markdown/YAML/JSON formatter
-            shfmt.enable = true; # Shell formatter
-            actionlint.enable = true; # GitHub Actions linter
-            zizmor.enable = true; # GitHub Actions security analyzer
-            shellcheck.enable = true; # Shell script analyzer
+            stylua.enable = true;
+            nixpkgs-fmt.enable = true;
+            prettier.enable = true;
+            shfmt.enable = true;
+            actionlint.enable = true;
+            zizmor.enable = true;
+            shellcheck.enable = true;
           };
           settings.formatter.shellcheck.options = [ "--exclude=SC1091,SC2016" ];
         };
@@ -37,24 +37,21 @@
 
         devShells.default = pkgs.mkShell {
           buildInputs = with pkgs; [
-            # Lua and development tools
             lua5_1
             luajitPackages.luacheck
-            luajitPackages.busted # Testing framework
+            luajitPackages.busted
+            luajitPackages.luacov
 
-            # WebSocket implementation
             luajitPackages.luasocket
             luajitPackages.lua-cjson
 
-            # Development utilities
             ast-grep
-            neovim # For testing the plugin
-            luarocks # Lua package manager
-            gnumake # For running the Makefile
-            websocat # WebSocket testing utility
-            jq # JSON processor for parsing responses
+            neovim
+            luarocks
+            gnumake
+            websocat
+            jq
 
-            # Formatting tools (via treefmt-nix)
             treefmt.config.build.wrapper
           ];
         };

lua/claudecode/server/init.lua

@@ -1,39 +1,51 @@
--- WebSocket server for Claude Code Neovim integration
+---@brief WebSocket server for Claude Code Neovim integration
 local M = {}
+math.randomseed(os.time()) -- Seed for random port selection
 
--- Server state
+---@class ServerState
+---@field server table|nil The server instance
+---@field port number|nil The port server is running on
+---@field clients table A list of connected clients
+---@field handlers table Message handlers by method name
 M.state = {
   server = nil,
   port = nil,
   clients = {},
   handlers = {},
 }
 
--- Find an available port in the given range
-function M.find_available_port(min, _) -- '_' for unused max param
+---@brief Find an available port in the given range
+---@param min number The minimum port number
+---@param max number The maximum port number
+---@return number port The selected port
+function M.find_available_port(min, max)
   -- TODO: Implement port scanning logic
-  -- For now, return a mock value
-  return min
+  if min > max then
+    -- Defaulting to min in this edge case to avoid math.random error.
+    -- Consider logging a warning or error here in a real scenario.
+    return min
+  end
+  return math.random(min, max)
 end
 
--- Initialize the WebSocket server
+---@brief Initialize the WebSocket server
+---@param config table Configuration options
+---@return boolean success Whether server started successfully
+---@return number|string port_or_error Port number or error message
 function M.start(config)
   if M.state.server then
-    -- Already running
     return false, "Server already running"
   end
 
   -- TODO: Implement actual WebSocket server
   -- This is a placeholder that would be replaced with real implementation
 
-  -- Find an available port
   local port = M.find_available_port(config.port_range.min, config.port_range.max)
 
   if not port then
     return false, "No available ports found"
   end
 
-  -- Store the port in state
   M.state.port = port
 
   -- Mock server object for now
@@ -42,91 +54,78 @@ function M.start(config)
     clients = {},
   }
 
-  -- Register message handlers
   M.register_handlers()
 
   return true, port
 end
 
--- Stop the WebSocket server
+---@brief Stop the WebSocket server
+---@return boolean success Whether server stopped successfully
+---@return string|nil error_message Error message if any
 function M.stop()
   if not M.state.server then
-    -- Not running
     return false, "Server not running"
   end
 
   -- TODO: Implement actual WebSocket server shutdown
-  -- This is a placeholder
 
-  -- Reset state
   M.state.server = nil
   M.state.port = nil
   M.state.clients = {}
 
   return true
 end
 
--- Register message handlers
+---@brief Register message handlers for the server
 function M.register_handlers()
   -- TODO: Implement message handler registration
-  -- These would be functions that handle specific message types
 
-  -- Example handlers:
   M.state.handlers = {
     ["mcp.connect"] = function(_, _) -- '_' for unused args
-      -- Handle connection handshake
       -- TODO: Implement
     end,
 
     ["mcp.tool.invoke"] = function(_, _) -- '_' for unused args
-      -- Handle tool invocation
       -- TODO: Implement by dispatching to tool implementations
     end,
   }
 end
 
--- Send a message to a client
+---@brief Send a message to a client
+---@param _client table The client to send to
+---@param _method string The method name
+---@param _params table|nil The parameters to send
+---@return boolean success Whether message was sent successfully
 function M.send(_client, _method, _params) -- Prefix unused params with underscore
   -- TODO: Implement sending WebSocket message
-  -- This is a placeholder
-
-  -- Structure what would be sent (commented out to avoid unused var warning)
-  -- local message = {
-  --   jsonrpc = "2.0",
-  --   method = _method,
-  --   params = _params,
-  -- }
-
-  -- Mock sending logic
-  -- In real implementation, this would send the JSON-encoded message
-  -- to the WebSocket client
 
   return true
 end
 
--- Send a response to a client
-function M.send_response(_client, id, result, error_data) -- Normal params since they're now used
+---@brief Send a response to a client
+---@param _client table The client to send to
+---@param id number|string The request ID to respond to
+---@param result any|nil The result data if successful
+---@param error_data table|nil The error data if failed
+---@return boolean success Whether response was sent successfully
+function M.send_response(_client, id, result, error_data)
   -- TODO: Implement sending WebSocket response
-  -- This is a placeholder
 
-  -- Structure what would be sent (this is a comment, we'll make a real variable below)
-  -- In actual implementation, we would send the message via WebSocket
   if error_data then
-    -- Create error response
     local _ = { jsonrpc = "2.0", id = id, error = error_data } -- luacheck: ignore
   else
-    -- Create result response
     local _ = { jsonrpc = "2.0", id = id, result = result } -- luacheck: ignore
   end
 
-  -- Mock sending logic
   return true
 end
 
--- Broadcast a message to all connected clients
+---@brief Broadcast a message to all connected clients
+---@param method string The method name
+---@param params table|nil The parameters to send
+---@return boolean success Whether broadcast was successful
 function M.broadcast(method, params)
   -- TODO: Implement broadcasting to all clients
-  -- This is a placeholder
 
   for _, client in pairs(M.state.clients) do
     M.send(client, method, params)

run_tests.sh

@@ -11,9 +11,9 @@ echo "Found test files:"
 echo "$TEST_FILES"
 
 if [ -n "$TEST_FILES" ]; then
-  # Pass test files to busted - quotes needed but shellcheck disabled as we need word splitting
+  # Pass test files to busted with coverage flag - quotes needed but shellcheck disabled as we need word splitting
   # shellcheck disable=SC2086
-  busted -v $TEST_FILES
+  busted --coverage -v $TEST_FILES
 else
   echo "No test files found"
 fi

tests/mocks/vim.lua

@@ -1,5 +1,67 @@
 -- Mock implementation of the Neovim API for tests
 
+-- Spy functionality for testing
+if _G.spy == nil then
+  _G.spy = {
+    on = function(table, method_name)
+      -- Save original function
+      local original = table[method_name]
+      -- Keep track of calls
+      local calls = {}
+
+      -- Replace with spied function
+      table[method_name] = function(...)
+        table.insert(calls, { vals = { ... } })
+        if original then
+          return original(...)
+        end
+      end
+
+      -- Add spy methods to the function
+      table[method_name].calls = calls
+      table[method_name].spy = function()
+        return {
+          was_called = function(n)
+            assert(#calls == n, "Expected " .. n .. " calls, got " .. #calls)
+            return true
+          end,
+          was_not_called = function()
+            assert(#calls == 0, "Expected 0 calls, got " .. #calls)
+            return true
+          end,
+          was_called_with = function(...)
+            local expected = { ... }
+            assert(#calls > 0, "Function was never called")
+
+            -- Compare args
+            local last_call = calls[#calls].vals
+            for i, v in ipairs(expected) do
+              if type(v) == "table" and v._type == "match" then
+                -- Use custom matcher (simplified)
+                if v._match == "is_table" and type(last_call[i]) ~= "table" then
+                  assert(false, "Expected table at arg " .. i)
+                end
+              else
+                assert(last_call[i] == v, "Argument mismatch at position " .. i)
+              end
+            end
+            return true
+          end,
+        }
+      end
+
+      return table[method_name]
+    end,
+  }
+
+  -- Simple table matcher for spy assertions
+  _G.match = {
+    is_table = function()
+      return { _type = "match", _match = "is_table" }
+    end,
+  }
+end
+
 local vim = {
   _buffers = {},
   _windows = {},