@bettercms-ai/convert 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @bettercms-ai/convert
 
+## 0.16.1
+
+### Patch Changes
+
+- Fix `--forms` tie-breaking. 0.16.0's second tie-break rule ("the form posting nothing beyond its
+  fields wins") could bind a look-alike form — for example a "forgot password" dialog posting only
+  `email` — to the newsletter without reporting it. 0.16.1 removes that rule: such cases stay
+  `FORM_AMBIGUOUS` until you name the file with `--pin "<form>=<file>"`. When the remaining rule
+  (the form posting more of a `<form>`'s fields wins) decides a tie, the receipt now carries a `notes`
+  line naming the file and the rival that lost it. `--pin` is also stricter: an empty value or a
+  repeated pin for the same form is refused, `--pin` cannot be combined with `--componentize`, and
+  two forms pinned to one file both wire.
+
+## 0.16.0
+
+### Minor Changes
+
+- 17aaccb: `--forms` breaks the ties that left ScrewFast's two forms `FORM_AMBIGUOUS`: a `<form>` two CMS forms both cover goes to the one it posts more fields of (a contact form is not the newsletter because it also posts `email`), and among several `<form>`s covering one CMS form the one posting nothing beyond its fields wins. For the tie nothing can break — two email-only forms, a footer newsletter and a "forgot password" dialog — the new `--pin "<form>=<file>"` names the file; the pending message says so.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -630,6 +630,13 @@ a reason — `FORM_NOT_IN_SOURCE`, `FORM_AMBIGUOUS`, `FIELD_UNMATCHED`, `ACTION_
 leads into another form's inbox, silently, forever. A `<form>` that already carries
 `data-bcms-form` is `alreadyWired` and is left alone, so a second run is a no-op.
 
+Two `<form>`s that both post exactly a form's fields are `FORM_AMBIGUOUS`, and no rule can break
+that tie: `--pin "<form>=<file>"` (repeatable, form by id or name) names the file, and a pin is
+exclusive only against forms that carry no pin of their own, so two forms living in one file can
+both be pinned to it. **Keep passing a pin on every later run** — a pin is not written into the
+tree, so an unpinned run over the same repository reports that form ambiguous again and its
+receipt stops listing the file it is wired to, even though the markup still is.
+
 `--receipt <file>` writes this run's own receipt (`forms-receipt.json` — a separate file from the
 P2 run's, since the two runs describe different work), and `--strict` exits 2 on any pending form.
 `--forms` and `--componentize` are separate runs; doing both in one command is refused.

package/dist/cli.js

@@ -6483,7 +6483,7 @@ function wire(source, candidate, form) {
     source.appendLeft(el.inner.end - tail.length, `${tail || "\n"}${messageFor(dialect)}`);
   }
 }
-async function wireForms(briefIn, sources) {
+async function wireForms(briefIn, sources, options_ = {}) {
   const brief = readBrief(briefIn);
   const forms = brief.forms ?? [];
   const candidates = [];
@@ -6521,7 +6521,34 @@ async function wireForms(briefIn, sources) {
   }
   const holds = (c, f) => f.fields.filter((field) => c.controls.has(field.key)).length;
   const covers2 = (c, f) => f.fields.length > 0 && holds(c, f) === f.fields.length;
+  const samePath = (a, b) => a.replace(/\\/g, "/").replace(/^\.\//, "") === b.replace(/\\/g, "/").replace(/^\.\//, "");
   const options = new Map(forms.map((f) => [f.id, candidates.filter((c) => covers2(c, f))]));
+  const pinned = /* @__PURE__ */ new Map();
+  for (const [ref, file] of Object.entries(options_.pins ?? {})) {
+    const form = forms.find((f) => f.id === ref || f.name === ref);
+    if (!form) throw new Error(`--pin ${ref}: the brief lists no form with that id or name.`);
+    if (file.trim() === "") throw new Error(`--pin ${ref}: no file named. Give "<form>=<file>".`);
+    pinned.set(form.id, file);
+  }
+  for (const [id, file] of pinned) {
+    options.set(id, options.get(id).filter((c) => samePath(c.file, file)));
+    for (const other of forms) {
+      const its = pinned.get(other.id);
+      if (other.id === id || its !== void 0 && samePath(its, file)) continue;
+      options.set(other.id, options.get(other.id).filter((c) => !samePath(c.file, file)));
+    }
+  }
+  const beat = /* @__PURE__ */ new Map();
+  for (const c of candidates) {
+    const claimants = forms.filter((f) => options.get(f.id).includes(c));
+    if (claimants.length < 2) continue;
+    const top = Math.max(...claimants.map((f) => holds(c, f)));
+    const winners = claimants.filter((f) => holds(c, f) === top);
+    if (winners.length !== 1) continue;
+    const rivals = claimants.filter((f) => f !== winners[0]);
+    for (const f of rivals) options.set(f.id, options.get(f.id).filter((x) => x !== c));
+    beat.set(c, { winner: winners[0], rivals });
+  }
   const wanted = /* @__PURE__ */ new Map();
   for (const list of options.values()) for (const c of list) wanted.set(c, (wanted.get(c) ?? 0) + 1);
   const matched = [];
@@ -6532,7 +6559,12 @@ async function wireForms(briefIn, sources) {
   for (const form of forms) {
     const list = options.get(form.id) ?? [];
     if (list.length > 1) {
-      pend2(form, "FORM_AMBIGUOUS", void 0, `${list.length} forms post every field of "${form.name}": ${list.map((c) => c.file).join(", ")}.`);
+      pend2(
+        form,
+        "FORM_AMBIGUOUS",
+        void 0,
+        `${list.length} forms post every field of "${form.name}": ${list.map((c) => c.file).join(", ")}.${pinned.has(form.id) ? " The pin names that file, and it holds more than one." : ` Name the right one with --pin "${form.name}=<file>".`}`
+      );
       continue;
     }
     if (list.length === 1 && (wanted.get(list[0]) ?? 0) > 1) {
@@ -6541,7 +6573,13 @@ async function wireForms(briefIn, sources) {
     }
     if (list.length === 0) {
       const [best] = candidates.map((c) => ({ c, n: holds(c, form) })).filter((x) => x.n > 0).sort((a, b) => b.n - a.n);
-      if (best) {
+      const pin = pinned.get(form.id);
+      if (pin) {
+        pend2(form, "FORM_NOT_IN_SOURCE", pin, `the pinned file has no <form> posting ${form.fields.map((f) => f.key).join(", ")}.`);
+      } else if (best && best.n === form.fields.length) {
+        const owner = forms.find((f) => f !== form && options.get(f.id).includes(best.c));
+        pend2(form, "FORM_NOT_IN_SOURCE", best.c.file, `the only <form> posting ${form.fields.map((f) => f.key).join(", ")} is "${owner?.name ?? "another form"}"'s.`);
+      } else if (best) {
         const missing = form.fields.filter((f) => !best.c.controls.has(f.key)).map((f) => f.key);
         pend2(form, "FIELD_UNMATCHED", best.c.file, `no control posts ${missing.join(", ")} in the <form> that posts its other fields.`);
       } else if (unreadable[0]) {
@@ -6589,6 +6627,14 @@ ${indent}${scriptFor(last.candidate.dialect)}`);
     files.push({ path, operation: "modify", content: source.toString() });
   }
   const notes = onSite.filter(({ form }) => form.status === "draft").map(({ form }) => `publish form ${form.name} in the Forms tab \u2014 a draft form rejects every submission with 403.`);
+  for (const { form, candidate } of matched) {
+    const tie = beat.get(candidate);
+    if (tie?.winner === form) {
+      notes.push(
+        `form ${form.name}: ${candidate.file} posts every field of ${tie.rivals.map((f) => f.name).join(", ")} too, and more of ${form.name}'s, so it went to ${form.name} \u2014 name the file yourself with --pin "<form>=<file>" if that is wrong.`
+      );
+    }
+  }
   for (const { form, candidate } of matched) {
     const keys = form.fields.filter((field) => candidate.foreign.has(candidate.controls.get(field.key))).map((field) => field.key);
     if (keys.length > 0) {
@@ -9689,7 +9735,7 @@ function emitStubs2(dialects, slugs, contents, out) {
 // package.json
 var package_default = {
   name: "@bettercms-ai/convert",
-  version: "0.15.0",
+  version: "0.16.1",
   type: "module",
   description: "Deterministic codemod that turns an imported site's text-matched bindings into declared ones \u2014 parser offsets in, one magic-string pass out, plus a receipt of everything it could not do.",
   bin: {
@@ -9750,6 +9796,7 @@ function parseArgs(argv) {
     brief: void 0,
     componentize: false,
     forms: false,
+    pins: {},
     xray: void 0,
     plan: void 0,
     copy: "bind",
@@ -9766,7 +9813,16 @@ function parseArgs(argv) {
     if (arg === "--brief") args.brief = argv[++i];
     else if (arg === "--componentize") args.componentize = true;
     else if (arg === "--forms") args.forms = true;
-    else if (arg === "--xray") args.xray = argv[++i];
+    else if (arg === "--pin") {
+      const raw = argv[++i] ?? "";
+      const at = raw.indexOf("=");
+      if (at < 1 || at === raw.length - 1) {
+        throw new CliError(`--pin takes <form>=<file>, e.g. --pin "Newsletter=src/components/FooterSection.astro". See --help.`);
+      }
+      const form = raw.slice(0, at);
+      if (Object.hasOwn(args.pins, form)) throw new CliError(`--pin ${form} twice: give one file. See --help.`);
+      args.pins[form] = raw.slice(at + 1);
+    } else if (arg === "--xray") args.xray = argv[++i];
     else if (arg === "--plan") args.plan = argv[++i];
     else if (arg === "--copy") {
       const mode = argv[++i];
@@ -9802,6 +9858,9 @@ var HELP = `bettercms-convert ${VERSION}
                        endpoint, the id, a marker per field and the submit script. A form
                        the brief lists as a DRAFT is wired and receipted: publish it in the
                        Forms tab, or it rejects every submission with a 403.
+  --pin <form>=<file>  With --forms: the file a form's <form> is in, when the run reports
+                       FORM_AMBIGUOUS (two files post exactly its fields). Form by id or
+                       name. Repeatable.
   --xray <dist-dir>    Measure a LOCAL build instead of converting: how much of each page's
                        visible copy no binding owns, and the biggest buckets of it. Run it
                        after a build to see what the next conversion still has to reach,
@@ -9984,6 +10043,9 @@ async function main() {
   if (args.forms && args.componentize) {
     throw new CliError("--forms and --componentize are separate runs. Do one, then the other. See --help.");
   }
+  if (Object.keys(args.pins).length > 0 && !args.forms) {
+    throw new CliError("--pin only means something with --forms. See --help.");
+  }
   const root = resolve(args.root);
   const brief = JSON.parse(await readFile(resolve(args.brief), "utf-8"));
   if (!Array.isArray(brief.pages)) {
@@ -10025,7 +10087,7 @@ async function main() {
     return args.strict && receipt2.sections.pending.length > 0 ? 2 : 0;
   }
   if (args.forms) {
-    const { files: files2, receipt: receipt2 } = await wireForms(brief, sources);
+    const { files: files2, receipt: receipt2 } = await wireForms(brief, sources, { pins: args.pins });
     await written(files2);
     await saveReceipt(receipt2);
     reportForms(files2, receipt2, args.dryRun);