@futurelastic/colab-handbook 1.18.0-rc.4 → 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.4"
36
+ "version": "1.18.0-rc.6"
37
37
  }
@@ -516,7 +516,7 @@ jobs:
516
516
  {
517
517
  echo "### colab promote --auto"
518
518
  echo
519
- jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
519
+ jq -r '.checks[]? | "- \(if .checked == false then "·" elif .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
520
520
  echo
521
521
  } >> "$GITHUB_STEP_SUMMARY"
522
522
  if [ "${DRY_RUN:-false}" = "true" ]; then
@@ -585,7 +585,7 @@ jobs:
585
585
  {
586
586
  echo "### colab release cut --auto"
587
587
  echo
588
- jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
588
+ jq -r '.checks[]? | "- \(if .checked == false then "·" elif .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
589
589
  echo
590
590
  } >> "$GITHUB_STEP_SUMMARY"
591
591
  if [ "${DRY_RUN:-false}" = "true" ]; then
@@ -721,7 +721,7 @@ jobs:
721
721
  {
722
722
  echo "### colab release finalize --auto — $STATE"
723
723
  echo
724
- jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
724
+ jq -r '.checks[]? | "- \(if .checked == false then "·" elif .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
725
725
  echo
726
726
  if [ -n "$WHY" ]; then echo "**Why no final:** $WHY"; echo; fi
727
727
  if [ "$(jq -r '(.skipped // []) | length' "$OUT")" != "0" ]; then
package/tools/colab CHANGED
@@ -1311,7 +1311,9 @@ Refuses, naming each failed condition (all are reported, not just the first):
1311
1311
  under a project.yml \`migrations:\` prefix) or an existing migration was
1312
1312
  edited/deleted. Other layouts are not read — a declared migration in another
1313
1313
  format is NAMED in the detail, and the release notes still owe the §6
1314
- judgement on the diff
1314
+ judgement on the diff. When nothing was read — no default layout and no
1315
+ \`migrations:\` declared, or a declared migration in another format changed —
1316
+ the row prints · "not checked" (#670): it refuses nothing, and it is never a ✓
1315
1317
  switch-dependencies a colab:switch marker is malformed, or a finished switch needs one that is not
1316
1318
  manifest-version the tag does not equal the version a manifest declares (VERSION, package.json,
1317
1319
  Cargo.toml [package], else [workspace.package] (#620), pyproject.toml
@@ -1470,13 +1472,22 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
1470
1472
  // same one rule the ship gate reads (tools/lib/migration-paths.js), never a second regex.
1471
1473
  const declared = migrationPaths.unionPaths(projectDoc(repoAbs), projectDocAt(repoAbs, sha));
1472
1474
  const changes = releaseCutChanges(repoAbs, lastFinal, sha, declared);
1475
+ // #670: does a default layout exist at the candidate — anywhere in the tree, as the defaults are
1476
+ // matched (migration-paths.js isMigrationPath)? Without one and with nothing declared, the check
1477
+ // read nothing: "not checked", never a ✓. null = the tree could not be read, never "absent".
1478
+ const layoutR = git.git(['ls-tree', '-r', '-d', '--name-only', sha], repoAbs);
1479
+ const layout = layoutR.ok ? layoutR.stdout.split('\n').some((d) => d && migrationPaths.isMigrationPath(`${d}/`, [])) : null;
1473
1480
  const schema = changes === null
1474
1481
  ? { ok: false, unread: true, detail: 'git diff failed — schema changes cannot be read' }
1475
- : releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared);
1482
+ : releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared, layout);
1476
1483
  // #441: every migration file since the last final, destructive or not — an operator-granted
1477
1484
  // automatic final refuses an ungranted one (release-finalize.js migrationGrantVerdict).
1478
1485
  const migrations = changes === null ? null : changes.filter((c) => releaseCut.isMigrationPath(c.path, declared)).map((c) => c.path);
1479
- 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 };
1480
1491
  }
1481
1492
 
1482
1493
  /**
@@ -1614,7 +1625,7 @@ function finalTags(repoAbs, onlyTags = null) {
1614
1625
  * since the newest final. The version is computed here only to find that tracking issue; decide()
1615
1626
  * computes it again from the same inputs, so the two cannot disagree.
1616
1627
  */
1617
- 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 }) {
1618
1629
  const grantDecl = policy.effective.finalGrant;
1619
1630
  const trust = trustAt(repoAbs, `${remote}/main`);
1620
1631
  const finalGrant = isGhUsable(repoAbs)
@@ -1634,7 +1645,7 @@ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, au
1634
1645
  : { ok: false, reason: 'no tracking issue yet to carry a grant' };
1635
1646
  if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
1636
1647
  }
1637
- 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 };
1638
1649
  const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs, remoteTags), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
1639
1650
  return { finalGrant, holds, migrations, spacing, tracking };
1640
1651
  }
@@ -1727,7 +1738,7 @@ function cmdReleaseCut(argv) {
1727
1738
  const tags = lines(git.git(['tag', '--list'], repoAbs)).filter(onRemote);
1728
1739
  const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs)).filter(onRemote);
1729
1740
 
1730
- const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
1741
+ const { ci, suite, schema, switches, issues, migrations: migrationPathsSince, migrationLayout } = measureCandidateConditions(repoAbs, {
1731
1742
  sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
1732
1743
  verifying: verifyingPolicy(repoAbs), // #624: the ship gate's rule for which runs may veto
1733
1744
  });
@@ -1743,7 +1754,7 @@ function cmdReleaseCut(argv) {
1743
1754
  // #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
1744
1755
  // measured only there, so every candidate route's run is what it was.
1745
1756
  const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
1746
- 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 }) : {};
1747
1758
  if (fast && auto) auto.spacing = fastFacts.spacing;
1748
1759
  // #590: route library-fast — a final with nothing deployed. The release-hold veto is its one extra
1749
1760
  // read; a hand cut also needs MIGRATION.md for a manifest-declared major (--auto reads it already).
@@ -1862,7 +1873,7 @@ function cmdReleaseCut(argv) {
1862
1873
  for (const l of verdict.signals.lines) print(` · ${l}`);
1863
1874
  }
1864
1875
  const width = Math.max(...verdict.checks.map((c) => c.condition.length));
1865
- for (const c of verdict.checks) print(` ${c.ok ? '✓' : '✗'} ${c.condition.padEnd(width)} ${c.detail}`);
1876
+ for (const c of verdict.checks) print(` ${c.checked === false ? '·' : c.ok ? '✓' : '✗'} ${c.condition.padEnd(width)} ${c.detail}`);
1866
1877
  print('');
1867
1878
  if (verdict.noop) {
1868
1879
  print(fast
@@ -2230,7 +2241,7 @@ function cmdReleaseFinalize(argv) {
2230
2241
  const mg = tracking && tracking.number
2231
2242
  ? migrationGrant.evaluateIssue(rec, cand.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
2232
2243
  : { ok: false, reason: 'no tracking issue yet to carry a grant' };
2233
- 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 });
2234
2245
  }
2235
2246
  const verdict = releaseFinalize.decide({
2236
2247
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
@@ -2379,7 +2390,7 @@ function cmdReleaseFinalize(argv) {
2379
2390
  } else {
2380
2391
  print(`colab release finalize${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} (last final: ${lastFinal || 'none'}${cand ? `, candidate: ${cand.tag}` : ''})`);
2381
2392
  const width = Math.max(...verdict.checks.map((c) => c.condition.length));
2382
- for (const c of verdict.checks) print(` ${c.ok ? '✓' : (c.required ? '✗' : '·')} ${c.condition.padEnd(width)} ${c.detail}`);
2393
+ for (const c of verdict.checks) print(` ${c.checked === false ? '·' : c.ok ? '✓' : (c.required ? '✗' : '·')} ${c.condition.padEnd(width)} ${c.detail}`);
2383
2394
  if (walk && skipped.length) {
2384
2395
  print(' other open candidates:');
2385
2396
  for (const x of skipped) print(` · ${x.tag}: ${x.state}${x.detail ? ` — ${x.detail}` : ''}`);
@@ -854,8 +854,21 @@ function laravelUpBody(text) {
854
854
  * — an edited or deleted migration counts as destructive, because rewriting history a database has
855
855
  * already run is not an add. A false positive costs a human cutting the candidate; a false negative
856
856
  * is the §6 judgement the release notes still owe (read the diff, not only this).
857
+ *
858
+ * #670: a third outcome beside ✓ and ✗ — NOT CHECKED, `{ ok: true, checked: false }`. It refuses
859
+ * nothing (an absent `migrations:` still changes no gate — project.schema.md `migrations`; for a
860
+ * DECLARED migration in an unread format, the #441 migration-grant check still holds an automatic
861
+ * final), but it is never printed as a green pass:
862
+ * a ✓ reading "other layouts are not read" was read as "no migration" by the human finalizing a
863
+ * release whose migrations sat in a directory this check never looked at. Two cases:
864
+ * - nothing declared and no default layout at the candidate (`layout` false) — nothing was read;
865
+ * - a declared migration in a format the heuristic does not read changed, and nothing it did read
866
+ * is destructive (a destructive read file is still ✗).
867
+ * `layout` = does `database/migrations/` or `prisma/migrations/` exist in the tree at the candidate:
868
+ * true / false / null (the tree could not be read — never "absent"). Undefined = a caller that does
869
+ * not measure it, read as today: present.
857
870
  */
858
- function schemaVerdict(changes, since, declared) {
871
+ function schemaVerdict(changes, since, declared, layout) {
859
872
  const inPaths = (changes || []).filter((c) => isMigrationPath(c.path, declared));
860
873
  const migrations = inPaths.filter((c) => /\.(php|sql)$/.test(c.path));
861
874
  // #383: a declared path widens what COUNTS as a migration, not what this heuristic can READ. A
@@ -867,10 +880,16 @@ function schemaVerdict(changes, since, declared) {
867
880
  ? inPaths.filter((c) => !/\.(php|sql)$/.test(c.path) && !migrationPaths.isMigrationPath(c.path, []))
868
881
  : [];
869
882
  const scope = `Laravel database/migrations + Prisma prisma/migrations${declared && declared.length ? ` + declared ${declared.join(', ')} (php/sql only)` : ''} — other layouts are not read`;
870
- const unreadNote = unread.length
871
- ? `; ${unread.length} declared migration file(s) in a format this check does not read — a human reads them: ${unread.map((c) => c.path).join(', ')}`
872
- : '';
873
- if (!migrations.length) return { ok: true, detail: `no migration file changed since ${since} (${scope})${unreadNote}` };
883
+ const hasDeclared = !!(declared && declared.length);
884
+ const notChecked = (why) => ({ ok: true, checked: false, detail: `not checked — ${why}` });
885
+ const unreadWhy = () => `${unread.length} declared migration file(s) changed since ${since} in a format this check does not read (php/sql only) — a human reads them before the final: ${unread.map((c) => c.path).join(', ')}`;
886
+ const howToDeclare = 'a repo whose migrations live elsewhere declares their directory as `migrations:` in .github/project.yml (project.schema.md `migrations`); a repo with no database has nothing to declare';
887
+ if (!migrations.length) {
888
+ if (unread.length) return notChecked(unreadWhy());
889
+ if (!hasDeclared && layout === false) return notChecked(`no Laravel database/migrations/ or Prisma prisma/migrations/ directory at the candidate and no \`migrations:\` declared, so no migration was read — ${howToDeclare}`);
890
+ if (!hasDeclared && layout === null) return notChecked(`the tree at the candidate could not be read for a migration layout, so no migration was read — ${howToDeclare}`);
891
+ return { ok: true, detail: `no migration file changed since ${since} (${scope})` };
892
+ }
874
893
  const findings = [];
875
894
  for (const c of migrations) {
876
895
  const st = String(c.status || '').charAt(0);
@@ -888,7 +907,8 @@ function schemaVerdict(changes, since, declared) {
888
907
  if (findings.length) {
889
908
  return { ok: false, detail: `destructive schema change since ${since} — a release carrying one is a human's to cut (CONVENTIONS.md §6, Switched epics rule 5): ${findings.join('; ')}` };
890
909
  }
891
- return { ok: true, detail: `${migrations.length} migration file(s) added since ${since}, none destructive (${scope})${unreadNote}` };
910
+ if (unread.length) return notChecked(`${migrations.length} migration file(s) added since ${since}, none destructive — but ${unreadWhy()}`);
911
+ return { ok: true, detail: `${migrations.length} migration file(s) added since ${since}, none destructive (${scope})` };
892
912
  }
893
913
 
894
914
  // ---- §6 condition 4: switch dependencies -------------------------------------------------------
@@ -1165,7 +1185,12 @@ function decide(facts) {
1165
1185
 
1166
1186
  for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
1167
1187
  if (!verdict) add(condition, false, 'not measured', true);
1168
- else add(condition, verdict.ok, verdict.detail, isUnread(verdict));
1188
+ else {
1189
+ add(condition, verdict.ok, verdict.detail, isUnread(verdict));
1190
+ // #670: a not-checked verdict passes but is not a ✓ — the one optional field a row can carry,
1191
+ // present only then, so every other row (and `--json` on every other run) is unchanged.
1192
+ if (verdict.checked === false) checks[checks.length - 1].checked = false;
1193
+ }
1169
1194
  }
1170
1195
 
1171
1196
  // #610: a final needs the heavy lane green at its exact sha, under every integration profile. Only
@@ -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 {
@@ -713,6 +725,7 @@ function decide(facts) {
713
725
  if (hv) add('heavy-lane', hv.ok, hv.detail);
714
726
  for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
715
727
  add(condition, v && v.ok, v ? v.detail : 'not measured');
728
+ if (v && v.checked === false) checks[checks.length - 1].checked = false; // #670: passes, never a ✓
716
729
  }
717
730
  // #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
718
731
  for (const c of releaseTag.preTagChecks({ tag: cand.version, manifests: f.manifests, ancestry: f.ancestry, tags: f.tags, trunk: 'main', versionSource: p.effective.versionSource === 'tag' ? 'tag' : 'manifest' })) add(c.condition, c.ok, c.detail);
@@ -802,7 +815,7 @@ function tagMessage(verdict, { candidate, period, actor }) {
802
815
  verdict.grant ? `Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or final: human, revokes it)` : null,
803
816
  '',
804
817
  'Conditions (CONVENTIONS.md §6):',
805
- ...verdict.checks.map((c) => `- ${c.condition}: ${c.ok ? 'ok' : (c.required ? 'FAILED' : 'informational')} — ${c.detail}`),
818
+ ...verdict.checks.map((c) => `- ${c.condition}: ${c.checked === false ? 'not checked' : c.ok ? 'ok' : (c.required ? 'FAILED' : 'informational')} — ${c.detail}`),
806
819
  ].filter((l) => l !== null).join('\n') + '\n';
807
820
  }
808
821