rungate 0.5.0 → 0.7.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 (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -21,20 +21,40 @@
21
21
  * This module is the counting and the comparison; `gates/gate-executor.ts`
22
22
  * holds the refusal and decides when to bank a new reading.
23
23
  *
24
- * ## What this guard does NOT do, stated rather than implied
24
+ * ## The erasure this used to permit, and what closed it (#494)
25
25
  *
26
26
  * The banked census lives in the run's `workflow-state.json`, which is a
27
- * file the heal agent can write. A heal agent that deleted a test AND the
28
- * census would see `first-reading` on the next round and pass. This guard
29
- * raises the cost of an accidental deletion, which is the failure mode that
30
- * actually happened on `wf_5cdce852-1e2`; it is not tamper-evident against a
31
- * deliberate one, and `writeWorkflowState`'s Zod validation does not make it
32
- * so, because an absent optional key is valid.
33
- *
34
- * Closing that properly means putting the reading somewhere the guarded
35
- * party does not write — the witness, or an HMAC over it — and is filed
36
- * separately rather than half-done here. A guard whose limit is written down
37
- * is a guard somebody can finish; one whose limit is implied is one everybody
27
+ * file the heal agent can write — `workflows/ship.js` hands it the file by
28
+ * name, with a working `writeWorkflowState` recipe. A heal agent that
29
+ * deleted a test AND the census saw `first-reading` on the next round and
30
+ * passed, because `first-reading` increments neither `fails` nor `warns`.
31
+ * `writeWorkflowState`'s Zod validation did not help: an absent optional
32
+ * key is valid.
33
+ *
34
+ * Since #494 the gate SIGNS the banked census — `signCensus` in
35
+ * `gates/witness.ts`, HMAC over the sorted reading and the run's slug —
36
+ * and stores the signature beside it. The signature alone cannot close the
37
+ * hole, because an agent erasing the census erases the signature with it
38
+ * and the two absences are identical. The second half is a fact the state
39
+ * file does not hold: `~/.rungate/<slug>/witnesses/`, written by
40
+ * `writeWitness` on every gate run and named by no prompt. An unsigned or
41
+ * mismatched census where a witness already exists is UNMEASURED, which is
42
+ * a WARN in this gate, and no longer a first reading.
43
+ *
44
+ * ## What it still does NOT do, stated rather than implied
45
+ *
46
+ * Tamper-EVIDENT, not tamper-proof, and that is the intended goal. The gate
47
+ * salt is readable by anything running as this user, so an agent that knows
48
+ * where it lives can re-sign a census it rewrote. It can also delete the
49
+ * witness directory, which puts the run back to looking like a first round.
50
+ * Both are a different and louder act than deleting a key out of a file the
51
+ * prompt told it to edit, and neither is what the accidental deletion on
52
+ * `wf_5cdce852-1e2` looked like.
53
+ *
54
+ * Closing THAT means a store the run cannot write at all — an append-only
55
+ * log off the machine, or a signing key the gate process does not hold.
56
+ * Filed rather than half-done here. A guard whose limit is written down is
57
+ * a guard somebody can finish; one whose limit is implied is one everybody
38
58
  * assumes is complete.
39
59
  *
40
60
  * ## Why a declaration count and not a run
@@ -52,6 +72,7 @@
52
72
  */
53
73
  import { existsSync, readdirSync, readFileSync, statSync } from "fs";
54
74
  import { join } from "path";
75
+ import { testDeclarations } from "./test-case-bodies";
55
76
 
56
77
  /**
57
78
  * Directories a census never walks into.
@@ -101,30 +122,77 @@ const TEST_FILE = /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs)$/;
101
122
  export const MAX_CENSUS_FILE_BYTES = 2_000_000;
102
123
 
103
124
  /**
104
- * Declaration forms bun recognises. `test` and `it`, bare or with a modifier.
105
- *
106
- * Anchored on a word boundary so `subtest(` and `omit(` do not count, and
107
- * requiring the open paren so a bare mention in prose does not. The modifier
108
- * list is explicit rather than `\w+` because `test.each(...)(...)` and a
109
- * hypothetical `test.anything` should not silently start counting — an
110
- * unrecognised form is better as a miss we can see than as a count nobody
111
- * can explain.
125
+ * Which reader took a census, stamped beside it (#883).
126
+ *
127
+ * A census is BANKED per run and compared round to round, so the first round
128
+ * after this module's reader changes compares an old number against a new
129
+ * one and every file whose count moved reads as a regression. A reading
130
+ * taken with a different instrument is not comparable with one taken by
131
+ * this one, and the honest answer to an incomparable pair is UNMEASURED
132
+ * rather than either verdict.
133
+ *
134
+ * `"1"` is the pre-#883 reader and is never written — a banked census with
135
+ * no stamp IS version 1, which is how the migration is detected at all.
136
+ *
137
+ * **Bump this whenever `testDeclarations` changes what it counts.** Not when
138
+ * it changes how it is spelled: the stamp is about comparability of numbers,
139
+ * and a refactor that moves no count costs every in-flight run a round of
140
+ * UNMEASURED for nothing.
141
+ *
142
+ * **It IS covered by the signature, and the first draft of #883 said the
143
+ * opposite.** That draft's docblock read *"It is NOT a security control…
144
+ * the stamp is not covered by `signCensus`, so an agent that can edit the
145
+ * state file can edit it — but that agent can already delete the census
146
+ * outright."* Both halves are wrong, and writing the sentence is what
147
+ * stopped the question being asked:
148
+ *
149
+ * - Flipping this one byte is CHEAPER than deleting the census and much
150
+ * quieter. The census still verifies, so the round reports a WARN whose
151
+ * text explains an ordinary migration and refuses nothing.
152
+ * - `nextCensus` banks the current reading on a reader change, by design —
153
+ * so the lowered count becomes the baseline and the NEXT round is clean.
154
+ * The erasure #494 exists to catch is laundered into the record.
155
+ *
156
+ * `signStampedCensus` in `gates/witness.ts` signs the census and this stamp
157
+ * together. A forged or deleted stamp reads `unverified`; an absent one is
158
+ * checked against the v1 payload, which is what a real pre-#883 file has.
159
+ * Still tamper-evident rather than tamper-proof: the boundary is the salt.
112
160
  */
113
- const DECLARATION =
114
- /(?<![.\w$])(?:test|it)(?:\.(?:skip|todo|only|failing|each|skipIf|todoIf|only))?\s*[(`]/g;
161
+ export const TEST_CENSUS_READER = "2";
115
162
 
116
163
  /**
117
164
  * How many tests a source file declares.
118
165
  *
119
- * Comments are NOT stripped. A commented-out test is a removed test, and
120
- * stripping would make "comment the block out" a way past the guard. The
121
- * cost is that prose saying `test(` counts, which inflates a file's number
122
- * — and inflation is harmless here, because only a DECREASE is refused.
123
- * The one direction this may be wrong in is toward not refusing, which is
124
- * the direction a guard over somebody else's edits has to be wrong in.
166
+ * A projection of `testDeclarations`, which is the one binding deciding what
167
+ * a declaration is (#883). Before that it had its own expression, and the
168
+ * two disagreed on 174 of this tree's 483 test files: `gates/gate-executor.ts`
169
+ * refused a round on THIS count while the deletion reading named cases from
170
+ * the other, so an operator handed *"30 test(s) before, 27 after"* beside a
171
+ * list of 8 case names could not reconcile them.
172
+ *
173
+ * ## Comments ARE excluded now, and the old rationale was backwards
174
+ *
175
+ * This docblock used to read:
176
+ *
177
+ * > Comments are NOT stripped. A commented-out test is a removed test, and
178
+ * > stripping would make "comment the block out" a way past the guard.
179
+ *
180
+ * The second sentence is inverted, and it is worth leaving the correction
181
+ * here rather than quietly deleting it. Only a DECREASE is refused. With
182
+ * comments counted, commenting a test out leaves the number unchanged, so
183
+ * the guard does not fire — the hole the sentence describes was the one the
184
+ * policy created. Measured on the pre-#883 reader:
185
+ *
186
+ * countTestDeclarations('test("a", () => {})') → 1
187
+ * countTestDeclarations('// test("a", () => {})') → 1
188
+ *
189
+ * Excluding comments makes the count drop, which is exactly the refusal the
190
+ * guard exists for. The same scan also excludes a `test(` sequence inside a
191
+ * string, a template or a regex, which is where ~225 of the old reader's 443
192
+ * extra matches on this tree came from — prose, counted as coverage.
125
193
  */
126
194
  export function countTestDeclarations(source: string): number {
127
- return [...source.matchAll(DECLARATION)].length;
195
+ return testDeclarations(source).length;
128
196
  }
129
197
 
130
198
  /**
@@ -0,0 +1,274 @@
1
+ /**
2
+ * Every position in a tree that NAMES the project's test command, and the
3
+ * comparison between them (#621, #626 category 1, relocated here by #637).
4
+ *
5
+ * ## Why this is a library module and not a section of a script
6
+ *
7
+ * It was written inside `test/test-command-agreement.test.ts` (#621), moved
8
+ * into `scripts/contract-parity.ts` when the parity check came to need it
9
+ * (#626), and moved HERE by #637 — because a script cannot be imported by a
10
+ * script, and the moment a second consumer appears the only two options are an
11
+ * importable module or a second copy. A second copy of the three extractors is
12
+ * a producer and a consumer that must agree with nothing comparing them, which
13
+ * is the exact defect this whole family of checks exists to find.
14
+ *
15
+ * `lib/` is the position that makes the question answerable in one place:
16
+ * `test/test-command-agreement.test.ts`, `test/ci-global-tools.test.ts`,
17
+ * `test/contract-parity.test.ts` and `scripts/contract-parity.ts` all import
18
+ * these bindings from here, and there is one site to mutate.
19
+ *
20
+ * ## The decider this is NOT a second copy of
21
+ *
22
+ * `lib/test-command.ts`'s `testCommandDecision` answers "what command should
23
+ * this project RUN", with a config rung, a `package.json` rung and a default.
24
+ * This module answers "what command does each position in the tree SAY", which
25
+ * is a different question with a different failure mode: the decision has to
26
+ * produce an answer for every project, and this has to refuse when a position
27
+ * says nothing.
28
+ *
29
+ * They are not two deciders that agree, and the input that proves it is a tree
30
+ * with `test.command` set, no `dev.testCmd`, and a `package.json` `scripts.test`
31
+ * naming something else: `testCommandsNamedByConfig` reports `test.command` and
32
+ * `testCommandDecision` reports the package script. `commandParity` reads both
33
+ * on purpose, and a disagreement between them is a finding rather than noise.
34
+ *
35
+ * ## Where `suiteJobName` lives, and why it is not here
36
+ *
37
+ * #735 made `lib/ci-checkout.ts`'s `suiteJobName` the one binding for "which
38
+ * job in a generated `ci.yml` runs the suite" — `test` normally, `test-shard`
39
+ * under a matrix, where `test` becomes an aggregate that runs nothing. It was
40
+ * exported precisely so `scripts/contract-parity.ts` could ask rather than
41
+ * carry a copy.
42
+ *
43
+ * The CI extractor moved here, so the IMPORT moved with it and
44
+ * `scripts/contract-parity.ts` no longer names `suiteJobName` at all — its
45
+ * only use there was inside the function below. That is the same arrangement
46
+ * #735 asked for, one position further out: one declaration in
47
+ * `lib/ci-checkout.ts`, one consumer here, nothing to disagree. Leaving the
48
+ * import behind in the script would have been an unused specifier, not a
49
+ * second reader, but it would also have been the first thing to tempt someone
50
+ * into re-adding a local copy.
51
+ *
52
+ * ## Finding nothing in every file is perfect agreement
53
+ *
54
+ * Zero strings are trivially all equal, so every extractor here REFUSES when it
55
+ * finds no command rather than returning `[]`, and the refusal is let out of
56
+ * `testCommandAgreement` rather than folded into an empty violation list. A
57
+ * template edit that moves a table row or renames a CI step must turn this red,
58
+ * not quiet (`.claude/rules/checks-must-be-able-to-fail.md`, third shape).
59
+ */
60
+ import { existsSync, readFileSync } from "fs";
61
+ import { join } from "path";
62
+ import { suiteJobName } from "./ci-checkout";
63
+ import { RUNGATE_CONFIG_RELATIVE_PATH, resolveConfig } from "./config-loader";
64
+
65
+ /**
66
+ * The three positions compared, as repo-relative paths.
67
+ *
68
+ * `CONFIG_JSON` is a LABEL, not a path: the config's location is asked of
69
+ * `lib/config-loader.ts` (`rungateConfigPath` below), because this repository
70
+ * supports two layouts indefinitely and a reader that knows only the directory
71
+ * form silently gets nothing from a consumer on the monolith
72
+ * (`.claude/rules/config-access.md`, and CONFIG-1 enforces it).
73
+ */
74
+ export const AGENTS_MD = "AGENTS.md";
75
+ export const CONFIG_JSON = RUNGATE_CONFIG_RELATIVE_PATH;
76
+ export const CI_YML = join(".github", "workflows", "ci.yml");
77
+ export const AGREEMENT_FILES = [AGENTS_MD, CONFIG_JSON, CI_YML] as const;
78
+
79
+ /**
80
+ * Where this project's rungate config actually is, or null when it has none.
81
+ *
82
+ * Through `resolveConfig`, so both layouts are honoured and a corrupt config
83
+ * THROWS rather than arriving as an absent one — the distinction #70 lost for
84
+ * a month, and the one #626 AC-4 keeps as two separate UNMEASURED kinds.
85
+ */
86
+ export function rungateConfigPath(root: string): string | null {
87
+ const resolution = resolveConfig(root);
88
+ if (resolution.status === "absent") return null;
89
+ return resolution.source === "directory" ? join(resolution.path, "config.json") : resolution.path;
90
+ }
91
+
92
+ /** One test command, and the position in the tree that names it. */
93
+ export interface NamedTestCommand {
94
+ /** Repo-relative path. */
95
+ file: string;
96
+ /** Where inside the file — the row, the field, the step. */
97
+ where: string;
98
+ command: string;
99
+ }
100
+
101
+ /** Thrown when a file this check reads names no test command at all. */
102
+ export class NoTestCommandError extends Error {}
103
+
104
+ function refuse(file: string, why: string): never {
105
+ throw new NoTestCommandError(
106
+ `${file} names no test command: ${why}. ` +
107
+ `Three files naming nothing are not three files that agree — ` +
108
+ `see .claude/rules/checks-must-be-able-to-fail.md.`,
109
+ );
110
+ }
111
+
112
+ /**
113
+ * The `| Test | \`…\` |` row of AGENTS.md's Commands table.
114
+ *
115
+ * The cell must be exactly `Test`: `Test as CI sees it` is a different command
116
+ * on purpose, and matching it here would make the check compare a row against
117
+ * itself. The section is sliced out first — asserting against the whole
118
+ * document is how a claim about one section gets satisfied by a match
119
+ * somewhere else (#297, #484, #60).
120
+ */
121
+ export function testCommandsNamedByAgentsMd(text: string): NamedTestCommand[] {
122
+ const start = text.indexOf("\n## Commands");
123
+ if (start === -1) refuse(AGENTS_MD, "it has no `## Commands` section");
124
+ const rest = text.slice(start + 1);
125
+ const end = rest.indexOf("\n## ", 1);
126
+ const section = end === -1 ? rest : rest.slice(0, end);
127
+ if (section.trim() === "") refuse(AGENTS_MD, "its `## Commands` section is empty");
128
+
129
+ const row = /^\|\s*Test\s*\|\s*`([^`]+)`\s*\|/m.exec(section);
130
+ if (!row) refuse(AGENTS_MD, "its Commands table has no `| Test | \\`…\\` |` row");
131
+ return [{ file: AGENTS_MD, where: "the Commands table's Test row", command: row![1].trim() }];
132
+ }
133
+
134
+ /**
135
+ * The `**Test:** \`…\`` line of AGENTS.md's Workflow section.
136
+ *
137
+ * A second position in the same generated file, and the reason the slice above
138
+ * matters: the two have always agreed here, so the live tree cannot witness a
139
+ * reader that confuses them.
140
+ */
141
+ export function testCommandNamedByAgentsWorkflow(text: string): NamedTestCommand[] {
142
+ const line = /^\s*-?\s*\*\*Test:\*\*\s*`([^`]+)`/m.exec(text);
143
+ return line ? [{ file: AGENTS_MD, where: "the Workflow section's Test line", command: line[1].trim() }] : [];
144
+ }
145
+
146
+ /**
147
+ * Every test command the rungate config declares.
148
+ *
149
+ * Both fields, because both are read: `test.command` is what the ship run
150
+ * measures with (`workflows/ship.js`, which cannot import — #69) and
151
+ * `dev.testCmd` is the top rung of `lib/test-command.ts`, which is what the
152
+ * scaffold writes into AGENTS.md and CI.
153
+ */
154
+ export function testCommandsNamedByConfig(text: string): NamedTestCommand[] {
155
+ // Deliberately not caught: a corrupt config is never a missing config
156
+ // (.claude/rules/config-access.md).
157
+ const config = JSON.parse(text) as { test?: { command?: unknown }; dev?: { testCmd?: unknown } };
158
+ const found: NamedTestCommand[] = [];
159
+ const declared = (where: string, value: unknown) => {
160
+ if (typeof value === "string" && value.trim() !== "") {
161
+ found.push({ file: CONFIG_JSON, where, command: value.trim() });
162
+ }
163
+ };
164
+ declared("test.command", config?.test?.command);
165
+ declared("dev.testCmd", config?.dev?.testCmd);
166
+ if (found.length === 0) refuse(CONFIG_JSON, "neither `test.command` nor `dev.testCmd` is set");
167
+ return found;
168
+ }
169
+
170
+ /**
171
+ * Steps that are part of running CI but are not the project's test command.
172
+ * Named rather than positional: "the second run step" is a proxy, and a proxy
173
+ * is a thing a template edit can satisfy while the property breaks.
174
+ */
175
+ const NOT_THE_TEST_STEP = new Set(["bun install", "bun run typecheck"]);
176
+
177
+ /**
178
+ * The shard selector is a CI PARTITION, not a different test command (#735).
179
+ *
180
+ * `bun test --shard=2/4` runs a quarter of the files of `bun test`; it does
181
+ * not run them differently. The property #621 protects is that one command
182
+ * is named everywhere, and appending a partition selector in CI does not
183
+ * break it — but comparing the raw strings says it does, and the cheap fix
184
+ * for that red is to add the sharded spelling to AGENTS.md, which would put
185
+ * a CI-only flag in the row a human copies to run the suite locally.
186
+ *
187
+ * Stripped only at the END and only with a `N/M` argument, so a command that
188
+ * genuinely differs before the flag still disagrees.
189
+ *
190
+ * `\S+` will not do for the numerator: the generated value is the GitHub
191
+ * expression `${{ matrix.shard }}`, which contains spaces.
192
+ */
193
+ const SHARD_SELECTOR = /\s+--shard=.+?\/\d+\s*$/;
194
+
195
+ /** The test step of the generated suite job in ci.yml. */
196
+ export function testCommandsNamedByCiWorkflow(text: string): NamedTestCommand[] {
197
+ // `suiteJobName` is the one binding for "which job runs the suite" — it is
198
+ // `test` normally and `test-shard` under a matrix, where `test` becomes the
199
+ // aggregate and runs no tests at all. A second copy of that rule here would
200
+ // survive any mutation of the first and both would read as covered.
201
+ const anchor = `\n ${suiteJobName(text)}:`;
202
+ const start = text.indexOf(anchor);
203
+ if (start === -1) refuse(CI_YML, "it has no `test:` job");
204
+ const rest = text.slice(start + 1);
205
+ // The next job at the same indent ends this one. Jobs a consumer added are
206
+ // theirs (#216) and must not be read as this project's test command.
207
+ const head = anchor.slice(1);
208
+ const end = /\n {2}[A-Za-z_][\w-]*:/.exec(rest.slice(head.length));
209
+ const job = end === null ? rest : rest.slice(0, head.length + end.index);
210
+ if (job.trim() === "") refuse(CI_YML, "its `test:` job is empty");
211
+
212
+ const runs = job
213
+ .split("\n")
214
+ .map(line => /^\s+- run:\s*(\S.*)$/.exec(line))
215
+ .filter((m): m is RegExpExecArray => m !== null)
216
+ .map(m => m[1].trim())
217
+ // `run: |` opens a block scalar; the body is not a command on this line.
218
+ .filter(cmd => cmd !== "|" && !cmd.startsWith("|"))
219
+ .filter(cmd => !NOT_THE_TEST_STEP.has(cmd))
220
+ .map(cmd => cmd.replace(SHARD_SELECTOR, ""));
221
+
222
+ if (runs.length === 0) {
223
+ refuse(CI_YML, "its `test:` job runs nothing but setup and the type check");
224
+ }
225
+ return [{ file: CI_YML, where: "the test job's run step", command: runs[0] }];
226
+ }
227
+
228
+ const EXTRACTORS: Record<string, (text: string) => NamedTestCommand[]> = {
229
+ [AGENTS_MD]: testCommandsNamedByAgentsMd,
230
+ [CONFIG_JSON]: testCommandsNamedByConfig,
231
+ [CI_YML]: testCommandsNamedByCiWorkflow,
232
+ };
233
+
234
+ export interface TestCommandAgreement {
235
+ commands: NamedTestCommand[];
236
+ /** Empty when every position names the same string. */
237
+ violations: string[];
238
+ }
239
+
240
+ /**
241
+ * The violation text, shared by the three-file binding and the category.
242
+ *
243
+ * Exported because `commandParity` compares SIX positions and this one
244
+ * compares three — a second copy of the sentence would be a second decider
245
+ * that agrees with this one on every input either has ever seen.
246
+ */
247
+ export function commandDisagreement(commands: NamedTestCommand[]): string[] {
248
+ const distinct = [...new Set(commands.map(c => c.command))];
249
+ if (distinct.length <= 1) return [];
250
+ return [
251
+ `the test command is spelled ${distinct.length} different ways: ` +
252
+ commands.map(c => `${c.file} (${c.where}) says \`${c.command}\``).join("; "),
253
+ ];
254
+ }
255
+
256
+ /**
257
+ * The three-file binding #621 shipped. Reads all three files, extracts what
258
+ * each names, and reports a violation when the set of distinct strings is
259
+ * larger than one.
260
+ *
261
+ * A missing file and a file that names nothing both THROW. Neither is a clean
262
+ * reading, and both would otherwise arrive here as "no disagreement".
263
+ */
264
+ export function testCommandAgreement(root: string): TestCommandAgreement {
265
+ const commands: NamedTestCommand[] = [];
266
+ for (const file of AGREEMENT_FILES) {
267
+ const path = file === CONFIG_JSON ? rungateConfigPath(root) : join(root, file);
268
+ if (path === null || !existsSync(path)) {
269
+ throw new NoTestCommandError(`${file} does not exist under ${root}, so it names no test command`);
270
+ }
271
+ commands.push(...EXTRACTORS[file](readFileSync(path, "utf-8")));
272
+ }
273
+ return { commands, violations: commandDisagreement(commands) };
274
+ }
@@ -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
+ }