knip-cleanup

Knip Integration and Barrel Cleanup

Four phases, each one committed and verified on its own. Later phases depend on earlier ones: every deletion exposes another layer of dead code, so knip is re-run between them rather than once at the start.

Do not start at phase 3. A knip baseline full of false positives will delete something real.

Phase 0: measure before believing the complaint

If the user also reports line-ending churn on every format, check before changing anything:

git ls-files --eol | awk '{print $1, $2}' | sort | uniq -c | sort -rn | head
<formatter> --check .    # biome check . / prettier --check .

i/lf w/lf across the board with a clean formatter run means the tracked tree is already normalized and the churn is in newly created files. The fix is prevention, not renormalizing: .editorconfig with end_of_line = lf, the editor's own EOL setting ("files.eol": "\n" for VS Code), and git config core.autocrlf false locally. Renormalizing a tree that is already LF produces a huge no-op diff and fixes nothing.

Phase 1: a baseline that is actually true

Install knip at the repo root, one config, one script. In a monorepo never give each package its own config: a per-workspace run cannot see that another workspace imports the symbol, so every shared export reads as dead.

{
  "$schema": "https://unpkg.com/knip@<major>/schema.json",
  "tags": ["-knipignore"],
  "workspaces": {
    "packages/lib": {
      "entry": ["src/index.ts", "src/**/*.test.ts"],
      "project": ["src/**/*.ts"],
      "includeEntryExports": true,
      "ignoreExportsUsedInFile": true
    }
  }
}

Then iterate until the report contains only real findings. Expect these, in this order:

• Every compiled entrypoint must be listed. Grep the Dockerfiles, CI, and build scripts for --outfile, --entry, bun build, esbuild. A second binary built from src/worker.ts is invisible to knip and its whole dependency tree reports as unused.
• Config files that read env at load time (prisma.config.ts and friends) crash knip's plugin loader. Disable that plugin ("prisma": false) rather than faking the variable.
• includeEntryExports: true wherever package.json exports uses wildcards. A map like "./utils/*": "./src/utils/*.ts" makes every file an entry, and knip then reports nothing at all for that package. Verify by adding a deliberately unused export and confirming knip sees it — silence is the failure mode here, so it will not announce itself.
• Framework-indirect dependencies (@prisma/client, pg, a JWT lib reached through a plugin) go in ignoreDependencies. Check each one is genuinely reached before ignoring it.
• Type-level assertions are not dead code. A type XInSync = [Assert<A, B>, Assert<B, A>] drift guard has no runtime caller by design. Tag it @knipignore (with "tags": ["-knipignore"] in the config) and say in a comment what it guards. Deleting it silently removes a check.