rungate 0.4.0 → 0.5.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/config/behavioral-sc-map.json +170 -0
- package/config/brief-policies.json +28 -0
- package/config/ceremony-profiles.json +207 -0
- package/config/check-registry.json +114 -0
- package/config/matcher-registry.json +142 -0
- package/config/prove-evidence.schema.json +65 -0
- package/config/spec-policies.json +36 -0
- package/config/universal-rules.yaml +15 -0
- package/config/workflow-schema.json +279 -0
- package/lib/ac-quality.ts +119 -0
- package/lib/cli-commands.ts +7 -1
- package/lib/config-loader.ts +129 -5
- package/lib/conformity.ts +1122 -31
- package/lib/context-docs.ts +182 -0
- package/lib/create-brief.ts +22 -17
- package/lib/create-sc.ts +35 -8
- package/lib/doc-scan-targets.ts +435 -0
- package/lib/gate-check-audit.ts +9 -9
- package/lib/github.ts +195 -0
- package/lib/js-top-level-code.ts +27 -2
- package/lib/organize.ts +129 -40
- package/lib/package-closure.ts +387 -0
- package/lib/project-aliases.ts +100 -0
- package/lib/release-preflight.ts +352 -48
- package/lib/rungate-schema.ts +23 -1
- package/lib/sc-cover.ts +92 -1
- package/lib/sc-ids.ts +151 -0
- package/lib/scaffold/defaults.ts +40 -0
- package/lib/scaffold/managed-workflow.ts +125 -27
- package/lib/scaffold/owned-files.ts +6 -0
- package/lib/scaffold/profiles.ts +94 -0
- package/lib/scaffold/rehearsal.ts +355 -0
- package/lib/scaffold/steps.ts +787 -105
- package/lib/scaffold/write-steps.ts +208 -0
- package/lib/scratch-cleanup.ts +198 -0
- package/lib/scratch-roots.ts +94 -0
- package/lib/source-anchor.ts +144 -0
- package/lib/success-doc.ts +779 -0
- package/lib/suite-run-reading.ts +194 -0
- package/lib/test-census.ts +199 -0
- package/lib/trajectory.ts +377 -0
- package/lib/validators/spec-validators.ts +52 -35
- package/lib/workflow-security.ts +152 -7
- package/lib/workflow-test-harness.ts +349 -0
- package/lib/worktree-cleanup.ts +123 -7
- package/lib/worktree-repo.ts +165 -0
- package/package.json +10 -1
- package/scripts/audit-specs.ts +134 -37
- package/scripts/audit-transcript.ts +259 -0
- package/scripts/create-sc.ts +15 -1
- package/scripts/create-success.ts +162 -0
- package/scripts/detect-sc-drift.ts +200 -0
- package/scripts/extract-constraints.ts +16 -36
- package/scripts/scaffold-project.ts +51 -137
- package/scripts/split-spec.ts +315 -0
- package/scripts/sync-sc-status.ts +751 -0
- package/specs/SPEC-TEMPLATE.md +200 -0
- package/templates/SUCCESS-TEMPLATE.md +72 -0
- package/templates/agent-briefs/_shared.md +9 -0
- package/templates/agent-briefs/aditi.md +46 -0
- package/templates/agent-briefs/discovery.md +37 -0
- package/templates/agent-briefs/marcus.md +39 -0
- package/templates/agent-briefs/quinn.md +67 -0
- package/templates/agent-briefs/rook.md +40 -0
- package/templates/agent-briefs/serena.md +39 -0
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every step that writes, as one callable body (#398).
|
|
3
|
+
*
|
|
4
|
+
* This used to be the inside of `if (fix) { … }` in
|
|
5
|
+
* `scripts/scaffold-project.ts`, with a four-`existsSync` `else` standing in
|
|
6
|
+
* for it during an audit. Those two branches shared no code, so they could
|
|
7
|
+
* only agree by somebody keeping them in step, and the measured disagreement
|
|
8
|
+
* was 28 paths to 0.
|
|
9
|
+
*
|
|
10
|
+
* Pulling the body out here is what lets audit RUN it against a clone instead
|
|
11
|
+
* of predicting it — see `lib/scaffold/rehearsal.ts`. Nothing about the
|
|
12
|
+
* ordering changed in the move, including the two comments that explain why
|
|
13
|
+
* particular steps sit where they do (#72, #123); they are load-bearing and
|
|
14
|
+
* are carried verbatim.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { existsSync, writeFileSync } from "fs";
|
|
18
|
+
import { join } from "path";
|
|
19
|
+
|
|
20
|
+
import {
|
|
21
|
+
safeDir,
|
|
22
|
+
safeWrite,
|
|
23
|
+
regenerateOwned,
|
|
24
|
+
generateAgentsMdContent,
|
|
25
|
+
refreshScopedRulesStep,
|
|
26
|
+
refreshAgentsMd,
|
|
27
|
+
updateSpecsTable,
|
|
28
|
+
injectEnvironmentSection,
|
|
29
|
+
generateConformityTest,
|
|
30
|
+
generateAgentBriefsStep,
|
|
31
|
+
generateOrAuditProjectHarness,
|
|
32
|
+
generateCodeMapStep,
|
|
33
|
+
copySpecTemplateIfEmpty,
|
|
34
|
+
createGitignore,
|
|
35
|
+
createTsconfig,
|
|
36
|
+
generateProjectState,
|
|
37
|
+
createClaudeMdBridge,
|
|
38
|
+
seedSuccessDoc,
|
|
39
|
+
createCiWorkflows,
|
|
40
|
+
createGitHooks,
|
|
41
|
+
deployHooksToConsumers,
|
|
42
|
+
addPaiHarnessDevDep,
|
|
43
|
+
reportExternalAdoptionStep,
|
|
44
|
+
runAuditSpecsFix,
|
|
45
|
+
postScaffoldCommit,
|
|
46
|
+
} from "./steps";
|
|
47
|
+
import {
|
|
48
|
+
addFrontmatterToSpecs, addFrontmatterToAdrs, detectOversizedSpecs,
|
|
49
|
+
checkGovernsAlignment, detectMisplacedSpecs, detectUnconvertedSpecs,
|
|
50
|
+
} from "../validators/spec-validators";
|
|
51
|
+
import type { ProjectType } from "../generators/types";
|
|
52
|
+
import { DEFAULT_PROFILE, isStepIncluded, type ScaffoldProfile } from "./profiles";
|
|
53
|
+
|
|
54
|
+
export interface WriteStepOptions {
|
|
55
|
+
force?: boolean;
|
|
56
|
+
commit?: boolean;
|
|
57
|
+
/**
|
|
58
|
+
* True when running against a disposable clone. The two steps that reach
|
|
59
|
+
* outside the tree are skipped — see `STEPS_NOT_REHEARSED` in
|
|
60
|
+
* `./rehearsal.ts`, which carries the reason for each.
|
|
61
|
+
*/
|
|
62
|
+
rehearsing?: boolean;
|
|
63
|
+
/**
|
|
64
|
+
* How much of the harness this project opted into. Orthogonal to
|
|
65
|
+
* `projectType`, which selects WHICH generators run; this selects whether
|
|
66
|
+
* the harness-only ones run at all. See `STEPS_NOT_MINIMAL` in
|
|
67
|
+
* `./profiles.ts`, which carries the reason for each exclusion.
|
|
68
|
+
*/
|
|
69
|
+
profile?: ScaffoldProfile;
|
|
70
|
+
/**
|
|
71
|
+
* Opt OUT of the mechanical fixes (#42 SC-4). Default on, because a
|
|
72
|
+
* re-scaffold that reports a gap it could have closed is a worse onboarding
|
|
73
|
+
* than one that closes it.
|
|
74
|
+
*/
|
|
75
|
+
autoFix?: boolean;
|
|
76
|
+
/**
|
|
77
|
+
* Opt IN to removing consumers the source scan did not find (#42 SC-2).
|
|
78
|
+
*
|
|
79
|
+
* Deliberately NOT covered by `autoFix`'s opt-out default — see
|
|
80
|
+
* `pruneStaleConsumers`. Adding a frontmatter line and deleting a config
|
|
81
|
+
* entry are not in the same risk class, and one flag governing both would
|
|
82
|
+
* make the safe default impossible to express.
|
|
83
|
+
*/
|
|
84
|
+
pruneConsumers?: boolean;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
export function runScaffoldWriteSteps(
|
|
88
|
+
projectPath: string,
|
|
89
|
+
projectType: ProjectType,
|
|
90
|
+
actions: string[],
|
|
91
|
+
opts: WriteStepOptions = {},
|
|
92
|
+
): void {
|
|
93
|
+
const { force = false, commit = false, rehearsing = false, profile = DEFAULT_PROFILE, autoFix = true, pruneConsumers = false } = opts;
|
|
94
|
+
|
|
95
|
+
// Phase 0: Security and directory setup
|
|
96
|
+
createGitignore(projectPath, actions);
|
|
97
|
+
safeDir(join(projectPath, "specs"), "specs", actions);
|
|
98
|
+
safeDir(join(projectPath, "reference"), "reference", actions);
|
|
99
|
+
safeDir(join(projectPath, ".github"), ".github", actions);
|
|
100
|
+
safeDir(join(projectPath, ".github", "workflows"), ".github/workflows", actions);
|
|
101
|
+
safeDir(join(projectPath, "scripts"), "scripts", actions);
|
|
102
|
+
safeDir(join(projectPath, "docs"), "docs", actions);
|
|
103
|
+
safeDir(join(projectPath, "docs", "adr"), "docs/adr", actions);
|
|
104
|
+
|
|
105
|
+
const testDirName = existsSync(join(projectPath, "test")) ? "test" : "tests";
|
|
106
|
+
safeDir(join(projectPath, testDirName), testDirName, actions);
|
|
107
|
+
|
|
108
|
+
// Before Phase 0.5 and before createCiWorkflows on purpose (#72): both decide
|
|
109
|
+
// whether to emit a type check by looking for tsconfig.json on disk.
|
|
110
|
+
createTsconfig(projectPath, actions);
|
|
111
|
+
|
|
112
|
+
// Phase 0.5: Generate AGENTS.md
|
|
113
|
+
const agentsMd = generateAgentsMdContent(projectPath, projectType, actions, profile);
|
|
114
|
+
writeFileSync(join(projectPath, "AGENTS.md"), agentsMd);
|
|
115
|
+
actions.push("REGENERATED: AGENTS.md");
|
|
116
|
+
refreshAgentsMd(projectPath, projectType, actions);
|
|
117
|
+
updateSpecsTable(join(projectPath, "AGENTS.md"), actions);
|
|
118
|
+
|
|
119
|
+
// Phase 0.6: Create copilot instructions
|
|
120
|
+
const copilotInstructions = `# Copilot Instructions\n\nRead [AGENTS.md](../AGENTS.md) for project context, key files, specs, and workflow.\n\nAll project knowledge lives in AGENTS.md. Start there.\n`;
|
|
121
|
+
safeWrite(join(projectPath, ".github", "copilot-instructions.md"), copilotInstructions, ".github/copilot-instructions.md", actions);
|
|
122
|
+
|
|
123
|
+
// Phase 0.7: regenerate the conformity test. Strategy passed, not looked up — the label carries the project's own test dir, which may not be `test/` (#208).
|
|
124
|
+
regenerateOwned(join(projectPath, testDirName, "scaffold-conformity.test.ts"), generateConformityTest(projectPath), `${testDirName}/scaffold-conformity.test.ts`, actions, "regenerate");
|
|
125
|
+
|
|
126
|
+
// Validators. These used to run outside the `if (fix)` block with a `{ fix }`
|
|
127
|
+
// flag, which is why `addFrontmatterToSpecs` is the one step audit ever
|
|
128
|
+
// reported anything from.
|
|
129
|
+
if (autoFix) {
|
|
130
|
+
addFrontmatterToSpecs(join(projectPath, "specs"), actions);
|
|
131
|
+
addFrontmatterToAdrs(join(projectPath, "docs", "adr"), actions);
|
|
132
|
+
} else {
|
|
133
|
+
// Named, not silent. A run that declined to fix and said nothing is
|
|
134
|
+
// indistinguishable from one that had nothing to fix (#208, SC-819).
|
|
135
|
+
actions.push("SKIP: auto-fix of spec and ADR frontmatter (--no-auto-fix)");
|
|
136
|
+
}
|
|
137
|
+
detectOversizedSpecs(join(projectPath, "specs"), actions);
|
|
138
|
+
checkGovernsAlignment(join(projectPath, "specs"), actions);
|
|
139
|
+
detectMisplacedSpecs(projectPath, actions);
|
|
140
|
+
detectUnconvertedSpecs(join(projectPath, "specs"), actions);
|
|
141
|
+
|
|
142
|
+
// Phase 0.8: Workflow project setup
|
|
143
|
+
if (projectType === "workflow") {
|
|
144
|
+
const workflowDef = `---
|
|
145
|
+
doc-type: spec
|
|
146
|
+
testable: no
|
|
147
|
+
governs: workflow-definition
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
# Workflow Definition
|
|
151
|
+
|
|
152
|
+
## Trigger
|
|
153
|
+
|
|
154
|
+
When should this workflow run?
|
|
155
|
+
|
|
156
|
+
## Inputs
|
|
157
|
+
|
|
158
|
+
What inputs does this workflow require?
|
|
159
|
+
|
|
160
|
+
## Process
|
|
161
|
+
|
|
162
|
+
What steps does this workflow perform?
|
|
163
|
+
|
|
164
|
+
## Output
|
|
165
|
+
|
|
166
|
+
What does this workflow produce?
|
|
167
|
+
`;
|
|
168
|
+
safeWrite(join(projectPath, "specs", "WORKFLOW-DEFINITION.md"), workflowDef, "specs/WORKFLOW-DEFINITION.md", actions);
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// Phase 1.5: Harness config + briefs. Harness-only under `minimal` — see
|
|
172
|
+
// STEPS_NOT_MINIMAL for why each is excluded.
|
|
173
|
+
if (isStepIncluded("generateOrAuditProjectHarness", profile)) {
|
|
174
|
+
generateOrAuditProjectHarness(projectPath, actions, { pruneConsumers });
|
|
175
|
+
}
|
|
176
|
+
injectEnvironmentSection(projectPath, actions);
|
|
177
|
+
if (isStepIncluded("generateAgentBriefsStep", profile)) {
|
|
178
|
+
generateAgentBriefsStep(projectPath, actions);
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
// Phase 3: Final setup
|
|
182
|
+
copySpecTemplateIfEmpty(join(projectPath, "specs"), actions);
|
|
183
|
+
generateProjectState(projectPath, actions);
|
|
184
|
+
// Both profiles. #485 is about the file existing at all, and `minimal` is
|
|
185
|
+
// the profile the consumer that found the gap was scaffolded with.
|
|
186
|
+
seedSuccessDoc(projectPath, actions);
|
|
187
|
+
runAuditSpecsFix(projectPath, actions);
|
|
188
|
+
addPaiHarnessDevDep(projectPath, actions);
|
|
189
|
+
createClaudeMdBridge(projectPath, actions);
|
|
190
|
+
// See STEPS_NOT_MINIMAL.
|
|
191
|
+
if (isStepIncluded("createCiWorkflows", profile)) {
|
|
192
|
+
createCiWorkflows(projectPath, actions, { force });
|
|
193
|
+
}
|
|
194
|
+
createGitHooks(projectPath, actions);
|
|
195
|
+
|
|
196
|
+
// Leaves the tree. See STEPS_NOT_REHEARSED.
|
|
197
|
+
if (!rehearsing) deployHooksToConsumers(projectPath, actions);
|
|
198
|
+
|
|
199
|
+
// Phase 3.5: steps that DESCRIBE the project run last, so they describe the tree this run left (#123).
|
|
200
|
+
reportExternalAdoptionStep(projectPath, actions);
|
|
201
|
+
refreshScopedRulesStep(projectPath, projectType, actions, profile);
|
|
202
|
+
if (projectType === "code") {
|
|
203
|
+
generateCodeMapStep(projectPath, actions);
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
// Leaves the tree. See STEPS_NOT_REHEARSED.
|
|
207
|
+
if (!rehearsing) postScaffoldCommit(projectPath, actions, { commit });
|
|
208
|
+
}
|
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cite a line of source by what it SAYS, not by where it sits (#514).
|
|
3
|
+
*
|
|
4
|
+
* A spec that writes `workflows/ship.js:5775` is making a claim that stops
|
|
5
|
+
* being true the next time anything is inserted above line 5775, and nothing
|
|
6
|
+
* about the spec changes when it does. `test/gate-env-expressibility.test.ts`
|
|
7
|
+
* SC-1719 is the one guard anybody wrote for one such citation, and keeping
|
|
8
|
+
* it green cost three hand edits of five numbers in two PRs.
|
|
9
|
+
*
|
|
10
|
+
* Measured on `specs/GATE-CONTRACTS-SPEC.md` while fixing this: of its seven
|
|
11
|
+
* line citations, the three under that guard were correct and **three of the
|
|
12
|
+
* four unguarded ones were already wrong** — `gate-executor.ts:1725` pointed
|
|
13
|
+
* at a `parseFloat`, `evidence-prevalidator.ts:208` at a comment, and
|
|
14
|
+
* `scaffold-rungate-config.ts:66` at an unrelated `existsSync`. Each pointed
|
|
15
|
+
* at a plausible-looking line. Nobody had noticed.
|
|
16
|
+
*
|
|
17
|
+
* So the citation carries the text and the resolver reports the position:
|
|
18
|
+
*
|
|
19
|
+
* `workflows/ship.js@"const containerConfig = projectConfig.container"`
|
|
20
|
+
*
|
|
21
|
+
* **Resolution is total.** Not found and found-twice are both refusals, and
|
|
22
|
+
* the second one matters more than it looks: an ambiguous anchor is how a
|
|
23
|
+
* citation lands somewhere plausible, which is precisely the failure the line
|
|
24
|
+
* numbers had. `0`, `null` and "the first match" are indistinguishable from a
|
|
25
|
+
* correct answer; a refusal naming the count is not.
|
|
26
|
+
*/
|
|
27
|
+
import { existsSync, readFileSync, realpathSync } from "fs";
|
|
28
|
+
import { join, resolve, sep } from "path";
|
|
29
|
+
|
|
30
|
+
/** `path@"anchor"` inside a single markdown code span. */
|
|
31
|
+
export const ANCHOR_CITATION = /`([A-Za-z0-9_./-]+)@"([^"`]*)"`/g;
|
|
32
|
+
|
|
33
|
+
/** The old form, kept so a document can be checked for having left it behind. */
|
|
34
|
+
export const LINE_CITATION = /`?\b([A-Za-z0-9_./-]+\.(?:ts|js|json)):(\d+)\b/g;
|
|
35
|
+
|
|
36
|
+
export interface Citation {
|
|
37
|
+
path: string;
|
|
38
|
+
anchor: string;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export type Resolution =
|
|
42
|
+
| { ok: true; path: string; anchor: string; line: number; text: string }
|
|
43
|
+
| { ok: false; path: string; anchor: string; reason: string };
|
|
44
|
+
|
|
45
|
+
/** Every anchor citation in a document, in order, deduplicated by nothing. */
|
|
46
|
+
export function anchorCitations(doc: string): Citation[] {
|
|
47
|
+
const out: Citation[] = [];
|
|
48
|
+
for (const m of doc.matchAll(ANCHOR_CITATION)) out.push({ path: m[1], anchor: m[2] });
|
|
49
|
+
return out;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Where a citation points, or why it does not point anywhere.
|
|
54
|
+
*
|
|
55
|
+
* `root` is the repository root; a citation's path is repo-relative, because
|
|
56
|
+
* a bare filename is how `steps.ts:43` came to be ambiguous between three
|
|
57
|
+
* files in this repo's own ADRs.
|
|
58
|
+
*/
|
|
59
|
+
export function resolveCitation(root: string, cite: Citation): Resolution {
|
|
60
|
+
const { path, anchor } = cite;
|
|
61
|
+
const fail = (reason: string): Resolution => ({ ok: false, path, anchor, reason });
|
|
62
|
+
|
|
63
|
+
if (anchor.length === 0) return fail("the anchor is empty, so it matches nothing and everything");
|
|
64
|
+
// Short anchors are the ones that become ambiguous later, after an
|
|
65
|
+
// unrelated edit somewhere else in the file. Refusing them now is cheaper
|
|
66
|
+
// than refusing them on the day they break something.
|
|
67
|
+
if (anchor.trim().length < 12) {
|
|
68
|
+
return fail(`the anchor "${anchor}" is ${anchor.trim().length} characters — too short to stay unique`);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// The path comes out of a markdown document, and this function reads
|
|
72
|
+
// whatever it names. Flagged by the commit security review: `ANCHOR_CITATION`
|
|
73
|
+
// admits `.` and `/`, so `../../../../etc/passwd` is a well-formed citation
|
|
74
|
+
// and `join` resolves it happily out of the tree.
|
|
75
|
+
//
|
|
76
|
+
// No live document does that — every citation here is written by someone
|
|
77
|
+
// with commit access — but "the input happens to be trusted today" is not a
|
|
78
|
+
// property of a library, and a spec is exactly the sort of file a consumer
|
|
79
|
+
// generates. Refused rather than normalised: a citation that climbs out of
|
|
80
|
+
// the repository is not a citation with a fixable path, it is a citation to
|
|
81
|
+
// something this function has no business reading.
|
|
82
|
+
//
|
|
83
|
+
// Three checks, and each has an input only it reaches. The first draft had
|
|
84
|
+
// four, and the battery measured the fourth — a `..`-segment spelling rule
|
|
85
|
+
// — at **0 red**, because `resolve` normalises `..` and the containment
|
|
86
|
+
// check below already refuses it. Two deciders answering one question, the
|
|
87
|
+
// fourth shape in `.claude/rules/checks-must-be-able-to-fail.md`. Dropped.
|
|
88
|
+
//
|
|
89
|
+
// `/etc/passwd` only this rule. `join` CONCATENATES a leading
|
|
90
|
+
// slash rather than absorbing it, so the path stays
|
|
91
|
+
// inside the tree and containment has nothing to say
|
|
92
|
+
// `../../etc/passwd` only containment, below
|
|
93
|
+
// a symlink inside only `realpathSync`, below — `resolve` is purely
|
|
94
|
+
// lexical and cannot see a link at all
|
|
95
|
+
//
|
|
96
|
+
// The first of those is not an escape: `join(root, "/etc/passwd")` reads
|
|
97
|
+
// `<root>/etc/passwd`. It is refused because a citation written absolute
|
|
98
|
+
// means something other than what its author thinks it means, and a
|
|
99
|
+
// confident citation to the wrong file is this whole issue.
|
|
100
|
+
if (path.startsWith("/")) return fail("the path is absolute — citations are repository-relative");
|
|
101
|
+
|
|
102
|
+
const full = join(root, path);
|
|
103
|
+
const contained = resolve(root) + sep;
|
|
104
|
+
if (!resolve(full).startsWith(contained)) {
|
|
105
|
+
return fail("the path resolves outside the repository, so it is not a citation to this tree");
|
|
106
|
+
}
|
|
107
|
+
if (!existsSync(full)) return fail("no such file in the repository");
|
|
108
|
+
|
|
109
|
+
// The symlink question, which the lexical check genuinely cannot answer:
|
|
110
|
+
// a link INSIDE the tree whose target is outside it resolves to a
|
|
111
|
+
// contained path and reads an uncontained file. `realpathSync` is the only
|
|
112
|
+
// thing that follows it, and it needs the file to exist, which is why it
|
|
113
|
+
// sits here rather than beside its lexical sibling.
|
|
114
|
+
if (!realpathSync(full).startsWith(realpathSync(resolve(root)) + sep)) {
|
|
115
|
+
return fail("the path is a symlink whose target is outside the repository");
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const source = readFileSync(full, "utf-8");
|
|
119
|
+
const count = source.split(anchor).length - 1;
|
|
120
|
+
if (count === 0) return fail("the file no longer contains this text");
|
|
121
|
+
if (count > 1) {
|
|
122
|
+
return fail(
|
|
123
|
+
`the text appears ${count} times, so the citation does not name a site — ` +
|
|
124
|
+
`an ambiguous anchor is how a citation lands somewhere plausible`,
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const lines = source.split("\n");
|
|
129
|
+
const index = lines.findIndex(l => l.includes(anchor));
|
|
130
|
+
// A multi-line anchor has no single line, and silently reporting its first
|
|
131
|
+
// is the kind of "near enough" that put three wrong numbers in a spec.
|
|
132
|
+
if (index < 0) return fail("the text spans more than one line, so it does not name a line");
|
|
133
|
+
return { ok: true, path, anchor, line: index + 1, text: lines[index] };
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** Every citation in a document that does not resolve, as sentences. */
|
|
137
|
+
export function citationFailures(root: string, doc: string): string[] {
|
|
138
|
+
const out: string[] = [];
|
|
139
|
+
for (const cite of anchorCitations(doc)) {
|
|
140
|
+
const r = resolveCitation(root, cite);
|
|
141
|
+
if (!r.ok) out.push(`${cite.path}@"${cite.anchor}" — ${r.reason}`);
|
|
142
|
+
}
|
|
143
|
+
return out;
|
|
144
|
+
}
|