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
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Who owns the harness work root, and may this process delete inside it (#904).
|
|
3
|
+
*
|
|
4
|
+
* ## The harm this exists to stop
|
|
5
|
+
*
|
|
6
|
+
* `lib/stale-cleanup.ts` walks every top-level directory under the harness
|
|
7
|
+
* work root and renames or deletes it on `mtime` and `phase` alone. It has
|
|
8
|
+
* never had an ownership check. A self-hosted pool that runs several runner
|
|
9
|
+
* processes under one service account shares a `$HOME`, so those runners also
|
|
10
|
+
* share `$HOME/.rungate` — and a SessionStart on runner-5 archives runner-4's
|
|
11
|
+
* live run directory the moment runner-4's `workflow-state.json` looks stale.
|
|
12
|
+
*
|
|
13
|
+
* The failure that produces is NON-LOCAL. Runner-4 fails in a step that did
|
|
14
|
+
* nothing wrong, because a sibling moved a file underneath it. It reads as a
|
|
15
|
+
* flaky test, which is the worst possible disguise for a contention bug.
|
|
16
|
+
*
|
|
17
|
+
* ## Why this is not the `$HOME`-in-the-workflow fix
|
|
18
|
+
*
|
|
19
|
+
* The cheapest wrong fix is `HOME: ${{ runner.temp }}/home` in the workflow
|
|
20
|
+
* YAML. The symptom goes away for CI and the harness keeps its one unguarded
|
|
21
|
+
* `$HOME` assumption: a consumer who runs the same jobs without that line
|
|
22
|
+
* gets the original bug back, and nothing in the harness says so. The check
|
|
23
|
+
* here is on the sweep's behaviour, so it is unaffected by that line either
|
|
24
|
+
* way — which is the point. A regression test that goes green when you edit
|
|
25
|
+
* the workflow file is testing the workflow file.
|
|
26
|
+
*
|
|
27
|
+
* ## Why an empty `$HOME` cannot see this
|
|
28
|
+
*
|
|
29
|
+
* `scripts/test-clean-env.ts` runs suites with `HOME` at an empty `mkdtemp`.
|
|
30
|
+
* An empty work root archives nothing whether the sweep is ownership-aware or
|
|
31
|
+
* not, so the isolation bug is invisible to exactly the suites that look most
|
|
32
|
+
* rigorous. The discriminating input is a work root that is POPULATED with
|
|
33
|
+
* another runner's directory: the ownership-blind sweep archives it, the
|
|
34
|
+
* guarded one refuses and names the owner.
|
|
35
|
+
*
|
|
36
|
+
* ## The lifecycle, and why auto-claim is safe only when vacant
|
|
37
|
+
*
|
|
38
|
+
* Claiming a root that already holds state would let whichever runner booted
|
|
39
|
+
* first assume ownership of everybody's work — the original bug with a marker
|
|
40
|
+
* file on top. So a claim happens only when there is nothing to destroy:
|
|
41
|
+
*
|
|
42
|
+
* - vacant root, no marker → claim it, sweep (a no-op this time round)
|
|
43
|
+
* - marker names this runner → sweep, exactly as before
|
|
44
|
+
* - marker names another → REFUSE, and name the other runner
|
|
45
|
+
* - occupied, no marker → REFUSE; nothing here can be attributed
|
|
46
|
+
* - not on a runner at all → sweep, exactly as before
|
|
47
|
+
*
|
|
48
|
+
* The last line is why this change is inert on a developer's machine and in
|
|
49
|
+
* every existing test: `RUNNER_NAME` is a GitHub Actions variable, so off a
|
|
50
|
+
* runner the verdict is `unscoped` and the sweep behaves as it always has.
|
|
51
|
+
*
|
|
52
|
+
* Once each runner has its own `HOME` (#904's infrastructure half), each
|
|
53
|
+
* private root is vacant on its first job, claims itself, and sweeps normally
|
|
54
|
+
* forever after. This check is what converts that isolation into something
|
|
55
|
+
* measurable instead of something assumed.
|
|
56
|
+
*
|
|
57
|
+
* ## Zero is not success
|
|
58
|
+
*
|
|
59
|
+
* A refused sweep returns `archived: 0`, which is indistinguishable from "a
|
|
60
|
+
* clean root with nothing to archive". That ambiguity is the reason
|
|
61
|
+
* `sweep: false` and `reason` exist as fields rather than as a log line:
|
|
62
|
+
* silence, `0` and `null` must not all mean the same thing.
|
|
63
|
+
*/
|
|
64
|
+
|
|
65
|
+
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
|
|
66
|
+
import { join } from "path";
|
|
67
|
+
|
|
68
|
+
/** Basename of the ownership marker written at the root of the work dir. */
|
|
69
|
+
export const WORK_ROOT_OWNER_FILE = ".owner";
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Directory entries that do not count as occupancy.
|
|
73
|
+
*
|
|
74
|
+
* `.archive` is excluded only when it is EMPTY — an archive holding another
|
|
75
|
+
* runner's directories is occupancy, and treating the directory's mere
|
|
76
|
+
* existence as vacancy would let a root be claimed out from under the very
|
|
77
|
+
* state the sweep already moved there.
|
|
78
|
+
*/
|
|
79
|
+
const VACANCY_EXEMPT = new Set([WORK_ROOT_OWNER_FILE, ".archive"]);
|
|
80
|
+
|
|
81
|
+
export const WORK_ROOT_REFUSED_SHARED =
|
|
82
|
+
"the harness work root is claimed by a DIFFERENT runner, so the stale " +
|
|
83
|
+
"sweep refused: archiving here would move a sibling runner's live state " +
|
|
84
|
+
"out from under it, and the job that fails is the sibling's, not this one " +
|
|
85
|
+
"(#904). Give each runner its own HOME.";
|
|
86
|
+
|
|
87
|
+
export const WORK_ROOT_REFUSED_UNATTRIBUTED =
|
|
88
|
+
"the harness work root already holds run state but records no owning " +
|
|
89
|
+
"runner, so the stale sweep refused: on a shared HOME nothing here can be " +
|
|
90
|
+
"attributed to this runner, and an unattributed delete is the bug (#904).";
|
|
91
|
+
|
|
92
|
+
export const WORK_ROOT_REFUSED_UNNAMABLE =
|
|
93
|
+
"RUNNER_NAME is set but contains no characters usable as an owner id, so " +
|
|
94
|
+
"the stale sweep refused: this runner cannot be told apart from a sibling " +
|
|
95
|
+
"and ownership cannot be decided (#904).";
|
|
96
|
+
|
|
97
|
+
export type WorkRootState =
|
|
98
|
+
| "unscoped"
|
|
99
|
+
| "vacant"
|
|
100
|
+
| "claimed"
|
|
101
|
+
| "owned"
|
|
102
|
+
| "shared"
|
|
103
|
+
| "unattributed"
|
|
104
|
+
| "unnamable";
|
|
105
|
+
|
|
106
|
+
export interface WorkRootVerdict {
|
|
107
|
+
/** May this process delete or archive inside the work root? */
|
|
108
|
+
readonly sweep: boolean;
|
|
109
|
+
readonly state: WorkRootState;
|
|
110
|
+
/** This process's runner id, or `null` when not running on a runner. */
|
|
111
|
+
readonly runner: string | null;
|
|
112
|
+
/** The id recorded in the marker file, or `null` when there is none. */
|
|
113
|
+
readonly owner: string | null;
|
|
114
|
+
/** One of the exported refusal constants, and non-null exactly when `sweep` is false. */
|
|
115
|
+
readonly reason: string | null;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Filesystem-safe form of a runner name.
|
|
120
|
+
*
|
|
121
|
+
* GitHub Actions names hosted runners "GitHub Actions 2" — spaces and all —
|
|
122
|
+
* so the raw value is not usable as a path component or a stable token.
|
|
123
|
+
*/
|
|
124
|
+
function slugifyRunner(raw: string): string {
|
|
125
|
+
return raw
|
|
126
|
+
.trim()
|
|
127
|
+
.toLowerCase()
|
|
128
|
+
.replace(/[^a-z0-9._-]+/g, "-")
|
|
129
|
+
.replace(/^[-.]+|[-.]+$/g, "");
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* This process's runner id, or `null` when it is not running on a runner.
|
|
134
|
+
*
|
|
135
|
+
* Returns `null` for BOTH "absent" and "unusable", so callers that need to
|
|
136
|
+
* tell a developer's laptop from a misconfigured runner must read
|
|
137
|
+
* `workRootOwnership`'s verdict instead — `null` here is deliberately not a
|
|
138
|
+
* licence to sweep.
|
|
139
|
+
*/
|
|
140
|
+
export function runnerId(env: NodeJS.ProcessEnv = process.env): string | null {
|
|
141
|
+
const slug = slugifyRunner(env.RUNNER_NAME ?? "");
|
|
142
|
+
return slug === "" ? null : slug;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* An `.archive` that cannot be read counts as OCCUPIED, not as empty — an
|
|
147
|
+
* unreadable directory is a thing this process knows nothing about, and the
|
|
148
|
+
* safe reading of "I could not tell" is "do not claim this root".
|
|
149
|
+
*/
|
|
150
|
+
function archiveIsEmpty(workRoot: string): boolean {
|
|
151
|
+
try {
|
|
152
|
+
return readdirSync(join(workRoot, ".archive")).length === 0;
|
|
153
|
+
} catch {
|
|
154
|
+
return false;
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
function isVacant(workRoot: string): boolean {
|
|
159
|
+
let names: string[];
|
|
160
|
+
try {
|
|
161
|
+
names = readdirSync(workRoot);
|
|
162
|
+
} catch {
|
|
163
|
+
// Unreadable or absent: there is nothing here this process could destroy.
|
|
164
|
+
return true;
|
|
165
|
+
}
|
|
166
|
+
for (const name of names) {
|
|
167
|
+
if (!VACANCY_EXEMPT.has(name)) return false;
|
|
168
|
+
if (name === ".archive" && !archiveIsEmpty(workRoot)) return false;
|
|
169
|
+
}
|
|
170
|
+
return true;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
function readOwner(workRoot: string): string | null {
|
|
174
|
+
const marker = join(workRoot, WORK_ROOT_OWNER_FILE);
|
|
175
|
+
if (!existsSync(marker)) return null;
|
|
176
|
+
try {
|
|
177
|
+
const recorded = readFileSync(marker, "utf-8").trim();
|
|
178
|
+
return recorded === "" ? null : recorded;
|
|
179
|
+
} catch {
|
|
180
|
+
return null;
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* Record `runner` as the owner of `workRoot`.
|
|
186
|
+
*
|
|
187
|
+
* Exported so that a consumer provisioning a genuinely private `HOME` can
|
|
188
|
+
* claim it up front rather than waiting for a vacant-root job to do it.
|
|
189
|
+
* Idempotent, and deliberately silent on failure: an unwritable root is
|
|
190
|
+
* reported by the next verdict as `unattributed`, which refuses, rather than
|
|
191
|
+
* by throwing out of a SessionStart hook.
|
|
192
|
+
*/
|
|
193
|
+
export function claimWorkRoot(workRoot: string, runner: string): boolean {
|
|
194
|
+
try {
|
|
195
|
+
mkdirSync(workRoot, { recursive: true });
|
|
196
|
+
writeFileSync(join(workRoot, WORK_ROOT_OWNER_FILE), `${runner}\n`);
|
|
197
|
+
return true;
|
|
198
|
+
} catch {
|
|
199
|
+
return false;
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* Decide whether this process may delete inside `workRoot`.
|
|
205
|
+
*
|
|
206
|
+
* Claims a vacant root as a side effect; see the module docblock for why that
|
|
207
|
+
* is the only case in which claiming cannot harm a sibling.
|
|
208
|
+
*/
|
|
209
|
+
export function workRootOwnership(
|
|
210
|
+
workRoot: string,
|
|
211
|
+
env: NodeJS.ProcessEnv = process.env,
|
|
212
|
+
): WorkRootVerdict {
|
|
213
|
+
const raw = env.RUNNER_NAME ?? "";
|
|
214
|
+
if (raw.trim() === "") {
|
|
215
|
+
return { sweep: true, state: "unscoped", runner: null, owner: null, reason: null };
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
const runner = slugifyRunner(raw);
|
|
219
|
+
if (runner === "") {
|
|
220
|
+
return {
|
|
221
|
+
sweep: false,
|
|
222
|
+
state: "unnamable",
|
|
223
|
+
runner: null,
|
|
224
|
+
owner: null,
|
|
225
|
+
reason: WORK_ROOT_REFUSED_UNNAMABLE,
|
|
226
|
+
};
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
const owner = readOwner(workRoot);
|
|
230
|
+
if (owner !== null) {
|
|
231
|
+
return owner === runner
|
|
232
|
+
? { sweep: true, state: "owned", runner, owner, reason: null }
|
|
233
|
+
: {
|
|
234
|
+
sweep: false,
|
|
235
|
+
state: "shared",
|
|
236
|
+
runner,
|
|
237
|
+
owner,
|
|
238
|
+
reason: WORK_ROOT_REFUSED_SHARED,
|
|
239
|
+
};
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
if (!isVacant(workRoot)) {
|
|
243
|
+
return {
|
|
244
|
+
sweep: false,
|
|
245
|
+
state: "unattributed",
|
|
246
|
+
runner,
|
|
247
|
+
owner: null,
|
|
248
|
+
reason: WORK_ROOT_REFUSED_UNATTRIBUTED,
|
|
249
|
+
};
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
const claimed = claimWorkRoot(workRoot, runner);
|
|
253
|
+
return {
|
|
254
|
+
sweep: true,
|
|
255
|
+
state: claimed ? "claimed" : "vacant",
|
|
256
|
+
runner,
|
|
257
|
+
owner: claimed ? runner : null,
|
|
258
|
+
reason: null,
|
|
259
|
+
};
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* The log line a refusing sweep emits.
|
|
264
|
+
*
|
|
265
|
+
* One formatter so the reason, the two runner ids and the path always travel
|
|
266
|
+
* together: a refusal that named neither party would be exactly as mysterious
|
|
267
|
+
* as the silent delete it replaces.
|
|
268
|
+
*/
|
|
269
|
+
export function workRootRefusalLine(workRoot: string, verdict: WorkRootVerdict): string {
|
|
270
|
+
return (
|
|
271
|
+
`REFUSED sweep state=${verdict.state} runner=${verdict.runner ?? "?"} ` +
|
|
272
|
+
`owner=${verdict.owner ?? "none"} path=${workRoot} :: ${verdict.reason}`
|
|
273
|
+
);
|
|
274
|
+
}
|
package/lib/sc-claim-forms.ts
CHANGED
|
@@ -169,11 +169,86 @@ const IDS_ONLY =
|
|
|
169
169
|
*/
|
|
170
170
|
const PAREN_LABEL = /^\s*(?:SC|AC)-[A-Z]?\d+\s*:/;
|
|
171
171
|
|
|
172
|
+
/**
|
|
173
|
+
* A RANGE inside a parenthetical — `(SC-1930..SC-1948)`.
|
|
174
|
+
*
|
|
175
|
+
* An attribution names THE criterion a statement is about. A range names a
|
|
176
|
+
* group, which is how prose refers to a set it is discussing rather than
|
|
177
|
+
* claiming, and the scanner can only see the two ids that are literally
|
|
178
|
+
* written: a range of nineteen credits its two endpoints and silently not
|
|
179
|
+
* the seventeen between them. A form that credits 2 of the 19 ids it names
|
|
180
|
+
* is not measuring anything.
|
|
181
|
+
*
|
|
182
|
+
* Found in #574, on this sentence:
|
|
183
|
+
*
|
|
184
|
+
* * The spec's 19 behavioural criteria (SC-1930..SC-1948) are NOT
|
|
185
|
+
* * covered here.
|
|
186
|
+
*
|
|
187
|
+
* — which credited SC-1930 and SC-1948 and ticked both boxes. The
|
|
188
|
+
* self-reference this area keeps producing, now in its sharpest form: a
|
|
189
|
+
* comment saying the criteria are not covered was the evidence that they
|
|
190
|
+
* were.
|
|
191
|
+
*
|
|
192
|
+
* Measured before narrowing, because narrowing a detector is the change
|
|
193
|
+
* most likely to buy green with blindness: of 32 attribution credits in the
|
|
194
|
+
* tree, 30 are plain and 2 are ranges — and the 2 are these. A range at the
|
|
195
|
+
* START of a line is still a claim, by the `line` form, which is where
|
|
196
|
+
* `* SC-561..SC-564 (SPEC.md)` is credited and is unaffected.
|
|
197
|
+
*/
|
|
198
|
+
const PAREN_RANGE = /\.\.+/;
|
|
199
|
+
|
|
172
200
|
function inIdOnlyParenthetical(line: string, at: number): boolean {
|
|
173
201
|
const open = line.lastIndexOf("(", at);
|
|
174
202
|
if (open < 0) return false;
|
|
175
203
|
const close = line.indexOf(")", open);
|
|
176
204
|
if (close < 0 || close < at) return false;
|
|
177
205
|
const inner = line.slice(open + 1, close);
|
|
206
|
+
if (PAREN_RANGE.test(inner)) return false;
|
|
178
207
|
return IDS_ONLY.test(inner) || PAREN_LABEL.test(inner);
|
|
179
208
|
}
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* A `describe`/`test`/`it` call that opens a title literal, and whether it
|
|
212
|
+
* will ever run (#574).
|
|
213
|
+
*
|
|
214
|
+
* A test title is the project's oldest coverage convention and the one
|
|
215
|
+
* position that needed no rule — until `test.todo("SC-1930: …")` turned out
|
|
216
|
+
* to be a title too. A todo is the one test guaranteed never to fail, so
|
|
217
|
+
* crediting it produces a tick indistinguishable from a tick earned by a
|
|
218
|
+
* test that can go red. Measured when this was found: 64 ids named only
|
|
219
|
+
* inside a `.todo`, 37 of them ticked `[x]` in a spec, and 19 more about to
|
|
220
|
+
* flip on the next run of the sync — one of them from a file whose own
|
|
221
|
+
* comment says, four lines from the top, that none of its criteria are
|
|
222
|
+
* covered here.
|
|
223
|
+
*
|
|
224
|
+
* `.skip` is the same fact with a different word, and there are five of
|
|
225
|
+
* those. `.skipIf` and `.todoIf` take a condition, so whether they ran is
|
|
226
|
+
* not answerable from the source at all; there are none today and they are
|
|
227
|
+
* named anyway, because a predicate narrower than what it detects is this
|
|
228
|
+
* repo's third defect shape and the cost of naming them is one word each.
|
|
229
|
+
*
|
|
230
|
+
* `.only`, `.each`, `.failing` and `.concurrent` all RUN, so they still
|
|
231
|
+
* credit — `.failing` included, because a test expected to fail is still a
|
|
232
|
+
* test that goes red when the expectation stops holding.
|
|
233
|
+
*
|
|
234
|
+
* Returns `null` when the text does not open a title call at all. The three
|
|
235
|
+
* answers are distinct on purpose: a non-running title must be reported as
|
|
236
|
+
* UNMEASURED rather than dropped, and dropping it would make "nobody has
|
|
237
|
+
* written this test" look exactly like "nobody has mentioned this id".
|
|
238
|
+
*/
|
|
239
|
+
export type TitleCall = "runs" | "never-runs";
|
|
240
|
+
|
|
241
|
+
const NON_RUNNING = /\.(?:todo|skip|skipIf|todoIf)\b/;
|
|
242
|
+
|
|
243
|
+
/** Opens a `describe`/`test`/`it` title, allowing `.each(...)`, `.only`, `.skip`, `.todo`. */
|
|
244
|
+
const TITLE_CALL = /\b(?:describe|test|it)\s*((?:\.\w+\s*(?:\([^)]*\))?\s*)*)\(\s*$/;
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* THE single exported predicate for whether a title call declares coverage,
|
|
248
|
+
* for the same reason `commentClaimForm` is: one binding to mutate.
|
|
249
|
+
*/
|
|
250
|
+
export function titleCall(before: string): TitleCall | null {
|
|
251
|
+
const m = TITLE_CALL.exec(before);
|
|
252
|
+
if (m === null) return null;
|
|
253
|
+
return NON_RUNNING.test(m[1] ?? "") ? "never-runs" : "runs";
|
|
254
|
+
}
|
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The SC id namespace as it exists on this machine, not in this checkout (#503).
|
|
3
|
+
*
|
|
4
|
+
* `nextSCNumber` allocates "highest + 1", and #392 taught it to read the whole
|
|
5
|
+
* registry rather than one spec's content. Both fixes are about the same
|
|
6
|
+
* mistake at different widths, and the width was still wrong: the registry is
|
|
7
|
+
* `specs/` **in the working tree the command happens to run in**.
|
|
8
|
+
*
|
|
9
|
+
* On 2026-10-16 two sessions allocated `SC-1706..1710` within minutes of each
|
|
10
|
+
* other — one in `specs/HARNESS-STANDARD.md`, one in
|
|
11
|
+
* `specs/CONFIG-DIRECTORY-STRUCTURE-SPEC.md`, in two worktrees of the same
|
|
12
|
+
* repository. Both read the highest id they could see. Both were right about
|
|
13
|
+
* their own tree. `test/spec-sc-ids-unique.test.ts` was green in each,
|
|
14
|
+
* independently, until a rebase put them in one place.
|
|
15
|
+
*
|
|
16
|
+
* That is the second shape in `.claude/rules/checks-must-be-able-to-fail.md`
|
|
17
|
+
* — a detector narrower than what it detects. The question is "is this number
|
|
18
|
+
* free in the project"; the detector answered "is this number free in this
|
|
19
|
+
* checkout". The two differ exactly when more than one session is working,
|
|
20
|
+
* which here is the normal case: this repository has 110 worktrees on disk.
|
|
21
|
+
*
|
|
22
|
+
* ## Two sources, because the collision lives in the gap between them
|
|
23
|
+
*
|
|
24
|
+
* | Source | Catches | Misses |
|
|
25
|
+
* |---|---|---|
|
|
26
|
+
* | sibling worktrees' `specs/` | **uncommitted** ids in another session's tree | a branch whose worktree was removed |
|
|
27
|
+
* | every local and remote-tracking ref | committed ids on any branch, pushed or not | work that exists only on another machine |
|
|
28
|
+
*
|
|
29
|
+
* Neither alone is enough. The #503 collision was an unpushed branch in
|
|
30
|
+
* another worktree, which the ref scan sees only once it is committed —
|
|
31
|
+
* and `.claude/rules/parallel-sessions.md` exists because that window is
|
|
32
|
+
* real and people sit in it for an hour.
|
|
33
|
+
*
|
|
34
|
+
* ## This errs toward "taken", deliberately
|
|
35
|
+
*
|
|
36
|
+
* A stale worktree holding an abandoned branch contributes ids that nothing
|
|
37
|
+
* will ever claim, and the allocator will skip them. That costs a gap in the
|
|
38
|
+
* numbering, which costs nothing: SC ids are opaque join keys, not an
|
|
39
|
+
* ordering anyone reads. The other direction costs a collision, which is two
|
|
40
|
+
* spec lines a test can bind to and no way to see which one it bound to.
|
|
41
|
+
*
|
|
42
|
+
* ## What this is NOT
|
|
43
|
+
*
|
|
44
|
+
* It is not a guard that refuses on a cross-tree duplicate, and that is a
|
|
45
|
+
* measurement rather than a shrug. Across the 110 worktrees on this machine,
|
|
46
|
+
* 30 ids are declared in more than one spec FILE: `SC-A1`/`SC-A2`, which are
|
|
47
|
+
* anti-criteria that several specs legitimately carry, and `SC-694..703`,
|
|
48
|
+
* which is a REAL collision from months ago, resolved on main by renumbering
|
|
49
|
+
* and preserved forever in the stale trees that still hold the losing side.
|
|
50
|
+
* A guard over that population is permanently red for reasons nobody can act
|
|
51
|
+
* on, which is the fastest way to build a refusal everyone learns to click
|
|
52
|
+
* past. Fix the allocator that mints collisions; do not alarm on the fossils.
|
|
53
|
+
*/
|
|
54
|
+
import { execFileSync } from "child_process";
|
|
55
|
+
import { existsSync, readdirSync, readFileSync, statSync } from "fs";
|
|
56
|
+
import { join } from "path";
|
|
57
|
+
|
|
58
|
+
import { isFixtureScId, scDeclarationPattern, scHeadingDeclarationPattern } from "./sc-ids";
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* One place ids were looked for, and whether the look succeeded.
|
|
62
|
+
*
|
|
63
|
+
* `worktree` and `refs` are this module's own two sources. The other four
|
|
64
|
+
* are the legs `allocateScNumber` composes on top of them (#593, #725) — the
|
|
65
|
+
* spec's own content, the spec registry, the ids spelled in source, and the
|
|
66
|
+
* reservation store. They live in the same shape because the question a
|
|
67
|
+
* reader asks is one question: which widths produced this number, and did any
|
|
68
|
+
* of them fail to run.
|
|
69
|
+
*
|
|
70
|
+
* `reservations` is the only leg that is not a reading of ids somebody has
|
|
71
|
+
* already written down. It is a reading of ids somebody has DECLARED they are
|
|
72
|
+
* about to write down, which is the half the other five structurally cannot
|
|
73
|
+
* see (#725).
|
|
74
|
+
*/
|
|
75
|
+
export interface SourceReading {
|
|
76
|
+
label: string;
|
|
77
|
+
kind: "worktree" | "refs" | "spec-content" | "registry" | "source-mentions" | "reservations";
|
|
78
|
+
/** `read` means the ids below came from here; `skipped` means they did not. */
|
|
79
|
+
status: "read" | "skipped";
|
|
80
|
+
/**
|
|
81
|
+
* Why it was skipped — or, on a PARTIAL read, what it could not reach
|
|
82
|
+
* (#606). A leg over four directories that opened three of them is `read`
|
|
83
|
+
* for the three and still owes an account of the fourth; folding that into
|
|
84
|
+
* `skipped` would make it indistinguishable from a leg that opened none.
|
|
85
|
+
* Absent only on a read that reached everything it was pointed at.
|
|
86
|
+
*/
|
|
87
|
+
reason?: string;
|
|
88
|
+
/** How many distinct ids this source contributed. */
|
|
89
|
+
found: number;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
export interface ScNamespaceReading {
|
|
93
|
+
/** id → the labels that declared it. */
|
|
94
|
+
ids: Map<string, string[]>;
|
|
95
|
+
sources: SourceReading[];
|
|
96
|
+
/**
|
|
97
|
+
* Why this reading is a floor rather than a fact. Never empty: a clone on
|
|
98
|
+
* another machine is outside anything this process can see, and saying so
|
|
99
|
+
* is the difference between an unmeasured half and a silent pass
|
|
100
|
+
* (`.claude/rules/config-access.md`).
|
|
101
|
+
*/
|
|
102
|
+
unmeasured: string[];
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function git(root: string, args: string[]): string {
|
|
106
|
+
// 64 MB, because the default is 1 MB and a grep over a thousand refs blows
|
|
107
|
+
// through it. Measured: the first run of this module reported
|
|
108
|
+
// `ENOBUFS (stdout or stderr buffer reached maxBuffer size limit)` as a
|
|
109
|
+
// skipped source, which is the reading behaving correctly over a bug.
|
|
110
|
+
return execFileSync("git", args, {
|
|
111
|
+
cwd: root,
|
|
112
|
+
encoding: "utf-8",
|
|
113
|
+
timeout: 120_000,
|
|
114
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
115
|
+
// Captured, not inherited. A failed `git` here is a source this reading
|
|
116
|
+
// records as skipped, and letting its stderr through would put
|
|
117
|
+
// "fatal: not a git repository" in the middle of a suite's output for a
|
|
118
|
+
// case that is handling exactly that (#60: a test must not corrupt the
|
|
119
|
+
// output stream of the suite containing it).
|
|
120
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
121
|
+
});
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Every worktree of this repository except `root` itself.
|
|
126
|
+
*
|
|
127
|
+
* `failure` is non-null when git could not be asked at all — which is a
|
|
128
|
+
* different fact from "there are no siblings", and conflating the two is how
|
|
129
|
+
* a reading of nothing reads as a reading of everything.
|
|
130
|
+
*/
|
|
131
|
+
export function siblingWorktrees(root: string): { paths: string[]; failure: string | null } {
|
|
132
|
+
let out: string;
|
|
133
|
+
try {
|
|
134
|
+
out = git(root, ["worktree", "list", "--porcelain"]);
|
|
135
|
+
} catch (err) {
|
|
136
|
+
return { paths: [], failure: (err as Error).message.split("\n")[0] };
|
|
137
|
+
}
|
|
138
|
+
const paths: string[] = [];
|
|
139
|
+
let current: string | null = null;
|
|
140
|
+
let prunable = false;
|
|
141
|
+
const flush = (): void => {
|
|
142
|
+
if (current && !prunable && current !== root) paths.push(current);
|
|
143
|
+
current = null;
|
|
144
|
+
prunable = false;
|
|
145
|
+
};
|
|
146
|
+
for (const line of out.split("\n")) {
|
|
147
|
+
if (line.startsWith("worktree ")) {
|
|
148
|
+
flush();
|
|
149
|
+
current = line.slice("worktree ".length);
|
|
150
|
+
} else if (line.startsWith("prunable")) {
|
|
151
|
+
prunable = true;
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
flush();
|
|
155
|
+
return { paths, failure: null };
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** The ids a single `specs/` directory declares, by checkbox or by heading. */
|
|
159
|
+
function idsInSpecsDir(specsDir: string): string[] {
|
|
160
|
+
const ids: string[] = [];
|
|
161
|
+
for (const name of readdirSync(specsDir)) {
|
|
162
|
+
if (!name.endsWith(".md")) continue;
|
|
163
|
+
let content: string;
|
|
164
|
+
try {
|
|
165
|
+
content = readFileSync(join(specsDir, name), "utf-8");
|
|
166
|
+
} catch {
|
|
167
|
+
// A spec we cannot read contributes nothing, and the caller records the
|
|
168
|
+
// tree as read regardless: one unreadable file is not an unmeasured
|
|
169
|
+
// tree, and pretending otherwise would make every reading unmeasured.
|
|
170
|
+
continue;
|
|
171
|
+
}
|
|
172
|
+
for (const m of content.matchAll(scDeclarationPattern())) ids.push(m[2]);
|
|
173
|
+
for (const m of content.matchAll(scHeadingDeclarationPattern())) ids.push(m[1]);
|
|
174
|
+
}
|
|
175
|
+
return ids;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/**
|
|
179
|
+
* Ids declared in `specs/` on any ref this repository holds — local branches
|
|
180
|
+
* and remote-tracking branches both.
|
|
181
|
+
*
|
|
182
|
+
* One `git grep` over every ref at once rather than a checkout each: measured
|
|
183
|
+
* at 0.17s over 1087 refs, against minutes for the obvious implementation.
|
|
184
|
+
*/
|
|
185
|
+
function idsInRefs(root: string): { ids: string[]; refs: number; failure: string | null } {
|
|
186
|
+
let refList: string;
|
|
187
|
+
try {
|
|
188
|
+
refList = git(root, ["for-each-ref", "--format=%(refname)", "refs/heads", "refs/remotes"]);
|
|
189
|
+
} catch (err) {
|
|
190
|
+
return { ids: [], refs: 0, failure: (err as Error).message.split("\n")[0] };
|
|
191
|
+
}
|
|
192
|
+
const refs = refList.split("\n").filter(r => r.trim() !== "");
|
|
193
|
+
if (refs.length === 0) return { ids: [], refs: 0, failure: null };
|
|
194
|
+
|
|
195
|
+
const ids: string[] = [];
|
|
196
|
+
// Batched: a ref list this long overruns the argument limit in one call.
|
|
197
|
+
for (let i = 0; i < refs.length; i += 100) {
|
|
198
|
+
let out: string;
|
|
199
|
+
try {
|
|
200
|
+
out = git(root, [
|
|
201
|
+
"grep",
|
|
202
|
+
"-h",
|
|
203
|
+
"-E",
|
|
204
|
+
// Declaration-shaped lines only — a checkbox or a heading. Every
|
|
205
|
+
// mention would be correct and is ~30x the output, which is how the
|
|
206
|
+
// first version hit the buffer limit.
|
|
207
|
+
"^(- \\[.\\] |#+ )SC-[A-Z]?[0-9]+",
|
|
208
|
+
...refs.slice(i, i + 100),
|
|
209
|
+
"--",
|
|
210
|
+
"specs/*.md",
|
|
211
|
+
]);
|
|
212
|
+
} catch (err) {
|
|
213
|
+
// git grep exits 1 when nothing matched, which is a real answer and not
|
|
214
|
+
// a failure. Anything else is a failure, and the caller must hear it.
|
|
215
|
+
const status = (err as { status?: number }).status;
|
|
216
|
+
if (status === 1) continue;
|
|
217
|
+
return { ids, refs: refs.length, failure: (err as Error).message.split("\n")[0] };
|
|
218
|
+
}
|
|
219
|
+
for (const m of out.matchAll(scDeclarationPattern())) ids.push(m[2]);
|
|
220
|
+
for (const m of out.matchAll(scHeadingDeclarationPattern())) ids.push(m[1]);
|
|
221
|
+
}
|
|
222
|
+
return { ids, refs: refs.length, failure: null };
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* Every SC id this machine can see, with an account of where it looked.
|
|
227
|
+
*
|
|
228
|
+
* Fixture ids — the reserved 9000s — are dropped. The reservation exists so a
|
|
229
|
+
* fixture can spell an id without claiming it, and counting one as taken
|
|
230
|
+
* would push every future criterion past 9000 and destroy the reservation it
|
|
231
|
+
* was built on. That is `nextSCNumber`'s rule for `spelledInSource`, applied
|
|
232
|
+
* at the same width.
|
|
233
|
+
*/
|
|
234
|
+
export function readScNamespace(root: string): ScNamespaceReading {
|
|
235
|
+
const ids = new Map<string, string[]>();
|
|
236
|
+
const sources: SourceReading[] = [];
|
|
237
|
+
const unmeasured: string[] = [];
|
|
238
|
+
|
|
239
|
+
const record = (id: string, label: string): void => {
|
|
240
|
+
if (isFixtureScId(id)) return;
|
|
241
|
+
const seen = ids.get(id) ?? [];
|
|
242
|
+
if (!seen.includes(label)) seen.push(label);
|
|
243
|
+
ids.set(id, seen);
|
|
244
|
+
};
|
|
245
|
+
|
|
246
|
+
const { paths, failure } = siblingWorktrees(root);
|
|
247
|
+
if (failure !== null) {
|
|
248
|
+
sources.push({ label: "git worktree list", kind: "worktree", status: "skipped", reason: failure, found: 0 });
|
|
249
|
+
unmeasured.push(`sibling worktrees could not be enumerated: ${failure}`);
|
|
250
|
+
}
|
|
251
|
+
for (const path of paths) {
|
|
252
|
+
const specsDir = join(path, "specs");
|
|
253
|
+
let usable = false;
|
|
254
|
+
try {
|
|
255
|
+
usable = existsSync(specsDir) && statSync(specsDir).isDirectory();
|
|
256
|
+
} catch {
|
|
257
|
+
usable = false;
|
|
258
|
+
}
|
|
259
|
+
if (!usable) {
|
|
260
|
+
// A worktree git lists but whose tree is gone, or which predates
|
|
261
|
+
// specs/. Recorded rather than dropped: a skipped source is the thing
|
|
262
|
+
// that makes the count below a floor.
|
|
263
|
+
sources.push({ label: path, kind: "worktree", status: "skipped", reason: "no readable specs/ directory", found: 0 });
|
|
264
|
+
unmeasured.push(`${path}: no readable specs/ directory`);
|
|
265
|
+
continue;
|
|
266
|
+
}
|
|
267
|
+
let found: string[];
|
|
268
|
+
try {
|
|
269
|
+
found = idsInSpecsDir(specsDir);
|
|
270
|
+
} catch (err) {
|
|
271
|
+
sources.push({ label: path, kind: "worktree", status: "skipped", reason: (err as Error).message, found: 0 });
|
|
272
|
+
unmeasured.push(`${path}: ${(err as Error).message}`);
|
|
273
|
+
continue;
|
|
274
|
+
}
|
|
275
|
+
for (const id of found) record(id, path);
|
|
276
|
+
sources.push({ label: path, kind: "worktree", status: "read", found: new Set(found).size });
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
const refs = idsInRefs(root);
|
|
280
|
+
if (refs.failure !== null) {
|
|
281
|
+
sources.push({ label: "refs", kind: "refs", status: "skipped", reason: refs.failure, found: 0 });
|
|
282
|
+
unmeasured.push(`branch refs could not be read: ${refs.failure}`);
|
|
283
|
+
} else {
|
|
284
|
+
for (const id of refs.ids) record(id, "refs");
|
|
285
|
+
sources.push({
|
|
286
|
+
label: `refs (${refs.refs} local and remote-tracking)`,
|
|
287
|
+
kind: "refs",
|
|
288
|
+
status: "read",
|
|
289
|
+
found: new Set(refs.ids).size,
|
|
290
|
+
});
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
// Always present, and not boilerplate: it is the one half of the namespace
|
|
294
|
+
// no process on this machine can reach, and an allocator that did not say
|
|
295
|
+
// so would be claiming a guarantee it cannot give.
|
|
296
|
+
unmeasured.push(
|
|
297
|
+
"ids allocated in a clone on another machine, and not yet pushed or fetched here, are not visible to any of the above",
|
|
298
|
+
);
|
|
299
|
+
|
|
300
|
+
return { ids, sources, unmeasured };
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/**
|
|
304
|
+
* A one-line account of what a reading covered, for a CLI to print.
|
|
305
|
+
*
|
|
306
|
+
* It NAMES the legs rather than counting them (#593). A count says how many
|
|
307
|
+
* sources answered; it cannot say which width went unasked, and a number
|
|
308
|
+
* allocated without consulting the spec registry printed the same
|
|
309
|
+
* "2 source(s)" as one that had. This is the single binding every caller
|
|
310
|
+
* prints through, so there is no second renderer to drift from it.
|
|
311
|
+
*/
|
|
312
|
+
export function describeReading(reading: ScNamespaceReading): string {
|
|
313
|
+
const read = reading.sources.filter(s => s.status === "read");
|
|
314
|
+
const skipped = reading.sources.filter(s => s.status === "skipped");
|
|
315
|
+
const legs = [...new Set(reading.sources.map(s => s.kind))];
|
|
316
|
+
const parts = [
|
|
317
|
+
`${reading.ids.size} ids across ${read.length} source(s)`,
|
|
318
|
+
`legs: ${legs.join(", ")}`,
|
|
319
|
+
skipped.length > 0 ? `${skipped.length} skipped` : null,
|
|
320
|
+
`${reading.unmeasured.length} unmeasured`,
|
|
321
|
+
].filter(Boolean);
|
|
322
|
+
return parts.join(", ");
|
|
323
|
+
}
|