ci: fail on unused exports, types and duplicates

[aviggiano]

Problem

pnpm -w knip is the blocking "Find dead code and dependencies" CI step and part of pnpm -w ci. It checks only files,dependencies,unlisted,unresolved. A separate continue-on-error step ran knip --include exports,types,duplicates --no-exit-code and only printed its findings, so a new unused export never failed a build. On origin/main (13af837f), with those three categories included, knip 6.33.0 reports 40 unused exports, 38 unused exported types and 4 duplicate exports. The list is the same before and after pnpm -w build.

Root cause

The three categories stayed out of the blocking script until the earlier dead-code removals landed. The findings that remain fall into two groups:

• 78 symbols (40 values, 38 types) that only their own module uses. No other module, test, script or package entry point imports them.
• 4 aliases that export one value under a second name.

Change

Four commits:

1. refactor: delete duplicate export aliases. Each alias is deleted, and callers use the declared name.

   • cleanGenerated (= cleanRun) and materializeRun (= materializeSelection) in runtime. The CLI clean and materialize commands and the dashboard now call cleanRun and materializeSelection. These are already the operation names that their audit records store.
   • findingNoteSchema (= findingReportBoundTextSchema) in artifacts. Finding notes use the schema directly. It is the same object, so the generated JSON Schemas do not change.
   • MODAL_MAX_SANDBOX_TIMEOUT_MS, MODAL_RECOVERY_SANDBOX_TIMEOUT_MS and MODAL_SANDBOX_TIMEOUT_MS in modal were one 24-hour value under three names. MODAL_SANDBOX_TIMEOUT_MS stays, and recovery workers now use it. layout.test.ts drops the two assertions that compared the aliases with each other. It keeps the 24-hour value and ordering assertions.

2. refactor(cli): split the pairwise chart into panel helpers. Commit 3 un-exports buildPairwiseChart, which changes its declaration line. pnpm -w lint:strict:ci then applies max-lines-per-function (limit 80) to the whole function, which is 142 lines. The panel definitions move to pairwisePanels(), and the drawing of one panel moves to pairwisePanelParts(). Apart from indentation, the moved code is unchanged.

3. refactor: stop exporting symbols that only their own module uses. This removes export from all 78 symbols:

   • 69 are in production modules of cli, dashboard (frontend), modal, runtime, security and topology. 25 of these are payload types in cli-contracts.ts and run-statistics.ts.
   • 8 are in test helpers of evals, modal and runtime.
   • 1 is COHORT_REACHABILITY_LANES in scripts/ci/verify-cohort-reachability.mjs.

   assertCurrentPersistentWorkerLineage was async but never awaited anything. Once its declaration line changes, strict lint rejects that (require-await). The function is now synchronous, and its one caller no longer awaits it. It still throws inside the caller's try/finally while the lineage lock is held. The temporary-root.ts doc comment no longer says removeRegisteredRoots is exposed.

4. ci: fail on unused exports, types and duplicates. exports,types,duplicates are added to the --include list of the root knip script, and the non-blocking "Report unused exports" CI step is deleted.

The diff is 43 files, +174/−173. The chart split accounts for +76/−53. The rest is export removals, the alias deletions with their caller and test updates, the synchronous lineage assertion (+2/−5), one doc-comment fix and the CI change.

The previous push (3e6e2718) sat on the old wave-1 integration base (a48ad9c3). This push is rebased onto origin/main (13af837f). The rebase hit one conflict, in packages/cli/src/run-statistics.ts: #1200 added "canceled" to NodeStatisticsStatus, and this PR removes that type's export. It is resolved as type NodeStatisticsStatus = NodeStatus | "canceled" | "unknown";. Main still produces the same 82 findings, so no hunk was dropped or added.

• Modal: MODAL_SANDBOX_TIMEOUT_MS is kept although it was the alias, because production code and tests already use that name. It now holds the 24-hour literal, and MODAL_MAX_SANDBOX_TIMEOUT_MS and MODAL_RECOVERY_SANDBOX_TIMEOUT_MS are deleted. The value does not change.

Deliberately not built

• No knip ignore entries, @public/@internal tags or ignoreExportsUsedInFile. Every finding is fixed in code. The two @internal JSDoc tags already in packages/runtime/src/git-capture-diagnostics.ts stay. workspace-handoff.ts imports both tagged functions, and the gate still exits 0 with the tags removed, so they hide nothing.

• Exports that only tests import stay exported. Default-mode knip, the mode CI runs, counts test files as consumers, so such an export is not a finding. knip --production leaves out tests and the other non-production entries (build scripts and the runtime workflow templates). On this branch it lists 16 more exports that only those files use. Examples are the CLI schema IDs, setOperatorNpmCliForTests, and PROVIDER_SCOPED_SENSITIVE_ENVIRONMENT_CAPABILITY (read only by controller-source.test.ts). Reworking those is a separate change.

• Exports that a package entry point re-exports stay exempt. Default-mode knip does not report entry-file exports, and that includes everything an entry pulls in through export *. With the branch built, knip --include exports,types,duplicates --include-entry-exports still reports 207 unused exports and 175 unused exported types. For example, only packages/config/src/defaults.ts uses DEFAULT_CODEX_MODEL and normalizeEvalConfig. But packages/config/src/index.ts re-exports that module with export *, so the gate does not report them. Narrowing the package entry points is a separate change.

• This PR does not touch any schema/*.json file, generated validator or contract description string. It has no CHANGELOG edit.

• The CLI schema registry's typescriptExport values for operatorInputJsonSchema and reportBundleManifestJsonSchema now name module-private constants. The field is descriptive only: schemaRegistryBundleDigest does not hash it, and json validate does not print it.

Verification

The base comparisons ran in a separate detached worktree at origin/main (13af837f), installed with pnpm install --frozen-lockfile and built with pnpm -w build.

• knip gate (the discriminating check). On base, the old script exits 0. The new command ([email protected] --include files,dependencies,unlisted,unresolved,exports,types,duplicates --treat-config-hints-as-errors) exits 1. It reports Unused exports (40), Unused exported types (38) and Duplicate exports (4), with the same list before and after the build. The 78 symbols that commit 3 un-exports are exactly the 78 base findings (set comparison). On this branch, pnpm -w knip exits 0 both before and after pnpm -w build. CI runs it before the build.
• Strict-lint interactions. Two variants confirm that commit 2 and the lineage change are still needed. Replacing commit 2 with a bare export removal makes lint:strict:ci fail on buildPairwiseChart with max-lines-per-function (142 > 80). Keeping assertCurrentPersistentWorkerLineage async makes it fail with require-await. packages/cli/src/benchmark-analysis/ has not changed on main since the old base.
• Pairwise chart. buildComparisonChart renders a fixed fixture of three pairs, one with null credits and F1 (two NA cells). The base and branch builds produce byte-identical paired_row_comparison.svg (sha256 c7c75edd…) and paired_row_comparison.png (6c532e2b…).
• Artifact schemas. All 73 exported *JsonSchema(s) values of @ultrafuzz/artifacts serialize identically in the base and branch builds. verify-schema-snapshots.mjs passes on both.

Gates at 155d5f20, all exit 0:

• pnpm -w build, pnpm -w lint, pnpm -w format:check, pnpm -w docs:check
• pnpm -w knip, before and after the build
• CI=1 ESLINT_PLUGIN_DIFF_COMMIT=origin/main pnpm -w lint:strict:ci, with the exit code checked directly
• pnpm --filter typecheck for the 8 changed packages: artifacts, cli, dashboard, evals, modal, runtime, security and topology
• the tsconfig.test.json compile for artifacts, cli, dashboard, runtime and security

Targeted tests at 155d5f20, all passing:

Package	Tests	Pass
runtime	clean.test, materialize.test	10
cli	benchmark-analysis.test	13
cli	"run, ps, status, inspect, report, materialize, clean, and lifecycle commands expose product workflow evidence" (runs the renamed cleanRun and materializeSelection calls end to end)	1
modal	worker-lineage.test, layout.test	16 + 4
scripts	verify-cohort-reachability.test, release-validation-lanes.test (parses ci.yml)	16 + 3

worker-lineage.test includes "serializes competing attempt claims and fences the superseded writer", which exercises the rejection path of the now-synchronous assertion. The full suites were not run, because the host is shared. The rest of the diff is export removals, which the typechecks, the test compiles and knip cover.

• Also exits 0 in CI's partial state: in a fresh worktree after pnpm --filter @ultrafuzz/modal... build, which is what the "Test CI policy scripts" step builds before knip runs.

Risk

• All workspace packages are "private": true, and no in-repo consumer uses a removed name. Five names disappear from package entry points:

  • cleanGenerated and materializeRun (@ultrafuzz/runtime)
  • findingNoteSchema (@ultrafuzz/artifacts)
  • MODAL_MAX_SANDBOX_TIMEOUT_MS and MODAL_RECOVERY_SANDBOX_TIMEOUT_MS (@ultrafuzz/modal)

  None of the 78 un-exported symbols was reachable from an entry point. Recovery workers keep the same 24-hour sandbox timeout, now through MODAL_SANDBOX_TIMEOUT_MS.

• Once this lands, pnpm -w knip fails any PR that leaves an export, exported type or alias unused. A deletion that orphans an export must also delete or un-export it. A PR that starts importing one of the 78 now-private symbols must add its export back.

• Parallel branches. I checked each head below two ways. First, the new knip command ran on the head and on its merge-base with main, to find the findings the head adds. Second, the head was trial-merged onto 155d5f20 (git -c rerere.enabled=false merge --no-commit).

  • Incoming branches. Two branches are due to land next: the per-journal append lock (claude/x07-journal-append-lock, fa27e111) and the dynamic-expansion-retry change (claude/retry-withdraws-deferred-prompts, 4b1b3a44). Neither shares files with this PR. Both merge cleanly, and knip exits 0 on each result.
  • fix(runtime): a renderer or projection change no longer strands runs whose dynamic groups expanded #1216 (28ca73a9) merges cleanly, and knip exits 0.
  • refactor!: remove per-node cloud execution (execution.mode = "cloud") #1197 (52cb2506) needs three fixes:
    • Beyond its conflicts with main, it conflicts with this PR in two files. packages/runtime/src/clean.ts has adjacent deletions: refactor!: remove per-node cloud execution (execution.mode = "cloud") #1197 deletes readPersistedModalExecution and this PR deletes the cleanGenerated alias, so keep neither. packages/runtime/test/cloud-worker-harness.ts is a modify/delete conflict, so take the deletion.
    • It also deletes the only outside importer of currentTaskOutputBinding (packages/modal/test/current-artifact-fixtures.ts:243), which the new gate then reports. The function is still used at line 517 of that file, so the fix is to remove its export.
  • feat(runtime): let agents record roadblocks in a run-local friction log #1162 (54f1706d) adds export function resolveFrogBin in packages/runtime/src/friction-log.ts. Only that module uses it, so the new gate reports it. The fix is to remove the export. Its merge conflicts exist against main alone.
  • feat(runtime)!: run lifecycle commands from the pnpm-patched install instead of per-command npm installs (#921 step 1) #1201, feat(topology)!: a failed property lens no longer skips the rest of the campaign #1198 and fix(runtime): record final-report producer selections in the run instead of querying smithers #1183 add no findings. Their merge conflicts exist against main alone.

Refs #462.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no actionable regression was identified.

Summary

The PR makes unused exports, exported types, and duplicate exports blocking knip findings in CI. It removes the existing findings by making module-local symbols private, deleting redundant aliases, and updating their callers.

_{Reviews (1) · Last reviewed commit: "ci: fail on unused exports, types and du..."}