chore(tools): make unreachable-code analysis runnable from the Taskfile

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.
This commit is contained in:
sam committed 2026-09-18 13:15:26 +10:00
1 parent c984cc6cbc
commit 8d0716900d
3 files changed
+159 -3

No files matched your search

+37
View File
@@ -93,6 +93,43 @@ tasks:
cmds:
- govulncheck ./...
deadcode:
desc: "Report functions no shipped binary can reach (whole-program RTA from ./cmd/...). Not part of task check: it reports a standing backlog, so gating on it would fail every run until that backlog is zero."
summary: |
Answers "is this reachable in production", which no linter does:
golangci-lint's unused check is package-scoped, so anything exported
and called from a sibling package looks live even when no binary
reaches it.
Run via `go run ...@latest` deliberately. A locally installed 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".
Building it against the repo toolchain makes that failure impossible.
-test=false is the point of the report: a function reached only by its
own tests is not reachable in production.
Read the output in one direction only. RTA over-approximates what is
reachable, so "unreachable func" is sound and worth acting on, while
silence proves nothing: interface dispatch and any address-taken
function (every reflect.ValueOf entry in the *extract tables) is
assumed reachable whether or not it is ever called.
cmds:
- go run golang.org/x/tools/cmd/deadcode@latest -test=false ./cmd/...
reachaudit:
desc: "Classify unreachable code as tracked / untracked / dynamic (tools/reachaudit). Wraps task deadcode with provenance and tracker status."
summary: |
deadcode says a function is unreachable. reachaudit says whether that
is a known gap, a forgotten one, or an artifact of runtime loading
(yaegi, reflection) that must never be deleted.
--refresh re-runs the analysis. Without it the tool reuses
/tmp/reachaudit-deadcode.txt with no staleness check, which will
happily report last week's tree against today's code.
cmds:
- python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}}
ui:deps:
desc: Install the dashboard's node dependencies (ui/node_modules is gitignored)
internal: true
+117
View File
@@ -0,0 +1,117 @@
# 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 module
- `test` — `_test.go`
- `generated` — matches the standard generated-file header, plus
`internal/contracts/**` and `ui/dist/`
- `dynamic` — a `reflect.ValueOf` table 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:
```json
{"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:
```sh
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:
1. Two distinct methods spelled `Register` on different types resolve to two
separate records, and a reference to one does not increment the other.
2. A symbol referenced only from `_test.go` reports `prod: 0`.
3. A symbol referenced only from a `reflect.ValueOf` table reports `prod: 0`
and `dynamic: 1`, not `prod: 1`.
4. A generated file's references land in `generated`, not `prod`.
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.
+5 -3
View File
@@ -67,8 +67,10 @@ def cmd_closure(repo: Path) -> set[str]:
def deadcode_findings(repo: Path) -> list[str]:
"""Run deadcode, or reuse a cached run. Falls back to an empty list with a
loud warning rather than silently reporting zero findings."""
cache = Path("/tmp/reachaudit-deadcode.txt")
if cache.exists():
head = run(["git", "rev-parse", "HEAD"], repo) or "unknown"
dirty = "-dirty" if run(["git", "status", "--porcelain"], repo) else ""
cache = Path(f"/tmp/reachaudit-deadcode-{head[:12]}{dirty}.txt")
if cache.exists() and not dirty:
return cache.read_text().splitlines()
print("running deadcode (this compiles the module, may take a minute)...", file=sys.stderr)
out = subprocess.run(
@@ -138,7 +140,7 @@ def consumers(repo: Path, pkg: str) -> tuple[int, int]:
def main() -> int:
ap = argparse.ArgumentParser()
ap.add_argument("--repo", default=str(Path.home() / "projects/archie-core"))
ap.add_argument("--repo", default=str(Path(__file__).resolve().parents[2]))
ap.add_argument("--json")
ap.add_argument("--md")
ap.add_argument("--refresh", action="store_true", help="re-run deadcode instead of using the cache")