@biffo/cli 0.148.2 → 0.150.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) {
@@ -350,10 +378,11 @@ var coreDiffCommand = new Command("diff").description(
 ).option("--cwd <path>", "Instance repo root to inspect (defaults to the current directory)").option(
   "--template <path>",
   "Path to a biffo-template checkout to compare against (defaults to the template this CLI ships with)"
-).action(async (options) => {
+).option("--json", "Emit the classification as JSON on stdout instead of the human report").action(async (options) => {
   const cwd = options.cwd ? resolve(options.cwd) : process.cwd();
   const runOptions = { cwd };
   if (options.template) runOptions.templateRoot = resolve(options.template);
+  if (options.json) runOptions.json = true;
   try {
     await runCoreDiff(runOptions);
   } catch (err) {
@@ -368,6 +397,20 @@ async function runCoreDiff(options) {
   const instanceVersion = readInstanceCoreVersion(options.cwd);
   const diff = computeCoreDiff(templateRoot, options.cwd, manifest);
   const total = diff.added.length + diff.removed.length + diff.modified.length;
+  if (options.json) {
+    const payload = {
+      schemaVersion: 1,
+      instanceCore: instanceVersion ?? null,
+      templateCore: templateVersion,
+      modified: diff.modified,
+      added: diff.added,
+      removed: diff.removed,
+      instanceOnly: diff.instanceOnly,
+      unchanged: diff.unchanged
+    };
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
   console.log(chalk2.bold("\n  Biffo core diff\n"));
   console.log(`  instance core:  ${instanceVersion ?? chalk2.dim("(unrecorded)")}`);
   console.log(`  template core:  ${templateVersion}
@@ -1521,8 +1564,19 @@ function planMigrationCarry(options) {
   const entries = [];
   const skipped = [];
   const recognised = [];
+  const declinedIndex = new Map((options.declined ?? []).map((d) => [d.file, d]));
+  const declined = [];
   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);
@@ -1569,7 +1623,9 @@ 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 };
 }
 function indexInstanceMigrations(instance) {
   const index = {
@@ -2437,7 +2493,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.");
@@ -2674,6 +2734,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"})`

package/package.json

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