@bettercms-ai/convert 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,342 @@
 # @bettercms-ai/convert
 
+## 0.4.0
+
+The workspace lockfile records this version: a lock still naming 0.3.0 makes a frozen install
+reject the checkout, which is what broke the migrator image on #616.
+
+### Minor Changes
+
+- Componentize Phase B: an extracted section declares the lane its copy actually lives in.
+
+  An element carries exactly ONE `data-bcms-field`, and which address it names is now decided
+  when the component RENDERS rather than when the codemod ran. A placement bound to a page
+  field group declares the page path, as before. A placement that owns its copy — `overrides`
+  and no `bind` — declares the block lane, `<blockId>__overrides.<propKey>`, which is where
+  the editor commits an instance's own value.
+
+  🔴 The extracted files are BYTE-IDENTICAL in both copy models. That is the point: moving a
+  page's copy onto its instances is a data change on the server, not a second cut of the
+  repository, and one component renders a Phase A placement on one page and a Phase B
+  instance on the next. Each of P2's bindings is wrapped in the placement's own chooser,
+  `bcmsFields({ blockId, bind, overrides }, "<prefix>")`, so the page path is still verbatim
+  in the file. The prefix that turns a page path into a prop key comes from the plan's
+  `fields[].key`/`path` map, not from the group key.
+
+  The root's `data-bcms-block` is now REPLACED when the repository already wrote one, instead
+  of a second being appended beside it — two instances claiming one element.
+
+- `--copy bind|instance` (default `bind`), and the `COPY_MODE_MISMATCH` refusal.
+
+  An assertion rather than a switch, since the output does not depend on it. It catches the
+  one order-of-operations mistake that would otherwise be silent: `--copy instance` run in the
+  repository before the server has moved the copy leaves a tree that looks converted and
+  renders every section out of page fields the dashboard is about to hide. A plan whose
+  placements all still carry `bind` refuses every section by name, with nothing written. The
+  receipt carries `copy`, the same word the server's receipt uses.
+
+  The registry's shipped fallback now omits `bind` for an instance-owned placement, for the
+  same reason: binding it would make a fresh clone render a section out of hidden fields.
+
+- The extracted-component format is VERSIONED (`section v2`), and older ones are upgraded.
+
+  🔴 Without this Phase B never reaches a repository that already ran 0.3. Completion is
+  decided on the marker and a v1 component carries one, so every already-componentized page
+  was reported done, its components kept their page-path bindings, and `--copy instance`
+  there placed five sections while moving no address at all. Each v1 component is now brought
+  to the current format in place — every `data-bcms-field` wrapped in the chooser, the chooser
+  declared and imported, the marker restamped — once, before any page is called done. A
+  component the plan says nothing about is left alone; one that cannot be upgraded is
+  `SECTION_UNMIGRATABLE` rather than a silent skip.
+
+- An already-componentized page's shipped placements are restated from the current plan.
+
+  A bind run followed by an instance run kept `bind` on every placement in the registry's
+  fallback table, so a fresh clone rendered sections out of page fields the dashboard had
+  already hidden — and the reverse transition never put `bind` back. The `bind` is now
+  restated on every run, in the order the registry already holds; nothing is extracted, and
+  the registry is rewritten only when those bytes actually change. Repeated placements of one
+  component — two groups sharing a `shapeHash`, which is what `shapeHash` is FOR — are matched
+  POSITIONALLY, registry order against plan order per slug: keying them by slug collapsed them,
+  so a page with one group still bound and another moved wrote both from the second.
+
+- The v1 → v2 upgrade reuses names the file already has, or refuses.
+
+  These files have been sitting in somebody's repository. Blindly adding
+  `import { bcmsFields }` and `const bcmsField = …` to a module that already declares either
+  produced a duplicate binding — a file that does not compile — reported as a successful
+  upgrade. An import of the helper's own `bcmsFields` is reused under whatever local name it
+  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
+  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`
+  must be declared as `const bcmsField = <that exact local>(…)`, read structurally off the
+  module's own top-level AST.
+
+- Which group an upgraded component was cut from is read off the FILE, not off the plan.
+
+  One component serves every page whose group has its shape, and its markup carries the paths of
+  the one page it was cut FROM. Taking the plan's first placement for that slug gave a component
+  reading `hero.*` the prefix `landingHero.` as soon as that placement came first: every wrapped
+  address matched nothing, the block lane never fired, and the file was stamped current for good.
+  The candidate prefixes are matched against the addresses the file actually declares, and a slug
+  whose placements cannot be told apart that way is `SECTION_UNMIGRATABLE`. Server-pending
+  placements count as prefix EVIDENCE — which group the bytes were cut from is a fact about the
+  past, and a refused placement may be the only thing that explains them — while still being
+  excluded from placement and copy-mode decisions.
+
+- Fresh extraction allocates collision-free names for the chooser and its import.
+
+  The markup being cut is the PAGE's, and a page is free to have declared `bcmsField` itself.
+  Declaring ours unconditionally — and listing the name as `provided`, so `carryFor` neither
+  carried the page's declaration nor reported it free — silently rebound every use of theirs
+  inside the extracted section to our chooser. Both names now go through the same allocator as
+  every other identifier this codemod introduces, reserved against the module's bindings AND
+  against every identifier-shaped token in the bytes being lifted: in a TSX page that declaration
+  lives inside the component function, where a module-level check cannot see it, so the capture
+  happened anyway. ALL of the names, not the two base ones — reserving only `bcmsField` sent the
+  allocator to `bcmsField_1`, which a section referencing both also uses, and the capture simply
+  moved one suffix along.
+
+- The prop map is checked before this repository is consulted at all, AND against the
+  addresses it has to convert.
+
+  Checking it where the markup is cut let an ALREADY-componentized page bypass it: a later plan
+  spelling `{ key: "title", path: "hero.heading" }` was reported complete while the component it
+  names went on addressing `overrides.heading`, a key the instance does not hold. The map is a
+  property of the plan, so it is now answered from the plan, before completion is even asked.
+
+  🔴 AND A MAP CAN BE INTERNALLY CONSISTENT AND STILL WRONG ABOUT THE SECTION.
+  `{ groupKey: "hero", key: "title", path: "other.title" }` derives one clean prefix, `other.`,
+  which matches nothing the markup declares — so every element quietly stayed on the page lane
+  while the run reported the section done. The derived prefix is now verified against every
+  address the section actually declares — and a field address this cannot read statically
+  (`{computedPath}`, `{prefix + ".title"}`) counts as one it cannot convert, because contributing
+  nothing to the check is how such an element stayed on the page lane at render time. A
+  repeater's template literal is readable and is not affected.
+
+- Migration refusals are about ONE component, and a `.tsx` chooser is found where it lives.
+
+  Keyed by slug alone, an unmigratable `Hero.astro` marked the perfectly good `Hero.tsx`
+  unmigratable in a mixed repository — a page refused for a fact about a file its route does not
+  render. And a `.tsx` component declares its chooser INSIDE the function, which is where this
+  package puts it: a program-level binding check saw nothing there and inserted a second
+  `const bcmsField` into the same block. Both scopes are read; the refusal is keyed by dialect
+  and slug.
+
+  Reading a registry back also resolves its extensionless imports to a file its OWN dialect can
+  render. Two dialects share a component name whenever they share a slug, and a general resolver
+  — whose extension order is this package's, not the project's — bound the `.tsx` registry's
+  `hero` to the astro file, after which everything was about the wrong component.
+
+- `readRegistry` validates each `SHIPPED` row instead of trusting the array.
+
+  `[null]` is valid JSON, and the first thing to read it back dereferenced `placement.slug` and
+  threw a `TypeError` out of a pure function that names nothing. A row must be an object with a
+  string `slug` and, when present, string `bind`/`blockId`; anything else is `REGISTRY_UNREADABLE`,
+  which is what every other unreadable row in that file already was — as is a `REGISTRY` naming
+  no components (this module is only emitted when there is at least one, so a table with no rows
+  is one whose rows were lost) and a `SHIPPED` slug the `REGISTRY` does not name. An EMPTY
+  `SHIPPED` is still read: a run whose only page was `SECTION_NOT_CONTIGUOUS` writes the
+  components and no order at all, so refusing that would strand the repository. A single page
+  whose placement list is EMPTY is refused, though — `every` is vacuously true of it, and the
+  fallback exists precisely so a build with no CMS blocks renders the bands the repository ships.
+
+- Two more edges: a root carrying SEVERAL `data-bcms-block` attributes keeps exactly one (only
+  the first was being rewritten, so the extracted element still came out with two), and a v1
+  component with no `data-bcms-field` at all is upgraded on its marker alone rather than refused
+  for an ambiguity it cannot have — every candidate prefix matched it vacuously.
+
+### Patch Changes
+
+- No synthesized group fallback: an extracted component reads `bcmsSection(page, bind, overrides)`.
+
+  🔴 `bind ?? "<groupKey>"` belonged to Phase A, where every placement was bound and the default
+  could only restate what the placement already said. Under Phase B a placement that OWNS its
+  copy carries no bind on purpose — and the fallback put the page's field group straight back
+  underneath it, so a key the instance had not been given rendered the page's stale copy out of
+  fields the dashboard has already hidden. A placement that names no group has none, and every
+  `bcms(...)` then renders what the template shipped with. The v1 → v2 upgrade rewrites the old
+  form away rather than stamping it as current — through the module's own AST, by offset and
+  through the file's OWN local name for the export, because an exact-text rewrite missed a call a
+  formatter had reflowed and a name-matched one missed an aliased
+  `import { bcmsSection as sectionCopy }`; the marker then said the question had been settled. A
+  module with no readable program is refused, and so is one where nothing was rewritten while a
+  `??` fallback sits in a call this cannot identify as the helper's.
+
+- Only provably safe field expressions count as an address.
+
+  Starting with a quote is not a proof: `{"hero.title".replace("hero", "footer")}` names
+  `footer.title` at render time, and reading its first characters as the address accepted a
+  section whose element then quietly stayed on the page lane — the failure the check exists to
+  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`.
+
+- `COPY_MODE_MISMATCH` ignores sections the SERVER already refused.
+
+  A `copy: "instance"` section carrying `pending` is not a placement this run would make, but it
+  counted as evidence that the plan had moved its copy — so `--copy instance` passed the gate on
+  a plan whose only instance-owned section was server-pending, and the run wrote the BIND
+  conversion for the sections it could act on. Which is the exact tree the flag exists to stop.
+
+- A bound address is RE-BASED onto its own placement's group.
+
+  The markup is cut from ONE page and carries that page's paths, and the whole point of
+  `shapeHash` is that a second page renders the same component bound to a group of its own.
+  Handing the embedded path through unchanged declared `hero.title` on a page whose field is
+  `landingHero.title` — an address that page does not have, so the editor wrote into nothing
+  and the meter counted a binding that was never there.
+
+- `INLINE_NEEDS_INSTANCE`: a page that cannot be looped cannot own its copy.
+
+  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*
+  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.
+
+- `HELPER_CONFLICT` and `COPY_MODE_MISMATCH` now return an EMPTY file list.
+
+  On an already-componentized repository the registry read-back seeds the component table, so
+  the emit fired even though every section was pending: the helper was upgraded, the sections
+  library rebuilt and the registry rewritten for a run the operator was told did nothing. With
+  a hand-edited helper it was worse — the v1 → v2 upgrade rewrote components to
+  `import { bcmsFields }` from a module that does not export it. A refusal that modifies the
+  tree is not a refusal, so both return before reading or emitting any generated artefact.
+
+- Two new refusals where the codemod used to guess.
+
+  `PROP_MAP_INCONSISTENT`: a plan whose `fields[].path` is not one common prefix plus its
+  `key` — `{ path: "hero.heading", key: "title" }` — fell back to `<groupKey>.`, so the block
+  address became `overrides.heading` for a prop the instance holds as `title`, and every edit
+  went to a key nothing reads. `DUPLICATE_FIELD_BINDING`: an element already carrying two
+  `data-bcms-field` had both rewritten, leaving the extracted element still violating the
+  one-attribute invariant.
+
+- Helper v4: `bcmsSection` merges OVERRIDES-FIRST, per key.
+
+  `overrides[key] ?? group[key]` rather than "overrides, or else the group". The case that
+  matters is the one in between — a section whose copy is half moved — where a key the
+  instance does not hold has to keep rendering the page's value rather than nothing. `??`,
+  never `||`: an empty string is a value an editor typed. A table prop stored in the shape
+  the dashboard edits (`{ rows: [...] }`) is unwrapped to its list, so `bcmsRows` sees an
+  array instead of falling back to the rows the template shipped with.
+
+  New export `bcmsFields`, which is what an extracted section's bindings read through. An
+  existing v1–v3 helper is upgraded in place as usual; one this package did not write is
+  still `HELPER_CONFLICT`.
+
+## 0.3.0
+
+### Minor Changes
+
+- Componentize: a section the repository has ALREADY componentised is REGISTERED, not refused.
+
+  A page whose `index.astro` imports `Hero.astro` and renders `<Hero />` has made the cut
+  this lane exists to make. There is nothing in the page to extract, and refusing left the
+  CMS naming a section no component in the repo rendered. The existing file is now
+  registered under the section's slug — the registry imports it where it lives — and the
+  page keeps its call site. It has to be ONE file, one the page IMPORTS, and one the
+  registry's own dialect can render; anything else is `SECTION_ROOT_AMBIGUOUS` with the
+  reason named.
+
+  New receipt bucket, in the arithmetic:
+  `plan sections === extracted + inlineOnly + alreadyExtracted + registered + pending.length`.
+  `registered` is orthogonal to placement — nothing was written for those sections, so
+  counting them `extracted` would claim authorship of bytes this package never produced.
+
+  A page with a registered section is ALL OR NOTHING: `<Sections>` renders every placement
+  the page has, so the run is replaced by one `<Sections page="…" />` only when every
+  section of the page resolved and every call site is a bare tag in that run. Otherwise the
+  call sites stay exactly where their author put them — replacing a subset would render a
+  registered section twice, once in place and once out of the registry. The registry
+  read-back also resolves ANY relative import now, not only `./Name`: without that a second
+  run dropped the registered entry and the page rendered blank.
+
+- Repeaters: a row that holds a list of its own becomes a loop inside the loop.
+
+  `cards[i].items[j].label` is emitted as a nested `.map` in astro and jsx, reading its rows
+  off the ROW — `bcmsRows(card, "items", [ …this card's own items… ])` — so a bullet added in
+  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
+  `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
+  indexed twice stays `REPEATER_FIXED_LENGTH`, and so does the html dialect, which has no
+  loop form at all.
+
+- A hand-written declaration counts as `alreadyDeclared`, never `NO_ORIGINAL`.
+
+  An element that names the target (`data-bcms-field`, `data-bcms-layout-field`, an address
+  in `data-bcms-props`) but gets its copy some other way is DECLARED: the publisher injects
+  into it and the editor makes it click-to-edit. It is simply not reading through the
+  committed helper. The receipt gains one row per already-declared path —
+  `paths.declarations[] { route, scope, path, kind, file, readsFromCms }` — and the
+  arithmetic is unchanged. The evidence has to be on the file the ROUTER says serves that
+  route: without a read there is nothing in a declaration that says which route it is for,
+  and two routes legitimately carry `hero.title`.
+
+  README: the "declared by hand" paragraph, and the address grammar in one place —
+  `data-bcms-field` / `data-bcms-layout-field="layout:<section>:<field>"`, attribute values
+  through `data-bcms-props="<address>|<kind>|<attr>"`, and `data-bcms-block` on a section root.
+
+- Review hardening for all three of the above.
+
+  **Componentize.** A section the page renders BOTH inline and through a component it imports is
+  `SECTION_ROOT_AMBIGUOUS`: cutting the inline copy left `<Sections>` rendering the band out of
+  the registry while the untouched `<Hero />` beside it rendered it again. So is a section two
+  imported components both render, and a namespace the page imports but never calls. A registered
+  component is imported in the shape its module actually exports — default, `import { Hero }`, or
+  `import * as Bands` plus the member the call site names — because a default import of a named
+  export binds `undefined`. Contiguity now requires whitespace or comments between the roots, not
+  merely consecutive element siblings: `<Hero />Read this first<Features />` had no element in the
+  way and the run splice deleted the sentence. The registry read-back goes through the dialect's
+  parser instead of a line-shaped regex, so a formatter cannot make it forget the components it
+  names — and when the tables genuinely cannot be reconstructed the run refuses with the new
+  `REGISTRY_UNREADABLE` rather than rebuilding a registry without them.
+
+  **Repeaters.** A nested list the repository ships ONE row of still becomes a loop; the plan
+  already says `items` is an array, and reading one bullet as "not a list" is how the second one an
+  editor adds never renders.
+
+  **Declarations.** The route rule now covers LOCATED paths too — a hand-written declaration on
+  another route's page file, or on an element two routes both claim, is not evidence for either —
+  and every declarations row names the file it was found on. `aliasesFrom` reads JSONC (block
+  comments, trailing commas), because a tsconfig this package could not parse silently declared no
+  aliases and every aliased import then read as "not imported"; one it still cannot read is a
+  `TSCONFIG_UNREADABLE` note on the receipt.
+
+- A second review round, over the same three.
+
+  **The registry read-back.** An import must resolve to a file that is actually there —
+  composing the path from our own naming convention meant a component somebody DELETED still
+  "resolved", and the run re-emitted a registry importing it. Both tables are now parsed
+  property by property, with strings and comments skipped by the brace matcher, so a one-line
+  table, a wrapped one and a comment containing a `}` are all read whole; anything that cannot
+  be reconstructed in full is `REGISTRY_UNREADABLE` rather than a quiet partial rebuild.
+
+  **Bindings.** `import Default, { Hero } from "./bands"` binds one module twice; the binding
+  the page actually CALLS is the one registered, instead of whichever came first.
+
+  **Declarations.** The route gate now also applies to a declaration that reads from the CMS —
+  a home page rendering a teaser of `/about`'s headline reads `/about`'s snapshot legitimately,
+  and counting it left `/about`'s own page hardcoded and unreported. "Another route's page" means
+  a route THE BRIEF names: `routeOfFile` reads the repository's convention and the two disagree
+  about a dynamic route (`/[slug]` vs `/post/[slug]`), and refusing on a name the brief never
+  issued rejected every dynamic route's own page.
+
+  **Configs.** A tsconfig whose `baseUrl`/`paths` are valid JSON of the wrong type threw a
+  `TypeError` out of a pure function; the shape is checked and a bad one is
+  `TSCONFIG_UNREADABLE`, which the componentize receipt now carries too.
+
 ## 0.2.0
 
 ### Minor Changes