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.
- package/bin/rungate.ts +5 -1
- package/gates/.gate-salt +1 -1
- package/lib/ai-review-threads.ts +152 -9
- package/lib/blocked-by-write.ts +95 -0
- package/lib/board-mirror.ts +28 -9
- package/lib/cli-commands.ts +40 -4
- package/lib/config-trackable.ts +91 -6
- package/lib/consumer-triage.ts +214 -0
- package/lib/issue-filing-gate.ts +84 -23
- package/lib/live-issues.ts +5 -0
- package/lib/scaffold/adr-accepted-workflow.ts +5 -6
- package/lib/scaffold/board-project-step.ts +49 -0
- package/lib/scaffold/human-steps.ts +39 -3
- package/lib/scaffold/owned-files.ts +14 -4
- package/lib/scaffold/spec-scope.ts +215 -0
- package/lib/scaffold/specs-placed-workflow.ts +249 -0
- package/lib/scaffold/steps.ts +14 -1
- package/lib/scaffold/write-steps.ts +9 -1
- package/lib/spec-placement.ts +89 -0
- package/lib/success-doc.ts +1 -1
- package/package.json +4 -1
- package/scripts/ai-review-threads.ts +42 -8
- package/scripts/board-conformance.ts +142 -8
- package/scripts/board-scope.ts +149 -0
- package/scripts/board-snapshot.ts +121 -5
- package/scripts/consumer-triage.ts +235 -0
- package/scripts/plan-deps.ts +58 -8
- package/scripts/plan-issues.ts +9 -3
- package/scripts/status-view.ts +955 -0
- package/scripts/sync-sc-status.ts +64 -4
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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")
|
|
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)));
|