fix(mutmut): re-verify survivors against full test selection before trusting them (#269)

[cdeust]

Summary

Closes #269. scripts/mutation_check.sh false-reported 50 survivors for
ast_extractor_registry.py's _make_extractor/build_extra_extractors:
mutmut's per-mutant test attribution is recorded once, from a coverage
trace of the FIRST test whose call reaches the mutated line. Since
ast_parser._EXTRACTORS = {..., **build_extra_extractors()} builds its
dispatch table once, eagerly, at import time, every test after the
first exercises the already-built, cached closures without ever
re-invoking the mutated functions — mutmut narrowed the per-mutant
rerun to one (often irrelevant) test and reported "survived" for all 50
mutants even though the full 3-file test selection genuinely kills
every one.

scripts/mutation_recheck_survivors.py closes the gap generically,
for any source file, not by special-casing this one: every mutant
mutmut reports "survived" is re-run against the FULL declared test
selection before the verdict is trusted. A mutant the full selection
kills is reported as RECOVERED — a distinct, visible category,
never silently folded into "killed" (a false-survivor report otherwise
either blocks a correct commit or trains reviewers to wave off real
survivors as "probably a tooling artifact", the exact silent-failure
risk §12 exists to close).

scripts/mutation_check.sh also gained multi-file test-selection
support (<test_paths> now accepts a space-separated list), which
turned out to be load-bearing, not cosmetic: reproducing the issue
requires ast_parser.py in the same mutation scope, because mutmut's
own forced-fail bootstrap check needs something in scope that gets
re-invoked on every test (mutating ast_extractor_registry.py alone
starves that check — nothing in it is ever called more than once per
process — and mutmut run aborts with "Unable to force test failures"
before producing any per-mutant result at all).

Re-running the full reproduction surfaced one genuine (non-false)
survivor the current mutmut version (3.6.0) generates that the
issue's original reproduction did not: _make_extractor__mutmut_10
replaces the source argument to the calls-extractor with None,
invisible to every existing per-language test because
extract_calls_generic's hardcoded node-type list ("call"/
"call_expression") never matches any of the 7 languages' own
call-expression node type (Java's is method_invocation, for
instance — a separate, pre-existing, out-of-scope language-coverage
gap). A new test, test_make_extractor_threads_the_real_source_into_calls_extraction,
monkeypatches extract_calls_generic to assert _make_extractor's own
composition contract directly, closing it without touching that
unrelated gap.

Layer assignment (Move 1)

• scripts/mutation_recheck_survivors.py — new, pure decision logic
  (parse/recheck/format) plus a thin I/O boundary (default_runner,
  injected everywhere else); lives beside scripts/mutation_check.sh,
  the other repo-tooling script in this family.
• scripts/mutation_check.sh — orchestration only (bash), unchanged role.
• tests_py/scripts/test_mutation_recheck_survivors.py,
  tests_py/core/test_ast_extractors_multilang.py — tests.
• Doc-count resync (README/CONTRIBUTING/CLAUDE.md/ASSURANCE-CASE/
  .bestpractices.json/badge SVG) — required by this repo's
  suite-size-is-hardcoded convention; not a design change.

Stakes calibration (Move 7)

• Classification: Medium. Repo tooling (not auth/billing/crypto/
  concurrency/data-integrity), but load-bearing for every future PR's
  mutation gate. Full Moves 1–5 applied anyway given the depth of the
  investigation required.

Completion Ledger

Path in diff	Test/evidence
parse_survivors — extract "survived" mutant names	ParseSurvivorsTests (5 tests: normal, none, empty, dedup, substring-immune)
recheck_survivor — re-run one mutant against full selection	RecheckSurvivorTests (7 tests: exit 0/nonzero, env var, base_env non-mutation, exact cmd, cwd, mutant_name passthrough)
recheck_all_survivors — empty short-circuit / ValueError / per-survivor recheck	RecheckAllSurvivorsTests (4 tests, incl. exact ValueError message + mutants_dir forwarding)
any_genuine_survivors	AnyGenuineSurvivorsTests (3 tests)
format_report — empty / all-recovered / all-genuine / mixed	FormatReportTests (4 tests, exact-string equality)
_main — argv validation, stdin parse, exit codes 0/1/2, stdout/stderr content	MainCliTests (9 tests, incl. exact usage text, exact printed report)
default_runner (real subprocess boundary)	exercised end-to-end via the real mutation_check.sh runs below, not unit-mocked (Move 5: thin I/O boundary)
mutation_check.sh multi-test-path splitting + -- separator	manual end-to-end runs against ast_extractor_registry.py + ast_parser.py (3-file selection) and against json_native.py (1-file selection, unchanged behavior)
mutation_check.sh survivor recheck wiring	same end-to-end runs; RECOVERED/GENUINE split observed correctly both times
new _make_extractor calls-threading test	test_make_extractor_threads_the_real_source_into_calls_extraction; kills x__make_extractor__mutmut_10 (confirmed via targeted mutation run)
doc-count resync (6560→6593)	scripts/check_doc_claims.py --test-count 6593 exit 0, scripts/generate_repo_badges.py --check --test-count 6593 exit 0, full suite 6593 passed, 117 subtests passed

Verification

• scripts/mutation_recheck_survivors.py mutation-tested against its own new test file: 0 surviving mutants (final run, after three iterations closing string-literal/argument-forwarding/exact-output gaps the first two runs surfaced).
• ast_extractor_registry.py + ast_parser.py mutated together against the 3-file selection: 0 genuine survivors in _make_extractor/build_extra_extractors (all 53 reported "survived" by mutmut are RECOVERED); the 33 remaining GENUINE survivors are all in ast_parser.py's OTHER, unrelated functions (is_available, parse_file_ast, _node_text, _extract_module_doc, _extract_python, _extract_js) — pre-existing, out of this issue's stated scope, and NOT part of this PR's shipped [tool.mutmut] scope (still json_native.py in the committed pyproject.toml).
• json_native.py scoped run unchanged: same 5 documented-equivalent survivors as before (no regression).
• ruff check . / ruff format --check .: clean. shellcheck scripts/mutation_check.sh: clean.
• Full suite: 6593 passed, 117 subtests passed (exit 0).

Unresolved (evidence, not a ticket — flagging per this run's instructions)

Mutating ast_extractor_registry.py together with ast_parser.py (required for mutmut's own forced-fail bootstrap to succeed at all when reproducing this issue) surfaces 33 genuine, pre-existing mutation survivors in ast_parser.py's own functions, unrelated to _make_extractor/build_extra_extractors: is_available (2), parse_file_ast (5), _node_text (2), _extract_module_doc (11), _extract_python (1), _extract_js (2). None of these are false-survivor artifacts of this issue's root cause — they are real test gaps in a ~250-line file spanning six independent functions, each likely needing several new precise tree-sitter-AST assertions. This is genuinely outside #269's stated acceptance criteria (which name only the two ast_extractor_registry.py functions) and outside this PR's shipped [tool.mutmut] scope (the committed scope stays json_native.py; my diagnostic widening to include ast_parser.py was reverted after each run). Evidence: /tmp/mut_run2.log-equivalent local run, mutant names listed in this PR body's Verification section above. Leaving this for the coordinator to decide whether it warrants its own follow-up PR (not filing an issue per this run's explicit instruction).