@futurelastic/colab-handbook 1.13.0-rc.47 → 1.13.0-rc.48

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.13.0-rc.47"
36
+ "version": "1.13.0-rc.48"
37
37
  }
package/tools/colab CHANGED
@@ -2049,10 +2049,25 @@ function cmdReleaseFinalize(argv) {
2049
2049
  });
2050
2050
  // #566: only the run that CUT the candidate vouches for what it published — read from the rows
2051
2051
  // BEFORE the #425 own-workflow filter (the release workflow is the cutter), minus this run itself.
2052
- const cutRun = releaseFinalize.cutRunVerdict(rawRows, {
2052
+ const cutRunOpts = {
2053
2053
  tag: cand.tag, cutAt: cand.cutAt, ownRunId: process.env.GITHUB_ACTIONS === 'true' ? process.env.GITHUB_RUN_ID || null : null,
2054
2054
  jobCount: (id) => git.ghRunJobCount(repoAbs, id),
2055
- });
2055
+ };
2056
+ const cutRun = releaseFinalize.cutRunVerdict(rawRows, cutRunOpts);
2057
+ // #565: a run that failed only in its deploy jobs (staging) — the three run-reading conditions
2058
+ // re-read with it counted as passed. decide() uses that reading on a human final only, and names
2059
+ // the failure either way. Jobs are read lazily: only when a condition already failed.
2060
+ let deployReport = null;
2061
+ if (Array.isArray(rawRows) && !(conditions.ci.ok && conditions.suite.ok && cutRun.ok)) {
2062
+ const d = releaseFinalize.deployOnlyFailures(rawRows, (id) => git.ghRunJobs(repoAbs, id));
2063
+ if (d.failures.length) {
2064
+ const at = `${cand.tag}@${shortSha(cand.sha)}`;
2065
+ const lenRows = releaseCut.withoutOwnWorkflow(d.rows); // #425, as readRuns does
2066
+ const run = git.summarizeRunsForCommit(lenRows, cand.sha);
2067
+ const ci = run ? (({ ok, detail }) => ({ ok, detail }))(classifyCiRun(repoAbs, run, at)) : { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
2068
+ deployReport = { failures: d.failures, ci, suite: releaseCut.fullSuiteVerdict(lenRows, at), cutRun: releaseFinalize.cutRunVerdict(d.rows, cutRunOpts) };
2069
+ }
2070
+ }
2056
2071
  const suiteWorkflows = [...new Set((rows || []).map((r) => r.workflowName || '(unnamed workflow)'))];
2057
2072
  const period = releaseFinalize.periodVerdict({ cutAt: cand.cutAt, trackingCreatedAt: tracking && tracking.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2058
2073
  // #437: the window is main plus project.yml's trunk: when that is another branch (trunk: dev).
@@ -2076,7 +2091,7 @@ function cmdReleaseFinalize(argv) {
2076
2091
  }
2077
2092
  const verdict = releaseFinalize.decide({
2078
2093
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
2079
- ci: conditions.ci, suite: conditions.suite, cutRun, schema: conditions.schema, switches: conditions.switches,
2094
+ ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
2080
2095
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2081
2096
  human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2082
2097
  });
@@ -77,7 +77,7 @@ const STATES = Object.freeze([
77
77
 
78
78
  const CONDITIONS = Object.freeze([
79
79
  'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
80
- 'ci-green', 'full-suite', 'cut-run', 'schema-additive', 'switch-dependencies',
80
+ 'ci-green', 'full-suite', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
81
81
  ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
82
82
  ]);
83
83
 
@@ -379,6 +379,56 @@ function cutRunVerdict(rows, { tag, cutAt, ownRunId = null, jobCount = null } =
379
379
  };
380
380
  }
381
381
 
382
+ // ---- a failed deploy job: a report on a human final, a gate on an automatic one (#565) -------------
383
+
384
+ // A job whose name says it deploys. The release workflow deploys the candidate to staging after it has
385
+ // built, tested and published it; that job's failure is about the deploy target (a host the runner
386
+ // cannot reach, a registry permission, a sibling image that was never built), never about the code.
387
+ const DEPLOY_JOB_RE = /\bdeploy/i;
388
+
389
+ /** Does a job named `name` deploy? Read from the name: GitHub's job read carries no environment. */
390
+ function isDeployJob(name) {
391
+ return DEPLOY_JOB_RE.test(String(name || ''));
392
+ }
393
+
394
+ /**
395
+ * The runs at a candidate's commit that failed ONLY in deploy jobs (#565). `rows` are the run rows
396
+ * (null = unread); `jobsOf(databaseId)` returns that run's jobs (`git.ghRunJobs`, null = unread), asked
397
+ * lazily and only for a completed run that concluded `failure`.
398
+ *
399
+ * A run is deploy-only when its jobs were read, at least one did not pass, and every job that did not
400
+ * pass (anything but success/skipped/neutral — cancelled included) is a deploy job. A job that builds,
401
+ * tests or publishes failing keeps the run a failure; so does a run whose jobs could not be read.
402
+ *
403
+ * Returns { rows, failures } — `rows` a copy of `rows` where each deploy-only run reads `success` and
404
+ * carries `deployFailed` (its failed deploy jobs), `failures` [{ workflowName, databaseId, jobs }] for
405
+ * the report. Measuring this never decides anything: decide() uses the rewritten reading only on a
406
+ * human final, and names the failures either way.
407
+ */
408
+ function deployOnlyFailures(rows, jobsOf) {
409
+ if (!Array.isArray(rows) || typeof jobsOf !== 'function') return { rows, failures: [] };
410
+ const failures = [];
411
+ const out = rows.map((r) => {
412
+ if (!r || r.status !== 'completed' || r.conclusion !== 'failure' || r.databaseId == null) return r;
413
+ const jobs = jobsOf(r.databaseId);
414
+ if (!Array.isArray(jobs) || !jobs.length) return r;
415
+ const bad = jobs.filter((j) => j && !(j.status === 'completed' && NOT_RED.has(j.conclusion)));
416
+ if (!bad.length || !bad.every((j) => isDeployJob(j.name))) return r;
417
+ const named = bad.map((j) => `${j.name} (${j.status === 'completed' ? j.conclusion || 'no conclusion' : j.status || 'unknown'})`);
418
+ failures.push({ workflowName: r.workflowName || '(unnamed workflow)', databaseId: r.databaseId, jobs: named });
419
+ return { ...r, conclusion: 'success', deployFailed: named };
420
+ });
421
+ return { rows: out, failures };
422
+ }
423
+
424
+ /** The `deploy-report` check's detail — what failed, and what it means on this final. */
425
+ function deployReportDetail(failures, { blocking }) {
426
+ const what = failures.map((f) => `${f.workflowName} run ${f.databaseId}: ${f.jobs.join(', ')}`).join('; ');
427
+ return blocking
428
+ ? `a deploy job failed at this candidate (${what}); an automatic final treats it as blocking, so ci-green, full-suite and cut-run read the run as failed`
429
+ : `a deploy job failed at this candidate (${what}); its build, tests and publish passed, so on a human final this is a report, not a gate: ci-green, full-suite and cut-run read that run without its deploy jobs. Check the deploy target before you finalize`;
430
+ }
431
+
382
432
  // ---- the test period ----------------------------------------------------------------------------
383
433
 
384
434
  /**
@@ -617,7 +667,17 @@ function decide(facts) {
617
667
  add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : per.detail, ownClock);
618
668
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
619
669
  add('trunk-green', tr.ok, tr.detail, ownClock);
620
- for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['cut-run', f.cutRun], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
670
+ // #565: a run that failed only in deploy jobs is a report on a human final (the human who decides
671
+ // sees it), and stays a gate on an automatic one. `deployReport` carries the verdicts re-read with
672
+ // those runs counted as passed; it is absent when no such run exists.
673
+ const dr = f.deployReport && Array.isArray(f.deployReport.failures) && f.deployReport.failures.length ? f.deployReport : null;
674
+ const lenient = !!dr && !auto;
675
+ const pick = (strict, relaxed) => (lenient && relaxed ? relaxed : strict);
676
+ for (const [condition, v] of [['ci-green', pick(f.ci, dr && dr.ci)], ['full-suite', pick(f.suite, dr && dr.suite)], ['cut-run', pick(f.cutRun, dr && dr.cutRun)]]) {
677
+ add(condition, v && v.ok, v ? v.detail : 'not measured');
678
+ }
679
+ if (dr) add('deploy-report', false, deployReportDetail(dr.failures, { blocking: !lenient }), false);
680
+ for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
621
681
  add(condition, v && v.ok, v ? v.detail : 'not measured');
622
682
  }
623
683
  // #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
@@ -699,7 +759,7 @@ module.exports = {
699
759
  STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
700
760
  parseVersion, compareVersions, parseCandidate,
701
761
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
702
- selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
762
+ selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, isDeployJob, deployOnlyFailures, deployReportDetail, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
703
763
  handoffCommand, decide, tagMessage, migrationGrantVerdict,
704
764
  carriedIssues, previousFinal, releasedEvent, releasedComment,
705
765
  };