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.
- package/lib/agents-md-sections.ts +144 -0
- package/lib/branch-diff.ts +139 -0
- package/lib/bun-version.ts +268 -0
- package/lib/ci-checkout.ts +1 -1
- package/lib/compliance.ts +13 -11
- package/lib/config-loader.ts +12 -0
- package/lib/conformity.ts +184 -88
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +90 -4
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +22 -0
- package/lib/fallow-availability.ts +129 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +71 -23
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/junit-checks.ts +484 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/report-provenance.ts +156 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +311 -0
- package/lib/scaffold/ai-review-step.ts +180 -0
- package/lib/scaffold/owned-files.ts +42 -2
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +128 -73
- package/lib/scaffold/write-steps.ts +6 -4
- package/lib/scanner.ts +38 -12
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/suite-run-reading.ts +170 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +166 -10
- package/lib/tool-probe.ts +120 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/package.json +1 -1
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +17 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +90 -19
- package/scripts/generate-code-map.ts +53 -12
- package/scripts/scaffold-project.ts +4 -1
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +57 -5
- 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
|
+
}
|
package/lib/ci-checkout.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
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
|
|
218
|
-
const
|
|
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[]>();
|
package/lib/config-loader.ts
CHANGED
|
@@ -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
|