rungate 0.5.0 → 0.6.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/agents-md-sections.ts +144 -0
- package/lib/branch-diff.ts +139 -0
- package/lib/bun-version.ts +268 -0
- package/lib/ci-checkout.ts +1 -1
- package/lib/compliance.ts +13 -11
- package/lib/config-loader.ts +12 -0
- package/lib/conformity.ts +184 -88
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +90 -4
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +22 -0
- package/lib/fallow-availability.ts +129 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +71 -23
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/junit-checks.ts +484 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/report-provenance.ts +156 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +311 -0
- package/lib/scaffold/ai-review-step.ts +180 -0
- package/lib/scaffold/owned-files.ts +42 -2
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +128 -73
- package/lib/scaffold/write-steps.ts +6 -4
- package/lib/scanner.ts +38 -12
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/suite-run-reading.ts +170 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +166 -10
- package/lib/tool-probe.ts +120 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/package.json +1 -1
- 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 +17 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +90 -19
- package/scripts/generate-code-map.ts +53 -12
- package/scripts/scaffold-project.ts +4 -1
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +57 -5
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -0,0 +1,484 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every check a gate run actually executed, read off bun's JUnit report (#532).
|
|
3
|
+
*
|
|
4
|
+
* ## Why the console output cannot answer this
|
|
5
|
+
*
|
|
6
|
+
* `gates/gate-executor.ts`'s `parseTestResults` scans for `(pass)` and
|
|
7
|
+
* `(fail)` markers. Measured on bun 1.3.14, with stdout piped:
|
|
8
|
+
*
|
|
9
|
+
* ```
|
|
10
|
+
* $ bun test p.test.ts # 2 passing, 1 failing
|
|
11
|
+
* (fail) beta fails [0.18ms]
|
|
12
|
+
* 2 pass
|
|
13
|
+
* 1 fail
|
|
14
|
+
* ```
|
|
15
|
+
*
|
|
16
|
+
* **There are no `(pass)` lines.** The runner prints a marker for a failure
|
|
17
|
+
* and a count for everything else, so the `(pass)` branch of
|
|
18
|
+
* `parseTestResults` matches nothing on the runner this repo uses, and the
|
|
19
|
+
* `results` array it returns is a FAILURE list wearing a neutral name.
|
|
20
|
+
*
|
|
21
|
+
* That is fine for the failure ledger, which is all it was ever read for.
|
|
22
|
+
* It is fatal for #532: the retirement rule needs the names a later gate
|
|
23
|
+
* **ran and did not fail**, and a failure list cannot name a single one of
|
|
24
|
+
* them. Sourcing `checksRun` from `results` produced two entries out of a
|
|
25
|
+
* hundred and seventeen on a real scope run — a positive witness that
|
|
26
|
+
* witnesses nothing, which is this repo's central defect class
|
|
27
|
+
* (.claude/rules/checks-must-be-able-to-fail.md).
|
|
28
|
+
*
|
|
29
|
+
* ## Why the JUnit report can
|
|
30
|
+
*
|
|
31
|
+
* `--reporter=junit --reporter-outfile=<path>` writes every testcase, and it
|
|
32
|
+
* runs ALONGSIDE the console output rather than replacing it — one spawn
|
|
33
|
+
* still prints the `(fail)` markers the detail parser reads.
|
|
34
|
+
*
|
|
35
|
+
* ## The trap in it, and it is the dangerous direction
|
|
36
|
+
*
|
|
37
|
+
* A test excluded by `--test-name-pattern` is **still listed**, as a
|
|
38
|
+
* `<skipped />`. Measured, with `-t "keep me"` over a file of five tests:
|
|
39
|
+
*
|
|
40
|
+
* ```xml
|
|
41
|
+
* <testcase name="keep me one" classname="alpha group" ... />
|
|
42
|
+
* <testcase name="skip me two" classname="alpha group" ...><skipped /></testcase>
|
|
43
|
+
* ```
|
|
44
|
+
*
|
|
45
|
+
* The gate's whole pattern is an exclusion — the scope gate runs
|
|
46
|
+
* `schema|scope` over `gates/`, so most of the file is filtered out on every
|
|
47
|
+
* run. Counting a filtered test as "run" would retire a refusal the gate
|
|
48
|
+
* never re-measured, which is worse than the bug #532 closes: it would erase
|
|
49
|
+
* a true refusal rather than keep a stale one.
|
|
50
|
+
*
|
|
51
|
+
* So a `<skipped />` testcase is NOT a check that ran, and the count of them
|
|
52
|
+
* is returned rather than discarded, because "ran 2, skipped 115" and
|
|
53
|
+
* "ran 117" are different facts about the same report.
|
|
54
|
+
*
|
|
55
|
+
* ## Why the names are rebuilt from the element nesting
|
|
56
|
+
*
|
|
57
|
+
* `classname` looks like the obvious source and is not usable: bun emits the
|
|
58
|
+
* describe chain REVERSED and double-escaped. Measured on a
|
|
59
|
+
* `describe("outer") > describe("inner")`, whose console name is
|
|
60
|
+
* `outer > inner > deep fails`:
|
|
61
|
+
*
|
|
62
|
+
* ```xml
|
|
63
|
+
* <testcase name="deep fails" classname="inner &gt; outer" ... />
|
|
64
|
+
* ```
|
|
65
|
+
*
|
|
66
|
+
* The nested `<testsuite>` elements carry the same chain in the right order,
|
|
67
|
+
* so the name is rebuilt from the stack. The outermost suite is the FILE —
|
|
68
|
+
* its `name` is a path — and it is dropped, which is what makes the rebuilt
|
|
69
|
+
* string match the `(fail)` marker the console printed for the same test.
|
|
70
|
+
* That match is load-bearing: `checksRun` has to be a superset of
|
|
71
|
+
* `failedChecks` or the subtraction in `lib/gate-refusal-currency.ts` reports
|
|
72
|
+
* a still-failing check as resolved.
|
|
73
|
+
*/
|
|
74
|
+
import { readFileSync } from "fs";
|
|
75
|
+
|
|
76
|
+
/** What one JUnit report says about which checks ran. */
|
|
77
|
+
export interface JunitReading {
|
|
78
|
+
/**
|
|
79
|
+
* The full names of the checks that RAN — passed or failed. `null` when
|
|
80
|
+
* the report could not be read, which is a different answer from `[]`
|
|
81
|
+
* ("the report says nothing ran") and has to stay different all the way
|
|
82
|
+
* to the consumer (.claude/rules/config-access.md, Silent Default
|
|
83
|
+
* Substitution).
|
|
84
|
+
*/
|
|
85
|
+
names: string[] | null;
|
|
86
|
+
/** Why `names` is null, or why the reading is partial. */
|
|
87
|
+
reason?: string;
|
|
88
|
+
/** Testcases listed but not run — filtered out, `.skip`, or `.todo`. */
|
|
89
|
+
skipped: number;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const ENTITIES: Array<[RegExp, string]> = [
|
|
93
|
+
[/</g, "<"],
|
|
94
|
+
[/>/g, ">"],
|
|
95
|
+
[/"/g, '"'],
|
|
96
|
+
[/'/g, "'"],
|
|
97
|
+
// Last, so `&gt;` decodes to `>` and not to `>`.
|
|
98
|
+
[/&/g, "&"],
|
|
99
|
+
];
|
|
100
|
+
|
|
101
|
+
function unescapeXml(s: string): string {
|
|
102
|
+
return ENTITIES.reduce((acc, [re, to]) => acc.replace(re, to), s);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function attr(tag: string, name: string): string | null {
|
|
106
|
+
const m = tag.match(new RegExp(`\\b${name}="([^"]*)"`));
|
|
107
|
+
return m ? unescapeXml(m[1]) : null;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** One testcase, as the report describes it. */
|
|
111
|
+
interface ScannedTestcase {
|
|
112
|
+
/** The full name, rebuilt from the `<testsuite>` nesting. */
|
|
113
|
+
name: string;
|
|
114
|
+
/** The `time` attribute in MILLISECONDS, or `NaN` when it carries none. */
|
|
115
|
+
ms: number;
|
|
116
|
+
/** False for a `<skipped />` testcase — filtered out, `.skip` or `.todo`. */
|
|
117
|
+
ran: boolean;
|
|
118
|
+
/**
|
|
119
|
+
* The `type` of the testcase's `<failure>`, or null if it did not fail.
|
|
120
|
+
* bun writes `TimeoutError` for a test the runner killed and
|
|
121
|
+
* `AssertionError` for one that failed on its merits — the distinction
|
|
122
|
+
* #621 is entirely about, and the only place in the run where it survives
|
|
123
|
+
* in machine-readable form.
|
|
124
|
+
*/
|
|
125
|
+
failure: string | null;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const NOT_A_REPORT = "no <testsuites> root — this is not a bun JUnit report";
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Every testcase in the report, in document order, or `null` when the input
|
|
132
|
+
* is not a bun JUnit report.
|
|
133
|
+
*
|
|
134
|
+
* Written as a tag scanner rather than with an XML library because the only
|
|
135
|
+
* structure it needs is the `<testsuite>` nesting depth, and a dependency
|
|
136
|
+
* that parses the whole document would be a larger surface for a smaller
|
|
137
|
+
* answer.
|
|
138
|
+
*
|
|
139
|
+
* ONE scanner, two public readings. The names (#532) and the durations
|
|
140
|
+
* (#621) are different questions about the same elements, and a second
|
|
141
|
+
* scanner would be a second place for "a `<skipped />` testcase did not run"
|
|
142
|
+
* to be decided — so a mutation of either would leave the other holding the
|
|
143
|
+
* answer up (.claude/rules/checks-must-be-able-to-fail.md, the fourth shape).
|
|
144
|
+
*/
|
|
145
|
+
function scanJunitTestcases(xml: string): { cases: ScannedTestcase[]; skipped: number } | null {
|
|
146
|
+
if (!xml.includes("<testsuites")) return null;
|
|
147
|
+
|
|
148
|
+
const cases: ScannedTestcase[] = [];
|
|
149
|
+
const suites: string[] = [];
|
|
150
|
+
let skipped = 0;
|
|
151
|
+
|
|
152
|
+
// `pending` is non-null between a `<testcase>` open tag and its close.
|
|
153
|
+
let pending: ScannedTestcase | null = null;
|
|
154
|
+
|
|
155
|
+
const TOKEN = /<(\/?)(testsuite|testcase|skipped|failure|error)\b([^>]*?)(\/?)>/g;
|
|
156
|
+
for (const m of xml.matchAll(TOKEN)) {
|
|
157
|
+
const [, closing, tag, rest, selfClosing] = m;
|
|
158
|
+
if (tag === "testsuite") {
|
|
159
|
+
if (closing) {
|
|
160
|
+
suites.pop();
|
|
161
|
+
} else if (!selfClosing) {
|
|
162
|
+
suites.push(attr(rest, "name") ?? "");
|
|
163
|
+
}
|
|
164
|
+
continue;
|
|
165
|
+
}
|
|
166
|
+
if (tag === "testcase") {
|
|
167
|
+
if (closing) {
|
|
168
|
+
if (pending !== null) cases.push(pending);
|
|
169
|
+
pending = null;
|
|
170
|
+
continue;
|
|
171
|
+
}
|
|
172
|
+
// The first suite on the stack is the FILE, whose name is a path.
|
|
173
|
+
// Everything above it is a `describe`.
|
|
174
|
+
const testcase: ScannedTestcase = {
|
|
175
|
+
name: [...suites.slice(1), attr(rest, "name") ?? ""].join(" > "),
|
|
176
|
+
ms: durationMs(rest),
|
|
177
|
+
ran: true,
|
|
178
|
+
failure: null,
|
|
179
|
+
};
|
|
180
|
+
if (selfClosing) {
|
|
181
|
+
cases.push(testcase);
|
|
182
|
+
} else {
|
|
183
|
+
pending = testcase;
|
|
184
|
+
}
|
|
185
|
+
continue;
|
|
186
|
+
}
|
|
187
|
+
if (tag === "skipped" && !closing && pending !== null) {
|
|
188
|
+
pending.ran = false;
|
|
189
|
+
skipped++;
|
|
190
|
+
}
|
|
191
|
+
if (tag === "failure" && !closing && pending !== null) {
|
|
192
|
+
pending.failure = attr(rest, "type") ?? "";
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
return { cases, skipped };
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* The `time` attribute in milliseconds.
|
|
201
|
+
*
|
|
202
|
+
* bun writes it in fractional SECONDS — `time="1.201579"` for a test the
|
|
203
|
+
* console printed as `[1201.58ms]`. Reading it as milliseconds would put
|
|
204
|
+
* every duration a thousand times below any budget it is compared against,
|
|
205
|
+
* and a proximity check over it would be green for every suite that has ever
|
|
206
|
+
* run (#621).
|
|
207
|
+
*/
|
|
208
|
+
function durationMs(tag: string): number {
|
|
209
|
+
const raw = attr(tag, "time");
|
|
210
|
+
if (raw === null || raw.trim() === "") return NaN;
|
|
211
|
+
const seconds = Number(raw);
|
|
212
|
+
return Number.isFinite(seconds) ? seconds * 1000 : NaN;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/** The names of every testcase the report says RAN, in document order. */
|
|
216
|
+
export function parseJunitCheckNames(xml: string): JunitReading {
|
|
217
|
+
const scan = scanJunitTestcases(xml);
|
|
218
|
+
if (scan === null) return { names: null, skipped: 0, reason: NOT_A_REPORT };
|
|
219
|
+
return { names: scan.cases.filter(c => c.ran).map(c => c.name), skipped: scan.skipped };
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** `parseJunitCheckNames` over a file, with the read failure as a reading. */
|
|
223
|
+
export function readJunitCheckNames(path: string): JunitReading {
|
|
224
|
+
let xml: string;
|
|
225
|
+
try {
|
|
226
|
+
xml = readFileSync(path, "utf-8");
|
|
227
|
+
} catch (e: any) {
|
|
228
|
+
// The name, not the message: a reader error quotes the path and this
|
|
229
|
+
// string is written into workflow-state.json.
|
|
230
|
+
return { names: null, skipped: 0, reason: `the JUnit report could not be read (${e?.code || e?.name || "unknown"})` };
|
|
231
|
+
}
|
|
232
|
+
return parseJunitCheckNames(xml);
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* The full witness: every check the gate reported a verdict for.
|
|
237
|
+
*
|
|
238
|
+
* The JUnit report covers the bun tests. `reported` covers everything else
|
|
239
|
+
* the gate decided on its own — `test-census: UNMEASURED`,
|
|
240
|
+
* `ac-verdict-fail: AC-2`, the dev-server liveness probe — which are real
|
|
241
|
+
* verdicts with no testcase behind them, and which appear in the failure
|
|
242
|
+
* ledger. Leaving them out would break the superset property in exactly the
|
|
243
|
+
* places where the names are not bun's.
|
|
244
|
+
*
|
|
245
|
+
* `null` in, `null` out. A gate whose report could not be read says nothing
|
|
246
|
+
* about what it ran, and must retire nothing.
|
|
247
|
+
*/
|
|
248
|
+
export function checksRunFrom(reading: JunitReading, reported: string[]): string[] | null {
|
|
249
|
+
return unionNames(reading.names, reported);
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* `base` with `extra` appended, de-duplicated, order preserved. `null`
|
|
254
|
+
* propagates.
|
|
255
|
+
*
|
|
256
|
+
* Exported because the union has to be applied twice: once at the gate's
|
|
257
|
+
* call site, and again inside `writeGateResult`, which pushes
|
|
258
|
+
* `ac-verdict-fail:` entries of its own AFTER the caller has read the
|
|
259
|
+
* results. A second union there is not a second decider — it is the same
|
|
260
|
+
* function over a later reading of the same list, and skipping it would
|
|
261
|
+
* leave `checksRun` short of `failures` by exactly the entries that gate
|
|
262
|
+
* adds last.
|
|
263
|
+
*/
|
|
264
|
+
export function unionNames(base: string[] | null, extra: string[]): string[] | null {
|
|
265
|
+
if (base === null) return null;
|
|
266
|
+
const seen = new Set<string>();
|
|
267
|
+
const out: string[] = [];
|
|
268
|
+
for (const name of [...base, ...extra]) {
|
|
269
|
+
if (typeof name !== "string" || name === "" || seen.has(name)) continue;
|
|
270
|
+
seen.add(name);
|
|
271
|
+
out.push(name);
|
|
272
|
+
}
|
|
273
|
+
return out;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/* ───────────────────────────────────────────────────────────────────────────
|
|
277
|
+
* #621: how close the suite ran to the per-test timeout
|
|
278
|
+
*
|
|
279
|
+
* The same report, asked a different question. #621's 122 "failures" were
|
|
280
|
+
* 122 timeouts: every one at or above bun's 5000ms per-test budget, 112
|
|
281
|
+
* carrying `timed out after 5000ms`, and not one an assertion failure. A
|
|
282
|
+
* verdict like that is a fact about machine load, not about the code.
|
|
283
|
+
*
|
|
284
|
+
* The warning is in the durations. A test at 99% of the budget passes today
|
|
285
|
+
* and is killed the first time it runs beside 27 agents, and the console
|
|
286
|
+
* output says nothing about it — only the JUnit report carries a number for
|
|
287
|
+
* every testcase.
|
|
288
|
+
*
|
|
289
|
+
* TWO READINGS, NOT ONE VERDICT. `durationCoverageViolations` answers "did
|
|
290
|
+
* this reading read anything?" and `timeoutProximityViolations` answers "is
|
|
291
|
+
* anything it read near the budget?". An empty report satisfies the second
|
|
292
|
+
* perfectly, which is why the first exists and why the proximity check stays
|
|
293
|
+
* SILENT on an empty reading instead of refusing it: if both refused, they
|
|
294
|
+
* would be one question with two names, and nothing could tell a report that
|
|
295
|
+
* is clean from a reader that stopped reading (AC-7).
|
|
296
|
+
* ──────────────────────────────────────────────────────────────────────── */
|
|
297
|
+
|
|
298
|
+
/** One testcase's measured duration. */
|
|
299
|
+
export interface TestcaseDuration {
|
|
300
|
+
/** The full name, as the console prints it. */
|
|
301
|
+
name: string;
|
|
302
|
+
/** Milliseconds. */
|
|
303
|
+
ms: number;
|
|
304
|
+
/** The runner killed it: bun wrote `<failure type="TimeoutError" />`. */
|
|
305
|
+
timedOut: boolean;
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/** What one JUnit report says about how long its testcases took. */
|
|
309
|
+
export interface JunitDurationReading {
|
|
310
|
+
/**
|
|
311
|
+
* Every testcase that RAN and carried a readable duration. `null` when the
|
|
312
|
+
* report could not be read at all — a different answer from `[]` ("the
|
|
313
|
+
* report lists nothing"), and the two have to stay different all the way to
|
|
314
|
+
* the consumer (.claude/rules/config-access.md, Silent Default
|
|
315
|
+
* Substitution).
|
|
316
|
+
*/
|
|
317
|
+
durations: TestcaseDuration[] | null;
|
|
318
|
+
/** How many durations were read. The reading's own coverage (AC-7a). */
|
|
319
|
+
count: number;
|
|
320
|
+
/** Testcases listed but not run — filtered out, `.skip`, or `.todo`. */
|
|
321
|
+
skipped: number;
|
|
322
|
+
/**
|
|
323
|
+
* Testcases that ran and carried no readable `time`. Counted rather than
|
|
324
|
+
* dropped: a reader that silently shrinks its own population reports a
|
|
325
|
+
* clean proximity check over the half it managed to parse.
|
|
326
|
+
*/
|
|
327
|
+
withoutDuration: number;
|
|
328
|
+
/** Why `durations` is null. */
|
|
329
|
+
reason?: string;
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/** Every testcase duration the report carries, in document order. */
|
|
333
|
+
export function parseJunitDurations(xml: string): JunitDurationReading {
|
|
334
|
+
const scan = scanJunitTestcases(xml);
|
|
335
|
+
if (scan === null) {
|
|
336
|
+
return { durations: null, count: 0, skipped: 0, withoutDuration: 0, reason: NOT_A_REPORT };
|
|
337
|
+
}
|
|
338
|
+
const ran = scan.cases.filter(c => c.ran);
|
|
339
|
+
const durations = ran
|
|
340
|
+
.filter(c => Number.isFinite(c.ms))
|
|
341
|
+
.map(c => ({ name: c.name, ms: c.ms, timedOut: c.failure === "TimeoutError" }));
|
|
342
|
+
return {
|
|
343
|
+
durations,
|
|
344
|
+
count: durations.length,
|
|
345
|
+
skipped: scan.skipped,
|
|
346
|
+
withoutDuration: ran.length - durations.length,
|
|
347
|
+
};
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/** `parseJunitDurations` over a file, with the read failure as a reading. */
|
|
351
|
+
export function readJunitDurations(path: string): JunitDurationReading {
|
|
352
|
+
let xml: string;
|
|
353
|
+
try {
|
|
354
|
+
xml = readFileSync(path, "utf-8");
|
|
355
|
+
} catch (e: any) {
|
|
356
|
+
return {
|
|
357
|
+
durations: null,
|
|
358
|
+
count: 0,
|
|
359
|
+
skipped: 0,
|
|
360
|
+
withoutDuration: 0,
|
|
361
|
+
// The name, not the message: a reader error quotes the path.
|
|
362
|
+
reason: `the JUnit report could not be read (${e?.code || e?.name || "unknown"})`,
|
|
363
|
+
};
|
|
364
|
+
}
|
|
365
|
+
return parseJunitDurations(xml);
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* The per-test timeout a `bunfig.toml` declares, or `null` if it declares
|
|
370
|
+
* none.
|
|
371
|
+
*
|
|
372
|
+
* Scoped to the `[test]` table and nothing else. A `timeout` under
|
|
373
|
+
* `[install]` is a different setting entirely, and a reader that matched the
|
|
374
|
+
* key anywhere in the document would measure the suite against a number
|
|
375
|
+
* about package downloads — searching the document instead of the slice is
|
|
376
|
+
* how three checks in this repo went green over text they were not about
|
|
377
|
+
* (.claude/rules/checks-must-be-able-to-fail.md).
|
|
378
|
+
*/
|
|
379
|
+
export function bunfigTestTimeoutMs(toml: string): number | null {
|
|
380
|
+
const lines = toml.split("\n");
|
|
381
|
+
const start = lines.findIndex(line => /^\s*\[test\]\s*(#.*)?$/.test(line));
|
|
382
|
+
if (start === -1) return null;
|
|
383
|
+
const rest = lines.slice(start + 1);
|
|
384
|
+
const end = rest.findIndex(line => /^\s*\[/.test(line));
|
|
385
|
+
const section = (end === -1 ? rest : rest.slice(0, end)).join("\n");
|
|
386
|
+
const m = /^\s*timeout\s*=\s*(\d+)\s*(#.*)?$/m.exec(section);
|
|
387
|
+
return m ? Number(m[1]) : null;
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
/**
|
|
391
|
+
* What is wrong with the READING, before anything is concluded from it
|
|
392
|
+
* (AC-7a).
|
|
393
|
+
*
|
|
394
|
+
* A scan that reports a verdict should report its own coverage: "0 of 0 are
|
|
395
|
+
* near the budget" and "0 of 13358 are near the budget" are the same PASS
|
|
396
|
+
* today, and no reader can tell them apart from the output.
|
|
397
|
+
*/
|
|
398
|
+
export function durationCoverageViolations(reading: JunitDurationReading, source: string): string[] {
|
|
399
|
+
if (reading.durations === null) {
|
|
400
|
+
return [
|
|
401
|
+
`the JUnit report at ${source} could not be read (${reading.reason ?? "no reason recorded"}), ` +
|
|
402
|
+
`so nothing is known about how long anything took (#621)`,
|
|
403
|
+
];
|
|
404
|
+
}
|
|
405
|
+
const out: string[] = [];
|
|
406
|
+
if (reading.count === 0) {
|
|
407
|
+
out.push(
|
|
408
|
+
`the JUnit report at ${source} carries no testcase durations (0 read, ${reading.skipped} skipped) — ` +
|
|
409
|
+
`an empty report satisfies a proximity check by having nothing in it, which is not a measurement (#621)`,
|
|
410
|
+
);
|
|
411
|
+
}
|
|
412
|
+
if (reading.withoutDuration > 0) {
|
|
413
|
+
out.push(
|
|
414
|
+
`${reading.withoutDuration} of ${reading.withoutDuration + reading.count} testcases that ran in ${source} ` +
|
|
415
|
+
`carry no readable time attribute — the reading is partial, and the missing ones are exactly the ` +
|
|
416
|
+
`population a proximity check cannot see (#621)`,
|
|
417
|
+
);
|
|
418
|
+
}
|
|
419
|
+
return out;
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
/**
|
|
423
|
+
* Every testcase the per-test budget is about to kill, or already killed —
|
|
424
|
+
* named, with its duration (AC-3b).
|
|
425
|
+
*
|
|
426
|
+
* ## Three classes, and only two of them are findings
|
|
427
|
+
*
|
|
428
|
+
* | What the report shows | What it means | Reported |
|
|
429
|
+
* |---|---|---|
|
|
430
|
+
* | `<failure type="TimeoutError" />` | the runner killed it | **yes** — this is #621's 122 |
|
|
431
|
+
* | ran, and finished inside the band `[timeout·(1−f), timeout)` | it is next | **yes** — the warning |
|
|
432
|
+
* | ran, and finished at or past `timeout` without timing out | it was given a BIGGER budget, or it could not have got there | no |
|
|
433
|
+
*
|
|
434
|
+
* The third row is the one that keeps this check usable. A test carrying
|
|
435
|
+
* `}, 240000)` — `gates/workflow.test.ts`'s typecheck check, measured at
|
|
436
|
+
* 16770ms — is not at risk from a 5000ms default, and reporting it would
|
|
437
|
+
* make the check red on every run forever. A gate that cries wolf trains its
|
|
438
|
+
* reader to ignore it, which is the cost #621 is filed about; so the rule is
|
|
439
|
+
* that **a duration past the budget is itself the evidence that the budget
|
|
440
|
+
* is not this test's**.
|
|
441
|
+
*
|
|
442
|
+
* It follows that declaring a per-test timeout silences a row here, and that
|
|
443
|
+
* is deliberate: an 8-second test that says it needs 8 seconds is a decision
|
|
444
|
+
* somebody made, and an 8-second test that nobody budgeted for is a timeout
|
|
445
|
+
* waiting for a loaded machine. Raising the FILE-wide default to silence a
|
|
446
|
+
* row is the repair #621 refuses, and it is refused where the default is
|
|
447
|
+
* declared rather than here.
|
|
448
|
+
*
|
|
449
|
+
* SILENT on a reading of nothing, deliberately — see the header above.
|
|
450
|
+
* `durationCoverageViolations` is the question about an empty reading, and
|
|
451
|
+
* keeping them apart is what makes a red row say which one broke.
|
|
452
|
+
*/
|
|
453
|
+
export function timeoutProximityViolations(
|
|
454
|
+
reading: JunitDurationReading,
|
|
455
|
+
timeoutMs: number,
|
|
456
|
+
withinFraction = 0.01,
|
|
457
|
+
): string[] {
|
|
458
|
+
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
|
|
459
|
+
return [
|
|
460
|
+
`no usable per-test timeout to compare against (${timeoutMs}) — a budget of zero or NaN makes every ` +
|
|
461
|
+
`comparison below meaningless rather than clean (#621)`,
|
|
462
|
+
];
|
|
463
|
+
}
|
|
464
|
+
if (reading.durations === null) return [];
|
|
465
|
+
const floor = timeoutMs * (1 - withinFraction);
|
|
466
|
+
const out: string[] = [];
|
|
467
|
+
for (const d of reading.durations) {
|
|
468
|
+
if (d.timedOut) {
|
|
469
|
+
out.push(
|
|
470
|
+
`${d.name} was KILLED after ${d.ms.toFixed(2)}ms by a per-test timeout — it did not fail on its ` +
|
|
471
|
+
`merits, and on a less loaded machine it would not have failed at all (#621)`,
|
|
472
|
+
);
|
|
473
|
+
continue;
|
|
474
|
+
}
|
|
475
|
+
if (d.ms >= floor && d.ms < timeoutMs) {
|
|
476
|
+
out.push(
|
|
477
|
+
`${d.name} took ${d.ms.toFixed(2)}ms, ${((d.ms / timeoutMs) * 100).toFixed(1)}% of the ${timeoutMs}ms ` +
|
|
478
|
+
`per-test timeout — within ${withinFraction * 100}% of being killed instead of failing on its merits. ` +
|
|
479
|
+
`Make it faster, or give it a budget of its own with a per-test timeout argument (#621)`,
|
|
480
|
+
);
|
|
481
|
+
}
|
|
482
|
+
}
|
|
483
|
+
return out;
|
|
484
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The project's one day stamp (#600).
|
|
3
|
+
*
|
|
4
|
+
* A LEAF module, in the shape `lib/git-dates.ts` established (#508): one
|
|
5
|
+
* exported binding, no relative imports, so there is exactly one thing to
|
|
6
|
+
* mutate and every call site names the same rule.
|
|
7
|
+
*
|
|
8
|
+
* ## Why this exists
|
|
9
|
+
*
|
|
10
|
+
* `new Date().toISOString().split("T")[0]` is the UTC calendar day. Between
|
|
11
|
+
* 20:00 EDT and midnight that is TOMORROW, so an evening session stamps work
|
|
12
|
+
* on a day it did not happen. Twenty sites in this tree did it, and the one
|
|
13
|
+
* that mattered was `scripts/update-project-state.ts`, whose stamp is read
|
|
14
|
+
* back by the pre-commit hook: the hook only produced a staged diff when the
|
|
15
|
+
* computed stamp differed from the stored one, so the DA-owned-file violation
|
|
16
|
+
* of #599 fired for about four hours a day and the other twenty hours of
|
|
17
|
+
* green runs were not evidence of compliance. A date that is wrong for four
|
|
18
|
+
* hours a day is worse than one that is wrong always, because the twenty
|
|
19
|
+
* green hours look like a passing check.
|
|
20
|
+
*
|
|
21
|
+
* ## What it is NOT for
|
|
22
|
+
*
|
|
23
|
+
* Instants. `new Date().toISOString()` — the whole timestamp — is correct and
|
|
24
|
+
* stays correct: an instant is zone-free and UTC is its canonical spelling.
|
|
25
|
+
* This module is only about collapsing an instant to the calendar day a
|
|
26
|
+
* HUMAN would write next to it, and that question has no answer without a
|
|
27
|
+
* zone.
|
|
28
|
+
*
|
|
29
|
+
* ## Why Intl rather than getFullYear/getMonth/getDate
|
|
30
|
+
*
|
|
31
|
+
* The local-getter form is three calls that must each be padded correctly and
|
|
32
|
+
* cannot be pointed at another zone, so a test for the defect would have to
|
|
33
|
+
* mutate `process.env.TZ` and could never assert the explicit-zone case.
|
|
34
|
+
* `formatToParts` answers both from one binding, and `calendar`/
|
|
35
|
+
* `numberingSystem` are pinned so a host default cannot hand back a
|
|
36
|
+
* non-Gregorian year or non-Latin digits.
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
const PART_FORMAT: Intl.DateTimeFormatOptions = {
|
|
40
|
+
calendar: "gregory",
|
|
41
|
+
numberingSystem: "latn",
|
|
42
|
+
year: "numeric",
|
|
43
|
+
month: "2-digit",
|
|
44
|
+
day: "2-digit",
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* The calendar day `at` falls on, in `timeZone`, as `YYYY-MM-DD`.
|
|
49
|
+
*
|
|
50
|
+
* @param at the instant to collapse. Defaults to now.
|
|
51
|
+
* @param timeZone an IANA zone. Defaults to the process zone, which is what
|
|
52
|
+
* every call site in this repo wants — the day the person
|
|
53
|
+
* running the command is living in.
|
|
54
|
+
*/
|
|
55
|
+
export function localCalendarDay(at: Date = new Date(), timeZone?: string): string {
|
|
56
|
+
if (Number.isNaN(at.getTime())) {
|
|
57
|
+
// Intl renders an invalid date as literal "Invalid Date" parts rather
|
|
58
|
+
// than throwing, and a frontmatter block reading `updated: Invalid Date`
|
|
59
|
+
// is worse than a crash: it is written, committed, and read as a date.
|
|
60
|
+
throw new Error("localCalendarDay: invalid Date — nothing to stamp");
|
|
61
|
+
}
|
|
62
|
+
const parts = new Intl.DateTimeFormat(
|
|
63
|
+
"en-US",
|
|
64
|
+
timeZone ? { ...PART_FORMAT, timeZone } : PART_FORMAT,
|
|
65
|
+
).formatToParts(at);
|
|
66
|
+
const of = (type: Intl.DateTimeFormatPartTypes) => parts.find(p => p.type === type)?.value;
|
|
67
|
+
const year = of("year");
|
|
68
|
+
const month = of("month");
|
|
69
|
+
const day = of("day");
|
|
70
|
+
if (!year || !month || !day) {
|
|
71
|
+
// Only reachable if a host's ICU stops emitting a requested part. Loud,
|
|
72
|
+
// because the alternative is `undefined-undefined-undefined` in a doc.
|
|
73
|
+
throw new Error(
|
|
74
|
+
`localCalendarDay: Intl did not return year/month/day for ${timeZone ?? "the process zone"}`,
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
return `${year.padStart(4, "0")}-${month}-${day}`;
|
|
78
|
+
}
|
|
@@ -164,3 +164,62 @@ export function missingStateVerdict(opts: {
|
|
|
164
164
|
}
|
|
165
165
|
return { verdict: "SKIP", detail: "project-state.json not found and no PROJECT-STATE.md to maintain — nothing to do" };
|
|
166
166
|
}
|
|
167
|
+
|
|
168
|
+
/** One rendered session, and the entries the selection could not place. */
|
|
169
|
+
export interface SessionSelection<T> {
|
|
170
|
+
/** Newest first, at most `limit` of them. */
|
|
171
|
+
rendered: T[];
|
|
172
|
+
/**
|
|
173
|
+
* Entries whose `date` does not begin with an ISO date.
|
|
174
|
+
*
|
|
175
|
+
* They are NOT excluded — they rank below every dated entry, in array
|
|
176
|
+
* order, which is the only information left about them and is exactly
|
|
177
|
+
* what the old renderer used for everything. A project whose dates are
|
|
178
|
+
* all free-form therefore renders exactly as it did before.
|
|
179
|
+
*
|
|
180
|
+
* They are reported by name, because an entry nobody can order is a
|
|
181
|
+
* thing worth saying out loud: it will be outranked by any dated entry,
|
|
182
|
+
* however old, and that is surprising if you cannot see it.
|
|
183
|
+
*/
|
|
184
|
+
undated: T[];
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})\b/;
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* The `limit` NEWEST sessions, chosen by date (#572).
|
|
191
|
+
*
|
|
192
|
+
* The renderer used to take `[...sessions].reverse().slice(0, 3)` — "the
|
|
193
|
+
* last three entries of the array", which is correct exactly while the
|
|
194
|
+
* array is in append order and which nothing anywhere enforced. Session 48
|
|
195
|
+
* was written to `sessions[0]`, so eight merged issues never appeared in
|
|
196
|
+
* PROJECT-STATE.md, the file AGENTS.md tells the next session to read
|
|
197
|
+
* first. The script printed `✅ rewrote` every time, because it had in fact
|
|
198
|
+
* rewritten the file.
|
|
199
|
+
*
|
|
200
|
+
* This is the second instance of that bug in the same function. The first
|
|
201
|
+
* was `slice(0, 3)` rendering the three OLDEST entries, and the fix was
|
|
202
|
+
* `.reverse()` — which repaired the symptom and left the defect: the
|
|
203
|
+
* renderer still had no idea which sessions were newest, it just trusted a
|
|
204
|
+
* position. Choosing by date removes the position from the question
|
|
205
|
+
* entirely, so where an entry is written stops mattering.
|
|
206
|
+
*
|
|
207
|
+
* Ties keep array order with the later index first, which is the only
|
|
208
|
+
* information left when two entries share a day — and several do.
|
|
209
|
+
*/
|
|
210
|
+
export function selectRecentSessions<T extends { date: string }>(
|
|
211
|
+
sessions: readonly T[],
|
|
212
|
+
limit: number,
|
|
213
|
+
): SessionSelection<T> {
|
|
214
|
+
const undated: T[] = [];
|
|
215
|
+
const ranked = sessions.map((s, i) => {
|
|
216
|
+
const m = ISO_DATE.exec(s.date ?? "");
|
|
217
|
+
if (m === null) undated.push(s);
|
|
218
|
+
// An undated entry sorts below every dated one. `""` is less than any
|
|
219
|
+
// ISO date, so the comparison needs no second branch — and a branch
|
|
220
|
+
// that exists only for the empty case is a branch no fixture reaches.
|
|
221
|
+
return { s, key: m === null ? "" : m[0], i };
|
|
222
|
+
});
|
|
223
|
+
ranked.sort((a, b) => (a.key === b.key ? b.i - a.i : a.key < b.key ? 1 : -1));
|
|
224
|
+
return { rendered: ranked.slice(0, limit).map(d => d.s), undated };
|
|
225
|
+
}
|
package/lib/promote-outputs.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, statSync } from "fs";
|
|
2
2
|
import { join, basename } from "path";
|
|
3
|
+
import { localCalendarDay } from "./local-calendar-day";
|
|
3
4
|
|
|
4
5
|
interface PromoteResult {
|
|
5
6
|
promoted: string[];
|
|
@@ -32,7 +33,10 @@ export function promoteOutputs(projectRoot: string): PromoteResult {
|
|
|
32
33
|
const data = JSON.parse(readFileSync(councilJson, "utf-8"));
|
|
33
34
|
const topic = data.topic || slug;
|
|
34
35
|
const topicSlug = topic.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
|
|
35
|
-
|
|
36
|
+
// `capturedAt` is an ISO INSTANT written by the council run, so
|
|
37
|
+
// slicing it is reading a recorded field rather than stamping a day.
|
|
38
|
+
// The fallback — nothing recorded — is a day stamp and is local (#600).
|
|
39
|
+
const date = data.capturedAt?.slice(0, 10) || localCalendarDay();
|
|
36
40
|
const destDir = join(projectRoot, "docs", "council");
|
|
37
41
|
const destFile = join(destDir, `${date}-${topicSlug}.md`);
|
|
38
42
|
|
|
@@ -140,7 +144,7 @@ function buildResearchMarkdown(data: any, topic: string): string {
|
|
|
140
144
|
"---",
|
|
141
145
|
"doc-type: research",
|
|
142
146
|
"status: active",
|
|
143
|
-
`created: ${
|
|
147
|
+
`created: ${localCalendarDay()}`,
|
|
144
148
|
`governs: ${topic}`,
|
|
145
149
|
"---",
|
|
146
150
|
"",
|