@bettercms-ai/convert 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @bettercms-ai/convert
 
+## 0.7.0
+
+### Minor Changes
+
+- e8b5b1c: Convert the shapes real template sites are made of: data literals rendered through `.map`, headings whose copy is one text node of a mixed element, and images imported from `src/assets`. Root-level `.md` files are no longer read as templates, and a located-but-unplaced path now carries a reason that is true (`IN_EXPRESSION`, or `NOT_IN_SOURCE` with the file named).
+
+  New helper exports `bcmsRowsAs` and `bcmsImage` (helper v5), and two new pending reasons: `REPEATER_AMBIGUOUS` and `IMAGE_ASSET_UNRESOLVED`.
+
+## 0.6.0
+
+### Minor Changes
+
+- 5ad31fd: Astro SSR draft recipe now names `@astrojs/node` standalone, the auto-injected draft routes, and `loadPage` + `loadComponents`.
+
 ## 0.5.0
 
 ### Minor Changes
@@ -97,7 +111,7 @@ reject the checkout, which is what broke the migrator image on #616.
   has; a `bcmsField` the file demonstrably builds from our helper is left alone and only its
   bindings are wrapped; anything else is `SECTION_UNMIGRATABLE`.
 
-  🔴 A NAME IS NOT A PROVENANCE. Reusing anything *called* `bcmsFields` trusted an import from
+  🔴 A NAME IS NOT A PROVENANCE. Reusing anything _called_ `bcmsFields` trusted an import from
   any module at all — `import { bcmsFields } from "./their-utils"` is a different function with
   the same name — and any coexisting `bcmsField` vouched for itself. The specifier must RESOLVE
   to the helper module this package writes (through the project's own aliases), and `bcmsField`
@@ -203,7 +217,7 @@ reject the checkout, which is what broke the migrator image on #616.
   catch, reached through the check itself. Two shapes are provable: a string literal and NOTHING
   else, and a template literal whose every interpolation is an INDEX (`[${i}]`, what a repeater
   writes, which cannot change the prefix). Everything else — `{computedPath}`, `{"a" + x}`,
-  `` {`${prefix}.title`} `` — is opaque, and opaque is `PROP_MAP_INCONSISTENT`.
+  ``{`${prefix}.title`}`` — is opaque, and opaque is `PROP_MAP_INCONSISTENT`.
 
 - `COPY_MODE_MISMATCH` ignores sections the SERVER already refused.
 
@@ -224,7 +238,7 @@ reject the checkout, which is what broke the migrator image on #616.
 
   The in-place call site — `<Hero bind="hero" page={pageSnapshot("home")} />` — is written by
   the codemod from the plan and carries no `blockId` and no `overrides`; it never consults the
-  CMS's blocks at all, which is exactly what makes the inline form componentisation *without*
+  CMS's blocks at all, which is exactly what makes the inline form componentisation _without_
   the page builder. Emitting it for a placement whose copy has MOVED rendered the page's field
   group and declared the page lane for an address that no longer holds anything. The component
   is still written; the page is left as its author wrote it.
@@ -294,7 +308,7 @@ reject the checkout, which is what broke the migrator image on #616.
   the dashboard renders. The committed helper needed nothing: `bcmsRows` already passes a
   nested array through untouched and `bcmsSection` hands a section its group whole.
 
-  The bindings are `` data-bcms-field={`cards[${i}].items[${j}].label`} `` and the shape is
+  The bindings are ``data-bcms-field={`cards[${i}].items[${j}].label`}`` and the shape is
   `cards[*].items[*].label`; the loop now REPORTS the bindings it wrote, both loop variables
   included, instead of the caller re-deriving a literal the file does not contain. ONE level
   of nesting — what the plan mints and what the component prop validator accepts — so a leaf

package/README.md

@@ -58,10 +58,52 @@ tolerant pass that will only place a literal occurring exactly once between a `>
 that, an injected `llmFallback` whose output is accepted only if it re-parses and declares exactly
 the paths that were asked for. The CLI injects none — the agent running it is tier 3.
 
-**Everything it will not do has a name.** `AMBIGUOUS_LITERAL` when two different paths share a
-sentence and position cannot separate them (both are skipped; the rest of the file still converts),
-`SUBSTRING_ONLY`, `IN_SCRIPT_OR_COMMENT`, `KIND_MISMATCH`, `NOT_IN_SOURCE`, `PARSE_ERROR` — and the
-receipt's arithmetic is checked, not hoped for:
+**A prose file is a template only where a framework renders one.** `.md`, `.mdx`, `.njk`, `.hbs`,
+`.ejs`, `.liquid`, `.erb` and `.twig` are opened under a directory named `pages`, `content`, `src`,
+`app`, `routes`, `layouts`, `components`, `templates`, `views`, `_includes` or `_layouts` — and
+never at the repository root or under `docs/`. A README quoting the hero line is documentation
+ABOUT the site, and because a path counts as rewritten only when every located occurrence was, one
+of them pended 176 of 735 paths on a real repository with a reason naming a file nobody would ever
+want bound.
+
+**A scalar module literal is converted too.** `const tagline = "…"` rendered as `{tagline}` becomes
+`const tagline = bcms(page, "<path>", "…")`, with the declaration on the element that renders it —
+a literal path, because there is no index to template. Refused as `IN_EXPRESSION` when the
+identifier is rendered more than once, used in an attribute as well, or transformed on the way:
+moving the declaration to a CMS read changes the value everywhere that identifier is used.
+
+**Copy that lives in a data literal is converted too.** `deriveSchema` reads the BUILT page, so
+four cards arrive as `cards[0..3]`; the repository renders ONE element from a frontmatter (astro)
+or module-scope (jsx/tsx) array through `.map`. The declaration becomes
+
+```js
+const features = bcmsRowsAs(bcmsHome, "cards", [ …the original array, verbatim… ],
+                            { title: "h3-field", body: "p-field" });
+```
+
+— the rows come from the CMS and are renamed onto the template's OWN property names, so
+`feature.tone`, `feature.link` and every other property the brief never heard of keep rendering
+(`bcmsRowsAs` merges each CMS row over the row the template shipped with, and a row an editor adds
+inherits row 0's styling). Each row element then declares
+`` data-bcms-field={`cards[${i}].<leaf>`} ``, and the callback gains an index parameter if it had
+none. An imported data module stays `IN_DATA_FILE`.
+
+**An image is bound through its import, not through its url.** An image's `original` is the name
+the bundler minted (`/_astro/hero.do77EGgx_ZNfVA8.jpg`) — it exists in no file, and the asset
+itself is not a source candidate, so a text search can never find it. What survives the build is
+the BASE NAME, and the page says it itself: `import hero from "../assets/hero.jpg"`. The element
+rendering that binding — `<img>`, `<source>`, `<video poster>`, or `<Image>`/`<Picture>` from
+`astro:assets`, which forward unknown props to the `<img>` they render — gets
+`src={bcmsImage(page, "<path>", hero)}` and the declaration beside it.
+
+**Everything it will not do has a name, and the name is TRUE.** `AMBIGUOUS_LITERAL` when two
+different paths share a sentence and position cannot separate them (both are skipped; the rest of
+the file still converts), `SUBSTRING_ONLY`, `IN_SCRIPT_OR_COMMENT`, `KIND_MISMATCH`,
+`REPEATER_AMBIGUOUS` (one array declaration, two loops over it — the row has two homes),
+`IMAGE_ASSET_UNRESOLVED`, `PARSE_ERROR`. `NOT_IN_SOURCE` is reserved for what it says: a path
+`locate` found in a file is `IN_EXPRESSION` when it sits in the module region or an expression
+node, and where `NOT_IN_SOURCE` is still the answer the row names the file it was found in. And
+the receipt's arithmetic is checked, not hoped for:
 
 ```
 paths.declared === paths.rewritten + paths.alreadyDeclared + paths.pending.length
@@ -428,6 +470,19 @@ and removing them would mean editing statements no section asked about.
 
 ## Not here yet
 
+An array of PRIMITIVES — `const items = ["a", "b", "c"]`, or of tuples — whose elements the brief
+gave a separate NON-indexed path each (`li-field`, `li-rtl`, …) rather than one repeater group.
+There is no group to key and no constant to rewrite, so those stay `IN_EXPRESSION`; what would fix
+them is the derive lane minting the group, not a third shape here. Svelte and vue data literals are
+not converted either — both lanes are written against the two dialects that keep their module and
+their markup in one file with an AST this package already holds.
+
+SHARED CHROME the brief still calls page copy. A header rendered by one component that nine routes
+each declare a `nav[0].label` for is nine targets on one element, and there is no honest binding: a
+read names ONE route's snapshot. That is `promoteSharedChrome`'s job on the derive side — once the
+field is `scope: "layout"` the codemod collapses the nine to one identity and binds it. Until then
+those paths are `AMBIGUOUS_LITERAL`, which is true.
+
 `promoteSharedChrome`, and prop drilling through a svelte or vue component (both parse, and both
 bind their own copy; only `findPropTargets` is jsx/astro-only, so a drilled prop there is
 `PROP_TARGET_NOT_FOUND` rather than a wrong edit).