@bettercms-ai/convert 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # @bettercms-ai/convert
 
+## 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

package/README.md

@@ -71,6 +71,49 @@ A path counts as rewritten only when EVERY located occurrence of it was. A value
 the home page and a shared header is two places a reader sees it, and converting one of them reads
 as a finished job.
 
+**A declaration this package did not write still counts.** An element that names the target —
+`data-bcms-field`, `data-bcms-layout-field` or an address in `data-bcms-props` — but gets its copy
+some other way (a literal somebody left there, the project's own data module) is DECLARED: the
+publisher injects into that element and the editor makes it click-to-edit. It is simply not reading
+through the committed helper. Those land in `alreadyDeclared` with a receipt row of their own,
+`readsFromCms: false`, rather than in `NO_ORIGINAL`:
+
+```jsonc
+"declarations": [{ "route": "/", "scope": "page", "path": "hero.title",
+                   "kind": "text", "file": "src/pages/index.astro", "readsFromCms": false }]
+```
+
+The evidence may never be ANOTHER ROUTE'S PAGE FILE — one the brief itself names, since
+`routeOfFile` reads the repository's convention and the two legitimately disagree about a dynamic
+route — and it may never be an element two routes both claim. The same rule gates a declaration
+that DOES read 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. Without a read there is nothing in a declaration that says which route it is for, and two
+routes legitimately carry `hero.title` — so "some file declares that string" would mark the other
+route bound and leave it hardcoded forever. A path with no original at all is stricter still: the
+only evidence available is the file's identity, so it has to be the one file the router says serves
+that route. A layout path has no route by construction, and any file may carry it.
+
+**A tsconfig is JSONC.** Comments and trailing commas are read (that is what `tsc --init` writes),
+because a config this package cannot parse declares no `paths` aliases as far as it is concerned —
+and then every `@/components/Hero` resolves to nothing and the refusal that follows names the wrong
+cause. Its alias fields are shape-checked too: `"paths": "src/*"` is valid JSON and the wrong type,
+and reading it threw a `TypeError` out of a pure function naming nothing. One it still cannot read
+is a receipt NOTE rather than a silence — on the componentize receipt as well, which resolves a
+page's `<Hero />` through exactly those aliases:
+
+```jsonc
+"notes": [{ "code": "TSCONFIG_UNREADABLE", "file": "tsconfig.json", "message": "…" }]
+```
+
+**The address grammar, in one place.** Page copy is `data-bcms-field="<path>"` plus
+`data-bcms-kind="<kind>"`. The shared chrome is a DIFFERENT attribute carrying a prefixed address,
+`data-bcms-layout-field="layout:<section>:<field>"`, so the block lane's own `[data-bcms-field]`
+query cannot reach a chrome marker. A value that lives in an ATTRIBUTE (a promoted nav link's
+`href`) has no field attribute of its own and rides `data-bcms-props="<address>|<kind>|<attr>;…"` —
+where `<address>` carries the same `layout:` prefix when it is chrome. A section root additionally
+carries `data-bcms-block="<blockId>"`, which is what the editor hit-tests for section chrome and
+reorder.
+
 ## As a library
 
 ```ts
@@ -92,6 +135,17 @@ proposer re-derives them from its own scan rather than believing the receipt. A
 become a loop — non-consecutive siblings, one row shaped differently, the html dialect — is still
 declared and read per index and reported `REPEATER_FIXED_LENGTH`.
 
+**A row that holds a list of its own becomes a loop inside the loop.** `cards[i].items[j].label` is
+a nested `.map` in astro and jsx, reading its rows off the ROW — `bcmsRows(card, "items", […])`,
+the same helper one level down, because `bcmsRows` passes a nested array through untouched and
+`bcmsSection` hands a section its group whole. The binding is
+`` data-bcms-field={`cards[${i}].items[${j}].label`} `` and the shape is `cards[*].items[*].label`.
+ONE level: that is what the plan mints and what the component prop validator accepts, so a leaf
+indexed twice keeps the length the template gives it. One inner row is enough to make the loop —
+the plan already says `items` is an array, and reading a card that ships a single bullet as "not a
+list" is how the second bullet an editor adds never renders. The html dialect has no loop form at all, so
+it stays fixed-length there — every index declared, the number of rows the template's.
+
 **A prop-drilled literal is converted in two hops, in one proposal.** `<Hero title="…" />` becomes
 `title={bcms(…)}` plus `bcmsBindings={{ title: "hero.title" }}`, and the `<h1>{title}</h1>` inside
 `Hero` — resolved through the file's own imports, relative or through the project's tsconfig
@@ -142,7 +196,7 @@ modify src/pages/index.astro
 modify bcms-content/home.json
 add    bcms-content/components.json
 
-5 sections extracted (0 inline-only, 0 already extracted, 0 pending)
+5 sections extracted (0 registered, 0 inline-only, 0 already extracted, 0 pending)
 ```
 
 `--plan <file>` is required and is only read in this mode. `--dry-run`, `--receipt`, `--strict` and
@@ -166,8 +220,22 @@ add    bcms-content/components.json
   ran, with nothing in the diff to explain it. The fallback is decided on the **raw** block list:
   a page whose blocks all name components this repo does not have has still been *arranged*, and
   putting the shipped bands back would undo an editor's work on the next build.
+- **Nothing at all, for a section the repository has ALREADY componentised.** A page that renders
+  `<Hero />` from a file it imports has made this cut itself: the existing file is REGISTERED under
+  the section's slug — the registry imports it where it lives, **in the shape its module actually
+  exports**: a default import, `import { Hero }` for a named export, or `import * as Bands` plus the
+  member the page's own call site names — and the page keeps calling it. When one module is bound
+  twice (`import Default, { Hero } from "./bands"`), the binding the page actually CALLS is the one
+  registered. It has to be a file this page imports, the only one it imports that renders the
+  group, and one the registry's dialect can render; a section the page ALSO renders inline is two
+  answers and is refused. Everything else is `SECTION_ROOT_AMBIGUOUS` with the reason spelled out.
 - **The page** — the contiguous run of section roots replaced by one `<Sections page="<slug>" />`,
-  with the import added.
+  with the import added. Contiguous means consecutive element siblings **and** nothing but
+  whitespace or comments in the bytes between them: `<Hero />Read this first<Features />` has no
+  element in the way, and one splice over that run would delete the sentence. A page with a REGISTERED section is all or nothing: `<Sections>` renders
+  every placement the page has, so the run is replaced only when every one of the page's sections
+  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.
 - **The stubs** — `blocks: []` added to each page's snapshot (keys it already has are kept), and
   `bcms-content/components.json` = `[]`.
 
@@ -211,11 +279,12 @@ import travels as `import * as X`, not as a named one.
 
 | reason | |
 |---|---|
-| `SECTION_ROOT_AMBIGUOUS` | the group's fields sit under no single element, one section's root contains another's, or the group is rendered somewhere other than this route's page file. |
+| `SECTION_ROOT_AMBIGUOUS` | the group's fields sit under no single element, one section's root contains another's, the page renders it BOTH inline and through a component it imports, two imported components render it, or it is rendered somewhere this cannot register — a file this page does not import, a component of another dialect, a namespace the page never calls. The message says which. |
 | `SECTION_NOT_CONTIGUOUS` | the page's section roots share no container at all. **The components are still written**; the page is left exactly as its author wrote it. |
 | `SECTION_FREE_IDENTIFIERS` | the markup uses a name the component file cannot be given. The identifier is named in the message. |
 | `COMPONENT_CONFLICT` | a file already sits at `src/components/bcms/<Name>` and this package did not write it. Decided on our marker, never on the path — that is a name a person may reasonably have chosen first. |
 | `REGISTRY_CONFLICT` | the same, for `Sections.astro`/`Sections.tsx` or `src/lib/bcms-sections.ts`. Both are rebuilt whole on every run, so an unmarked file there would be destroyed. `--overwrite-helper` proceeds. |
+| `REGISTRY_UNREADABLE` | the registry IS ours and its `REGISTRY`/`SHIPPED` tables cannot be read back — a component it names is GONE from the tree, a row is not a property this can read, or the tables are missing. Every property is parsed structurally and all of them must convert; a partial read is what silently drops a page's bands. It is rebuilt whole every run, so re-emitting it from what this run happened to see would blank those pages. No flag overrides this one: deleting the file is a decision only a person can take. |
 | `ROUTE_FILE_AMBIGUOUS` | two files serve one route. |
 | `DIALECT_UNSUPPORTED` | the page is svelte, vue or html. Nothing is written for it. |
 | `HELPER_CONFLICT` | `src/bcms-content.ts` is a module this package did not write. `--overwrite-helper` proceeds. |
@@ -236,7 +305,14 @@ brand-new page untouched.
 The registry and the sections library are rebuilt WHOLE each run, so they are first read back:
 components an earlier run wrote are reused rather than rewritten, and the shipped order of every
 page already served is carried forward. Without that, componentizing one new page emitted a
-registry that had never heard of the others, and they rendered blank.
+registry that had never heard of the others, and they rendered blank. The read-back goes through
+the dialect's own PARSER, so a formatter that rewrote our imports (single quotes, a wrapped line)
+changes nothing; the two tables are brace-matched with strings and comments skipped and every
+property is parsed structurally, so a one-line table, a wrapped one, or a comment containing a `}`
+are all read whole. An import must resolve to a file that is actually there — composing the path
+from our own naming convention re-emitted a registry importing a component somebody had deleted.
+When any of that cannot be reconstructed the run refuses by name rather than rebuilding from what
+it happens to see.
 
 A run whose roots DO share a container but have a foreign sibling between them is not refused: each
 root becomes its own `<Hero …/>` where its markup was, counted `inlineOnly`. The markup is
@@ -245,17 +321,20 @@ componentised and the ORDER stays the repository's — looping that page would m
 The arithmetic is checked rather than hoped for:
 
 ```
-plan sections === extracted + inlineOnly + alreadyExtracted + pending.length
+plan sections === extracted + inlineOnly + alreadyExtracted + registered + pending.length
 ```
 
-`alreadyExtracted` is the fourth bucket the plan document does not name, and it is what makes the
-round trip observable: a second run over an already-componentised tree reports `extracted: 0,
+`registered` is orthogonal to placement: nothing was written for those sections — the file was
+somebody's before the run and stays theirs — so counting them `extracted` would claim authorship of
+bytes this package never produced. `alreadyExtracted` is the bucket the plan document does not
+name, and it is what makes the round trip observable: a second run over an already-componentised tree reports `extracted: 0,
 pending: []` **and** still accounts for every section. Our own output is recognised by a marker
 comment, never by its path — `src/components/bcms/` is a directory anybody may put a component in.
 
 Known leftovers, stated rather than hidden: a page whose every read moved into a component keeps
-the now-unused `bcms`/snapshot imports P2 added. They are harmless at build time and removing them
-would mean editing statements no section asked about.
+the now-unused `bcms`/snapshot imports P2 added, and a page whose registered call sites became one
+`<Sections>` keeps the imports of the components it used to call. They are harmless at build time
+and removing them would mean editing statements no section asked about.
 
 ## Not here yet