test: 241 unpinned mutants in the AST extractor walkers (down from 368) — language extractors have almost no behavioural tests

[cdeust]

Context

Surfaced while fixing the unbounded AST recursion in the extractor layer (branch fix/ast-walk-type-recursion-depth). A scoped mutation run over the five extractor modules shows the language walkers are largely unpinned by tests.

Measured 2026-08-06, same tool selection both sides:

scripts/mutation_check.sh \
  "tests_py/core/test_ast_extractors.py tests_py/core/test_ast_parser_extra_langs.py tests_py/core/test_ast_extractor_depth.py" \
  mcp_server/core/ast_extractors.py mcp_server/core/ast_extractors_jvm.py \
  mcp_server/core/ast_extractors_clike.py mcp_server/core/ast_extractors_scripting.py \
  mcp_server/core/ast_extractors_extra.py

	mutants	killed	no tests	survived
HEAD (before the recursion fix)	1554	475	851	228
after the recursion fix	1486	571	492	423

The survived column rising while no tests falls is reclassification, not regression: the new depth tests execute code that no test reached before, so mutants moved from "never run" into "run but not detected". The honest metric is not-killed = survived + no tests, and it improved in every walker:

function	HEAD not-killed	after
_walk_for_calls	40	13
_walk_java	59	37
_walk_kotlin	77	54
_walk_csharp	59	36
_walk_ruby	53	33
_walk_php	61	51
_extract_swift_node	19	17
_walk_type	0	0
total	368	241

The gap

241 mutants remain unpinned in those seven walkers, and 423 across the five modules in total. Concretely, the Java, Kotlin, C#, Ruby, PHP and Swift definition extractors have almost no behavioural tests: tests_py/core/test_ast_extractors.py covers Python, JS and Go only, and test_ast_parser_extra_langs.py is thin.

This is pre-existing debt, not introduced by the recursion fix, which is why it was not treated as a blocker on that PR (rules/coding-standards.md §12.5: the per-commit tier does not punish a change for a pre-existing gap). It is filed here rather than left as prose, per §14.3.

Notable non-walker survivors in the same run, same cause: _extract_rust_node 51, extract_go_definitions 34, _extract_js_node 20, _extract_python_class 16, _extract_python_func 15, _collect_call_basenames 14.

Why it matters beyond the score

These extractors decide what enters the code graph. A silent behaviour change in one of them (a wrong qualified name, a dropped nested class, a method attributed to the wrong scope) degrades every downstream consumer — ingest_codebase, wiki reference pages, unified_search — with no failing test and no visible signal. The recursion fix had to lean on a purpose-built differential harness against the old implementation over 2229 sources precisely because the test suite could not have caught an ordering regression.

Acceptance criteria

1. Behavioural tests for the six language extractors covering, per language: top-level function, class/type with methods, nested type, unnamed/anonymous construct, and the qualified-name shape (Type.method).
2. Not-killed count for the seven walkers is 0, or each remaining mutant is documented as equivalent with a written rationale at the use site (§12.1).
3. The same scoped mutation_check.sh invocation above is the verification command, and its output is quoted in the PR.
4. Consider promoting these modules into memory/critical-zones.conf so the sweep tracks them (§12.5).

Note on the tooling

scripts/mutation_check.sh reported none — 0 surviving mutants 🎉 on this run while its own progress counter ended at 🙁 423. The survivor list from mutmut results is 915 lines and non-empty. The script's grep-based survivor detection therefore produced a false green here; the cleanup trap deletes mutants/ and .mutmut-cache on exit, so the discrepancy cannot be investigated after the fact. Worth a separate look — a mutation gate that can report a false clean is worse than no gate.

[cdeust]

Walker half closed by #373 (merged)

	at filing	now
not-killed, seven walkers	241	6, all documented equivalents
killed, five extractor modules	571	847

tests_py/core/test_ast_extractor_walkers.py pins Java, Kotlin, C#, Ruby, PHP and Swift with exact ordered (name, kind) assertions. Acceptance criteria 1 and 2 are met for the walkers.

The six remaining are equivalents, each with a rationale at the use site: three because the body node is reachable via the catch-all regardless of the mutation, two tied to #372, one because the else "" name fallback is unreachable in every grammar in use.

Criterion 3's tooling note is also closed: scripts/mutation_check.sh now cross-checks two independent survivor counts and refuses to render a verdict when they disagree, instead of printing a false green.

What is still open here

The runner is file-granular, so it mutates every function in the five modules, not just the seven walkers. It exits 1 with 177 survivors in functions this PR did not target:

• _extract_rust_node
• extract_go_definitions, _extract_go_receiver, extract_go_imports
• _extract_python_class, _extract_python_func, _extract_python_decorated, _extract_python_children
• _extract_js_node, _extract_js_class
• _collect_call_basenames, _text
• the six extract_*_definitions entry points

Same treatment applies: exact-output behavioural tests, then triage what survives. _extract_rust_node (51) and extract_go_definitions (34) are the two biggest and the obvious next slice.

Criterion 4 — promoting these modules into memory/critical-zones.conf — is untouched and should probably wait until the file-level count is low enough that the sweep is informative rather than noise.

[cdeust]

Closed by #376 (merged).

Final state

	at filing	now
unpinned mutants, five extractor modules	639	51
mutants no test executes	462	0
killed	847	1435 of 1486

Acceptance criteria 1–3 are met. Every public entry point in the five modules has an exact-output test, and every remaining survivor carries a written rationale at the use site, split into provably equivalent by construction and unreachable today — those two claims age differently and a future reader needs to know which they are looking at.

Criterion 4 (promoting these modules into memory/critical-zones.conf) is not done and should not be until the item below is resolved.

The gate cannot express this result

scripts/mutation_check.sh still exits 1 on these files and always will. It has no notion of an accepted equivalent, so a module where every survivor has a rationale is indistinguishable to it from one nobody has examined. That makes the blocking per-commit tier unusable on these five files for any future one-line change.

I deliberately did not invent a suppression mechanism, because a loose one would recreate the false green this same script had before #373 — it reported 0 surviving mutants on a run whose own counter said 423. What it needs is a typed, registered, fail-closed exemption keyed to an individual mutant with a mandatory rationale, so an unlisted survivor still fails and a listed one still has to justify itself.

Filing that as its own issue is the sensible next step; it is a gate-design decision, not a test-coverage one.

Rough edges surfaced, not fixed

Seven behaviours are now pinned as current behaviour with their cause, each a plausible resolution defect worth its own decision: C emits a struct twice when a typedef names it; C++ drops struct while C keeps it; Rust drops functions inside mod {} and keeps use a::{B,C} / as clauses verbatim; Python drops import os.path as p; JS ignores require() and new; PHP group-use loses its prefix.

Related: #372 (decorator calls produce no graph edge).