# Baseline-ratcheted typechecking

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.