chore(knip): clear the parked dead-code backlog and drop the ceiling to 0

[hubgan]

Built on top of #769, so this PR carries that commit too — the workflows only run for PRs targeting main, which is why it is based there rather than on the branch. #769 on its own is the minimal, low-risk fix for the currently-red job; if it merges first this shrinks to its own commit, and if this one merges first it closes #769 as well.

What this does

#572 landed the gate with 215 findings parked under --max-issues. That bounded the backlog but left it in place, and the first thing to touch it (#663) pushed the total to 218 and turned the job red. This clears the backlog and sets the ceiling to 0, so the next unused export fails the job instead of consuming headroom nobody knew was there.

	before	after
Unused exports	47	0
Unused exported types	156	0
Unused exported class members	12	0
--max-issues	215	0

Scope check first

Every workspace holding a finding is private: true. @swmansion/argent — the one published package — had zero, so nothing here moves a public API.

Two shapes of fix

Still referenced inside its own file → drop export (146 types, 36 exports). The declaration stays put; it just leaves the module's public surface. tsc keeps emitting these into the .d.ts as local declarations that the exported signatures reference.

For the 146 types that is the whole story: they are erased, so the emitted .js is byte-identical. For the 36 values it is not. Dropping export from a const/function/class removes its exports.X binding from the emitted dist/*.js — 36 declarations across 26 files here. packages/tool-server/dist/utils/device-info.js no longer carries exports.REMOTE_PREFIX or exports.VEGA_SERIAL_PREFIX; telemetry/dist/posthog.js loses exports.POSTHOG_PROJECT_TOKEN; in the ESM-emitting argent-installer, isTempRunnerPath / resolveLocalArgentDir / PACKAGE_ROOT leave the module namespace object entirely.

Nothing in the repo or in the packages/argent-private submodule at the pinned revision reads any of them by path, so nothing breaks. Flagging it because a require() of a built dist/*.js loses a dropped export exactly the way it lost the deleted __resetAndroidDevtoolsInstallCache this branch had to restore — so this half of the diff does deserve runtime scrutiny, not a skim.

Referenced nowhere → delete. Orphaned test seams (__test, _testValidators), stale compatibility re-exports, and a few real orphans. The ones worth a reviewer's eye:

• localSimctl — the SimctlBackend strategy is only ever constructed with remoteSimctl. What keeps the local iOS impl off it is the handler signature: buildIosLaunchHandler / buildIosRestartHandler read services.nativeDevtools, and ios-remote is the only platform that declares that service, so the local impl — which resolves native-devtools per device inside its own handler — has nothing to hand them and shells out to xcrun itself.
• sendCharInsert — removing the __sendCharInsert test alias exposed the underlying helper as unreferenced. It is superseded, not unwired: the Chromium keyboard impl dispatches its own type: "char" event inline (keyboard/platforms/chromium.ts:58), which is exactly what this helper did. Chromium typing is unaffected.
• Error metadata fields — ServiceNotFoundError.serviceId, ToolNotFoundError.toolId and their two siblings were never read. The e.serviceId in registry-error-events.test.ts is a field on the event object the handler pushes, not on the error class; the err.toolId in http.ts is NotImplementedOnPlatformError, a different class that keeps its fields. Flagging these in case they are wanted as deliberate diagnostics.

Deleting SourceMapsRegistry.toGeneratedPosition / findMatchingSource cascaded into their only helper (buildSourceCandidates) and then into projectRoot, which had no remaining reader — so the constructor parameter goes too. StubSourceMapsRegistry existed only to pass super(""), so it goes with it.

The three cross-workspace members

ArtifactStore.register, ArtifactStore.list and TypedEventEmitter.off are all called from other workspaces — the artifact route and screenshot tools in tool-server, and registry-listener in telemetry. They are reported unused anyway, and the reason is the unbuilt tree the gate runs against: every workspace resolves main/types to a dist/ that does not exist, so @argent/registry resolves to nothing and the cross-workspace edge never forms. Build the tree and all three findings disappear on their own; a control member that really is dead is still reported in the built run, so the pass is live either way. Nothing about this is specific to classMembers — every cross-workspace reference is invisible the same way.

Each is exempted at the declaration with a @public JSDoc tag rather than by name in knip.jsonc, for one reason: scope. ignoreMembers matches a name across the whole workspace, so it would also hide a future dead register/list/off on any other class in packages/registry; @public binds to the member it is written on.

What @public does not buy is a staleness check, and neither does ignoreMembers. Measured on a clean unbuilt worktree: a bogus ignoreMembers name and a redundant @public each leave the run at exit 0 with no hint, while a bogus ignoreDependencies name exits 1 with Remove from ignoreDependencies. treatConfigHintsAsErrors is live and simply has no producer for either exemption style — so when one of the three stops being earned, nothing says so, and the JSDoc at each member is the only record a re-audit has. Each one names its callers, and off records how to re-derive them (rename the member and read the Property 'off' does not exist errors; grepping .off( over-reports, since 14 of the 38 call-site hits are Node EventEmitters). One correction to the commit message on that change: it says 35 hits where the exact count is 38 — 14 Node EventEmitter, 24 TypedEventEmitter (21 production, 3 in a test). The 14 and the 21 are right.

knip.jsonc, CONTRIBUTING.md step 5 and the workflow's failure-explanation step all described a parked backlog and a ceiling to stay under. All three are rewritten for a gate that must simply come back empty, and all three now name the @public escape hatch — the remedy for a symbol whose only caller is out of knip's reach.

Verification

Run against a clean worktree with no build output, the way CI counts:

• npm run knip — exit 0, prints nothing. Both passes empty, no config hints.
• npx tsc --build — clean.
• npm run lint (eslint . --max-warnings 0) — clean.
• npx prettier --check . — clean.
• npm test --workspaces — tool-server 329 files / 3857 passed; registry, telemetry, update-core, tools-client, mcp, cli green.
• npm run typecheck:tests --workspaces — 13 workspaces define the script and all 13 are clean, but the command itself exits 1: npm errors Missing script: "typecheck:tests" for the three that do not define it rather than skipping them. Worth knowing before re-running this bullet and reading the exit code as a failure.

End-to-end on a tool-server built from this branch, driven over its HTTP API:

• Chromium (Electron smoke app) — describe, screenshot, gesture-tap (counter advanced 0 → 1), POST /api/clipboard/text read back out of the renderer, the WS clipboardSync command, and debugger-connect / debugger-status / debugger-evaluate (sourceMapReady: true with StubSourceMapsRegistry gone).
• iOS — boot-device, launch-app, describe via ax-service, screenshot.
• tvOS — boot-device, launch-app on an Apple TV udid, focus-driven describe. The registry snapshot then carries NativeDevtools:<tvOS udid>, confirming injection is resolved on tvOS through the local impl.
• Android — boot-device on a dedicated AVD, describe via android-devtools, gesture-tap.
• Metro source maps — the registry driven against a real 12.5 MB Metro .map over loopback, the way Debugger.scriptParsed drives it: allowlist passes and waitForPending() resolves on both, while retained heap after gc drops from 17.3 MB to 3.6 MB.

Review follow-ups

Five commits on top, one per finding. The base is back on main, so the workflows run again.

• docs(launch-app) — the services comment explained the empty shape through LaunchAppAndroidServices, deleted here, and skipped LaunchAppVegaServices, which is still there. Same edit in restart-app/types.ts.
• docs(registry) — the @public tag on ArtifactStore.register named 2 of 7 callers. Derived the full set the way the sibling tag on off prescribes: renamed the member, read the 16 TS2339 errors tsc --build reports across flow-visual (5), screenshot (4), native-profiler-stop (2), screenshot-diff (2), native-profiler-analyze, react-profiler-analyze and screen-recording-stop. The re-derivation recipe is recorded too — .register( greps as badly as .off(.
• docs(knip) — "the build, the tests and this gate all stay green on a wrong delete" held for argent-private and not for the cross-workspace case that justifies three of the four @public tags. Deleting ArtifactStore.register gives 16 TS2339 errors and 9 failed | 2 passed in test/artifacts.test.ts; only the gate stays green. Split in the workflow comment, the failure annotation and CONTRIBUTING.md step 5.
• perf(debugger) — doRegister's data: branch still base64-decoded and JSON.parsed a payload it dropped, inside a catch that swallows. Both arms returned the same void, so the branch collapses to an early return; scriptUrl / scriptId go with it, since their last reader was the deleted this.maps.push(...) and doRegister is private.
• test(debugger) — the allowlist check moved to a top-level early return with nothing pinning it: delete the line and both SSRF files still pass 17/17. Two tests now assert doRegister consults it — four rejected URLs reach no fetch, and the loopback *.map Metro emits still does.

Re-verified after: npm run knip exit 0 and empty on a tsc --build --clean tree, tsc --build, eslint . --max-warnings 0, prettier --check . all clean, and npm test --workspaces with tool-server at 329 files / 3854 passed. The one red test, argent-installer's globalPath returns ~/.config/opencode/opencode.json, fails identically with these commits stashed — it reads the real ~/.config/opencode, which holds a .jsonc on this machine.

End-to-end on a tool-server run from this branch over its HTTP API, on every platform:

• Chromium — launch-app, describe, screenshot (returned an artifact handle, GET /artifacts/<id> served the 137542-byte PNG back), gesture-tap (counter 0 → 1), debugger-connect / debugger-status (sourceMapReady: true) / debugger-evaluate (read taps: 1 out of the page).
• iOS — launch-app, describe via native-devtools, restart-app, screenshot.
• tvOS — launch-app, focus-driven describe (12 focusables in TVSettings), tv-remote, restart-app.
• Android — launch-app, describe via android-devtools, restart-app, screenshot.
• Vega — boot-device on the tv VVD, describe via the automation toolkit.
• Metro — the real debugger-connect / debugger-status / debugger-evaluate tools against a stand-in Metro (HTTP /json/list + CDP WebSocket) emitting three Debugger.scriptParsed events: a loopback *.map on a counting server, a 1.4 MB inline data: map, and http://169.254.169.254/latest.map. sourceMapReady: true, loadedScripts: 3, evaluate 42, the loopback map fetched exactly once and the metadata URL never. A malformed inline payload gives byte-identical output, which is the finding.

Merge with main

Putting the base back on main made CI resolve the merge, and the Unit Tests job went red on a conflict no side could see on its own: #771 fixed the same red gate this branch's first commit did, the other way round — it made component-names.test.ts import StrippedName, ComponentAnnotation and ComponentNameResolution instead of dropping their export. Merged main in, reproduced it (tsc --noEmit -p tsconfig.test.json → three TS2459s) and took main's resolution: the three exports are back. The gate stays green because knip treats test files as entry points, so a type a test imports is not an unused export.

All nine workflows are green on the head commit.

[latekvo]

[Diplomat]: Reviewed at c24b6ba1. Ran on a clean npm ci --ignore-scripts worktree: npm run knip (exit 0, empty), npx tsc --build, npm run typecheck:tests --workspaces (13 workspaces), eslint . --max-warnings 0, prettier --check ., npm test -w packages/tool-server (329 files / 3857 passed), and node packages/argent/scripts/bundle-tools.cjs (all four esbuild bundles built; only the unrelated trace-processor asset download is missing locally). Diffed every emitted dist/*.js against a build of f136c024. Booted the Electron smoke app against tool-servers built from both f136c024 and c24b6ba1 and compared describe, screenshot, gesture-tap, /artifacts/:id, debugger-connect/debugger-evaluate, keyboard and five error paths — identical output on both, and typing still lands real characters in a focused field. Also mutated the gate itself (unused export, unused type, unused class member, stale ignoreDependencies, stale ignoreMembers) to check what it does and does not catch. Findings inline.

[latekvo]

[Diplomat]: Reviewed at 671447d3, on top of the earlier round at c24b6ba1. Five of that round's seven findings land cleanly, each re-checked by re-running its repro across the boundary: both orphaned comments are gone, the ignoreMembers block is replaced by per-member tags, the discovery.ts rewrite holds clause by clause (readSourceFragment does return null on an empty projectRoot, source-resolver.ts:156), and __resetAndroidDevtoolsInstallCache is restored with a byte-identical body and now survives the gate on the @public tag alone - the submodule driver's require(dist).__resetAndroidDevtoolsInstallCache() succeeds at head and threw TypeError against a build of c24b6ba1. The two that are not resolved get replies on their existing threads rather than new comments.

What I ran on a clean npm ci --ignore-scripts worktree at this head: npm run knip (exit 0, empty, unbuilt and built), npx tsc --build, eslint . --max-warnings 0, prettier --check ., and the suites - tool-server 329 files / 3857 passed, telemetry 295, registry 90, argent-installer 554, argent-cli 459, argent-mcp 79, argent-tools-client 191. On npm run typecheck:tests --workspaces: 13 workspaces define the script, not six, and all 13 are clean - but the command itself exits 1, because npm errors Missing script: "typecheck:tests" for the three that do not define it rather than skipping them. Worth knowing if anyone re-runs that verification bullet and sees a nonzero exit. Built base and head and diffed all 432 emitted .js plus the four esbuild bundles from bundle-tools.cjs. Mutated the gate itself through 15 issue classes and confirmed each is caught in the pass the prose predicts, and that no knip issue type falls through both passes. Ran a live tool-server on a Chromium/Electron device against head and base and compared describe, gesture-tap, keyboard, gesture-scroll, screenshot, chromium-tabs, debugger-connect/status/evaluate, view-network-logs and five error paths - identical, apart from a pre-existing non-deterministic adb error-message race I reproduced on both builds.

Worth stating what came back clean, since most of it is the part that could have gone wrong. All 214 lost exports (183 unexported, 31 deleted) are unreferenced across every file type, scripts/, .github/, all 41 markdown files and the argent-private submodule at the pinned revision 79ae7d91 - __resetAndroidDevtoolsInstallCache was the only cross-boundary caller and it is fixed. Every one of the 183 unexported symbols still has an in-file use, so none of them became dead-but-invisible, which is the way this shape of change usually goes wrong. knip --production and --include-entry-exports, head against base with both trees unbuilt, report zero newly orphaned files and zero new issues at head. No barrel lost a symbol it still re-exports, and no value export became export type. Under noUnusedLocals/noUnusedParameters/exactOptionalPropertyTypes/noImplicitOverride the base-to-head delta across the monorepo is exactly one new error, the clipboard field below. And git merge-tree of this head into current origin/main is conflict-free, with the merged tree passing npm run knip unbuilt and tsc --build - so the zero headroom does not fire against what main has landed since the merge base.

One piece of context rather than a finding: the base was retargeted to fix/knip-component-name-types-unexported at 13:38:53Z, after all nine checks were created at 13:34:17Z, and every workflow filters pull_request: branches: [main] - so the green checks predate the retarget and nothing can re-run at the current base.

[latekvo]

[Diplomat]: This trims the shim's re-export list from four symbols to two, but the file has no production importer to be compatible with. The header directly above says it "is kept as a thin re-export for source compatibility with existing imports"; the only import of it anywhere is its own test:

$ grep -rn "ios-profiler/lifecycle" --include='*.ts' packages | grep -v /dist/
packages/tool-server/test/ios-instruments/lifecycle.test.ts:4:import { waitForChildExit, shutdownChild } from "../../src/utils/ios-profiler/lifecycle";

Same at base, and nothing in the argent-private submodule at 79ae7d91 reaches it either. The file therefore survives the files check only through the blind spot this PR documents at knip.jsonc:135-142 - test files are entry points, so a module nothing but its own test imports still counts as reached. Pointing that one test at ../profiler-shared/lifecycle would have removed the file, which is what the surrounding 135 files are doing. Flagging it because this is the change that edited the shim and would naturally have caught it, and because the header now states a reason that does not hold.

[hubgan]

Leaving this one, and flagging why rather than acting on it.

The finding holds - packages/tool-server/test/ios-instruments/lifecycle.test.ts is the only importer, so the shim survives the files check purely through the test-files-are-entry-points blind spot, and the header's "source compatibility with existing imports" has nothing to be compatible with.

But it reads the same at the merge base: the file had no production importer at f136c024 either, and the header sentence is unchanged by this PR - the diff only trims two erased type re-exports off the list. So the dead shim predates this change, and pointing that one test at ../profiler-shared/lifecycle to delete the file is a change this PR did not make and should not smuggle in. Worth its own commit; happy to do it separately if you would rather it went in here.

[latekvo]

[Diplomat]: Reviewed at fec27a18, on top of the rounds at c24b6ba1 and 671447d3.

This PR's base is fix/knip-component-name-types-unexported, and every gate in this repo triggers on pull_request: branches: [main] — so none of them has run since 671447d3. I ran the equivalents locally on a clean npm ci --ignore-scripts worktree with packages/*/dist verified absent: npm run knip (exit 0, zero bytes of output), npx tsc --build, eslint . --max-warnings 0, npx prettier --check ., npm run typecheck:tests across the 13 workspaces that define it, typecheck:scripts, test:scripts (86), check-workspace-versions, and npm test --workspaces — tool-server 329 files / 3857 tests, matching the description. All green.

Beyond the gates:

• Live tool-server built from this branch, driven over HTTP against an Electron app: boot-device, describe, screenshot (artifact handle returned across the workspace boundary), gesture-tap (counter 0 → 1), keyboard, debugger-connect / debugger-status (sourceMapReady: true with StubSourceMapsRegistry gone) / debugger-evaluate, the WS clipboardSync command for both true and false, GET /artifacts and /artifacts/:id (200, 9477-byte PNG), and the dispose cascade.
• Published artifact. npm run pack:mcp (exit 0) and an md5 diff of the four emitted bundles against the merge base: cli-cmds.mjs, installer.mjs and mcp-server.mjs are byte-identical, and tool-server.cjs is smaller by exactly the deleted code with an unchanged entry export surface.
• CLI / MCP / installer. argent mcp over real stdio returns 73 tools with a tools/list payload that diffs empty against the merge base; argent init -y --local / update / uninstall round-trip under a throwaway HOME, with the bundled skills, rules and agents copied byte-for-byte (the PACKAGE_ROOT question, answered at runtime).
• Reachability sweep. All 192 symbols that lost their export, plus every outright deletion, grepped against the packages/argent-private submodule at its pinned 79ae7d9, against every non-TS file type, and against all markdown — no consumer anywhere. __resetAndroidDevtoolsInstallCache was the positive control and its @public tag checks out against research/android-describe-busy-ui/drivers/test-fallback.js.
• Mutation. Deleting ArtifactStore.register, deleting the SSRF allowlist guard, dropping redirect: "error", stripping each @public tag, and reverting --max-issues 0 to 215, each with a control run.

Six findings below. Separately, I have replied on the earlier threads where the fix left something behind — including one where the mechanism I gave last round was wrong and is now in knip.jsonc.

[latekvo]

[Diplomat]: Reviewed at c6d0d62d35cfb292a3282f3f89beba48809f674d. Ran the review moves over the whole 140-file diff — claims vs code, nearest twin, non-happy paths, inputs, reachability both ways, what outlives the call — plus the absence pass (sibling, prose, symmetry, mutation), with an adversarial round that tried to refute each finding before it went in.

What I ran: npm run knip on a dist-free npm ci worktree (exit 0, empty) and again with a planted instance of each of knip's 15 issue types; npx tsc --build, eslint . --max-warnings 0, prettier --check ., npm run typecheck:tests --workspaces --if-present, and npm test --workspaces (tool-server 332 files / 3884 passed, every other workspace green); the @swmansion/argent esbuild bundle (SourceMapConsumer gone from dist/tool-server.cjs, the allowlist still in it); the merge at 5af1b3d4 checked per-file against both parents; a sweep of every runtime binding the diff drops, against the repo, the argent-private submodule and the published tarball; and the branch's own tool-server driven over its HTTP API against a stand-in Metro and an Electron device (debugger-connect, debugger-status, launch-app, restart-app, keyboard, the WS clipboardSync route), with origin/main at fe597685 built as the control.

Inline comments below; four older threads have replies rather than new comments.

[latekvo]

Great job. A review / RCs might still land but feel free to merge as soon as you're ready

[latekvo]

[Diplomat, Deepseek V4 Flash 0731]: Ran the full sweep on this head (db01fa7): claims vs code, nearest twin, non-happy paths, inputs, reachability both ways, and what outlives the call, plus the absence pass (sibling/prose/symmetry/mutation) across the exports sweep, the source-map registry rewrite and the knip gate. Re-verified every prior round's finding at head and pushed a fresh four-agent pass over the move set. Gates all green on the unbuilt tree CI counts: npm run knip (exit 0, empty on both passes), npx tsc --build, eslint . --max-warnings 0, prettier --check, and the source-map SSRF suite 21/21. No HIGH or MEDIUM finding survived the sweep; the only LOW-shaped item (the shared launch-app/restart-app docstring twin) is out of this diff and already an accepted thread. Returned clean. Thank you for contributing!