@futurelastic/colab-handbook 1.20.1-rc.3 → 1.20.1-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.20.1-rc.3"
36
+ "version": "1.20.1-rc.5"
37
37
  }
package/tools/colab CHANGED
@@ -12060,7 +12060,8 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
12060
12060
  // #606: trunk's tip has no FINISHED run and is a docs-only commit (an adopter's CI `paths-ignore`s
12061
12061
  // docs, or the run is simply not done) — docs change no code, so trunk's CI is the verdict of the
12062
12062
  // newest trunk commit that is NOT docs-only. A finished red run at the tip is never overridden.
12063
- if (target === trunk && (run.status === 'none' || run.status !== 'completed')) {
12063
+ // #688: a tip where every workflow skipped ran nothing, which is not a red: read it like `none`.
12064
+ if (target === trunk && (run.status === 'none' || run.status !== 'completed' || run.allSkipped)) {
12064
12065
  const door = docsOnlyTipDoor(repoAbs, trunk, run.sha, readOpts);
12065
12066
  if (door) return door;
12066
12067
  }
@@ -12190,7 +12191,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
12190
12191
  */
12191
12192
  function classifyCiRun(repoAbs, run, at) {
12192
12193
  const v = classifyCiRunRaw(repoAbs, run, at);
12193
- return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) + verifyRuns.dispatchCountedNote(run && run.dispatchCounted) + readViaNote(run) };
12194
+ return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.skippedOnlyNote(run && run.skippedOnly) + verifyRuns.setAsideNote(run && run.setAside) + verifyRuns.dispatchCountedNote(run && run.dispatchCounted) + readViaNote(run) };
12194
12195
  }
12195
12196
 
12196
12197
  /** #682: a forge verdict's not-green contexts, named — '' on GitHub, or when every context is green. */
@@ -12408,17 +12409,27 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
12408
12409
  // the trunk-CI row reads (commit statuses on Forgejo) — never keyed on the gh flag, so a stale or red
12409
12410
  // branch head cannot pass here as `unread` while the CI row passes on the forge's statuses.
12410
12411
  const fc = forgeCi(repoAbs);
12412
+ let verifiedRun = null;
12411
12413
  if (headSha && fc) run = fc.ciVerdict(headSha, { branch });
12412
- else if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
12414
+ else if (headSha && gh) {
12415
+ // #691: one read, two summaries. `run` stays exactly what the stale-base and docs-only rows have
12416
+ // always read; `verifiedRun` applies the verifying-runs policy (#503) the trunk row uses, so the
12417
+ // head row below never refuses on a run that policy sets aside (a release lane, an ignored workflow).
12418
+ const rows = git.ghRunsForCommit(repoAbs, branch, headSha);
12419
+ run = git.summarizeRunsForCommit(rows, headSha);
12420
+ verifiedRun = git.summarizeRunsForCommit(rows, headSha, { verifying: verifyingPolicy(repoAbs), finishedRed: true });
12421
+ }
12413
12422
  // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
12414
12423
  // #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
12415
- // row — the class code-ship B1a reads through `colab ci-wait` on GitHub. null on GitHub, and where
12416
- // the head has no run to judge (the stale-base row speaks for those).
12417
- const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind }) : null;
12424
+ // row. #691: on GitHub it is emitted only for a head whose run FINISHED red — waiting on a running
12425
+ // one stays code-ship B1a's `colab ci-wait` — and is null otherwise, as it is wherever the head has
12426
+ // no run to judge (the stale-base row speaks for those).
12427
+ const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind })
12428
+ : (gh ? staleBase.githubBranchHeadRedVerdict({ headSha, run: verifiedRun, branch }) : null);
12418
12429
  return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ciReadable: !!(fc || gh) }), run, headSha, headCi };
12419
12430
  }
12420
12431
 
12421
- /** #682: the forge branch-head CI row's name — one spelling for the JSON and the prose table. */
12432
+ /** #682: the branch-head CI row's name (forge; on GitHub a finished-red head only, #691) — one spelling for the JSON and the prose table. */
12422
12433
  const BRANCH_HEAD_CI_ROW = 'branch CI green at its head (#682)';
12423
12434
 
12424
12435
  /**
@@ -13242,7 +13253,7 @@ function cmdShipDryJson(opts) {
13242
13253
  } else {
13243
13254
  checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
13244
13255
  class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
13245
- const hc = staleJson.headCi; // #682: forge only — a red head needs a person, a running one clears
13256
+ const hc = staleJson.headCi; // #682 forge, #691 GitHub (red only) — a red head needs a person, a running one clears
13246
13257
  if (hc) checks.push({ name: BRANCH_HEAD_CI_ROW, ok: hc.ok, class: hc.ok ? null : (hc.selfClearing ? SELF_CLEARING : HUMAN_GATED), verdict: hc.verdict, detail: hc.detail });
13247
13258
  }
13248
13259
  // #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
@@ -193,7 +193,9 @@ function create(repoAbs, eng) {
193
193
  if (typeof rowsFilter === 'function') rows = rowsFilter(rows);
194
194
  const summary = require('./git').summarizeRunsForCommit(rows, full);
195
195
  // #682: additive — the contexts that keep this sha from green, so a refusal can name them.
196
- const ng = notGreen(rows);
196
+ // #688: a context the verdict set aside as skipped is not one of them.
197
+ const aside = new Set((summary.skippedOnly || []).map((x) => x.workflowName));
198
+ const ng = notGreen(rows).filter((x) => !aside.has(x.name));
197
199
  return ng.length ? { ...summary, notGreen: ng } : summary;
198
200
  },
199
201
 
package/tools/lib/git.js CHANGED
@@ -1254,6 +1254,10 @@ function excludedRunSummary(rows) {
1254
1254
  * along as `setAside`, each with its reason. #567: a `workflow_dispatch` run the policy's
1255
1255
  * `dispatchVerifies` resolver rescues (lost push event) is counted and named in `dispatchCounted`. Opt-in: without `opts.verifying` nothing changes, so
1256
1256
  * readers that never asked (release finalize, the base-ci advisory, ci-grant) read exactly as before.
1257
+ *
1258
+ * #688: a workflow whose every run at the sha was skipped is then set aside beside a run that can
1259
+ * verify the code (setAsideWhollySkipped, below); the rows ride along as `skippedOnly`, and `allSkipped`
1260
+ * says nothing but such workflows ran here. `runCount` no longer counts them (#461's rule).
1257
1261
  */
1258
1262
  function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1259
1263
  if (allForSha === null) return null;
@@ -1268,18 +1272,32 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1268
1272
  dispatchCounted = split.dispatchCounted || [];
1269
1273
  }
1270
1274
  const { heads, superseded } = newestRunPerWorkflow(owned);
1275
+ const { judged, skippedOnly, allSkipped } = setAsideWhollySkipped(heads, superseded, opts && opts.verifying);
1271
1276
  const extra = {
1272
1277
  ...(dropped.length ? { excluded: excludedRunSummary(dropped) } : {}),
1273
1278
  ...(superseded.length ? { superseded: excludedRunSummary(superseded) } : {}),
1279
+ ...(skippedOnly.length ? { skippedOnly: excludedRunSummary(skippedOnly) } : {}),
1280
+ ...(allSkipped ? { allSkipped: true } : {}),
1274
1281
  ...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
1275
1282
  ...(dispatchCounted.length ? { dispatchCounted: excludedRunSummary(dispatchCounted) } : {}),
1283
+ // #691: opt-in (`opts.finishedRed`), so no reader that never asked sees a new field — every
1284
+ // JUDGED run that finished red: completed, and not success, cancelled or skipped (neither of
1285
+ // those two executed anything). The summary's single `conclusion` names only the first not-green
1286
+ // row it meets, which can be a `skipped` one beside a real failure; a caller asking "did any run
1287
+ // finish red here" reads this list instead. Absent when none did.
1288
+ ...(opts && opts.finishedRed && judged.some(isFinishedRed) ? { finishedRed: excludedRunSummary(judged.filter(isFinishedRed)) } : {}),
1276
1289
  // #651: the rows came from the unfiltered listing because the forge's filter index was empty.
1277
1290
  ...(allForSha.some((x) => x && x.readVia === 'unfiltered-listing') ? { readVia: 'unfiltered-listing' } : {}),
1278
1291
  };
1279
- const r = summarizeRepoOwnedRuns(heads, sha);
1292
+ const r = summarizeRepoOwnedRuns(judged, sha);
1280
1293
  return { ...r, ...extra };
1281
1294
  }
1282
1295
 
1296
+ /** #691: a run that ran and failed — completed, and not success, cancelled or skipped. */
1297
+ function isFinishedRed(x) {
1298
+ return !!x && x.status === 'completed' && x.conclusion !== 'success' && x.conclusion !== 'cancelled' && x.conclusion !== 'skipped';
1299
+ }
1300
+
1283
1301
  /** Sort key for "which run of one workflow is newer": createdAt, then databaseId; null = unknown. */
1284
1302
  function runRecency(x) {
1285
1303
  const t = x && x.createdAt ? Date.parse(x.createdAt) : NaN;
@@ -1316,7 +1334,7 @@ function isNewerRun(a, b) {
1316
1334
  * nothing (a same-repo `pull_request` run gated off by a fork-PR `if:`, a `workflow_run` that
1317
1335
  * declined), so a newer `skipped` row never stands for a workflow that has a run that ran: push
1318
1336
  * `failure` + newer `skipped` reads red, push `success` + newer `skipped` reads green. A workflow
1319
- * whose runs are ALL skipped still reads not-green, as before.
1337
+ * whose runs are ALL skipped is setAsideWhollySkipped's question (#688).
1320
1338
  *
1321
1339
  * Newest = later createdAt, then higher databaseId; when neither key separates two rows, gh's
1322
1340
  * newest-first order decides (the first row seen is kept). An unfinished newest run still blocks
@@ -1349,6 +1367,39 @@ function newestRunPerWorkflow(rows) {
1349
1367
  return { heads, superseded };
1350
1368
  }
1351
1369
 
1370
+ /**
1371
+ * #688: a NAMED workflow whose every run at the sha concluded `skipped` executed nothing, so it does
1372
+ * not decide the sha once another run there can. Measured: a workflow with every job gated on an
1373
+ * unset repository variable fires on a trunk push, concludes `skipped`, and the sha read
1374
+ * `conclusion=skipped` beside a green CI — every later ship refused, by a merge that passed every
1375
+ * check. The rest of the heads then decide as usual: success is green, a failure is named, a run in
1376
+ * flight is pending (a skipped sibling used to read red while CI ran), cancelled-only is #628's.
1377
+ *
1378
+ * Nothing is set aside when:
1379
+ * - no other head can verify the code. All-skipped stays not-green (#514): nothing verified it.
1380
+ * With no policy, only a verifying trigger counts, so a `workflow_run` success never carries a
1381
+ * skipped CI; with one, its counted rows are already that set.
1382
+ * - `ship-gate-workflows` is declared. That list says exactly these workflows must count, so a
1383
+ * skip there is the owner's named gate not running.
1384
+ * - the workflow has a `cancelled` attempt at the sha: a run started and never finished (#628).
1385
+ * - the row is unnamed: it cannot be told apart from a straggler of another run (#92).
1386
+ *
1387
+ * `allSkipped` marks a sha where such workflows are all that exist, whichever of the above held:
1388
+ * nothing ran there, which is not a red, so the docs-only door (#606) may read past it.
1389
+ */
1390
+ function setAsideWhollySkipped(heads, superseded, policy) {
1391
+ const isSkipped = (x) => !!x && x.status === 'completed' && x.conclusion === 'skipped';
1392
+ const otherAttempt = new Set(superseded.filter((x) => x && x.workflowName && !isSkipped(x)).map((x) => x.workflowName));
1393
+ const wholly = heads.filter((x) => isSkipped(x) && x.workflowName && !otherAttempt.has(x.workflowName));
1394
+ const allSkipped = wholly.length > 0 && wholly.length === heads.length;
1395
+ const unchanged = { judged: heads, skippedOnly: [], allSkipped };
1396
+ if (!wholly.length || allSkipped || (policy && policy.gate)) return unchanged;
1397
+ const rest = heads.filter((x) => !wholly.includes(x));
1398
+ const canVerify = policy ? () => true : (x) => require('./verify-runs').setAsideReason(x, null) === null;
1399
+ if (!rest.some(canVerify)) return unchanged;
1400
+ return { judged: rest, skippedOnly: wholly, allSkipped: false };
1401
+ }
1402
+
1352
1403
  function summarizeRepoOwnedRuns(forSha, sha) {
1353
1404
  if (forSha.length === 0) return { status: 'none', conclusion: null, sha, createdAt: null, databaseId: null, runCount: 0 };
1354
1405
 
@@ -725,9 +725,10 @@ function isSkippedOnly(runs) {
725
725
  * #616: the run rows minus every workflow whose runs at the sha were ALL `skipped` — an opt-in
726
726
  * workflow gated off by an `if:` (a scheduled load profile waiting for its runner) records a skipped
727
727
  * run on every tick, and one landing on the candidate's commit made ci-green read
728
- * "conclusion=skipped" and refused every finalize older than one schedule period. Release-only on
729
- * purpose: the ship gate (git.summarizeRunsForCommit, #514) keeps reading an all-skipped workflow
730
- * as not-green, so this filter is applied by the release callers, never inside git.js.
728
+ * "conclusion=skipped" and refused every finalize older than one schedule period. Wider than the ship
729
+ * gate's own rule (git.js setAsideWhollySkipped, #688) on purpose: this drops such a workflow even
730
+ * when nothing else ran, and fullSuiteVerdict then refuses by name; a declared gate list does not
731
+ * apply. So it stays a filter the release callers apply, never inside git.js.
731
732
  * A workflow with a skipped run AND any other run keeps all its rows (skipped + failure stays red;
732
733
  * cancelled-only is untouched and still fails full-suite). null passes through.
733
734
  */
@@ -384,7 +384,9 @@ function wiring(fires) {
384
384
  * least one success. `attempt` is the highest run attempt seen — how many times it was re-run.
385
385
  * Unlike summarizeRunsForCommit it does NOT reduce to the newest run per workflow (#461): a batch
386
386
  * 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.
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.
388
390
  */
389
391
  function combinedVerdict(rows) {
390
392
  const list = Array.isArray(rows) ? rows : null;
@@ -123,4 +123,43 @@ function branchHeadCiVerdict(a) {
123
123
  `Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`, then run ship again` };
124
124
  }
125
125
 
126
- module.exports = { staleBaseVerdict, branchHeadCiVerdict };
126
+ /**
127
+ * #691: the GitHub half of #682's row. On GitHub the branch head's class used to be left wholly to
128
+ * code-ship B1a (`colab ci-wait`), so `colab ship --dry --json` read READY on a head whose run had
129
+ * FINISHED red — measured on a required secret-scan job that failed before scanning anything. The
130
+ * row now refuses that one state, human-gated, in dry and real ship alike; everything else stays as
131
+ * it was on GitHub (null — no row):
132
+ *
133
+ * a run at the head finished red -> red, human-gated (red:infra or red:finding is B1a's call)
134
+ * green / in flight / no run / unread -> null: B1a's ci-wait still owns the wait, the stale-base
135
+ * row still speaks for `none` and an unread run
136
+ *
137
+ * "Finished red" is #606's docs-only rule (`docsOnlyBranchRow`): completed, and not success,
138
+ * cancelled or skipped — so a code branch is never held to a weaker rule than a docs-only one.
139
+ * `run` is the head's summary read under the verifying-runs policy (#503), the same rule the trunk
140
+ * row uses, so a run that policy sets aside (a release lane, a `ship-ignore-workflows` entry) never
141
+ * refuses here. `run.finishedRed` (tools/lib/git.js) lists every judged red run; without it the
142
+ * summary's own status/conclusion decides.
143
+ *
144
+ * @param {object} a
145
+ * @param {string|null} a.headSha - the branch head on the remote
146
+ * @param {object|null} a.run - summarizeRunsForCommit's verdict at headSha, verifying policy applied
147
+ * @param {string} a.branch
148
+ * @returns {null|{ok:false, verdict:'red', selfClearing:false, detail:string}}
149
+ */
150
+ function githubBranchHeadRedVerdict(a) {
151
+ const run = a && a.run;
152
+ if (!a || !a.headSha || !run || run.status === 'none') return null;
153
+ const listed = Array.isArray(run.finishedRed) ? run.finishedRed : [];
154
+ const summaryRed = run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
155
+ if (!listed.length && !summaryRed) return null;
156
+ const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (GitHub Actions)`;
157
+ const failing = listed.length
158
+ ? listed.map((x) => `${x.workflowName || 'run'} (${x.conclusion || 'none'})`).join(', ')
159
+ : `conclusion=${run.conclusion || 'none'}`;
160
+ return { ok: false, verdict: 'red', selfClearing: false,
161
+ detail: `${at} finished red — failing: ${failing}. A branch lands only on its own green (C7.contract.03): ` +
162
+ 'red:infra → re-run once; red:finding → send it back (code-ship B1a)' };
163
+ }
164
+
165
+ module.exports = { staleBaseVerdict, branchHeadCiVerdict, githubBranchHeadRedVerdict };
@@ -214,4 +214,15 @@ function setAsideNote(rows) {
214
214
  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(', ')}`;
215
215
  }
216
216
 
217
- module.exports = { VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, parsePolicy, setAsideReason, splitVerifying, setAsideNote, workflowTriggers, dispatchCountedNote };
217
+ /**
218
+ * #688: the wholly skipped workflows a verdict did not judge (git.js setAsideWhollySkipped), named so a
219
+ * reader can see a gated workflow did not run. '' when none.
220
+ */
221
+ function skippedOnlyNote(rows) {
222
+ const list = Array.isArray(rows) ? rows : [];
223
+ if (!list.length) return '';
224
+ const names = list.map((x) => `${x.workflowName || 'unnamed'}${x.databaseId ? ` (run ${x.databaseId})` : ''}`);
225
+ return ` — not judged, every run skipped so it ran nothing here (#688; name a workflow in ship-gate-workflows if it must run): ${names.join(', ')}`;
226
+ }
227
+
228
+ module.exports = { VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, parsePolicy, setAsideReason, splitVerifying, setAsideNote, skippedOnlyNote, workflowTriggers, dispatchCountedNote };