@futurelastic/colab-handbook 1.14.1-rc.4 → 1.14.1-rc.6

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.4"
36
+ "version": "1.14.1-rc.6"
37
37
  }
package/tools/colab CHANGED
@@ -1499,10 +1499,24 @@ function measurePromotion(repoAbs, { sha, trunk, remote, fetched }) {
1499
1499
  return releaseCut.promotionVerdict({ trunk, sha, parents, headOnTrunk, mergedFromTrunk: merged || false });
1500
1500
  }
1501
1501
 
1502
- /** Every candidate `colab release cut` made, as [{ name, date }] — what the cadence window counts (#422). */
1503
- 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) {
1504
1517
  const fe = git.git(['for-each-ref', 'refs/tags', '--format=%(refname:short)%09%(objecttype)%09%(taggerdate:iso-strict)%09%(contents:subject)'], repoAbs);
1505
1518
  return (fe.ok ? fe.stdout.split('\n').filter(Boolean) : []).map((l) => l.split('\t'))
1519
+ .filter(([name]) => !onlyTags || onlyTags.has(name))
1506
1520
  .filter(([name, type, , subject]) => type === 'tag' && /-rc\.[1-9][0-9]*$/.test(name) && String(subject || '').endsWith('(colab release cut)'))
1507
1521
  .map(([name, , date]) => ({ name, date }));
1508
1522
  }
@@ -1569,11 +1583,11 @@ function measureAutoSignals(repoAbs, { doc, sha, lastFinal, remote, issues, trun
1569
1583
  return { signals, migration: (v) => releaseCut.parseMigrationSection(migrationText, v) };
1570
1584
  }
1571
1585
 
1572
- /** #446: every final `vX.Y.Z` tag as [{ name, date }] — what release.final-spacing counts. A human's final counts too. */
1573
- 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) {
1574
1588
  const fe = git.git(['for-each-ref', 'refs/tags', '--format=%(refname:short)%09%(creatordate:iso-strict)'], repoAbs);
1575
1589
  return (fe.ok ? fe.stdout.split('\n').filter(Boolean) : []).map((l) => l.split('\t'))
1576
- .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 }));
1577
1591
  }
1578
1592
 
1579
1593
  /**
@@ -1583,7 +1597,7 @@ function finalTags(repoAbs) {
1583
1597
  * since the newest final. The version is computed here only to find that tracking issue; decide()
1584
1598
  * computes it again from the same inputs, so the two cannot disagree.
1585
1599
  */
1586
- 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 }) {
1587
1601
  const grantDecl = policy.effective.finalGrant;
1588
1602
  const trust = trustAt(repoAbs, `${remote}/main`);
1589
1603
  const finalGrant = isGhUsable(repoAbs)
@@ -1604,7 +1618,7 @@ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, au
1604
1618
  if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
1605
1619
  }
1606
1620
  const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal }), paths: paths || null };
1607
- 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() });
1608
1622
  return { finalGrant, holds, migrations, spacing, tracking };
1609
1623
  }
1610
1624
 
@@ -1674,13 +1688,18 @@ function cmdReleaseCut(argv) {
1674
1688
  deploy: doc.deploy === undefined || doc.deploy === null ? 'none' : String(doc.deploy),
1675
1689
  });
1676
1690
 
1677
- 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 });
1678
1696
  const suggestion = lastFinal
1679
1697
  ? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${remote}/main`))
1680
1698
  : { bump: null, why: 'no final tag yet' };
1681
1699
  const lines = (r) => (r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : []);
1682
- const tags = lines(git.git(['tag', '--list'], repoAbs));
1683
- 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);
1684
1703
 
1685
1704
  const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
1686
1705
  sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
@@ -1690,14 +1709,14 @@ function cmdReleaseCut(argv) {
1690
1709
  let auto = null; // #422
1691
1710
  if (opts.auto) {
1692
1711
  const { signals, migration } = measureAutoSignals(repoAbs, { doc, sha, lastFinal, remote, issues, trunk });
1693
- 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() });
1694
1713
  auto = { signals, migration, cadence, promotion: offTrunk ? measurePromotion(repoAbs, { sha, trunk, remote, fetched: trunkFetch }) : null };
1695
1714
  }
1696
1715
 
1697
1716
  // #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
1698
1717
  // measured only there, so every candidate route's run is what it was.
1699
1718
  const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
1700
- 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 }) : {};
1701
1720
  if (fast && auto) auto.spacing = fastFacts.spacing;
1702
1721
  // #590: route library-fast — a final with nothing deployed. The release-hold veto is its one extra
1703
1722
  // read; a hand cut also needs MIGRATION.md for a manifest-declared major (--auto reads it already).
@@ -2044,10 +2063,12 @@ function cmdReleaseFinalize(argv) {
2044
2063
  const shaR = git.git(['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/main^{commit}`], repoAbs);
2045
2064
  if (!shaR.ok || !shaR.stdout) throw new UserError(`no ${remote}/main — releases are cut from main (CONVENTIONS.md §6)`);
2046
2065
  const mainSha = shaR.stdout;
2047
- 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 });
2048
2069
 
2049
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);
2050
- 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) => {
2051
2072
  const [name, type, peeled, obj, date, subject] = l.split('\t');
2052
2073
  const annotated = type === 'tag';
2053
2074
  return { name, annotated, sha: annotated ? peeled : obj, date: annotated ? date : null, subject: annotated ? subject : '', onMain: false };
@@ -2109,7 +2130,7 @@ function cmdReleaseFinalize(argv) {
2109
2130
  let rows; let rawRows;
2110
2131
  const conditions = measureCandidateConditions(repoAbs, {
2111
2132
  sha: cand.sha,
2112
- lastFinal: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha }),
2133
+ lastFinal: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }),
2113
2134
  at: `${cand.tag}@${shortSha(cand.sha)}`,
2114
2135
  readRuns: () => { rawRows = git.ghRunsAtCommit(repoAbs, cand.sha); rows = releaseCut.withoutOwnWorkflow(rawRows); return rows; }, // #425
2115
2136
  issues,
@@ -2154,7 +2175,7 @@ function cmdReleaseFinalize(argv) {
2154
2175
  const mg = tracking && tracking.number
2155
2176
  ? migrationGrant.evaluateIssue(rec, cand.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
2156
2177
  : { ok: false, reason: 'no tracking issue yet to carry a grant' };
2157
- 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 }) });
2158
2179
  }
2159
2180
  const verdict = releaseFinalize.decide({
2160
2181
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
@@ -599,8 +599,12 @@ function headCandidateVerdict({ candidatesAuto, sha, tagsAtSha, owed, runs, prom
599
599
  const suite = runs.filter((r) => r && !DOWNSTREAM_EVENTS.includes(r.event));
600
600
  if (!suite.length) return out('not-green', `no suite run at ${at} yet — nothing is owed until it is green`);
601
601
  if (suite.some((r) => r.status !== 'completed')) return out('not-green', `a suite run at ${at} is still in flight`);
602
- if (suite.some((r) => r.conclusion !== 'success' && r.conclusion !== 'cancelled')) return out('not-green', `${at} is not green — no candidate is owed for a red head`);
603
- const ok = suite.filter((r) => r.conclusion === 'success');
602
+ // #618: a workflow whose every run here was `skipped` (an opt-in gated off by `if:`) did not run —
603
+ // same reading as release ci-green/full-suite (#616). Skipped beside a red run stays red; a head
604
+ // whose only runs were skipped falls through to "no successful suite run" below.
605
+ const judged = withoutSkippedOnlyWorkflows(suite);
606
+ if (judged.some((r) => r.conclusion !== 'success' && r.conclusion !== 'cancelled')) return out('not-green', `${at} is not green — no candidate is owed for a red head`);
607
+ const ok = judged.filter((r) => r.conclusion === 'success');
604
608
  if (!ok.length) return out('not-green', `no successful suite run at ${at}`);
605
609
  const ms = (x) => Date.parse(x);
606
610
  const greenMs = Math.max(...ok.map((r) => ms(r.updatedAt)).filter((n) => !Number.isNaN(n)));
@@ -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
  };