@futurelastic/colab-handbook 1.13.0-rc.30 → 1.13.0-rc.31

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.30"
36
+ "version": "1.13.0-rc.31"
37
37
  }
package/tools/colab CHANGED
@@ -1882,11 +1882,14 @@ under CONVENTIONS.md §6's release rung, re-checking everything at the moment it
1882
1882
 
1883
1883
  Conditions (--json checks[].condition; required:false means reported, not blocking, on this row):
1884
1884
  release-policy candidate tracking-issue release-hold regressions test-period trunk-green
1885
- ci-green full-suite schema-additive switch-dependencies final-grant migration-grant human
1885
+ ci-green full-suite cut-run schema-additive switch-dependencies final-grant migration-grant human
1886
1886
 
1887
1887
  regressions blocked_by edges on the tracking issue: open -> refused; closed after the period
1888
1888
  began -> needs-new-candidate. Record one with: colab blocked <tracking> --by <issue>
1889
1889
  test-period from max(candidate tag date, tracking issue creation), release: test-period long
1890
+ cut-run the run that cut the candidate (in progress at the tag's date) concluded success — a
1891
+ cancelled publish refuses; an earlier green run at the commit that cut nothing never
1892
+ vouches for it (#566)
1890
1893
  trunk-green every run since the period began on main — and on project.yml's trunk: when that is
1891
1894
  another branch (trunk: dev, #437) — of the workflows that ran at the candidate,
1892
1895
  none red — required only where the final is automatic, or for an older --tag (#548)
@@ -2035,14 +2038,20 @@ function cmdReleaseFinalize(argv) {
2035
2038
  if (!trackings.has(cand.version)) trackings.set(cand.version, trackingFor(cand.version, { isCandidate: true }));
2036
2039
  const tracking = trackings.get(cand.version);
2037
2040
  const supersededHeld = records.filter((r) => r.state === 'OPEN' && r.held && r.version !== cand.version && !finals.has(r.version)).map((r) => r.number);
2038
- let rows;
2041
+ let rows; let rawRows;
2039
2042
  const conditions = measureCandidateConditions(repoAbs, {
2040
2043
  sha: cand.sha,
2041
2044
  lastFinal: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha }),
2042
2045
  at: `${cand.tag}@${shortSha(cand.sha)}`,
2043
- readRuns: () => { rows = releaseCut.withoutOwnWorkflow(git.ghRunsAtCommit(repoAbs, cand.sha)); return rows; }, // #425
2046
+ readRuns: () => { rawRows = git.ghRunsAtCommit(repoAbs, cand.sha); rows = releaseCut.withoutOwnWorkflow(rawRows); return rows; }, // #425
2044
2047
  issues,
2045
2048
  });
2049
+ // #566: only the run that CUT the candidate vouches for what it published — read from the rows
2050
+ // BEFORE the #425 own-workflow filter (the release workflow is the cutter), minus this run itself.
2051
+ const cutRun = releaseFinalize.cutRunVerdict(rawRows, {
2052
+ tag: cand.tag, cutAt: cand.cutAt, ownRunId: process.env.GITHUB_ACTIONS === 'true' ? process.env.GITHUB_RUN_ID || null : null,
2053
+ jobCount: (id) => git.ghRunJobCount(repoAbs, id),
2054
+ });
2046
2055
  const suiteWorkflows = [...new Set((rows || []).map((r) => r.workflowName || '(unnamed workflow)'))];
2047
2056
  const period = releaseFinalize.periodVerdict({ cutAt: cand.cutAt, trackingCreatedAt: tracking && tracking.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2048
2057
  // #437: the window is main plus project.yml's trunk: when that is another branch (trunk: dev).
@@ -2066,7 +2075,7 @@ function cmdReleaseFinalize(argv) {
2066
2075
  }
2067
2076
  const verdict = releaseFinalize.decide({
2068
2077
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
2069
- ci: conditions.ci, suite: conditions.suite, schema: conditions.schema, switches: conditions.switches,
2078
+ ci: conditions.ci, suite: conditions.suite, cutRun, schema: conditions.schema, switches: conditions.switches,
2070
2079
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2071
2080
  human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2072
2081
  });
package/tools/lib/git.js CHANGED
@@ -1061,8 +1061,9 @@ function ghRunForCommit(repo, branch, sha, limit = 10, opts = {}) {
1061
1061
  */
1062
1062
  function ghRunsAtCommit(repo, sha, limit = 100) {
1063
1063
  if (!sha) return null;
1064
+ // updatedAt is additive (#566): release finalize places a run around the candidate's cut instant.
1064
1065
  const r = gh(['run', 'list', '--commit', sha, '-L', String(limit),
1065
- '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,event'], { cwd: repo });
1066
+ '--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,event'], { cwd: repo });
1066
1067
  if (!r.ok) return null;
1067
1068
  let runs;
1068
1069
  try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
@@ -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', 'schema-additive', 'switch-dependencies',
80
+ 'ci-green', 'full-suite', 'cut-run', 'schema-additive', 'switch-dependencies',
81
81
  ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
82
82
  ]);
83
83
 
@@ -319,6 +319,66 @@ function whyNoFinal({ state, candidate, checks, period, skipped, now } = {}) {
319
319
  return { line, next };
320
320
  }
321
321
 
322
+ // ---- the run that cut the candidate (#566) ------------------------------------------------------
323
+
324
+ // Slack around the tag's cut instant: the tagger date is the runner's clock, a run's createdAt /
325
+ // updatedAt are GitHub's, both to the second.
326
+ const CUT_RUN_SLACK_MS = 120000;
327
+
328
+ /**
329
+ * Did the run that CUT this candidate finish what it does after the cut? `rows` are the workflow
330
+ * runs at the candidate's commit (`git.ghRunsAtCommit`, null = unread), WITHOUT the #425 own-workflow
331
+ * filter — the release workflow is exactly the one this reads; only the calling run itself is dropped
332
+ * (`ownRunId`), since a run cannot vouch for or against itself while it is still running.
333
+ *
334
+ * The cutter is every run that was in progress at `cutAt` (the annotated tag's date): created no later
335
+ * than the cut, and either not finished or finished no earlier than it. Each one must have concluded
336
+ * `success`. Measured (#566): the run that cut a candidate had its image-publish job CANCELLED; ci-green
337
+ * and full-suite set that run aside as superseded (#461 — a cancelled run never stands for its workflow
338
+ * while that workflow has any other run at the sha) and counted an EARLIER run of the same workflow at
339
+ * the same commit that concluded success having cut nothing. finalize said candidate-ready for a
340
+ * candidate whose image did not exist. Here only the cutter vouches, and cancelled is a failure: a run
341
+ * cancelled after its cut may have stopped before its publish.
342
+ *
343
+ * A CANCELLED row whose job count `jobCount(databaseId)` reads 0 never ran — the measured shape of a
344
+ * pending run GitHub cancelled out of the release workflow's concurrency group when a newer one queued —
345
+ * so it cut nothing and is dropped. Asked lazily, only for a cancelled row; null (unread) keeps it.
346
+ *
347
+ * No run in progress at the cut → ok: the candidate was cut by hand (`colab release cut` outside a
348
+ * workflow), and no run owes it anything. A completed row with no `updatedAt` (an older read) cannot
349
+ * be placed around the cut and is not counted — absence of the field never refuses.
350
+ *
351
+ * Returns { ok, detail, runs } — `runs` the cutter rows' ids, for the report.
352
+ */
353
+ function cutRunVerdict(rows, { tag, cutAt, ownRunId = null, jobCount = null } = {}) {
354
+ if (rows === null || rows === undefined) return { ok: false, detail: `the workflow runs at ${tag} could not be read — the run that cut it cannot be checked`, runs: [] };
355
+ const cut = Date.parse(cutAt);
356
+ if (Number.isNaN(cut)) return { ok: false, detail: `${tag} carries no readable cut time — the run that cut it cannot be found`, runs: [] };
357
+ const own = ownRunId === null || ownRunId === undefined || ownRunId === '' ? null : String(ownRunId);
358
+ const cutters = rows.filter((r) => {
359
+ if (!r || (own && String(r.databaseId) === own)) return false;
360
+ const created = Date.parse(r.createdAt);
361
+ if (Number.isNaN(created) || created > cut + CUT_RUN_SLACK_MS) return false;
362
+ if (r.status !== 'completed') return true;
363
+ const ended = Date.parse(r.updatedAt);
364
+ if (Number.isNaN(ended) || ended < cut - CUT_RUN_SLACK_MS) return false;
365
+ if (r.conclusion === 'cancelled' && typeof jobCount === 'function' && r.databaseId != null && jobCount(r.databaseId) === 0) return false;
366
+ return true;
367
+ });
368
+ const ids = cutters.map((r) => r.databaseId).filter((x) => x !== null && x !== undefined);
369
+ const name = (r) => `${r.workflowName || '(unnamed workflow)'} run ${r.databaseId != null ? r.databaseId : '(id unread)'}`;
370
+ if (!cutters.length) return { ok: true, detail: `no workflow run at ${tag} was in progress when it was cut (${cutAt}) — cut by hand, no run's publish to wait for`, runs: [] };
371
+ const bad = cutters.filter((r) => !(r.status === 'completed' && r.conclusion === 'success'));
372
+ if (!bad.length) return { ok: true, detail: `the run that cut ${tag} (${cutters.map(name).join(', ')}) concluded success`, runs: ids };
373
+ const how = (r) => (r.status === 'completed' ? `concluded ${r.conclusion || 'with no conclusion'}` : `is still ${r.status || 'running'}`);
374
+ const rerun = bad.filter((r) => r.status === 'completed' && r.databaseId != null).map((r) => `gh run rerun ${r.databaseId} --failed`);
375
+ return {
376
+ ok: false,
377
+ detail: `the run that cut ${tag} — ${bad.map((r) => `${name(r)} ${how(r)}`).join('; ')} — did not finish what it publishes after the cut (an image, a package, a Release): ${tag}'s artifacts may not exist. An earlier green run at the same commit that cut nothing cannot vouch for it (#566). ${rerun.length ? `Re-run it (${rerun.join('; ')}) and finalize again, or cut a new candidate.` : 'Wait for it to finish, then finalize again.'}`,
378
+ runs: ids,
379
+ };
380
+ }
381
+
322
382
  // ---- the test period ----------------------------------------------------------------------------
323
383
 
324
384
  /**
@@ -480,6 +540,7 @@ function handoffCommand(tag) {
480
540
  * trunk trunkGreenVerdict(...)
481
541
  * regressions regressionVerdict(...)
482
542
  * ci, suite, schema, switches { ok, detail }
543
+ * cutRun #566 — cutRunVerdict(): the run that cut the candidate concluded success
483
544
  * finalGrant #441 — release-policy.js finalGrantVerdict() of policy.effective.finalGrant (only
484
545
  * read when the policy carries one; absent = unresolved, never a grant)
485
546
  * migrations #441 — migrationGrantVerdict() (only read when the policy carries a grant)
@@ -555,7 +616,7 @@ function decide(facts) {
555
616
  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);
556
617
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
557
618
  add('trunk-green', tr.ok, tr.detail, ownClock);
558
- for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
619
+ 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]]) {
559
620
  add(condition, v && v.ok, v ? v.detail : 'not measured');
560
621
  }
561
622
  // #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
@@ -637,7 +698,7 @@ module.exports = {
637
698
  STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
638
699
  parseVersion, compareVersions, parseCandidate,
639
700
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
640
- selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
701
+ selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
641
702
  handoffCommand, decide, tagMessage, migrationGrantVerdict,
642
703
  carriedIssues, previousFinal, releasedEvent, releasedComment,
643
704
  };