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.
- package/README.md +82 -0
- package/gates/.gate-salt +1 -1
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +50 -5
- package/lib/board-flow.ts +235 -0
- package/lib/board-lane-health.ts +381 -0
- package/lib/board-mirror.ts +53 -35
- package/lib/board-ready-fanout.ts +56 -13
- package/lib/board-ready-rule.ts +545 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/conformity.ts +95 -2
- package/lib/filing-compliance.ts +367 -0
- package/lib/finding-arbiter.ts +79 -5
- package/lib/generators/agents-md.ts +149 -0
- package/lib/github.ts +79 -0
- package/lib/graphql-cursor.ts +80 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +33 -3
- package/lib/issue-file-overlap.ts +340 -0
- package/lib/issue-filing-gate.ts +173 -8
- package/lib/issue-repair.ts +13 -9
- package/lib/issue-shape.ts +196 -0
- package/lib/scaffold/ai-review-findings.ts +9 -1
- package/lib/scaffold/ai-review-step.ts +35 -1
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +34 -11
- package/lib/spec-placement.ts +108 -0
- package/lib/stage-ladder.ts +28 -3
- package/lib/work-status.ts +423 -0
- package/package.json +1 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/board-mirror.ts +221 -8
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-spec.ts +79 -1
package/scripts/board-mirror.ts
CHANGED
|
@@ -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
|
|
244
|
-
const readyChanges =
|
|
245
|
-
.
|
|
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
|
|
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 —
|
|
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
|
|
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}`);
|
package/scripts/plan-spec.ts
CHANGED
|
@@ -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);
|