Eve library

Baseline-ratcheted typechecking

Other

Revision 1

On this page

Run a real compiler check from the repository root:

sh
node tools/typecheck/ratchet.mjs --app apps/oshun/web --tsconfig tsconfig.typecheck.json
node --test --test-concurrency=1 tools/typecheck/ratchet.test.mjs

The ratchet tolerates committed counts of known app-owned, located errors and excludes located dependency errors. New app-owned fingerprints or additional occurrences fail with exit 1. Located resolution errors retain their warning; a passing ratchet is not a declaration that all transitive source typechecks.

Compiler/setup failures exit 2 before baseline comparison or --update:

  • A diagnostic without a file location, including missing ambient types, missing configurations and configurations with no inputs.
  • A spawn error, signal termination or exit outside TypeScript's 0/1/2 statuses.
  • A nonzero exit without located diagnostics, or with unrecognized failure output. The parser supports --pretty false diagnostics and their indented continuation lines; unsupported output is not treated as a passing check.

Recognized npm warn lines (including warnings about pnpm-only settings) remain visible but are not errors. Warnings alone cannot explain a failed exit, and failed exits with npm error are never admitted. The compiler subprocess has unambiguous no-color output even when Nx forces color. Fatal output is flushed before exit so a large dependency diagnostic dump cannot truncate the actual setup failure.

The original output is retained for ordinary compiler/setup failures. Neither an existing baseline nor --update can admit these failures. Baseline policy for located errors is unchanged; only deliberately reviewed backlog should ever be updated. This does not validate every compiler option or repair missing packages.

cached-ratchet.mjs also hashes its own implementation and the ratchet, including uncommitted edits. Nx's default typecheck inputs include this tool directory's .mjs files. These invalidate old passes when gate behavior changes; they do not establish hermetic dependency/environment caching. Use uncached runs for release evidence or after environment/dependency changes.

The serial Node suite covers CLI success/failure, baseline preservation, path and count boundaries, six installed-TypeScript integration fixtures, and cache invalidation. Compiler output/status doubles exercise conditions independently; integration cases execute the installed compiler through an isolated local npx shim without downloading packages. The cache test uses a disposable Git checkout and its own temporary cache. OSHUN CI runs this suite before affected-project selection, including when only these tools change. Run expensive real consumer gates serially under the repository's resource-safety policy.