rungate 0.8.13 → 0.8.14

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 (40) hide show
  1. package/README.md +82 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  4. package/lib/ai-review-rounds.ts +99 -0
  5. package/lib/ai-review-suppression.ts +200 -21
  6. package/lib/bash-write-guard.ts +50 -5
  7. package/lib/board-flow.ts +235 -0
  8. package/lib/board-lane-health.ts +381 -0
  9. package/lib/board-mirror.ts +53 -35
  10. package/lib/board-ready-fanout.ts +56 -13
  11. package/lib/board-ready-rule.ts +545 -0
  12. package/lib/board-throughput.ts +136 -0
  13. package/lib/board-walkthrough.ts +240 -0
  14. package/lib/body-evidence.ts +203 -0
  15. package/lib/branch-protection.ts +399 -9
  16. package/lib/conformity.ts +95 -2
  17. package/lib/filing-compliance.ts +367 -0
  18. package/lib/finding-arbiter.ts +79 -5
  19. package/lib/generators/agents-md.ts +149 -0
  20. package/lib/github.ts +79 -0
  21. package/lib/graphql-cursor.ts +80 -0
  22. package/lib/issue-create-override.ts +415 -3
  23. package/lib/issue-decomposition.ts +33 -3
  24. package/lib/issue-file-overlap.ts +340 -0
  25. package/lib/issue-filing-gate.ts +173 -8
  26. package/lib/issue-repair.ts +13 -9
  27. package/lib/issue-shape.ts +196 -0
  28. package/lib/scaffold/ai-review-findings.ts +9 -1
  29. package/lib/scaffold/ai-review-step.ts +35 -1
  30. package/lib/source-census.ts +108 -0
  31. package/lib/spec-deps.ts +34 -11
  32. package/lib/spec-placement.ts +108 -0
  33. package/lib/stage-ladder.ts +28 -3
  34. package/lib/work-status.ts +423 -0
  35. package/package.json +1 -1
  36. package/scripts/ai-review-findings.ts +8 -13
  37. package/scripts/ai-review-threads.ts +16 -17
  38. package/scripts/board-mirror.ts +221 -8
  39. package/scripts/generate-code-map.ts +1 -1
  40. package/scripts/plan-spec.ts +79 -1
@@ -38,11 +38,18 @@ import { existsSync, readFileSync } from "fs";
38
38
  import { isAbsolute, join } from "path";
39
39
  import { parseArgs } from "util";
40
40
  import { createGitHubClient } from "../lib/github";
41
+ import {
42
+ heldReason,
43
+ readyCap,
44
+ readyOccupancy,
45
+ selectReady,
46
+ type ReadyOccupancy,
47
+ } from "../lib/board-ready-rule";
48
+ import { measureClosedIssues } from "../lib/board-throughput";
41
49
  import {
42
50
  criterionIdsIn,
43
51
  isReady,
44
52
  mirrorRows,
45
- openFrontier,
46
53
  phaseOf,
47
54
  specCriteriaIn,
48
55
  } from "../lib/board-mirror";
@@ -54,6 +61,135 @@ import {
54
61
  */
55
62
  export const REFUSAL_EXIT = 1;
56
63
 
64
+ /**
65
+ * `owner/name`, or `null` for anything that is not exactly that.
66
+ *
67
+ * **`split("/")[1]` is `undefined` for `--repo rungate`, and a `!` only
68
+ * silences the type checker.** That `undefined` reached
69
+ * `measureClosedIssues` and surfaced as an opaque GraphQL error far from
70
+ * the typo that caused it — ai-review on #1795.
71
+ *
72
+ * Exported because the first version of this guard was inline in
73
+ * `main()`, where no case could reach it: the mutation battery removed
74
+ * the whole condition and read ZERO. A guard no test can observe is a
75
+ * line in a file (`.claude/rules/checks-must-be-able-to-fail.md`).
76
+ */
77
+ export function parseRepo(value: string): { owner: string; name: string } | null {
78
+ const parts = value.split("/");
79
+ if (parts.length !== 2) return null;
80
+ const [owner, name] = parts;
81
+ if (!owner || !name) return null;
82
+ return { owner, name };
83
+ }
84
+
85
+ /**
86
+ * Split what this command MAY write into what the cap lets through.
87
+ *
88
+ * **The cap applies here too, and from the same function the workflow
89
+ * uses.** This command is the hand-run second CALLER of Ready's rule —
90
+ * not a second rule, which is the distinction that matters: it and
91
+ * `board-ready.yml` both read `lib/board-ready-rule.ts`, so they cannot
92
+ * size the lane differently. Before this, the workflow filled to a
93
+ * derived depth and one hand-run of this command refilled the lane to
94
+ * whatever happened to be eligible.
95
+ *
96
+ * **A demotion to Backlog is never capped**, and that is the half a
97
+ * naive implementation gets wrong. The cap bounds what may ENTER Ready;
98
+ * applying it to departures would pin a claimed or newly-blocked card in
99
+ * the lane for as long as the lane stayed full — the cap would start
100
+ * preserving exactly the staleness it exists to prevent.
101
+ *
102
+ * Exported so a case can hold it. Inline, the only way to observe it was
103
+ * to run the command against a live board.
104
+ */
105
+ /**
106
+ * The items this command may move, and how many of them hold Ready.
107
+ *
108
+ * **One array, read twice — not two filters that happen to agree.**
109
+ * `occupied` used to be counted over EVERY board item while the
110
+ * transitions were computed over the open ones, so anything the command
111
+ * can never move counted against the cap forever and silently starved
112
+ * promotions. A closed issue whose Status was never taken off Ready is
113
+ * the case ai-review named; a DRAFT board item, which has no state at
114
+ * all, is the one that was live on the board when this was written.
115
+ *
116
+ * Returning both from one pass is the point. Re-spelling
117
+ * `state === "OPEN"` beside the count would be two deciders answering one
118
+ * question, which no behavioural test can tell apart
119
+ * (`.claude/rules/checks-must-be-able-to-fail.md`) — and that is exactly
120
+ * how the two came to disagree. ai-review round 3 of #1795.
121
+ */
122
+ export function readyPopulation<T extends { state: string; status: string }>(
123
+ items: readonly T[],
124
+ ): { writable: T[]; occupied: number } {
125
+ const writable = items.filter(i => i.state === "OPEN");
126
+ return { writable, occupied: writable.filter(i => i.status === READY).length };
127
+ }
128
+
129
+ export function splitReadyChanges<
130
+ T extends {
131
+ item: { number: number; phase: number | null; labels: readonly string[]; status: string };
132
+ to: string;
133
+ },
134
+ >(
135
+ eligible: readonly T[],
136
+ cap: number | null,
137
+ occupied: number,
138
+ ): {
139
+ readyWritable: T[];
140
+ heldByCap: T[];
141
+ selection: ReturnType<typeof selectReady>;
142
+ /** The reading the caller must restate, never re-derive (#1852). */
143
+ occ: ReadyOccupancy;
144
+ } {
145
+ const promotions = eligible.filter(c => c.to === READY);
146
+ const demotions = eligible.filter(c => c.to !== READY);
147
+ // **A demotion in THIS batch frees a slot in this batch.** `occupied`
148
+ // is the pre-write count, so handing it to `selectReady` unchanged
149
+ // under-promotes by however many cards are leaving Ready in the same
150
+ // run — a frontier move that demotes three and promotes three would
151
+ // promote none. ai-review round 2 of #1795.
152
+ //
153
+ // Only demotions FROM Ready free anything. This command may also
154
+ // overwrite a card with no Status at all, and counting those would
155
+ // over-promote past the cap — the opposite error, reached by the
156
+ // obvious fix.
157
+ const freed = demotions.filter(c => c.item.status === READY).length;
158
+ // **This command's lane view is OPEN ISSUES ONLY, by design, so its two
159
+ // occupancy counts are one number** (#1852). `readyPopulation` filters to
160
+ // `state === "OPEN"` before counting, deliberately: a closed issue left on
161
+ // Ready counted against the cap forever and starved promotions
162
+ // (ai-review round 3 of #1795), and a draft has no state at all and is
163
+ // dropped before it reaches here.
164
+ //
165
+ // So WEDGED is unreachable from this caller, and that is HONEST rather
166
+ // than convenient: a lane held full by cards this command cannot see is a
167
+ // lane it also cannot clear, and `scripts/board-ready.ts` reads the whole
168
+ // column and reports it. What this caller must not do is invent a second
169
+ // free-slot calculation, which is the defect #1852 closed.
170
+ const after = Math.max(0, occupied - freed);
171
+ const occ = readyOccupancy(after, after, cap);
172
+ const selection = selectReady(
173
+ promotions.map(c => ({ number: c.item.number, phase: c.item.phase, labels: c.item.labels })),
174
+ occ,
175
+ );
176
+ // **Written in the order `selectReady` chose, not in board order.**
177
+ // A `filter` over `promotions` re-derives the right MEMBERSHIP in the
178
+ // wrong SEQUENCE, so the log and the write order stop matching the
179
+ // phase-then-age ranking the lane is supposed to express — and a run
180
+ // that dies part-way through would have written an arbitrary subset
181
+ // rather than the highest-ranked one. ai-review round 2 of #1795.
182
+ const byNumber = new Map(promotions.map(c => [c.item.number, c]));
183
+ const chosen = selection.promote.map(p => byNumber.get(p.number)!).filter(Boolean);
184
+ const chosenNumbers = new Set(chosen.map(c => c.item.number));
185
+ return {
186
+ readyWritable: [...demotions, ...chosen],
187
+ heldByCap: promotions.filter(c => !chosenNumbers.has(c.item.number)),
188
+ selection,
189
+ occ,
190
+ };
191
+ }
192
+
57
193
  const USAGE = `rungate board-mirror --project <node-id> [--spec <spec.md>] [--field <name>] [--write] [--ready] [--json]
58
194
 
59
195
  --project the ProjectV2 node id, e.g. PVT_kwHO…
@@ -65,6 +201,10 @@ const USAGE = `rungate board-mirror --project <node-id> [--spec <spec.md>] [--fi
65
201
  already exist on the project — this does not create one, because
66
202
  a typo would silently add a column nobody looks at.
67
203
  --write write the field. Without it nothing is mutated.
204
+ --repo owner/name — required with --ready, which derives Ready's depth
205
+ from how much that repository delivered. A board can span
206
+ repositories and carries no single answer, so there is no
207
+ default: without it the depth is UNMEASURED and nothing moves.
68
208
  --ready also move Status between Backlog and Ready from the OPEN
69
209
  blocked-by count. Implies nothing unless --write is given too.
70
210
  --json the whole reading.`;
@@ -87,6 +227,8 @@ interface Item {
87
227
  criteriaCell: string;
88
228
  milestone: string;
89
229
  phase: number | null;
230
+ /** Ordering's second source when no milestone places the issue (#1853). */
231
+ labels: readonly string[];
90
232
  }
91
233
 
92
234
  const ITEMS_QUERY = `query($project: ID!, $field: String!, $after: String) {
@@ -105,6 +247,7 @@ const ITEMS_QUERY = `query($project: ID!, $field: String!, $after: String) {
105
247
  ... on Issue {
106
248
  number title body state
107
249
  milestone { title }
250
+ labels(first: 20) { pageInfo { hasNextPage } nodes { name } }
108
251
  assignees { totalCount }
109
252
  issueDependenciesSummary { blockedBy totalBlockedBy }
110
253
  }
@@ -128,6 +271,7 @@ export async function main(argv: string[]): Promise<number> {
128
271
  ready: { type: "boolean", default: false },
129
272
  json: { type: "boolean", default: false },
130
273
  "project-root": { type: "string" },
274
+ repo: { type: "string" },
131
275
  },
132
276
  allowPositionals: false,
133
277
  });
@@ -136,6 +280,15 @@ export async function main(argv: string[]): Promise<number> {
136
280
  return REFUSAL_EXIT;
137
281
  }
138
282
  const { values } = parsed;
283
+ // **`split("/")[1]` is `undefined` for `--repo rungate`, and the `!`
284
+ // only silences the type checker.** That `undefined` reaches
285
+ // `measureClosedIssues` and surfaces as an opaque GraphQL error far
286
+ // from the typo that caused it. Validated here, where the message can
287
+ // name the flag. ai-review on #1795.
288
+ if (values.repo !== undefined && parseRepo(values.repo) === null) {
289
+ console.error(`board-mirror: --repo must be owner/name, got "${values.repo}"\n\n${USAGE}`);
290
+ return REFUSAL_EXIT;
291
+ }
139
292
  if (!values.project) {
140
293
  console.error(`board-mirror: --project is required\n\n${USAGE}`);
141
294
  return REFUSAL_EXIT;
@@ -214,6 +367,21 @@ export async function main(argv: string[]): Promise<number> {
214
367
  fieldId = node.field.id;
215
368
  for (const n of node.items.nodes) {
216
369
  if (!n.content?.number) continue; // a draft item has no issue
370
+ // **A truncated label list is UNMEASURED, not a short one** (#1853).
371
+ // Ordering reads a label when no milestone places the issue, so a
372
+ // ranked label sitting on page two makes this writer promote the
373
+ // issue as if nothing placed it — and that is indistinguishable from
374
+ // an issue nothing places. `scripts/board-ready.ts` refuses the same
375
+ // state; this file silently did not, which is the one-site-fixed
376
+ // shape ai-review round 1 of #1855 named.
377
+ if (n.content.labels?.pageInfo?.hasNextPage) {
378
+ console.error(
379
+ `board-mirror: #${n.content.number} carries more than 20 labels, so the label that ` +
380
+ `ranks it may be unread and its position in Ready would be wrong. UNMEASURED, ` +
381
+ `nothing written.`,
382
+ );
383
+ return REFUSAL_EXIT;
384
+ }
217
385
  items.push({
218
386
  itemId: n.id,
219
387
  number: n.content.number,
@@ -227,6 +395,12 @@ export async function main(argv: string[]): Promise<number> {
227
395
  criteriaCell: n.fieldValueByName?.text ?? "",
228
396
  milestone: n.content.milestone?.title ?? "",
229
397
  phase: phaseOf(n.content.milestone?.title),
398
+ // Ordering's second source (#1853). This writer promotes too, so a
399
+ // mirror run that ranked everything milestone-less as UNPLACED
400
+ // would order by age exactly where the fan-out no longer does.
401
+ labels: (n.content.labels?.nodes ?? [])
402
+ .map((l: any) => l?.name)
403
+ .filter((x: any) => typeof x === "string"),
230
404
  });
231
405
  }
232
406
  if (!node.items.pageInfo.hasNextPage) break;
@@ -240,10 +414,9 @@ export async function main(argv: string[]): Promise<number> {
240
414
  .filter(i => (byNumber.get(i.number)?.text ?? "") !== i.criteriaCell)
241
415
  .map(i => ({ item: i, to: byNumber.get(i.number)!.text }));
242
416
 
243
- const frontier = openFrontier(items);
244
- const readyChanges = items
245
- .filter(i => i.state === "OPEN")
246
- .map(i => ({ item: i, to: isReady(i, frontier) ? READY : BACKLOG }))
417
+ const { writable, occupied } = readyPopulation(items);
418
+ const readyChanges = writable
419
+ .map(i => ({ item: i, to: isReady(i) ? READY : BACKLOG }))
247
420
  .filter(c => c.to !== c.item.status);
248
421
 
249
422
  // An assignee is a person saying "mine". Where their card sits is then
@@ -253,9 +426,27 @@ export async function main(argv: string[]): Promise<number> {
253
426
  // may have claimed the issue.
254
427
  const mayWrite = (c: { item: Item }) =>
255
428
  MAY_OVERWRITE.includes(c.item.status) && c.item.assignees === 0;
256
- const readyWritable = readyChanges.filter(mayWrite);
429
+ const eligible = readyChanges.filter(mayWrite);
257
430
  const readySkipped = readyChanges.filter(c => !mayWrite(c));
258
431
 
432
+ // A board can span repositories, so there is no repository to default
433
+ // to and no honest depth without one. UNMEASURED, and nothing is
434
+ // promoted on a null cap.
435
+ // Re-parsed rather than carried, so there is one spelling of what a
436
+ // repository argument is. `main` has already refused anything this
437
+ // returns null for.
438
+ const repo = values.repo === undefined ? null : parseRepo(values.repo);
439
+ // **Gated on `--ready`, not merely on `--repo`.** This pages every
440
+ // closed issue in the repository, and a plain Criteria sync that
441
+ // happens to pass `--repo` has no use for a depth. ai-review round 2
442
+ // of #1795.
443
+ const closedReadings =
444
+ values.ready && repo
445
+ ? await measureClosedIssues((q, v) => client.graphql(q, v), repo.owner, repo.name)
446
+ : null;
447
+ const cap = closedReadings === null ? null : readyCap(closedReadings.throughput);
448
+ const { readyWritable, heldByCap, selection, occ } = splitReadyChanges(eligible, cap, occupied);
449
+
259
450
  if (values.json) {
260
451
  console.log(
261
452
  JSON.stringify(
@@ -267,6 +458,13 @@ export async function main(argv: string[]): Promise<number> {
267
458
  fieldChanges: fieldChanges.map(c => ({ number: c.item.number, from: c.item.criteriaCell, to: c.to })),
268
459
  readyWritable: readyWritable.map(c => ({ number: c.item.number, from: c.item.status, to: c.to })),
269
460
  readySkipped: readySkipped.map(c => ({ number: c.item.number, status: c.item.status })),
461
+ // The depth and what it held back, so a consumer reading this
462
+ // JSON can tell "nothing was eligible" from "the lane is full"
463
+ // from "the depth could not be read". Three different facts
464
+ // that all used to come out as an empty `readyWritable`.
465
+ readyCap: cap,
466
+ readyOccupied: occupied,
467
+ readyHeldByCap: heldByCap.map(c => c.item.number),
270
468
  wrote: values.write,
271
469
  },
272
470
  null,
@@ -285,9 +483,24 @@ export async function main(argv: string[]): Promise<number> {
285
483
  if (fieldChanges.length === 0) console.log(` every cell already agrees with its issue body`);
286
484
  if (values.ready) {
287
485
  console.log(
288
- `\n Ready lane — the frontier is ` +
289
- (frontier === null ? `nowhere: no open issue sits in a phase` : `Phase ${frontier}`),
486
+ `\n Ready lane — eligibility is unblocked and unclaimed; phase orders, it does not gate`,
290
487
  );
488
+ console.log(` depth: ${cap ?? "UNMEASURED"}. ${selection.why}`);
489
+ if (cap === null && !values.repo) {
490
+ console.log(
491
+ ` pass --repo owner/name to derive the depth; a board can span repositories ` +
492
+ `so there is nothing to default to, and nothing is promoted without it`,
493
+ );
494
+ }
495
+ for (const c of heldByCap) {
496
+ // `heldReason(cap)`, never a literal. The literal was the exact
497
+ // defect ai-review found in `scripts/board-ready.ts` on #1794 —
498
+ // an unmeasured depth reported as a full lane — and I wrote it
499
+ // fresh here one pull request later, with the fix exported and
500
+ // in the tree. `test/board-ready-rule.test.ts` now refuses the
501
+ // string anywhere but its own binding.
502
+ console.log(` #${c.item.number} eligible but held: ${heldReason(occ)}`);
503
+ }
291
504
  for (const c of readyWritable) {
292
505
  console.log(` #${c.item.number} ${c.item.status || "(none)"} -> ${c.to} (${c.item.milestone || "no milestone"}; ${c.item.blockedByOpen} open of ${c.item.blockedByTotal} blockers, ${c.item.assignees} assignee(s))`);
293
506
  }
@@ -263,7 +263,7 @@ generator: rungate/scripts/generate-code-map.ts
263
263
 
264
264
  # Code Map — ${pkg.name}
265
265
 
266
- Auto-generated architecture snapshot. Re-run \`bun generate-code-map.ts ${projectPath}\` to refresh.
266
+ Auto-generated architecture snapshot. Re-run \`bun generate-code-map.ts .\` to refresh.
267
267
  Regenerate when src/ has commits since scanned-at-sha.
268
268
 
269
269
  ${FRESHNESS_NOTICE}`);
@@ -49,11 +49,34 @@ import {
49
49
  import {
50
50
  milestoneBody,
51
51
  milestonePlan,
52
+ placementCoverage,
52
53
  placementReading,
53
54
  uncoveredByMilestone,
54
55
  } from "../lib/spec-placement";
56
+ import { specCriteriaIn } from "../lib/board-mirror";
55
57
  import { readMilestonePrefix } from "../lib/live-issues";
56
58
 
59
+ /**
60
+ * Which files are specs, asked of the one sweep that already decides it.
61
+ *
62
+ * `specCriteriaIn` excludes `NOT_A_SPEC`, locates nested specs, and refuses
63
+ * rather than returning a short list. Walking `specs/` here instead would be
64
+ * a second decider for the same question, and no behavioural test of either
65
+ * could see the two disagree.
66
+ */
67
+ function listSpecPaths(root: string): {
68
+ reading: "MEASURED" | "UNMEASURED";
69
+ unmeasuredReasons: string[];
70
+ paths: string[];
71
+ } {
72
+ const sweep = specCriteriaIn(root);
73
+ return {
74
+ reading: sweep.reading,
75
+ unmeasuredReasons: [...sweep.unmeasuredReasons],
76
+ paths: sweep.specs.map(s => s.path),
77
+ };
78
+ }
79
+
57
80
  /**
58
81
  * THE one non-zero exit. One site, so `test/plan-spec.test.ts` can build a
59
82
  * mutant with it set to `0` and prove each refusal is what the case observed
@@ -128,13 +151,55 @@ const LIVE_GITHUB: PlanSpecGitHub = {
128
151
  };
129
152
 
130
153
  const USAGE = `rungate plan-spec <spec.md> --repo <owner/name> --prefix <name> [--write] [--json]
154
+ rungate plan-spec --coverage [--project-root <dir>] [--json]
131
155
 
132
156
  --repo owner/name. Defaults to $GITHUB_REPOSITORY.
133
157
  --prefix the milestone name prefix, e.g. "Convergence" gives
134
158
  "Convergence Phase 1 — stop the repeats". Required: deriving it
135
159
  from the filename would call the live milestones something else.
136
160
  --write create and rename milestones. Without it, nothing is mutated.
137
- --json the whole reading, for something other than a person.`;
161
+ --json the whole reading, for something other than a person.
162
+ --coverage every spec in the tree and whether its criteria are placed,
163
+ instead of one spec. Takes no spec, reaches no network and
164
+ writes nothing. A spec with no placement table is named as
165
+ UNPLANNED rather than contributing nothing (SC-2611).`;
166
+
167
+ /**
168
+ * The repo-wide reading, printed. Reaches no network and writes nothing.
169
+ *
170
+ * It exits non-zero on UNMEASURED and on nothing else. An unplanned spec is
171
+ * a FINDING, not a refusal: 25 of 26 were unplanned when this was written, so
172
+ * a non-zero exit would be a gate nobody could ever get green and everybody
173
+ * would learn to pass `|| true`.
174
+ */
175
+ function reportCoverage(root: string, asJson: boolean): number {
176
+ const r = placementCoverage(root, listSpecPaths, (base, path) =>
177
+ readFileSync(join(base, path), "utf-8"),
178
+ );
179
+ if (asJson) {
180
+ console.log(JSON.stringify(r, null, 2));
181
+ return r.reading === "UNMEASURED" ? REFUSAL_EXIT : 0;
182
+ }
183
+ if (r.reading === "UNMEASURED") {
184
+ return refuse(false, `UNMEASURED — ${r.unmeasuredReasons.join("; ")}`);
185
+ }
186
+ console.log(`placement coverage — ${r.specs.length} spec(s) under ${join(root, "specs")}\n`);
187
+ console.log(` PLANNED ${r.planned.length}`);
188
+ console.log(` UNPLANNED ${r.unplanned.length}`);
189
+ console.log(` NO_CRITERIA ${r.noCriteria.length}\n`);
190
+ // `r.unplanned`, never a second `state === "UNPLANNED"` filter here. The
191
+ // roll-up already decides which specs are unplanned, and a filter of my
192
+ // own is a second decider answering the same question: found by the
193
+ // mutation battery, which blanked `unplanned` and left these rows printing
194
+ // (`.claude/rules/checks-must-be-able-to-fail.md`, *two deciders agree*).
195
+ for (const path of r.unplanned) {
196
+ const s = r.specs.find(s => s.path === path)!;
197
+ console.log(` UNPLANNED ${s.path} — ${s.criteria} criteria, ${s.placed} placed`);
198
+ for (const why of s.reasons) console.log(` ${why}`);
199
+ }
200
+ if (r.unplanned.length === 0) console.log(" every spec stating criteria places them.");
201
+ return 0;
202
+ }
138
203
 
139
204
  export async function main(argv: string[], gh: PlanSpecGitHub = LIVE_GITHUB): Promise<number> {
140
205
  let parsed;
@@ -146,6 +211,7 @@ export async function main(argv: string[], gh: PlanSpecGitHub = LIVE_GITHUB): Pr
146
211
  prefix: { type: "string" },
147
212
  write: { type: "boolean", default: false },
148
213
  json: { type: "boolean", default: false },
214
+ coverage: { type: "boolean", default: false },
149
215
  "project-root": { type: "string" },
150
216
  },
151
217
  allowPositionals: true,
@@ -159,6 +225,18 @@ export async function main(argv: string[], gh: PlanSpecGitHub = LIVE_GITHUB): Pr
159
225
  }
160
226
 
161
227
  const { values, positionals } = parsed;
228
+ // Before the spec argument is demanded: --coverage is the whole-tree
229
+ // reading and there is no one spec it could be given.
230
+ if (values.coverage) {
231
+ if (positionals.length > 0) {
232
+ return refuse(
233
+ values.json,
234
+ `--coverage reads every spec, so it takes none; got ${JSON.stringify(positionals[0])}`,
235
+ true,
236
+ );
237
+ }
238
+ return reportCoverage(values["project-root"] ?? process.cwd(), values.json);
239
+ }
162
240
  const specArg = positionals[0];
163
241
  if (!specArg) {
164
242
  return refuse(values.json, `no spec given`, true);