@bettercms-ai/convert 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @bettercms-ai/convert
 
+## 0.8.0
+
+### Minor Changes
+
+- 8a4e961: Bind array literals written inline in the markup, and drill a repeater row's leaf into the
+  component that renders it.
+
+  `{['Offer', 'Structure', 'RTL'].map((item) => <li>…</li>)}` had no lane at all — the list lane
+  searches the module for a NAMED array, and an inline literal has no name — so every one of its
+  items came back `IN_EXPRESSION` with the copy in plain sight. The `]` immediately before the
+  `.map(` is the literal's close, which is what makes it safe without a name: there is exactly one
+  loop over it and nothing else in the file can hold a second reference. A value rendered beside an
+  icon (`<li><span>✓</span>{item}</li>`) gets a `<span>` of its own instead of declaring on the
+  parent, because a publish writing the value over the parent deletes the icon.
+
+  `demos.map((demo) => <DemoCard title={demo.title} />)` refused the whole group with
+  `PROP_TARGET_NOT_FOUND`: the value is rendered in the component's file, not the page's. It now
+  follows the same drill the scalar lane has always used — a row's leaf is that journey with an index
+  in the path. The call site declares one `bcmsBindings={{ title: `cards[${i}].title` }}` per element
+  and the component gets `data-bcms-field={bcmsBindings?.title}`. `{...row}` counts as passing the
+  prop. Every leaf placed or none, as before: a drill that misses refuses the group by its own reason.
+
+  Also: `tsconfig.json` / `jsconfig.json` are now opened by the scan gate. `aliasesFrom` reads them
+  and nothing ever handed it one, so every `paths` alias resolved to nothing and every prop drilled
+  through an `@components/*` import refused with the component sitting right there.
+
+  `bindDataLiterals` is async for this; it is exported, and a caller outside this package has to
+  await it.
+
+- 07f6648: Bind arrays of primitives and tuples rendered through `.map`.
+
+  `const promise = [['Once', 'One message'], …]` iterated as `promise.map(([title, text], i) => …)`
+  is the same shape as a row of objects one rung simpler, and the derive lane describes it as a
+  repeater group all the same. The declaration becomes `bcmsTuples(page, [[…paths…], …], [ …the
+original array, verbatim… ])` — `bcmsList` for a list one wide — and each rendered element carries
+  the same templated `data-bcms-field` a repeater writes, so a second run reads it back and changes
+  nothing. The committed helper is v6; an existing v5 helper upgrades in place.
+
+  The read maps over the path list rather than over the CMS array, so every row's text is editable
+  and the number of rows is still the template's: the receipt adds one `PRIMITIVE_LIST` note per
+  array saying a row added in the CMS does not appear and a deleted one falls back to the template's
+  own copy. A list whose paths are unrelated scalars, one used anywhere but that single `.map` or
+  `export`ed, one rendered inside a larger expression, one whose tuple position changes kind between
+  rows, and one the brief covers only part of are all refused by name.
+
+  On the Shatter acceptance repository this moves 16 paths from `IN_EXPRESSION` to `rewritten`
+  (219 → 235 of 735).
+
+## 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,104 @@ 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 array of PRIMITIVES or TUPLES is converted through its paths, not through its name.** The
+same shape one rung simpler: `const deliverables = ["…", "…", "…"]`, or
+`const faqs = [["q", "a"], …]`, iterated by `.map` with the callback rendering the item (or its
+destructured positions) on one element each. There is no row object to key, so every element's
+path is passed to the read:
+
+```js
+const faqs = bcmsTuples(bcmsLanding, [["faqs[0].dt-field", "faqs[0].dd-field"], …],
+                        [ …the original array, verbatim… ]);
+```
+
+`bcmsList` is the same for a list one wide. Each rendered element declares
+`` data-bcms-field={`faqs[${i}].<leaf>`} `` — the same templated path a repeater writes, so a
+second run reads it back and changes nothing — and the callback gains an index parameter, and a
+jsx row its `key`, if it had none.
+
+These arrays render exactly the paths this run wrote. Unlike `bcmsRows`, which reads the array
+itself, `bcmsList`/`bcmsTuples` map over that fixed path list — so every row's TEXT is editable and
+the NUMBER of rows is still the template's: a row added in the CMS has no path and never appears,
+and a row deleted falls back to the copy the template shipped with. The receipt says so out loud,
+once per array, as a `PRIMITIVE_LIST` note. Reading the array itself is the derive lane's job, not a
+fourth shape here.
+
+The lane refuses, by name: `IN_EXPRESSION` when the identifier is used anywhere but that one `.map`
+or is `export`ed (the read replaces the value everywhere, including in files this run cannot see),
+when the callback renders the item inside a larger expression, when an element is not a string
+literal, when one tuple position is text in one row and richtext in the next (one element has one
+sink), when the brief's paths do not cover EVERY element of the array, and when the paths are
+unrelated scalars rather than one group's rows — that last one could only be declared as an
+expression nothing downstream can verify; `REPEATER_AMBIGUOUS` when two loops iterate the array.
+
+**An array literal written INLINE in the markup is the same lane, with no name between the two
+halves.** `{['Offer', 'Structure', 'RTL'].map((item) => <li>…</li>)}` is what a template reaches
+for whenever the list is four words long — nobody lifts four bullet points into a `const` — and the
+copy then sits inside an expression the matcher is blind to by construction. The `]` immediately
+before the `.map(` IS the literal's close, so there is exactly one loop over it and nothing else in
+the file can hold a second reference to it: no "used anywhere but that one `.map`" test is needed,
+and everything else — the paths, the templated declaration, the index parameter, the refusals — is
+the named lane's. A value rendered BESIDE something else (`<li><span>✓</span>{item}</li>`) gets a
+`<span>` of its own rather than declaring on the parent, because a publish writing the value over
+the parent deletes the icon; the same wrap the scalar lane writes for a mixed element.
+
+**A row's leaf handed to a component is drilled, exactly as a scalar prop is.**
+`demos.map((demo) => <DemoCard title={demo.title} />)` renders the value in the COMPONENT's file,
+so the page's call site declares `` bcmsBindings={{ title: `cards[${i}].title` }} `` — one object
+per element, merged when a row hands two leaves to one component — and the component's element gets
+`data-bcms-field={bcmsBindings?.title}` with the prop added to its destructuring and its props
+type. `{...row}` counts as passing the prop: it is how most templates hand a row over. The group
+still binds whole or not at all, so a drill that misses (the component cannot be resolved, nothing
+in it renders the prop, this conversion already rewrites that file, or the call site already
+carries a `bcmsBindings`) refuses the WHOLE group by the drill's own reason.
+
+**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 +522,22 @@ and removing them would mean editing statements no section asked about.
 
 ## Not here yet
 
+GROWABLE lists. An array of primitives or tuples is bound (above) but renders the number of rows
+the template shipped with, because the read maps over a fixed path list rather than over the CMS
+array — and when the brief gave its elements unrelated scalar paths (`li-field`, `li-rtl`, …)
+rather than one group's rows, it is not bound at all: the only declaration that could carry a
+different path per row is an expression, and one nothing downstream can verify is worse than the
+honest `IN_EXPRESSION`. Both are the same fix on the derive side — minting the group — not a
+further shape here. Svelte and vue data literals are not converted
+either; all three 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).