@bettercms-ai/convert 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @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

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).