rungate 0.6.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 +81 -16
- package/lib/behavioral-cache.ts +150 -2
- 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 +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- 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 +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- 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/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- 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 +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -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/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -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-id-cross-tree.ts +19 -7
- 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 +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- 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/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 +241 -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-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- 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/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
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
|
+
}
|
package/lib/test-suite-lock.ts
CHANGED
|
@@ -37,6 +37,7 @@ import { execFileSync } from "child_process";
|
|
|
37
37
|
import { createHash } from "crypto";
|
|
38
38
|
import { tmpdir } from "os";
|
|
39
39
|
import { join } from "path";
|
|
40
|
+
import { readProcessTable, type ProcessRow } from "./process-table";
|
|
40
41
|
|
|
41
42
|
/**
|
|
42
43
|
* Suites allowed to run AT ONCE. Measured, not chosen: one full suite peaks at
|
|
@@ -538,27 +539,169 @@ function segmentIsFullSuite(segment: string, depth = 0): boolean {
|
|
|
538
539
|
*/
|
|
539
540
|
const LIVENESS_GRACE_SECONDS = 25;
|
|
540
541
|
|
|
542
|
+
/** The spelling of a suite that the command line itself carries. */
|
|
543
|
+
const SPELLED_BUN = /(^|\/|\s)bun\s+(run\s+)?test(\s|$)/;
|
|
544
|
+
|
|
545
|
+
/** `test` or `run test` as the first arguments after argv[0]. */
|
|
546
|
+
const SUITE_ARGUMENTS = /^\s+(run\s+)?test(\s|$)/;
|
|
547
|
+
|
|
548
|
+
/** What one `ps` command line is. `unknown` is a reading, not a default. */
|
|
549
|
+
export type PsLineReading = "suite" | "not-suite" | "unknown";
|
|
550
|
+
|
|
551
|
+
/** How argv[0] is resolved to the file it actually names. Injected for tests. */
|
|
552
|
+
export type ExecutableResolver = (path: string) => string;
|
|
553
|
+
|
|
554
|
+
/**
|
|
555
|
+
* The one place a `ps` line is judged to be a running suite (#707).
|
|
556
|
+
*
|
|
557
|
+
* Exported so there is exactly one binding to mutate and one thing for a
|
|
558
|
+
* case to drive over a table of real command lines. `suiteLiveness` reads
|
|
559
|
+
* the process table; this decides what a line means, and the two questions
|
|
560
|
+
* are separable only because they are separate functions. **The orphan
|
|
561
|
+
* reaper in `lib/orphan-reaper.ts` asks this same binding**, so the thing
|
|
562
|
+
* that decides what keeps a slot and the thing that decides what may be
|
|
563
|
+
* killed cannot drift apart — which is the whole of the #690/#707 pairing.
|
|
564
|
+
*
|
|
565
|
+
* ## Widening the leading boundary buys nothing, and that is still true
|
|
566
|
+
*
|
|
567
|
+
* `/tmp/brun test` is the documented workaround for #690, and `brun` is
|
|
568
|
+
* b-r-u-n: it **does not contain `bun` at all**, so no loosening of a
|
|
569
|
+
* pattern written over the string `bun` can ever match it. Measured:
|
|
570
|
+
* `"brun".includes("bun")` is `false`. #727 established this and reverted
|
|
571
|
+
* the widening, and nothing below re-litigates it — `SPELLED_BUN` is
|
|
572
|
+
* unchanged.
|
|
573
|
+
*
|
|
574
|
+
* ## What is new: ask the filesystem what the executable IS
|
|
575
|
+
*
|
|
576
|
+
* The workaround is a SYMLINK — measured on this machine, 2026-10-21:
|
|
577
|
+
* `/tmp/brun -> /opt/homebrew/bin/bun`, which `realpath`s to
|
|
578
|
+
* `/opt/homebrew/Cellar/bun/<version>/bin/bun`. So the name is an evasion
|
|
579
|
+
* and the identity is not. When a line's ARGUMENTS are a suite invocation
|
|
580
|
+
* (`<exe> test …` or `<exe> run test …`) but argv[0] is not spelled `bun`,
|
|
581
|
+
* this resolves argv[0] on disk and reads the basename of what it points
|
|
582
|
+
* at. A renamed or symlinked launcher is a `suite`; a resolution that
|
|
583
|
+
* cannot be taken is `unknown`.
|
|
584
|
+
*
|
|
585
|
+
* This is the liveness signal "that is not the process name at all" which
|
|
586
|
+
* the previous revision of this comment asked for, arriving as the
|
|
587
|
+
* executable's identity rather than as a heartbeat. A heartbeat was the
|
|
588
|
+
* other candidate and it is not available at this layer: the slot is taken
|
|
589
|
+
* by a PreToolUse hook that exits immediately, and a session running a
|
|
590
|
+
* foreground suite makes no tool calls while it waits, so nothing exists
|
|
591
|
+
* that could refresh the file.
|
|
592
|
+
*
|
|
593
|
+
* ## The two directions, and why they are not symmetric
|
|
594
|
+
*
|
|
595
|
+
* A resolution that fails, or an argv[0] that is not an absolute path, is
|
|
596
|
+
* `unknown` — and so is a binary whose resolved basename is something else,
|
|
597
|
+
* because a *copy* of bun under another name resolves to itself and no
|
|
598
|
+
* cheap reading can tell it from an unrelated program called with a `test`
|
|
599
|
+
* argument. The two consumers read that third state in OPPOSITE directions,
|
|
600
|
+
* deliberately:
|
|
601
|
+
*
|
|
602
|
+
* - **Keeping a slot** needs "not positively idle", so `unknown` keeps it.
|
|
603
|
+
* Over-detection costs at most one wedged slot for a TTL. Missing a suite
|
|
604
|
+
* that IS there reclaims a live slot and lets two real suites run against
|
|
605
|
+
* a cap of one, which is the OOM condition this whole mechanism prevents.
|
|
606
|
+
* - **Killing a process** needs "positively a suite", so `unknown` is never
|
|
607
|
+
* reaped. Over-detection there costs somebody else's work.
|
|
608
|
+
*
|
|
609
|
+
* The cost of the conservative reading is bounded and worth naming: one
|
|
610
|
+
* long-lived unrelated `/usr/bin/foo test` process makes the machine read
|
|
611
|
+
* `unknown`, which switches the early liveness reclaim off and leaves the
|
|
612
|
+
* 420-second TTL as the only staleness rule. That is the pre-#74 behaviour,
|
|
613
|
+
* not a new failure mode.
|
|
614
|
+
*/
|
|
615
|
+
export function classifyPsLine(
|
|
616
|
+
line: string,
|
|
617
|
+
options: { resolveExecutable?: ExecutableResolver } = {},
|
|
618
|
+
): PsLineReading {
|
|
619
|
+
if (SPELLED_BUN.test(line)) return "suite";
|
|
620
|
+
|
|
621
|
+
const space = line.indexOf(" ");
|
|
622
|
+
if (space <= 0) return "not-suite";
|
|
623
|
+
const argv0 = line.slice(0, space);
|
|
624
|
+
if (!SUITE_ARGUMENTS.test(line.slice(space))) return "not-suite";
|
|
625
|
+
|
|
626
|
+
// The arguments say "suite" and the name does not. Everything from here is
|
|
627
|
+
// a question about the file on disk, which is the thing a rename cannot
|
|
628
|
+
// change.
|
|
629
|
+
if (!argv0.startsWith("/")) return "unknown";
|
|
630
|
+
let resolved: string;
|
|
631
|
+
try {
|
|
632
|
+
resolved = (options.resolveExecutable ?? realpathSync)(argv0);
|
|
633
|
+
} catch {
|
|
634
|
+
return "unknown";
|
|
635
|
+
}
|
|
636
|
+
return resolved.slice(resolved.lastIndexOf("/") + 1) === "bun" ? "suite" : "unknown";
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
/**
|
|
640
|
+
* `psLineIsSuite` as it has always behaved: a projection of the reading
|
|
641
|
+
* above, kept because callers and cases already name it.
|
|
642
|
+
*
|
|
643
|
+
* It is a PROJECTION and not a second decider — there is one `classifyPsLine`
|
|
644
|
+
* and this restates its answer — so a mutation of the classifier moves this
|
|
645
|
+
* too, which is the property that makes the battery able to see either.
|
|
646
|
+
*/
|
|
647
|
+
export function psLineIsSuite(
|
|
648
|
+
line: string,
|
|
649
|
+
options: { resolveExecutable?: ExecutableResolver } = {},
|
|
650
|
+
): boolean {
|
|
651
|
+
return classifyPsLine(line, options) === "suite";
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
/** What the machine as a whole is doing. `unknown` is a reading. */
|
|
655
|
+
export type SuiteLiveness = "running" | "idle" | "unknown";
|
|
656
|
+
|
|
657
|
+
export interface LivenessOptions {
|
|
658
|
+
rows?: ProcessRow[];
|
|
659
|
+
readRows?: () => ProcessRow[];
|
|
660
|
+
resolveExecutable?: ExecutableResolver;
|
|
661
|
+
}
|
|
662
|
+
|
|
541
663
|
/**
|
|
542
|
-
*
|
|
664
|
+
* Whether any full suite is running anywhere on this machine.
|
|
543
665
|
*
|
|
544
|
-
* ONLY THE
|
|
545
|
-
* bun processes to sessions is unreliable — the agentgrit suite
|
|
546
|
-
* dangling bun processes per run, which is why slots are files
|
|
547
|
-
* process count. This does not attribute anything: a slot
|
|
548
|
-
* suite, so if NO suite is running at all, every slot is
|
|
666
|
+
* ONLY THE `idle` CASE IS ACTED ON, deliberately. #67 established that
|
|
667
|
+
* attributing bun processes to sessions is unreliable — the agentgrit suite
|
|
668
|
+
* leaks ~31 dangling bun processes per run, which is why slots are files
|
|
669
|
+
* rather than a process count. This does not attribute anything: a slot
|
|
670
|
+
* means a running suite, so if NO suite is running at all, every slot is
|
|
671
|
+
* provably false.
|
|
549
672
|
*
|
|
550
|
-
*
|
|
551
|
-
*
|
|
552
|
-
*
|
|
673
|
+
* `idle` is therefore a POSITIVE claim and it is made only when the whole
|
|
674
|
+
* table was read and every row was classified. One unclassifiable row makes
|
|
675
|
+
* the reading `unknown`, because `idle` is the only reading that lets a live
|
|
676
|
+
* slot be taken away from somebody.
|
|
677
|
+
*/
|
|
678
|
+
export function suiteLiveness(options: LivenessOptions = {}): SuiteLiveness {
|
|
679
|
+
let rows: ProcessRow[];
|
|
680
|
+
try {
|
|
681
|
+
rows = options.rows ?? (options.readRows ?? readProcessTable)();
|
|
682
|
+
} catch {
|
|
683
|
+
return "unknown";
|
|
684
|
+
}
|
|
685
|
+
let sawUnknown = false;
|
|
686
|
+
for (const row of rows) {
|
|
687
|
+
const reading = classifyPsLine(row.command, options);
|
|
688
|
+
if (reading === "suite") return "running";
|
|
689
|
+
if (reading === "unknown") sawUnknown = true;
|
|
690
|
+
}
|
|
691
|
+
return sawUnknown ? "unknown" : "idle";
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
/**
|
|
695
|
+
* True when the machine is NOT positively idle.
|
|
553
696
|
*
|
|
554
|
-
*
|
|
555
|
-
* caller
|
|
697
|
+
* The collapse is one-sided on purpose: `unknown` reads as `true` here, so a
|
|
698
|
+
* caller that only wants "may I take this slot away" gets the safe answer
|
|
699
|
+
* without having to remember which way round the third state goes. A caller
|
|
700
|
+
* that needs to tell `unknown` from `running` asks `suiteLiveness` — and the
|
|
701
|
+
* reaper does, because the opposite collapse would kill on a guess.
|
|
556
702
|
*/
|
|
557
|
-
export function anySuiteRunning(): boolean {
|
|
558
|
-
|
|
559
|
-
return out
|
|
560
|
-
.split("\n")
|
|
561
|
-
.some(line => /(^|\/|\s)bun\s+(run\s+)?test(\s|$)/.test(line));
|
|
703
|
+
export function anySuiteRunning(options: LivenessOptions = {}): boolean {
|
|
704
|
+
return suiteLiveness(options) !== "idle";
|
|
562
705
|
}
|
|
563
706
|
|
|
564
707
|
/**
|