feat(find_symbol): report searched kinds, index module/class variables

[andrebrait]

Problem

find_symbol searches functions and classes — and only those. _resolve_symbol_info reads meta.functions and meta.classes on both its symbol-table fast path and its all-files fallback, and StructuralMetadata has no field for anything else. That has been true since the first commit; there is no variables field to consult.

The failure mode is not the missing coverage, it is what a miss claims:

{"error": "symbol 'pfb' not found", "scanned_files": 2085, "complete": true}

plus a docstring promising callers they "do not need to fall back to grep/search_codebase". pfb in that project is a module-level dict referenced 317 times in a single file. An agent that trusts complete: true concludes the symbol does not exist and stops looking.

Changes

1. Honest miss reporting. A miss now returns the kinds it actually searched, and — when an indexed kind was excluded — what it skipped plus the exact retry:

{
  "error": "symbol 'pfb' not found",
  "scanned_files": 2085,
  "searched": ["function", "class"],
  "not_searched": ["variable"],
  "retry_with": "find_symbol(name='pfb', kinds=['variable'])"
}

complete: true stays on the hit path, where it is accurate. The MCP _suggestion leads with the retry instead of sending the caller straight to grep.

2. kinds parameter and variable indexing. find_symbol(name, kinds=[...]) takes function, class, and variable. Variables cover module globals, constants (UPPER_SNAKE or a Final[...] annotation), and class attributes. The Python annotator extracts them from Assign / AnnAssign at module and class scope. Function locals are skipped — they cannot be referenced from another module, so indexing them would grow the index without making anything findable. AugAssign is skipped as well: x += 1 rebinds an existing name, so treating it as a definition would report the wrong line.

Bindings go in a new ProjectIndex.variable_table (bare name and qualified name → defining files), deliberately not in symbol_table:

• a module global can never shadow a same-named function in the resolvers that walk symbol_table;
• same-named globals across files (logger, DEFAULTS) are routine, so the value is a list and a collision reports as ambiguous rather than silently picking a winner.

3. TOKEN_SAVIOR_VARIABLES gates both halves:

value	effect
off	annotators skip extraction; an explicit kinds=["variable"] is rejected with an explanation, rather than returning an empty result that reads as "no such variable"
index (default)	variables are indexed, searched only when requested
search	variables are indexed and included in the default kinds

Read per call, so it can be flipped without a server restart.

Compatibility

• _CACHE_VERSION 2 → 3. The new variables field is persisted; a stale v2 cache would report every project as variable-free.
• Default kinds is the previous behaviour, so existing callers see no change apart from the richer miss payload.
• The MCP handler forwards kinds only when the caller sets it, so query engines with the older two-argument find_symbol signature keep working.
• Annotators other than Python leave variables empty. searched / not_searched report that honestly instead of hiding it. Adding extraction to another annotator is now a per-language change with no further plumbing.

Tests

tests/test_symbol_kinds.py, 24 tests: miss reporting, extraction (module/class scope, constant detection, locals excluded), kinds lookup and isolation, ambiguity, all three env-var modes, cache round-trip, and a guard that the cache version was bumped. Full suite: 1813 passed, 1 pre-existing failure (test_daemon_client.py::test_successful_call_returns_text — pytest's tmp_path exceeds the 104-byte macOS AF_UNIX limit; unrelated to this change and green on the same machine under a shorter path).

ruff check src/ tests/ clean.

One doc gap left deliberately: the new variable is documented in the variables_mode() docstring rather than the README, since the README has no environment-variable reference yet (#56).

[Mibayy]

Merged as 30daf13 on main, with you as the commit author.

Not via the merge button, and the reason matters: main had its history rewritten today to purge a leaked credential and some customer data from the public repo. Your branch predates that rewrite, so merging it would have pushed the purged commits straight back in. I cherry-picked your commits onto the new main instead. Same content, same authorship, no reintroduction.

Full suite green (2044 passed) and CI green on main.

If you send more PRs, please rebase on the current main first, otherwise the diff will look enormous and the merge button stays unsafe.

Thanks for the work, it was accurate and well tested.