@futurelastic/colab-handbook 1.20.1-rc.5 → 1.20.1-rc.6

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.20.1-rc.5"
36
+ "version": "1.20.1-rc.6"
37
37
  }
package/tools/colab CHANGED
@@ -15618,7 +15618,7 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
15618
15618
  let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
15619
15619
  if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
15620
15620
  const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
15621
- return { ref: x.parsed.ref, base7: x.parsed.base7, rooted: true, verdict: shipBatch.combinedVerdict(runs),
15621
+ return { ref: x.parsed.ref, base7: x.parsed.base7, rooted: true, verdict: shipBatch.combinedVerdict(runs, { verifying: verifyRuns.parsePolicy(doc) }),
15622
15622
  builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
15623
15623
  });
15624
15624
  const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
@@ -15723,6 +15723,8 @@ function cmdShipBatch(opts) {
15723
15723
  const repoAbs = resolveRepo(opts);
15724
15724
  if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo`);
15725
15725
  const doc = projectDoc(repoAbs);
15726
+ // #692: the combined run reads a wholly skipped workflow as #688 does, unless ship-gate-workflows names it.
15727
+ const batchRead = { verifying: verifyRuns.parsePolicy(doc) };
15726
15728
  const trunk = resolveTrunk(repoAbs, doc);
15727
15729
  if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
15728
15730
  // #591: a member built on another machine names its hand-off inline — `<branch>@<hand-off-url>`.
@@ -15910,7 +15912,7 @@ function cmdShipBatch(opts) {
15910
15912
  print(` ${want} is gone and ${atTip.parsed.ref} at ${trunk}'s tip carries this batch — its parent landed; resuming on ${trunk}'s tip`);
15911
15913
  } else {
15912
15914
  const pc = chains.get(want);
15913
- const verdict = shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, want, p.sha));
15915
+ const verdict = shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, want, p.sha), batchRead);
15914
15916
  const child = rooted.find((x) => x !== p && p.sha.startsWith(x.parsed.base7)) || null;
15915
15917
  if (verdict.state === 'red') {
15916
15918
  if (child) {
@@ -15944,7 +15946,7 @@ function cmdShipBatch(opts) {
15944
15946
  let foreignStep = null;
15945
15947
  if (foreign.length) {
15946
15948
  const runs = git.ghRunsForRef(repoAbs, atBase.parsed.ref, atBase.sha);
15947
- foreignStep = shipBatch.foreignBatchStep(shipBatch.combinedVerdict(runs), { settledAtMs: shipBatch.settledAt(runs), nowMs: Date.now() });
15949
+ foreignStep = shipBatch.foreignBatchStep(shipBatch.combinedVerdict(runs, batchRead), { settledAtMs: shipBatch.settledAt(runs), nowMs: Date.now() });
15948
15950
  }
15949
15951
  if (foreignStep && foreignStep.step === 'wait') {
15950
15952
  print(`⏸ ship-batch: another batch is in flight at this base — ${atBase.parsed.ref} carries ${inBatch.map((m) => m.branch).join(', ')}${foreignStep.why ? ` (${foreignStep.why})` : ''}.`);
@@ -15973,7 +15975,7 @@ function cmdShipBatch(opts) {
15973
15975
  }
15974
15976
  }
15975
15977
  }
15976
- let verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
15978
+ let verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha), batchRead) : null;
15977
15979
  // #610: integration-profile: gated — a wave lands only on a green heavy run at its head too. The
15978
15980
  // heavy verdict joins the combined one (integration-profile.js waveVerdict), so a heavy red takes
15979
15981
  // the same re-run / split path a light red does, and the split walks toward the culprit.
@@ -16975,7 +16977,7 @@ function cmdBatchStats(argv) {
16975
16977
  if (!isGhUsable(repoAbs)) {
16976
16978
  notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — trunk commits only: no combined runs, no green times, no partner matching`);
16977
16979
  } else {
16978
- const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .status, .conclusion, .run_attempt, .created_at, .updated_at, (if ((.head_branch // "") | startswith("ship-batch/")) then .head_commit.message else null end)] | @json';
16980
+ const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .status, .conclusion, .run_attempt, .created_at, .updated_at, (if ((.head_branch // "") | startswith("ship-batch/")) then .head_commit.message else null end), .name] | @json';
16979
16981
  // One query per UTC day: GitHub answers at most 1000 rows for a filtered run list, and a busy
16980
16982
  // repo passes that inside a fortnight. A day that still hits the cap is named, never hidden.
16981
16983
  const days = [];
@@ -16990,7 +16992,9 @@ function cmdBatchStats(argv) {
16990
16992
  if (!line.trim()) continue;
16991
16993
  let a; try { a = JSON.parse(line); } catch (_) { continue; }
16992
16994
  n++;
16993
- runs.push({ id: a[0], branch: a[1], sha: a[2], event: a[3], status: a[4], conclusion: a[5], attempt: a[6], createdMs: Date.parse(a[7]), updatedMs: Date.parse(a[8]), message: a[9] });
16995
+ // #692: `.name` is the workflow's `name:` (a `run-name:` is `.display_title`) — what the
16996
+ // ship's gate list and #688's per-workflow rule key on.
16997
+ runs.push({ id: a[0], branch: a[1], sha: a[2], event: a[3], status: a[4], conclusion: a[5], attempt: a[6], createdMs: Date.parse(a[7]), updatedMs: Date.parse(a[8]), message: a[9], workflowName: a[10] || undefined });
16994
16998
  }
16995
16999
  if (n >= 1000) capped.push(day);
16996
17000
  }
@@ -17013,7 +17017,7 @@ function cmdBatchStats(argv) {
17013
17017
 
17014
17018
  const cfg = shipBatch.parseShipBatch(doc);
17015
17019
  const waitCfg = shipBatch.parseShipBatchWait(doc);
17016
- const rep = batchStats.derive({ commits, runs, builds, trunk, config: { n: cfg.n, waitSec: waitCfg.sec } });
17020
+ const rep = batchStats.derive({ commits, runs, builds, trunk, config: { n: cfg.n, waitSec: waitCfg.sec }, verifying: verifyRuns.parsePolicy(doc) });
17017
17021
  rep.repo = shortRepo(repoAbs);
17018
17022
  rep.since = sinceIso;
17019
17023
  rep.until = new Date(nowMs).toISOString();
@@ -64,11 +64,12 @@ const isBatchRef = (b) => String(b || '').startsWith(shipBatch.REF_PREFIX);
64
64
 
65
65
  /**
66
66
  * When did `branch` go green at the head it had at time `atMs`? Its runs created before `atMs` are
67
- * read; the newest sha among them is the head at that moment. Green only when every run at that sha
68
- * finished success (cancelled aside, as combinedVerdict reads it) by `atMs` → the latest finish.
67
+ * read; the newest sha among them is the head at that moment. Green only when combinedVerdict reads
68
+ * the runs at that sha green, and their successes finished by `atMs` → the latest finish.
69
69
  * Null when there is no run, or the head was not green yet — unknown, never a guess.
70
+ * `verifying` (#692): the ship's policy, so a wholly skipped workflow reads as the batch lane reads it.
70
71
  */
71
- function greenAt(runsByBranch, branch, atMs, sha = null) {
72
+ function greenAt(runsByBranch, branch, atMs, sha = null, verifying = null) {
72
73
  const rows = (runsByBranch.get(branch) || []).filter((r) => r.createdMs <= atMs);
73
74
  if (!rows.length) return null;
74
75
  const headSha = sha
@@ -76,12 +77,28 @@ function greenAt(runsByBranch, branch, atMs, sha = null) {
76
77
  : rows.reduce((a, b) => (b.createdMs > a.createdMs ? b : a)).sha;
77
78
  if (!headSha) return null;
78
79
  const at = rows.filter((r) => r.sha === headSha);
79
- const v = shipBatch.combinedVerdict(at.map((r) => ({ status: r.status, conclusion: r.conclusion, attempt: r.attempt })));
80
+ const v = shipBatch.combinedVerdict(at.map(verdictRow), verdictOpts(verifying));
80
81
  if (v.state !== 'green') return null;
81
82
  const done = Math.max(...at.filter((r) => r.conclusion === 'success').map((r) => r.updatedMs));
82
83
  return done <= atMs ? done : null;
83
84
  }
84
85
 
86
+ /**
87
+ * #692: the projection combinedVerdict reads. `workflowName` and `event` ride along so #688's rule
88
+ * (a wholly skipped workflow is not judged beside a run that can verify the code) reads these rows
89
+ * exactly as `colab ship --batch` reads its own. A side effect of the name, wanted for the same
90
+ * reason: #629 now applies here too, so a named workflow whose only run was cancelled no longer reads
91
+ * green beside another workflow's success. A row without the field stays unnamed, read as before.
92
+ */
93
+ function verdictRow(r) {
94
+ return {
95
+ status: r.status, conclusion: r.conclusion, attempt: r.attempt, databaseId: r.id,
96
+ ...(r.workflowName ? { workflowName: r.workflowName } : {}),
97
+ ...(r.event ? { event: r.event } : {}),
98
+ };
99
+ }
100
+ const verdictOpts = (verifying) => (verifying ? { verifying } : {});
101
+
85
102
  /** Which feature branch carried a serial landing that closed `issues`, as of `atMs`? Newest run wins. */
86
103
  function branchForIssues(runsByBranch, issues, atMs) {
87
104
  if (!issues.length) return null;
@@ -100,14 +117,17 @@ function branchForIssues(runsByBranch, issues, atMs) {
100
117
  /**
101
118
  * The report. Inputs:
102
119
  * commits [{ sha, dateMs, body }] — trunk first-parent, inside the window, any order
103
- * runs [{ id, branch, sha, event, status, conclusion, attempt, createdMs, updatedMs, message? }]
120
+ * runs [{ id, branch, sha, event, status, conclusion, attempt, createdMs, updatedMs, message?,
121
+ * workflowName? }]
104
122
  * `message` is the head commit's message, needed only for ship-batch/** rows
123
+ * verifying optional — the ship's verify-runs policy (`{gate, ignore}`, #692); absent, a skipped
124
+ * row reads red as before
105
125
  * builds optional { [sha]: [message, …] } — every commit message of an UNLANDED build, when the
106
126
  * caller could read them (compare API); a landed build is read from trunk instead
107
127
  * trunk trunk branch name
108
128
  * config { n, waitSec } — the repo's declared knobs, echoed so the report says what it tunes
109
129
  */
110
- function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config = {} } = {}) {
130
+ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config = {}, verifying = null } = {}) {
111
131
  const notes = [];
112
132
  const runsByBranch = new Map();
113
133
  const trunkRuns = new Map(); // sha → rows
@@ -157,12 +177,12 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
157
177
  for (const l of landings) {
158
178
  if (l.kind === 'batch') {
159
179
  for (const m of l.members) {
160
- changes.push({ landing: l, branch: m.branch, issues: branchName.branchIssueNumbers(m.branch), greenMs: greenAt(runsByBranch, m.branch, l.atMs, m.sha), atMs: l.atMs });
180
+ changes.push({ landing: l, branch: m.branch, issues: branchName.branchIssueNumbers(m.branch), greenMs: greenAt(runsByBranch, m.branch, l.atMs, m.sha, verifying), atMs: l.atMs });
161
181
  }
162
182
  } else {
163
183
  const br = branchForIssues(runsByBranch, l.issues, l.atMs);
164
184
  l.branch = br;
165
- changes.push({ landing: l, branch: br, issues: l.issues, greenMs: br ? greenAt(runsByBranch, br, l.atMs) : null, atMs: l.atMs });
185
+ changes.push({ landing: l, branch: br, issues: l.issues, greenMs: br ? greenAt(runsByBranch, br, l.atMs, null, verifying) : null, atMs: l.atMs });
166
186
  }
167
187
  }
168
188
 
@@ -171,7 +191,7 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
171
191
  const buildRows = [];
172
192
  for (const [k, rows] of batchRuns) {
173
193
  const [ref, sha] = k.split(' ');
174
- const v = shipBatch.combinedVerdict(rows.map((r) => ({ status: r.status, conclusion: r.conclusion, attempt: r.attempt, databaseId: r.id })));
194
+ const v = shipBatch.combinedVerdict(rows.map(verdictRow), verdictOpts(verifying));
175
195
  const landed = landedHeads.has(sha);
176
196
  const messages = landed ? null : (builds[sha] || rows.map((r) => r.message).filter(Boolean).slice(0, 1));
177
197
  buildRows.push({ ref, sha, state: v.state, attempt: v.attempt, landed, createdMs: Math.min(...rows.map((r) => r.createdMs)), messages });
@@ -235,14 +255,14 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
235
255
  const via = tagVia ? { via: c.landing.kind === 'serial' ? 'serial' : 'batch-of-one' } : {};
236
256
  for (const o of changes) {
237
257
  if (o === c || o.landing === c.landing || o.atMs <= c.atMs || !o.branch || o.branch === c.branch) continue;
238
- const gNow = greenAt(runsByBranch, o.branch, c.atMs);
258
+ const gNow = greenAt(runsByBranch, o.branch, c.atMs, null, verifying);
239
259
  if (gNow !== null) {
240
260
  missed = true;
241
261
  pairs.push({ kind: 'missed', landed: label, partner: o.branch, ...via });
242
262
  continue;
243
263
  }
244
264
  if (end === null) continue;
245
- const gEnd = greenAt(runsByBranch, o.branch, end);
265
+ const gEnd = greenAt(runsByBranch, o.branch, end, null, verifying);
246
266
  if (gEnd !== null && gEnd > c.atMs) {
247
267
  near = true;
248
268
  const from = c.greenMs !== null ? c.greenMs : c.atMs;
@@ -18,6 +18,8 @@
18
18
  * semantic conflicts need no shared file. The combined run is the gate.
19
19
  */
20
20
 
21
+ const verifyRuns = require('./verify-runs');
22
+
21
23
  // The SAFETY ceiling (#557): what any repo may declare, never what it gets. 3 until a red batch had
22
24
  // a cheaper exit than N serial cycles; split-and-retry (nextStep's `split`) is that exit, so the
23
25
  // ceiling is now 8 — the size from which bisection beats a serial fallback. A repo's own
@@ -384,33 +386,71 @@ function wiring(fires) {
384
386
  * least one success. `attempt` is the highest run attempt seen — how many times it was re-run.
385
387
  * Unlike summarizeRunsForCommit it does NOT reduce to the newest run per workflow (#461): a batch
386
388
  * ref is built fresh and re-run in place (same run, higher `attempt`), so it carries no superseded
387
- * attempts of a workflow for that reduction to set aside. Nor does it set a wholly skipped workflow
388
- * aside (#688): a skip here reads red, so a workflow gated off on `ship-batch/**` costs a split or
389
- * a serial landing rather than a refusal of trunk.
389
+ * attempts of a workflow for that reduction to set aside.
390
+ *
391
+ * #692: `opts.verifying` (the verify-runs.js policy, `{gate, ignore}`) applies #688's rule here too:
392
+ * a named workflow whose every row is `skipped` executed nothing, so it is set aside beside a row
393
+ * that can verify the code, unless `ship-gate-workflows` names it. Measured shape (#688): a
394
+ * workflow with every job gated on an unset repository variable fires on the batch push, concludes
395
+ * skipped, and read every batch red. Without `opts.verifying` nothing is set aside — a skip reads
396
+ * red, as before; batchGreenCoversTrunk asks that strict reading on purpose.
390
397
  */
391
- function combinedVerdict(rows) {
398
+ function combinedVerdict(rows, opts = {}) {
392
399
  const list = Array.isArray(rows) ? rows : null;
393
400
  if (list === null) return { state: 'pending', attempt: 1, runIds: [], why: 'the run list could not be read' };
394
401
  const runIds = list.map((r) => r.databaseId).filter((x) => x !== null && x !== undefined);
395
402
  const attempt = list.reduce((m, r) => Math.max(m, Number(r.attempt) || 1), 1);
396
403
  if (list.length === 0) return { state: 'none', attempt, runIds, why: 'no run at the batch head yet' };
397
- const bad = list.find((r) => r.status === 'completed' && r.conclusion !== 'success' && r.conclusion !== 'cancelled');
398
- if (bad) return { state: 'red', attempt, runIds, why: `a run finished ${bad.conclusion}` };
399
- if (list.some((r) => r.status !== 'completed')) return { state: 'pending', attempt, runIds, why: 'a run is still in flight' };
404
+ const policy = opts && opts.verifying ? opts.verifying : null;
405
+ const { judged, skippedOnly } = policy ? setAsideSkippedWorkflows(list, policy) : { judged: list, skippedOnly: [] };
406
+ const note = verifyRuns.skippedOnlyNote(skippedOnly);
407
+ const bad = judged.find((r) => r.status === 'completed' && r.conclusion !== 'success' && r.conclusion !== 'cancelled');
408
+ if (bad) {
409
+ const gated = bad.conclusion === 'skipped' && bad.workflowName && policy && Array.isArray(policy.gate) && policy.gate.includes(bad.workflowName);
410
+ return { state: 'red', attempt, runIds, why: gated
411
+ ? `workflow "${bad.workflowName}" finished skipped — ${verifyRuns.GATE_KEY} names it, so it must run here (#692)`
412
+ : `a run finished ${bad.conclusion}` };
413
+ }
414
+ if (judged.some((r) => r.status !== 'completed')) return { state: 'pending', attempt, runIds, why: `a run is still in flight${note}` };
400
415
  // #629 (the batch-ref twin of #628): a NAMED workflow whose rows here are all cancelled verified
401
416
  // nothing, and another workflow's success must not carry the verdict for it — measured shape: the
402
417
  // test workflow hung and was cancelled, a lint workflow passed, and the batch read green. A
403
418
  // batch ref is re-run in place (same run, higher attempt), so a cancelled row is never a
404
419
  // superseded straggler beside a newer run of its workflow; a same-workflow success still clears
405
420
  // it. Unnamed rows (batch-stats.js projections, older fixtures) stay neutral, as in #628.
406
- const succeeded = new Set(list.filter((r) => r.conclusion === 'success' && r.workflowName).map((r) => r.workflowName));
407
- const cancelledOnly = list.find((r) => r.workflowName && r.conclusion === 'cancelled' && !succeeded.has(r.workflowName));
421
+ const succeeded = new Set(judged.filter((r) => r.conclusion === 'success' && r.workflowName).map((r) => r.workflowName));
422
+ const cancelledOnly = judged.find((r) => r.workflowName && r.conclusion === 'cancelled' && !succeeded.has(r.workflowName));
408
423
  if (cancelledOnly) {
409
424
  const id = cancelledOnly.databaseId !== null && cancelledOnly.databaseId !== undefined ? ` (run ${cancelledOnly.databaseId})` : '';
410
425
  return { state: 'red', attempt, runIds, why: `workflow "${cancelledOnly.workflowName}" never finished here — its only run${id} was cancelled, so it verified nothing; re-run it` };
411
426
  }
412
- if (list.some((r) => r.conclusion === 'success')) return { state: 'green', attempt, runIds, why: `${list.length} run(s): all success` };
413
- return { state: 'red', attempt, runIds, why: 'every run was cancelled' };
427
+ if (judged.some((r) => r.conclusion === 'success')) return { state: 'green', attempt, runIds, why: `${judged.length} run(s): all success${note}` };
428
+ return { state: 'red', attempt, runIds, why: skippedOnly.length ? `every run that ran was cancelled${note}` : 'every run was cancelled' };
429
+ }
430
+
431
+ /**
432
+ * #692: #688's rule (git.js setAsideWhollySkipped) for the rows at one batch head. A NAMED workflow
433
+ * whose every row is a finished `skipped` is set aside — returned as `skippedOnly` — when:
434
+ * - `ship-gate-workflows` does not name it. A named gate workflow that skipped reads red: the
435
+ * owner said exactly these must count. (git.js sets nothing aside once the list is declared,
436
+ * because its rows were already narrowed to the list; batch rows are not, so the test is per
437
+ * name.)
438
+ * - another row can verify the code (a verifying trigger, or no `event` field). All-skipped
439
+ * stays red (#514): nothing verified the batch.
440
+ * Unnamed rows are never set aside (#92). A workflow with any row that is not a finished skip is
441
+ * left whole, so its skipped row still reads red beside it, as before #692.
442
+ */
443
+ function setAsideSkippedWorkflows(list, policy) {
444
+ const gate = policy && Array.isArray(policy.gate) ? policy.gate : null;
445
+ const isSkipped = (r) => !!r && r.status === 'completed' && r.conclusion === 'skipped';
446
+ const names = new Set(list.filter((r) => r && r.workflowName).map((r) => r.workflowName));
447
+ const wholly = new Set([...names].filter((n) => (!gate || !gate.includes(n))
448
+ && list.every((r) => !r || r.workflowName !== n || isSkipped(r))));
449
+ const unchanged = { judged: list, skippedOnly: [] };
450
+ if (!wholly.size) return unchanged;
451
+ const rest = list.filter((r) => !r || !wholly.has(r.workflowName));
452
+ if (!rest.some((r) => !isSkipped(r) && verifyRuns.setAsideReason(r, null) === null)) return unchanged;
453
+ return { judged: rest, skippedOnly: list.filter((r) => r && wholly.has(r.workflowName)) };
414
454
  }
415
455
 
416
456
  /**
@@ -524,6 +564,10 @@ function givenUpRefs({ refs, members } = {}) {
524
564
  * - the workflow FILES firing on a trunk push and on a `ship-batch/**` push are the same set;
525
565
  * - there are at least as many batch rows as trunk-firing workflows.
526
566
  * Anything else → false, and trunk waits for its own run exactly as today.
567
+ *
568
+ * #692: the batch rows are read WITHOUT the skipped-workflow rule (combinedVerdict with no policy).
569
+ * A workflow gated on the trunk ref is `skipped` on every batch ref, so a skip here would vouch for
570
+ * a trunk run that will execute; the stand-in needs every batch row to have run and passed.
527
571
  */
528
572
  function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires }) {
529
573
  const t = Array.isArray(trunkRows) ? trunkRows : [];