@bettercms-ai/convert 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -164,7 +164,9 @@ declare function locate(brief: BriefLike, sources: SourceFile[], options?: Locat
  * sentence appears in three files" and "this field is bound" are different questions — and a path
  * is only `rewritten` when EVERY located occurrence of it was.
  */
-type PendingReason = "NO_ORIGINAL" | "NOT_IN_SOURCE" | "DIALECT_UNSUPPORTED" | "IN_EXPRESSION" | "IN_SCRIPT_OR_COMMENT" | "IN_DATA_FILE" | "AMBIGUOUS_LITERAL" | "KIND_MISMATCH" | "SUBSTRING_ONLY" | "PROP_TARGET_NOT_FOUND" | "PROP_DRILLED_DEEP" | "REPEATER_FIXED_LENGTH" | "DYNAMIC_PARAMS_UNAVAILABLE" | "BRIEF_META_UNPLACED" | "PARSE_ERROR" | "TIER3_UNVERIFIABLE";
+type PendingReason = "NO_ORIGINAL" | "NOT_IN_SOURCE" | "DIALECT_UNSUPPORTED" | "IN_EXPRESSION" | "IN_SCRIPT_OR_COMMENT" | "IN_DATA_FILE" | "AMBIGUOUS_LITERAL" | "KIND_MISMATCH" | "SUBSTRING_ONLY" | "PROP_TARGET_NOT_FOUND" | "PROP_DRILLED_DEEP" | "REPEATER_FIXED_LENGTH" | "DYNAMIC_PARAMS_UNAVAILABLE" | "BRIEF_META_UNPLACED" | "PARSE_ERROR" | "TIER3_UNVERIFIABLE"
+/** @see CANVAS_REASONS — these two are about the SITE's live-preview lane, not a brief path. */
+ | "CANVAS_BRIDGE_MANUAL" | "SSR_DRAFT_ROUTE";
 interface PendingPath {
     route: string;
     scope: "page" | "layout";
@@ -174,6 +176,10 @@ interface PendingPath {
     file?: string;
     reason: PendingReason;
     message?: string;
+    /** 1-based line in `file`, when the reason points at one place a human has to go. */
+    line?: number;
+    /** What to do about it, in prose — a recipe, not a diagnosis. @see message */
+    hint?: string;
 }
 /**
  * One path that was already DECLARED before this run — and how honestly.
@@ -237,6 +243,14 @@ interface ConversionReceipt {
     dynamicBindings: DynamicBinding[];
     /** Facts about the repository that shaped this run. OPTIONAL: an older receipt carries none. */
     notes?: ReceiptNote[];
+    /**
+     * Can the visual editor push drafts to this site? OPTIONAL: an older receipt carries none, and a
+     * reader must treat absent as unknown rather than as `"pending"`.
+     */
+    canvas?: {
+        lane: "bridge" | "pending";
+        files?: string[];
+    };
 }
 /**
  * One binding whose `data-bcms-field` is an expression, and where its value is written literally.
@@ -698,7 +712,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. */
@@ -725,6 +739,35 @@ declare function helperSource(dialect: Dialect): string;
  */
 declare function isKnownHelper(content: string, dialect: Dialect): number | null;
 
+/** The recipe an Astro site needs instead — never auto-migrate a site to SSR. */
+declare const SSR_DRAFT_RECIPE: string;
+interface CanvasSource {
+    path: string;
+    content: string;
+    /** The babel AST from `parseFile("jsx", …)`. Absent for every non-jsx dialect. */
+    ast?: unknown;
+}
+interface CanvasResult {
+    lane: "bridge" | "pending";
+    /** Files the bridge was installed in. */
+    files: string[];
+    /** Rewritten contents, by path. Empty when the lane is pending. */
+    edits: Map<string, string>;
+    pending: PendingPath[];
+}
+/**
+ * The one row every Astro conversion carries. Exported so a test names it instead of restating it.
+ */
+declare const ASTRO_LANE_PENDING: PendingPath;
+/**
+ * Install the draft bridge, or say why not.
+ *
+ * `routes` maps a brief route (`/about`) to its slug, so a route written as a literal in the page
+ * can name itself. An Astro project is refused wholesale: bridging it needs a server render, which
+ * is a deploy-shaped decision and never a codemod's.
+ */
+declare function canvasBridge(sources: CanvasSource[], routes: Map<string, string>): CanvasResult;
+
 /**
  * Which files in a repository can possibly render a page's copy.
  *
@@ -979,6 +1022,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;
@@ -1024,10 +1076,21 @@ interface ComponentizePlan {
  *   `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" | "REGISTRY_UNREADABLE" | "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;
@@ -1070,6 +1133,15 @@ interface SectionsReceipt {
 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[];
@@ -1106,9 +1178,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. */
@@ -1202,4 +1292,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 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 };
+export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type Brief, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type CanvasResult, type CanvasSource, 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, SSR_DRAFT_RECIPE, 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, canvasBridge, 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 };