polish: add health check, LuaCATS annotations, drop deprecated compat

- Add lua/pytrize/health.lua for :checkhealth pytrize support. Checks
  Neovim version (>= 0.9), Python treesitter parser, grep availability,
  and configured highlight group existence.
- Add LuaCATS @param/@return doc annotations to api.lua, marks.lua, and
  init.lua for better lua-language-server discoverability.
- Remove deprecated ts_query.parse_query compatibility shim in
  call_spec.lua; use vim.treesitter.query.parse directly (requires
  Neovim >= 0.9).

Author: sigfriedCub1990

lua/pytrize/api.lua

@@ -1,10 +1,14 @@
 local M = {}
 
+--- Clear pytrize virtual text from buffer.
+---@param bufnr? integer Buffer number (0 or nil for current buffer)
 M.clear = function(bufnr)
     local marks = require("pytrize.marks")
     marks.clear(bufnr or 0)
 end
 
+--- Set pytrize virtual text for parametrize entries in buffer.
+---@param bufnr? integer Buffer number (0 or nil for current buffer)
 M.set = function(bufnr)
     local cs = require("pytrize.call_spec")
     local marks = require("pytrize.marks")
@@ -38,24 +42,28 @@ M.set = function(bufnr)
     end
 end
 
+--- Jump to the parametrize entry declaration under cursor.
 M.jump = function()
     local jump = require("pytrize.jump")
 
     jump.to_param_declaration()
 end
 
+--- Jump to fixture definition under cursor.
 M.jump_fixture = function()
     local jump = require("pytrize.jump")
 
     jump.to_fixture_declaration()
 end
 
+--- Rename fixture under cursor across the project.
 M.rename_fixture = function()
     local rename = require("pytrize.rename")
 
     rename.rename_fixture()
 end
 
+--- Show all usages of fixture under cursor in quickfix list.
 M.fixture_usages = function()
     local usages = require("pytrize.usages")
 

lua/pytrize/call_spec.lua

@@ -1,8 +1,7 @@
 local M = {}
 
 local ts = vim.treesitter
-local ts_query = ts.query
-local parse_query = ts_query.parse or ts_query.parse_query
+local parse_query = vim.treesitter.query.parse
 
 local warn = require("pytrize.warn").warn
 local tbls = require("pytrize.tables")

lua/pytrize/health.lua

@@ -0,0 +1,39 @@
+local M = {}
+
+M.check = function()
+    vim.health.start("pytrize")
+
+    -- Check Neovim version
+    if vim.fn.has("nvim-0.9.0") == 1 then
+        vim.health.ok("Neovim >= 0.9.0")
+    else
+        vim.health.error("Neovim >= 0.9.0 required")
+    end
+
+    -- Check Python treesitter parser
+    local ok = pcall(vim.treesitter.language.inspect, "python")
+    if ok then
+        vim.health.ok("Python treesitter parser installed")
+    else
+        vim.health.error("Python treesitter parser not found", {
+            "Install with :TSInstall python (nvim-treesitter) or compile manually",
+        })
+    end
+
+    -- Check for grep (used by fixture rename/usages)
+    if vim.fn.executable("grep") == 1 then
+        vim.health.ok("grep command available")
+    else
+        vim.health.warn("grep not found — fixture rename and usages features will not work")
+    end
+
+    -- Check highlight group
+    local settings = require("pytrize.settings").settings
+    if vim.fn.hlexists(settings.highlight) == 1 then
+        vim.health.ok(string.format("Highlight group '%s' exists", settings.highlight))
+    else
+        vim.health.warn(string.format("Highlight group '%s' not found — virtual text may be invisible", settings.highlight))
+    end
+end
+
+return M

lua/pytrize/init.lua

@@ -23,6 +23,8 @@ local function setup_commands()
     end, { desc = "Show fixture usages in quickfix list" })
 end
 
+--- Configure the pytrize plugin.
+---@param opts? PytrizeSettings
 M.setup = function(opts)
     opts = opts or {}
     settings.update(opts)