@futurelastic/colab-handbook 1.18.0-rc.5 → 1.18.0-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.18.0-rc.5"
36
+ "version": "1.18.0-rc.6"
37
37
  }
package/tools/colab CHANGED
@@ -1483,7 +1483,11 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
1483
1483
  // #441: every migration file since the last final, destructive or not — an operator-granted
1484
1484
  // automatic final refuses an ungranted one (release-finalize.js migrationGrantVerdict).
1485
1485
  const migrations = changes === null ? null : changes.filter((c) => releaseCut.isMigrationPath(c.path, declared)).map((c) => c.path);
1486
- return { ci, suite, schema, switches, issues, migrations };
1486
+ // #671: could a migration have been seen at all? A declared prefix is a layout; otherwise the
1487
+ // default-layout reading above (null = unread, never "absent"). The grant gate fails closed
1488
+ // without one, so its empty list never reads "nothing read" as "nothing changed".
1489
+ const migrationLayout = declared.length ? true : layout;
1490
+ return { ci, suite, schema, switches, issues, migrations, migrationLayout };
1487
1491
  }
1488
1492
 
1489
1493
  /**
@@ -1621,7 +1625,7 @@ function finalTags(repoAbs, onlyTags = null) {
1621
1625
  * since the newest final. The version is computed here only to find that tracking issue; decide()
1622
1626
  * computes it again from the same inputs, so the two cannot disagree.
1623
1627
  */
1624
- function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, remoteTags = null }) {
1628
+ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, migrationLayout = null, remoteTags = null }) {
1625
1629
  const grantDecl = policy.effective.finalGrant;
1626
1630
  const trust = trustAt(repoAbs, `${remote}/main`);
1627
1631
  const finalGrant = isGhUsable(repoAbs)
@@ -1641,7 +1645,7 @@ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, au
1641
1645
  : { ok: false, reason: 'no tracking issue yet to carry a grant' };
1642
1646
  if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
1643
1647
  }
1644
- const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal }), paths: paths || null };
1648
+ const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal, layout: migrationLayout }), paths: paths || null };
1645
1649
  const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs, remoteTags), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
1646
1650
  return { finalGrant, holds, migrations, spacing, tracking };
1647
1651
  }
@@ -1734,7 +1738,7 @@ function cmdReleaseCut(argv) {
1734
1738
  const tags = lines(git.git(['tag', '--list'], repoAbs)).filter(onRemote);
1735
1739
  const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs)).filter(onRemote);
1736
1740
 
1737
- const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
1741
+ const { ci, suite, schema, switches, issues, migrations: migrationPathsSince, migrationLayout } = measureCandidateConditions(repoAbs, {
1738
1742
  sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
1739
1743
  verifying: verifyingPolicy(repoAbs), // #624: the ship gate's rule for which runs may veto
1740
1744
  });
@@ -1750,7 +1754,7 @@ function cmdReleaseCut(argv) {
1750
1754
  // #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
1751
1755
  // measured only there, so every candidate route's run is what it was.
1752
1756
  const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
1753
- const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, remoteTags }) : {};
1757
+ const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, migrationLayout, remoteTags }) : {};
1754
1758
  if (fast && auto) auto.spacing = fastFacts.spacing;
1755
1759
  // #590: route library-fast — a final with nothing deployed. The release-hold veto is its one extra
1756
1760
  // read; a hand cut also needs MIGRATION.md for a manifest-declared major (--auto reads it already).
@@ -2237,7 +2241,7 @@ function cmdReleaseFinalize(argv) {
2237
2241
  const mg = tracking && tracking.number
2238
2242
  ? migrationGrant.evaluateIssue(rec, cand.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
2239
2243
  : { ok: false, reason: 'no tracking issue yet to carry a grant' };
2240
- migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }) });
2244
+ migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }), layout: conditions.migrationLayout });
2241
2245
  }
2242
2246
  const verdict = releaseFinalize.decide({
2243
2247
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
@@ -560,11 +560,23 @@ function regressionVerdict(edges, { periodStart }) {
560
560
  * human gate. `paths` is every migration file changed since the last final (null = unread);
561
561
  * `grant` is migration-grant.js evaluateIssue() of the version's TRACKING issue, bound to the
562
562
  * version (`colab migration-grant <tracking> --branch vX.Y.Z`), or null when there was nothing to
563
- * evaluate. Returns { ok, detail }.
563
+ * evaluate. `layout` (#671) says whether a migration could have been seen at the candidate at all:
564
+ * true = a `migrations:` prefix is declared or a default layout (Laravel database/migrations/,
565
+ * Prisma prisma/migrations/) exists in the tree; false = neither, so an empty `paths` is "nothing
566
+ * read", not "nothing changed"; null/absent = the tree could not be read. An empty `paths` passes
567
+ * only with a layout. Returns { ok, detail } (+ unread: true when something could not be read).
564
568
  */
565
- function migrationGrantVerdict({ paths, grant, since }) {
569
+ function migrationGrantVerdict({ paths, grant, since, layout }) {
566
570
  if (paths === null || paths === undefined) return { ok: false, unread: true, detail: 'the migration files since the last final could not be read — an unread migration is not an absent one' };
567
- if (!paths.length) return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
571
+ if (!paths.length) {
572
+ // #671: fail closed where nothing could have been seen — an automatically deployed final never
573
+ // reads "nothing read" as "nothing changed". The way out is named in the detail, never implied —
574
+ // route-neutral: release finalize prints its own human command, and route deploy-tag-fast has none.
575
+ const wayOut = 'declare the migration directory as `migrations:` in .github/project.yml (project.schema.md `migrations`); until then the final is a human act, not the grant\'s — and a repo with no database has no layout to declare, so its final stays one';
576
+ if (layout === false) return { ok: false, detail: `no migration was read since ${since || 'the first commit'}: no \`migrations:\` declared and no Laravel database/migrations/ or Prisma prisma/migrations/ directory at the candidate, so a migration elsewhere would be invisible — ${wayOut}` };
577
+ if (layout !== true) return { ok: false, unread: true, detail: `the tree at the candidate could not be read for a migration layout, so an empty migration list since ${since || 'the first commit'} is not evidence that none changed — ${wayOut}` };
578
+ return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
579
+ }
568
580
  const list = paths.join(', ');
569
581
  if (grant && grant.ok) return { ok: true, detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}), granted on the tracking issue #${grant.issue}` };
570
582
  return {