rungate 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -0,0 +1,432 @@
1
+ /**
2
+ * The other half of #523: is the list of "fields that must be stable" still true?
3
+ *
4
+ * `lib/discovery-stability.ts` compares k recorded runs over
5
+ * `STABLE_DISCOVERY_FIELDS`. That list was not written by taste — it was
6
+ * derived from one criterion, stated on #523 before any code:
7
+ *
8
+ * **A discovery field is required to be stable exactly when something
9
+ * downstream BRANCHES on it.**
10
+ *
11
+ * The same comment named the consequence and did not build it:
12
+ *
13
+ * *"The list is derivable, so it can be a test rather than a document.
14
+ * Something walking the branch points in `workflows/ship.js` and comparing
15
+ * them to the declared stable set would catch a new branch on a field
16
+ * nobody declared stable — which is the failure mode a hand-maintained
17
+ * list has."*
18
+ *
19
+ * This module is that walk. Without it the comparator has a hole that is
20
+ * invisible from inside itself: add `if (discovery.riskTier === 'HIGH')` to
21
+ * the workflow tomorrow and every test in `test/discovery-stability.test.ts`
22
+ * stays green, because every one of them reads the declared list, the schema,
23
+ * or synthetic states — never the workflow. The measurement would go on
24
+ * reporting "8 fields observed, 0 varied" while the field that actually
25
+ * decides the run was not among them. A list that can only be checked against
26
+ * itself is a document.
27
+ *
28
+ * ## The two readings, and what varies between them
29
+ *
30
+ * Reading A is the DECLARATION: `STABLE_DISCOVERY_FIELDS` plus `NOT_ASSERTED`,
31
+ * hand-written in `lib/discovery-stability.ts`.
32
+ *
33
+ * Reading B is the CODE: the conditions in `workflows/ship.js`, parsed, and
34
+ * the discovery properties read inside them.
35
+ *
36
+ * They have different producers and different inputs, which is the whole
37
+ * point — a determinism check that builds the same thing twice with the same
38
+ * code is 0 red against the mutation it exists to catch. Editing either side
39
+ * alone changes the result here: a new branch grows B, deleting an entry
40
+ * shrinks A, and `auditBranchCoverage` reports the disagreement either way.
41
+ *
42
+ * What this asserts is therefore (c): **a refusal when the two readings
43
+ * disagree.** Not a shape, not an order. No model is called and nothing here
44
+ * can red on a model-day.
45
+ *
46
+ * ## Why an empty reading is refused rather than counted as agreement
47
+ *
48
+ * A census that finds nothing agrees with every possible list. If the
49
+ * extractor breaks — the workflow stops parsing, the discovery object is
50
+ * renamed, acorn changes a node name — the honest result is UNMEASURED, not
51
+ * "no undeclared fields". Both the empty-source and the zero-branch-point
52
+ * cases leave through `refuse()`, which is guarded by the single exported
53
+ * `BRANCH_CENSUS_REFUSE` constant so a test can zero it and show each negative
54
+ * case passing only because the refusal fired
55
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
56
+ */
57
+
58
+ import { parse } from "acorn";
59
+
60
+ import { NOT_ASSERTED, STABLE_DISCOVERY_FIELDS, type StableField } from "./discovery-stability";
61
+
62
+ /**
63
+ * The one switch every refusal goes through. Declared on a single line and
64
+ * assigned exactly once, so a mutant copy with `= 0` neutralises ALL refusals
65
+ * and no branch can quietly bypass the mutation by raising directly.
66
+ */
67
+ export const BRANCH_CENSUS_REFUSE = 1;
68
+
69
+ /** Raised by every refusal in this module. */
70
+ export class BranchCensusRefusal extends Error {
71
+ constructor(reason: string) {
72
+ super(`branch census REFUSED: ${reason}`);
73
+ this.name = "BranchCensusRefusal";
74
+ }
75
+ }
76
+
77
+ function refuse(reason: string): never | void {
78
+ if (BRANCH_CENSUS_REFUSE) throw new BranchCensusRefusal(reason);
79
+ }
80
+
81
+ /**
82
+ * The identifiers the workflow holds DISCOVERY's model output in.
83
+ *
84
+ * `discovery` is the object `workflows/ship.js` parses the discovery agent's
85
+ * JSON into; `disc` is the short alias the same file uses in a few helpers.
86
+ * A rename that misses this list drops the census to zero branch points,
87
+ * which is refused rather than reported as agreement.
88
+ */
89
+ export const DISCOVERY_ROOTS = ["discovery", "disc"] as const;
90
+
91
+ /**
92
+ * Where a read of a discovery field decides what the run does.
93
+ *
94
+ * Keyed by acorn node type, valued by the property holding the deciding
95
+ * expression. A read anywhere else in the program — interpolated into a
96
+ * prompt, logged, copied into the state file — is not a branch and is not
97
+ * the subject of #523's criterion.
98
+ */
99
+ export const CONDITION_POSITIONS: Record<string, readonly string[]> = {
100
+ IfStatement: ["test"],
101
+ ConditionalExpression: ["test"],
102
+ SwitchStatement: ["discriminant"],
103
+ SwitchCase: ["test"],
104
+ WhileStatement: ["test"],
105
+ DoWhileStatement: ["test"],
106
+ ForStatement: ["test"],
107
+ /**
108
+ * `a && b` / `a || c` / `a ?? b`: the LEFT operand decides whether the right
109
+ * one is evaluated, so it is a branch wherever it appears. The right operand
110
+ * is not — it is the consequent.
111
+ */
112
+ LogicalExpression: ["left"],
113
+ };
114
+
115
+ export interface BranchPoint {
116
+ /** The discovery property the condition reads, e.g. `ceremonyTier`. */
117
+ field: string;
118
+ /** The root identifier it was read off — one of `DISCOVERY_ROOTS`. */
119
+ root: string;
120
+ /** The acorn construct that makes it a branch, e.g. `IfStatement.test`. */
121
+ construct: string;
122
+ /** 1-based line in the source, so a finding can be opened. */
123
+ line: number;
124
+ /** The condition text, collapsed and clipped. Evidence, not decoration. */
125
+ snippet: string;
126
+ }
127
+
128
+ type AstNode = { type: string; start: number; end: number; [k: string]: unknown };
129
+
130
+ function isNode(value: unknown): value is AstNode {
131
+ return (
132
+ typeof value === "object" &&
133
+ value !== null &&
134
+ typeof (value as AstNode).type === "string" &&
135
+ typeof (value as AstNode).start === "number" &&
136
+ typeof (value as AstNode).end === "number"
137
+ );
138
+ }
139
+
140
+ /**
141
+ * acorn options, matching `lib/reachability.ts`: `workflows/ship.js` is a
142
+ * module body the Workflow runtime wraps in an async function before running,
143
+ * so it legitimately contains top-level `return` and `await`. Both options
144
+ * only widen what PARSES.
145
+ */
146
+ const PARSE_OPTIONS = {
147
+ ecmaVersion: "latest",
148
+ sourceType: "module",
149
+ allowReturnOutsideFunction: true,
150
+ allowAwaitOutsideFunction: true,
151
+ allowHashBang: true,
152
+ } as const;
153
+
154
+ function children(node: AstNode): AstNode[] {
155
+ const out: AstNode[] = [];
156
+ for (const value of Object.values(node)) {
157
+ if (Array.isArray(value)) {
158
+ for (const child of value) if (isNode(child)) out.push(child);
159
+ } else if (isNode(value)) {
160
+ out.push(value);
161
+ }
162
+ }
163
+ return out;
164
+ }
165
+
166
+ function walk(node: AstNode, visit: (n: AstNode) => void): void {
167
+ visit(node);
168
+ for (const child of children(node)) walk(child, visit);
169
+ }
170
+
171
+ /**
172
+ * The discovery property a member expression reads, or null.
173
+ *
174
+ * Only the FIRST property off the root is returned: `discovery.sizing` and
175
+ * `discovery.sizing.predicted` both census as `sizing`, because the criterion
176
+ * is about which model-authored field decides the run, and the declaration
177
+ * side maps its own finer state paths onto these names through `readAs`.
178
+ * Computed access (`discovery[k]`) yields no name and is reported separately.
179
+ */
180
+ function rootedRead(node: AstNode): { root: string; field: string } | null {
181
+ if (node.type !== "MemberExpression") return null;
182
+ const object = node.object as AstNode | undefined;
183
+ const property = node.property as AstNode | undefined;
184
+ if (!isNode(object) || !isNode(property)) return null;
185
+ if (object.type !== "Identifier") return null;
186
+ const root = String((object as unknown as { name: string }).name);
187
+ if (!(DISCOVERY_ROOTS as readonly string[]).includes(root)) return null;
188
+ if (node.computed === true) return null;
189
+ if (property.type !== "Identifier") return null;
190
+ return { root, field: String((property as unknown as { name: string }).name) };
191
+ }
192
+
193
+ function lineOf(source: string, offset: number): number {
194
+ let line = 1;
195
+ for (let i = 0; i < offset && i < source.length; i++) if (source[i] === "\n") line++;
196
+ return line;
197
+ }
198
+
199
+ function clip(text: string, max = 110): string {
200
+ const flat = text.replace(/\s+/g, " ").trim();
201
+ return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
202
+ }
203
+
204
+ /**
205
+ * Every discovery property read inside a condition, one entry per read.
206
+ *
207
+ * REFUSES when the source does not parse, and when the walk finds no branch
208
+ * point at all — see the module header for why an empty census is not
209
+ * agreement.
210
+ */
211
+ export function extractDiscoveryBranchPoints(source: string): BranchPoint[] {
212
+ let program: AstNode;
213
+ try {
214
+ program = parse(source, PARSE_OPTIONS) as unknown as AstNode;
215
+ } catch (err) {
216
+ refuse(`the source does not parse as JavaScript: ${(err as Error).message}`);
217
+ return [];
218
+ }
219
+
220
+ const found: BranchPoint[] = [];
221
+ walk(program, node => {
222
+ const positions = CONDITION_POSITIONS[node.type];
223
+ if (!positions) return;
224
+ for (const position of positions) {
225
+ const condition = node[position];
226
+ if (!isNode(condition)) continue;
227
+ walk(condition, inner => {
228
+ const read = rootedRead(inner);
229
+ if (!read) return;
230
+ found.push({
231
+ field: read.field,
232
+ root: read.root,
233
+ construct: `${node.type}.${position}`,
234
+ line: lineOf(source, inner.start),
235
+ snippet: clip(source.slice(condition.start, condition.end)),
236
+ });
237
+ });
238
+ }
239
+ });
240
+
241
+ if (found.length === 0) {
242
+ refuse(
243
+ `no condition in this source reads any of [${DISCOVERY_ROOTS.join(", ")}]. ` +
244
+ `A census that finds nothing agrees with every possible list, so this is UNMEASURED, ` +
245
+ `not "no undeclared fields".`,
246
+ );
247
+ }
248
+
249
+ return found;
250
+ }
251
+
252
+ /* ────────────────────────── the declaration side ────────────────────────── */
253
+
254
+ /**
255
+ * A declaration entry that names which workflow-source property it covers.
256
+ *
257
+ * `STABLE_DISCOVERY_FIELDS` speaks in STATE paths (`sizing.ceremonyTier`) and
258
+ * the workflow speaks in DISCOVERY-object properties (`discovery.ceremonyTier`)
259
+ * — `workflows/ship.js` flattens one into the other when it writes the state
260
+ * file. `readAs` is that mapping, declared rather than guessed: a path with no
261
+ * `readAs` covers nothing, so adding an entry does not silently excuse a
262
+ * branch.
263
+ */
264
+ export interface SourceMapped {
265
+ path: string;
266
+ readAs?: readonly string[];
267
+ }
268
+
269
+ /** The discovery properties a declaration list claims to cover. */
270
+ export function coveredFields(entries: readonly SourceMapped[]): Set<string> {
271
+ const out = new Set<string>();
272
+ for (const entry of entries) for (const name of entry.readAs ?? []) out.add(name);
273
+ return out;
274
+ }
275
+
276
+ /**
277
+ * Branched on, and NOT MEASURABLE — the third register, and the one this
278
+ * census produced.
279
+ *
280
+ * `filesToModify` and `scopeOut` both meet #523's criterion outright: the run
281
+ * takes a different path on each of them. Neither is in
282
+ * `WorkflowStateSchema`. They exist inside a run and are gone when it ends, so
283
+ * no comparison over recorded run states can read them in either direction —
284
+ * a declared path for one would resolve to `undefined` in every run, which is
285
+ * perfectly stable and completely uninformative.
286
+ *
287
+ * They are therefore recorded as **UNMEASURED, not as excluded**. The
288
+ * distinction is the point: `NOT_ASSERTED` means "we looked and decided not
289
+ * to", this means "we could not look". A reading nobody could take is not a
290
+ * reading that passed.
291
+ *
292
+ * The excuse is itself checked. `test/discovery-branch-coverage.test.ts`
293
+ * asserts every entry here is genuinely ABSENT from the real
294
+ * `WorkflowStateSchema` — so the day somebody persists `filesToModify`, this
295
+ * entry becomes false and reddens, forcing the field into
296
+ * `STABLE_DISCOVERY_FIELDS` where it now belongs. An excuse that cannot go
297
+ * stale is a comment.
298
+ */
299
+ export const BRANCHED_BUT_UNPERSISTED: { field: string; reason: string }[] = [
300
+ {
301
+ field: "filesToModify",
302
+ reason:
303
+ "`workflows/ship.js:3841` branches the M-size decomposition on `(discovery.filesToModify || []).length >= 3`, and `:2964` feeds its contents to `scopeContradiction`, which REFUSES the run. Both are decisions, so the criterion is met — but `WorkflowStateSchema` has no `filesToModify`, so a k-run series cannot observe it. Measuring this needs the field persisted first.",
304
+ },
305
+ {
306
+ field: "scopeOut",
307
+ reason:
308
+ "`workflows/ship.js:2961` passes it to `deniedFiles`, whose result decides an early return and then a refusal; `:3837` recomputes the denied list that bounds the sub-issues. Same position as `filesToModify` — a real branch on model-authored content, absent from `WorkflowStateSchema`, therefore unobservable rather than stable.",
309
+ },
310
+ ];
311
+
312
+ export interface CoverageFinding {
313
+ field: string;
314
+ points: BranchPoint[];
315
+ }
316
+
317
+ export interface CoverageReport {
318
+ /** Every branch point the walk found, in source order. */
319
+ points: BranchPoint[];
320
+ /** Distinct discovery properties branched on. */
321
+ branchedFields: string[];
322
+ /**
323
+ * Branched on, and classified by neither list. THE FINDING: the run takes a
324
+ * different path on this field and nobody has said whether it is allowed to
325
+ * vary.
326
+ */
327
+ undeclared: CoverageFinding[];
328
+ /**
329
+ * Declared stable with a `branchedOnBy` justification, but no condition in
330
+ * the workflow reads it any more. The justification has gone stale — the
331
+ * other direction of the same rot.
332
+ */
333
+ staleJustification: string[];
334
+ /** Branched on and deliberately excluded, with the reason already on record. */
335
+ excluded: string[];
336
+ /**
337
+ * Branched on, meets the criterion, and the state file does not carry it —
338
+ * so no series can measure it. UNMEASURED, never counted as stable.
339
+ */
340
+ unmeasurable: string[];
341
+ }
342
+
343
+ /**
344
+ * Compare the two readings and report every disagreement, in both directions.
345
+ *
346
+ * REFUSES when the declaration covers nothing: a `readAs`-less list excuses
347
+ * no branch and would report every field in the workflow as a finding, which
348
+ * reads as a catastrophic result rather than as a broken instrument.
349
+ */
350
+ export function auditBranchCoverage(
351
+ points: BranchPoint[],
352
+ stable: readonly SourceMapped[] = STABLE_DISCOVERY_FIELDS as readonly StableField[] as readonly SourceMapped[],
353
+ notAsserted: readonly SourceMapped[] = NOT_ASSERTED as readonly SourceMapped[],
354
+ unpersisted: readonly { field: string }[] = BRANCHED_BUT_UNPERSISTED,
355
+ ): CoverageReport {
356
+ const stableFields = coveredFields(stable);
357
+ const excludedFields = coveredFields(notAsserted);
358
+ const unpersistedFields = new Set(unpersisted.map(u => u.field));
359
+ if (stableFields.size === 0 && excludedFields.size === 0) {
360
+ refuse(
361
+ "neither declaration list maps to a single workflow property, so every branch would " +
362
+ "report as undeclared. That is a broken mapping, not a finding.",
363
+ );
364
+ }
365
+
366
+ const byField = new Map<string, BranchPoint[]>();
367
+ for (const point of points) {
368
+ const list = byField.get(point.field);
369
+ if (list) list.push(point);
370
+ else byField.set(point.field, [point]);
371
+ }
372
+
373
+ const branchedFields = [...byField.keys()].sort();
374
+ const undeclared: CoverageFinding[] = [];
375
+ const excluded: string[] = [];
376
+ const unmeasurable: string[] = [];
377
+ for (const field of branchedFields) {
378
+ if (stableFields.has(field)) continue;
379
+ if (excludedFields.has(field)) {
380
+ excluded.push(field);
381
+ continue;
382
+ }
383
+ if (unpersistedFields.has(field)) {
384
+ unmeasurable.push(field);
385
+ continue;
386
+ }
387
+ undeclared.push({ field, points: byField.get(field) ?? [] });
388
+ }
389
+
390
+ const staleJustification = [...stableFields].filter(f => !byField.has(f)).sort();
391
+
392
+ return { points, branchedFields, undeclared, staleJustification, excluded, unmeasurable };
393
+ }
394
+
395
+ /** The finding, as text. Never a verdict a gate silently consumes. */
396
+ export function formatCoverageReport(report: CoverageReport): string {
397
+ const lines = [
398
+ `Discovery branch-point census (#523)`,
399
+ ``,
400
+ `${report.points.length} branch read(s) over ${report.branchedFields.length} field(s): ${report.branchedFields.join(", ")}`,
401
+ ``,
402
+ ];
403
+ if (report.undeclared.length === 0) {
404
+ lines.push(`No undeclared branched field. Every field a condition reads is classified.`);
405
+ } else {
406
+ lines.push(`UNDECLARED — branched on, classified by neither list:`);
407
+ for (const finding of report.undeclared) {
408
+ lines.push(` ${finding.field}`);
409
+ for (const point of finding.points) {
410
+ lines.push(` line ${point.line} [${point.construct}] ${point.snippet}`);
411
+ }
412
+ }
413
+ }
414
+ if (report.staleJustification.length > 0) {
415
+ lines.push(
416
+ ``,
417
+ `STALE — declared stable, but no condition reads them any more: ${report.staleJustification.join(", ")}`,
418
+ );
419
+ }
420
+ if (report.unmeasurable.length > 0) {
421
+ lines.push(
422
+ ``,
423
+ `UNMEASURED — branched on, but the state file does not carry them, so no series ` +
424
+ `can read them: ${report.unmeasurable.join(", ")}. This is not a clean result for ` +
425
+ `those fields; it is the absence of one.`,
426
+ );
427
+ }
428
+ if (report.excluded.length > 0) {
429
+ lines.push(``, `Branched and deliberately not asserted: ${report.excluded.join(", ")}`);
430
+ }
431
+ return lines.join("\n");
432
+ }