knip.jsonc

// Knip configuration — dead-code and dependency hygiene (#416).
//
// Unconfigured, knip reports ~341 "unused files" and several hundred duplicate
// exports here, because the defaults assume an application: anything not
// reachable from one entry point is dead, and two names for one value is a
// mistake. Neither holds for a library whose whole surface is its exports, and
// one of them is a documented convention. So the rules that fight the project
// are off, and the ones that catch real problems are on.
{
  "$schema": "https://unpkg.com/knip@6/schema.json",

  // The things that legitimately reach into the tree without being imported by
  // it: the test suites, the smoke cases (discovered at runtime by their own
  // harness), the build scripts and the benchmarks. The published entry points
  // are NOT listed — knip derives them from the `exports` map itself (the root
  // barrel plus one subpath per subsystem), and repeating them here is reported
  // as a redundant pattern. Deliberately no count: this comment named three
  // (`src/index.ts`, `src/testkit/index.ts`, `src/devtools/index.ts`) long after
  // the subsystem subpaths took it past a dozen.
  "entry": [
    "tests/**/*.test.ts",
    "tests/**/*.mjs",
    "tests/integration/**/*.ts",
    "scripts/**/*.{ts,mjs}",
    "benchmarks/**/*.ts"
  ],

  "project": ["src/**/*.ts", "scripts/**/*.{ts,mjs}"],

  // The framework-comparison benchmarks (#27) carry their own package.json and
  // lockfile, for the same reason `examples/` stays out of scope below: the
  // frameworks actor-ts is measured against are installed there, so resolving
  // those imports against the root manifest reports every one as `unlisted` —
  // an error here, and noise rather than a finding. The `entry` pattern above
  // (`benchmarks/**/*.ts`) pulls the whole tree in otherwise. Verified before
  // adding: without this, knip reports `nact` and `xstate` as unlisted.
  "ignore": ["benchmarks/comparison/**"],

  // `examples/` stays out of scope via `project` above. It is not published, and
  // its four frontends (Angular, Next, React, Svelte) each carry their own
  // package.json — resolving those imports against the root manifest reports
  // every framework dependency as unlisted, which is noise, not a finding.

  // Only the packages knip actually reports. Every one is reached through a
  // lazy `import()` (or is the type package for one), which static analysis
  // cannot attribute to the manifest entry — `better-sqlite3` from
  // `SqliteJournal.ts` / `SqliteClient.ts`, `@fastify/static` from the static
  // file handler. The rest of the optional peers resolve fine and are
  // deliberately not listed: an ignore entry that is not needed hides a
  // finding later.
  //
  // That rule is why this list is five entries and not ten. `@hono/node-server`,
  // `@hono/node-ws`, `hono`, `express` and `@types/express` were listed until
  // the knip 6.29 -> 6.35 bump, which started attributing all five to their lazy
  // call sites; knip then reported the entries themselves as unnecessary, and a
  // hint that names a dead exemption is exactly the finding this comment says an
  // unneeded entry would hide. Removed, and `lint:knip` is silent rather than
  // merely green.
  //
  // `ws` and `@types/ws` are the exception that had to be measured rather than
  // reasoned about (#676). The two peers added with them — `fzstd` and `memjs`
  // — are attributed from a literal `await import()` in
  // `tests/unit/ci/OptionalPeerModuleShapes.test.ts` and so are deliberately
  // NOT listed here; `@types/memjs` is attributed too, through the `memjs`
  // import it types. `ws` is not, and neither is its type package:
  // knip credits neither from that same file, and a static
  // `import { WebSocketServer } from 'ws'` does not move it either (both forms
  // were tried). `ws` ships no declarations of its own and carries an `exports`
  // map with no `types` condition, so the runtime package and `@types/ws` are
  // reached by different resolution paths and knip lands on neither. The import
  // is real and asserted — see the test above, and
  // `tests/smoke/cases/20-express-upgrade-middleware.mjs`, which imports `ws`
  // on all three runtimes.
  "ignoreDependencies": [
    "@fastify/static",
    "@types/better-sqlite3",
    "@types/ws",
    "better-sqlite3",
    "ws"
  ],

  "rules": {
    // OFF — fights the project rather than finding problems:
    //
    // `duplicates`: AGENTS.md requires every options family to export `XOptions`
    // as *both* a type union and a value alias for `XOptionsBuilder`. That is
    // two names for one value on purpose, in ~60 files.
    "duplicates": "off",
    // `exports` / `types`: a library's public API has no in-repo consumer by
    // definition. Turning these on would report the entire surface.
    "exports": "off",
    "types": "off",
    "nsExports": "off",
    "nsTypes": "off",
    // `enumMembers`: same reasoning one level down — a public enum's members
    // need no internal reference to be justified.
    "enumMembers": "off",

    // ON — these catch things that are actually wrong:
    //
    // `files`: a module reachable from no entry point is dead weight in the
    // published package.
    "files": "error",
    // `dependencies` / `devDependencies`: a manifest entry nothing imports.
    "dependencies": "error",
    "devDependencies": "error",
    // `unlisted` / `unresolved`: an import with no manifest entry behind it —
    // the failure mode that breaks a fresh install rather than the local tree.
    "unlisted": "error",
    "unresolved": "error",
    // `binaries`: a script invoking a tool nobody declared.
    "binaries": "error",
    // OFF — referencing an optional peer is the whole design: the framework
    // imports it lazily so a consumer installs only the backends it uses.
    "optionalPeerDependencies": "off"
  }
}