From d4c8aca8a98856dc6cb40ec2537c1efc628db01f Mon Sep 17 00:00:00 2001 From: sebi Date: Thu, 19 Nov 2026 02:17:11 -0500 Subject: [PATCH 1/3] feat(cli): x upgrade --only, and no check runs on main alone MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `x upgrade --only [,…]` runs the hop's `x verify` on the named steps, read by the same reader as `x verify --only` (verify-only.ts). The report never reads as a full gate: proof `verify-only`, `verify.only[]`, `verify.notRun[]`, a NOT THE FULL GATE summary, a human line and a `then` naming `x verify --only --json`. Default stays the full gate. deploy-proof (ci.yml) and tutorial-run.yml ran only on pushes to main and went red on the merge of a green PR (#1272). Both now run on pull requests that touch the paths they depend on; scripts/ci-workflow-main-only.test.ts fails a workflow or ci.yml job that checks main alone. verify stays the one verdict; the health row reads main's tutorial runs only. Co-Authored-By: Claude Opus 5.5 --- .dz/briefs/health.md | 2 +- .github/workflows/ci.yml | 22 ++++-- .github/workflows/tutorial-run.yml | 34 +++++++- CHANGELOG.md | 1 + docs/history/ci-split.md | 24 +++++- packages/cli/src/cmd-upgrade-fixture.ts | 6 ++ packages/cli/src/cmd-upgrade-only.test.ts | 96 +++++++++++++++++++++++ packages/cli/src/cmd-upgrade-spec.ts | 9 ++- packages/cli/src/cmd-upgrade.ts | 16 +++- packages/cli/src/cmd-verify.ts | 45 ++--------- packages/cli/src/messages-upgrade.ts | 6 ++ packages/cli/src/upgrade-gate.ts | 16 +++- packages/cli/src/upgrade-report.ts | 22 +++++- packages/cli/src/upgrade-scope.ts | 32 ++++++++ packages/cli/src/verify-only.ts | 67 ++++++++++++++++ scripts/ci-workflow-main-only.test.ts | 78 ++++++++++++++++++ scripts/deploy-proof-due.test.ts | 32 ++++++++ scripts/deploy-proof-due.ts | 40 ++++++++-- scripts/lib/health-tutorials.test.ts | 5 ++ scripts/lib/health-tutorials.ts | 19 ++++- scripts/tutorial-run.test.ts | 10 ++- wiki/CLI-Reference.md | 8 +- wiki/Upgrading.md | 9 +++ 23 files changed, 522 insertions(+), 77 deletions(-) create mode 100644 packages/cli/src/cmd-upgrade-only.test.ts create mode 100644 packages/cli/src/upgrade-scope.ts create mode 100644 packages/cli/src/verify-only.ts create mode 100644 scripts/ci-workflow-main-only.test.ts diff --git a/.dz/briefs/health.md b/.dz/briefs/health.md index 9782f2672..ed47c9d31 100644 --- a/.dz/briefs/health.md +++ b/.dz/briefs/health.md @@ -17,7 +17,7 @@ or PR announces. No verdict is always re-run, never filed: a null `conclusion` ( | `dependabot-not-stuck` | `gh pr list --app dependabot --limit 5 --state open --json number,createdAt,updatedAt,statusCheckRollup` | green checks at any age; failed checks until >7 days since `updatedAt` (7 exactly is not over). Green: completed CheckRuns `SUCCESS`, `NEUTRAL`, `SKIPPED`, StatusContexts `SUCCESS`; terminal failures red. Pending, missing, malformed, unknown, mixed evidence = no verdict; so is a missing or invalid `updatedAt`, never replaced by `createdAt`. A page of `--limit` (5) is truncated: raise it, file nothing until short. A confirmed stuck PR files even beside a PR with unread evidence. `--state open` excludes merged and closed; `createdAt` is context, never inactivity | | `demo-shipped` | `gh run list --workflow deploy-social-demo.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt` | `success` on a `workflow_run`. Null `conclusion` = still building: read `status`. `skipped` = the `ci.yml` completion was no green push (the deploy job's `if:`): red `main-green` files it; with it green, look for a non-push `ci.yml` run. `workflow_dispatch` = an operator's run, not a push publish; `headBranch` names the ref. Other non-success: name the guard its log's `::error::` line names. The ask carries `url`, `createdAt`, `databaseId`, `displayTitle`, `headBranch` | | `release-exists` | `t=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main)`, then `gh release view "$t" --json tagName,isDraft,publishedAt` | `isDraft` false AND `publishedAt` set; a draft, or none, is unhealthy. Missing = unhealthy: gh prints `release not found` and no JSON — the message is the signal, not the exit code. Any other unreadable answer = `cannot tell` (`X_HEALTH_ROW_UNREADABLE`) | -| `tutorials-run` | `gh run list --workflow tutorial-run.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt` | `success`, or no run yet (paths-filtered: nothing diverged). `cancelled` (superseded by a newer push) = re-run. Else a tutorial no longer runs as written: the ask names `url` and `bun run scripts/tutorial-run.ts --json`, whose `X_DOC_TUTORIAL_DIVERGED` names page and line | +| `tutorials-run` | `gh run list --workflow tutorial-run.yml --branch main --limit 1 --json databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt` | `success`, or no run yet (paths-filtered: nothing diverged). `cancelled` (superseded by a newer push) = re-run. Else a tutorial no longer runs as written: the ask names `url` and `bun run scripts/tutorial-run.ts --json`, whose `X_DOC_TUTORIAL_DIVERGED` names page and line | | `flake-hunt` | `gh run list --workflow flake-hunt.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,headSha,displayTitle,url,createdAt` | `success` under 48 h; older = unhealthy, the schedule stopped. No run or `cancelled` = re-run. Else a test failed in a shuffled order: open `flake-hunt` issues name test, seed, rerun | | `bench` | `gh run list --workflow bench.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,headSha,displayTitle,url,createdAt` | `success` under 8 days; older = the weekly schedule stopped. No run or `cancelled` = re-run. Else a figure failed to measure | | `compat` | `gh run list --workflow compat.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,headSha,displayTitle,url,createdAt` | `success` under 8 days; older = the schedule stopped. No run or `cancelled` = re-run. Else a cell is red: open `compat` issues name each and its replay | diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e04f19ad3..fc3a3e88e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,7 +9,7 @@ name: ci # parts, and `verify`, their one verdict), does each tracked app still gate # (`reference-app-verify`), can a stranger scaffold an app that gates (`scaffold-smoke`), do the # deployable artifacts BUILD and RENDER (`container`), does a rolling upgrade on the scaffolded -# chart drop a request (`deploy-proof`, main only), is each package green and above its +# chart drop a request (`deploy-proof`: main, and a pull request touching its paths), is each package green and above its # coverage bar in isolation (`packages`), and does any of it work on native Windows (`windows`, # the one runner that is not `ubuntu-latest`). The last four each carry their own argument, above # the job. One more asks first, on a push: did a green pull-request run already test this tree @@ -1332,12 +1332,15 @@ jobs: # Service, and fails on a single non-2xx. Every step is `docker/deploy-proof/run.sh`, which a # developer runs unchanged on a laptop. # - # Main only, and only when a file that decides the answer moved since a proof that PASSED: kind - # plus two image builds is minutes, not seconds, and a push that touches none of those paths - # cannot change the verdict. Budget: <= 8 minutes; the timeout below is the ceiling, not the - # target. + # On main, only when a file that decides the answer moved since a proof that PASSED: kind plus + # two image builds is minutes, not seconds, and a push that touches none of those paths cannot + # change the verdict. On a pull request, only when its diff touches one of those paths: main-only, + # it went red on the merge of a green pull request (#1272's `held-job.sh` edited a registry + # shape `x new` no longer wrote). Beside the gate, never in `verify`'s needs: a red proof is a red + # check on the pull request, and `verify` stays the one verdict. Budget: <= 8 minutes; the + # timeout below is the ceiling, not the target. deploy-proof: - if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch' + if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch' runs-on: ubuntu-latest timeout-minutes: 15 # `actions: read` is the previous run's job list, which the decision below reads. @@ -1348,6 +1351,8 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + # Depth 2: a pull request's decision diffs its merge commit against the base tip. + fetch-depth: 2 # Before the decision, because the decision is a Bun script: ~10 s on a push that then skips. - uses: ./.github/actions/setup # A `paths:` filter belongs to a whole workflow, never to one job, so the filter is a step — @@ -1356,8 +1361,9 @@ jobs: # path, and release.yml then published from B. Now a skip inherits the PREVIOUS main run's # verdict, so it is legal only when that run's deploy-proof concluded `success` and no # deciding file moved since its commit; a red, cancelled, unfinished or unreadable - # predecessor runs the proof, and so does every `release:` commit and every manual run. The - # rule and the path list: scripts/deploy-proof-due.ts, unit-tested beside it. + # predecessor runs the proof, and so does every `release:` commit and every manual run. A pull + # request inherits nothing: it runs when its own diff touches a deciding path. The rule and + # the path list: scripts/deploy-proof-due.ts, unit-tested beside it. - name: did a file that decides the verdict move since a proof that passed? id: paths env: diff --git a/.github/workflows/tutorial-run.yml b/.github/workflows/tutorial-run.yml index d0284b066..5cfaf2f0b 100644 --- a/.github/workflows/tutorial-run.yml +++ b/.github/workflows/tutorial-run.yml @@ -3,9 +3,13 @@ name: tutorial-run # Does a stranger following tutorials 1–4 on this commit see what the pages show? Every ```bash # fence, in order, on a scaffold built from this checkout (`scripts/tutorial-run.ts`). Its own # workflow, never a `ci` job: it installs and gates a scaffold several times, and `ci`'s clock and -# push count must not pay for that. On a push to `main` only, filtered to the files that can move a -# tutorial's output — a push touching none of them starts nothing. Not on a PR: a tutorial left -# wrong breaks `main` for one push at most, and the red run is read by the daily health brief. +# push count must not pay for that. On a push to `main` AND a pull request, filtered to the files +# that can move a tutorial's output — the generators, `x new`, `x db` and the CLI's message +# catalog — so a change touching none of them starts nothing. Main-only, it went red on the merge +# of a green pull request (#1272: `x db gen`'s success line gained its tables); on a pull request +# the red lands before the merge. Not a required check: `verify` is the one +# (docs/history/ci-split.md), and a path-filtered workflow never leaves a check pending. +# `scripts/ci-workflow-main-only.test.ts` holds the two path lists equal. # The same job RUNS `wiki/Building-Your-Own-Base.md`'s recipes: each `## Recipe:` fence written to # the path it names in a scratch app and driven by `scripts/base-recipes/` — seconds, no scaffold. @@ -16,6 +20,26 @@ on: - 'wiki/Tutorial-0[1-4]*' - 'packages/cli/src/templates/**' - 'packages/cli/src/cmd-generate*' + - 'packages/cli/src/cmd-new*' + - 'packages/cli/src/cmd-db*' + - 'packages/cli/src/db-*' + - 'packages/cli/src/messages*' + - 'packages/cli/src/verify-*' + - 'scripts/tutorial-run.ts' + - 'scripts/lib/tutorial-steps.ts' + - 'wiki/Building-Your-Own-Base.md' + - 'scripts/base-recipes/**' + - 'scripts/lib/base-recipes.ts' + - '.github/workflows/tutorial-run.yml' + pull_request: + paths: + - 'wiki/Tutorial-0[1-4]*' + - 'packages/cli/src/templates/**' + - 'packages/cli/src/cmd-generate*' + - 'packages/cli/src/cmd-new*' + - 'packages/cli/src/cmd-db*' + - 'packages/cli/src/db-*' + - 'packages/cli/src/messages*' - 'packages/cli/src/verify-*' - 'scripts/tutorial-run.ts' - 'scripts/lib/tutorial-steps.ts' @@ -25,8 +49,10 @@ on: - '.github/workflows/tutorial-run.yml' workflow_dispatch: +# One group per ref: a newer push to main supersedes the run before it, as it always did, and a pull +# request's run is superseded only by its own next push — never by main's, nor main's by it. concurrency: - group: tutorial-run + group: tutorial-run-${{ github.ref }} cancel-in-progress: true permissions: diff --git a/CHANGELOG.md b/CHANGELOG.md index d1c8dc635..c021ca63a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - `x heavy run --max-wait ` gives up with `X_HEAVY_WAIT_EXPIRED` (exit 75); `x heavy status` names each run's wrapper and command pids (`wrapperAlive`, `childPids` in `--json`), and a heavy run also waits while the CPU is saturated and another run is admitted. - `x clean --services` stops this app's test service stack, and the gate prints one line saying whether it started, reused or shared one. - `x dev`'s port refusal names the directory of the process holding the port. +- `x upgrade --only [,…]` runs the hop's `x verify` on those steps alone, so `unit`, `live` and `e2e` can be left to CI on a loaded machine. The report never reads as a full gate: `proof: "verify-only"`, `verify.notRun[]`, a `NOT THE FULL GATE` summary and a `then` naming `x verify --only `. A bare `x upgrade` still runs the full gate ([Upgrading](wiki/Upgrading.md)). ### Changed diff --git a/docs/history/ci-split.md b/docs/history/ci-split.md index 89c9b7c1a..46fa7c890 100644 --- a/docs/history/ci-split.md +++ b/docs/history/ci-split.md @@ -70,7 +70,7 @@ servers a `services:` block cannot start. | `scaffold-smoke` | 5 | one scaffold per runner: default, `--no-example`, and one per `x new --shape` (`api`, `blog`, `dashboard` since 2026-11-06), held to `NEW_SHAPES` by `scripts/ci-workflow-shape.test.ts` | | `packages` | 4 + 1 | each unit tested and covered alone; `cli` cut into two weight-band parts on two shards, the other 31 units on two more; `packages (merge)` folds the parts and judges `cli` (2026-11-17, below) | | `container` | 1 | unchanged | -| `deploy-proof` | 1 | unchanged, `main` only | +| `deploy-proof` | 1 | `main`, and a pull request whose diff touches a deciding path (2026-11-19, below) | | `fault-drills` | 1 | `x drill` on `examples/dummy` against one Postgres: `pg-blackhole`, `worker-sigkill`, `web-sigterm` — added 2026-11-06, below | | `release-rehearsal` | 1 | pull requests only: on a diff touching `scripts/`, the CLI's templates, codemods or upgrade, or any `package.json`, `release.ts --bump minor --rehearse` stamps the next minor in the runner's checkout (never committed) and the version-sensitive suites run against it — a test that bakes the current version breaks here, not on the release PR (added 2026-11-15) | | `windows` | 1 | native Windows in PowerShell: lint, typecheck, a path-heavy unit subset, a scaffold smoke — added 2026-10-05, below | @@ -103,6 +103,7 @@ services where it starts any (22 s + 8 s before this change, for two servers by | a part starts only the services it exports URLs for | `scripts/test-services-shape.test.ts` | | a suite that needs a service URL is run by a part that exports it | `scripts/test-services-shape.test.ts` | | `windows` is the one non-Ubuntu runner, pwsh on every step, ≤ 25 min | `scripts/ci-workflow-shape.test.ts` | +| no check runs on `main` alone: a workflow a push to `main` starts runs on a pull request over the same paths, unless it publishes; no `ci.yml` job a push runs is skipped on a pull request | `scripts/ci-workflow-main-only.test.ts` | ## Trade @@ -344,6 +345,25 @@ more under coverage than its weights say, ~0.4 s of isolation per file. Expected install and a fold of two ~150 KB documents. The first run's `packages` logs are the proof; the next lever is a per-file overhead in `planParts`' cost, so the bands balance at ~210 s each. +## Nothing checks `main` alone, 2026-11-19 + +Two jobs ran only on a push to `main`, and both went red on the merge of a green pull request +(#1272): `deploy-proof` (`docker/deploy-proof/held-job.sh` edited a registry shape `x new` no +longer wrote) and `tutorial-run` (Tutorial 2's `x db gen` line gained its tables). Each now runs on +a pull request too, over the paths it already depended on: + +| Job | On a pull request | Cost | +|---|---|---| +| `deploy-proof` | when `scripts/deploy-proof-due.ts` finds a `VERDICT_PATHS` file in the diff (merge commit against its first parent, depth 2); none: the job runs its decision step and skips the rest. It inherits nothing — `main` still decides by the predecessor rule | ≤ 8 min, beside the gate, off the critical path | +| `tutorial-run.yml` | `pull_request.paths` equal to `push.paths`; the list gained `cmd-new*`, `cmd-db*`, `db-*` and `messages*`, where the tutorial output it diverged on lives | ~2.5 min, its own workflow | + +`verify` is still the one verdict: neither job is in its `needs`, neither is required, and a +path-filtered workflow never leaves a check pending — a red one is a red check on the pull request. +`scripts/lib/health-tutorials.ts` reads `--branch main` alone, so a pull request's red is never +main's health. `scripts/ci-workflow-main-only.test.ts` holds the rule: a workflow pushed on `main` +with no `pull_request` trigger, or with different paths, fails unless it is a named publisher +(`wiki.yml`, `scorecard.yml`); a `ci.yml` job whose `if` admits a push and not a pull request fails. + ## Fault drills, 2026-11-06 `fault-drills` asks one question no other job can: does the reference app keep the framework's @@ -387,7 +407,7 @@ when it became a symlink to `CLAUDE.md`. `ci.yml` runs on pushes to `main`, `nex | `deploy-social-demo.yml` | green `ci` on `main` → the demo image | | `deploy-docs-site.yml` | green `ci` on `main` → `dummy/docs-site`'s static build on GitHub Pages; **inert** — every job skipped — until the owner sets the `DOCS_SITE_ORIGIN` repository variable (`scripts/ci-workflow-shape-docs.test.ts`) | | `wiki.yml` | push to `main` → the wiki | -| `tutorial-run.yml` | push to `main` touching a tutorial or a generator → tutorials 1–4 fence by fence, `X_DOC_TUTORIAL_DIVERGED`; never on a PR, never in `ci` | +| `tutorial-run.yml` | push to `main` or a PR touching a tutorial, a generator, `x new`, `x db` or the CLI's messages → tutorials 1–4 fence by fence, `X_DOC_TUTORIAL_DIVERGED`; never in `ci`, never required; one concurrency group per ref (on PRs since 2026-11-19, below) | | `bench.yml` | weekly + dispatch → re-measured first-hour/http-hello JSON as one PR on `bench/re-measured`, replaced by the next run; never in `ci`. No `release` trigger: a Release `release-tag.yml` creates with `GITHUB_TOKEN` starts no run, so it never fired. Needs Actions allowed to create pull requests (repository and organisation Actions settings); the cost is that required reviews must come from CODEOWNERS, which the bot cannot satisfy. Both 2026-11 runs were refused the PR; a refusal now says so and prints the `gh pr create` that opens it by hand, never the approve switch as the remedy | | `workflow-lint.yml` | push or PR touching `.github/**` → zizmor 1.32.0 at `medium` and above, online audits (impostor commits, advisories) included; a deliberate finding is suppressed in place with its reason. Its own workflow so a path filter can gate it; not a required check, so the filter never leaves one pending (added 2026-11-09) | | `scorecard.yml` | push to `main`, weekly, a change to `main`'s rules → the OpenSSF Scorecard run, published to the Scorecard API the README badge reads (`publish_results: true`); never gates a merge (added 2026-11-10) | diff --git a/packages/cli/src/cmd-upgrade-fixture.ts b/packages/cli/src/cmd-upgrade-fixture.ts index 293b2af77..45492f772 100644 --- a/packages/cli/src/cmd-upgrade-fixture.ts +++ b/packages/cli/src/cmd-upgrade-fixture.ts @@ -289,6 +289,10 @@ export const recording = (script: Script = {}): { runner: Runner; spawned: strin if ((script.generateCode ?? 0) !== 0) return answer(command, '', script.generateCode); return answer(command, await generated(options.cwd, args[3] ?? '')); default: + // `x upgrade --only `: the installed verify, narrowed to the list the hop was given. + if (label.startsWith('x verify --only ')) { + return answer(command, script.verify ?? VERIFY_GREEN, script.verifyCode ?? 0); + } return expect.unreachable(`an unscripted spawn: ${label}`); } }; @@ -349,6 +353,8 @@ interface Output { readonly ok: boolean; readonly summary: string; readonly failed: readonly string[]; + readonly only?: readonly string[]; + readonly notRun?: readonly string[]; readonly findings: readonly { step?: string; code: string; diff --git a/packages/cli/src/cmd-upgrade-only.test.ts b/packages/cli/src/cmd-upgrade-only.test.ts new file mode 100644 index 000000000..4d23a9b32 --- /dev/null +++ b/packages/cli/src/cmd-upgrade-only.test.ts @@ -0,0 +1,96 @@ +// `x upgrade --only`: the hop's gate narrowed to the named steps, and every report saying which +// steps it did not run — so a scoped green is never read as the full gate. + +import { afterEach, describe, expect, test } from 'bun:test'; +import { + fixture, + fixtureWithoutApp, + recording, + removeFixtures, + run, + VERIFY_RED, +} from './cmd-upgrade-fixture'; +import { VERIFY_STEP_NAMES } from './verify-step'; + +afterEach(removeFixtures); + +const SCOPED = ['typecheck', 'lint']; +const NOT_RUN = VERIFY_STEP_NAMES.filter((name) => !SCOPED.includes(name)); + +describe('unit · x upgrade --only, a scoped gate', () => { + test('the installed verify runs with the same list, and the report names the rest', async () => { + const dir = await fixture(); + const { runner, spawned } = recording(); + // Typed out of order: the list is the gate's declared order, as `x verify --only` keeps it. + const { code, output } = await run(dir, runner, ['--only', 'lint,typecheck']); + expect(spawned.at(-1)).toBe('x verify --only typecheck,lint'); + expect(spawned).not.toContain('x verify'); + expect(code).toBe(0); + expect(output.data?.proof).toBe('verify-only'); + expect(output.data?.verify).toMatchObject({ ok: true, only: SCOPED, notRun: NOT_RUN }); + expect(output.summary).toContain('NOT THE FULL GATE'); + expect(output.summary).not.toContain('the gate is green'); + expect(output.data?.then).toContain(`x verify --only ${NOT_RUN.join(',')} --json`); + }); + + test('the terminal names the steps not run and the command that runs them', async () => { + const dir = await fixture(); + const { lines } = await run(dir, recording().runner, ['--only', 'typecheck,lint'], { + json: false, + }); + const notRun = lines.find((line) => line.includes('not run by this hop')); + expect(notRun).toContain(`x verify --only ${NOT_RUN.join(',')} --json`); + }); + + test('a red scoped gate is red, and still says what it did not run', async () => { + const dir = await fixture(); + const { runner } = recording({ verify: VERIFY_RED, verifyCode: 1 }); + const { code, output } = await run(dir, runner, ['--only', 'typecheck,lint']); + expect(code).toBe(1); + expect(output.data?.done).toBe(false); + expect(output.data?.verify).toMatchObject({ + ok: false, + failed: ['typecheck'], + notRun: NOT_RUN, + }); + }); + + test('every step named is the full gate, and is reported as one', async () => { + const dir = await fixture(); + const { spawned, runner } = recording(); + const { output } = await run(dir, runner, ['--only', VERIFY_STEP_NAMES.join(',')]); + expect(spawned.at(-1)).toBe('x verify'); + expect(output.data?.proof).toBe('verify'); + expect(output.summary).toContain('the gate is green'); + }); + + test('no flag: the full gate, and the report carries no scope', async () => { + const dir = await fixture(); + const { output } = await run(dir, recording().runner); + expect(output.data?.proof).toBe('verify'); + expect(output.data?.verify).not.toHaveProperty('only'); + expect(output.data?.verify).not.toHaveProperty('notRun'); + }); +}); + +describe('unit · x upgrade --only, the refusals', () => { + test('a step that does not exist is refused before anything spawns, with the corrected list', async () => { + const dir = await fixture(); + const { runner, spawned } = recording(); + const { code, output } = await run(dir, runner, ['--only', 'typecheck,lnt']); + expect(code).toBe(1); + expect(spawned).toEqual([]); + expect(output.findings?.[0]?.code).toBe('X_CLI_BAD_FLAG'); + expect(output.findings?.[0]?.fix).toBe('x upgrade --only typecheck,lint --json'); + }); + + test('a repository with no app has no x verify to narrow: refused, nothing spawned', async () => { + const dir = await fixtureWithoutApp(); + const { runner, spawned } = recording(); + const { code, output } = await run(dir, runner, ['--only', 'lint']); + expect(code).toBe(1); + expect(spawned).toEqual([]); + expect(output.findings?.[0]?.code).toBe('X_CLI_BAD_FLAG'); + expect(output.findings?.[0]?.fix).toBe('x upgrade --json'); + }); +}); diff --git a/packages/cli/src/cmd-upgrade-spec.ts b/packages/cli/src/cmd-upgrade-spec.ts index 3e3fa33e6..6401d3c10 100644 --- a/packages/cli/src/cmd-upgrade-spec.ts +++ b/packages/cli/src/cmd-upgrade-spec.ts @@ -11,7 +11,7 @@ export const upgradeSpec: CommandSpec = { summary: 'move every @ultimat3/* one major in lockstep, raise the Bun floor, install, apply codemods, gate — and name the section to read', usage: - 'x upgrade [--to ] [--dry-run] [--json] · x upgrade codemods --from [--to ] [--dry-run] [--json]', + 'x upgrade [--to ] [--only [,…]] [--dry-run] [--json] · x upgrade codemods --from [--to ] [--dry-run] [--json]', // The one command a repository with pins and no `app.config.ts` can still use: `upgrade-root.ts` // finds its root, and its report says which check it could run. `codemods` needs the app. subcommands: UPGRADE_SUBCOMMANDS, @@ -30,6 +30,13 @@ export const upgradeSpec: CommandSpec = { summary: 'the release the app came from: the codemods whose version lies after it, up to --to, run', }, + { + name: 'only', + type: 'string', + subcommands: ['run'], + summary: + "the hop's x verify runs only the named step(s), comma-separated, as x verify --only does — NOT THE FULL GATE: data.verify.notRun names the rest, for CI to run (default: the full gate)", + }, { name: 'dry-run', type: 'boolean', diff --git a/packages/cli/src/cmd-upgrade.ts b/packages/cli/src/cmd-upgrade.ts index 9e2146143..960422bfc 100644 --- a/packages/cli/src/cmd-upgrade.ts +++ b/packages/cli/src/cmd-upgrade.ts @@ -35,6 +35,8 @@ import { publishedVersions, releaseBunRange } from './upgrade-registry'; import type { PlannedWrites } from './upgrade-report'; import { humanLines, NO_WRITES, report, thenLine } from './upgrade-report'; import { findUpgradeRoot } from './upgrade-root'; +import type { GateScope } from './upgrade-scope'; +import { readScope } from './upgrade-scope'; import { stopChildrenOnSignal, tagRunner, upgradeTag } from './upgrade-signals'; import type { UnfinishedHop } from './upgrade-unfinished'; import { clearUnfinished, readUnfinished, writeUnfinished } from './upgrade-unfinished'; @@ -170,6 +172,7 @@ export const createUpgradeCommand = ( root: string, app: boolean, to: string | undefined, + scope: GateScope | undefined, ): Promise { const dryRun = flagBool(ctx.args, 'dry-run'); const unfinished = await readUnfinished(root); @@ -321,6 +324,7 @@ export const createUpgradeCommand = ( onStage: stageReached, codemods: { from: resume === undefined ? hop.from : EVERY_RELEASE, to: hop.to }, ...(bunMoved === undefined ? {} : { bunMoved }), + ...(scope === undefined ? {} : { only: scope }), }); return { gate: hopGate, scripts: [] }; }); @@ -339,6 +343,15 @@ export const createUpgradeCommand = ( }; const span = { from: hop.from, to: hop.to }; if (gate !== undefined) { + const notRun = gate.verify.notRun ?? []; + if (done && notRun.length > 0) { + const scoped = { + ...span, + only: (gate.verify.only ?? []).join(','), + notRun: notRun.join(','), + }; + return ok('upgrade', msg('cli.upgrade.doneScoped', scoped), extra); + } return done ? ok('upgrade', msg('cli.upgrade.done', span), extra) : failed( @@ -363,6 +376,7 @@ export const createUpgradeCommand = ( if (ctx.args.subcommand === 'codemods') return runUpgradeCodemods(ctx); const { dir: root, app } = await findUpgradeRoot(ctx.cwd); const to = readTarget(ctx); + const scope = readScope(ctx, app); // One hop per app at a time, and a stopped hop stops its children: every spawn below is // tagged, and SIGINT/SIGTERM kill that tree and release the lock before the signal lands. const release = await acquireUpgradeLock(root); @@ -371,7 +385,7 @@ export const createUpgradeCommand = ( const undoSignals = stopChildrenOnSignal({ tag, pids, cleanup: release }); try { const runner = tagRunner(ctx.runner, tag, ctx.env, pids); - return await runHop({ ...ctx, runner }, root, app, to); + return await runHop({ ...ctx, runner }, root, app, to, scope); } finally { undoSignals(); release(); diff --git a/packages/cli/src/cmd-verify.ts b/packages/cli/src/cmd-verify.ts index 983f60044..17e21f10a 100644 --- a/packages/cli/src/cmd-verify.ts +++ b/packages/cli/src/cmd-verify.ts @@ -10,11 +10,10 @@ // why: Bun ships no path-joining primitive: `join`/`isAbsolute` resolve a part path against the cwd. import { isAbsolute, join } from 'node:path'; -import { nearestName, renderFixShellArg } from '@ultimat3/core'; import { requireAppRoot } from './app-root'; import { verifySpec } from './cmd-verify-spec'; import type { CliCommand, CommandContext } from './command'; -import { BadFlagError, MissingPositionalError } from './errors'; +import { MissingPositionalError } from './errors'; import { readIntFlag } from './flag-number'; import type { CommandResult, JsonValue } from './output'; import type { ParsedArgs } from './parse'; @@ -25,6 +24,7 @@ import { VERIFY_STEPS } from './verify-checks'; import { readVerifyFloor } from './verify-floor'; import type { VerifyPart } from './verify-merge'; import { coverageRiders, mergeParts, parsePart, VerifyMergeInputError } from './verify-merge'; +import { readStepList } from './verify-only'; import { measurePace } from './verify-pace'; import { verifyPlanCommand } from './verify-plan'; import { withVerifyProgress } from './verify-progress'; @@ -157,44 +157,9 @@ async function mergeCommand( }); } -/** - * The steps `--only` names, or nothing: one step (`--only lint`) or a comma-separated list - * (`--only typecheck,lint,boundaries`) run in ONE process, in the gate's declared order whatever - * order they were typed in. Refused against `VERIFY_STEP_NAMES` — the same constant the runner's - * list is built from — so a typo can never be read as "narrow to no steps at all", which is a run - * that passes by checking nothing. An empty item (`lint,,drift`, a trailing comma) is refused for - * the same reason. - * - * A near miss leads with the list as it would be with each typo corrected; an item near NOTHING - * gets the gate itself rather than an invented lead, which is the rule `parse.ts` already follows - * for a command that resembles none. Both arms are commands that run. - */ -export const readOnlySteps = (args: ParsedArgs): readonly VerifyStepName[] | undefined => { - const raw = flagString(args, 'only'); - if (raw === undefined) return undefined; - const items = raw.split(',').map((item) => item.trim()); - const unknown = items.filter((item) => !isStepName(item)); - if (unknown.length === 0) { - return VERIFY_STEP_NAMES.filter((name) => items.includes(name)); - } - // An empty item corrects to nothing — never to whichever step is nearest to ''. - const corrected = items.map((item) => - isStepName(item) ? item : item === '' ? undefined : nearestName(item, VERIFY_STEP_NAMES), - ); - const fix = corrected.every((item) => item !== undefined) - ? `x verify --only ${renderFixShellArg([...new Set(corrected)].join(','), '')} --json` - : 'x verify --json'; - const named = unknown.map((item) => (item === '' ? '(empty)' : `"${item}"`)).join(', '); - throw new BadFlagError({ - flag: 'only', - command: 'verify', - reason: `${named} ${unknown.length === 1 ? 'is not a gate step' : 'are not gate steps'} (${VERIFY_STEP_NAMES.join(', ')})`, - fix, - }); -}; - -const isStepName = (raw: string): raw is VerifyStepName => - (VERIFY_STEP_NAMES as readonly string[]).includes(raw); +/** `--only`'s list, read by `verify-only.ts` — the one reader `x upgrade --only` shares. */ +export const readOnlySteps = (args: ParsedArgs): readonly VerifyStepName[] | undefined => + readStepList(args, 'verify'); /** * Both bounds are the constants the flag summary already names, so `x help verify` and the reader diff --git a/packages/cli/src/messages-upgrade.ts b/packages/cli/src/messages-upgrade.ts index 53514efb6..a2d523560 100644 --- a/packages/cli/src/messages-upgrade.ts +++ b/packages/cli/src/messages-upgrade.ts @@ -29,6 +29,12 @@ export const UPGRADE_MESSAGES = { 'cli.upgrade.typescript': 'typescript, by hand: {file} declares {from}, below the {to} the framework is checked with — run: {fix}', 'cli.upgrade.done': '{from} -> {to}: the gate is green', + 'cli.upgrade.doneScoped': + '{from} -> {to}: green on {only} only — NOT THE FULL GATE; not run: {notRun}', + 'cli.upgrade.notRun': + 'not run by this hop, so not proven yet — CI, or this machine, owes: x verify --only {steps} --json', + 'cli.upgrade.then.scoped': + 'review the diff and commit this hop to {to}; it is done only once x verify --only {steps} --json (or a bare x verify) is green on it, in CI or here, then re-run x upgrade --json for the next one', 'cli.upgrade.dryRun': '{from} -> {to}: nothing written, no gate run', 'cli.upgrade.guard': 'guard, yours to take or leave: {fix}', 'cli.upgrade.doctorWarning': 'doctor warning: {code}, red on the next major — fix: {fix}', diff --git a/packages/cli/src/upgrade-gate.ts b/packages/cli/src/upgrade-gate.ts index 995c411a6..8f02a952a 100644 --- a/packages/cli/src/upgrade-gate.ts +++ b/packages/cli/src/upgrade-gate.ts @@ -145,6 +145,10 @@ export interface HopGate { /** The steps that went red, whether or not they carried a finding. */ readonly failed: readonly string[]; readonly findings: readonly GateFinding[]; + /** `x upgrade --only`'s list, as run; absent when the hop ran the full gate. */ + readonly only?: readonly string[]; + /** The gate's steps this hop did NOT run, owed elsewhere (CI); absent beside a full gate. */ + readonly notRun?: readonly string[]; }; } @@ -254,6 +258,8 @@ export async function runHopGate(input: { readonly bunMoved?: CoverageRebaseline; /** The span whose codemods run first, so every later stage judges the carried-across tree. */ readonly codemods?: { readonly from: string; readonly to: string }; + /** `x upgrade --only`: verify narrowed to these steps, a strict subset of the gate's. */ + readonly only?: { readonly steps: readonly string[]; readonly notRun: readonly string[] }; }): Promise { const { runner, root, onStage } = input; const installed = (args: readonly string[]): Promise => @@ -294,7 +300,15 @@ export async function runHopGate(input: { // Before `verify`, from the report that exercise just wrote: the gate judges the figures it holds. const exerciseFloor = await ratchetExerciseFloor(root, stamp); onStage('verify'); - const verify = readVerify(await installed(['verify', '--json'])); + const { only } = input; + const verify = + only === undefined + ? readVerify(await installed(['verify', '--json'])) + : { + ...readVerify(await installed(['verify', '--only', only.steps.join(','), '--json'])), + only: only.steps, + notRun: only.notRun, + }; return { codemods, superseded, diff --git a/packages/cli/src/upgrade-report.ts b/packages/cli/src/upgrade-report.ts index 99628a015..cd9bb8706 100644 --- a/packages/cli/src/upgrade-report.ts +++ b/packages/cli/src/upgrade-report.ts @@ -34,11 +34,18 @@ export interface PlannedWrites { readonly manual: readonly BunManual[]; } -/** The strongest check a hop had: the verdict `done` rests on, stated rather than implied. */ -export type HopProof = 'verify' | 'scripts' | 'none'; +/** + * The strongest check a hop had: the verdict `done` rests on, stated rather than implied. + * `verify-only` is `x upgrade --only`'s: green on some steps, the rest in `verify.notRun`. + */ +export type HopProof = 'verify' | 'verify-only' | 'scripts' | 'none'; -export const proofOf = (gate: HopGate | undefined, scripts: readonly RepoScript[]): HopProof => - gate !== undefined ? 'verify' : scripts.length > 0 ? 'scripts' : 'none'; +const notRunOf = (gate: HopGate | undefined): readonly string[] => gate?.verify.notRun ?? []; + +export const proofOf = (gate: HopGate | undefined, scripts: readonly RepoScript[]): HopProof => { + if (gate !== undefined) return notRunOf(gate).length > 0 ? 'verify-only' : 'verify'; + return scripts.length > 0 ? 'scripts' : 'none'; +}; /** What the agent does next, as a sentence naming the commands. */ export const thenLine = (input: { @@ -68,6 +75,10 @@ export const thenLine = (input: { : msg('cli.upgrade.then.scriptsRed', { to: hop.to }); } if (gate?.verify.ok !== true) return msg('cli.upgrade.then.red', { to: hop.to }); + const notRun = notRunOf(gate); + if (notRun.length > 0) { + return msg('cli.upgrade.then.scoped', { to: hop.to, steps: notRun.join(',') }); + } return hop.next === null ? msg('cli.upgrade.then.last', { to: hop.to }) : msg('cli.upgrade.then.walk', { to: hop.to, next: hop.next }); @@ -154,6 +165,9 @@ export const humanLines = ( ...scripts .filter((script) => script.ok === false) .map((script) => msg('cli.upgrade.scriptRed', { name: script.name })), + ...(notRunOf(gate).length === 0 + ? [] + : [msg('cli.upgrade.notRun', { steps: notRunOf(gate).join(',') })]), msg('cli.upgrade.then', { then }), ]; }; diff --git a/packages/cli/src/upgrade-scope.ts b/packages/cli/src/upgrade-scope.ts new file mode 100644 index 000000000..94fe75a51 --- /dev/null +++ b/packages/cli/src/upgrade-scope.ts @@ -0,0 +1,32 @@ +// `x upgrade --only`: which of the gate's steps the hop's `x verify` runs, read before anything +// spawns. The list is `x verify --only`'s, read by the same reader (`verify-only.ts`). + +import type { CommandContext } from './command'; +import { BadFlagError } from './errors'; +import { readStepList, stepsNotIn } from './verify-only'; + +/** A scoped gate's list and the steps it leaves out: what the hop's report owes to be honest. */ +export interface GateScope { + readonly steps: readonly string[]; + readonly notRun: readonly string[]; +} + +/** + * `--only`, read before anything spawns. Every step named is the full gate, so it runs as one and + * reports as one; a repository with no `app.config.ts` runs scripts, never `x verify`, so a list + * there would narrow nothing and is refused rather than ignored. + */ +export const readScope = (ctx: CommandContext, app: boolean): GateScope | undefined => { + const steps = readStepList(ctx.args, 'upgrade'); + if (steps === undefined) return undefined; + if (!app) { + throw new BadFlagError({ + flag: 'only', + command: 'upgrade', + reason: 'no app.config.ts here, so the hop runs the typecheck and test scripts, not x verify', + fix: 'x upgrade --json', + }); + } + const notRun = stepsNotIn(steps); + return notRun.length === 0 ? undefined : { steps, notRun }; +}; diff --git a/packages/cli/src/verify-only.ts b/packages/cli/src/verify-only.ts new file mode 100644 index 000000000..ece81736f --- /dev/null +++ b/packages/cli/src/verify-only.ts @@ -0,0 +1,67 @@ +// `--only [,…]`, read once for every command that narrows the gate: `x verify --only` +// and `x upgrade --only` take the same list, refused the same way, so the two cannot disagree. + +import { nearestName, renderFixShellArg } from '@ultimat3/core'; +import { BadFlagError } from './errors'; +import type { ParsedArgs } from './parse'; +import { flagString } from './parse'; +import type { VerifyStepName } from './verify-step'; +import { VERIFY_STEP_NAMES } from './verify-step'; + +/** The commands whose `--only` narrows the gate; each refusal's `fix:` re-runs the one typed. */ +export type StepListCommand = 'verify' | 'upgrade'; + +const isStepName = (raw: string): raw is VerifyStepName => + (VERIFY_STEP_NAMES as readonly string[]).includes(raw); + +/** + * The steps `--only` names, or nothing: one step (`--only lint`) or a comma-separated list + * (`--only typecheck,lint,boundaries`), in the gate's declared order whatever order they were + * typed in. Refused against `VERIFY_STEP_NAMES` — the same constant the runner's list is built + * from — so a typo can never be read as "narrow to no steps at all", which is a run that passes by + * checking nothing. An empty item (`lint,,drift`, a trailing comma) is refused for the same reason. + * + * A near miss leads with the list as it would be with each typo corrected; an item near NOTHING + * gets the command itself rather than an invented lead, which is the rule `parse.ts` already + * follows for a command that resembles none. Both arms are commands that run. + */ +export const readStepList = ( + args: ParsedArgs, + command: StepListCommand, +): readonly VerifyStepName[] | undefined => { + const raw = flagString(args, 'only'); + if (raw === undefined) return undefined; + const items = raw.split(',').map((item) => item.trim()); + const unknown = items.filter((item) => !isStepName(item)); + if (unknown.length === 0) { + return VERIFY_STEP_NAMES.filter((name) => items.includes(name)); + } + // An empty item corrects to nothing — never to whichever step is nearest to ''. + const corrected = items.map((item) => + isStepName(item) ? item : item === '' ? undefined : nearestName(item, VERIFY_STEP_NAMES), + ); + const list = corrected.every((item) => item !== undefined) + ? renderFixShellArg([...new Set(corrected)].join(','), '') + : undefined; + throw new BadFlagError({ + flag: 'only', + command, + reason: `${reasonOf(unknown)} (${VERIFY_STEP_NAMES.join(', ')})`, + fix: command === 'verify' ? verifyFix(list) : upgradeFix(list), + }); +}; + +// One literal per command: the command word never reaches a `fix:` as a spliced value. +const verifyFix = (list: string | undefined): string => + list === undefined ? 'x verify --json' : `x verify --only ${list} --json`; +const upgradeFix = (list: string | undefined): string => + list === undefined ? 'x upgrade --json' : `x upgrade --only ${list} --json`; + +const reasonOf = (unknown: readonly string[]): string => { + const named = unknown.map((item) => (item === '' ? '(empty)' : `"${item}"`)).join(', '); + return `${named} ${unknown.length === 1 ? 'is not a gate step' : 'are not gate steps'}`; +}; + +/** The gate's steps a narrowed run leaves out, in declared order: what someone else still owes. */ +export const stepsNotIn = (only: readonly string[]): readonly VerifyStepName[] => + VERIFY_STEP_NAMES.filter((name) => !only.includes(name)); diff --git a/scripts/ci-workflow-main-only.test.ts b/scripts/ci-workflow-main-only.test.ts new file mode 100644 index 000000000..32ce9acda --- /dev/null +++ b/scripts/ci-workflow-main-only.test.ts @@ -0,0 +1,78 @@ +// No check runs on `main` alone. A job that answers only after the merge reddens `main` on a green +// pull request — twice on 2026-11-19 (#1272: `deploy-proof`, `tutorial-run`). Every workflow a push +// to `main` starts runs on a pull request too, over the same paths, unless it publishes rather than +// checks; every ci.yml job a push to `main` runs, a pull request runs. + +import { describe, expect, test } from 'bun:test'; +import { readdir } from 'node:fs/promises'; // why: Bun has no directory listing primitive. +import { jobOf, readWorkflow, text } from './lib/ci-workflow-read'; +import { repoRoot } from './lib/run'; + +/** Push-only on purpose: each publishes what the gate already checked, and answers no diff. */ +const PUBLISHERS: Readonly> = { + 'wiki.yml': + 'publishes wiki/ to the GitHub wiki; the gate`s doc guards read those pages on every PR', + 'scorecard.yml': 'publishes the OpenSSF score of main; it checks no diff and never gates a merge', +}; + +const record = (value: unknown): Readonly> => + typeof value === 'object' && value !== null ? (value as Record) : {}; + +const triggersOf = async (file: string): Promise>> => + record(record(await readWorkflow(file))['on']); + +const pushesMain = (push: unknown): boolean => { + const branches = record(push)['branches']; + return Array.isArray(branches) && branches.includes('main'); +}; + +const files = (await readdir(`${repoRoot()}/.github/workflows`)).filter((name) => + name.endsWith('.yml'), +); + +describe('unit · workflows · nothing checks main alone', () => { + test('every workflow a push to main starts runs on a pull request, over the same paths', async () => { + const mainOnly: string[] = []; + const pathsDiffer: string[] = []; + for (const file of files) { + const on = await triggersOf(file); + if (!pushesMain(on['push']) || Object.hasOwn(PUBLISHERS, file)) continue; + if (!Object.hasOwn(on, 'pull_request')) { + mainOnly.push(file); + continue; + } + const pushPaths = record(on['push'])['paths']; + const prPaths = record(on['pull_request'])['paths']; + if (JSON.stringify(pushPaths) !== JSON.stringify(prPaths)) pathsDiffer.push(file); + } + expect(mainOnly, 'add `pull_request:` with the push paths, or a PUBLISHERS row').toEqual([]); + expect(pathsDiffer, 'a pull request must watch the paths main does').toEqual([]); + }); + + test('every publisher named here is still a workflow pushed on main', async () => { + for (const file of Object.keys(PUBLISHERS)) { + expect(files).toContain(file); + expect(pushesMain((await triggersOf(file))['push'])).toBe(true); + } + }); + + test('no ci.yml job a push runs is skipped on a pull request', async () => { + const ci = await readWorkflow('ci.yml'); + const pushOnly = Object.entries(ci.jobs ?? {}) + .filter(([, job]) => /github\.event_name == 'push'|refs\/heads\/main/.test(text(job.if))) + .filter(([, job]) => !text(job.if).includes("github.event_name == 'pull_request'")) + .map(([name]) => name); + expect(pushOnly).toEqual([]); + }); + + test('deploy-proof decides a pull request off its merge commit`s first parent', async () => { + const proof = jobOf(await readWorkflow('ci.yml'), 'deploy-proof'); + const checkout = (proof.steps ?? []).find((step) => text(step.uses).startsWith('actions/')); + expect(checkout?.with?.['fetch-depth']).toBe(2); + }); + + test('tutorial-run is grouped per ref: main never cancels a pull request`s run', async () => { + const tutorials = await readWorkflow('tutorial-run.yml'); + expect(tutorials.concurrency?.group).toContain('github.ref'); + }); +}); diff --git a/scripts/deploy-proof-due.test.ts b/scripts/deploy-proof-due.test.ts index 4761b4a60..1fa7afc2c 100644 --- a/scripts/deploy-proof-due.test.ts +++ b/scripts/deploy-proof-due.test.ts @@ -77,6 +77,38 @@ describe('unit · deploy-proof-due · the decision', () => { }); }); +// A proof run on main alone broke main twice after green pull requests (#1272: held-job.sh edited a +// registry shape `x new` no longer wrote). A pull request whose diff touches a deciding path now +// runs it before the merge; one that touches none has nothing the proof could answer. +describe('unit · deploy-proof-due · a pull request', () => { + const pr = (changed: readonly string[] | undefined): DeployProofInput => ({ + event: 'pull_request', + subject: 'Merge abc into def', + predecessor: undefined, + changed, + }); + + test('a pull request touching a deciding path runs the proof, naming the file', () => { + const decision = deployProofDue(pr(['wiki/Home.md', 'docker/deploy-proof/held-job.sh'])); + expect(decision).toEqual({ + run: true, + reason: 'this pull request changes docker/deploy-proof/held-job.sh', + }); + }); + + test('a pull request touching none skips, inheriting nothing — main still proves on the merge', () => { + const decision = deployProofDue(pr(['wiki/Home.md', 'packages/money/src/format.ts'])); + expect(decision.run).toBe(false); + expect(decision.base).toBeUndefined(); + expect(decision.reason).toContain('no file that decides the proof'); + }); + + test('a pull request whose diff could not be read runs it: unknown is never a skip', () => { + expect(deployProofDue(pr(undefined)).run).toBe(true); + expect(deployProofDue(pr([])).run).toBe(true); + }); +}); + describe('unit · deploy-proof-due · the paths that decide the verdict', () => { test('the chart, the image, the deploy command and the serving path decide it', () => { for (const file of [ diff --git a/scripts/deploy-proof-due.ts b/scripts/deploy-proof-due.ts index 9f1f8f7ae..d75bd175c 100644 --- a/scripts/deploy-proof-due.ts +++ b/scripts/deploy-proof-due.ts @@ -2,7 +2,8 @@ // Is ci.yml's `deploy-proof` due on this push to main? It may skip only when no file that decides // the rolling upgrade moved since a commit whose proof PASSED. Diffing against `github.event.before` // alone let a red proof on A be hidden by a B that touched no deciding path, and release.yml then -// published from B (plan 101 K15). Unknown is never a skip: every doubt runs the proof. +// published from B (plan 101 K15). On a pull request: due when its diff touches a deciding path, so +// a break lands red before the merge, not on main. Unknown is never a skip: every doubt runs it. // // bun run scripts/deploy-proof-due.ts [--json] (ci.yml; writes run= to $GITHUB_OUTPUT) @@ -50,7 +51,10 @@ export interface DeployProofInput { /** This commit's subject line. */ readonly subject: string; readonly predecessor: Predecessor | undefined; - /** Files changed between the predecessor's commit and this one; undefined when unreadable. */ + /** + * Files changed between the predecessor's commit and this one — on a pull request, between its + * base tip and its merge commit; undefined when unreadable. + */ readonly changed: readonly string[] | undefined; } @@ -71,6 +75,7 @@ export const touchesVerdict = (changed: readonly string[]): string | undefined = * deciding files equal a commit whose proof was performed and green. */ export function deployProofDue(input: DeployProofInput): DeployProofDecision { + if (input.event === 'pull_request') return pullRequestDue(input.changed); if (input.event !== 'push') return { run: true, reason: `a ${input.event} run always proves` }; if (RELEASE_SUBJECT.test(input.subject)) { return { run: true, reason: 'a release commit is proved on itself, never by inheritance' }; @@ -99,6 +104,20 @@ export function deployProofDue(input: DeployProofInput): DeployProofDecision { }; } +/** + * A pull request inherits nothing — its skip is no verdict, and the push to main after the merge + * still decides by the rule above. An empty or unreadable diff is unknown, and unknown runs. + */ +function pullRequestDue(changed: readonly string[] | undefined): DeployProofDecision { + if (changed === undefined || changed.length === 0) { + return { run: true, reason: "the pull request's diff could not be read" }; + } + const moved = touchesVerdict(changed); + return moved === undefined + ? { run: false, reason: 'no file that decides the proof is in this pull request' } + : { run: true, reason: `this pull request changes ${moved}` }; +} + /** * Unknown is never a skip, including a throw while publishing the decision. Discard any inherited * verdict and publish a forced proof once; if that publication also fails, reject so CI fails @@ -222,6 +241,15 @@ async function changedSince(base: string, cwd: string): Promise line !== '') : undefined; } +/** + * A pull request's files: its merge commit against its first parent, the base tip it was made on + * — ci.yml checks this job out at depth 2, as `changes` is. Undefined on failure. + */ +async function pullRequestFiles(cwd: string): Promise { + const diff = await run(['git', 'diff', '--no-renames', '--name-only', 'HEAD^1', 'HEAD'], { cwd }); + return diff.ok ? diff.output.split('\n').filter((line) => line !== '') : undefined; +} + if (import.meta.main) { const args = parseScriptArgs(Bun.argv.slice(2)); const cwd = repoRoot(); @@ -235,9 +263,11 @@ if (import.meta.main) { const asks = event === 'push' && !(subject.ok && RELEASE_SUBJECT.test(subject.output)); const predecessor = asks ? await readPredecessor(cwd) : undefined; const changed = - predecessor?.conclusion === 'success' - ? await changedSince(predecessor.headSha, cwd) - : undefined; + event === 'pull_request' + ? await pullRequestFiles(cwd) + : predecessor?.conclusion === 'success' + ? await changedSince(predecessor.headSha, cwd) + : undefined; return { event, subject: subject.ok ? subject.output : '', predecessor, changed }; }, async (candidate) => { diff --git a/scripts/lib/health-tutorials.test.ts b/scripts/lib/health-tutorials.test.ts index 067e02ba7..1bad8246b 100644 --- a/scripts/lib/health-tutorials.test.ts +++ b/scripts/lib/health-tutorials.test.ts @@ -34,6 +34,11 @@ describe('row 10 · the tutorials run as written', () => { expect(verdict({ runs: { message: 'HTTP 502' } })).toBe('X_HEALTH_ROW_UNREADABLE'); }); + // A pull request runs the workflow too, and its red is that pull request's, never main's. + test('the row reads main alone', () => { + expect(TUTORIALS_RUN_COMMAND).toContain(' --branch main '); + }); + test('the reader asks gh exactly what the row command says', async () => { const asked: string[] = []; const gh = async (args: readonly string[]): Promise => { diff --git a/scripts/lib/health-tutorials.ts b/scripts/lib/health-tutorials.ts index 0f29839db..6880eb6e3 100644 --- a/scripts/lib/health-tutorials.ts +++ b/scripts/lib/health-tutorials.ts @@ -1,6 +1,6 @@ -// Row 10's read, judge and command: whether the newest `tutorial-run.yml` run — tutorials 1–4 run -// fence by fence on a scaffold of `main` — ended green. That workflow runs outside `ci` and on no -// PR, so nothing else announces its red; this row is where the daily checkup reads it. +// Row 10's read, judge and command: whether the newest `tutorial-run.yml` run on `main` — tutorials +// 1–4 run fence by fence on a scaffold of it — ended green. That workflow runs outside `ci`, so +// nothing else announces main's red; a pull request's run is that pull request's, never read here. import type { RunRow } from './health-narrow'; import { jsonDocument, narrowRuns } from './health-narrow'; @@ -10,7 +10,18 @@ import { gh } from './release-due-gh'; import type { RunResult } from './run'; const FIELDS = 'databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt'; -const ARGS = ['run', 'list', '--workflow', 'tutorial-run.yml', '--limit', '1', '--json', FIELDS]; +const ARGS = [ + 'run', + 'list', + '--workflow', + 'tutorial-run.yml', + '--branch', + 'main', + '--limit', + '1', + '--json', + FIELDS, +]; // Exported for the test that pins it against the argv the reader spawns: a re-run is the same query. export const TUTORIALS_RUN_COMMAND = `gh ${ARGS.join(' ')}`; diff --git a/scripts/tutorial-run.test.ts b/scripts/tutorial-run.test.ts index 7dae9c2fe..b8e667b74 100644 --- a/scripts/tutorial-run.test.ts +++ b/scripts/tutorial-run.test.ts @@ -122,7 +122,8 @@ describe('the committed tutorials', () => { }); describe('.github/workflows/tutorial-run.yml', () => { - test('runs on a push to main touching a tutorial or a generator, never on a PR, never in ci', async () => { + // On a pull request too since 2026-11-19: main-only, it went red on a green PR's merge (#1272). + test('runs on a push to main and a PR touching a tutorial or a generator, never in ci', async () => { const text = await Bun.file(`${repoRoot()}/.github/workflows/tutorial-run.yml`).text(); const doc = Bun.YAML.parse(text) as { readonly on: { @@ -130,19 +131,22 @@ describe('.github/workflows/tutorial-run.yml', () => { readonly branches?: readonly string[]; readonly paths?: readonly string[]; }; - readonly pull_request?: unknown; + readonly pull_request?: { readonly paths?: readonly string[] }; }; readonly jobs: Readonly< Record >; }; expect(doc.on.push?.branches).toEqual(['main']); - expect(doc.on.pull_request).toBeUndefined(); + expect(doc.on.pull_request?.paths).toEqual(doc.on.push?.paths); expect(doc.on.push?.paths).toEqual( expect.arrayContaining([ 'wiki/Tutorial-0[1-4]*', 'packages/cli/src/templates/**', 'packages/cli/src/cmd-generate*', + 'packages/cli/src/cmd-db*', + 'packages/cli/src/db-*', + 'packages/cli/src/messages*', 'packages/cli/src/verify-*', ]), ); diff --git a/wiki/CLI-Reference.md b/wiki/CLI-Reference.md index 533d701cb..a4d866402 100644 --- a/wiki/CLI-Reference.md +++ b/wiki/CLI-Reference.md @@ -1761,7 +1761,7 @@ Every test leftover the framework knows of, cleared (`As of 27.3.0`): the migrat ## x upgrade ```bash -x upgrade [--to ] [--dry-run] [--json] +x upgrade [--to ] [--only [,…]] [--dry-run] [--json] x upgrade codemods --from [--to ] [--dry-run] [--json] ``` @@ -1780,6 +1780,8 @@ One major per run, so each hop's gate attributes its red to that hop. `As of 30. A dry run refuses exactly what the real run would, then stops before step 4 — after previewing this CLI's codemods for the span, written nowhere. It never commits; `git diff` is the hop. Under `--json` fd 1 is one document, fd 2 a `{"upgrade":""}` line per stage and a heartbeat a minute. +`--only [,…]` (`As of 2026-11-19`): the last stage runs `x verify --only --json` in place of `x verify --json` — the list `x verify --only` takes, in the gate's order, refused the same way (`X_CLI_BAD_FLAG`, `fix:` the corrected `x upgrade --only …`), and refused with no `app.config.ts`, where no `x verify` runs. **Not the full gate**: `proof` is `verify-only`, `verify.notRun[]` names every step left out, the summary says `NOT THE FULL GATE` and `then` names `x verify --only --json` for CI. Every step named is the full gate, reported as one. Default: the full gate. The stages before it (codemods, manifest, doctor, guards, a Bun-floor hop's coverage rebaseline, exercise) run either way: each writes what the hop leaves. + `--to`: an exact release in the next major. Over a mixed set a run moves the LOWEST pins one major: `^19` beside `^29` is told `--to 20.x.y`, that hop rewrites only the pins at or below it (a pin above is never moved backwards) and names its walkthrough, `next` names the following hop, and the last one levels the set. A straggler jump straight to the highest major is `X_UPGRADE_HOP_TOO_WIDE`: it skipped every walkthrough between. | `data` field | Meaning | @@ -1789,7 +1791,7 @@ A dry run refuses exactly what the real run would, then stops before step 4 — | `done` | verify's verdict, and the exit code follows it. `true` when already there, `false` on a dry run | | `dryRun` | nothing written, no gate run | | `app` | whether the root holds `app.config.ts` | -| `proof` | what `done` rests on: `verify`, `scripts` or `none` | +| `proof` | what `done` rests on: `verify` (the full gate), `verify-only` (`--only`: some steps, the rest in `verify.notRun`), `scripts` or `none` | | `section` | `{ title, url, local }` in [Upgrading](Upgrading); `local` is the same section as an `x docs` topic, printed whole offline; `null` when no major is crossed | | `pins[]` | `{ file, name, from, to }` | | `bun` | `{ from, to, edited[], manual[] }`. `manual[]`: `{ path, line, text, why }`, a site only you can move, listed on every run | @@ -1800,7 +1802,7 @@ A dry run refuses exactly what the real run would, then stops before step 4 — | `exerciseFloor` | `{ file, written }`: the `exercise` keys (`unprovenMax`, `statementsMax` ≥ 100) the hop's own `x exercise` measured, written into an `x.verify.json` that stated none, so the hop stays green and the floor only falls. A key the app already wrote is never touched; `null` when nothing was written | | `manifest` | `{ ok, findings[] }`. A failure does not stop the gate | | `exercise` | `{ reported, ok, findings[] }` from the hop's own `x exercise --json`, listed (and printed) before the gate's findings; each `fix` pastes as written. `reported: false`: the hop's CLI answered no exercise document — unknown, never a finding | -| `verify` | `{ ok, summary, failed[], findings[] }`, each finding `{ step?, code, cause, fix, at? }` | +| `verify` | `{ ok, summary, failed[], findings[], only?, notRun? }`, each finding `{ step?, code, cause, fix, at? }`. `only[]` and `notRun[]` only under `--only`: the steps run, and the gate's steps this hop did not run | | `codemods` | `As of 2026-11-15`: `{ from, to, dryRun, source, applied[] }`, each `applied[]` a codemod that ran: `{ id, since, summary, changed[], skipped[] }`; a `skipped[]` entry is `{ path, reason, diff? }`, a file the codemod would not overwrite (the app edited it), with the template's change as a unified diff to make by hand. `source: installed` — the hop's own CLI applied its list; `driver` — that CLI predates codemods, so this one applied its own. `reinstalled: true` — a `package.json` differs after the codemods (read byte for byte, never off a codemod's report), so the hop ran `bun install` again before any gate stage; `x upgrade codemods` does the same by hand. `failure: { code, cause, fix }` — the installed CLI's codemods run failed for a reason other than lacking the subcommand: nothing applied, this CLI does not stand in, and the hop is not done. `null`: no app, or already at the target, where no codemod runs (`As of 2026-11-18`; `x upgrade codemods --from 0.0.0 --json` carries an app still holding an old template's copy) | | `superseded[]` | `As of 2026-11-15`: a workaround the hop's framework made unnecessary, read after the codemods — `{ code: X_SUPERSEDED_WORKAROUND, cause, fix, at }`. A warning, never the verdict | | `then` | the next thing to do, in a sentence naming the commands | diff --git a/wiki/Upgrading.md b/wiki/Upgrading.md index bd47f19b1..e9d697245 100644 --- a/wiki/Upgrading.md +++ b/wiki/Upgrading.md @@ -61,6 +61,15 @@ Each entry changes a surface the table below covers. | that the tarball is attested | `npm view @ultimat3/core dist.attestations` | a `provenance` object | | every name that must move together | `bun run scripts/release-workflow.ts --json` | the 30 derived names — check each | +**A hop's gate, handed to CI in part.** `As of 2026-11-19`. A bare `x upgrade --json` runs the full `x verify` and is the default. On a loaded machine, `x upgrade --only [,…] --json` runs the hop's `x verify` on those steps alone — the list `x verify --only` takes, refused the same way — and every other stage of the hop unchanged. It is **not the full gate**, and the report says so: `proof: "verify-only"`, `verify.only[]` the steps run, `verify.notRun[]` the rest, a summary reading `NOT THE FULL GATE`, and `then` naming `x verify --only --json`. Commit the hop on a branch and let CI run the rest; the hop is proven when that is green. + +```sh +x upgrade --only typecheck,lint --json # here: two steps, and the hop +# then, in CI on the hop's commit: x verify --only --json +``` + +To leave only `unit`, `live` and `e2e` to CI, name every other step: `x help verify` lists them in the gate's order. + ## 30.x → 31.0.0, entry by entry `As of 2026-11-10`, released: the 74 breaking entries of `CHANGELOG.md`'s `## 31.0.0` section, in their order. No legacy path, no codemod, no shim. v31 is the stable line — the next major waits for its window ([Stability](Stability)). From aceb28b4853f44a8b4707d9fe43950fe2dcbeff3 Mon Sep 17 00:00:00 2001 From: sebi Date: Thu, 19 Nov 2026 02:37:24 -0500 Subject: [PATCH 2/3] fix: review findings on x upgrade --only and the main-only rule - verify.notRun counts the installed CLI's gate (its `x verify plan --parts 1`), so the follow-up names steps that CLI has; this CLI's list stands in when it has no plan. - The ci.yml job rule evaluates each `if` for a push to main and for a pull request (scripts/lib/workflow-if.ts) instead of matching text. - The tutorials health row reads `--branch main --event push`: a fork's PR from a branch named main is not main. - .dz/briefs/health.md trimmed under the platform cap with its header; brief-cap.test.ts reserves 100 characters for that header. Co-Authored-By: Claude Opus 5.5 --- .dz/briefs/health.md | 8 +- docs/history/ci-split.md | 4 +- packages/cli/src/cmd-upgrade-fixture.ts | 16 +++- packages/cli/src/cmd-upgrade-only.test.ts | 25 +++++- packages/cli/src/upgrade-gate.ts | 7 +- packages/cli/src/upgrade-scope.ts | 32 +++++++- scripts/ci-workflow-main-only.test.ts | 20 +++-- scripts/lib/brief-cap.test.ts | 17 ++++- scripts/lib/health-tutorials.test.ts | 7 +- scripts/lib/health-tutorials.ts | 5 +- scripts/lib/workflow-if.test.ts | 47 ++++++++++++ scripts/lib/workflow-if.ts | 92 +++++++++++++++++++++++ wiki/CLI-Reference.md | 2 +- 13 files changed, 258 insertions(+), 24 deletions(-) create mode 100644 scripts/lib/workflow-if.test.ts create mode 100644 scripts/lib/workflow-if.ts diff --git a/.dz/briefs/health.md b/.dz/briefs/health.md index ed47c9d31..e3237835c 100644 --- a/.dz/briefs/health.md +++ b/.dz/briefs/health.md @@ -17,7 +17,7 @@ or PR announces. No verdict is always re-run, never filed: a null `conclusion` ( | `dependabot-not-stuck` | `gh pr list --app dependabot --limit 5 --state open --json number,createdAt,updatedAt,statusCheckRollup` | green checks at any age; failed checks until >7 days since `updatedAt` (7 exactly is not over). Green: completed CheckRuns `SUCCESS`, `NEUTRAL`, `SKIPPED`, StatusContexts `SUCCESS`; terminal failures red. Pending, missing, malformed, unknown, mixed evidence = no verdict; so is a missing or invalid `updatedAt`, never replaced by `createdAt`. A page of `--limit` (5) is truncated: raise it, file nothing until short. A confirmed stuck PR files even beside a PR with unread evidence. `--state open` excludes merged and closed; `createdAt` is context, never inactivity | | `demo-shipped` | `gh run list --workflow deploy-social-demo.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt` | `success` on a `workflow_run`. Null `conclusion` = still building: read `status`. `skipped` = the `ci.yml` completion was no green push (the deploy job's `if:`): red `main-green` files it; with it green, look for a non-push `ci.yml` run. `workflow_dispatch` = an operator's run, not a push publish; `headBranch` names the ref. Other non-success: name the guard its log's `::error::` line names. The ask carries `url`, `createdAt`, `databaseId`, `displayTitle`, `headBranch` | | `release-exists` | `t=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main)`, then `gh release view "$t" --json tagName,isDraft,publishedAt` | `isDraft` false AND `publishedAt` set; a draft, or none, is unhealthy. Missing = unhealthy: gh prints `release not found` and no JSON — the message is the signal, not the exit code. Any other unreadable answer = `cannot tell` (`X_HEALTH_ROW_UNREADABLE`) | -| `tutorials-run` | `gh run list --workflow tutorial-run.yml --branch main --limit 1 --json databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt` | `success`, or no run yet (paths-filtered: nothing diverged). `cancelled` (superseded by a newer push) = re-run. Else a tutorial no longer runs as written: the ask names `url` and `bun run scripts/tutorial-run.ts --json`, whose `X_DOC_TUTORIAL_DIVERGED` names page and line | +| `tutorials-run` | `gh run list --workflow tutorial-run.yml --branch main --event push --limit 1 --json databaseId,event,status,conclusion,headBranch,displayTitle,url,createdAt` | `success`, or no run yet (paths-filtered). `cancelled` (superseded) = re-run. Else a tutorial diverged: the ask names `url` and `bun run scripts/tutorial-run.ts --json` (`X_DOC_TUTORIAL_DIVERGED`: page, line) | | `flake-hunt` | `gh run list --workflow flake-hunt.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,headSha,displayTitle,url,createdAt` | `success` under 48 h; older = unhealthy, the schedule stopped. No run or `cancelled` = re-run. Else a test failed in a shuffled order: open `flake-hunt` issues name test, seed, rerun | | `bench` | `gh run list --workflow bench.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,headSha,displayTitle,url,createdAt` | `success` under 8 days; older = the weekly schedule stopped. No run or `cancelled` = re-run. Else a figure failed to measure | | `compat` | `gh run list --workflow compat.yml --limit 1 --json databaseId,event,status,conclusion,headBranch,headSha,displayTitle,url,createdAt` | `success` under 8 days; older = the schedule stopped. No run or `cancelled` = re-run. Else a cell is red: open `compat` issues name each and its replay | @@ -34,9 +34,9 @@ One ask per unhealthy row unless an open issue names it, titled by the signal (` `publish failed: `, `Dependabot # failed checks, inactive since `), its body the command, its output and the failing run's URL. A red `main` first: nothing releases from it. -A `Dependabot` npm-bump ask carries cause and repair: Dependabot cannot write `bun.lock`, so its -lock is stale by construction; a pin left behind fails `X_RELEASE_VERSION_SKEW`; the repair is -`bun run lockfile:fix`; a conflicted lock is never merged over — the local regeneration lands first. +A `Dependabot` npm-bump ask says why and the repair: it cannot write `bun.lock`, so its lock is +stale; a pin left behind fails `X_RELEASE_VERSION_SKEW`; repair: `bun run lockfile:fix`; a +conflicted lock is never merged over — regenerate it locally first. Never re-run a publish, delete a tag, a Release or a branch, or `npm publish` from here. `PUBLISHING.md` owns every recovery; a fix ships as the next patch, never a moved tag. diff --git a/docs/history/ci-split.md b/docs/history/ci-split.md index 46fa7c890..c2b6893a1 100644 --- a/docs/history/ci-split.md +++ b/docs/history/ci-split.md @@ -362,7 +362,9 @@ path-filtered workflow never leaves a check pending — a red one is a red check `scripts/lib/health-tutorials.ts` reads `--branch main` alone, so a pull request's red is never main's health. `scripts/ci-workflow-main-only.test.ts` holds the rule: a workflow pushed on `main` with no `pull_request` trigger, or with different paths, fails unless it is a named publisher -(`wiki.yml`, `scorecard.yml`); a `ci.yml` job whose `if` admits a push and not a pull request fails. +(`wiki.yml`, `scorecard.yml`); a `ci.yml` job whose `if` runs on a push to `main` and not on a pull +request fails — each `if` evaluated for both events (`scripts/lib/workflow-if.ts`), never matched +as a substring. ## Fault drills, 2026-11-06 diff --git a/packages/cli/src/cmd-upgrade-fixture.ts b/packages/cli/src/cmd-upgrade-fixture.ts index 45492f772..39a90f64d 100644 --- a/packages/cli/src/cmd-upgrade-fixture.ts +++ b/packages/cli/src/cmd-upgrade-fixture.ts @@ -14,6 +14,7 @@ import { REQUIRED_BUN } from './app-root'; import { dispatch } from './dispatch'; import type { ExecResult, Runner } from './exec'; import { exec } from './exec'; +import { VERIFY_STEP_NAMES } from './verify-step'; const trees: TempTree[] = []; /** @@ -178,6 +179,8 @@ interface Script { readonly generateCode?: number; /** `x verify --only unit`'s stdout. */ readonly unit?: string; + /** `x verify plan --parts 1 --json`'s stdout: the installed CLI's step list (default: this CLI's). */ + readonly plan?: string; /** The installed `x upgrade codemods`' stdout and exit code; default: none ran. */ readonly codemods?: string; readonly codemodsCode?: number; @@ -196,6 +199,14 @@ export const codemodsDocument = ( data: { codemods: { ...span, dryRun: false, applied } }, }); +/** `x verify plan --parts 1 --json`, as a CLI whose gate is `steps` answers it. */ +export const planDocument = (steps: readonly string[]): string => + JSON.stringify({ + ok: true, + command: 'verify plan', + data: { parts: 1, matrix: { include: [{ part: 'gate', only: steps.join(',') }] } }, + }); + /** `boundaries`, as the installed CLI reports it: one finding per break of each guard on disk. */ const boundariesDocument = async (cwd: string, script: Script): Promise => { let count = 0; @@ -230,7 +241,8 @@ export const recording = (script: Script = {}): { runner: Runner; spawned: strin return exec(command, { ...options, env: { ...options.env, ...TEMP_TREE_GIT_ENV } }); expect(command[0]).toBe(process.execPath); const args = command.slice(1); - const only = args[2] === '--only' ? ` --only ${args[3] ?? ''}` : ''; + const only = + args[2] === '--only' ? ` --only ${args[3] ?? ''}` : args[2] === 'plan' ? ' plan' : ''; const label = args[0]?.endsWith('bin.ts') ? `x ${args[1]}${only}` : args.slice(0, 2).join(' '); spawned.push(label); if (args[0] === 'update') { @@ -285,6 +297,8 @@ export const recording = (script: Script = {}): { runner: Runner; spawned: strin ); case 'x verify --only unit': return answer(command, script.unit ?? VERIFY_GREEN); + case 'x verify plan': + return answer(command, script.plan ?? planDocument(VERIFY_STEP_NAMES)); case 'x g': if ((script.generateCode ?? 0) !== 0) return answer(command, '', script.generateCode); return answer(command, await generated(options.cwd, args[3] ?? '')); diff --git a/packages/cli/src/cmd-upgrade-only.test.ts b/packages/cli/src/cmd-upgrade-only.test.ts index 4d23a9b32..fb75ddd47 100644 --- a/packages/cli/src/cmd-upgrade-only.test.ts +++ b/packages/cli/src/cmd-upgrade-only.test.ts @@ -5,6 +5,7 @@ import { afterEach, describe, expect, test } from 'bun:test'; import { fixture, fixtureWithoutApp, + planDocument, recording, removeFixtures, run, @@ -23,7 +24,7 @@ describe('unit · x upgrade --only, a scoped gate', () => { const { runner, spawned } = recording(); // Typed out of order: the list is the gate's declared order, as `x verify --only` keeps it. const { code, output } = await run(dir, runner, ['--only', 'lint,typecheck']); - expect(spawned.at(-1)).toBe('x verify --only typecheck,lint'); + expect(spawned.slice(-2)).toEqual(['x verify plan', 'x verify --only typecheck,lint']); expect(spawned).not.toContain('x verify'); expect(code).toBe(0); expect(output.data?.proof).toBe('verify-only'); @@ -33,6 +34,28 @@ describe('unit · x upgrade --only, a scoped gate', () => { expect(output.data?.then).toContain(`x verify --only ${NOT_RUN.join(',')} --json`); }); + // The follow-up runs on the INSTALLED CLI, which may be majors older than this one: a step it + // never had is no step CI can be told to run. + test('the steps not run are the installed release`s, never this CLI`s', async () => { + const dir = await fixture(); + const older = ['typecheck', 'lint', 'unit', 'live', 'e2e']; + const { output } = await run(dir, recording({ plan: planDocument(older) }).runner, [ + '--only', + 'typecheck,lint', + ]); + expect(output.data?.verify?.notRun).toEqual(['unit', 'live', 'e2e']); + expect(output.data?.then).toContain('x verify --only unit,live,e2e --json'); + }); + + test('an installed CLI with no plan to ask: this CLI`s list stands in', async () => { + const dir = await fixture(); + const { output } = await run(dir, recording({ plan: 'error: unknown command' }).runner, [ + '--only', + 'typecheck,lint', + ]); + expect(output.data?.verify?.notRun).toEqual(NOT_RUN); + }); + test('the terminal names the steps not run and the command that runs them', async () => { const dir = await fixture(); const { lines } = await run(dir, recording().runner, ['--only', 'typecheck,lint'], { diff --git a/packages/cli/src/upgrade-gate.ts b/packages/cli/src/upgrade-gate.ts index 8f02a952a..0065c6b3e 100644 --- a/packages/cli/src/upgrade-gate.ts +++ b/packages/cli/src/upgrade-gate.ts @@ -21,6 +21,7 @@ import type { BaselinedGuard, WithheldGuard } from './upgrade-guards'; import { installMissingGuards } from './upgrade-guards'; import { parseJson } from './upgrade-registry'; import type { HopCodemods } from './upgrade-report-codemods'; +import { installedNotRun } from './upgrade-scope'; // Where it always was: `verify-exercise.ts` and `verify-budgets-build.ts` read it from here. export { documentIn } from './upgrade-document'; @@ -301,13 +302,15 @@ export async function runHopGate(input: { const exerciseFloor = await ratchetExerciseFloor(root, stamp); onStage('verify'); const { only } = input; + // The installed gate's own list first: the steps owed to CI are steps that CLI has. + const notRun = only === undefined ? undefined : await installedNotRun(installed, only); const verify = - only === undefined + only === undefined || notRun === undefined ? readVerify(await installed(['verify', '--json'])) : { ...readVerify(await installed(['verify', '--only', only.steps.join(','), '--json'])), only: only.steps, - notRun: only.notRun, + notRun, }; return { codemods, diff --git a/packages/cli/src/upgrade-scope.ts b/packages/cli/src/upgrade-scope.ts index 94fe75a51..f38f827c7 100644 --- a/packages/cli/src/upgrade-scope.ts +++ b/packages/cli/src/upgrade-scope.ts @@ -1,8 +1,12 @@ // `x upgrade --only`: which of the gate's steps the hop's `x verify` runs, read before anything -// spawns. The list is `x verify --only`'s, read by the same reader (`verify-only.ts`). +// spawns, and which it leaves out — counted against the installed CLI's gate, which may be older. +// The list is `x verify --only`'s, read by the same reader (`verify-only.ts`). +import { t } from '@ultimat3/schema'; import type { CommandContext } from './command'; import { BadFlagError } from './errors'; +import type { ExecResult } from './exec'; +import { documentIn } from './upgrade-document'; import { readStepList, stepsNotIn } from './verify-only'; /** A scoped gate's list and the steps it leaves out: what the hop's report owes to be honest. */ @@ -30,3 +34,29 @@ export const readScope = (ctx: CommandContext, app: boolean): GateScope | undefi const notRun = stepsNotIn(steps); return notRun.length === 0 ? undefined : { steps, notRun }; }; + +const PLAN = t.object({ + data: t.object({ + matrix: t.object({ include: t.array(t.object({ only: t.string })) }), + }), +}); + +/** + * The steps the INSTALLED CLI's gate has and this hop did not run: its `x verify plan --parts 1`, + * the one form that reads no app. A CLI with no plan (or no answer) leaves this CLI's list + * standing, the best evidence there is; a step it lacks then fails CI's run by name. + */ +export async function installedNotRun( + cli: (args: readonly string[]) => Promise, + scope: GateScope, +): Promise { + const parsed = PLAN.safeParse( + documentIn((await cli(['verify', 'plan', '--parts', '1', '--json'])).stdout), + ); + if (parsed.issues !== undefined) return scope.notRun; + const rows = (parsed.value as { data: { matrix: { include: readonly { only: string }[] } } }).data + .matrix.include; + const gate = new Set(rows.flatMap((row) => row.only.split(','))); + if (gate.size === 0) return scope.notRun; + return [...gate].filter((name) => name !== '' && !scope.steps.includes(name)); +} diff --git a/scripts/ci-workflow-main-only.test.ts b/scripts/ci-workflow-main-only.test.ts index 32ce9acda..4e3d4acad 100644 --- a/scripts/ci-workflow-main-only.test.ts +++ b/scripts/ci-workflow-main-only.test.ts @@ -7,6 +7,7 @@ import { describe, expect, test } from 'bun:test'; import { readdir } from 'node:fs/promises'; // why: Bun has no directory listing primitive. import { jobOf, readWorkflow, text } from './lib/ci-workflow-read'; import { repoRoot } from './lib/run'; +import { evaluateIf } from './lib/workflow-if'; /** Push-only on purpose: each publishes what the gate already checked, and answers no diff. */ const PUBLISHERS: Readonly> = { @@ -56,12 +57,21 @@ describe('unit · workflows · nothing checks main alone', () => { } }); - test('no ci.yml job a push runs is skipped on a pull request', async () => { + // Evaluated, never matched: a substring test passed an `if` that named `pull_request` inside a + // main-ref guard and so skipped every pull request (`scripts/lib/workflow-if.test.ts`). + test('no ci.yml job a push to main runs is skipped on a pull request', async () => { const ci = await readWorkflow('ci.yml'); - const pushOnly = Object.entries(ci.jobs ?? {}) - .filter(([, job]) => /github\.event_name == 'push'|refs\/heads\/main/.test(text(job.if))) - .filter(([, job]) => !text(job.if).includes("github.event_name == 'pull_request'")) - .map(([name]) => name); + const pushMain = { 'github.event_name': 'push', 'github.ref': 'refs/heads/main' }; + const pull = { 'github.event_name': 'pull_request', 'github.ref': 'refs/pull/1/merge' }; + const unreadable: string[] = []; + const pushOnly: string[] = []; + for (const [name, job] of Object.entries(ci.jobs ?? {})) { + const onPush = evaluateIf(text(job.if), pushMain); + const onPull = evaluateIf(text(job.if), pull); + if (onPush === undefined || onPull === undefined) unreadable.push(name); + else if (onPush && !onPull) pushOnly.push(name); + } + expect(unreadable, 'extend scripts/lib/workflow-if.ts to read these').toEqual([]); expect(pushOnly).toEqual([]); }); diff --git a/scripts/lib/brief-cap.test.ts b/scripts/lib/brief-cap.test.ts index b0517407d..db3e32bbd 100644 --- a/scripts/lib/brief-cap.test.ts +++ b/scripts/lib/brief-cap.test.ts @@ -13,6 +13,13 @@ setDefaultTimeout(REPO_SCAN_TIMEOUT_MS); /** The scheduled-checkup platform's ceiling, in characters (the refusal counts them, not bytes). */ const BRIEF_CAP = 10_000; +/** + * The header the platform prepends before it counts: a 9,984-character `health.md` was measured at + * 10,065 with it (PR #1274's review, 2026-11-19), so a brief that fits the bare cap could still be + * refused on every tick. 100 holds that 81 with room. + */ +const HEADER_RESERVE = 100; + const MAINTAINER = '.dz/maintainer/maintainer.yml'; const scheduledBriefs = async (): Promise => @@ -31,14 +38,16 @@ describe('unit · a scheduled brief fits the platform cap', () => { expect(briefs).toContain('.dz/briefs/release-due.md'); }); - // was: "the brief fits the platform cap" - test('every one is at most BRIEF_CAP characters', async () => { + // was: "every one is at most BRIEF_CAP characters" — the platform's header counts too. + test('every one is at most BRIEF_CAP characters, its header included', async () => { const over: string[] = []; for (const path of await scheduledBriefs()) { // Characters, as the refusal counts them: a byte length overcounts every non-ASCII dash. const length = [...(await Bun.file(join(repoRoot(), path)).text())].length; - if (length > BRIEF_CAP) - over.push(`${path}: ${String(length)} characters, cap ${String(BRIEF_CAP)}`); + if (length > BRIEF_CAP - HEADER_RESERVE) + over.push( + `${path}: ${String(length)} characters, cap ${String(BRIEF_CAP - HEADER_RESERVE)} before the platform's header`, + ); } expect(over).toEqual([]); }); diff --git a/scripts/lib/health-tutorials.test.ts b/scripts/lib/health-tutorials.test.ts index 1bad8246b..97fdf06ff 100644 --- a/scripts/lib/health-tutorials.test.ts +++ b/scripts/lib/health-tutorials.test.ts @@ -34,9 +34,10 @@ describe('row 10 · the tutorials run as written', () => { expect(verdict({ runs: { message: 'HTTP 502' } })).toBe('X_HEALTH_ROW_UNREADABLE'); }); - // A pull request runs the workflow too, and its red is that pull request's, never main's. - test('the row reads main alone', () => { - expect(TUTORIALS_RUN_COMMAND).toContain(' --branch main '); + // A pull request runs the workflow too, and its red is that pull request's, never main's — a + // fork's PR from a branch named `main` included, which `--branch` alone would let through. + test('the row reads pushes to main alone', () => { + expect(TUTORIALS_RUN_COMMAND).toContain(' --branch main --event push '); }); test('the reader asks gh exactly what the row command says', async () => { diff --git a/scripts/lib/health-tutorials.ts b/scripts/lib/health-tutorials.ts index 6880eb6e3..9c0fd376b 100644 --- a/scripts/lib/health-tutorials.ts +++ b/scripts/lib/health-tutorials.ts @@ -1,6 +1,7 @@ // Row 10's read, judge and command: whether the newest `tutorial-run.yml` run on `main` — tutorials // 1–4 run fence by fence on a scaffold of it — ended green. That workflow runs outside `ci`, so -// nothing else announces main's red; a pull request's run is that pull request's, never read here. +// nothing else announces main's red. A pull request's run — a fork's branch may be named `main` too +// — is that pull request's: `--event push` keeps it out. import type { RunRow } from './health-narrow'; import { jsonDocument, narrowRuns } from './health-narrow'; @@ -17,6 +18,8 @@ const ARGS = [ 'tutorial-run.yml', '--branch', 'main', + '--event', + 'push', '--limit', '1', '--json', diff --git a/scripts/lib/workflow-if.test.ts b/scripts/lib/workflow-if.test.ts new file mode 100644 index 000000000..35ed615ee --- /dev/null +++ b/scripts/lib/workflow-if.test.ts @@ -0,0 +1,47 @@ +// `workflow-if.ts`: the `if:` subset ci.yml writes, read the way GitHub reads it for one event — and +// undefined, never a guess, for anything outside it. + +import { describe, expect, test } from 'bun:test'; +import { expr } from './ci-workflow-read'; +import { evaluateIf } from './workflow-if'; + +const PUSH_MAIN = { 'github.event_name': 'push', 'github.ref': 'refs/heads/main' }; +const PULL = { 'github.event_name': 'pull_request', 'github.ref': 'refs/pull/7/merge' }; + +describe('unit · workflow-if', () => { + test('equality, disjunction and the precedence of && over ||', () => { + const proof = + "(github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'pull_request'"; + expect(evaluateIf(proof, PUSH_MAIN)).toBe(true); + expect(evaluateIf(proof, PULL)).toBe(true); + expect(evaluateIf(proof, { ...PUSH_MAIN, 'github.ref': 'refs/heads/next' })).toBe(false); + expect( + evaluateIf( + "github.event_name == 'push' || github.event_name == 'pull_request' && false", + PUSH_MAIN, + ), + ).toBe(true); + }); + + // The shape a substring test let through: it names `pull_request` and still skips every one. + test('a main-ref guard around the pull_request arm is false on a pull request', () => { + const narrowed = + "github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'pull_request')"; + expect(evaluateIf(narrowed, PUSH_MAIN)).toBe(true); + expect(evaluateIf(narrowed, PULL)).toBe(false); + }); + + test('an unset output is empty, status functions answer a healthy run, an expression is unwrapped', () => { + const gated = expr("!cancelled() && needs.tested.outputs.tested != 'true'"); + expect(evaluateIf(gated, PULL)).toBe(true); + expect(evaluateIf(gated, { ...PULL, 'needs.tested.outputs.tested': 'true' })).toBe(false); + expect(evaluateIf('', PULL)).toBe(true); + }); + + test('outside the subset is undefined: a function it does not know, a bad parenthesis, a stray token', () => { + expect(evaluateIf("contains(github.ref, 'main')", PULL)).toBeUndefined(); + expect(evaluateIf("(github.event_name == 'push'", PULL)).toBeUndefined(); + expect(evaluateIf("github.event_name == 'push' )", PULL)).toBeUndefined(); + expect(evaluateIf('github.event_name >= 1', PULL)).toBeUndefined(); + }); +}); diff --git a/scripts/lib/workflow-if.ts b/scripts/lib/workflow-if.ts new file mode 100644 index 000000000..5f784b020 --- /dev/null +++ b/scripts/lib/workflow-if.ts @@ -0,0 +1,92 @@ +// A job's `if:` evaluated against one event, for the workflow shape tests: the subset ci.yml writes +// — `==`, `!=`, `&&`, `||`, `!`, parentheses, quoted strings, context paths and the status +// functions. A substring test passed a condition that admitted `pull_request` and still skipped +// every one (`github.ref == 'refs/heads/main' && (… || github.event_name == 'pull_request')`). + +/** The context one evaluation reads; a path it does not name is `''`, as an unset output is. */ +export type IfContext = Readonly>; + +type Value = string | boolean; + +/** Status functions as a run that has not been cancelled or failed answers them. */ +const FUNCTIONS: ReadonlyMap = new Map([ + ['success()', true], + ['always()', true], + ['cancelled()', false], + ['failure()', false], +]); + +const WORD = /\s*(\|\||&&|==|!=|!|\(|\)|'[^']*'|[A-Za-z_][\w.-]*\(\)|[A-Za-z_][\w.-]*)/y; + +/** The words, or undefined at the first character this subset cannot read. */ +const splitWords = (source: string): readonly string[] | undefined => { + const words: string[] = []; + WORD.lastIndex = 0; + while (source.slice(WORD.lastIndex).trim() !== '') { + const match = WORD.exec(source); + if (match?.[1] === undefined) return undefined; + words.push(match[1]); + } + return words; +}; + +const truthy = (operand: Value): boolean => + typeof operand === 'boolean' ? operand : operand !== ''; + +/** + * True when the job runs for `context`; undefined for an `if` outside the subset, which a caller + * reports as unreadable rather than guessing. Every parse step answers undefined on what it cannot + * read, and each caller passes that up. + */ +export function evaluateIf(condition: string, context: IfContext): boolean | undefined { + const body = condition.trim().replace(/^\$\{\{([\s\S]*)\}\}$/, '$1'); + if (body.trim() === '') return true; + const words = splitWords(body); + if (words === undefined) return undefined; + let at = 0; + + const value = (word: string): Value | undefined => { + if (word.startsWith("'")) return word.slice(1, -1); + if (word.endsWith('()')) return FUNCTIONS.get(word); + if (word === 'true' || word === 'false') return word === 'true'; + if (['(', ')', '!', '==', '!=', '&&', '||'].includes(word)) return undefined; + return Object.hasOwn(context, word) ? (context[word] ?? '') : ''; + }; + const primary = (): Value | undefined => { + const word = words[at++]; + if (word === undefined) return undefined; + if (word === '!') { + const operand = primary(); + return operand === undefined ? undefined : !truthy(operand); + } + if (word !== '(') return value(word); + const inner = or(); + return words[at++] === ')' ? inner : undefined; + }; + const comparison = (): Value | undefined => { + const left = primary(); + const operator = words[at]; + if (left === undefined || (operator !== '==' && operator !== '!=')) return left; + at++; + const right = primary(); + if (right === undefined) return undefined; + return operator === '==' ? left === right : left !== right; + }; + const chain = (operator: '&&' | '||', next: () => Value | undefined): Value | undefined => { + const first = next(); + if (first === undefined) return undefined; + let result = truthy(first); + while (words[at] === operator) { + at++; + const operand = next(); + if (operand === undefined) return undefined; + result = operator === '&&' ? result && truthy(operand) : result || truthy(operand); + } + return result; + }; + const and = (): Value | undefined => chain('&&', comparison); + const or = (): Value | undefined => chain('||', and); + + const result = or(); + return result === undefined || at !== words.length ? undefined : truthy(result); +} diff --git a/wiki/CLI-Reference.md b/wiki/CLI-Reference.md index a4d866402..1cd4beabf 100644 --- a/wiki/CLI-Reference.md +++ b/wiki/CLI-Reference.md @@ -1780,7 +1780,7 @@ One major per run, so each hop's gate attributes its red to that hop. `As of 30. A dry run refuses exactly what the real run would, then stops before step 4 — after previewing this CLI's codemods for the span, written nowhere. It never commits; `git diff` is the hop. Under `--json` fd 1 is one document, fd 2 a `{"upgrade":""}` line per stage and a heartbeat a minute. -`--only [,…]` (`As of 2026-11-19`): the last stage runs `x verify --only --json` in place of `x verify --json` — the list `x verify --only` takes, in the gate's order, refused the same way (`X_CLI_BAD_FLAG`, `fix:` the corrected `x upgrade --only …`), and refused with no `app.config.ts`, where no `x verify` runs. **Not the full gate**: `proof` is `verify-only`, `verify.notRun[]` names every step left out, the summary says `NOT THE FULL GATE` and `then` names `x verify --only --json` for CI. Every step named is the full gate, reported as one. Default: the full gate. The stages before it (codemods, manifest, doctor, guards, a Bun-floor hop's coverage rebaseline, exercise) run either way: each writes what the hop leaves. +`--only [,…]` (`As of 2026-11-19`): the last stage runs `x verify --only --json` in place of `x verify --json` — the list `x verify --only` takes, in the gate's order, refused the same way (`X_CLI_BAD_FLAG`, `fix:` the corrected `x upgrade --only …`), and refused with no `app.config.ts`, where no `x verify` runs. **Not the full gate**: `proof` is `verify-only`, `verify.notRun[]` names every step left out — of the installed CLI's gate, read off its `x verify plan --parts 1 --json` (this CLI's list when it has no plan), the summary says `NOT THE FULL GATE` and `then` names `x verify --only --json` for CI. Every step named is the full gate, reported as one. Default: the full gate. The stages before it (codemods, manifest, doctor, guards, a Bun-floor hop's coverage rebaseline, exercise) run either way: each writes what the hop leaves. `--to`: an exact release in the next major. Over a mixed set a run moves the LOWEST pins one major: `^19` beside `^29` is told `--to 20.x.y`, that hop rewrites only the pins at or below it (a pin above is never moved backwards) and names its walkthrough, `next` names the following hop, and the last one levels the set. A straggler jump straight to the highest major is `X_UPGRADE_HOP_TOO_WIDE`: it skipped every walkthrough between. From 38253ef173ff5ea0d5aa9f5d020c1f3c9d0b5da8 Mon Sep 17 00:00:00 2001 From: sebi Date: Thu, 19 Nov 2026 02:50:24 -0500 Subject: [PATCH 3/3] fix(cli): x upgrade --only naming the installed gate's every step runs it as the full gate Co-Authored-By: Claude Opus 5.5 --- packages/cli/src/cmd-upgrade-only.test.ts | 12 ++++++++++++ packages/cli/src/upgrade-gate.ts | 5 +++-- wiki/CLI-Reference.md | 2 +- 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/packages/cli/src/cmd-upgrade-only.test.ts b/packages/cli/src/cmd-upgrade-only.test.ts index fb75ddd47..4af244578 100644 --- a/packages/cli/src/cmd-upgrade-only.test.ts +++ b/packages/cli/src/cmd-upgrade-only.test.ts @@ -47,6 +47,18 @@ describe('unit · x upgrade --only, a scoped gate', () => { expect(output.data?.then).toContain('x verify --only unit,live,e2e --json'); }); + // An older CLI's whole gate, every step of it named: nothing is owed, so it is the full gate. + test('every step the installed release has, named: the full gate, reported as one', async () => { + const dir = await fixture(); + const older = ['typecheck', 'lint', 'unit']; + const { runner, spawned } = recording({ plan: planDocument(older) }); + const { output } = await run(dir, runner, ['--only', older.join(',')]); + expect(spawned.slice(-2)).toEqual(['x verify plan', 'x verify']); + expect(output.data?.proof).toBe('verify'); + expect(output.data?.verify).not.toHaveProperty('notRun'); + expect(output.summary).toContain('the gate is green'); + }); + test('an installed CLI with no plan to ask: this CLI`s list stands in', async () => { const dir = await fixture(); const { output } = await run(dir, recording({ plan: 'error: unknown command' }).runner, [ diff --git a/packages/cli/src/upgrade-gate.ts b/packages/cli/src/upgrade-gate.ts index 0065c6b3e..de020c26a 100644 --- a/packages/cli/src/upgrade-gate.ts +++ b/packages/cli/src/upgrade-gate.ts @@ -302,10 +302,11 @@ export async function runHopGate(input: { const exerciseFloor = await ratchetExerciseFloor(root, stamp); onStage('verify'); const { only } = input; - // The installed gate's own list first: the steps owed to CI are steps that CLI has. + // The installed gate's own list first: the steps owed to CI are steps that CLI has. None owed + // (every one of its steps named) is that CLI's full gate, run and reported as one. const notRun = only === undefined ? undefined : await installedNotRun(installed, only); const verify = - only === undefined || notRun === undefined + only === undefined || notRun === undefined || notRun.length === 0 ? readVerify(await installed(['verify', '--json'])) : { ...readVerify(await installed(['verify', '--only', only.steps.join(','), '--json'])), diff --git a/wiki/CLI-Reference.md b/wiki/CLI-Reference.md index 1cd4beabf..29fd9fbf8 100644 --- a/wiki/CLI-Reference.md +++ b/wiki/CLI-Reference.md @@ -1780,7 +1780,7 @@ One major per run, so each hop's gate attributes its red to that hop. `As of 30. A dry run refuses exactly what the real run would, then stops before step 4 — after previewing this CLI's codemods for the span, written nowhere. It never commits; `git diff` is the hop. Under `--json` fd 1 is one document, fd 2 a `{"upgrade":""}` line per stage and a heartbeat a minute. -`--only [,…]` (`As of 2026-11-19`): the last stage runs `x verify --only --json` in place of `x verify --json` — the list `x verify --only` takes, in the gate's order, refused the same way (`X_CLI_BAD_FLAG`, `fix:` the corrected `x upgrade --only …`), and refused with no `app.config.ts`, where no `x verify` runs. **Not the full gate**: `proof` is `verify-only`, `verify.notRun[]` names every step left out — of the installed CLI's gate, read off its `x verify plan --parts 1 --json` (this CLI's list when it has no plan), the summary says `NOT THE FULL GATE` and `then` names `x verify --only --json` for CI. Every step named is the full gate, reported as one. Default: the full gate. The stages before it (codemods, manifest, doctor, guards, a Bun-floor hop's coverage rebaseline, exercise) run either way: each writes what the hop leaves. +`--only [,…]` (`As of 2026-11-19`): the last stage runs `x verify --only --json` in place of `x verify --json` — the list `x verify --only` takes, in the gate's order, refused the same way (`X_CLI_BAD_FLAG`, `fix:` the corrected `x upgrade --only …`), and refused with no `app.config.ts`, where no `x verify` runs. **Not the full gate**: `proof` is `verify-only`, `verify.notRun[]` names every step left out — of the installed CLI's gate, read off its `x verify plan --parts 1 --json` (this CLI's list when it has no plan), the summary says `NOT THE FULL GATE` and `then` names `x verify --only --json` for CI. Every step named — of this CLI's gate, or of the installed one's — is the full gate, run and reported as one. Default: the full gate. The stages before it (codemods, manifest, doctor, guards, a Bun-floor hop's coverage rebaseline, exercise) run either way: each writes what the hop leaves. `--to`: an exact release in the next major. Over a mixed set a run moves the LOWEST pins one major: `^19` beside `^29` is told `--to 20.x.y`, that hop rewrites only the pins at or below it (a pin above is never moved backwards) and names its walkthrough, `next` names the following hop, and the last one levels the set. A straggler jump straight to the highest major is `X_UPGRADE_HOP_TOO_WIDE`: it skipped every walkthrough between.