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,364 @@
1
+ /**
2
+ * What a test runner's own output says it did (#469, #490).
3
+ *
4
+ * `lib/suite-measurement.ts` reads the RECORD a run left behind and refuses
5
+ * everything that is not a complete, SHA-bound result. This file is one step
6
+ * upstream of it: it reads the runner's output and decides whether there is a
7
+ * result to record at all. The two defects it exists for are the same defect
8
+ * at two sizes.
9
+ *
10
+ * **#469 — a run that read none of its files exits 0.** Observed verbatim on
11
+ * 2026-10-16, after a worktree was deleted by hand while its suite was
12
+ * running: four `error: ENOENT reading "…"` blocks, no `N pass / N fail`
13
+ * summary, and `[exited with code 0]`. Reproduced here on bun 1.3.14 by
14
+ * removing the test directory from the first file imported, which prints the
15
+ * banner and nothing else. The exit code differs between the two — 0 then, 1
16
+ * now — which is the argument for not reading the exit code at all. Both runs
17
+ * measured nothing, and only the absence of a summary says so.
18
+ *
19
+ * **#490 — a runner that discovers nothing looks exactly like a clean run.**
20
+ * Measured on the same bun: a project whose only test file declares no tests
21
+ * prints
22
+ *
23
+ * 0 pass
24
+ * 0 fail
25
+ * Ran 0 tests across 1 file. [6.00ms]
26
+ *
27
+ * and exits 0. Every indicator is green over a suite that asserted nothing.
28
+ *
29
+ * **The file count is the proxy; the executed count is the property.** #490
30
+ * asks for the discovered FILE count to be greater than zero, and that row
31
+ * above is why this module does not stop there: one empty file satisfies
32
+ * "files > 0" while measuring exactly as much as no files at all. That is the
33
+ * trap `.claude/rules/checks-must-be-able-to-fail.md` records as wording a
34
+ * refusal after the cheapest proxy rather than after the property — a proxy
35
+ * is a thing people can satisfy directly. So the file count is READ, RECORDED
36
+ * and refused when it contradicts the results, and the refusal that carries
37
+ * the weight is about what the runner executed.
38
+ *
39
+ * Nothing here throws, for the same reason nothing in `lib/suite-measurement.ts`
40
+ * does: it is read on the path that decides whether a run may ship, and a
41
+ * throw is a refusal the caller's error handling can turn back into a ship.
42
+ */
43
+
44
+ /**
45
+ * `N pass` and `N fail` on their own lines — bun's summary, and the shape
46
+ * `parseTestFailureCount` in gates/gate-executor.ts has read since #307.
47
+ * Anchored to the whole line so a sentence mentioning "0 fail" inside a
48
+ * captured test output cannot be read as the summary.
49
+ */
50
+ const PASS_LINE = /^\s*(\d+)\s+pass\s*$/gm;
51
+ const FAIL_LINE = /^\s*(\d+)\s+fail\s*$/gm;
52
+
53
+ /** `Ran 11521 tests across 324 files.` — and `1 test across 1 file.` */
54
+ const RAN_LINE = /^Ran\s+(\d+)\s+tests?\s+across\s+(\d+)\s+files?\./gm;
55
+
56
+ export interface MeasuredRun {
57
+ status: "MEASURED";
58
+ pass: number;
59
+ fail: number;
60
+ /**
61
+ * Tests the runner says it ran, or null when it did not say.
62
+ *
63
+ * null rather than `pass + fail`: a derived number here would be
64
+ * indistinguishable from one the runner reported, and the point of the
65
+ * whole module is that a number nobody measured must not be reportable.
66
+ */
67
+ tests: number | null;
68
+ /**
69
+ * Test files the runner discovered, or null when it did not say.
70
+ *
71
+ * **null, never 0.** "This runner does not report a file count" and "this
72
+ * runner found no files" are opposite facts, and `0` is the one value that
73
+ * would let a reader add them together — `.claude/rules/config-access.md`,
74
+ * *Silent Default Substitution*, pointed at the number #490 is about.
75
+ */
76
+ files: number | null;
77
+ }
78
+
79
+ export interface UnmeasuredRun {
80
+ status: "UNMEASURED";
81
+ reason: string;
82
+ }
83
+
84
+ export type SuiteRun = MeasuredRun | UnmeasuredRun;
85
+
86
+ function unmeasured(reason: string): UnmeasuredRun {
87
+ return { status: "UNMEASURED", reason };
88
+ }
89
+
90
+ /** The last match of a global pattern, or null. Last, because a suite run can
91
+ * contain another suite's captured output and the summary is printed at the
92
+ * end — the same choice `parseTestFailureCount` made in #307. */
93
+ function lastMatch(re: RegExp, text: string): RegExpMatchArray | null {
94
+ const all = [...text.matchAll(re)];
95
+ return all.length === 0 ? null : all[all.length - 1];
96
+ }
97
+
98
+ /** How much of the output to quote back in a refusal, so a reason is readable
99
+ * without pasting a 400 KB suite log into a gate failure. */
100
+ function tail(output: string, limit = 240): string {
101
+ const lines = output.trimEnd().split("\n").filter(l => l.trim() !== "");
102
+ const last = lines.slice(-3).join(" / ");
103
+ return last.length > limit ? `${last.slice(0, limit)}…` : last || "(nothing)";
104
+ }
105
+
106
+ /**
107
+ * Read a test runner's output.
108
+ *
109
+ * FAILS CLOSED. Every path that cannot positively establish that the runner
110
+ * executed something returns UNMEASURED with a reason. There is no path that
111
+ * returns a zero-failure MEASURED reading from an output that does not say so.
112
+ *
113
+ * The EXIT CODE is deliberately not a parameter. #469's run exited 0 having
114
+ * measured nothing; the reproduction of it here exits 1. A reading that
115
+ * consulted the exit code would have been wrong about one of them, and
116
+ * choosing which is not a thing this function can know.
117
+ */
118
+ export function readSuiteRun(output: unknown): SuiteRun {
119
+ if (typeof output !== "string" || output.trim() === "") {
120
+ return unmeasured(
121
+ "the test runner produced no output, so there is nothing to read a result out of — " +
122
+ "a run with no output is not a run with no failures (#469)",
123
+ );
124
+ }
125
+
126
+ const passMatch = lastMatch(PASS_LINE, output);
127
+ const failMatch = lastMatch(FAIL_LINE, output);
128
+
129
+ // #469's shape, and half of it. ONE branch, two sentences: the run printed
130
+ // no summary, or printed half of one, and in both cases there is no result
131
+ // to read. Written as a single decider on purpose — a separate `!pass &&
132
+ // !fail` branch above this would be a second guard answering a question
133
+ // this one already answers, and no behavioural test could tell them apart
134
+ // (.claude/rules/checks-must-be-able-to-fail.md, the fourth shape). The
135
+ // distinction is a wording, so it lives in the wording.
136
+ if (!passMatch || !failMatch) {
137
+ const missing = [!passMatch && "pass", !failMatch && "fail"].filter(Boolean) as string[];
138
+ const what =
139
+ missing.length === 2
140
+ ? "printed no pass/fail summary, so it never reported a result — this is a run that " +
141
+ "measured nothing, not a run that found nothing wrong"
142
+ : `printed a "${passMatch ? "pass" : "fail"}" count but no "${missing[0]}" count, so its ` +
143
+ "summary is incomplete and the missing half cannot be assumed to be zero";
144
+ return unmeasured(`the test runner ${what} (#469). Last output: ${tail(output)}`);
145
+ }
146
+
147
+ const pass = Number(passMatch[1]);
148
+ const fail = Number(failMatch[1]);
149
+
150
+ const ran = lastMatch(RAN_LINE, output);
151
+ const tests = ran ? Number(ran[1]) : null;
152
+ const files = ran ? Number(ran[2]) : null;
153
+
154
+ // #490 SC-1, as a contradiction rather than as a second way of asking
155
+ // whether anything ran. A runner claiming results it discovered no files to
156
+ // produce is not reporting a measurement of this project, and it is the one
157
+ // case the executed-count refusal below cannot see: that one fires when
158
+ // nothing ran, and this one fires only when something did.
159
+ if (files === 0 && pass + fail > 0) {
160
+ return unmeasured(
161
+ `the test runner reported ${pass + fail} result(s) but says it discovered 0 test files — ` +
162
+ "the counts contradict each other, so neither can be read as a measurement of this project (#490)",
163
+ );
164
+ }
165
+
166
+ // #490's real shape, and the reason this is about the executed count rather
167
+ // than the file count: `Ran 0 tests across 1 file.` exits 0 with every
168
+ // indicator green. One empty file satisfies "files > 0" and measures
169
+ // nothing.
170
+ if (pass + fail === 0) {
171
+ const where =
172
+ files === null
173
+ ? "and it did not say how many test files it discovered"
174
+ : `across the ${files} test file(s) it discovered`;
175
+ return unmeasured(
176
+ `the test runner executed 0 tests ${where} — a runner that discovered nothing to run is ` +
177
+ "indistinguishable from a clean suite by its exit code, and it is not one (#490)",
178
+ );
179
+ }
180
+
181
+ return { status: "MEASURED", pass, fail, tests, files };
182
+ }
183
+
184
+ /**
185
+ * The verdict a reading supports.
186
+ *
187
+ * Three verdicts and not two, for the reason `lib/suite-measurement.ts`
188
+ * states: UNMEASURED is not a result, it is the statement that this run has
189
+ * no suite evidence.
190
+ */
191
+ export function suiteRunVerdict(run: SuiteRun): "PASS" | "FAIL" | "UNMEASURED" {
192
+ if (run.status !== "MEASURED") return "UNMEASURED";
193
+ return run.fail === 0 ? "PASS" : "FAIL";
194
+ }
195
+
196
+ /* ─────────────────────────────────────────────────────────────
197
+ * The failures that happen before there is any output (#621)
198
+ * ───────────────────────────────────────────────────────────── */
199
+
200
+ /**
201
+ * What a caller knows about one attempt to measure the suite.
202
+ *
203
+ * `readSuiteRun` above reads what a runner PRINTED, and that is everything
204
+ * once a runner has run. Two of the three ways a measurement fails never get
205
+ * that far, and both of them print nothing:
206
+ *
207
+ * - the full-suite slot pool refused, so no runner was started at all;
208
+ * - the runner binary could not be executed.
209
+ *
210
+ * Both reach the output parser as an empty string, where they are
211
+ * indistinguishable from each other and from a runner that ran and said
212
+ * nothing. The facts that separate them are not IN the output, so they travel
213
+ * beside it.
214
+ */
215
+ export interface SuiteRunAttempt {
216
+ /**
217
+ * The full-suite slot pool's answer, when one was asked for.
218
+ *
219
+ * Structurally typed rather than imported from `lib/test-suite-lock.ts`: a
220
+ * real `AcquireResult` satisfies it, and this module stays free of `fs` and
221
+ * `child_process` so it can be read anywhere a verdict is read. Omit it
222
+ * when no slot was required — `undefined` means "not asked", which is not
223
+ * the same fact as a refusal.
224
+ */
225
+ slot?: SlotOutcome | null;
226
+ /**
227
+ * What the process launcher reported when it could not start the runner —
228
+ * `spawnSync(...).error`, or anything else that says the launch failed.
229
+ * Absent and null both mean the runner launched.
230
+ */
231
+ launchError?: unknown;
232
+ /** The command that was attempted, as argv or as a string. */
233
+ command?: unknown;
234
+ /** What the runner printed, handed to `readSuiteRun` unchanged. */
235
+ output?: unknown;
236
+ /**
237
+ * The exit status, when there was one.
238
+ *
239
+ * RECORDED, NEVER CONSULTED. It is quoted into an UNMEASURED reason so an
240
+ * operator reading the artefact does not have to go and re-run anything,
241
+ * and no branch below asks what it is. SC-1829 is the measurement that says
242
+ * why: among this module's fixtures, exit 0 and exit 1 each cover both a
243
+ * measured and an unmeasured run, so a reading keyed off it is wrong about
244
+ * one of them.
245
+ */
246
+ exitCode?: unknown;
247
+ }
248
+
249
+ /** The shape of a slot-pool answer this module needs. `AcquireResult` is one. */
250
+ export interface SlotOutcome {
251
+ ok: boolean;
252
+ holders?: ReadonlyArray<{
253
+ sessionId?: string;
254
+ workerId?: string;
255
+ ageSeconds?: number;
256
+ }>;
257
+ degraded?: boolean;
258
+ }
259
+
260
+ function isRecord(v: unknown): v is Record<string, unknown> {
261
+ return typeof v === "object" && v !== null && !Array.isArray(v);
262
+ }
263
+
264
+ /** `bun test`, from argv or from a string. Never empty — an unnamed command
265
+ * is a fact worth printing rather than a hole in the sentence. */
266
+ function describeCommand(command: unknown): string {
267
+ if (Array.isArray(command)) {
268
+ const parts = command.filter((p): p is string => typeof p === "string" && p !== "");
269
+ if (parts.length > 0) return parts.join(" ");
270
+ }
271
+ if (typeof command === "string" && command.trim() !== "") return command.trim();
272
+ return "(the harness did not record which command it tried to run)";
273
+ }
274
+
275
+ /** `ENOENT: Executable not found in $PATH: "…"`. */
276
+ function describeLaunchFailure(error: unknown): string {
277
+ const record = isRecord(error) ? error : null;
278
+ const code = record && typeof record.code === "string" ? record.code : null;
279
+ const message =
280
+ record && typeof record.message === "string" && record.message !== ""
281
+ ? record.message
282
+ : String(error);
283
+ return code ? `${code}: ${message}` : message;
284
+ }
285
+
286
+ /** ` by holder-worker (12s)`, or nothing when the pool named nobody. */
287
+ function describeHolders(holders: SlotOutcome["holders"]): string {
288
+ if (!Array.isArray(holders)) return "";
289
+ const named = holders
290
+ .filter(isRecord)
291
+ .map(h => {
292
+ const who = typeof h.workerId === "string" && h.workerId !== ""
293
+ ? h.workerId
294
+ : typeof h.sessionId === "string" && h.sessionId !== ""
295
+ ? h.sessionId
296
+ : "an unidentified worker";
297
+ const age = typeof h.ageSeconds === "number" && Number.isFinite(h.ageSeconds)
298
+ ? `${h.ageSeconds}s`
299
+ : "age unknown";
300
+ return `${who} (${age})`;
301
+ });
302
+ return named.length === 0 ? "" : ` by ${named.join(", ")}`;
303
+ }
304
+
305
+ /** `. The runner exited 1.`, or nothing when no status was recorded. */
306
+ function describeExit(exitCode: unknown): string {
307
+ return typeof exitCode === "number" ? ` The runner exited ${exitCode}.` : "";
308
+ }
309
+
310
+ /**
311
+ * Read one attempt to measure the suite.
312
+ *
313
+ * FAILS CLOSED, like everything else here, and for the one reason #621 names
314
+ * by hand: `scripts/test-clean-env.ts` exits 2 when the slot pool refuses,
315
+ * and **that exit must record UNMEASURED, never FAIL**. A refused run and a
316
+ * broken runner are not results about the tree; they are the absence of a
317
+ * measurement, and an absence that reads as a failing suite is as wrong as
318
+ * one that reads as a clean one — it just fails in the direction nobody
319
+ * notices, by making the gate cry wolf until its reader stops believing it.
320
+ *
321
+ * The three refusals are ORDERED and each is the only decider for its fact.
322
+ * The output parser is `readSuiteRun`, called once at the end rather than
323
+ * re-implemented, so the missing-summary refusal has exactly one binding and
324
+ * a mutation of it cannot be held up by a copy in here
325
+ * (.claude/rules/checks-must-be-able-to-fail.md, the fourth shape).
326
+ */
327
+ export function readSuiteAttempt(attempt: SuiteRunAttempt): SuiteRun {
328
+ // 1. The pool refused. Checked first because nothing downstream of it ran:
329
+ // there is no launch error and no output, so every later branch would
330
+ // describe this as "the runner printed nothing", which is true and
331
+ // useless — the runner was never asked to print anything.
332
+ //
333
+ // `ok !== true` rather than `ok === false`: a slot answer this module
334
+ // cannot read is not an acquired slot.
335
+ const slot = attempt.slot;
336
+ if (slot !== undefined && slot !== null && slot.ok !== true) {
337
+ return unmeasured(
338
+ "the suite was never run: the full-suite slot pool is exhausted — every slot is held" +
339
+ `${describeHolders(slot.holders)}, so ${describeCommand(attempt.command)} was refused ` +
340
+ "before any runner started. A refused run has no result, and must not be read as a " +
341
+ "failing one (#621)",
342
+ );
343
+ }
344
+
345
+ // 2. The runner could not be executed. Also checked before the output,
346
+ // because an ENOENT launch prints nothing: left to the parser it would
347
+ // report "the test runner produced no output", which names neither the
348
+ // runner nor the fact that there isn't one to name.
349
+ if (attempt.launchError !== undefined && attempt.launchError !== null) {
350
+ return unmeasured(
351
+ `the test runner could not be executed: ${describeCommand(attempt.command)} — ` +
352
+ `${describeLaunchFailure(attempt.launchError)}. No suite ran, so there is no result to ` +
353
+ "read, and the absence of a runner is not the absence of failures (#621)",
354
+ );
355
+ }
356
+
357
+ // 3. Whatever the runner printed, read by the one reader that reads output.
358
+ // The exit status is appended to a refusal rather than consulted for it.
359
+ const run = readSuiteRun(attempt.output);
360
+ if (run.status === "UNMEASURED") {
361
+ return unmeasured(`${run.reason}${describeExit(attempt.exitCode)}`);
362
+ }
363
+ return run;
364
+ }
@@ -0,0 +1,199 @@
1
+ /**
2
+ * test-census.ts — how many tests each file declares, before and after
3
+ *
4
+ * #307 SC-A19. Run `wf_5cdce852-1e2`'s heal loop went from 34 tests to 23
5
+ * across two rounds, with no `skip` and no `todo` recorded. Most of that
6
+ * rewrite was a fair consolidation; three guards had nothing replacing them,
7
+ * and the only thing that noticed was `SECURITY_REVIEW_STALE` — which was
8
+ * looking at something else.
9
+ *
10
+ * A heal agent is told a gate failed and asked to make it pass. Deleting the
11
+ * test is a correct solution to that instruction and an incorrect solution to
12
+ * the problem, and the gate cannot tell the difference afterwards: a suite
13
+ * with the failing test removed is green, and green is what it was asked for.
14
+ *
15
+ * So the count is taken on every gate run and compared to the previous one.
16
+ * Every heal round ends in a gate re-run, so "between gate runs" and "across
17
+ * a heal" are the same window, and the comparison lives where it can be
18
+ * executed by a test rather than in `workflows/ship.js`, which has no
19
+ * filesystem access and could only have asked an agent to do it.
20
+ *
21
+ * This module is the counting and the comparison; `gates/gate-executor.ts`
22
+ * holds the refusal and decides when to bank a new reading.
23
+ *
24
+ * ## What this guard does NOT do, stated rather than implied
25
+ *
26
+ * The banked census lives in the run's `workflow-state.json`, which is a
27
+ * file the heal agent can write. A heal agent that deleted a test AND the
28
+ * census would see `first-reading` on the next round and pass. This guard
29
+ * raises the cost of an accidental deletion, which is the failure mode that
30
+ * actually happened on `wf_5cdce852-1e2`; it is not tamper-evident against a
31
+ * deliberate one, and `writeWorkflowState`'s Zod validation does not make it
32
+ * so, because an absent optional key is valid.
33
+ *
34
+ * Closing that properly means putting the reading somewhere the guarded
35
+ * party does not write — the witness, or an HMAC over it — and is filed
36
+ * separately rather than half-done here. A guard whose limit is written down
37
+ * is a guard somebody can finish; one whose limit is implied is one everybody
38
+ * assumes is complete.
39
+ *
40
+ * ## Why a declaration count and not a run
41
+ *
42
+ * Running the suite twice per heal round costs this project about thirteen
43
+ * minutes a round. A static count costs milliseconds and answers the question
44
+ * actually asked — "did a test stop existing" — rather than "did the number of
45
+ * passing tests go down", which also moves when a heal legitimately fixes a
46
+ * failure.
47
+ *
48
+ * It is deliberately a count of DECLARATIONS, including `.skip` and `.todo`.
49
+ * A heal that converts a failing test to `test.todo` has removed the check
50
+ * just as thoroughly as deleting it, and that conversion is the cheapest way
51
+ * past a count that only looked at live tests.
52
+ */
53
+ import { existsSync, readdirSync, readFileSync, statSync } from "fs";
54
+ import { join } from "path";
55
+
56
+ /**
57
+ * Directories a census never walks into.
58
+ *
59
+ * The walk is the whole project, NOT a fixed list of test directories. A
60
+ * `["test", "gates"]` list is rungate's own layout, and a consumer that keeps
61
+ * its tests beside its sources — `src/foo.test.ts`, which is the commonest
62
+ * JavaScript convention there is — would census to `{}` on every run. An
63
+ * empty census compares clean against an empty census forever, so the guard
64
+ * would be dead for exactly the projects it is supposed to protect, and
65
+ * nothing would say so.
66
+ */
67
+ export const CENSUS_SKIP = new Set([
68
+ "node_modules",
69
+ ".git",
70
+ "dist",
71
+ "build",
72
+ "coverage",
73
+ ".next",
74
+ ".turbo",
75
+ "vendor",
76
+ "test-fixtures",
77
+ "worktrees",
78
+ ]);
79
+
80
+ /**
81
+ * What counts as a test file.
82
+ *
83
+ * The JS/TS family only, stated rather than implied: a consumer whose suite
84
+ * is pytest or `go test` censuses to `{}`, and `censusVerdict` reports that
85
+ * as UNMEASURED rather than as nothing-removed. "We cannot see this
86
+ * project's tests" is a different answer from "no test was removed", and
87
+ * only the first one is honest about a polyglot repo.
88
+ */
89
+ const TEST_FILE = /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs)$/;
90
+
91
+ /**
92
+ * A file this large is not a hand-written suite, and reading it into memory
93
+ * on every gate run is a cost with no reading behind it.
94
+ *
95
+ * Oversized files are skipped, which is safe BECAUSE the cap is stable: a
96
+ * file over it is absent from both censuses and never reads as a deletion.
97
+ * The one case that does produce a false refusal is a file crossing the cap
98
+ * between rounds, and that is the direction to be wrong in — loudly, naming
99
+ * the file, rather than quietly dropping a test from the comparison.
100
+ */
101
+ export const MAX_CENSUS_FILE_BYTES = 2_000_000;
102
+
103
+ /**
104
+ * Declaration forms bun recognises. `test` and `it`, bare or with a modifier.
105
+ *
106
+ * Anchored on a word boundary so `subtest(` and `omit(` do not count, and
107
+ * requiring the open paren so a bare mention in prose does not. The modifier
108
+ * list is explicit rather than `\w+` because `test.each(...)(...)` and a
109
+ * hypothetical `test.anything` should not silently start counting — an
110
+ * unrecognised form is better as a miss we can see than as a count nobody
111
+ * can explain.
112
+ */
113
+ const DECLARATION =
114
+ /(?<![.\w$])(?:test|it)(?:\.(?:skip|todo|only|failing|each|skipIf|todoIf|only))?\s*[(`]/g;
115
+
116
+ /**
117
+ * How many tests a source file declares.
118
+ *
119
+ * Comments are NOT stripped. A commented-out test is a removed test, and
120
+ * stripping would make "comment the block out" a way past the guard. The
121
+ * cost is that prose saying `test(` counts, which inflates a file's number
122
+ * — and inflation is harmless here, because only a DECREASE is refused.
123
+ * The one direction this may be wrong in is toward not refusing, which is
124
+ * the direction a guard over somebody else's edits has to be wrong in.
125
+ */
126
+ export function countTestDeclarations(source: string): number {
127
+ return [...source.matchAll(DECLARATION)].length;
128
+ }
129
+
130
+ /**
131
+ * `{ "test/a.test.ts": 12, … }` for every test file anywhere under `root`.
132
+ *
133
+ * Pass a `skipped` array to be told which files the walk declined to read.
134
+ * Optional so the common caller stays a one-liner, and the gate passes one
135
+ * so it can say so rather than reporting over a comparison that quietly
136
+ * excluded something.
137
+ */
138
+ export function censusOf(root: string, skipped: string[] = []): Record<string, number> {
139
+ const out: Record<string, number> = {};
140
+ const walk = (dir: string, rel: string) => {
141
+ if (!existsSync(dir)) return;
142
+ for (const e of readdirSync(dir, { withFileTypes: true })) {
143
+ const r = rel ? `${rel}/${e.name}` : e.name;
144
+ if (e.isDirectory()) {
145
+ if (CENSUS_SKIP.has(e.name) || e.name.startsWith(".")) continue;
146
+ walk(join(dir, e.name), r);
147
+ } else if (e.isFile() && TEST_FILE.test(e.name)) {
148
+ // `isFile()`, not `!isDirectory()`. A dirent for a symlink answers
149
+ // false to both, so this walk follows no links in either direction:
150
+ // no symlinked-directory loop, and no `readFileSync` on a link to a
151
+ // character device, which has size 0 and never ends.
152
+ const p = join(dir, e.name);
153
+ if (statSync(p).size > MAX_CENSUS_FILE_BYTES) {
154
+ // Named, not dropped. A skip the caller cannot see is a file
155
+ // silently outside the comparison, which is the shape this whole
156
+ // guard exists to refuse — and a reader looking at "no test was
157
+ // removed" deserves to know which files that sentence is not
158
+ // about.
159
+ skipped.push(r);
160
+ continue;
161
+ }
162
+ out[r] = countTestDeclarations(readFileSync(p, "utf-8"));
163
+ }
164
+ }
165
+ };
166
+ walk(root, "");
167
+ return out;
168
+ }
169
+
170
+ /**
171
+ * Files that lost tests between two censuses, named with both numbers.
172
+ *
173
+ * Three rules, and the second is the one a naive implementation misses:
174
+ *
175
+ * - a file whose count DROPPED is a regression
176
+ * - a file that DISAPPEARED is a regression of its whole count — deleting
177
+ * the file is the obvious way past a per-file comparison
178
+ * - a file that APPEARED is not a regression, and neither is a rise
179
+ *
180
+ * An empty census `before` returns nothing. That is correct and worth
181
+ * stating: it means the guard cannot refuse when it never got a reading, and
182
+ * the caller is responsible for noticing that it got one. A comparison that
183
+ * refused on an absent baseline would fire on every first round.
184
+ */
185
+ export function censusRegressions(
186
+ before: Record<string, number>,
187
+ after: Record<string, number>,
188
+ ): string[] {
189
+ const out: string[] = [];
190
+ for (const [file, was] of Object.entries(before).sort()) {
191
+ const now = after[file];
192
+ if (now === undefined) {
193
+ if (was > 0) out.push(`${file}: the file declared ${was} test(s) and is gone`);
194
+ } else if (now < was) {
195
+ out.push(`${file}: ${was} test(s) before, ${now} after`);
196
+ }
197
+ }
198
+ return out;
199
+ }