@futurelastic/colab-handbook 1.20.1-rc.2 → 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.2"
36
+ "version": "1.20.1-rc.4"
37
37
  }
@@ -124,11 +124,12 @@
124
124
  # (`colab ship` dispatches it for you when a red in this workflow is what stands between the branch
125
125
  # and trunk). A dispatch on any ref other than main is ALWAYS dry, input or not. A dry run checks out
126
126
  # the branch, runs every step with `--dry` — the same decisions, nothing promoted, tagged, released,
127
- # pushed or dispatched — and skips only the steps whose names end in `[publish]`. The step
127
+ # pushed or dispatched — and turns off the steps whose names end in `[publish]`. The step
128
128
  # "Dry run — nothing is tagged, released or published" runs only then; it is how the cure rule
129
129
  # recognises the run. Keep both names as they are: the cure rule matches steps BY NAME, and accepts
130
130
  # a dry run only if every step that ran in trunk's red run passed in it and every step it skipped
131
- # ends in `[publish]`. So a red INSIDE a `[publish]` step, or in the npm or deploy jobs (which never
131
+ # ends in `[publish]` or is one of the two steps a dry run never runs: the #547 retry and the
132
+ # heavy-lane start. So a red INSIDE a `[publish]` step, or in the npm or deploy jobs (which never
132
133
  # run without a tag), cannot be cured by a dry run — that stays a human ci-grant.
133
134
  #
134
135
  # DOWNLOADS — EVERY FINAL, NOT ONLY THE ONES THIS RUN TAGGED (#669). A repo whose finals carry files
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. */
@@ -164,18 +164,32 @@
164
164
  * This is the not-a-back-door proof: a red INSIDE a publishing step can never be cured this way,
165
165
  * because the dry run skips exactly that step. It is 4b, applied to dry-run instances on every
166
166
  * path, not only the carve-out's;
167
- * D3. every step the dry run did NOT run to success is a skipped publishing step. A dry run that
168
- * also skipped some ordinary step past trunk's failure point has not run the job, it has run
169
- * part of it.
167
+ * D3. every step the dry run did NOT run to success is a skipped publishing step, or one of the
168
+ * template's steps that every dry run skips by construction (`DRY_RUN_CONDITIONAL_STEPS`, #694).
169
+ * A dry run that also skipped some other step past trunk's failure point has not run the job, it
170
+ * has run part of it.
170
171
  *
171
172
  * Why a NAME marker and not a list declared in the workflow: steps are matched by exact name (D2/4b),
172
173
  * so marking the very step that failed on trunk renames it, and D2 then reads it as absent and
173
174
  * refuses. A list inside the workflow would be read from the branch, which is the party being graded.
174
175
  *
175
- * Limit, stated: a red in a publishing step, or in a later job that only runs after a tag (npm,
176
- * deploy), cannot be cured by a dry run. That stays a ci-grant. So does a red job that ran ZERO steps
177
- * (a runner that never picked it up) on the carve-out path: 4c has no usable duration for it and
178
- * refuses, which is the safe direction and a deliberately unmade loosening, like the timeout case.
176
+ * Why D3's second arm is a fixed list of exact names in this module (#694), not "also skipped on trunk"
177
+ * and not a second marker. Steps past trunk's failure point are always skipped on trunk, and on a red
178
+ * that ran zero steps every step was, so "also skipped on trunk" admits exactly what D3 refuses. A marker
179
+ * needs a template change and a sync in every adopter's copy before it helps anyone. The list is read
180
+ * from the CLI, never from the branch being graded, and it works on every copy already in the field; an
181
+ * adopter who renames one of those steps gets a refusal, the safe direction. A branch that edits its
182
+ * workflow can rename a step to a listed name, as it can append `[publish]` or gut a `run:` body: that is
183
+ * the carve-out's stated content-blindness, and D2 still refuses for any step that ran on trunk.
184
+ *
185
+ * Limits, stated: a red in a publishing step, or in a later job that only runs after a tag (npm,
186
+ * deploy), cannot be cured by a dry run. That stays a ci-grant. So does a red on a run where a listed
187
+ * step RAN on trunk (the retry step on an hourly retry run, the heavy-lane start after a cut): D2 requires
188
+ * it to pass in the dry run, and the dry run skips it. So does a dry run that skipped its Finalize step
189
+ * because the heavy lane is not green at the candidate. And so does a red job that ran ZERO steps whose
190
+ * timestamps are equal or missing, on the carve-out path: 4c has no usable duration for it. Measured, a
191
+ * job the runner service refused has 2-6 s between its timestamps, so 4c passes it; relaxing 4c stays
192
+ * unmade until the unusable shape is observed, like the timeout case.
179
193
  *
180
194
  * DISPATCH EVIDENCE FOR A JOB A BRANCH PUSH SKIPS (#510). One level below #474: the WORKFLOW runs on a
181
195
  * branch push, but one of its JOBS is trunk-only by its own `if:` (true on trunk, on a schedule and on
@@ -264,10 +278,31 @@ const PUBLISH_STEP_MARKER = '[publish]';
264
278
  * step name byte for byte. */
265
279
  const DRY_RUN_STEP = 'Dry run — nothing is tagged, released or published';
266
280
 
281
+ /** The template steps every dry run skips on their own `if:` (#694), admitted by D3 by exact name.
282
+ * The retry step runs only on the hourly retry run (`RETRY_RUN`, a schedule); the heavy-lane start needs
283
+ * a tag, and a dry run hands none on. tools/lib/release-auto-template.test.js pins these names and
284
+ * conditions against the template, and fails on a new conditional step nobody has classified. */
285
+ const DRY_RUN_CONDITIONAL_STEPS = Object.freeze([
286
+ 'Retry a refused cut once the CLI moved (#547)',
287
+ 'Start the heavy lane at the new candidate',
288
+ ]);
289
+
267
290
  function isPublishStepName(name) {
268
291
  return typeof name === 'string' && name.trimEnd().endsWith(PUBLISH_STEP_MARKER);
269
292
  }
270
293
 
294
+ /** A step D3 lets a dry run skip: a publishing step, or one every dry run skips by construction. */
295
+ function dryRunMaySkip(name) {
296
+ return isPublishStepName(name) || DRY_RUN_CONDITIONAL_STEPS.includes(name);
297
+ }
298
+
299
+ /** A step the job's own definition ran, as against the runner's bookkeeping, which GitHub reports as
300
+ * `success` even when every step of the job was skipped. */
301
+ function ranOwnStep(s) {
302
+ return !!s && s.conclusion === 'success' && s.name !== 'Set up job' && s.name !== 'Complete job'
303
+ && !String(s.name).startsWith('Post ');
304
+ }
305
+
271
306
  /** A job instance is a dry run iff its sentinel step concluded `success`. A skipped sentinel is an
272
307
  * ordinary run (the template's `if:` was false), never a dry one. */
273
308
  function isDryRunSteps(steps) {
@@ -432,9 +467,10 @@ function dryRunEvidence(red, mine) {
432
467
  }
433
468
  for (const s of mine.steps) {
434
469
  if (!s || s.conclusion === 'success') continue;
435
- if (s.conclusion === 'skipped' && isPublishStepName(s.name)) continue;
470
+ if (s.conclusion === 'skipped' && dryRunMaySkip(s.name)) continue;
436
471
  return `step \`${s && s.name}\` concluded \`${s && s.conclusion}\` in the branch's dry run of job \`${label}\` and is not a publishing step ` +
437
- `(name ending \`${PUBLISH_STEP_MARKER}\`) — a dry run may skip only the steps that write outside the run`;
472
+ `(name ending \`${PUBLISH_STEP_MARKER}\`) or a step every dry run skips (${DRY_RUN_CONDITIONAL_STEPS.map((n) => `\`${n}\``).join(', ')}) — ` +
473
+ 'a dry run may skip only those';
438
474
  }
439
475
  return '';
440
476
  }
@@ -604,6 +640,13 @@ function workflowCarveOut(jobEvidence) {
604
640
  }
605
641
  }
606
642
 
643
+ // 4b leaves nothing to compare when the job ran no step on trunk, and GitHub reports a job whose
644
+ // steps were all skipped as `success` (#694) — so the branch must show one step of its own that ran.
645
+ if (!red.ranSteps.length && !mine.steps.some(ranOwnStep)) {
646
+ return { ok: false, jobs: [],
647
+ reason: `job \`${red.name}\` ran no step on trunk and no step of its own on the branch's run — a job whose steps were all skipped reports success without having run anything` };
648
+ }
649
+
607
650
  // 4c — duration floor, relative to the failure it replaces.
608
651
  if (!usableMs(red.durationMs) || !usableMs(mine.durationMs)) {
609
652
  return { ok: false, jobs: [],
@@ -656,10 +699,10 @@ function manifestStepProof(jobEvidence, { noLateSkip = false } = {}) {
656
699
  if (at > last) last = at;
657
700
  }
658
701
  if (noLateSkip) {
659
- // A dry run (#474) skips its `[publish]` steps by design, and D3 already refused any OTHER skip
660
- // in it — so those, and only those, are not a dropped tool.
702
+ // A dry run (#474) skips the steps `dryRunMaySkip` names by design, and D3 already refused any
703
+ // OTHER skip in it — so those, and only those, are not a dropped tool.
661
704
  const late = mine.steps.slice(last + 1)
662
- .find((s) => s && s.conclusion === 'skipped' && !(mine.dryRun && isPublishStepName(s.name)));
705
+ .find((s) => s && s.conclusion === 'skipped' && !(mine.dryRun && dryRunMaySkip(s.name)));
663
706
  if (late) {
664
707
  return { ok: false,
665
708
  reason: `step \`${late.name}\` in job \`${jobLabel(red)}\` comes after trunk's failure point and was skipped on the branch — ` +
@@ -1009,4 +1052,4 @@ function admittedText(admitted) {
1009
1052
  module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, manifestStepProof, shapeJobEvidence, dryRunDispatchPlan,
1010
1053
  cureDispatchPlan, dispatchEvidence,
1011
1054
  priorRedShaFromMessage, redJobSet, redSetShrank,
1012
- WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL, PYTHON_MANIFEST_REFUSAL, PUBLISH_STEP_MARKER, DRY_RUN_STEP };
1055
+ WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL, PYTHON_MANIFEST_REFUSAL, PUBLISH_STEP_MARKER, DRY_RUN_STEP, DRY_RUN_CONDITIONAL_STEPS };
@@ -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 };