@futurelastic/colab-handbook 1.14.1-rc.3 → 1.14.1-rc.5

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.3"
36
+ "version": "1.14.1-rc.5"
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 }; }
@@ -1498,10 +1499,24 @@ function measurePromotion(repoAbs, { sha, trunk, remote, fetched }) {
1498
1499
  return releaseCut.promotionVerdict({ trunk, sha, parents, headOnTrunk, mergedFromTrunk: merged || false });
1499
1500
  }
1500
1501
 
1501
- /** Every candidate `colab release cut` made, as [{ name, date }] — what the cadence window counts (#422). */
1502
- function cutCandidates(repoAbs) {
1502
+ /**
1503
+ * #617: the push remote's tag names, read with `ls-remote` — what a release cut/finalize may read.
1504
+ * Fails closed: an unreadable remote tag set means the version cannot be computed the way CI would.
1505
+ */
1506
+ function remoteTagSetOrThrow(repoAbs, remote) {
1507
+ const r = releaseTag.remoteTagNames(repoAbs, remote);
1508
+ if (!r.ok) throw new UserError(`git ls-remote --tags ${remote} failed — the release version is computed from ${remote}'s tags only, so nothing is decided without them (${r.stderr})`);
1509
+ return r.names;
1510
+ }
1511
+
1512
+ /**
1513
+ * Every candidate `colab release cut` made, as [{ name, date }] — what the cadence window counts (#422).
1514
+ * `onlyTags` (#617): the push remote's tag names — a local tag the remote never had is not a cut.
1515
+ */
1516
+ function cutCandidates(repoAbs, onlyTags = null) {
1503
1517
  const fe = git.git(['for-each-ref', 'refs/tags', '--format=%(refname:short)%09%(objecttype)%09%(taggerdate:iso-strict)%09%(contents:subject)'], repoAbs);
1504
1518
  return (fe.ok ? fe.stdout.split('\n').filter(Boolean) : []).map((l) => l.split('\t'))
1519
+ .filter(([name]) => !onlyTags || onlyTags.has(name))
1505
1520
  .filter(([name, type, , subject]) => type === 'tag' && /-rc\.[1-9][0-9]*$/.test(name) && String(subject || '').endsWith('(colab release cut)'))
1506
1521
  .map(([name, , date]) => ({ name, date }));
1507
1522
  }
@@ -1568,11 +1583,11 @@ function measureAutoSignals(repoAbs, { doc, sha, lastFinal, remote, issues, trun
1568
1583
  return { signals, migration: (v) => releaseCut.parseMigrationSection(migrationText, v) };
1569
1584
  }
1570
1585
 
1571
- /** #446: every final `vX.Y.Z` tag as [{ name, date }] — what release.final-spacing counts. A human's final counts too. */
1572
- function finalTags(repoAbs) {
1586
+ /** #446: every final `vX.Y.Z` tag as [{ name, date }] — what release.final-spacing counts. A human's final counts too. #617: only the push remote's (`onlyTags`). */
1587
+ function finalTags(repoAbs, onlyTags = null) {
1573
1588
  const fe = git.git(['for-each-ref', 'refs/tags', '--format=%(refname:short)%09%(creatordate:iso-strict)'], repoAbs);
1574
1589
  return (fe.ok ? fe.stdout.split('\n').filter(Boolean) : []).map((l) => l.split('\t'))
1575
- .filter(([name]) => releaseCut.parseVersion(name)).map(([name, date]) => ({ name, date }));
1590
+ .filter(([name]) => (!onlyTags || onlyTags.has(name)) && releaseCut.parseVersion(name)).map(([name, date]) => ({ name, date }));
1576
1591
  }
1577
1592
 
1578
1593
  /**
@@ -1582,7 +1597,7 @@ function finalTags(repoAbs) {
1582
1597
  * since the newest final. The version is computed here only to find that tracking issue; decide()
1583
1598
  * computes it again from the same inputs, so the two cannot disagree.
1584
1599
  */
1585
- function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths }) {
1600
+ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, remoteTags = null }) {
1586
1601
  const grantDecl = policy.effective.finalGrant;
1587
1602
  const trust = trustAt(repoAbs, `${remote}/main`);
1588
1603
  const finalGrant = isGhUsable(repoAbs)
@@ -1603,7 +1618,7 @@ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, au
1603
1618
  if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
1604
1619
  }
1605
1620
  const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal }), paths: paths || null };
1606
- const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
1621
+ const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs, remoteTags), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
1607
1622
  return { finalGrant, holds, migrations, spacing, tracking };
1608
1623
  }
1609
1624
 
@@ -1673,13 +1688,18 @@ function cmdReleaseCut(argv) {
1673
1688
  deploy: doc.deploy === undefined || doc.deploy === null ? 'none' : String(doc.deploy),
1674
1689
  });
1675
1690
 
1676
- const lastFinal = releaseTag.latestReleaseTag(repoAbs, { ref: `${remote}/main` });
1691
+ // #617: every tag this cut reads is one the push remote holds — a fresh CI checkout sees only those,
1692
+ // and a clone holding more (a fork's fetched `upstream` line) must reach the same verdict, not cut
1693
+ // a version off a line the remote never carried.
1694
+ const remoteTags = remoteTagSetOrThrow(repoAbs, remote);
1695
+ const lastFinal = releaseTag.latestReleaseTag(repoAbs, { ref: `${remote}/main`, onlyTags: remoteTags });
1677
1696
  const suggestion = lastFinal
1678
1697
  ? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${remote}/main`))
1679
1698
  : { bump: null, why: 'no final tag yet' };
1680
1699
  const lines = (r) => (r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : []);
1681
- const tags = lines(git.git(['tag', '--list'], repoAbs));
1682
- const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs));
1700
+ const onRemote = (t) => remoteTags.has(t);
1701
+ const tags = lines(git.git(['tag', '--list'], repoAbs)).filter(onRemote);
1702
+ const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs)).filter(onRemote);
1683
1703
 
1684
1704
  const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
1685
1705
  sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
@@ -1689,14 +1709,14 @@ function cmdReleaseCut(argv) {
1689
1709
  let auto = null; // #422
1690
1710
  if (opts.auto) {
1691
1711
  const { signals, migration } = measureAutoSignals(repoAbs, { doc, sha, lastFinal, remote, issues, trunk });
1692
- const cadence = releaseCut.cadenceVerdict({ candidates: cutCandidates(repoAbs), perDay: policy.effective.candidatesPerDay, now: new Date().toISOString() });
1712
+ const cadence = releaseCut.cadenceVerdict({ candidates: cutCandidates(repoAbs, remoteTags), perDay: policy.effective.candidatesPerDay, now: new Date().toISOString() });
1693
1713
  auto = { signals, migration, cadence, promotion: offTrunk ? measurePromotion(repoAbs, { sha, trunk, remote, fetched: trunkFetch }) : null };
1694
1714
  }
1695
1715
 
1696
1716
  // #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
1697
1717
  // measured only there, so every candidate route's run is what it was.
1698
1718
  const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
1699
- const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince }) : {};
1719
+ const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, remoteTags }) : {};
1700
1720
  if (fast && auto) auto.spacing = fastFacts.spacing;
1701
1721
  // #590: route library-fast — a final with nothing deployed. The release-hold veto is its one extra
1702
1722
  // read; a hand cut also needs MIGRATION.md for a manifest-declared major (--auto reads it already).
@@ -2043,10 +2063,12 @@ function cmdReleaseFinalize(argv) {
2043
2063
  const shaR = git.git(['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/main^{commit}`], repoAbs);
2044
2064
  if (!shaR.ok || !shaR.stdout) throw new UserError(`no ${remote}/main — releases are cut from main (CONVENTIONS.md §6)`);
2045
2065
  const mainSha = shaR.stdout;
2046
- const lastFinal = releaseTag.latestReleaseTag(repoAbs, { ref: `${remote}/main` });
2066
+ // #617: candidates and finals are the push remote's — never a tag only this clone holds.
2067
+ const remoteTags = remoteTagSetOrThrow(repoAbs, remote);
2068
+ const lastFinal = releaseTag.latestReleaseTag(repoAbs, { ref: `${remote}/main`, onlyTags: remoteTags });
2047
2069
 
2048
2070
  const fe = git.git(['for-each-ref', 'refs/tags', '--format=%(refname:short)%09%(objecttype)%09%(*objectname)%09%(objectname)%09%(taggerdate:iso-strict)%09%(contents:subject)'], repoAbs);
2049
- const tags = (fe.ok ? fe.stdout.split('\n').filter(Boolean) : []).map((l) => {
2071
+ const tags = (fe.ok ? fe.stdout.split('\n').filter(Boolean) : []).filter((l) => remoteTags.has(l.split('\t')[0])).map((l) => {
2050
2072
  const [name, type, peeled, obj, date, subject] = l.split('\t');
2051
2073
  const annotated = type === 'tag';
2052
2074
  return { name, annotated, sha: annotated ? peeled : obj, date: annotated ? date : null, subject: annotated ? subject : '', onMain: false };
@@ -2108,7 +2130,7 @@ function cmdReleaseFinalize(argv) {
2108
2130
  let rows; let rawRows;
2109
2131
  const conditions = measureCandidateConditions(repoAbs, {
2110
2132
  sha: cand.sha,
2111
- lastFinal: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha }),
2133
+ lastFinal: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }),
2112
2134
  at: `${cand.tag}@${shortSha(cand.sha)}`,
2113
2135
  readRuns: () => { rawRows = git.ghRunsAtCommit(repoAbs, cand.sha); rows = releaseCut.withoutOwnWorkflow(rawRows); return rows; }, // #425
2114
2136
  issues,
@@ -2128,7 +2150,7 @@ function cmdReleaseFinalize(argv) {
2128
2150
  const d = releaseFinalize.deployOnlyFailures(rawRows, (id) => git.ghRunJobs(repoAbs, id));
2129
2151
  if (d.failures.length) {
2130
2152
  const at = `${cand.tag}@${shortSha(cand.sha)}`;
2131
- const lenRows = releaseCut.withoutOwnWorkflow(d.rows); // #425, as readRuns does
2153
+ const lenRows = releaseCut.withoutSkippedOnlyWorkflows(releaseCut.withoutOwnWorkflow(d.rows)); // #425 + #616, as the first read does
2132
2154
  const run = git.summarizeRunsForCommit(lenRows, cand.sha);
2133
2155
  const ci = run ? (({ ok, detail }) => ({ ok, detail }))(classifyCiRun(repoAbs, run, at)) : { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
2134
2156
  deployReport = { failures: d.failures, ci, suite: releaseCut.fullSuiteVerdict(lenRows, at), cutRun: releaseFinalize.cutRunVerdict(d.rows, cutRunOpts) };
@@ -2153,7 +2175,7 @@ function cmdReleaseFinalize(argv) {
2153
2175
  const mg = tracking && tracking.number
2154
2176
  ? migrationGrant.evaluateIssue(rec, cand.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
2155
2177
  : { ok: false, reason: 'no tracking issue yet to carry a grant' };
2156
- migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha }) });
2178
+ migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }) });
2157
2179
  }
2158
2180
  const verdict = releaseFinalize.decide({
2159
2181
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
@@ -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,
@@ -56,10 +56,21 @@ function describeArgs({ ref = null, abbrev = 0, includePrerelease = false } = {}
56
56
  * there is none (no tags, only candidates, not a repo). Never throws.
57
57
  *
58
58
  * Nearest by ancestry, same as the describe it replaces — "latest reachable", not "highest SemVer".
59
+ *
60
+ * `onlyTags` (#617) — a Set of tag names, usually the push remote's (`remoteTagNames`). When given,
61
+ * every local tag outside it is excluded from the walk, so a clone holding tags the remote never
62
+ * had (a fork's fetched `upstream` line) answers exactly as a fresh CI checkout of the remote does.
59
63
  */
60
- function latestReleaseTag(root, { ref = null, includePrerelease = false } = {}) {
64
+ function latestReleaseTag(root, { ref = null, includePrerelease = false, onlyTags = null } = {}) {
61
65
  try {
62
- const out = execFileSync('git', ['-C', root, ...describeArgs({ ref, abbrev: 0, includePrerelease })], {
66
+ const args = describeArgs({ ref, abbrev: 0, includePrerelease });
67
+ if (onlyTags) {
68
+ const local = execFileSync('git', ['-C', root, 'tag', '--list'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
69
+ .split('\n').map((t) => t.trim()).filter(Boolean);
70
+ const foreign = local.filter((t) => !onlyTags.has(t)).map((t) => `--exclude=${t}`);
71
+ args.splice(args.length - (ref ? 1 : 0), 0, ...foreign);
72
+ }
73
+ const out = execFileSync('git', ['-C', root, ...args], {
63
74
  encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
64
75
  }).trim();
65
76
  return out || null;
@@ -68,6 +79,37 @@ function latestReleaseTag(root, { ref = null, includePrerelease = false } = {})
68
79
  }
69
80
  }
70
81
 
82
+ /**
83
+ * `git ls-remote --tags` output → the Set of tag names it lists (#617). Peeled `^{}` lines name the
84
+ * same tag as the line before them, so they collapse into it.
85
+ */
86
+ function parseLsRemoteTags(stdout) {
87
+ const names = new Set();
88
+ for (const line of String(stdout || '').split('\n')) {
89
+ const ref = line.split('\t')[1];
90
+ if (!ref || !ref.startsWith('refs/tags/')) continue;
91
+ names.add(ref.slice('refs/tags/'.length).replace(/\^\{\}$/, ''));
92
+ }
93
+ return names;
94
+ }
95
+
96
+ /**
97
+ * The tag names on `remote` (#617) — what a fresh CI checkout of that remote sees, which a local clone
98
+ * need not: a fork that fetched its `upstream` holds that line's tags too, and a release computed from
99
+ * them disagrees with the CI run of the same command. Asked of the remote directly (`ls-remote`), so
100
+ * no local ref can leak in. `{ ok, names, stderr }` — never throws; a caller fails closed on !ok.
101
+ */
102
+ function remoteTagNames(root, remote) {
103
+ try {
104
+ const out = execFileSync('git', ['-C', root, 'ls-remote', '--tags', remote], {
105
+ encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000,
106
+ });
107
+ return { ok: true, names: parseLsRemoteTags(out), stderr: '' };
108
+ } catch (e) {
109
+ return { ok: false, names: new Set(), stderr: String((e && e.stderr) || (e && e.message) || 'ls-remote failed').split('\n')[0] };
110
+ }
111
+ }
112
+
71
113
  // ---- pre-tag checks (#424) — fail closed before ANY candidate or final -------------------------
72
114
  //
73
115
  // Learned from a library that releases on every merge and publishes to a registry. Three checks, each
@@ -222,6 +264,6 @@ function preTagChecks({ tag, manifests, ancestry, tags, trunk = 'main', versionS
222
264
  }
223
265
 
224
266
  module.exports = {
225
- PRERELEASE_TAG_GLOB, isPrereleaseTag, describeArgs, latestReleaseTag,
267
+ PRERELEASE_TAG_GLOB, isPrereleaseTag, describeArgs, latestReleaseTag, parseLsRemoteTags, remoteTagNames,
226
268
  PRE_TAG_CONDITIONS, MANIFESTS, parseSemver, manifestVersions, preTagChecks,
227
269
  };