Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .github/workflows/pr-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ name: pr-ci
# WHICH PORTS: `detect` maps the PR's changed paths to ports with
# scripts/ci-affected-ports.sh, the same mapper local-ci.yml uses. A change under a
# port's directory selects that port; a change to fixtures/, spec/, scripts/, .github/,
# agent-context/ or anything unrecognised selects ALL ports (the mapper fails open); a
# docs-only change selects none and runs only the offline `gates` lane.
# agent-context/, docs/ or anything unrecognised selects ALL ports (the mapper fails
# open); only the root prose files (README.md, CHANGELOG.md, CONTRIBUTING.md,
# AGENTS.md, CLAUDE.md) select none and run only the offline `gates` lane.
#
# WHAT RUNS PER PORT: unit tests plus the conformance corpora, not the docker
# integration suites (integration-tests.yml owns those, on tags and on demand):
Expand Down
84 changes: 62 additions & 22 deletions .no-mistakes.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,23 @@
# conformance.yml's lanes, integration-tests.yml's Testcontainers matrix), so pinning the
# gate to it runs exactly the repository's checks, the same ones GitHub runs.
#
# THE SPLIT. These two commands together are exactly `scripts/ci-local.sh --quick`, cut
# along the script's own `--only` section boundaries so neither step repeats the other.
# `scripts/ci-local.sh --help` enumerates what each section contains, and
# `MO_CI_LIST_ONLY=1 scripts/ci-local.sh --only <section>` prints its exact step list.
# Measured green on a warm tree 2026-09-18: test 256s, lint 23s. The test step's mutation
# gate is DIFF-SCOPED (gate_completeness_diff in the script): it mutates only the
# stryker.conf.mjs `mutate` files the branch changed against its base, and SKIPs when it
# changed none. Before 2026-11-14 it ran the full pass every round, 10-45 min under load
# and most of this step's wall time. The full pass is `--only mutation`, the flagless
# run's mutation lane, and conformance.yml (tags, nightly, dispatch).
# THE SPLIT. `lint` is `--only gates`, the one lane every change runs. `test` is
# `--affected`: it lists what the branch changed against its merge base, maps the paths to
# lanes with scripts/ci-lane-map.txt, prints which lanes it selected, skipped and why, and
# runs only those (ts-fast + ts-unit for a TypeScript or web-client change; java-slow,
# python or csharp for a change confined to that port; every selectable lane for a change
# to fixtures, spec, scripts, workflows, agent-context, docs or any path the map does not
# claim; none for a change to only the root README, CHANGELOG, CONTRIBUTING, AGENTS or CLAUDE
# files, which the gates lane covers). Selected lanes run exactly as
# `--only <lane> --no-integration` does, so a lane's contents are unchanged. Force every
# lane with MO_CI_FULL=1. Before 2026-11-15 this step was always `--only ts-fast --only
# ts-unit`, so a Java, Python or C# change was validated by the TypeScript tests and by
# nothing in its own port. Measured green on a warm tree 2026-09-18: ts-fast + ts-unit
# 256s, gates 23s. The test step's mutation gate is DIFF-SCOPED (gate_completeness_diff in
# the script) and runs inside ts-fast: it mutates only the stryker.conf.mjs `mutate` files
# the branch changed against its base, and SKIPs when it changed none. That is unchanged by
# the selection. The full pass is `--only mutation`, the flagless run's mutation lane, and
# conformance.yml (tags, nightly, dispatch).
#
# ORDER IS LOAD-BEARING, and it is why the work is split this way round rather than one
# `--quick` in `test`. The pipeline runs test BEFORE lint. The `gates` section contains
Expand All @@ -39,18 +46,19 @@
# NOT all of them, which is the part worth being exact about: five invoke `node` directly
# (publish-set, script-name hooks, extract field kinds, metamodel-version, migration guides),
# `check-publish-intent.sh` spawns `node` internally, and `gate_positioning_claims` invokes
# bare `bun`. What holds across both kinds is the flag's safety: it cannot misfire on a
# missing dotnet/mvn/uv, because nothing in `gates`, `ts-fast` or `ts-unit` invokes them.
# bare `bun`. `gates`, `ts-fast` and `ts-unit` invoke no dotnet/mvn/uv. `--affected` can select the
# lanes that do, and there the flag is the point: a change to that port with its toolchain
# missing FAILS, where a plain run would skip it and report green.
#
# WHAT IS DELIBERATELY NOT HERE — the rest of the flagless `scripts/ci-local.sh`: the C#,
# Java, Kotlin and Python conformance lanes, the full Java reactor, and
# integration-tests.yml's five-port Testcontainers matrix plus the migrate-ts / runtime-ts
# real-Postgres suites (`--only ts-slow`). Dropped for cost — they turn a ~4.5 minute step
# into a much longer one on every round — and for dependence: they need dotnet, mvn, uv and
# a live Docker daemon, which a gate host is not guaranteed to have, and neither
# `--strict-toolchains` (a missing toolchain FAILS) nor its absence (a down Docker SKIPS
# silently) gives an honest per-change signal when they are missing. docs/RELEASING.md
# requires the flagless run before `bun publish`, which is where they are enforced.
# WHAT IS DELIBERATELY NOT HERE — the docker half. `--affected` implies `--no-integration`:
# integration-tests.yml's five-port Testcontainers matrix, the migrate-ts / runtime-ts
# real-Postgres suites (`--only ts-slow`) and the cube live check need a live Docker daemon,
# which a gate host is not guaranteed to have, and a down daemon SKIPS silently without
# `--strict-toolchains`. They turn a ~4.5 minute step into a much longer one on every round.
# A port's selected lane DOES need its toolchain (dotnet, mvn, uv), and under
# `--strict-toolchains` a missing one FAILS rather than skipping, so a change to that port
# is never reported green unchecked. docs/RELEASING.md requires the flagless run before
# `bun publish`, which is where the docker half and every lane are enforced.
#
# NOTE: this file must be at the repo ROOT as `.no-mistakes.yaml` (NOT under
# .no-mistakes/), and repo commands are read from the DEFAULT BRANCH — so nothing here
Expand All @@ -61,7 +69,7 @@
# commands above already run the same script the GitHub workflows run.

commands:
test: "scripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchains"
test: "scripts/ci-local.sh --affected --strict-toolchains"
lint: "scripts/ci-local.sh --only gates --strict-toolchains"

# Public repository: keep PR bodies short and the run intent out of them.
Expand All @@ -70,5 +78,37 @@ pr:
appendix: collapsed

# Mark a failing test command as pre-existing when it also fails on the base.
#
# THE EVIDENCE PHASE. After `commands.test` passes, the gate ALWAYS runs an agent that derives
# end-user scenarios and drives the product itself; no setting turns that turn off. It, not
# `commands.test`, is the long part of this step: 264 recorded Test steps for this repository
# average about 43 minutes, 130 of them over 30, against 4-5 for the command itself, and the
# agent's budget is 75 minutes on this host. Its prompt is the one thing a repository controls,
# so the runbook below scopes it the way `--affected` scopes the command: by the paths the
# change touches (`path_instructions` match the changed-file list, as scripts/ci-lane-map.txt
# does). This is guidance to a model, not a switch: it narrows what the agent is told to do
# and does not bound it. The bound is the host's `test_agent_timeout`. These fields are read
# from the default branch only, so they too take effect after merge.
test:
base_attribution: true
instructions: |
This repository ships libraries, a code generator and command line tools. There is no server or app to start. The test command already ran the lanes this change affects, and its output begins with the lanes it selected and skipped, so do not re-run the full suites or the lanes of ports the change does not touch. Drive the changed behavior directly instead: run the affected CLI command or generator on a small fixture from the fixtures directory, or the focused tests of the module the change touches. Keep to at most three scenarios and finish in about ten minutes. Report no-surface when the change has no runtime behavior, such as documentation, comments, CI configuration or metadata.
path_instructions:
- path: "docs/**"
instructions: |
Documentation only. There is nothing to start or drive. Return no-surface at once without running anything: the test command already ran the lanes whose tests read these pages, and the gates lane checks the prose.
- path: "server/typescript/**"
instructions: |
TypeScript port. Drive the meta CLI from the workspace on a fixture, or run bun test in only the package the change touches. Do not run the Java, Python or C# suites.
- path: "client/web/**"
instructions: |
Web client packages. Run bun test in only the package the change touches and check that its built entry still bundles. Do not run the server suites.
- path: "server/java/**"
instructions: |
Java and Kotlin ports. Run mvn test for only the Maven modules the change touches, with -pl and -am, not the whole reactor. Do not run the TypeScript, Python or C# suites.
- path: "server/python/**"
instructions: |
Python port. Run pytest on only the test modules the change touches. Do not run the TypeScript, Java or C# suites.
- path: "server/csharp/**"
instructions: |
C# port. Run dotnet test on only the test project the change touches. Do not run the TypeScript, Java or Python suites.
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,8 @@ adds the C#/Java/Kotlin/Python conformance lanes, the Java reactor and `integrat
Testcontainers matrix. Run `--quick` before opening a PR and the full script before a tag;
`MO_CI_LIST_ONLY=1 scripts/ci-local.sh [flags]` prints what a selection would run without
running it. The no-mistakes validation gate runs the script for you — see `.no-mistakes.yaml`,
whose `lint` and `test` commands partition `--quick` between the two steps. That file is read
whose `test` command runs `--affected` (only the lanes the change touches, per
`scripts/ci-lane-map.txt`) and whose `lint` command runs `--only gates`. That file is read
from the **default branch**, so it does nothing until it is merged to `main`.

**`leak-scan` is hosted again.** `main`'s protection requires that one status, and `hygiene.yml`
Expand Down
41 changes: 31 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,11 +94,10 @@ definition of the checks: each wrapper checks out, installs the toolchains its
lane needs, and calls the script, so a local run is the same check a workflow
run would be. A pull request runs the leak scan (`hygiene.yml`) and `pr-ci.yml`, which
runs the unit tests and conformance corpora of only the ports the PR touches (a change
under `fixtures/`, `spec/`, `scripts/`, `.github/` or `agent-context/`, or to any file
under `fixtures/`, `spec/`, `scripts/`, `.github/`, `agent-context/` or `docs/`, or to any file
outside a port's directory that the selector does not recognise, touches every port; a
change only to `docs/` or to Markdown files outside those directories runs just the
offline gates). Its `pr-ci` job is green only when every selected lane is, and a newer
push cancels the superseded run. The docker integration suites run on release tags and on
change only to the root prose files above runs just the offline gates). Its `pr-ci` job is
green only when every selected lane is, and a newer push cancels the superseded run. The docker integration suites run on release tags and on
manual dispatch. Run the script locally before opening or merging a PR, so nothing red
reaches `main`:

Expand All @@ -110,9 +109,30 @@ scripts/ci-local.sh # full parity: hygiene.yml's leak-scan, all-port
scripts/ci-local.sh --quick # hygiene.yml in full + the TypeScript half of
# conformance.yml; skips the C#/Java/Kotlin/Python
# ports, the java reactor and the docker suite
scripts/ci-local.sh --affected # only the lanes this change needs (see below)
MO_CI_LIST_ONLY=1 scripts/ci-local.sh --quick # print the steps, run nothing
```

**`--affected` runs only what a change can break.** It lists the paths you changed since the
merge base with the base branch (committed, uncommitted and untracked), maps each to lanes
with the table in [`scripts/ci-lane-map.txt`](scripts/ci-lane-map.txt), and prints the lanes it
selected, the lanes it skipped and the rule each path matched, so a reviewer can see what was
not run. A change confined to one port runs that port (`ts-fast` and `ts-unit` for TypeScript
and the web client, `java-slow`, `python`, `csharp`); a change to `fixtures/`, `spec/`,
`scripts/` (the map included), `.github/`, `agent-context/`, anything under `docs/` (port
tests read those pages) or any path no rule claims runs every lane, because unknown means
full; a change to only the root `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `AGENTS.md`
or `CLAUDE.md` runs no lane. It never runs `gates` (`--only gates` does, on every change) and
never the docker half, so a change confined to the Java port skips the Java docker
integration suites, which run on release tags and manual dispatch. When more than one port
is selected their lanes run in parallel, as the full run's do, so a change is never slower
than the full run; one port runs serially. Mutation testing is as before: diff-scoped inside
`ts-fast`. `MO_CI_FULL=1 scripts/ci-local.sh --affected` forces every lane,
`MO_CI_AFFECTED_BASE=<ref>` picks the base, and `scripts/ci-select-lanes.sh [<ref>]` explains
a selection without running anything. The flagless run above is unchanged and is what
[releases](docs/RELEASING.md) use. The same map drives `pr-ci.yml`'s port detection, and
`scripts/test-ci-lane-selection.sh` (in the `gates` lane) pins what each kind of change selects.

The full run does its tree-writing steps first (install, the drift gates, one workspace
build), then runs the rest as parallel lanes: at most `MO_CI_JOBS` at once, default 8. Each
lane's output prints as one block when the lane finishes, so lanes never interleave. The
Expand All @@ -127,12 +147,13 @@ gate and a Java pom-version drift guard on every push (activate hooks once per
clone: `git config core.hooksPath .githooks`).

If you drive changes through the no-mistakes validation gate, `.no-mistakes.yaml` pins its
`test` step to `scripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchains` and
its `lint` step to `scripts/ci-local.sh --only gates --strict-toolchains` — together exactly
`--quick`, split so neither step repeats the other's work. `--strict-toolchains` is part of
both: it promotes a SKIP to a FAIL, so a gate host missing bun cannot report green. Those
commands are read from the **default branch**, so editing them on a feature branch has no
effect until it merges.
`test` step to `scripts/ci-local.sh --affected --strict-toolchains` and its `lint` step to
`scripts/ci-local.sh --only gates --strict-toolchains`: the lanes the change affects, then
the gates every change runs, split so the gates run after the build `test` does.
`--strict-toolchains` is part of both: it promotes a SKIP to a FAIL, so a gate host missing
bun (or, for a change to a port, that port's toolchain) cannot report green. Those commands are
read from the **default branch**, so editing them on a feature branch has no effect until it
merges.

## Releasing

Expand Down
41 changes: 20 additions & 21 deletions scripts/ci-affected-ports.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
#
# Usage: scripts/ci-affected-ports.sh <base-sha> <head-sha>
# Prints a space-separated subset of: ts java python csharp
# (empty output = docs-only push: run only the cheap shared gates).
# (empty output = a push touching only the root prose files: run just the cheap shared gates).
#
# Fail-open policy: an unknown base (force-push zeros), an unresolvable
# range, or ANY path not matched by a rule selects ALL ports — this script
# may only ever shrink coverage when it is certain.
# range, or ANY path not matched by a rule in scripts/ci-lane-map.txt selects ALL
# ports — this script may only ever shrink coverage when it is certain.
#
# NOT the whole selection. local-ci calls `ci-ports-to-run.sh`, which unions this
# answer with the ports that are not known-green on main. "What changed" alone
Expand All @@ -17,25 +17,22 @@ set -uo pipefail

ALL="ts java python csharp"

# The path -> lane rules are scripts/ci-lane-map.txt, read through ci-select-lanes.sh, so
# the no-mistakes gate (`ci-local.sh --affected`) and the hosted workflows share ONE table.
# This script keeps its job of answering in PORTS, the unit the workflows' `detect` jobs
# pass on, by mapping each selected lane to its port.
# Docs are NOT prose-only in that table (port tests read docs/), so a docs/ change selects
# every port here too; only the named root prose files select none.
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
MO_SELECT_LIB=1 source "$HERE/ci-select-lanes.sh"

map_paths_to_ports() { # args: changed paths; echoes the port set
local p sel_ts=0 sel_java=0 sel_python=0 sel_csharp=0
for p in "$@"; do
case "$p" in
server/typescript/*|client/web/*) sel_ts=1 ;;
server/java/*) sel_java=1 ;;
server/python/*) sel_python=1 ;;
server/csharp/*) sel_csharp=1 ;;
fixtures/*|spec/*|scripts/*|.github/*|agent-context/*)
echo "$ALL"; return 0 ;;
docs/*|*.md) : ;; # gates only
*) echo "$ALL"; return 0 ;; # fail open
esac
select_lanes "$@"
local lane port out=""
for lane in $SELECTED_LANES; do
port="$(lane_to_port "$lane")"
case " $out " in *" $port "*) ;; *) out="$out $port" ;; esac
done
local out=""
[ "$sel_ts" -eq 1 ] && out="$out ts"
[ "$sel_java" -eq 1 ] && out="$out java"
[ "$sel_python" -eq 1 ] && out="$out python"
[ "$sel_csharp" -eq 1 ] && out="$out csharp"
echo "${out# }"
}

Expand All @@ -47,7 +44,9 @@ if [ -z "$BASE" ] || [ "$BASE" = "0000000000000000000000000000000000000000" ] \
|| ! git rev-parse -q --verify "$BASE^{commit}" >/dev/null 2>&1; then
echo "$ALL"; exit 0
fi
CHANGED="$(git diff --name-only "$BASE" "$HEAD")" || { echo "$ALL"; exit 0; }
# --no-renames: a rename's old path must be listed too, so moving a file OUT of a
# port selects that port exactly like moving one in (matches ci-select-lanes.sh).
CHANGED="$(git diff --no-renames --name-only "$BASE" "$HEAD")" || { echo "$ALL"; exit 0; }
[ -z "$CHANGED" ] && { echo ""; exit 0; }
# shellcheck disable=SC2086
mapfile -t paths <<<"$CHANGED"
Expand Down
Loading
Loading