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,209 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Does a document the routing table calls a spec actually state anything? (#579)
|
|
3
|
+
*
|
|
4
|
+
* `.claude/rules/specs-routing.md` is the table every agent is told to consult
|
|
5
|
+
* before changing an area. It is generated from `specs/`, one row per file,
|
|
6
|
+
* and it promises each row GOVERNS something. Nothing checked that the
|
|
7
|
+
* document on the other end states a requirement.
|
|
8
|
+
*
|
|
9
|
+
* `specs/PROJECT-STATE.md` was a **rendered PROJECT-STATE.md snapshot from
|
|
10
|
+
* 2026-09-22 with spec frontmatter pasted on top** — a "Current phase" line, a
|
|
11
|
+
* stale priorities list, and status tables citing criteria it did not declare.
|
|
12
|
+
* It sat in the routing table as the governing spec for project state
|
|
13
|
+
* management for two months. An agent sent there before touching
|
|
14
|
+
* `scripts/update-project-state.ts` got no criteria at all.
|
|
15
|
+
*
|
|
16
|
+
* **A gap in a routing table is visible; this is not.** The reader believes
|
|
17
|
+
* they have arrived. That is the same harm as `.claude/rules/config-access.md`'s
|
|
18
|
+
* Silent Default Substitution with a document as the victim: an empty answer
|
|
19
|
+
* and a correct answer are the same shape to the consumer.
|
|
20
|
+
*
|
|
21
|
+
* ## Why the exemption is frontmatter and not an allowlist
|
|
22
|
+
*
|
|
23
|
+
* Some documents in `specs/` legitimately state no criteria —
|
|
24
|
+
* `BOOTSTRAP-DATA-FLOW-SPEC.md` is a redirect stub whose whole job is to point
|
|
25
|
+
* readers at the directory it was split into. An allowlist would cover that,
|
|
26
|
+
* and two things are wrong with one here.
|
|
27
|
+
*
|
|
28
|
+
* DRIFT-3 refuses any entry ADDED to `.claude/conformity-allowlists.json`
|
|
29
|
+
* relative to `origin/main`, because an agent must not pass a gate by editing
|
|
30
|
+
* the gate. Shipping this check with its current violators pre-listed is
|
|
31
|
+
* exactly that move, and the ratchet is right to refuse it.
|
|
32
|
+
*
|
|
33
|
+
* The better reason is that **an allowlist is invisible to the person being
|
|
34
|
+
* harmed.** The reader harmed by a criteria-free spec is the one who followed
|
|
35
|
+
* the routing table to it; a JSON file in `.claude/` is not on that path. A
|
|
36
|
+
* declaration in the document's own frontmatter is, and the generated routing
|
|
37
|
+
* table can render it, so the warning reaches the reader before they click
|
|
38
|
+
* rather than after they have read 300 lines looking for requirements.
|
|
39
|
+
*
|
|
40
|
+
* So: state criteria, or say `criteria: none` and say why. Both are honest.
|
|
41
|
+
* Silence is the thing that is not.
|
|
42
|
+
*/
|
|
43
|
+
import { existsSync, readFileSync, readdirSync, statSync } from "fs";
|
|
44
|
+
import { basename, join } from "path";
|
|
45
|
+
|
|
46
|
+
/** A checkbox criterion line, whatever id prefix it uses. */
|
|
47
|
+
const CRITERION_LINE = /^\s*- \[[ xX]\]/;
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Counted on any checkbox line rather than on `- [ ] SC-`.
|
|
51
|
+
*
|
|
52
|
+
* `BOOTSTRAP-TEST-PLAN.md` numbers its criteria `TP-1`, `TP-2`, and the first
|
|
53
|
+
* census written for this issue counted `- [ ] SC-` and reported it as
|
|
54
|
+
* stating nothing. It states 41 criteria. A detector narrower than what it
|
|
55
|
+
* detects, in the direction that accuses a correct document —
|
|
56
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`, second shape.
|
|
57
|
+
*/
|
|
58
|
+
export function countCriteria(content: string): number {
|
|
59
|
+
return content.split("\n").filter(l => CRITERION_LINE.test(l)).length;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export interface SpecRequirementReading {
|
|
63
|
+
/** Path relative to `specs/`, so a report can name it. */
|
|
64
|
+
spec: string;
|
|
65
|
+
criteria: number;
|
|
66
|
+
/** The document says it states none, in its own frontmatter. */
|
|
67
|
+
declaredNone: boolean;
|
|
68
|
+
/** Why it states none. A declaration with no reason is a mute. */
|
|
69
|
+
reason: string | null;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function frontmatterField(content: string, key: string): string | null {
|
|
73
|
+
const fm = content.match(/^---\n([\s\S]*?)\n---/);
|
|
74
|
+
if (!fm) return null;
|
|
75
|
+
const m = fm[1].match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
|
|
76
|
+
return m ? m[1].trim() : null;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export function readSpecRequirements(specsDir: string, rel: string): SpecRequirementReading {
|
|
80
|
+
const content = readFileSync(join(specsDir, rel), "utf-8");
|
|
81
|
+
const declared = frontmatterField(content, "criteria");
|
|
82
|
+
const reason = frontmatterField(content, "criteria-reason");
|
|
83
|
+
return {
|
|
84
|
+
spec: rel,
|
|
85
|
+
criteria: countCriteria(content),
|
|
86
|
+
declaredNone: declared === "none",
|
|
87
|
+
reason: reason && reason.length > 0 ? reason : null,
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Refusals, worded after the property rather than after the proxy.
|
|
93
|
+
*
|
|
94
|
+
* Three of them, and the second and third exist because the first alone is
|
|
95
|
+
* satisfiable by something other than fixing the problem — #492's trap. A
|
|
96
|
+
* check that only refused "no criteria and no declaration" is cleared by
|
|
97
|
+
* pasting `criteria: none` onto a spec that has requirements and has simply
|
|
98
|
+
* not written them down, which is the state this check exists to surface.
|
|
99
|
+
*/
|
|
100
|
+
export function requirementViolations(readings: SpecRequirementReading[]): string[] {
|
|
101
|
+
const out: string[] = [];
|
|
102
|
+
for (const r of readings) {
|
|
103
|
+
if (r.criteria === 0 && !r.declaredNone) {
|
|
104
|
+
out.push(
|
|
105
|
+
`${r.spec} states no criteria and does not say so. The routing table presents it as a ` +
|
|
106
|
+
`governing spec, so a reader is sent there expecting requirements. Add criteria, or ` +
|
|
107
|
+
`declare "criteria: none" with a "criteria-reason:" in its frontmatter.`,
|
|
108
|
+
);
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
// Both directions, like every other ratchet here. A spec that gains
|
|
112
|
+
// criteria must withdraw the declaration, or the declaration rots into a
|
|
113
|
+
// line that certifies nothing — and the routing table keeps warning
|
|
114
|
+
// readers away from a document that now has what they came for.
|
|
115
|
+
if (r.declaredNone && r.criteria > 0) {
|
|
116
|
+
out.push(
|
|
117
|
+
`${r.spec} declares "criteria: none" and states ${r.criteria}. Remove the declaration.`,
|
|
118
|
+
);
|
|
119
|
+
continue;
|
|
120
|
+
}
|
|
121
|
+
if (r.declaredNone && r.reason === null) {
|
|
122
|
+
out.push(
|
|
123
|
+
`${r.spec} declares "criteria: none" with no "criteria-reason:". A reader routed here ` +
|
|
124
|
+
`needs to know whether this is a redirect stub or an unwritten spec.`,
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
return out;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* `testable:` read as a value rather than as `=== "true"`.
|
|
133
|
+
*
|
|
134
|
+
* DRIFT-2 and SPEC-DISCOVERY both ask `fm.testable === "true"`, so every
|
|
135
|
+
* other spelling is silently FALSE. `specs/DA-COMPLIANCE-SPEC.md` carries
|
|
136
|
+
* `testable: no`, which happens to mean what its author intended; `testable:
|
|
137
|
+
* yes` would mean the opposite of what its author intended and nothing would
|
|
138
|
+
* say so. The spec would drop out of the conformity surface while its
|
|
139
|
+
* frontmatter, the routing table and any reader all said it was in.
|
|
140
|
+
*
|
|
141
|
+
* A fail-open with no amplifier today is still a fail-open. One line.
|
|
142
|
+
*/
|
|
143
|
+
export function testableViolations(specsDir: string, specs: string[]): string[] {
|
|
144
|
+
const out: string[] = [];
|
|
145
|
+
for (const rel of specs) {
|
|
146
|
+
const raw = frontmatterField(readFileSync(join(specsDir, rel), "utf-8"), "testable");
|
|
147
|
+
if (raw === null) continue; // absence is a separate check's question
|
|
148
|
+
if (raw !== "true" && raw !== "false") {
|
|
149
|
+
out.push(
|
|
150
|
+
`${rel} has "testable: ${raw}". Every reader compares against the string "true", so ` +
|
|
151
|
+
`anything else means false — including "yes". Write true or false.`,
|
|
152
|
+
);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
return out;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Spec basenames that also name a file somewhere else in the project.
|
|
160
|
+
*
|
|
161
|
+
* DRIFT-2 credits a testable spec when any test file's text contains its
|
|
162
|
+
* name, and for a top-level spec that name is a bare basename. On this repo
|
|
163
|
+
* `specs/PROJECT-STATE.md` and the generated root `PROJECT-STATE.md` share
|
|
164
|
+
* one, and **ten test files mention the root one** — so the spec was
|
|
165
|
+
* referenced, by DRIFT-2's reading, by tests that have nothing to do with it.
|
|
166
|
+
*
|
|
167
|
+
* This is the fifth shape and it was aimed straight at #579's own fix: the
|
|
168
|
+
* issue's prescribed remedy is `testable: true` plus "a test naming it, which
|
|
169
|
+
* test/update-project-state.test.ts can do in one line". Flipping the flag
|
|
170
|
+
* alone would have turned DRIFT-2 green for this spec on the strength of
|
|
171
|
+
* `test/organize-project.test.ts` talking about a status file.
|
|
172
|
+
*
|
|
173
|
+
* Measured rather than assumed: exactly one spec basename collides on this
|
|
174
|
+
* tree. Requiring the `specs/`-qualified path from EVERY test would orphan 15
|
|
175
|
+
* of 22 testable specs, so the rule is narrowed to the ambiguous ones — where
|
|
176
|
+
* a bare name genuinely does not say which file is meant.
|
|
177
|
+
*/
|
|
178
|
+
export function ambiguousSpecNames(root: string, specs: string[]): Set<string> {
|
|
179
|
+
const names = new Map<string, string>();
|
|
180
|
+
for (const rel of specs) names.set(basename(rel), rel);
|
|
181
|
+
const found = new Set<string>();
|
|
182
|
+
const SKIP = new Set(["node_modules", ".git", "specs", "dist", "build", ".fallow", ".next"]);
|
|
183
|
+
const walk = (dir: string): void => {
|
|
184
|
+
let entries: string[];
|
|
185
|
+
try { entries = readdirSync(dir); } catch { return; }
|
|
186
|
+
for (const n of entries) {
|
|
187
|
+
if (SKIP.has(n)) continue;
|
|
188
|
+
const p = join(dir, n);
|
|
189
|
+
let st;
|
|
190
|
+
try { st = statSync(p); } catch { continue; }
|
|
191
|
+
if (st.isDirectory()) walk(p);
|
|
192
|
+
else if (names.has(n)) found.add(names.get(n)!);
|
|
193
|
+
}
|
|
194
|
+
};
|
|
195
|
+
if (existsSync(root)) walk(root);
|
|
196
|
+
return found;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Whether a test names THIS spec.
|
|
201
|
+
*
|
|
202
|
+
* Unambiguous names are matched bare, which is how every existing credit in
|
|
203
|
+
* this repo is earned. An ambiguous one must be written `specs/<path>`, which
|
|
204
|
+
* is the only form that says which file is meant.
|
|
205
|
+
*/
|
|
206
|
+
export function specIsReferenced(testContent: string, rel: string, ambiguous: Set<string>): boolean {
|
|
207
|
+
if (ambiguous.has(rel)) return testContent.includes(`specs/${rel}`);
|
|
208
|
+
return testContent.includes(rel);
|
|
209
|
+
}
|
package/lib/suite-run-reading.ts
CHANGED
|
@@ -192,3 +192,173 @@ export function suiteRunVerdict(run: SuiteRun): "PASS" | "FAIL" | "UNMEASURED" {
|
|
|
192
192
|
if (run.status !== "MEASURED") return "UNMEASURED";
|
|
193
193
|
return run.fail === 0 ? "PASS" : "FAIL";
|
|
194
194
|
}
|
|
195
|
+
|
|
196
|
+
/* ─────────────────────────────────────────────────────────────
|
|
197
|
+
* The failures that happen before there is any output (#621)
|
|
198
|
+
* ───────────────────────────────────────────────────────────── */
|
|
199
|
+
|
|
200
|
+
/**
|
|
201
|
+
* What a caller knows about one attempt to measure the suite.
|
|
202
|
+
*
|
|
203
|
+
* `readSuiteRun` above reads what a runner PRINTED, and that is everything
|
|
204
|
+
* once a runner has run. Two of the three ways a measurement fails never get
|
|
205
|
+
* that far, and both of them print nothing:
|
|
206
|
+
*
|
|
207
|
+
* - the full-suite slot pool refused, so no runner was started at all;
|
|
208
|
+
* - the runner binary could not be executed.
|
|
209
|
+
*
|
|
210
|
+
* Both reach the output parser as an empty string, where they are
|
|
211
|
+
* indistinguishable from each other and from a runner that ran and said
|
|
212
|
+
* nothing. The facts that separate them are not IN the output, so they travel
|
|
213
|
+
* beside it.
|
|
214
|
+
*/
|
|
215
|
+
export interface SuiteRunAttempt {
|
|
216
|
+
/**
|
|
217
|
+
* The full-suite slot pool's answer, when one was asked for.
|
|
218
|
+
*
|
|
219
|
+
* Structurally typed rather than imported from `lib/test-suite-lock.ts`: a
|
|
220
|
+
* real `AcquireResult` satisfies it, and this module stays free of `fs` and
|
|
221
|
+
* `child_process` so it can be read anywhere a verdict is read. Omit it
|
|
222
|
+
* when no slot was required — `undefined` means "not asked", which is not
|
|
223
|
+
* the same fact as a refusal.
|
|
224
|
+
*/
|
|
225
|
+
slot?: SlotOutcome | null;
|
|
226
|
+
/**
|
|
227
|
+
* What the process launcher reported when it could not start the runner —
|
|
228
|
+
* `spawnSync(...).error`, or anything else that says the launch failed.
|
|
229
|
+
* Absent and null both mean the runner launched.
|
|
230
|
+
*/
|
|
231
|
+
launchError?: unknown;
|
|
232
|
+
/** The command that was attempted, as argv or as a string. */
|
|
233
|
+
command?: unknown;
|
|
234
|
+
/** What the runner printed, handed to `readSuiteRun` unchanged. */
|
|
235
|
+
output?: unknown;
|
|
236
|
+
/**
|
|
237
|
+
* The exit status, when there was one.
|
|
238
|
+
*
|
|
239
|
+
* RECORDED, NEVER CONSULTED. It is quoted into an UNMEASURED reason so an
|
|
240
|
+
* operator reading the artefact does not have to go and re-run anything,
|
|
241
|
+
* and no branch below asks what it is. SC-1829 is the measurement that says
|
|
242
|
+
* why: among this module's fixtures, exit 0 and exit 1 each cover both a
|
|
243
|
+
* measured and an unmeasured run, so a reading keyed off it is wrong about
|
|
244
|
+
* one of them.
|
|
245
|
+
*/
|
|
246
|
+
exitCode?: unknown;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** The shape of a slot-pool answer this module needs. `AcquireResult` is one. */
|
|
250
|
+
export interface SlotOutcome {
|
|
251
|
+
ok: boolean;
|
|
252
|
+
holders?: ReadonlyArray<{
|
|
253
|
+
sessionId?: string;
|
|
254
|
+
workerId?: string;
|
|
255
|
+
ageSeconds?: number;
|
|
256
|
+
}>;
|
|
257
|
+
degraded?: boolean;
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
function isRecord(v: unknown): v is Record<string, unknown> {
|
|
261
|
+
return typeof v === "object" && v !== null && !Array.isArray(v);
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/** `bun test`, from argv or from a string. Never empty — an unnamed command
|
|
265
|
+
* is a fact worth printing rather than a hole in the sentence. */
|
|
266
|
+
function describeCommand(command: unknown): string {
|
|
267
|
+
if (Array.isArray(command)) {
|
|
268
|
+
const parts = command.filter((p): p is string => typeof p === "string" && p !== "");
|
|
269
|
+
if (parts.length > 0) return parts.join(" ");
|
|
270
|
+
}
|
|
271
|
+
if (typeof command === "string" && command.trim() !== "") return command.trim();
|
|
272
|
+
return "(the harness did not record which command it tried to run)";
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
/** `ENOENT: Executable not found in $PATH: "…"`. */
|
|
276
|
+
function describeLaunchFailure(error: unknown): string {
|
|
277
|
+
const record = isRecord(error) ? error : null;
|
|
278
|
+
const code = record && typeof record.code === "string" ? record.code : null;
|
|
279
|
+
const message =
|
|
280
|
+
record && typeof record.message === "string" && record.message !== ""
|
|
281
|
+
? record.message
|
|
282
|
+
: String(error);
|
|
283
|
+
return code ? `${code}: ${message}` : message;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/** ` by holder-worker (12s)`, or nothing when the pool named nobody. */
|
|
287
|
+
function describeHolders(holders: SlotOutcome["holders"]): string {
|
|
288
|
+
if (!Array.isArray(holders)) return "";
|
|
289
|
+
const named = holders
|
|
290
|
+
.filter(isRecord)
|
|
291
|
+
.map(h => {
|
|
292
|
+
const who = typeof h.workerId === "string" && h.workerId !== ""
|
|
293
|
+
? h.workerId
|
|
294
|
+
: typeof h.sessionId === "string" && h.sessionId !== ""
|
|
295
|
+
? h.sessionId
|
|
296
|
+
: "an unidentified worker";
|
|
297
|
+
const age = typeof h.ageSeconds === "number" && Number.isFinite(h.ageSeconds)
|
|
298
|
+
? `${h.ageSeconds}s`
|
|
299
|
+
: "age unknown";
|
|
300
|
+
return `${who} (${age})`;
|
|
301
|
+
});
|
|
302
|
+
return named.length === 0 ? "" : ` by ${named.join(", ")}`;
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
/** `. The runner exited 1.`, or nothing when no status was recorded. */
|
|
306
|
+
function describeExit(exitCode: unknown): string {
|
|
307
|
+
return typeof exitCode === "number" ? ` The runner exited ${exitCode}.` : "";
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/**
|
|
311
|
+
* Read one attempt to measure the suite.
|
|
312
|
+
*
|
|
313
|
+
* FAILS CLOSED, like everything else here, and for the one reason #621 names
|
|
314
|
+
* by hand: `scripts/test-clean-env.ts` exits 2 when the slot pool refuses,
|
|
315
|
+
* and **that exit must record UNMEASURED, never FAIL**. A refused run and a
|
|
316
|
+
* broken runner are not results about the tree; they are the absence of a
|
|
317
|
+
* measurement, and an absence that reads as a failing suite is as wrong as
|
|
318
|
+
* one that reads as a clean one — it just fails in the direction nobody
|
|
319
|
+
* notices, by making the gate cry wolf until its reader stops believing it.
|
|
320
|
+
*
|
|
321
|
+
* The three refusals are ORDERED and each is the only decider for its fact.
|
|
322
|
+
* The output parser is `readSuiteRun`, called once at the end rather than
|
|
323
|
+
* re-implemented, so the missing-summary refusal has exactly one binding and
|
|
324
|
+
* a mutation of it cannot be held up by a copy in here
|
|
325
|
+
* (.claude/rules/checks-must-be-able-to-fail.md, the fourth shape).
|
|
326
|
+
*/
|
|
327
|
+
export function readSuiteAttempt(attempt: SuiteRunAttempt): SuiteRun {
|
|
328
|
+
// 1. The pool refused. Checked first because nothing downstream of it ran:
|
|
329
|
+
// there is no launch error and no output, so every later branch would
|
|
330
|
+
// describe this as "the runner printed nothing", which is true and
|
|
331
|
+
// useless — the runner was never asked to print anything.
|
|
332
|
+
//
|
|
333
|
+
// `ok !== true` rather than `ok === false`: a slot answer this module
|
|
334
|
+
// cannot read is not an acquired slot.
|
|
335
|
+
const slot = attempt.slot;
|
|
336
|
+
if (slot !== undefined && slot !== null && slot.ok !== true) {
|
|
337
|
+
return unmeasured(
|
|
338
|
+
"the suite was never run: the full-suite slot pool is exhausted — every slot is held" +
|
|
339
|
+
`${describeHolders(slot.holders)}, so ${describeCommand(attempt.command)} was refused ` +
|
|
340
|
+
"before any runner started. A refused run has no result, and must not be read as a " +
|
|
341
|
+
"failing one (#621)",
|
|
342
|
+
);
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
// 2. The runner could not be executed. Also checked before the output,
|
|
346
|
+
// because an ENOENT launch prints nothing: left to the parser it would
|
|
347
|
+
// report "the test runner produced no output", which names neither the
|
|
348
|
+
// runner nor the fact that there isn't one to name.
|
|
349
|
+
if (attempt.launchError !== undefined && attempt.launchError !== null) {
|
|
350
|
+
return unmeasured(
|
|
351
|
+
`the test runner could not be executed: ${describeCommand(attempt.command)} — ` +
|
|
352
|
+
`${describeLaunchFailure(attempt.launchError)}. No suite ran, so there is no result to ` +
|
|
353
|
+
"read, and the absence of a runner is not the absence of failures (#621)",
|
|
354
|
+
);
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
// 3. Whatever the runner printed, read by the one reader that reads output.
|
|
358
|
+
// The exit status is appended to a refusal rather than consulted for it.
|
|
359
|
+
const run = readSuiteRun(attempt.output);
|
|
360
|
+
if (run.status === "UNMEASURED") {
|
|
361
|
+
return unmeasured(`${run.reason}${describeExit(attempt.exitCode)}`);
|
|
362
|
+
}
|
|
363
|
+
return run;
|
|
364
|
+
}
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one test command for a project (#488).
|
|
3
|
+
*
|
|
4
|
+
* The scaffold read `dev.testCmd` in four places and wrote it into
|
|
5
|
+
* everything an agent reads — AGENTS.md's Commands table, the agent briefs,
|
|
6
|
+
* the ship workflow — and then generated a CI workflow that ran `bun test`
|
|
7
|
+
* regardless. `createCiWorkflows` had `harness` in scope and reached for
|
|
8
|
+
* `harness?.ci?.bunVersion`, `?.runner` and `?.branches` four lines above
|
|
9
|
+
* the hardcode.
|
|
10
|
+
*
|
|
11
|
+
* The divergence is silent in both directions. If the consumer's command is
|
|
12
|
+
* a superset, CI is weaker than the gate every agent was told about. If
|
|
13
|
+
* `bun test` does not work in their project at all, CI is red for a reason
|
|
14
|
+
* no config change can fix, because the field that would fix it is not
|
|
15
|
+
* read.
|
|
16
|
+
*
|
|
17
|
+
* ## Why this is a module and not four `||` chains that agree
|
|
18
|
+
*
|
|
19
|
+
* They did not agree. Four sites resolved the same question four ways:
|
|
20
|
+
*
|
|
21
|
+
* | Site | Ladder |
|
|
22
|
+
* |---|---|
|
|
23
|
+
* | `createCiWorkflows` | `"bun test"` |
|
|
24
|
+
* | `generateAgentsMdContent` | `dev.testCmd \|\| "bun test"` |
|
|
25
|
+
* | `scanProject` | `package.json scripts.test \|\| "bun test"` |
|
|
26
|
+
* | `generateAgentBriefs` | `dev.testCmd \|\| scan.testCmd \|\| "bun test"` |
|
|
27
|
+
*
|
|
28
|
+
* So a consumer with a `scripts.test` and no `dev.testCmd` was told one
|
|
29
|
+
* command by AGENTS.md and another by CI, and two sites that happen to
|
|
30
|
+
* agree today are one decider too many — only a mutation of a SHARED
|
|
31
|
+
* binding can show that the agreement is load-bearing rather than
|
|
32
|
+
* coincidental. This is #87's fix for the type check, applied to the step
|
|
33
|
+
* directly below the one #87 collapsed.
|
|
34
|
+
*
|
|
35
|
+
* ## The rungs, and what each one is not
|
|
36
|
+
*
|
|
37
|
+
* 1. **`dev.testCmd` from the rungate config.** The operator said so, in
|
|
38
|
+
* the field the harness documents for exactly this.
|
|
39
|
+
* 2. **`package.json` `scripts.test`, verbatim.** The value, not `bun run
|
|
40
|
+
* test`. That is the existing behaviour of `scanProject`, so this rung
|
|
41
|
+
* is a collapse rather than a new judgement — and `bun run test` would
|
|
42
|
+
* fire `pretest`/`posttest`, which on this repo means CI running
|
|
43
|
+
* `sync-sc-status.ts` and writing to the tree.
|
|
44
|
+
* 3. **`bun test`.** Unchanged for every consumer that declares neither.
|
|
45
|
+
*
|
|
46
|
+
* ## What this does NOT cover
|
|
47
|
+
*
|
|
48
|
+
* `workflows/ship.js` resolves `test.command || dev.testCmd || 'bun test'`
|
|
49
|
+
* and cannot import (#69). It is the fifth site and it stays its own, which
|
|
50
|
+
* is a known gap rather than an oversight — the subprocess boundary is how
|
|
51
|
+
* workflows comply with `.claude/rules/config-access.md`.
|
|
52
|
+
*/
|
|
53
|
+
import { existsSync, readFileSync } from "fs";
|
|
54
|
+
import { join } from "path";
|
|
55
|
+
import { tryLoadRungateConfig } from "./config-loader";
|
|
56
|
+
|
|
57
|
+
export type TestCommandSource = "config" | "package-script" | "default";
|
|
58
|
+
|
|
59
|
+
export interface TestCommandDecision {
|
|
60
|
+
/** The shell command. Never null — every project can run something. */
|
|
61
|
+
command: string;
|
|
62
|
+
source: TestCommandSource;
|
|
63
|
+
/** Why this command and not another. */
|
|
64
|
+
reason: string;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
export const DEFAULT_TEST_COMMAND = "bun test";
|
|
68
|
+
|
|
69
|
+
export function testCommandDecision(root: string): TestCommandDecision {
|
|
70
|
+
// Through the loader, never a constructed path to `.claude/rungate*`
|
|
71
|
+
// (`.claude/rules/config-access.md`). It also means both config layouts
|
|
72
|
+
// are honoured — a consumer who followed the documented migration to the
|
|
73
|
+
// directory form is the exact population a monolith-only read loses.
|
|
74
|
+
//
|
|
75
|
+
// It THROWS on a malformed config, deliberately: a corrupt config is
|
|
76
|
+
// never a missing config, and `catch {}` here is the conversion that rule
|
|
77
|
+
// exists to forbid. The one caller that must survive corruption is the
|
|
78
|
+
// config REPAIR step, and it calls `inferredTestCommand` instead — see
|
|
79
|
+
// below for why that is not a loophole.
|
|
80
|
+
const config = tryLoadRungateConfig(root) as { dev?: { testCmd?: unknown } } | null;
|
|
81
|
+
const declared = config?.dev?.testCmd;
|
|
82
|
+
if (typeof declared === "string" && declared.trim() !== "") {
|
|
83
|
+
return {
|
|
84
|
+
command: declared,
|
|
85
|
+
source: "config",
|
|
86
|
+
reason: "the project declares `dev.testCmd`, which beats anything inferred",
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
return inferredTestCommand(root);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The same decision with the config rung removed — what this project's test
|
|
95
|
+
* command would be if the config said nothing.
|
|
96
|
+
*
|
|
97
|
+
* Exactly one caller, and it is not a convenience: `generateOrAuditProjectHarness`
|
|
98
|
+
* chooses the value to WRITE into `dev.testCmd`, so asking the loader for
|
|
99
|
+
* `dev.testCmd` first is circular, and it runs against trees whose config is
|
|
100
|
+
* malformed — that is what it exists to repair. Routing it through the
|
|
101
|
+
* throwing loader killed the repair with `SyntaxError: JSON Parse error` in
|
|
102
|
+
* the step whose job is to fix that file.
|
|
103
|
+
*
|
|
104
|
+
* Split rather than flagged, because a boolean parameter makes the two
|
|
105
|
+
* behaviours one call site's argument rather than two named things, and the
|
|
106
|
+
* shared rungs stay shared either way.
|
|
107
|
+
*/
|
|
108
|
+
export function inferredTestCommand(root: string): TestCommandDecision {
|
|
109
|
+
const pkgPath = join(root, "package.json");
|
|
110
|
+
if (existsSync(pkgPath)) {
|
|
111
|
+
try {
|
|
112
|
+
const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
|
|
113
|
+
const script = pkg?.scripts?.test;
|
|
114
|
+
if (typeof script === "string" && script.trim() !== "") {
|
|
115
|
+
return {
|
|
116
|
+
command: script,
|
|
117
|
+
source: "package-script",
|
|
118
|
+
reason: "the project declares a `test` script and no `dev.testCmd`",
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
} catch {
|
|
122
|
+
// An unreadable package.json is not a reason to lose the test command.
|
|
123
|
+
// The default below needs no package.json at all, and this module's
|
|
124
|
+
// neighbours already shrug at this rather than killing the scaffold.
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
return {
|
|
129
|
+
command: DEFAULT_TEST_COMMAND,
|
|
130
|
+
source: "default",
|
|
131
|
+
reason: "the project declares neither `dev.testCmd` nor a `test` script",
|
|
132
|
+
};
|
|
133
|
+
}
|