deadcode: add the two analyzers that can find dead code under internal/

[Philip Lombardi (plombardi89)]

Step 1 of #670: the tooling, as a report rather than a gate. This PR adds no deletions — those are split by component across eight sibling PRs listed at the bottom.

The problem #670 describes

unused cannot see dead exported code under internal/. That is a documented design decision, not a gap. From honnef.co/go/tools, unused/unused.go:48-62: a package uses its exported named types, and a named type uses its exported methods. Every method on an exported type is therefore transitively live because the type is exported, however provably closed the package is. staticcheck's whole-program mode, which did consider that, was removed.

The problem #670 does not describe

x/tools/cmd/deadcode, the tool the issue proposes, does not detect the seven LinkManager methods the issue was filed about:

$ go tool deadcode -whylive=...netlink.LinkManager.SetLinkNoARP ./...
deadcode: ...LinkManager.SetLinkNoARP is reachable only through reflection

x/tools/go/callgraph/rta/rta.go:281-287,433-437 — an ssa.MakeInterface calls addRuntimeType, which marks every exported method of that type reachable, because reflection could call any of them. RTA is sound with respect to reflection by design and this is the price: one var i any = x anywhere in the program buys every exported method on x's type a clean bill of health for the rest of the analysis.

Which is the same blind spot as unused, arrived at from the other direction. Adding deadcode alone would have closed the issue on a tool that cannot see the case that prompted it.

So this adds two analyzers, not one.

What make deadcode does

Four scans, one report. Nothing is wired into CI and nothing fails the build.

golang.org/x/tools/cmd/deadcode is pinned as a third tool directive next to govulncheck and controller-gen. hack/cmd/deadcode-report owns the verdict, following the split make vulncheck already uses: the analyzer emits JSON, is never asked for a verdict, and a non-zero exit means the scan itself failed. An input that decodes to zero packages is treated as a failed scan rather than a clean tree, because a truncated run is otherwise indistinguishable from one.

Two axes are crossed because both change the answer:

• Tags. deadcode's own documentation says results hold for a single GOOS/GOARCH/-tags configuration. The tree is scanned once per tag set and the results intersected. DEADCODE_TAGS is kept in step with run.build-tags in .golangci.yaml; a tag in one list and not the other is code one of the two never looks at.
• -test. Without it, code reachable only from a test reads as dead. That is the signal that matters when a production caller is deleted and its test is not, so both runs are kept and reported separately. Writing a test for dead code moves it between sections rather than resolving it.

hack/cmd/unreferenced asks the cruder question the reflection rule cannot swallow: does any identifier, in any package, in any test, under any build tag, denote this declaration? It covers funcs, methods, types, aliases, consts and vars.

The two are complementary and neither subsumes the other. A cluster of dead functions that only call each other reads as referenced by one and dead by the other. Self-reference is excluded so a recursive dead function is still reported; method receivers are excluded so a type whose only remaining mentions are its own methods' receivers cannot keep itself alive. Struct fields are deliberately out of scope: between struct tags, encoding/json and reflection, a reference count says very little about them.

The filter that decides whether the output is useful or dangerous

wqProvider.NewDepthMetric is not named anywhere in this tree and deleting it would break client-go's workqueue.MetricsProvider. Any method whose receiver implements an interface declaring a method of that name is dropped, with the interface recorded, and the count is always printed so a suppression is never silent. Interfaces are collected from every transitive dependency, which is what covers slog.Handler, prometheus.Collector and yaml.Unmarshaler. On this tree it suppresses 332.

What it found

Run against main, before any of the sibling PRs:

	Reported
Unreachable from any binary or test	80
Reachable only from tests	151
Unreferenced declarations	120

Three classes that neither a grep nor deadcode alone could reach:

• NetlinkCache.LinkList and AddrList. The names occur throughout the package and the node agent, but every one of those is vishvananda/netlink's package-level function, not the cache method that shadows it.
• Three unexported constants invisible to unused because a group-mate of each is live.
• A dead method → dead field → dead client-factory-call chain in forge, which field-writes-are-uses makes structurally invisible.

Tests

hack/cmd/deadcode-report has ten tests covering intersection across tag configurations, line-number drift (identity is the declaration, not its position), the test-only section, generated and marker exclusion, and the empty-input-is-a-failure contract.

hack/cmd/unreferenced is tested against two fixture modules under testdata/, asserting the exact finding set: a dead method on a type boxed into an interface is reported, a method needed for fmt.Stringer is not, a test-file declaration is never a candidate, a generated file is skipped, self-reference and method receivers do not count as uses, and a reference under any one tag configuration keeps a declaration alive under all of them.

A note for step 2 of #670

The sibling PRs exposed a property worth knowing before anyone designs the gate: removing a caller makes its callees dead in turn, and neither analyzer can report the second round until the first has landed. Re-running after the deletions surfaced four more findings, one of which was NetlinkCache.HasLink, whose only callers were two of the seven methods from the issue. A gate should expect to need more than one pass after a large deletion.

The rest of the sweep

Deletions are split by component, each independent of the others and of this PR:

• net: delete unreachable and unreferenced code in netlink, ebpf and metrics #675 — net: netlink, ebpf, metrics, config (includes the seven methods from Dead exported code in internal/ is invisible to unused; evaluate x/tools deadcode #670)
• net: delete the superseded node-CIDR controller #676 — net: the superseded node-CIDR controller
• gantry: delete unused fakes, options and the unadopted log vocabulary #677 — gantry
• kube, forge: delete unused cluster and Azure helpers #678 — kube, forge
• agent: delete unreferenced helpers and unread constants #679 — agent
• metalman: delete unreferenced helpers #680 — metalman
• operator, orca, playpen: delete unreferenced helpers #681 — operator, orca, playpen
• hack: delete unreferenced dev-tooling helpers #682 — hack dev tooling

Merging this one first lets reviewers of the other eight run make deadcode on their branch to confirm the report is clean for their area. There is no code dependency either way.

Unobserved Prometheus metrics found during the sweep are tracked separately in #672.

Refs #670