Add dead-code gate (vulture) - #21
Merged
Merged
Conversation
Adds tools/check-dead-code.sh, a vulture wrapper shared across the org, plus a whitelist and a CI step. The wrapper exists because the obvious vulture setup — excluding tests — makes anything used only by tests look dead, which is the largest single source of false positives. This scans tests so their usage counts, then drops findings whose location is a test file. Across the estate that took the raw finding count from 217 to 102 without a single judgement call; build artefacts and framework decorators account for the rest. The whitelist separates two things that are usually conflated: names vulture cannot see being used (framework contracts, wire formats), and names that appear genuinely dead but need a decision. The second section is a backlog, listed so the gate is green today and starts catching NEW dead code immediately.
Three entries were labelled by filename pattern rather than by what they are: bistatic_models.py matched a models.py rule, and the two *_nested_value helpers matched a config-field rule. The names and locations were right; only the explanatory comments were wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a vulture dead-code gate:
tools/check-dead-code.sh, a whitelist, and a CI step.Why a wrapper rather than calling vulture directly
The obvious setup excludes
tests/, which makes anything used only bytests look dead — the single largest source of false positives. This scans
tests so their usage counts, then drops findings whose location is a test
file, which is the behaviour you actually want.
Combined with excluding build artefacts (a stale source copy that doubles every
finding) and ignoring framework-dispatched decorators, that took the estate-wide
count from 217 to 102 without a single judgement call.
The whitelist has two sections, deliberately
Contracts — names genuinely referenced by something vulture cannot see:
stdlib
http.serverhandler methods,ssl.SSLContextattributes, generatedwire models. These are permanent.
UNREVIEWED — 27 entries in this repo that appear genuinely dead and
need a decision: delete, or finish wiring up whatever was left unfinished.
This section is a backlog, not an exemption. Nothing here has been deleted,
because "this config field is never read" usually means someone left work
half-done, and that is a call for whoever wrote it. Listing them keeps the gate
green today, so it starts catching new dead code from this PR onward
rather than waiting on a cleanup that may take weeks.
Verified
Gate passes on this branch, and fails (exit 1) when a dead function is added —
tested, since a gate that cannot fail is worthless.
🤖 Generated with Claude Code