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

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.1"
36
+ "version": "1.20.1-rc.3"
37
37
  }
@@ -276,7 +276,12 @@ jobs:
276
276
  x86_64|amd64) arch=x64 ;;
277
277
  *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
278
278
  esac
279
- curl -sSL -o gitleaks.tar.gz \
279
+ # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
280
+ # then fails with "not in gzip format", naming neither the download nor the host.
281
+ # --retry: a re-run during the same upstream error spends the one re-run branch CI
282
+ # allows, so a brief error is retried here first. A longer outage still fails, at
283
+ # curl, naming the status (#690).
284
+ curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 -o gitleaks.tar.gz \
280
285
  "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
281
286
  # Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
282
287
  # step then works on BOTH GitHub-hosted and shared self-hosted runners
@@ -266,7 +266,12 @@ jobs:
266
266
  x86_64|amd64) arch=x64 ;;
267
267
  *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
268
268
  esac
269
- curl -sSL -o gitleaks.tar.gz \
269
+ # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
270
+ # then fails with "not in gzip format", naming neither the download nor the host.
271
+ # --retry: a re-run during the same upstream error spends the one re-run branch CI
272
+ # allows, so a brief error is retried here first. A longer outage still fails, at
273
+ # curl, naming the status (#690).
274
+ curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 -o gitleaks.tar.gz \
270
275
  "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
271
276
  # Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
272
277
  # step then works on BOTH GitHub-hosted and shared self-hosted runners
@@ -277,7 +277,12 @@ jobs:
277
277
  x86_64|amd64) arch=x64 ;;
278
278
  *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
279
279
  esac
280
- curl -sSL -o gitleaks.tar.gz \
280
+ # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
281
+ # then fails with "not in gzip format", naming neither the download nor the host.
282
+ # --retry: a re-run during the same upstream error spends the one re-run branch CI
283
+ # allows, so a brief error is retried here first. A longer outage still fails, at
284
+ # curl, naming the status (#690).
285
+ curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 -o gitleaks.tar.gz \
281
286
  "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
282
287
  # Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
283
288
  # step then works on BOTH GitHub-hosted and shared self-hosted runners
@@ -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
@@ -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 };