@futurelastic/colab-handbook 1.12.0-rc.25 → 1.12.0-rc.27

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
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.25"
30
+ "version": "1.12.0-rc.27"
31
31
  }
package/tools/colab CHANGED
@@ -3660,7 +3660,13 @@ It is minted only when ALL of these hold, checked before any network call:
3660
3660
  - the record is well-formed AND passing (approve · checklist pass · escalation clear · CI pass) —
3661
3661
  a grant carrying a failing review is a contradiction, so it is refused, not recorded;
3662
3662
  - the branch is pushed, and --head (if given) equals origin's tip — the grant binds that tip;
3663
- - this checkout's project.yml declares \`migration-grant: reviewer\` (#398; absent = human).
3663
+ - this checkout's project.yml declares \`migration-grant: reviewer\` (#398; absent = human);
3664
+ - checklist-items, when given, is <passed>/${migrationGrant.REVIEW_CHECKLIST_ITEMS} and, with checklist pass, every item
3665
+ passed (#457) — the record counts against the checklist the migration-review skill walks today.
3666
+ Then, read from CI after the tracker read and before anything is written (#457):
3667
+ - ci-roundtrip pass is TRUE at the head: the "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" job ran and
3668
+ passed there (the rule ship applies), and --ci-run, when given, is one of the runs at that
3669
+ head and carries the job. A repo whose CI has no such job cannot mint a reviewer grant at all.
3664
3670
  COLAB_HUMAN=1 is still required for every role. The reviewer identity is DECLARED, not attested.
3665
3671
  \`colab ship\` honours a reviewer grant only when ALL of (#401): P the target's project.yml says
3666
3672
  \`migration-grant: reviewer\` · M this record is live, trusted and passing · HEAD its head is the
@@ -3796,9 +3802,36 @@ function migrationGrantReviewRecord(repoAbs, opts) {
3796
3802
  if (!v.passing) {
3797
3803
  throw new UserError(`the review does not pass (${migrationGrant.reviewRecordFailure(rec)}) — a grant carrying a failing review is a contradiction; nothing was posted`);
3798
3804
  }
3805
+ // #457: checks only a NEW record faces (the checklist denominator) — local, so before the gh gate.
3806
+ const mintProblems = migrationGrant.mintRecordProblems(rec);
3807
+ if (mintProblems.length) throw new UserError(`the review record is invalid: ${mintProblems.join('; ')}`);
3799
3808
  return rec;
3800
3809
  }
3801
3810
 
3811
+ /**
3812
+ * #457: the record says `ci-roundtrip: pass` — read CI at its head and refuse unless the round-trip
3813
+ * job is really there and passed (tools/lib/migration-grant.js mintRoundtripCheck: the same
3814
+ * roundtripVerdict `colab ship` applies, plus the cited `ci-run` must carry the job). Needs gh, so
3815
+ * it runs in cmdMigrationGrantCreate after the tracker read and BEFORE the label is applied —
3816
+ * nothing is written when it refuses. The workflows guard diffs trunk against the reviewed head;
3817
+ * an unreadable diff counts as touched, failing closed exactly as shipMigrationCtx does.
3818
+ */
3819
+ function migrationGrantRoundtripCheck(repoAbs, branch, rec) {
3820
+ if (rec['ci-roundtrip'] !== 'pass') return;
3821
+ const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
3822
+ const remote = git.remoteInfo(repoAbs).name || 'origin';
3823
+ let d = trunk ? git.git(['diff', '--name-only', `${remote}/${trunk}...${rec.head}`], repoAbs) : { ok: false };
3824
+ if (!d.ok && trunk) d = git.git(['diff', '--name-only', `${trunk}...${rec.head}`], repoAbs);
3825
+ const workflowsTouched = !d.ok || d.stdout.split('\n').some((f) => f.startsWith('.github/workflows/'));
3826
+ let runs = null;
3827
+ const list = git.ghRunsForCommit(repoAbs, branch, rec.head, 20);
3828
+ if (Array.isArray(list)) {
3829
+ runs = list.map((r) => ({ databaseId: r.databaseId, workflowName: r.workflowName || null, jobs: git.ghRunJobs(repoAbs, r.databaseId) }));
3830
+ }
3831
+ const c = migrationGrant.mintRoundtripCheck(rec, runs, { workflowsTouched });
3832
+ if (!c.ok) throw new UserError(`${c.reason}; nothing was posted`);
3833
+ }
3834
+
3802
3835
  function cmdMigrationGrantCreate(repoAbs, num, opts) {
3803
3836
  // --branch and branch existence are already validated by cmdMigrationGrant, ahead of the
3804
3837
  // isGhUsable gate — see the comment there. Kept as a defensive re-check in case this function is
@@ -3822,6 +3855,9 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
3822
3855
  || `this repo has no \`${labels.MIGRATION_GRANT_LABEL}\` label`);
3823
3856
  }
3824
3857
 
3858
+ // #457: a record claiming a CI round-trip pass is checked against CI BEFORE anything is written.
3859
+ if (opts.reviewRecord) migrationGrantRoundtripCheck(repoAbs, opts.branch, opts.reviewRecord);
3860
+
3825
3861
  const editR = git.ghIssueEdit(repoAbs, num, labels.migrationGrantLabelArgs({}));
3826
3862
  if (!editR.ok) throw new UserError(`gh edit #${num} failed (${editR.stderr.split('\n')[0] || editR.code})`);
3827
3863
 
@@ -10105,7 +10141,7 @@ function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk) {
10105
10141
  const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha));
10106
10142
  if (fresh.fresh) {
10107
10143
  verdict = { ok: false, class: SELF_CLEARING,
10108
- detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${ciVerdict.EMPTY_READ_GRACE_MINUTES}m grace; retry later` };
10144
+ detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${ciVerdict.EMPTY_READ_GRACE_MINUTES}m grace; retry later${excludedRunsNote(run)}` };
10109
10145
  }
10110
10146
  }
10111
10147
  // #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
@@ -10142,6 +10178,23 @@ function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk) {
10142
10178
  * the detail string still reads sensibly rather than "undefined runs".
10143
10179
  */
10144
10180
  function classifyCiRun(repoAbs, run, at) {
10181
+ const v = classifyCiRunRaw(repoAbs, run, at);
10182
+ return { ...v, detail: v.detail + excludedRunsNote(run) };
10183
+ }
10184
+
10185
+ /**
10186
+ * #451: the runs a verdict did NOT count, named in its detail — runs from workflows the repo does
10187
+ * not own (`event: dynamic`, e.g. Dependabot Updates) are dropped by git.summarizeRunsForCommit
10188
+ * before the verdict is computed, and a reader must be able to see what was dropped. '' when none.
10189
+ */
10190
+ function excludedRunsNote(run) {
10191
+ const ex = run && Array.isArray(run.excluded) ? run.excluded : [];
10192
+ if (!ex.length) return '';
10193
+ const names = ex.map((x) => `${x.workflowName || 'unnamed'} (${x.conclusion || x.status || '?'}${x.databaseId ? `, run ${x.databaseId}` : ''})`);
10194
+ return ` — excluded ${ex.length} run${ex.length === 1 ? '' : 's'} from workflows this repo does not own (event: dynamic, #451): ${names.join(', ')}`;
10195
+ }
10196
+
10197
+ function classifyCiRunRaw(repoAbs, run, at) {
10145
10198
  if (run.status === 'completed') {
10146
10199
  if (run.conclusion === 'success') {
10147
10200
  const n = run.runCount == null ? 1 : run.runCount;
@@ -10476,7 +10529,10 @@ function shipCureJobEvidence(repoAbs, trunk, redSha, branch, evRun) {
10476
10529
  // ALL runs at the red sha, not the single row `ghRunForCommit` would pick: a red job can sit in a
10477
10530
  // sibling workflow the picker never returned, and admitting a carve-out while that job is still
10478
10531
  // red is exactly the failure this evidence exists to prevent.
10479
- const redRuns = git.ghRunsForCommit(repoAbs, trunk, redSha);
10532
+ // #451: a run from a workflow the repo does not own is not part of trunk's red — same drop the
10533
+ // verdict itself makes (git.summarizeRunsForCommit), so cure evidence never chases its jobs.
10534
+ const redRunsAll = git.ghRunsForCommit(repoAbs, trunk, redSha);
10535
+ const redRuns = redRunsAll === null ? null : redRunsAll.filter(git.isRepoOwnedRun);
10480
10536
  if (redRuns === null || redRuns.length === 0) return null;
10481
10537
 
10482
10538
  // Same inverted allowlist git.js uses at run level (#146/#165): only `success`/`cancelled` are
package/tools/lib/git.js CHANGED
@@ -865,7 +865,9 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
865
865
  const r = run('gh', ['run', 'list', '--branch', branch, '-L', String(limit),
866
866
  // workflowName is additive (#338): `colab release cut`'s full-suite condition groups the rows by
867
867
  // workflow — a workflow whose only run at the sha was cancelled never ran its suite.
868
- '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName'], { cwd: repo });
868
+ // event is additive (#451): summarizeRunsForCommit drops `dynamic` rows (workflows the repo
869
+ // does not own) before it computes a verdict, and can only do that if the row says so.
870
+ '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,event'], { cwd: repo });
869
871
  if (!r.ok) return null;
870
872
  let runs;
871
873
  try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
@@ -956,9 +958,43 @@ function ghRunsSince(repo, branch, sinceDay, limit = 1000) {
956
958
  return { runs, truncated: runs.length >= limit };
957
959
  }
958
960
 
959
- /** ghRunForCommit's pick, over rows already read (null in -> null out). */
960
- function summarizeRunsForCommit(forSha, sha) {
961
- if (forSha === null) return null;
961
+ /**
962
+ * #451: a run whose `event` is `dynamic` comes from a workflow the repo does not own — GitHub's
963
+ * dynamic workflows (Dependabot Updates, code scanning default setup, …), which never execute the
964
+ * code at the sha they are filed against. Such a row is not evidence about that sha, so it is
965
+ * dropped before any verdict is computed. A row with no `event` field (an older read, a hand-built
966
+ * fixture) is kept: absence of the field never excludes anything.
967
+ */
968
+ function isRepoOwnedRun(x) {
969
+ return !(x && x.event === 'dynamic');
970
+ }
971
+
972
+ /** The dropped rows, in the compact shape a verdict detail names them by. */
973
+ function excludedRunSummary(rows) {
974
+ return rows.map((x) => ({
975
+ workflowName: x.workflowName || null, status: x.status || null,
976
+ conclusion: x.conclusion || null, databaseId: x.databaseId || null,
977
+ }));
978
+ }
979
+
980
+ /**
981
+ * ghRunForCommit's pick, over rows already read (null in -> null out).
982
+ *
983
+ * #451: rows from workflows the repo does not own (`event: dynamic`) are dropped first; when any
984
+ * were, the result carries an additive `excluded` list naming them, so a caller can say what it
985
+ * did not count. When nothing is left the sha reads `none`, exactly as if no run had existed —
986
+ * a repo-owned red is never affected, since only `dynamic` rows are dropped.
987
+ */
988
+ function summarizeRunsForCommit(allForSha, sha) {
989
+ if (allForSha === null) return null;
990
+ const dropped = allForSha.filter((x) => !isRepoOwnedRun(x));
991
+ const forSha = dropped.length ? allForSha.filter(isRepoOwnedRun) : allForSha;
992
+ const extra = dropped.length ? { excluded: excludedRunSummary(dropped) } : {};
993
+ const r = summarizeRepoOwnedRuns(forSha, sha);
994
+ return { ...r, ...extra };
995
+ }
996
+
997
+ function summarizeRepoOwnedRuns(forSha, sha) {
962
998
  if (forSha.length === 0) return { status: 'none', conclusion: null, sha, createdAt: null, databaseId: null, runCount: 0 };
963
999
 
964
1000
  // runCount (#176) is additive: how many sibling workflow rows exist at this sha, so a caller can
@@ -1070,7 +1106,7 @@ module.exports = {
1070
1106
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
1071
1107
  dirtyTracked, dirtyUntracked, dirtyAny,
1072
1108
  ghAvailable, ghState, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
1073
- ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit,
1109
+ ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
1074
1110
  ghRunJobCount, ghRunJobs,
1075
1111
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1076
1112
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
@@ -345,6 +345,61 @@ function roundtripVerdict(jobs, opts) {
345
345
  return { ok: true, legs, reason: '' };
346
346
  }
347
347
 
348
+ /**
349
+ * #457 — the MINT-time half of R. `colab ship` re-reads the round-trip at the head (roundtripVerdict
350
+ * above, through shipMigrationCtx), so a false `ci-roundtrip: pass` never opened the gate — but the
351
+ * grant record itself could still assert a fact its cited run does not contain, and the issue then
352
+ * sat looking "granted" until a ship pass measured it. This applies the same verdict when the record
353
+ * is WRITTEN, so a record that says `pass` is refused unless CI agrees at `rec.head`.
354
+ *
355
+ * Pure: `runs` is every run at the head — `[{ databaseId, workflowName, jobs }]`, `jobs` being
356
+ * git.ghRunJobs rows — or null when the run list could not be read (a run with `jobs: null` is an
357
+ * unread run). Checks, in order:
358
+ * - the run list and every run's jobs were read (an unread result is never a pass);
359
+ * - roundtripVerdict over all their jobs is ok — the exact rule ship applies, workflows guard
360
+ * included, so a record mint can never accept what ship would refuse;
361
+ * - `ci-run`, when given, resolves to a run id (bare digits, or a `/runs/<id>` URL), names one of
362
+ * those runs, and that run itself carries a round-trip job — a record must not cite a run that
363
+ * does not contain the evidence it is cited for, even when a sibling run does.
364
+ * A record whose `ci-roundtrip` is not `pass` is not this function's to judge (it never mints).
365
+ * Returns { ok, reason, verdict }.
366
+ */
367
+ function mintRoundtripCheck(rec, runs, opts) {
368
+ const o = opts || {};
369
+ const r = rec || {};
370
+ if (r['ci-roundtrip'] !== 'pass') return { ok: true, reason: '', verdict: null };
371
+ const sha = r.head ? String(r.head).slice(0, 7) : 'the head';
372
+ const no = (reason, verdict = null) => ({ ok: false, reason, verdict });
373
+ let jobs = null;
374
+ if (Array.isArray(runs) && runs.every((x) => x && Array.isArray(x.jobs))) {
375
+ jobs = [];
376
+ for (const x of runs) for (const j of x.jobs) jobs.push({ ...j, workflowName: x.workflowName || null });
377
+ }
378
+ const verdict = roundtripVerdict(jobs, { headSha: r.head, workflowsTouched: !!o.workflowsTouched });
379
+ if (!verdict.ok) {
380
+ const hint = verdict.reason.startsWith('no "') ? ` — this repo's CI must run the template's migrations job before a reviewer grant can record a pass` : '';
381
+ return no(`the record says ci-roundtrip: pass, but ${verdict.reason}${hint}`, verdict);
382
+ }
383
+ if (r['ci-run'] !== undefined && r['ci-run'] !== null && String(r['ci-run']) !== '') {
384
+ const id = parseRunId(r['ci-run']);
385
+ if (id === null) return no(`ci-run "${r['ci-run']}" does not name a run id (digits, or a URL ending /runs/<id>) — a cited run nobody can look up proves nothing`, verdict);
386
+ const cited = runs.find((x) => String(x.databaseId) === id);
387
+ if (!cited) return no(`ci-run ${id} is not a run at ${sha} — the record must cite the run that graded the head it binds`, verdict);
388
+ if (!cited.jobs.some((j) => j && typeof j.name === 'string' && j.name.startsWith(ROUNDTRIP_JOB_PREFIX))) {
389
+ return no(`ci-run ${id} has no "${ROUNDTRIP_JOB_PREFIX}" job — cite the run that carries the round-trip`, verdict);
390
+ }
391
+ }
392
+ return { ok: true, reason: '', verdict };
393
+ }
394
+
395
+ /** A run id from a `ci-run` value — bare digits, or the `/runs/<id>` segment of a run URL — or null. */
396
+ function parseRunId(v) {
397
+ const s = String(v).trim();
398
+ if (/^\d+$/.test(s)) return s;
399
+ const m = s.match(/\/runs\/(\d+)(?:[/?#]|$)/);
400
+ return m ? m[1] : null;
401
+ }
402
+
348
403
  /** A step that reached a terminal conclusion other than skipped/cancelled — ci-cure.js stepRan. */
349
404
  function stepRanOk(s) {
350
405
  return !!s && s.status === 'completed' && s.conclusion !== 'skipped' && s.conclusion !== 'cancelled';
@@ -448,6 +503,37 @@ function validateReviewRecord(rec, marker) {
448
503
  return { valid, passing, problems };
449
504
  }
450
505
 
506
+ /** #457 — the checklist the migration-review skill walks has this many items, so a record's
507
+ * `checklist-items` is `<passed>/10`. Kept in step with skills/migration-review/SKILL.md (a test
508
+ * reads the skill and pins it). */
509
+ const REVIEW_CHECKLIST_ITEMS = 10;
510
+
511
+ /**
512
+ * #457 — record checks that apply only when a grant is MINTED, never when one is read. They are
513
+ * kept out of validateReviewRecord on purpose: that function is also ship's read path, and a
514
+ * grant recorded under an older, shorter checklist must not change meaning after the fact (ship
515
+ * re-verifies everything that matters — HEAD and the live round-trip — on its own). A new record,
516
+ * though, must be counted against the checklist that exists today:
517
+ * - `checklist-items`, when given, has denominator REVIEW_CHECKLIST_ITEMS;
518
+ * - `checklist: pass` with `checklist-items` N/M needs N = M — a pass with an item failing is a
519
+ * contradiction, the same way a grant carrying a failing review is.
520
+ * Returns a list of problems ([] = fine).
521
+ */
522
+ function mintRecordProblems(rec) {
523
+ const r = rec || {};
524
+ const problems = [];
525
+ const items = r['checklist-items'];
526
+ if (items === undefined || items === null || !/^\d+\/\d+$/.test(String(items))) return problems;
527
+ const [a, b] = String(items).split('/').map(Number);
528
+ if (b !== REVIEW_CHECKLIST_ITEMS) {
529
+ problems.push(`"checklist-items" is ${items} — the migration-review checklist has ${REVIEW_CHECKLIST_ITEMS} items, so the record is <passed>/${REVIEW_CHECKLIST_ITEMS}`);
530
+ }
531
+ if (r.checklist === 'pass' && a !== b) {
532
+ problems.push(`"checklist" is pass but "checklist-items" is ${items} — a pass means every item passed`);
533
+ }
534
+ return problems;
535
+ }
536
+
451
537
  /** Why a VALID record is not passing, as one line — or '' when it passes. */
452
538
  function reviewRecordFailure(rec) {
453
539
  const why = [];
@@ -638,4 +724,6 @@ module.exports = {
638
724
  GRANT_POLICIES, parseGrantPolicy,
639
725
  // #401 — ship honours a reviewer grant
640
726
  ROUNDTRIP_JOB_PREFIX, roundtripVerdict, SHIP_CONDITION_TAG,
727
+ // #457 — the mint-time checks
728
+ REVIEW_CHECKLIST_ITEMS, mintRecordProblems, mintRoundtripCheck, parseRunId,
641
729
  };