@bettercms-ai/convert 0.22.0 → 0.24.0

package/dist/index.d.ts

@@ -955,7 +955,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 = 11;
+declare const HELPER_VERSION = 12;
 /** 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. */
@@ -981,6 +981,22 @@ declare function helperSource(dialect: Dialect): string;
  * treats them the same way, because it cannot tell them apart and must not overwrite either.
  */
 declare function isKnownHelper(content: string, dialect: Dialect): number | null;
+/** One committed helper a build may replace: where it lives, what replaces it, and which bytes qualify. */
+interface HelperUpgrade {
+    path: string;
+    source: string;
+    /** sha256 of every OLDER helper this package wrote at `path`. Anything else is left alone. */
+    digests: string[];
+}
+/**
+ * What a BetterCMS build swaps in for a helper this package wrote at an older version.
+ *
+ * The hosting builder applies these to its own throwaway checkout — never to the repository — so a
+ * site converted before the helper read published content at request time gets that reader on its
+ * next build, with no commit and no codemod run. The rule is `isKnownHelper`'s: only bytes this
+ * package produced are replaced, so an edited or foreign module at the same path is never touched.
+ */
+declare function helperUpgrades(): HelperUpgrade[];
 
 /**
  * The submit runtime, LIFTED VERBATIM from `src/lib/sites/render-page.ts` `FORM_SCRIPT`.
@@ -1837,6 +1853,84 @@ declare function readBrief(value: unknown): Brief;
  */
 declare function readPlan(value: unknown): ComponentizePlan;
 
+/** The plan's own file shape, restated rather than imported to keep `index.ts` acyclic. */
+interface UpgradeFile {
+    path: string;
+    operation: "modify" | "add";
+    content: string;
+}
+/** Why a root was left without the marker. */
+type UpgradeSkipReason = 
+/** The root has its own `style` attribute; a second one would be resolved by the dialect. */
+"OWN_STYLE"
+/** The root has a spread (`{...rest}`) that may carry a style. */
+ | "SPREAD"
+/** Only a block ID reaches the root (`{Astro.props.bcmsBlock}`, `{id}`): its style is not in scope. */
+ | "BLOCK_ID_ONLY"
+/** `data-bcms-block="abc"`: a literal id, with no block object behind it. */
+ | "BLOCK_LITERAL"
+/** A call, a conditional, anything that does not name one block. */
+ | "BLOCK_UNRESOLVABLE"
+/** `data-bcms-block` on a component tag is a prop, not an element the editor can find. */
+ | "NOT_AN_ELEMENT"
+/** A dialect this pass does not rewrite (html, vue, svelte). */
+ | "DIALECT_UNSUPPORTED"
+/** The name this pass would introduce is already something else in the file. */
+ | "NAME_TAKEN"
+/** A generated section whose registry or `bcms-sections` no longer has the shape it can patch. */
+ | "REGISTRY_UNRECOGNISED"
+/** The file did not parse. */
+ | "PARSE_ERROR";
+interface UpgradeRootRef {
+    file: string;
+    /** 1-based line of the root's `<`. */
+    line: number;
+    tag: string;
+    /** What `data-bcms-block` was given, as written: `{blockId}`, `"abc"`. */
+    block: string;
+}
+interface UpgradedRoot extends UpgradeRootRef {
+    form: "section-prop" | "sectionRootAttrs" | "helper";
+}
+interface SkippedRoot extends UpgradeRootRef {
+    reason: UpgradeSkipReason;
+    message: string;
+}
+interface SectionUpgradeReceipt {
+    /** The helper at `src/bcms-content.ts` (and its siblings), when there is one or this pass wrote one. */
+    helpers: {
+        path: string;
+        from: number | null;
+        to: number;
+        operation: "add" | "modify" | "unchanged" | "foreign";
+    }[];
+    /** Generated registry / `bcms-sections` modules patched to hand `block.style` down. */
+    registry: {
+        path: string;
+        operation: "modify" | "unchanged";
+    }[];
+    roots: {
+        upgraded: UpgradedRoot[];
+        alreadyMarked: UpgradeRootRef[];
+        skipped: SkippedRoot[];
+    };
+}
+interface UpgradeOptions {
+    /** Replace a helper module this package did not write, when a root needs the helper. */
+    overwriteHelper?: boolean;
+    /** The repository's root `package.json`, to tell whether its SDK exports `sectionRootAttrs`. */
+    packageJson?: string;
+}
+/** Thrown, like `convertSources`, when the helper is needed and is not ours to replace. */
+declare class UpgradeError extends Error {
+    readonly code = "HELPER_CONFLICT";
+    constructor(message: string);
+}
+declare function upgradeSections(sources: readonly SourceFile[], options?: UpgradeOptions): Promise<{
+    files: UpgradeFile[];
+    receipt: SectionUpgradeReceipt;
+}>;
+
 /** One file operation, exactly as `src/lib/github/plan-digest.ts` spells it. */
 interface PlanFile {
     path: string;
@@ -1871,4 +1965,4 @@ declare function convertSources(briefIn: Brief, sources: SourceFile[], options?:
     receipt: ConversionReceipt;
 }>;
 
-export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type Brief, type BriefForm, 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, FORM_SCRIPT, type FileDeclaration, type FindSitesResult, type FixAction, FormInvariantError, type FormPendingReason, type FormsReceipt, 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 PendingFix, type PendingForm, 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, type Xray, type XrayBucket, aliasesFrom, assertForms, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findLiteral, findSites, findSitesTolerant, fixFor, flat, helperSource, importsIn, isDecorativeGlyph, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, measureUnaddressable, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeCounts, routeOfFile, stripTags, unreadableConfigs, walkAst, wireForms };
+export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type Brief, type BriefForm, 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, FORM_SCRIPT, type FileDeclaration, type FindSitesResult, type FixAction, FormInvariantError, type FormPendingReason, type FormsReceipt, HELPER_PATH, HELPER_VERSION, type HelperUpgrade, type ImageResult, type ImageTarget, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingFix, type PendingForm, 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 SectionUpgradeReceipt, type SectionsReceipt, type Site, type SiteWhere, type SkippedRoot, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, UpgradeError, type UpgradeOptions, type UpgradeRootRef, type UpgradeSkipReason, type UpgradedRoot, type ValidationCode, ValidationError, type Xray, type XrayBucket, aliasesFrom, assertForms, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findLiteral, findSites, findSitesTolerant, fixFor, flat, helperSource, helperUpgrades, importsIn, isDecorativeGlyph, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, measureUnaddressable, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeCounts, routeOfFile, stripTags, unreadableConfigs, upgradeSections, walkAst, wireForms };