@futurelastic/colab-handbook 1.21.0-rc.4 → 1.21.0-rc.5

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/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.21.0-rc.4"
36
+ "version": "1.21.0-rc.5"
37
37
  }
package/tools/colab CHANGED
@@ -5283,11 +5283,16 @@ function cmdCiGrantReviewer(num, opts) {
5283
5283
  throw new UserError(`"${opts.branch}" has no completed, successful CI run at ${shortSha(head)} (status=${evRun.status} conclusion=${evRun.conclusion || 'none'}) — a reviewer grant needs the branch green at its exact head`);
5284
5284
  }
5285
5285
 
5286
- // Every claimed cure is a red check on trunk at the red sha.
5287
- const redRunJobs = trunkRedRunJobs(repoAbs, trunk, redSha);
5288
- const redJobs = redRunJobs === null ? null : ciCure.redJobSet(redRunJobs);
5286
+ // Every claimed cure is a red check on trunk at the red sha — the reviewer's red set (#730), which
5287
+ // also names the jobs of a cancelled run whose re-run is spent; each such cure is then proven on the
5288
+ // branch's own run of the same workflow and job at the head.
5289
+ const redJobs = trunkReviewerRedJobs(repoAbs, trunk, redSha);
5289
5290
  const cr = ciGrant.curesAreRed(ciGrant.parseCures(rec.cures), redJobs);
5290
5291
  if (!cr.ok) throw new UserError(`${cr.reason}; nothing was posted`);
5292
+ const proof = ciGrant.spentCancelledCuresProven(cr.matched, () => branchHeadJobs(repoAbs, opts.branch, head));
5293
+ if (!proof.ok) {
5294
+ throw new UserError(`${proof.reason}; nothing was posted. Re-run once that workflow has succeeded on the branch head, or a human grants it: \`COLAB_HUMAN=1 colab ci-grant ${num} --branch ${opts.branch}\``);
5295
+ }
5291
5296
 
5292
5297
  rec.red = redSha.toLowerCase();
5293
5298
  const v = ciGrant.validateReviewRecord(rec);
@@ -12795,10 +12800,10 @@ function shipCiGrants(repoAbs, gh, issues, branch, trunk, redSha) {
12795
12800
  // host's revoke window, and trunk's red checks at redSha, read lazily and at most once.
12796
12801
  policy: ciGrant.parseGrantPolicy(projectDocAt(repoAbs, trunk)).policy,
12797
12802
  now: Date.now(),
12798
- redJobs: () => {
12799
- const jobs = trunkRedRunJobs(repoAbs, trunk, redSha);
12800
- return jobs === null ? null : ciCure.redJobSet(jobs);
12801
- },
12803
+ // #730: the reviewer's red set (spent cancelled runs included), and the branch head's jobs that
12804
+ // prove a spent cancelled cure — the same two reads `colab ci-grant --role ci-reviewer` mints on.
12805
+ redJobs: () => trunkReviewerRedJobs(repoAbs, trunk, redSha),
12806
+ branchJobs: () => (evRun && evRun.sha ? branchHeadJobs(repoAbs, branch, evRun.sha) : null),
12802
12807
  });
12803
12808
  }
12804
12809
 
@@ -12992,6 +12997,49 @@ function trunkRedRunJobs(repoAbs, trunk, sha, limit) {
12992
12997
  return out;
12993
12998
  }
12994
12999
 
13000
+ /**
13001
+ * #730 — the red-job set the REVIEWER grant reads at `sha` (mint and ship; the cure rule keeps
13002
+ * `trunkRedRunJobs` + `redJobSet`). Same run read as `trunkRedRunJobs`, plus the jobs of every
13003
+ * cancelled run whose one re-run is spent (ci-cure.js `spentCancelledRuns`), shaped by the pure
13004
+ * `reviewerRedJobSet`. `null` on any failed read, or when nothing red can be named.
13005
+ */
13006
+ function trunkReviewerRedJobs(repoAbs, trunk, sha) {
13007
+ const runsAll = git.ghRunsForCommit(repoAbs, trunk, sha);
13008
+ const runs = runsAll === null ? null : runsAll.filter(git.isRepoOwnedRun);
13009
+ if (runs === null || runs.length === 0) return null;
13010
+ const failedRuns = runs.filter((r) => r.status === 'completed' && r.conclusion !== 'success' && r.conclusion !== 'cancelled');
13011
+ const jobsOf = (list) => {
13012
+ const out = [];
13013
+ for (const r of list) {
13014
+ const jobs = git.ghRunJobs(repoAbs, r.databaseId);
13015
+ if (jobs === null) return null;
13016
+ out.push(...jobs.map((j) => ({ ...j, workflowName: r.workflowName || '', workflowId: r.workflowId ?? null })));
13017
+ }
13018
+ return out;
13019
+ };
13020
+ const failedRunJobs = jobsOf(failedRuns);
13021
+ const cancelledRunJobs = jobsOf(ciCure.spentCancelledRuns(runs));
13022
+ if (failedRunJobs === null || cancelledRunJobs === null) return null;
13023
+ return ciCure.reviewerRedJobSet({ failedRunJobs, cancelledRunJobs });
13024
+ }
13025
+
13026
+ /**
13027
+ * #730 — every job of every run on `branch` at `sha`, tagged with its run's `workflowName`,
13028
+ * `runStatus` and `runConclusion`: what ci-grant.js `spentCancelledCuresProven` reads. `null` on
13029
+ * any failed read — never an empty set standing for "could not tell".
13030
+ */
13031
+ function branchHeadJobs(repoAbs, branch, sha) {
13032
+ const runs = git.ghRunsForCommit(repoAbs, branch, sha);
13033
+ if (runs === null) return null;
13034
+ const out = [];
13035
+ for (const r of runs.filter(git.isRepoOwnedRun)) {
13036
+ const jobs = git.ghRunJobs(repoAbs, r.databaseId);
13037
+ if (jobs === null) return null;
13038
+ out.push(...jobs.map((j) => ({ ...j, workflowName: r.workflowName || '', runStatus: r.status || null, runConclusion: r.conclusion || null })));
13039
+ }
13040
+ return out;
13041
+ }
13042
+
12995
13043
  /**
12996
13044
  * The red-job set at the red sha the prior exemption on this continuous red was measured against
12997
13045
  * (#477) — read only when condition 3 refused as stacked AND job evidence exists (containment + 2a
@@ -800,6 +800,52 @@ function redJobSet(redRunJobs) {
800
800
  return shaped.redJobs.map((j) => ({ name: j.name, workflowName: j.workflowName }));
801
801
  }
802
802
 
803
+ /** Run conclusions that executed nothing — a run of a workflow carrying only these never finished. */
804
+ const NEUTRAL_RUN_CONCLUSIONS = new Set(['cancelled', 'skipped']);
805
+
806
+ /**
807
+ * #730 — the runs at one trunk sha that make it red by being cancelled with their one keyed re-run
808
+ * already spent (#628 asks for exactly one re-run): a NAMED, completed, `cancelled` run whose
809
+ * `attempt` is greater than 1, in a workflow with no other run at the sha that ran (anything but
810
+ * `cancelled`/`skipped` — such a run supersedes it, #92). An unknown `attempt` is not a spent one:
811
+ * the re-run is still the next step, so the run stays out. PURE; `runs` are run rows (repo-owned).
812
+ */
813
+ function spentCancelledRuns(runs) {
814
+ if (!Array.isArray(runs)) return [];
815
+ const ran = new Set(runs.filter((r) => r && r.workflowName && !NEUTRAL_RUN_CONCLUSIONS.has(r.conclusion)).map((r) => r.workflowName));
816
+ return runs.filter((r) => r && r.workflowName && r.status === 'completed' && r.conclusion === 'cancelled'
817
+ && Number(r.attempt) > 1 && !ran.has(r.workflowName));
818
+ }
819
+
820
+ /**
821
+ * #730 — the red-job set the REVIEWER grant reads (mint and ship), never the cure rule's: the cure
822
+ * path's `redJobSet` over the failed runs, plus every job of a spent cancelled run
823
+ * (`spentCancelledRuns`) that did not pass or skip. Those carry `spentCancelled: true`, which makes the
824
+ * grant prove each such cure on the branch's own run of the same workflow and job
825
+ * (ci-grant.js `spentCancelledCuresProven`) — a cancelled check verified nothing on either side, so
826
+ * the branch's run must have.
827
+ *
828
+ * `failedRunJobs` / `cancelledRunJobs` are the raw job rows (tagged `workflowName`) of each kind of
829
+ * run. `null` when either is not an array or any job is unfinished (unmeasurable), and when both sets
830
+ * are empty — the same "nothing red could be named" answer the cure path gives. PURE.
831
+ */
832
+ function reviewerRedJobSet({ failedRunJobs, cancelledRunJobs } = {}) {
833
+ if (!Array.isArray(failedRunJobs) || !Array.isArray(cancelledRunJobs)) return null;
834
+ const failed = failedRunJobs.length ? redJobSet(failedRunJobs) : [];
835
+ if (failed === null) return null;
836
+ if (cancelledRunJobs.some((j) => !j || j.status !== 'completed')) return null;
837
+ const out = [...failed];
838
+ const seen = new Set(out.map(jobKey));
839
+ for (const j of cancelledRunJobs) {
840
+ if (j.conclusion === 'success' || j.conclusion === 'skipped') continue;
841
+ const red = { name: j.name, workflowName: j.workflowName || '', spentCancelled: true };
842
+ if (seen.has(jobKey(red))) continue;
843
+ seen.add(jobKey(red));
844
+ out.push(red);
845
+ }
846
+ return out.length ? out : null;
847
+ }
848
+
803
849
  /**
804
850
  * Progress past condition 3 (#477) — PURE. `prior` is the red-job set at the red sha the most recent
805
851
  * exemption on this continuous red was measured against; `current` the red-job set at trunk's red
@@ -1051,5 +1097,5 @@ function admittedText(admitted) {
1051
1097
 
1052
1098
  module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, manifestStepProof, shapeJobEvidence, dryRunDispatchPlan,
1053
1099
  cureDispatchPlan, dispatchEvidence,
1054
- priorRedShaFromMessage, redJobSet, redSetShrank,
1100
+ priorRedShaFromMessage, redJobSet, redSetShrank, spentCancelledRuns, reviewerRedJobSet,
1055
1101
  WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL, PYTHON_MANIFEST_REFUSAL, PUBLISH_STEP_MARKER, DRY_RUN_STEP, DRY_RUN_CONDITIONAL_STEPS };
@@ -259,10 +259,10 @@ function syncedFrom(opts, headSha, redSha, evidenceSha) {
259
259
  * `records` maps issue number → the `ghIssueView` result for that issue, or `null` on a failed
260
260
  * read (the caller's job, not this function's).
261
261
  *
262
- * `opts` (#504) additionally carries `{ policy, now, redJobs }` for the reviewer role: per issue a
263
- * live human grant wins, unchanged; otherwise an issue carrying a live reviewer grant is judged by
264
- * evaluateReviewerIssue (records must then include `title`). `redJobs` is a thunk, called at most
265
- * once per set. A granted reviewer entry carries `role: 'ci-reviewer'`, `reviewer`, `head`, `cures`.
262
+ * `opts` (#504) additionally carries `{ policy, now, redJobs, branchJobs }` for the reviewer role: per
263
+ * issue a live human grant wins, unchanged; otherwise an issue carrying a live reviewer grant is
264
+ * judged by evaluateReviewerIssue (records must then include `title`). `redJobs` and `branchJobs`
265
+ * (#730) are thunks, each called at most once per set. A granted reviewer entry carries `role: 'ci-reviewer'`, `reviewer`, `head`, `cures`.
266
266
  */
267
267
  function evaluateShipSet(issues, records, branch, trunk, redTrunkSha, evidence, labelName, opts) {
268
268
  const list = Array.isArray(issues) ? issues : [];
@@ -281,6 +281,14 @@ function evaluateShipSet(issues, records, branch, trunk, redTrunkSha, evidence,
281
281
  }
282
282
  return redJobsMemo;
283
283
  };
284
+ // #730: the branch head's jobs, read only when a cure names a spent cancelled check.
285
+ let branchJobsMemo;
286
+ const branchJobs = () => {
287
+ if (branchJobsMemo === undefined) {
288
+ try { branchJobsMemo = opts && typeof opts.branchJobs === 'function' ? opts.branchJobs() : null; } catch (_) { branchJobsMemo = null; }
289
+ }
290
+ return branchJobsMemo;
291
+ };
284
292
  for (const n of list) {
285
293
  const rec = records ? records[n] : null;
286
294
  const v = evaluateIssue(rec, branch, trunk, redTrunkSha, evidence, n, labelName, opts);
@@ -294,7 +302,7 @@ function evaluateShipSet(issues, records, branch, trunk, redTrunkSha, evidence,
294
302
  const hasReviewer = !!rec && liveGrantRecords(rec.comments).some((g) => g.role !== 'human');
295
303
  if (!hasReviewer) { missing.push({ issue: n, reason: v.reason }); continue; }
296
304
  const r = evaluateReviewerIssue(rec, { branch, trunk, redTrunkSha, evidence, issueNum: n, labelName,
297
- policy: opts && opts.policy, now: opts && opts.now, redJobs });
305
+ policy: opts && opts.policy, now: opts && opts.now, redJobs, branchJobs });
298
306
  if (r.ok) {
299
307
  granted.push({ issue: n, role: REVIEWER_ROLE, reviewer: r.grant.reviewer, head: r.grant.head,
300
308
  branch: r.grant.branch, by: r.grant.login, at: r.grant.at, redSha: r.grant.redSha, evidenceSha: r.grant.head,
@@ -535,7 +543,40 @@ function curesAreRed(cures, redJobs) {
535
543
  return { ok: false, unmatched,
536
544
  reason: `the review claims to cure ${unmatched.map((c) => `\`${c}\``).join(', ')}, which ${unmatched.length === 1 ? 'is' : 'are'} not red on trunk at that sha (red: ${red})` };
537
545
  }
538
- return { ok: true, unmatched: [], reason: '' };
546
+ // #730: the red job each cure names, so a caller can prove the spent-cancelled ones on the branch.
547
+ const matched = list.map((c) => redJobs.find((j) => checkLabel(j) === c) || redJobs.find((j) => j.name === c));
548
+ return { ok: true, unmatched: [], matched, reason: '' };
549
+ }
550
+
551
+ /**
552
+ * #730 — a cure naming a spent cancelled check (ci-cure.js `reviewerRedJobSet`, `spentCancelled`)
553
+ * is proven only by the branch's OWN run of that workflow: a completed `success` run whose job of the
554
+ * same name concluded `success` too. "The branch's CI is green" is not enough here — the trunk check
555
+ * verified nothing, so a branch run of it that was itself cancelled or skipped proves nothing either,
556
+ * and a green sibling workflow must never stand in for it.
557
+ *
558
+ * `matched` is curesAreRed's `matched`; `branchJobs` is every job at the branch head, each tagged with
559
+ * its run's `workflowName`, `runStatus` and `runConclusion` — or null when it could not be read.
560
+ * Returns `{ ok, reason }`; ok without reading anything when no cure names a spent cancelled check.
561
+ */
562
+ function spentCancelledCuresProven(matched, branchJobs) {
563
+ const wanted = (Array.isArray(matched) ? matched : []).filter((j) => j && j.spentCancelled);
564
+ if (wanted.length === 0) return { ok: true, reason: '' };
565
+ const rows = typeof branchJobs === 'function' ? branchJobs() : branchJobs;
566
+ if (!Array.isArray(rows)) {
567
+ return { ok: false, reason: `the branch head's jobs could not be read — ${wanted.map((j) => `\`${checkLabel(j)}\``).join(', ')} never finished on trunk, so only the branch's own run of it can prove the cure, and an unread run proves nothing` };
568
+ }
569
+ const unproven = wanted.filter((red) => !rows.some((b) => b && (b.workflowName || '') === (red.workflowName || '') && b.name === red.name
570
+ && b.runStatus === 'completed' && b.runConclusion === 'success' && b.status === 'completed' && b.conclusion === 'success'));
571
+ if (unproven.length) {
572
+ const seen = (red) => {
573
+ const same = rows.filter((b) => b && (b.workflowName || '') === (red.workflowName || '') && b.name === red.name);
574
+ return same.length ? same.map((b) => `run ${b.runConclusion || b.runStatus || '?'} / job ${b.conclusion || b.status || '?'}`).join(', ') : 'no such job at the head';
575
+ };
576
+ return { ok: false,
577
+ reason: `${unproven.map((j) => `\`${checkLabel(j)}\` (${seen(j)})`).join(', ')} never finished on trunk (its re-run was spent cancelled), and the branch's own run of it did not succeed at its head — a cancelled or skipped run proves nothing, on either side` };
578
+ }
579
+ return { ok: true, reason: '' };
539
580
  }
540
581
 
541
582
  function titleIsTrunkRed(title) {
@@ -544,10 +585,12 @@ function titleIsTrunkRed(title) {
544
585
 
545
586
  /**
546
587
  * The reviewer-grant verdict for one issue on a ship. `ctx` = { branch, trunk, redTrunkSha, evidence,
547
- * issueNum, labelName, policy, now, redJobs } where `evidence` is `{ok, sha}` for the branch's CURRENT
548
- * remote head (or null on a failed read), `now` is an ISO instant or ms (absent = Date.now()), and
549
- * `redJobs` is a function returning the red-job set at `redTrunkSha` (or null) — called only once
550
- * everything cheaper has passed. Checks, cheapest first, each with its own reason. `record` must be a
588
+ * issueNum, labelName, policy, now, redJobs, branchJobs } where `evidence` is `{ok, sha}` for the
589
+ * branch's CURRENT remote head (or null on a failed read), `now` is an ISO instant or ms (absent =
590
+ * Date.now()), `redJobs` is a function returning the red-job set at `redTrunkSha` (or null) — called
591
+ * only once everything cheaper has passed — and `branchJobs` (#730) a function returning the branch
592
+ * head's jobs for `spentCancelledCuresProven`, called only when a cure names a spent cancelled
593
+ * check (absent reads as unmeasured, which refuses such a cure). Checks, cheapest first, each with its own reason. `record` must be a
551
594
  * ghIssueView result carrying `title`. Returns { ok, grant, reason }.
552
595
  */
553
596
  function evaluateReviewerIssue(record, ctx) {
@@ -588,6 +631,13 @@ function evaluateReviewerIssue(record, ctx) {
588
631
  try { redJobs = typeof c.redJobs === 'function' ? c.redJobs() : (c.redJobs === undefined ? null : c.redJobs); } catch (_) { redJobs = null; }
589
632
  const cr = curesAreRed(parseCures(g.record.cures), redJobs);
590
633
  if (!cr.ok) return no(`#${issue}: ${cr.reason}`, g);
634
+ // #730: a spent cancelled cure must still be proven on the branch's own run, at ship as at mint.
635
+ let branchJobs = null;
636
+ const pr = spentCancelledCuresProven(cr.matched, () => {
637
+ try { branchJobs = typeof c.branchJobs === 'function' ? c.branchJobs() : (c.branchJobs === undefined ? null : c.branchJobs); } catch (_) { branchJobs = null; }
638
+ return branchJobs;
639
+ });
640
+ if (!pr.ok) return no(`#${issue}: ${pr.reason}`, g);
591
641
  return { issue, ok: true, grant: g, reason: '' };
592
642
  }
593
643
 
@@ -599,5 +649,5 @@ module.exports = {
599
649
  // #504 — the reviewer role
600
650
  REVIEW_GRANT_MARK, REVIEW_GRANT_RE, REVIEWER_ROLE, GRANT_ROLES, REVIEW_RECORD_FIELDS, TRUNK_RED_TITLE_PREFIX,
601
651
  GRANT_POLICIES, parseGrantPolicy, parseCures, formatCures, validateReviewRecord, reviewGrantCommentBody,
602
- parseReviewGrant, liveGrantRecords, checkLabel, curesAreRed, titleIsTrunkRed, evaluateReviewerIssue,
652
+ parseReviewGrant, liveGrantRecords, checkLabel, curesAreRed, spentCancelledCuresProven, titleIsTrunkRed, evaluateReviewerIssue,
603
653
  };
@@ -108,6 +108,8 @@ function restRow(x) {
108
108
  // #705: the ref the run is on — a zero-jobs run is told apart from one queued behind its own
109
109
  // concurrency group by an older in-progress run of the same workflow on the SAME ref.
110
110
  headBranch: x.head_branch || null,
111
+ // #730: which attempt the row is — a re-run keeps the run id and bumps this.
112
+ attempt: x.run_attempt ?? null,
111
113
  };
112
114
  }
113
115
 
package/tools/lib/git.js CHANGED
@@ -1015,7 +1015,9 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
1015
1015
  // id, never its display name; mapped to `workflowId`, the name the REST row (ci-wait restRow) uses.
1016
1016
  // updatedAt is additive (#555): a finished run's completion time, the lone-member wait's anchor.
1017
1017
  // headBranch is additive (#705): the ref the concurrency-queue read (ghActiveRunsOfWorkflow) keys on.
1018
- '--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,workflowDatabaseId,event,headBranch'], { cwd: repo });
1018
+ // attempt is additive (#730): a cancelled run whose one re-run is spent (attempt > 1) is red to the
1019
+ // reviewer grant (ci-cure.js spentCancelledRuns); the REST row carries it as run_attempt.
1020
+ '--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,workflowDatabaseId,event,headBranch,attempt'], { cwd: repo });
1019
1021
  if (!r.ok) return null;
1020
1022
  let runs;
1021
1023
  try { runs = JSON.parse(r.stdout); } catch (_) { return null; }