Harden the dead-code gate's own test coverage

[jonnyspicer]

Follow-up to #1–#3, acting on a mutation-testing review of that work. The gate itself was sound; its tests proved less than they appeared to.

What mutation testing found

Each mutation was applied to check-dead-code.sh and the 9-test suite re-run:

Mutation	Before	After this PR
exit 127 → exit 2	9 passed ❌ missed	caught
bare cd "$TARGET" (no guard)	n/a	caught
DECORATORS=""	9 passed ❌ missed	caught
delete vulture_whitelist.py pickup	9 passed	correctly not caught — see below
EXCLUDE=""	caught	caught, but for the wrong reason — see below

Suite goes 9 → 14.

Changes

Assert exit 127 exactly. 127 is this gate's entire contract and was only asserted as "non-zero", so changing it to 2 passed cleanly.

Guard the cd. A bare cd "$TARGET" exits 1 under set -e when the target is missing or is a file — the same code as "dead code found". A typo'd args: [backedn] in a consumer would surface in CI as if dead code had been found. Now exits 2 (this script's existing "bad usage" code) and names the target.

Make try-repo a real test. ops contains zero .py files, so pre-commit try-repo . dead-code --all-files scanned nothing — it proved entry:/language: resolve but could not distinguish "ran" from "no-opped". Replaced with a positive control: planted dead code must make the hook FAIL and name the symbol, then pass once removed.

Two behaviour tests with concrete consumers. vulture_whitelist.py suppression, and --ignore-decorators — the latter because Tower-Finder's backend is the Flask/FastAPI app here, and @app.*,@bp.*,@router.* is the only thing stopping every route handler reading as dead. If that broke, its CI would fill with false findings, and the plausible human response — deleting "unused" handlers — is worse than the gate failing outright.

Two findings worth recording rather than fixing

The whitelist pickup is inert, not untested. The review called check-dead-code.sh:65 "the single line keeping six consumers green" because deleting it failed no test. That premise is wrong — vulture already picks up vulture_whitelist.py when it walks ., so passing it explicitly changes nothing:

whitelist present, not passed explicitly  -> rc=0, no findings
whitelist present, passed explicitly      -> rc=0, no findings   (identical)
whitelist REMOVED                         -> rc=3, finding reported

The mutation is behaviour-preserving, so no test should fail. The line keeps an explanatory comment rather than being removed — it is harmless, and changing the shared script for zero behavioural gain would need a version bump to reach six consumers. A mutation that no test catches is either a coverage gap or proof the code does nothing; the two are not distinguishable without checking whether behaviour changed.

EXCLUDE="" is caught for the wrong reason. vulture's prepare_pattern() turns an empty exclude into **, which matches everything — so all four failures share one symptom (nothing gets scanned at all) rather than four tests independently validating exclude semantics. Losing a single token such as build has a real, independent effect and would not be caught. Left open deliberately and recorded here so it is not rediscovered as news.

Consumer impact

None. All six pin dead-code-v1.0; this lands on main ahead of that tag and reaches them at the next deliberate version bump. No tag is created here.

🤖 Generated with Claude Code

https://claude.ai/code/session_013ZcazeseXVpu8XrYA2tE1V