@futurelastic/colab-handbook 1.18.0-rc.10 → 1.18.0-rc.12
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 +31 -0
- package/package.json +1 -1
- package/tools/colab +28 -12
- package/tools/lib/adopt.js +5 -1
- package/tools/lib/migration-paths.js +83 -3
- package/tools/lib/release-cut.js +30 -5
- package/tools/lib/release-finalize.js +26 -3
package/audit/audit.mjs
CHANGED
|
@@ -269,6 +269,9 @@ function parseScalarValue(raw) {
|
|
|
269
269
|
const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds", "contention"]); // owner: #394 · gate: #410 · thresholds: #560 · contention: #630
|
|
270
270
|
// The one map whose pairs may hold an INLINE list (`coupled: [a, b]`) — still one level, still no block list (#630).
|
|
271
271
|
const LIST_IN_MAP_KEYS = new Set(["contention"]);
|
|
272
|
+
// A key whose empty value may open EITHER a block list or a one-level map: `migrations:` is a list of
|
|
273
|
+
// paths, or the `none: <reason>` block (#672). The two line shapes cannot be mistaken for each other.
|
|
274
|
+
const LIST_OR_MAP_KEYS = new Set(["migrations"]);
|
|
272
275
|
|
|
273
276
|
function parseFlatYaml(text) {
|
|
274
277
|
const out = {};
|
|
@@ -340,6 +343,7 @@ function parseFlatYaml(text) {
|
|
|
340
343
|
if (trimmed === "") {
|
|
341
344
|
if (NESTED_MAP_KEYS.has(key)) mapKey = key;
|
|
342
345
|
else listKey = key;
|
|
346
|
+
if (LIST_OR_MAP_KEYS.has(key)) mapKey = key;
|
|
343
347
|
}
|
|
344
348
|
});
|
|
345
349
|
return { data: out, problems };
|
|
@@ -893,6 +897,16 @@ function makeSource(target) {
|
|
|
893
897
|
return [];
|
|
894
898
|
}
|
|
895
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
|
+
},
|
|
896
910
|
// Every path under a directory named `migrations` (#383's undeclared-layout check). null =
|
|
897
911
|
// git could not list — the check then says nothing rather than reporting a clean tree.
|
|
898
912
|
migrationDirFiles: () => {
|
|
@@ -924,6 +938,8 @@ function makeSource(target) {
|
|
|
924
938
|
// Same cost argument as markdownFiles: a recursive tree listing per repo per sweep. null = not
|
|
925
939
|
// enumerated, so #383's undeclared-migration-layout check is local-only, silently.
|
|
926
940
|
migrationDirFiles: () => null,
|
|
941
|
+
// Same cost argument: the declared-path existence check (#676) is local-only too.
|
|
942
|
+
filesAtHeadUnder: () => null,
|
|
927
943
|
tags: () => listRemoteTags(target.slug),
|
|
928
944
|
metadata: () => readRemoteMetadata(target.slug),
|
|
929
945
|
// The duration report (#137) needs a per-commit walk over historical blobs
|
|
@@ -1426,6 +1442,21 @@ function auditRepoInner(target, ctx) {
|
|
|
1426
1442
|
migCfg.problems.forEach((p) => fail(p));
|
|
1427
1443
|
migCfg.notes.forEach((p) => warn(p));
|
|
1428
1444
|
const migFiles = src.migrationDirFiles();
|
|
1445
|
+
// #672's guard, where the declaration is read: `migrations: none` beside a Laravel or Prisma
|
|
1446
|
+
// migrations directory is a contradiction, and every later cut refuses it too (release-cut.js
|
|
1447
|
+
// schemaVerdict, release-finalize.js migrationGrantVerdict). Local-only, like the rule below.
|
|
1448
|
+
if (migFiles && migCfg.none) {
|
|
1449
|
+
const dirsOf = migFiles.map((f) => f.split("/").slice(0, -1).map((_, i, a) => a.slice(0, i + 1).join("/"))).flat();
|
|
1450
|
+
const why = migrationPaths.noneContradiction(migCfg.none, migrationPaths.defaultLayoutDirs([...new Set(dirsOf)]));
|
|
1451
|
+
if (why) fail(`migrations: ${why}`);
|
|
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
|
+
}
|
|
1429
1460
|
if (migFiles) {
|
|
1430
1461
|
const undeclared = migrationPaths.undeclaredMigrationDirs(migFiles, migCfg.paths);
|
|
1431
1462
|
if (undeclared.length) {
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -1486,18 +1486,34 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
|
|
|
1486
1486
|
// matched (migration-paths.js isMigrationPath)? Without one and with nothing declared, the check
|
|
1487
1487
|
// read nothing: "not checked", never a ✓. null = the tree could not be read, never "absent".
|
|
1488
1488
|
const layoutR = git.git(['ls-tree', '-r', '-d', '--name-only', sha], repoAbs);
|
|
1489
|
-
const
|
|
1489
|
+
const layoutDirs = layoutR.ok ? migrationPaths.defaultLayoutDirs(layoutR.stdout.split('\n')) : null;
|
|
1490
|
+
const layout = layoutDirs ? layoutDirs.length > 0 : null;
|
|
1491
|
+
// #672: `migrations: none` counts only as committed AT THE CANDIDATE — never the disk copy, which on
|
|
1492
|
+
// a finalize is trunk's head, not what ships — and only where nothing declares a layout (a declared
|
|
1493
|
+
// path anywhere wins: the gate then sees more, never less). The default-layout guard is the verdicts'.
|
|
1494
|
+
const noneAt = declared.length ? null : migrationPaths.parseMigrationPaths(projectDocAt(repoAbs, sha)).none;
|
|
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 : [];
|
|
1490
1505
|
const schema = changes === null
|
|
1491
1506
|
? { ok: false, unread: true, detail: 'git diff failed — schema changes cannot be read' }
|
|
1492
|
-
: releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared, layout);
|
|
1507
|
+
: releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared, presence ? layout : null, none, presence ? missing : null);
|
|
1493
1508
|
// #441: every migration file since the last final, destructive or not — an operator-granted
|
|
1494
1509
|
// automatic final refuses an ungranted one (release-finalize.js migrationGrantVerdict).
|
|
1495
1510
|
const migrations = changes === null ? null : changes.filter((c) => releaseCut.isMigrationPath(c.path, declared)).map((c) => c.path);
|
|
1496
|
-
// #671: could a migration have been seen at all? A declared prefix is a layout
|
|
1497
|
-
// default-layout reading above (null = unread, never
|
|
1498
|
-
// without one, so its empty list never reads "nothing read"
|
|
1499
|
-
|
|
1500
|
-
|
|
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 };
|
|
1501
1517
|
}
|
|
1502
1518
|
|
|
1503
1519
|
/**
|
|
@@ -1635,7 +1651,7 @@ function finalTags(repoAbs, onlyTags = null) {
|
|
|
1635
1651
|
* since the newest final. The version is computed here only to find that tracking issue; decide()
|
|
1636
1652
|
* computes it again from the same inputs, so the two cannot disagree.
|
|
1637
1653
|
*/
|
|
1638
|
-
function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, migrationLayout = null, remoteTags = null }) {
|
|
1654
|
+
function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, migrationLayout = null, migrationsNone = null, migrationsMissing = [], remoteTags = null }) {
|
|
1639
1655
|
const grantDecl = policy.effective.finalGrant;
|
|
1640
1656
|
const trust = trustAt(repoAbs, `${remote}/main`);
|
|
1641
1657
|
const finalGrant = isGhUsable(repoAbs)
|
|
@@ -1655,7 +1671,7 @@ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, au
|
|
|
1655
1671
|
: { ok: false, reason: 'no tracking issue yet to carry a grant' };
|
|
1656
1672
|
if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
|
|
1657
1673
|
}
|
|
1658
|
-
const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal, layout: migrationLayout }), paths: paths || null };
|
|
1674
|
+
const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal, layout: migrationLayout, none: migrationsNone, missing: migrationsMissing }), paths: paths || null };
|
|
1659
1675
|
const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs, remoteTags), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
|
|
1660
1676
|
return { finalGrant, holds, migrations, spacing, tracking };
|
|
1661
1677
|
}
|
|
@@ -1748,7 +1764,7 @@ function cmdReleaseCut(argv) {
|
|
|
1748
1764
|
const tags = lines(git.git(['tag', '--list'], repoAbs)).filter(onRemote);
|
|
1749
1765
|
const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs)).filter(onRemote);
|
|
1750
1766
|
|
|
1751
|
-
const { ci, suite, schema, switches, issues, migrations: migrationPathsSince, migrationLayout } = measureCandidateConditions(repoAbs, {
|
|
1767
|
+
const { ci, suite, schema, switches, issues, migrations: migrationPathsSince, migrationLayout, migrationsNone, migrationsMissing } = measureCandidateConditions(repoAbs, {
|
|
1752
1768
|
sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
|
|
1753
1769
|
verifying: verifyingPolicy(repoAbs), // #624: the ship gate's rule for which runs may veto
|
|
1754
1770
|
});
|
|
@@ -1764,7 +1780,7 @@ function cmdReleaseCut(argv) {
|
|
|
1764
1780
|
// #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
|
|
1765
1781
|
// measured only there, so every candidate route's run is what it was.
|
|
1766
1782
|
const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
|
|
1767
|
-
const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, migrationLayout, remoteTags }) : {};
|
|
1783
|
+
const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, migrationLayout, migrationsNone, migrationsMissing, remoteTags }) : {};
|
|
1768
1784
|
if (fast && auto) auto.spacing = fastFacts.spacing;
|
|
1769
1785
|
// #590: route library-fast — a final with nothing deployed. The release-hold veto is its one extra
|
|
1770
1786
|
// read; a hand cut also needs MIGRATION.md for a manifest-declared major (--auto reads it already).
|
|
@@ -2251,7 +2267,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2251
2267
|
const mg = tracking && tracking.number
|
|
2252
2268
|
? migrationGrant.evaluateIssue(rec, cand.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
|
|
2253
2269
|
: { ok: false, reason: 'no tracking issue yet to carry a grant' };
|
|
2254
|
-
migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }), layout: conditions.migrationLayout });
|
|
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 });
|
|
2255
2271
|
}
|
|
2256
2272
|
const verdict = releaseFinalize.decide({
|
|
2257
2273
|
policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
|
package/tools/lib/adopt.js
CHANGED
|
@@ -280,7 +280,7 @@ function detectMigrationCandidates(cfg, trackedFiles) {
|
|
|
280
280
|
if ([...dirs].some((d) => dir.startsWith(d))) continue;
|
|
281
281
|
dirs.add(dir);
|
|
282
282
|
}
|
|
283
|
-
return { declared: parsed.declared ? declared : null, candidates: [...dirs].sort() };
|
|
283
|
+
return { declared: parsed.declared ? declared : null, none: parsed.none, candidates: [...dirs].sort() };
|
|
284
284
|
}
|
|
285
285
|
|
|
286
286
|
const MIGRATION_CANDIDATES_SHOWN = 6;
|
|
@@ -288,6 +288,10 @@ const MIGRATION_CANDIDATES_SHOWN = 6;
|
|
|
288
288
|
/** The step-2 remainder line about `migrations:` — adopt never asks it, so it always reports it. */
|
|
289
289
|
function migrationsStepText(m) {
|
|
290
290
|
const tail = 'project.schema.md `migrations`; `colab adopt` does not ask it, step 2';
|
|
291
|
+
if (m && m.none) {
|
|
292
|
+
const extra = m.candidates.length ? ` — but these look like migrations, check: ${listShort(m.candidates)}` : '';
|
|
293
|
+
return `\`migrations: none\` declared (${m.none.reason})${extra} — ${tail}`;
|
|
294
|
+
}
|
|
291
295
|
if (m && m.declared && m.declared.length) {
|
|
292
296
|
const extra = m.candidates.length ? ` — still uncovered, check: ${listShort(m.candidates)}` : '';
|
|
293
297
|
return `\`migrations:\` declared (${m.declared.join(', ')})${extra} — ${tail}`;
|
|
@@ -76,30 +76,57 @@ function entryCovers(p, f) {
|
|
|
76
76
|
* lenient in the direction that makes the gate STRICTER (it still sees
|
|
77
77
|
* the path the author obviously meant); the audit fails the shape.
|
|
78
78
|
*
|
|
79
|
+
* - a `none:` block → #672: the repo has no schema migrations, and `none:`'s value says why:
|
|
80
|
+
* migrations:
|
|
81
|
+
* none: every record lives behind another service's API
|
|
82
|
+
* `none` is then `{ reason }` and `paths` is []. A block, not a scalar plus a
|
|
83
|
+
* sibling key, because the reason is part of the declaration and must not
|
|
84
|
+
* drift from it (and tools/lib/yaml.js reads no flow maps). Without a reason —
|
|
85
|
+
* a bare `migrations: none`, an empty `none:`, a `none` list entry — it is a
|
|
86
|
+
* problem and `none` stays null: the grant gate keeps failing closed (#671).
|
|
87
|
+
* Whether a default layout contradicts it is the caller's to measure, at the
|
|
88
|
+
* commit (`noneContradiction`).
|
|
89
|
+
*
|
|
79
90
|
* `paths` never includes the defaults — `isMigrationPath` always applies those itself. An entry
|
|
80
91
|
* keeps its trailing `/` as written (#673): `a/b/` is a directory, `a/b` a file or a directory.
|
|
81
92
|
*/
|
|
82
93
|
function parseMigrationPaths(doc) {
|
|
83
94
|
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'migrations');
|
|
84
95
|
if (!has || doc.migrations === null || doc.migrations === undefined) {
|
|
85
|
-
return { declared: false, paths: [], problems: [], notes: [], reason: 'migrations absent — defaults only' };
|
|
96
|
+
return { declared: false, paths: [], none: null, problems: [], notes: [], reason: 'migrations absent — defaults only' };
|
|
86
97
|
}
|
|
87
98
|
const v = doc.migrations;
|
|
88
99
|
const problems = [];
|
|
89
100
|
const notes = [];
|
|
101
|
+
const NONE_FORM = 'write it as a block naming why — `migrations:` then, indented, `none: <why this repo has no schema migrations>`';
|
|
102
|
+
if (v && typeof v === 'object' && !Array.isArray(v)) {
|
|
103
|
+
const keys = Object.keys(v);
|
|
104
|
+
if (keys.length !== 1 || keys[0] !== 'none') {
|
|
105
|
+
return { declared: true, paths: [], none: null, problems: [`migrations is a block with ${keys.map((k) => `\`${k}\``).join(', ') || 'no key'} — the only block form is \`none: <reason>\` (#672); a layout is a list (e.g. [backend/migrations/])`], notes, reason: 'migrations malformed — defaults only' };
|
|
106
|
+
}
|
|
107
|
+
const why = typeof v.none === 'string' ? v.none.trim() : '';
|
|
108
|
+
if (!why) return { declared: true, paths: [], none: null, problems: [`migrations: none has no reason — ${NONE_FORM}; until it has one, it declares nothing`], notes, reason: 'migrations: none without a reason — defaults only' };
|
|
109
|
+
return { declared: true, paths: [], none: { reason: why }, problems, notes, reason: `migrations: none — ${why}` };
|
|
110
|
+
}
|
|
111
|
+
if (typeof v === 'string' && v.trim().toLowerCase() === 'none') {
|
|
112
|
+
return { declared: true, paths: [], none: null, problems: [`migrations: none needs its reason — ${NONE_FORM}; until it has one, it declares nothing`], notes, reason: 'migrations: none without a reason — defaults only' };
|
|
113
|
+
}
|
|
90
114
|
let entries;
|
|
91
115
|
if (Array.isArray(v)) entries = v;
|
|
92
116
|
else if (typeof v === 'string' && v.trim() !== '') {
|
|
93
117
|
entries = [v];
|
|
94
118
|
problems.push(`migrations is a bare string ${JSON.stringify(v)}, expected a list (e.g. [${v.trim()}])`);
|
|
95
119
|
} else {
|
|
96
|
-
return { declared: true, paths: [], problems: [`migrations is ${JSON.stringify(v)}, expected a list of repo-relative prefixes (e.g. [backend/migrations/])`], notes, reason: 'migrations malformed — defaults only' };
|
|
120
|
+
return { declared: true, paths: [], none: null, problems: [`migrations is ${JSON.stringify(v)}, expected a list of repo-relative prefixes (e.g. [backend/migrations/])`], notes, reason: 'migrations malformed — defaults only' };
|
|
97
121
|
}
|
|
98
122
|
if (Array.isArray(v) && v.length === 0) {
|
|
99
123
|
notes.push('migrations is an empty list — omit the key for the defaults alone');
|
|
100
124
|
}
|
|
101
125
|
const paths = [];
|
|
102
126
|
for (const raw of entries) {
|
|
127
|
+
// #672: `none` inside a list would be a path named `none` — and any declared path reads as a
|
|
128
|
+
// layout, so it would wave the fail-closed grant gate through. Refused, never kept as a path.
|
|
129
|
+
if (typeof raw === 'string' && raw.trim().toLowerCase() === 'none') { problems.push(`migrations: "none" in a list is not a path — to declare no schema migrations, ${NONE_FORM}`); continue; }
|
|
103
130
|
const r = normalizeEntry(raw);
|
|
104
131
|
if (r.problem) { problems.push(`migrations: ${r.problem}`); continue; }
|
|
105
132
|
if (DEFAULT_MIGRATION_PATHS.includes(dirForm(r.path))) {
|
|
@@ -109,7 +136,33 @@ function parseMigrationPaths(doc) {
|
|
|
109
136
|
if (paths.some((q) => dirForm(q) === dirForm(r.path))) { notes.push(`migrations: "${r.path}" is declared twice`); continue; }
|
|
110
137
|
paths.push(r.path);
|
|
111
138
|
}
|
|
112
|
-
return { declared: true, paths, problems, notes, reason: paths.length ? `migrations: [${paths.join(', ')}] + defaults` : 'defaults only' };
|
|
139
|
+
return { declared: true, paths, none: null, problems, notes, reason: paths.length ? `migrations: [${paths.join(', ')}] + defaults` : 'defaults only' };
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* #672's guard: a `migrations: none` contradicted by the tree. `none` is parseMigrationPaths().none;
|
|
144
|
+
* `defaultDirs` the default-layout directories found at the commit (`database/migrations/`,
|
|
145
|
+
* `prisma/migrations/`, anywhere), or null when the tree could not be read. Returns a refusal detail,
|
|
146
|
+
* or null when `none` stands (or there is no `none`). An unread tree is not "absent": the caller
|
|
147
|
+
* fails closed on it the way it already does — this answers only "does a layout exist".
|
|
148
|
+
*/
|
|
149
|
+
function noneContradiction(none, defaultDirs) {
|
|
150
|
+
if (!none || !defaultDirs || !defaultDirs.length) return null;
|
|
151
|
+
const dirs = defaultDirs.slice(0, 3).join(', ') + (defaultDirs.length > 3 ? ` (+${defaultDirs.length - 3} more)` : '');
|
|
152
|
+
return `the repo declares \`migrations: none\` (${none.reason}) but ${dirs} exists at the commit — a repo that can have migrations is never waved through: remove the \`none:\` block (the default layout is read without it), or remove the directory`;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** The default-layout directories in a `git ls-tree -r -d --name-only` listing (#670, #672), outermost match per path. */
|
|
156
|
+
function defaultLayoutDirs(dirs) {
|
|
157
|
+
const out = [];
|
|
158
|
+
for (const d of dirs || []) {
|
|
159
|
+
if (!d) continue;
|
|
160
|
+
const dd = `${d}/`;
|
|
161
|
+
for (const def of DEFAULT_MIGRATION_PATHS) {
|
|
162
|
+
if ((dd === def || dd.endsWith(`/${def}`)) && !out.includes(dd)) out.push(dd);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
return out;
|
|
113
166
|
}
|
|
114
167
|
|
|
115
168
|
/** Union of several docs' declared prefixes (trunk's + the branch's) — the gate sees every one. */
|
|
@@ -119,6 +172,32 @@ function unionPaths(...docs) {
|
|
|
119
172
|
return out;
|
|
120
173
|
}
|
|
121
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
|
+
|
|
122
201
|
/** Is `file` (repo-relative, `/`-separated) a migration under the defaults or a declared prefix? */
|
|
123
202
|
function isMigrationPath(file, declared) {
|
|
124
203
|
const f = String(file || '');
|
|
@@ -162,4 +241,5 @@ function undeclaredMigrationDirs(files, declared) {
|
|
|
162
241
|
|
|
163
242
|
module.exports = {
|
|
164
243
|
DEFAULT_MIGRATION_PATHS, parseMigrationPaths, unionPaths, isMigrationPath, isDeclaredFile, undeclaredMigrationDirs,
|
|
244
|
+
noneContradiction, defaultLayoutDirs, declaredPresence, missingNote,
|
|
165
245
|
};
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -925,9 +925,28 @@ function laravelDestructive(up, addedBefore) {
|
|
|
925
925
|
* is destructive (a destructive read file is still ✗).
|
|
926
926
|
* `layout` = does `database/migrations/` or `prisma/migrations/` exist in the tree at the candidate:
|
|
927
927
|
* true / false / null (the tree could not be read — never "absent"). Undefined = a caller that does
|
|
928
|
-
* not measure it, read as today: present.
|
|
928
|
+
* not measure it, read as today: present. `none` (#672) = the candidate's `migrations: none` block
|
|
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.
|
|
929
937
|
*/
|
|
930
|
-
function schemaVerdict(changes, since, declared, layout) {
|
|
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) {
|
|
946
|
+
// #672: the candidate's `migrations: none` block. Contradicted by a default layout → refused on every
|
|
947
|
+
// cut, whatever changed; otherwise, with nothing changed, "not checked" naming the declaration —
|
|
948
|
+
// never a ✓ (nothing was read), never the "declare a layout" advice (the repo already answered).
|
|
949
|
+
if (none && 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']) };
|
|
931
950
|
const inPaths = (changes || []).filter((c) => isMigrationPath(c.path, declared));
|
|
932
951
|
// #673: a declared schema FILE (an inline schema the server applies itself) is read by the lines
|
|
933
952
|
// its change added — never "unread", and an edit is never "an existing migration was rewritten".
|
|
@@ -942,13 +961,19 @@ function schemaVerdict(changes, since, declared, layout) {
|
|
|
942
961
|
const unread = (declared && declared.length)
|
|
943
962
|
? history.filter((c) => !/\.(php|sql)$/.test(c.path) && !migrationPaths.isMigrationPath(c.path, []))
|
|
944
963
|
: [];
|
|
945
|
-
|
|
946
|
-
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;
|
|
947
968
|
const notChecked = (why) => ({ ok: true, checked: false, detail: `not checked — ${why}` });
|
|
948
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(', ')}`;
|
|
949
|
-
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
|
|
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)';
|
|
950
971
|
if (!migrations.length && !schemaFiles.length) {
|
|
951
972
|
if (unread.length) return notChecked(unreadWhy());
|
|
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
|
+
}
|
|
952
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}`);
|
|
953
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}`);
|
|
954
979
|
return { ok: true, detail: `no migration file changed since ${since} (${scope})` };
|
|
@@ -61,6 +61,7 @@
|
|
|
61
61
|
*/
|
|
62
62
|
|
|
63
63
|
const releaseTag = require('./release-tag');
|
|
64
|
+
const migrationPaths = require('./migration-paths');
|
|
64
65
|
|
|
65
66
|
// The tracking marker and the event marker are wire format: codec/release.js (#498, epic #496),
|
|
66
67
|
// re-exported below under the names this module always had. VERSION_RE is the codec's, so a
|
|
@@ -564,17 +565,39 @@ function regressionVerdict(edges, { periodStart }) {
|
|
|
564
565
|
* true = a `migrations:` prefix is declared or a default layout (Laravel database/migrations/,
|
|
565
566
|
* Prisma prisma/migrations/) exists in the tree; false = neither, so an empty `paths` is "nothing
|
|
566
567
|
* read", not "nothing changed"; null/absent = the tree could not be read. An empty `paths` passes
|
|
567
|
-
* only with a layout
|
|
568
|
+
* only with a layout — or (#672) with `none`: the candidate's committed `migrations: none` block
|
|
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
|
+
* (`layout` true) the declaration is a contradiction and the gate refuses, migrations changed or not:
|
|
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.
|
|
576
|
+
* Returns { ok, detail } (+ unread: true when something could not be read).
|
|
568
577
|
*/
|
|
569
|
-
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 }) {
|
|
570
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' };
|
|
586
|
+
if (none) {
|
|
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>)` };
|
|
588
|
+
if (layout === false && !paths.length) return { ok: true, detail: `no schema migrations to read since ${since || 'the first commit'}: the repo declares \`migrations: none\` (${none.reason}), and no Laravel or Prisma migrations directory exists at the candidate` };
|
|
589
|
+
}
|
|
571
590
|
if (!paths.length) {
|
|
572
591
|
// #671: fail closed where nothing could have been seen — an automatically deployed final never
|
|
573
592
|
// reads "nothing read" as "nothing changed". The way out is named in the detail, never implied —
|
|
574
593
|
// route-neutral: release finalize prints its own human command, and route deploy-tag-fast has none.
|
|
575
594
|
// #673: a schema applied inline by the server's own code is declarable too — as the FILE — and the
|
|
576
595
|
// detail names the grant command that clears its next change, so no one reaches for a raw tag.
|
|
577
|
-
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>).
|
|
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
|
+
}
|
|
578
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}` };
|
|
579
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}` };
|
|
580
603
|
return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
|