@gjsify/cli 0.36.0 → 0.37.0

package/lib/commands/affected.js

@@ -1,117 +1,59 @@
-// `gjsify affected --base <sha> [--head <ref>] [--format=...]`
+// `gjsify affected` — diff against `<base>` and emit the workspaces AFFECTED by
+// the change set: seeds plus everything that transitively depends on them. CI
+// feeds the output to `gjsify foreach test --include …`, so a single-package PR
+// tests the touched workspace and its consumers instead of the whole monorepo.
 //
-// Diffs the working tree against `<base>` and emits the set of workspaces
-// that are AFFECTED by the change set — i.e. seeds plus everything that
-// transitively depends on them. CI uses the output as the `--include`
-// filter for `gjsify foreach test`, so a typical single-package PR ends
-// up running the touched workspace + its downstream consumers instead of
-// the whole monorepo.
+// EVERY VERDICT HERE IS SCOPED TO ONE WORKFLOW: `main.yml`. That is the single
+// most misread thing in this file. "Ignored" NEVER means "irrelevant to the
+// repository" — it means "cannot change what `main.yml` builds or tests". Sibling
+// workflows gate themselves with their own `paths:` filters, so `packages/node-gi/**`
+// and `packages/napi/**` are load-bearing build inputs to THEIR workflows and still
+// belong in IGNORE here.
 //
-// EVERY VERDICT THIS FILE EMITS IS SCOPED TO ONE WORKFLOW: `main.yml`. That
-// scoping is the single most misread thing here, so it is stated before the
-// tables rather than after. The classifier is booted only by `main.yml`'s
-// `changes` job, and `main.yml` is the only workflow whose jobs consume its
-// outputs. So "ignored" NEVER means "irrelevant to the repository" — it means
-// "cannot change what `main.yml` builds or tests". Sibling workflows
-// (`prebuilds.yml`, `audit-runtimes.yml`, `node-gi.yml`, `napi.yml`,
-// `deploy-docs.yml`, …) gate themselves with their OWN `paths:` filters and are
-// unaffected by anything decided here. `IGNORE` has always worked this way —
-// `packages/node-gi/**` and `packages/napi/**` are load-bearing build inputs to
-// their own workflows and ignored here — but the table read as a global claim,
-// which is how a directory that is genuinely irrelevant to `main.yml` still
-// looks like something that must not be ignored.
+// Classifier order, first match wins: IGNORE → GLOBAL_TRIGGERS → SCRIPT_COUPLINGS
+// → TEST_ONLY → CODE (map file→workspace, then walk reverse-dep edges). IGNORE runs
+// first and therefore WINS OVER GLOBAL: `packages/infra/cli/README.md` must not
+// force a full run just because `packages/infra/cli/` is a global trigger.
 //
-// Classifier table (first-match wins) handles the cases that aren't a
-// straightforward "file lives in workspace X":
+// Integration suites run when a closure member is a dependency of an
+// `@gjsify/integration-*` workspace, or on a global trigger; e2e runs on any
+// global trigger, an explicit `tests/e2e/**` touch, or a coupling that declares it.
 //
-//   1. IGNORE  — cannot change what `main.yml` builds or tests: pure-docs /
-//      *.md / website / refs/ submodule / other workflows' files and their
-//      inputs / LICENSE / .gitignore. Discarded FIRST, before every other
-//      rule: an ignored file is never build-relevant to this workflow, not
-//      even inside a GLOBAL_TRIGGERS directory (e.g.
-//      `packages/infra/cli/README.md` must not force a full run just because
-//      `packages/infra/cli/` is a global trigger). Ignore wins over global.
+// `include-args` CONTRACT (github-actions format) — read before changing its
+// shape. The value is a SPACE-SEPARATED list of ALREADY-SHELL-SAFE tokens
+// (`--include @gjsify/fs --include @gjsify/stream`) whose only supported
+// consumption is an UNQUOTED `$INCLUDE_ARGS` expansion, where word splitting is
+// the intent. It carries NO quoting of its own, deliberately:
 //
-//   2. GLOBAL_TRIGGERS  — a non-ignored change touching infra the classifier
-//      itself depends on (`@gjsify/workspace`, `@gjsify/cli`, the bundler
-//      plugins, the lockfile, root tsconfig / package.json, this very
-//      workflow file). Emits `global=true` → CI must run the full suite. We
-//      can't trust the closure when the algorithm that computes it just
-//      changed.
-//
-//   3. SCRIPT_COUPLINGS  — a build input that reaches its consumer through a
-//      BUILD SCRIPT instead of a dependency, so the closure walk has no edge
-//      to follow. Contributes EXTRA seeds (and may force a test tier). See
-//      the table for why this cannot be inferred and must be declared.
-//
-//   4. TEST_ONLY  — every changed file under ONE workspace is a spec
-//      file, e2e fixture, or integration test. Seed = that workspace
-//      but SKIP the closure expansion (downstream consumers don't care
-//      about test code changes).
-//
-//   5. CODE (default)  — `workspacesForChangedFiles` maps file → ws,
-//      then `affectedClosure` walks reverse-dep edges.
-//
-// Integration tests are gated separately: they run when any workspace
-// in the closure appears as a `dependencies` entry of any
-// `@gjsify/integration-*` workspace, OR on a `globalTrigger`. Same for
-// e2e: any infra change OR explicit `tests/e2e/**` touch turns the e2e
-// gate on.
-//
-// Output formats:
-//
-//   --format=text             (default)   human-readable summary
-//   --format=json                         { global, workspaces[], runIntegration, runE2E, skipAll, reason }
-//   --format=globs                        one `@gjsify/<name>` per line
-//   --format=github-actions                $GITHUB_OUTPUT key=value lines
-//
-// `include-args` CONTRACT (github-actions format) — read this before changing
-// its shape. The value is a SPACE-SEPARATED list of ALREADY-SHELL-SAFE tokens:
-//
-//     include-args=--include @gjsify/fs --include @gjsify/stream
-//
-// and its only supported consumption is an UNQUOTED `$INCLUDE_ARGS` expansion
-// in a POSIX shell, where word splitting is exactly the intent. It carries NO
-// quoting of its own, deliberately:
-//
-//   * `main.yml` splices it into a `su testuser -c "… sh -c '…'"` nesting, and
-//     the result of a parameter expansion is NEVER re-scanned for quotes. When
-//     this emitted `--include '@gjsify/fs'`, the apostrophes became part of the
-//     glob, every pattern matched zero workspaces, and `foreach` exited 0 —
-//     CI "built" nothing on every selective PR run in 0.65 s (repo task #75).
-//     Pre-quoting a value for an unknown number of nesting levels cannot work;
-//     emitting tokens that need no quoting at any level can.
-//   * There are FIVE consumers of this one output — the build / browser-bundle
-//     / check / test steps splice it into a command line, and thirteen
+//   * `main.yml` splices it into a `su testuser -c "… sh -c '…'"` nesting, and the
+//     result of a parameter expansion is never re-scanned for quotes. When this
+//     emitted `--include '@gjsify/fs'` the apostrophes became part of the glob,
+//     every pattern matched zero workspaces, and `foreach` exited 0 — CI "built"
+//     nothing on every selective PR run, in 0.65 s. Pre-quoting for an unknown
+//     number of nesting levels cannot work; emitting tokens that need no quoting
+//     at any level can.
+//   * The output has two kinds of consumer: shell splices, and
 //     `contains(needs.changes.outputs.include-args, '@gjsify/…')` GitHub
-//     expressions substring-match it. A format that requires per-consumer
-//     unquoting would have to be repeated five times in the very nesting that
-//     produced the bug; `contains()` is unaffected either way (it matched the
-//     quoted spelling too, which is why the gates kept working while the build
-//     silently did nothing).
+//     expressions. Per-consumer unquoting would have to be repeated in the very
+//     nesting that produced the bug, and `contains()` is unaffected either way —
+//     it matched the quoted spelling too, which is why the gates kept working
+//     while the build silently did nothing.
 //
 // Shell-safety is ENFORCED, not assumed: `assertShellSafeWorkspaceName` rejects
-// any workspace name outside `[A-Za-z0-9@._/-]` before it is emitted. npm names
-// cannot contain those characters, so this never fires in practice — and if it
-// somehow does, the command exits non-zero, the classify step's
-// `continue-on-error` leaves the outputs unset, and CI falls back to a FULL
-// run. Failing towards "run everything" is the safe direction.
+// any name outside `[A-Za-z0-9@._/-]`. npm names cannot contain those characters,
+// so it never fires in practice; if it does, the non-zero exit leaves the classify
+// step's outputs unset and CI falls back to a FULL run — failing towards "run
+// everything" is the safe direction.
 //
-// `--changed-from-stdin` skips `git diff` entirely and reads a newline-
-// separated list of paths from stdin. Useful for local debugging and
-// for the spec suite. Stdin is slurped via `utils/stdin.ts`, NOT
-// `readFileSync(0)` — `@gjsify/fs` has no numeric-fd path, so the Node
-// idiom opens the relative file `./0` and the committed GJS classifier
-// bundle died with `ENOENT … read '0'` on every `--changed-from-stdin` run.
+// `--changed-from-stdin` reads paths from stdin instead of running `git diff`.
+// Slurped via `utils/stdin.ts`, NOT `readFileSync(0)`: `@gjsify/fs` has no
+// numeric-fd path, so the Node idiom opens the relative file `./0` and the
+// committed GJS bundle died with `ENOENT … read '0'` on every such run.
 import { spawnSync } from 'node:child_process';
-// STATIC import, never a lazy `require('node:fs')`. This package is ESM
-// (`"type": "module"`), so a bare `require` is a ReferenceError the moment the
-// line executes — and the only line that executes it sits behind
-// `if (process.env.GITHUB_OUTPUT)`, i.e. exclusively inside a GitHub Actions
-// step. That is why it survived from the command's first commit: every local
-// run and every spec took the stdout branch. There is no reason for laziness
-// here — the command already statically imports `node:child_process`, and the
-// classifier bundle resolves `node:fs` through `@gjsify/fs` like any other.
+// STATIC, never a lazy `require('node:fs')`: this package is ESM, so a bare
+// `require` is a ReferenceError — and the only line that would execute it sits
+// behind `if (process.env.GITHUB_OUTPUT)`, so it survives every local run and
+// every spec and fires only inside a GitHub Actions step.
 import { appendFileSync } from 'node:fs';
 import { readStdinLines } from '../utils/stdin.js';
 import { discoverWorkspaces, buildDependencyGraph, buildReverseDependencyGraph, affectedClosure, workspacesForChangedFiles, } from '@gjsify/workspace';
@@ -160,83 +102,61 @@ const GLOBAL_TRIGGERS = [
     /^packages\/infra\/cli\//,
     /^packages\/infra\/rolldown-plugin-gjsify\//,
     /^packages\/infra\/resolve-npm\//,
-    // The test framework every spec imports. It is a *devDependency* of
-    // virtually every workspace, so with the prod-deps-only closure below
-    // (`includeDev: false`) a change to it would otherwise yield a near-empty
-    // closure and silently skip every downstream test — yet a bug in a matcher
-    // can break assertions anywhere. Treat it as a global trigger so a
-    // `@gjsify/unit` change re-runs the full suite.
+    // The test framework every spec imports, as a *devDependency* — which the
+    // prod-deps-only closure below does not walk, so a change to it would yield a
+    // near-empty closure and silently skip every downstream test, while a bug in a
+    // matcher can break assertions anywhere.
     /^packages\/gjs\/unit\//,
-    // The composite action every CI job runs to set itself up. A change here
-    // alters the environment of the whole matrix, so it must force a full run
-    // EXPLICITLY — it already did, but only by falling through to the
-    // conservative "unmatched files" path, which is luck rather than intent.
+    // The composite action every CI job sets itself up with: a change alters the
+    // environment of the whole matrix. Listed EXPLICITLY — it previously forced a
+    // full run only by falling through to the "unmatched files" path, which is luck
+    // rather than intent.
     /^\.github\/actions\//,
     // Cross-cutting dep + lockfile + root config.
     /^gjsify-lock\.json$/,
     /^package\.json$/,
     /^tsconfig[^/]*\.json$/,
-    // The workflow file itself — a job-shape change is invisible until
-    // the workflow re-runs, so a path-filtered job can't safely apply
-    // the new shape to an in-flight PR.
+    // The workflow file itself: a job-shape change is invisible until the workflow
+    // re-runs, so a path-filtered job cannot safely apply the new shape to an
+    // in-flight PR.
     /^\.github\/workflows\/main\.yml$/,
     /^scripts\/audit-runtimes\.mjs$/,
 ];
 /**
  * Inputs OWNED BY ANOTHER WORKFLOW — build-relevant, just not to `main.yml`.
  *
- * This is the sub-table where the workflow scoping stated at the top of the
- * file is load-bearing, so each entry NAMES the workflow that does gate it.
- * The test for membership is not "is this file unimportant" (none of these
- * are) but "can `main.yml` build or test differently because of it" — and for
- * every entry the answer is no, while the owning workflow has the path in its
- * own `paths:` filter and would go red on a break.
- *
- * Adding a regex here is therefore a claim with two halves, and BOTH must
- * hold: `main.yml` must not read the path, and some other workflow must.
+ * Adding a regex here is a claim with two halves and BOTH must hold: `main.yml`
+ * must not read the path, and some other workflow must have it in its own
+ * `paths:` filter so a break still reds a PR. The test is never "is this file
+ * unimportant" — none of these are.
  */
 const OTHER_WORKFLOW_INPUTS = [
-    // Each sibling workflow's own definition. `main.yml` is deliberately
-    // absent — it is a GLOBAL_TRIGGER, since a job-shape change there is
-    // invisible until the workflow re-runs.
+    // Each sibling workflow's own definition. `main.yml` is deliberately absent: it
+    // is a GLOBAL_TRIGGER instead.
     /^\.github\/workflows\/(deploy-docs|commitlint|release|release-cut|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image|cancel-pr-runs)\.yml$/,
-    // `prebuilds.yml`'s toolchain (#838): the QEMU-emulated build script and
-    // the `changed-packages` classifier that decides which native packages a
-    // prebuild run rebuilds. `prebuilds.yml` lists `.github/prebuild-toolchain/**`
-    // in BOTH its `push` and `pull_request` `paths:` filters, so a break here
-    // reds that workflow on the same PR. `main.yml` never executes any of it —
-    // it builds no prebuild and runs no emulated leg.
+    // `prebuilds.yml`'s toolchain (#838): the QEMU-emulated build script and the
+    // classifier deciding which native packages a prebuild run rebuilds. It is in
+    // both of that workflow's `paths:` filters; `main.yml` builds no prebuild and
+    // runs no emulated leg.
     /^\.github\/prebuild-toolchain\//,
-    // The REPO-SCOPED manifest-conformance rules (#847) — `tier`, `refs-pin`,
-    // `platforms-ci` plus the `unchecked-fields` ledger. Their gate is
-    // `audit-runtimes.yml`, which runs `node scripts/audit-runtimes.mjs
-    // --check --strict` on EVERY pull_request with no `paths:` filter at all,
-    // so this content is verified on every PR regardless of what is ignored
-    // here; `prebuilds.yml` additionally declares it a shared input (#843) and
-    // rebuilds every native package when it changes.
+    // The REPO-SCOPED manifest-conformance rules (#847), gated by
+    // `audit-runtimes.yml`, which runs on EVERY pull_request with no `paths:` filter;
+    // `prebuilds.yml` also treats it as a shared input (#843).
     //
-    // The distinction that makes this safe is a real one, not a technicality:
-    // `main.yml` DOES run manifest-conformance code, but it reaches it through
-    // `scripts/verify-package-outputs.mjs` importing
-    // `packages/infra/manifest-conformance/lib/**` — the PACKAGE, a normal
-    // workspace under the `packages/infra/*` glob that maps and seeds like any
-    // other. Only the `scripts/`-side repo-scoped half is ignored, and that
-    // half is precisely the half `main.yml` does not load.
+    // The distinction is real, not a technicality: `main.yml` DOES run
+    // manifest-conformance code, but reaches it through
+    // `packages/infra/manifest-conformance/` — the PACKAGE, a normal workspace that
+    // maps and seeds like any other. Only the `scripts/`-side repo-scoped half is
+    // ignored, and that is precisely the half `main.yml` does not load.
     /^scripts\/manifest-conformance\//,
-    // The authored status data (ADR 0016) and the generator that renders it.
-    // Same two halves as the entry above, and both hold: `main.yml` reads
-    // NEITHER — it never runs `npm run status:generate` and never opens
-    // `status/`, which the grep for it confirms (the only hits are comments
-    // citing `open-todos.md` as a ledger) — while `audit-runtimes.yml` runs the
-    // `status-data` rule over exactly this data on EVERY pull_request with no
-    // `paths:` filter.
+    // The authored status data (ADR 0016) + its generator. Same two halves:
+    // `main.yml` never runs `status:generate` and never opens `status/`, while
+    // `audit-runtimes.yml` runs the `status-data` rule over it on every PR.
     //
-    // WHAT IT COSTS TODAY: `status/*.md` already fell into `IGNORE` through the
-    // generic `/\.md$/i`, so the drift was invisible for the prose files and
-    // showed up only on `status/status.json` — which matched nothing, landed in
-    // `unmatched`, and forced a FULL CI run for a file `main.yml` cannot read.
-    // Editing one package's status prose paid for the whole matrix. Naming the
-    // directory makes the `.md` case intentional rather than incidental.
+    // Naming the directory makes the `.md` case intentional rather than incidental:
+    // `status/*.md` already fell into IGNORE via the generic `/\.md$/i`, so the gap
+    // showed up only on `status/status.json`, which matched nothing, landed in
+    // `unmatched`, and paid for a FULL matrix run over a file `main.yml` cannot read.
     /^status\//,
     /^scripts\/generate-status\.mjs$/,
 ];
@@ -247,33 +167,19 @@ const IGNORE = [
     /^website\//,
     /^docs\//,
     ...OTHER_WORKFLOW_INPUTS,
-    // `.githooks/` WAS here, and that is what let #1095 break its own guard. IGNORE
-    // is applied FIRST and wins over everything, so a hook change selected nothing,
-    // the e2e tier stayed off, the PR went green and `main` went red on the push
-    // run. It is a SCRIPT_COUPLING now instead: no seeds (there is no workspace to
-    // rebuild) but `runE2E`, because tests/e2e/git-hooks-cli-bundle-staleness is the
-    // only thing that exercises the hook at all.
-    // @gjsify/node-gi (the Node-native GObject-Introspection engine, Axis 5) is
-    // NOT a gjsify workspace member — the GJS-first install/foreach tooling can't
-    // build its node-gyp addon, so the main workflow neither builds nor tests it.
-    // Its own `.github/workflows/node-gi.yml` is the source of truth (built +
-    // tested on Node). Without this carve-out its files map to no workspace and
-    // land in `unmatched`, forcing a conservative full run on every node-gi PR.
+    // Neither `@gjsify/node-gi` (the Node-native GI engine) nor `@gjsify/napi` (the
+    // N-API host over SpiderMonkey) is a gjsify workspace member: the GJS-first
+    // install/foreach tooling cannot build their node-gyp addons or Vala+C++/meson
+    // shim, so `main.yml` neither builds nor tests them and their own workflows are
+    // the source of truth. Without the carve-outs their files map to no workspace,
+    // land in `unmatched`, and force a full run on every node-gi/napi PR.
     /^packages\/node-gi\//,
-    // @gjsify/napi (the N-API host over GJS's SpiderMonkey, the forward mirror of
-    // node-gi) is likewise NOT a gjsify workspace member — the GJS-first
-    // install/foreach tooling can't build its Vala+C++/meson shim or its node-gyp
-    // test addons, so the main workflow neither builds nor tests it. Its own
-    // `.github/workflows/napi.yml` is the source of truth. Without this carve-out
-    // its files map to no workspace and force a conservative full run on every
-    // napi PR.
     /^packages\/napi\//,
     // Flatpak build/distribution tooling (SDK-extension manifest + metainfo). No
     // package-test consumers; its own `tests/e2e/flatpak-sdk-extension` runs on
-    // `tests/e2e/**` / global triggers. This used to cite `.githooks/` as the
-    // precedent — that one has since moved to SCRIPT_COUPLINGS because ignoring it
-    // let a change walk past the suite guarding it, so the precedent is now the
-    // counter-example. Worth revisiting here for the same reason.
+    // `tests/e2e/**` and global triggers. Worth revisiting: ignoring `.githooks/`
+    // for the same reason is what let a change walk past the suite guarding it (see
+    // SCRIPT_COUPLINGS), and IGNORE wins over every other rule.
     /^flatpak\//,
     /^LICENSE/,
     /^\.gitignore$/,
@@ -289,43 +195,35 @@ const TEST_PATHS = [/\.spec\.[mc]?[tj]sx?$/, /^tests\/(e2e|integration)\//];
 const SCRIPT_COUPLINGS = [
     {
         // `.githooks/pre-commit` is guarded by an e2e suite and reachable from no
-        // workspace at all — it is not source, not a dependency, and its consumer is
-        // git. So a change to it selected NOTHING, the e2e tier stayed off (it turns
-        // on for a `tests/e2e/**` touch), and the PR went green while breaking the
-        // very test written to hold the hook: #1095 edited the hook's command line,
-        // merged clean, and turned `main` red on the push run.
-        //
-        // The same shape #1028 left a note about — whoever changes the GUARDED thing
-        // walks past the guard — and the reason it repeats is that the guard's
+        // workspace at all — not source, not a dependency, its consumer is git. So a
+        // change to it selected NOTHING and the e2e tier stayed off (that turns on
+        // for a `tests/e2e/**` touch): #1095 edited the hook's command line, merged
+        // green, and turned `main` red on the push run. Same shape #1028 noted —
+        // whoever changes the GUARDED thing walks past the guard, because the guard's
         // trigger names the TEST's path instead of the thing under test.
         //
-        // No extra seeds: there is no workspace to rebuild. The whole point is the
-        // tier.
+        // No extra seeds: there is no workspace to rebuild. The tier is the point.
         match: /^\.githooks\//,
         seeds: [],
         runE2E: true,
         why: 'tests/e2e/git-hooks-cli-bundle-staleness drives .githooks/pre-commit',
     },
     {
-        // `templates/*` ARE workspaces (root `package.json#workspaces` carries
-        // a `templates/*` glob), so a template change already seeds its own
-        // `@gjsify/template-<name>`. That is not the consumer that matters.
-        //
-        // The consumer is `@gjsify/create-app`, and it is unreachable twice
-        // over: it lives at `packages/infra/create-gjsify/`, so no
-        // directory-name search finds it, and it takes the templates in
-        // through `node scripts/process-template.mjs` in its `build` script
-        // (which resolves each template's `workspace:^` specifiers and copies
-        // the result into `dist-templates/`), so there is no dependency edge
-        // either. `dist-templates/` is a build-output cache candidate, so once
-        // it is stale it stays stale.
+        // `templates/*` ARE workspaces, so a template change already seeds its own
+        // `@gjsify/template-<name>` — not the consumer that matters. That consumer is
+        // `@gjsify/create-app`, unreachable twice over: it lives at
+        // `packages/infra/create-gjsify/`, so no directory-name search finds it, and
+        // it pulls the templates in through its own `scripts/process-template.mjs`
+        // build step (which resolves each `workspace:^` specifier and copies the
+        // result into `dist-templates/`), so there is no dependency edge either.
+        // `dist-templates/` is a build-output cache candidate, so once stale it
+        // stays stale.
         match: /^templates\//,
         seeds: ['@gjsify/create-app'],
-        // …and `tests/e2e/create-app` is the ONLY thing that would notice: it
-        // scaffolds a project out of `dist-templates/` and builds it. Without
-        // this a templates-only PR got neither the regenerated templates nor
-        // the suite that exercises them. PR #853 passed only by accident of
-        // also touching root `package.json` and tripping a global trigger.
+        // `tests/e2e/create-app` is the ONLY thing that would notice — it scaffolds a
+        // project out of `dist-templates/` and builds it. Without this a
+        // templates-only PR got neither the regenerated templates nor that suite;
+        // #853 passed only by also touching root `package.json`.
         runE2E: true,
         why: '@gjsify/create-app build → node scripts/process-template.mjs reads templates/',
     },
@@ -342,11 +240,8 @@ function classifyAndExpand(workspaces, changedFiles) {
             skipAll: true,
         };
     }
-    // Drop ignored files FIRST — before the global-trigger check. An ignored
-    // file (docs, *.md, LICENSE, .gitignore, …) is never build-relevant, not
-    // even inside a GLOBAL_TRIGGERS directory: `packages/infra/cli/README.md`
-    // must NOT force a full run just because `packages/infra/cli/` is a global
-    // trigger. Ignore wins over global.
+    // Ignored files go FIRST, before the global-trigger check: ignore wins over
+    // global, so `packages/infra/cli/README.md` must not force a full run.
     const remaining = [];
     for (const f of files) {
         if (IGNORE.some((re) => re.test(f)))
@@ -378,12 +273,10 @@ function classifyAndExpand(workspaces, changedFiles) {
             }
         }
     }
-    // Map files → workspaces. Files outside any workspace stay in `unmatched`.
     const { matched, unmatched } = workspacesForChangedFiles(workspaces, remaining);
-    // SCRIPT_COUPLINGS: add the seeds no graph edge can reach. Applied BEFORE
-    // the `unmatched` bail-out so the table works for a coupled directory that
-    // is NOT itself a workspace — such a file would otherwise force a full run
-    // and the declared seeds would never be consulted.
+    // Seeds no graph edge can reach. BEFORE the `unmatched` bail-out, so the table
+    // also works for a coupled directory that is not itself a workspace — such a
+    // file would otherwise force a full run and never consult the declared seeds.
     const knownNames = new Set(workspaces.map((w) => w.name));
     const couplingSeeds = new Set();
     const couplingAccounted = new Set();
@@ -395,11 +288,10 @@ function classifyAndExpand(workspaces, changedFiles) {
         for (const h of hits)
             couplingAccounted.add(h);
         for (const s of c.seeds) {
-            // A declared seed that is not a workspace means the table has
-            // drifted from the tree (package renamed, moved, removed). Fail
-            // towards the full run and SAY SO — the whole point of this table
-            // is that a missing rebuild here is otherwise invisible, so it must
-            // never degrade quietly back into the bug it exists to prevent.
+            // A declared seed that is not a workspace means the table drifted from the
+            // tree (renamed, moved, removed). Fail towards the full run and SAY SO: a
+            // missing rebuild here is invisible, so this must never degrade quietly
+            // back into the bug the table exists to prevent.
             if (!knownNames.has(s)) {
                 return {
                     global: true,
@@ -416,10 +308,8 @@ function classifyAndExpand(workspaces, changedFiles) {
         if (c.runE2E)
             couplingRunE2E = true;
     }
-    // Unmatched-but-not-ignored files are suspicious enough to fall back to
-    // the conservative "full run" path. Examples: a new top-level dotfile,
-    // a script in `scripts/` we haven't carved out, a refs/-adjacent file.
-    // A file a coupling claimed is accounted for and does not count here.
+    // Unmatched-but-not-ignored (a new top-level dotfile, an uncarved `scripts/`
+    // file) falls back to the full run. A file a coupling claimed does not count.
     const stillUnmatched = unmatched.filter((f) => !couplingAccounted.has(f));
     if (stillUnmatched.length > 0) {
         return {
@@ -433,14 +323,13 @@ function classifyAndExpand(workspaces, changedFiles) {
     }
     for (const s of couplingSeeds)
         matched.add(s);
-    // TEST_ONLY shortcut: every remaining file is a spec / e2e / integration
-    // path, all under ONE workspace. Skip the closure expansion — test code
-    // has no downstream consumers. A coupling deliberately disables it: the
-    // extra seeds exist precisely because a downstream consumer DOES care.
+    // Every remaining file is a spec / e2e / integration path under ONE workspace, so
+    // skip the closure: test code has no downstream consumers. A coupling disables
+    // this — its extra seeds exist precisely because a consumer DOES care.
     const testOnly = couplingSeeds.size === 0 && remaining.every((f) => TEST_PATHS.some((re) => re.test(f)));
     if (testOnly && matched.size === 1) {
         const only = [...matched][0];
-        // E2E or integration test-only changes still need their own job.
+        // An e2e- or integration-only change still needs its own job.
         const touchedE2E = remaining.some((f) => f.startsWith('tests/e2e/'));
         const touchedIntegration = remaining.some((f) => f.startsWith('tests/integration/'));
         return {
@@ -452,29 +341,23 @@ function classifyAndExpand(workspaces, changedFiles) {
             skipAll: false,
         };
     }
-    // Default: closure walk over PRODUCTION dependencies only (`includeDev:
-    // false`). The closure answers "whose tests must re-run because a package
-    // they depend on changed" — and that is a RUNTIME relationship. Walking
-    // devDependency edges instead conflated it with the build/test toolchain:
-    // every workspace devDepends `@gjsify/cli`/`@gjsify/tsc`/`@gjsify/unit`,
-    // and the umbrella `@gjsify/node-polyfills` prod-depends every polyfill, so
-    // ANY single-package change fanned out to ~210 of 221 workspaces — the
-    // closure was the whole monorepo and selective CI bought almost nothing.
-    // Prod-only collapses a typical seed to a handful (e.g. sqlite 210→4,
-    // fetch 210→34) while keeping every real runtime dependent. Safe against
-    // under-selection: no `*.spec.ts` imports a *cross-package* sibling via a
-    // devDependency (the only such spec imports are self-imports, which are
-    // covered by the package being its own seed); the universal test framework
-    // `@gjsify/unit` is handled by GLOBAL_TRIGGERS above; and every push-to-
-    // main + the nightly cron still run the FULL suite as the backstop.
+    // PRODUCTION dependencies only. The closure answers "whose tests must re-run
+    // because a package they depend on changed", which is a RUNTIME relationship;
+    // walking devDependency edges conflated it with the build/test toolchain, so ANY
+    // single-package change fanned out to ~210 of 221 workspaces and selective CI
+    // bought almost nothing. Prod-only collapses a typical seed to a handful (sqlite
+    // 210→4, fetch 210→34) while keeping every real runtime dependent.
+    //
+    // Safe against under-selection: no `*.spec.ts` imports a CROSS-PACKAGE sibling
+    // via a devDependency (the only such imports are self-imports, covered by the
+    // package being its own seed), `@gjsify/unit` is a GLOBAL_TRIGGER above, and
+    // every push-to-main plus the nightly cron still run the FULL suite.
     const reverse = buildReverseDependencyGraph(workspaces, { includeDev: false });
     const closure = affectedClosure(reverse, [...matched]);
-    // Integration suites whose forward deps overlap with the closure also
-    // need to run. We walk the forward graph with `includeDev: true` here
-    // (deliberately broader than the reverse closure) so an integration suite
-    // is never missed: integration packages declare the pillars they exercise
-    // as `dependencies`, but the wider walk also tolerates a devDep-declared
-    // edge. Over-running an integration suite is cheap; missing one is not.
+    // `includeDev: true`, deliberately broader than the reverse closure: integration
+    // packages declare the pillars they exercise as `dependencies`, but the wider
+    // walk tolerates a devDep-declared edge too. Over-running an integration suite is
+    // cheap; missing one is not.
     const forward = buildDependencyGraph(workspaces, { includeDev: true });
     let runIntegration = false;
     for (const [from, deps] of forward.edges) {
@@ -488,8 +371,6 @@ function classifyAndExpand(workspaces, changedFiles) {
             }
         }
     }
-    // A `tests/e2e/**` touch turns the tier on, and so does any coupling that
-    // declares e2e as its only real coverage (see SCRIPT_COUPLINGS).
     const runE2E = remaining.some((f) => f.startsWith('tests/e2e/')) || couplingRunE2E;
     return {
         global: false,
@@ -504,33 +385,30 @@ function classifyAndExpand(workspaces, changedFiles) {
 function isIntegrationWorkspace(name) {
     return name.startsWith('@gjsify/integration-');
 }
-// ─── git diff + stdin ──────────────────────────────────────────────────────
 function runGitDiff(cwd, base, head) {
-    // `git diff --name-only base...head` lists changed paths on `head`
-    // relative to the merge-base. That matches what GitHub PR diffs show
-    // and survives stacked PRs without picking up commits from base.
+    // `base...head` lists changed paths on `head` relative to the MERGE-BASE, which
+    // matches what a GitHub PR diff shows and survives stacked PRs without picking up
+    // commits from base.
     const r = spawnSync('git', ['diff', '--name-only', `${base}...${head}`], {
         cwd,
         encoding: 'utf8',
     });
     if (r.status !== 0) {
-        // Surface a clear error — caller (CI) will fall back to full run
-        // via `continue-on-error: true` on the classify step.
+        // CI falls back to a full run via `continue-on-error: true` on the classify
+        // step.
         process.stderr.write(`gjsify affected: git diff failed (${r.status}): ${r.stderr.trim()}\n`);
-        // Under GJS `process.exit()` is DEFERRED (no atexit — the call
-        // returns), so in this synchronous, value-returning helper a bare
-        // exit fell through to the `return` below and handed the caller a
-        // diff parsed from a failed git run. `return process.exit(…)` cannot
-        // help here either — it would hand the caller the pending exit
-        // promise as a `string[]`. The throw is what actually stops the
-        // caller; on Node the exit(2) halts first and the throw is dead.
+        // Under GJS `process.exit()` is DEFERRED (no atexit — the call returns), so in
+        // this synchronous, value-returning helper a bare exit fell through to the
+        // `return` below and handed the caller a diff parsed from a failed git run.
+        // `return process.exit(…)` cannot help either: it would hand the caller the
+        // pending exit promise as a `string[]`. The throw is what stops the caller; on
+        // Node the exit(2) halts first and the throw is dead.
         // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
         process.exit(2);
         throw new Error(`gjsify affected: git diff failed (${r.status})`);
     }
     return r.stdout.split('\n').filter(Boolean);
 }
-// ─── Output ────────────────────────────────────────────────────────────────
 function emit(format, r) {
     if (format === 'json') {
         process.stdout.write(JSON.stringify(r) + '\n');
@@ -542,8 +420,8 @@ function emit(format, r) {
         return;
     }
     if (format === 'github-actions') {
-        // Unquoted, space-separated tokens — see the `include-args` CONTRACT
-        // block at the top of this file. Do NOT re-add quoting here.
+        // Unquoted, space-separated tokens — see the `include-args` CONTRACT at the
+        // top of this file. Do NOT re-add quoting here.
         const includeArgs = r.global
             ? ''
             : r.workspaces.map((n) => `--include ${assertShellSafeWorkspaceName(n)}`).join(' ');
@@ -557,7 +435,6 @@ function emit(format, r) {
             `reason=${r.reason}`,
         ];
         if (out) {
-            // GitHub Actions: append to $GITHUB_OUTPUT.
             for (const l of lines)
                 appendFileSync(out, `${l}\n`);
         }
@@ -578,12 +455,10 @@ function emit(format, r) {
     for (const name of r.workspaces)
         process.stdout.write(`    - ${name}\n`);
 }
-// A workspace name that survives an UNQUOTED shell expansion unchanged: no
-// whitespace, no quote/escape characters, no glob metacharacters, no `$`, and
-// nothing the shell would treat as an operator. npm package names are a strict
-// subset of this, so the guard is a machine-checked restatement of the
-// `include-args` contract rather than a real runtime branch. Returns the name
-// so it can be used inline at the emit site.
+// A name that survives an UNQUOTED shell expansion unchanged: no whitespace, no
+// quote/escape characters, no glob metacharacters, no `$`, nothing the shell reads
+// as an operator. npm names are a strict subset, so this is a machine-checked
+// restatement of the `include-args` contract rather than a real runtime branch.
 const SHELL_SAFE_WORKSPACE_NAME = /^[A-Za-z0-9@][A-Za-z0-9@._/-]*$/;
 function assertShellSafeWorkspaceName(name) {
     if (SHELL_SAFE_WORKSPACE_NAME.test(name))
@@ -592,10 +467,10 @@ function assertShellSafeWorkspaceName(name) {
         `  \`include-args\` token (the value is consumed by an UNQUOTED $INCLUDE_ARGS expansion — see the\n` +
         `  contract at the top of commands/affected.ts). Rename the workspace, or teach this command a\n` +
         `  transport the consumers can unquote. Refusing to emit a filter that would silently mis-match.\n`);
-    // NOT unreachable under GJS: `process.exit()` is DEFERRED there (no atexit
-    // — the call returns), so the throw below is what actually stops an unsafe
-    // name from reaching the emit site; the exit code rides the scheduled
-    // teardown. On Node the exit(2) halts first and the throw is dead code.
+    // NOT unreachable under GJS: `process.exit()` is DEFERRED there (no atexit — the
+    // call returns), so the throw below is what stops an unsafe name from reaching the
+    // emit site, and the exit code rides the scheduled teardown. On Node the exit(2)
+    // halts first and the throw is dead code.
     // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
     process.exit(2);
     throw new Error(`gjsify affected: unsafe workspace name ${name}`);