@futurelastic/colab-handbook 1.12.0-rc.60 → 1.12.0-rc.61

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/audit/audit.mjs CHANGED
@@ -109,6 +109,8 @@ const trustHumansLib = require("../tools/lib/trust-humans.js");
109
109
  const hermeticLib = require("../tools/lib/hermetic.js");
110
110
  // #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
111
111
  const treeGreenLib = require("../tools/lib/tree-green.js");
112
+ // #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
113
+ const verifyRunsLib = require("../tools/lib/verify-runs.js");
112
114
  // #410: the optional `gate:` block — read through the same module the skills name.
113
115
  const gateLib = require("../tools/lib/gate.js");
114
116
  // #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
@@ -1363,6 +1365,16 @@ function auditRepo(target, ctx) {
1363
1365
  if (!tr.valid) fail(tr.reason);
1364
1366
  }
1365
1367
 
1368
+ // ---- ship-gate-workflows / ship-ignore-workflows (#503) ---------------------
1369
+ // Which workflow runs at trunk's head count as "trunk CI" for ship. Absent = the runs that verify
1370
+ // the code (push / pull_request triggered); post-CI release/deploy runs are set aside. An invalid
1371
+ // list fails: the reader ignores it and applies the default, so the declaration does nothing.
1372
+ {
1373
+ const vp = verifyRunsLib.parsePolicy(cfg);
1374
+ info.shipCiWorkflows = vp.gate || vp.ignore.length ? { gate: vp.gate, ignore: vp.ignore } : null;
1375
+ for (const why of vp.problems) fail(why);
1376
+ }
1377
+
1366
1378
  // ---- gate (#410) ----------------------------------------------------------
1367
1379
  // Local = a fast smoke check, branch CI = the one authoritative gate. tools/lib/gate.js
1368
1380
  // parseGate is the one reading. An invalid block fails: the reader falls back to the local full
package/package.json CHANGED
@@ -31,5 +31,5 @@
31
31
  "engines": {
32
32
  "node": ">=18"
33
33
  },
34
- "version": "1.12.0-rc.60"
34
+ "version": "1.12.0-rc.61"
35
35
  }
package/tools/colab CHANGED
@@ -47,6 +47,7 @@ const ciCure = require('./lib/ci-cure');
47
47
  const ciVerdict = require('./lib/ci-verdict');
48
48
  const baseCiVerdict = require('./lib/base-ci-verdict');
49
49
  const treeGreen = require('./lib/tree-green');
50
+ const verifyRuns = require('./lib/verify-runs');
50
51
  const ciWait = require('./lib/ci-wait'); // #495
51
52
  const staleBase = require('./lib/stale-base');
52
53
  const dirtyOwner = require('./lib/dirty-owner');
@@ -10422,10 +10423,13 @@ function trunkWorkflowFiles(repoAbs, sha) {
10422
10423
  */
10423
10424
  function readCiVerdict(repoAbs, gh, target, trunk) {
10424
10425
  if (!gh) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: `gh not usable (${ghUnusableWhy(repoAbs)}) — cannot confirm CI` } };
10425
- let run = git.ghRunForSha(repoAbs, target);
10426
+ // #503: only runs that VERIFY the code count — a post-CI release/deploy run at the same sha is set
10427
+ // aside and named, never a red and never a reason to wait (tools/lib/verify-runs.js).
10428
+ const readOpts = { verifying: verifyRuns.parsePolicy(projectDoc(repoAbs)) };
10429
+ let run = git.ghRunForSha(repoAbs, target, undefined, undefined, readOpts);
10426
10430
  let via = target;
10427
10431
  if (run && run.status === 'none' && target !== trunk) {
10428
- run = git.ghRunForSha(repoAbs, trunk);
10432
+ run = git.ghRunForSha(repoAbs, trunk, undefined, undefined, readOpts);
10429
10433
  via = `${trunk} (line "${target}" has no runs — ungated, advisory)`;
10430
10434
  }
10431
10435
  if (!run) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: 'gh run list failed' } };
@@ -10435,7 +10439,7 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10435
10439
  // Re-read the same sha by commit (the read `release finalize` already trusts, #339) before
10436
10440
  // believing it. A failed re-read changes nothing: the branch read's `none` stands.
10437
10441
  if (run.status === 'none' && target === trunk) {
10438
- const byCommit = git.ghRunForCommitAnyRef(repoAbs, run.sha);
10442
+ const byCommit = git.ghRunForCommitAnyRef(repoAbs, run.sha, undefined, readOpts);
10439
10443
  if (byCommit && byCommit.status !== 'none') {
10440
10444
  run = byCommit;
10441
10445
  via = `${trunk} (by commit — the branch-filtered read was empty)`;
@@ -10450,7 +10454,7 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10450
10454
  const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha));
10451
10455
  if (fresh.fresh) {
10452
10456
  verdict = { ok: false, class: SELF_CLEARING,
10453
- 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)}` };
10457
+ 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)}${verifyRuns.setAsideNote(run.setAside)}` };
10454
10458
  }
10455
10459
  }
10456
10460
  // #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
@@ -10521,7 +10525,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
10521
10525
  */
10522
10526
  function classifyCiRun(repoAbs, run, at) {
10523
10527
  const v = classifyCiRunRaw(repoAbs, run, at);
10524
- return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) };
10528
+ return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) };
10525
10529
  }
10526
10530
 
10527
10531
  /**
@@ -13648,6 +13652,13 @@ the same read (shipCiCheck's readCiVerdict): by branch, re-read by commit when e
13648
13652
  workflows the repo does not own dropped (#451), each workflow judged by its newest run (#461).
13649
13653
  Read-only: no claim, no label, no write.
13650
13654
 
13655
+ Only runs that VERIFY the code are judged (#503): push / pull_request / merge_group triggered.
13656
+ A run of any other trigger at the same sha — a workflow_run release (release-auto.yml), a
13657
+ scheduled finalize, a dispatch, a deploy — comes after the verdict and is set aside and named in
13658
+ the detail (--json: setAside). Override in .github/project.yml, by workflow name:
13659
+ ship-gate-workflows: [CI] exactly these workflows count, whatever their trigger
13660
+ ship-ignore-workflows: [Deploy] set these aside too, even when push-triggered
13661
+
13651
13662
  The first output word is one verdict:
13652
13663
  GREEN every judged workflow's newest run at the sha succeeded — ship's row would pass
13653
13664
  RED a judged run completed and did not succeed — trunk is red
@@ -13711,7 +13722,9 @@ function cmdTrunkCi(argv) {
13711
13722
  const sha = r.run ? r.run.sha || null : null;
13712
13723
  let detail = r.verdict.detail;
13713
13724
  if (verdict === 'UNREADABLE' && gh && !git.ghState().ok) detail += ` (${ghUnusableWhy(repoAbs)})`;
13714
- out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail, ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}) };
13725
+ out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail,
13726
+ ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}),
13727
+ ...(r.run && Array.isArray(r.run.setAside) && r.run.setAside.length ? { setAside: r.run.setAside } : {}) };
13715
13728
  if (key && verdict !== 'UNREADABLE' && sha === headSha) cache.put(key, out);
13716
13729
  }
13717
13730
  if (opts.json) {
@@ -13775,8 +13788,9 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
13775
13788
 
13776
13789
  <run-id> wait for one workflow run (actions/runs/<id>)
13777
13790
  --sha <sha> wait for EVERY repo-owned workflow at the sha (the verdict colab ship reads:
13778
- newest run per workflow, dynamic workflows dropped — #451/#461); a sha with no
13779
- run yet counts as pending until the deadline
13791
+ newest run per workflow, dynamic workflows dropped — #451/#461; only runs that
13792
+ verify the code, so a post-CI release/deploy run is set aside — #503); a sha
13793
+ with no run yet counts as pending until the deadline
13780
13794
  --branch <b> narrow --sha to runs on that branch
13781
13795
  --timeout <d> deadline: 45m (default), 90s, 1h, or seconds
13782
13796
 
@@ -13824,6 +13838,7 @@ function cmdCiWait(argv) {
13824
13838
  return ciWait.EXIT.ALREADY_WAITING;
13825
13839
  }
13826
13840
 
13841
+ const verifyPolicy = verifyRuns.parsePolicy(projectDoc(repoAbs));
13827
13842
  const poll = (etag) => {
13828
13843
  const r = git.ghApiConditional(repoAbs, apiPath, etag);
13829
13844
  if (r.kind !== 'ok') return r;
@@ -13833,7 +13848,9 @@ function cmdCiWait(argv) {
13833
13848
  } else {
13834
13849
  const rows = Array.isArray(r.json.workflow_runs) ? r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === opts.sha) : null;
13835
13850
  if (!rows) return { kind: 'error', status: r.status, detail: 'response has no workflow_runs' };
13836
- summary = git.summarizeRunsForCommit(rows, opts.sha);
13851
+ // #503: the same verifying-runs policy ship reads — a wait on trunk's head ends when the CI
13852
+ // that verifies the code ends, not when the post-CI release run does.
13853
+ summary = git.summarizeRunsForCommit(rows, opts.sha, { verifying: verifyPolicy });
13837
13854
  const pick = rows.find((x) => x.databaseId === summary.databaseId);
13838
13855
  summary = { ...summary, url: pick ? pick.url : null };
13839
13856
  }
@@ -13856,11 +13873,12 @@ function cmdCiWait(argv) {
13856
13873
  outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified,
13857
13874
  waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
13858
13875
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
13876
+ ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
13859
13877
  };
13860
13878
  if (opts.json) print(JSON.stringify(out, null, 2));
13861
13879
  else {
13862
13880
  print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
13863
- `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}`);
13881
+ `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}`);
13864
13882
  }
13865
13883
  return code;
13866
13884
  }
package/tools/lib/git.js CHANGED
@@ -823,12 +823,12 @@ function ghLabelEditDescription(repo, name, description) {
823
823
  * when tools/lib/ci-verdict.js finds the run WEDGED rather than merely slow. Nothing here waits or
824
824
  * polls — it reports what is true at read time and lets the caller decide.
825
825
  */
826
- function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name || 'origin') {
826
+ function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name || 'origin', opts = {}) {
827
827
  const head = run('git', ['ls-remote', remote, `refs/heads/${branch}`], { cwd: repo });
828
828
  if (!head.ok) return null;
829
829
  const sha = (head.stdout.split('\n')[0] || '').split('\t')[0].trim();
830
830
  if (!sha) return null; // branch does not exist on the remote
831
- return ghRunForCommit(repo, branch, sha, limit);
831
+ return ghRunForCommit(repo, branch, sha, limit, opts);
832
832
  }
833
833
 
834
834
  /**
@@ -955,8 +955,8 @@ function ghRunsForRef(repo, ref, sha, limit = 20) {
955
955
  return runs.filter((x) => x && x.headSha === sha);
956
956
  }
957
957
 
958
- function ghRunForCommit(repo, branch, sha, limit = 10) {
959
- return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha);
958
+ function ghRunForCommit(repo, branch, sha, limit = 10, opts = {}) {
959
+ return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha, opts);
960
960
  }
961
961
 
962
962
  /**
@@ -981,8 +981,8 @@ function ghRunsAtCommit(repo, sha, limit = 100) {
981
981
  * empty trunk read `none`: the branch-filtered list was measured returning nothing for a trunk sha
982
982
  * whose green run existed, and clearing on its own a minute later. Null on failure, as elsewhere.
983
983
  */
984
- function ghRunForCommitAnyRef(repo, sha, limit = 50) {
985
- return summarizeRunsForCommit(ghRunsAtCommit(repo, sha, limit), sha);
984
+ function ghRunForCommitAnyRef(repo, sha, limit = 50, opts = {}) {
985
+ return summarizeRunsForCommit(ghRunsAtCommit(repo, sha, limit), sha, opts);
986
986
  }
987
987
 
988
988
  /**
@@ -1029,6 +1029,7 @@ function excludedRunSummary(rows) {
1029
1029
  return rows.map((x) => ({
1030
1030
  workflowName: x.workflowName || null, status: x.status || null,
1031
1031
  conclusion: x.conclusion || null, databaseId: x.databaseId || null,
1032
+ ...(x.setAsideWhy ? { why: x.setAsideWhy } : {}),
1032
1033
  }));
1033
1034
  }
1034
1035
 
@@ -1043,15 +1044,28 @@ function excludedRunSummary(rows) {
1043
1044
  * #461: the repo-owned rows are then reduced to the newest run per workflow (newestRunPerWorkflow,
1044
1045
  * below); the rows that reduction set aside ride along as an additive `superseded` list, same shape
1045
1046
  * as `excluded`, present only when non-empty. Every quantifier below runs over the reduced set.
1047
+ *
1048
+ * #503: `opts.verifying` (a tools/lib/verify-runs.js policy, `{gate, ignore}`) narrows the owned rows
1049
+ * to the runs that VERIFY the code — push / pull-request triggered, or the declared set — BEFORE the
1050
+ * per-workflow reduction; the rest (a `workflow_run` release, a scheduled finalize, a deploy) ride
1051
+ * along as `setAside`, each with its reason. Opt-in: without `opts.verifying` nothing changes, so
1052
+ * readers that never asked (release finalize, the base-ci advisory, ci-grant) read exactly as before.
1046
1053
  */
1047
- function summarizeRunsForCommit(allForSha, sha) {
1054
+ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1048
1055
  if (allForSha === null) return null;
1049
1056
  const dropped = allForSha.filter((x) => !isRepoOwnedRun(x));
1050
- const owned = dropped.length ? allForSha.filter(isRepoOwnedRun) : allForSha;
1057
+ let owned = dropped.length ? allForSha.filter(isRepoOwnedRun) : allForSha;
1058
+ let setAside = [];
1059
+ if (opts && opts.verifying) {
1060
+ const split = require('./verify-runs').splitVerifying(owned, opts.verifying);
1061
+ owned = split.counted;
1062
+ setAside = split.setAside;
1063
+ }
1051
1064
  const { heads, superseded } = newestRunPerWorkflow(owned);
1052
1065
  const extra = {
1053
1066
  ...(dropped.length ? { excluded: excludedRunSummary(dropped) } : {}),
1054
1067
  ...(superseded.length ? { superseded: excludedRunSummary(superseded) } : {}),
1068
+ ...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
1055
1069
  };
1056
1070
  const r = summarizeRepoOwnedRuns(heads, sha);
1057
1071
  return { ...r, ...extra };
@@ -0,0 +1,104 @@
1
+ 'use strict';
2
+ /**
3
+ * Which workflow runs at a sha VERIFY the code there (#503) — the pure half of the rule `colab
4
+ * ship`'s CI gate, `colab trunk-ci` and `colab ci-wait` read. No gh, no git, no I/O.
5
+ *
6
+ * THE RULE. A run counts toward "is this sha green" when its trigger is a push or a pull request
7
+ * (`push`, `pull_request`, `pull_request_target`, `merge_group`) — the triggers that run a suite
8
+ * against the code. A run of any OTHER trigger is set aside and named: `workflow_run` (the
9
+ * handbook's own `release-auto.yml` fires on CI's completion, cuts a candidate, publishes, deploys
10
+ * to staging — 20–30 min after the verifying run already finished), `schedule` (the same template's
11
+ * daily finalize lands on trunk's head too), `workflow_dispatch`, `release`, `deployment`, … Those
12
+ * runs come AFTER the verdict and act on it; their failure belongs to the release lane, so they
13
+ * must neither turn trunk red for ship nor make ship wait for them.
14
+ *
15
+ * Measured (one adopted fork, 2026-10-05): CI green at 15:18Z, `Release (auto)` then in progress at
16
+ * the same trunk sha, and four green, graded candidates parked behind it — every landing cost one
17
+ * CI cycle plus one release cycle.
18
+ *
19
+ * A row with no `event` field (an older read, a hand-built fixture) is counted: absence of the field
20
+ * never excludes anything, so every verdict computable before #503 without it is computed the same.
21
+ *
22
+ * OVERRIDES (project.yml), matched against the run's workflow `name:` — the only workflow identity
23
+ * every run read carries (`gh run list` has no file path):
24
+ * ship-gate-workflows: [CI, Lint] the explicit set: exactly these workflows count, whatever
25
+ * their trigger; every other workflow is set aside.
26
+ * ship-ignore-workflows: [Deploy] set these aside too, even when push-triggered (a deploy
27
+ * workflow that fires on a push to trunk). Wins over the gate
28
+ * list for a name in both.
29
+ */
30
+
31
+ const VERIFYING_EVENTS = Object.freeze(['push', 'pull_request', 'pull_request_target', 'merge_group']);
32
+ const GATE_KEY = 'ship-gate-workflows';
33
+ const IGNORE_KEY = 'ship-ignore-workflows';
34
+
35
+ /** One list key: absent → null; a non-empty list of non-empty strings → the names; else invalid. */
36
+ function parseNameList(doc, key) {
37
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, key);
38
+ if (!has || doc[key] === null || doc[key] === undefined) return { declared: false, valid: true, names: null };
39
+ let v = doc[key];
40
+ if (typeof v === 'string') v = [v];
41
+ if (!Array.isArray(v) || v.length === 0) {
42
+ return { declared: true, valid: false, names: null, reason: `${key} must be a non-empty list of workflow names (the workflow's \`name:\`), got ${JSON.stringify(doc[key])}` };
43
+ }
44
+ const bad = v.filter((x) => typeof x !== 'string' || !x.trim());
45
+ if (bad.length) {
46
+ return { declared: true, valid: false, names: null, reason: `${key} has ${bad.length} entr${bad.length === 1 ? 'y' : 'ies'} that ${bad.length === 1 ? 'is' : 'are'} not a workflow name: ${JSON.stringify(bad)}` };
47
+ }
48
+ return { declared: true, valid: true, names: v.map((x) => x.trim()) };
49
+ }
50
+
51
+ /**
52
+ * The policy from a parsed project.yml doc: `{ gate: string[]|null, ignore: string[], valid,
53
+ * problems: string[] }`. An invalid key is IGNORED by the reader (the default rule applies) and
54
+ * reported by the audit — a malformed override must not silently widen what ship counts as green
55
+ * in either direction, and the default is the measured-safe reading.
56
+ */
57
+ function parsePolicy(doc) {
58
+ const g = parseNameList(doc, GATE_KEY);
59
+ const i = parseNameList(doc, IGNORE_KEY);
60
+ const problems = [g, i].filter((x) => !x.valid).map((x) => x.reason);
61
+ return {
62
+ gate: g.valid ? g.names : null,
63
+ ignore: i.valid && i.names ? i.names : [],
64
+ valid: problems.length === 0,
65
+ problems,
66
+ };
67
+ }
68
+
69
+ /** Why one row is set aside, or null when it counts. */
70
+ function setAsideReason(row, policy) {
71
+ const p = policy || { gate: null, ignore: [] };
72
+ const name = row && row.workflowName;
73
+ if (name && p.ignore && p.ignore.includes(name)) return `${IGNORE_KEY}`;
74
+ if (p.gate) return name && p.gate.includes(name) ? null : `not in ${GATE_KEY}`;
75
+ const ev = row && row.event;
76
+ if (ev === undefined || ev === null || ev === '') return null;
77
+ return VERIFYING_EVENTS.includes(ev) ? null : `event: ${ev}`;
78
+ }
79
+
80
+ /** Split rows into `{ counted, setAside }`; each set-aside row carries `setAsideWhy`. Null in → null out. */
81
+ function splitVerifying(rows, policy) {
82
+ if (!Array.isArray(rows)) return null;
83
+ const counted = [];
84
+ const setAside = [];
85
+ for (const r of rows) {
86
+ const why = setAsideReason(r, policy);
87
+ if (why) setAside.push({ ...r, setAsideWhy: why });
88
+ else counted.push(r);
89
+ }
90
+ return { counted, setAside };
91
+ }
92
+
93
+ /**
94
+ * The verdict-detail suffix naming what was set aside — '' when nothing was. `rows` is the compact
95
+ * summary shape (`{workflowName, status, conclusion, databaseId, why}`).
96
+ */
97
+ function setAsideNote(rows) {
98
+ const list = Array.isArray(rows) ? rows : [];
99
+ if (!list.length) return '';
100
+ const names = list.map((x) => `${x.workflowName || 'unnamed'} (${x.conclusion || x.status || '?'}${x.databaseId ? `, run ${x.databaseId}` : ''}${x.why ? `; ${x.why}` : ''})`);
101
+ return ` — set aside ${list.length} run${list.length === 1 ? '' : 's'} that do${list.length === 1 ? 'es' : ''} not verify the code (post-CI release/deploy lane, #503): ${names.join(', ')}`;
102
+ }
103
+
104
+ module.exports = { VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, parsePolicy, setAsideReason, splitVerifying, setAsideNote };