rungate 0.8.26 → 0.8.28

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.
@@ -36,9 +36,11 @@ import {
36
36
  aiReviewThreadsExitCode,
37
37
  postReviewThreads,
38
38
  prIsForkReading,
39
+ refusalFrom,
39
40
  threadsDetailLines,
40
41
  threadsLandedPhrase,
41
42
  type AiReviewThreadPoster,
43
+ type AiReviewPullCommenter,
42
44
  type AiReviewThreadResponse,
43
45
  } from "../lib/ai-review-threads";
44
46
  import {
@@ -171,12 +173,8 @@ const post: AiReviewThreadPoster = async request => {
171
173
  });
172
174
  return { ok: true };
173
175
  } catch (e) {
174
- const err = e as { status?: number; message?: string };
175
- return {
176
- ok: false,
177
- status: typeof err.status === "number" ? err.status : null,
178
- message: err.message ?? String(e),
179
- } satisfies AiReviewThreadResponse;
176
+ // #2363: keeps GitHub's structured errors[], which the classifiers read first.
177
+ return refusalFrom(e) satisfies AiReviewThreadResponse;
180
178
  }
181
179
  };
182
180
 
@@ -192,11 +190,47 @@ const post: AiReviewThreadPoster = async request => {
192
190
  // workflow sets (#2203). Unset reads null, which keeps the fork degrade — so
193
191
  // this CLI under a workflow that does not yet set it behaves as before.
194
192
  const fork = prIsForkReading(process.env[AI_REVIEW_PR_IS_FORK_VAR]);
195
- const result = await postReviewThreads(reading, post, f => carryKey(f, lineTextFor(f)), fork);
193
+
194
+ // #2338: the conversation fallback for a finding GitHub refuses at the file.
195
+ // Offered only when the conversation could be read, so an earlier round's
196
+ // comment is found and not posted twice; unread, the old refusal stands.
197
+ let comment: AiReviewPullCommenter | undefined;
198
+ try {
199
+ // Paged by hand to the end: a short page is the last one.
200
+ const existing: string[] = [];
201
+ for (let page = 1; ; page++) {
202
+ const { data } = await client.rest.issues.listComments({
203
+ owner: parsed.owner,
204
+ repo: parsed.repo,
205
+ issue_number: parsed.pr,
206
+ per_page: 100,
207
+ page,
208
+ });
209
+ for (const c of data as { body?: string | null }[]) existing.push(c.body ?? "");
210
+ if (data.length < 100) break;
211
+ }
212
+ comment = {
213
+ existing,
214
+ post: async body => {
215
+ try {
216
+ await client.rest.issues.createComment({ owner: parsed.owner, repo: parsed.repo, issue_number: parsed.pr, body });
217
+ return { ok: true };
218
+ } catch (e) {
219
+ return refusalFrom(e);
220
+ }
221
+ },
222
+ };
223
+ } catch (e) {
224
+ console.log(
225
+ `${COMMAND}: the pull request's conversation could not be read (${escapeAnnotation((e as Error).message)}), so a finding ` +
226
+ `GitHub refuses at the file has no fallback this round`,
227
+ );
228
+ }
229
+ const result = await postReviewThreads(reading, post, f => carryKey(f, lineTextFor(f)), fork, comment);
196
230
  for (const line of threadsDetailLines(result, COMMAND)) console.log(line);
197
231
  console.log(
198
232
  `${COMMAND}: ${result.outcome} — attempted ${result.attempted}, posted ${result.posted}, ` +
199
- `demoted ${result.demoted}`,
233
+ `demoted ${result.demoted}, on the conversation ${result.pullComments}`,
200
234
  );
201
235
 
202
236
  // The outcome reaches the run summary as an annotation only when it is worth
@@ -238,6 +238,46 @@ export interface BoardSnapshot {
238
238
  * {@link BoardIssue.criteriaField}.
239
239
  */
240
240
  familyIssues?: FamilyIssue[];
241
+
242
+ /**
243
+ * Every open issue a consumer filed (`from-consumer`), with when it was
244
+ * filed, its milestone and its verdict marker — SC-2783, ADR-020.
245
+ *
246
+ * `takenAt` is when the producer read it, so the age is a property of the
247
+ * snapshot and not of whoever reads it later. **Absent means it was never
248
+ * read**, and `consumer-intake` goes UNMEASURED.
249
+ */
250
+ consumerIntake?: ConsumerIntake;
251
+ }
252
+
253
+ /** The consumer-filed issues and when they were read — SC-2783. */
254
+ export interface ConsumerIntake {
255
+ takenAt: string;
256
+ issues: ConsumerIntakeIssue[];
257
+ }
258
+
259
+ /** One open consumer-filed issue — SC-2783. */
260
+ export interface ConsumerIntakeIssue {
261
+ number: number;
262
+ createdAt: string;
263
+ milestone: string | null;
264
+ /** The verdict a trusted marker comment records, or null for none. */
265
+ verdict: string | null;
266
+ }
267
+
268
+ /** How long a consumer issue may wait for an answer before it is overdue — SC-2783. */
269
+ export const CONSUMER_INTAKE_GRACE_MS = 2 * 24 * 60 * 60 * 1000;
270
+
271
+ /**
272
+ * The consumer issues older than the grace period with neither a verdict
273
+ * marker nor a milestone — SC-2783. Either one answers the report; a
274
+ * milestone a person set counts as much as a triage verdict.
275
+ */
276
+ export function consumerIntakeOverdue(intake: ConsumerIntake): ConsumerIntakeIssue[] {
277
+ const at = Date.parse(intake.takenAt);
278
+ return intake.issues.filter(
279
+ i => i.verdict === null && i.milestone === null && at - Date.parse(i.createdAt) > CONSUMER_INTAKE_GRACE_MS,
280
+ );
241
281
  }
242
282
 
243
283
  /** One open issue in some phase-milestone family — #2223 / E4. */
@@ -267,6 +307,12 @@ export interface DeclaredWork {
267
307
  outside?: string;
268
308
  /** A criterion placed under a value the engine does not know — `declared-work` goes UNMEASURED (SC-2778). */
269
309
  unknownPlacement?: string;
310
+ /**
311
+ * The ADR whose acceptance this change introduces and whose Decomposition
312
+ * row names this criterion (#2323). Its issue is filed when that ADR merges,
313
+ * so until then it is planned, named apart, and never unaccounted.
314
+ */
315
+ planned?: string;
270
316
  }
271
317
 
272
318
  /**
@@ -283,7 +329,9 @@ export function declaredWorkUnaccounted(b: BoardSnapshot): DeclaredWork[] {
283
329
  const named = new Set((b.repoIssues ?? []).flatMap(i => i.names));
284
330
  // SC-2778: a criterion the spec parks outside every phase is declared, not
285
331
  // owed — asking for its issue asks for work the spec says cannot start.
286
- return (b.declaredWork ?? []).filter(w => w.outside === undefined).filter(w =>
332
+ // #2323: a criterion an unmerged ADR plans has no issue YET, because the
333
+ // merge is what files it — owed, but not by anybody who could have filed it.
334
+ return (b.declaredWork ?? []).filter(w => w.outside === undefined && w.planned === undefined).filter(w =>
287
335
  w.kind === "criterion" ? !named.has(w.id) : !(typeof w.issue === "number" && open.has(w.issue)),
288
336
  );
289
337
  }
@@ -468,6 +516,12 @@ export interface Reading {
468
516
  * built elsewhere (a test, a formatter caller) need not invent an empty list.
469
517
  */
470
518
  declared?: string[];
519
+ /**
520
+ * Rows left out of BOTH sides because an ADR this change accepts plans them,
521
+ * and its merge files their issues (#2323). Named apart like {@link declared},
522
+ * under their own heading so a planned criterion never reads as parked.
523
+ */
524
+ planned?: string[];
471
525
  }
472
526
 
473
527
  interface ReadingSpec {
@@ -515,6 +569,8 @@ interface ReadingSpec {
515
569
  offenders?: (board: BoardSnapshot) => string[];
516
570
  /** The rows declared outside every phase, named — see {@link Reading.declared}. */
517
571
  declared?: (board: BoardSnapshot) => string[];
572
+ /** The rows an unmerged ADR plans, named — see {@link Reading.planned}. */
573
+ planned?: (board: BoardSnapshot) => string[];
518
574
  }
519
575
 
520
576
  /** The issue numbers actually on the board, for resolving a reference. */
@@ -891,11 +947,50 @@ export const READINGS: readonly ReadingSpec[] = [
891
947
  unknown.map(w => `${w.id} (${w.source}) is placed ${JSON.stringify(w.unknownPlacement)}`).join("; ");
892
948
  },
893
949
  measure: b => {
894
- const total = b.declaredWork!.filter(w => w.outside === undefined).length;
950
+ const total = b.declaredWork!.filter(w => w.outside === undefined && w.planned === undefined).length;
895
951
  return { measured: total - declaredWorkUnaccounted(b).length, target: total };
896
952
  },
897
953
  offenders: b => declaredWorkUnaccounted(b).map(w => `${w.id} (${w.source}) names no open issue`),
898
954
  declared: b => b.declaredWork!.filter(w => w.outside !== undefined).map(w => `${w.id} (${w.source}) — ${w.outside}`),
955
+ // Every planned row, parked or not: an ADR about to file an issue for a
956
+ // criterion the spec parks is worth seeing on both lines.
957
+ planned: b => b.declaredWork!.filter(w => w.planned !== undefined).map(w => `${w.id} (${w.source}) — ${w.planned}`),
958
+ },
959
+ {
960
+ name: "consumer-intake",
961
+ item: "SC-2783",
962
+ what: "every consumer-filed issue older than two days carries a verdict marker or a milestone",
963
+ readsIssueRefs: false,
964
+ // The denominator is EVERY open issue, not the consumer ones: a
965
+ // repository nobody has filed into is conformant, and counting only
966
+ // consumer issues would make it 0 of 0, which this frame reads as
967
+ // UNMEASURED — every repository without consumers would fail its board.
968
+ // The question is therefore "no open issue is an unanswered consumer
969
+ // report", asked of a population that was read.
970
+ unreadable: b => {
971
+ if (b.consumerIntake === undefined) {
972
+ return "consumer-filed issues were never read with their comments, so whether any waits unanswered is unknown";
973
+ }
974
+ if (b.repoIssues === undefined) return "open issues were never read, so the intake has nothing to be counted against";
975
+ if (Number.isNaN(Date.parse(b.consumerIntake.takenAt))) {
976
+ return `the intake's read time ${JSON.stringify(b.consumerIntake.takenAt)} is not a time, so no issue's age is known`;
977
+ }
978
+ // A consumer row outside the open population would be dropped by the
979
+ // ratio below, and the reading would get easier the more it disagreed.
980
+ const open = new Set(b.repoIssues.map(i => i.number));
981
+ const stray = b.consumerIntake.issues.filter(i => !open.has(i.number)).map(i => `#${i.number}`);
982
+ return stray.length === 0
983
+ ? null
984
+ : `consumer issue(s) ${stray.join(", ")} are not among the open issues read, so the two readings disagree`;
985
+ },
986
+ measure: b => ({
987
+ measured: b.repoIssues!.length - consumerIntakeOverdue(b.consumerIntake!).length,
988
+ target: b.repoIssues!.length,
989
+ }),
990
+ offenders: b =>
991
+ consumerIntakeOverdue(b.consumerIntake!).map(
992
+ i => `#${i.number} — filed by a consumer at ${i.createdAt}, and carries neither a verdict marker nor a milestone`,
993
+ ),
899
994
  },
900
995
  ];
901
996
 
@@ -921,16 +1016,17 @@ export function takeReading(spec: ReadingSpec, board: BoardSnapshot | null): Rea
921
1016
  // board to hand it. `main` can no longer reach this arm at all (#1718:
922
1017
  // every source either produces a board or returns a reason), so the one
923
1018
  // way here is an API caller passing null, and that is what it now says.
924
- return { ...base, status: "unmeasured", measured: 0, target: 0, why: "no board snapshot was passed to this reading, so nothing was measured — that is a caller with no board, not a board with nothing on it", offenders: [], declared: [] };
1019
+ return { ...base, status: "unmeasured", measured: 0, target: 0, why: "no board snapshot was passed to this reading, so nothing was measured — that is a caller with no board, not a board with nothing on it", offenders: [], declared: [], planned: [] };
925
1020
  }
926
1021
  const why = spec.unreadable?.(board) ?? null;
927
- if (why !== null) return { ...base, status: "unmeasured", measured: 0, target: 0, why, offenders: [], declared: [] };
1022
+ if (why !== null) return { ...base, status: "unmeasured", measured: 0, target: 0, why, offenders: [], declared: [], planned: [] };
928
1023
  const { measured, target } = spec.measure(board);
929
1024
  const declared = spec.declared?.(board) ?? [];
1025
+ const planned = spec.planned?.(board) ?? [];
930
1026
  if (target === 0) {
931
- return { ...base, status: "unmeasured", measured, target, why: "the board carries nothing for this reading to count, so 0 of 0 is not a pass", offenders: [], declared };
1027
+ return { ...base, status: "unmeasured", measured, target, why: "the board carries nothing for this reading to count, so 0 of 0 is not a pass", offenders: [], declared, planned };
932
1028
  }
933
- if (measured >= target) return { ...base, status: "met", measured, target, why: `${measured} of ${target}`, offenders: [], declared };
1029
+ if (measured >= target) return { ...base, status: "met", measured, target, why: `${measured} of ${target}`, offenders: [], declared, planned };
934
1030
  // Named only here. A met reading never pays for the list, and an
935
1031
  // UNMEASURED one must not print rows — it did not read the population it
936
1032
  // would be naming them out of.
@@ -942,6 +1038,7 @@ export function takeReading(spec: ReadingSpec, board: BoardSnapshot | null): Rea
942
1038
  why: `${measured} of ${target} — ${target - measured} short`,
943
1039
  offenders: spec.offenders?.(board) ?? [],
944
1040
  declared,
1041
+ planned,
945
1042
  };
946
1043
  }
947
1044
 
@@ -968,7 +1065,10 @@ export function formatReading(r: Reading): string {
968
1065
  // denominator silently reads the same as one nobody wrote down.
969
1066
  const named = r.declared ?? [];
970
1067
  const declared = named.length === 0 ? "" : `\n declared outside phases (${named.length}): ${named.join(", ")}`;
971
- const head = `${mark} ${r.name.padEnd(20)} ${r.why}\n ${r.what} [${r.item}]${declared}`;
1068
+ // #2323: work an unmerged ADR plans, whose issues its merge files.
1069
+ const plans = r.planned ?? [];
1070
+ const planned = plans.length === 0 ? "" : `\n planned by an ADR this change accepts (${plans.length}): ${plans.join(", ")}`;
1071
+ const head = `${mark} ${r.name.padEnd(20)} ${r.why}\n ${r.what} [${r.item}]${declared}${planned}`;
972
1072
  if (r.offenders.length === 0) return head;
973
1073
  const shown = r.offenders.slice(0, OFFENDERS_SHOWN).map(o => `\n ${o}`).join("");
974
1074
  const rest = r.offenders.length > OFFENDERS_SHOWN
@@ -1332,6 +1432,10 @@ export function readSnapshotText(text: string): SnapshotRead {
1332
1432
  const familyRows = Array.isArray(raw.familyIssues) ? raw.familyIssues.map(normaliseFamilyIssue) : null;
1333
1433
  const family =
1334
1434
  familyRows !== null && familyRows.every(f => f !== null) ? { familyIssues: familyRows as FamilyIssue[] } : {};
1435
+ // SC-2783. The declared-work rule: one row this command cannot identify
1436
+ // unreads the whole intake, because a dropped row is an unanswered report
1437
+ // the reading would never name.
1438
+ const intake = normaliseConsumerIntake(raw.consumerIntake);
1335
1439
 
1336
1440
  return {
1337
1441
  board: {
@@ -1347,11 +1451,30 @@ export function readSnapshotText(text: string): SnapshotRead {
1347
1451
  ...edges,
1348
1452
  ...declared,
1349
1453
  ...family,
1454
+ ...(intake === null ? {} : { consumerIntake: intake }),
1350
1455
  },
1351
1456
  why: null,
1352
1457
  };
1353
1458
  }
1354
1459
 
1460
+ /** The consumer intake, or `null` when it is absent or any part is unidentifiable — SC-2783. */
1461
+ function normaliseConsumerIntake(raw: unknown): ConsumerIntake | null {
1462
+ if (typeof raw !== "object" || raw === null) return null;
1463
+ const r = raw as Record<string, unknown>;
1464
+ if (typeof r.takenAt !== "string" || !Array.isArray(r.issues)) return null;
1465
+ const issues: ConsumerIntakeIssue[] = [];
1466
+ for (const row of r.issues as unknown[]) {
1467
+ if (typeof row !== "object" || row === null) return null;
1468
+ const i = row as Record<string, unknown>;
1469
+ if (typeof i.number !== "number" || !Number.isInteger(i.number)) return null;
1470
+ if (typeof i.createdAt !== "string" || Number.isNaN(Date.parse(i.createdAt))) return null;
1471
+ if (i.milestone !== null && typeof i.milestone !== "string") return null;
1472
+ if (i.verdict !== null && typeof i.verdict !== "string") return null;
1473
+ issues.push({ number: i.number, createdAt: i.createdAt, milestone: i.milestone as string | null, verdict: i.verdict as string | null });
1474
+ }
1475
+ return { takenAt: r.takenAt, issues };
1476
+ }
1477
+
1355
1478
  /** One family-issue row, or `null` for one this command cannot identify — #2223 / E4. */
1356
1479
  function normaliseFamilyIssue(raw: unknown): FamilyIssue | null {
1357
1480
  if (typeof raw !== "object" || raw === null) return null;
@@ -1368,7 +1491,18 @@ function normaliseDeclaredWork(raw: unknown): DeclaredWork | null {
1368
1491
  if (raw === null || typeof raw !== "object") return null;
1369
1492
  const r = raw as Record<string, unknown>;
1370
1493
  if (typeof r.id !== "string" || r.id === "" || typeof r.source !== "string") return null;
1371
- if (r.kind === "criterion") return { kind: "criterion", id: r.id, source: r.source, ...placementAnnotation(r) };
1494
+ if (r.kind === "criterion") {
1495
+ // #2323: absent is "not planned"; present and not a path is a row this
1496
+ // command cannot identify, and dropping the mark would count it missing.
1497
+ if ("planned" in r && (typeof r.planned !== "string" || r.planned === "")) return null;
1498
+ return {
1499
+ kind: "criterion",
1500
+ id: r.id,
1501
+ source: r.source,
1502
+ ...placementAnnotation(r),
1503
+ ...(typeof r.planned === "string" ? { planned: r.planned } : {}),
1504
+ };
1505
+ }
1372
1506
  if (r.kind !== "stage-item") return null;
1373
1507
  if (r.issue === null || r.issue === undefined) return { kind: "stage-item", id: r.id, source: r.source, issue: null };
1374
1508
  return typeof r.issue === "number" && Number.isInteger(r.issue)
@@ -0,0 +1,149 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * `rungate board-scope [--spec <path>] [--json]` — #2275.
4
+ *
5
+ * Read-only. Before a maintainer opts an existing spec into the board, this
6
+ * prints what each spec holds: its criteria, how many are ticked, whether it
7
+ * has a placement table, and its `board:` setting. Each unticked criterion
8
+ * gets a looks-done HINT when a test claims its id (`onboardingHint`), or says
9
+ * why it cannot tell. Measured on two consumer repos (2026-11-16): 18 of 59
10
+ * unticked criteria were already done and nothing ticks them, so the
11
+ * checkboxes alone cannot say what is left.
12
+ *
13
+ * It never ticks anything. Ticking stays a person's act, with evidence, and
14
+ * `audit-spec-evidence` already refuses a tick that names no proof.
15
+ *
16
+ * A spec with criteria that is not opted in is listed as NOT TRACKED, a
17
+ * population of its own, so "not on the board" never reads as "done".
18
+ */
19
+ import { readFileSync } from "fs";
20
+ import { join, relative } from "path";
21
+ import { parseArgs } from "util";
22
+ import { specFilesIn } from "../lib/board-mirror";
23
+ import { readDerivedDeclaration } from "../lib/derived-spec";
24
+ import { isTemplateSpec } from "../lib/sc-ids";
25
+ import { parseCriteria } from "../lib/spec-evidence";
26
+ import { boardDeclaration, onboardingHint, parsePlacementRows, tracksOnBoard, type OnboardingHint } from "../lib/spec-placement";
27
+ import { claimedScKeys, scopedKey } from "./sync-sc-status";
28
+
29
+ /** The one exit code every refusal routes through. */
30
+ export const REFUSE_EXIT = 1;
31
+
32
+ export interface SpecScope {
33
+ path: string;
34
+ scope: string;
35
+ tracked: boolean;
36
+ criteria: number;
37
+ ticked: number;
38
+ placementTable: boolean;
39
+ /** Why the `board:` declaration could not be taken as written, by name — empty when it could. */
40
+ boardProblems: string[];
41
+ /** The generator a `generated-by:` copy names: listed, never counted as not tracked. */
42
+ generated?: string;
43
+ hints: { id: string; hint: OnboardingHint }[];
44
+ }
45
+
46
+ /** Why `--spec` may not be opted in, or null. A template's ids are placeholders; a generated copy is not the source. */
47
+ export function optInRefusal(path: string, content: string): string | null {
48
+ if (isTemplateSpec(path)) return `${path} is the spec template; its ids are placeholders, so it is never opted in`;
49
+ const derived = readDerivedDeclaration(content);
50
+ if (derived.status === "derived") {
51
+ return `${path} is generated by ${derived.generator}; opt in the source it is generated from, not this copy`;
52
+ }
53
+ return null;
54
+ }
55
+
56
+ /** Every spec in the sweep, or the one named, read for onboarding. */
57
+ export function boardScope(root: string, only?: string): { specs: SpecScope[] } | { refusal: string } {
58
+ if (only !== undefined) {
59
+ let content: string;
60
+ try {
61
+ content = readFileSync(join(root, only), "utf-8");
62
+ } catch (e) {
63
+ return { refusal: `${only} could not be read (${(e as Error).message})` };
64
+ }
65
+ const refused = optInRefusal(only, content);
66
+ if (refused !== null) return { refusal: refused };
67
+ }
68
+ // The file list, not the id sweep: a tree where no spec states a criterion
69
+ // yet is exactly what a report made before onboarding must still list.
70
+ const sweep = specFilesIn(root);
71
+ if (sweep.reading === "UNMEASURED") return { refusal: `UNMEASURED: the specs/ listing failed: ${sweep.reasons.join("; ")}` };
72
+ if (only !== undefined && !sweep.paths.includes(only)) return { refusal: `${only} is not a spec the sweep reads under specs/` };
73
+
74
+ const texts = new Map(sweep.paths.map(p => [p, readFileSync(join(root, p), "utf-8")]));
75
+ const declaredBy = new Map<string, string[]>();
76
+ for (const [p, text] of texts) {
77
+ for (const c of parseCriteria(text)) declaredBy.set(c.id, [...(declaredBy.get(c.id) ?? []), p]);
78
+ }
79
+ const claimed = claimedScKeys(join(root, "specs"), join(root, "test"));
80
+
81
+ const specs: SpecScope[] = [];
82
+ for (const path of only === undefined ? sweep.paths : [only]) {
83
+ const text = texts.get(path)!;
84
+ const board = boardDeclaration(text);
85
+ const criteria = parseCriteria(text);
86
+ const derived = readDerivedDeclaration(text);
87
+ const specFile = relative(join(root, "specs"), join(root, path));
88
+ const isClaimed = (id: string) => claimed.has(scopedKey(specFile, id));
89
+ specs.push({
90
+ path,
91
+ scope: board.scope,
92
+ tracked: tracksOnBoard(board),
93
+ boardProblems: [...board.problems, ...board.unknownKeys.map(k => `\`board.${k}\` is not a key the engine knows`)],
94
+ criteria: criteria.length,
95
+ ticked: criteria.filter(c => c.ticked).length,
96
+ placementTable: parsePlacementRows(text).length > 0,
97
+ ...(derived.status === "derived" ? { generated: derived.generator } : {}),
98
+ hints: criteria.filter(c => !c.ticked).map(c => ({ id: c.id, hint: onboardingHint(c.id, path, isClaimed, declaredBy) })),
99
+ });
100
+ }
101
+ return { specs };
102
+ }
103
+
104
+ function hintText(h: OnboardingHint): string {
105
+ if (h.kind === "looks-done") return "looks done: a test claims it. Tick it yourself, with proved-by:, if it is";
106
+ if (h.kind === "ambiguous") return `ambiguous: also stated by ${h.others.join(", ")}`;
107
+ return `cannot tell: ${h.why}`;
108
+ }
109
+
110
+ export function formatScope(specs: readonly SpecScope[], named = false): string {
111
+ const lines: string[] = [];
112
+ // A spec asked for by name is always shown, criteria or not (review of #2329).
113
+ const shown = (x: SpecScope) => named || x.criteria > 0;
114
+ for (const s of specs.filter(x => shown(x) && x.generated !== undefined)) {
115
+ lines.push(`${s.path} — generated by ${s.generated}; opt in its source, so it is not counted`);
116
+ }
117
+ for (const s of specs.filter(x => shown(x) && x.generated === undefined)) {
118
+ const state = s.tracked ? `tracked (${s.scope})` : `NOT TRACKED (${s.scope})`;
119
+ lines.push(`${s.path} — ${state}: ${s.criteria} criteria, ${s.ticked} ticked, placement table: ${s.placementTable ? "yes" : "no"}`);
120
+ // A board: block that cannot be read is named, never shown as merely untracked.
121
+ for (const p of s.boardProblems) lines.push(` board: ${p}`);
122
+ for (const { id, hint } of s.hints) lines.push(` ${id} ${hintText(hint)}`);
123
+ }
124
+ const untracked = specs.filter(s => s.criteria > 0 && !s.tracked && s.generated === undefined);
125
+ lines.push(
126
+ "",
127
+ `not tracked: ${untracked.length} spec(s), ${untracked.reduce((n, s) => n + s.criteria, 0)} criteria the board does not show`,
128
+ );
129
+ return lines.join("\n");
130
+ }
131
+
132
+ function main(argv: string[], root = process.cwd()): number {
133
+ let values: { spec?: string; json?: boolean };
134
+ try {
135
+ ({ values } = parseArgs({ args: argv, options: { spec: { type: "string" }, json: { type: "boolean" } }, strict: true }));
136
+ } catch (e) {
137
+ console.error(`board-scope: ${(e as Error).message}`);
138
+ return REFUSE_EXIT;
139
+ }
140
+ const read = boardScope(root, values.spec);
141
+ if ("refusal" in read) {
142
+ console.error(`board-scope: ${read.refusal}`);
143
+ return REFUSE_EXIT;
144
+ }
145
+ console.log(values.json ? JSON.stringify(read.specs, null, 2) : formatScope(read.specs, values.spec !== undefined));
146
+ return 0;
147
+ }
148
+
149
+ if (import.meta.main) process.exit(main(process.argv.slice(2)));