@bettercms-ai/convert 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @bettercms-ai/convert
 
+## 0.12.0
+
+### Minor Changes
+
+- a243594: Every pending path leaves with an exact fix, and a locator resolves each path sharing a literal.
+
+  `paths.pending[]` rows now carry `fix: { file, line, col?, snippet, action, why? }` — one action
+  out of a closed set (`wrap-span`, `declare-attr`, `bind-expression`, `declare-richtext`,
+  `bind-data`, `manual`), so "rerun until nothing is pending" is a loop an agent can finish instead
+  of a list of category names. A literal one element renders on several routes is named as shared
+  chrome rather than sent for an attribute that could only ever be one route's.
+
+  Positional resolution is now per PATH rather than per literal: one path with no locator used to
+  refuse the whole literal, so a page whose rows carried locators converted none of them.
+
+  Two paths whose locators cannot be told apart now place NEITHER. Resolution counts the targets
+  wanting each element before it assigns any, so it no longer depends on brief order: `plan` runs
+  per file, and claiming greedily let the first of two indistinguishable paths win in every file —
+  writing one path's `data-bcms-field` onto the other's element and reporting it bound.
+
+  An action that edits an element (`wrap-span`, `declare-attr`, `declare-richtext`) is never issued
+  at a position inside a frontmatter array or a `<script>`; there is no element there, so the fix is
+  `bind-data` on the row the copy actually lives in. A fix for a dynamic route names the template
+  that generates it instead of an empty file. Files that talk ABOUT the site — `*.test.*`,
+  `*.spec.*`, `__tests__/`, `__mocks__/`, root `*.config.*` — are no longer read, so a test
+  asserting on the hero line stops holding an already-declared path pending.
+
+  Fix positions are measured against the bytes the run WRITES, not the ones it read — the same run
+  inserts a helper import above most pending lines, so a receipt minted from the originals named a
+  line one or more short of the element on 616 of 948 Shatter rows.
+
+## 0.11.0
+
+### Minor Changes
+
+- `--componentize` extracts FLAT field families (`wrap-h2-latest`, whose key is `h2_latest`), which were
+  refused as `PROP_MAP_INCONSISTENT`. The section reads its copy through the new helper `bcmsSectionPaths`
+  and addresses instance copy by the override key the plan names (`overrideKey`, including repeater rows).
+- An Astro section carries the page's scoped plain-CSS `<style>` blocks, so it renders styled on its own —
+  for every newly extracted section, dotted families included (Astro scopes styles per file, so page CSS
+  never reached a moved section). `is:global`, `define:vars`, `lang="…"` and `@import`/`@use` blocks stay on
+  the page.
+- The componentize receipt lists `componentFiles` (`{ slug, path, export }`): submit it with the MCP tool
+  `submit_componentize_receipt` so every extracted section is recorded as its component's source and the
+  dashboard's Output can build, validate and render it.
+- Helper v7. A v6 helper is recognised and upgraded in place.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -184,6 +184,60 @@ the receipt's arithmetic is checked, not hoped for:
 paths.declared === paths.rewritten + paths.alreadyDeclared + paths.pending.length
 ```
 
+### What pending means — every row carries the edit, not the diagnosis
+
+A reason is a diagnosis and nobody can act on one. So every `paths.pending[]` row also carries a
+`fix`: the file, the 1-based line and column, the bytes that are there now, and ONE action out of
+a closed set. That is what makes "run it again until nothing is pending" a loop an agent can
+actually finish — and what `get_next_steps` prints, one line per path.
+
+```jsonc
+{ "route": "/about", "scope": "page", "path": "p-founded-in-2019-in", "kind": "text",
+  "reason": "DIALECT_UNSUPPORTED",
+  "fix": { "file": "src/data/facts.js", "line": 3, "col": 25,
+           "snippet": "export const founded = \"Founded in 2019 in Bristol.\";",
+           "action": "bind-data",
+           "why": "src/data/facts.js holds this copy as data — bind the element that renders it." } }
+```
+
+| action | what to type |
+|---|---|
+| `wrap-span` | the value shares its element with something else, or is rendered in a position no attribute reaches — give it a `<span data-bcms-field="…">` of its own. |
+| `declare-attr` | the element is there and nothing said which path it is — add `data-bcms-field` to it at `file:line`. |
+| `declare-richtext` | the container is fed markup (`set:html`, `dangerouslySetInnerHTML`) — bind it with the richtext helper. |
+| `bind-expression` | the value is computed in the markup (a ternary, a template literal) — read the path there instead. |
+| `bind-data` | the copy lives in a data module, a frontmatter array or a content-collection entry — bind THAT field, and the element that renders it. |
+| `manual` | none of the above is true; `why` says what a human has to decide. |
+
+Reason → action, and the two places the answer is not the obvious one:
+
+| reason | action |
+|---|---|
+| `AMBIGUOUS_LITERAL`, one route | `declare-attr` — `why` names every candidate file. |
+| `AMBIGUOUS_LITERAL`, **several routes** | `manual` — one element cannot carry N routes' bindings. This is SHARED CHROME the derive lane did not promote: a Layout field is one value for the whole site, and an attribute here would bind one route and silently freeze the rest. |
+| `IN_EXPRESSION` in the markup | `bind-expression`, or `declare-richtext` for a richtext value. |
+| `IN_EXPRESSION` **in the frontmatter or a `<script>`** | `bind-data` — the copy is a row in the file's own data, and the array is what gets bound, not the `{l.label}` that reads it. |
+| `DIALECT_UNSUPPORTED` on `.md`/`.mdx` | `bind-data` — a content-collection body is the entry's `document` field. |
+| `NOT_IN_SOURCE` / `NO_ORIGINAL` | `bind-data` when the copy is in a data module, else `manual`: the built page formats it and the source holds the input. |
+| `PROP_TARGET_NOT_FOUND`, `PROP_DRILLED_DEEP`, `SUBSTRING_ONLY` | `wrap-span`. |
+| `REPEATER_AMBIGUOUS`, `REPEATER_FIXED_LENGTH` | `declare-attr` on the row's own element. |
+| `IMAGE_ASSET_UNRESOLVED`, `IN_DATA_FILE` | `bind-data`. |
+| `SUBTREE_NOT_HTML` | `declare-richtext`. |
+| `KIND_MISMATCH`, `IN_SCRIPT_OR_COMMENT`, `DYNAMIC_PARAMS_UNAVAILABLE`, `BRIEF_META_UNPLACED`, `PARSE_ERROR`, `TIER3_UNVERIFIABLE`, `CANVAS_BRIDGE_MANUAL`, `SSR_DRAFT_ROUTE` | `manual`, with the reason quoted in `why` — read the row's `message` for what blocked it. |
+
+**A file that talks ABOUT the site is not a source file.** A path is rewritten only when every
+located occurrence was, so a test asserting on the hero line, or a build config quoting the font
+stack, used to hold an already-declared path pending. `*.test.*`, `*.spec.*`, `__tests__/`,
+`__mocks__/` and root-level `*.config.*` are never opened, alongside `node_modules/` and `dist/`.
+A data module under `src/` — `src/site.config.ts` — is not a build config and stays bindable.
+
+**`--xray` and the receipt exclude the same things.** The xray measures a BUILT site's visible
+copy and the receipt measures the brief's paths in SOURCE, so they never have the same
+denominator — but neither counts a decorative glyph, a `<script>` or a `<style>` as copy
+(`isDecorativeGlyph` is the one reader), and the two lane rows `CANVAS_BRIDGE_MANUAL` and
+`SSR_DRAFT_ROUTE` ride `paths.pending` without entering the arithmetic above. A path the receipt
+calls pending is copy the xray will still count as unaddressed; a path it calls rewritten is not.
+
 A path counts as rewritten only when EVERY located occurrence of it was. A value rendered by both
 the home page and a shared header is two places a reader sees it, and converting one of them reads
 as a finished job.