perf: query caching, settings validation, cache auto-invalidation

- Cache the treesitter parametrize query at module level in call_spec.lua
  instead of re-parsing it on every call to get_param_call_nodes.
- Add type validation to settings.update(): reject values whose type
  doesn't match the default, with a warning message.
- Add BufWritePost/BufDelete autocommand in ts.lua to automatically
  invalidate fixture scan cache entries when Python files are saved or
  deleted. clear_scan_cache() now accepts an optional filepath argument.
- Add LuaCATS annotations to settings.lua (@Class PytrizeSettings).

Author: sigfriedCub1990

lua/pytrize/call_spec.lua

@@ -21,25 +21,25 @@ local get_root = function(bufnr)
     return trees[1]:root()
 end
 
+local PARAM_QUERY = parse_query(
+    "python",
+    [[
+      (decorated_definition (
+        decorator (
+          call
+            function: ((attribute) @param)
+        )
+      ))
+    ]]
+)
+
 local get_param_call_nodes = function(bufnr)
     local tsroot = get_root(bufnr)
     if tsroot == nil then
         return {}
     end
-    local query = parse_query(
-        "python",
-        -- TODO not sure why eg (#eq? @param "pytest.mark.parametrize") does not work
-        [[
-          (decorated_definition (
-            decorator (
-              call
-                function: ((attribute) @param)
-            )
-          ))
-        ]]
-    )
     local nodes = {}
-    for _, node, _ in query:iter_captures(tsroot) do
+    for _, node, _ in PARAM_QUERY:iter_captures(tsroot, bufnr) do
         if ts.get_node_text(node, bufnr) == "pytest.mark.parametrize" then
             table.insert(nodes, node:parent())
         end

lua/pytrize/settings.lua

@@ -2,20 +2,31 @@ local M = {}
 
 local warn = require("pytrize.warn").warn
 
--- defaults
+---@class PytrizeSettings
+---@field no_commands boolean Whether to skip creating user commands (default: false)
+---@field highlight string Highlight group for virtual text (default: "LineNr")
+---@field metrics boolean Show performance metrics for operations (default: false)
+
+---@type PytrizeSettings
 M.settings = {
     no_commands = false,
     highlight = "LineNr",
     metrics = false,
-    -- preferred_input = 'telescope',
 }
 
+---@param opts table
 M.update = function(opts)
     for k, v in pairs(opts) do
         if M.settings[k] == nil then
-            warn("unexpected setting " .. k)
+            warn(string.format("unknown setting '%s'", k))
         else
-            M.settings[k] = v
+            local expected = type(M.settings[k])
+            local actual = type(v)
+            if expected ~= actual then
+                warn(string.format("invalid type for setting '%s': expected %s, got %s", k, expected, actual))
+            else
+                M.settings[k] = v
+            end
         end
     end
 end

lua/pytrize/ts.lua

@@ -80,8 +80,24 @@ end
 
 local scan_cache = {}
 
-M.clear_scan_cache = function()
-    scan_cache = {}
+-- Auto-invalidate cache when Python files are saved or deleted
+local cache_group = vim.api.nvim_create_augroup("PytrizeCache", { clear = true })
+vim.api.nvim_create_autocmd({ "BufWritePost", "BufDelete" }, {
+    group = cache_group,
+    pattern = "*.py",
+    callback = function(args)
+        local filepath = vim.api.nvim_buf_get_name(args.buf)
+        scan_cache[filepath] = nil
+    end,
+})
+
+---@param filepath? string Clear a single entry, or all entries if nil.
+M.clear_scan_cache = function(filepath)
+    if filepath then
+        scan_cache[filepath] = nil
+    else
+        scan_cache = {}
+    end
 end
 
 M.scan_fixtures = function(filepath)

tests/pytrize/settings_spec.lua

@@ -25,12 +25,26 @@ describe("settings", function()
   end)
 
   it("does not crash on unknown key", function()
-    -- Stub vim.notify to avoid errors in headless mode
     local original_notify = vim.notify
     local notified = false
     vim.notify = function() notified = true end
     settings_mod.update({ nonexistent_key = "value" })
     vim.notify = original_notify
     assert.is_true(notified)
   end)
+
+  it("rejects wrong type for a setting", function()
+    local original_notify = vim.notify
+    local warned = false
+    vim.notify = function(msg)
+      if type(msg) == "string" and msg:find("invalid type") then
+        warned = true
+      end
+    end
+    settings_mod.update({ highlight = 123 })  -- should be string, not number
+    vim.notify = original_notify
+    assert.is_true(warned)
+    -- value should not have changed
+    assert.are.equal("LineNr", settings_mod.settings.highlight)
+  end)
 end)