@biffo/cli 0.149.0 → 0.151.0

package/dist/index.js

@@ -25,8 +25,19 @@ import { dirname, join, parse as parsePath } from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod";
 var SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+var DeclinedMigrationSchema = z.object({
+  /** The *template's* filename for the migration, e.g. `0010_add_organizations.py`. */
+  file: z.string({ required_error: "file is required \u2014 it must name a template migration" }).min(1, "file is required \u2014 it must name a template migration"),
+  // `required_error` as well as `min(1)`: zod reports a bare "Required" for an
+  // absent key, which would lose the guidance in the exact case most likely to
+  // occur — someone adding an entry and omitting the field.
+  reason: z.string({ required_error: "reason is required \u2014 a decline nobody can review is drift" }).min(1, "reason is required \u2014 a decline nobody can review is drift"),
+  /** Optional `owner/repo#123` recording where the decline is being resolved. */
+  upstream: z.string().optional()
+});
 var CoreManifestSchema = z.object({
-  version: z.string().regex(SEMVER, "must be a semver, e.g. 1.2.3")
+  version: z.string().regex(SEMVER, "must be a semver, e.g. 1.2.3"),
+  declinedMigrations: z.array(DeclinedMigrationSchema).optional()
 });
 var CORE_VERSION_FILE = "core.version";
 var INSTANCE_CORE_FILE = "biffo.core.json";
@@ -112,6 +123,9 @@ function readInstanceCoreVersion(cwd) {
     const inherited = join(cwd, CORE_VERSION_FILE);
     return existsSync(inherited) ? readCoreVersionFile(inherited) : null;
   }
+  return parseInstanceCoreManifest(path).validated.version;
+}
+function parseInstanceCoreManifest(path) {
   let parsed;
   try {
     parsed = JSON.parse(readFileSync(path, "utf8"));
@@ -123,7 +137,15 @@ function readInstanceCoreVersion(cwd) {
     const detail = result.error.issues[0]?.message ?? "unexpected shape";
     throw new Error(`${INSTANCE_CORE_FILE} is invalid: ${detail}`);
   }
-  return result.data.version;
+  return {
+    validated: result.data,
+    raw: parsed ?? {}
+  };
+}
+function readDeclinedMigrations(cwd) {
+  const path = join(cwd, INSTANCE_CORE_FILE);
+  if (!existsSync(path)) return [];
+  return parseInstanceCoreManifest(path).validated.declinedMigrations ?? [];
 }
 function planCoreVersionCleanup(cwd) {
   const path = join(cwd, CORE_VERSION_FILE);
@@ -150,13 +172,19 @@ function coreVersionsEqual(a, b) {
     return false;
   }
 }
-function serializeInstanceCoreVersion(version) {
+function serializeInstanceCoreVersion(version, rest = {}) {
   parseCoreVersion(version);
-  return `${JSON.stringify({ version }, null, 2)}
+  return `${JSON.stringify({ version, ...rest }, null, 2)}
 `;
 }
 function writeInstanceCoreVersion(cwd, version) {
-  writeFileSync(join(cwd, INSTANCE_CORE_FILE), serializeInstanceCoreVersion(version));
+  const path = join(cwd, INSTANCE_CORE_FILE);
+  let rest = {};
+  if (existsSync(path)) {
+    rest = { ...parseInstanceCoreManifest(path).raw };
+    delete rest.version;
+  }
+  writeFileSync(path, serializeInstanceCoreVersion(version, rest));
 }
 function latestCoreVersionFromTags(repo, git = defaultTagRunner, options = {}) {
   if (options.fetch !== false) {
@@ -1536,14 +1564,33 @@ function planMigrationCarry(options) {
   const entries = [];
   const skipped = [];
   const recognised = [];
+  const declinedIndex = new Map((options.declined ?? []).map((d) => [d.file, d]));
+  const declined = [];
+  const divergedBodies = [];
   let head = instanceHead;
   for (const m of chainOrder(template)) {
+    const decline = declinedIndex.get(m.file);
+    if (decline) {
+      declined.push({
+        file: m.file,
+        reason: decline.reason,
+        ...decline.upstream !== void 0 && { upstream: decline.upstream }
+      });
+      continue;
+    }
     const already = alreadyCarried(m, identity, templateBodyCounts);
     if (already) {
       skipped.push(m.file);
       if (already.how !== "filename") {
         recognised.push({ file: m.file, instanceFile: already.instance.file, how: already.how });
       }
+      if (migrationBodyHash(m.content) !== migrationBodyHash(already.instance.content)) {
+        divergedBodies.push({
+          file: m.file,
+          instanceFile: already.instance.file,
+          how: already.how
+        });
+      }
       continue;
     }
     let revision = m.revision;
@@ -1584,7 +1631,33 @@ function planMigrationCarry(options) {
     ],
     `${MIGRATIONS_VERSIONS_DIR} (after carry)`
   );
-  return { entries, instanceHead, skipped, recognised };
+  const templateFiles = new Set(template.map((m) => m.file));
+  const staleDeclines = [...declinedIndex.keys()].filter((f) => !templateFiles.has(f));
+  return {
+    entries,
+    instanceHead,
+    skipped,
+    recognised,
+    declined,
+    staleDeclines,
+    divergedBodies
+  };
+}
+var TEST_PATH_RE = /(^|\/)tests?\/.*\btest_[^/]*\.py$/;
+function findMigrationTestPairings(changes, divergedBodies) {
+  if (divergedBodies.length === 0) return [];
+  const pairings = [];
+  for (const change of changes) {
+    if (!TEST_PATH_RE.test(change.path)) continue;
+    const content = change.content;
+    if (content === void 0) continue;
+    for (const d of divergedBodies) {
+      if (content.includes(d.file)) {
+        pairings.push({ testPath: change.path, migration: d.file, instanceFile: d.instanceFile });
+      }
+    }
+  }
+  return pairings;
 }
 function indexInstanceMigrations(instance) {
   const index = {
@@ -2452,7 +2525,11 @@ async function runCoreUpgradeResolved(options, deps, cleanups) {
   console.log(`  merge base:      ${fromVersion}`);
   console.log(`  target:          ${toVersion}
 `);
-  const migrations = planMigrationCarry({ templateDir: theirsDir, instanceDir: options.cwd });
+  const migrations = planMigrationCarry({
+    templateDir: theirsDir,
+    instanceDir: options.cwd,
+    declined: readDeclinedMigrations(options.cwd)
+  });
   const coreVersionCleanup = planCoreVersionCleanup(options.cwd);
   if (plan.changes.length === 0 && migrations.entries.length === 0) {
     log.success("Nothing to upgrade \u2014 the instance already matches the target for all core files.");
@@ -2468,6 +2545,10 @@ async function runCoreUpgradeResolved(options, deps, cleanups) {
   printBreakingChanges(breaking, options.apply === true);
   printPlan(plan);
   printMigrationCarry(migrations);
+  printMigrationBodyDrift(
+    migrations,
+    findMigrationTestPairings(plan.changes, migrations.divergedBodies)
+  );
   printCoreVersionCleanup(coreVersionCleanup, options.apply === true);
   warnStaleFirstPartyCopies(options.cwd);
   console.log(
@@ -2689,6 +2770,22 @@ function printMigrationCarry(migrations) {
       `  ${chalk4.dim("already carried".padEnd(15))} ${r.file} ` + chalk4.dim(`\u2192 this instance calls it ${r.instanceFile} (matched by ${r.how})`)
     );
   }
+  for (const d of migrations.declined) {
+    const upstream = d.upstream ? chalk4.dim(` [${d.upstream}]`) : "";
+    console.log(
+      `  ${chalk4.yellow("declined".padEnd(15))} ${d.file} ` + chalk4.dim(`\u2192 skipped per biffo.core.json: ${d.reason}`) + upstream
+    );
+  }
+  for (const f of migrations.staleDeclines) {
+    console.log(
+      `  ${chalk4.yellow("stale decline".padEnd(15))} ${f} ` + chalk4.dim("\u2192 declined in biffo.core.json, but the target template has no such migration.")
+    );
+    console.log(
+      chalk4.dim(
+        "                  Either the filename is wrong (declining nothing) or the decline\n                  has outlived its cause and should be deleted."
+      )
+    );
+  }
   for (const e of migrations.entries) {
     const suffix = e.reissuedFrom ? chalk4.dim(
       ` (revision ${e.revision}, re-issued from ${e.reissuedFrom}; revises ${e.downRevision ?? "base"})`
@@ -2696,6 +2793,39 @@ function printMigrationCarry(migrations) {
     console.log(`  ${chalk4.green("migration".padEnd(15))} ${e.path}${suffix}`);
   }
 }
+function printMigrationBodyDrift(migrations, pairings) {
+  if (migrations.divergedBodies.length === 0) return;
+  console.log();
+  for (const d of migrations.divergedBodies) {
+    const alias = d.instanceFile === d.file ? "" : chalk4.dim(` (this instance calls it ${d.instanceFile})`);
+    console.log(
+      `  ${chalk4.yellow("body drift".padEnd(15))} ${d.file}${alias}
+` + chalk4.dim(
+        "                  The template has changed this migration since you carried it.\n                  An applied migration cannot be re-run, so the carry left yours\n                  alone and this change will NOT reach you."
+      )
+    );
+  }
+  if (pairings.length === 0) {
+    console.log(
+      chalk4.dim(
+        "\n  No arriving test asserts the new body, so this upgrade should still go green.\n  It stays a convergence gap: fresh environments get the new body, you keep the old."
+      )
+    );
+    return;
+  }
+  console.log(
+    `
+  ${chalk4.red.bold("This upgrade will not go green.")} ${pairings.length} arriving test(s) assert a migration body you will not receive:`
+  );
+  for (const p of pairings) {
+    console.log(`    ${chalk4.red(p.testPath)} ${chalk4.dim(`\u2192 asserts ${p.migration}`)}`);
+  }
+  console.log(
+    chalk4.dim(
+      "\n  Resolve before merging, by one of:\n    - port the migration body change into your copy by hand, keeping its\n      `# biffo:carried-from:` marker \u2014 safe only if re-stating the DDL is a\n      no-op against your already-migrated database;\n    - drop the arriving test from this PR and raise it upstream, if the\n      property it asserts cannot hold here;\n    - ask upstream to ship the change as a follow-on migration instead, which\n      is the only option that actually converges an applied chain.\n"
+    )
+  );
+}
 function printCoreVersionCleanup(cleanup, applying) {
   if (cleanup === null) return;
   if (cleanup.action === "delete") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.149.0",
+  "version": "0.151.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",