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.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- 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 +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
package/lib/test-census.ts
CHANGED
|
@@ -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
|
-
* ##
|
|
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
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
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
|
-
*
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
111
|
-
*
|
|
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
|
|
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
|
-
*
|
|
120
|
-
*
|
|
121
|
-
*
|
|
122
|
-
*
|
|
123
|
-
*
|
|
124
|
-
*
|
|
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
|
|
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
|
+
}
|