SuperAPI AI Directory

run-ts-cleanup

General & other

View repository

Updated 10-16 06:16

About this skill

Run TS Cleanup

A TypeScript codebase accumulates. Features get deprecated but their files stay. A refactor lands half-finished and both abstractions survive. An LLM writes cn for the fourth time in a fourth directory, launders types with as any, duplicates schemas, and blankets properties in defensive ?. optional chains. Dependencies outlive the code that imported them. Types get exported "just in case" and never consumed. This skill sweeps all of it into a clean end state guided by The 4 Pillars of TypeScript Project Cleanup:

  1. Reachability & Dead Code (Graph Layer): Prune unreferenced files, dead exports, orphaned dependencies, and abandoned zombie features using Knip.
  2. Encapsulation & Boundary Integrity (Visibility Layer): Decouple test-only leaks, internalize in-file exports, and designate explicit public API entry points (!).
  3. Type System Rigor & Soundness (Semantic Layer): Eradicate type laundering (as any, as unknown as T), maintain the type-coverage ratchet, enforce schema inference as single source of truth, and ensure declaration-emit safety.
  4. Module & Build Graph Health (Architecture Layer): Eliminate barrel smog, break cyclic dependency loops via dpdm/madge, restore tree-shaking, and maintain deterministic lockfiles.
  • Every dead symbol, file, export, type, and dependency is found by a real engine, not by guesswork — and each finding is triaged before deletion, never deleted on the engine's word alone.
  • Every deletion lands in a reversible causal wave behind a passing verification gate, so any single step reverts with one git reset or git revert.
  • The root cause is addressed, not just the symptom: duplicate helpers get consolidated, circular barrels get untangled, single-use wrappers get inlined — so the same bloat does not regrow.
  • The codebase ends more navigable than it started, for the next agent and the next human, without a single behavioural change.

This is a finishing tool. Run it on a green main branch, not mid-feature.

When To Use

Trigger on phrases and repo states like:

  • "clean up this TypeScript project", "my codebase is a mess", "remove the dead code"
  • "find unused dependencies", "prune unused exports", "delete orphaned files"
  • "there's too much AI slop in here", "tighten up the types", "untangle these imports"
  • "set up knip", "run knip", "why is this bundle so big"
  • Repo state: after a feature deprecation, a framework migration, or a long LLM-driven build-out.

Do NOT use this skill for:

  • Pure formatting or style-only changes — run the project's own formatter; this skill deletes code.
  • Branch, worktree, and repo-artifact cleanup — use run-repo-cleanup.
  • Reviewing a diff or PR — use run-review.
  • A dirty working tree — commit or stash first; Phase 0 refuses to start otherwise.
  • A red baseline — fix the failing build or tests first. Cleanup on a broken repo cannot tell your breakage from its own.

Modes

Pick the mode explicitly at the start, from the user's ask. Announce which one you picked. Escalating mid-run is fine; silently doing more than was asked is not.

Mode Runs Fires on
Sweep Phase 0-1, then lint autofix and Wave 1 only "tidy this up quickly", "drop the dead files"
Standard Phases 0-3, then Waves 1-5 "clean up the dead code" — the default
Deep Standard, plus Phase 4 root-cause work, type hardening, and structural refactor "the codebase is a mess", "make this maintainable"

The Engines

No single tool finds everything. Each engine sees one scope and is blind to the others.

Engine Finds Scope
Knip (v5/v6) Unused files, exports, types, dependencies Module graph
Biome / Oxlint / ESLint / Ultracite Unused locals, dead imports, correctness lint File AST
tsc Type errors, declaration-emit breakage Program
type-coverage any-creep, as a number Program
dpdm / madge Circular dependencies Import graph
anti-slop (Oxlint plugin) LLM-generated antipatterns File AST

Knip and the linters are complements, not alternatives: Knip finds a file nothing imports, a linter finds an import nothing uses. Read references/engines/engine-matrix.md for the full matrix and the auto-detection protocol.

Pinned Defaults

Decided once; override per-project only if the repo says otherwise (AGENTS.md / CLAUDE.md / CONTRIBUTING.md win over this skill).

Key Default Why
the gate tsc --noEmit → test → build, resolved for the detected package manager The single verification barrier. Defined once in references/remediation/waves.md; every "Run the gate" in this skill means exactly that.
branch chore/ts-cleanup Never work on main.
config file knip.jsonc (fallback knip.json) JSONC carries comments explaining why each entry exists.
package manager Detected from packageManager field, else lockfile Never hardcode pnpm. See waves.md §1.2.
wave order Files → Barrels → Encapsulation → Types → Dependencies Causal order: pruning leaves first eliminates dead import branches; dependencies pruned last avoids TS2307 crashes.
commit unit One commit per wave Each wave reverts independently.
suppression Targeted keys only ignoreDependencies, ignoreBinaries, ignoreExportsUsedInFile, explicit entry.

Non-Negotiable Safety Rails

  1. Start green. Verify git status --porcelain is empty, the typecheck passes, and the test suite passes before touching anything. A cleanup that begins on a red baseline cannot distinguish its own damage from pre-existing damage.
  2. Suppress false positives with targeted keys. Reach for ignoreDependencies, ignoreBinaries, ignoreExportsUsedInFile, or an explicit entry — each one silences exactly the finding it names. A broad top-level ignore severs graph edges instead, so files the ignored code imports start reporting as dead and get deleted.
  3. Triage every finding before deleting it. Apply the Three-Question Verification Test to each one. An engine reports what it cannot see a reference to; framework entry points, dynamic imports, and published API surfaces are all invisible to it.
  4. Delete in causal wave order. Files first, then barrels and cycles, then internalizing exports, then unused types, then dependencies and lockfile sync.
  5. Run the gate after every wave, before every commit. A wave that fails the gate is reverted or fixed, never committed.
  6. Prove declaration-emit safety before un-exporting. tsc --noEmit builds the implementation graph and never the declaration graph, so it passes on code that tsc -b will reject. Use --outDir /tmp/dts-check (avoiding the TS5053 flag conflict) or --isolatedDeclarations. See references/types/declaration-emit.md.
  7. Fix the cause, then the symptom. Consolidate the four copies of cn before deleting three of them; migrate the call sites before pruning the abstraction.

The Six Phases

        dead code · unused deps · AI slop · weak types · tangled imports
                              │
   Phase 0 — Baseline: clean tree, green typecheck, green tests, branch cut
                              │
   Phase 1 — Engine setup: detect the stack, configure each engine, resolve the manager
                              │
   Phase 2 — Survey: run every engine, batch findings, score risk
                              │
   Phase 3 — Triage: every finding gets a verdict — dead, false-positive, or deferred
                              │
   Phase 4 — Root cause: consolidate duplicates, untangle cycles, inline wrappers  [Deep]
                              │
   Phase 5 — Waves: delete in order, gate after each, one commit per wave
                              │
     zero dead code · green gate · one revertable commit per wave · a report you trust

Each phase gates the next. If you are tempted to skip one, re-survey instead.


Phase 0 — Baseline

Think first: "Is this repo green right now, and can I prove it?"

  1. Refuse to proceed on a dirty tree:
    test -z "$(git status --porcelain)" || { echo "Dirty tree — commit or stash first."; exit 1; }
    
  2. Cut the working branch: git checkout -b chore/ts-cleanup
  3. Resolve the package manager and write the gate script once — references/remediation/waves.md §1.2-1.4 gives the detection snippet.
  4. Run the gate. Record that it passed. This is the baseline every later gate is compared against.
  5. Capture the starting metrics for the final report: finding counts per engine, type-coverage percentage, cycle count.

Gate → Phase 1 when: the tree is clean, the branch exists, the gate passes, and baseline metrics are recorded.


Phase 1 — Engine Setup

Think first: "Which engines does this repo already have, and which does it need?"

  1. Detect what is installed — Biome, Oxlint, ESLint, Prettier, Ultracite, Knip, madge, type-coverage:
    python3 scripts/audit-ts-health.py --target .
    
    With no --check-* flag it runs all four audits. Passing any --check-* flag narrows it to just those.
  2. Generate or review the Knip config:
    python3 scripts/init-knip-config.py --dry-run     # inspect first
    python3 scripts/init-knip-config.py --format jsonc
    
    It detects frameworks and monorepo layout, and stamps a $schema matching the installed Knip major version.
  3. Resolve configuration hints before trusting any finding. Knip reports config hints ahead of issues; a hint left unresolved produces a cascade of false findings downstream. Tune entry points until the hints are gone — references/engines/knip-configuration.md has the plugin catalog, monorepo patterns, and compiler settings.
  4. Confirm zero broad top-level ignore patterns in the config.

Gate → Phase 2 when: every engine the mode needs is runnable, config hints are resolved, and no broad ignores remain.


Phase 2 — Survey

Think first: "What does every engine see, and how much of it is worth acting on?"

  1. Run the dead-code engine and batch its output:
    python3 scripts/batch-findings.py --run --output markdown --out-file cleanup-plan.md
    
    Batches 1-6 come from the dead-code engine, each with a risk score and a gate rendered for the detected manager.
  2. Run the remaining engines the mode calls for — lint, type-coverage, madge. Their findings form batches 7-9. Commands in references/engines/lint-engines.md and references/engines/analysis-engines.md.
  3. Read the batch definitions and risk model in references/detection/finding-classification.md — nine batches, each naming its producing engine and the wave it feeds. Several collapse: batches 3 and 9 feed Wave 2, batches 4 and 5 feed Wave 3, batches 6 and 8 feed Wave 4, and batch 1 feeds Wave 5.

Gate → Phase 3 when: cleanup-plan.md exists, every finding sits in a batch, and every batch carries a risk score.


Phase 3 — Triage

Think first: "Which of these findings would break production if I deleted it?"

Apply the Three-Question Verification Test to every finding:

  1. Framework lifecycle? Does a convention invoke this without importing it — a Next.js page.tsx / route.ts, a Remix loader, an Astro content config, a Playwright fixture?
  2. Dynamic invocation? Is it reached through a template-literal import(), a string-keyed registry, or runtime reflection?
  3. Public contract? Is it exported to consumers outside this repo's static graph, via exports or typesVersions?

Verify with the codebase, not from memory:

rg -g '!node_modules' -g '!dist' 'symbolOrPackageName'

Codify each confirmed false positive back into config as a targeted key — never as a broad ignore. Framework entry catalogs, dynamic-import patterns, and lint/type false positives are in references/detection/false-positive-triage.md.

Gate → Phase 4 when: every finding in cleanup-plan.md carries an explicit verdict of dead, false-positive, or deferred. Zero blanks. Count them and state the number.


Phase 4 — Root Cause

Think first: "Why did this bloat appear, and what stops it coming back?"

Deep mode only. Sweep and Standard skip to Phase 5.

Deleting the symptom leaves the generator running. Work out which origin produced each cluster, then fix that:

What you found Where to go
Four copies of cn, duplicate formatDate, useless try/catch, phantom null checks, boolean theater, type laundering references/detection/code-slop-catalog.md — 4 pillars, 7 agent patterns, and per-pattern remediation
Circular imports, bloated barrels, single-use wrappers, scattered helpers references/remediation/structural-refactor.md — plan-first structural work
Brain methods, deep nesting, long parameter lists, speculative generality references/remediation/complexity-thresholds.md — numeric thresholds to prioritise by
any sprawl, missing strict flags, weak inference references/types/strict-migration.md — the ratchet

Consolidation is a code change like any other: run the gate and commit it before starting Wave 1.

Gate → Phase 5 when: duplicates are consolidated behind one canonical implementation, call sites are migrated, cycles are broken, and the gate passes.


Phase 5 — Waves

Think first: "What is the smallest deletion I can make, prove, and commit right now?"

Five waves, in causal order. After each: run the gate, then commit. A wave that fails the gate gets fixed or reverted — never committed. Full protocol, per-wave scope, and rollback in references/remediation/waves.md.

Wave Deletes Additional check Commit
1 Orphaned and unreferenced files (git rm) — chore: remove unreferenced files
2 Dead barrel re-exports; break cycles and repoint consumers — refactor: prune dead barrel re-exports and cycles
3 Test-only leaks and in-file-only exports (strip export) — refactor: internalize private exports
BRIDGE Linter autofix and formatter pass (between Wave 3 & 4) Clears unused locals (TS6133) and formats chore: linter autofix and format after un-export
4 Unused types, interfaces, enum members Declaration emit (--outDir /tmp/dts-check or tsc -b) refactor: prune dead types
5 Unused dependencies, then refresh the lockfile — chore(deps): prune unused dependencies and sync lockfile

Wave 3 needs the linter bridge. Stripping an export turns unused in-module bindings into unused locals (TS6133). Run the detected engine's autofix immediately after — recipes in references/engines/lint-engines.md, timing rationale in waves.md §8. Note: linters clean file-local un-export residue; any consumer actively referencing a stripped export must be refactored in Wave 3 directly. Verify declaration emit before stripping anything reachable from a public signature: references/types/declaration-emit.md.

Post-flight

  1. Re-run every engine. Confirm zero remaining findings, or an explicit deferred list.
  2. Diff the metrics against the Phase 0 baseline: findings removed, type-coverage delta, cycle count delta, dependency count delta.
  3. Remove scratch artifacts: cleanup-plan.md, .cleanup-gate.sh, any baseline JSON.
  4. Report what was deleted, what was deferred and why, and the metric deltas.

Gate → done when: every wave is committed, the gate passes on the final commit, engines report clean, and the report is delivered.


Common Mistakes

Mistake Consequence Instead
Broad top-level "ignore": ["src/legacy/**"] Knip stops traversing those files, so their imports report as dead and get deleted Use ignoreDependencies / ignoreBinaries / ignoreExportsUsedInFile / explicit entry
Acting on findings before resolving config hints Every downstream finding is suspect; you triage noise Clear hints in Phase 1, then survey
One big cleanup commit No bisect, no partial revert, unreviewable One commit per wave
Deleting dependencies before pruning dead files Orphaning transitive packages and triggering TS2307 on unreferenced code Wave order: files → barrels → exports → types → dependencies
Trusting tsc --declaration --emitDeclarationOnly --noEmit Fails immediately with error TS5053 option conflict Use tsc --declaration --emitDeclarationOnly --outDir /tmp/dts-check or --isolatedDeclarations
Hardcoding pnpm in the gate The gate silently no-ops on npm/yarn/bun repos Resolve the manager from packageManager or the lockfile
Deleting duplicate helpers without migrating callers Each copy had drifted; consumers depended on the differences Consolidate, migrate, gate, then delete
Skipping Phase 0 because the repo "looks fine" Pre-existing failures get attributed to the cleanup Prove green first

Scripts

Python 3 stdlib only — no dependencies, no network beyond the engines they invoke.

Script Phase Purpose Mutates?
scripts/audit-ts-health.py 1, 4 Detects linters and formatters, audits tsconfig.json flags, finds import cycles, flags slop markers. No
scripts/init-knip-config.py 1 Scans frameworks and monorepo layout; emits knip.jsonc/knip.json with a version-matched $schema. Yes — --dry-run to preview, --force to overwrite
scripts/batch-findings.py 2 Runs or parses the dead-code engine; batches findings, scores risk, renders gates for the detected manager. Only with --out-file

Run any script with --help for its full flag surface.

References

Bottom Line

Prove green → configure the engines → survey every scope → give every finding a verdict → fix the cause → delete in five gated waves → report the deltas.