rungate 0.2.1 → 0.4.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/bin/rungate.ts +70 -0
- package/lib/aes-calculator.ts +66 -0
- package/lib/agent-audit.ts +139 -0
- package/lib/agent-brief-validation.ts +359 -0
- package/lib/agents-md-refs.ts +90 -0
- package/lib/bash-file-read.ts +197 -0
- package/lib/behavioral-cache.ts +78 -0
- package/lib/branch-cleanup.ts +234 -0
- package/lib/brief-context-parser.ts +35 -0
- package/lib/brief-precedence.ts +114 -0
- package/lib/canary.ts +117 -0
- package/lib/check-registry.ts +226 -0
- package/lib/ci-checkout.ts +426 -0
- package/lib/cli-commands.ts +137 -0
- package/lib/compliance-backfill.ts +232 -0
- package/lib/compliance-report.ts +605 -0
- package/lib/compliance.ts +361 -0
- package/lib/config-loader.ts +255 -0
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +2161 -137
- package/lib/container-provenance.ts +230 -0
- package/lib/create-brief.ts +150 -0
- package/lib/create-sc.ts +267 -0
- package/lib/decomposition-waves.ts +197 -0
- package/lib/deep-merge.ts +69 -0
- package/lib/dev-liveness.ts +214 -0
- package/lib/directive-extractor.ts +210 -0
- package/lib/distribution-standing.ts +113 -0
- package/lib/doc-hygiene.ts +238 -0
- package/lib/eval-criteria.ts +6 -0
- package/lib/evidence-portability.ts +123 -0
- package/lib/evidence-prevalidator.ts +390 -0
- package/lib/evidence-required.ts +150 -0
- package/lib/evidence-satisfiability.ts +288 -0
- package/lib/frontmatter.ts +163 -0
- package/lib/gap-scanner.ts +348 -0
- package/lib/gate-check-audit.ts +190 -0
- package/lib/gate-enforcement.ts +366 -0
- package/lib/generators/agent-briefs.ts +136 -0
- package/lib/generators/agents-md.ts +511 -0
- package/lib/generators/code-map.ts +60 -0
- package/lib/generators/types.ts +184 -0
- package/lib/git-ref-normalizer.ts +107 -0
- package/lib/github.ts +539 -0
- package/lib/harness-identity.ts +63 -0
- package/lib/hill-climb.ts +164 -0
- package/lib/instruction-effectiveness.ts +131 -0
- package/lib/issue-closure-audit.ts +225 -0
- package/lib/issue-create-override.ts +343 -0
- package/lib/issue-extraction.ts +368 -0
- package/lib/js-top-level-code.ts +250 -0
- package/lib/liveness-contradiction.ts +149 -0
- package/lib/organize.ts +505 -0
- package/lib/paths.ts +197 -6
- package/lib/phase2-decomposition.ts +270 -0
- package/lib/post-fix-verify.ts +157 -0
- package/lib/prior-branch.ts +512 -0
- package/lib/project-state-shape.ts +166 -0
- package/lib/promote-outputs.ts +156 -0
- package/lib/prove-label-gate.ts +128 -0
- package/lib/reachability.ts +302 -0
- package/lib/release-preflight.ts +288 -0
- package/lib/rule-health-pipeline.ts +264 -0
- package/lib/rule-health-trend.ts +161 -0
- package/lib/rule-provenance.ts +149 -0
- package/lib/rule-registry.ts +128 -0
- package/lib/rungate-schema.ts +127 -5
- package/lib/sc-claim-forms.ts +179 -0
- package/lib/sc-cover.ts +150 -0
- package/lib/sc-guard.ts +157 -0
- package/lib/sc-ids.ts +344 -0
- package/lib/scaffold/defaults.ts +165 -0
- package/lib/scaffold/managed-workflow.ts +370 -0
- package/lib/scaffold/owned-files.ts +265 -0
- package/lib/scaffold/pre-push-hook.ts +165 -0
- package/lib/scaffold/steps.ts +2621 -0
- package/lib/scanner.ts +701 -0
- package/lib/scope-denylist.ts +258 -0
- package/lib/screenshot-upload.ts +73 -0
- package/lib/secret-patterns.ts +112 -0
- package/lib/security-verdict.ts +616 -0
- package/lib/signal-phrases.ts +1 -0
- package/lib/spec-change-conformity.ts +80 -0
- package/lib/spec-files.ts +62 -0
- package/lib/spec-registry.ts +133 -0
- package/lib/spec-updater.ts +96 -0
- package/lib/stale-cleanup.ts +224 -0
- package/lib/stale-issue-scanner.ts +36 -0
- package/lib/strip-js-comments.ts +269 -0
- package/lib/suite-measurement.ts +228 -0
- package/lib/task-completion-checks.ts +224 -0
- package/lib/test-suite-lock.ts +1136 -0
- package/lib/transcript-checker.ts +1140 -0
- package/lib/typescript-project.ts +233 -0
- package/lib/validators/spec-validators.ts +171 -0
- package/lib/verdict-capture.ts +73 -0
- package/lib/verified-push.ts +535 -0
- package/lib/workflow-security.ts +174 -0
- package/lib/worktree-cleanup.ts +432 -0
- package/lib/worktree-collect.ts +283 -0
- package/lib/worktree-isolation.ts +82 -0
- package/lib/worktree-repo.ts +300 -0
- package/package.json +27 -3
- package/prompts/ac-adversary.md +14 -2
- package/prompts/aditi.md +5 -0
- package/prompts/blast-radius.md +5 -0
- package/prompts/container-verify.md +5 -0
- package/prompts/discovery.md +4 -0
- package/prompts/environment.md +5 -0
- package/prompts/evidence-hierarchy.md +5 -0
- package/prompts/evidence-validator.md +11 -0
- package/prompts/marcus.md +5 -0
- package/prompts/prevention.md +5 -0
- package/prompts/prove-reproducer.md +12 -0
- package/prompts/quinn-decision-tree.md +5 -0
- package/prompts/quinn-ui-brief.md +5 -0
- package/prompts/quinn.md +5 -0
- package/prompts/rca.md +5 -0
- package/prompts/read-before-write.md +4 -0
- package/prompts/regression.md +5 -0
- package/prompts/serena.md +5 -0
- package/scripts/audit-specs.ts +464 -0
- package/scripts/convert-spec.ts +293 -0
- package/scripts/create-sc.ts +92 -0
- package/scripts/create-spec.ts +166 -0
- package/scripts/extract-constraints.ts +4 -3
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/scaffold-project.ts +138 -1426
- package/scripts/sync-spec-tests.ts +211 -126
package/lib/conformity.ts
CHANGED
|
@@ -6,8 +6,18 @@
|
|
|
6
6
|
* runScaffoldConformity(import.meta.dir + "/..");
|
|
7
7
|
*/
|
|
8
8
|
import { describe, test, expect } from "bun:test";
|
|
9
|
-
import { existsSync, readFileSync, readdirSync } from "fs";
|
|
10
|
-
import {
|
|
9
|
+
import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
|
|
10
|
+
import { collectSpecFiles } from "./spec-files";
|
|
11
|
+
import { spawnSync } from "child_process";
|
|
12
|
+
import { join, dirname } from "path";
|
|
13
|
+
import { fileURLToPath } from "url";
|
|
14
|
+
import { deriveDirectoryName } from "../scripts/split-spec";
|
|
15
|
+
import { readFreshCache } from "./behavioral-cache";
|
|
16
|
+
import { tryLoadRungateConfig } from "./config-loader";
|
|
17
|
+
import { stripJsComments } from "./strip-js-comments";
|
|
18
|
+
import { parseScDeclarations } from "./sc-ids";
|
|
19
|
+
import { isHarnessItself } from "./harness-identity";
|
|
20
|
+
import { tsconfigVerdict } from "./typescript-project";
|
|
11
21
|
|
|
12
22
|
// ── Shared utilities ────────────────────────────────────────
|
|
13
23
|
|
|
@@ -15,13 +25,89 @@ export function parseFrontmatter(content: string): Record<string, string> | null
|
|
|
15
25
|
const match = content.match(/^---\n([\s\S]*?)\n---/);
|
|
16
26
|
if (!match) return null;
|
|
17
27
|
const fields: Record<string, string> = {};
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
28
|
+
const lines = match[1].split("\n");
|
|
29
|
+
for (let i = 0; i < lines.length; i++) {
|
|
30
|
+
const kv = lines[i].match(/^(\w[\w-]*):\s*(.+)$/);
|
|
31
|
+
if (kv) {
|
|
32
|
+
fields[kv[1]] = kv[2].trim();
|
|
33
|
+
continue;
|
|
34
|
+
}
|
|
35
|
+
// Block-style key — `tiers:` with its value on the indented lines below.
|
|
36
|
+
// Without this branch the key reads as ABSENT, so a presence check on a
|
|
37
|
+
// field that is plainly there (marcus.md's `tiers`, SC-423) fails against
|
|
38
|
+
// correct input. The value is the flattened block, which is enough for the
|
|
39
|
+
// presence and substring checks the conformity matchers make of it.
|
|
40
|
+
const blockKey = lines[i].match(/^(\w[\w-]*):\s*$/);
|
|
41
|
+
if (!blockKey) continue;
|
|
42
|
+
const block: string[] = [];
|
|
43
|
+
while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) {
|
|
44
|
+
block.push(lines[++i].trim());
|
|
45
|
+
}
|
|
46
|
+
fields[blockKey[1]] = block.join("; ");
|
|
21
47
|
}
|
|
22
48
|
return fields;
|
|
23
49
|
}
|
|
24
50
|
|
|
51
|
+
/**
|
|
52
|
+
* SC-286: Resolve and validate file paths - reject traversal and absolute paths
|
|
53
|
+
* Returns resolved path or null if path is unsafe
|
|
54
|
+
*/
|
|
55
|
+
export function resolveAndContain(root: string, target: string): string | null {
|
|
56
|
+
// Reject path traversal
|
|
57
|
+
if (target.includes("../")) return null;
|
|
58
|
+
// Reject absolute paths
|
|
59
|
+
if (target.startsWith("/")) return null;
|
|
60
|
+
// Allow normal relative paths (including those with dots in filenames like .rungate)
|
|
61
|
+
return join(root, target);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Resolve the actual .git directory, handling worktrees where .git is a file
|
|
66
|
+
* containing "gitdir: /path/to/real/gitdir".
|
|
67
|
+
*/
|
|
68
|
+
function resolveGitDir(root: string): string {
|
|
69
|
+
const dotGit = join(root, ".git");
|
|
70
|
+
if (!existsSync(dotGit)) return dotGit;
|
|
71
|
+
const stat = statSync(dotGit);
|
|
72
|
+
if (stat.isDirectory()) return dotGit;
|
|
73
|
+
// Worktree: .git is a file with "gitdir: <path>"
|
|
74
|
+
const content = readFileSync(dotGit, "utf-8").trim();
|
|
75
|
+
const match = content.match(/^gitdir:\s*(.+)$/);
|
|
76
|
+
if (match) {
|
|
77
|
+
const gitdir = match[1].trim();
|
|
78
|
+
// gitdir may be absolute or relative
|
|
79
|
+
return gitdir.startsWith("/") ? gitdir : join(root, gitdir);
|
|
80
|
+
}
|
|
81
|
+
return dotGit;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Resolve a file path that starts with .git/ through the worktree-aware git dir.
|
|
86
|
+
* For non-.git paths, returns the normal join(root, file).
|
|
87
|
+
*/
|
|
88
|
+
function resolveFilePath(root: string, file: string): string {
|
|
89
|
+
if (file.startsWith(".git/")) {
|
|
90
|
+
const gitDir = resolveGitDir(root);
|
|
91
|
+
// For worktrees, hooks live in the main repo's hooks dir, not the worktree gitdir.
|
|
92
|
+
// The worktree gitdir (e.g. .git/worktrees/name/) doesn't have hooks/.
|
|
93
|
+
// Walk up to the main .git dir if we're in a worktree subdir.
|
|
94
|
+
const suffix = file.slice(".git/".length); // e.g. "hooks/pre-commit"
|
|
95
|
+
const resolved = join(gitDir, suffix);
|
|
96
|
+
if (existsSync(resolved)) return resolved;
|
|
97
|
+
// Try the common dir (main repo .git) for shared resources like hooks
|
|
98
|
+
const commonDirFile = join(gitDir, "commondir");
|
|
99
|
+
if (existsSync(commonDirFile)) {
|
|
100
|
+
const commonDir = readFileSync(commonDirFile, "utf-8").trim();
|
|
101
|
+
const commonResolved = commonDir.startsWith("/")
|
|
102
|
+
? join(commonDir, suffix)
|
|
103
|
+
: join(gitDir, commonDir, suffix);
|
|
104
|
+
if (existsSync(commonResolved)) return commonResolved;
|
|
105
|
+
}
|
|
106
|
+
return resolved;
|
|
107
|
+
}
|
|
108
|
+
return join(root, file);
|
|
109
|
+
}
|
|
110
|
+
|
|
25
111
|
export { SIGNAL_PHRASE_PATTERNS } from "./signal-phrases";
|
|
26
112
|
|
|
27
113
|
// ── Structured findings (machine-readable for agents) ──────
|
|
@@ -51,6 +137,7 @@ export interface StalenessEntry {
|
|
|
51
137
|
const _findings: ConformityFinding[] = [];
|
|
52
138
|
const _candidates: ConstraintCandidate[] = [];
|
|
53
139
|
const _staleness: StalenessEntry[] = [];
|
|
140
|
+
let _behavioralCount = 0;
|
|
54
141
|
|
|
55
142
|
export function addFinding(finding: ConformityFinding): void {
|
|
56
143
|
_findings.push(finding);
|
|
@@ -80,6 +167,70 @@ export function clearFindings(): void {
|
|
|
80
167
|
_findings.length = 0;
|
|
81
168
|
_candidates.length = 0;
|
|
82
169
|
_staleness.length = 0;
|
|
170
|
+
_behavioralCount = 0;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
export function addBehavioralCount(count: number): void {
|
|
174
|
+
_behavioralCount += count;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
export function getBehavioralCount(): number {
|
|
178
|
+
return _behavioralCount;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
// ── Auto-flip: track passing SCs and flip checkboxes ────────
|
|
182
|
+
|
|
183
|
+
interface PassingSC {
|
|
184
|
+
id: string;
|
|
185
|
+
specPath: string;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
const _passingSCs: PassingSC[] = [];
|
|
189
|
+
|
|
190
|
+
export function recordPassingSC(id: string, specPath: string): void {
|
|
191
|
+
_passingSCs.push({ id, specPath });
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
export function getPassingSCs(): readonly PassingSC[] {
|
|
195
|
+
return _passingSCs;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* Flip `- [ ] SC-N` to `- [x] SC-N` for every SC recorded as passing in this
|
|
200
|
+
* process.
|
|
201
|
+
*
|
|
202
|
+
* DELIBERATELY HAS NO AUTOMATIC CALLER (#86). It used to run from an afterAll
|
|
203
|
+
* inside runScaffoldConformity, which made a test run mutate the spec files
|
|
204
|
+
* that the next run's test collection reads from — the suite alternated
|
|
205
|
+
* between 57 and 99 tests and reported 0 fail either way.
|
|
206
|
+
*
|
|
207
|
+
* Routine syncing is handled by scripts/sync-sc-status.ts via the `posttest`
|
|
208
|
+
* hook, which re-derives pass state independently. Call this only from an
|
|
209
|
+
* explicitly-invoked command, never from a test lifecycle hook.
|
|
210
|
+
*/
|
|
211
|
+
export function flipPassingCheckboxes(): number {
|
|
212
|
+
const byFile = new Map<string, Set<string>>();
|
|
213
|
+
for (const { id, specPath } of _passingSCs) {
|
|
214
|
+
if (!byFile.has(specPath)) byFile.set(specPath, new Set());
|
|
215
|
+
byFile.get(specPath)!.add(id);
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
let flipped = 0;
|
|
219
|
+
for (const [specPath, ids] of byFile) {
|
|
220
|
+
if (!existsSync(specPath)) continue;
|
|
221
|
+
let content = readFileSync(specPath, "utf-8");
|
|
222
|
+
let changed = false;
|
|
223
|
+
for (const id of ids) {
|
|
224
|
+
const unchecked = `- [ ] ${id}:`;
|
|
225
|
+
if (content.includes(unchecked)) {
|
|
226
|
+
content = content.replace(unchecked, `- [x] ${id}:`);
|
|
227
|
+
changed = true;
|
|
228
|
+
flipped++;
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
if (changed) writeFileSync(specPath, content);
|
|
232
|
+
}
|
|
233
|
+
return flipped;
|
|
83
234
|
}
|
|
84
235
|
|
|
85
236
|
export function writeFindingsReport(root: string): string {
|
|
@@ -94,6 +245,7 @@ export function writeFindingsReport(root: string): string {
|
|
|
94
245
|
failures: _findings.filter(f => f.severity === "FAIL").length,
|
|
95
246
|
warnings: _findings.filter(f => f.severity === "WARN").length,
|
|
96
247
|
candidateCount: _candidates.length,
|
|
248
|
+
behavioralCount: _behavioralCount,
|
|
97
249
|
staleCount: _staleness.length,
|
|
98
250
|
findings: _findings,
|
|
99
251
|
constraintCandidates: _candidates,
|
|
@@ -102,32 +254,115 @@ export function writeFindingsReport(root: string): string {
|
|
|
102
254
|
return reportPath;
|
|
103
255
|
}
|
|
104
256
|
|
|
105
|
-
interface ParsedSC {
|
|
257
|
+
export interface ParsedSC {
|
|
106
258
|
id: string;
|
|
107
259
|
statement: string;
|
|
108
260
|
specFile: string;
|
|
261
|
+
/**
|
|
262
|
+
* Whether the SC's checkbox is ticked — `- [x]` rather than `- [ ]`.
|
|
263
|
+
*
|
|
264
|
+
* This drives the whole binding: a CHECKED SC claims to be done, so it is
|
|
265
|
+
* run as a real assertion and may fail the suite; an UNCHECKED one is work
|
|
266
|
+
* not started, so it is emitted as `test.todo`. Optional only because
|
|
267
|
+
* ParsedSC is constructed by hand in a dozen call sites that predate the
|
|
268
|
+
* field; `extractSCs` always sets it, and the planner treats a missing
|
|
269
|
+
* value as unchecked.
|
|
270
|
+
*/
|
|
271
|
+
checked?: boolean;
|
|
109
272
|
}
|
|
110
273
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
274
|
+
/** A ParsedSC as produced by extractSCs, where the checkbox state is known. */
|
|
275
|
+
export interface ExtractedSC extends ParsedSC {
|
|
276
|
+
checked: boolean;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
// ── Behavioral SC detection ───────────────────────────────
|
|
280
|
+
|
|
281
|
+
/**
|
|
282
|
+
* Detects whether an SC has the (behavioral) suffix, indicating it requires
|
|
283
|
+
* runtime verification (agent sessions, transcripts, auditing) and cannot
|
|
284
|
+
* be tested by static file checks.
|
|
285
|
+
*/
|
|
286
|
+
export function isBehavioralSC(sc: ParsedSC): boolean {
|
|
287
|
+
return /\(behavioral\)\s*$/.test(sc.statement);
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* Counts behavioral SCs in a list.
|
|
292
|
+
*/
|
|
293
|
+
export function countBehavioralSCs(scs: ParsedSC[]): number {
|
|
294
|
+
return scs.filter(isBehavioralSC).length;
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/**
|
|
298
|
+
* Returns the routing annotation for behavioral SCs.
|
|
299
|
+
* Behavioral SCs are verified via SESSION-AUDIT-SPEC's two feedback loops,
|
|
300
|
+
* not via static conformity checks.
|
|
301
|
+
*/
|
|
302
|
+
export function getBehavioralRouting(sc: ParsedSC): string | null {
|
|
303
|
+
if (!isBehavioralSC(sc)) return null;
|
|
304
|
+
return "Verified via SESSION-AUDIT-SPEC § Two Feedback Loops (runtime behavioral check)";
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Returns an AssertionFn for a behavioral SC when cached results exist.
|
|
309
|
+
* Returns null when no fresh cache entry exists (treated as unmatchable).
|
|
310
|
+
* Stale entries (>= 7 days old) return null so they're treated as unmatchable.
|
|
311
|
+
*/
|
|
312
|
+
export function behavioralPattern(sc: ParsedSC, cachePath: string): ((root: string) => void) | null {
|
|
313
|
+
const cache = readFreshCache(cachePath);
|
|
314
|
+
const entry = cache[sc.id];
|
|
315
|
+
if (!entry) return null;
|
|
316
|
+
|
|
317
|
+
return (_root: string) => {
|
|
318
|
+
if (!entry.passed) {
|
|
319
|
+
throw new Error(`Behavioral SC ${sc.id} failed: ${entry.evidence}`);
|
|
320
|
+
}
|
|
321
|
+
};
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/**
|
|
325
|
+
* Pull every success criterion out of a spec, in BOTH checkbox states.
|
|
326
|
+
*
|
|
327
|
+
* This used to be `/^- \[ \] (SC-\w+)/` — unchecked only. Every SC marked
|
|
328
|
+
* done was therefore invisible to the engine: 261 of them in this repo,
|
|
329
|
+
* none asserted, and the suite reported 0 fail because it never looked.
|
|
330
|
+
* Narrowing this pattern again is caught by the floor test in
|
|
331
|
+
* test/phase-1-5.test.ts.
|
|
332
|
+
*
|
|
333
|
+
* The pattern itself moved to `lib/sc-ids.ts` (#330). It was one of four
|
|
334
|
+
* copies in the tree, each with a different idea of what an id looks like:
|
|
335
|
+
* this one admitted `SC-\w+`, the coverage lookup and the uniqueness guard
|
|
336
|
+
* only `SC-\d+`, so an anti-criterion was a declaration to this reader and
|
|
337
|
+
* invisible to the other two.
|
|
338
|
+
*/
|
|
339
|
+
export function extractSCs(content: string, specFile: string): ExtractedSC[] {
|
|
340
|
+
return parseScDeclarations(content, specFile);
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
export interface SpecMetadata {
|
|
344
|
+
scs: ExtractedSC[];
|
|
345
|
+
compliance: "strict" | "permissive";
|
|
346
|
+
status: "active" | "draft";
|
|
119
347
|
}
|
|
120
348
|
|
|
121
|
-
function collectTestableSpecs(root: string, extraSpecDirs?: string[]):
|
|
122
|
-
const
|
|
349
|
+
export function collectTestableSpecs(root: string, extraSpecDirs?: string[]): Map<string, SpecMetadata> {
|
|
350
|
+
const specMap = new Map<string, SpecMetadata>();
|
|
123
351
|
|
|
124
352
|
const localSpecs = join(root, "specs");
|
|
125
353
|
if (existsSync(localSpecs)) {
|
|
126
|
-
for (const f of
|
|
354
|
+
for (const f of collectSpecFiles(localSpecs)) {
|
|
127
355
|
const content = readFileSync(join(localSpecs, f), "utf-8");
|
|
128
356
|
const fm = parseFrontmatter(content);
|
|
129
357
|
if (fm?.testable === "true") {
|
|
130
|
-
|
|
358
|
+
const compliance = fm?.compliance === "permissive" ? "permissive" : "strict";
|
|
359
|
+
const scs = extractSCs(content, f);
|
|
360
|
+
const hasCheckedSC = /- \[x\] SC-/i.test(content);
|
|
361
|
+
specMap.set(f, {
|
|
362
|
+
scs,
|
|
363
|
+
compliance,
|
|
364
|
+
status: hasCheckedSC ? "active" : "draft",
|
|
365
|
+
});
|
|
131
366
|
}
|
|
132
367
|
}
|
|
133
368
|
}
|
|
@@ -140,38 +375,355 @@ function collectTestableSpecs(root: string, extraSpecDirs?: string[]): ParsedSC[
|
|
|
140
375
|
if (fm?.testable !== "true") continue;
|
|
141
376
|
const governs = fm?.governs || "";
|
|
142
377
|
if (!governs.toLowerCase().includes("scaffold") && !governs.toLowerCase().includes("universal")) continue;
|
|
143
|
-
|
|
378
|
+
const compliance = fm?.compliance === "permissive" ? "permissive" : "strict";
|
|
379
|
+
const hasCheckedSC = /- \[x\] SC-/i.test(content);
|
|
380
|
+
const specFile = `${dir.split("/").pop()}/${f}`;
|
|
381
|
+
specMap.set(specFile, {
|
|
382
|
+
scs: extractSCs(content, specFile),
|
|
383
|
+
compliance,
|
|
384
|
+
status: hasCheckedSC ? "active" : "draft",
|
|
385
|
+
});
|
|
144
386
|
}
|
|
145
387
|
}
|
|
146
388
|
|
|
147
|
-
return
|
|
389
|
+
return specMap;
|
|
148
390
|
}
|
|
149
391
|
|
|
150
392
|
// ── Pattern matchers ────────────────────────────────────────
|
|
151
393
|
|
|
152
394
|
type AssertionFn = (root: string) => void;
|
|
395
|
+
type MatcherHandler = (sc: ParsedSC, match: RegExpMatchArray) => AssertionFn | null;
|
|
396
|
+
|
|
397
|
+
// Config loading with caching
|
|
398
|
+
const _registryCache = new Map<string, Array<{ name: string; regex: string }>>();
|
|
399
|
+
|
|
400
|
+
/**
|
|
401
|
+
* Project-owned conformity exemptions, read from
|
|
402
|
+
* `<root>/.claude/conformity-allowlists.json`.
|
|
403
|
+
*
|
|
404
|
+
* A file rather than a constant because the callers that need it differ in
|
|
405
|
+
* editability: test/scaffold-conformity.test.ts is harness-managed and
|
|
406
|
+
* regenerated on re-scaffold, so a list written into it would be silently
|
|
407
|
+
* wiped. Keying on `root` is also what keeps a consumer from inheriting
|
|
408
|
+
* rungate's exemptions, which is the defect this replaced.
|
|
409
|
+
*
|
|
410
|
+
* Absent or unreadable means no exemptions adopted, and the checks report
|
|
411
|
+
* advisory rather than failing. That is deliberate: before #80 they could not
|
|
412
|
+
* fail at all, so a missing file must not break an existing consumer.
|
|
413
|
+
*/
|
|
414
|
+
function loadConformityAllowlists(root: string): {
|
|
415
|
+
untestedSpecs?: string[];
|
|
416
|
+
orphanFiles?: string[];
|
|
417
|
+
} {
|
|
418
|
+
try {
|
|
419
|
+
const p = join(root, ".claude", "conformity-allowlists.json");
|
|
420
|
+
if (!existsSync(p)) return {};
|
|
421
|
+
const parsed = JSON.parse(readFileSync(p, "utf-8"));
|
|
422
|
+
return {
|
|
423
|
+
untestedSpecs: Array.isArray(parsed.untestedSpecs) ? parsed.untestedSpecs : undefined,
|
|
424
|
+
orphanFiles: Array.isArray(parsed.orphanFiles) ? parsed.orphanFiles : undefined,
|
|
425
|
+
};
|
|
426
|
+
} catch {
|
|
427
|
+
return {};
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
/**
|
|
432
|
+
* The exemption lists in a conformity-allowlists file, keyed by list name.
|
|
433
|
+
*
|
|
434
|
+
* Every array-valued key is read, not just the two `loadConformityAllowlists`
|
|
435
|
+
* consumes. A list added later must be covered by the growth check the day it
|
|
436
|
+
* appears, not the day someone remembers to add it here — the opposite
|
|
437
|
+
* arrangement is how an exemption mechanism acquires an unwatched corner.
|
|
438
|
+
*/
|
|
439
|
+
export function allowlistEntries(json: string): Record<string, string[]> {
|
|
440
|
+
const parsed = JSON.parse(json);
|
|
441
|
+
const lists: Record<string, string[]> = {};
|
|
442
|
+
for (const [key, value] of Object.entries(parsed)) {
|
|
443
|
+
if (Array.isArray(value)) lists[key] = value.map(String);
|
|
444
|
+
}
|
|
445
|
+
return lists;
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
/**
|
|
449
|
+
* Entries present in `headJson` and absent from `baseJson` (#302).
|
|
450
|
+
*
|
|
451
|
+
* The existing ratchet enforces STALENESS — an entry that stops being a
|
|
452
|
+
* violation fails the build — and that half is real. It does not enforce
|
|
453
|
+
* GROWTH: a new entry for a genuinely new violation is not stale, so every
|
|
454
|
+
* check passes. An agent could introduce a violation and exempt it in the
|
|
455
|
+
* same commit, which is the one move this harness exists to prevent — an
|
|
456
|
+
* agent must not be able to pass a gate by editing the gate.
|
|
457
|
+
*
|
|
458
|
+
* Direction is the whole point. REMOVALS always pass: an agent that fixes a
|
|
459
|
+
* violation and delists it is the case the ratchet is for, and refusing that
|
|
460
|
+
* would trade one outage for another. Only additions are reported.
|
|
461
|
+
*
|
|
462
|
+
* Comparing against `origin/main` rather than the merge base is deliberate
|
|
463
|
+
* and safe in the direction that matters: entries added on main that a branch
|
|
464
|
+
* does not carry read as REMOVALS and pass, so the base can be stale without
|
|
465
|
+
* producing a false refusal.
|
|
466
|
+
*/
|
|
467
|
+
export function allowlistAdditions(baseJson: string, headJson: string): string[] {
|
|
468
|
+
const base = allowlistEntries(baseJson);
|
|
469
|
+
const head = allowlistEntries(headJson);
|
|
470
|
+
const added: string[] = [];
|
|
471
|
+
for (const [list, entries] of Object.entries(head)) {
|
|
472
|
+
const before = new Set(base[list] ?? []);
|
|
473
|
+
for (const entry of entries) {
|
|
474
|
+
if (!before.has(entry)) added.push(`${list}: ${entry}`);
|
|
475
|
+
}
|
|
476
|
+
}
|
|
477
|
+
return added;
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
/**
|
|
481
|
+
* Report a check that did not run, rather than returning silently.
|
|
482
|
+
*
|
|
483
|
+
* A bare `return` on a missing directory reads as a pass in every report, which
|
|
484
|
+
* is the same failure as the `expect(true).toBe(true)` bodies removed in #80 —
|
|
485
|
+
* the check contributes a green tick while verifying nothing. Wording matches
|
|
486
|
+
* the fallow skips so skipped checks are greppable as one class.
|
|
487
|
+
*/
|
|
488
|
+
function checkSkipped(check: string, reason: string): void {
|
|
489
|
+
console.warn(`SKIP ${check}: ${reason} — this check did NOT run.`);
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
function loadBuiltInRegistry(): Array<{ name: string; regex: string }> {
|
|
493
|
+
const key = "__builtin__";
|
|
494
|
+
if (_registryCache.has(key)) return _registryCache.get(key)!;
|
|
495
|
+
const configPath = join(dirname(fileURLToPath(import.meta.url)), "..", "config", "matcher-registry.json");
|
|
496
|
+
const entries: Array<{ name: string; regex: string }> = JSON.parse(readFileSync(configPath, "utf-8"));
|
|
497
|
+
_registryCache.set(key, entries);
|
|
498
|
+
return entries;
|
|
499
|
+
}
|
|
500
|
+
|
|
501
|
+
/**
|
|
502
|
+
* Load the matcher registry, optionally merging consumer-defined custom matchers.
|
|
503
|
+
*
|
|
504
|
+
* When projectRoot is provided, looks for .claude/rungate.json in that directory
|
|
505
|
+
* and merges any `customMatchers` array entries with the built-in registry.
|
|
506
|
+
* Consumer entries with the same `name` as a built-in entry override the built-in.
|
|
507
|
+
*/
|
|
508
|
+
/**
|
|
509
|
+
* `allowBuiltInOverride` is the difference between the AUTHORING view and the
|
|
510
|
+
* VERIFICATION view of the same config, and the two must not be the same.
|
|
511
|
+
*
|
|
512
|
+
* A consumer may name a custom matcher after a built-in, and `create-spec`
|
|
513
|
+
* honours it — that is a documented feature and extending the vocabulary is
|
|
514
|
+
* the point of custom matchers. But the conformity engine is verifying the
|
|
515
|
+
* very project that wrote that config, and `.claude/rungate.json` shadowing
|
|
516
|
+
* `content-contains` with a regex that matches nothing would switch the
|
|
517
|
+
* check off from inside the subject under test. The run would stay green and
|
|
518
|
+
* report nothing unusual, which is the defect class this repo exists to
|
|
519
|
+
* catch, arriving through its own extension point.
|
|
520
|
+
*
|
|
521
|
+
* So the engine takes `allowBuiltInOverride: false`: a consumer may ADD a
|
|
522
|
+
* matcher, never REPLACE one. A shadowing entry is dropped and named, rather
|
|
523
|
+
* than dropped quietly, because a consumer who meant it needs to know it did
|
|
524
|
+
* not take effect.
|
|
525
|
+
*
|
|
526
|
+
* This only became reachable when the runner started passing its project root
|
|
527
|
+
* (#212). Before that the engine ignored consumer config entirely, which is
|
|
528
|
+
* why the asymmetry had never had to be stated.
|
|
529
|
+
*/
|
|
530
|
+
function loadRegistry(
|
|
531
|
+
projectRoot?: string,
|
|
532
|
+
opts?: { allowBuiltInOverride?: boolean },
|
|
533
|
+
): Array<{ name: string; regex: string }> {
|
|
534
|
+
const allowOverride = opts?.allowBuiltInOverride ?? true;
|
|
535
|
+
const cacheKey = `${projectRoot ?? "__builtin__"}::${allowOverride ? "permissive" : "strict"}`;
|
|
536
|
+
if (_registryCache.has(cacheKey)) return _registryCache.get(cacheKey)!;
|
|
537
|
+
|
|
538
|
+
const builtIn = loadBuiltInRegistry();
|
|
539
|
+
if (!projectRoot) {
|
|
540
|
+
return builtIn;
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
// Consumer custom matchers, via the loader (ADR-002 D1, #309). Reading the
|
|
544
|
+
// monolith directly saw nothing on a project that had migrated to the
|
|
545
|
+
// directory layout, so a consumer's custom matchers silently stopped
|
|
546
|
+
// existing the moment they ran the scaffold that migrates them.
|
|
547
|
+
// Named without constructing the path — the loader resolves either layout,
|
|
548
|
+
// so there is no single file to point at, and spelling one out here would
|
|
549
|
+
// be the very access CONFIG-1 forbids in the file that hosts CONFIG-1.
|
|
550
|
+
const configDesc = `the rungate config under ${projectRoot}`;
|
|
551
|
+
let customMatchers: Array<{ name: string; regex: string }>;
|
|
552
|
+
try {
|
|
553
|
+
const config = tryLoadRungateConfig(projectRoot);
|
|
554
|
+
if (!config) {
|
|
555
|
+
_registryCache.set(cacheKey, builtIn);
|
|
556
|
+
return builtIn;
|
|
557
|
+
}
|
|
558
|
+
customMatchers = (config as { customMatchers?: Array<{ name: string; regex: string }> })
|
|
559
|
+
.customMatchers ?? [];
|
|
560
|
+
} catch (err) {
|
|
561
|
+
// Falling back to the built-ins is right — one consumer's broken config
|
|
562
|
+
// must not take the engine's own matchers down with it. Doing it in
|
|
563
|
+
// silence was not: every SC written against a custom matcher then reads
|
|
564
|
+
// as unrecognised, with nothing anywhere saying the config failed to
|
|
565
|
+
// parse (#212).
|
|
566
|
+
//
|
|
567
|
+
// The error's TYPE is reported and its message is not. A parse failure's
|
|
568
|
+
// message routinely quotes the bytes around the offending position, and
|
|
569
|
+
// this file is a project's own config — echoing its contents into build
|
|
570
|
+
// logs is how a secret in a misplaced field reaches somewhere it was
|
|
571
|
+
// never meant to go.
|
|
572
|
+
console.warn(
|
|
573
|
+
`WARN: ${configDesc} could not be read as JSON (${err instanceof Error ? err.name : "error"}; ` +
|
|
574
|
+
`message withheld — it can quote file contents). ` +
|
|
575
|
+
`Falling back to the built-in matcher registry — any customMatchers in that file are NOT loaded, ` +
|
|
576
|
+
`so SCs written against them will be reported as having no matcher.`,
|
|
577
|
+
);
|
|
578
|
+
_registryCache.set(cacheKey, builtIn);
|
|
579
|
+
return builtIn;
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
if (customMatchers.length === 0) {
|
|
583
|
+
_registryCache.set(cacheKey, builtIn);
|
|
584
|
+
return builtIn;
|
|
585
|
+
}
|
|
586
|
+
|
|
587
|
+
const builtInNames = new Set(builtIn.map((e) => e.name));
|
|
588
|
+
const accepted: Array<{ name: string; regex: string }> = [];
|
|
589
|
+
for (const candidate of customMatchers) {
|
|
590
|
+
if (!allowOverride && builtInNames.has(candidate.name)) {
|
|
591
|
+
console.warn(
|
|
592
|
+
`WARN: ${configDesc} defines a custom matcher named "${candidate.name}", which is a built-in. ` +
|
|
593
|
+
`A project cannot replace a built-in matcher while being verified by it — the entry is IGNORED. ` +
|
|
594
|
+
`Rename it to extend the vocabulary instead.`,
|
|
595
|
+
);
|
|
596
|
+
continue;
|
|
597
|
+
}
|
|
598
|
+
// Compiled here rather than at use: a regex that cannot compile would
|
|
599
|
+
// otherwise throw from inside the matcher loop, taking down a run over
|
|
600
|
+
// one bad consumer entry. The entry is refused; the rest still load.
|
|
601
|
+
try {
|
|
602
|
+
new RegExp(candidate.regex, "i");
|
|
603
|
+
} catch {
|
|
604
|
+
console.warn(
|
|
605
|
+
`WARN: ${configDesc} custom matcher "${candidate.name}" has a regex that does not compile — the entry is IGNORED.`,
|
|
606
|
+
);
|
|
607
|
+
continue;
|
|
608
|
+
}
|
|
609
|
+
accepted.push(candidate);
|
|
610
|
+
}
|
|
611
|
+
|
|
612
|
+
// Built-ins first. In the permissive view a shadowing entry has already
|
|
613
|
+
// displaced its built-in; in the strict view it was dropped above, so
|
|
614
|
+
// ordering alone cannot let a consumer entry pre-empt a built-in check.
|
|
615
|
+
const merged = allowOverride
|
|
616
|
+
? [...builtIn.filter((e) => !accepted.some((c) => c.name === e.name)), ...accepted]
|
|
617
|
+
: [...builtIn, ...accepted];
|
|
618
|
+
|
|
619
|
+
_registryCache.set(cacheKey, merged);
|
|
620
|
+
return merged;
|
|
621
|
+
}
|
|
622
|
+
|
|
623
|
+
// ── Compound success criteria (#220) ────────────────────────
|
|
624
|
+
//
|
|
625
|
+
// `content-contains` captures exactly one bracket list and `matchPattern`
|
|
626
|
+
// returns on the first registry hit, so "FILE contains [a] and not contains
|
|
627
|
+
// [b]" bound, asserted [a], and discarded the rest with no signal. 21 ticked
|
|
628
|
+
// SCs were in that state; three of them asserted something false and passed
|
|
629
|
+
// anyway. The sweep is in #220.
|
|
630
|
+
//
|
|
631
|
+
// Two rules the parser follows, both of which a narrower reading gets wrong:
|
|
632
|
+
//
|
|
633
|
+
// - An SC's requirement ends where its explanation begins. Everything from
|
|
634
|
+
// the first " — " is rationale, and rationale saying "the reader and the
|
|
635
|
+
// writer agree" must not become a clause.
|
|
636
|
+
// - The defect is NOT about negation. Two of the 21 carry a POSITIVE second
|
|
637
|
+
// clause naming a different file, and a fix written in terms of
|
|
638
|
+
// "not contains" would leave those just as unasserted.
|
|
639
|
+
|
|
640
|
+
export type SCClause = { file: string; items: string[]; negated: boolean };
|
|
641
|
+
|
|
642
|
+
const CLAUSE_HEAD = /^(\S+)\s+contains?\s+\[([^\]]+)\]/;
|
|
643
|
+
const CLAUSE_TAIL =
|
|
644
|
+
/^\s+and\s+(?:(\S*[./]\S*)\s+)?(not\s+contains?|does\s+not\s+contain|must\s+NOT\s+contain|has\s+no|contains?)\s+\[([^\]]+)\]/i;
|
|
645
|
+
|
|
646
|
+
/** Rationale is commentary, not requirement. */
|
|
647
|
+
const requirementOf = (statement: string) => statement.split(" — ")[0].trimEnd();
|
|
648
|
+
|
|
649
|
+
const splitItems = (raw: string) => raw.split(",").map(i => i.trim()).filter(Boolean);
|
|
153
650
|
|
|
154
|
-
|
|
155
|
-
const s = sc.statement;
|
|
651
|
+
const isCodeFile = (file: string) => /\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(file);
|
|
156
652
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
653
|
+
/**
|
|
654
|
+
* Parse a contains-family statement into every clause it states.
|
|
655
|
+
* Returns null when the statement is not compound, so callers fall through to
|
|
656
|
+
* the single-clause matcher rather than this becoming a second way to bind.
|
|
657
|
+
*/
|
|
658
|
+
export function parseCompoundClauses(statement: string): SCClause[] | null {
|
|
659
|
+
const body = requirementOf(statement);
|
|
660
|
+
const head = CLAUSE_HEAD.exec(body);
|
|
661
|
+
if (!head) return null;
|
|
662
|
+
|
|
663
|
+
const headFile = head[1].replace(/`/g, "");
|
|
664
|
+
const clauses: SCClause[] = [{ file: headFile, items: splitItems(head[2]), negated: false }];
|
|
665
|
+
|
|
666
|
+
let end = head[0].length;
|
|
667
|
+
for (;;) {
|
|
668
|
+
const tail = CLAUSE_TAIL.exec(body.slice(end));
|
|
669
|
+
if (!tail) break;
|
|
670
|
+
end += tail[0].length;
|
|
671
|
+
const verb = tail[2].toLowerCase();
|
|
672
|
+
clauses.push({
|
|
673
|
+
file: (tail[1] ?? headFile).replace(/`/g, ""),
|
|
674
|
+
items: splitItems(tail[3]),
|
|
675
|
+
negated: /\bnot\b|has\s+no/.test(verb),
|
|
676
|
+
});
|
|
677
|
+
}
|
|
678
|
+
return clauses.length > 1 ? clauses : null;
|
|
679
|
+
}
|
|
680
|
+
|
|
681
|
+
/**
|
|
682
|
+
* The guard's view of its own input: text a contains-family statement states
|
|
683
|
+
* but no clause consumed. A leftover bracket list is a requirement that would
|
|
684
|
+
* be silently dropped, so it is named rather than discarded.
|
|
685
|
+
*
|
|
686
|
+
* Prose residue is deliberately NOT refused here. Around eight SCs carry real
|
|
687
|
+
* requirements as prose ("and is under 3,000 tokens"); refusing those turns 39
|
|
688
|
+
* SCs malformed at once, and rewriting them into testable form is #211's work.
|
|
689
|
+
* Returns null for statements no contains-family matcher owns — other matchers
|
|
690
|
+
* answer for their own spans, and "AGENTS.md is under [200] lines" is not a
|
|
691
|
+
* discarded assertion.
|
|
692
|
+
*/
|
|
693
|
+
export function unconsumedAssertion(statement: string): string | null {
|
|
694
|
+
const body = requirementOf(statement);
|
|
695
|
+
const head = CLAUSE_HEAD.exec(body);
|
|
696
|
+
if (!head) return null;
|
|
697
|
+
|
|
698
|
+
let end = head[0].length;
|
|
699
|
+
for (;;) {
|
|
700
|
+
const tail = CLAUSE_TAIL.exec(body.slice(end));
|
|
701
|
+
if (!tail) break;
|
|
702
|
+
end += tail[0].length;
|
|
703
|
+
}
|
|
704
|
+
const residue = body.slice(end).trim();
|
|
705
|
+
return /\[[^\]]+\]/.test(residue) ? residue : null;
|
|
706
|
+
}
|
|
707
|
+
|
|
708
|
+
// Handler registry — one function per pattern type
|
|
709
|
+
const matcherHandlers: Record<string, MatcherHandler> = {
|
|
710
|
+
"file-exists": (sc, match) => {
|
|
711
|
+
const target = match[1].replace(/`/g, "");
|
|
160
712
|
if (target.startsWith("~/") || target.startsWith("/")) return null;
|
|
161
|
-
const limitMatch =
|
|
713
|
+
const limitMatch = sc.statement.match(/≤\s*(\d+)\s*lines/);
|
|
162
714
|
return (root) => {
|
|
163
715
|
expect(existsSync(join(root, target))).toBe(true);
|
|
164
716
|
if (limitMatch) {
|
|
165
717
|
const content = readFileSync(join(root, target), "utf-8");
|
|
166
|
-
|
|
718
|
+
const lineCount = content.trimEnd().split("\n").length;
|
|
719
|
+
expect(lineCount).toBeLessThanOrEqual(parseInt(limitMatch[1]));
|
|
167
720
|
}
|
|
168
721
|
};
|
|
169
|
-
}
|
|
722
|
+
},
|
|
170
723
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
const
|
|
174
|
-
const minMatch = s.match(/(?:with\s+)?≥\s*(\d+)\s+(\w+)/);
|
|
724
|
+
"dir-exists": (sc, match) => {
|
|
725
|
+
const dir = match[1].replace(/`/g, "");
|
|
726
|
+
const minMatch = sc.statement.match(/(?:with\s+)?≥\s*(\d+)\s+(\w+)/);
|
|
175
727
|
const aliases: Record<string, string[]> = {
|
|
176
728
|
"tests": ["tests", "test"],
|
|
177
729
|
"test": ["test", "tests"],
|
|
@@ -180,28 +732,55 @@ function matchPattern(sc: ParsedSC): AssertionFn | null {
|
|
|
180
732
|
const candidates = aliases[dir] || [dir];
|
|
181
733
|
return (root) => {
|
|
182
734
|
const found = candidates.find(d => existsSync(join(root, d)));
|
|
735
|
+
if (!found) {
|
|
736
|
+
addFinding({
|
|
737
|
+
ruleId: "SCAFFOLD-DIR-EXISTS",
|
|
738
|
+
severity: "FAIL",
|
|
739
|
+
file: dir,
|
|
740
|
+
message: `Required directory "${dir}" not found`,
|
|
741
|
+
fixCommand: `mkdir -p ${dir}`,
|
|
742
|
+
});
|
|
743
|
+
}
|
|
183
744
|
expect(found).toBeDefined();
|
|
184
745
|
if (minMatch && found) {
|
|
185
|
-
|
|
746
|
+
const count = readdirSync(join(root, found)).length;
|
|
747
|
+
const required = parseInt(minMatch[1]);
|
|
748
|
+
if (count < required) {
|
|
749
|
+
addFinding({
|
|
750
|
+
ruleId: "SCAFFOLD-DIR-COUNT",
|
|
751
|
+
severity: "FAIL",
|
|
752
|
+
file: found,
|
|
753
|
+
message: `${found}/ has ${count} files (requires ≥${required})`,
|
|
754
|
+
fixCommand: `Add files to ${found}/ — needs at least ${required}`,
|
|
755
|
+
});
|
|
756
|
+
}
|
|
757
|
+
expect(count).toBeGreaterThanOrEqual(required);
|
|
186
758
|
}
|
|
187
759
|
};
|
|
188
|
-
}
|
|
760
|
+
},
|
|
189
761
|
|
|
190
|
-
|
|
762
|
+
"all-specs-frontmatter": (sc) => {
|
|
191
763
|
return (root) => {
|
|
192
764
|
const specsDir = join(root, "specs");
|
|
193
765
|
if (!existsSync(specsDir)) return;
|
|
194
|
-
|
|
766
|
+
|
|
767
|
+
// #225 — the hand-rolled one-level descent that used to live here is
|
|
768
|
+
// now the shared collector, so the seven flat callers get the same
|
|
769
|
+
// behaviour instead of this one site being the only correct reader.
|
|
770
|
+
const specFiles = collectSpecFiles(specsDir);
|
|
771
|
+
|
|
772
|
+
const missing = specFiles.filter(f => {
|
|
195
773
|
const fm = parseFrontmatter(readFileSync(join(specsDir, f), "utf-8"));
|
|
774
|
+
// Skip redirect files (status: split)
|
|
775
|
+
if (fm?.status === "split") return false;
|
|
196
776
|
return !fm || !("testable" in fm);
|
|
197
777
|
});
|
|
198
778
|
expect(missing).toEqual([]);
|
|
199
779
|
};
|
|
200
|
-
}
|
|
780
|
+
},
|
|
201
781
|
|
|
202
|
-
|
|
203
|
-
const
|
|
204
|
-
const target = fileMatch?.[1]?.replace(/`/g, "") || "AGENTS.md";
|
|
782
|
+
"paths-resolve": (sc, match) => {
|
|
783
|
+
const target = match[1]?.replace(/`/g, "") || "AGENTS.md";
|
|
205
784
|
return (root) => {
|
|
206
785
|
const p = join(root, target);
|
|
207
786
|
if (!existsSync(p)) return;
|
|
@@ -215,81 +794,586 @@ function matchPattern(sc: ParsedSC): AssertionFn | null {
|
|
|
215
794
|
}
|
|
216
795
|
expect(broken).toEqual([]);
|
|
217
796
|
};
|
|
218
|
-
}
|
|
797
|
+
},
|
|
219
798
|
|
|
220
|
-
|
|
221
|
-
const contentLimit =
|
|
222
|
-
const codeLimit =
|
|
799
|
+
"root-clean": (sc) => {
|
|
800
|
+
const contentLimit = sc.statement.match(/content:\s*≤\s*(\d+)/i);
|
|
801
|
+
const codeLimit = sc.statement.match(/code:\s*≤\s*(\d+)/i);
|
|
223
802
|
return (root) => {
|
|
224
803
|
const items = readdirSync(root).filter(f => !f.startsWith(".") && f !== "node_modules");
|
|
225
|
-
// Detect project type: if src/, lib/, gates/, or package.json with deps → code project
|
|
226
804
|
const isCode = existsSync(join(root, "src")) || existsSync(join(root, "lib")) ||
|
|
227
805
|
existsSync(join(root, "gates")) || existsSync(join(root, "Makefile"));
|
|
228
806
|
const limit = isCode
|
|
229
807
|
? (codeLimit ? parseInt(codeLimit[1]) : 30)
|
|
230
808
|
: (contentLimit ? parseInt(contentLimit[1]) : 10);
|
|
809
|
+
if (items.length > limit) {
|
|
810
|
+
addFinding({
|
|
811
|
+
ruleId: "SCAFFOLD-ROOT-CLEAN",
|
|
812
|
+
severity: "FAIL",
|
|
813
|
+
file: ".",
|
|
814
|
+
message: `Root has ${items.length} items (limit: ${limit}). Move non-essential files to subdirectories.`,
|
|
815
|
+
fixCommand: `Review root items and move docs to docs/, scripts to scripts/, specs to specs/`,
|
|
816
|
+
});
|
|
817
|
+
}
|
|
231
818
|
expect(items.length).toBeLessThanOrEqual(limit);
|
|
232
819
|
};
|
|
233
|
-
}
|
|
820
|
+
},
|
|
234
821
|
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
const
|
|
238
|
-
const target = pointerMatch[2].replace(/`/g, "");
|
|
822
|
+
"pointer-exists": (sc, match) => {
|
|
823
|
+
const file = match[1].replace(/`/g, "");
|
|
824
|
+
const target = match[2].replace(/`/g, "");
|
|
239
825
|
return (root) => {
|
|
240
|
-
|
|
241
|
-
expect(
|
|
826
|
+
const path = resolveFilePath(root, file);
|
|
827
|
+
expect(existsSync(path)).toBe(true);
|
|
828
|
+
expect(readFileSync(path, "utf-8")).toContain(target);
|
|
242
829
|
};
|
|
243
|
-
}
|
|
830
|
+
},
|
|
244
831
|
|
|
245
|
-
if (/bun\s+test.*passes/i.test(s)) return () => { expect(true).toBe(true); };
|
|
246
832
|
|
|
247
|
-
|
|
833
|
+
"canary": () => {
|
|
248
834
|
return (root) => {
|
|
249
835
|
const testDir = existsSync(join(root, "test")) ? join(root, "test") : join(root, "tests");
|
|
250
836
|
if (!existsSync(testDir)) return;
|
|
251
837
|
const testFiles = readdirSync(testDir).filter(f => f.includes("conformity") || f.includes("canary"));
|
|
252
838
|
expect(testFiles.length).toBeGreaterThanOrEqual(1);
|
|
253
839
|
};
|
|
840
|
+
},
|
|
841
|
+
|
|
842
|
+
"content-contains-compound": (sc) => {
|
|
843
|
+
const clauses = parseCompoundClauses(sc.statement);
|
|
844
|
+
// Not actually compound — fall through so `content-contains` handles it.
|
|
845
|
+
if (!clauses) return null;
|
|
846
|
+
return (root) => {
|
|
847
|
+
for (const clause of clauses) {
|
|
848
|
+
const path = resolveFilePath(root, clause.file);
|
|
849
|
+
if (!existsSync(path)) {
|
|
850
|
+
expect(existsSync(path)).toBe(true);
|
|
851
|
+
return;
|
|
852
|
+
}
|
|
853
|
+
const content = readFileSync(path, "utf-8");
|
|
854
|
+
const view = clause.negated && isCodeFile(clause.file)
|
|
855
|
+
? stripJsComments(content)
|
|
856
|
+
: content;
|
|
857
|
+
for (const item of clause.items) {
|
|
858
|
+
if (clause.negated) {
|
|
859
|
+
expect(view).not.toContain(item);
|
|
860
|
+
} else {
|
|
861
|
+
expect(view).toContain(item);
|
|
862
|
+
}
|
|
863
|
+
}
|
|
864
|
+
}
|
|
865
|
+
};
|
|
866
|
+
},
|
|
867
|
+
|
|
868
|
+
"content-contains": (sc, match) => {
|
|
869
|
+
const file = match[1].replace(/`/g, "");
|
|
870
|
+
const items = match[2].split(",").map(i => i.trim());
|
|
871
|
+
return (root) => {
|
|
872
|
+
const path = resolveFilePath(root, file);
|
|
873
|
+
if (!existsSync(path)) {
|
|
874
|
+
expect(existsSync(path)).toBe(true);
|
|
875
|
+
return;
|
|
876
|
+
}
|
|
877
|
+
const content = readFileSync(path, "utf-8");
|
|
878
|
+
for (const item of items) {
|
|
879
|
+
expect(content).toContain(item);
|
|
880
|
+
}
|
|
881
|
+
};
|
|
882
|
+
},
|
|
883
|
+
|
|
884
|
+
"content-not-contains": (sc, match) => {
|
|
885
|
+
const file = match[1].replace(/`/g, "");
|
|
886
|
+
const items = match[2].split(",").map(i => i.trim());
|
|
887
|
+
return (root) => {
|
|
888
|
+
const path = resolveFilePath(root, file);
|
|
889
|
+
if (!existsSync(path)) {
|
|
890
|
+
expect(existsSync(path)).toBe(true);
|
|
891
|
+
return;
|
|
892
|
+
}
|
|
893
|
+
const content = readFileSync(path, "utf-8");
|
|
894
|
+
for (const item of items) {
|
|
895
|
+
expect(content).not.toContain(item);
|
|
896
|
+
}
|
|
897
|
+
};
|
|
898
|
+
},
|
|
899
|
+
|
|
900
|
+
"count-threshold": (sc, match) => {
|
|
901
|
+
// #225 — the registry's regex is `^(.+?)\s+(?:is under|at most)…`, which
|
|
902
|
+
// is wider than this handler was. "AGENTS.md Rules section at most [200]
|
|
903
|
+
// words" matched, and the whole phrase "AGENTS.md Rules section" was then
|
|
904
|
+
// treated as a path: the file did not exist, so the check failed an SC
|
|
905
|
+
// that the tree satisfies (97 words against a threshold of 200). The
|
|
906
|
+
// registry's own `syntax` field says `{file} is under [N] lines|words`
|
|
907
|
+
// and never promised sections, so the regex admitted a form the handler
|
|
908
|
+
// could not honour — the shape #212 is about, met from the handler side.
|
|
909
|
+
const subject = match[1].replace(/`/g, "").trim();
|
|
910
|
+
const sectionMatch = subject.match(/^(\S+)\s+(.+?)\s+section$/i);
|
|
911
|
+
const file = sectionMatch ? sectionMatch[1] : subject;
|
|
912
|
+
const section = sectionMatch ? sectionMatch[2] : null;
|
|
913
|
+
const threshold = parseInt(match[2]);
|
|
914
|
+
const unit = match[3].toLowerCase();
|
|
915
|
+
// "(excluding tables/headers)" is part of the criterion, not commentary:
|
|
916
|
+
// a Rules section is mostly a table, and counting the table's words
|
|
917
|
+
// measures the opposite of the leanness the SC asks for.
|
|
918
|
+
const excludeTables = /excluding\s+tables/i.test(sc.statement);
|
|
919
|
+
return (root) => {
|
|
920
|
+
const path = join(root, file);
|
|
921
|
+
if (!existsSync(path)) {
|
|
922
|
+
expect(existsSync(path)).toBe(true);
|
|
923
|
+
return;
|
|
924
|
+
}
|
|
925
|
+
let content = readFileSync(path, "utf-8");
|
|
926
|
+
if (section) {
|
|
927
|
+
const lines = content.split("\n");
|
|
928
|
+
const start = lines.findIndex(l => new RegExp(`^#+\\s+${section}\\s*$`, "i").test(l));
|
|
929
|
+
// A named section that is not there is a failure of the criterion,
|
|
930
|
+
// not a reason to measure the whole file and probably pass.
|
|
931
|
+
expect(start, `${file} has no "${section}" section to measure`).toBeGreaterThan(-1);
|
|
932
|
+
const rest = lines.slice(start + 1);
|
|
933
|
+
const end = rest.findIndex(l => /^#+\s/.test(l));
|
|
934
|
+
content = (end === -1 ? rest : rest.slice(0, end)).join("\n");
|
|
935
|
+
}
|
|
936
|
+
if (excludeTables) {
|
|
937
|
+
content = content
|
|
938
|
+
.split("\n")
|
|
939
|
+
.filter(l => !/^\s*\|/.test(l) && !/^#+\s/.test(l))
|
|
940
|
+
.join("\n");
|
|
941
|
+
}
|
|
942
|
+
if (unit.startsWith("line")) {
|
|
943
|
+
const lineCount = content.trimEnd().split("\n").length;
|
|
944
|
+
expect(lineCount).toBeLessThanOrEqual(threshold);
|
|
945
|
+
} else {
|
|
946
|
+
const wordCount = content.split(/\s+/).filter(w => w.length > 0).length;
|
|
947
|
+
expect(wordCount).toBeLessThanOrEqual(threshold);
|
|
948
|
+
}
|
|
949
|
+
};
|
|
950
|
+
},
|
|
951
|
+
|
|
952
|
+
"json-field-equals": (sc, match) => {
|
|
953
|
+
const file = match[1].replace(/`/g, "");
|
|
954
|
+
const field = match[2];
|
|
955
|
+
const expectedValue = match[3];
|
|
956
|
+
return (root) => {
|
|
957
|
+
const path = join(root, file);
|
|
958
|
+
if (!existsSync(path)) {
|
|
959
|
+
expect(existsSync(path)).toBe(true);
|
|
960
|
+
return;
|
|
961
|
+
}
|
|
962
|
+
const content = readFileSync(path, "utf-8");
|
|
963
|
+
const json = JSON.parse(content);
|
|
964
|
+
// Support nested fields like "config.name"
|
|
965
|
+
const fieldParts = field.split(".");
|
|
966
|
+
let value = json;
|
|
967
|
+
for (const part of fieldParts) {
|
|
968
|
+
value = value?.[part];
|
|
969
|
+
}
|
|
970
|
+
expect(value).toBe(expectedValue);
|
|
971
|
+
};
|
|
972
|
+
},
|
|
973
|
+
|
|
974
|
+
"section-exists": (sc, match) => {
|
|
975
|
+
const file = match[1].replace(/`/g, "");
|
|
976
|
+
const sectionName = match[2];
|
|
977
|
+
return (root) => {
|
|
978
|
+
const path = join(root, file);
|
|
979
|
+
if (!existsSync(path)) {
|
|
980
|
+
expect(existsSync(path)).toBe(true);
|
|
981
|
+
return;
|
|
982
|
+
}
|
|
983
|
+
const content = readFileSync(path, "utf-8");
|
|
984
|
+
// Match both # and ## headings
|
|
985
|
+
const hasSection = new RegExp(`^#+ ${sectionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "mi").test(content);
|
|
986
|
+
expect(hasSection).toBe(true);
|
|
987
|
+
};
|
|
988
|
+
},
|
|
989
|
+
|
|
990
|
+
"regex-match": (sc, match) => {
|
|
991
|
+
const file = match[1].replace(/`/g, "");
|
|
992
|
+
const pattern = match[2];
|
|
993
|
+
const flags = match[3] || "";
|
|
994
|
+
return (root) => {
|
|
995
|
+
const path = join(root, file);
|
|
996
|
+
if (!existsSync(path)) {
|
|
997
|
+
expect(existsSync(path)).toBe(true);
|
|
998
|
+
return;
|
|
999
|
+
}
|
|
1000
|
+
const content = readFileSync(path, "utf-8");
|
|
1001
|
+
const regex = new RegExp(pattern, flags);
|
|
1002
|
+
expect(regex.test(content)).toBe(true);
|
|
1003
|
+
};
|
|
1004
|
+
},
|
|
1005
|
+
|
|
1006
|
+
"source-contains": (sc, match) => {
|
|
1007
|
+
const file = match[1].replace(/`/g, "");
|
|
1008
|
+
// Only match if it's a source file path (lib/, scripts/, hooks/, gates/) or has "harness" prefix
|
|
1009
|
+
const isSourceFile = /^(lib|scripts|hooks|gates)\//.test(file) || sc.statement.toLowerCase().includes("harness");
|
|
1010
|
+
if (isSourceFile) {
|
|
1011
|
+
const items = match[2].split(",").map(i => i.trim());
|
|
1012
|
+
return (root) => {
|
|
1013
|
+
const path = join(root, file);
|
|
1014
|
+
if (!existsSync(path)) {
|
|
1015
|
+
expect(existsSync(path)).toBe(true);
|
|
1016
|
+
return;
|
|
1017
|
+
}
|
|
1018
|
+
const content = readFileSync(path, "utf-8");
|
|
1019
|
+
for (const item of items) {
|
|
1020
|
+
expect(content).toContain(item);
|
|
1021
|
+
}
|
|
1022
|
+
};
|
|
1023
|
+
}
|
|
1024
|
+
return null;
|
|
1025
|
+
},
|
|
1026
|
+
|
|
1027
|
+
"json-has-field": (sc, match) => {
|
|
1028
|
+
const file = match[1].replace(/`/g, "");
|
|
1029
|
+
const filePath = file.endsWith(".json") ? file : `${file}.json`;
|
|
1030
|
+
const field = match[2];
|
|
1031
|
+
return (root) => {
|
|
1032
|
+
const path = join(root, filePath);
|
|
1033
|
+
if (!existsSync(path)) {
|
|
1034
|
+
expect(existsSync(path)).toBe(true);
|
|
1035
|
+
return;
|
|
1036
|
+
}
|
|
1037
|
+
const content = readFileSync(path, "utf-8");
|
|
1038
|
+
const json = JSON.parse(content);
|
|
1039
|
+
// Support nested fields like "config.name"
|
|
1040
|
+
const fieldParts = field.split(".");
|
|
1041
|
+
let value = json;
|
|
1042
|
+
for (const part of fieldParts) {
|
|
1043
|
+
value = value?.[part];
|
|
1044
|
+
}
|
|
1045
|
+
expect(value).toBeDefined();
|
|
1046
|
+
};
|
|
1047
|
+
},
|
|
1048
|
+
|
|
1049
|
+
"scaffold-produces": (sc, match) => {
|
|
1050
|
+
const file = match[1].replace(/`/g, "");
|
|
1051
|
+
return (root) => {
|
|
1052
|
+
// For now, this checks if the file exists in the root
|
|
1053
|
+
// A more complete implementation would actually run scaffold and check output
|
|
1054
|
+
const path = join(root, file);
|
|
1055
|
+
expect(existsSync(path)).toBe(true);
|
|
1056
|
+
};
|
|
1057
|
+
},
|
|
1058
|
+
|
|
1059
|
+
"frontmatter-field": (sc, match) => {
|
|
1060
|
+
const file = match[1].replace(/`/g, "");
|
|
1061
|
+
const field = match[2];
|
|
1062
|
+
const expectedValue = match[3]?.trim();
|
|
1063
|
+
return (root) => {
|
|
1064
|
+
const path = join(root, file);
|
|
1065
|
+
if (!existsSync(path)) {
|
|
1066
|
+
expect(existsSync(path)).toBe(true);
|
|
1067
|
+
return;
|
|
1068
|
+
}
|
|
1069
|
+
const content = readFileSync(path, "utf-8");
|
|
1070
|
+
const fm = parseFrontmatter(content);
|
|
1071
|
+
expect(fm).toBeDefined();
|
|
1072
|
+
expect(fm?.[field]).toBeDefined();
|
|
1073
|
+
if (expectedValue !== undefined) {
|
|
1074
|
+
expect(fm?.[field]).toBe(expectedValue);
|
|
1075
|
+
}
|
|
1076
|
+
};
|
|
1077
|
+
},
|
|
1078
|
+
|
|
1079
|
+
"file-line-range": (sc, match) => {
|
|
1080
|
+
const file = match[1].replace(/`/g, "");
|
|
1081
|
+
const min = parseInt(match[2]);
|
|
1082
|
+
const max = parseInt(match[3]);
|
|
1083
|
+
return (root) => {
|
|
1084
|
+
const path = join(root, file);
|
|
1085
|
+
if (!existsSync(path)) {
|
|
1086
|
+
expect(existsSync(path)).toBe(true);
|
|
1087
|
+
return;
|
|
1088
|
+
}
|
|
1089
|
+
const content = readFileSync(path, "utf-8");
|
|
1090
|
+
const lineCount = content.trimEnd().split("\n").length;
|
|
1091
|
+
expect(lineCount).toBeGreaterThanOrEqual(min);
|
|
1092
|
+
expect(lineCount).toBeLessThanOrEqual(max);
|
|
1093
|
+
};
|
|
1094
|
+
},
|
|
1095
|
+
|
|
1096
|
+
"command-output": (sc, match) => {
|
|
1097
|
+
const command = match[1];
|
|
1098
|
+
const items = match[2].split(",").map(i => i.trim());
|
|
1099
|
+
return (root) => {
|
|
1100
|
+
const result = spawnSync("sh", ["-c", command], {
|
|
1101
|
+
cwd: root,
|
|
1102
|
+
timeout: 10000,
|
|
1103
|
+
encoding: "utf-8",
|
|
1104
|
+
env: { ...process.env },
|
|
1105
|
+
});
|
|
1106
|
+
const exitCode = result.status ?? 1;
|
|
1107
|
+
expect(exitCode).toBe(0);
|
|
1108
|
+
const stdout = result.stdout || "";
|
|
1109
|
+
for (const item of items) {
|
|
1110
|
+
expect(stdout.includes(item)).toBe(true);
|
|
1111
|
+
}
|
|
1112
|
+
};
|
|
1113
|
+
},
|
|
1114
|
+
};
|
|
1115
|
+
|
|
1116
|
+
/**
|
|
1117
|
+
* The names the engine can actually assert. Exported so the registry can be
|
|
1118
|
+
* reconciled against it (#212) instead of the two drifting apart unobserved —
|
|
1119
|
+
* `matchPattern` iterates the REGISTRY, so a handler missing from it is
|
|
1120
|
+
* unreachable however well tested, and an entry missing a handler asserts
|
|
1121
|
+
* nothing while still matching the author's syntax.
|
|
1122
|
+
*/
|
|
1123
|
+
export function matcherHandlerNames(): string[] {
|
|
1124
|
+
return Object.keys(matcherHandlers);
|
|
1125
|
+
}
|
|
1126
|
+
|
|
1127
|
+
/**
|
|
1128
|
+
* Why a statement did or did not become an assertion.
|
|
1129
|
+
*
|
|
1130
|
+
* `matchPattern` answered `null` for two different situations, and collapsing
|
|
1131
|
+
* them is the defect in #212: a statement that matched a registry regex whose
|
|
1132
|
+
* entry has no handler was reported exactly like a statement that matched
|
|
1133
|
+
* nothing at all. The first means "recognised, and nothing implements it";
|
|
1134
|
+
* the second means "unrecognised". SUCCESS.md claim 4 — "could not measure"
|
|
1135
|
+
* must never read as "nothing wrong" — needs them distinct.
|
|
1136
|
+
*/
|
|
1137
|
+
export type MatcherResolution =
|
|
1138
|
+
| { kind: "assert"; matcher: string; assertion: AssertionFn }
|
|
1139
|
+
| { kind: "unimplemented"; matcher: string }
|
|
1140
|
+
| { kind: "unrecognised" };
|
|
1141
|
+
|
|
1142
|
+
export function resolveMatcher(sc: ParsedSC, projectRoot?: string): MatcherResolution {
|
|
1143
|
+
// Strict view: the project being verified may add matchers, never replace a
|
|
1144
|
+
// built-in one. See loadRegistry's docblock — `isMatchablePattern` keeps the
|
|
1145
|
+
// permissive view because it answers an authoring question, not a
|
|
1146
|
+
// verification one.
|
|
1147
|
+
const registry = loadRegistry(projectRoot, { allowBuiltInOverride: false });
|
|
1148
|
+
let recognisedBy: string | null = null;
|
|
1149
|
+
|
|
1150
|
+
for (const entry of registry) {
|
|
1151
|
+
const regex = new RegExp(entry.regex, "i");
|
|
1152
|
+
const match = sc.statement.match(regex);
|
|
1153
|
+
if (!match) continue;
|
|
1154
|
+
|
|
1155
|
+
const handler = matcherHandlers[entry.name];
|
|
1156
|
+
if (!handler) {
|
|
1157
|
+
// Recognised. Remember which matcher claimed it, but keep looking — a
|
|
1158
|
+
// later entry may both match and be implemented, and that is a better
|
|
1159
|
+
// answer than refusing.
|
|
1160
|
+
recognisedBy ??= entry.name;
|
|
1161
|
+
continue;
|
|
1162
|
+
}
|
|
1163
|
+
const result = handler(sc, match);
|
|
1164
|
+
if (result) return { kind: "assert", matcher: entry.name, assertion: result };
|
|
1165
|
+
}
|
|
1166
|
+
|
|
1167
|
+
return recognisedBy ? { kind: "unimplemented", matcher: recognisedBy } : { kind: "unrecognised" };
|
|
1168
|
+
}
|
|
1169
|
+
|
|
1170
|
+
export function matchPattern(sc: ParsedSC, projectRoot?: string): AssertionFn | null {
|
|
1171
|
+
const outcome = resolveMatcher(sc, projectRoot);
|
|
1172
|
+
return outcome.kind === "assert" ? outcome.assertion : null;
|
|
1173
|
+
}
|
|
1174
|
+
|
|
1175
|
+
/**
|
|
1176
|
+
* Check if an SC statement matches any pattern in the registry (built-in + consumer).
|
|
1177
|
+
* Unlike matchPattern, this only checks regex matches — it does not require a handler.
|
|
1178
|
+
* Used by create-spec for SC validation: a consumer custom pattern without a handler
|
|
1179
|
+
* is still a valid SC pattern for specification purposes.
|
|
1180
|
+
*/
|
|
1181
|
+
export function isMatchablePattern(sc: ParsedSC, projectRoot?: string): boolean {
|
|
1182
|
+
const registry = loadRegistry(projectRoot);
|
|
1183
|
+
for (const entry of registry) {
|
|
1184
|
+
const regex = new RegExp(entry.regex, "i");
|
|
1185
|
+
if (regex.test(sc.statement)) {
|
|
1186
|
+
return true;
|
|
1187
|
+
}
|
|
254
1188
|
}
|
|
1189
|
+
return false;
|
|
1190
|
+
}
|
|
1191
|
+
|
|
1192
|
+
// ── SC → test binding ───────────────────────────────────────
|
|
1193
|
+
|
|
1194
|
+
/**
|
|
1195
|
+
* How a single SC becomes (or fails to become) a test.
|
|
1196
|
+
*
|
|
1197
|
+
* Kept as data, separate from `describe`/`test`, so the binding rules can be
|
|
1198
|
+
* asserted directly — see test/conformity-sc-binding.test.ts. The important
|
|
1199
|
+
* property is that an `assert` entry hands back the RAW assertion: nothing
|
|
1200
|
+
* here catches, so a failing checked SC fails the suite.
|
|
1201
|
+
*/
|
|
1202
|
+
export type SCPlanEntry =
|
|
1203
|
+
| { kind: "behavioral"; sc: ParsedSC; routing: string | null }
|
|
1204
|
+
| { kind: "todo"; sc: ParsedSC }
|
|
1205
|
+
| { kind: "unmatched"; sc: ParsedSC }
|
|
1206
|
+
| { kind: "unimplemented"; sc: ParsedSC; matcher: string }
|
|
1207
|
+
| { kind: "assert"; sc: ParsedSC; assertion: AssertionFn };
|
|
255
1208
|
|
|
256
|
-
|
|
1209
|
+
/**
|
|
1210
|
+
* Decide what each SC becomes:
|
|
1211
|
+
* behavioral — runtime-only, routed to SESSION-AUDIT-SPEC
|
|
1212
|
+
* todo — unchecked, i.e. work not started; never a silent assertion
|
|
1213
|
+
* assert — checked and matchable; runs for real and may fail
|
|
1214
|
+
* unmatched — checked but the statement binds to no matcher: a coverage
|
|
1215
|
+
* gap, reported and ratcheted rather than silently dropped
|
|
1216
|
+
* unimplemented — checked, and the statement DID match a registry entry
|
|
1217
|
+
* that has no handler. Reported apart from `unmatched`
|
|
1218
|
+
* because "recognised and nothing implements it" is a
|
|
1219
|
+
* different defect from "unrecognised", and the author of
|
|
1220
|
+
* such an SC was told by create-spec that it was valid (#212)
|
|
1221
|
+
*/
|
|
1222
|
+
export function planSCTests(scs: ParsedSC[], projectRoot?: string): SCPlanEntry[] {
|
|
1223
|
+
return scs.map((sc): SCPlanEntry => {
|
|
1224
|
+
if (isBehavioralSC(sc)) return { kind: "behavioral", sc, routing: getBehavioralRouting(sc) };
|
|
1225
|
+
if (!sc.checked) return { kind: "todo", sc };
|
|
1226
|
+
const outcome = resolveMatcher(sc, projectRoot);
|
|
1227
|
+
if (outcome.kind === "assert") return { kind: "assert", sc, assertion: outcome.assertion };
|
|
1228
|
+
if (outcome.kind === "unimplemented") return { kind: "unimplemented", sc, matcher: outcome.matcher };
|
|
1229
|
+
return { kind: "unmatched", sc };
|
|
1230
|
+
});
|
|
257
1231
|
}
|
|
258
1232
|
|
|
259
1233
|
// ── Exported test runners ───────────────────────────────────
|
|
260
1234
|
|
|
261
1235
|
export function runScaffoldConformity(root: string, opts?: { extraSpecDirs?: string[] }) {
|
|
262
|
-
const
|
|
263
|
-
const
|
|
264
|
-
|
|
1236
|
+
const specMap = collectTestableSpecs(root, opts?.extraSpecDirs ?? []);
|
|
1237
|
+
const specsDir = join(root, "specs");
|
|
1238
|
+
|
|
1239
|
+
function resolveSpecPath(specFile: string): string {
|
|
1240
|
+
if (specFile.includes("/")) {
|
|
1241
|
+
const parts = specFile.split("/");
|
|
1242
|
+
for (const dir of opts?.extraSpecDirs ?? []) {
|
|
1243
|
+
if (dir.endsWith(parts[0])) return join(dir, parts.slice(1).join("/"));
|
|
1244
|
+
}
|
|
1245
|
+
}
|
|
1246
|
+
return join(specsDir, specFile);
|
|
1247
|
+
}
|
|
265
1248
|
|
|
266
1249
|
describe("Spec-Driven Conformity Tests", () => {
|
|
267
|
-
if (
|
|
268
|
-
test("at least one testable spec with SCs exists", () => {
|
|
269
|
-
expect(allSCs.length).toBeGreaterThan(0);
|
|
270
|
-
});
|
|
1250
|
+
if (specMap.size === 0) {
|
|
1251
|
+
test.skip("at least one testable spec with SCs exists (no specs found — consumer project)", () => {});
|
|
271
1252
|
return;
|
|
272
1253
|
}
|
|
273
1254
|
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
1255
|
+
// No afterAll checkbox flip here, deliberately (#86).
|
|
1256
|
+
//
|
|
1257
|
+
// This describe builds its test list at collection time by reading SC
|
|
1258
|
+
// checkboxes off disk. Writing those same files back at the end of the run
|
|
1259
|
+
// meant run N mutated the input run N+1 collected from, so the generated
|
|
1260
|
+
// test list alternated between two shapes — 57 tests, then 99, then 57.
|
|
1261
|
+
// Both parities reported 0 fail, so nothing ever surfaced it: the suite was
|
|
1262
|
+
// not hiding a failure, it was hiding whether 42 checks ran at all.
|
|
1263
|
+
//
|
|
1264
|
+
// Checkbox syncing still happens, deliberately and separately, via the
|
|
1265
|
+
// `posttest` hook in package.json -> scripts/sync-sc-status.ts. That script
|
|
1266
|
+
// re-derives pass state from the specs itself rather than riding on a test
|
|
1267
|
+
// run's in-memory bookkeeping, so it is not load-bearing for this suite and
|
|
1268
|
+
// nothing is lost by removing the hook.
|
|
1269
|
+
|
|
1270
|
+
for (const [specFile, metadata] of specMap) {
|
|
282
1271
|
describe(specFile, () => {
|
|
283
1272
|
const unmatched: string[] = [];
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
1273
|
+
const unimplemented: string[] = [];
|
|
1274
|
+
const behavioral: string[] = [];
|
|
1275
|
+
const specPath = resolveSpecPath(specFile);
|
|
1276
|
+
// `root`, not nothing: without it `loadRegistry` never reads the
|
|
1277
|
+
// consumer's `.claude/rungate.json`, so every custom matcher is
|
|
1278
|
+
// invisible to the engine while `create-spec` — which DOES pass a
|
|
1279
|
+
// project root to `isMatchablePattern` — accepts criteria written
|
|
1280
|
+
// against them. That is the authoring-tool/engine divergence in #212,
|
|
1281
|
+
// and it was not hypothetical: the planted-project test in
|
|
1282
|
+
// test/matcher-registry-parity.test.ts reported its criterion as
|
|
1283
|
+
// `unmatched` until this argument was supplied.
|
|
1284
|
+
for (const entry of planSCTests(metadata.scs, root)) {
|
|
1285
|
+
const { sc } = entry;
|
|
1286
|
+
if (entry.kind === "behavioral") {
|
|
1287
|
+
behavioral.push(`${sc.id}: ${sc.statement} → ${entry.routing}`);
|
|
1288
|
+
} else if (entry.kind === "todo") {
|
|
1289
|
+
// bun-types declares test.todo as requiring a body even though the
|
|
1290
|
+
// runtime accepts a bare label. A no-op body satisfies both: todo
|
|
1291
|
+
// tests are not executed unless `bun test --todo` is passed.
|
|
1292
|
+
test.todo(`${sc.id}: ${sc.statement}`, () => {});
|
|
1293
|
+
} else if (entry.kind === "unmatched") {
|
|
1294
|
+
unmatched.push(`${sc.id}: ${sc.statement}`);
|
|
1295
|
+
} else if (entry.kind === "unimplemented") {
|
|
1296
|
+
// Not folded into `unmatched`: this SC's syntax WAS recognised,
|
|
1297
|
+
// and create-spec would have told its author it was valid. The
|
|
1298
|
+
// gap is a registry entry with no handler, which is a different
|
|
1299
|
+
// thing to fix and a different thing to report (#212).
|
|
1300
|
+
unimplemented.push(`${sc.id}: matched "${entry.matcher}", which has no handler — ${sc.statement}`);
|
|
1301
|
+
} else {
|
|
1302
|
+
// A CHECKED SC claims the work is done. Run its assertion for
|
|
1303
|
+
// real: no try/catch, so it fails the suite when the claim is
|
|
1304
|
+
// false. The old body swallowed the throw, which is why 13 false
|
|
1305
|
+
// claims sat green for months (#209).
|
|
1306
|
+
test(`${sc.id}: ${sc.statement}`, () => {
|
|
1307
|
+
entry.assertion(root);
|
|
1308
|
+
recordPassingSC(sc.id, specPath);
|
|
1309
|
+
});
|
|
1310
|
+
}
|
|
1311
|
+
}
|
|
1312
|
+
if (behavioral.length > 0) {
|
|
1313
|
+
addBehavioralCount(behavioral.length);
|
|
1314
|
+
// This is a REPORT, not a test, and that is the fix (#328).
|
|
1315
|
+
//
|
|
1316
|
+
// It used to be a `test()` whose body was `expect(true).toBe(true)`
|
|
1317
|
+
// — shape three in .claude/rules/checks-must-be-able-to-fail.md,
|
|
1318
|
+
// written out literally rather than arrived at by accident, and the
|
|
1319
|
+
// only executable check on 40 ticked criteria.
|
|
1320
|
+
//
|
|
1321
|
+
// The first attempt at a repair kept the `test()` and asserted that
|
|
1322
|
+
// every listed SC carries the `(behavioral)` marker. The mutation
|
|
1323
|
+
// harness measured that at ZERO red, and it was right to: this list
|
|
1324
|
+
// is only ever appended to when `entry.kind === "behavioral"`, which
|
|
1325
|
+
// happens only when `isBehavioralSC(sc)` is already true. The
|
|
1326
|
+
// assertion was a tautology — a second unfalsifiable check wearing
|
|
1327
|
+
// the first one's clothes.
|
|
1328
|
+
//
|
|
1329
|
+
// There is nothing locally falsifiable to put here. Whether a
|
|
1330
|
+
// behavioral criterion is SATISFIED is a runtime question this file
|
|
1331
|
+
// cannot answer, and whether it is CLASSIFIED correctly is true by
|
|
1332
|
+
// construction. So the slot stops pretending: the listing stays,
|
|
1333
|
+
// because findability is genuinely useful, and the teeth live in
|
|
1334
|
+
// test/behavioral-sc-ratchet.test.ts, which bounds the population
|
|
1335
|
+
// and which the same harness measures at 1 red when slackened.
|
|
1336
|
+
//
|
|
1337
|
+
// A report that admits it is a report is strictly better than a test
|
|
1338
|
+
// that cannot fail, because only one of them is counted as evidence.
|
|
1339
|
+
console.log(
|
|
1340
|
+
`Behavioral SCs in ${specFile} — NOT VERIFIED HERE, bounded by ` +
|
|
1341
|
+
`BEHAVIORAL_TICKED_RATCHET (#328):\n ${behavioral.join("\n ")}`,
|
|
1342
|
+
);
|
|
288
1343
|
}
|
|
289
1344
|
if (unmatched.length > 0) {
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
1345
|
+
// SC-287 used to FAIL here in strict mode. That branch had never
|
|
1346
|
+
// fired: the only SCs that reached it were unchecked ones, and
|
|
1347
|
+
// unchecked SCs now become `todo` before the matcher runs. The
|
|
1348
|
+
// population is now CHECKED SCs written in prose no matcher binds
|
|
1349
|
+
// to — 54 of them on the day they first became visible (#209).
|
|
1350
|
+
//
|
|
1351
|
+
// Failing 54 specs at once would get the whole file skipped, so the
|
|
1352
|
+
// teeth live in a single repo-wide ratchet instead:
|
|
1353
|
+
// test/conformity-sc-binding.test.ts asserts the total may fall but
|
|
1354
|
+
// never rise. Here we name them, per spec, so they are findable.
|
|
1355
|
+
const level = metadata.compliance === "permissive" ? "WARN" : "WARN (strict)";
|
|
1356
|
+
test(`${level}: ${unmatched.length} checked SCs have no pattern matcher`, () => {
|
|
1357
|
+
console.warn(`Unmatched checked SCs in ${specFile}:\n ${unmatched.join("\n ")}`);
|
|
1358
|
+
expect(unmatched.length).toBeGreaterThan(0);
|
|
1359
|
+
});
|
|
1360
|
+
}
|
|
1361
|
+
// Deliberately BELOW the unmatched branch, not between it and the
|
|
1362
|
+
// behavioral report. #328's guard slices the source from the
|
|
1363
|
+
// behavioral branch to `if (unmatched.length > 0) {` and asserts that
|
|
1364
|
+
// region contains no `test(` — the behavioral slot must stay a report.
|
|
1365
|
+
// This block legitimately IS a test, so placing it in that window
|
|
1366
|
+
// turns #328's guard red. The guard is right; this belongs here.
|
|
1367
|
+
if (unimplemented.length > 0) {
|
|
1368
|
+
// Unlike the unmatched aggregate above, this one FAILS, and it can
|
|
1369
|
+
// afford to: the population is zero in this repo and the parity
|
|
1370
|
+
// test in test/matcher-registry-parity.test.ts keeps it there, so
|
|
1371
|
+
// it cannot turn specs red en masse. A registry entry with no
|
|
1372
|
+
// handler is a harness defect, not a backlog of prose criteria
|
|
1373
|
+
// waiting to be rewritten — the author was told by create-spec that
|
|
1374
|
+
// their syntax was valid, and the engine then asserted nothing.
|
|
1375
|
+
test(`FAIL: ${unimplemented.length} SCs matched a registry entry that has no handler`, () => {
|
|
1376
|
+
expect(unimplemented).toEqual([]);
|
|
293
1377
|
});
|
|
294
1378
|
}
|
|
295
1379
|
});
|
|
@@ -299,19 +1383,28 @@ export function runScaffoldConformity(root: string, opts?: { extraSpecDirs?: str
|
|
|
299
1383
|
describe("Scaffold: structural checks", () => {
|
|
300
1384
|
test("AGENTS.md has required standard sections", () => {
|
|
301
1385
|
if (!existsSync(join(root, "AGENTS.md"))) {
|
|
1386
|
+
addFinding({ ruleId: "SCAFFOLD-AGENTS-MISSING", severity: "FAIL", file: "AGENTS.md", message: "AGENTS.md not found", fixCommand: "Run scaffold to generate AGENTS.md" });
|
|
302
1387
|
expect(existsSync(join(root, "AGENTS.md"))).toBe(true);
|
|
303
1388
|
return;
|
|
304
1389
|
}
|
|
305
1390
|
const content = readFileSync(join(root, "AGENTS.md"), "utf-8");
|
|
306
|
-
const required = ["Project Identity", "
|
|
1391
|
+
const required = ["Project Identity", "Rules", "Commands", "Workflow"];
|
|
307
1392
|
const missing = required.filter(s => !content.toLowerCase().includes(s.toLowerCase()));
|
|
1393
|
+
if (missing.length > 0) {
|
|
1394
|
+
addFinding({ ruleId: "SCAFFOLD-AGENTS-SECTIONS", severity: "FAIL", file: "AGENTS.md", message: `Missing sections: ${missing.join(", ")}`, fixCommand: "Re-run scaffold to regenerate AGENTS.md" });
|
|
1395
|
+
}
|
|
308
1396
|
expect(missing).toEqual([]);
|
|
309
1397
|
});
|
|
310
1398
|
|
|
311
|
-
test("rungate
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
1399
|
+
test("rungate config has required fields (if configured)", () => {
|
|
1400
|
+
// Through the loader (ADR-002 D1, #309). Reading the monolith directly
|
|
1401
|
+
// meant a project on the directory layout skipped this check entirely —
|
|
1402
|
+
// `existsSync` was false, the test returned, and a config missing
|
|
1403
|
+
// `project` or `repo` passed by never being looked at. Exactly the
|
|
1404
|
+
// shape .claude/rules/checks-must-be-able-to-fail.md opens with, in the
|
|
1405
|
+
// check that validates config.
|
|
1406
|
+
const config = tryLoadRungateConfig(root);
|
|
1407
|
+
if (!config) return;
|
|
315
1408
|
expect(config.project).toBeDefined();
|
|
316
1409
|
expect(config.repo).toBeDefined();
|
|
317
1410
|
});
|
|
@@ -336,25 +1429,56 @@ export function runSpecDiscovery(root: string) {
|
|
|
336
1429
|
|
|
337
1430
|
test("every .md in specs/ has testable field", () => {
|
|
338
1431
|
if (!existsSync(specsDir)) return;
|
|
339
|
-
const missing =
|
|
1432
|
+
const missing = collectSpecFiles(specsDir).filter(f => {
|
|
340
1433
|
const fm = parseFrontmatter(readFileSync(join(specsDir, f), "utf-8"));
|
|
341
1434
|
return !fm || !("testable" in fm);
|
|
342
1435
|
});
|
|
1436
|
+
for (const f of missing) {
|
|
1437
|
+
addFinding({ ruleId: "SPEC-FRONTMATTER", severity: "FAIL", file: `specs/${f}`, message: `Spec "${f}" missing testable field in frontmatter`, fixCommand: `Add "testable: true" or "testable: false" to frontmatter of specs/${f}` });
|
|
1438
|
+
}
|
|
343
1439
|
expect(missing).toEqual([]);
|
|
344
1440
|
});
|
|
345
1441
|
|
|
346
1442
|
test("at least one testable spec exists", () => {
|
|
347
1443
|
if (!existsSync(specsDir)) return;
|
|
348
|
-
const testable =
|
|
1444
|
+
const testable = collectSpecFiles(specsDir).filter(f => {
|
|
349
1445
|
const fm = parseFrontmatter(readFileSync(join(specsDir, f), "utf-8"));
|
|
350
1446
|
return fm?.testable === "true";
|
|
351
1447
|
});
|
|
352
|
-
|
|
1448
|
+
if (testable.length === 0) {
|
|
1449
|
+
addFinding({
|
|
1450
|
+
ruleId: "SPEC-DISCOVERY-TESTABLE",
|
|
1451
|
+
severity: "WARN",
|
|
1452
|
+
file: "specs/",
|
|
1453
|
+
message: "No spec has testable: true. Add testable: true to a spec when ready for conformity testing.",
|
|
1454
|
+
fixCommand: `Add "testable: true" to frontmatter of a spec in specs/`,
|
|
1455
|
+
});
|
|
1456
|
+
console.warn("SPEC-DISCOVERY: No testable specs found — skipping (add testable: true when ready)");
|
|
1457
|
+
} else {
|
|
1458
|
+
expect(testable.length).toBeGreaterThan(0);
|
|
1459
|
+
}
|
|
353
1460
|
});
|
|
354
1461
|
});
|
|
355
1462
|
}
|
|
356
1463
|
|
|
357
|
-
|
|
1464
|
+
/**
|
|
1465
|
+
* @param options.untestedAllowlist Specs permitted to have no referencing test,
|
|
1466
|
+
* owned by the CALLING project. Omitted means the caller has not adopted the
|
|
1467
|
+
* ratchet, and DRIFT-2 reports advisory instead of failing — see the comment
|
|
1468
|
+
* on DRIFT-2 for why a consumer must not inherit rungate's backlog.
|
|
1469
|
+
*
|
|
1470
|
+
* The allowlist is deliberately in `options`, not position 2: the consumer test
|
|
1471
|
+
* that lib/scaffold/steps.ts generates calls `runSpecDrift(ROOT, findings)`, so
|
|
1472
|
+
* a positional second parameter would receive a findings array and exempt
|
|
1473
|
+
* nothing, failing every consumer build.
|
|
1474
|
+
*/
|
|
1475
|
+
export function runSpecDrift(
|
|
1476
|
+
root: string,
|
|
1477
|
+
_findings?: unknown[],
|
|
1478
|
+
options?: { untestedAllowlist?: string[] },
|
|
1479
|
+
) {
|
|
1480
|
+
const untestedAllowlist =
|
|
1481
|
+
options?.untestedAllowlist ?? loadConformityAllowlists(root).untestedSpecs;
|
|
358
1482
|
const specsDir = join(root, "specs");
|
|
359
1483
|
const testDirs = [join(root, "test"), join(root, "tests")].filter(d => existsSync(d));
|
|
360
1484
|
|
|
@@ -387,8 +1511,8 @@ export function runSpecDrift(root: string) {
|
|
|
387
1511
|
});
|
|
388
1512
|
|
|
389
1513
|
test("DRIFT-2: Every testable spec is referenced by at least one test", () => {
|
|
390
|
-
if (!existsSync(specsDir)) return;
|
|
391
|
-
const testable =
|
|
1514
|
+
if (!existsSync(specsDir)) return checkSkipped("DRIFT-2", "no specs/ directory");
|
|
1515
|
+
const testable = collectSpecFiles(specsDir).filter(f => {
|
|
392
1516
|
const fm = parseFrontmatter(readFileSync(join(specsDir, f), "utf-8"));
|
|
393
1517
|
return fm?.testable === "true";
|
|
394
1518
|
});
|
|
@@ -401,15 +1525,170 @@ export function runSpecDrift(root: string) {
|
|
|
401
1525
|
}
|
|
402
1526
|
|
|
403
1527
|
const orphaned = testable.filter(s => !allContent.includes(s));
|
|
404
|
-
|
|
405
|
-
|
|
1528
|
+
|
|
1529
|
+
// Was `expect(true).toBe(true)` after a console.warn, so the mechanical
|
|
1530
|
+
// enforcement of CLAUDE.md's "SCs without tests are wishes" could never
|
|
1531
|
+
// fail (#80). Turning it on revealed 10 testable specs in rungate with no
|
|
1532
|
+
// test referencing them at all — over half the testable surface.
|
|
1533
|
+
//
|
|
1534
|
+
// That backlog cannot be asserted to zero without writing ten tests, so
|
|
1535
|
+
// adopters pass a RATCHET list: anything on it may stay untested, an
|
|
1536
|
+
// addition fails the build, and a listed spec that GAINS a test must be
|
|
1537
|
+
// delisted or the build fails — otherwise the allowlist rots into another
|
|
1538
|
+
// artifact that certifies nothing.
|
|
1539
|
+
//
|
|
1540
|
+
// The list belongs to the CALLING PROJECT, never to this file. An earlier
|
|
1541
|
+
// version hardcoded rungate's ten spec filenames here, and
|
|
1542
|
+
// lib/scaffold/steps.ts generates a consumer conformity test that calls
|
|
1543
|
+
// this function — so every consumer inherited rungate's backlog. A
|
|
1544
|
+
// consumer with an untested spec of a matching name was silently
|
|
1545
|
+
// exempted, and a consumer that HAD such a spec with a test failed its
|
|
1546
|
+
// own build demanding it delist an entry from a file inside rungate that
|
|
1547
|
+
// it cannot edit.
|
|
1548
|
+
if (!untestedAllowlist) {
|
|
1549
|
+
// No ratchet adopted. Report, but do not fail: before #80 this check
|
|
1550
|
+
// could not fail at all, so failing here would break every existing
|
|
1551
|
+
// consumer on upgrade for a backlog they never opted into.
|
|
1552
|
+
if (orphaned.length > 0) {
|
|
1553
|
+
console.warn(
|
|
1554
|
+
`WARN DRIFT-2: ${orphaned.length} testable spec(s) have no referencing test — ` +
|
|
1555
|
+
`${orphaned.join(", ")}. This check is ADVISORY because no untestedAllowlist ` +
|
|
1556
|
+
`was supplied. Pass one to runSpecDrift to enforce it as a ratchet.`,
|
|
1557
|
+
);
|
|
1558
|
+
}
|
|
1559
|
+
return;
|
|
406
1560
|
}
|
|
407
|
-
|
|
1561
|
+
|
|
1562
|
+
const newlyOrphaned = orphaned.filter(s => !untestedAllowlist.includes(s));
|
|
1563
|
+
expect(newlyOrphaned).toEqual([]);
|
|
1564
|
+
|
|
1565
|
+
const staleAllowlist = untestedAllowlist.filter(
|
|
1566
|
+
s => testable.includes(s) && !orphaned.includes(s),
|
|
1567
|
+
);
|
|
1568
|
+
expect(staleAllowlist).toEqual([]);
|
|
1569
|
+
});
|
|
1570
|
+
|
|
1571
|
+
test("DRIFT-3: the exemption lists did not GROW", () => {
|
|
1572
|
+
// #302. The staleness checks above enforce one direction: an entry that
|
|
1573
|
+
// stops being a violation fails. A NEW entry for a genuinely new
|
|
1574
|
+
// violation is not stale, so until now an agent could introduce a
|
|
1575
|
+
// conformity violation and exempt it in the same commit — passing a
|
|
1576
|
+
// gate by editing the gate, which is the one move this harness exists
|
|
1577
|
+
// to refuse.
|
|
1578
|
+
//
|
|
1579
|
+
// It sits here rather than in the collection guard deliberately. The
|
|
1580
|
+
// collection guard sees paths, not contents, and would catch only
|
|
1581
|
+
// growth arriving via agent collection — not a human commit, a heal
|
|
1582
|
+
// round, or a single-worktree run that bypasses collection entirely.
|
|
1583
|
+
const allowlistPath = join(root, ".claude", "conformity-allowlists.json");
|
|
1584
|
+
if (!existsSync(allowlistPath)) return;
|
|
1585
|
+
|
|
1586
|
+
const show = spawnSync("git", ["-C", root, "show", `origin/main:.claude/conformity-allowlists.json`], {
|
|
1587
|
+
encoding: "utf-8",
|
|
1588
|
+
timeout: 20_000,
|
|
1589
|
+
});
|
|
1590
|
+
|
|
1591
|
+
if (show.error || show.status !== 0) {
|
|
1592
|
+
// ADVISORY, not a refusal, and only here. A consumer may legitimately
|
|
1593
|
+
// have no `origin/main` — a fresh scaffold, a local-only repo — and
|
|
1594
|
+
// refusing for want of a comparison base would break every one of
|
|
1595
|
+
// them on upgrade for a rule they never opted into. That is the same
|
|
1596
|
+
// judgement loadConformityAllowlists already makes about a missing
|
|
1597
|
+
// allowlist file. rungate's own suite asserts the base IS readable,
|
|
1598
|
+
// because in this repo an unreadable one is a fault, not a setup.
|
|
1599
|
+
console.warn(
|
|
1600
|
+
`WARN DRIFT-3: could not read origin/main's copy of the conformity allowlist, so ` +
|
|
1601
|
+
`growth was NOT checked. This is UNMEASURED, not clean.`,
|
|
1602
|
+
);
|
|
1603
|
+
return;
|
|
1604
|
+
}
|
|
1605
|
+
|
|
1606
|
+
const added = allowlistAdditions(show.stdout, readFileSync(allowlistPath, "utf-8"));
|
|
1607
|
+
expect(
|
|
1608
|
+
added,
|
|
1609
|
+
`an exemption was ADDED relative to origin/main. Fix the violation, or make the ` +
|
|
1610
|
+
`exemption a deliberate recorded decision rather than a diff.`,
|
|
1611
|
+
).toEqual([]);
|
|
408
1612
|
});
|
|
409
1613
|
});
|
|
410
1614
|
}
|
|
411
1615
|
|
|
412
|
-
|
|
1616
|
+
/**
|
|
1617
|
+
* @param options.orphanAllowlist Files permitted to have zero references, owned
|
|
1618
|
+
* by the CALLING project. Same contract and same positional constraint as
|
|
1619
|
+
* runSpecDrift's untestedAllowlist — the generated consumer test calls
|
|
1620
|
+
* `runDocHygiene(ROOT, findings)`.
|
|
1621
|
+
*/
|
|
1622
|
+
/**
|
|
1623
|
+
* Every path's most recent commit date, from ONE git subprocess (#323).
|
|
1624
|
+
*
|
|
1625
|
+
* Exported so the regression test can run it against the repository and
|
|
1626
|
+
* compare it to the per-file calls it replaced — a single site to mutate, and
|
|
1627
|
+
* the only way to prove the parser still agrees with git rather than merely
|
|
1628
|
+
* being faster. A detector that got quicker by finding less would pass every
|
|
1629
|
+
* timing test and none of the ones that matter.
|
|
1630
|
+
*
|
|
1631
|
+
* Walks newest-first, so the first time a path appears is its latest commit
|
|
1632
|
+
* and later entries are ignored. Paths deleted or renamed earlier in history
|
|
1633
|
+
* also appear; they are never looked up, which is cheaper than filtering them.
|
|
1634
|
+
*
|
|
1635
|
+
* `pathspecs` must be the SET OF PATHS THE CALLER WILL LOOK UP, not the
|
|
1636
|
+
* directories they mostly live in. The first version of this took the six doc
|
|
1637
|
+
* directories, which is where the staleness scan finds most of its files — but
|
|
1638
|
+
* the scan also walks root-level markdown, and `git log -- specs docs` cannot
|
|
1639
|
+
* report a commit for `AGENTS.md`. Six files silently dropped out of the
|
|
1640
|
+
* lookup and `if (!dateStr) continue` read that as "newly added, so not
|
|
1641
|
+
* stale". A detector narrower than what it detects, shipped inside the fix for
|
|
1642
|
+
* a different instance of the same thing. Passing the lookup set makes the
|
|
1643
|
+
* pathspec and the keys the same list by construction, so they cannot drift.
|
|
1644
|
+
*
|
|
1645
|
+
* Fails CLOSED. `spawnSync` does not throw when git exits non-zero, so a
|
|
1646
|
+
* broken invocation would otherwise return an empty map and every file would
|
|
1647
|
+
* read as newly added — total blindness that looks exactly like a clean run.
|
|
1648
|
+
*/
|
|
1649
|
+
export function lastCommitDates(root: string, pathspecs: string[]): Map<string, string> {
|
|
1650
|
+
const lastCommit = new Map<string, string>();
|
|
1651
|
+
// Not a git repository: nothing is tracked, so no path has a commit date.
|
|
1652
|
+
// That is a real answer, not a failure, and scaffolded projects hit it.
|
|
1653
|
+
if (!existsSync(join(root, ".git"))) return lastCommit;
|
|
1654
|
+
if (pathspecs.length === 0) return lastCommit;
|
|
1655
|
+
{
|
|
1656
|
+
const log = spawnSync(
|
|
1657
|
+
"git",
|
|
1658
|
+
["-C", root, "log", "--format=%H %ci", "--name-only", "--", ...pathspecs],
|
|
1659
|
+
{ timeout: 60_000, maxBuffer: 64 * 1024 * 1024 },
|
|
1660
|
+
);
|
|
1661
|
+
if (log.error) {
|
|
1662
|
+
throw new Error(`lastCommitDates: git log could not run in ${root}: ${log.error.message}`);
|
|
1663
|
+
}
|
|
1664
|
+
if (log.status !== 0) {
|
|
1665
|
+
throw new Error(
|
|
1666
|
+
`lastCommitDates: git log exited ${log.status} in ${root}: ` +
|
|
1667
|
+
`${log.stderr?.toString().trim() || "(no stderr)"}`,
|
|
1668
|
+
);
|
|
1669
|
+
}
|
|
1670
|
+
let currentDate = "";
|
|
1671
|
+
for (const line of log.stdout.toString().split("\n")) {
|
|
1672
|
+
const header = /^[0-9a-f]{7,40} (\d{4}-\d{2}-\d{2})/.exec(line);
|
|
1673
|
+
if (header) {
|
|
1674
|
+
currentDate = header[1];
|
|
1675
|
+
continue;
|
|
1676
|
+
}
|
|
1677
|
+
const path = line.trim();
|
|
1678
|
+
if (!path || !currentDate) continue;
|
|
1679
|
+
if (!lastCommit.has(path)) lastCommit.set(path, currentDate);
|
|
1680
|
+
}
|
|
1681
|
+
}
|
|
1682
|
+
return lastCommit;
|
|
1683
|
+
}
|
|
1684
|
+
|
|
1685
|
+
export function runDocHygiene(
|
|
1686
|
+
root: string,
|
|
1687
|
+
_findings?: unknown[],
|
|
1688
|
+
options?: { orphanAllowlist?: string[] },
|
|
1689
|
+
) {
|
|
1690
|
+
const orphanAllowlist =
|
|
1691
|
+
options?.orphanAllowlist ?? loadConformityAllowlists(root).orphanFiles;
|
|
413
1692
|
const specsDir = join(root, "specs");
|
|
414
1693
|
const refDir = join(root, "reference");
|
|
415
1694
|
// .claude/agents/ excluded — Claude Code reads those by name convention, not import
|
|
@@ -440,7 +1719,24 @@ export function runDocHygiene(root: string) {
|
|
|
440
1719
|
? readdirSync(dir).filter(f => exts.some(e => f.endsWith(e)))
|
|
441
1720
|
: readdirSync(dir, { recursive: true }).map(f => String(f)).filter(f => exts.some(e => f.endsWith(e)));
|
|
442
1721
|
for (const f of files) {
|
|
443
|
-
|
|
1722
|
+
const rel = String(f);
|
|
1723
|
+
|
|
1724
|
+
// skipDirs above only filters TOP-LEVEL entries of root, so the
|
|
1725
|
+
// recursive walk still descended into .claude/worktrees/ — which
|
|
1726
|
+
// holds full copies of the repo, 39 of them on the machine where
|
|
1727
|
+
// this was found. Every file in every worktree counted as a
|
|
1728
|
+
// reference, so nothing was ever an orphan locally while a clean CI
|
|
1729
|
+
// checkout saw three. That divergence is what made HYGIENE-3 look
|
|
1730
|
+
// intermittent and got a real failure dismissed as flake.
|
|
1731
|
+
if (rel.includes("worktrees/") || skipDirs.has(rel.split("/")[0])) continue;
|
|
1732
|
+
|
|
1733
|
+
// The allowlist names the very files it exempts, so counting it as a
|
|
1734
|
+
// reference makes every listed orphan stop being an orphan — the
|
|
1735
|
+
// ratchet then fails demanding they be delisted, and delisting makes
|
|
1736
|
+
// them orphans again. A list that invalidates itself by existing.
|
|
1737
|
+
if (rel.endsWith("conformity-allowlists.json")) continue;
|
|
1738
|
+
|
|
1739
|
+
try { chunks.push(readFileSync(join(dir, rel), "utf-8")); } catch {}
|
|
444
1740
|
}
|
|
445
1741
|
} catch {}
|
|
446
1742
|
}
|
|
@@ -455,27 +1751,33 @@ export function runDocHygiene(root: string) {
|
|
|
455
1751
|
|
|
456
1752
|
describe("Doc Hygiene", () => {
|
|
457
1753
|
test("HYGIENE-1: All specs have non-empty governs field", () => {
|
|
458
|
-
if (!existsSync(specsDir)) return;
|
|
1754
|
+
if (!existsSync(specsDir)) return checkSkipped("HYGIENE-1", "no specs/ directory");
|
|
459
1755
|
const missing: string[] = [];
|
|
460
|
-
for (const f of
|
|
1756
|
+
for (const f of collectSpecFiles(specsDir)) { // #225 — subdirectories too
|
|
461
1757
|
const content = readFileSync(join(specsDir, f), "utf-8");
|
|
462
1758
|
const fm = parseFrontmatter(content);
|
|
463
1759
|
if (!fm) continue;
|
|
464
1760
|
const governs = fm.governs || "";
|
|
465
1761
|
if (!governs || governs.includes("TODO")) missing.push(f);
|
|
466
1762
|
}
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
}
|
|
470
|
-
expect(true).toBe(true);
|
|
1763
|
+
// Was unconditionally passing after a console.warn (#80).
|
|
1764
|
+
expect(missing).toEqual([]);
|
|
471
1765
|
});
|
|
472
1766
|
|
|
473
1767
|
test("HYGIENE-2: All specs have updated field in frontmatter", () => {
|
|
474
1768
|
if (!existsSync(specsDir)) return;
|
|
475
1769
|
const missing: string[] = [];
|
|
476
|
-
|
|
1770
|
+
|
|
1771
|
+
// #225 — the hand-rolled one-level descent that used to live here is
|
|
1772
|
+
// now the shared collector, so the seven flat callers get the same
|
|
1773
|
+
// behaviour instead of this one site being the only correct reader.
|
|
1774
|
+
const specFiles = collectSpecFiles(specsDir);
|
|
1775
|
+
|
|
1776
|
+
for (const f of specFiles) {
|
|
477
1777
|
const content = readFileSync(join(specsDir, f), "utf-8");
|
|
478
1778
|
const fm = parseFrontmatter(content);
|
|
1779
|
+
// Skip redirect files (status: split)
|
|
1780
|
+
if (fm?.status === "split") continue;
|
|
479
1781
|
if (!fm || !fm.updated) missing.push(f);
|
|
480
1782
|
}
|
|
481
1783
|
expect(missing).toEqual([]);
|
|
@@ -490,25 +1792,60 @@ export function runDocHygiene(root: string) {
|
|
|
490
1792
|
if (!index.includes(f)) orphans.push(`${relPath}/${f}`);
|
|
491
1793
|
}
|
|
492
1794
|
}
|
|
493
|
-
|
|
494
|
-
|
|
1795
|
+
// Was unconditionally passing after a console.warn (#80). Two orphans it
|
|
1796
|
+
// had been quietly reporting — specs/bootstrap-data-flow.png and
|
|
1797
|
+
// scripts/self-containment-check.sh — were archived to reference/, the
|
|
1798
|
+
// remedy this check recommends in its own message.
|
|
1799
|
+
//
|
|
1800
|
+
// Converting it to a bare `expect(orphans).toEqual([])` then turned Gates
|
|
1801
|
+
// red on main, because sizing from the warn output was taken as the
|
|
1802
|
+
// post-merge state without re-running the check against a clean tree. The
|
|
1803
|
+
// warn output listed two; a clean checkout has three more that local runs
|
|
1804
|
+
// did not surface. Same instrument as DRIFT-2 applies here and was not
|
|
1805
|
+
// used: list what cannot be fixed now, fail on an addition, fail if a
|
|
1806
|
+
// listed file gains a reference and is not delisted.
|
|
1807
|
+
//
|
|
1808
|
+
// Caller-owned for the same reason as DRIFT-2 — consumers must not
|
|
1809
|
+
// inherit rungate's exemptions.
|
|
1810
|
+
if (!orphanAllowlist) {
|
|
1811
|
+
if (orphans.length > 0) {
|
|
1812
|
+
console.warn(
|
|
1813
|
+
`WARN HYGIENE-3: ${orphans.length} file(s) with zero references — ` +
|
|
1814
|
+
`${orphans.join(", ")}. ADVISORY because no orphanAllowlist was supplied. ` +
|
|
1815
|
+
`Pass one to runDocHygiene to enforce it as a ratchet.`,
|
|
1816
|
+
);
|
|
1817
|
+
}
|
|
1818
|
+
return;
|
|
495
1819
|
}
|
|
496
|
-
|
|
1820
|
+
|
|
1821
|
+
const newOrphans = orphans.filter(o => !orphanAllowlist.includes(o));
|
|
1822
|
+
expect(newOrphans).toEqual([]);
|
|
1823
|
+
|
|
1824
|
+
const staleAllowlist = orphanAllowlist.filter(o => !orphans.includes(o));
|
|
1825
|
+
expect(staleAllowlist).toEqual([]);
|
|
497
1826
|
});
|
|
498
1827
|
|
|
499
|
-
test("HYGIENE-4:
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
1828
|
+
test("HYGIENE-4: Every spec appears in the specs routing table", () => {
|
|
1829
|
+
// The table lives in .claude/rules/specs-routing.md, NOT AGENTS.md. This
|
|
1830
|
+
// check read AGENTS.md, which contains no spec references at all, so it
|
|
1831
|
+
// "found" 22 violations — every spec in the repo — and reported none of
|
|
1832
|
+
// them because it ended in expect(true).toBe(true) (#80). The premise was
|
|
1833
|
+
// stale, which is how a check this wrong stayed invisible.
|
|
1834
|
+
const routingPath = join(root, ".claude", "rules", "specs-routing.md");
|
|
1835
|
+
if (!existsSync(specsDir)) return checkSkipped("HYGIENE-4", "no specs/ directory");
|
|
1836
|
+
if (!existsSync(routingPath)) return checkSkipped("HYGIENE-4", "no .claude/rules/specs-routing.md");
|
|
1837
|
+
const routing = readFileSync(routingPath, "utf-8");
|
|
1838
|
+
const specFiles = readdirSync(specsDir)
|
|
1839
|
+
.filter(f => f.endsWith(".md"))
|
|
1840
|
+
// SPEC-TEMPLATE.md documents how to write a spec; it governs nothing.
|
|
1841
|
+
.filter(f => f !== "SPEC-TEMPLATE.md");
|
|
1842
|
+
const unlisted = specFiles.filter(f => !routing.includes(f));
|
|
1843
|
+
expect(unlisted).toEqual([]);
|
|
508
1844
|
});
|
|
509
1845
|
|
|
510
1846
|
test("HYGIENE-5: reference/ contents not in active routing", () => {
|
|
511
|
-
if (!existsSync(refDir)
|
|
1847
|
+
if (!existsSync(refDir)) return checkSkipped("HYGIENE-5", "no reference/ directory");
|
|
1848
|
+
if (!existsSync(join(root, "AGENTS.md"))) return checkSkipped("HYGIENE-5", "no AGENTS.md");
|
|
512
1849
|
const agentsContent = readFileSync(join(root, "AGENTS.md"), "utf-8");
|
|
513
1850
|
const leaked: string[] = [];
|
|
514
1851
|
for (const sub of readdirSync(refDir)) {
|
|
@@ -523,10 +1860,8 @@ export function runDocHygiene(root: string) {
|
|
|
523
1860
|
}
|
|
524
1861
|
} catch {}
|
|
525
1862
|
}
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
}
|
|
529
|
-
expect(true).toBe(true);
|
|
1863
|
+
// Was unconditionally passing after a console.warn (#80).
|
|
1864
|
+
expect(leaked).toEqual([]);
|
|
530
1865
|
});
|
|
531
1866
|
|
|
532
1867
|
test("HYGIENE-10: All ADRs have doc-type: adr in frontmatter", () => {
|
|
@@ -540,7 +1875,7 @@ export function runDocHygiene(root: string) {
|
|
|
540
1875
|
missing.push(f);
|
|
541
1876
|
addFinding({
|
|
542
1877
|
ruleId: "HYGIENE-10",
|
|
543
|
-
severity: "
|
|
1878
|
+
severity: "WARN",
|
|
544
1879
|
file: `docs/adr/${f}`,
|
|
545
1880
|
message: `ADR "${f}" missing doc-type: adr in frontmatter`,
|
|
546
1881
|
fixCommand: `Add "doc-type: adr" to frontmatter of docs/adr/${f}`,
|
|
@@ -548,9 +1883,8 @@ export function runDocHygiene(root: string) {
|
|
|
548
1883
|
}
|
|
549
1884
|
}
|
|
550
1885
|
if (missing.length > 0) {
|
|
551
|
-
console.
|
|
1886
|
+
console.warn(`HYGIENE-10 WARN: ADRs missing doc-type: ${missing.join(", ")}. Fix: add "doc-type: adr" to frontmatter.`);
|
|
552
1887
|
}
|
|
553
|
-
expect(missing).toEqual([]);
|
|
554
1888
|
});
|
|
555
1889
|
|
|
556
1890
|
test("HYGIENE-7: No spec files at root (must be in specs/)", () => {
|
|
@@ -636,7 +1970,14 @@ export function runDocHygiene(root: string) {
|
|
|
636
1970
|
expect(misplaced).toEqual([]);
|
|
637
1971
|
});
|
|
638
1972
|
|
|
639
|
-
|
|
1973
|
+
// WARN, not a gate, and the name now says so. This reports a review
|
|
1974
|
+
// BACKLOG — 119 pending candidates on rungate as of #80 — so asserting it
|
|
1975
|
+
// to zero would block every push until someone triages all of them. It
|
|
1976
|
+
// previously claimed "No unreviewed constraint candidates" while ending in
|
|
1977
|
+
// expect(true).toBe(true), which is the dishonest combination: a gate-
|
|
1978
|
+
// sounding name over an unconditional pass. Advisory is the honest shape
|
|
1979
|
+
// here; the lie was the name, not the leniency.
|
|
1980
|
+
test("WARN HYGIENE-6: Unreviewed constraint candidates in changed docs", async () => {
|
|
640
1981
|
const { extractConstraints } = await import("../scripts/extract-constraints");
|
|
641
1982
|
const result = await extractConstraints(root, { apply: false });
|
|
642
1983
|
|
|
@@ -663,6 +2004,116 @@ export function runDocHygiene(root: string) {
|
|
|
663
2004
|
expect(true).toBe(true);
|
|
664
2005
|
});
|
|
665
2006
|
|
|
2007
|
+
test("HYGIENE-11: Stale unreferenced files warn with archival suggestion", () => {
|
|
2008
|
+
const index = getRefIndex();
|
|
2009
|
+
// stalenessThreshold through the loader (ADR-002 D1, #309), default 90
|
|
2010
|
+
// days. The bare `catch {}` is kept deliberately narrow in meaning: a
|
|
2011
|
+
// config that cannot be read must not take HYGIENE-11 down, but it also
|
|
2012
|
+
// must not silently become 90 — which, with nothing logged, is what it
|
|
2013
|
+
// used to do.
|
|
2014
|
+
let threshold = 90;
|
|
2015
|
+
try {
|
|
2016
|
+
const config = tryLoadRungateConfig(root);
|
|
2017
|
+
if (typeof config?.stalenessThreshold === "number") {
|
|
2018
|
+
threshold = config.stalenessThreshold;
|
|
2019
|
+
}
|
|
2020
|
+
} catch (err) {
|
|
2021
|
+
console.warn(
|
|
2022
|
+
`WARN: HYGIENE-11 could not read the rungate config (${(err as Error).name}); ` +
|
|
2023
|
+
`using the ${threshold}-day default. A configured threshold is NOT in effect.`,
|
|
2024
|
+
);
|
|
2025
|
+
}
|
|
2026
|
+
|
|
2027
|
+
// Scan docs directories for markdown files — skip reference/ entirely (AC-2)
|
|
2028
|
+
const scanTargets: string[] = [];
|
|
2029
|
+
const docDirs = ["specs", "docs", "docs/adr", "docs/research", "docs/council", "docs/guides"];
|
|
2030
|
+
for (const rel of docDirs) {
|
|
2031
|
+
const dir = join(root, rel);
|
|
2032
|
+
if (!existsSync(dir)) continue;
|
|
2033
|
+
for (const f of readdirSync(dir).filter(f => f.endsWith(".md"))) {
|
|
2034
|
+
const fullPath = join(dir, f);
|
|
2035
|
+
try {
|
|
2036
|
+
if (statSync(fullPath).isFile()) {
|
|
2037
|
+
scanTargets.push(`${rel}/${f}`);
|
|
2038
|
+
}
|
|
2039
|
+
} catch {}
|
|
2040
|
+
}
|
|
2041
|
+
}
|
|
2042
|
+
|
|
2043
|
+
// Also scan root-level markdown (excluding reference/)
|
|
2044
|
+
for (const f of readdirSync(root).filter(f => f.endsWith(".md"))) {
|
|
2045
|
+
scanTargets.push(f);
|
|
2046
|
+
}
|
|
2047
|
+
|
|
2048
|
+
// Filter out reference/ paths (AC-2)
|
|
2049
|
+
const filtered = scanTargets.filter(f => !f.startsWith("reference/") && !f.includes("/reference/"));
|
|
2050
|
+
|
|
2051
|
+
// One git call for every file, not one per file (#323).
|
|
2052
|
+
//
|
|
2053
|
+
// This was `spawnSync("git", ["log", "-1", ..., "--", rel])` inside the
|
|
2054
|
+
// loop: 60 serial subprocesses against the same repository, each with
|
|
2055
|
+
// its own 5-second timeout. Nothing was wrong with any single call — the
|
|
2056
|
+
// test was load-sensitive by construction, and if any one spawn was slow
|
|
2057
|
+
// (another suite holding the index, a busy machine, a cold cache) it hit
|
|
2058
|
+
// the timeout and the test went red. Measured at 1 failure in 3
|
|
2059
|
+
// identical runs, always at ~5007 ms. It also got worse on its own as
|
|
2060
|
+
// the repo grew, because more docs means more dice rolls.
|
|
2061
|
+
//
|
|
2062
|
+
// `--name-only` over the whole history, walked newest-first, gives every
|
|
2063
|
+
// path's most recent commit date from a single subprocess. The first
|
|
2064
|
+
// time a path is seen is its latest commit, so later entries are
|
|
2065
|
+
// ignored.
|
|
2066
|
+
//
|
|
2067
|
+
// `filtered` is passed, NOT `docDirs`. The first cut of this fix passed
|
|
2068
|
+
// the six doc directories, and `git log -- specs docs` has nothing to
|
|
2069
|
+
// say about the six root-level markdown files this scan also walks —
|
|
2070
|
+
// AGENTS.md, CLAUDE.md, SUCCESS.md and friends dropped out of the map,
|
|
2071
|
+
// and the `if (!dateStr) continue` below read that as "newly added, so
|
|
2072
|
+
// not stale". Handing it the exact lookup set keeps the pathspec and the
|
|
2073
|
+
// keys the same list by construction.
|
|
2074
|
+
const lastCommit = lastCommitDates(root, filtered);
|
|
2075
|
+
|
|
2076
|
+
const staleUnreferenced: { file: string; daysSince: number }[] = [];
|
|
2077
|
+
for (const rel of filtered) {
|
|
2078
|
+
const dateStr = lastCommit.get(rel);
|
|
2079
|
+
// No commit for this path means it is untracked or newly added, which
|
|
2080
|
+
// is the opposite of stale.
|
|
2081
|
+
if (!dateStr) continue;
|
|
2082
|
+
const daysSince = (Date.now() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24);
|
|
2083
|
+
if (daysSince <= threshold) continue;
|
|
2084
|
+
|
|
2085
|
+
// Check cross-references: filename must appear somewhere in the codebase index
|
|
2086
|
+
const basename = rel.split("/").pop()!;
|
|
2087
|
+
if (index.includes(basename)) continue;
|
|
2088
|
+
|
|
2089
|
+
staleUnreferenced.push({ file: rel, daysSince: Math.floor(daysSince) });
|
|
2090
|
+
}
|
|
2091
|
+
|
|
2092
|
+
// AC-3: Each warning includes git mv archival command
|
|
2093
|
+
if (staleUnreferenced.length > 0) {
|
|
2094
|
+
for (const entry of staleUnreferenced) {
|
|
2095
|
+
const archiveDest = `reference/${entry.file.split("/").pop()}`;
|
|
2096
|
+
addFinding({
|
|
2097
|
+
ruleId: "HYGIENE-11",
|
|
2098
|
+
severity: "WARN",
|
|
2099
|
+
file: entry.file,
|
|
2100
|
+
message: `Stale unreferenced file (${entry.daysSince}d, threshold=${threshold}d)`,
|
|
2101
|
+
fixCommand: `git mv ${entry.file} ${archiveDest}`,
|
|
2102
|
+
});
|
|
2103
|
+
console.warn(`HYGIENE-11: ${entry.file} — stale (${entry.daysSince}d) and unreferenced. Fix: git mv ${entry.file} ${archiveDest}`);
|
|
2104
|
+
}
|
|
2105
|
+
}
|
|
2106
|
+
|
|
2107
|
+
// AC-1: At least 2 assertions
|
|
2108
|
+
// 1. reference/ files were filtered out
|
|
2109
|
+
const referenceFiles = scanTargets.filter(f => f.startsWith("reference/") || f.includes("/reference/"));
|
|
2110
|
+
expect(filtered.every(f => !f.startsWith("reference/") && !f.includes("/reference/"))).toBe(true);
|
|
2111
|
+
|
|
2112
|
+
// 2. All stale unreferenced entries have git mv fix commands
|
|
2113
|
+
const hygieneFindings = getFindings().filter(f => f.ruleId === "HYGIENE-11");
|
|
2114
|
+
expect(hygieneFindings.every(f => f.fixCommand?.startsWith("git mv "))).toBe(true);
|
|
2115
|
+
});
|
|
2116
|
+
|
|
666
2117
|
test("HYGIENE-REPORT: Write unified findings report", () => {
|
|
667
2118
|
const findings = getFindings();
|
|
668
2119
|
const candidates = getCandidates();
|
|
@@ -756,20 +2207,239 @@ export function runAgentFileValidation(root: string) {
|
|
|
756
2207
|
expect(mismatched).toEqual([]);
|
|
757
2208
|
});
|
|
758
2209
|
|
|
759
|
-
test("AGENT-5:
|
|
2210
|
+
test("AGENT-5: Shared agent principles exist as unconditional rule", () => {
|
|
2211
|
+
const rulesDir = join(root, ".claude", "rules");
|
|
2212
|
+
if (!existsSync(rulesDir)) {
|
|
2213
|
+
addFinding({ ruleId: "AGENT-5", severity: "FAIL", file: ".claude/rules/", message: "No rules directory found", fixCommand: "Re-scaffold to generate rules" });
|
|
2214
|
+
expect(existsSync(rulesDir)).toBe(true);
|
|
2215
|
+
return;
|
|
2216
|
+
}
|
|
2217
|
+
const principlesFile = join(rulesDir, "agent-principles.md");
|
|
2218
|
+
expect(existsSync(principlesFile)).toBe(true);
|
|
2219
|
+
const content = readFileSync(principlesFile, "utf-8");
|
|
2220
|
+
expect(content).toContain("Core Principles");
|
|
2221
|
+
});
|
|
2222
|
+
|
|
2223
|
+
test("AGENT-7: All agent briefs have required sections", () => {
|
|
760
2224
|
if (!existsSync(agentsDir)) return;
|
|
2225
|
+
const sectionChecks: Array<{ name: string; pattern: RegExp }> = [
|
|
2226
|
+
{ name: "frontmatter", pattern: /^---\n[\s\S]*?\n---/ },
|
|
2227
|
+
{ name: "identity", pattern: /You are\s+\w+/i },
|
|
2228
|
+
{ name: "agent-specific-section", pattern: /^##\s+(Workflow|Rules|Testing|Discovery|What you|TDD|CLI|UI|Project Type|Efficiency|Design|Architecture|Context|Report)/im },
|
|
2229
|
+
];
|
|
761
2230
|
const missing: string[] = [];
|
|
762
2231
|
for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
|
|
763
2232
|
const content = readFileSync(join(agentsDir, f), "utf-8");
|
|
764
|
-
|
|
765
|
-
|
|
2233
|
+
for (const check of sectionChecks) {
|
|
2234
|
+
if (!check.pattern.test(content)) {
|
|
2235
|
+
missing.push(`${f}: missing required section '${check.name}'`);
|
|
2236
|
+
addFinding({
|
|
2237
|
+
ruleId: "AGENT-REQUIRED-SECTION",
|
|
2238
|
+
severity: "FAIL",
|
|
2239
|
+
file: `.claude/agents/${f}`,
|
|
2240
|
+
message: `Brief missing required section: ${check.name}`,
|
|
2241
|
+
});
|
|
2242
|
+
}
|
|
766
2243
|
}
|
|
767
2244
|
}
|
|
768
2245
|
if (missing.length > 0) {
|
|
769
|
-
console.
|
|
2246
|
+
console.error(`Agent briefs missing required sections:\n ${missing.join("\n ")}`);
|
|
770
2247
|
}
|
|
771
2248
|
expect(missing).toEqual([]);
|
|
772
2249
|
});
|
|
2250
|
+
|
|
2251
|
+
test("AGENT-8: Agent brief models match the roles config", () => {
|
|
2252
|
+
if (!existsSync(agentsDir)) return;
|
|
2253
|
+
// Was hardcoded to "sonnet". Roles are now routed per-role, so the
|
|
2254
|
+
// meaningful check is that each brief matches its configured model —
|
|
2255
|
+
// briefs are generated from that config, and a mismatch means someone
|
|
2256
|
+
// hand-edited generated output.
|
|
2257
|
+
//
|
|
2258
|
+
// #90: this read `.claude/rungate.json` directly, which is the LEGACY
|
|
2259
|
+
// monolith. Scaffold migrated projects to `.claude/rungate/` and
|
|
2260
|
+
// generates briefs from `roles.json` there, so on any migrated project
|
|
2261
|
+
// the generator and this validator read different files. They disagreed
|
|
2262
|
+
// in this very repo — roles.json said sonnet, the stale monolith said
|
|
2263
|
+
// opus — and AGENT-8 reported a violation against output that exactly
|
|
2264
|
+
// matched its real source.
|
|
2265
|
+
//
|
|
2266
|
+
// The failure mode was worse than a false alarm: the message told the
|
|
2267
|
+
// reader to "re-scaffold instead of editing the brief", and
|
|
2268
|
+
// re-scaffolding reproduced the same briefs, so following the advice
|
|
2269
|
+
// could not clear it.
|
|
2270
|
+
//
|
|
2271
|
+
// Go through the canonical loader, which understands both layouts and
|
|
2272
|
+
// prefers the directory. tryLoadRungateConfig is the non-throwing
|
|
2273
|
+
// variant: absent config is "nothing to check", while a MALFORMED
|
|
2274
|
+
// config still throws, per ADR-001 D2 — a broken config must not read
|
|
2275
|
+
// as an unconfigured one.
|
|
2276
|
+
const VALID_MODELS = ["sonnet", "opus", "haiku", "fable"];
|
|
2277
|
+
const roles: Record<string, { model?: string }> =
|
|
2278
|
+
(tryLoadRungateConfig(root)?.roles as Record<string, { model?: string }>) ?? {};
|
|
2279
|
+
|
|
2280
|
+
const wrong: string[] = [];
|
|
2281
|
+
for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
|
|
2282
|
+
const content = readFileSync(join(agentsDir, f), "utf-8");
|
|
2283
|
+
const fm = parseFrontmatter(content);
|
|
2284
|
+
const role = f.replace(/\.md$/, "");
|
|
2285
|
+
const expected = roles[role]?.model;
|
|
2286
|
+
if (!fm?.model) {
|
|
2287
|
+
wrong.push(`${f}: missing model field`);
|
|
2288
|
+
} else if (!VALID_MODELS.includes(fm.model)) {
|
|
2289
|
+
wrong.push(`${f}: model is "${fm.model}", expected one of ${VALID_MODELS.join("|")}`);
|
|
2290
|
+
} else if (expected && fm.model !== expected) {
|
|
2291
|
+
wrong.push(`${f}: model is "${fm.model}", but the roles config says "${expected}" — re-scaffold instead of editing the brief`);
|
|
2292
|
+
}
|
|
2293
|
+
}
|
|
2294
|
+
if (wrong.length > 0) {
|
|
2295
|
+
wrong.forEach(w => addFinding({
|
|
2296
|
+
ruleId: "AGENT-MODEL",
|
|
2297
|
+
severity: "FAIL",
|
|
2298
|
+
file: `.claude/agents/${w.split(":")[0]}`,
|
|
2299
|
+
message: w,
|
|
2300
|
+
}));
|
|
2301
|
+
console.error(`Agent briefs with wrong model:\n ${wrong.join("\n ")}`);
|
|
2302
|
+
}
|
|
2303
|
+
expect(wrong).toEqual([]);
|
|
2304
|
+
});
|
|
2305
|
+
|
|
2306
|
+
test("AGENT-9: All agent briefs are under 120 lines", () => {
|
|
2307
|
+
if (!existsSync(agentsDir)) return;
|
|
2308
|
+
const over: string[] = [];
|
|
2309
|
+
for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
|
|
2310
|
+
const content = readFileSync(join(agentsDir, f), "utf-8");
|
|
2311
|
+
const lineCount = content.trimEnd().split("\n").length;
|
|
2312
|
+
if (lineCount > 120) {
|
|
2313
|
+
over.push(`${f}: ${lineCount} lines (max 120)`);
|
|
2314
|
+
addFinding({
|
|
2315
|
+
ruleId: "AGENT-LINECOUNT",
|
|
2316
|
+
severity: "FAIL",
|
|
2317
|
+
file: `.claude/agents/${f}`,
|
|
2318
|
+
message: `Brief is ${lineCount} lines, exceeds 120-line cap`,
|
|
2319
|
+
});
|
|
2320
|
+
}
|
|
2321
|
+
}
|
|
2322
|
+
if (over.length > 0) {
|
|
2323
|
+
console.error(`Agent briefs over 120 lines:\n ${over.join("\n ")}`);
|
|
2324
|
+
}
|
|
2325
|
+
expect(over).toEqual([]);
|
|
2326
|
+
});
|
|
2327
|
+
|
|
2328
|
+
test("AGENT-11: AGENTS.md is under line cap (sigmoid collapse prevention)", () => {
|
|
2329
|
+
const agentsMdPath = join(root, "AGENTS.md");
|
|
2330
|
+
if (!existsSync(agentsMdPath)) return;
|
|
2331
|
+
const content = readFileSync(agentsMdPath, "utf-8");
|
|
2332
|
+
const lineCount = content.trimEnd().split("\n").length;
|
|
2333
|
+
const consumerLines = (content.match(/^- \w/gm) || []).length;
|
|
2334
|
+
const cap = 100 + Math.max(0, consumerLines - 10);
|
|
2335
|
+
if (lineCount > cap) {
|
|
2336
|
+
addFinding({
|
|
2337
|
+
ruleId: "AGENTS-MD-LINECOUNT",
|
|
2338
|
+
severity: "FAIL",
|
|
2339
|
+
file: "AGENTS.md",
|
|
2340
|
+
message: `AGENTS.md is ${lineCount} lines, exceeds ${cap}-line cap (base 100 + ${Math.max(0, consumerLines - 10)} consumer lines). Move reference tables to .claude/rules/`,
|
|
2341
|
+
});
|
|
2342
|
+
}
|
|
2343
|
+
expect(lineCount).toBeLessThanOrEqual(cap);
|
|
2344
|
+
});
|
|
2345
|
+
|
|
2346
|
+
test("AGENT-10: No unfilled template variables in agent briefs", () => {
|
|
2347
|
+
if (!existsSync(agentsDir)) return;
|
|
2348
|
+
const unfilled: string[] = [];
|
|
2349
|
+
for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
|
|
2350
|
+
const content = readFileSync(join(agentsDir, f), "utf-8");
|
|
2351
|
+
const vars = content.match(/\$\{[A-Z_]+\}/g);
|
|
2352
|
+
if (vars && vars.length > 0) {
|
|
2353
|
+
unfilled.push(`${f}: unfilled template variables: ${vars.join(", ")}`);
|
|
2354
|
+
addFinding({
|
|
2355
|
+
ruleId: "AGENT-TEMPLATE-VAR",
|
|
2356
|
+
severity: "FAIL",
|
|
2357
|
+
file: `.claude/agents/${f}`,
|
|
2358
|
+
message: `Brief has unfilled template variables: ${vars.join(", ")}`,
|
|
2359
|
+
});
|
|
2360
|
+
}
|
|
2361
|
+
}
|
|
2362
|
+
if (unfilled.length > 0) {
|
|
2363
|
+
console.error(`Agent briefs with unfilled template variables:\n ${unfilled.join("\n ")}`);
|
|
2364
|
+
}
|
|
2365
|
+
expect(unfilled).toEqual([]);
|
|
2366
|
+
});
|
|
2367
|
+
|
|
2368
|
+
test("AGENT-6: All file paths referenced in briefs exist", () => {
|
|
2369
|
+
if (!existsSync(agentsDir)) return;
|
|
2370
|
+
const broken: string[] = [];
|
|
2371
|
+
for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
|
|
2372
|
+
const content = readFileSync(join(agentsDir, f), "utf-8");
|
|
2373
|
+
const refs = content.match(/node_modules\/[^\s`*)"']+/g) || [];
|
|
2374
|
+
for (const ref of refs) {
|
|
2375
|
+
const clean = ref.replace(/[`*)"']+$/, "");
|
|
2376
|
+
if (!existsSync(join(root, clean))) {
|
|
2377
|
+
broken.push(`${f} → ${clean}`);
|
|
2378
|
+
addFinding({
|
|
2379
|
+
ruleId: "AGENT-BROKEN-REF",
|
|
2380
|
+
severity: "FAIL",
|
|
2381
|
+
file: `.claude/agents/${f}`,
|
|
2382
|
+
message: `Brief references "${clean}" but file does not exist`,
|
|
2383
|
+
fixCommand: `Check prompts/ directory for correct filename — may be a typo or renamed file`,
|
|
2384
|
+
});
|
|
2385
|
+
}
|
|
2386
|
+
}
|
|
2387
|
+
}
|
|
2388
|
+
if (broken.length > 0) {
|
|
2389
|
+
console.error(`Broken references in agent briefs:\n ${broken.join("\n ")}`);
|
|
2390
|
+
}
|
|
2391
|
+
expect(broken).toEqual([]);
|
|
2392
|
+
});
|
|
2393
|
+
});
|
|
2394
|
+
}
|
|
2395
|
+
|
|
2396
|
+
// ── SC-294: Directory validation ───────────────────────────
|
|
2397
|
+
|
|
2398
|
+
export function runDirectoryValidation(root: string) {
|
|
2399
|
+
const specsDir = join(root, "specs");
|
|
2400
|
+
|
|
2401
|
+
describe("Directory Validation (SC-294)", () => {
|
|
2402
|
+
test("SC-294: Every specs/ subdirectory has a parent spec file", () => {
|
|
2403
|
+
if (!existsSync(specsDir)) return;
|
|
2404
|
+
|
|
2405
|
+
const invalid: string[] = [];
|
|
2406
|
+
|
|
2407
|
+
// Find all subdirectories in specs/
|
|
2408
|
+
const entries = readdirSync(specsDir);
|
|
2409
|
+
const subdirs = entries.filter(entry => {
|
|
2410
|
+
const fullPath = join(specsDir, entry);
|
|
2411
|
+
try {
|
|
2412
|
+
return statSync(fullPath).isDirectory();
|
|
2413
|
+
} catch {
|
|
2414
|
+
return false;
|
|
2415
|
+
}
|
|
2416
|
+
});
|
|
2417
|
+
|
|
2418
|
+
// For each subdirectory, check if there's a corresponding parent spec
|
|
2419
|
+
for (const subdir of subdirs) {
|
|
2420
|
+
// Find all .md files in specs/
|
|
2421
|
+
const specFiles = entries.filter(f => f.endsWith(".md"));
|
|
2422
|
+
|
|
2423
|
+
// Check if any spec file derives to this directory name
|
|
2424
|
+
let found = false;
|
|
2425
|
+
for (const specFile of specFiles) {
|
|
2426
|
+
const derived = deriveDirectoryName(specFile);
|
|
2427
|
+
if (derived === subdir) {
|
|
2428
|
+
found = true;
|
|
2429
|
+
break;
|
|
2430
|
+
}
|
|
2431
|
+
}
|
|
2432
|
+
|
|
2433
|
+
if (!found) {
|
|
2434
|
+
invalid.push(`${subdir}/: no parent spec derives to this directory name`);
|
|
2435
|
+
}
|
|
2436
|
+
}
|
|
2437
|
+
|
|
2438
|
+
if (invalid.length > 0) {
|
|
2439
|
+
console.error(`Hand-created directories (SC-294 violation):\n ${invalid.join("\n ")}\n\nDirectories MUST be created by split-spec.ts, not manually.`);
|
|
2440
|
+
}
|
|
2441
|
+
expect(invalid).toEqual([]);
|
|
2442
|
+
});
|
|
773
2443
|
});
|
|
774
2444
|
}
|
|
775
2445
|
|
|
@@ -786,7 +2456,38 @@ interface FallowResult {
|
|
|
786
2456
|
workspace_diagnostics: Array<{ kind: string; message: string }>;
|
|
787
2457
|
}
|
|
788
2458
|
|
|
2459
|
+
// `fallow` is an optional external tool and is NOT a declared dependency. When
|
|
2460
|
+
// it is absent, `npx fallow` does a registry fetch on every invocation — four
|
|
2461
|
+
// tests x one fetch each, each outliving bun's per-test timeout. The tests then
|
|
2462
|
+
// fail as timeouts instead of skipping, which blocks the pre-push conformity
|
|
2463
|
+
// gate on a tool nobody installed.
|
|
2464
|
+
//
|
|
2465
|
+
// Resolve it locally instead, with no network path. Memoised PER ROOT —
|
|
2466
|
+
// runFallowCheck is exported and consumer projects call it with their own
|
|
2467
|
+
// root, so a single process can ask about several. A root-independent cache
|
|
2468
|
+
// would answer for the wrong directory.
|
|
2469
|
+
const FALLOW_AVAILABLE = new Map<string, boolean>();
|
|
2470
|
+
|
|
2471
|
+
function fallowAvailable(root: string): boolean {
|
|
2472
|
+
const cached = FALLOW_AVAILABLE.get(root);
|
|
2473
|
+
if (cached !== undefined) return cached;
|
|
2474
|
+
const available =
|
|
2475
|
+
existsSync(join(root, "node_modules", ".bin", "fallow")) ||
|
|
2476
|
+
Bun.which("fallow") !== null;
|
|
2477
|
+
FALLOW_AVAILABLE.set(root, available);
|
|
2478
|
+
return available;
|
|
2479
|
+
}
|
|
2480
|
+
|
|
2481
|
+
/** Shared skip notice — a skipped check must say so, not read as a pass. */
|
|
2482
|
+
function fallowSkipped(check: string): void {
|
|
2483
|
+
console.warn(
|
|
2484
|
+
`SKIP ${check}: fallow is not installed (not a declared dependency) — ` +
|
|
2485
|
+
`this check did NOT run. Install it to enable static analysis.`,
|
|
2486
|
+
);
|
|
2487
|
+
}
|
|
2488
|
+
|
|
789
2489
|
function runFallowCommand(root: string, args: string[]): FallowResult | null {
|
|
2490
|
+
if (!fallowAvailable(root)) return null;
|
|
790
2491
|
const result = Bun.spawnSync(["npx", "fallow", ...args, "--format", "json", "--quiet"], {
|
|
791
2492
|
cwd: root,
|
|
792
2493
|
env: { ...process.env, NODE_NO_WARNINGS: "1" },
|
|
@@ -806,10 +2507,7 @@ export function runFallowCheck(root: string, opts?: { skipUnusedExports?: boolea
|
|
|
806
2507
|
describe("Fallow: static analysis", () => {
|
|
807
2508
|
test("FALLOW-1: No unused files", () => {
|
|
808
2509
|
const result = runFallowCommand(root, ["dead-code", "--unused-files"]);
|
|
809
|
-
if (!result) {
|
|
810
|
-
console.warn("Fallow not available or failed to run — skipping");
|
|
811
|
-
return;
|
|
812
|
-
}
|
|
2510
|
+
if (!result) { fallowSkipped("FALLOW-1 (unused files)"); return; }
|
|
813
2511
|
const unused = result.unused_files.map(f => f.path).filter(p => !p.includes("test/fixtures/") && !p.includes("reference/"));
|
|
814
2512
|
if (unused.length > 0) {
|
|
815
2513
|
console.warn(`Unused files (${unused.length}):\n ${unused.slice(0, 10).join("\n ")}${unused.length > 10 ? `\n ... and ${unused.length - 10} more` : ""}`);
|
|
@@ -820,7 +2518,7 @@ export function runFallowCheck(root: string, opts?: { skipUnusedExports?: boolea
|
|
|
820
2518
|
if (!opts?.skipUnusedExports) {
|
|
821
2519
|
test("FALLOW-2: No unused exports", () => {
|
|
822
2520
|
const result = runFallowCommand(root, ["dead-code", "--unused-exports"]);
|
|
823
|
-
if (!result) return;
|
|
2521
|
+
if (!result) { fallowSkipped("FALLOW-2 (unused exports)"); return; }
|
|
824
2522
|
const unused = (result.unused_exports || [])
|
|
825
2523
|
.filter(e => !e.path.includes("test/fixtures/") && !e.path.includes("reference/"))
|
|
826
2524
|
.map(e => `${e.path}:${e.line ?? "?"} ${e.export_name}`);
|
|
@@ -833,7 +2531,7 @@ export function runFallowCheck(root: string, opts?: { skipUnusedExports?: boolea
|
|
|
833
2531
|
|
|
834
2532
|
test("FALLOW-3: No unused dependencies", () => {
|
|
835
2533
|
const result = runFallowCommand(root, ["dead-code", "--unused-deps"]);
|
|
836
|
-
if (!result) return;
|
|
2534
|
+
if (!result) { fallowSkipped("FALLOW-3 (unused dependencies)"); return; }
|
|
837
2535
|
const unused = result.unused_dependencies?.map(d => d.name) || [];
|
|
838
2536
|
if (unused.length > 0) {
|
|
839
2537
|
console.warn(`Unused dependencies (${unused.length}):\n ${unused.join("\n ")}`);
|
|
@@ -843,10 +2541,10 @@ export function runFallowCheck(root: string, opts?: { skipUnusedExports?: boolea
|
|
|
843
2541
|
|
|
844
2542
|
test("FALLOW-4: No circular dependencies", () => {
|
|
845
2543
|
const result = runFallowCommand(root, ["dead-code"]);
|
|
846
|
-
if (!result) return;
|
|
2544
|
+
if (!result) { fallowSkipped("FALLOW-4 (circular dependencies)"); return; }
|
|
847
2545
|
const circles = result.circular_dependencies || [];
|
|
848
2546
|
if (circles.length > 0) {
|
|
849
|
-
console.warn(`Circular dependencies (${circles.length}):\n ${circles.slice(0, 5).map(c => c.path || JSON.stringify(c.
|
|
2547
|
+
console.warn(`Circular dependencies (${circles.length}):\n ${circles.slice(0, 5).map(c => c.path || JSON.stringify(c.chain ?? c)).join("\n ")}${circles.length > 5 ? `\n ... and ${circles.length - 5} more` : ""}`);
|
|
850
2548
|
}
|
|
851
2549
|
if (fail) expect(circles).toEqual([]);
|
|
852
2550
|
});
|
|
@@ -872,15 +2570,51 @@ export function runPackageValidation(root: string) {
|
|
|
872
2570
|
const pkgPath = join(root, "package.json");
|
|
873
2571
|
if (!existsSync(pkgPath)) return;
|
|
874
2572
|
const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
|
|
2573
|
+
// The harness is not a consumer of itself. npm has no way to express
|
|
2574
|
+
// a self-dependency and would be wrong to: `rungate` IS the thing
|
|
2575
|
+
// this check asks every other project to depend on. Surfaced by #208
|
|
2576
|
+
// — once rungate's own conformity test stopped being frozen by
|
|
2577
|
+
// `safeWrite`, this check ran here for the first time and failed on a
|
|
2578
|
+
// requirement it is not possible to satisfy.
|
|
2579
|
+
if (isHarnessItself(root)) return;
|
|
875
2580
|
expect(pkg.devDependencies?.rungate).toBeDefined();
|
|
876
2581
|
});
|
|
877
2582
|
});
|
|
878
2583
|
}
|
|
879
2584
|
|
|
2585
|
+
/**
|
|
2586
|
+
* #87 — TSC-1 demanded a tsconfig.json that the generator had deliberately
|
|
2587
|
+
* decided not to write.
|
|
2588
|
+
*
|
|
2589
|
+
* `createTsconfig` skips a project with no hand-written TypeScript, because a
|
|
2590
|
+
* tsconfig whose `include` matches nothing is tsc error TS18003 — a type check
|
|
2591
|
+
* that reads as broken rather than as "nothing to check". `createCiWorkflows`
|
|
2592
|
+
* and the AGENTS.md generator both agreed and emitted no step and no row. Then
|
|
2593
|
+
* this hard assert ran in that same consumer's generated conformity suite and
|
|
2594
|
+
* failed over the absent file. Both halves of the question were asserted at
|
|
2595
|
+
* once, which is the contradiction #87 was filed to settle.
|
|
2596
|
+
*
|
|
2597
|
+
* Settled in favour of "consumers may be non-TypeScript projects", so TSC-1
|
|
2598
|
+
* asks `tsconfigVerdict` — the one predicate `createTsconfig` uses — whether
|
|
2599
|
+
* it has anything to assert. The skip is RECORDED as a finding rather than
|
|
2600
|
+
* taken quietly: an unmeasured check and a satisfied check look identical from
|
|
2601
|
+
* the outside, and `.claude/rules/config-access.md` names the silent form as
|
|
2602
|
+
* the anti-pattern it is.
|
|
2603
|
+
*/
|
|
880
2604
|
export function runTsconfigValidation(root: string) {
|
|
881
2605
|
describe("TSConfig validation", () => {
|
|
882
|
-
test("TSC-1: tsconfig.json exists", () => {
|
|
883
|
-
|
|
2606
|
+
test("TSC-1: tsconfig.json exists where TypeScript source does", () => {
|
|
2607
|
+
const verdict = tsconfigVerdict(root);
|
|
2608
|
+
if (!verdict.applicable) {
|
|
2609
|
+
addFinding({
|
|
2610
|
+
ruleId: "TSC-1",
|
|
2611
|
+
severity: "WARN",
|
|
2612
|
+
file: "tsconfig.json",
|
|
2613
|
+
message: `UNMEASURED: ${verdict.reason}`,
|
|
2614
|
+
});
|
|
2615
|
+
return;
|
|
2616
|
+
}
|
|
2617
|
+
expect(verdict.present, verdict.reason).toBe(true);
|
|
884
2618
|
});
|
|
885
2619
|
|
|
886
2620
|
test("TSC-2: strict mode enabled", () => {
|
|
@@ -940,12 +2674,302 @@ export function runModuleDepthCheck(root: string) {
|
|
|
940
2674
|
});
|
|
941
2675
|
}
|
|
942
2676
|
|
|
2677
|
+
// ── Config access conformity (ADR-002 D4, #309) ────────────────
|
|
2678
|
+
//
|
|
2679
|
+
// ADR-001 decided the single-loader policy on 2026-10-05 and specified this
|
|
2680
|
+
// check as the enforcement. It was never built. Six days later the thing it
|
|
2681
|
+
// was written to stop had gone from ~24 sites to ~89 — the policy was
|
|
2682
|
+
// written down the whole time, which is the measurement that makes
|
|
2683
|
+
// "a rule nothing executes is not a rule" a number rather than a slogan.
|
|
2684
|
+
//
|
|
2685
|
+
// TWO checks, not one, because there are two bypass routes and ADR-001's
|
|
2686
|
+
// single check would have missed eleven of them: `workflows/*.js` reaches
|
|
2687
|
+
// config from inside agent PROMPT TEXT, which a TypeScript-source scan does
|
|
2688
|
+
// not look at.
|
|
2689
|
+
//
|
|
2690
|
+
// ## The self-reference trap
|
|
2691
|
+
//
|
|
2692
|
+
// This file is inside the scanned set and is about to contain the literals
|
|
2693
|
+
// it searches for. An allowlist naming the exempt files becomes evidence
|
|
2694
|
+
// those files are referenced — this repo has hit that three times. So the
|
|
2695
|
+
// pattern is ASSEMBLED from fragments that never appear adjacent in this
|
|
2696
|
+
// source, and the test asserts the check reports zero against its own file.
|
|
2697
|
+
// The three real violations this file used to carry are migrated to the
|
|
2698
|
+
// loader in the same change, so that zero is a fact and not an exemption.
|
|
2699
|
+
const CFG_DOT = ".";
|
|
2700
|
+
const CFG_DIR = "claude";
|
|
2701
|
+
const CFG_NAME = "rungate";
|
|
2702
|
+
|
|
2703
|
+
/**
|
|
2704
|
+
* A path being built to the config, in CODE.
|
|
2705
|
+
*
|
|
2706
|
+
* Comments are blanked by `stripJsComments` before this runs — offset
|
|
2707
|
+
* preserving, already proven on `ship.js` by its own suite — rather than by a
|
|
2708
|
+
* line rule of my own. Prose that DISCUSSES the config is not an access, and
|
|
2709
|
+
* counting it would bury the real sites in noise until the ratchet became a
|
|
2710
|
+
* number nobody reads.
|
|
2711
|
+
*
|
|
2712
|
+
* STATED LIMIT, carried over from ADR-001 and not an oversight: this is
|
|
2713
|
+
* string matching, so `join(root, CFG_DOT + CFG_DIR, dynamicName)` is not
|
|
2714
|
+
* caught. It catches every one of the present sites; a variable-constructed
|
|
2715
|
+
* path is not the realistic failure mode and an AST check is not worth the
|
|
2716
|
+
* dependency.
|
|
2717
|
+
*/
|
|
2718
|
+
function configAccessPattern(): RegExp {
|
|
2719
|
+
return new RegExp(
|
|
2720
|
+
"\\" + CFG_DOT + CFG_DIR + "[\"'`/\\\\,\\s)]+\\s*[\"'`]?" + CFG_NAME,
|
|
2721
|
+
"g",
|
|
2722
|
+
);
|
|
2723
|
+
}
|
|
2724
|
+
|
|
2725
|
+
/** Directories CHECK-1 walks. Tests and `test/` are excluded by ADR-002 D4. */
|
|
2726
|
+
const CONFIG_SCAN_DIRS = ["lib", "gates", "scripts", "hooks", "generators"];
|
|
2727
|
+
|
|
2728
|
+
/** The one module allowed to read the config. ADR-002 D1. */
|
|
2729
|
+
const CONFIG_LOADER = "lib/config-loader.ts";
|
|
2730
|
+
|
|
2731
|
+
function walkSources(dir: string, rel: string, out: Array<{ path: string; text: string }>) {
|
|
2732
|
+
let entries;
|
|
2733
|
+
try {
|
|
2734
|
+
entries = readdirSync(dir, { withFileTypes: true });
|
|
2735
|
+
} catch {
|
|
2736
|
+
return;
|
|
2737
|
+
}
|
|
2738
|
+
for (const e of entries) {
|
|
2739
|
+
const abs = join(dir, e.name);
|
|
2740
|
+
const relPath = rel ? `${rel}/${e.name}` : e.name;
|
|
2741
|
+
if (e.isDirectory()) {
|
|
2742
|
+
if (e.name === "test" || e.name === "node_modules") continue;
|
|
2743
|
+
walkSources(abs, relPath, out);
|
|
2744
|
+
continue;
|
|
2745
|
+
}
|
|
2746
|
+
if (!/\.(ts|js)$/.test(e.name) || /\.test\.ts$/.test(e.name)) continue;
|
|
2747
|
+
out.push({ path: relPath, text: readFileSync(abs, "utf-8") });
|
|
2748
|
+
}
|
|
2749
|
+
}
|
|
2750
|
+
|
|
2751
|
+
/** What a scan saw: per-file counts, and how much it actually read. */
|
|
2752
|
+
export interface ConfigAccessScan {
|
|
2753
|
+
/** Repo-relative path -> site count. Allowlisted files are excluded. */
|
|
2754
|
+
counts: Record<string, number>;
|
|
2755
|
+
/** Files walked. ZERO means the scan found nothing to look at. */
|
|
2756
|
+
filesScanned: number;
|
|
2757
|
+
/** Bytes read. Zero with a non-zero file count means empty sources. */
|
|
2758
|
+
bytesScanned: number;
|
|
2759
|
+
}
|
|
2760
|
+
|
|
2761
|
+
/**
|
|
2762
|
+
* CHECK-1's reading: direct config access in TypeScript sources.
|
|
2763
|
+
*
|
|
2764
|
+
* A separate function from the refusal so there is ONE site for the mutation
|
|
2765
|
+
* harness to short-circuit (`.claude/rules/checks-must-be-able-to-fail.md`,
|
|
2766
|
+
* and ADR-002 D4's third mutation).
|
|
2767
|
+
*/
|
|
2768
|
+
export function scanConfigAccess(root: string): ConfigAccessScan {
|
|
2769
|
+
const files: Array<{ path: string; text: string }> = [];
|
|
2770
|
+
for (const d of CONFIG_SCAN_DIRS) walkSources(join(root, d), d, files);
|
|
2771
|
+
|
|
2772
|
+
const counts: Record<string, number> = {};
|
|
2773
|
+
let bytesScanned = 0;
|
|
2774
|
+
for (const f of files) {
|
|
2775
|
+
bytesScanned += f.text.length;
|
|
2776
|
+
if (f.path === CONFIG_LOADER) continue;
|
|
2777
|
+
const n = (stripJsComments(f.text).match(configAccessPattern()) || []).length;
|
|
2778
|
+
if (n > 0) counts[f.path] = n;
|
|
2779
|
+
}
|
|
2780
|
+
return { counts, filesScanned: files.length, bytesScanned };
|
|
2781
|
+
}
|
|
2782
|
+
|
|
2783
|
+
/**
|
|
2784
|
+
* CHECK-2's reading: config access inside `workflows/*.js`, prompts included.
|
|
2785
|
+
*
|
|
2786
|
+
* Comments are stripped and literals are NOT, which is the whole point —
|
|
2787
|
+
* `ship.js` is mostly prompt text, and the eleven sites ADR-001's check could
|
|
2788
|
+
* not see all live inside template literals handed to agents.
|
|
2789
|
+
*/
|
|
2790
|
+
export function scanPromptConfigAccess(root: string): ConfigAccessScan {
|
|
2791
|
+
const dir = join(root, "workflows");
|
|
2792
|
+
const counts: Record<string, number> = {};
|
|
2793
|
+
let filesScanned = 0;
|
|
2794
|
+
let bytesScanned = 0;
|
|
2795
|
+
let entries: string[];
|
|
2796
|
+
try {
|
|
2797
|
+
entries = readdirSync(dir).filter(f => f.endsWith(".js"));
|
|
2798
|
+
} catch {
|
|
2799
|
+
return { counts, filesScanned: 0, bytesScanned: 0 };
|
|
2800
|
+
}
|
|
2801
|
+
for (const f of entries) {
|
|
2802
|
+
const text = readFileSync(join(dir, f), "utf-8");
|
|
2803
|
+
filesScanned++;
|
|
2804
|
+
bytesScanned += text.length;
|
|
2805
|
+
const n = (stripJsComments(text).match(configAccessPattern()) || []).length;
|
|
2806
|
+
if (n > 0) counts[`workflows/${f}`] = n;
|
|
2807
|
+
}
|
|
2808
|
+
return { counts, filesScanned, bytesScanned };
|
|
2809
|
+
}
|
|
2810
|
+
|
|
2811
|
+
/**
|
|
2812
|
+
* The banked violations, read from `.claude/config-access-ratchet.json`.
|
|
2813
|
+
*
|
|
2814
|
+
* Data rather than a constant, because `lib/conformity.ts` travels into every
|
|
2815
|
+
* scaffolded project and rungate's own numbers have no business there. A
|
|
2816
|
+
* consumer with no ratchet file gets `{}` — zero tolerance, which is the
|
|
2817
|
+
* right default for a tree that has never had the defect.
|
|
2818
|
+
*
|
|
2819
|
+
* NOT `.claude/rungate*`, deliberately: this is harness metadata about a
|
|
2820
|
+
* migration, not project config, and routing it through the loader would make
|
|
2821
|
+
* the check depend on the thing it is enforcing access to.
|
|
2822
|
+
*/
|
|
2823
|
+
export function readConfigAccessRatchet(
|
|
2824
|
+
root: string,
|
|
2825
|
+
scope: "sources" | "workflows" | "all" = "all",
|
|
2826
|
+
): Record<string, number> {
|
|
2827
|
+
const p = join(root, ".claude", "config-access-ratchet.json");
|
|
2828
|
+
if (!existsSync(p)) return {};
|
|
2829
|
+
const raw = JSON.parse(readFileSync(p, "utf-8"));
|
|
2830
|
+
const out: Record<string, number> = {};
|
|
2831
|
+
for (const [k, v] of Object.entries(raw)) {
|
|
2832
|
+
if (typeof v !== "number") continue;
|
|
2833
|
+
// One file, two checks. Scoping matters because the both-ways ratchet
|
|
2834
|
+
// complains about a banked entry with no violations left, and CHECK-1
|
|
2835
|
+
// never scans `workflows/` — without this it would demand the removal of
|
|
2836
|
+
// every entry CHECK-2 owns, and vice versa.
|
|
2837
|
+
const isWorkflow = k.startsWith("workflows/");
|
|
2838
|
+
if (scope === "sources" && isWorkflow) continue;
|
|
2839
|
+
if (scope === "workflows" && !isWorkflow) continue;
|
|
2840
|
+
out[k] = v;
|
|
2841
|
+
}
|
|
2842
|
+
return out;
|
|
2843
|
+
}
|
|
2844
|
+
|
|
2845
|
+
/**
|
|
2846
|
+
* Turn a scan into refusals. Empty allows. BOTH DIRECTIONS.
|
|
2847
|
+
*
|
|
2848
|
+
* Over its number refuses, and so does UNDER — an entry that has stopped
|
|
2849
|
+
* being a violation is an entry nobody will ever remove, and the list rots
|
|
2850
|
+
* into one more artefact that certifies nothing. A file absent from the
|
|
2851
|
+
* ratchet is allowed nothing, which is ADR-002 D4's requirement that the
|
|
2852
|
+
* ratchet "refuses on any new file entering the violation set even while the
|
|
2853
|
+
* count is above zero": the migration window is exactly when the next reader
|
|
2854
|
+
* is most likely to be written.
|
|
2855
|
+
*
|
|
2856
|
+
* An EMPTY SCAN REFUSES. A conformity check that silently scans zero files
|
|
2857
|
+
* reports zero violations and is indistinguishable from compliance, which is
|
|
2858
|
+
* this repo's defining defect and would be the most embarrassing possible
|
|
2859
|
+
* place to reproduce it (ADR-002 D4, mutation 5).
|
|
2860
|
+
*/
|
|
2861
|
+
export function configAccessViolations(
|
|
2862
|
+
scan: ConfigAccessScan,
|
|
2863
|
+
banked: Record<string, number>,
|
|
2864
|
+
label: string,
|
|
2865
|
+
requireNonEmpty = true,
|
|
2866
|
+
): string[] {
|
|
2867
|
+
const out: string[] = [];
|
|
2868
|
+
if (requireNonEmpty && scan.filesScanned === 0) {
|
|
2869
|
+
return [
|
|
2870
|
+
`${label}: the scan read NO files. A check that scans nothing reports ` +
|
|
2871
|
+
`zero violations and cannot be told from compliance — refusing rather ` +
|
|
2872
|
+
`than reporting clean (ADR-002 D4).`,
|
|
2873
|
+
];
|
|
2874
|
+
}
|
|
2875
|
+
if (requireNonEmpty && scan.filesScanned > 0 && scan.bytesScanned === 0) {
|
|
2876
|
+
return [`${label}: ${scan.filesScanned} files were walked and none had any content.`];
|
|
2877
|
+
}
|
|
2878
|
+
|
|
2879
|
+
for (const [file, n] of Object.entries(scan.counts).sort()) {
|
|
2880
|
+
const allowed = banked[file] ?? 0;
|
|
2881
|
+
if (n > allowed) {
|
|
2882
|
+
out.push(
|
|
2883
|
+
`${label}: ${file} has ${n} direct config access site(s), ${allowed} allowed. ` +
|
|
2884
|
+
`Only ${CONFIG_LOADER} may read the config (ADR-002 D1). Use ` +
|
|
2885
|
+
`loadRungateConfig / tryLoadRungateConfig / resolveConfig.`,
|
|
2886
|
+
);
|
|
2887
|
+
} else if (n < allowed) {
|
|
2888
|
+
out.push(
|
|
2889
|
+
`${label}: ${file} is banked at ${allowed} but only ${n} remain — lower the ` +
|
|
2890
|
+
`number in .claude/config-access-ratchet.json in the same commit that earned it.`,
|
|
2891
|
+
);
|
|
2892
|
+
}
|
|
2893
|
+
}
|
|
2894
|
+
for (const [file, allowed] of Object.entries(banked).sort()) {
|
|
2895
|
+
if (allowed > 0 && !(file in scan.counts)) {
|
|
2896
|
+
out.push(
|
|
2897
|
+
`${label}: ${file} is banked at ${allowed} but has no violations left — ` +
|
|
2898
|
+
`remove its entry from .claude/config-access-ratchet.json.`,
|
|
2899
|
+
);
|
|
2900
|
+
}
|
|
2901
|
+
}
|
|
2902
|
+
return out;
|
|
2903
|
+
}
|
|
2904
|
+
|
|
2905
|
+
/**
|
|
2906
|
+
* CHECK-1 — direct config access in TypeScript sources (ADR-002 D4).
|
|
2907
|
+
*
|
|
2908
|
+
* FAILS; does not warn. `DEPTH-1` and `ABSENCE-1` only `console.warn`, and
|
|
2909
|
+
* warnings are how 89 sites accumulated with the policy written down.
|
|
2910
|
+
*/
|
|
2911
|
+
export function runConfigAccessValidation(root: string) {
|
|
2912
|
+
describe("Config access (ADR-002 D1)", () => {
|
|
2913
|
+
test("CONFIG-1: only the loader reads the rungate config", () => {
|
|
2914
|
+
const scan = scanConfigAccess(root);
|
|
2915
|
+
const violations = configAccessViolations(
|
|
2916
|
+
scan,
|
|
2917
|
+
readConfigAccessRatchet(root, "sources"),
|
|
2918
|
+
"CONFIG-1",
|
|
2919
|
+
);
|
|
2920
|
+
for (const v of violations) {
|
|
2921
|
+
addFinding({
|
|
2922
|
+
ruleId: "CONFIG-1",
|
|
2923
|
+
severity: "FAIL",
|
|
2924
|
+
file: v.split(": ")[1]?.split(" ")[0] || "",
|
|
2925
|
+
message: v,
|
|
2926
|
+
fixCommand: "Route the read through lib/config-loader.ts",
|
|
2927
|
+
});
|
|
2928
|
+
}
|
|
2929
|
+
expect(violations, violations.join("\n")).toEqual([]);
|
|
2930
|
+
});
|
|
2931
|
+
});
|
|
2932
|
+
}
|
|
2933
|
+
|
|
2934
|
+
/**
|
|
2935
|
+
* CHECK-2 — config access inside workflow prompt text (ADR-002 D4).
|
|
2936
|
+
*
|
|
2937
|
+
* The check ADR-001 did not have, and the reason its single check would have
|
|
2938
|
+
* been insufficient: `ship.js:1637` reaches the config from inside a prompt.
|
|
2939
|
+
* Allowlist is empty — no workflow has any business reading it directly.
|
|
2940
|
+
*/
|
|
2941
|
+
export function runPromptConfigAccessValidation(root: string) {
|
|
2942
|
+
describe("Config access in workflows (ADR-002 D4)", () => {
|
|
2943
|
+
test("CONFIG-2: no workflow reaches the rungate config, prompts included", () => {
|
|
2944
|
+
const scan = scanPromptConfigAccess(root);
|
|
2945
|
+
// A project with no workflows/ directory is not in violation; the
|
|
2946
|
+
// empty-scan refusal above is for a scan that should have found files.
|
|
2947
|
+
const violations = configAccessViolations(
|
|
2948
|
+
scan,
|
|
2949
|
+
readConfigAccessRatchet(root, "workflows"),
|
|
2950
|
+
"CONFIG-2",
|
|
2951
|
+
scan.filesScanned > 0,
|
|
2952
|
+
);
|
|
2953
|
+
for (const v of violations) {
|
|
2954
|
+
addFinding({
|
|
2955
|
+
ruleId: "CONFIG-2",
|
|
2956
|
+
severity: "FAIL",
|
|
2957
|
+
file: v.split(": ")[1]?.split(" ")[0] || "",
|
|
2958
|
+
message: v,
|
|
2959
|
+
fixCommand: "Point the prompt at the resolved-config artefact instead",
|
|
2960
|
+
});
|
|
2961
|
+
}
|
|
2962
|
+
expect(violations, violations.join("\n")).toEqual([]);
|
|
2963
|
+
});
|
|
2964
|
+
});
|
|
2965
|
+
}
|
|
2966
|
+
|
|
943
2967
|
export function runAbsenceValidation(root: string) {
|
|
944
2968
|
describe("Absence validation", () => {
|
|
945
2969
|
test("ABSENCE-1: anti-criteria use absence verification", () => {
|
|
946
2970
|
const specsDir = join(root, "specs");
|
|
947
2971
|
if (!existsSync(specsDir)) return;
|
|
948
|
-
for (const f of
|
|
2972
|
+
for (const f of collectSpecFiles(specsDir)) { // #225 — subdirectories too
|
|
949
2973
|
const content = readFileSync(join(specsDir, f), "utf-8");
|
|
950
2974
|
const antiCriteria = content.match(/^- \[ \] SC-A\d+:.+$/gm) || [];
|
|
951
2975
|
for (const ac of antiCriteria) {
|