feat(lint): add dead-code lint for flags and unexported helpers

[ktn-jamf]

Summary

• New standalone tool at scripts/lint-dead-code/ that AST-walks internal/commands/ and surfaces dead Cobra flag bindings + dead unexported helpers.
• Allowlist via Cobra Annotations["lint:keep-flag"] for flags and //lint:keep doc comments for funcs.
• Wired as a CI step (make lint-dead) with continue-on-error: true — warn-only for the first 2 weeks.
• Flips to exit-2 with --gate once we've burned in the heuristics.

Why

Inspired by cli-printing-press's dogfood structural verifier. As the
generator's surface grew, hand-written commands accumulate hidden tax:
flag variables that lost their last reader during a refactor, helpers
that no other path calls anymore. At our scale (~373 flag bindings in
internal/commands/, dozens of unexported helpers), grep+eyeball is too
unreliable to catch this on every PR. A 200-line AST walker run on every
push gives us mechanical confidence — and the same allowlist convention
(lint:keep-flag annotations, //lint:keep doc comments) generalises
to future structural verifiers (anti-reimplementation, MCP-surface-parity,
naming-consistency).

Behavior contract

Dead flags: call sites matching <cmd>.{Persistent}Flags().XVar(&backing, "name", ...) where the backing ident has zero reads anywhere in the same package besides the binding &IDENT and the declaration site. Scans test files too — test reads count as legitimate use.

Dead funcs: top-level unexported funcs in internal/commands/ (recursive, including pro/generated/ and platform/generated/) with zero same-package references besides the declaration. Skips init, main, Test*, Benchmark*, Fuzz*, Example*, and methods.

Allowlist (flags): add Annotations: map[string]string{"lint:keep-flag": "name1,name2"} to the owning *cobra.Command composite literal. Statically resolved on a best-effort basis — if the literal isn't statically resolvable, no allowlist applies.

Allowlist (funcs): add //lint:keep to the func's doc-comment group. Bare marker accepted for now; rationale convention may be enforced later.

First-sweep findings

$ go run ./scripts/lint-dead-code/
No dead flags or functions found.

Zero — the codebase is in good shape. The infrastructure is in place so we catch the next drift, not the current state. Will revisit if maintainers spot false negatives.

Test plan

• go build ./... passes
• go test ./... passes (new scanner tests + full suite)
• make lint clean (golangci-lint)
• make verify-generated passes
• make lint-dead runs cleanly (no findings)
• Four testdata fixtures (clean, dead-flag, dead-func, allowlisted) cover the positive + suppression paths

Warn-only for the first 2 weeks. After calibration we'll flip the CI step to make lint-dead -- --gate (exit-2 on findings) and drop the continue-on-error.

🤖 Generated with Claude Code