Disciplines · Runbooks

Runbook: Per-Library Typecheck Cleanup

When an upstream package's exports field narrows under

3sections2 minread
Markdown source
On this page

Owner: shared infra Last reviewed: 2026-05-28

The repo-root npx tsc --noEmit is green. Per-library tsc --noEmit loops in some libraries still fail because of patterns the root typecheck doesn't surface (composite-mode rootDir violations, package-export drift, stale generated/ outputs).

Audit #60 framed this as "3 catastrophic + 14 high libs". The catastrophic ones (lakshmi, tara/analytics, veritas/auth + 24 libs sharing the rootDir+composite pattern across veritas + aphrodite + asase) were fixed in:

  • 87b3da7 (lakshmi composite + receipts createHash import)
  • 8e2a4f1 (tara/analytics declaration + veritas/auth lib + DOM)
  • 0bac56e (24-lib rootDir+composite sweep)

The remaining lib-level failures fall into two patterns. Each is tracked as follow-up; the per-library owner takes the fix as part of their next PR.

Pattern A: Package-export drift (TS2305)#

When an upstream package's exports field narrows under moduleResolution: "bundler", a named import that worked under "node" mode stops resolving. The fix is to import from the explicit subpath the upstream lib's exports allows.

Example landed: libs/veritas/search/src/client.ts imported ClientOptions from @elastic/elasticsearch (its main index), which under bundler mode resolves to the ESM index — which doesn't re-export ClientOptions. Fixed by importing from @elastic/elasticsearch/lib/client.

Search for these with:

bash
find libs -maxdepth 3 -name 'tsconfig.json' | while read tc; do
  d=$(dirname "$tc")
  cd "$d"
  npx tsc --noEmit 2>&1 | grep -E 'TS2305' && echo "  in $d"
  cd -
done

Pattern B: Real type errors in implementation#

A handful of libs have actual type errors in their source — not config issues. Examples:

  • libs/veritas/expansion: 16 errors, mostly missing properties on ExpansionPlanSchema types that drifted from the prisma model.
  • libs/veritas/business: 28 errors — decimal precision conflict between drizzle-orm and the prisma client types.
  • libs/veritas/storage: 59 errors — S3Client constructor signature changed in @aws-sdk/client-s3 v3 → v4.
  • libs/veritas/content-auth: 124 errors — biggest single offender; the @c2pa-rs/wasm package's type defs target a newer toolchain than this lib's tsconfig target: ES2020.
  • libs/veritas/risk: 54 errors — zod v3 → v4 schema-output type shape changes ripple through every risk-rule type.
  • libs/aphrodite/avatar-physics: 15 errors — @rapier/rapier3d type defs.
  • libs/asase/sota: 23 errors — drift after the recent ML pipeline refactor that landed BatchInferenceRequest shape changes.

Each is a per-owner fix. The shared-infra team won't take blanket PRs here because the right fix needs the lib's domain knowledge (which schema field is canonical, which sdk version is intended, etc.).

How to verify your lib#

bash
cd libs/<domain>/<package>
npx tsc --noEmit

If this fails:

  1. Check whether the failure is a TS6059 / TS6307 rootDir issue. If so, remove rootDir and composite from the lib's tsconfig.json — the @nx/js:tsc executor handles cross-package builds via the workspace path map.
  2. Check whether the failure is a TS2305 named-import miss. If so, import from the explicit subpath the upstream lib's exports field allows.
  3. Otherwise, fix the underlying type error.

The repo-root npx tsc --noEmit from the workspace root is the canonical typecheck; lib-level checks are convenience-only and don't gate CI directly. The CI typecheck job runs the root command, plus @nx/js:tsc builds per-project, both of which are green as of 2026-05-28.