rungate 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/lib/agents-md-sections.ts +144 -0
  2. package/lib/branch-diff.ts +139 -0
  3. package/lib/bun-version.ts +268 -0
  4. package/lib/ci-checkout.ts +1 -1
  5. package/lib/compliance.ts +13 -11
  6. package/lib/config-loader.ts +12 -0
  7. package/lib/conformity.ts +184 -88
  8. package/lib/context-docs.ts +143 -28
  9. package/lib/create-brief.ts +2 -1
  10. package/lib/create-sc.ts +90 -4
  11. package/lib/doc-scan-targets.ts +9 -0
  12. package/lib/evidence-command-transport.ts +160 -0
  13. package/lib/evidence-prevalidator.ts +22 -0
  14. package/lib/fallow-availability.ts +129 -0
  15. package/lib/gate-refusal-currency.ts +112 -0
  16. package/lib/gate-timeouts.ts +82 -0
  17. package/lib/generators/agent-briefs.ts +4 -1
  18. package/lib/generators/agents-md.ts +71 -23
  19. package/lib/generators/code-map.ts +2 -1
  20. package/lib/generators/types.ts +8 -0
  21. package/lib/git-dates.ts +55 -0
  22. package/lib/junit-checks.ts +484 -0
  23. package/lib/local-calendar-day.ts +78 -0
  24. package/lib/project-state-shape.ts +59 -0
  25. package/lib/promote-outputs.ts +6 -2
  26. package/lib/report-provenance.ts +156 -0
  27. package/lib/sc-claim-forms.ts +75 -0
  28. package/lib/sc-id-cross-tree.ts +311 -0
  29. package/lib/scaffold/ai-review-step.ts +180 -0
  30. package/lib/scaffold/owned-files.ts +42 -2
  31. package/lib/scaffold/rehearsal.ts +205 -71
  32. package/lib/scaffold/steps.ts +128 -73
  33. package/lib/scaffold/write-steps.ts +6 -4
  34. package/lib/scanner.ts +38 -12
  35. package/lib/spec-listing.ts +148 -0
  36. package/lib/spec-requirements.ts +209 -0
  37. package/lib/suite-run-reading.ts +170 -0
  38. package/lib/test-command.ts +133 -0
  39. package/lib/test-suite-lock.ts +166 -10
  40. package/lib/tool-probe.ts +120 -0
  41. package/lib/tracked-vs-ignored.ts +234 -0
  42. package/lib/validators/spec-validators.ts +3 -2
  43. package/package.json +1 -1
  44. package/scripts/audit-specs.ts +247 -12
  45. package/scripts/audit-transcript.ts +2 -1
  46. package/scripts/convert-spec.ts +2 -1
  47. package/scripts/create-sc.ts +17 -7
  48. package/scripts/create-spec.ts +2 -1
  49. package/scripts/create-success.ts +2 -1
  50. package/scripts/extract-constraints.ts +90 -19
  51. package/scripts/generate-code-map.ts +53 -12
  52. package/scripts/scaffold-project.ts +4 -1
  53. package/scripts/split-spec.ts +2 -1
  54. package/scripts/sync-sc-status.ts +57 -5
  55. package/scripts/sync-spec-tests.ts +2 -1
@@ -0,0 +1,144 @@
1
+ /**
2
+ * The one section of AGENTS.md the harness does not own (#568).
3
+ *
4
+ * `specs/bootstrap-data-flow/problem-statement.md` makes exactly one promise
5
+ * about user content surviving a scaffold run:
6
+ *
7
+ * > Everything is regenerable. All harness-managed files can be rebuilt
8
+ * > from scratch by re-running scaffold. **The only user-owned content
9
+ * > that survives regeneration is Hard Constraints in AGENTS.md**
10
+ * > (preserved between markers).
11
+ *
12
+ * Nothing implemented it. `lib/scaffold/write-steps.ts` built the file from
13
+ * a template and called `writeFileSync`, so the section and both extraction
14
+ * markers went with it. Measured on a consumer: 37 constraint lines removed
15
+ * by one run, reported as `REGENERATED: AGENTS.md`, exit 0.
16
+ *
17
+ * The cost is not the file. Those lines are the project's non-inferable
18
+ * rules — which port is destructive, which endpoint is permanently off,
19
+ * what the deploy sequence is — and an agent cannot recover them by reading
20
+ * the code, which is the entire reason the section exists. Four weeks after
21
+ * that run, an agent on that project removed a flag another issue had
22
+ * deliberately set, because nothing in the repo said why.
23
+ *
24
+ * ## Why a heading and not a marker pair
25
+ *
26
+ * The spec says "preserved between markers", and the extractor
27
+ * (`scripts/extract-constraints.ts`) does write between
28
+ * `<!-- BEGIN AUTO-EXTRACTED -->` and `<!-- END AUTO-EXTRACTED -->`. But on
29
+ * the consumer that lost them, most of the section was OUTSIDE the markers:
30
+ * eight extracted lines between them and twenty-nine hand-written ones
31
+ * after. Preserving only the marked block would have rescued the lines a
32
+ * machine can regenerate and dropped the ones only a human holds — the
33
+ * section's most valuable content, defined by the mechanism that was easiest
34
+ * to anchor on.
35
+ *
36
+ * So the unit is the **section**: the heading, and everything up to the next
37
+ * one. The markers are ordinary lines inside it and are preserved by being
38
+ * inside it, which is also what makes a project that has never run the
39
+ * extractor work the same way.
40
+ *
41
+ * ## The post-condition is the check, not the merge
42
+ *
43
+ * `preserveSections` could be wrong in a dozen ways — an anchor that is not
44
+ * there, a heading at EOF, a generated template that one day grows its own
45
+ * Hard Constraints section. Rather than reason about each, it compares
46
+ * the lines it found against the lines it produced and reports what is
47
+ * missing. A merge that silently drops something is the defect; a merge that
48
+ * names what it dropped is a refusal the caller can act on.
49
+ */
50
+
51
+ /** The heading that opens the preserved section. Case-sensitive, at the start of a line. */
52
+ const HARD_CONSTRAINTS = /^##[ \t]+Hard Constraints\b[^\n]*$/m;
53
+
54
+ /** Any other `##` heading — where the preserved section ends. */
55
+ const NEXT_H2 = /^##[ \t]+/m;
56
+
57
+ /**
58
+ * Where the preserved section is re-inserted, in order of preference.
59
+ *
60
+ * `## Rules` first, because constraints are rules and a reader scanning for
61
+ * one should not have to pass the Commands table to find the other. The
62
+ * fallbacks exist because a profile can omit sections, and an anchor that is
63
+ * not in the generated output is not an error — appending is.
64
+ */
65
+ const ANCHORS = [/^##[ \t]+Rules$/m, /^##[ \t]+Commands$/m, /^##[ \t]+Workflow$/m];
66
+
67
+ export interface SectionReading {
68
+ /** The section verbatim — heading line through the last line before the next `##`. */
69
+ text: string;
70
+ /** Its non-blank lines, heading included. The unit the loss check counts. */
71
+ lines: string[];
72
+ }
73
+
74
+ export interface PreserveResult {
75
+ /** The bytes to write. Equal to `generated` when there was nothing to preserve. */
76
+ content: string;
77
+ /** The section carried over, or null when the existing file had none. */
78
+ preserved: SectionReading | null;
79
+ /**
80
+ * Lines that were in the existing section and are not in `content`.
81
+ *
82
+ * Always empty on the paths this module controls. It is non-empty only
83
+ * when the merge itself failed, which is the case a caller must refuse on
84
+ * rather than write.
85
+ */
86
+ lost: string[];
87
+ }
88
+
89
+ /**
90
+ * Read the Hard Constraints section out of an AGENTS.md, or null.
91
+ *
92
+ * Returns null for "no such heading" AND for a heading with nothing under
93
+ * it — the second is a section somebody emptied, and carrying an empty
94
+ * heading forward would make a run that preserved nothing look identical to
95
+ * a run that preserved something.
96
+ */
97
+ export function readHardConstraints(content: string | null): SectionReading | null {
98
+ if (content === null) return null;
99
+ const open = HARD_CONSTRAINTS.exec(content);
100
+ if (open === null) return null;
101
+
102
+ const start = open.index;
103
+ const rest = content.slice(start + open[0].length);
104
+ const next = NEXT_H2.exec(rest);
105
+ const text = (next === null ? content.slice(start) : content.slice(start, start + open[0].length + next.index)).replace(/\s+$/, "");
106
+
107
+ const lines = text.split("\n").map(l => l.trim()).filter(l => l !== "");
108
+ // The heading alone is not a section. One line means nothing survived the
109
+ // last edit, and there is no content to promise anybody.
110
+ if (lines.length < 2) return null;
111
+ return { text, lines };
112
+ }
113
+
114
+ /**
115
+ * Graft the existing file's Hard Constraints section into freshly generated
116
+ * content, and report anything the graft dropped.
117
+ *
118
+ * Idempotent by construction: the section is re-inserted at the same anchor
119
+ * every run, so the second run over its own output is byte-identical, which
120
+ * is what SC-364 asks of every generator here.
121
+ */
122
+ export function preserveSections(existing: string | null, generated: string): PreserveResult {
123
+ const preserved = readHardConstraints(existing);
124
+ if (preserved === null) return { content: generated, preserved: null, lost: [] };
125
+
126
+ // A generated template that already carries the section is not a case
127
+ // today, and writing it off as impossible is how the next person finds a
128
+ // duplicate heading in a consumer's AGENTS.md. Its own section wins, and
129
+ // the post-condition below reports whatever that costs.
130
+ let content: string;
131
+ const own = readHardConstraints(generated);
132
+ if (own !== null) {
133
+ content = generated;
134
+ } else {
135
+ const anchor = ANCHORS.map(a => a.exec(generated)).find(m => m !== null) ?? null;
136
+ content =
137
+ anchor === null
138
+ ? `${generated.replace(/\s+$/, "")}\n\n${preserved.text}\n`
139
+ : `${generated.slice(0, anchor.index)}${preserved.text}\n\n${generated.slice(anchor.index)}`;
140
+ }
141
+
142
+ const have = new Set(content.split("\n").map(l => l.trim()));
143
+ return { content, preserved, lost: preserved.lines.filter(l => !have.has(l)) };
144
+ }
@@ -0,0 +1,139 @@
1
+ /**
2
+ * What THIS branch changed since the scope gate ran (#531).
3
+ *
4
+ * Three gate checks — `prove-evidence-type`, `contextual-skip-validation`
5
+ * and the ship-round repeat — decide what a run must prove from a list of
6
+ * changed files. All three built that list with
7
+ *
8
+ * git diff --name-only ${scopeSha}..HEAD
9
+ *
10
+ * Two dots compares two commits DIRECTLY. When `scopeSha` is not an ancestor
11
+ * of `HEAD`, the output also carries everything on the other side of the
12
+ * fork, and the gate attributes all of it to this branch.
13
+ *
14
+ * Measured on run `wf_e230fddc-a71`, whose `gates.scope.commitSha` was
15
+ * `247afba4`:
16
+ *
17
+ * ```
18
+ * git merge-base --is-ancestor 247afba4 HEAD -> false
19
+ * git diff --name-only 247afba4..HEAD | wc -l -> 78
20
+ * git diff --name-only 247afba4...HEAD | wc -l -> 3
21
+ * ```
22
+ *
23
+ * The branch touched three files. The gate saw seventy-eight and refused
24
+ * twice over files that do not exist on it — a `Dockerfile` it has never
25
+ * contained, and seven `.tsx` files it has never contained.
26
+ *
27
+ * Three dots diffs HEAD against the MERGE BASE, which is the question every
28
+ * one of these checks is actually asking: what did this branch do.
29
+ *
30
+ * ## Why the sha was wrong to begin with, and why three dots is not enough
31
+ *
32
+ * `247afba4` was the tip of the branch the MAIN CHECKOUT happened to be
33
+ * sitting on, while the run was shipping a worktree. `writeGateResult`
34
+ * recorded `gitSha(state.projectRoot)`. The state names `treeUnderTest`
35
+ * correctly, so the right value was available and the writer read HEAD from
36
+ * somewhere else — which is `.claude/rules/checks-must-be-able-to-fail.md`'s
37
+ * "a consumer reads a name, a producer writes a different name" in the
38
+ * smallest possible form. Both halves are fixed: the recorder reads the tree
39
+ * under test, and the readers compare branch-relative. Three dots alone
40
+ * still mis-attributes when the recorded sha came from the wrong tree, and
41
+ * the right sha alone still mis-attributes across a fork.
42
+ *
43
+ * ## An unusable diff is UNMEASURED, and says so
44
+ *
45
+ * The three call sites read `if (!diff.ok || !diff.output) return`, which
46
+ * collapses "git could not answer" into "nothing changed" — and the first of
47
+ * those is the state a check should be loudest about, because every file
48
+ * gate below it then passes for want of input. The reading keeps them apart:
49
+ * `files: null` is "could not measure", `files: []` is "measured, nothing
50
+ * changed" (`.claude/rules/config-access.md`, Silent Default Substitution).
51
+ *
52
+ * **The call sites still RETURN on `null`, and that is deliberate rather
53
+ * than an oversight.** An unreachable scope sha is an ORDINARY outcome, not
54
+ * an anomaly: a rebase during the run — which this project does on nearly
55
+ * every PR — leaves `gates.scope.commitSha` pointing at a commit no longer
56
+ * in the branch's history, and `A...HEAD` then fails. Refusing on it would
57
+ * red every rebased run, so the reading is printed as `WARN: … UNMEASURED`
58
+ * and the check declines to decide. The difference from before is that the
59
+ * decline is now visible in the gate log instead of being spelled
60
+ * `// no changed files`.
61
+ */
62
+
63
+ /** What one reading of the branch diff says. */
64
+ export interface BranchDiffReading {
65
+ /**
66
+ * The files this branch changed, or `null` when git could not answer.
67
+ * `[]` means it answered and the answer was none, which is a measurement.
68
+ */
69
+ files: string[] | null;
70
+ /** Why `files` is null. */
71
+ reason?: string;
72
+ }
73
+
74
+ /**
75
+ * An argv-form git runner, injected so the reading can be driven without git.
76
+ *
77
+ * Argv and not a command string: `scopeSha` comes out of
78
+ * `workflow-state.json`, which the run's own agents write, and the old call
79
+ * sites interpolated it straight into a shell. The sha is validated below as
80
+ * well — both, because the validation is the thing a later edit is most
81
+ * likely to widen.
82
+ */
83
+ export type DiffRunner = (args: string[]) => { ok: boolean; output: string };
84
+
85
+ /** A git object name and nothing else. */
86
+ const SHA = /^[0-9a-f]{7,64}$/;
87
+
88
+ /**
89
+ * The argv. One place, so the dot count has one binding to mutate.
90
+ *
91
+ * `-z` for the same reason `scripts/verify-merge-content.ts` uses it:
92
+ * `git diff --name-only` C-QUOTES any path holding a non-ASCII byte, a
93
+ * quote, a tab or a newline — `"caf\303\251.tsx"`, quotes included. Every
94
+ * consumer of this list is a regex on the filename, and
95
+ * `/\.(tsx|jsx|css)$/i` does not match a string ending in `"`. So a UI file
96
+ * with an accent in its name walks past `local-ui-validated` and
97
+ * `quinn-on-ui-change` without matching anything, which is #531's own defect
98
+ * — a changed-file list that is wrong about what changed — arriving through
99
+ * the encoding instead of through the dot count. `-z` emits raw bytes,
100
+ * NUL-separated, and nothing is ever re-parsed.
101
+ */
102
+ export function branchDiffArgs(scopeSha: string): string[] {
103
+ // THREE dots. See the docstring: two dots is the whole of #531.
104
+ return ["diff", "--name-only", "-z", `${scopeSha}...HEAD`];
105
+ }
106
+
107
+ /**
108
+ * The files this branch changed since `scopeSha`, branch-relative.
109
+ *
110
+ * `checkName` is carried so the UNMEASURED line names the check that could
111
+ * not measure rather than the helper that noticed.
112
+ */
113
+ export function readBranchDiff(
114
+ scopeSha: unknown,
115
+ run: DiffRunner,
116
+ checkName: string,
117
+ ): BranchDiffReading {
118
+ if (typeof scopeSha !== "string" || !SHA.test(scopeSha)) {
119
+ return {
120
+ files: null,
121
+ reason:
122
+ `${checkName}: gates.scope.commitSha is ${JSON.stringify(scopeSha)}, which is not a git ` +
123
+ `object name, so the changed-file list could not be built (#531).`,
124
+ };
125
+ }
126
+ const r = run(branchDiffArgs(scopeSha));
127
+ if (!r.ok) {
128
+ return {
129
+ files: null,
130
+ reason:
131
+ `${checkName}: \`git ${branchDiffArgs(scopeSha).join(" ")}\` failed, so the changed-file ` +
132
+ `list is UNMEASURED. This is not "nothing changed" — every file-matched gate below reads ` +
133
+ `this list, and an empty one waves all of them through (#531).`,
134
+ };
135
+ }
136
+ // NUL, not newline, and no `trim` on the paths themselves — a filename may
137
+ // legally contain a newline, and trimming one would rewrite it.
138
+ return { files: r.output.split("\0").filter(Boolean) };
139
+ }
@@ -0,0 +1,268 @@
1
+ /**
2
+ * The one Bun version for a project (#622).
3
+ *
4
+ * Nothing in this repository pinned the runtime. `.github/workflows/ci.yml`
5
+ * and `gates.yml` carried `bun-version: "latest"`, `release.yml` carried the
6
+ * literal `"1.3.14"`, the development machine ran 1.3.14 and CI's `latest`
7
+ * resolved to **1.4.3** — a full minor apart, with nothing comparing any of
8
+ * the four.
9
+ *
10
+ * `latest` is the opposite of a pin: the runtime executing a given commit can
11
+ * change between two runs of that same commit, with nothing in the diff to
12
+ * explain a new failure. Re-running a red job was also a Bun upgrade, and a
13
+ * green local run could not say which runtime produced it.
14
+ *
15
+ * ## Why this is a module and not a string in two template literals
16
+ *
17
+ * It was two, and they were fed by `harness?.ci?.bunVersion || "latest"` in
18
+ * `lib/scaffold/steps.ts` while two other workflow files — neither of them
19
+ * generated — named versions of their own. Four positions, three spellings,
20
+ * no decider. This is #87's fix for the type check and #488's for the test
21
+ * command, applied to the step directly beside them: one binding, so a
22
+ * mutation of it can show that the agreement is load-bearing rather than
23
+ * coincidental.
24
+ *
25
+ * ## The rungs, and what each one is not
26
+ *
27
+ * 1. **`.bun-version` at the project root.** The ecosystem's file:
28
+ * `oven-sh/setup-bun` reads it through `bun-version-file`, and so do
29
+ * `mise` and `asdf`. It wins because it is the file CI itself obeys —
30
+ * a resolver that preferred something else would be naming a version CI
31
+ * does not install.
32
+ * 2. **`ci.bunVersion` in the rungate config.** The field the harness has
33
+ * documented since SC-86, and the only declaration a consumer who has not
34
+ * adopted `.bun-version` has. Emitted as a literal, because there is no
35
+ * file for CI to point at.
36
+ * 3. **Nothing.** `null`, and the state is named `undeclared` rather than
37
+ * quietly becoming `latest`. `.claude/rules/config-access.md`: a built-in
38
+ * default substituted for an absent declaration must be loud, because `0`,
39
+ * `{}`, `null` and silence are all indistinguishable from success.
40
+ *
41
+ * ## What this does NOT cover
42
+ *
43
+ * - **Which bun is on the developer's PATH.** Two installations from two
44
+ * package managers sit on the issue's machine; this reports the mismatch,
45
+ * it cannot fix it. That is what `bunVersionReading` is for.
46
+ * - **Whether the declared version exists.** A pin CI cannot resolve fails
47
+ * the job, loudly, naming the value — which is the point. A
48
+ * well-formedness guard with `|| "latest"` behind it is the cheapest repair
49
+ * for that failure and is exactly the silent fallback AC-7 forbids, so
50
+ * `isPinnedBunVersion` refuses moving tags and nothing else.
51
+ * - **`package.json` `engines.bun` and `.tool-versions`.** Neither exists in
52
+ * this tree, and a rung nobody declares is a rung nothing can test. Add one
53
+ * here, with a case, if a consumer turns up on it — not before.
54
+ * - **`workflows/*.js`.** They cannot import (#69) and none of them installs
55
+ * bun; if one ever does, it reads the resolved config the way every other
56
+ * workflow prompt does.
57
+ */
58
+ import { existsSync, readFileSync } from "fs";
59
+ import { join } from "path";
60
+ import { tryLoadRungateConfig } from "./config-loader";
61
+
62
+ /** The declaration file, at the project root. The name `setup-bun` knows. */
63
+ export const BUN_VERSION_FILE = ".bun-version";
64
+
65
+ /**
66
+ * Tags that resolve to whatever shipped today. Declaring one is a declaration
67
+ * that the project is NOT pinned, which is a legitimate thing for a consumer
68
+ * to choose and is not a thing this repository may choose by accident.
69
+ */
70
+ export const MOVING_BUN_TAGS = ["latest", "canary"] as const;
71
+
72
+ export type BunVersionSource = "bun-version-file" | "config" | "undeclared";
73
+
74
+ export interface BunVersionDecision {
75
+ /** The declared version. Null only when nothing declares one. */
76
+ version: string | null;
77
+ source: BunVersionSource;
78
+ /** Why this version and not another. */
79
+ reason: string;
80
+ /**
81
+ * Both declarations present and disagreeing. Empty when they agree, or when
82
+ * only one of them exists. Reported rather than resolved in silence: two
83
+ * positions naming two versions is #621's defect, and the loser here is the
84
+ * one a human is most likely to have edited.
85
+ */
86
+ conflict: string;
87
+ }
88
+
89
+ /** Where a decision came from, spelled the way a log reader can act on. */
90
+ export function bunVersionSourceLabel(source: BunVersionSource): string {
91
+ if (source === "bun-version-file") return BUN_VERSION_FILE;
92
+ if (source === "config") return "ci.bunVersion in .claude/rungate/config.json";
93
+ return "no declaration";
94
+ }
95
+
96
+ /**
97
+ * Is this a pin — a value that names the same runtime tomorrow?
98
+ *
99
+ * Deliberately NOT a semver test. `1.0.x`, a commit sha and a download URL are
100
+ * all things `setup-bun` resolves, and narrowing this to `\d+\.\d+\.\d+` is
101
+ * the over-narrow detector that would reject a legitimate declaration and send
102
+ * someone looking for a fallback.
103
+ */
104
+ export function isPinnedBunVersion(version: string | null | undefined): boolean {
105
+ if (typeof version !== "string") return false;
106
+ const v = version.trim();
107
+ if (v === "") return false;
108
+ return !(MOVING_BUN_TAGS as readonly string[]).includes(v);
109
+ }
110
+
111
+ function fileDeclaration(root: string): string | null {
112
+ const path = join(root, BUN_VERSION_FILE);
113
+ if (!existsSync(path)) return null;
114
+ // A file that exists and says nothing is not a declaration. It is also not
115
+ // a reason to throw: `setup-bun` would fail on it anyway, and the rung below
116
+ // is a better answer than a dead scaffold.
117
+ const raw = readFileSync(path, "utf-8").trim();
118
+ return raw === "" ? null : raw;
119
+ }
120
+
121
+ function configDeclaration(root: string): string | null {
122
+ // Through the loader, never a constructed path to `.claude/rungate*`
123
+ // (`.claude/rules/config-access.md`), so both config layouts are honoured.
124
+ // It THROWS on a malformed config, deliberately: a corrupt config is never a
125
+ // missing config, and `catch {}` here is the conversion that rule forbids.
126
+ const config = tryLoadRungateConfig(root) as { ci?: { bunVersion?: unknown } } | null;
127
+ const declared = config?.ci?.bunVersion;
128
+ if (typeof declared !== "string" || declared.trim() === "") return null;
129
+ return declared.trim();
130
+ }
131
+
132
+ /** One position that declares a version, and what it says. */
133
+ export interface BunVersionDeclaration {
134
+ source: Exclude<BunVersionSource, "undeclared">;
135
+ version: string;
136
+ }
137
+
138
+ /**
139
+ * Every position in a project that declares a Bun version, in rung order.
140
+ *
141
+ * Separate from `declaredBunVersion` because the two questions are different:
142
+ * the decision is "what will CI install", and this is "who said so". A caller
143
+ * comparing positions — `scripts/contract-parity.ts` — needs the second, and
144
+ * reconstructing it from the decision's `conflict` string was the alternative:
145
+ * a consumer parsing a producer's prose, which is this repository's most
146
+ * expensive recurring mistake (#626).
147
+ */
148
+ export function bunVersionDeclarations(root: string): BunVersionDeclaration[] {
149
+ const out: BunVersionDeclaration[] = [];
150
+ const fromFile = fileDeclaration(root);
151
+ if (fromFile !== null) out.push({ source: "bun-version-file", version: fromFile });
152
+ const fromConfig = configDeclaration(root);
153
+ if (fromConfig !== null) out.push({ source: "config", version: fromConfig });
154
+ return out;
155
+ }
156
+
157
+ export function declaredBunVersion(root: string): BunVersionDecision {
158
+ const declarations = bunVersionDeclarations(root);
159
+ const fromFile = declarations.find(d => d.source === "bun-version-file")?.version ?? null;
160
+ const fromConfig = declarations.find(d => d.source === "config")?.version ?? null;
161
+ const conflict =
162
+ fromFile !== null && fromConfig !== null && fromFile !== fromConfig
163
+ ? `${BUN_VERSION_FILE} declares ${fromFile} and ci.bunVersion declares ${fromConfig}; ` +
164
+ `CI installs what ${BUN_VERSION_FILE} says, so the config field is the stale one`
165
+ : "";
166
+
167
+ if (fromFile !== null) {
168
+ return {
169
+ version: fromFile,
170
+ source: "bun-version-file",
171
+ reason: `the project declares ${BUN_VERSION_FILE}, which is the file setup-bun itself reads`,
172
+ conflict,
173
+ };
174
+ }
175
+ if (fromConfig !== null) {
176
+ return {
177
+ version: fromConfig,
178
+ source: "config",
179
+ reason: `the project declares ci.bunVersion and no ${BUN_VERSION_FILE}`,
180
+ conflict,
181
+ };
182
+ }
183
+ return {
184
+ version: null,
185
+ source: "undeclared",
186
+ reason: `the project declares neither ${BUN_VERSION_FILE} nor ci.bunVersion`,
187
+ conflict,
188
+ };
189
+ }
190
+
191
+ export type BunVersionState = "match" | "mismatch" | "undeclared";
192
+
193
+ export interface BunVersionReading {
194
+ state: BunVersionState;
195
+ /** One line, for a log somebody pastes into an issue. */
196
+ line: string;
197
+ }
198
+
199
+ /**
200
+ * What a run should say about the runtime it is running on.
201
+ *
202
+ * `running` is a parameter rather than `Bun.version` read inside, and that is
203
+ * the whole of AC-4: a comparison that reads the machine can only be driven
204
+ * with the machine's own answer, so the mismatch branch is unreachable from a
205
+ * test on any machine that is already correct — which is every machine where
206
+ * the case would be written.
207
+ */
208
+ export function bunVersionReading(decision: BunVersionDecision, running: string): BunVersionReading {
209
+ const suffix = decision.conflict ? ` WARNING: ${decision.conflict}.` : "";
210
+
211
+ if (decision.version === null) {
212
+ return {
213
+ state: "undeclared",
214
+ line:
215
+ `bun ${running} is running, and the declared version is UNMEASURED — ` +
216
+ `${decision.reason}, so this run says nothing about what CI will install.${suffix}`,
217
+ };
218
+ }
219
+ if (decision.version !== running) {
220
+ return {
221
+ state: "mismatch",
222
+ line:
223
+ `WARNING: bun ${running} is running but ${bunVersionSourceLabel(decision.source)} declares ` +
224
+ `${decision.version} — this run does NOT model CI, and a result pasted from it ` +
225
+ `describes ${running}.${suffix}`,
226
+ };
227
+ }
228
+ return {
229
+ state: "match",
230
+ line: `bun ${running} (declared in ${bunVersionSourceLabel(decision.source)}).${suffix}`,
231
+ };
232
+ }
233
+
234
+ /**
235
+ * The `with:` body of a generated `oven-sh/setup-bun` step.
236
+ *
237
+ * One function, so the generator has nothing to decide and no second place
238
+ * for a fallback to grow. It returns LINES rather than writing anything,
239
+ * which is what lets a test assert the emission for a declaration no machine
240
+ * has — including one CI cannot resolve.
241
+ */
242
+ export function setupBunWith(decision: BunVersionDecision, indent: string): string {
243
+ if (decision.source === "bun-version-file") {
244
+ return (
245
+ `${indent}# Pinned by ${BUN_VERSION_FILE} — the project's single declaration (#622).\n` +
246
+ `${indent}# setup-bun reads that file, so there is no version spelled here to drift from it.\n` +
247
+ `${indent}bun-version-file: "${BUN_VERSION_FILE}"`
248
+ );
249
+ }
250
+ if (decision.source === "config") {
251
+ return (
252
+ `${indent}# From ci.bunVersion in .claude/rungate/config.json — this project declares no\n` +
253
+ `${indent}# ${BUN_VERSION_FILE}. Add one and re-scaffold to let CI read the declaration directly.\n` +
254
+ `${indent}bun-version: "${decision.version}"`
255
+ );
256
+ }
257
+ // UNPINNED, said out loud. The value is unchanged from what this generator
258
+ // has always emitted for a project that declares nothing — changing a
259
+ // consumer's runtime without being asked is not this issue's business — but
260
+ // the silence is. An unpinned CI is a state, and a state that is not
261
+ // reportable is one nobody fixes.
262
+ return (
263
+ `${indent}# UNPINNED: ${decision.reason}, so every run of this job installs whatever\n` +
264
+ `${indent}# shipped today and re-running a red job is also a Bun upgrade. Declare a version in\n` +
265
+ `${indent}# ${BUN_VERSION_FILE} (or ci.bunVersion) and re-scaffold.\n` +
266
+ `${indent}bun-version: "latest"`
267
+ );
268
+ }
@@ -62,7 +62,7 @@ export interface CheckoutModelResult {
62
62
  export const UNMODELLED: readonly string[] = [
63
63
  "the runner OS — CI is ubuntu-latest and this runs on the developer's machine, so anything platform-dependent (BSD vs GNU flags, path casing, file watchers) is still invisible here",
64
64
  "a fresh `bun install` — node_modules is linked from the working tree rather than installed, so a missing or mis-ranged dependency still passes locally",
65
- "the bun version — CI pins `bun-version: latest` at the moment the job runs; this uses whichever bun is on PATH",
65
+ "the bun version — CI installs what `.bun-version` declares (or `ci.bunVersion` when that file is absent; the file wins, and `declaredBunVersion` reports the disagreement when both exist) and this uses whichever bun is on PATH; since #622 the run REPORTS which one it is and whether it matches, but nothing here switches runtimes, so a mismatch is announced rather than removed",
66
66
  "the PR merge commit — `actions/checkout@v4` on a pull_request checks out a merge of the head into the base, while this checks out the head alone, so a conflict-free-but-broken merge is not modelled",
67
67
  "network and API availability — CI has neither the developer's `gh` credentials (stripped) nor their network conditions",
68
68
  "files git ignores — a `.env` or a stray build artefact present locally and absent in CI is carried over only if git can see it",
package/lib/compliance.ts CHANGED
@@ -10,6 +10,7 @@
10
10
  */
11
11
  import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from "fs";
12
12
  import { join, relative } from "path";
13
+ import { probeExternalTool } from "./tool-probe";
13
14
 
14
15
  // ── Types ──────────────────────────────────────────────────
15
16
 
@@ -191,15 +192,14 @@ export function collectComplianceSurface(root: string, surface?: string[]): stri
191
192
  }
192
193
 
193
194
  // ── Tool Availability ──────────────────────────────────────
194
-
195
- function checkToolAvailable(command: string, args: string[]): boolean {
196
- try {
197
- const result = Bun.spawnSync([command, ...args], { timeout: 5_000 });
198
- return result.exitCode === 0 || result.stdout.toString().length > 0;
199
- } catch {
200
- return false;
201
- }
202
- }
195
+ //
196
+ // The probe lives in `lib/tool-probe.ts` and has THREE outcomes (#626 AC-10).
197
+ // What was here returned `false` for "agnix is not installed", "npx ran and
198
+ // failed" and "the registry timed out" alike, which is why #597's CI failures
199
+ // could be re-run red to green on an identical SHA with nothing to read that
200
+ // said why. `available` below is the same boolean these two call sites always
201
+ // wanted — the difference is that it is now a projection of a reading that
202
+ // still knows which of the three happened.
203
203
 
204
204
  // ── Layer 1: Template Compliance ───────────────────────────
205
205
 
@@ -214,8 +214,10 @@ export async function runTemplateCompliance(
214
214
  ): Promise<ComplianceReport> {
215
215
  const files = collectComplianceSurface(root, opts?.surface);
216
216
 
217
- const agnixAvailable = checkToolAvailable("agnix", ["--version"]);
218
- const reporailsAvailable = checkToolAvailable("npx", ["@reporails/cli", "version"]);
217
+ const agnixProbe = probeExternalTool("agnix", ["--version"]);
218
+ const reporailsProbe = probeExternalTool("npx", ["@reporails/cli", "version"]);
219
+ const agnixAvailable = agnixProbe.available;
220
+ const reporailsAvailable = reporailsProbe.available;
219
221
 
220
222
  // agnix: batch mode works fine for file attribution
221
223
  const agnixByFile = new Map<string, AgnixDiagnostic[]>();
@@ -107,6 +107,18 @@ export type ResolvedConfig = z.infer<typeof ResolvedConfigSchema>;
107
107
  /** ship.js:1705's fallback, kept identical so normalisation changes no run. */
108
108
  export const DEFAULT_TEST_TIMEOUT = 120000;
109
109
 
110
+ /**
111
+ * The config's path relative to a project root, in the directory layout.
112
+ *
113
+ * Exported because a reader sometimes has to NAME the file without reading
114
+ * it — `scripts/contract-parity.ts` compares what each position in a tree
115
+ * DECLARES, so it labels and plants the config by path. Writing that literal
116
+ * anywhere else is a CONFIG-1 violation and rightly so, and the fix for a
117
+ * label is the same as the fix for a read: get it from here, so there is one
118
+ * module that knows where the config lives.
119
+ */
120
+ export const RUNGATE_CONFIG_RELATIVE_PATH = join(".claude", "rungate", "config.json");
121
+
110
122
  /**
111
123
  * The resolution (ADR-002 D2(a)). `absent` is TRUTHY and carries no `.test`,
112
124
  * so the four sites that wrote `config?.test?.command || fallback` cannot