rungate 0.4.1 → 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.
Files changed (87) hide show
  1. package/config/behavioral-sc-map.json +170 -0
  2. package/config/brief-policies.json +28 -0
  3. package/config/ceremony-profiles.json +207 -0
  4. package/config/check-registry.json +114 -0
  5. package/config/matcher-registry.json +142 -0
  6. package/config/prove-evidence.schema.json +65 -0
  7. package/config/spec-policies.json +36 -0
  8. package/config/universal-rules.yaml +15 -0
  9. package/config/workflow-schema.json +279 -0
  10. package/lib/agents-md-sections.ts +144 -0
  11. package/lib/branch-diff.ts +139 -0
  12. package/lib/bun-version.ts +268 -0
  13. package/lib/ci-checkout.ts +1 -1
  14. package/lib/cli-commands.ts +7 -1
  15. package/lib/compliance.ts +13 -11
  16. package/lib/config-loader.ts +12 -0
  17. package/lib/conformity.ts +1147 -116
  18. package/lib/context-docs.ts +143 -28
  19. package/lib/create-brief.ts +2 -1
  20. package/lib/create-sc.ts +90 -4
  21. package/lib/doc-scan-targets.ts +9 -0
  22. package/lib/evidence-command-transport.ts +160 -0
  23. package/lib/evidence-prevalidator.ts +22 -0
  24. package/lib/fallow-availability.ts +129 -0
  25. package/lib/gate-refusal-currency.ts +112 -0
  26. package/lib/gate-timeouts.ts +82 -0
  27. package/lib/generators/agent-briefs.ts +4 -1
  28. package/lib/generators/agents-md.ts +71 -23
  29. package/lib/generators/code-map.ts +2 -1
  30. package/lib/generators/types.ts +8 -0
  31. package/lib/git-dates.ts +55 -0
  32. package/lib/github.ts +195 -0
  33. package/lib/js-top-level-code.ts +27 -2
  34. package/lib/junit-checks.ts +484 -0
  35. package/lib/local-calendar-day.ts +78 -0
  36. package/lib/package-closure.ts +278 -2
  37. package/lib/project-state-shape.ts +59 -0
  38. package/lib/promote-outputs.ts +6 -2
  39. package/lib/release-preflight.ts +196 -0
  40. package/lib/report-provenance.ts +156 -0
  41. package/lib/sc-claim-forms.ts +75 -0
  42. package/lib/sc-id-cross-tree.ts +311 -0
  43. package/lib/scaffold/ai-review-step.ts +180 -0
  44. package/lib/scaffold/defaults.ts +40 -0
  45. package/lib/scaffold/managed-workflow.ts +125 -27
  46. package/lib/scaffold/owned-files.ts +48 -2
  47. package/lib/scaffold/profiles.ts +94 -0
  48. package/lib/scaffold/rehearsal.ts +232 -73
  49. package/lib/scaffold/steps.ts +777 -152
  50. package/lib/scaffold/write-steps.ts +56 -13
  51. package/lib/scanner.ts +38 -12
  52. package/lib/source-anchor.ts +144 -0
  53. package/lib/spec-listing.ts +148 -0
  54. package/lib/spec-requirements.ts +209 -0
  55. package/lib/success-doc.ts +779 -0
  56. package/lib/suite-run-reading.ts +364 -0
  57. package/lib/test-census.ts +199 -0
  58. package/lib/test-command.ts +133 -0
  59. package/lib/test-suite-lock.ts +166 -10
  60. package/lib/tool-probe.ts +120 -0
  61. package/lib/tracked-vs-ignored.ts +234 -0
  62. package/lib/trajectory.ts +377 -0
  63. package/lib/validators/spec-validators.ts +35 -6
  64. package/lib/workflow-security.ts +101 -0
  65. package/lib/workflow-test-harness.ts +349 -0
  66. package/package.json +6 -1
  67. package/scripts/audit-specs.ts +247 -12
  68. package/scripts/audit-transcript.ts +2 -1
  69. package/scripts/convert-spec.ts +2 -1
  70. package/scripts/create-sc.ts +17 -7
  71. package/scripts/create-spec.ts +2 -1
  72. package/scripts/create-success.ts +163 -0
  73. package/scripts/extract-constraints.ts +90 -19
  74. package/scripts/generate-code-map.ts +53 -12
  75. package/scripts/scaffold-project.ts +31 -4
  76. package/scripts/split-spec.ts +2 -1
  77. package/scripts/sync-sc-status.ts +57 -5
  78. package/scripts/sync-spec-tests.ts +2 -1
  79. package/specs/SPEC-TEMPLATE.md +200 -0
  80. package/templates/SUCCESS-TEMPLATE.md +72 -0
  81. package/templates/agent-briefs/_shared.md +9 -0
  82. package/templates/agent-briefs/aditi.md +46 -0
  83. package/templates/agent-briefs/discovery.md +37 -0
  84. package/templates/agent-briefs/marcus.md +39 -0
  85. package/templates/agent-briefs/quinn.md +67 -0
  86. package/templates/agent-briefs/rook.md +40 -0
  87. package/templates/agent-briefs/serena.md +39 -0
@@ -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 &amp;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
+ [/&lt;/g, "<"],
94
+ [/&gt;/g, ">"],
95
+ [/&quot;/g, '"'],
96
+ [/&apos;/g, "'"],
97
+ // Last, so `&amp;gt;` decodes to `&gt;` and not to `>`.
98
+ [/&amp;/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
+ }