rungate 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/config/behavioral-sc-map.json +170 -0
- package/config/brief-policies.json +28 -0
- package/config/ceremony-profiles.json +207 -0
- package/config/check-registry.json +114 -0
- package/config/matcher-registry.json +142 -0
- package/config/prove-evidence.schema.json +65 -0
- package/config/spec-policies.json +36 -0
- package/config/universal-rules.yaml +15 -0
- package/config/workflow-schema.json +279 -0
- package/lib/ac-quality.ts +119 -0
- package/lib/cli-commands.ts +7 -1
- package/lib/config-loader.ts +129 -5
- package/lib/conformity.ts +1122 -31
- package/lib/context-docs.ts +182 -0
- package/lib/create-brief.ts +22 -17
- package/lib/create-sc.ts +35 -8
- package/lib/doc-scan-targets.ts +435 -0
- package/lib/gate-check-audit.ts +9 -9
- package/lib/github.ts +195 -0
- package/lib/js-top-level-code.ts +27 -2
- package/lib/organize.ts +129 -40
- package/lib/package-closure.ts +387 -0
- package/lib/project-aliases.ts +100 -0
- package/lib/release-preflight.ts +352 -48
- package/lib/rungate-schema.ts +23 -1
- package/lib/sc-cover.ts +92 -1
- package/lib/sc-ids.ts +151 -0
- package/lib/scaffold/defaults.ts +40 -0
- package/lib/scaffold/managed-workflow.ts +125 -27
- package/lib/scaffold/owned-files.ts +6 -0
- package/lib/scaffold/profiles.ts +94 -0
- package/lib/scaffold/rehearsal.ts +355 -0
- package/lib/scaffold/steps.ts +787 -105
- package/lib/scaffold/write-steps.ts +208 -0
- package/lib/scratch-cleanup.ts +198 -0
- package/lib/scratch-roots.ts +94 -0
- package/lib/source-anchor.ts +144 -0
- package/lib/success-doc.ts +779 -0
- package/lib/suite-run-reading.ts +194 -0
- package/lib/test-census.ts +199 -0
- package/lib/trajectory.ts +377 -0
- package/lib/validators/spec-validators.ts +52 -35
- package/lib/workflow-security.ts +152 -7
- package/lib/workflow-test-harness.ts +349 -0
- package/lib/worktree-cleanup.ts +123 -7
- package/lib/worktree-repo.ts +165 -0
- package/package.json +10 -1
- package/scripts/audit-specs.ts +134 -37
- package/scripts/audit-transcript.ts +259 -0
- package/scripts/create-sc.ts +15 -1
- package/scripts/create-success.ts +162 -0
- package/scripts/detect-sc-drift.ts +200 -0
- package/scripts/extract-constraints.ts +16 -36
- package/scripts/scaffold-project.ts +51 -137
- package/scripts/split-spec.ts +315 -0
- package/scripts/sync-sc-status.ts +751 -0
- package/specs/SPEC-TEMPLATE.md +200 -0
- package/templates/SUCCESS-TEMPLATE.md +72 -0
- package/templates/agent-briefs/_shared.md +9 -0
- package/templates/agent-briefs/aditi.md +46 -0
- package/templates/agent-briefs/discovery.md +37 -0
- package/templates/agent-briefs/marcus.md +39 -0
- package/templates/agent-briefs/quinn.md +67 -0
- package/templates/agent-briefs/rook.md +40 -0
- package/templates/agent-briefs/serena.md +39 -0
|
@@ -0,0 +1,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
|
+
}
|
package/lib/gate-check-audit.ts
CHANGED
|
@@ -46,16 +46,16 @@ export const WARN_TIER_CHECKS: Readonly<Record<string, string>> = Object.freeze(
|
|
|
46
46
|
"spec-decision-compliance: AC language aligns with spec decisions":
|
|
47
47
|
"#409 Decision #9 placed this in the WARN tier explicitly: it matches AC prose against " +
|
|
48
48
|
"regex anti-patterns, and a regex over prose is not a basis for refusing a run.",
|
|
49
|
-
"outcome-evidence-behavioral: OUTCOME AC evidence is not just a number":
|
|
50
|
-
"#183 — reported, not fixed. This one is NOT a documented decision like the two above; " +
|
|
51
|
-
"it is `tsc-pass`'s shape with a console.warn where the assertion should be, and the " +
|
|
52
|
-
"sibling check `outcome-acs-no-skip` two tests above it does assert. Tightening it is a " +
|
|
53
|
-
"behaviour change to a live gate and belongs to its own issue.",
|
|
54
49
|
"ac-issue-alignment: ACs cover goal keywords":
|
|
55
|
-
"#
|
|
56
|
-
"
|
|
57
|
-
"
|
|
58
|
-
"
|
|
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
59
|
});
|
|
60
60
|
|
|
61
61
|
/**
|
package/lib/github.ts
CHANGED
|
@@ -37,6 +37,16 @@ export interface GitHubClient {
|
|
|
37
37
|
update: (params: { owner: string; repo: string; pull_number: number; [key: string]: any }) => Promise<{ data: any }>;
|
|
38
38
|
list: (params: { owner: string; repo: string; [key: string]: any }) => Promise<{ data: any[] }>;
|
|
39
39
|
};
|
|
40
|
+
checks: {
|
|
41
|
+
/**
|
|
42
|
+
* Check runs for one ref (#46).
|
|
43
|
+
*
|
|
44
|
+
* `ref` is passed a commit SHA and never a branch name. The endpoint
|
|
45
|
+
* accepts both, and the branch form is the whole defect this gate would
|
|
46
|
+
* otherwise introduce — see `readCi`.
|
|
47
|
+
*/
|
|
48
|
+
listForRef: (params: { owner: string; repo: string; ref: string; per_page?: number }) => Promise<{ data: { total_count: number; check_runs: any[] } }>;
|
|
49
|
+
};
|
|
40
50
|
};
|
|
41
51
|
/**
|
|
42
52
|
* The GraphQL endpoint, for the handful of operations REST does not expose.
|
|
@@ -537,3 +547,188 @@ export async function listPRs(client: GitHubClient, repoSlug: string, opts?: Lis
|
|
|
537
547
|
});
|
|
538
548
|
return response.data;
|
|
539
549
|
}
|
|
550
|
+
|
|
551
|
+
// ── CI verification (#46) ────────────────────────────────────
|
|
552
|
+
|
|
553
|
+
/**
|
|
554
|
+
* One check run, reduced to the four fields a verdict depends on.
|
|
555
|
+
*
|
|
556
|
+
* `headSha` is carried even though the query is already keyed on a SHA. It is
|
|
557
|
+
* the field `readCi` re-checks, and re-checking it is the point: see below.
|
|
558
|
+
*/
|
|
559
|
+
export interface CheckRunSummary {
|
|
560
|
+
name: string;
|
|
561
|
+
/** `queued` | `in_progress` | `completed`, per the checks API. */
|
|
562
|
+
status: string;
|
|
563
|
+
/** `null` until the run completes. Never treat null as success. */
|
|
564
|
+
conclusion: string | null;
|
|
565
|
+
headSha: string;
|
|
566
|
+
url?: string;
|
|
567
|
+
}
|
|
568
|
+
|
|
569
|
+
export interface CiReading {
|
|
570
|
+
verdict: "PASS" | "FAIL" | "UNMEASURED";
|
|
571
|
+
/** The commit the verdict is ABOUT. A reading without this is not a reading. */
|
|
572
|
+
sha: string;
|
|
573
|
+
/** A sentence naming why, in every branch including PASS. */
|
|
574
|
+
reason: string;
|
|
575
|
+
checks: CheckRunSummary[];
|
|
576
|
+
failed: string[];
|
|
577
|
+
pending: string[];
|
|
578
|
+
/** Checks that completed without concluding either way — skipped, neutral. */
|
|
579
|
+
inconclusive: string[];
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
/**
|
|
583
|
+
* Conclusions that mean the check ran and said no.
|
|
584
|
+
*
|
|
585
|
+
* `cancelled` is in here deliberately. A cancelled run measured nothing, so
|
|
586
|
+
* the tempting reading is UNMEASURED — but on this repo's CI a cancellation is
|
|
587
|
+
* almost always `concurrency: cancel-in-progress` superseding the run, and
|
|
588
|
+
* calling that "unmeasured" lets a superseded commit's gate pass on a reading
|
|
589
|
+
* about a commit nobody is shipping. FAIL is the direction that costs a re-run
|
|
590
|
+
* rather than a bad merge.
|
|
591
|
+
*/
|
|
592
|
+
const CI_FAILURE_CONCLUSIONS = new Set([
|
|
593
|
+
"failure",
|
|
594
|
+
"timed_out",
|
|
595
|
+
"cancelled",
|
|
596
|
+
"action_required",
|
|
597
|
+
"startup_failure",
|
|
598
|
+
"stale",
|
|
599
|
+
]);
|
|
600
|
+
|
|
601
|
+
/**
|
|
602
|
+
* Conclusions that completed without answering the question.
|
|
603
|
+
*
|
|
604
|
+
* `skipped` is the one that matters. A skipped check is the single most
|
|
605
|
+
* convincing-looking way for this gate to certify nothing: the run exists, it
|
|
606
|
+
* completed, it did not fail, and a verdict computed as "no failures" calls it
|
|
607
|
+
* PASS. It measured nothing, so the reading is UNMEASURED.
|
|
608
|
+
*/
|
|
609
|
+
const CI_INCONCLUSIVE_CONCLUSIONS = new Set(["skipped", "neutral"]);
|
|
610
|
+
|
|
611
|
+
/**
|
|
612
|
+
* The verdict for one commit, from the checks recorded against it.
|
|
613
|
+
*
|
|
614
|
+
* Pure, and separate from the fetching, because every interesting decision
|
|
615
|
+
* here is a classification rather than a network call — and the classification
|
|
616
|
+
* is the part that has to be wrong-proof.
|
|
617
|
+
*
|
|
618
|
+
* **There is no branch that arrives at PASS by not finding a failure.** PASS
|
|
619
|
+
* requires at least one check, every check belonging to this exact commit,
|
|
620
|
+
* every check `completed`, and every conclusion `success`. Absence, pending,
|
|
621
|
+
* skipped and null all land elsewhere. That is the whole design: the natural
|
|
622
|
+
* implementation of "did CI pass" is `!checks.some(failed)`, which returns
|
|
623
|
+
* true for a commit CI has never heard of.
|
|
624
|
+
*
|
|
625
|
+
* **A check whose `headSha` differs is discarded, not counted.** The checks
|
|
626
|
+
* API accepts a branch name as `ref` and will happily answer about whatever
|
|
627
|
+
* commit that branch pointed at when CI last ran — so a gate keyed on the
|
|
628
|
+
* branch certifies the previous push. Filtering here means that even a caller
|
|
629
|
+
* who passes a branch name gets UNMEASURED rather than a stale PASS.
|
|
630
|
+
*/
|
|
631
|
+
export function readCi(sha: string, checks: CheckRunSummary[]): CiReading {
|
|
632
|
+
const base = { sha, checks, failed: [] as string[], pending: [] as string[], inconclusive: [] as string[] };
|
|
633
|
+
|
|
634
|
+
if (!sha || !/^[0-9a-f]{7,40}$/i.test(sha)) {
|
|
635
|
+
return { ...base, verdict: "UNMEASURED", reason: `"${sha}" is not a commit SHA, so there is nothing to ask CI about — a ref that is not a SHA would be answered about whatever commit it last pointed at` };
|
|
636
|
+
}
|
|
637
|
+
|
|
638
|
+
const mine = checks.filter(c => c.headSha === sha);
|
|
639
|
+
const foreign = checks.filter(c => c.headSha !== sha);
|
|
640
|
+
if (mine.length === 0) {
|
|
641
|
+
return {
|
|
642
|
+
...base,
|
|
643
|
+
verdict: "UNMEASURED",
|
|
644
|
+
reason: foreign.length > 0
|
|
645
|
+
? `every check found belongs to a different commit (${[...new Set(foreign.map(c => c.headSha))].join(", ")}), not ${sha} — this is the stale reading, not a pass`
|
|
646
|
+
: `no check has been recorded for ${sha} — CI has not reported on this commit, which is not the same as reporting success`,
|
|
647
|
+
};
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
const failed = mine.filter(c => c.conclusion !== null && CI_FAILURE_CONCLUSIONS.has(c.conclusion)).map(c => c.name);
|
|
651
|
+
const pending = mine.filter(c => c.status !== "completed").map(c => c.name);
|
|
652
|
+
const inconclusive = mine
|
|
653
|
+
.filter(c => c.status === "completed" && (c.conclusion === null || CI_INCONCLUSIVE_CONCLUSIONS.has(c.conclusion)))
|
|
654
|
+
.map(c => c.name);
|
|
655
|
+
const full = { ...base, checks: mine, failed, pending, inconclusive };
|
|
656
|
+
|
|
657
|
+
// A failure first, even with others still running. More waiting cannot
|
|
658
|
+
// un-fail a check, and reporting UNMEASURED here would turn a known red into
|
|
659
|
+
// "we did not find out".
|
|
660
|
+
if (failed.length > 0) {
|
|
661
|
+
return { ...full, verdict: "FAIL", reason: `CI failed on ${sha}: ${failed.join(", ")}` };
|
|
662
|
+
}
|
|
663
|
+
if (pending.length > 0) {
|
|
664
|
+
return { ...full, verdict: "UNMEASURED", reason: `CI has not finished on ${sha} — still running: ${pending.join(", ")}` };
|
|
665
|
+
}
|
|
666
|
+
if (inconclusive.length > 0) {
|
|
667
|
+
return { ...full, verdict: "UNMEASURED", reason: `CI completed on ${sha} without measuring: ${inconclusive.join(", ")} neither passed nor failed` };
|
|
668
|
+
}
|
|
669
|
+
return { ...full, verdict: "PASS", reason: `all ${mine.length} check${mine.length === 1 ? "" : "s"} passed on ${sha}: ${mine.map(c => c.name).join(", ")}` };
|
|
670
|
+
}
|
|
671
|
+
|
|
672
|
+
/** The check runs GitHub has recorded against one commit. */
|
|
673
|
+
export async function listCheckRuns(client: GitHubClient, repoSlug: string, sha: string): Promise<CheckRunSummary[]> {
|
|
674
|
+
const { owner, repo } = parseOwnerRepo(repoSlug);
|
|
675
|
+
const response = await client.rest.checks.listForRef({ owner, repo, ref: sha, per_page: 100 });
|
|
676
|
+
return (response.data?.check_runs ?? []).map((c: any) => ({
|
|
677
|
+
name: String(c.name ?? "<unnamed>"),
|
|
678
|
+
status: String(c.status ?? "unknown"),
|
|
679
|
+
conclusion: c.conclusion === undefined ? null : c.conclusion,
|
|
680
|
+
headSha: String(c.head_sha ?? ""),
|
|
681
|
+
url: typeof c.html_url === "string" ? c.html_url : undefined,
|
|
682
|
+
}));
|
|
683
|
+
}
|
|
684
|
+
|
|
685
|
+
export interface WaitForCiOptions {
|
|
686
|
+
timeoutMs: number;
|
|
687
|
+
intervalMs: number;
|
|
688
|
+
/** Injected so a test can run the loop without waiting for it. */
|
|
689
|
+
sleep?: (ms: number) => Promise<void>;
|
|
690
|
+
now?: () => number;
|
|
691
|
+
}
|
|
692
|
+
|
|
693
|
+
/**
|
|
694
|
+
* Poll until CI has an answer for this commit, or until the wait runs out.
|
|
695
|
+
*
|
|
696
|
+
* Polling, and not a webhook, because a local harness has no inbound endpoint
|
|
697
|
+
* for a webhook to arrive at — the choice is not whether to poll but who does
|
|
698
|
+
* and whether the wait is bounded. `gh run watch` polls too, and blocks
|
|
699
|
+
* without a bound.
|
|
700
|
+
*
|
|
701
|
+
* **A timeout returns the last reading, which is UNMEASURED.** It never
|
|
702
|
+
* upgrades to PASS, and it never degrades to FAIL either: running out of
|
|
703
|
+
* patience is not evidence about the code. The returned reason names what was
|
|
704
|
+
* still pending, so the operator can see what it was waiting for.
|
|
705
|
+
*/
|
|
706
|
+
export async function waitForCi(
|
|
707
|
+
client: GitHubClient,
|
|
708
|
+
repoSlug: string,
|
|
709
|
+
sha: string,
|
|
710
|
+
opts: WaitForCiOptions,
|
|
711
|
+
): Promise<CiReading> {
|
|
712
|
+
const sleep = opts.sleep ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
|
|
713
|
+
const now = opts.now ?? (() => Date.now());
|
|
714
|
+
const deadline = now() + Math.max(0, opts.timeoutMs);
|
|
715
|
+
let reading = readCi(sha, await listCheckRuns(client, repoSlug, sha));
|
|
716
|
+
|
|
717
|
+
// Only a pending or absent reading is worth waiting on. A FAIL will not
|
|
718
|
+
// improve, a PASS will not get better, and an inconclusive check has already
|
|
719
|
+
// finished — polling those is time spent to reach the same answer.
|
|
720
|
+
const worthWaiting = (r: CiReading) => r.verdict === "UNMEASURED" && (r.pending.length > 0 || r.checks.length === 0);
|
|
721
|
+
|
|
722
|
+
while (worthWaiting(reading) && now() < deadline) {
|
|
723
|
+
await sleep(Math.min(opts.intervalMs, Math.max(0, deadline - now())));
|
|
724
|
+
reading = readCi(sha, await listCheckRuns(client, repoSlug, sha));
|
|
725
|
+
}
|
|
726
|
+
if (worthWaiting(reading)) {
|
|
727
|
+
const waited = Math.round(opts.timeoutMs / 1000);
|
|
728
|
+
return {
|
|
729
|
+
...reading,
|
|
730
|
+
reason: `${reading.reason} — gave up after ${waited}s, which is a statement about the wait and not about the code`,
|
|
731
|
+
};
|
|
732
|
+
}
|
|
733
|
+
return reading;
|
|
734
|
+
}
|