- The CI wiring vouch accepted any syntactically-executable `run:`, so a step moved into a release-only job or put behind `if: false` still reported as wired while PR CI validated nothing. It now requires an UNCONDITIONAL step: any `if:` on the job or the step disqualifies it, since this guard cannot evaluate an Actions expression and "runs sometimes" is not the property being asserted. Seven predicate cases, including the two conditional shapes and a multi-line `run:` that must still count. - The `local:gate` stage list now has one owner, `docs/quality-gate.md`. It had three copies, and they drifted apart across rounds 5, 6 and 8 of this review — which is the argument the PR itself is making, applied to itself. Signed-off-by: cliffhall <cliff@futurescale.com>
145 lines
6.1 KiB
Markdown
145 lines
6.1 KiB
Markdown
---
|
|
name: pre-push-gate
|
|
description: Run the mandatory pre-push gate and diagnose a failing stage — npm run format then npm run local:gate, what each stage checks, and the known traps (stale tsc cache, symlinked worktree node_modules, concurrent runs, orphaned smoke ports).
|
|
disable-model-invocation: true
|
|
---
|
|
|
|
# The pre-push gate
|
|
|
|
**The rule** (stated in [`AGENTS.md`](../../../AGENTS.md)): run `npm run format`
|
|
before committing and **`npm run local:gate`** before pushing. `npm run
|
|
validate` is the fast inner-loop check and is **not** a substitute — it runs no
|
|
coverage gate, no smokes, and no Storybook tests.
|
|
|
|
The reference for what each stage covers, and the CI-vs-local split, is
|
|
[`docs/quality-gate.md`](../../../docs/quality-gate.md). This skill is how to
|
|
run it and what to do when it goes red.
|
|
|
|
## The two commands
|
|
|
|
```sh
|
|
cd <repo root>
|
|
npm run format # auto-fix: core/, scripts/, the shared surface, every client
|
|
npm run local:gate # several minutes
|
|
```
|
|
|
|
The stages it runs, in order, are listed in
|
|
[`docs/quality-gate.md`](../../../docs/quality-gate.md) — deliberately in one
|
|
place only. That list drifted apart across three copies while this PR was in
|
|
review, which is the argument for not making a fourth. `npm run local:gate`
|
|
prints each stage as it starts, so the running command is the other reliable
|
|
answer.
|
|
|
|
It is a **strict superset** of GitHub CI (which additionally runs `npm install`,
|
|
and runs `coverage` as a parallel job). So the direction that matters holds:
|
|
**passing `local:gate` locally means CI's gates will pass.** The reverse does
|
|
not.
|
|
|
|
⚠️ **There is no `npm run ci`.** The gate was renamed to `local:gate` (#2146)
|
|
precisely because `npm ci` is a built-in that clean-installs from the lockfile
|
|
and does *not* run this script. `npm run ci` now fails with npm's missing-script
|
|
error.
|
|
|
|
## Verify by exit code, not by grepping output
|
|
|
|
Prettier failures are `[warn]` lines that match no obvious failure pattern, so a
|
|
grep-based check reports success on a red run. Capture the status:
|
|
|
|
```sh
|
|
npm run local:gate; echo "EXIT=$?"
|
|
```
|
|
|
|
⚠️ If you run it as a background task, the harness's "exit code 0" notification
|
|
describes the *wrapper*, not the gate — read the `EXIT=` line.
|
|
|
|
## Diagnosing a failing stage
|
|
|
|
### `verify:format-coverage` / `format:check`
|
|
|
|
Something isn't formatted, or a tracked source file is covered by no
|
|
`format:check` glob. Run the **root** `npm run format` (it covers `core/`,
|
|
`scripts/`, the shared surface, and every client) — not a single client's.
|
|
|
|
### `verify:typecheck-coverage`
|
|
|
|
A tracked `.ts`/`.tsx`/`.mts`/`.cts` lands in no tsconfig project. Usually a new
|
|
top-level file in a client whose build config roots at `./src`; add it to that
|
|
client's `tsconfig.test.json` (or the src config's `include`).
|
|
|
|
### `verify:skills` / `verify:skills:cli`
|
|
|
|
A `.claude/skills` manifest does not parse, declares no invocation mode, or a
|
|
model-invoked skill is missing its eval cases. `verify:skills:cli` is the
|
|
authoritative validator and fetches a pinned CLI over the network if you have
|
|
none installed — so it is also the one stage that will fail offline.
|
|
|
|
### `verify:dep-lockstep`
|
|
|
|
A dependency reaching one `tsc` program from two installs resolves to two
|
|
versions. **Align the versions** — bump it in every install that declares it.
|
|
Do not raise the heap with `--max-old-space-size`; that hides the class rather
|
|
than fixing it.
|
|
|
|
### `lint`
|
|
|
|
**There is no warning tier** — every `lint` script runs `--max-warnings 0`, so a
|
|
warning fails exactly as an error does. Fix the finding; don't widen a
|
|
`globalIgnores` or drop the rule. If a rule genuinely must be waived on a line,
|
|
use its inline disable comment **with a one-line justification**.
|
|
|
|
### `typecheck` passes locally but CI's `tsc -b` fails
|
|
|
|
⚠️ The **incremental cache** hides type errors. Re-run with `tsc -b --force`, or
|
|
in a fresh worktree.
|
|
|
|
### `coverage`
|
|
|
|
The per-file gate is ≥90 on **all four** dimensions (lines, statements,
|
|
functions, branches). A genuinely unreachable branch is annotated at the source
|
|
with a justified `/* v8 ignore … -- <reason> */`, never waved through by
|
|
lowering the gate. See `/testing` for the acceptable reasons.
|
|
|
|
Also check the file is inside a gated directory — the web coverage `include` is
|
|
a whitelist, so a module placed outside it falls out of the gate silently.
|
|
|
|
### `smoke:web*`
|
|
|
|
⚠️ **An orphaned prod web server from a previous run fakes a rejection.** It
|
|
answers the readiness probe with *its* token, and the deep link comes back
|
|
`data-deeplink="rejected"` with no error. Assert the port is free before
|
|
blaming the change.
|
|
|
|
### `local:storybook`
|
|
|
|
⚠️ In a worktree with a **symlinked `node_modules`** every story file fails on
|
|
Vite's `fs.allow`. Do a real `npm install` in the worktree.
|
|
|
|
### Everything times out at once
|
|
|
|
⚠️ Two concurrent `npm run local:gate` runs starve each other — ~326 tests time
|
|
out at 5s. Run one at a time. (A `pgrep -f "npm run local:gate"` wait loop
|
|
matches *itself* and never exits.)
|
|
|
|
## Local-only steps
|
|
|
|
Two stages have no GitHub CI counterpart, each deliberately:
|
|
|
|
- **`smoke:web:firefox`** — the three browser-driven web smokes again under
|
|
Firefox. Trialled as a CI job and removed (#2086): across a dozen runs it never
|
|
disagreed with Chromium, and `playwright install --with-deps` carries a real
|
|
flake surface. Kept in front of a human about to push instead.
|
|
- **`smoke:tui`** — needs a real TTY. It *is* invoked in CI via `npm run smoke`
|
|
and self-skips there on `process.env.CI`, so it needs no guarding.
|
|
|
|
A guard (`scripts/lib/workflow-gate.mjs`, run by `npm run test:scripts`) fails
|
|
the suite if a workflow invokes a `local:*` script, a non-Chromium engine pass,
|
|
or sets `SMOKE_BROWSER` to anything but a literal `chromium`. Don't work around
|
|
it — the split is the design.
|
|
|
|
## Publish-only check
|
|
|
|
`npm run pack:verify` builds, packs the real tarball, installs it into a clean
|
|
throwaway consumer, and drives the installed `mcp-inspector` bin end to end. It
|
|
needs **network access**, so it is a local/release check and is in neither
|
|
`local:gate` nor CI. Run it when touching packaging (the `files` allowlist,
|
|
a bundler `external` list, anything read from disk at runtime).
|