@bettercms-ai/convert 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -175,6 +175,29 @@ interface PendingPath {
     reason: PendingReason;
     message?: string;
 }
+/**
+ * One path that was already DECLARED before this run — and how honestly.
+ *
+ * 🔴 `readsFromCms: false` IS THE INTERESTING ROW. An element carrying a `data-bcms-field` (or a
+ * `data-bcms-props` / `data-bcms-layout-field`) that gets its copy some other way — a hand-written
+ * declaration on markup that still renders a literal, or reads it from the project's own data
+ * module — is DECLARED: the publisher writes into it and the editor can click it. It is simply not
+ * reading through this package's helper. Reporting it `NO_ORIGINAL` said the opposite of the truth
+ * — a path nobody had declared — and sent an agent to convert an element that was already done.
+ *
+ * The row is informative; `paths.alreadyDeclared` is the number the arithmetic uses, and both
+ * shapes count towards it.
+ */
+interface DeclaredPath {
+    route: string;
+    scope: "page" | "layout";
+    path: string;
+    kind: string;
+    /** The file the declaration was found on. */
+    file?: string;
+    /** Does the declaring element read this value through the committed helper? */
+    readsFromCms: boolean;
+}
 /** One file the conversion touched, and the tier that produced it. A file is exactly one tier. */
 interface ReceiptFile {
     path: string;
@@ -187,6 +210,13 @@ interface ConversionReceipt {
         declared: number;
         rewritten: number;
         alreadyDeclared: number;
+        /**
+         * One row per already-declared path, saying whether it reads from the CMS. @see DeclaredPath
+         *
+         * OPTIONAL, because a receipt written by an older version of this package does not carry it and
+         * a reader must not require it. The COUNT above is the contract; this is the detail.
+         */
+        declarations?: DeclaredPath[];
         pending: PendingPath[];
     };
     occurrences: {
@@ -205,6 +235,8 @@ interface ConversionReceipt {
      * a reviewer can see what to look for, and so the scan has somewhere to disagree with.
      */
     dynamicBindings: DynamicBinding[];
+    /** Facts about the repository that shaped this run. OPTIONAL: an older receipt carries none. */
+    notes?: ReceiptNote[];
 }
 /**
  * One binding whose `data-bcms-field` is an expression, and where its value is written literally.
@@ -226,6 +258,19 @@ interface DynamicBinding {
         literal: string;
     }[];
 }
+/**
+ * Something about the REPOSITORY that changed what this run could see, named rather than swallowed.
+ *
+ * Not a path and not a refusal: a note is about a file the conversion READ, and it explains why a
+ * later reason may name the wrong cause. `TSCONFIG_UNREADABLE` is the first — a project config this
+ * package could not parse declares no `paths` aliases as far as it is concerned, so every aliased
+ * import resolves to nothing and the component behind it reads as one the page does not import.
+ */
+interface ReceiptNote {
+    code: "TSCONFIG_UNREADABLE";
+    file: string;
+    message: string;
+}
 /** Raised when the receipt does not add up. Never caught inside this package. */
 declare class ReceiptInvariantError extends Error {
     readonly code = "RECEIPT_INVARIANT";
@@ -653,7 +698,7 @@ declare function attrsFor(path: string, kind: string, props?: AttrBinding[], sco
 declare function propsAttribute(props: AttrBinding[]): string;
 
 /** Bumped whenever the emitted source changes. `isKnownHelper` upgrades anything older. */
-declare const HELPER_VERSION = 3;
+declare const HELPER_VERSION = 4;
 /** Where each dialect's helper lives. Null = this dialect reads nothing at build time. */
 declare const HELPER_PATH: Record<Dialect, string | null>;
 /** The directory the snapshots live in, at the repository root. */
@@ -712,6 +757,14 @@ declare function isSourceCandidate(path: string): boolean;
  * specifiers only, which is a smaller conversion and a true one.
  */
 declare function aliasesFrom(sources: SourceFile[]): Map<string, string[]>;
+/**
+ * The project configs this package could not read, by path — a receipt NOTE, never a silent skip.
+ *
+ * A config that fails even the tolerant reader is one whose `paths` aliases nobody can resolve, so
+ * an aliased import reads as "not imported" and the refusal that follows names the wrong cause.
+ * The note says which file to look at. @see ConversionReceipt.notes
+ */
+declare function unreadableConfigs(sources: SourceFile[]): string[];
 /** The repository path a specifier names, or null when it is not among the files we were given. */
 declare function resolveSpecifier(fromFile: string, specifier: string, files: Set<string>, aliases: Map<string, string[]>): string | null;
 /** What one local name was imported from, and WHICH export of it. */
@@ -926,6 +979,15 @@ interface ComponentizePlanSection {
         componentId?: string;
         proposedSlug?: string;
     };
+    /**
+     * WHERE THIS PLACEMENT'S COPY LIVES — Phase B's one new field.
+     *
+     * `"instance"` says the server moved the group's values onto the instance's `overrides`, so the
+     * placement carries no `bind` and its elements declare the BLOCK lane. ABSENT MEANS `"bind"`:
+     * a plan written by a Phase A server says nothing here, and a codemod that required the field
+     * would refuse every plan older than itself. @see readPlan
+     */
+    copy?: string;
     /** The SERVER already decided it cannot place this one. Not this codemod's to extract. */
     pending?: {
         reason?: string;
@@ -963,15 +1025,29 @@ interface ComponentizePlan {
  *   `COMPONENT_CONFLICT`         a file already sits at the component's path and this package did
  *                                not write it.
  *   `REGISTRY_CONFLICT`          the same, for the registry or the sections library.
+ *   `REGISTRY_UNREADABLE`        the registry IS ours, and its tables cannot be read back. It is
+ *                                rewritten whole every run, so rebuilding it from what this run
+ *                                happened to see would drop the components it already names.
  *   `ROUTE_FILE_AMBIGUOUS`       two files serve one route; the repository's own router has to
  *                                pick, and a codemod that picks differently edits a dead page.
  *   `DIALECT_UNSUPPORTED`        the page is svelte / vue / html; nothing is written for it.
  *   `HELPER_CONFLICT`            `src/bcms-content.ts` is a module this package did not write.
  *   `SNAPSHOT_INVALID`           `bcms-content/<page>.json` is not JSON this can add `blocks` to.
+ *   `COPY_MODE_MISMATCH`         `--copy instance` was asked of a plan whose placements are all
+ *                                still bound to page field groups. @see ComponentizeOptions
+ *   `PROP_MAP_INCONSISTENT`      the plan's `fields[].path` is not `<one prefix> + fields[].key`,
+ *                                so a page path cannot be turned into a prop key losslessly.
+ *   `DUPLICATE_FIELD_BINDING`    one element in the section carries more than one
+ *                                `data-bcms-field`, and there is no single address to rewrite.
+ *   `INLINE_NEEDS_INSTANCE`      the page cannot be looped, and the in-place call site the codemod
+ *                                would write carries no `blockId`/`overrides` — so a placement
+ *                                whose copy has MOVED could neither render nor address it.
+ *   `SECTION_UNMIGRATABLE`       an OLDER generated component at this section's path cannot be
+ *                                upgraded to the current format. @see migrateSections
  *   `NOT_IN_SOURCE`              no file we were given renders the group, or the route names no
  *                                page file this package can find.
  */
-type SectionPendingReason = "SECTION_ROOT_AMBIGUOUS" | "SECTION_NOT_CONTIGUOUS" | "SECTION_FREE_IDENTIFIERS" | "COMPONENT_CONFLICT" | "REGISTRY_CONFLICT" | "ROUTE_FILE_AMBIGUOUS" | "DIALECT_UNSUPPORTED" | "HELPER_CONFLICT" | "SNAPSHOT_INVALID" | "NOT_IN_SOURCE";
+type SectionPendingReason = "SECTION_ROOT_AMBIGUOUS" | "SECTION_NOT_CONTIGUOUS" | "SECTION_FREE_IDENTIFIERS" | "COMPONENT_CONFLICT" | "REGISTRY_CONFLICT" | "REGISTRY_UNREADABLE" | "ROUTE_FILE_AMBIGUOUS" | "DIALECT_UNSUPPORTED" | "HELPER_CONFLICT" | "SNAPSHOT_INVALID" | "COPY_MODE_MISMATCH" | "PROP_MAP_INCONSISTENT" | "DUPLICATE_FIELD_BINDING" | "INLINE_NEEDS_INSTANCE" | "SECTION_UNMIGRATABLE" | "NOT_IN_SOURCE";
 interface PendingSection {
     route: string;
     groupKey: string;
@@ -998,11 +1074,31 @@ interface SectionsReceipt {
      * account for every section of the plan if "done earlier" is a bucket of its own.
      */
     alreadyExtracted: number;
+    /**
+     * The repository ALREADY has the component: the page imports it, and the registry now names it.
+     *
+     * 🔴 ITS OWN BUCKET, AND ORTHOGONAL TO PLACEMENT. Nothing was written for these — the file was
+     * somebody's before this run and stays theirs — so counting them `extracted` would claim
+     * authorship of bytes this package never produced, and counting them `pending` would say the CMS
+     * has no component for a section it plainly does. Whether the page's call sites were then
+     * replaced by the loop is a separate question, answered by `extracted` for the sections this run
+     * did cut.
+     */
+    registered: number;
     pending: PendingSection[];
 }
 interface ComponentizeReceipt {
     /** The plan this run was made against, carried so a receipt can be matched to one. */
     planDigest: string;
+    /**
+     * Which copy model this run was asked for — the same word the server's receipt carries.
+     *
+     * It does NOT change the bytes of an extracted component: the lane an element declares is
+     * decided at render time from the placement's own props, so one file serves both. What it
+     * changes is what the run will accept — `"instance"` against a plan that moved no copy is
+     * `COPY_MODE_MISMATCH` — and what the registry's shipped fallback binds. @see bcmsFields
+     */
+    copy: "bind" | "instance";
     sections: SectionsReceipt;
     /** The component slugs this run wrote a file for, sorted. */
     components: string[];
@@ -1013,6 +1109,15 @@ interface ComponentizeReceipt {
      * that does not place them has done exactly what it was told.
      */
     planPending: number;
+    /**
+     * Facts about the repository that shaped this run — the same list the conversion receipt carries.
+     *
+     * A tsconfig this package cannot read declares no `paths` aliases as far as it is concerned, and
+     * THIS lane resolves a page's `<Hero />` through exactly those aliases: the section then reads as
+     * one the page does not import, and `SECTION_ROOT_AMBIGUOUS` names the wrong cause. The note is
+     * what points at the real one.
+     */
+    notes?: ReceiptNote[];
 }
 /** Raised when the receipt does not account for every section. Never caught inside this package. */
 declare class SectionInvariantError extends Error {
@@ -1030,9 +1135,27 @@ declare function assertSections(total: number, sections: SectionsReceipt): Secti
 interface ComponentizeOptions {
     /** Replace a helper module this package did not write, instead of refusing. The CLI's flag. */
     overwriteHelper?: boolean;
+    /**
+     * WHICH COPY MODEL THE OPERATOR MEANT — `"bind"` (Phase A, the default) or `"instance"`.
+     *
+     * 🔴 AN ASSERTION, NOT A SWITCH. The extracted files are identical either way, so this flag
+     * exists to catch the order-of-operations mistake that would otherwise be silent: running
+     * `--copy instance` 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 are all still bound says so, and the run refuses by name.
+     */
+    copy?: "bind" | "instance";
 }
-/** The marker that says a file is OURS. Idempotence is decided on it, never on a path. */
-declare const SECTION_MARKER = "// @bettercms-ai/convert section v1";
+/**
+ * The marker that says a file is OURS — and WHICH FORMAT it is in.
+ *
+ * 🔴 THE VERSION IS LOAD-BEARING, NOT DECORATION. Idempotence is decided on this marker, so a v1
+ * component (0.3: page-path bindings, no render-time lane) read as "already ours, nothing to do"
+ * was skipped forever — every repository converted before Phase B stayed on the page lane, and
+ * `--copy instance` there reported five sections done and moved no address at all. A format change
+ * bumps the version, and anything older is MIGRATED before it is called done. @see migrateSections
+ */
+declare const SECTION_MARKER = "// @bettercms-ai/convert section v2";
 /** The same, for the two modules that hold the registry rather than a section. */
 declare const REGISTRY_MARKER = "// @bettercms-ai/convert sections v1";
 /** Where the generated components live. Fixed, so a second run knows its own output on sight. */
@@ -1126,4 +1249,4 @@ declare function convertSources(briefIn: Brief, sources: SourceFile[], options?:
     receipt: ConversionReceipt;
 }>;
 
-export { type AstNode, type AttrBinding, type Brief, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type Dialect, type DynamicBinding, type FileDeclaration, type FindSitesResult, HELPER_PATH, HELPER_VERSION, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionsReceipt, type Site, type SiteWhere, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, type ValidationCode, ValidationError, aliasesFrom, assertReceipt, assertSections, attrsFor, briefDigest, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, findSites, findSitesTolerant, flat, helperSource, importsIn, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeOfFile, stripTags, walkAst };
+export { type AstNode, type AttrBinding, type Brief, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type DeclaredPath, type Dialect, type DynamicBinding, type FileDeclaration, type FindSitesResult, HELPER_PATH, HELPER_VERSION, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type ReceiptNote, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionsReceipt, type Site, type SiteWhere, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, type ValidationCode, ValidationError, aliasesFrom, assertReceipt, assertSections, attrsFor, briefDigest, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, findSites, findSitesTolerant, flat, helperSource, importsIn, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeOfFile, stripTags, unreadableConfigs, walkAst };