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,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
+ }
@@ -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
+ }