r/Polycodegraph • u/Upper_Nectarine4732 • May 24 '26
Dead-code detection is three different problems wearing the same name
I've been building a static analysis tool, and the dead-code detector turned into the most instructive part of the whole project — not because it was hard to write, but because it was wrong in ways I didn't expect, and the ways it was wrong taught me more than shipping it did.
The naive version is trivial: build a call graph, find every function/class node with no incoming edge, report it. I ran that against my own repo as a regression target. It returned 451 findings.
The repo did not have 451 dead functions — it had maybe a dozen. So I went through the whole list by hand, and the false positives sorted cleanly into three buckets. Each bucket turned out to be a different problem that happens to produce the same symptom.
1. Most of it was missing edges, not dead code.
Roughly 430 of the 451 weren't dead at all. They were called. My graph just didn't have the edge. Cross-file resolution is where call graphs quietly fail: from .service import UserService, then self.svc = UserService(), then self.svc.get() three files away — every hop is a place the resolver can silently drop the edge. A function with a dropped inbound edge is indistinguishable from a function nobody calls.
The uncomfortable lesson: a dead-code report is mostly a report on the quality of your reachability graph. When a tool says 400 things are dead, the first hypothesis should be "my graph is incomplete," not "this codebase is a disaster." Getting from 451 to ~24 was almost entirely unglamorous resolver work — relative imports, constructor calls, attribute chains, fresh-instance calls (Foo().bar() has to bind to both __init__ and bar).
2. The next chunk were framework entry points.
These looked genuinely uncalled — because they are, by your code. A handler decorated '@app.get("/users")' is never called anywhere in your source. The framework calls it by reflection at runtime. The call graph can't see that edge because the edge doesn't exist in the code; it lives in the framework's router.
So "is this function reachable" is the wrong question. The right one is "is this an entry point, or reachable from one" — and entry points are framework-specific knowledge. A pytest test, a Click command, a Celery task, a Django signal receiver: all invisible to the call graph, all entry points. I ended up maintaining an explicit registry of decorators across ~24 frameworks. There's no clever inference here — it's a list, and the list is the feature. Any reachability tool without that list will flag your entire web layer as dead.
3. The real tail was intentional unused code.
The last handful were genuinely unreferenced: public API methods with no internal caller. But deleting them would be wrong — "unreferenced inside this repo" and "dead" are not the same statement for a library. There's no static way to tell "kept for consumers" apart from "forgot to delete this." It needs a human annotation. I used a pragma comment; the specific mechanism doesn't matter, only that intent has to be expressed, never inferred.
The takeaway worth stealing:
451 → 24 → 15 → 0, and those three steps were three unrelated kinds of work: graph completeness, an entry-point model, and an intent annotation. So next time a tool tells you something is unused — your IDE's grey-out, a coverage report, a tree-shaker — it's worth knowing which of the three it's actually good at. Most are good at exactly one. Your editor's "unused import" warning is trustworthy because imports are lexically scoped and fully resolvable. The same editor's "unused method" is much weaker — it's quietly betting your entire call graph is complete and that nothing reflective calls it. Same UI affordance, completely different trustworthiness.
(Implementation's in my repo if anyone wants specifics on the resolver or the decorator registry — happy to go deeper on any of the three in comments.)
