@futurelastic/colab-handbook 1.14.1-rc.2 → 1.14.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.14.1-rc.2"
36
+ "version": "1.14.1-rc.4"
37
37
  }
package/tools/colab CHANGED
@@ -1439,7 +1439,8 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
1439
1439
  suite = { ok: false, detail: `gh not usable (${why}) — cannot confirm the suite ran at ${at}` };
1440
1440
  switches = { ok: false, unread: true, detail: `gh not usable (${why}) — the colab:switch markers cannot be read` };
1441
1441
  } else {
1442
- const rows = readRuns();
1442
+ // #616: a workflow whose every run at the sha was skipped did not run — not counted either way.
1443
+ const rows = releaseCut.withoutSkippedOnlyWorkflows(readRuns());
1443
1444
  const run = git.summarizeRunsForCommit(rows, sha);
1444
1445
  if (!run) ci = { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
1445
1446
  else { const v = classifyCiRun(repoAbs, run, at); ci = { ok: v.ok, detail: v.detail }; }
@@ -2128,7 +2129,7 @@ function cmdReleaseFinalize(argv) {
2128
2129
  const d = releaseFinalize.deployOnlyFailures(rawRows, (id) => git.ghRunJobs(repoAbs, id));
2129
2130
  if (d.failures.length) {
2130
2131
  const at = `${cand.tag}@${shortSha(cand.sha)}`;
2131
- const lenRows = releaseCut.withoutOwnWorkflow(d.rows); // #425, as readRuns does
2132
+ const lenRows = releaseCut.withoutSkippedOnlyWorkflows(releaseCut.withoutOwnWorkflow(d.rows)); // #425 + #616, as the first read does
2132
2133
  const run = git.summarizeRunsForCommit(lenRows, cand.sha);
2133
2134
  const ci = run ? (({ ok, detail }) => ({ ok, detail }))(classifyCiRun(repoAbs, run, at)) : { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
2134
2135
  deployReport = { failures: d.failures, ci, suite: releaseCut.fullSuiteVerdict(lenRows, at), cutRun: releaseFinalize.cutRunVerdict(d.rows, cutRunOpts) };
@@ -10588,7 +10589,10 @@ function ciGrantTrailerLine(grantVerdict, branch, trunk) {
10588
10589
  // scan (ci-cure.js priorRedShaFromMessage) reads is unchanged.
10589
10590
  const rv = grantVerdict.granted.filter((x) => x.role && x.role !== 'human');
10590
10591
  const via = rv.length ? ` via ${rv[0].role} ${[...new Set(rv.map((x) => x.reviewer))].join(',')}` : '';
10591
- return `CI-Grant: ${issues} branch ${branch} over-red ${trunk}@${shortSha(g.redSha)} evidence ${shortSha(g.evidenceSha)}${via}`;
10592
+ // #615: a grant that survived a pure trunk sync says so — the evidence sha is what the human
10593
+ // reviewed, the synced head is what CI ran green and what lands.
10594
+ const sy = g.syncedTo ? ` synced-to ${shortSha(g.syncedTo)} by ${g.syncMerges} trunk merge${g.syncMerges === 1 ? '' : 's'}` : '';
10595
+ return `CI-Grant: ${issues} branch ${branch} over-red ${trunk}@${shortSha(g.redSha)} evidence ${shortSha(g.evidenceSha)}${sy}${via}`;
10592
10596
  }
10593
10597
 
10594
10598
  /**
@@ -11964,6 +11968,14 @@ function shipCiGrants(repoAbs, gh, issues, branch, trunk, redSha) {
11964
11968
  return ciGrant.evaluateShipSet(issues, records, branch, trunk, redSha, evidence, labels.CI_GRANT_LABEL, {
11965
11969
  trust: trustAt(repoAbs, trunk),
11966
11970
  labelActors: (n) => git.ghIssueLabelActors(repoAbs, n, labels.CI_GRANT_LABEL),
11971
+ // #615: the head's pure trunk-sync lineage, bounded by the RED sha (not trunk's tip) — a merge of
11972
+ // anything past what the human reviewed against is not a sync this grant covers.
11973
+ // The head may have been synced from another machine: fetch it when absent (a failed fetch just
11974
+ // yields an empty chain — the grant voids, as before #615).
11975
+ syncChain: (head, red) => {
11976
+ if (!git.git(['cat-file', '-e', `${head}^{commit}`], repoAbs).ok) git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', head], repoAbs);
11977
+ return shipHandoff.syncMergeChain((a) => git.git(a, repoAbs), head, red);
11978
+ },
11967
11979
  // #504 — the reviewer role: the opt-in as committed on TRUNK (never the branch), the clock for a
11968
11980
  // host's revoke window, and trunk's red checks at redSha, read lazily and at most once.
11969
11981
  policy: ciGrant.parseGrantPolicy(projectDocAt(repoAbs, trunk)).policy,
@@ -159,7 +159,9 @@ const { TRUSTED_ASSOCIATIONS, authorIsHuman, labelApplierIsHuman } = require('./
159
159
  *
160
160
  * `opts` (#407) — OPTIONAL `{ trust, labelActors }`, the same contract as migration-grant.js's
161
161
  * evaluateIssue: absent/undeclared trust keeps the association check byte-identical; declared, the
162
- * grant author and the label's latest applier must both be listed in trust-humans.
162
+ * grant author and the label's latest applier must both be listed in trust-humans. `opts.syncChain`
163
+ * (#615) — `(headSha, redSha) => [sha…]`, see syncedFrom: lets the grant survive a pure trunk sync
164
+ * of the reviewed head; a granted verdict then carries `synced: { to, merges }` (else null).
163
165
  */
164
166
  function evaluateIssue(record, branch, trunk, redTrunkSha, evidence, issueNum, labelName, opts) {
165
167
  const trust = opts && opts.trust;
@@ -206,9 +208,19 @@ function evaluateIssue(record, branch, trunk, redTrunkSha, evidence, issueNum, l
206
208
  return { issue, ok: false, grant: g,
207
209
  reason: `#${issue}'s grant requires a completed, successful CI run on \`${branch}\`'s current head — none exists` };
208
210
  }
211
+ let synced = null;
209
212
  if (evidence.sha !== g.evidenceSha) {
210
- return { issue, ok: false, grant: g,
211
- reason: `#${issue}'s grant was reviewed against evidence run \`${g.evidenceSha}\`, but \`${branch}\`'s head is now \`${evidence.sha}\` — the branch moved since the human reviewed it` };
213
+ // #615: the stale-base sync ship itself demands (#395) must not void the grant ship demands. A
214
+ // head that is the reviewed head plus nothing but PURE merges of trunk at-or-before the red sha
215
+ // (ship-handoff.js syncMergeChain, the #579 proof: two parents, the second already in the red
216
+ // sha, tree == git's own conflict-free merge) carries no content the human did not review —
217
+ // only trunk content the grant already exists to exempt. Anything else still voids it.
218
+ const at = syncedFrom(opts, evidence.sha, g.redSha, g.evidenceSha);
219
+ if (at < 0) {
220
+ return { issue, ok: false, grant: g,
221
+ reason: `#${issue}'s grant was reviewed against evidence run \`${g.evidenceSha}\`, but \`${branch}\`'s head is now \`${evidence.sha}\` — the branch moved since the human reviewed it by more than a clean merge of trunk up to the red sha` };
222
+ }
223
+ synced = { to: evidence.sha, merges: at + 1 };
212
224
  }
213
225
  if (trust && trust.declared) {
214
226
  // #407 Wanted 2 — the label applier, read last: only once the grant would otherwise pass.
@@ -217,7 +229,23 @@ function evaluateIssue(record, branch, trunk, redTrunkSha, evidence, issueNum, l
217
229
  const lab = labelApplierIsHuman(actors, trust, labelName);
218
230
  if (!lab.ok) return { issue, ok: false, grant: g, reason: `#${issue}: ${lab.reason}` };
219
231
  }
220
- return { issue, ok: true, grant: g, reason: '' };
232
+ return { issue, ok: true, grant: g, synced, reason: '' };
233
+ }
234
+
235
+ /**
236
+ * #615 — where in the head's pure-sync lineage the reviewed evidence sha sits: the 0-based index of
237
+ * the sync merge whose first parent is `evidenceSha` (so `+1` merges were added on top of it), or -1
238
+ * when it is not there or the lineage could not be measured. `opts.syncChain(headSha, redSha)` is the
239
+ * caller's git thunk returning ship-handoff.js syncMergeChain's nearest-first sha list (this module
240
+ * stays pure); absent, throwing or non-array reads as "no proof" — the grant voids, as before #615.
241
+ */
242
+ function syncedFrom(opts, headSha, redSha, evidenceSha) {
243
+ let chain = null;
244
+ try { chain = opts && typeof opts.syncChain === 'function' ? opts.syncChain(headSha, redSha) : null; } catch (_) { chain = null; }
245
+ if (!Array.isArray(chain)) return -1;
246
+ const want = String(evidenceSha || '').toLowerCase();
247
+ if (!want) return -1;
248
+ return chain.findIndex((s) => String(s || '').toLowerCase() === want);
221
249
  }
222
250
 
223
251
  /**
@@ -257,7 +285,8 @@ function evaluateShipSet(issues, records, branch, trunk, redTrunkSha, evidence,
257
285
  const rec = records ? records[n] : null;
258
286
  const v = evaluateIssue(rec, branch, trunk, redTrunkSha, evidence, n, labelName, opts);
259
287
  if (v.ok) {
260
- granted.push({ issue: n, branch: v.grant.branch, by: v.grant.login, at: v.grant.at, redSha: v.grant.redSha, evidenceSha: v.grant.evidenceSha });
288
+ granted.push({ issue: n, branch: v.grant.branch, by: v.grant.login, at: v.grant.at, redSha: v.grant.redSha, evidenceSha: v.grant.evidenceSha,
289
+ ...(v.synced ? { syncedTo: v.synced.to, syncMerges: v.synced.merges } : {}) });
261
290
  continue;
262
291
  }
263
292
  // #504: a reviewer grant is consulted only when the human one failed AND the issue carries a
@@ -655,12 +655,11 @@ function handoffTrackingBody(version) {
655
655
  function fullSuiteVerdict(rows, at) {
656
656
  if (rows === null || rows === undefined) return { ok: false, detail: `gh run list failed — cannot confirm the suite ran at ${at}` };
657
657
  if (!rows.length) return { ok: false, detail: `no workflow run at ${at} — the suite never ran on this commit` };
658
- const byWorkflow = new Map();
659
- for (const r of rows) {
660
- const name = r.workflowName || '(unnamed workflow)';
661
- if (!byWorkflow.has(name)) byWorkflow.set(name, []);
662
- byWorkflow.get(name).push(r);
663
- }
658
+ const byWorkflow = groupByWorkflow(rows);
659
+ const skippedOnly = [];
660
+ for (const [name, runs] of byWorkflow) if (isSkippedOnly(runs)) { skippedOnly.push(name); byWorkflow.delete(name); }
661
+ // #616: a workflow whose every run was skipped did not run — it vouches for nothing and fails nothing.
662
+ if (!byWorkflow.size) return { ok: false, detail: `no workflow ran at ${at} — every run was skipped (${skippedOnly.join(', ')})` };
664
663
  const missing = [];
665
664
  for (const [name, runs] of byWorkflow) {
666
665
  if (!runs.some((r) => r.status === 'completed' && r.conclusion === 'success')) {
@@ -668,7 +667,41 @@ function fullSuiteVerdict(rows, at) {
668
667
  }
669
668
  }
670
669
  if (missing.length) return { ok: false, detail: `no successful run at ${at} for: ${missing.join('; ')}` };
671
- return { ok: true, detail: `${byWorkflow.size} workflow(s) at ${at}, each with a successful run` };
670
+ const note = skippedOnly.length ? ` (not run, skipped: ${skippedOnly.join(', ')})` : '';
671
+ return { ok: true, detail: `${byWorkflow.size} workflow(s) at ${at}, each with a successful run${note}` };
672
+ }
673
+
674
+ function groupByWorkflow(rows) {
675
+ const byWorkflow = new Map();
676
+ for (const r of rows) {
677
+ const name = (r && r.workflowName) || '(unnamed workflow)';
678
+ if (!byWorkflow.has(name)) byWorkflow.set(name, []);
679
+ byWorkflow.get(name).push(r);
680
+ }
681
+ return byWorkflow;
682
+ }
683
+
684
+ /** Every run of the workflow finished and concluded `skipped` — it executed nothing (#514, #616). */
685
+ function isSkippedOnly(runs) {
686
+ return runs.length > 0 && runs.every((r) => r && r.status === 'completed' && r.conclusion === 'skipped');
687
+ }
688
+
689
+ /**
690
+ * #616: the run rows minus every workflow whose runs at the sha were ALL `skipped` — an opt-in
691
+ * workflow gated off by an `if:` (a scheduled load profile waiting for its runner) records a skipped
692
+ * run on every tick, and one landing on the candidate's commit made ci-green read
693
+ * "conclusion=skipped" and refused every finalize older than one schedule period. Release-only on
694
+ * purpose: the ship gate (git.summarizeRunsForCommit, #514) keeps reading an all-skipped workflow
695
+ * as not-green, so this filter is applied by the release callers, never inside git.js.
696
+ * A workflow with a skipped run AND any other run keeps all its rows (skipped + failure stays red;
697
+ * cancelled-only is untouched and still fails full-suite). null passes through.
698
+ */
699
+ function withoutSkippedOnlyWorkflows(rows) {
700
+ if (!Array.isArray(rows)) return rows;
701
+ const drop = new Set();
702
+ for (const [name, runs] of groupByWorkflow(rows)) if (isSkippedOnly(runs)) drop.add(name);
703
+ if (!drop.size) return rows;
704
+ return rows.filter((r) => !drop.has((r && r.workflowName) || '(unnamed workflow)'));
672
705
  }
673
706
 
674
707
  /**
@@ -1152,7 +1185,7 @@ module.exports = {
1152
1185
  isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
1153
1186
  parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
1154
1187
  parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
1155
- fullSuiteVerdict, withoutOwnWorkflow, isMigrationPath, schemaVerdict,
1188
+ fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, isMigrationPath, schemaVerdict,
1156
1189
  parseSwitchMarkers, switchVerdict,
1157
1190
  promotionVerdict, decide, tagMessage, versionSourceOf,
1158
1191
  DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs, finalReleaseArgs, handoffTrackingBody,