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.
@@ -33,7 +33,7 @@
33
33
  * true by taking it.
34
34
  */
35
35
  import { spawnSync } from "child_process";
36
- import { existsSync, readFileSync } from "fs";
36
+ import { existsSync, readFileSync, readdirSync } from "fs";
37
37
  import { isAbsolute, join, relative } from "path";
38
38
  import { parseArgs } from "util";
39
39
  import { describeSpecSource, resolveSpecSource, type GitRunner } from "../lib/spec-source";
@@ -44,6 +44,7 @@ import { readBoardConfig, readBoardInputs, readQueueLabel } from "../lib/config-
44
44
  import { resolveConfig } from "../lib/config-loader";
45
45
  import { resolveRepoSlug } from "../lib/branch-cleanup";
46
46
  import {
47
+ ghWithoutGhToken,
47
48
  inMilestoneFamily,
48
49
  readIssueStates,
49
50
  readLiveIssues,
@@ -67,8 +68,10 @@ import {
67
68
  // SC-2615, SC-2616, SC-2617 — the three repository-wide populations.
68
69
  import { answerableIds, criterionAnswer, specCriteriaIn, specPathSweep } from "../lib/board-mirror";
69
70
  import { dependencyPlan } from "../lib/spec-deps";
70
- import type { DeclaredWork, FamilyIssue, PlannedEdge, RepoIssueCriteria, SpecDeferral, SpecPlacementRow } from "./board-conformance";
71
+ import type { ConsumerIntake, DeclaredWork, FamilyIssue, PlannedEdge, RepoIssueCriteria, SpecDeferral, SpecPlacementRow } from "./board-conformance";
72
+ import { CONSUMER_LABEL, trustedBodies, verdictIn, type IssueComment } from "../lib/consumer-triage";
71
73
  import { parseCriteria } from "../lib/spec-evidence";
74
+ import { hasDecompositionTable, newlyAccepted, parseDecompositionPlan } from "../lib/issue-decomposition";
72
75
 
73
76
  /**
74
77
  * THE one non-zero exit, declared once so `test/board-snapshot.test.ts` can
@@ -107,6 +110,12 @@ export interface BoardSnapshotGitHub {
107
110
  projectId: string,
108
111
  fieldName: string,
109
112
  ) => Promise<Map<number, ProjectFieldReading>>;
113
+ /**
114
+ * One issue's comments, with who wrote them — SC-2783, for the verdict
115
+ * marker. Optional so a caller that never reads comments says so by
116
+ * omission, and `consumer-intake` is then UNMEASURED rather than empty.
117
+ */
118
+ readComments?: (repo: string, number: number) => Promise<IssueComment[]>;
110
119
  }
111
120
 
112
121
  const LIVE_GITHUB: BoardSnapshotGitHub = {
@@ -117,8 +126,47 @@ const LIVE_GITHUB: BoardSnapshotGitHub = {
117
126
  readFieldIdentity: fieldId => readProjectFieldIdentity(fieldId),
118
127
  readFieldValues: (repo, numbers, projectId, fieldName) =>
119
128
  readProjectFieldValues(repo, numbers, projectId, fieldName),
129
+ readComments: async (repo, number) =>
130
+ ghWithoutGhToken(["api", "--paginate", `repos/${repo}/issues/${number}/comments?per_page=100`, "--jq", ".[] | [.body, .user.login, .author_association] | @json"])
131
+ .split("\n")
132
+ .filter(l => l.trim() !== "")
133
+ .map(l => {
134
+ const [body, author, association] = JSON.parse(l) as [string | null, string, string];
135
+ return { body: body ?? "", author, association };
136
+ }),
120
137
  };
121
138
 
139
+ /**
140
+ * The consumer-filed open issues, each with its age and verdict — SC-2783.
141
+ *
142
+ * `null` (the key is then omitted, and `consumer-intake` is UNMEASURED) when
143
+ * any part of the population cannot be read: comments were not readable, an
144
+ * issue carries no filing time, or a cut label list hides whether an issue is
145
+ * a consumer's at all. A partial intake would drop exactly the reports the
146
+ * reading exists to name.
147
+ */
148
+ export async function readConsumerIntake(
149
+ gh: BoardSnapshotGitHub,
150
+ repo: string,
151
+ open: readonly LiveIssue[],
152
+ takenAt: string,
153
+ ): Promise<ConsumerIntake | null> {
154
+ if (gh.readComments === undefined) return null;
155
+ if (open.some(i => i.labelsTruncated === true && !i.labels.includes(CONSUMER_LABEL))) return null;
156
+ const consumer = open.filter(i => i.labels.includes(CONSUMER_LABEL));
157
+ if (consumer.some(i => i.createdAt === undefined)) return null;
158
+ const issues: ConsumerIntake["issues"] = [];
159
+ try {
160
+ for (const i of consumer) {
161
+ const verdict = verdictIn(trustedBodies(await gh.readComments(repo, i.number)));
162
+ issues.push({ number: i.number, createdAt: i.createdAt!, milestone: i.milestone, verdict });
163
+ }
164
+ } catch {
165
+ return null; // a comment read that failed is a reading not taken, never "no marker"
166
+ }
167
+ return { takenAt, issues };
168
+ }
169
+
122
170
  const USAGE = `rungate board-snapshot <spec.md> --prefix <name> [--repo <owner/name>]
123
171
 
124
172
  --prefix the milestone name prefix, e.g. "Pipeline" for
@@ -252,6 +300,8 @@ export interface ProducedSnapshot {
252
300
  declaredWork?: DeclaredWork[];
253
301
  /** #2223 / E4: every open issue in any phase-milestone family, with the Criteria column. Absent when the column was not read. */
254
302
  familyIssues?: FamilyIssue[];
303
+ /** SC-2783. Absent when any consumer issue's labels, age or comments could not be read. */
304
+ consumerIntake?: ConsumerIntake;
255
305
  }
256
306
 
257
307
  /**
@@ -274,6 +324,8 @@ export interface ProducedSnapshot {
274
324
  export function readDeclaredWork(
275
325
  root: string,
276
326
  specs: readonly { path: string; state: SpecPlacementRow["state"]; deferred?: boolean; board?: { scope: string } }[],
327
+ /** Criteria an ADR this change accepts plans, from {@link plannedByUnmergedAdr} — #2323. */
328
+ planned: ReadonlyMap<string, string> = new Map(),
277
329
  ): { declaredWork?: DeclaredWork[] } {
278
330
  const work: DeclaredWork[] = [];
279
331
  for (const s of specs) {
@@ -292,7 +344,10 @@ export function readDeclaredWork(
292
344
  // the two readings agree on every criterion the spec parks.
293
345
  const placed = placementsById(content);
294
346
  for (const c of parseCriteria(content)) {
295
- if (!c.ticked) work.push({ kind: "criterion", id: c.id, source: s.path, ...outsidePhases(placed.get(c.id)) });
347
+ if (!c.ticked) {
348
+ const adr = planned.get(c.id);
349
+ work.push({ kind: "criterion", id: c.id, source: s.path, ...outsidePhases(placed.get(c.id)), ...(adr === undefined ? {} : { planned: adr }) });
350
+ }
296
351
  }
297
352
  }
298
353
  const statePath = join(root, "project-state.json");
@@ -329,6 +384,58 @@ export function readDeclaredWork(
329
384
  return { declaredWork: work };
330
385
  }
331
386
 
387
+ /** The ref an ADR's acceptance is read against: the main every reading here is about. */
388
+ export const PLANNED_ADR_REF = "origin/main";
389
+
390
+ /**
391
+ * Criteria planned by an ADR whose acceptance this tree introduces — #2323.
392
+ *
393
+ * An ADR that adds criteria to an opted-in spec states them before their
394
+ * issues exist, because merging the ADR is what files them (AGENTS.md rule 9
395
+ * step 3, `adr-accepted.yml`). On its own pull request `declared-work` would
396
+ * read each as "names no open issue", and the live stage ladder would refuse
397
+ * the merge that is the only way to file them.
398
+ *
399
+ * So a criterion a Decomposition row names is planned when that ADR is
400
+ * accepted in this tree and was not accepted at {@link PLANNED_ADR_REF}:
401
+ * `newlyAccepted`, the same decider `plan-issues --accepted-since` uses.
402
+ * An ADR already accepted on main is not this change's plan, and its missing
403
+ * issue is a real gap: `adr-accepted.yml` did not place it.
404
+ *
405
+ * Fails closed: a ref that does not resolve, a git that does not run, or an
406
+ * answer this cannot read exempts NOTHING, so every criterion reads as missing.
407
+ * Returns criterion id → the ADR's repo-relative path.
408
+ */
409
+ export function plannedByUnmergedAdr(root: string, git: GitRunner): Map<string, string> {
410
+ const dir = join(root, "docs", "adr");
411
+ if (!existsSync(dir)) return new Map();
412
+ const planned = new Map<string, string>();
413
+ for (const name of readdirSync(dir).filter(n => /^ADR-\d+.*\.md$/.test(n)).sort()) {
414
+ const rel = `docs/adr/${name}`;
415
+ const text = readFileSync(join(dir, name), "utf-8");
416
+ if (!hasDecompositionTable(text)) continue;
417
+ const at = git(["cat-file", "-e", `${PLANNED_ADR_REF}:${rel}`]);
418
+ if (at.code === null) return new Map();
419
+ let before: string | null = null;
420
+ if (at.ok) {
421
+ const shown = git(["show", `${PLANNED_ADR_REF}:${rel}`]);
422
+ if (!shown.ok) return new Map();
423
+ before = shown.stdout;
424
+ } else if (!/does not exist|exists on disk, but not in/.test(at.stderr)) {
425
+ // THE ONE fail-closed decider for the ref. A ref that does not resolve
426
+ // says "invalid object name", which is not "the path is absent at the
427
+ // ref", so an unreadable origin/main exempts nothing. A separate
428
+ // rev-parse probe would be a second decider for the same question.
429
+ return new Map();
430
+ }
431
+ if (!newlyAccepted(before, text)) continue;
432
+ const plan = parseDecompositionPlan(text);
433
+ if (plan.reading !== "MEASURED") continue;
434
+ for (const row of plan.rows) if (!planned.has(row.criterion)) planned.set(row.criterion, rel);
435
+ }
436
+ return planned;
437
+ }
438
+
332
439
  /** The path the deferral bank lives at, relative to the project root — SC-2734. */
333
440
  export const DEFERRAL_BANK = ".claude/spec-deferral-ratchet.json";
334
441
 
@@ -969,7 +1076,10 @@ export async function main(
969
1076
  // readings cannot disagree about which specs are in scope. A sweep that
970
1077
  // could not enumerate `specs/` emits no rows, and `declared-work` is then
971
1078
  // UNMEASURED rather than a stage-only count.
972
- const declared = placements.specPlacements === undefined ? {} : readDeclaredWork(root, placements.specPlacements);
1079
+ const declared =
1080
+ placements.specPlacements === undefined
1081
+ ? {}
1082
+ : readDeclaredWork(root, placements.specPlacements, plannedByUnmergedAdr(root, git(root)));
973
1083
 
974
1084
  // #2223 / E4. Emitted only when the column was actually queried: no board,
975
1085
  // a mismatched field, or a failed read all omit the key, and
@@ -984,8 +1094,13 @@ export async function main(
984
1094
  }
985
1095
  : {};
986
1096
 
1097
+ // SC-2783. Read at the same instant the snapshot is stamped, so the age the
1098
+ // reading computes is the age the producer saw.
1099
+ const producedAt = new Date().toISOString();
1100
+ const consumerIntake = await readConsumerIntake(gh, repo, openIssues, producedAt);
1101
+
987
1102
  const snapshot: ProducedSnapshot = {
988
- producedAt: new Date().toISOString(),
1103
+ producedAt,
989
1104
  spec: specArg,
990
1105
  phases: actions.map(a => ({ phase: a.phase, criteria: a.criteria, milestoneState: a.action })),
991
1106
  issues: snapshotIssues,
@@ -999,6 +1114,7 @@ export async function main(
999
1114
  ...edges,
1000
1115
  ...declared,
1001
1116
  ...family,
1117
+ ...(consumerIntake === null ? {} : { consumerIntake }),
1002
1118
  };
1003
1119
 
1004
1120
  process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
@@ -0,0 +1,235 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * `rungate consumer-triage` — SC-2782, ADR-020 Decision 1.
4
+ *
5
+ * Reads every open issue labelled `from-consumer` that carries no verdict
6
+ * marker, asks `triageVerdict` (`lib/consumer-triage.ts`, the one decider) for
7
+ * each, and prints the answer. With `--write` it applies it:
8
+ *
9
+ * 1. `board.queueLabel`, for every verdict but DUPLICATE;
10
+ * 2. the milestone, when the verdict names one the issue is not already in;
11
+ * 3. the marker comment, LAST.
12
+ *
13
+ * The label goes before the milestone (review of #2367) so that a milestone a
14
+ * run set always has the label beside it: that pair is the decider's evidence
15
+ * of a run that stopped before its marker (#2364). A run that dies after the
16
+ * label leaves no milestone, and the next run places the issue as new.
17
+ *
18
+ * The comment is last on purpose. The marker is what says "triaged", so it is
19
+ * written only once the moves it records have landed: a move that fails leaves
20
+ * no marker, and the next run (the daily sweep, SC-2784) asks again.
21
+ *
22
+ * Any tracker read that fails is UNMEASURED and nothing is written. A
23
+ * partial reading is worse than none here: an open issue missing from the
24
+ * corpus is a duplicate or an overlap the decider cannot see.
25
+ */
26
+ import { parseArgs } from "util";
27
+ import {
28
+ CONSUMER_LABEL,
29
+ trustedBodies,
30
+ triageVerdict,
31
+ verdictComment,
32
+ verdictIn,
33
+ type IssueComment,
34
+ type OpenPull,
35
+ type Triage,
36
+ type TriageIssue,
37
+ } from "../lib/consumer-triage";
38
+ import { enginePrefixReading, readQueueLabel } from "../lib/config-readers";
39
+ import type { PlacingFamily } from "../lib/issue-repair";
40
+ import { ghWithoutGhToken, readLiveIssues } from "../lib/live-issues";
41
+ import type { LiveMilestone } from "../lib/spec-placement";
42
+ import { LIVE_PLACE, placingFamilies } from "./plan-issues";
43
+
44
+ /** Every refusal exits through this. */
45
+ export const REFUSAL_EXIT = 1;
46
+
47
+ /**
48
+ * Each open pull request's full file list. `gh pr list --json files` returns
49
+ * one page of files per pull request, so a list shorter than `changedFiles`
50
+ * is cut, not short: it is read again page by page (review of #2356), and one
51
+ * still short is UNMEASURED, never a smaller overlap.
52
+ */
53
+ export function completePullFiles(
54
+ rows: readonly (OpenPull & { readonly changedFiles: number })[],
55
+ pageFiles: (number: number) => string[],
56
+ ): OpenPull[] {
57
+ return rows.map(({ changedFiles, ...r }) => {
58
+ if (r.files.length >= changedFiles) return r;
59
+ const files = pageFiles(r.number);
60
+ if (files.length < changedFiles) {
61
+ throw new Error(`pull request #${r.number} changes ${changedFiles} files and only ${files.length} could be read`);
62
+ }
63
+ return { ...r, files };
64
+ });
65
+ }
66
+
67
+ /** More open pull requests than this and the list is cut, so the overlap reading is UNMEASURED. */
68
+ export const PULL_LIMIT = 300;
69
+
70
+ const USAGE = "rungate consumer-triage --repo <owner/name> [--write] [--json] [--project-root <dir>]";
71
+
72
+ type OpenIssue = TriageIssue & { readonly labels: readonly string[]; readonly labelsTruncated?: boolean };
73
+
74
+ /** What the triage needs from the tracker. Injected so a test never shells out. */
75
+ export interface TriageGitHub {
76
+ milestones: (repo: string) => Promise<LiveMilestone[]>;
77
+ openIssues: (repo: string) => Promise<OpenIssue[]>;
78
+ openPulls: (repo: string) => Promise<OpenPull[]>;
79
+ /** Every comment on one issue, with its author, paged to the end. */
80
+ comments: (repo: string, number: number) => Promise<IssueComment[]>;
81
+ comment: (repo: string, number: number, body: string) => Promise<void>;
82
+ setMilestone: (repo: string, number: number, title: string) => Promise<void>;
83
+ addLabel: (repo: string, number: number, label: string) => Promise<void>;
84
+ /** The opted-in families — `placingFamilies`, the reader `plan-issues --place` uses. */
85
+ families: (root: string, live: readonly LiveMilestone[]) => { families: PlacingFamily[]; refusals: string[] };
86
+ }
87
+
88
+ const LIVE: TriageGitHub = {
89
+ milestones: LIVE_PLACE.milestones,
90
+ openIssues: async repo => (await readLiveIssues(repo, false)).filter(i => i.state === "OPEN"),
91
+ openPulls: async repo => {
92
+ const rows = JSON.parse(
93
+ ghWithoutGhToken(["pr", "list", "--repo", repo, "--state", "open", "--limit", String(PULL_LIMIT), "--json", "number,title,body,milestone,files,changedFiles"]),
94
+ ) as { number: number; title: string; body: string | null; milestone: { title: string } | null; files: { path: string }[] | null; changedFiles: number }[];
95
+ if (rows.length >= PULL_LIMIT) throw new Error(`${rows.length} open pull requests reached the read limit of ${PULL_LIMIT}, so the list is cut`);
96
+ return completePullFiles(
97
+ rows.map(r => ({ number: r.number, title: r.title, body: r.body, milestone: r.milestone?.title ?? null, files: (r.files ?? []).map(f => f.path), changedFiles: r.changedFiles })),
98
+ n =>
99
+ ghWithoutGhToken(["api", "--paginate", `repos/${repo}/pulls/${n}/files?per_page=100`, "--jq", ".[] | [.filename] | @json"])
100
+ .split("\n")
101
+ .filter(l => l.trim() !== "")
102
+ .map(l => (JSON.parse(l) as [string])[0]),
103
+ );
104
+ },
105
+ comments: async (repo, number) =>
106
+ // One JSON string per line: `--paginate` concatenates pages, so a single
107
+ // JSON document would not parse, and a raw body with a newline would read
108
+ // as two comments.
109
+ ghWithoutGhToken(["api", "--paginate", `repos/${repo}/issues/${number}/comments?per_page=100`, "--jq", ".[] | [.body, .user.login, .author_association] | @json"])
110
+ .split("\n")
111
+ .filter(l => l.trim() !== "")
112
+ .map(l => {
113
+ const [body, author, association] = JSON.parse(l) as [string, string, string];
114
+ return { body, author, association };
115
+ }),
116
+ comment: async (repo, number, body) => void ghWithoutGhToken(["issue", "comment", String(number), "--repo", repo, "--body", body]),
117
+ setMilestone: async (repo, number, title) => void ghWithoutGhToken(["issue", "edit", String(number), "--repo", repo, "--milestone", title]),
118
+ addLabel: async (repo, number, label) => void ghWithoutGhToken(["issue", "edit", String(number), "--repo", repo, "--add-label", label]),
119
+ families: (root, live) => placingFamilies(root, live),
120
+ };
121
+
122
+ interface Row {
123
+ number: number;
124
+ triage: Triage | { kind: "TRIAGED"; why: string };
125
+ results: string[];
126
+ }
127
+
128
+ export async function main(argv: string[], gh: TriageGitHub = LIVE): Promise<number> {
129
+ let values;
130
+ try {
131
+ ({ values } = parseArgs({
132
+ args: argv,
133
+ options: {
134
+ repo: { type: "string" },
135
+ write: { type: "boolean", default: false },
136
+ json: { type: "boolean", default: false },
137
+ "project-root": { type: "string" },
138
+ },
139
+ }));
140
+ } catch (e) {
141
+ console.error(`consumer-triage: ${(e as Error).message}\n\n${USAGE}`);
142
+ return REFUSAL_EXIT;
143
+ }
144
+ const repo = values.repo ?? process.env.GITHUB_REPOSITORY ?? "";
145
+ if (!/^[^/\s]+\/[^/\s]+$/.test(repo)) {
146
+ console.error(`consumer-triage: --repo <owner/name> is required (or GITHUB_REPOSITORY)\n\n${USAGE}`);
147
+ return REFUSAL_EXIT;
148
+ }
149
+ const root = values["project-root"] ?? process.cwd();
150
+ const write = values.write === true;
151
+
152
+ const engine = enginePrefixReading(root);
153
+ if (engine.unmeasured !== null) console.error(`consumer-triage: ${engine.unmeasured}`);
154
+ const queueLabel = readQueueLabel(root);
155
+
156
+ // Every read before any write, and any one failing refuses the whole run.
157
+ let issues: OpenIssue[];
158
+ let pulls: OpenPull[];
159
+ let families: PlacingFamily[];
160
+ const pending: OpenIssue[] = [];
161
+ const rows: Row[] = [];
162
+ try {
163
+ const live = await gh.milestones(repo);
164
+ const read = gh.families(root, live);
165
+ if (read.refusals.length > 0) {
166
+ console.error(`consumer-triage: UNMEASURED — the opted-in families could not be read, so nothing was triaged:`);
167
+ for (const r of read.refusals) console.error(` - ${r}`);
168
+ return REFUSAL_EXIT;
169
+ }
170
+ families = read.families;
171
+ issues = (await gh.openIssues(repo)).sort((a, b) => a.number - b.number);
172
+ pulls = await gh.openPulls(repo);
173
+ const cut = issues.filter(i => i.labelsTruncated === true && !i.labels.includes(CONSUMER_LABEL));
174
+ if (cut.length > 0) {
175
+ throw new Error(`${cut.map(i => `#${i.number}`).join(", ")} carry more labels than one page holds, so whether they are from a consumer is unread`);
176
+ }
177
+ for (const i of issues.filter(i => i.labels.includes(CONSUMER_LABEL))) {
178
+ const already = verdictIn(trustedBodies(await gh.comments(repo, i.number)));
179
+ if (already !== null) rows.push({ number: i.number, triage: { kind: "TRIAGED", why: `already carries a ${already} verdict` }, results: [] });
180
+ else pending.push(i);
181
+ }
182
+ } catch (e) {
183
+ console.error(`consumer-triage: UNMEASURED — could not read the tracker, so nothing was triaged:`);
184
+ console.error(` - ${(e as Error).message}`);
185
+ return REFUSAL_EXIT;
186
+ }
187
+
188
+ const ctx = { openIssues: issues, openPulls: pulls, families, enginePrefix: engine.prefix, queueLabel };
189
+ for (const issue of pending) {
190
+ const triage = triageVerdict(issue, ctx);
191
+ const row: Row = { number: issue.number, triage, results: [] };
192
+ rows.push(row);
193
+ if (!write || triage.kind === "LEFT" || triage.kind === "REFUSED") continue;
194
+ try {
195
+ if (triage.kind !== "DUPLICATE" && queueLabel !== null && !issue.labels.includes(queueLabel)) {
196
+ await gh.addLabel(repo, issue.number, queueLabel);
197
+ row.results.push(`label ${queueLabel}`);
198
+ }
199
+ if (triage.kind !== "DUPLICATE" && triage.milestone !== issue.milestone) {
200
+ await gh.setMilestone(repo, issue.number, triage.milestone);
201
+ row.results.push(`milestone "${triage.milestone}"`);
202
+ }
203
+ await gh.comment(repo, issue.number, verdictComment(triage));
204
+ row.results.push("verdict comment");
205
+ } catch (e) {
206
+ row.results.push(`FAILED: ${(e as Error).message} — no verdict comment, so the next run tries again`);
207
+ }
208
+ }
209
+ rows.sort((a, b) => a.number - b.number);
210
+
211
+ const refused = rows.filter(r => r.triage.kind === "REFUSED");
212
+ const failed = rows.filter(r => r.results.some(x => x.startsWith("FAILED")));
213
+ const exit = refused.length > 0 || failed.length > 0 ? REFUSAL_EXIT : 0;
214
+
215
+ if (values.json === true) {
216
+ console.log(JSON.stringify({ repo, write, queueLabel, rows }, null, 2));
217
+ return exit;
218
+ }
219
+ console.log(`consumer-triage — ${repo}: ${rows.length} open ${CONSUMER_LABEL} issue(s), ${pending.length} with no verdict`);
220
+ if (queueLabel === null) console.log(` board.queueLabel is not configured, so no queue label is given (UNMEASURED, not an empty queue)`);
221
+ for (const r of rows) {
222
+ const t = r.triage;
223
+ const what = t.kind === "DUPLICATE" ? `DUPLICATE of #${t.of}` : t.kind === "OVERLAPS" ? `OVERLAPS #${t.of} → "${t.milestone}"` : "milestone" in t ? `${t.kind} → "${t.milestone}"` : t.kind;
224
+ console.log(` #${r.number} ${what} — ${t.why}`);
225
+ for (const x of r.results) console.log(` ${x}`);
226
+ }
227
+ if (!write && pending.length > 0) console.log(`\nNothing written. Re-run with --write to apply.`);
228
+ if (refused.length > 0) console.error(`\nconsumer-triage: ${refused.length} issue(s) could not be given a verdict without guessing.`);
229
+ if (failed.length > 0) console.error(`\nconsumer-triage: ${failed.length} issue(s) FAILED to write.`);
230
+ return exit;
231
+ }
232
+
233
+ if (import.meta.main) {
234
+ process.exit(await main(process.argv.slice(2)));
235
+ }
@@ -21,18 +21,26 @@
21
21
  * only hand-authored dependencies in the repository, so this prints them and
22
22
  * stops. See `lib/spec-deps.ts`.
23
23
  *
24
- * ## Why one call per blocked issue
24
+ * ## Why the edges are grouped by blocked issue
25
25
  *
26
- * `gh issue edit <N> --add-blocked-by <M>` takes the flag repeatedly. The
27
- * live convergence set is 194 edges over 37 blocked issues, so grouping is
28
- * 37 mutations rather than 194. `groupByBlocked` decides the grouping and is
29
- * tested on its own, because the group IS what reaches GitHub.
26
+ * `groupByBlocked` decides the grouping and is tested on its own, because the
27
+ * group IS what reaches GitHub: each group is one `addBlockers` call, which
28
+ * writes its links and reads them back once. Since #2345 the links go through
29
+ * the REST dependencies endpoint, one POST per link, because
30
+ * `issue edit --add-blocked-by` is missing from older runners' `gh`. So the
31
+ * live convergence set's 194 edges over 37 blocked issues are 194 writes and
32
+ * 37 read-backs, plus one id read per distinct blocker (`BLOCKER_IDS`).
30
33
  */
34
+ import { addBlockers } from "../lib/blocked-by-write";
31
35
  import { parseArgs } from "util";
32
36
  import { createGitHubClient } from "../lib/github";
33
37
  import { dependencyPlan, groupByBlocked } from "../lib/spec-deps";
34
38
  import type { DepEdge, DepIssue } from "../lib/spec-deps";
35
39
  import { ghWithoutGhToken, inMilestoneFamily, readLiveIssues, readMilestonePrefix } from "../lib/live-issues";
40
+ import { existsSync, readFileSync } from "fs";
41
+ import { join } from "path";
42
+ import { specFilesIn } from "../lib/board-mirror";
43
+ import { phaseOrderFor } from "../lib/spec-placement";
36
44
 
37
45
  /**
38
46
  * THE one non-zero exit. One site, so `test/plan-deps.test.ts` can build a
@@ -91,14 +99,17 @@ export interface PlanDepsGitHub {
91
99
  addBlockers: (repo: string, blocked: number, blockers: readonly number[]) => Promise<void>;
92
100
  }
93
101
 
102
+ /** Each blocker's database id, read once per run however many issues it blocks. */
103
+ const BLOCKER_IDS = new Map<string, number>();
104
+
94
105
  async function liveAddBlockers(
95
106
  repo: string,
96
107
  blocked: number,
97
108
  blockers: readonly number[],
98
109
  ): Promise<void> {
99
- const args = ["issue", "edit", String(blocked), "--repo", repo];
100
- for (const b of blockers) args.push("--add-blocked-by", String(b));
101
- ghWithoutGhToken(args);
110
+ // Through the REST dependencies API, one link at a time: `issue edit
111
+ // --add-blocked-by` does not exist in an older runner's gh (#2345).
112
+ addBlockers(repo, blocked, blockers, ghWithoutGhToken, BLOCKER_IDS);
102
113
  }
103
114
 
104
115
  const LIVE_GITHUB: PlanDepsGitHub = {
@@ -227,6 +238,45 @@ export async function main(argv: string[], gh: PlanDepsGitHub = LIVE_GITHUB): Pr
227
238
 
228
239
  const prefix = prefixRead.prefix;
229
240
 
241
+ // `board: { phaseOrder: false }`: the family's spec opts out of phase-order
242
+ // links. Read before the network, like the prefix, so a setting that cannot
243
+ // be read is refused without a tracker call, and an opt-out writes nothing
244
+ // at all. Absent specs/ is a tree where nothing can opt out, so it is on.
245
+ const root = values["project-root"] ?? process.cwd();
246
+ if (existsSync(join(root, "specs"))) {
247
+ const sweep = specFilesIn(root);
248
+ if (sweep.reading === "UNMEASURED") {
249
+ return refuse(values.json, `UNMEASURED — the specs could not be listed to read board.phaseOrder: ${sweep.reasons.join("; ")}`);
250
+ }
251
+ // A listed spec the read refuses is UNMEASURED, named, like every other
252
+ // spec sweep — never an uncaught throw (review of #2352).
253
+ const texts: { path: string; text: string }[] = [];
254
+ for (const p of sweep.paths) {
255
+ try {
256
+ texts.push({ path: p, text: readFileSync(join(root, p), "utf-8") });
257
+ } catch (e) {
258
+ return refuse(values.json, `UNMEASURED — ${p} could not be read to find board.phaseOrder: ${(e as Error).message}`);
259
+ }
260
+ }
261
+ const order = phaseOrderFor(texts, prefix);
262
+ if (order.kind === "unreadable") return refuse(values.json, `UNMEASURED — ${order.why}`);
263
+ if (order.kind === "off") {
264
+ const why = `${prefix}: ${order.spec} declares board.phaseOrder: false, so no phase-order links are written; real blocked-by links are untouched`;
265
+ if (values.json) {
266
+ console.log(
267
+ JSON.stringify(
268
+ { reading: "PHASE_ORDER_OFF", unmeasuredReasons: [], phases: [], missing: [], present: [], extra: [], unphased: [], frontier: null, results: [], wrote: "phase-order-off", why },
269
+ null,
270
+ 2,
271
+ ),
272
+ );
273
+ } else {
274
+ console.log(`plan-deps: ${why}`);
275
+ }
276
+ return 0;
277
+ }
278
+ }
279
+
230
280
  // Only now does anything touch the network. `createClient` is inside the
231
281
  // same `try` as the read: repairing only the call a finding named would
232
282
  // leave the other one on the same path throwing the same way.
@@ -28,6 +28,7 @@
28
28
  * issues it is itself demoting, and touches no others. The cause and the
29
29
  * cleanup are one action.
30
30
  */
31
+ import { addBlockers, removeBlocker } from "../lib/blocked-by-write";
31
32
  import { existsSync, readFileSync, readdirSync } from "fs";
32
33
  import { spawnSync } from "child_process";
33
34
  import { isAbsolute, join, relative, sep } from "path";
@@ -158,7 +159,8 @@ const LIVE_GITHUB: PlanIssuesGitHub = {
158
159
  gh(["issue", "edit", String(number), "--repo", repo, "--remove-milestone"]);
159
160
  },
160
161
  removeBlockedBy: async (repo, blocked, blocker) => {
161
- gh(["issue", "edit", String(blocked), "--repo", repo, "--remove-blocked-by", String(blocker)]);
162
+ // REST, not `issue edit --remove-blocked-by`, which an older runner's gh lacks (#2345).
163
+ removeBlocker(repo, blocked, blocker, args => gh([...args]), BLOCKER_IDS);
162
164
  },
163
165
  // PAGINATED, for the reason `LIVE_DECOMPOSE.milestones` gives: a phase
164
166
  // milestone on page two would read as absent and refuse the run.
@@ -348,7 +350,8 @@ const LIVE_DECOMPOSE: DecomposeGitHub = {
348
350
  return n;
349
351
  },
350
352
  addBlockedBy: async (repo, blocked, blocker) => {
351
- gh(["issue", "edit", String(blocked), "--repo", repo, "--add-blocked-by", String(blocker)]);
353
+ // REST, not `issue edit --add-blocked-by`, which an older runner's gh lacks (#2345).
354
+ addBlockers(repo, blocked, [blocker], args => gh([...args]), BLOCKER_IDS);
352
355
  },
353
356
  blockedBy: async (repo, issue) => {
354
357
  const out = gh([
@@ -666,7 +669,10 @@ export interface PlaceGitHub {
666
669
  setMilestone: (repo: string, number: number, title: string) => Promise<void>;
667
670
  }
668
671
 
669
- const LIVE_PLACE: PlaceGitHub = {
672
+ /** Each blocker's database id, read once per run however many issues it blocks (#2345). */
673
+ const BLOCKER_IDS = new Map<string, number>();
674
+
675
+ export const LIVE_PLACE: PlaceGitHub = {
670
676
  milestones: LIVE_GITHUB.milestones,
671
677
  openIssues: async repo => (await readLiveIssues(repo, false)).filter(i => i.state === "OPEN"),
672
678
  setMilestone: LIVE_GITHUB.setMilestone,