Add `task deadcode` (whole-program RTA from ./cmd/...) and `task reachaudit` (the existing classifier on top of it). Neither joins `task check`: both report a standing backlog, so gating on them fails every run until that backlog is zero, same as `task vuln`. `task deadcode` shells to `go run ...@latest` rather than a local binary on purpose. A deadcode built against an older Go than this module exits non-zero and prints nothing, which reads as "no dead code" instead of "analysis failed" -- the locally installed copy was built against 1.26 against a 1.27 module and had been silently reporting an empty tree. reachaudit had two traps that made it answer confidently from nothing: its --repo default pointed at a path that does not exist on either machine, and it reused /tmp/reachaudit-deadcode.txt with no staleness check, so it would serve a previous tree's analysis indefinitely. Key the cache on HEAD and refuse it outright when the tree is dirty. Also lands the design for tools/symbolrefs, the type-resolved reference index that covers what reachability cannot: RTA treats every address-taken function as live, so every reflect.ValueOf entry in the *extract tables launders a dead symbol into a reachable-looking one, and deadcode reports functions only, leaving dead package vars unrepresentable.
5.3 KiB
Type-resolved symbol reference index (tools/symbolrefs)
Status: proposed. Single-file Go tool in the tools module.
The gap
Three questions get asked constantly during audits, and each currently gets answered by a different unreliable method:
| Question | Today | Problem |
|---|---|---|
| Is this reachable from a shipped binary? | task deadcode |
Sound but incomplete, functions only |
| Who references this symbol? | grep / ast-grep |
Matches spelling, not identity |
| Is this package in any binary? | tools/reachaudit |
Package granularity |
The middle row is the hole. grep -rn "Register(" cannot tell
plugin.Registry.Register from captureintake.Receiver.Register from
forgerpc.Server.Register, all of which exist here. It also matches the three
sibling checkouts under .worktrees/, which are near-complete copies of the
module, so every count is inflated by a factor nobody notices.
This matters because reachability alone does not settle a finding. RTA
over-approximates: it assumes every address-taken function may be called, and
every reflect.ValueOf entry in wfextract, gateextract, pluginextract,
secretextract and logextract is address-taken. deadcode is therefore
silent on worktree.Manager.Resume despite it having zero callers anywhere in
the tree. deadcode also reports functions only, so a dead package var like
secret.DefaultRegistry is structurally invisible to it.
A reference index answers what reachability cannot: a symbol with zero non-test reference sites is dead regardless of what RTA believes about its address. The two reports are complementary, and neither subsumes the other.
What it does
packages.Load over the root module with NeedTypes | NeedTypesInfo | NeedSyntax | NeedDeps, then for every identifier in every file resolve
TypesInfo.Uses[ident] to a types.Object and attribute the reference to its
declaring object. Identity comes from the type checker, so spelling collisions
and sibling worktrees both disappear: go list resolves by import path and
never walks .worktrees/.
Each reference site is classified by the file that holds it:
prod— an ordinary non-test file in the moduletest—_test.gogenerated— matches the standard generated-file header, plusinternal/contracts/**andui/dist/dynamic— areflect.ValueOftable or other runtime-loading site, which means static analysis cannot see the real caller
dynamic is a separate class rather than folded into prod because the whole
point is to stop those sites laundering a dead symbol into a live-looking one.
Output is JSONL on stdout, one record per package-level declaration:
{"symbol":"internal/worktree.Manager.Resume","kind":"method",
"decl":{"file":"internal/worktree/worktree.go","line":261},
"refs":{"prod":0,"test":4,"generated":0,"dynamic":0},
"sites":[{"file":"internal/worktree/worktree_test.go","line":88,"class":"test"}]}
So the query that took me six hand-run greps this session becomes one line:
task symbolrefs | jq -c 'select(.refs.prod == 0 and .refs.dynamic == 0)'
Scope
In: package-level funcs, methods, types, vars, consts in the root module.
Out: local variables, struct fields, reachability (that is task deadcode),
and any write path. The tool is read-only and advisory. It never proposes
deletion, matching reachaudit's existing stance.
Decisions
Single file, tools/symbolrefs/symbolrefs.go. It is dev tooling, not
product code, so it belongs beside docsgen and contractaudit in the tools
module rather than under internal/. That module is already covered by
task test:tools, which task check runs.
No persisted index. deadcode does whole-program RTA in under 7 seconds;
this does strictly less work (no SSA, no call graph). Anything cached becomes a
rendered view that outlives its evidence, which is the exact failure that made
STATUS.md claim 90 of 91 findings re-verified while most statuses were 77
commits stale, and the same reason reachaudit's /tmp cache had to be keyed
on HEAD. Recompute; do not reconcile.
Not in task check. It reports a standing backlog, so gating on it fails
every run until the backlog is zero. Same rationale as task deadcode and
task vuln.
No new dependency. golang.org/x/tools is already in go.sum at v0.49.0.
How it is verified
Red first, per the repo protocol. The tests are table-driven against small
fixture modules built in t.TempDir(), asserting the classification that
distinguishes this tool from grep:
- Two distinct methods spelled
Registeron different types resolve to two separate records, and a reference to one does not increment the other. - A symbol referenced only from
_test.goreportsprod: 0. - A symbol referenced only from a
reflect.ValueOftable reportsprod: 0anddynamic: 1, notprod: 1. - A generated file's references land in
generated, notprod.
Mutation-verify each: reintroduce the conflated behaviour and watch the
assertion fail, per HANDOFF.md rule 5.
Acceptance is a live cross-check, not a unit test: run it against the tree and
confirm it reports prod: 0 for worktree.Manager.Resume,
webui.NewDangerousService and secret.DefaultRegistry, all three of which
were confirmed dead by hand this session and all three of which deadcode
either missed or could not represent.