rungate 0.3.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/ac-quality.ts +119 -0
- package/lib/brief-precedence.ts +114 -0
- package/lib/ci-checkout.ts +27 -1
- package/lib/compliance-backfill.ts +16 -4
- package/lib/compliance-report.ts +109 -8
- package/lib/config-loader.ts +129 -5
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +520 -27
- package/lib/context-docs.ts +182 -0
- package/lib/create-brief.ts +22 -17
- package/lib/create-sc.ts +55 -33
- package/lib/decomposition-waves.ts +197 -0
- package/lib/doc-scan-targets.ts +435 -0
- package/lib/gate-check-audit.ts +190 -0
- package/lib/generators/agents-md.ts +10 -5
- package/lib/issue-extraction.ts +368 -0
- package/lib/organize.ts +129 -40
- package/lib/package-closure.ts +111 -0
- package/lib/phase2-decomposition.ts +270 -0
- package/lib/prior-branch.ts +24 -1
- package/lib/project-aliases.ts +100 -0
- package/lib/prove-label-gate.ts +93 -0
- package/lib/release-preflight.ts +225 -15
- package/lib/rungate-schema.ts +36 -2
- package/lib/sc-cover.ts +92 -1
- package/lib/sc-ids.ts +151 -0
- package/lib/scaffold/pre-push-hook.ts +165 -0
- package/lib/scaffold/rehearsal.ts +330 -0
- package/lib/scaffold/steps.ts +175 -122
- package/lib/scaffold/write-steps.ts +167 -0
- package/lib/scope-denylist.ts +258 -0
- package/lib/scratch-cleanup.ts +198 -0
- package/lib/scratch-roots.ts +94 -0
- package/lib/task-completion-checks.ts +50 -3
- package/lib/typescript-project.ts +233 -0
- package/lib/validators/spec-validators.ts +23 -34
- package/lib/verified-push.ts +179 -2
- package/lib/workflow-security.ts +51 -7
- package/lib/worktree-cleanup.ts +318 -20
- package/lib/worktree-repo.ts +465 -0
- package/package.json +8 -2
- package/scripts/audit-specs.ts +134 -37
- package/scripts/audit-transcript.ts +259 -0
- package/scripts/create-sc.ts +15 -1
- package/scripts/detect-sc-drift.ts +200 -0
- package/scripts/extract-constraints.ts +16 -36
- package/scripts/scaffold-project.ts +26 -136
- package/scripts/split-spec.ts +315 -0
- package/scripts/sync-sc-status.ts +751 -0
|
@@ -0,0 +1,435 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a project's documentation actually lives (#440).
|
|
3
|
+
*
|
|
4
|
+
* `collectScanTargets` was four flat `readdirSync` loops — `*.md`, `docs/*.md`
|
|
5
|
+
* (skipping `archive`), `docs/adr/*.md`, `specs/*.md` — with no recursion.
|
|
6
|
+
* Measured on a consumer project: 84 files scanned, **28 missed**, and every
|
|
7
|
+
* one of the 28 sat in a directory that project's own
|
|
8
|
+
* `.claude/rules/docs-routing.md` names as a documentation location.
|
|
9
|
+
*
|
|
10
|
+
* | Missed | files |
|
|
11
|
+
* |---|---|
|
|
12
|
+
* | `docs/specs/` | 17 |
|
|
13
|
+
* | `reference/` | 5 |
|
|
14
|
+
* | `docs/designs/` | 3 |
|
|
15
|
+
* | `docs/agents/` | 3 |
|
|
16
|
+
*
|
|
17
|
+
* `docs/specs/` is the headline: specs are the densest source of hard
|
|
18
|
+
* constraints in a repo, and the extractor scanned `specs/` (2 files) while
|
|
19
|
+
* skipping `docs/specs/` (17). Same word, different directory, silently
|
|
20
|
+
* dropped.
|
|
21
|
+
*
|
|
22
|
+
* The fix that makes it self-correcting is to stop hardcoding. Every
|
|
23
|
+
* scaffolded project already has a routing table enumerating where its
|
|
24
|
+
* documentation lives — scaffold WRITES that file — so deriving the scan from
|
|
25
|
+
* it makes the extractor track each project's actual layout instead of a list
|
|
26
|
+
* someone has to remember to update.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "fs";
|
|
30
|
+
import { isAbsolute, join, relative, resolve } from "path";
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Directory names never descended into, wherever they appear.
|
|
34
|
+
*
|
|
35
|
+
* ONE exported list, so there is one thing to mutate and one place to add to.
|
|
36
|
+
* `worktrees` covers `.claude/worktrees`, which is the case the issue names:
|
|
37
|
+
* a worktree is a second copy of the whole repo, so descending into one
|
|
38
|
+
* doubles every constraint and attributes half of them to a path that will
|
|
39
|
+
* not exist tomorrow.
|
|
40
|
+
*/
|
|
41
|
+
export const SCAN_EXCLUDE_DIRS: readonly string[] = [
|
|
42
|
+
"archive", "node_modules", ".git", "worktrees", "dist", "build", "coverage",
|
|
43
|
+
];
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* How deep recursion goes beneath a named root.
|
|
47
|
+
*
|
|
48
|
+
* Bounded because the roots come from a file in the repo, and an unbounded
|
|
49
|
+
* walk driven by repo content is a denial of service with extra steps. Six is
|
|
50
|
+
* well past anything observed: the deepest documentation path measured was
|
|
51
|
+
* `specs/bootstrap-data-flow/<file>.md`, at two.
|
|
52
|
+
*/
|
|
53
|
+
export const MAX_SCAN_DEPTH = 6;
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Scanned when a project has no routing table.
|
|
57
|
+
*
|
|
58
|
+
* Exactly the four the hardcoded version used, so a project without a routing
|
|
59
|
+
* table sees no change in behaviour — the fallback is the old code, named and
|
|
60
|
+
* reported rather than assumed.
|
|
61
|
+
*/
|
|
62
|
+
/**
|
|
63
|
+
* How many directories may be walked.
|
|
64
|
+
*
|
|
65
|
+
* Depth was bounded from the start; breadth was not, and the roots come from
|
|
66
|
+
* a file in the repo — so a table naming thousands of directories is still a
|
|
67
|
+
* walk driven by repo content with no ceiling. Twenty is well past anything
|
|
68
|
+
* observed: this repo declares six.
|
|
69
|
+
*/
|
|
70
|
+
export const MAX_SCAN_ROOTS = 20;
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* How many files the scan may collect.
|
|
74
|
+
*
|
|
75
|
+
* A cap on roots is not a cap on work — twenty roots times six levels of
|
|
76
|
+
* unbounded fanout is still unbounded — so the bound belongs on the thing
|
|
77
|
+
* that actually grows. This repo's own scan collects 92.
|
|
78
|
+
*/
|
|
79
|
+
export const MAX_SCAN_FILES = 2000;
|
|
80
|
+
|
|
81
|
+
export const DEFAULT_SCAN_DIRS: readonly string[] = ["docs", "docs/adr", "specs"];
|
|
82
|
+
|
|
83
|
+
export const ROUTING_RELATIVE_PATH = join(".claude", "rules", "docs-routing.md");
|
|
84
|
+
|
|
85
|
+
export interface DocScanPlan {
|
|
86
|
+
/** Which list the roots came from. Never inferred by the caller. */
|
|
87
|
+
source: "routing" | "default";
|
|
88
|
+
/** Why, in a sentence — so a report can say it rather than imply it. */
|
|
89
|
+
reason: string;
|
|
90
|
+
/** Directories, relative to the project, that exist and were walked. */
|
|
91
|
+
roots: string[];
|
|
92
|
+
/**
|
|
93
|
+
* Directories the routing table names that are NOT on disk.
|
|
94
|
+
*
|
|
95
|
+
* UNMEASURED, not skipped. A routing table that has drifted from the tree
|
|
96
|
+
* is a finding about the project, and `0`, `[]` and "fine" are
|
|
97
|
+
* indistinguishable if it is dropped — which is the whole subject of
|
|
98
|
+
* `.claude/rules/config-access.md`'s *Silent Default Substitution*.
|
|
99
|
+
*/
|
|
100
|
+
unmeasured: string[];
|
|
101
|
+
/** Absolute paths, root-level flat plus each root walked. */
|
|
102
|
+
files: string[];
|
|
103
|
+
/**
|
|
104
|
+
* Paths refused because they resolve outside the project (BUG-440-A).
|
|
105
|
+
*
|
|
106
|
+
* Reported rather than dropped, for the same reason `unmeasured` is: a
|
|
107
|
+
* symlinked documentation root that silently contributes nothing is
|
|
108
|
+
* indistinguishable from one that was read and happened to be empty.
|
|
109
|
+
*/
|
|
110
|
+
refused: string[];
|
|
111
|
+
/**
|
|
112
|
+
* How many directories the walk entered.
|
|
113
|
+
*
|
|
114
|
+
* On the plan so that the file cap stopping the WALK is checkable rather
|
|
115
|
+
* than asserted in prose — a cap that only stops pushing bounds the output
|
|
116
|
+
* while the traversal keeps costing.
|
|
117
|
+
*/
|
|
118
|
+
walked: number;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* The resolved path, if it is really inside the project. Otherwise null.
|
|
123
|
+
*
|
|
124
|
+
* Lexical checks — `startsWith("/")`, `includes("..")` — cannot see a
|
|
125
|
+
* symlink, and recursion is what made that matter: the flat scan this
|
|
126
|
+
* replaces could not descend into `docs/elsewhere -> /somewhere`, so the
|
|
127
|
+
* exposure arrived with the walk. `extract-constraints` turns every `.md`
|
|
128
|
+
* sentence it reaches into a candidate constraint written to AGENTS.md, so
|
|
129
|
+
* one symlink in a cloned repo would copy markdown from anywhere the process
|
|
130
|
+
* can read into this project's rules.
|
|
131
|
+
*
|
|
132
|
+
* Containment, not a symlink ban: a link within the repo is ordinary, and
|
|
133
|
+
* refusing it would be a narrower detector than the thing being detected.
|
|
134
|
+
*/
|
|
135
|
+
/**
|
|
136
|
+
* Whether a resolved path lies in or under an excluded directory.
|
|
137
|
+
*
|
|
138
|
+
* Keyed on the RESOLVED path, not the entry name. Measured before this was
|
|
139
|
+
* fixed: `docs/vendor -> node_modules` produced
|
|
140
|
+
* `node_modules/pkg/README.md`, because the exclusion saw the label
|
|
141
|
+
* `vendor`. ONE decider for "is this excluded", so there is one binding to
|
|
142
|
+
* mutate and no second copy that could hold a case up after the first is
|
|
143
|
+
* broken.
|
|
144
|
+
*/
|
|
145
|
+
function excludedByPath(rootReal: string, real: string): boolean {
|
|
146
|
+
const rel = relative(rootReal, real);
|
|
147
|
+
if (rel === "") return false;
|
|
148
|
+
// Case-insensitive, always — not "when the filesystem is". On macOS and
|
|
149
|
+
// Windows `NODE_MODULES` and `node_modules` are one directory, and keying
|
|
150
|
+
// on the exact bytes let the whole list be bypassed by changing a letter.
|
|
151
|
+
// Measured before this: `docs/vendor -> NODE_MODULES` was scanned.
|
|
152
|
+
const lowered = SCAN_EXCLUDE_DIRS.map(d => d.toLowerCase());
|
|
153
|
+
return rel.split("/").some(seg => lowered.includes(seg.toLowerCase()));
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
function containedReal(rootReal: string, path: string): string | null {
|
|
157
|
+
let real: string;
|
|
158
|
+
try {
|
|
159
|
+
real = realpathSync(path);
|
|
160
|
+
} catch {
|
|
161
|
+
return null;
|
|
162
|
+
}
|
|
163
|
+
const rel = relative(rootReal, real);
|
|
164
|
+
if (rel !== "" && (rel.startsWith("..") || isAbsolute(rel))) return null;
|
|
165
|
+
return real;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Everything from the "Where to Create Things" heading onwards.
|
|
170
|
+
*
|
|
171
|
+
* The routing file has TWO tables and they mean different things. The first
|
|
172
|
+
* answers "where do I read about X"; the second answers "where do I put a new
|
|
173
|
+
* X", and it includes `src/` and `test/`. Reading both conflates
|
|
174
|
+
* documentation with source — measured on this repo, it pulled 36 files out
|
|
175
|
+
* of `test/fixtures/`, which is a synthetic project whose "constraints" would
|
|
176
|
+
* then be extracted and attributed to the real one.
|
|
177
|
+
*
|
|
178
|
+
* The cut is by SECTION rather than by column position. A parser tied to a
|
|
179
|
+
* column layout would silently read half when one table changed shape; a
|
|
180
|
+
* heading is what actually separates the two meanings.
|
|
181
|
+
*/
|
|
182
|
+
const CREATE_SECTION = /^##\s+Where to Create Things\s*$/m;
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* The directories a routing table names as places documentation is READ from.
|
|
186
|
+
*
|
|
187
|
+
* Tokens ending in `/` are directories; `CODE-MAP.md` and friends are single
|
|
188
|
+
* files already caught by the flat root scan.
|
|
189
|
+
*/
|
|
190
|
+
export function routedDirectories(routingText: string): string[] {
|
|
191
|
+
const cut = CREATE_SECTION.exec(routingText);
|
|
192
|
+
const readSection = cut ? routingText.slice(0, cut.index) : routingText;
|
|
193
|
+
const out: string[] = [];
|
|
194
|
+
for (const m of readSection.matchAll(/`([^`]+)`/g)) {
|
|
195
|
+
const token = m[1]!.trim();
|
|
196
|
+
if (!token.endsWith("/")) continue;
|
|
197
|
+
const dir = token.replace(/\/+$/, "");
|
|
198
|
+
if (dir === "" || dir.startsWith("/") || dir.includes("..")) continue;
|
|
199
|
+
// "(6 specs)" and similar annotations live outside the backticks, but a
|
|
200
|
+
// token with whitespace in it is prose, not a path.
|
|
201
|
+
if (/\s/.test(dir)) continue;
|
|
202
|
+
if (!out.includes(dir)) out.push(dir);
|
|
203
|
+
}
|
|
204
|
+
return out;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
interface WalkState {
|
|
208
|
+
projectPath: string;
|
|
209
|
+
rootReal: string;
|
|
210
|
+
/**
|
|
211
|
+
* Resolved paths already handled.
|
|
212
|
+
*
|
|
213
|
+
* Keyed on the RESOLVED path, which is what makes it do two jobs: it stops
|
|
214
|
+
* a symlink loop, and it stops one file reachable under two names from
|
|
215
|
+
* being collected twice. A file counted twice reads as two independent
|
|
216
|
+
* sources agreeing, which is the evidence a reader weighs most heavily.
|
|
217
|
+
*/
|
|
218
|
+
seen: Set<string>;
|
|
219
|
+
files: string[];
|
|
220
|
+
refused: string[];
|
|
221
|
+
truncatedFiles: number;
|
|
222
|
+
walked: number;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* The project-anchored canonical spelling of a contained path.
|
|
227
|
+
*
|
|
228
|
+
* `real` is correct but anchored on the resolved root, and on macOS that is
|
|
229
|
+
* `/private/var/...` where the caller said `/var/...`. Callers do
|
|
230
|
+
* `relative(projectPath, file)`, so the path has to keep the caller's
|
|
231
|
+
* spelling of the root while taking the resolved spelling of everything
|
|
232
|
+
* below it.
|
|
233
|
+
*
|
|
234
|
+
* Reporting the canonical name also makes the list deterministic: a file
|
|
235
|
+
* reachable both directly and through an internal symlink was otherwise
|
|
236
|
+
* recorded under whichever name `readdirSync` happened to return first.
|
|
237
|
+
*/
|
|
238
|
+
function anchored(projectPath: string, rootReal: string, real: string): string {
|
|
239
|
+
const rel = relative(rootReal, real);
|
|
240
|
+
return rel === "" ? projectPath : join(projectPath, rel);
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
function walkMarkdown(dir: string, depth: number, st: WalkState): void {
|
|
244
|
+
if (depth > MAX_SCAN_DEPTH) return;
|
|
245
|
+
// The cap stops the WALK. Stopping only the push bounds `files` while the
|
|
246
|
+
// traversal and `st.seen` keep growing, which caps the output and not the
|
|
247
|
+
// work.
|
|
248
|
+
if (st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; return; }
|
|
249
|
+
st.walked++;
|
|
250
|
+
let entries: string[];
|
|
251
|
+
try {
|
|
252
|
+
entries = readdirSync(dir);
|
|
253
|
+
} catch {
|
|
254
|
+
return;
|
|
255
|
+
}
|
|
256
|
+
for (const entry of entries) {
|
|
257
|
+
const path = join(dir, entry);
|
|
258
|
+
const isMarkdown = entry.endsWith(".md");
|
|
259
|
+
let isDir: boolean;
|
|
260
|
+
try {
|
|
261
|
+
isDir = statSync(path).isDirectory();
|
|
262
|
+
} catch {
|
|
263
|
+
continue;
|
|
264
|
+
}
|
|
265
|
+
if (!isDir && !isMarkdown) continue;
|
|
266
|
+
|
|
267
|
+
const real = containedReal(st.rootReal, path);
|
|
268
|
+
if (real === null) {
|
|
269
|
+
st.refused.push(path);
|
|
270
|
+
continue;
|
|
271
|
+
}
|
|
272
|
+
if (excludedByPath(st.rootReal, real)) {
|
|
273
|
+
st.refused.push(real);
|
|
274
|
+
continue;
|
|
275
|
+
}
|
|
276
|
+
if (st.seen.has(real)) continue;
|
|
277
|
+
st.seen.add(real);
|
|
278
|
+
if (!isDir && st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; continue; }
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
// The RESOLVED path is what gets walked and recorded, not the path that
|
|
282
|
+
// was validated a moment ago. Validating one value and using another is
|
|
283
|
+
// a window, however narrow, and using `real` closes it for free.
|
|
284
|
+
if (isDir) walkMarkdown(real, depth + 1, st);
|
|
285
|
+
else st.files.push(anchored(st.projectPath, st.rootReal, real));
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Plan the scan for one project.
|
|
291
|
+
*
|
|
292
|
+
* Root-level `.md` files are read FLAT, exactly as before — recursing from
|
|
293
|
+
* the project root would reach `test/`, `lib/` and every fixture in the tree.
|
|
294
|
+
* Only the named documentation directories are walked.
|
|
295
|
+
*/
|
|
296
|
+
export function planDocScan(projectPath: string): DocScanPlan {
|
|
297
|
+
const routingPath = join(projectPath, ROUTING_RELATIVE_PATH);
|
|
298
|
+
const hasRouting = existsSync(routingPath);
|
|
299
|
+
|
|
300
|
+
let declared: string[];
|
|
301
|
+
let source: DocScanPlan["source"];
|
|
302
|
+
let reason: string;
|
|
303
|
+
|
|
304
|
+
if (hasRouting) {
|
|
305
|
+
const routed = routedDirectories(readFileSync(routingPath, "utf-8"));
|
|
306
|
+
// UNION with the defaults, never replacement. This repo's own routing
|
|
307
|
+
// table names `docs/adr/` and `docs/research/` but not `docs/` — so a
|
|
308
|
+
// routing-only scan would have LOST the top-level `docs/*.md` the old
|
|
309
|
+
// code read. A fix for a scan that missed 28 files must not miss
|
|
310
|
+
// different ones.
|
|
311
|
+
declared = [...new Set([...routed, ...DEFAULT_SCAN_DIRS])];
|
|
312
|
+
// `source` answers "did the routing table contribute anything", which is
|
|
313
|
+
// not the same question as "does the file exist". A table naming nothing
|
|
314
|
+
// leaves the defaults doing all the work, and saying "routing" there
|
|
315
|
+
// would report a derivation that did not happen.
|
|
316
|
+
source = routed.length > 0 ? "routing" : "default";
|
|
317
|
+
reason = routed.length > 0
|
|
318
|
+
? `${routed.length} directories named in ${ROUTING_RELATIVE_PATH}, unioned with the default set`
|
|
319
|
+
: `${ROUTING_RELATIVE_PATH} exists but names no directories — the default set only`;
|
|
320
|
+
} else {
|
|
321
|
+
declared = [...DEFAULT_SCAN_DIRS];
|
|
322
|
+
source = "default";
|
|
323
|
+
reason = `no ${ROUTING_RELATIVE_PATH} — scanning the documented default set`;
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
let rootReal: string;
|
|
327
|
+
try {
|
|
328
|
+
rootReal = realpathSync(resolve(projectPath));
|
|
329
|
+
} catch {
|
|
330
|
+
// Loud, not empty. A project root that cannot be resolved has nothing to
|
|
331
|
+
// scan, and returning zero files would be indistinguishable from a
|
|
332
|
+
// project whose documentation is genuinely empty — Silent Default
|
|
333
|
+
// Substitution, in `.claude/rules/config-access.md`'s terms.
|
|
334
|
+
throw new Error(`cannot scan documentation: ${projectPath} does not resolve to a directory`);
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
const st: WalkState = {
|
|
338
|
+
projectPath,
|
|
339
|
+
rootReal,
|
|
340
|
+
seen: new Set<string>(),
|
|
341
|
+
files: [],
|
|
342
|
+
refused: [],
|
|
343
|
+
truncatedFiles: 0,
|
|
344
|
+
walked: 0,
|
|
345
|
+
};
|
|
346
|
+
|
|
347
|
+
const roots: string[] = [];
|
|
348
|
+
const unmeasured: string[] = [];
|
|
349
|
+
let truncated = 0;
|
|
350
|
+
for (const dir of declared) {
|
|
351
|
+
// The exclusion list has to cover the roots as well as the entries.
|
|
352
|
+
// Applying it only inside the walk left a routing table naming
|
|
353
|
+
// `node_modules/` or `worktrees/` walked outright — the exact case the
|
|
354
|
+
// list exists to stop, reached by the one path the list did not cover.
|
|
355
|
+
const abs = join(projectPath, dir);
|
|
356
|
+
const declaredReal = containedReal(st.rootReal, abs);
|
|
357
|
+
if (declaredReal !== null && excludedByPath(st.rootReal, declaredReal)) {
|
|
358
|
+
st.refused.push(abs);
|
|
359
|
+
continue;
|
|
360
|
+
}
|
|
361
|
+
if (roots.length >= MAX_SCAN_ROOTS) { truncated++; continue; }
|
|
362
|
+
let present: boolean;
|
|
363
|
+
try {
|
|
364
|
+
present = statSync(abs).isDirectory();
|
|
365
|
+
} catch {
|
|
366
|
+
present = false;
|
|
367
|
+
}
|
|
368
|
+
if (present && declaredReal === null) {
|
|
369
|
+
// A routed root that leaves the project is neither walked nor silently
|
|
370
|
+
// treated as missing — "the project does not have this" and "the
|
|
371
|
+
// project points this somewhere I will not follow" are different facts.
|
|
372
|
+
st.refused.push(abs);
|
|
373
|
+
continue;
|
|
374
|
+
}
|
|
375
|
+
// Only a ROUTING entry can be unmeasured. A default directory a project
|
|
376
|
+
// simply does not have is not drift; the routing table is a claim the
|
|
377
|
+
// project made about itself, and a claim that does not hold is a finding.
|
|
378
|
+
if (present) roots.push(dir);
|
|
379
|
+
else if (source === "routing" && !DEFAULT_SCAN_DIRS.includes(dir)) unmeasured.push(dir);
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
if (truncated > 0) {
|
|
383
|
+
// Loud, not silent: a scan that quietly stopped at twenty directories
|
|
384
|
+
// reads as a scan that covered everything.
|
|
385
|
+
reason += ` — bounded at ${MAX_SCAN_ROOTS} roots, ${truncated} not walked`;
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
try {
|
|
389
|
+
for (const f of readdirSync(projectPath)) {
|
|
390
|
+
if (!f.endsWith(".md")) continue;
|
|
391
|
+
const path = join(projectPath, f);
|
|
392
|
+
const real = containedReal(st.rootReal, path);
|
|
393
|
+
if (real === null) { st.refused.push(path); continue; }
|
|
394
|
+
if (st.seen.has(real)) continue;
|
|
395
|
+
st.seen.add(real);
|
|
396
|
+
if (st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; continue; }
|
|
397
|
+
st.files.push(anchored(projectPath, st.rootReal, real));
|
|
398
|
+
}
|
|
399
|
+
} catch {
|
|
400
|
+
// An unreadable project root is the caller's problem, not a silent empty
|
|
401
|
+
// scan — it will show as zero files against a reason that says otherwise.
|
|
402
|
+
}
|
|
403
|
+
for (const dir of roots) walkMarkdown(join(projectPath, dir), 1, st);
|
|
404
|
+
|
|
405
|
+
if (st.truncatedFiles > 0) {
|
|
406
|
+
// Loud, not silent: a scan that quietly stopped reading files reads as
|
|
407
|
+
// a scan that covered everything it was pointed at.
|
|
408
|
+
reason += ` — bounded at ${MAX_SCAN_FILES} files, ${st.truncatedFiles} not read`;
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
st.files.sort();
|
|
412
|
+
st.refused.sort();
|
|
413
|
+
return {
|
|
414
|
+
source, reason, roots, unmeasured,
|
|
415
|
+
files: st.files, refused: st.refused, walked: st.walked,
|
|
416
|
+
};
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/** Relative paths, for a report that a human reads. */
|
|
420
|
+
export function planSummary(projectPath: string, plan: DocScanPlan): string {
|
|
421
|
+
const parts = [
|
|
422
|
+
`scan: ${plan.files.length} files from ${plan.roots.length} directories (${plan.source} — ${plan.reason})`,
|
|
423
|
+
];
|
|
424
|
+
if (plan.refused.length > 0) {
|
|
425
|
+
parts.push(
|
|
426
|
+
`REFUSED: ${plan.refused.map(r => relative(projectPath, r) || r).join(", ")} — resolves outside the project`,
|
|
427
|
+
);
|
|
428
|
+
}
|
|
429
|
+
if (plan.unmeasured.length > 0) {
|
|
430
|
+
parts.push(
|
|
431
|
+
`UNMEASURED: ${plan.unmeasured.join(", ")} — named in ${ROUTING_RELATIVE_PATH} but not present in ${relative(projectPath, projectPath) || "the project"}`,
|
|
432
|
+
);
|
|
433
|
+
}
|
|
434
|
+
return parts.join("\n");
|
|
435
|
+
}
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which gate checks cannot fail, and which of those meant to (#183, #176).
|
|
3
|
+
*
|
|
4
|
+
* #176 found three checks in `gates/workflow.test.ts` that were satisfied by
|
|
5
|
+
* configuration or by nothing at all. `tsc-pass` was the clearest: two early
|
|
6
|
+
* returns and an empty tail, no `expect`, no `tsc` invocation, no baseline
|
|
7
|
+
* comparison. It had been counted as a passing gate check for its whole life.
|
|
8
|
+
*
|
|
9
|
+
* #183 is the audit of the rest of that list, and the thing worth building is
|
|
10
|
+
* not a one-time report. **Nothing in the repo could tell a check that is
|
|
11
|
+
* deliberately a warning from a check whose assertion was forgotten**, and
|
|
12
|
+
* that is exactly the gap `tsc-pass` lived in. Three checks are warn-only
|
|
13
|
+
* today; two say so in their own comments and one does not.
|
|
14
|
+
*
|
|
15
|
+
* So the audit is a binding instead of a paragraph: every check with no
|
|
16
|
+
* assertion must be named here with a reason, and every name here must still
|
|
17
|
+
* be a check with no assertion. Both directions fail. Adding an `expect` to a
|
|
18
|
+
* warn-tier check means deleting its entry in the same commit, and adding a
|
|
19
|
+
* check with no assertion means either writing the reason down or writing the
|
|
20
|
+
* assertion.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
/** One `test(...)` in a gate suite, with the body a brace matcher found. */
|
|
24
|
+
export interface GateCheck {
|
|
25
|
+
/** The first argument to `test(...)`, as written. */
|
|
26
|
+
name: string;
|
|
27
|
+
/** 1-indexed line of the `test(` call. */
|
|
28
|
+
line: number;
|
|
29
|
+
/** Everything between the callback's braces. */
|
|
30
|
+
body: string;
|
|
31
|
+
/** Does any `expect(` appear in the body? */
|
|
32
|
+
hasAssertion: boolean;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Checks that intentionally only warn, each with the reason.
|
|
37
|
+
*
|
|
38
|
+
* A reason is required because the entry is the documentation. "It is on the
|
|
39
|
+
* list" is the same non-answer as a green check that never looked.
|
|
40
|
+
*/
|
|
41
|
+
export const WARN_TIER_CHECKS: Readonly<Record<string, string>> = Object.freeze({
|
|
42
|
+
"quinn-container-port: Quinn tested the container, not the dev server":
|
|
43
|
+
"#344 — turning this into a refusal changes what blocks live runs and needs its own " +
|
|
44
|
+
"measurement. The fix there was that it stops being WRONG (it compared against one " +
|
|
45
|
+
"consumer's literal port); making it block is a separate decision.",
|
|
46
|
+
"spec-decision-compliance: AC language aligns with spec decisions":
|
|
47
|
+
"#409 Decision #9 placed this in the WARN tier explicitly: it matches AC prose against " +
|
|
48
|
+
"regex anti-patterns, and a regex over prose is not a basis for refusing a run.",
|
|
49
|
+
"ac-issue-alignment: ACs cover goal keywords":
|
|
50
|
+
"#423 Decision — measured, then kept as a warning. ADR-009 C4 asks that ACs cover the " +
|
|
51
|
+
"goal's keywords and the body warns under 50% coverage. Measured over the 153 " +
|
|
52
|
+
"workflow-state.json files under ~/.rungate carrying a goal: 71% fall under that " +
|
|
53
|
+
"threshold, median coverage 38%. Restricted to states whose ACs carry real statements " +
|
|
54
|
+
"the figure is 66% of 131, median 41%; for substantial ones, 73% of 101. The number does " +
|
|
55
|
+
"not move, and a check that would refuse two runs in three is an outage rather than a " +
|
|
56
|
+
"gate. Same basis #409 Decision #9 rejected for spec-decision-compliance: a match over " +
|
|
57
|
+
"prose is not grounds for refusing a run. The reading is lib/ac-quality.ts's " +
|
|
58
|
+
"goalKeywordCoverage so the threshold is drivable from both sides by a test.",
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* The stub a `describe` block substitutes when there is no workflow state.
|
|
63
|
+
*
|
|
64
|
+
* Not a check and not a warn-tier check — a placeholder so bun does not report
|
|
65
|
+
* an empty describe. It is separated out rather than allowlisted because the
|
|
66
|
+
* property that matters is different: a stub must have an EMPTY body. A stub
|
|
67
|
+
* that grew logic would be a check that runs only when nothing is being gated.
|
|
68
|
+
*/
|
|
69
|
+
export const STANDALONE_STUB_NAME = "skipped — no active workflow (standalone run)";
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* `expect(` — and `expect<T>(`, which the first draft of this regex missed.
|
|
73
|
+
*
|
|
74
|
+
* It reported `workflow-state.json validates` as having no assertion when the
|
|
75
|
+
* assertion is on the line below, written `expect<boolean>(...)` to widen a
|
|
76
|
+
* narrowed type. A detector that misses a form in its own tree is the second
|
|
77
|
+
* shape in `.claude/rules/checks-must-be-able-to-fail.md`, so the generic form
|
|
78
|
+
* is a case in the test rather than a note here.
|
|
79
|
+
*/
|
|
80
|
+
const ASSERTION = /\bexpect\s*(?:<[^>()]*>)?\s*\(/;
|
|
81
|
+
|
|
82
|
+
/** `(`/`[`/`{` depth-aware scan that skips strings, templates and comments. */
|
|
83
|
+
function matchingParen(source: string, openAt: number): number {
|
|
84
|
+
let depth = 0;
|
|
85
|
+
for (let i = openAt; i < source.length; i++) {
|
|
86
|
+
const c = source[i];
|
|
87
|
+
const next = source[i + 1];
|
|
88
|
+
if (c === "/" && next === "/") {
|
|
89
|
+
const nl = source.indexOf("\n", i);
|
|
90
|
+
i = nl === -1 ? source.length : nl;
|
|
91
|
+
continue;
|
|
92
|
+
}
|
|
93
|
+
if (c === "/" && next === "*") {
|
|
94
|
+
const close = source.indexOf("*/", i + 2);
|
|
95
|
+
i = close === -1 ? source.length : close + 1;
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
98
|
+
if (c === '"' || c === "'" || c === "`") {
|
|
99
|
+
const quote = c;
|
|
100
|
+
i++;
|
|
101
|
+
for (; i < source.length; i++) {
|
|
102
|
+
if (source[i] === "\\") { i++; continue; }
|
|
103
|
+
if (source[i] === quote) break;
|
|
104
|
+
// A `${` inside a template can itself contain the quote character, so
|
|
105
|
+
// the expression is skipped as a unit rather than scanned for one.
|
|
106
|
+
if (quote === "`" && source[i] === "$" && source[i + 1] === "{") {
|
|
107
|
+
let d = 1;
|
|
108
|
+
i += 2;
|
|
109
|
+
for (; i < source.length && d > 0; i++) {
|
|
110
|
+
if (source[i] === "{") d++;
|
|
111
|
+
else if (source[i] === "}") d--;
|
|
112
|
+
}
|
|
113
|
+
i--;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
continue;
|
|
117
|
+
}
|
|
118
|
+
if (c === "(" || c === "[" || c === "{") depth++;
|
|
119
|
+
else if (c === ")" || c === "]" || c === "}") {
|
|
120
|
+
depth--;
|
|
121
|
+
if (depth === 0) return i;
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
return -1;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Every `test("...", ...)` in a suite source, with its body.
|
|
129
|
+
*
|
|
130
|
+
* Brace-matched rather than indentation-matched. An indentation heuristic was
|
|
131
|
+
* the first attempt and it found 27 of 79 — it stopped at the first `});` that
|
|
132
|
+
* happened to sit at the right column, which in a file of nested `describe`
|
|
133
|
+
* blocks is almost immediately. A parser that silently sees a third of its
|
|
134
|
+
* input is the defect this whole file is about, so `parsesEveryCheck` below is
|
|
135
|
+
* asserted by the test rather than assumed here.
|
|
136
|
+
*/
|
|
137
|
+
export function gateChecks(source: string): GateCheck[] {
|
|
138
|
+
const checks: GateCheck[] = [];
|
|
139
|
+
const re = /(^|\n)(\s*)test\(\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`)/g;
|
|
140
|
+
let m: RegExpExecArray | null;
|
|
141
|
+
while ((m = re.exec(source)) !== null) {
|
|
142
|
+
const name = (m[3] ?? m[4] ?? m[5])!;
|
|
143
|
+
const callAt = m.index + m[1]!.length + m[2]!.length;
|
|
144
|
+
const openAt = source.indexOf("(", callAt);
|
|
145
|
+
const closeAt = matchingParen(source, openAt);
|
|
146
|
+
if (closeAt === -1) continue;
|
|
147
|
+
const call = source.slice(openAt, closeAt);
|
|
148
|
+
// The body is everything after the first `=> {` or `function () {` inside
|
|
149
|
+
// the call. Taking the whole call would count an `expect` in the test's
|
|
150
|
+
// own name or options object as an assertion.
|
|
151
|
+
const arrow = call.indexOf("=> {");
|
|
152
|
+
const body = arrow === -1 ? call : call.slice(arrow + 4);
|
|
153
|
+
checks.push({
|
|
154
|
+
name,
|
|
155
|
+
line: source.slice(0, callAt).split("\n").length,
|
|
156
|
+
body,
|
|
157
|
+
hasAssertion: ASSERTION.test(body),
|
|
158
|
+
});
|
|
159
|
+
re.lastIndex = closeAt;
|
|
160
|
+
}
|
|
161
|
+
return checks;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** Checks with no `expect(` anywhere in the body, in source order. */
|
|
165
|
+
export function checksWithoutAssertions(source: string): GateCheck[] {
|
|
166
|
+
return gateChecks(source).filter(c => !c.hasAssertion && c.name !== STANDALONE_STUB_NAME);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** The standalone placeholders, so their emptiness can be asserted. */
|
|
170
|
+
export function standaloneStubs(source: string): GateCheck[] {
|
|
171
|
+
return gateChecks(source).filter(c => c.name === STANDALONE_STUB_NAME);
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* Reads a field off `environments` that something other than a measurement
|
|
176
|
+
* writes — #176's second shape.
|
|
177
|
+
*
|
|
178
|
+
* Returns one entry per `sf("environments")?.<env>?.<field>` read, so the
|
|
179
|
+
* audit can name the writer of each. Text, deliberately: the point is to
|
|
180
|
+
* enumerate the reads so a human checks each writer, not to decide which are
|
|
181
|
+
* honest. A detector that tried to decide would be the narrower-than-what-it-
|
|
182
|
+
* detects shape in `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
183
|
+
*/
|
|
184
|
+
export function environmentVerdictReads(source: string): string[] {
|
|
185
|
+
const out = new Set<string>();
|
|
186
|
+
for (const m of source.matchAll(/sf\("environments"\)\?\.(\w+)\?\.(\w+)/g)) {
|
|
187
|
+
out.add(`${m[1]}.${m[2]}`);
|
|
188
|
+
}
|
|
189
|
+
return [...out].sort();
|
|
190
|
+
}
|
|
@@ -12,6 +12,7 @@ import { join } from "path";
|
|
|
12
12
|
import type { ProjectScan } from "./types";
|
|
13
13
|
import { OWNED_FILES, ownedFilesTable } from "../scaffold/owned-files";
|
|
14
14
|
import { isHarnessItself } from "../harness-identity";
|
|
15
|
+
import { typecheckDecision } from "../typescript-project";
|
|
15
16
|
|
|
16
17
|
/**
|
|
17
18
|
* Build the AGENTS.md frontmatter block.
|
|
@@ -102,11 +103,15 @@ export function generateAgentsMd(scan: ProjectScan): string {
|
|
|
102
103
|
// without a tsconfig.json that command prints help and exits 1. Every project
|
|
103
104
|
// scaffolded by rungate — including rungate — documented a type check that
|
|
104
105
|
// had never checked anything (#65/#76).
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
106
|
+
//
|
|
107
|
+
// #87 — which command, and whether there is one, is `typecheckDecision`'s to
|
|
108
|
+
// answer. This site had its own copy of the ladder and a third site had a
|
|
109
|
+
// different one again, so a project with its own `typecheck` script was
|
|
110
|
+
// documented as running `bunx tsc --noEmit` instead.
|
|
111
|
+
const typecheckCommand = typecheckDecision(scan.root).command;
|
|
112
|
+
const typecheckRow = typecheckCommand
|
|
113
|
+
? `\n| Type check | \`${typecheckCommand}\` |`
|
|
114
|
+
: "";
|
|
110
115
|
|
|
111
116
|
// The command that reproduces CI locally. Worth a row only where the script
|
|
112
117
|
// exists: a documented command that is not present is how the type check row
|