Knip Migration

Dead-code detection: explicit exports + knip

Dead-code / unused-dependency detection runs on knip. The legacy unimported tool is gone and the dependency checks deny it; legacy libs/* packages that never migrated have no dead-code tooling. The root knip.json holds only the shared rules — a package needs no workspaces entry there, since knip derives its entry files from package.json (main, bin, exports) and its own defaults (entry files).

Why this isn't just "swap the tool"

knip treats everything listed in a package's package.json#exports as an entry point. Today every package exports a ./* wildcard mapped to ./src/*.ts (via the @ledgerhq/source custom condition declared in tsconfig.base.json):

jsoncCopy code
"./*": {
  "@ledgerhq/source": "./src/*.ts",
  "import": "./lib-es/*.js",
  "require": "./lib/*.js",
  "default": "./lib/*.js"
}

Because of this wildcard, knip considers every top-level src/*.ts file "used" and cannot detect unused ("zombie") top-level source files. So a package needs to replace the ./* wildcard with explicit, minimal subpath exports that enumerate the package's true public API.

The few libs already pointed at knip (e.g. libs/env, libs/promise) still keep the ./* wildcard, so they are only partially migrated — do not copy them as the template.

New package = born migrated

A new package has no consumers, so it should start in the target state:

1. Explicit exports only. Enumerate the real public API; do not add a ./* wildcard. Mirror the . root entry per subpath, keeping the conditions:

   jsoncCopy code
   "exports": {
     ".":        { "@ledgerhq/source": "./src/index.ts",  "import": "./lib-es/index.js",  "require": "./lib/index.js",  "default": "./lib/index.js" },
     "./logic":  { "@ledgerhq/source": "./src/logic.ts",  "import": "./lib-es/logic.js",  "require": "./lib/logic.js",  "default": "./lib/logic.js" },
     "./lib-es/*": "./lib-es/*.js",
     "./lib/*": "./lib/*.js",
     "./package.json": "./package.json"
   }
   

2. Use knip — add a script that runs knip scoped to the workspace: pnpm knip --directory <relative-hop-to-root> -W <workspace-path> (--directory is the hop back to the repo root — ../.. for libs/<x>, ../../.. for libs/coin-modules/<x>; -W is the workspace path from root).

Dual-platform packages run knip once per platform

knip has no notion of moduleSuffixes. A suffix-less ./Tool specifier therefore resolves to nothing when only Tool.web.tsx and Tool.native.tsx exist, and both twins are reported as unused files (files is an error rule). Naming the suffix in the barrel fixes it for packages that may do so, but not under devtools/, where suffix-imports/no-platform-suffix makes a suffixed specifier a lint error.

So a package with platform twins gets two passes, through the shared helper knip.config.base.mjs:

jsCopy code
// <pkg>/knip.web.config.mjs — and the `native` mirror
import { createDualPlatformKnipConfig } from "../../knip.config.base.mjs";

export default createDualPlatformKnipConfig({
  packagePath: "devtools/shell",
  platform: "web",
  entry: [],
});

jsoncCopy code
// <pkg>/package.json — the hop in `--directory` is the depth back to the repo root
"unimported": "pnpm knip --directory ../.. -c devtools/shell/knip.web.config.mjs -W devtools/shell --tsConfig tsconfig.web.json && pnpm knip --directory ../.. -c devtools/shell/knip.native.config.mjs -W devtools/shell --tsConfig tsconfig.native.json"

Name the file knip.<platform>.config.mjs. The root ignore list matches **/*.config.*, so that name keeps knip from reporting its own config as unused. A .ts config does not match and needs a Sonar exclusion to compensate.

These configs carry no comments. This section is the single source for why they look as they do; the three options below are the only reasons a config should differ from the snippet above.

entry is [] unless package.json cannot yield the entry

knip derives entries from package.json (every exports condition, main, and specifiers in scripts), and reports an entry it already has as a redundant entry pattern. Name one only when that derivation misses a real entry point:

• the package declares no react-native condition, so only the web barrel is derived (devtools/env, and devtools/feature-flags / devtools/pay-card, which have no exports at all). Name src/index.native.ts in the native config.
• a platform file is reachable only through resolution. devtools/bindings pairs isMockSessionSupported.ts with a .native.ts override and no .web twin, and knip resolves the unsuffixed sibling first, so the native config names src/isMockSessionSupported.native.ts. Such an entry goes stale when the override is deleted; knip then reports Refine entry pattern (no match), so treat that hint as "the pair is gone, drop the entry".

additionalProjectExcludes is for an unsuffixed barrel

The platform glob the helper applies (!src/**/*.native.* on web, !src/**/*.web.* on native) only matches suffixed files. A web barrel named src/index.ts is not excluded from the native pass and becomes an unused file there, so the native config names it. A package whose web barrel is src/index.web.ts (devtools/transport-panel) needs nothing.

additionalIgnoreDependencies is a last resort

A dependency reached only from the excluded platform's files reads as unused, and dependencies is an error rule. Confirm the dependency is genuinely unreachable in that platform before reaching for this.

Two resolution facts that look like bugs

• An unsuffixed sibling beats the compiler extension. With {"web.ts": passThrough} registered, ./foo still resolves to foo.ts when both foo.ts and foo.web.ts exist.
• Compilers resolve file suffixes, not directory index suffixes. from "../hooks" never reaches hooks/index.web.ts. Import the module itself (../hooks/useDevToolsStorage).

A jest/** helper sits outside the project glob, so knip cannot see it importing a barrel export. Only typecheck catches that, which is why it runs before trusting a clean knip report.

Reviewing

For a new package, flag this and point here:

• a ./* wildcard in package.json#exports — new packages must enumerate explicit exports so knip can detect zombie files.

The workspaces block in knip.json is a temporary workaround

Everything must work without touching knip.json. The workspaces entries that remain are band-aids for packages that don't declare their surface properly yet — deep imports behind a ./* wildcard, runtime entries invisible to package.json (Electron preloads, web workers), or dependencies knip can't resolve. Each one hides a package that hasn't finished the migration above.

So: don't grow this file. Fixing the package's exports is the real fix, and it lets the corresponding workspaces entry be deleted. If you truly cannot avoid an entry, keep it to the smallest possible delta and remember a configured entry replaces knip's default patterns rather than extending them.