@bettercms-ai/convert 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -285,12 +285,31 @@ interface AttrNode {
     expression: boolean;
     /** The whole `name="value"` span, so an attribute can be replaced outright. */
     range: Range;
+    /**
+     * The braces of an expression-valued attribute, `{` and `}` included. Null when there are none.
+     *
+     * 🔴 `range` IS NOT THE EXPRESSION FOR A SHORTHAND. Astro reports `{title}` and `{...props}` at
+     * the offset of the IDENTIFIER, four characters into the spread — so a reader that looked for the
+     * first `{` inside `range` found none and concluded the attribute held no code. The section then
+     * travelled without whatever `title` was, into a component file that does not build. Every parser
+     * that has an expression says where it starts, rather than leaving each reader to scan for it.
+     */
+    expressionRange: Range | null;
 }
 type Node = {
     type: "element";
     tag: string;
     /** The `<` of the open tag. */
     start: number;
+    /**
+     * One past the element's LAST byte — the `>` of `</section>`, or of `<img … />`.
+     *
+     * Carried because the componentize lane lifts a whole element out of a page and into a file
+     * of its own: `start` and `inner` describe where a value goes, and neither says where the
+     * subtree stops. Recomputing it from `inner.end + "</tag>".length` would assume the closing
+     * tag holds no whitespace, and every parser here already reports the real end.
+     */
+    end: number;
     /** Where an attribute may be inserted: after the last attribute, before `/` and `>`. */
     attrInsertAt: number;
     /** Everything between the tags. Null for void and self-closing elements. */
@@ -634,7 +653,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 = 2;
+declare const HELPER_VERSION = 3;
 /** 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. */
@@ -698,8 +717,17 @@ declare function resolveSpecifier(fromFile: string, specifier: string, files: Se
 /** What one local name was imported from, and WHICH export of it. */
 interface ImportedFrom {
     specifier: string;
-    /** The exported name, or null for a default import. */
+    /** The exported name, or null for a default OR namespace import. @see kind */
     imported: string | null;
+    /**
+     * WHICH OF THE THREE, because they are three different statements to write back.
+     *
+     * 🔴 A NAMESPACE IMPORT IS NOT A NAMED ONE. `import * as Icons from "./icons"` was recorded with
+     * `imported: "Icons"` — the local name, because babel reports no `imported` for it — so a lane
+     * re-emitting the import wrote `import { Icons } from "./icons"`, which binds a named export
+     * nobody declared and fails at build. The distinction is on the specifier node; it is kept.
+     */
+    kind: "default" | "named" | "namespace";
 }
 /**
  * Local name → what it was imported from, for one file.
@@ -802,6 +830,268 @@ interface FileDeclaration {
 /** Every path one file declares, with the lane it declares it on. */
 declare function readDeclarations(file: string, content: string): Promise<FileDeclaration[]>;
 
+/**
+ * A dynamic route reads ITS OWN entry, and the route parameter is how it says which.
+ *
+ * 🔴 WITHOUT THE PARAMETER THE PAGE IS WRONG, NOT INCOMPLETE. `bcms(page, "title", "…")` on
+ * `[slug].astro` resolves the same value for every URL the route serves, so a hundred posts render
+ * the first post's title — a conversion that builds, passes every attribute check, and is visibly
+ * broken. So a dynamic route either gets its parameter or reports `DYNAMIC_PARAMS_UNAVAILABLE`
+ * and stays as it was.
+ *
+ * Astro hands it over for free (`Astro.params`). Next does not: `params` is an argument to the
+ * page component, so the SIGNATURE has to be edited — and on Next 15 `params` is a promise, which
+ * is why an already-`async` component gets `(await params).slug` and a synchronous one does not.
+ */
+
+/** `src/pages/[slug].astro`, `app/blog/[slug]/page.tsx` — a segment in brackets. */
+declare const isDynamicRoute: (file: string) => boolean;
+/**
+ * Which route does this FILE serve, or null when it is not a page at all.
+ *
+ * 🔴 A ROUTE IS NOT A FILE, AND IT IS NOT A SEARCH EITHER. Picking the page by "which file mentions
+ * this field group" reads whichever file holds the most matches — and a `hero` group is on every
+ * landing page, so `/about`'s sections were resolved against `/`'s file and one route's codemod
+ * rewrote another route's page. The router's own convention answers the question the route is
+ * actually asking.
+ *
+ * Every framework this package converts is here, including the two it cannot extract from
+ * (SvelteKit, Nuxt) — a page it can NAME is a page it can refuse by dialect, and a page it cannot
+ * name is `NOT_IN_SOURCE`, which are different facts.
+ */
+declare function routeOfFile(file: string): string | null;
+/**
+ * Every file that serves this route, in path order.
+ *
+ * More than one is not a tie to break: two files claiming one URL is a repository whose own router
+ * has to pick, and a codemod that picks differently edits a page nobody serves.
+ */
+declare function pageFilesFor(route: string, files: Iterable<string>): string[];
+
+type Element = Extract<Node, {
+    type: "element";
+}>;
+interface Carried {
+    /** `import Card from "../Card.astro";` — the page's own imports, re-based onto the new file. */
+    imports: string[];
+    /** Module-scope statements the markup depends on, in the page's own source order. */
+    declarations: string[];
+    /** Names nothing can account for. Non-empty means the section is refused, not written. */
+    free: string[];
+}
+/**
+ * Everything one section root needs, resolved against the page it is leaving.
+ *
+ * `provided` is what the component file declares for itself — its props, the snapshot local it
+ * redeclares, and the helper names it imports — so those are never carried and never free.
+ */
+declare function carryFor(options: {
+    dialect: Dialect;
+    fromFile: string;
+    toFile: string;
+    content: string;
+    parsed: ParsedFile;
+    root: Element;
+    provided: Iterable<string>;
+    /** Repository paths that must never be carried as an import — the helper, the snapshots. */
+    skipSpecifier: (repoPath: string, specifier: string) => boolean;
+}): Carried;
+
+/**
+ * The plan, as `get_componentize_plan` returns it.
+ *
+ * READ DEFENSIVELY. A newer server may carry fields this version has never heard of, and the
+ * customer runs whichever `npx @bettercms-ai/convert` npm hands them — so every field this module
+ * does not need is `unknown`, every field it does need is optional with a stated fallback, and
+ * an unexpected extra key is simply carried past. The shape is frozen; the reader is not brittle.
+ */
+interface ComponentizePlanField {
+    /** The leaf's key inside the group — `title`, `items[0].q`. */
+    key?: string;
+    /** The whole page path — `hero.title`. Derived from `groupKey` + `key` when absent. */
+    path?: string;
+    type?: string;
+    label?: string;
+    current?: unknown;
+}
+interface ComponentizePlanSection {
+    groupKey: string;
+    sectionType?: string;
+    label?: string;
+    order?: number;
+    shapeHash?: string;
+    fields?: ComponentizePlanField[];
+    /** Which component renders this placement — a proposed one, or one the project already has. */
+    reuse?: {
+        componentId?: string;
+        proposedSlug?: string;
+    };
+    /** The SERVER already decided it cannot place this one. Not this codemod's to extract. */
+    pending?: {
+        reason?: string;
+    };
+}
+interface ComponentizePlanPage {
+    pageId?: string;
+    route: string;
+    sections?: ComponentizePlanSection[];
+}
+interface ComponentizePlanComponent {
+    proposedSlug: string;
+    /** Present when the plan reuses a component the project already has. */
+    componentId?: string;
+    sectionType?: string;
+    name?: string;
+    category?: string;
+    placements?: number;
+}
+interface ComponentizePlan {
+    pages: ComponentizePlanPage[];
+    components?: ComponentizePlanComponent[];
+    digest?: string;
+}
+/**
+ * Why a section is not a component in this repository.
+ *
+ * Every one of them is a fact about the SOURCE rather than an apology:
+ *   `SECTION_ROOT_AMBIGUOUS`     its fields do not sit under one element, or two sections nest.
+ *   `SECTION_NOT_CONTIGUOUS`     the page's section roots do not share a container at all. The
+ *                                component IS written; the page is left exactly as it was.
+ *   `SECTION_FREE_IDENTIFIERS`   the markup uses a name the component file cannot be given — a
+ *                                local of the page's own component body, or an expression this
+ *                                version cannot read.
+ *   `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.
+ *   `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.
+ *   `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";
+interface PendingSection {
+    route: string;
+    groupKey: string;
+    reason: SectionPendingReason;
+    /** What exactly could not be done. Informative; the reason is the contract. */
+    message?: string;
+}
+interface SectionsReceipt {
+    /** Component written AND the page's run replaced by `<Sections page="…" />`. */
+    extracted: number;
+    /**
+     * Component written, but the page keeps CALLING it in place.
+     *
+     * The run was not contiguous — a sibling that belongs to no section sits between two roots — so
+     * a loop over `pageSections()` would silently reorder the page. Each root becomes its own
+     * `<Hero …/>` instead: the markup is componentised, the ORDER stays the repository's.
+     */
+    inlineOnly: number;
+    /**
+     * Already ours, from a previous run — its fields now live in a file carrying our marker.
+     *
+     * 🔴 ITS OWN BUCKET, NOT `extracted`. The round trip has to be observable: a second run over an
+     * already-componentised tree reports `extracted: 0, pending: []`, and it can only do that AND
+     * account for every section of the plan if "done earlier" is a bucket of its own.
+     */
+    alreadyExtracted: number;
+    pending: PendingSection[];
+}
+interface ComponentizeReceipt {
+    /** The plan this run was made against, carried so a receipt can be matched to one. */
+    planDigest: string;
+    sections: SectionsReceipt;
+    /** The component slugs this run wrote a file for, sorted. */
+    components: string[];
+    /**
+     * Sections the SERVER already marked pending (`NO_GROUP_ROOT`, `ALREADY_COMPONENTIZED`, …).
+     *
+     * Outside the arithmetic below on purpose: the plan says they are not to be placed, so a repo
+     * that does not place them has done exactly what it was told.
+     */
+    planPending: number;
+}
+/** Raised when the receipt does not account for every section. Never caught inside this package. */
+declare class SectionInvariantError extends Error {
+    readonly code = "SECTION_INVARIANT";
+    constructor(message: string);
+}
+/**
+ * The invariant, checked where the receipt is built.
+ *
+ * A section in none of the buckets is a section the codemod forgot, and forgetting is the failure
+ * this whole lane exists to make impossible — the same reasoning, and the same shape, as P2's
+ * `assertReceipt`.
+ */
+declare function assertSections(total: number, sections: SectionsReceipt): SectionsReceipt;
+interface ComponentizeOptions {
+    /** Replace a helper module this package did not write, instead of refusing. The CLI's flag. */
+    overwriteHelper?: boolean;
+}
+/** 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 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. */
+declare const COMPONENT_DIR = "src/components/bcms";
+/** The module that reads `blocks` out of the committed snapshots. */
+declare const SECTIONS_LIB = "src/lib/bcms-sections.ts";
+declare function componentizeSources(briefIn: Brief, planIn: ComponentizePlan, sources: SourceFile[], options?: ComponentizeOptions): Promise<{
+    files: PlanFile[];
+    receipt: ComponentizeReceipt;
+}>;
+/**
+ * The plan, checked at INGRESS.
+ *
+ * Every value the codemod turns into a path or writes into generated source is validated before it
+ * can reach either — `../package` as a page slug is a `package.json` this would have overwritten.
+ * @see validate.ts
+ */
+declare function readComponentizePlan(value: unknown): ComponentizePlan;
+
+/**
+ * The brief and the plan, checked at INGRESS — before a single byte is written.
+ *
+ * 🔴 A SLUG FROM THE WIRE BECOMES A PATH ON DISK. `bcms-content/<page.slug>.json` is composed from
+ * a string this package did not choose: a page slugged `../package` names the repository's own
+ * `package.json`, and the codemod would have written `{"blocks": []}` over it. The CLI's `--root`
+ * check catches an escape out of the tree; it cannot catch an escape WITHIN it, because the target
+ * is still under `--root`. So the value is refused where it enters, not where it is used.
+ *
+ * The same reasoning covers `groupKey` and `proposedSlug`: both are written into generated source
+ * as object keys and one of them decides a component's file name.
+ *
+ * NO ZOD. This package ships to `npx` in somebody else's repository and its dependency list is the
+ * five parsers; a validator for two known shapes is forty lines, and forty lines is cheaper than a
+ * dependency in every install. The checks are the ones zod would express: a type per field, a
+ * pattern per string that becomes a path, and a refusal that names the field it refused.
+ */
+
+type ValidationCode = "BRIEF_INVALID" | "PLAN_INVALID";
+/** Raised at ingress. The run is refused whole: nothing is written on a value this cannot trust. */
+declare class ValidationError extends Error {
+    readonly code: ValidationCode;
+    constructor(code: ValidationCode, message: string);
+}
+/**
+ * The brief, checked for everything the codemod reads off it.
+ *
+ * `slug` is the one that becomes a path. `route` is matched against the plan's and against the
+ * router's own conventions, so it has to be a URL path rather than an arbitrary string.
+ */
+declare function readBrief(value: unknown): Brief;
+/**
+ * The plan, checked for everything the codemod reads off it.
+ *
+ * PERMISSIVE ABOUT SHAPE, STRICT ABOUT VALUES: a newer server may add fields, and an unknown key
+ * is carried past untouched — but every field this version actually consumes is typed, and the two
+ * that become file names or source keys are `groupKey` and `proposedSlug`.
+ */
+declare function readPlan(value: unknown): ComponentizePlan;
+
 /** One file operation, exactly as `src/lib/github/plan-digest.ts` spells it. */
 interface PlanFile {
     path: string;
@@ -831,9 +1121,9 @@ interface Splice {
     end: number;
     text: string;
 }
-declare function convertSources(brief: Brief, sources: SourceFile[], options?: ConvertOptions): Promise<{
+declare function convertSources(briefIn: Brief, sources: SourceFile[], options?: ConvertOptions): Promise<{
     files: PlanFile[];
     receipt: ConversionReceipt;
 }>;
 
-export { type AstNode, type AttrBinding, type Brief, type BriefPage, type BriefPath, CONTENT_DIR, 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 PlanFile, type ReceiptFile, ReceiptInvariantError, type Rewrite, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, STUB_CONTENT, type Site, type SiteWhere, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, aliasesFrom, assertReceipt, attrsFor, briefDigest, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, findSites, findSitesTolerant, flat, helperSource, importsIn, isKnownHelper, isSourceCandidate, locate, overlapping, parseFile, propsAttribute, readDeclarations, readExpr, relativeImport, resolveSpecifier, rewriteFile, 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 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 };