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
|
@@ -0,0 +1,955 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Where the current plan stands, in one place a person can read without an
|
|
4
|
+
* agent — #2097.
|
|
5
|
+
*
|
|
6
|
+
* One renderer, two outputs:
|
|
7
|
+
* bun scripts/status-view.ts terminal text (what `/board` prints)
|
|
8
|
+
* bun scripts/status-view.ts --markdown > <f> the pinned issue's body
|
|
9
|
+
* bun scripts/status-view.ts --publish <f> --repo owner/name
|
|
10
|
+
* write <f> into the pinned issue
|
|
11
|
+
*
|
|
12
|
+
* `.github/workflows/status-issue.yml` runs the second and third on every
|
|
13
|
+
* change. Reading and writing are separate invocations so the board token,
|
|
14
|
+
* which the read needs, is never held by the step that writes (ADR-013).
|
|
15
|
+
*
|
|
16
|
+
* ## It follows the plan, not a name
|
|
17
|
+
*
|
|
18
|
+
* The goal and stages come from `project-state.json`. The phases are the
|
|
19
|
+
* milestones in the configured focus family (`board.milestonePrefix`, the
|
|
20
|
+
* setting Ready already orders by), and their one-line meanings come from the
|
|
21
|
+
* spec configured as `board.engineSpec`. Nothing here names a family or a
|
|
22
|
+
* spec. When the plan moves to other work, the config moves and so does the
|
|
23
|
+
* view.
|
|
24
|
+
*
|
|
25
|
+
* ## Unread is never empty
|
|
26
|
+
*
|
|
27
|
+
* Every section is a `Reading`. A source that could not be read renders as
|
|
28
|
+
* UNMEASURED with its reason, never as an empty list: an empty "In progress"
|
|
29
|
+
* is byte-identical to a project with nothing in progress
|
|
30
|
+
* (`.claude/rules/config-access.md`, Silent Default Substitution).
|
|
31
|
+
*
|
|
32
|
+
* Stage verdicts are each item's `done` flag. They are not re-run here:
|
|
33
|
+
* `test/stage-ladder.test.ts` runs every done item's proof command in CI on
|
|
34
|
+
* every pull request, so a `done` that stopped being true is already red
|
|
35
|
+
* there. Re-running roughly forty commands on every issue event would add
|
|
36
|
+
* minutes and decide nothing new.
|
|
37
|
+
*/
|
|
38
|
+
import { spawnSync } from "child_process";
|
|
39
|
+
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
|
|
40
|
+
import { tmpdir } from "os";
|
|
41
|
+
import { join } from "path";
|
|
42
|
+
import { readBoardConfig, readBoardInputs, readQueueLabel } from "../lib/config-readers";
|
|
43
|
+
import { nextCursor } from "../lib/graphql-cursor";
|
|
44
|
+
import { readMilestoneTitle } from "../lib/milestone-title";
|
|
45
|
+
import { parseCriteria } from "../lib/spec-evidence";
|
|
46
|
+
import { PHASE_VALUE, parsePlacementRows } from "../lib/spec-placement";
|
|
47
|
+
import { ladderReport } from "../lib/work-status";
|
|
48
|
+
|
|
49
|
+
/** The marker that identifies the pinned issue this script owns. */
|
|
50
|
+
export const STATUS_MARKER = "<!-- rungate:status-view -->";
|
|
51
|
+
/** Longest list a section prints before it links to the rest. */
|
|
52
|
+
export const LIST_LIMIT = 10;
|
|
53
|
+
/** The label a session puts on an issue it parks for a person to decide (#2138). */
|
|
54
|
+
export const NEEDS_DECISION = "needs-decision";
|
|
55
|
+
/** Every refusal exits through this. */
|
|
56
|
+
export const REFUSAL_EXIT = 1;
|
|
57
|
+
/** Where "How this view is made" points: the published package, which every repository using it can open. */
|
|
58
|
+
export const PACKAGE_PAGE = "https://www.npmjs.com/package/rungate";
|
|
59
|
+
/**
|
|
60
|
+
* This package's own CLI. Not `<root>/bin/rungate.ts`: in a consumer the
|
|
61
|
+
* package is in node_modules and the root has no bin/ (#2330).
|
|
62
|
+
*/
|
|
63
|
+
const CLI_ENTRY = join(import.meta.dir, "..", "bin", "rungate.ts");
|
|
64
|
+
|
|
65
|
+
export type Reading<T> = { kind: "READ"; value: T } | { kind: "UNMEASURED"; why: string };
|
|
66
|
+
|
|
67
|
+
export interface StageLine {
|
|
68
|
+
id: string;
|
|
69
|
+
name: string;
|
|
70
|
+
meaning: string;
|
|
71
|
+
state: "done" | "next" | "later";
|
|
72
|
+
open: string[];
|
|
73
|
+
total: number;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export interface PhaseLine {
|
|
77
|
+
number: number;
|
|
78
|
+
title: string;
|
|
79
|
+
meaning: string | null;
|
|
80
|
+
open: number;
|
|
81
|
+
closed: number;
|
|
82
|
+
url: string;
|
|
83
|
+
state: "done" | "current" | "later" | "empty";
|
|
84
|
+
/**
|
|
85
|
+
* For a phase with no issues only: how many criteria the spec's Phase
|
|
86
|
+
* placement table puts in it, and how many of those are unticked (#2147).
|
|
87
|
+
* Absent when the phase has issues, or the spec places nothing in it.
|
|
88
|
+
*/
|
|
89
|
+
criteria?: { placed: number; unticked: number };
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** A family other than the focus family: its totals, and every phase in it (#2330). */
|
|
93
|
+
export interface FamilyLine {
|
|
94
|
+
family: string;
|
|
95
|
+
open: number;
|
|
96
|
+
closed: number;
|
|
97
|
+
phases: PhaseLine[];
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** One open issue in a phase, with what still blocks it and who has it (#2330). */
|
|
101
|
+
export interface PhaseIssue {
|
|
102
|
+
number: number;
|
|
103
|
+
title: string;
|
|
104
|
+
url: string;
|
|
105
|
+
milestone: string;
|
|
106
|
+
assignees: string[];
|
|
107
|
+
/** Open blockers only: a closed blocker no longer holds anything back. */
|
|
108
|
+
blockers: number[];
|
|
109
|
+
/** The blocked-by list was longer than one page, so `blockers` may be short. */
|
|
110
|
+
moreBlockers: boolean;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export interface WorkLine {
|
|
114
|
+
number: number;
|
|
115
|
+
title: string;
|
|
116
|
+
url: string;
|
|
117
|
+
note?: string;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
export interface HealthLine {
|
|
121
|
+
name: string;
|
|
122
|
+
status: string;
|
|
123
|
+
measured: number;
|
|
124
|
+
target: number;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
export interface StatusView {
|
|
128
|
+
repo: string;
|
|
129
|
+
generatedAt: string;
|
|
130
|
+
commit: string | null;
|
|
131
|
+
family: string | null;
|
|
132
|
+
goal: Reading<string>;
|
|
133
|
+
stages: Reading<StageLine[]>;
|
|
134
|
+
phases: Reading<PhaseLine[]>;
|
|
135
|
+
otherFamilies: Reading<FamilyLine[]>;
|
|
136
|
+
/** Every open issue that sits in a milestone, for listing under its phase (#2330). */
|
|
137
|
+
phaseIssues: Reading<PhaseIssue[]>;
|
|
138
|
+
inProgress: Reading<WorkLine[]>;
|
|
139
|
+
ready: Reading<WorkLine[]>;
|
|
140
|
+
decisions: Reading<WorkLine[]>;
|
|
141
|
+
unphased: Reading<WorkLine[]>;
|
|
142
|
+
/**
|
|
143
|
+
* What `unphased` holds: queued issues with no milestone when a queue label
|
|
144
|
+
* is configured, or every open issue with no milestone when none is (#2330).
|
|
145
|
+
*/
|
|
146
|
+
unphasedScope: "queued" | "all";
|
|
147
|
+
health: Reading<HealthLine[]>;
|
|
148
|
+
/** A link whose address could not be read carries `url: null` and why, rendered as UNMEASURED. */
|
|
149
|
+
links: { label: string; url: string | null; why?: string }[];
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
export interface Milestone {
|
|
153
|
+
title: string;
|
|
154
|
+
open: number;
|
|
155
|
+
closed: number;
|
|
156
|
+
url: string;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
const read = <T>(value: T): Reading<T> => ({ kind: "READ", value });
|
|
160
|
+
const unmeasured = <T>(why: string): Reading<T> => ({ kind: "UNMEASURED", why });
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* The goal and the finish line, from the plan's own text.
|
|
164
|
+
*
|
|
165
|
+
* Well-formedness and the next stage are `ladderReport`'s, the one reader
|
|
166
|
+
* `work-status` also uses, so the two reports cannot disagree about which
|
|
167
|
+
* stage is next.
|
|
168
|
+
*/
|
|
169
|
+
export function planLines(source: string | null, where: string): { goal: Reading<string>; stages: Reading<StageLine[]> } {
|
|
170
|
+
const report = ladderReport(source, where);
|
|
171
|
+
if (report.kind === "UNMEASURED") return { goal: unmeasured(report.why), stages: unmeasured(report.why) };
|
|
172
|
+
// `ladderViolations` (inside `ladderReport`) has already refused a plan
|
|
173
|
+
// without a goal statement, so this reads it rather than re-checking it.
|
|
174
|
+
const doc = JSON.parse(source as string) as {
|
|
175
|
+
goal: { statement: string };
|
|
176
|
+
stages: { id: string; name: string; goal?: unknown; items: { id: string; done: boolean }[] }[];
|
|
177
|
+
};
|
|
178
|
+
const goal = read(doc.goal.statement.trim());
|
|
179
|
+
const stages = doc.stages.map(s => {
|
|
180
|
+
const open = s.items.filter(i => !i.done).map(i => i.id);
|
|
181
|
+
const state: StageLine["state"] = open.length === 0 ? "done" : s.id === report.next ? "next" : "later";
|
|
182
|
+
return {
|
|
183
|
+
id: s.id,
|
|
184
|
+
name: s.name,
|
|
185
|
+
meaning: typeof s.goal === "string" ? s.goal : "",
|
|
186
|
+
state,
|
|
187
|
+
open,
|
|
188
|
+
total: s.items.length,
|
|
189
|
+
};
|
|
190
|
+
});
|
|
191
|
+
return { goal, stages: read(stages) };
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* The first paragraph of a spec's `### Phase N` section, kept to whole
|
|
196
|
+
* sentences within `limit` characters (at least one sentence).
|
|
197
|
+
*
|
|
198
|
+
* Read, never written here. Where that paragraph is jargon, rewriting it is
|
|
199
|
+
* a spec edit, so the fix lands in one place and every reader gets it.
|
|
200
|
+
*/
|
|
201
|
+
export function phaseBlurb(specText: string, phase: number, limit = 280): string | null {
|
|
202
|
+
const lines = specText.split("\n");
|
|
203
|
+
const at = lines.findIndex(l => new RegExp(`^###\\s+Phase\\s+${phase}\\b`).test(l));
|
|
204
|
+
if (at === -1) return null;
|
|
205
|
+
const para: string[] = [];
|
|
206
|
+
for (const line of lines.slice(at + 1)) {
|
|
207
|
+
if (/^#{1,6}\s/.test(line)) break;
|
|
208
|
+
if (line.trim() === "") {
|
|
209
|
+
if (para.length > 0) break;
|
|
210
|
+
continue;
|
|
211
|
+
}
|
|
212
|
+
para.push(line.trim());
|
|
213
|
+
}
|
|
214
|
+
if (para.length === 0) return null;
|
|
215
|
+
// A sentence ends at punctuation FOLLOWED BY WHITESPACE, so the dot in
|
|
216
|
+
// "AGENTS.md" stays inside its sentence.
|
|
217
|
+
const sentences = para.join(" ").split(/(?<=[.!?])\s+/);
|
|
218
|
+
let out = "";
|
|
219
|
+
for (const s of sentences) {
|
|
220
|
+
const next = out === "" ? s : `${out} ${s}`;
|
|
221
|
+
if (out !== "" && next.length > limit) break;
|
|
222
|
+
out = next;
|
|
223
|
+
}
|
|
224
|
+
return out.trim();
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* Per phase number, the criteria the spec's Phase placement table puts there
|
|
229
|
+
* and how many are unticked. A placed id the spec never states counts as
|
|
230
|
+
* unticked: a criterion nobody can find has not been shown true.
|
|
231
|
+
*/
|
|
232
|
+
export function placedCriteria(specText: string): Map<number, { placed: number; unticked: number }> {
|
|
233
|
+
const ticked = new Map(parseCriteria(specText).map(c => [c.id, c.ticked]));
|
|
234
|
+
const out = new Map<number, { placed: number; unticked: number }>();
|
|
235
|
+
for (const row of parsePlacementRows(specText)) {
|
|
236
|
+
const m = row.placement.match(PHASE_VALUE);
|
|
237
|
+
if (m === null || row.ids.length === 0) continue;
|
|
238
|
+
// Summed, not set: a phase whose criteria sit in two rows is judged on both.
|
|
239
|
+
const prev = out.get(Number(m[1])) ?? { placed: 0, unticked: 0 };
|
|
240
|
+
out.set(Number(m[1]), {
|
|
241
|
+
placed: prev.placed + row.ids.length,
|
|
242
|
+
unticked: prev.unticked + row.ids.filter(id => ticked.get(id) !== true).length,
|
|
243
|
+
});
|
|
244
|
+
}
|
|
245
|
+
return out;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* The focus family's phases, in phase order, each with its meaning and progress.
|
|
250
|
+
*
|
|
251
|
+
* A phase with issues is judged by its issues. A phase with none is done only
|
|
252
|
+
* when the spec places criteria in it and every one is ticked (#2147) — work
|
|
253
|
+
* that landed before criteria became issues leaves a milestone empty and the
|
|
254
|
+
* phase finished. Anything less stays "empty", never done.
|
|
255
|
+
*/
|
|
256
|
+
export function phaseLines(milestones: readonly Milestone[], family: string, specText: string | null): PhaseLine[] {
|
|
257
|
+
const mine = milestones
|
|
258
|
+
.map(m => ({ m, r: readMilestoneTitle(m.title) }))
|
|
259
|
+
.filter(x => x.r !== null && x.r.family === family)
|
|
260
|
+
.map(x => ({ m: x.m, number: x.r!.phase }))
|
|
261
|
+
.sort((a, b) => a.number - b.number);
|
|
262
|
+
const current = mine.find(x => x.m.open > 0)?.number;
|
|
263
|
+
const placed = specText === null ? new Map<number, { placed: number; unticked: number }>() : placedCriteria(specText);
|
|
264
|
+
return mine.map(({ m, number }) => {
|
|
265
|
+
const criteria = m.open + m.closed === 0 ? placed.get(number) : undefined;
|
|
266
|
+
const state: PhaseLine["state"] =
|
|
267
|
+
m.open + m.closed === 0
|
|
268
|
+
? criteria !== undefined && criteria.unticked === 0
|
|
269
|
+
? "done"
|
|
270
|
+
: "empty"
|
|
271
|
+
: m.open === 0
|
|
272
|
+
? "done"
|
|
273
|
+
: number === current
|
|
274
|
+
? "current"
|
|
275
|
+
: "later";
|
|
276
|
+
return {
|
|
277
|
+
number,
|
|
278
|
+
title: m.title,
|
|
279
|
+
meaning: specText === null ? null : phaseBlurb(specText, number),
|
|
280
|
+
open: m.open,
|
|
281
|
+
closed: m.closed,
|
|
282
|
+
url: m.url,
|
|
283
|
+
state,
|
|
284
|
+
...(criteria === undefined ? {} : { criteria }),
|
|
285
|
+
};
|
|
286
|
+
});
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Every family other than the focus family, with its phases (#2330).
|
|
291
|
+
*
|
|
292
|
+
* A consumer's own work is usually NOT the focus family: the focus is the
|
|
293
|
+
* family Ready orders by, and on 2026-11-17 the one consumer had it set to a
|
|
294
|
+
* family whose phases were all closed. Shown as a count, its open family read
|
|
295
|
+
* `3 phase(s), 0 of 22 done` and named none of the 22 issues. The renderer
|
|
296
|
+
* collapses a family only when nothing in it is open.
|
|
297
|
+
*/
|
|
298
|
+
export function otherFamilyLines(milestones: readonly Milestone[], family: string): FamilyLine[] {
|
|
299
|
+
const names = new Set<string>();
|
|
300
|
+
for (const m of milestones) {
|
|
301
|
+
const f = readMilestoneTitle(m.title)?.family ?? null;
|
|
302
|
+
if (f !== null && f !== "" && f !== family) names.add(f);
|
|
303
|
+
}
|
|
304
|
+
return [...names]
|
|
305
|
+
.sort((a, b) => a.localeCompare(b))
|
|
306
|
+
.map(f => {
|
|
307
|
+
const phases = phaseLines(milestones, f, null);
|
|
308
|
+
return {
|
|
309
|
+
family: f,
|
|
310
|
+
open: phases.reduce((n, p) => n + p.open, 0),
|
|
311
|
+
closed: phases.reduce((n, p) => n + p.closed, 0),
|
|
312
|
+
phases,
|
|
313
|
+
};
|
|
314
|
+
});
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* Repository text made safe to place in the issue body.
|
|
319
|
+
*
|
|
320
|
+
* Titles are written by anyone who can open an issue. Unescaped, an
|
|
321
|
+
* `@name` would notify that person on every rewrite, and brackets or angle
|
|
322
|
+
* brackets would let a title inject a link or markup into the pinned view.
|
|
323
|
+
*
|
|
324
|
+
* **Criterion ids are broken with a non-breaking hyphen.** The pinned view is
|
|
325
|
+
* an open issue, and every reader that asks "does an open issue name SC-N?"
|
|
326
|
+
* reads its body. A title or spec sentence quoting `SC-2752` would make this
|
|
327
|
+
* issue cover that criterion for as long as it stays open, which is forever,
|
|
328
|
+
* so a real gap would never show again. `SC‑2752` (U+2011) reads the same and
|
|
329
|
+
* matches no id pattern.
|
|
330
|
+
*/
|
|
331
|
+
export function plain(s: string): string {
|
|
332
|
+
return s
|
|
333
|
+
.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
|
|
334
|
+
.replace(/&/g, "&")
|
|
335
|
+
.replace(/</g, "<")
|
|
336
|
+
.replace(/>/g, ">")
|
|
337
|
+
.replace(/([[\]`*_|\\])/g, "\\$1")
|
|
338
|
+
.replace(/@/g, "@​")
|
|
339
|
+
.replace(/\b([A-Z]{2,5})-([A-Z]?\d+)\b/g, "$1‑$2");
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/** Terminal text: control characters only, so an escape code cannot redraw the screen. */
|
|
343
|
+
function term(s: string): string {
|
|
344
|
+
return s.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
/** The note after an open issue in a phase: its open blockers, then who has it. */
|
|
348
|
+
function issueNote(i: PhaseIssue): string {
|
|
349
|
+
const notes: string[] = [];
|
|
350
|
+
if (i.blockers.length > 0) notes.push(`blocked by ${i.blockers.map(n => `#${n}`).join(", ")}${i.moreBlockers ? " and more" : ""}`);
|
|
351
|
+
else if (i.moreBlockers) notes.push("blocked by more than one page of issues");
|
|
352
|
+
if (i.assignees.length > 0) notes.push(i.assignees.join(", "));
|
|
353
|
+
return notes.join("; ");
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
const STAGE_MARK = { done: "✓", next: "●", later: "○" } as const;
|
|
357
|
+
const PHASE_MARK = { done: "✓", current: "●", later: "○", empty: "–" } as const;
|
|
358
|
+
|
|
359
|
+
type Fmt = {
|
|
360
|
+
text: (s: string) => string;
|
|
361
|
+
heading: (s: string) => string;
|
|
362
|
+
link: (label: string, url: string) => string;
|
|
363
|
+
item: (s: string) => string;
|
|
364
|
+
/** A list item nested `depth` levels under an item. */
|
|
365
|
+
sub: (depth: number, s: string) => string;
|
|
366
|
+
};
|
|
367
|
+
|
|
368
|
+
const MARKDOWN: Fmt = {
|
|
369
|
+
text: plain,
|
|
370
|
+
heading: s => `### ${s}`,
|
|
371
|
+
link: (label, url) => `[${plain(label)}](${url})`,
|
|
372
|
+
item: s => `- ${s}`,
|
|
373
|
+
sub: (depth, s) => `${" ".repeat(depth)}- ${s}`,
|
|
374
|
+
};
|
|
375
|
+
|
|
376
|
+
const TEXT: Fmt = {
|
|
377
|
+
text: term,
|
|
378
|
+
heading: s => `\n${s}\n${"─".repeat(s.length)}`,
|
|
379
|
+
link: (label, url) => `${term(label)} (${url})`,
|
|
380
|
+
item: s => ` ${s}`,
|
|
381
|
+
sub: (depth, s) => `${" ".repeat(depth)} ${s}`,
|
|
382
|
+
};
|
|
383
|
+
|
|
384
|
+
function section<T>(f: Fmt, title: string, r: Reading<T>, body: (v: T) => string[]): string[] {
|
|
385
|
+
const out = [f.heading(title)];
|
|
386
|
+
if (r.kind === "UNMEASURED") out.push(f.item(`UNMEASURED — ${f.text(r.why)}`));
|
|
387
|
+
else out.push(...body(r.value));
|
|
388
|
+
return out;
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
function workList(f: Fmt, lines: WorkLine[], empty: string, more?: string): string[] {
|
|
392
|
+
if (lines.length === 0) return [f.item(empty)];
|
|
393
|
+
const shown = lines.slice(0, LIST_LIMIT).map(w =>
|
|
394
|
+
f.item(`${f.link(`#${w.number}`, w.url)} ${f.text(w.title)}${w.note ? ` — ${f.text(w.note)}` : ""}`),
|
|
395
|
+
);
|
|
396
|
+
if (lines.length > LIST_LIMIT) {
|
|
397
|
+
shown.push(f.item(`… and ${lines.length - LIST_LIMIT} more${more ? ` (${more})` : ""}`));
|
|
398
|
+
}
|
|
399
|
+
return shown;
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/** A phase's line, its meaning, and the open issues in it, at list depth `depth`. */
|
|
403
|
+
function phaseBlock(f: Fmt, p: PhaseLine, issues: Reading<PhaseIssue[]>, markdown: boolean, depth: number): string[] {
|
|
404
|
+
const total = p.open + p.closed;
|
|
405
|
+
const c = p.criteria;
|
|
406
|
+
const why =
|
|
407
|
+
c === undefined
|
|
408
|
+
? ""
|
|
409
|
+
: c.unticked === 0
|
|
410
|
+
? `; its ${c.placed} criteria are ticked`
|
|
411
|
+
: `; ${c.unticked} of its ${c.placed} criteria unticked`;
|
|
412
|
+
const progress = total === 0 ? `no issues${why}` : `${p.closed} of ${total} done`;
|
|
413
|
+
const line = `${PHASE_MARK[p.state]} ${f.link(p.title, p.url)} — ${progress}`;
|
|
414
|
+
const out = [depth === 0 ? f.item(line) : f.sub(depth, line)];
|
|
415
|
+
if (p.meaning) out.push(`${markdown ? " ".repeat(depth + 1) : " ".repeat(depth) + " "}${f.text(p.meaning)}`);
|
|
416
|
+
if (issues.kind === "READ" && p.open > 0) {
|
|
417
|
+
const mine = issues.value.filter(i => i.milestone === p.title);
|
|
418
|
+
for (const i of mine.slice(0, LIST_LIMIT)) {
|
|
419
|
+
const note = issueNote(i);
|
|
420
|
+
out.push(f.sub(depth + 1, `${f.link(`#${i.number}`, i.url)} ${f.text(i.title)}${note ? ` — ${f.text(note)}` : ""}`));
|
|
421
|
+
}
|
|
422
|
+
if (mine.length > LIST_LIMIT) out.push(f.sub(depth + 1, `… and ${mine.length - LIST_LIMIT} more`));
|
|
423
|
+
// A milestone's open count includes pull requests, and the issue read
|
|
424
|
+
// returns issues only, so the difference is said rather than left as a
|
|
425
|
+
// phase that reads open with too little under it (review of #2334).
|
|
426
|
+
const prs = p.open - mine.length;
|
|
427
|
+
if (prs > 0) out.push(f.sub(depth + 1, `and ${prs} open pull request(s), which the milestone counts`));
|
|
428
|
+
}
|
|
429
|
+
return out;
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
/** One line when the open issues could not be read, so a phase without them is not read as a phase without issues. */
|
|
433
|
+
function issuesUnread(f: Fmt, issues: Reading<PhaseIssue[]>): string[] {
|
|
434
|
+
return issues.kind === "UNMEASURED" ? [f.item(`open issues per phase: UNMEASURED — ${f.text(issues.why)}`)] : [];
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
function render(v: StatusView, f: Fmt, markdown: boolean): string {
|
|
438
|
+
const out: string[] = [];
|
|
439
|
+
if (markdown) {
|
|
440
|
+
out.push(STATUS_MARKER);
|
|
441
|
+
out.push(
|
|
442
|
+
`> Rewritten from live readings by \`scripts/status-view.ts\` on every change. Do not edit by hand; ` +
|
|
443
|
+
`edits are overwritten. Read at ${v.generatedAt}${v.commit ? ` from \`${v.commit.slice(0, 8)}\`` : ""}.`,
|
|
444
|
+
);
|
|
445
|
+
} else {
|
|
446
|
+
out.push(`Where we are — read at ${v.generatedAt}${v.commit ? ` from ${v.commit.slice(0, 8)}` : ""}`);
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
out.push(...section(f, "The goal", v.goal, g => [f.text(g)]));
|
|
450
|
+
|
|
451
|
+
out.push(
|
|
452
|
+
...section(f, "The finish line", v.stages, stages =>
|
|
453
|
+
stages.map(s => {
|
|
454
|
+
const left = s.open.length === 0 ? "" : ` — ${s.open.length} of ${s.total} left: ${f.text(s.open.join(", "))}`;
|
|
455
|
+
const id = markdown ? `**${f.text(s.id)}**` : s.id;
|
|
456
|
+
return f.item(`${STAGE_MARK[s.state]} ${id} ${f.text(s.name)}: ${f.text(s.meaning)}${left}`);
|
|
457
|
+
}),
|
|
458
|
+
),
|
|
459
|
+
);
|
|
460
|
+
|
|
461
|
+
const phaseTitle = v.family === null ? "Phases" : `Phases (${v.family})`;
|
|
462
|
+
out.push(
|
|
463
|
+
...section(f, phaseTitle, v.phases, phases =>
|
|
464
|
+
phases.length === 0
|
|
465
|
+
? [f.item(`no milestone is in the ${f.text(v.family ?? "")} family`)]
|
|
466
|
+
: [...issuesUnread(f, v.phaseIssues), ...phases.flatMap(p => phaseBlock(f, p, v.phaseIssues, markdown, 0))],
|
|
467
|
+
),
|
|
468
|
+
);
|
|
469
|
+
out.push(
|
|
470
|
+
...section(f, "Other work", v.otherFamilies, fams =>
|
|
471
|
+
fams.length === 0
|
|
472
|
+
? [f.item("no other milestone family")]
|
|
473
|
+
: [
|
|
474
|
+
...(fams.some(x => x.open > 0) ? issuesUnread(f, v.phaseIssues) : []),
|
|
475
|
+
...fams.flatMap(x =>
|
|
476
|
+
x.open === 0 && x.closed === 0
|
|
477
|
+
? // No issue ever sat in these milestones: not started, which is not done (review of #2334).
|
|
478
|
+
[f.item(`${f.text(x.family)}: not started — no issue in any of its phases yet`)]
|
|
479
|
+
: x.open === 0
|
|
480
|
+
? [f.item(`✓ ${f.text(x.family)}: done — ${x.phases.length} phase(s), ${x.closed} closed`)]
|
|
481
|
+
: [
|
|
482
|
+
f.item(`${f.text(x.family)}: ${x.closed} of ${x.open + x.closed} done`),
|
|
483
|
+
...x.phases.flatMap(p => phaseBlock(f, p, v.phaseIssues, markdown, 1)),
|
|
484
|
+
],
|
|
485
|
+
),
|
|
486
|
+
],
|
|
487
|
+
),
|
|
488
|
+
);
|
|
489
|
+
|
|
490
|
+
out.push(...section(f, "In progress", v.inProgress, w => workList(f, w, "nothing is assigned or in a pull request")));
|
|
491
|
+
out.push(...section(f, "Ready next", v.ready, w => workList(f, w, "nothing is in Ready")));
|
|
492
|
+
out.push(...section(f, "Needs a decision", v.decisions, w => workList(f, w, "nothing is waiting on a decision")));
|
|
493
|
+
out.push(
|
|
494
|
+
...section(f, "Unphased", v.unphased, w =>
|
|
495
|
+
v.unphasedScope === "queued"
|
|
496
|
+
? workList(f, w, "every queued issue has a phase", "queued issues with no milestone")
|
|
497
|
+
: w.length === 0
|
|
498
|
+
? [f.item("every open issue has a milestone")]
|
|
499
|
+
: [f.item(`${w.length} open issue(s) have no milestone; the oldest is ${f.link(`#${w[0].number}`, w[0].url)} ${f.text(w[0].title)}`)],
|
|
500
|
+
),
|
|
501
|
+
);
|
|
502
|
+
out.push(
|
|
503
|
+
...section(f, "Health", v.health, h => {
|
|
504
|
+
const met = h.filter(x => x.status === "met").length;
|
|
505
|
+
return [
|
|
506
|
+
f.item(`board checks: ${met} of ${h.length} met`),
|
|
507
|
+
...h.filter(x => x.status !== "met").map(x => f.item(`${x.status.toUpperCase()} ${x.name}: ${x.measured} of ${x.target}`)),
|
|
508
|
+
];
|
|
509
|
+
}),
|
|
510
|
+
);
|
|
511
|
+
out.push(
|
|
512
|
+
f.heading("Links"),
|
|
513
|
+
...v.links.map(l => f.item(l.url === null ? `${f.text(l.label)} — UNMEASURED: ${f.text(l.why ?? "unknown")}` : f.link(l.label, l.url))),
|
|
514
|
+
);
|
|
515
|
+
if (markdown) {
|
|
516
|
+
out.push("", "_This view serves no criterion; it reports on the ones the plan names._");
|
|
517
|
+
}
|
|
518
|
+
return `${out.join("\n")}\n`;
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
/** The pinned issue's body. */
|
|
522
|
+
export function renderMarkdown(v: StatusView): string {
|
|
523
|
+
return render(v, MARKDOWN, true);
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
/** What `/board` prints in a terminal: the same sections, no markup. */
|
|
527
|
+
export function renderText(v: StatusView): string {
|
|
528
|
+
return render(v, TEXT, false);
|
|
529
|
+
}
|
|
530
|
+
|
|
531
|
+
// ---------------------------------------------------------------------------
|
|
532
|
+
// Reading the live sources. Everything below is I/O; everything above is pure.
|
|
533
|
+
// ---------------------------------------------------------------------------
|
|
534
|
+
|
|
535
|
+
type Gh = (args: string[]) => { ok: true; out: string } | { ok: false; why: string };
|
|
536
|
+
|
|
537
|
+
const liveGh: Gh = args => {
|
|
538
|
+
const r = spawnSync("gh", args, { encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 });
|
|
539
|
+
if (r.error) return { ok: false, why: `gh could not start: ${r.error.message}` };
|
|
540
|
+
if (r.status !== 0) return { ok: false, why: `gh ${args[0]} exited ${r.status}: ${(r.stderr ?? "").trim().split("\n")[0]}` };
|
|
541
|
+
return { ok: true, out: r.stdout };
|
|
542
|
+
};
|
|
543
|
+
|
|
544
|
+
function ghJson<T>(gh: Gh, args: string[]): Reading<T> {
|
|
545
|
+
const r = gh(args);
|
|
546
|
+
if (!r.ok) return unmeasured(r.why);
|
|
547
|
+
try {
|
|
548
|
+
return read(JSON.parse(r.out) as T);
|
|
549
|
+
} catch (e) {
|
|
550
|
+
return unmeasured(`gh returned text that is not JSON (${(e as Error).message})`);
|
|
551
|
+
}
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
/** `gh api --paginate` prints one JSON array per page; `--jq '.[]'` makes it one value per line. */
|
|
555
|
+
function ghLines<T>(gh: Gh, path: string, jq: string): Reading<T[]> {
|
|
556
|
+
const r = gh(["api", "--paginate", path, "--jq", jq]);
|
|
557
|
+
if (!r.ok) return unmeasured(r.why);
|
|
558
|
+
try {
|
|
559
|
+
return read(r.out.split("\n").filter(l => l.trim() !== "").map(l => JSON.parse(l) as T));
|
|
560
|
+
} catch (e) {
|
|
561
|
+
return unmeasured(`gh returned a line that is not JSON (${(e as Error).message})`);
|
|
562
|
+
}
|
|
563
|
+
}
|
|
564
|
+
|
|
565
|
+
interface OpenItem {
|
|
566
|
+
number: number;
|
|
567
|
+
title: string;
|
|
568
|
+
url: string;
|
|
569
|
+
pr: boolean;
|
|
570
|
+
assignees: string[];
|
|
571
|
+
labels: string[];
|
|
572
|
+
milestone: string | null;
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
export function gather(
|
|
576
|
+
root: string,
|
|
577
|
+
repo: string,
|
|
578
|
+
gh: Gh = liveGh,
|
|
579
|
+
now = new Date(),
|
|
580
|
+
health: (root: string) => Reading<HealthLine[]> = readHealth,
|
|
581
|
+
): StatusView {
|
|
582
|
+
const planPath = join(root, "project-state.json");
|
|
583
|
+
const plan = planLines(existsSync(planPath) ? readFileSync(planPath, "utf-8") : null, "project-state.json");
|
|
584
|
+
const { engineSpec, milestonePrefix } = readBoardInputs(root);
|
|
585
|
+
const queueLabel = readQueueLabel(root);
|
|
586
|
+
let specText: string | null = null;
|
|
587
|
+
if (engineSpec !== null && existsSync(join(root, engineSpec))) specText = readFileSync(join(root, engineSpec), "utf-8");
|
|
588
|
+
|
|
589
|
+
const milestones = ghLines<Milestone>(
|
|
590
|
+
gh,
|
|
591
|
+
`repos/${repo}/milestones?state=all&per_page=100`,
|
|
592
|
+
".[] | {title, open: .open_issues, closed: .closed_issues, url: .html_url}",
|
|
593
|
+
);
|
|
594
|
+
const phases: Reading<PhaseLine[]> =
|
|
595
|
+
milestonePrefix === null
|
|
596
|
+
? unmeasured("board.milestonePrefix is not set, so there is no focus family to show")
|
|
597
|
+
: milestones.kind === "UNMEASURED"
|
|
598
|
+
? unmeasured(milestones.why)
|
|
599
|
+
: read(phaseLines(milestones.value, milestonePrefix, specText));
|
|
600
|
+
const otherFamilies: Reading<FamilyLine[]> =
|
|
601
|
+
milestones.kind === "UNMEASURED" ? unmeasured(milestones.why) : read(otherFamilyLines(milestones.value, milestonePrefix ?? ""));
|
|
602
|
+
|
|
603
|
+
const items = ghLines<OpenItem>(
|
|
604
|
+
gh,
|
|
605
|
+
`repos/${repo}/issues?state=open&per_page=100`,
|
|
606
|
+
".[] | {number, title, url: .html_url, pr: (.pull_request != null), assignees: [.assignees[].login], labels: [.labels[].name], milestone: .milestone.title}",
|
|
607
|
+
);
|
|
608
|
+
const own = (i: OpenItem) => !i.pr;
|
|
609
|
+
const toLine = (i: OpenItem, note?: string): WorkLine => ({ number: i.number, title: i.title, url: i.url, note });
|
|
610
|
+
|
|
611
|
+
const inProgress: Reading<WorkLine[]> =
|
|
612
|
+
items.kind === "UNMEASURED"
|
|
613
|
+
? unmeasured(items.why)
|
|
614
|
+
: read([
|
|
615
|
+
...items.value.filter(i => i.pr).map(i => toLine(i, "pull request")),
|
|
616
|
+
...items.value.filter(i => own(i) && i.assignees.length > 0).map(i => toLine(i, i.assignees.join(", "))),
|
|
617
|
+
]);
|
|
618
|
+
|
|
619
|
+
// With no queue label there is no work queue to check, but an issue with no
|
|
620
|
+
// milestone is still outside every phase: count them, oldest first (#2330).
|
|
621
|
+
const unphased: Reading<WorkLine[]> =
|
|
622
|
+
items.kind === "UNMEASURED"
|
|
623
|
+
? unmeasured(items.why)
|
|
624
|
+
: read(
|
|
625
|
+
items.value
|
|
626
|
+
.filter(i => own(i) && i.milestone === null && (queueLabel === null || i.labels.includes(queueLabel)))
|
|
627
|
+
.sort((a, b) => (queueLabel === null ? a.number - b.number : 0))
|
|
628
|
+
.map(i => toLine(i)),
|
|
629
|
+
);
|
|
630
|
+
|
|
631
|
+
const phaseIssues = readPhaseIssues(gh, repo);
|
|
632
|
+
|
|
633
|
+
const decisions = readDecisions(gh, repo, items);
|
|
634
|
+
const ready = readReady(gh, root, items);
|
|
635
|
+
const healthReading = health(root);
|
|
636
|
+
const head = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf-8" });
|
|
637
|
+
|
|
638
|
+
const links: StatusView["links"] = [{ label: "Milestones", url: `https://github.com/${repo}/milestones` }];
|
|
639
|
+
// The board's address comes from the API, never built from config: a
|
|
640
|
+
// project owned by an organisation lives under /orgs/, one owned by a user
|
|
641
|
+
// under /users/, and the config does not say which (AI review of #2103).
|
|
642
|
+
const boardConfig = readBoardConfig(root);
|
|
643
|
+
if (boardConfig !== null) {
|
|
644
|
+
const r = ghJson<{ data?: { node?: { url?: string } } }>(gh, [
|
|
645
|
+
"api", "graphql", "-f", "query=query($p:ID!){node(id:$p){... on ProjectV2{url}}}", "-f", `p=${boardConfig.projectId}`,
|
|
646
|
+
]);
|
|
647
|
+
const url = r.kind === "READ" ? r.value.data?.node?.url : undefined;
|
|
648
|
+
links.push(
|
|
649
|
+
typeof url === "string" && url.startsWith("https://")
|
|
650
|
+
? { label: "The board", url }
|
|
651
|
+
: { label: "The board", url: null, why: r.kind === "UNMEASURED" ? r.why : "this token cannot see the project" },
|
|
652
|
+
);
|
|
653
|
+
}
|
|
654
|
+
if (queueLabel !== null) {
|
|
655
|
+
links.push({
|
|
656
|
+
label: `Open issues labelled ${queueLabel}`,
|
|
657
|
+
url: `https://github.com/${repo}/issues?q=${encodeURIComponent(`is:open label:${queueLabel}`)}`,
|
|
658
|
+
});
|
|
659
|
+
}
|
|
660
|
+
// The package, not a path in `repo`: in a consumer, scripts/status-view.ts
|
|
661
|
+
// is in node_modules, and a link built from the repository named a file the
|
|
662
|
+
// consumer does not have (#2330).
|
|
663
|
+
links.push({ label: "How this view is made", url: PACKAGE_PAGE });
|
|
664
|
+
|
|
665
|
+
return {
|
|
666
|
+
repo,
|
|
667
|
+
generatedAt: now.toISOString().replace(/\.\d+Z$/, "Z"),
|
|
668
|
+
commit: head.status === 0 ? head.stdout.trim() : null,
|
|
669
|
+
family: milestonePrefix,
|
|
670
|
+
goal: plan.goal,
|
|
671
|
+
stages: plan.stages,
|
|
672
|
+
phases,
|
|
673
|
+
otherFamilies,
|
|
674
|
+
phaseIssues,
|
|
675
|
+
inProgress,
|
|
676
|
+
ready,
|
|
677
|
+
decisions,
|
|
678
|
+
unphased,
|
|
679
|
+
unphasedScope: queueLabel === null ? "all" : "queued",
|
|
680
|
+
health: healthReading,
|
|
681
|
+
links,
|
|
682
|
+
};
|
|
683
|
+
}
|
|
684
|
+
|
|
685
|
+
/**
|
|
686
|
+
* Every open issue in a milestone, with its open blockers and assignees
|
|
687
|
+
* (#2330). One paged GraphQL read rather than a blocked-by call per issue:
|
|
688
|
+
* the workflow runs this on every issue event.
|
|
689
|
+
*/
|
|
690
|
+
const PHASE_ISSUES_QUERY =
|
|
691
|
+
"query($owner:String!,$name:String!,$after:String){repository(owner:$owner,name:$name){" +
|
|
692
|
+
"issues(first:100,after:$after,states:OPEN){pageInfo{hasNextPage endCursor} nodes{number title url " +
|
|
693
|
+
"milestone{title} assignees(first:10){nodes{login}} blockedBy(first:50){pageInfo{hasNextPage} nodes{number state}}}}}}";
|
|
694
|
+
|
|
695
|
+
/**
|
|
696
|
+
* Paged by hand, as `readReady` and `lib/live-issues.ts` do, rather than
|
|
697
|
+
* with `gh --paginate`: the query nests a second paged connection
|
|
698
|
+
* (`blockedBy`) in every node, and a hand loop follows the outer cursor by
|
|
699
|
+
* name instead of trusting gh to find the right `pageInfo` (review of #2334).
|
|
700
|
+
*/
|
|
701
|
+
function readPhaseIssues(gh: Gh, repo: string): Reading<PhaseIssue[]> {
|
|
702
|
+
const [owner, name] = repo.split("/");
|
|
703
|
+
const out: PhaseIssue[] = [];
|
|
704
|
+
let cursor: string | null = null;
|
|
705
|
+
for (let page = 0; page < 50; page++) {
|
|
706
|
+
const args = ["api", "graphql", "-f", `query=${PHASE_ISSUES_QUERY}`, "-f", `owner=${owner}`, "-f", `name=${name}`];
|
|
707
|
+
if (cursor !== null) args.push("-f", `after=${cursor}`);
|
|
708
|
+
const r = ghJson<{ data?: { repository?: { issues?: { pageInfo: { hasNextPage: boolean; endCursor: string }; nodes: any[] } } } }>(gh, args);
|
|
709
|
+
if (r.kind === "UNMEASURED") return unmeasured(r.why);
|
|
710
|
+
const conn = r.value.data?.repository?.issues;
|
|
711
|
+
if (!conn) return unmeasured("the open issues could not be read: the reply carried no issues connection");
|
|
712
|
+
for (const n of conn.nodes) {
|
|
713
|
+
if (!n?.milestone?.title) continue;
|
|
714
|
+
out.push({
|
|
715
|
+
number: n.number,
|
|
716
|
+
title: n.title,
|
|
717
|
+
url: n.url,
|
|
718
|
+
milestone: n.milestone.title,
|
|
719
|
+
assignees: (n.assignees?.nodes ?? []).map((a: { login: string }) => a.login),
|
|
720
|
+
blockers: (n.blockedBy?.nodes ?? []).filter((b: { state: string }) => b.state === "OPEN").map((b: { number: number }) => b.number),
|
|
721
|
+
moreBlockers: n.blockedBy?.pageInfo?.hasNextPage === true,
|
|
722
|
+
});
|
|
723
|
+
}
|
|
724
|
+
// The one decider of "is there another page" (SC-2721), so an empty or
|
|
725
|
+
// missing cursor on a page that says more exist is UNMEASURED, not the end.
|
|
726
|
+
const next = nextCursor(conn.pageInfo);
|
|
727
|
+
if (next.kind === "done") return read(out);
|
|
728
|
+
if (next.kind === "unreadable") return unmeasured(`the open issues could not be paged: ${next.why}`);
|
|
729
|
+
cursor = next.cursor;
|
|
730
|
+
}
|
|
731
|
+
return unmeasured("the open issues kept paging past 5,000");
|
|
732
|
+
}
|
|
733
|
+
|
|
734
|
+
/**
|
|
735
|
+
* What only a person can decide, as far as the tracker records it: an open
|
|
736
|
+
* pull request that changes a decision record (`docs/adr/`), which a person
|
|
737
|
+
* merges; open issues labelled `needs-criterion`, whose criterion text a
|
|
738
|
+
* person writes; and open issues labelled `needs-decision`, which a session
|
|
739
|
+
* parked for a person (#2138). A decision parked only in prose is still
|
|
740
|
+
* invisible here: on 2026-11-14 two were, and this section said nothing was
|
|
741
|
+
* waiting. Label the issue, or it is not on this list.
|
|
742
|
+
*/
|
|
743
|
+
function readDecisions(gh: Gh, repo: string, items: Reading<OpenItem[]>): Reading<WorkLine[]> {
|
|
744
|
+
if (items.kind === "UNMEASURED") return unmeasured(items.why);
|
|
745
|
+
const out: WorkLine[] = [];
|
|
746
|
+
for (const pr of items.value.filter(i => i.pr)) {
|
|
747
|
+
const files = ghLines<string>(gh, `repos/${repo}/pulls/${pr.number}/files?per_page=100`, ".[] | .filename | @json");
|
|
748
|
+
if (files.kind === "UNMEASURED") return unmeasured(`files of pull request #${pr.number}: ${files.why}`);
|
|
749
|
+
if (files.value.some(f => f.startsWith("docs/adr/"))) out.push({ number: pr.number, title: pr.title, url: pr.url, note: "decision record to merge" });
|
|
750
|
+
}
|
|
751
|
+
for (const i of items.value.filter(i => !i.pr)) {
|
|
752
|
+
const notes = [
|
|
753
|
+
...(i.labels.includes("needs-criterion") ? ["names no criterion"] : []),
|
|
754
|
+
...(i.labels.includes(NEEDS_DECISION) ? ["parked for a decision"] : []),
|
|
755
|
+
];
|
|
756
|
+
if (notes.length > 0) out.push({ number: i.number, title: i.title, url: i.url, note: notes.join("; ") });
|
|
757
|
+
}
|
|
758
|
+
return read(out);
|
|
759
|
+
}
|
|
760
|
+
|
|
761
|
+
/** The board's Ready lane: issues whose Status is `Ready`, in board order. */
|
|
762
|
+
function readReady(gh: Gh, root: string, items: Reading<OpenItem[]>): Reading<WorkLine[]> {
|
|
763
|
+
const board = readBoardConfig(root);
|
|
764
|
+
if (board === null) return unmeasured("no board is configured (board.id and board.fields.Criteria)");
|
|
765
|
+
if (items.kind === "UNMEASURED") return unmeasured(items.why);
|
|
766
|
+
const q =
|
|
767
|
+
"query($p:ID!,$c:String){node(id:$p){... on ProjectV2{items(first:100,after:$c){pageInfo{hasNextPage endCursor} " +
|
|
768
|
+
"nodes{status:fieldValueByName(name:\"Status\"){... on ProjectV2ItemFieldSingleSelectValue{name}} " +
|
|
769
|
+
"content{... on Issue{number state}}}}}}}";
|
|
770
|
+
const ready: number[] = [];
|
|
771
|
+
let cursor: string | null = null;
|
|
772
|
+
for (let page = 0; page < 50; page++) {
|
|
773
|
+
const args = ["api", "graphql", "-f", `query=${q}`, "-f", `p=${board.projectId}`];
|
|
774
|
+
if (cursor !== null) args.push("-f", `c=${cursor}`);
|
|
775
|
+
const r = ghJson<{ data?: { node?: { items?: { pageInfo: { hasNextPage: boolean; endCursor: string }; nodes: any[] } } } }>(gh, args);
|
|
776
|
+
if (r.kind === "UNMEASURED") return unmeasured(`the board could not be read: ${r.why}`);
|
|
777
|
+
const conn = r.value.data?.node?.items;
|
|
778
|
+
if (!conn) return unmeasured("the board could not be read: this token cannot see the project");
|
|
779
|
+
for (const n of conn.nodes) {
|
|
780
|
+
if (n?.status?.name === "Ready" && n?.content?.state === "OPEN" && typeof n.content.number === "number") ready.push(n.content.number);
|
|
781
|
+
}
|
|
782
|
+
if (!conn.pageInfo.hasNextPage) {
|
|
783
|
+
const byNumber = new Map(items.value.map(i => [i.number, i]));
|
|
784
|
+
return read(
|
|
785
|
+
ready.flatMap(n => {
|
|
786
|
+
const i = byNumber.get(n);
|
|
787
|
+
return i ? [{ number: i.number, title: i.title, url: i.url }] : [];
|
|
788
|
+
}),
|
|
789
|
+
);
|
|
790
|
+
}
|
|
791
|
+
cursor = conn.pageInfo.endCursor;
|
|
792
|
+
}
|
|
793
|
+
return unmeasured("the board kept paging past 5,000 items");
|
|
794
|
+
}
|
|
795
|
+
|
|
796
|
+
/** Board health: `board-conformance`'s own readings, written as JSON by the command itself (#1889). */
|
|
797
|
+
function readHealth(root: string): Reading<HealthLine[]> {
|
|
798
|
+
const dir = mkdtempSync(join(tmpdir(), "status-view-"));
|
|
799
|
+
try {
|
|
800
|
+
const out = join(dir, "readings.json");
|
|
801
|
+
const r = spawnSync("bun", [CLI_ENTRY, "board-conformance", "--emit-readings", out], {
|
|
802
|
+
cwd: root,
|
|
803
|
+
encoding: "utf-8",
|
|
804
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
805
|
+
});
|
|
806
|
+
if (!existsSync(out)) {
|
|
807
|
+
return unmeasured(`board-conformance wrote no readings (exit ${r.status}): ${(r.stderr ?? "").trim().split("\n").pop() ?? ""}`);
|
|
808
|
+
}
|
|
809
|
+
const rows = JSON.parse(readFileSync(out, "utf-8")) as HealthLine[];
|
|
810
|
+
if (!Array.isArray(rows) || rows.length === 0) return unmeasured("board-conformance wrote an empty list of readings");
|
|
811
|
+
return read(rows.map(x => ({ name: x.name, status: x.status, measured: x.measured, target: x.target })));
|
|
812
|
+
} catch (e) {
|
|
813
|
+
return unmeasured(`board-conformance's readings could not be parsed (${(e as Error).message})`);
|
|
814
|
+
} finally {
|
|
815
|
+
rmSync(dir, { recursive: true, force: true });
|
|
816
|
+
}
|
|
817
|
+
}
|
|
818
|
+
|
|
819
|
+
/**
|
|
820
|
+
* Write the rendered body into the issue that carries the marker, pinned or
|
|
821
|
+
* not. If there is none, create one. Then make sure it is pinned.
|
|
822
|
+
*
|
|
823
|
+
* **Found by marker among ALL open issues, not only the pinned ones** (AI
|
|
824
|
+
* review of #2103). Looking only at pinned issues meant a pin that failed
|
|
825
|
+
* once (the repository's three pin slots full, or a token without the right)
|
|
826
|
+
* created a fresh issue on every later run, because the one just created was
|
|
827
|
+
* never pinned and so was never found. Now it is found, reused, and the pin is
|
|
828
|
+
* retried. A pin that still fails is a warning annotation on its own line,
|
|
829
|
+
* and the body is still written.
|
|
830
|
+
*/
|
|
831
|
+
export function publish(body: string, repo: string, title: string, gh: Gh = liveGh): { ok: boolean; message: string } {
|
|
832
|
+
if (!body.startsWith(STATUS_MARKER)) return { ok: false, message: "refusing to publish a body without the status marker" };
|
|
833
|
+
const [owner, name] = repo.split("/");
|
|
834
|
+
const pinned = ghJson<{ data?: { repository?: { pinnedIssues?: { nodes: { issue: { number: number; body: string } }[] } } } }>(gh, [
|
|
835
|
+
"api", "graphql", "-f",
|
|
836
|
+
"query=query($o:String!,$n:String!){repository(owner:$o,name:$n){pinnedIssues(first:3){nodes{issue{number body}}}}}",
|
|
837
|
+
"-f", `o=${owner}`, "-f", `n=${name}`,
|
|
838
|
+
]);
|
|
839
|
+
if (pinned.kind === "UNMEASURED") return { ok: false, message: `UNMEASURED — the pinned issues could not be read: ${pinned.why}` };
|
|
840
|
+
const pinnedMine = (pinned.value.data?.repository?.pinnedIssues?.nodes ?? []).find(n => n.issue.body.startsWith(STATUS_MARKER));
|
|
841
|
+
let number: string | null = pinnedMine ? String(pinnedMine.issue.number) : null;
|
|
842
|
+
if (number === null) {
|
|
843
|
+
// Only an issue this workflow or a maintainer wrote. The marker is text
|
|
844
|
+
// anyone can type into an issue they open; reusing a stranger's issue
|
|
845
|
+
// would pin it, and its author could edit it back afterwards while it
|
|
846
|
+
// stays pinned (security review of #2103). A pinned issue needs no such
|
|
847
|
+
// check: pinning already takes maintainer rights.
|
|
848
|
+
const open = ghLines<{ number: number; body: string | null; login: string | null; association: string | null }>(
|
|
849
|
+
gh,
|
|
850
|
+
`repos/${repo}/issues?state=open&per_page=100`,
|
|
851
|
+
".[] | select(.pull_request == null) | {number, body, login: .user.login, association: .author_association}",
|
|
852
|
+
);
|
|
853
|
+
if (open.kind === "UNMEASURED") return { ok: false, message: `UNMEASURED — the open issues could not be read: ${open.why}` };
|
|
854
|
+
const found = open.value.find(i => (i.body ?? "").startsWith(STATUS_MARKER) && trustedAuthor(i.login, i.association));
|
|
855
|
+
if (found) number = String(found.number);
|
|
856
|
+
}
|
|
857
|
+
const dir = mkdtempSync(join(tmpdir(), "status-publish-"));
|
|
858
|
+
try {
|
|
859
|
+
const file = join(dir, "body.md");
|
|
860
|
+
writeFileSync(file, body);
|
|
861
|
+
let verb: string;
|
|
862
|
+
if (number !== null) {
|
|
863
|
+
const r = gh(["issue", "edit", number, "-R", repo, "--title", title, "--body-file", file]);
|
|
864
|
+
if (!r.ok) return { ok: false, message: r.why };
|
|
865
|
+
verb = "updated";
|
|
866
|
+
} else {
|
|
867
|
+
const created = gh(["issue", "create", "-R", repo, "--title", title, "--body-file", file]);
|
|
868
|
+
if (!created.ok) return { ok: false, message: created.why };
|
|
869
|
+
number = /\/issues\/(\d+)/.exec(created.out)?.[1] ?? null;
|
|
870
|
+
if (number === null) return { ok: false, message: `created an issue but could not read its number from: ${created.out.trim()}` };
|
|
871
|
+
verb = "created";
|
|
872
|
+
}
|
|
873
|
+
if (pinnedMine) return { ok: true, message: `${verb} #${number}` };
|
|
874
|
+
const pin = gh(["issue", "pin", number, "-R", repo]);
|
|
875
|
+
return pin.ok
|
|
876
|
+
? { ok: true, message: `${verb} and pinned #${number}` }
|
|
877
|
+
: {
|
|
878
|
+
ok: true,
|
|
879
|
+
message:
|
|
880
|
+
`${verb} #${number}\n::warning title=Status view::#${number} could not be pinned (${pin.why}). ` +
|
|
881
|
+
"Pin it once by hand; later runs find and reuse it either way.",
|
|
882
|
+
};
|
|
883
|
+
} finally {
|
|
884
|
+
rmSync(dir, { recursive: true, force: true });
|
|
885
|
+
}
|
|
886
|
+
}
|
|
887
|
+
|
|
888
|
+
/** The workflow's own identity, or someone with write access to the repository. */
|
|
889
|
+
export function trustedAuthor(login: string | null, association: string | null): boolean {
|
|
890
|
+
return login === "github-actions[bot]" || ["OWNER", "MEMBER", "COLLABORATOR"].includes(association ?? "");
|
|
891
|
+
}
|
|
892
|
+
|
|
893
|
+
/** The pinned issue's title: follows the focus family, never a fixed name. */
|
|
894
|
+
export function viewTitle(family: string | null): string {
|
|
895
|
+
return family === null ? "Where we are" : `Where we are: ${family}`;
|
|
896
|
+
}
|
|
897
|
+
|
|
898
|
+
function flag(argv: string[], name: string): string | null {
|
|
899
|
+
const i = argv.indexOf(name);
|
|
900
|
+
return i === -1 ? null : (argv[i + 1] ?? "");
|
|
901
|
+
}
|
|
902
|
+
|
|
903
|
+
/** `owner/name` from a git remote URL in any spelling git writes, or null for one that names no repository. */
|
|
904
|
+
export function repoFromRemote(url: string): string | null {
|
|
905
|
+
const m = /^(?:[a-z+]+:\/\/(?:[^@/]+@)?[^/]+\/|[^@/\s]+@[^:/\s]+:)([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(url.trim());
|
|
906
|
+
return m === null ? null : `${m[1]}/${m[2]}`;
|
|
907
|
+
}
|
|
908
|
+
|
|
909
|
+
/**
|
|
910
|
+
* Which repository to read: `--repo`, then `GITHUB_REPOSITORY`, then the
|
|
911
|
+
* checkout's `origin` remote (#2330), so `rungate board` run in a consumer
|
|
912
|
+
* reads that consumer with no flag. Null when none of the three names one.
|
|
913
|
+
*/
|
|
914
|
+
export function resolveRepo(argv: string[], env: Record<string, string | undefined>, root: string): string | null {
|
|
915
|
+
// An explicit `--repo` is used as given, even empty, so a bad flag is
|
|
916
|
+
// refused rather than guessed past. An empty GITHUB_REPOSITORY names
|
|
917
|
+
// nothing and falls through to the remote (review of #2334).
|
|
918
|
+
const flagged = flag(argv, "--repo");
|
|
919
|
+
if (flagged !== null) return flagged;
|
|
920
|
+
if (env.GITHUB_REPOSITORY !== undefined && env.GITHUB_REPOSITORY !== "") return env.GITHUB_REPOSITORY;
|
|
921
|
+
const origin = spawnSync("git", ["-C", root, "remote", "get-url", "origin"], { encoding: "utf-8" });
|
|
922
|
+
return origin.status === 0 ? repoFromRemote(origin.stdout) : null;
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
export function main(argv: string[], root = process.cwd()): number {
|
|
926
|
+
const repo = resolveRepo(argv, process.env, root);
|
|
927
|
+
if (repo === null || !/^[^/\s]+\/[^/\s]+$/.test(repo)) {
|
|
928
|
+
console.error("status-view: name the repository with --repo owner/name (or GITHUB_REPOSITORY), or run it in a checkout whose origin remote is the repository.");
|
|
929
|
+
return REFUSAL_EXIT;
|
|
930
|
+
}
|
|
931
|
+
const toPublish = flag(argv, "--publish");
|
|
932
|
+
if (toPublish !== null) {
|
|
933
|
+
if (toPublish === "" || !existsSync(toPublish)) {
|
|
934
|
+
console.error(`status-view: --publish needs a rendered file; "${toPublish}" does not exist.`);
|
|
935
|
+
return REFUSAL_EXIT;
|
|
936
|
+
}
|
|
937
|
+
const body = readFileSync(toPublish, "utf-8");
|
|
938
|
+
const family = readBoardInputs(root).milestonePrefix;
|
|
939
|
+
const r = publish(body, repo, viewTitle(family));
|
|
940
|
+
console.log(`status-view: ${r.message}`);
|
|
941
|
+
return r.ok ? 0 : REFUSAL_EXIT;
|
|
942
|
+
}
|
|
943
|
+
const view = gather(root, repo);
|
|
944
|
+
// Printed, never written to a path from argv: the caller redirects it.
|
|
945
|
+
// A write to an argv path is a site the spec-write sweep cannot follow
|
|
946
|
+
// (#1584), and a redirect in the workflow says where it goes in plain sight.
|
|
947
|
+
if (argv.includes("--markdown")) {
|
|
948
|
+
process.stdout.write(renderMarkdown(view));
|
|
949
|
+
} else {
|
|
950
|
+
process.stdout.write(renderText(view));
|
|
951
|
+
}
|
|
952
|
+
return 0;
|
|
953
|
+
}
|
|
954
|
+
|
|
955
|
+
if (import.meta.main) process.exit(main(process.argv.slice(2)));
|