@bettercms-ai/convert 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -164,7 +164,11 @@ 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"
+/** One array declaration, two loops over it: the row this leaf belongs to has two homes. */
+ | "REPEATER_AMBIGUOUS"
+/** An image whose built url maps to no repository asset, or to more than one. */
+ | "IMAGE_ASSET_UNRESOLVED" | "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 {
@@ -712,7 +716,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 = 4;
+declare const HELPER_VERSION = 5;
 /** 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. */
@@ -739,6 +743,180 @@ declare function helperSource(dialect: Dialect): string;
  */
 declare function isKnownHelper(content: string, dialect: Dialect): number | null;
 
+/**
+ * Copy that lives in a DATA LITERAL beside the markup, rendered through `.map`.
+ *
+ * 🔴 THE SHAPE EVERY REAL TEMPLATE IS MADE OF. `deriveSchema` reads the BUILT page, so three cards
+ * come back as `features[0..2]` whatever produced them — but the repository does not render three
+ * `<article>`s, it renders
+ *
+ *     const features = [{ title: "…", text: "…" }, …];
+ *     … {features.map((feature, i) => <Card><h3>{feature.title}</h3>…</Card>)}
+ *
+ * The copy is in the FRONTMATTER, the markup renders an expression, and the matcher is blind to
+ * both by construction (a string in a program is a program's; an expression may not render at
+ * all). So every one of those leaves came back `NOT_IN_SOURCE` with the value in plain sight, and
+ * the loop lane never fired either — `emitRepeater` templates repeated SIBLINGS, and here there is
+ * exactly one element in the source.
+ *
+ * WHAT THIS WRITES, and why it is the smallest edit that works:
+ *
+ *     const features = bcmsRowsAs(bcmsHome, "features", [{ title: "…", text: "…" }, …],
+ *                                 { title: "h3-field", text: "p-field" });
+ *     … <h3 data-bcms-field={`features[${i}].h3-field`} data-bcms-kind="text">{feature.title}</h3>
+ *
+ * The ARRAY is read from the CMS and the ORIGINAL property names are kept, so not one byte of the
+ * markup's expressions changes: `feature.tone`, `feature.link` and every other property the brief
+ * never heard of keep working, which is what a template does with the half of a row that is
+ * styling rather than copy. @see bcmsRowsAs, which merges each CMS row over the row the template
+ * shipped with for exactly that reason.
+ *
+ * WHAT IT REFUSES, by name rather than by guessing: an identifier iterated in two places
+ * (`REPEATER_AMBIGUOUS` — one declaration, two loops, and nothing says which one the brief's rows
+ * came from), a property that reaches the markup through a component or a transform
+ * (`PROP_TARGET_NOT_FOUND` / `IN_EXPRESSION`), and a leaf nested one array deeper
+ * (`PROP_DRILLED_DEEP`).
+ */
+
+/** One brief leaf of one row of one group — the same identity `loops.ts` calls a member. */
+interface DataMember {
+    key: string;
+    path: string;
+    kind: string;
+    /** The copy this leaf renders today, whitespace-flattened as the matcher flattens it. */
+    literal: string;
+    /** The page this leaf belongs to. Its snapshot is what the rows are read from. */
+    slug: string;
+}
+/** A byte range to replace, or a point to insert at when `start === end`. */
+interface DataSplice {
+    start: number;
+    end: number;
+    text: string;
+}
+interface DataContext {
+    content: string;
+    parsed: ParsedFile;
+    dialect: Dialect;
+    /** The name `bcmsRowsAs` is imported under here. @see scope.ts */
+    rowsAs: string;
+    /** The name `bcms` is imported under here — the scalar lane's read. @see scope.ts */
+    read: string;
+    /** The identifier a page's snapshot is imported under in this file. @see scope.ts */
+    snapshotName: (slug: string) => string;
+    /** How this file reads its route parameter, on a dynamic route. Null off one. */
+    slug: string | null;
+}
+interface DataResult {
+    splices: DataSplice[];
+    /** Did anything here write a `bcms(…)` read, so the file has to import one? @see bindScalar */
+    usesRead: boolean;
+    /** Did anything here write a `bcmsRowsAs(…)` read? */
+    usesRows: boolean;
+    /** The page slugs whose snapshot this lane now reads, so the file imports them. */
+    slugs: string[];
+    /** Target keys this plan bound. */
+    bound: string[];
+    /** What the file now declares, as a shape and as the bytes that resolve it. @see RepeaterPlan */
+    declarations: {
+        path: string;
+        literal: string;
+    }[];
+    /** Target keys this plan could not bind, each with the reason it could not. */
+    refused: {
+        key: string;
+        reason: PendingReason;
+    }[];
+}
+/**
+ * Bind every repeater group whose copy lives in a data literal in this same file.
+ *
+ * `members` is every indexed brief leaf this file could not otherwise place; groups it cannot
+ * account for are returned in `refused` with the reason, and are never partially written — a group
+ * half bound is a row whose second field silently stops reflecting.
+ */
+declare function bindDataLiterals(ctx: DataContext, members: DataMember[]): DataResult;
+
+/**
+ * An image whose `original` is a BUILT url, and the import the template actually renders.
+ *
+ * 🔴 THE BRIEF CANNOT NAME THE FILE. `deriveSchema` reads the built page, where an asset the
+ * bundler processed is `/_astro/workspace.do77EGgx_ZNfVA8.jpg` — a name that exists nowhere in the
+ * repository, and whose EXTENSION is not even the source's (Astro serves the same `.jpg` as
+ * `.webp` on one route and `.avif` on the next). So `locate` found nothing, every such path came
+ * back `NOT_IN_SOURCE`, and an image was the one kind of field a converted site never had.
+ *
+ * What survives the build is the BASE NAME. `workspace.do77EGgx_ZNfVA8.jpg` and
+ * `workspace.do77EGgx_YzFJw.webp` are both `workspace`, and the page that renders them says so
+ * itself: `import workspaceImage from "../assets/workspace.jpg"`. The import is the evidence —
+ * it is in the file being converted, it names a real path, and the element that renders it names
+ * the binding — so nothing here has to guess at bytes the scanner never opened (an image is not a
+ * source candidate, so the asset file is not in `sources` at all). @see scan.ts
+ *
+ * Ambiguity is refused rather than resolved: two imports whose base names both match, or an import
+ * nothing renders, is `IMAGE_ASSET_UNRESOLVED`.
+ */
+
+/** One image target: a path whose value is a url and whose element renders an imported asset. */
+interface ImageTarget {
+    key: string;
+    path: string;
+    kind: string;
+    /** The brief's `original` — the BUILT url. */
+    original: string;
+    slug: string;
+}
+interface ImageSplice {
+    start: number;
+    end: number;
+    text: string;
+}
+interface ImageContext {
+    content: string;
+    parsed: ParsedFile;
+    dialect: Dialect;
+    /** The name `bcmsImage` is imported under here. @see scope.ts */
+    image: string;
+    snapshotName: (slug: string) => string;
+    /** How this file reads its route parameter, on a dynamic route. Null off one. */
+    slug: string | null;
+}
+interface ImageResult {
+    splices: ImageSplice[];
+    slugs: string[];
+    bound: string[];
+    refused: {
+        key: string;
+        reason: "IMAGE_ASSET_UNRESOLVED";
+    }[];
+}
+/**
+ * Which local binding this built url came from, or null when nothing here says.
+ *
+ * Exported because the CALLER has to answer the same question one step earlier: an image path is
+ * unlocated by construction, so the file that renders it is found by asking every candidate page
+ * file whether it imports the asset. @see convertSources
+ */
+declare function assetCandidates(parsed: ParsedFile, dialect: Dialect, original: string): string[];
+/**
+ * The ONE binding, or null — which covers both "nothing matched" and "two did".
+ *
+ * 🔴 THE CALLER HAS TO TELL THOSE APART, which is why `assetCandidates` is the exported one.
+ * Collapsing them here made the ambiguous case indistinguishable from the absent one, and a
+ * repository holding `assets/team/hero.jpg` beside `assets/blog/hero.png` — a base name this
+ * cannot separate from one built url — reported `NOT_IN_SOURCE`, which is the opposite of the
+ * truth: the source has two of them.
+ */
+declare function assetImport(parsed: ParsedFile, dialect: Dialect, original: string): string | null;
+/**
+ * Bind every image path whose asset this file imports.
+ *
+ * The element's `src` becomes `bcmsImage(page, "<path>", <binding>)` — the CMS url when there is
+ * one, the import the bundler already optimised when there is not — so a build against the
+ * committed `{}` stub renders exactly the image the repository renders today.
+ */
+declare function bindImages(ctx: ImageContext, targets: ImageTarget[]): ImageResult;
+
 /** The recipe an Astro site needs instead — never auto-migrate a site to SSR. */
 declare const SSR_DRAFT_RECIPE: string;
 interface CanvasSource {
@@ -1292,4 +1470,4 @@ declare function convertSources(briefIn: Brief, sources: SourceFile[], options?:
     receipt: ConversionReceipt;
 }>;
 
-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 };
+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 DataMember, type DataResult, type DeclaredPath, type Dialect, type DynamicBinding, type FileDeclaration, type FindSitesResult, HELPER_PATH, HELPER_VERSION, type ImageResult, type ImageTarget, 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, assetCandidates, assetImport, attrsFor, bindDataLiterals, bindImages, 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 };