@bettercms-ai/convert 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @bettercms-ai/convert
 
+## 0.14.0
+
+### Minor Changes
+
+- df570ef: Receipt and brief shapes a consumer reads:
+  - `BriefPath.kind` is typed `BindingKind` rather than `BindingKind | ""` — the brief always names a kind, and the empty case only forced callers to handle a value it never sends.
+  - New `PendingReason` `"DOCUMENT_DECLARE_ONLY"`: a `document` path is never located and never rewritten, because its `original` is only the body's FIRST block and declaring the paragraph that renders it is what publish refuses. The row's fix names the wrapper to declare instead.
+  - `PendingFix.kind` (`"document" | "richtext"`, optional) accompanies a `declare-richtext` action to say WHICH container is meant.
+
 ## 0.13.0
 
 ### Minor Changes

package/dist/cli.js

@@ -2562,7 +2562,11 @@ var IMAGE_SOURCES = {
   video: ["poster"]
 };
 var isImageSource = (site) => site.where === "attr" && (IMAGE_SOURCES[site.tag.toLowerCase()] ?? []).includes(site.attr ?? "");
-var ownsSubtree = (kind, site, inline) => kind === "richtext" && (inline === true ? !site.nonHtml : !(site.mixed && site.textRange !== null));
+var ownsSubtree = (kind, site, inline) => (
+  // A `document` is the same claim at article scale: the element renders EVERY block of the Body,
+  // so its children come from the stored value and nothing else may be bound inside it.
+  (kind === "richtext" || kind === "document") && (inline === true ? !site.nonHtml : !(site.mixed && site.textRange !== null))
+);
 var norm = (value) => decodeEntities(value.normalize("NFC")).replace(/\s+/g, " ").trim();
 var BCMS_ATTRS = [
   "data-bcms-field",
@@ -5363,7 +5367,7 @@ function actionFor(reason, input, file, inData) {
   return chosen;
 }
 function reasonAction(reason, input, file, inData) {
-  const richtext = input.kind === "richtext" || input.inline === true;
+  const richtext = input.kind === "richtext" || input.kind === "document" || input.inline === true;
   switch (reason) {
     case "AMBIGUOUS_LITERAL":
       if (input.routes > 1) {
@@ -5414,6 +5418,11 @@ function reasonAction(reason, input, file, inData) {
       return { action: "wrap-span", why: "Only part of the element's text is this value \u2014 give it its own span." };
     case "SUBTREE_NOT_HTML":
       return { action: "declare-richtext", why: "The value is the element's whole subtree \u2014 bind it as richtext." };
+    case "DOCUMENT_DECLARE_ONLY":
+      return {
+        action: "declare-richtext",
+        why: 'This is a Body: bind the ONE element that renders every block of it \u2014 an article, a main or a div \u2014 with the richtext helper and data-bcms-kind="document". Never the paragraph holding its first block: that is where the whole article would be published.'
+      };
     default:
       return { action: "manual", why: `${reason} \u2014 see the receipt's message for what blocked this path.` };
   }
@@ -5430,7 +5439,10 @@ function fixFor(row, input) {
     ...place.col !== void 0 ? { col: place.col } : {},
     snippet: place.snippet,
     action,
-    ...why ? { why } : {}
+    ...why ? { why } : {},
+    // Only `declare-richtext` carries it, and only to say WHICH container is meant: one element
+    // for a rich-text value, the whole Body's wrapper for a document.
+    ...action === "declare-richtext" && (input.kind === "document" || input.kind === "richtext") ? { kind: input.kind } : {}
   };
 }
 function routeCounts(pending) {
@@ -8771,10 +8783,28 @@ async function convertSources(briefIn, sources, options) {
     }
     pend2(target, miss.reason === "no-original" ? "NO_ORIGINAL" : "NOT_IN_SOURCE");
   }
+  const documents = /* @__PURE__ */ new Set();
+  for (const [key, hit] of locatedByKey) {
+    const target = targets.get(key);
+    if (!target || target.kind !== "document") continue;
+    documents.add(key);
+    const byHand = declaredByHand(target, hit.files);
+    if (byHand !== null) {
+      declaredOnly++;
+      declaredRow(target, false, byHand);
+      continue;
+    }
+    pend2(
+      target,
+      "DOCUMENT_DECLARE_ONLY",
+      hit.files[0],
+      "A Body is bound by declaring the one element that renders every block of it, never the paragraph that happens to hold its first block."
+    );
+  }
   const byFile = /* @__PURE__ */ new Map();
   for (const [key, hit] of locatedByKey) {
     const target = targets.get(key);
-    if (!target) continue;
+    if (!target || documents.has(key)) continue;
     for (const file of hit.files) byFile.set(file, [...byFile.get(file) ?? [], target]);
   }
   const drill = {
@@ -8823,6 +8853,7 @@ async function convertSources(briefIn, sources, options) {
   let rewritten = 0;
   let alreadyDeclared = declaredOnly;
   for (const [key, hit] of locatedByKey) {
+    if (documents.has(key)) continue;
     const target = targets.get(key);
     const outcomes = hit.files.map((file) => results.get(file)?.get(target.key) ?? "NOT_IN_SOURCE");
     const worst = outcomes.find((o) => o !== "rewritten" && o !== "declared");
@@ -9607,7 +9638,7 @@ function emitStubs2(dialects, slugs, contents, out) {
 // package.json
 var package_default = {
   name: "@bettercms-ai/convert",
-  version: "0.13.0",
+  version: "0.14.0",
   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: {