pre-commit

name: pre-commit description: Run the mandatory pre-commit checks for the poku repository before staging a commit. Use this whenever the user asks to commit, prepare a commit, push, open a PR, or verify a change is ready. Runs typecheck, lint:fix, build, and the local test suite in order, plus runtime-sensitive suites when the change touches runtime detection, isolation, child-process spawning, environment-variable plumbing, or any Bun or Deno specific code path. user-invocable: true

Guarantee that every commit lands with passing type checks, formatted code, a successful build, and a green local test suite, so no regression in correctness, style, or distributable output reaches the upstream history.

Preconditions

On a fork, read CONTRIBUTING.md first.
Working tree reflects the change under review (no unrelated edits staged).

Recommended steps

Run in this exact order. Any non-zero exit blocks the commit.

npm run typecheck: TypeScript type check across the project.
npm run lint:fix: auto-fixes Biome and Prettier. May modify files, which must be restaged.
npm run build: produces lib/ from src/.
npm test: full local Node.js suite.

Runtime-sensitive checks (conditional)

Run additionally when the change touches runtime detection, isolation, child-process spawning, environment-variable plumbing, or any Bun or Deno specific code path.

bun run test:bun: full local Bun suite.
deno task test:deno: full local Deno suite.

Running a subset

Direct execution of a single test file:

npx tsx <path> or npx tsx src/bin/index.ts <path>
bun --bun <path> or bun --bun src/bin/index.ts <path>
deno run -A <path> or deno run -A src/bin/index.ts --denoAllow=all <path>

Filter the suite by path:

npm test -- --filter=<path>
bun run test:bun -- --filter=<path>
deno task test:deno -- --filter=<path>

Acceptance criteria

All four mandatory steps exit with code 0.
Runtime-sensitive suites exit 0 when applicable.
Any files rewritten by lint:fix are restaged before commit, so no unstaged formatting deltas remain.

Failure modes

typecheck fails: fix the type error at its source. Do not relax tsconfig or add any to silence it.
lint:fix rewrites files: restage them and re-run from step 1. If a rule needs to be disabled, justify it in code review, not by skipping the step.
build fails: fix the underlying TypeScript or bundler error. The build catches issues npm test does not.
npm test fails: fix the test or the code under test. Never bypass with --no-verify or by skipping the test. Treat a modified existing test as a possible regression and prefer adding new tests.
Runtime-sensitive suite fails: reproduce locally with the failing runtime before pushing. A Node-only green run does not clear a runtime-sensitive change.