@futurelastic/colab-handbook 1.18.0-rc.11 → 1.18.0-rc.13
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/audit/audit.mjs +19 -0
- package/package.json +1 -1
- package/tools/colab +69 -16
- package/tools/lib/migration-paths.js +27 -1
- package/tools/lib/release-cut.js +22 -3
- package/tools/lib/release-finalize.js +15 -1
package/audit/audit.mjs
CHANGED
|
@@ -897,6 +897,16 @@ function makeSource(target) {
|
|
|
897
897
|
return [];
|
|
898
898
|
}
|
|
899
899
|
},
|
|
900
|
+
// #676: the tracked files at HEAD under the given declared `migrations:` entries (pathspec-
|
|
901
|
+
// limited, never the whole tree). null = git could not list — the check then says nothing.
|
|
902
|
+
filesAtHeadUnder: (paths) => {
|
|
903
|
+
try {
|
|
904
|
+
const out = execFileSync("git", ["-C", root, "ls-tree", "-r", "--name-only", "HEAD", "--", ...paths], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 });
|
|
905
|
+
return out.split("\n").map((s) => s.trim()).filter(Boolean);
|
|
906
|
+
} catch {
|
|
907
|
+
return null;
|
|
908
|
+
}
|
|
909
|
+
},
|
|
900
910
|
// Every path under a directory named `migrations` (#383's undeclared-layout check). null =
|
|
901
911
|
// git could not list — the check then says nothing rather than reporting a clean tree.
|
|
902
912
|
migrationDirFiles: () => {
|
|
@@ -928,6 +938,8 @@ function makeSource(target) {
|
|
|
928
938
|
// Same cost argument as markdownFiles: a recursive tree listing per repo per sweep. null = not
|
|
929
939
|
// enumerated, so #383's undeclared-migration-layout check is local-only, silently.
|
|
930
940
|
migrationDirFiles: () => null,
|
|
941
|
+
// Same cost argument: the declared-path existence check (#676) is local-only too.
|
|
942
|
+
filesAtHeadUnder: () => null,
|
|
931
943
|
tags: () => listRemoteTags(target.slug),
|
|
932
944
|
metadata: () => readRemoteMetadata(target.slug),
|
|
933
945
|
// The duration report (#137) needs a per-commit walk over historical blobs
|
|
@@ -1438,6 +1450,13 @@ function auditRepoInner(target, ctx) {
|
|
|
1438
1450
|
const why = migrationPaths.noneContradiction(migCfg.none, migrationPaths.defaultLayoutDirs([...new Set(dirsOf)]));
|
|
1439
1451
|
if (why) fail(`migrations: ${why}`);
|
|
1440
1452
|
}
|
|
1453
|
+
// #676: a declared path that names nothing at HEAD is not a layout — release cut/finalize no
|
|
1454
|
+
// longer count it as one, and here it fails where the declaration is read, so the typo is found
|
|
1455
|
+
// before a release refuses on it. Local-only, like the rules around it.
|
|
1456
|
+
if (migCfg.paths.length && src.filesAtHeadUnder) {
|
|
1457
|
+
const presence = migrationPaths.declaredPresence(migCfg.paths, src.filesAtHeadUnder(migCfg.paths));
|
|
1458
|
+
if (presence && presence.missing.length) fail(`migrations: ${migrationPaths.missingNote(presence.missing, "HEAD")}`);
|
|
1459
|
+
}
|
|
1441
1460
|
if (migFiles) {
|
|
1442
1461
|
const undeclared = migrationPaths.undeclaredMigrationDirs(migFiles, migCfg.paths);
|
|
1443
1462
|
if (undeclared.length) {
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -1493,17 +1493,27 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
|
|
|
1493
1493
|
// path anywhere wins: the gate then sees more, never less). The default-layout guard is the verdicts'.
|
|
1494
1494
|
const noneAt = declared.length ? null : migrationPaths.parseMigrationPaths(projectDocAt(repoAbs, sha)).none;
|
|
1495
1495
|
const none = noneAt ? { ...noneAt, dirs: layoutDirs || [] } : null;
|
|
1496
|
+
// #676: a declared path is a layout only where it names something AT THE CANDIDATE — a misspelled or
|
|
1497
|
+
// stale entry used to open the grant gate having read nothing. null = the tree could not be listed.
|
|
1498
|
+
let presence = { present: [], missing: [] };
|
|
1499
|
+
if (declared.length) {
|
|
1500
|
+
// Pathspec-limited: only what sits under a declared entry is listed, never the whole tree.
|
|
1501
|
+
const filesR = git.git(['ls-tree', '-r', '--name-only', sha, '--', ...declared], repoAbs, { maxBuffer: 64 * 1024 * 1024 });
|
|
1502
|
+
presence = migrationPaths.declaredPresence(declared, filesR.ok ? filesR.stdout.split('\n').filter(Boolean) : null);
|
|
1503
|
+
}
|
|
1504
|
+
const missing = presence ? presence.missing : [];
|
|
1496
1505
|
const schema = changes === null
|
|
1497
1506
|
? { ok: false, unread: true, detail: 'git diff failed — schema changes cannot be read' }
|
|
1498
|
-
: releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared, layout, none);
|
|
1507
|
+
: releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared, presence ? layout : null, none, presence ? missing : null);
|
|
1499
1508
|
// #441: every migration file since the last final, destructive or not — an operator-granted
|
|
1500
1509
|
// automatic final refuses an ungranted one (release-finalize.js migrationGrantVerdict).
|
|
1501
1510
|
const migrations = changes === null ? null : changes.filter((c) => releaseCut.isMigrationPath(c.path, declared)).map((c) => c.path);
|
|
1502
|
-
// #671: could a migration have been seen at all? A declared prefix is a layout
|
|
1503
|
-
// default-layout reading above (null = unread, never
|
|
1504
|
-
// without one, so its empty list never reads "nothing read"
|
|
1505
|
-
|
|
1506
|
-
|
|
1511
|
+
// #671: could a migration have been seen at all? A declared prefix is a layout — #676: only one that
|
|
1512
|
+
// exists at the candidate; otherwise the default-layout reading above (null = unread, never
|
|
1513
|
+
// "absent"). The grant gate fails closed without one, so its empty list never reads "nothing read"
|
|
1514
|
+
// as "nothing changed". An unlistable tree with a declaration is unread, never a layout.
|
|
1515
|
+
const migrationLayout = !presence ? null : presence.present.length ? true : layout;
|
|
1516
|
+
return { ci, suite, schema, switches, issues, migrations, migrationLayout, migrationsNone: none, migrationsMissing: missing };
|
|
1507
1517
|
}
|
|
1508
1518
|
|
|
1509
1519
|
/**
|
|
@@ -1641,7 +1651,7 @@ function finalTags(repoAbs, onlyTags = null) {
|
|
|
1641
1651
|
* since the newest final. The version is computed here only to find that tracking issue; decide()
|
|
1642
1652
|
* computes it again from the same inputs, so the two cannot disagree.
|
|
1643
1653
|
*/
|
|
1644
|
-
function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, migrationLayout = null, migrationsNone = null, remoteTags = null }) {
|
|
1654
|
+
function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, migrationLayout = null, migrationsNone = null, migrationsMissing = [], remoteTags = null }) {
|
|
1645
1655
|
const grantDecl = policy.effective.finalGrant;
|
|
1646
1656
|
const trust = trustAt(repoAbs, `${remote}/main`);
|
|
1647
1657
|
const finalGrant = isGhUsable(repoAbs)
|
|
@@ -1661,7 +1671,7 @@ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, au
|
|
|
1661
1671
|
: { ok: false, reason: 'no tracking issue yet to carry a grant' };
|
|
1662
1672
|
if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
|
|
1663
1673
|
}
|
|
1664
|
-
const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal, layout: migrationLayout, none: migrationsNone }), paths: paths || null };
|
|
1674
|
+
const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal, layout: migrationLayout, none: migrationsNone, missing: migrationsMissing }), paths: paths || null };
|
|
1665
1675
|
const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs, remoteTags), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
|
|
1666
1676
|
return { finalGrant, holds, migrations, spacing, tracking };
|
|
1667
1677
|
}
|
|
@@ -1754,7 +1764,7 @@ function cmdReleaseCut(argv) {
|
|
|
1754
1764
|
const tags = lines(git.git(['tag', '--list'], repoAbs)).filter(onRemote);
|
|
1755
1765
|
const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs)).filter(onRemote);
|
|
1756
1766
|
|
|
1757
|
-
const { ci, suite, schema, switches, issues, migrations: migrationPathsSince, migrationLayout, migrationsNone } = measureCandidateConditions(repoAbs, {
|
|
1767
|
+
const { ci, suite, schema, switches, issues, migrations: migrationPathsSince, migrationLayout, migrationsNone, migrationsMissing } = measureCandidateConditions(repoAbs, {
|
|
1758
1768
|
sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
|
|
1759
1769
|
verifying: verifyingPolicy(repoAbs), // #624: the ship gate's rule for which runs may veto
|
|
1760
1770
|
});
|
|
@@ -1770,7 +1780,7 @@ function cmdReleaseCut(argv) {
|
|
|
1770
1780
|
// #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
|
|
1771
1781
|
// measured only there, so every candidate route's run is what it was.
|
|
1772
1782
|
const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
|
|
1773
|
-
const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, migrationLayout, migrationsNone, remoteTags }) : {};
|
|
1783
|
+
const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, migrationLayout, migrationsNone, migrationsMissing, remoteTags }) : {};
|
|
1774
1784
|
if (fast && auto) auto.spacing = fastFacts.spacing;
|
|
1775
1785
|
// #590: route library-fast — a final with nothing deployed. The release-hold veto is its one extra
|
|
1776
1786
|
// read; a hand cut also needs MIGRATION.md for a manifest-declared major (--auto reads it already).
|
|
@@ -2257,7 +2267,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2257
2267
|
const mg = tracking && tracking.number
|
|
2258
2268
|
? migrationGrant.evaluateIssue(rec, cand.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
|
|
2259
2269
|
: { ok: false, reason: 'no tracking issue yet to carry a grant' };
|
|
2260
|
-
migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }), layout: conditions.migrationLayout, none: conditions.migrationsNone });
|
|
2270
|
+
migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }), layout: conditions.migrationLayout, none: conditions.migrationsNone, missing: conditions.migrationsMissing });
|
|
2261
2271
|
}
|
|
2262
2272
|
const verdict = releaseFinalize.decide({
|
|
2263
2273
|
policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
|
|
@@ -3940,6 +3950,8 @@ change. Nothing else can produce a grant — no --force on ship, no project.yml
|
|
|
3940
3950
|
from an issue's content, age or park count. A human act on the issue is the whole answer.
|
|
3941
3951
|
|
|
3942
3952
|
colab migration-grant <N> --branch <branch> grant #N an exemption, bound to <branch>
|
|
3953
|
+
colab migration-grant <N> --branch vX.Y.Z on a release tracking issue: bound to that version
|
|
3954
|
+
(#677 — the command a release hand-off prints)
|
|
3943
3955
|
colab migration-grant <N> --revoke revoke #N's grant (idempotent — safe if none exists)
|
|
3944
3956
|
colab migration-grant --list [--json] list every issue with a live grant right now
|
|
3945
3957
|
|
|
@@ -3965,6 +3977,13 @@ Revoking removes the label FIRST (the gate is restored the same minute) and post
|
|
|
3965
3977
|
grantor — any revoke comment cancels every live grant on that issue, because a safety gate should
|
|
3966
3978
|
fail toward "closed" if either half only partially lands.
|
|
3967
3979
|
|
|
3980
|
+
A RELEASE VERSION (#677). --branch must name a ref (a local branch or origin's copy) — with one
|
|
3981
|
+
exception: a human grant naming a final version \`vX.Y.Z\` that is not a ref, on the issue whose body
|
|
3982
|
+
starts with that version's tracking marker (\`<!-- colab:release version=vX.Y.Z -->\`). That is the
|
|
3983
|
+
grant a release hand-off asks for (\`colab release cut --auto\` on deploy-tag-fast, and a deploy-tag
|
|
3984
|
+
candidate): the version becomes a tag only after the grant, and the release gate reads the grant
|
|
3985
|
+
against the version. Any other version — a typo, or one #N does not track — is refused, nothing posted.
|
|
3986
|
+
|
|
3968
3987
|
There is deliberately no local-only fallback: without a usable \`gh\`, every subcommand here REFUSES
|
|
3969
3988
|
rather than write (or read) something invisible to the machine \`ship\` might later run on.
|
|
3970
3989
|
|
|
@@ -4054,7 +4073,15 @@ function cmdMigrationGrant(argv) {
|
|
|
4054
4073
|
if (!opts.revoke && !opts.branch) {
|
|
4055
4074
|
throw new UserError('--branch <branch> is required — a grant is bound to one branch, never inferred from the current checkout');
|
|
4056
4075
|
}
|
|
4057
|
-
|
|
4076
|
+
// #677: a release version is the one binding name that is not a ref when it is granted — on route
|
|
4077
|
+
// deploy-tag-fast (and a deploy-tag candidate) the grant is what lets `vX.Y.Z` be tagged at all,
|
|
4078
|
+
// and the release gate compares the grant against the computed version, never a ref. So a human
|
|
4079
|
+
// grant naming a canonical final version is deferred here to cmdMigrationGrantCreate, which accepts
|
|
4080
|
+
// it only when #N's tracking marker names exactly that version: a typo is still refused, just one
|
|
4081
|
+
// step later (it needs the tracker). Any other name — and a reviewer grant, which binds a pushed
|
|
4082
|
+
// HEAD — keeps the ref check below, unchanged.
|
|
4083
|
+
if (!opts.revoke) opts.versionBinding = migrationGrantVersionBinding(repoAbs, opts);
|
|
4084
|
+
if (!opts.revoke && !opts.versionBinding && !git.branchExists(repoAbs, opts.branch)) {
|
|
4058
4085
|
throw new UserError(`branch "${opts.branch}" does not resolve to a ref (locally or on origin) — refusing to bind a grant to a name nothing exists at`);
|
|
4059
4086
|
}
|
|
4060
4087
|
// #397: the role, and for a reviewer grant its whole record — all answerable locally, so all
|
|
@@ -4075,6 +4102,19 @@ function cmdMigrationGrant(argv) {
|
|
|
4075
4102
|
return opts.revoke ? cmdMigrationGrantRevoke(repoAbs, num) : cmdMigrationGrantCreate(repoAbs, num, opts);
|
|
4076
4103
|
}
|
|
4077
4104
|
|
|
4105
|
+
/**
|
|
4106
|
+
* #677: true when this grant binds a release VERSION rather than a branch — a human grant whose
|
|
4107
|
+
* --branch is a canonical final version (`vX.Y.Z`, never an `-rc.N`) that resolves to no ref here.
|
|
4108
|
+
* Local only, so it runs before the gh gate; cmdMigrationGrantCreate then holds it to the issue's
|
|
4109
|
+
* tracking marker (`<!-- colab:release version=vX.Y.Z -->`). A ref of that name wins: the grant is
|
|
4110
|
+
* an ordinary branch grant and nothing about it changes.
|
|
4111
|
+
*/
|
|
4112
|
+
function migrationGrantVersionBinding(repoAbs, opts) {
|
|
4113
|
+
if (opts.role !== undefined && String(opts.role) !== 'human') return false;
|
|
4114
|
+
if (!releaseCut.parseVersion(opts.branch)) return false;
|
|
4115
|
+
return !git.branchExists(repoAbs, opts.branch);
|
|
4116
|
+
}
|
|
4117
|
+
|
|
4078
4118
|
/**
|
|
4079
4119
|
* #397: resolve the grant's role and, for a reviewer grant, build and check its review record.
|
|
4080
4120
|
* Returns null for a human grant (the unchanged path). Throws UserError on anything a reviewer
|
|
@@ -4195,15 +4235,23 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
|
|
|
4195
4235
|
if (!opts.branch) {
|
|
4196
4236
|
throw new UserError('--branch <branch> is required — a grant is bound to one branch, never inferred from the current checkout');
|
|
4197
4237
|
}
|
|
4198
|
-
if (!git.branchExists(repoAbs, opts.branch)) {
|
|
4238
|
+
if (!opts.versionBinding && !git.branchExists(repoAbs, opts.branch)) {
|
|
4199
4239
|
throw new UserError(`branch "${opts.branch}" does not resolve to a ref (locally or on origin) — refusing to bind a grant to a name nothing exists at`);
|
|
4200
4240
|
}
|
|
4201
4241
|
|
|
4202
|
-
const info = git.ghIssueView(repoAbs, num, ['state', 'labels']);
|
|
4242
|
+
const info = git.ghIssueView(repoAbs, num, opts.versionBinding ? ['state', 'labels', 'body'] : ['state', 'labels']);
|
|
4203
4243
|
if (!info) throw new UserError(`could not read #${num} from the tracker — refusing to write a grant blind`);
|
|
4204
4244
|
if (info.state !== 'OPEN') {
|
|
4205
4245
|
throw new UserError(`#${num} is ${info.state} — a grant expires the instant its issue closes, so granting a closed one would do nothing (CONVENTIONS.md §5, Migration exemption)`);
|
|
4206
4246
|
}
|
|
4247
|
+
// #677: a version-bound grant stands on the tracking marker in place of a ref — the name must be
|
|
4248
|
+
// exactly the version #N tracks, so a typo still binds nothing.
|
|
4249
|
+
if (opts.versionBinding) {
|
|
4250
|
+
const tracked = releaseFinalize.parseReleaseMarker(info.body);
|
|
4251
|
+
if (tracked !== opts.branch) {
|
|
4252
|
+
throw new UserError(`"${opts.branch}" is not a ref, and #${num} ${tracked ? `tracks ${tracked}, not ${opts.branch}` : 'carries no release tracking marker (<!-- colab:release version=vX.Y.Z -->)'} — a version is granted only on its own tracking issue; nothing was posted. Re-run with the version #${num} tracks, or the branch the migration is on: COLAB_HUMAN=1 colab migration-grant ${num} --branch ${tracked || '<branch>'}`);
|
|
4253
|
+
}
|
|
4254
|
+
}
|
|
4207
4255
|
|
|
4208
4256
|
const present = git.ghListLabels(repoAbs);
|
|
4209
4257
|
if (present && !present.includes(labels.MIGRATION_GRANT_LABEL)) {
|
|
@@ -4243,8 +4291,13 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
|
|
|
4243
4291
|
print(` Revoke any time: colab migration-grant ${num} --revoke`);
|
|
4244
4292
|
return 0;
|
|
4245
4293
|
}
|
|
4246
|
-
|
|
4247
|
-
|
|
4294
|
+
if (opts.versionBinding) {
|
|
4295
|
+
print(`Granted #${num} in ${shortRepo(repoAbs)} a migration exemption for release ${opts.branch}.`);
|
|
4296
|
+
print(` This covers ONLY that version's final, and expires the moment #${num} closes. The next green release run tags it.`);
|
|
4297
|
+
} else {
|
|
4298
|
+
print(`Granted #${num} in ${shortRepo(repoAbs)} a migration exemption for branch "${opts.branch}".`);
|
|
4299
|
+
print(` This covers ONLY this branch, and expires the moment #${num} closes.`);
|
|
4300
|
+
}
|
|
4248
4301
|
print(` Revoke any time: colab migration-grant ${num} --revoke`);
|
|
4249
4302
|
// Deliberately no pushEvent — see HELP_SHIP's JSON note: no receiver-agreed kind exists for
|
|
4250
4303
|
// this yet, and both markers are already visible on the tracker from any machine.
|
|
@@ -172,6 +172,32 @@ function unionPaths(...docs) {
|
|
|
172
172
|
return out;
|
|
173
173
|
}
|
|
174
174
|
|
|
175
|
+
/**
|
|
176
|
+
* #676: which declared entries name something at a commit. `files` is that commit's tracked-file list
|
|
177
|
+
* (`git ls-tree -r --name-only <sha>`), or null when it could not be read. A directory entry exists
|
|
178
|
+
* when a tracked file sits under it, a no-slash entry when it is that file or a directory holding one
|
|
179
|
+
* (entryCovers, the same rule the gate matches by). Returns `{ present, missing }` in declared order,
|
|
180
|
+
* or null for an unread tree — never "everything missing", which would be a guess.
|
|
181
|
+
*
|
|
182
|
+
* Before this a declared path counted as a layout whether or not it existed, so a misspelled or stale
|
|
183
|
+
* entry opened the migration-grant gate having read nothing. Only `present` is a layout; `missing` is
|
|
184
|
+
* named wherever the gate reports, and a gate with nothing else to read fails closed.
|
|
185
|
+
*/
|
|
186
|
+
function declaredPresence(declared, files) {
|
|
187
|
+
if (!Array.isArray(files)) return null;
|
|
188
|
+
const present = [];
|
|
189
|
+
const missing = [];
|
|
190
|
+
for (const p of declared || []) (files.some((f) => entryCovers(p, f)) ? present : missing).push(p);
|
|
191
|
+
return { present, missing };
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** `missing` (declaredPresence) as the one sentence every gate appends — empty when none is missing. */
|
|
195
|
+
function missingNote(missing, where = 'the candidate') {
|
|
196
|
+
if (!missing || !missing.length) return '';
|
|
197
|
+
const list = missing.join(', ');
|
|
198
|
+
return `declared \`migrations:\` ${missing.length === 1 ? 'path' : 'paths'} ${list} ${missing.length === 1 ? 'does' : 'do'} not exist at ${where}, so nothing was read there — fix or remove ${missing.length === 1 ? 'the entry' : 'the entries'} in .github/project.yml (a misspelled or stale path is not a layout, #676)`;
|
|
199
|
+
}
|
|
200
|
+
|
|
175
201
|
/** Is `file` (repo-relative, `/`-separated) a migration under the defaults or a declared prefix? */
|
|
176
202
|
function isMigrationPath(file, declared) {
|
|
177
203
|
const f = String(file || '');
|
|
@@ -215,5 +241,5 @@ function undeclaredMigrationDirs(files, declared) {
|
|
|
215
241
|
|
|
216
242
|
module.exports = {
|
|
217
243
|
DEFAULT_MIGRATION_PATHS, parseMigrationPaths, unionPaths, isMigrationPath, isDeclaredFile, undeclaredMigrationDirs,
|
|
218
|
-
noneContradiction, defaultLayoutDirs,
|
|
244
|
+
noneContradiction, defaultLayoutDirs, declaredPresence, missingNote,
|
|
219
245
|
};
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -927,8 +927,22 @@ function laravelDestructive(up, addedBefore) {
|
|
|
927
927
|
* true / false / null (the tree could not be read — never "absent"). Undefined = a caller that does
|
|
928
928
|
* not measure it, read as today: present. `none` (#672) = the candidate's `migrations: none` block
|
|
929
929
|
* (`{ reason, dirs? }`), or absent.
|
|
930
|
+
*
|
|
931
|
+
* #676: `missing` = the declared entries that do not exist at the candidate (migration-paths.js
|
|
932
|
+
* declaredPresence). They still classify a change (a file deleted under one is still read — the gate
|
|
933
|
+
* sees more, never less), but they are not a layout and not in the ✓'s scope: with nothing else to
|
|
934
|
+
* read the verdict is NOT CHECKED naming them, and beside a real layout every detail names them.
|
|
935
|
+
* `missing` null = the tree could not be listed (pass `layout` null with it): unread, never a ✓.
|
|
936
|
+
* Undefined = a caller that does not measure it, read as before: every declared path present.
|
|
930
937
|
*/
|
|
931
|
-
function schemaVerdict(changes, since, declared, layout, none) {
|
|
938
|
+
function schemaVerdict(changes, since, declared, layout, none, missing) {
|
|
939
|
+
const v = schemaVerdictCore(changes, since, declared, layout, none, missing);
|
|
940
|
+
const note = v.missingNamed ? '' : migrationPaths.missingNote(missing);
|
|
941
|
+
const { missingNamed, ...out } = v;
|
|
942
|
+
return note ? { ...out, detail: `${out.detail} — ${note}` } : out;
|
|
943
|
+
}
|
|
944
|
+
|
|
945
|
+
function schemaVerdictCore(changes, since, declared, layout, none, missing) {
|
|
932
946
|
// #672: the candidate's `migrations: none` block. Contradicted by a default layout → refused on every
|
|
933
947
|
// cut, whatever changed; otherwise, with nothing changed, "not checked" naming the declaration —
|
|
934
948
|
// never a ✓ (nothing was read), never the "declare a layout" advice (the repo already answered).
|
|
@@ -947,14 +961,19 @@ function schemaVerdict(changes, since, declared, layout, none) {
|
|
|
947
961
|
const unread = (declared && declared.length)
|
|
948
962
|
? history.filter((c) => !/\.(php|sql)$/.test(c.path) && !migrationPaths.isMigrationPath(c.path, []))
|
|
949
963
|
: [];
|
|
950
|
-
|
|
951
|
-
const
|
|
964
|
+
// `missing` null = the candidate's tree could not be listed: no declared path is known to exist.
|
|
965
|
+
const present = missing === null ? [] : (declared || []).filter((p) => !(missing || []).includes(p));
|
|
966
|
+
const scope = `Laravel database/migrations + Prisma prisma/migrations${present.length ? ` + declared ${present.join(', ')} (php/sql only; a declared file: the SQL it added)` : ''} — other layouts are not read`;
|
|
967
|
+
const hasDeclared = present.length > 0;
|
|
952
968
|
const notChecked = (why) => ({ ok: true, checked: false, detail: `not checked — ${why}` });
|
|
953
969
|
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(', ')}`;
|
|
954
970
|
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 schema migrations declares `migrations:` then `none: <why>` (#672)';
|
|
955
971
|
if (!migrations.length && !schemaFiles.length) {
|
|
956
972
|
if (unread.length) return notChecked(unreadWhy());
|
|
957
973
|
if (none && layout === false) return notChecked(`the repo declares \`migrations: none\` (${none.reason}) and no Laravel or Prisma migrations directory exists at the candidate, so there is no schema to read`);
|
|
974
|
+
if (!hasDeclared && layout === false && missing && missing.length) {
|
|
975
|
+
return { ...notChecked(`the declared \`migrations:\` ${missing.length === 1 ? 'path' : 'paths'} ${missing.join(', ')} ${missing.length === 1 ? 'does' : 'do'} not exist at the candidate and there is no Laravel database/migrations/ or Prisma prisma/migrations/ directory, so no migration was read — fix the path (a misspelled or stale entry is not a layout, #676), or ${howToDeclare}`), missingNamed: true };
|
|
976
|
+
}
|
|
958
977
|
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}`);
|
|
959
978
|
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}`);
|
|
960
979
|
return { ok: true, detail: `no migration file changed since ${since} (${scope})` };
|
|
@@ -569,9 +569,19 @@ function regressionVerdict(edges, { periodStart }) {
|
|
|
569
569
|
* (`{ reason, dirs? }` — `dirs` the default-layout directories found, for the refusal), honoured only where no default layout exists (`layout` false). With a layout there
|
|
570
570
|
* (`layout` true) the declaration is a contradiction and the gate refuses, migrations changed or not:
|
|
571
571
|
* a repo that can have migrations is never waved through; an unread tree still fails closed.
|
|
572
|
+
* #676: `layout` true comes from a declared path only when it EXISTS at the candidate
|
|
573
|
+
* (migration-paths.js declaredPresence); `missing` lists the declared paths that do not. Every detail
|
|
574
|
+
* names them, and with nothing else to read the refusal says so — a misspelled or stale path is not
|
|
575
|
+
* a layout. Missing beside a real layout is reported, never refused: the gate reads what exists.
|
|
572
576
|
* Returns { ok, detail } (+ unread: true when something could not be read).
|
|
573
577
|
*/
|
|
574
|
-
function migrationGrantVerdict(
|
|
578
|
+
function migrationGrantVerdict(args) {
|
|
579
|
+
const { missingNamed, ...v } = migrationGrantVerdictCore(args);
|
|
580
|
+
const note = missingNamed ? '' : migrationPaths.missingNote(args.missing);
|
|
581
|
+
return note ? { ...v, detail: `${v.detail} — ${note}` } : v;
|
|
582
|
+
}
|
|
583
|
+
|
|
584
|
+
function migrationGrantVerdictCore({ paths, grant, since, layout, none, missing }) {
|
|
575
585
|
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' };
|
|
576
586
|
if (none) {
|
|
577
587
|
if (layout === true) return { ok: false, detail: `${migrationPaths.noneContradiction(none, none.dirs && none.dirs.length ? none.dirs : ['a Laravel database/migrations/ or Prisma prisma/migrations/ directory'])} — then the usual migration grant applies (COLAB_HUMAN=1 colab migration-grant <tracking issue> --branch <version>)` };
|
|
@@ -584,6 +594,10 @@ function migrationGrantVerdict({ paths, grant, since, layout, none }) {
|
|
|
584
594
|
// #673: a schema applied inline by the server's own code is declarable too — as the FILE — and the
|
|
585
595
|
// detail names the grant command that clears its next change, so no one reaches for a raw tag.
|
|
586
596
|
const wayOut = 'declare where the schema lives as `migrations:` in .github/project.yml (project.schema.md `migrations`) — a migration directory (`migrations: [backend/migrations/]`) or, for a schema the server applies inline, the file itself (`migrations: [server/db.ts]`); a change under it then clears the usual way (COLAB_HUMAN=1 colab migration-grant <tracking issue> --branch <version>). A repo with no schema migrations at all declares that instead, with its reason (`migrations:` then `none: <why>`, #672). Until then the final is a human act, not the grant\'s';
|
|
597
|
+
if (layout === false && missing && missing.length) {
|
|
598
|
+
// #676: declared, but nothing it names is there — the same "cannot see" as an undeclared repo.
|
|
599
|
+
return { ok: false, missingNamed: true, detail: `no migration was read since ${since || 'the first commit'}: the declared \`migrations:\` ${missing.length === 1 ? 'path' : 'paths'} ${missing.join(', ')} ${missing.length === 1 ? 'does' : 'do'} not exist at the candidate and there is no Laravel database/migrations/ or Prisma prisma/migrations/ directory, so a migration would be invisible — fix the path (a misspelled or stale entry is not a layout, #676), or ${wayOut}` };
|
|
600
|
+
}
|
|
587
601
|
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}` };
|
|
588
602
|
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}` };
|
|
589
603
|
return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
|