rungate 0.5.0 → 0.7.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/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* #804 / #323 — what a scan says about itself while it is still running.
|
|
3
|
+
*
|
|
4
|
+
* ## The gap this fills, and why the instrument next door does not fill it
|
|
5
|
+
*
|
|
6
|
+
* `lib/suite-timeout-margin.ts` (#811) composes `timeoutProximityViolations`
|
|
7
|
+
* over a JUnit report. It is the right reading and it is a reading taken
|
|
8
|
+
* AFTERWARDS: a `bun test` run cannot read its own report, because the file is
|
|
9
|
+
* written when the run ends. Three consequences, each of which is the whole of
|
|
10
|
+
* why this module exists rather than a call into that one:
|
|
11
|
+
*
|
|
12
|
+
* 1. **A killed case is a row with no message.** #804's subject in one
|
|
13
|
+
* sentence. The report says `TimeoutError` and `5005.68ms`; it does not
|
|
14
|
+
* say what the scan was reading at 5005ms, how many files it had got
|
|
15
|
+
* through, or what the budget was. An agent sees a red case named after a
|
|
16
|
+
* rule it has not broken and goes looking for a violation that does not
|
|
17
|
+
* exist.
|
|
18
|
+
* 2. **A per-test timeout SILENCES the proximity row**, deliberately —
|
|
19
|
+
* `lib/junit-checks.ts` says so in those words, and it is right to: an
|
|
20
|
+
* 8-second test that says it needs 8 seconds is a decision somebody made.
|
|
21
|
+
* So the case that carried `}, 60_000)` was the one case #804 is about
|
|
22
|
+
* AND the one case the #621 instrument could not see.
|
|
23
|
+
* 3. **Nothing has wired a report to it yet.** That decision is #804's own
|
|
24
|
+
* open half and is not taken here.
|
|
25
|
+
*
|
|
26
|
+
* This is therefore not a second decider for the question
|
|
27
|
+
* `suiteMarginReading` answers. That question is *"across a finished run's
|
|
28
|
+
* report, which cases ended near the budget"*. This one is *"while THIS scan
|
|
29
|
+
* is running, has it crossed its stated fraction of the budget, and on which
|
|
30
|
+
* path"* — a different population, a different clock, and an answer that has
|
|
31
|
+
* to exist before the runner's kill rather than after it. The budget itself
|
|
32
|
+
* has one reader for both: `bunfigTestTimeoutMs`.
|
|
33
|
+
*
|
|
34
|
+
* ## One comparison, read twice
|
|
35
|
+
*
|
|
36
|
+
* `scanBudgetViolations` is the only comparison in this file.
|
|
37
|
+
* `measureScan` calls it on a PARTIAL reading after each file and emits
|
|
38
|
+
* whatever it returns, and the caller calls it again on the final reading and
|
|
39
|
+
* asserts. Mid-scan emission is what survives a kill — a line already written
|
|
40
|
+
* to stdout is in the captured transcript whether or not the case lives to
|
|
41
|
+
* assert anything. A second renderer for the mid-scan line would be two
|
|
42
|
+
* deciders that agree (`.claude/rules/checks-must-be-able-to-fail.md`, fourth
|
|
43
|
+
* shape), so there is not one.
|
|
44
|
+
*/
|
|
45
|
+
import { bunfigTestTimeoutMs } from "./junit-checks";
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* The fraction of the per-test budget a scan is allowed to spend: 50%.
|
|
49
|
+
*
|
|
50
|
+
* Not 1% and not 20%. Those are PROXIMITY bands — "this case nearly died" —
|
|
51
|
+
* and the two numbers `lib/suite-timeout-margin.ts` documents are the right
|
|
52
|
+
* ones for that question. This is a CEILING on a cost that grows with the
|
|
53
|
+
* tree, so it has to fire with room left to fix it, and it has to not fire on
|
|
54
|
+
* a loaded machine running a scan that is fine.
|
|
55
|
+
*
|
|
56
|
+
* Both halves, measured rather than asserted, against the 5000ms budget
|
|
57
|
+
* `bunfig.toml` declares:
|
|
58
|
+
*
|
|
59
|
+
* - **It catches the defect it was written for.** The pre-#798 scan was
|
|
60
|
+
* 3482ms idle over 378 files, and it is what took `main` red twice at
|
|
61
|
+
* 5005.68ms and 5172.46ms on loaded CI shards. 3482 is past 2500, so this
|
|
62
|
+
* reports it — by name, with a duration and a path — on an IDLE machine,
|
|
63
|
+
* before any shard is loaded.
|
|
64
|
+
* - **It does not fire on the scan that exists.** Measured 2026-10-21 on
|
|
65
|
+
* `41d287c5`: 174.68ms over 427 files, which is 3.5% of the budget. A
|
|
66
|
+
* false red needs 14.3x inflation. The observed idle-to-loaded inflation
|
|
67
|
+
* on the pre-#798 numbers is 5005/3482 = 1.44x.
|
|
68
|
+
*
|
|
69
|
+
* The cheapest wrong fix for a red here is to raise this number, and it is
|
|
70
|
+
* refused above 1 for a reason that is not tidiness: a ceiling at or past the
|
|
71
|
+
* budget cannot fire at all, because the runner kills the case first. Below 1
|
|
72
|
+
* it is a judgement call and a reviewer's problem, which is the right place
|
|
73
|
+
* for it.
|
|
74
|
+
*/
|
|
75
|
+
export const SCAN_CEILING = 0.5;
|
|
76
|
+
|
|
77
|
+
export interface ScanBudgetReading {
|
|
78
|
+
/** The budget in force, or null when none could be read. */
|
|
79
|
+
budgetMs: number | null;
|
|
80
|
+
/** Wall-clock spent in the scan at the moment this reading was taken. */
|
|
81
|
+
elapsedMs: number;
|
|
82
|
+
/** Files read so far. */
|
|
83
|
+
filesRead: number;
|
|
84
|
+
/** Files the scan set out to read. */
|
|
85
|
+
filesTotal: number;
|
|
86
|
+
/** The directory being scanned — "which path it was scanning", at the top. */
|
|
87
|
+
root: string;
|
|
88
|
+
/** The file in hand when this reading was taken, if the scan is mid-flight. */
|
|
89
|
+
current: string | null;
|
|
90
|
+
/** The single costliest file, which is where a regression usually is. */
|
|
91
|
+
slowest: { path: string; ms: number } | null;
|
|
92
|
+
/** False for a mid-scan reading. An incomplete scan read fewer files than it will. */
|
|
93
|
+
complete: boolean;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Everything wrong with the reading AND everything wrong with what it read,
|
|
98
|
+
* as ONE list.
|
|
99
|
+
*
|
|
100
|
+
* FAILS CLOSED, in both directions that matter:
|
|
101
|
+
*
|
|
102
|
+
* - **No budget is not a clean scan.** A reading with nothing to compare
|
|
103
|
+
* against is UNMEASURED and says so by name. `0`, `null` and silence are
|
|
104
|
+
* indistinguishable from success (`.claude/rules/config-access.md`).
|
|
105
|
+
* - **An empty scan is not a fast scan.** A completed scan that read zero
|
|
106
|
+
* files finishes inside any budget by having nothing in it — the #492
|
|
107
|
+
* shape, and the one this check is most able to acquire by accident,
|
|
108
|
+
* because a `readdirSync` filter that stops matching produces exactly it.
|
|
109
|
+
*/
|
|
110
|
+
export function scanBudgetViolations(r: ScanBudgetReading, ceiling: number = SCAN_CEILING): string[] {
|
|
111
|
+
const out: string[] = [];
|
|
112
|
+
|
|
113
|
+
if (!Number.isFinite(ceiling) || ceiling <= 0 || ceiling > 1) {
|
|
114
|
+
out.push(
|
|
115
|
+
`UNMEASURED: a scan ceiling of ${ceiling} is not a fraction of the budget. At or past 1 it can ` +
|
|
116
|
+
`never fire — the runner kills the case at the budget first — so raising it past 1 silences ` +
|
|
117
|
+
`this check rather than widening it (#804)`,
|
|
118
|
+
);
|
|
119
|
+
return out;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
if (r.budgetMs === null || !Number.isFinite(r.budgetMs) || r.budgetMs <= 0) {
|
|
123
|
+
out.push(
|
|
124
|
+
`UNMEASURED: no usable per-test budget to compare ${r.elapsedMs.toFixed(2)}ms against ` +
|
|
125
|
+
`(read ${r.budgetMs}). bunfig.toml's [test] timeout is the one declaring position for it, and ` +
|
|
126
|
+
`defaulting to bun's built-in 5000 here would be a second one (#621, #804)`,
|
|
127
|
+
);
|
|
128
|
+
return out;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
if (r.complete && r.filesRead === 0) {
|
|
132
|
+
out.push(
|
|
133
|
+
`UNMEASURED: the scan of ${r.root} completed having read 0 of ${r.filesTotal} files in ` +
|
|
134
|
+
`${r.elapsedMs.toFixed(2)}ms. An empty scan finishes inside any budget by having nothing in ` +
|
|
135
|
+
`it, so this is not a measurement of anything (#492, #804)`,
|
|
136
|
+
);
|
|
137
|
+
return out;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
const limit = r.budgetMs * ceiling;
|
|
141
|
+
if (r.elapsedMs >= limit) {
|
|
142
|
+
const pct = ((r.elapsedMs / r.budgetMs) * 100).toFixed(1);
|
|
143
|
+
const per = r.filesRead > 0 ? (r.elapsedMs / r.filesRead).toFixed(2) : "n/a";
|
|
144
|
+
const where = r.current !== null ? ` scanning ${r.current}` : "";
|
|
145
|
+
const slowest =
|
|
146
|
+
r.slowest !== null ? ` Costliest file so far: ${r.slowest.path} at ${r.slowest.ms.toFixed(2)}ms.` : "";
|
|
147
|
+
out.push(
|
|
148
|
+
`the scan of ${r.root} has spent ${r.elapsedMs.toFixed(2)}ms of its ${r.budgetMs}ms per-test budget ` +
|
|
149
|
+
`(${pct}%, ceiling ${ceiling * 100}% = ${limit.toFixed(0)}ms) after ${r.filesRead} of ` +
|
|
150
|
+
`${r.filesTotal} files${where} — ${per}ms per file.${slowest} ` +
|
|
151
|
+
`Make the scan cheaper or stop re-reading what it already knows. Raising the ceiling, or giving ` +
|
|
152
|
+
`the case a per-test timeout of its own, moves the same red further away AND takes this case out ` +
|
|
153
|
+
`of the #621 proximity reading, which is how #804 happened (#804, #323)`,
|
|
154
|
+
);
|
|
155
|
+
}
|
|
156
|
+
return out;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** The sentence a caller prints beside a reading, violations or not. */
|
|
160
|
+
export function describeScanBudget(r: ScanBudgetReading, ceiling: number = SCAN_CEILING): string {
|
|
161
|
+
const v = scanBudgetViolations(r, ceiling);
|
|
162
|
+
const head =
|
|
163
|
+
v.length > 0
|
|
164
|
+
? `${v.length} finding(s) for the scan of ${r.root}:`
|
|
165
|
+
: `MEASURED: the scan of ${r.root} read ${r.filesRead} of ${r.filesTotal} files in ` +
|
|
166
|
+
`${r.elapsedMs.toFixed(2)}ms, ${((r.elapsedMs / (r.budgetMs || NaN)) * 100).toFixed(1)}% of the ` +
|
|
167
|
+
`${r.budgetMs}ms budget (ceiling ${ceiling * 100}%).`;
|
|
168
|
+
return [head, ...v.map(x => ` - ${x}`)].join("\n");
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* The budget in force for the tree rooted at `root`, read from its
|
|
173
|
+
* `bunfig.toml`, or null when it declares none.
|
|
174
|
+
*
|
|
175
|
+
* One reader, shared with #621 and #811. A copy of the TOML parse here would
|
|
176
|
+
* be a second decider over one key.
|
|
177
|
+
*/
|
|
178
|
+
export function scanBudgetFromBunfig(source: string | null): number | null {
|
|
179
|
+
return source === null ? null : bunfigTestTimeoutMs(source);
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Run `read` over `files`, timing each one, and emit the moment the scan
|
|
184
|
+
* crosses its ceiling.
|
|
185
|
+
*
|
|
186
|
+
* The emission is the point. An assertion after the loop is unreachable on
|
|
187
|
+
* the run that matters — the one where the runner kills the case — and a
|
|
188
|
+
* killed case is #804's whole subject. A line already on stdout is in the
|
|
189
|
+
* captured transcript regardless, which is #323's SC-3 arriving at the place
|
|
190
|
+
* where a name is lost rather than at the transport.
|
|
191
|
+
*
|
|
192
|
+
* Emits AT MOST ONCE. A warning on every one of 427 iterations is a warning
|
|
193
|
+
* nobody reads, which is the failure mode #804's own thread recorded for the
|
|
194
|
+
* UNMEASURED line that had printed on every run for a month.
|
|
195
|
+
*
|
|
196
|
+
* `now` and `emit` are injected so a case can drive a slow scan without being
|
|
197
|
+
* slow, and read what was emitted without capturing a stream.
|
|
198
|
+
*/
|
|
199
|
+
export function measureScan<T>(opts: {
|
|
200
|
+
root: string;
|
|
201
|
+
files: string[];
|
|
202
|
+
budgetMs: number | null;
|
|
203
|
+
read: (file: string) => T[];
|
|
204
|
+
ceiling?: number;
|
|
205
|
+
now?: () => number;
|
|
206
|
+
emit?: (line: string) => void;
|
|
207
|
+
}): { values: T[]; reading: ScanBudgetReading } {
|
|
208
|
+
const ceiling = opts.ceiling ?? SCAN_CEILING;
|
|
209
|
+
const now = opts.now ?? (() => performance.now());
|
|
210
|
+
const emit = opts.emit ?? ((line: string) => console.error(line));
|
|
211
|
+
|
|
212
|
+
const started = now();
|
|
213
|
+
const values: T[] = [];
|
|
214
|
+
let slowest: { path: string; ms: number } | null = null;
|
|
215
|
+
let emitted = false;
|
|
216
|
+
let filesRead = 0;
|
|
217
|
+
|
|
218
|
+
const readingAt = (current: string | null, complete: boolean): ScanBudgetReading => ({
|
|
219
|
+
budgetMs: opts.budgetMs,
|
|
220
|
+
elapsedMs: now() - started,
|
|
221
|
+
filesRead,
|
|
222
|
+
filesTotal: opts.files.length,
|
|
223
|
+
root: opts.root,
|
|
224
|
+
current,
|
|
225
|
+
slowest,
|
|
226
|
+
complete,
|
|
227
|
+
});
|
|
228
|
+
|
|
229
|
+
for (const file of opts.files) {
|
|
230
|
+
const before = now();
|
|
231
|
+
values.push(...opts.read(file));
|
|
232
|
+
const cost = now() - before;
|
|
233
|
+
filesRead += 1;
|
|
234
|
+
if (slowest === null || cost > slowest.ms) slowest = { path: file, ms: cost };
|
|
235
|
+
|
|
236
|
+
if (!emitted) {
|
|
237
|
+
// The SAME comparison the caller will assert on, over a partial reading.
|
|
238
|
+
const found = scanBudgetViolations(readingAt(file, false), ceiling);
|
|
239
|
+
if (found.length > 0) {
|
|
240
|
+
emitted = true;
|
|
241
|
+
for (const line of found) emit(`[#804] ${line}`);
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
return { values, reading: readingAt(null, true) };
|
|
247
|
+
}
|
package/lib/scanner.ts
CHANGED
|
@@ -8,7 +8,8 @@
|
|
|
8
8
|
* no generation logic (agents-md, agent-briefs, code-map) is imported here
|
|
9
9
|
* (SC-365, AC-3).
|
|
10
10
|
*/
|
|
11
|
-
import { existsSync, readFileSync,
|
|
11
|
+
import { existsSync, readFileSync, statSync } from "fs";
|
|
12
|
+
import { readdirSorted } from "./readdir-sorted";
|
|
12
13
|
import { join, basename } from "path";
|
|
13
14
|
import { resolveConfig } from "./config-loader";
|
|
14
15
|
// A leaf, not a generator. SC-365 / AC-3 keeps generation logic out of the
|
|
@@ -16,6 +17,10 @@ import { resolveConfig } from "./config-loader";
|
|
|
16
17
|
// exists precisely so this module and the generators can share one answer
|
|
17
18
|
// instead of drifting apart (#380).
|
|
18
19
|
import { isHarnessItself } from "./harness-identity";
|
|
20
|
+
import { isSpecFile } from "./spec-listing";
|
|
21
|
+
import { scanDocsDirectory } from "./doc-routing";
|
|
22
|
+
import { testCommandDecision } from "./test-command";
|
|
23
|
+
import { projectStateDerivation, projectStateKeyFileNote } from "./project-state-derivation";
|
|
19
24
|
import type {
|
|
20
25
|
ProjectScan,
|
|
21
26
|
ProjectType,
|
|
@@ -104,12 +109,23 @@ function detectTechStack(root: string): string[] {
|
|
|
104
109
|
|
|
105
110
|
// ── Spec scanning ──────────────────────────────────────────────
|
|
106
111
|
|
|
107
|
-
|
|
112
|
+
/**
|
|
113
|
+
* Exported for `lib/scaffold/steps.ts`, which used to answer this question
|
|
114
|
+
* with its own copy. The copy drifted three times — #382's `SPEC-TEMPLATE.md`
|
|
115
|
+
* filter and #579's `criteriaNone` and `testable` derivation — each time
|
|
116
|
+
* because a fix landed here and nobody knew a second implementation existed.
|
|
117
|
+
* One derivation, so the next fix cannot land in only half of them (#827).
|
|
118
|
+
*/
|
|
119
|
+
export function scanSpecs(root: string): SpecEntry[] {
|
|
108
120
|
const specsDir = join(root, "specs");
|
|
109
121
|
if (!existsSync(specsDir)) return [];
|
|
110
122
|
|
|
111
123
|
const specs: SpecEntry[] = [];
|
|
112
|
-
|
|
124
|
+
// `isSpecFile`, not an inline name comparison. The audit in
|
|
125
|
+
// `lib/scaffold/steps.ts` answered the same question with its own filter
|
|
126
|
+
// and reached the opposite verdict for `SPEC-TEMPLATE.md`, so the one file
|
|
127
|
+
// this table deliberately omits was reported as missing from it (#382).
|
|
128
|
+
const specFiles = readdirSorted(specsDir).filter(isSpecFile);
|
|
113
129
|
|
|
114
130
|
for (const f of specFiles) {
|
|
115
131
|
const content = readFileSync(join(specsDir, f), "utf-8");
|
|
@@ -126,18 +142,23 @@ function scanSpecs(root: string): SpecEntry[] {
|
|
|
126
142
|
if (tMatch) testable = tMatch[1].trim();
|
|
127
143
|
}
|
|
128
144
|
|
|
129
|
-
|
|
145
|
+
// #579. A row in this table promises a reader that the document on the
|
|
146
|
+
// other end governs something. When the document says it states no
|
|
147
|
+
// criteria, the row says so too — see `lib/spec-requirements.ts` for why
|
|
148
|
+
// the declaration lives in frontmatter rather than in an allowlist.
|
|
149
|
+
const criteriaNone = /^criteria:\s*none\s*$/m.test(fmMatch?.[1] ?? "");
|
|
150
|
+
|
|
151
|
+
specs.push({ file: f, governs, testable, criteriaNone });
|
|
130
152
|
}
|
|
131
153
|
|
|
132
154
|
// Also scan specs subdirectories
|
|
133
155
|
try {
|
|
134
|
-
const specSubDirs =
|
|
135
|
-
.filter(
|
|
136
|
-
.map(d => d.name);
|
|
156
|
+
const specSubDirs = readdirSorted(specsDir)
|
|
157
|
+
.filter(n => { try { return statSync(join(specsDir, n)).isDirectory(); } catch { return false; } });
|
|
137
158
|
|
|
138
159
|
for (const sub of specSubDirs) {
|
|
139
160
|
const subPath = join(specsDir, sub);
|
|
140
|
-
const subFiles =
|
|
161
|
+
const subFiles = readdirSorted(subPath).filter(f => f.endsWith(".md") && f !== "INDEX.md");
|
|
141
162
|
if (subFiles.length > 0) {
|
|
142
163
|
const indexPath = join(subPath, "INDEX.md");
|
|
143
164
|
let groupGoverns = `${sub} (${subFiles.length} specs)`;
|
|
@@ -151,7 +172,24 @@ function scanSpecs(root: string): SpecEntry[] {
|
|
|
151
172
|
}
|
|
152
173
|
}
|
|
153
174
|
}
|
|
154
|
-
|
|
175
|
+
// `"yes"` was a literal here, and every reader of this field compares
|
|
176
|
+
// against the string `"true"` — so the group row has always rendered
|
|
177
|
+
// a word that means false to the code and true to a reader (#579).
|
|
178
|
+
// Derived from the members instead: testable if any of them is.
|
|
179
|
+
const anyTestable = subFiles.some(sf => {
|
|
180
|
+
try {
|
|
181
|
+
return /^testable:\s*true\s*$/m.test(
|
|
182
|
+
readFileSync(join(subPath, sf), "utf-8").match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "",
|
|
183
|
+
);
|
|
184
|
+
} catch {
|
|
185
|
+
return false;
|
|
186
|
+
}
|
|
187
|
+
});
|
|
188
|
+
specs.push({
|
|
189
|
+
file: `${sub}/ (${subFiles.length} specs)`,
|
|
190
|
+
governs: groupGoverns,
|
|
191
|
+
testable: String(anyTestable),
|
|
192
|
+
});
|
|
155
193
|
}
|
|
156
194
|
}
|
|
157
195
|
} catch {}
|
|
@@ -176,7 +214,7 @@ function detectConsumers(root: string): string[] {
|
|
|
176
214
|
const consumers: string[] = [];
|
|
177
215
|
const consumerPatterns = ["-routes.ts", "-generator.ts", "-plan.ts", "-intel.ts"];
|
|
178
216
|
|
|
179
|
-
for (const f of
|
|
217
|
+
for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts"))) {
|
|
180
218
|
try {
|
|
181
219
|
const content = readFileSync(join(srcDir, f), "utf-8");
|
|
182
220
|
const isConsumer = consumerPatterns.some(p => f.includes(p)) ||
|
|
@@ -204,7 +242,7 @@ function scanKeyFiles(root: string): KeyFile[] {
|
|
|
204
242
|
// Always include scaffold-generated files for idempotency (SC-364)
|
|
205
243
|
const keyFiles: KeyFile[] = [
|
|
206
244
|
{ file: "AGENTS.md", what: "Project entry point", when: "Always first" },
|
|
207
|
-
{ file: "PROJECT-STATE.md", what:
|
|
245
|
+
{ file: "PROJECT-STATE.md", what: projectStateKeyFileNote(projectStateDerivation(root)), when: "Session start, always first after AGENTS.md" },
|
|
208
246
|
{ file: "project-state.json", what: "Source of truth for project status", when: "When editing state" },
|
|
209
247
|
];
|
|
210
248
|
|
|
@@ -251,7 +289,7 @@ function scanTestFiles(root: string): TestFile[] {
|
|
|
251
289
|
if (!testDir) return [];
|
|
252
290
|
|
|
253
291
|
try {
|
|
254
|
-
return
|
|
292
|
+
return readdirSorted(join(root, testDir))
|
|
255
293
|
.filter(f => f.endsWith(".test.ts"))
|
|
256
294
|
.map(f => ({
|
|
257
295
|
label: f.replace(".test.ts", "").replace(/-/g, " "),
|
|
@@ -269,7 +307,7 @@ function scanRefFiles(root: string): RefFile[] {
|
|
|
269
307
|
if (!existsSync(refDir)) return [];
|
|
270
308
|
|
|
271
309
|
try {
|
|
272
|
-
return
|
|
310
|
+
return readdirSorted(refDir).map(f => ({
|
|
273
311
|
file: f,
|
|
274
312
|
what: "Historical reference",
|
|
275
313
|
}));
|
|
@@ -309,7 +347,7 @@ function scanDocRouting(root: string, categories: Category[]): DocRoute[] {
|
|
|
309
347
|
// Recursive: reference/ held 19 markdown files, every one of them in a
|
|
310
348
|
// subdirectory, and a shallow count advertised it as "(0 files)" (#91).
|
|
311
349
|
// A row saying a directory is empty reads as an instruction not to look.
|
|
312
|
-
const files =
|
|
350
|
+
const files = readdirSorted(catPath, { recursive: true }).filter(f => f.endsWith(".md"));
|
|
313
351
|
docRouting.push({ need: `${cat.label} (${files.length} files)`, file: `${cat.dir}/` });
|
|
314
352
|
} catch {
|
|
315
353
|
docRouting.push({ need: cat.label, file: `${cat.dir}/` });
|
|
@@ -319,41 +357,24 @@ function scanDocRouting(root: string, categories: Category[]): DocRoute[] {
|
|
|
319
357
|
}
|
|
320
358
|
}
|
|
321
359
|
|
|
322
|
-
// Docs top-level files
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
const content = readFileSync(docPath, "utf-8");
|
|
330
|
-
const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
|
|
331
|
-
let need = f.replace(/\.md$/, "").replace(/-/g, " ");
|
|
332
|
-
if (fmMatch) {
|
|
333
|
-
const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
|
|
334
|
-
if (gMatch && gMatch[1].trim() !== "TODO") need = gMatch[1].trim();
|
|
335
|
-
}
|
|
336
|
-
docRouting.push({ need, file: `docs/${f}` });
|
|
337
|
-
}
|
|
338
|
-
const subDirs = readdirSync(docsDir, { withFileTypes: true })
|
|
339
|
-
.filter(d => d.isDirectory() && !categories.some(c => c.dir === `docs/${d.name}`))
|
|
340
|
-
.map(d => d.name);
|
|
341
|
-
for (const sub of subDirs) {
|
|
342
|
-
const subPath = join(docsDir, sub);
|
|
343
|
-
const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md"));
|
|
344
|
-
if (subFiles.length > 0) {
|
|
345
|
-
docRouting.push({ need: `${sub} (${subFiles.length} files)`, file: `docs/${sub}/` });
|
|
346
|
-
}
|
|
347
|
-
}
|
|
348
|
-
} catch {}
|
|
349
|
-
}
|
|
360
|
+
// Docs top-level files and subdirectories, through the one binding (#617,
|
|
361
|
+
// #619). This was a complete second copy of `lib/scaffold/steps.ts`'s scan,
|
|
362
|
+
// with its own inline `governs:` regex — which is how one site could learn
|
|
363
|
+
// about a new frontmatter field and the other not.
|
|
364
|
+
try {
|
|
365
|
+
docRouting.push(...scanDocsDirectory(join(root, "docs"), categories.map(c => c.dir)));
|
|
366
|
+
} catch {}
|
|
350
367
|
|
|
351
|
-
//
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
368
|
+
// The "filter to non-obvious mappings" that used to end this function is
|
|
369
|
+
// deleted (#617). It could only ever drop a top-level `docs/*.md`: every
|
|
370
|
+
// other row's description contains an em dash or a parenthesis, or does not
|
|
371
|
+
// begin with its own filename. Dropping those IS the defect — 38 of 38 on
|
|
372
|
+
// one consumer — and a document with no `governs:` is UNMEASURED, not
|
|
373
|
+
// "governs nothing". Exclusion is the document's own declaration now, read
|
|
374
|
+
// once in `topLevelDocRoute`. Keeping the filter as well would leave a
|
|
375
|
+
// second decider that no mutation could distinguish from live code, since
|
|
376
|
+
// the marker it emits already defeats it.
|
|
377
|
+
return docRouting;
|
|
357
378
|
}
|
|
358
379
|
|
|
359
380
|
// ── Identity detection ─────────────────────────────────────────
|
|
@@ -449,13 +470,13 @@ function scanDirs(root: string): DirEntry[] {
|
|
|
449
470
|
const dirs: DirEntry[] = [];
|
|
450
471
|
|
|
451
472
|
try {
|
|
452
|
-
for (const entry of
|
|
473
|
+
for (const entry of readdirSorted(root)) {
|
|
453
474
|
if (entry.startsWith(".") && entry !== ".claude") continue;
|
|
454
475
|
if (skip.has(entry)) continue;
|
|
455
476
|
const full = join(root, entry);
|
|
456
477
|
try {
|
|
457
478
|
if (!statSync(full).isDirectory()) continue;
|
|
458
|
-
const files =
|
|
479
|
+
const files = readdirSorted(full, { recursive: true });
|
|
459
480
|
const exts = new Set(files.map(f => f.split(".").pop()).filter((e): e is string => Boolean(e)));
|
|
460
481
|
dirs.push({ name: entry, fileCount: files.length, types: [...exts].slice(0, 5) });
|
|
461
482
|
} catch {}
|
|
@@ -473,7 +494,7 @@ function scanModules(root: string): ModuleEntry[] {
|
|
|
473
494
|
if (!existsSync(srcDir)) return modules;
|
|
474
495
|
|
|
475
496
|
try {
|
|
476
|
-
for (const f of
|
|
497
|
+
for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
|
|
477
498
|
const content = readFileSync(join(srcDir, f), "utf-8");
|
|
478
499
|
const exports: string[] = [];
|
|
479
500
|
const exportPattern = /export\s+(?:function|const|class|type|interface)\s+(\w+)/g;
|
|
@@ -493,7 +514,7 @@ function scanRoutes(root: string): RouteEntry[] {
|
|
|
493
514
|
if (!existsSync(srcDir)) return routes;
|
|
494
515
|
|
|
495
516
|
try {
|
|
496
|
-
for (const f of
|
|
517
|
+
for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
|
|
497
518
|
const content = readFileSync(join(srcDir, f), "utf-8");
|
|
498
519
|
const routePatterns = [
|
|
499
520
|
/app\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/gi,
|
|
@@ -553,7 +574,7 @@ function scanPromptRouting(root: string, harness: Record<string, any> | null): R
|
|
|
553
574
|
if (!existsSync(promptsDir)) return promptsByAgent;
|
|
554
575
|
|
|
555
576
|
try {
|
|
556
|
-
const promptFiles =
|
|
577
|
+
const promptFiles = readdirSorted(promptsDir).filter(f => f.endsWith(".md"));
|
|
557
578
|
for (const f of promptFiles) {
|
|
558
579
|
const content = readFileSync(join(promptsDir, f), "utf-8");
|
|
559
580
|
const lower = f.toLowerCase();
|
|
@@ -608,16 +629,13 @@ function scanAgentMeta(harness: Record<string, any> | null): Record<string, { de
|
|
|
608
629
|
|
|
609
630
|
// ── Test command detection ─────────────────────────────────────
|
|
610
631
|
|
|
632
|
+
/**
|
|
633
|
+
* Through the one binding (#488). This knew only about package.json, so a
|
|
634
|
+
* consumer who set `dev.testCmd` got it honoured by the agent briefs and
|
|
635
|
+
* ignored by every scan-driven surface — and the CI generator read neither.
|
|
636
|
+
*/
|
|
611
637
|
function detectTestCmd(root: string): string {
|
|
612
|
-
|
|
613
|
-
if (!existsSync(pkgPath)) return "bun test";
|
|
614
|
-
|
|
615
|
-
try {
|
|
616
|
-
const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
|
|
617
|
-
if (pkg.scripts?.test) return pkg.scripts.test;
|
|
618
|
-
} catch {}
|
|
619
|
-
|
|
620
|
-
return "bun test";
|
|
638
|
+
return testCommandDecision(root).command;
|
|
621
639
|
}
|
|
622
640
|
|
|
623
641
|
// ── Categories ─────────────────────────────────────────────────
|
package/lib/scratch-roots.ts
CHANGED
|
@@ -29,7 +29,7 @@ import { stripJsComments } from "./strip-js-comments";
|
|
|
29
29
|
*/
|
|
30
30
|
export function repoRootIdents(src: string): Set<string> {
|
|
31
31
|
const idents = new Set<string>();
|
|
32
|
-
for (const m of src.matchAll(/(
|
|
32
|
+
for (const m of src.matchAll(/([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([^;\n]+)/g)) {
|
|
33
33
|
if (/import\.meta\.dir|process\.cwd\(\)/.test(m[2]!)) idents.add(m[1]!);
|
|
34
34
|
}
|
|
35
35
|
return idents;
|
|
@@ -38,14 +38,51 @@ export function repoRootIdents(src: string): Set<string> {
|
|
|
38
38
|
/**
|
|
39
39
|
* The declaration forms a scratch root can arrive in.
|
|
40
40
|
*
|
|
41
|
-
*
|
|
42
|
-
* tidiness. Moving creation out of module scope means writing
|
|
41
|
+
* The keyword is not matched AT ALL, and that is #437's requirement rather
|
|
42
|
+
* than tidiness. Moving creation out of module scope means writing
|
|
43
43
|
* `let SCRATCH = ""` at the top and `SCRATCH = mkdtempSync(...)` inside
|
|
44
44
|
* `beforeAll`, and a `const`-only pattern stops seeing both forms at once —
|
|
45
45
|
* so the fix for the leak would have opened a hole in the guard against
|
|
46
|
-
* fixed paths. Measured: it is 3 red
|
|
46
|
+
* fixed paths. Measured: it is 3 red if the keyword is required.
|
|
47
|
+
*
|
|
48
|
+
* It used to be matched OPTIONALLY — `(?:const|let|var\s+)?\s*` in front of
|
|
49
|
+
* the identifier — which satisfies #437 and is what #793 is about. An
|
|
50
|
+
* optional group with nothing required before it starts a backtracking
|
|
51
|
+
* attempt at essentially every offset: 1716ms over this repository's `test/`,
|
|
52
|
+
* and still 1712ms with the whole `join(...)` tail deleted, so the cost was
|
|
53
|
+
* never in the tail. The group was optional AND non-capturing, so it fed no
|
|
54
|
+
* capture and deleting it changes no output that is not a misparse: 32ms,
|
|
55
|
+
* with a byte-identical 400-element ident list over the real tree.
|
|
56
|
+
*
|
|
57
|
+
* The one input on which the two readings differ is an identifier literally
|
|
58
|
+
* beginning with a keyword — `letROOT = join(import.meta.dir, "..")`. The old
|
|
59
|
+
* pattern consumed `let` and captured `ROOT`, a variable nothing declared,
|
|
60
|
+
* and a root identifier nothing declared puts an unrelated `join(ROOT, ...)`
|
|
61
|
+
* prefix into a recursive-delete allowlist. Reading the identifier whole
|
|
62
|
+
* narrows that allowlist. See the #793 cases in `test/scratch-cleanup.test.ts`,
|
|
63
|
+
* which hold the equivalence element by element against a frozen copy of the
|
|
64
|
+
* old parse.
|
|
65
|
+
*/
|
|
66
|
+
const DECL = /([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(mkdtempSync\s*\(\s*)?join\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,\s*"(\.[^"]*)"/g;
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* The same pattern, un-anchored and non-global, used only to decide whether
|
|
70
|
+
* the expensive path is worth entering.
|
|
71
|
+
*
|
|
72
|
+
* DERIVED FROM `DECL`, never written out a second time. A hand-copied probe
|
|
73
|
+
* that drifts from the real pattern is how a guard goes quiet: it would skip
|
|
74
|
+
* the file the real regex was about to match on, report `[]`, and read as a
|
|
75
|
+
* clean scan. Building it from `DECL.source` means the two cannot disagree.
|
|
76
|
+
*
|
|
77
|
+
* Non-global on purpose — `.test()` on a `/g` regex advances `lastIndex` and
|
|
78
|
+
* returns a different answer on the next call with the same input.
|
|
79
|
+
*
|
|
80
|
+
* Sound because `stripJsComments` only ever REMOVES text: if the raw source
|
|
81
|
+
* cannot match, the stripped source cannot match either. The converse is not
|
|
82
|
+
* true — a match inside a comment enters the slow path and is then discarded
|
|
83
|
+
* there, which costs time and never costs correctness.
|
|
47
84
|
*/
|
|
48
|
-
const
|
|
85
|
+
const DECL_PROBE = new RegExp(DECL.source);
|
|
49
86
|
|
|
50
87
|
/** Navigation, not a scratch name. */
|
|
51
88
|
function isNavigation(literal: string): boolean {
|
|
@@ -54,6 +91,14 @@ function isNavigation(literal: string): boolean {
|
|
|
54
91
|
|
|
55
92
|
/** Scratch roots declared at a fixed path under the shared checkout. */
|
|
56
93
|
export function fixedScratchRoots(source: string): string[] {
|
|
94
|
+
// 379 test files, 5.8MB, and 75 of them can possibly match. Stripping
|
|
95
|
+
// comments from the other 304 cost 3.5s of the 5s budget and found nothing
|
|
96
|
+
// — enough that this test timed out on a Mini running five CI jobs while
|
|
97
|
+
// passing in milliseconds on an idle laptop. Skipping them is 906ms.
|
|
98
|
+
//
|
|
99
|
+
// A timeout bump was the other option and is the wrong one: it makes the
|
|
100
|
+
// red slower to arrive without making the scan any more able to finish.
|
|
101
|
+
if (!DECL_PROBE.test(source)) return [];
|
|
57
102
|
const src = stripJsComments(source);
|
|
58
103
|
const roots = repoRootIdents(src);
|
|
59
104
|
const out: string[] = [];
|