rungate 0.3.0 → 0.4.1
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/ac-quality.ts +119 -0
- package/lib/brief-precedence.ts +114 -0
- package/lib/ci-checkout.ts +27 -1
- package/lib/compliance-backfill.ts +16 -4
- package/lib/compliance-report.ts +109 -8
- package/lib/config-loader.ts +129 -5
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +520 -27
- package/lib/context-docs.ts +182 -0
- package/lib/create-brief.ts +22 -17
- package/lib/create-sc.ts +55 -33
- package/lib/decomposition-waves.ts +197 -0
- package/lib/doc-scan-targets.ts +435 -0
- package/lib/gate-check-audit.ts +190 -0
- package/lib/generators/agents-md.ts +10 -5
- package/lib/issue-extraction.ts +368 -0
- package/lib/organize.ts +129 -40
- package/lib/package-closure.ts +111 -0
- package/lib/phase2-decomposition.ts +270 -0
- package/lib/prior-branch.ts +24 -1
- package/lib/project-aliases.ts +100 -0
- package/lib/prove-label-gate.ts +93 -0
- package/lib/release-preflight.ts +225 -15
- package/lib/rungate-schema.ts +36 -2
- package/lib/sc-cover.ts +92 -1
- package/lib/sc-ids.ts +151 -0
- package/lib/scaffold/pre-push-hook.ts +165 -0
- package/lib/scaffold/rehearsal.ts +330 -0
- package/lib/scaffold/steps.ts +175 -122
- package/lib/scaffold/write-steps.ts +167 -0
- package/lib/scope-denylist.ts +258 -0
- package/lib/scratch-cleanup.ts +198 -0
- package/lib/scratch-roots.ts +94 -0
- package/lib/task-completion-checks.ts +50 -3
- package/lib/typescript-project.ts +233 -0
- package/lib/validators/spec-validators.ts +23 -34
- package/lib/verified-push.ts +179 -2
- package/lib/workflow-security.ts +51 -7
- package/lib/worktree-cleanup.ts +318 -20
- package/lib/worktree-repo.ts +465 -0
- package/package.json +8 -2
- package/scripts/audit-specs.ts +134 -37
- package/scripts/audit-transcript.ts +259 -0
- package/scripts/create-sc.ts +15 -1
- package/scripts/detect-sc-drift.ts +200 -0
- package/scripts/extract-constraints.ts +16 -36
- package/scripts/scaffold-project.ts +26 -136
- package/scripts/split-spec.ts +315 -0
- package/scripts/sync-sc-status.ts +751 -0
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Files a goal put out of bounds, and the plans that claimed them anyway (#306).
|
|
3
|
+
*
|
|
4
|
+
* ## What happened
|
|
5
|
+
*
|
|
6
|
+
* #274 attempt 4 (`wf_b3714a40-bb7`). The goal said, under a heading in
|
|
7
|
+
* capitals, "ALSO DO NOT FIX, ALREADY FILED: #295 … leave it there". The
|
|
8
|
+
* `to-issues` decomposer then emitted a sub-issue whose `filesToModify` was
|
|
9
|
+
* `gates/schema.ts`, `lib/evidence-prevalidator.ts`,
|
|
10
|
+
* `gates/SCHEMA-GUIDE.md` — the three files you would touch to fix #295, and
|
|
11
|
+
* nothing to do with #274. The agent did what its file list permitted, and
|
|
12
|
+
* the run refused on its own contradiction: one sub-issue both documented the
|
|
13
|
+
* defect and removed it.
|
|
14
|
+
*
|
|
15
|
+
* The attribution is the decomposer's, not the agent's. The collection guard
|
|
16
|
+
* (#178, SC-413) refuses any file no sub-issue claimed, and it did not refuse
|
|
17
|
+
* these — so they were in the plan. An agent handed `gates/schema.ts` and a
|
|
18
|
+
* defect description has been told, by the strongest signal in the system,
|
|
19
|
+
* that the file is in scope.
|
|
20
|
+
*
|
|
21
|
+
* ## One thing #306 got wrong, corrected here
|
|
22
|
+
*
|
|
23
|
+
* The issue proposes "the goal already names them; the decomposer could be
|
|
24
|
+
* given an explicit deny-list". **The goal did not name them.** Re-read the
|
|
25
|
+
* quoted prohibition: it names an ISSUE (`#295`) and three code symbols
|
|
26
|
+
* (`prevalidationViolations`, `reading.broken`, `acs[].status`). Not one file
|
|
27
|
+
* path. The paths came from `discovery.filesToModify`, which
|
|
28
|
+
* `workflows/ship.js:1952` hands to the decomposer verbatim as "Files to
|
|
29
|
+
* modify".
|
|
30
|
+
*
|
|
31
|
+
* That changes the fix in a way worth stating, because a deny-list built on
|
|
32
|
+
* the issue's premise would have returned `[]` for the very run that
|
|
33
|
+
* motivated it and passed — the decorative check
|
|
34
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` is about, shipped as its own
|
|
35
|
+
* remedy. So this module has two outputs, not one:
|
|
36
|
+
*
|
|
37
|
+
* - `deniedFiles` — paths the prohibition actually named, which can be
|
|
38
|
+
* enforced.
|
|
39
|
+
* - `unresolvedProhibitions` — prohibitions that named an issue and no file,
|
|
40
|
+
* which CANNOT be enforced and are reported rather than counted as clean.
|
|
41
|
+
* #274's own goal is this case. An empty deny-list and an unenforceable one
|
|
42
|
+
* look identical from the outside, and conflating them is the whole bug.
|
|
43
|
+
*/
|
|
44
|
+
|
|
45
|
+
/** A marked region of goal text and what could be extracted from it. */
|
|
46
|
+
export interface Prohibition {
|
|
47
|
+
/** The text of the marked paragraph. */
|
|
48
|
+
text: string;
|
|
49
|
+
/** Repo-relative paths named inside it. */
|
|
50
|
+
files: string[];
|
|
51
|
+
/** Issue numbers named inside it, as `#295`. */
|
|
52
|
+
issues: string[];
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Line markers that put the rest of a paragraph out of bounds.
|
|
57
|
+
*
|
|
58
|
+
* Deliberately short and literal. A wider list reads ordinary prose as a
|
|
59
|
+
* prohibition and starts denying files the run needs, which fails a correct
|
|
60
|
+
* plan — and a guard that fires on correct work is removed within a week.
|
|
61
|
+
*/
|
|
62
|
+
const MARKERS = [
|
|
63
|
+
/\bdo\s+not\s+fix\b/i,
|
|
64
|
+
/\bdo\s+not\s+touch\b/i,
|
|
65
|
+
/\bdo\s+not\s+modify\b/i,
|
|
66
|
+
/\bout\s+of\s+scope\b/i,
|
|
67
|
+
/\bnot\s+in\s+scope\b/i,
|
|
68
|
+
/\balready\s+filed\b/i,
|
|
69
|
+
];
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* A source path: an optional directory prefix and a KNOWN EXTENSION.
|
|
73
|
+
*
|
|
74
|
+
* The extension is what does the discriminating, and that is worth stating
|
|
75
|
+
* because the first draft of this file claimed the `/` did. It does not.
|
|
76
|
+
* `reading.broken` and `acs[].status` — both in #274's prohibition, both code
|
|
77
|
+
* expressions — are excluded because `.broken` and `.status` are not
|
|
78
|
+
* extensions, not because they lack a separator. Mutating the `/` from
|
|
79
|
+
* required to optional scored **zero red** against the cases written to
|
|
80
|
+
* defend it, which is how the claim was caught.
|
|
81
|
+
*
|
|
82
|
+
* The separator is optional on purpose, once it stopped being load-bearing:
|
|
83
|
+
* requiring it silently misses every root-level file a goal might name —
|
|
84
|
+
* `package.json`, `AGENTS.md`, `CODE-MAP.md` — which is a false negative in
|
|
85
|
+
* exactly the common case. How a bare name matches a plan entry is
|
|
86
|
+
* `matchesDenied` below, and it is not the same rule as for a full path.
|
|
87
|
+
*/
|
|
88
|
+
const PATH = /\b([A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*\.(?:ts|tsx|js|jsx|md|json|ya?ml|sh))\b/g;
|
|
89
|
+
|
|
90
|
+
const ISSUE_REF = /#(\d+)\b/g;
|
|
91
|
+
|
|
92
|
+
/** Paths named in a span of text, deduplicated, in first-seen order. */
|
|
93
|
+
export function pathsNamedIn(text: string): string[] {
|
|
94
|
+
return [...new Set([...text.matchAll(PATH)].map(m => m[1]))];
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Split goal text into the paragraphs a marker puts out of bounds.
|
|
99
|
+
*
|
|
100
|
+
* A paragraph, not a line: #274's prohibition is one bolded lead-in followed
|
|
101
|
+
* by two sentences, and a line-scoped reader would see the marker and stop
|
|
102
|
+
* before the content. A paragraph, not the rest of the document: a marker
|
|
103
|
+
* near the top would otherwise deny the entire goal.
|
|
104
|
+
*/
|
|
105
|
+
export function prohibitions(goalText: string): Prohibition[] {
|
|
106
|
+
const out: Prohibition[] = [];
|
|
107
|
+
for (const para of String(goalText ?? "").split(/\n\s*\n/)) {
|
|
108
|
+
if (!MARKERS.some(m => m.test(para))) continue;
|
|
109
|
+
out.push({
|
|
110
|
+
text: para.trim(),
|
|
111
|
+
files: pathsNamedIn(para),
|
|
112
|
+
issues: [...new Set([...para.matchAll(ISSUE_REF)].map(m => `#${m[1]}`))],
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
return out;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Every file the goal put out of bounds.
|
|
120
|
+
*
|
|
121
|
+
* `scopeOut` entries count in full — that field exists to say what is out of
|
|
122
|
+
* scope, so it needs no marker. Until now nothing read it at all: it was
|
|
123
|
+
* required by the discovery schema, appended to in one place, and consulted
|
|
124
|
+
* by nothing, which is its own small version of this bug.
|
|
125
|
+
*/
|
|
126
|
+
export function deniedFiles(goalText: string, scopeOut: readonly string[] = []): string[] {
|
|
127
|
+
const fromGoal = prohibitions(goalText).flatMap(p => p.files);
|
|
128
|
+
const fromScopeOut = scopeOut.flatMap(s => pathsNamedIn(String(s ?? "")));
|
|
129
|
+
return [...new Set([...fromGoal, ...fromScopeOut])];
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* Prohibitions that name an issue and no file (#306).
|
|
134
|
+
*
|
|
135
|
+
* These are the ones the deny-list cannot act on, and reporting them is the
|
|
136
|
+
* point. "Nothing was denied because the goal named nothing" and "nothing was
|
|
137
|
+
* denied because the goal named no files" are the same empty list, and only
|
|
138
|
+
* the first is a clean run.
|
|
139
|
+
*/
|
|
140
|
+
export function unresolvedProhibitions(goalText: string): Prohibition[] {
|
|
141
|
+
return prohibitions(goalText).filter(p => p.files.length === 0 && p.issues.length > 0);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** A plan item that claims files. Shaped to match a sub-issue or discovery. */
|
|
145
|
+
export interface FileClaimant {
|
|
146
|
+
title?: string;
|
|
147
|
+
filesToModify?: readonly string[];
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* One spelling per path, so a guard cannot be stepped around by rewriting it.
|
|
152
|
+
*
|
|
153
|
+
* A string comparison is only as good as its normalisation, and `./a/b.ts`,
|
|
154
|
+
* `a//b.ts`, `a/./b.ts` and `a/c/../b.ts` are four spellings of one file that
|
|
155
|
+
* an `===` reads as four different ones. The whole value of this module is a
|
|
156
|
+
* comparison, so an un-normalised one is a guard with a documented bypass —
|
|
157
|
+
* "a detector narrower than what it detects", third shape in
|
|
158
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
159
|
+
*
|
|
160
|
+
* A leading `..` is kept rather than resolved away: it escapes the repo root
|
|
161
|
+
* and there is nothing above it to collapse into, so dropping it would make
|
|
162
|
+
* `../secrets.ts` normalise to `secrets.ts` and match a deny entry that never
|
|
163
|
+
* meant it. Raised by the commit security review on this change.
|
|
164
|
+
*/
|
|
165
|
+
export function normalisePath(p: string): string {
|
|
166
|
+
const raw = String(p ?? "").trim().replace(/\\/g, "/");
|
|
167
|
+
const out: string[] = [];
|
|
168
|
+
for (const seg of raw.split("/")) {
|
|
169
|
+
if (seg === "" || seg === ".") continue;
|
|
170
|
+
if (seg === ".." && out.length > 0 && out.at(-1) !== "..") out.pop();
|
|
171
|
+
else out.push(seg);
|
|
172
|
+
}
|
|
173
|
+
return out.join("/");
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Does a plan's file entry fall under a denied entry?
|
|
178
|
+
*
|
|
179
|
+
* Two rules, because a goal names files two ways:
|
|
180
|
+
*
|
|
181
|
+
* - **A denied entry WITH a separator matches exactly**, after normalisation.
|
|
182
|
+
* A suffix match would read `test/gates/schema.ts` as `gates/schema.ts` and
|
|
183
|
+
* deny a file the prohibition never mentioned.
|
|
184
|
+
* - **A denied entry with NO separator matches by basename.** "Do not touch
|
|
185
|
+
* package.json" has to reach `package.json`, and "do not touch
|
|
186
|
+
* HARNESS-STANDARD.md" has to reach `specs/HARNESS-STANDARD.md` — a goal
|
|
187
|
+
* author naming a bare file means the file, wherever it lives. Requiring
|
|
188
|
+
* the path instead would make the common phrasing silently do nothing,
|
|
189
|
+
* which is this issue's own defect one level down.
|
|
190
|
+
*
|
|
191
|
+
* The basename arm compares the last segment rather than testing `endsWith`,
|
|
192
|
+
* because `endsWith("/package.json")` is satisfied by nothing a normalised
|
|
193
|
+
* path can spell differently but the segment comparison says what it means.
|
|
194
|
+
*/
|
|
195
|
+
export function matchesDenied(planFile: string, deniedEntry: string): boolean {
|
|
196
|
+
const plan = normalisePath(planFile);
|
|
197
|
+
const denied = normalisePath(deniedEntry);
|
|
198
|
+
if (denied === "" || plan === "") return false;
|
|
199
|
+
if (denied.includes("/")) return plan === denied;
|
|
200
|
+
return plan === denied || plan.split("/").at(-1) === denied;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** Violations, one line each. Empty allows. */
|
|
204
|
+
export function denylistViolations(
|
|
205
|
+
claimants: readonly FileClaimant[],
|
|
206
|
+
denied: readonly string[],
|
|
207
|
+
): string[] {
|
|
208
|
+
const out: string[] = [];
|
|
209
|
+
for (const [i, c] of claimants.entries()) {
|
|
210
|
+
for (const f of c.filesToModify ?? []) {
|
|
211
|
+
if (!denied.some(d => matchesDenied(f, d))) continue;
|
|
212
|
+
out.push(
|
|
213
|
+
`${c.title ? `"${c.title}"` : `plan item ${i + 1}`} claims ${f}, which the goal ` +
|
|
214
|
+
`put out of scope. An agent handed a file is an agent told the file is in ` +
|
|
215
|
+
`scope (#306).`,
|
|
216
|
+
);
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
return out;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Did the deny-list eat the entire plan? (commit security review, #306)
|
|
224
|
+
*
|
|
225
|
+
* Two findings on this change were about the same hazard from opposite
|
|
226
|
+
* sides. The goal text is attacker-influenceable — issue bodies are — and
|
|
227
|
+
* nothing here validates it. What limits the damage is direction: a
|
|
228
|
+
* deny-list only ever NARROWS what an agent may write, so a hostile goal can
|
|
229
|
+
* deny progress but cannot grant access. That is the safe direction, and it
|
|
230
|
+
* is why this is a report rather than a refusal.
|
|
231
|
+
*
|
|
232
|
+
* The one outcome that is NOT safe is silence. If every file the run was
|
|
233
|
+
* going to touch is denied, stripping leaves an empty plan, and an empty
|
|
234
|
+
* plan is indistinguishable from a run with nothing to do — work refused,
|
|
235
|
+
* reported as work completed. That is the fail-open, and it is the shape the
|
|
236
|
+
* rest of this issue is about, so it gets a message rather than an empty
|
|
237
|
+
* array.
|
|
238
|
+
*/
|
|
239
|
+
export function scopeContradiction(
|
|
240
|
+
files: readonly string[],
|
|
241
|
+
denied: readonly string[],
|
|
242
|
+
): string | null {
|
|
243
|
+
if (files.length === 0 || denied.length === 0) return null;
|
|
244
|
+
if (withoutDenied(files, denied).length > 0) return null;
|
|
245
|
+
return (
|
|
246
|
+
`every file the run planned to touch is out of scope (${files.join(", ")} vs ` +
|
|
247
|
+
`denied ${denied.join(", ")}). An empty plan looks exactly like a run with ` +
|
|
248
|
+
`nothing to do, so this is reported rather than stripped in silence (#306).`
|
|
249
|
+
);
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** The denied files stripped out, order preserved. Same rule as above. */
|
|
253
|
+
export function withoutDenied(
|
|
254
|
+
files: readonly string[],
|
|
255
|
+
denied: readonly string[],
|
|
256
|
+
): string[] {
|
|
257
|
+
return files.filter(f => !denied.some(d => matchesDenied(f, d)));
|
|
258
|
+
}
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Sweep scratch directories the test suite leaked into the repo root (#437).
|
|
3
|
+
*
|
|
4
|
+
* `test/tree-under-test.test.ts` and four others plant their fixtures with
|
|
5
|
+
* `mkdtempSync(join(REPO_ROOT, "<prefix>"))`. They all have correct `afterAll`
|
|
6
|
+
* cleanup; that is the point. The directory is created when bun *imports* the
|
|
7
|
+
* file, before any lifecycle hook can run and before any hook is guaranteed to
|
|
8
|
+
* run at all, so a suite that is interrupted, killed, or that throws during
|
|
9
|
+
* collection leaves one behind. 34 of them had accumulated when Jason noticed,
|
|
10
|
+
* all but one 0 bytes — created at import, never populated, never cleaned.
|
|
11
|
+
*
|
|
12
|
+
* #437 moves creation into `beforeAll`, which stops new ones appearing. This
|
|
13
|
+
* is the other half: the ones already there, and the ones a kill during
|
|
14
|
+
* `beforeAll` can still produce.
|
|
15
|
+
*
|
|
16
|
+
* Same family as #68 (39 stale worktrees) and #436 (a worktree git had pruned
|
|
17
|
+
* out from under): a resource created by tooling that only gets cleaned on the
|
|
18
|
+
* happy path.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
import { readdirSync, statSync, rmSync } from "fs";
|
|
22
|
+
import { join } from "path";
|
|
23
|
+
import { readFileSync } from "fs";
|
|
24
|
+
import { uniqueScratchPrefixes } from "./scratch-roots";
|
|
25
|
+
|
|
26
|
+
export interface ScratchCleanupResult {
|
|
27
|
+
/** Directories removed, named relative to the repo root. */
|
|
28
|
+
removed: string[];
|
|
29
|
+
/** Matched a prefix but was too young to be certain it is not in use. */
|
|
30
|
+
kept: string[];
|
|
31
|
+
/** Did not match any derived prefix — the overwhelming majority. */
|
|
32
|
+
refused: string[];
|
|
33
|
+
errors: string[];
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export interface ScratchCleanupOptions {
|
|
37
|
+
repoRoot: string;
|
|
38
|
+
/**
|
|
39
|
+
* How old a scratch directory must be before it is swept. Default one hour.
|
|
40
|
+
*
|
|
41
|
+
* NOT belt-and-braces. This runs at SessionStart, and another session may be
|
|
42
|
+
* three minutes into a suite whose scratch directory is live. The suite that
|
|
43
|
+
* created it cannot defend it — the directory is anonymous and holds no lock
|
|
44
|
+
* — so age is the only signal available, and the direction to be wrong in is
|
|
45
|
+
* leaving litter rather than deleting a running suite's fixtures.
|
|
46
|
+
*/
|
|
47
|
+
maxAgeMs?: number;
|
|
48
|
+
/** Report what would go without removing anything. */
|
|
49
|
+
dryRun?: boolean;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const ONE_HOUR_MS = 60 * 60 * 1000;
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* The file whose "prefixes" are test fixtures rather than real scratch roots.
|
|
56
|
+
*
|
|
57
|
+
* `test/scratch-paths-unique.test.ts` carries `mkdtempSync(join(ROOT, ".x-"))`
|
|
58
|
+
* as a STRING LITERAL, because that is the only way to prove its detector
|
|
59
|
+
* still fires. Stripping comments does not remove it. Deriving from it would
|
|
60
|
+
* put `.x-` into a deletion allowlist on the strength of a test fixture, which
|
|
61
|
+
* is the self-reference trap with a recursive delete on the end of it.
|
|
62
|
+
*/
|
|
63
|
+
const FIXTURE_FILE = "scratch-paths-unique.test.ts";
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Every prefix any suite in `test/` plants under the repo root.
|
|
67
|
+
*
|
|
68
|
+
* Derived, never listed. A hand-maintained list is a second place to forget,
|
|
69
|
+
* and forgetting there means a new suite's leak accumulates silently — which
|
|
70
|
+
* is the defect this module exists for, one level up.
|
|
71
|
+
*/
|
|
72
|
+
export function scratchPrefixes(repoRoot: string): string[] {
|
|
73
|
+
const testDir = join(repoRoot, "test");
|
|
74
|
+
const out: string[] = [];
|
|
75
|
+
let entries: string[];
|
|
76
|
+
try {
|
|
77
|
+
entries = readdirSync(testDir);
|
|
78
|
+
} catch {
|
|
79
|
+
return out; // no test directory — nothing plants anything
|
|
80
|
+
}
|
|
81
|
+
for (const f of entries) {
|
|
82
|
+
if (!f.endsWith(".ts")) continue;
|
|
83
|
+
if (f === FIXTURE_FILE) continue;
|
|
84
|
+
let src: string;
|
|
85
|
+
try {
|
|
86
|
+
src = readFileSync(join(testDir, f), "utf-8");
|
|
87
|
+
} catch {
|
|
88
|
+
continue;
|
|
89
|
+
}
|
|
90
|
+
for (const p of uniqueScratchPrefixes(src)) if (!out.includes(p)) out.push(p);
|
|
91
|
+
}
|
|
92
|
+
return out.sort();
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Exactly what `mkdtempSync` appends: six characters from this alphabet.
|
|
97
|
+
*
|
|
98
|
+
* Measured over 200 calls rather than read off the documentation — the
|
|
99
|
+
* lengths set came back `[6]` and the alphabet came back `[A-Za-z0-9]`.
|
|
100
|
+
*/
|
|
101
|
+
const MKDTEMP_SUFFIX = "[A-Za-z0-9]{6}";
|
|
102
|
+
|
|
103
|
+
/** A prefix is data; it reaches a RegExp, so it is escaped rather than trusted. */
|
|
104
|
+
function escapeRegex(s: string): string {
|
|
105
|
+
return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Whether `entry` is a name `mkdtempSync` could have produced from `prefixes`.
|
|
110
|
+
*
|
|
111
|
+
* The prefix list is a deletion allowlist, so this is written as one, and the
|
|
112
|
+
* first version was written as a weaker one. It asked only that the entry
|
|
113
|
+
* start with a prefix and be longer — and since the prefixes are DERIVED from
|
|
114
|
+
* `test/*.ts`, a suite writing `mkdtempSync(join(REPO_ROOT, ".c"))` would have
|
|
115
|
+
* armed a SessionStart hook to recursively delete `.claude/`.
|
|
116
|
+
* `isScratchEntry(".claude", [".c"])` returned true; it was found by a
|
|
117
|
+
* security review of the first push and confirmed by running it (BUG-437-A).
|
|
118
|
+
*
|
|
119
|
+
* The paths were never the hole — the sweeper builds those itself. The
|
|
120
|
+
* ALLOWLIST was, and an allowlist derived from file content is content
|
|
121
|
+
* steering a recursive delete just as surely as a path would be.
|
|
122
|
+
*
|
|
123
|
+
* So the test is the full shape, not a prefix test: the entry must be a
|
|
124
|
+
* prefix followed by EXACTLY the suffix `mkdtempSync` produces. A bare prefix
|
|
125
|
+
* with nothing after it is a directory someone made deliberately, and
|
|
126
|
+
* anything else is not a name this repo's tooling can have written.
|
|
127
|
+
*
|
|
128
|
+
* ONE anchored match, not a `startsWith` beside a slice at `p.length`. Those
|
|
129
|
+
* two are behaviourally identical on every input — relaxing `startsWith` to
|
|
130
|
+
* `includes` measured **0 of 24**, because the fixed offset refuses whatever
|
|
131
|
+
* the substring match would have let through. Two deciders that agree, with
|
|
132
|
+
* the delete still on the end of them. See
|
|
133
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
134
|
+
*/
|
|
135
|
+
export function isScratchEntry(entry: string, prefixes: string[]): boolean {
|
|
136
|
+
return prefixes.some(p =>
|
|
137
|
+
p.length > 1 && new RegExp(`^${escapeRegex(p)}${MKDTEMP_SUFFIX}$`).test(entry));
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* Remove leaked scratch directories from the repo root.
|
|
142
|
+
*
|
|
143
|
+
* Every path this deletes is one THIS function built, from
|
|
144
|
+
* `join(opts.repoRoot, entry)` where `entry` came from reading that same
|
|
145
|
+
* directory. No absolute path from any other source — not a config, not a
|
|
146
|
+
* prefix, not a `.git` file — can reach the `rmSync`. #436 learned that one
|
|
147
|
+
* the expensive way: content must never steer a recursive delete.
|
|
148
|
+
*/
|
|
149
|
+
export function cleanupScratchDirs(opts: ScratchCleanupOptions): ScratchCleanupResult {
|
|
150
|
+
const result: ScratchCleanupResult = { removed: [], kept: [], refused: [], errors: [] };
|
|
151
|
+
const maxAgeMs = opts.maxAgeMs ?? ONE_HOUR_MS;
|
|
152
|
+
const prefixes = scratchPrefixes(opts.repoRoot);
|
|
153
|
+
|
|
154
|
+
let entries: string[];
|
|
155
|
+
try {
|
|
156
|
+
entries = readdirSync(opts.repoRoot);
|
|
157
|
+
} catch (err) {
|
|
158
|
+
result.errors.push(`Failed to read ${opts.repoRoot}: ${err}`);
|
|
159
|
+
return result;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
for (const entry of entries) {
|
|
163
|
+
if (!isScratchEntry(entry, prefixes)) {
|
|
164
|
+
result.refused.push(entry);
|
|
165
|
+
continue;
|
|
166
|
+
}
|
|
167
|
+
const path = join(opts.repoRoot, entry);
|
|
168
|
+
let age: number;
|
|
169
|
+
try {
|
|
170
|
+
const stat = statSync(path);
|
|
171
|
+
if (!stat.isDirectory()) {
|
|
172
|
+
result.refused.push(entry);
|
|
173
|
+
continue;
|
|
174
|
+
}
|
|
175
|
+
age = Date.now() - stat.mtimeMs;
|
|
176
|
+
} catch (err) {
|
|
177
|
+
result.errors.push(`Failed to stat ${entry}: ${err}`);
|
|
178
|
+
continue;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
if (age < maxAgeMs) {
|
|
182
|
+
result.kept.push(`${entry} (${Math.round(age / 1000)}s old — a suite may still be using it)`);
|
|
183
|
+
continue;
|
|
184
|
+
}
|
|
185
|
+
if (opts.dryRun) {
|
|
186
|
+
result.removed.push(`${entry} (dry run)`);
|
|
187
|
+
continue;
|
|
188
|
+
}
|
|
189
|
+
try {
|
|
190
|
+
rmSync(path, { recursive: true, force: true });
|
|
191
|
+
result.removed.push(entry);
|
|
192
|
+
} catch (err) {
|
|
193
|
+
result.errors.push(`Failed to remove ${entry}: ${err}`);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
return result;
|
|
198
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The single owner of "what does a scratch root in this repo look like" (#437).
|
|
3
|
+
*
|
|
4
|
+
* Two questions are asked about the same source text, and they are asked from
|
|
5
|
+
* two different places:
|
|
6
|
+
*
|
|
7
|
+
* - `test/scratch-paths-unique.test.ts` asks which scratch roots are FIXED,
|
|
8
|
+
* because a fixed path under the shared checkout is a shared mutable
|
|
9
|
+
* resource (#323 SC-6).
|
|
10
|
+
* - `lib/scratch-cleanup.ts` asks which PREFIXES the unique ones use,
|
|
11
|
+
* because a sweeper needs to know what it is allowed to delete.
|
|
12
|
+
*
|
|
13
|
+
* They are the same parse. Two copies of it would be two deciders that agree —
|
|
14
|
+
* the fourth shape in `.claude/rules/checks-must-be-able-to-fail.md` — and
|
|
15
|
+
* worse than usual here, because the second decider's output is a deletion
|
|
16
|
+
* allowlist. A parser that quietly stopped seeing a prefix would not go red;
|
|
17
|
+
* it would stop sweeping, which is indistinguishable from nothing having
|
|
18
|
+
* leaked.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
import { stripJsComments } from "./strip-js-comments";
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Identifiers bound to the repository root, per file.
|
|
25
|
+
*
|
|
26
|
+
* `join(tmpDir, ".claude")` is a fixed name under an ALREADY-UNIQUE root —
|
|
27
|
+
* the suffix is on the parent, which is just as good. Only a path rooted at
|
|
28
|
+
* the shared checkout can collide, so the root is the thing to look at.
|
|
29
|
+
*/
|
|
30
|
+
export function repoRootIdents(src: string): Set<string> {
|
|
31
|
+
const idents = new Set<string>();
|
|
32
|
+
for (const m of src.matchAll(/(?:const|let|var)?\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([^;\n]+)/g)) {
|
|
33
|
+
if (/import\.meta\.dir|process\.cwd\(\)/.test(m[2]!)) idents.add(m[1]!);
|
|
34
|
+
}
|
|
35
|
+
return idents;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* The declaration forms a scratch root can arrive in.
|
|
40
|
+
*
|
|
41
|
+
* `const` is matched optionally, and that is #437's doing rather than
|
|
42
|
+
* tidiness. Moving creation out of module scope means writing
|
|
43
|
+
* `let SCRATCH = ""` at the top and `SCRATCH = mkdtempSync(...)` inside
|
|
44
|
+
* `beforeAll`, and a `const`-only pattern stops seeing both forms at once —
|
|
45
|
+
* so the fix for the leak would have opened a hole in the guard against
|
|
46
|
+
* fixed paths. Measured: it is 3 red without the relaxation.
|
|
47
|
+
*/
|
|
48
|
+
const DECL = /(?:const|let|var\s+)?\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(mkdtempSync\s*\(\s*)?join\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,\s*"(\.[^"]*)"/g;
|
|
49
|
+
|
|
50
|
+
/** Navigation, not a scratch name. */
|
|
51
|
+
function isNavigation(literal: string): boolean {
|
|
52
|
+
return literal === "." || literal === ".." || literal.startsWith("../");
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Scratch roots declared at a fixed path under the shared checkout. */
|
|
56
|
+
export function fixedScratchRoots(source: string): string[] {
|
|
57
|
+
const src = stripJsComments(source);
|
|
58
|
+
const roots = repoRootIdents(src);
|
|
59
|
+
const out: string[] = [];
|
|
60
|
+
for (const m of src.matchAll(new RegExp(DECL.source, "g"))) {
|
|
61
|
+
const [, name, wrapped, rootIdent, literal] = m;
|
|
62
|
+
if (wrapped) continue; // mkdtempSync — unique per run, which is the fix
|
|
63
|
+
if (!roots.has(rootIdent!)) continue; // already under a unique root
|
|
64
|
+
if (isNavigation(literal!)) continue;
|
|
65
|
+
// Only a directory this suite CREATES or DELETES is scratch. One it merely
|
|
66
|
+
// reads is configuration, and renaming it per run would break the read.
|
|
67
|
+
const mutates = new RegExp(`(?:mkdirSync|rmSync)\\(\\s*(?:join\\(\\s*)?${name}\\b`);
|
|
68
|
+
if (mutates.test(src)) out.push(`${name} = ${literal}`);
|
|
69
|
+
}
|
|
70
|
+
return out;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* The `mkdtempSync` prefixes a file plants under the repo root.
|
|
75
|
+
*
|
|
76
|
+
* This is the other half of the same parse, and it is what the sweeper's
|
|
77
|
+
* allowlist is built from. It deliberately returns the prefix EXACTLY as
|
|
78
|
+
* written — including the trailing `-` that `mkdtempSync` appends its random
|
|
79
|
+
* suffix to — because a prefix widened by even one character is a wider
|
|
80
|
+
* deletion allowlist.
|
|
81
|
+
*/
|
|
82
|
+
export function uniqueScratchPrefixes(source: string): string[] {
|
|
83
|
+
const src = stripJsComments(source);
|
|
84
|
+
const roots = repoRootIdents(src);
|
|
85
|
+
const out: string[] = [];
|
|
86
|
+
for (const m of src.matchAll(new RegExp(DECL.source, "g"))) {
|
|
87
|
+
const [, , wrapped, rootIdent, literal] = m;
|
|
88
|
+
if (!wrapped) continue; // a fixed path is the other function's subject
|
|
89
|
+
if (!roots.has(rootIdent!)) continue;
|
|
90
|
+
if (isNavigation(literal!)) continue;
|
|
91
|
+
if (!out.includes(literal!)) out.push(literal!);
|
|
92
|
+
}
|
|
93
|
+
return out;
|
|
94
|
+
}
|
|
@@ -11,6 +11,8 @@ import { spawnSync } from 'child_process';
|
|
|
11
11
|
import { existsSync, readFileSync } from 'fs';
|
|
12
12
|
import { join } from 'path';
|
|
13
13
|
|
|
14
|
+
import { tryLoadRungateConfig } from './config-loader';
|
|
15
|
+
|
|
14
16
|
export interface CompletionCheckResult {
|
|
15
17
|
passed: boolean;
|
|
16
18
|
blockers: string[];
|
|
@@ -105,15 +107,60 @@ export function checkUncommittedChanges(projectRoot: string): CompletionCheckRes
|
|
|
105
107
|
}
|
|
106
108
|
|
|
107
109
|
/**
|
|
108
|
-
* Run conformity checks if
|
|
110
|
+
* Run conformity checks if the project is scaffolded.
|
|
109
111
|
* Returns blocker if conformity fails.
|
|
110
112
|
*/
|
|
111
113
|
export function checkConformity(projectRoot: string): CompletionCheckResult {
|
|
112
114
|
const blockers: string[] = [];
|
|
113
115
|
const warnings: string[] = [];
|
|
114
116
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
+
// Either layout counts as scaffolded. The old existence check named the
|
|
118
|
+
// monolith only, so every consumer that followed the documented migration
|
|
119
|
+
// to `.claude/rungate/` stopped having its conformity suite run here —
|
|
120
|
+
// silently, reporting passed.
|
|
121
|
+
//
|
|
122
|
+
// The throw is CAUGHT and converted to a blocker, which is the one place in
|
|
123
|
+
// this migration that is not simply "let the loader throw". This function is
|
|
124
|
+
// reached from `hooks/TaskCompleted.hook.ts`, which has no catch of its own,
|
|
125
|
+
// and a hook that exits 1 is neither allow (0) nor block (2) — so an
|
|
126
|
+
// escaping throw would disable the entire completion gate, not just this
|
|
127
|
+
// check, on one unparseable byte. Blocking keeps ADR-001 D2's distinction
|
|
128
|
+
// (a corrupt config is never a missing config) and keeps the gate closed.
|
|
129
|
+
let configured: boolean;
|
|
130
|
+
try {
|
|
131
|
+
configured = tryLoadRungateConfig(projectRoot) !== null;
|
|
132
|
+
} catch (err: unknown) {
|
|
133
|
+
// The CLASS, not the message. `JSON.parse` quotes a token from the file it
|
|
134
|
+
// failed on — "Unexpected identifier \"ghp_…\"" — and a config can hold
|
|
135
|
+
// credentials, so the parser's text is a channel out of the file and into
|
|
136
|
+
// this blocker, which is printed to stderr and captured in transcripts.
|
|
137
|
+
// The reproduction command is the replacement for the detail: it gives the
|
|
138
|
+
// operator the full message on their own terminal, where the config
|
|
139
|
+
// already is.
|
|
140
|
+
const kind = err instanceof Error && err.name ? err.name : "error";
|
|
141
|
+
// No runnable command in the text, and the path is JSON-quoted.
|
|
142
|
+
//
|
|
143
|
+
// The first draft printed `bun -e '…${projectRoot}…'` for the operator to
|
|
144
|
+
// paste, which the push review called command injection and is: this is a
|
|
145
|
+
// library function, the root reaches it from the caller, and a path
|
|
146
|
+
// carrying `'; rm -rf ~; '` would have been printed as a command a human
|
|
147
|
+
// is being told to run. A refusal that hands someone a line to paste is
|
|
148
|
+
// an execution path with a person in the middle of it.
|
|
149
|
+
//
|
|
150
|
+
// `JSON.stringify` on the path escapes quotes and newlines, so a crafted
|
|
151
|
+
// root cannot end the sentence and forge a second one either.
|
|
152
|
+
return {
|
|
153
|
+
passed: false,
|
|
154
|
+
blockers: [
|
|
155
|
+
`rungate config under ${JSON.stringify(join(projectRoot, '.claude'))} could not be read ` +
|
|
156
|
+
`(${kind}), so conformity did not run — a config that exists and cannot be parsed is ` +
|
|
157
|
+
`not an unconfigured project. Load that root with loadRungateConfig from ` +
|
|
158
|
+
`lib/config-loader.ts to see the parser's own message.`,
|
|
159
|
+
],
|
|
160
|
+
warnings: [],
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
if (!configured) {
|
|
117
164
|
// No rungate config — skip conformity check
|
|
118
165
|
return { passed: true, blockers: [], warnings: [] };
|
|
119
166
|
}
|