@futurelastic/colab-handbook 1.20.1-rc.3 → 1.20.1-rc.4

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.4"
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. */
@@ -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,15 +1272,18 @@ 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) } : {}),
1276
1283
  // #651: the rows came from the unfiltered listing because the forge's filter index was empty.
1277
1284
  ...(allForSha.some((x) => x && x.readVia === 'unfiltered-listing') ? { readVia: 'unfiltered-listing' } : {}),
1278
1285
  };
1279
- const r = summarizeRepoOwnedRuns(heads, sha);
1286
+ const r = summarizeRepoOwnedRuns(judged, sha);
1280
1287
  return { ...r, ...extra };
1281
1288
  }
1282
1289
 
@@ -1316,7 +1323,7 @@ function isNewerRun(a, b) {
1316
1323
  * nothing (a same-repo `pull_request` run gated off by a fork-PR `if:`, a `workflow_run` that
1317
1324
  * declined), so a newer `skipped` row never stands for a workflow that has a run that ran: push
1318
1325
  * `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.
1326
+ * whose runs are ALL skipped is setAsideWhollySkipped's question (#688).
1320
1327
  *
1321
1328
  * Newest = later createdAt, then higher databaseId; when neither key separates two rows, gh's
1322
1329
  * newest-first order decides (the first row seen is kept). An unfinished newest run still blocks
@@ -1349,6 +1356,39 @@ function newestRunPerWorkflow(rows) {
1349
1356
  return { heads, superseded };
1350
1357
  }
1351
1358
 
1359
+ /**
1360
+ * #688: a NAMED workflow whose every run at the sha concluded `skipped` executed nothing, so it does
1361
+ * not decide the sha once another run there can. Measured: a workflow with every job gated on an
1362
+ * unset repository variable fires on a trunk push, concludes `skipped`, and the sha read
1363
+ * `conclusion=skipped` beside a green CI — every later ship refused, by a merge that passed every
1364
+ * check. The rest of the heads then decide as usual: success is green, a failure is named, a run in
1365
+ * flight is pending (a skipped sibling used to read red while CI ran), cancelled-only is #628's.
1366
+ *
1367
+ * Nothing is set aside when:
1368
+ * - no other head can verify the code. All-skipped stays not-green (#514): nothing verified it.
1369
+ * With no policy, only a verifying trigger counts, so a `workflow_run` success never carries a
1370
+ * skipped CI; with one, its counted rows are already that set.
1371
+ * - `ship-gate-workflows` is declared. That list says exactly these workflows must count, so a
1372
+ * skip there is the owner's named gate not running.
1373
+ * - the workflow has a `cancelled` attempt at the sha: a run started and never finished (#628).
1374
+ * - the row is unnamed: it cannot be told apart from a straggler of another run (#92).
1375
+ *
1376
+ * `allSkipped` marks a sha where such workflows are all that exist, whichever of the above held:
1377
+ * nothing ran there, which is not a red, so the docs-only door (#606) may read past it.
1378
+ */
1379
+ function setAsideWhollySkipped(heads, superseded, policy) {
1380
+ const isSkipped = (x) => !!x && x.status === 'completed' && x.conclusion === 'skipped';
1381
+ const otherAttempt = new Set(superseded.filter((x) => x && x.workflowName && !isSkipped(x)).map((x) => x.workflowName));
1382
+ const wholly = heads.filter((x) => isSkipped(x) && x.workflowName && !otherAttempt.has(x.workflowName));
1383
+ const allSkipped = wholly.length > 0 && wholly.length === heads.length;
1384
+ const unchanged = { judged: heads, skippedOnly: [], allSkipped };
1385
+ if (!wholly.length || allSkipped || (policy && policy.gate)) return unchanged;
1386
+ const rest = heads.filter((x) => !wholly.includes(x));
1387
+ const canVerify = policy ? () => true : (x) => require('./verify-runs').setAsideReason(x, null) === null;
1388
+ if (!rest.some(canVerify)) return unchanged;
1389
+ return { judged: rest, skippedOnly: wholly, allSkipped: false };
1390
+ }
1391
+
1352
1392
  function summarizeRepoOwnedRuns(forSha, sha) {
1353
1393
  if (forSha.length === 0) return { status: 'none', conclusion: null, sha, createdAt: null, databaseId: null, runCount: 0 };
1354
1394
 
@@ -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;
@@ -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 };