@bettercms-ai/convert 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,839 @@
+import { BindingKind } from '@bettercms-ai/types';
+
+/**
+ * Where the BUILT element that carried this value sat, so a duplicate literal can be resolved
+ * by position rather than by guessing.
+ *
+ * Best-effort by construction: built-DOM positions do not survive component expansion, wrappers
+ * or conditional rendering, so `ancestors` is compared as a SUBSEQUENCE of the source element's
+ * tag chain and any mismatch falls to `AMBIGUOUS_LITERAL` rather than to a coin flip.
+ */
+interface PathLocator {
+    /** Tag names from the nearest landmark down to the element's parent, outermost first. */
+    ancestors: string[];
+    /** The element's index among its ELEMENT siblings. */
+    siblingIndex: number;
+    /** Set when the element is one member of a derived repeater group. */
+    repeat?: {
+        groupKey: string;
+        index: number;
+    };
+}
+interface BriefPath {
+    /** The `data-bcms-field` value, in the editor's grammar (`hero.title`, `facts[2].label`). */
+    path: string;
+    /**
+     * PAGE or LAYOUT, and the difference is an attribute, a helper and an identity.
+     *
+     * A value the derive lane found identical on every route is the shared chrome — a header, a
+     * footer — and it is ONE field, not one per page. It is read with `bcmsLayout` and declared on
+     * `data-bcms-layout-field`, the separate attribute the chrome lane already carries
+     * (`src/lib/sites/render-page.ts`), so the block lane's own `[data-bcms-field]` query cannot
+     * reach it. Absent means `"page"`: a brief written before the distinction existed still means
+     * what it said.
+     */
+    scope?: "page" | "layout";
+    /** `data-bcms-kind` — "text" | "richtext" | "image", as `kindOf` spells it. */
+    kind: string;
+    /** The declared field type, which `kind` deliberately loses (richtext vs document). */
+    type: string;
+    label: string;
+    /** The copy the REPO renders today. Null when the import captured no default. */
+    original: string | null;
+    /** What the CMS holds now. */
+    current: string;
+    truncated?: true;
+    locator?: PathLocator;
+}
+interface BriefPage {
+    slug: string;
+    /** The URL the built site serves this page at. */
+    route: string;
+    title?: string;
+    paths: BriefPath[];
+    pathsOmitted?: number;
+}
+/** Only what the codemod reads. A backend `ConversionBrief` satisfies it. */
+interface Brief {
+    pages: BriefPage[];
+}
+/**
+ * The name of one brief — `(route, path, kind, original)` for every page, hashed.
+ *
+ * Identity, not integrity: the receipt carries it so a coverage meter can say "this conversion
+ * was run against THAT list of paths" and refuse to compare against a re-derived one. Labels and
+ * `current` values are excluded because an edit in the dashboard changes them without changing
+ * what there is to convert. So is SCOPE: a field that moves from page to layout is the same field
+ * with the same copy, and the pin carries each path's scope separately where it is actually read.
+ *
+ * 🔴 BYTE-FOR-BYTE `src/lib/content/brief-digest.ts`. The codemod runs on the customer's machine
+ * and the server computes the same name for the same brief; the pin is keyed by it and the
+ * receipt carries it, so a disagreement makes every receipt stop matching its pin and the
+ * coverage meter read zero forever. `brief-digest.test.ts` pins both against one literal hash.
+ */
+declare function briefDigest(brief: Brief): string;
+
+/**
+ * Where in the source does each of the brief's paths actually appear?
+ *
+ * Moved here verbatim from `src/lib/conversion/propose.ts`, which now re-exports it: the proposer
+ * checks "did the conversion bind every path in every file that renders it", and the codemod
+ * decides which files to open. A second implementation of "where does this string appear" would
+ * drift from the first silently, and the failure it produces is a proposal refused for not binding
+ * a path in a file the other half never asked it to touch.
+ */
+/** One file as it was read. Same shape the proposer's `SourceFile` has. */
+interface SourceFile {
+    path: string;
+    content: string;
+}
+/** A brief path whose `original` was found verbatim in the source. */
+interface LocatedPath {
+    route: string;
+    /** Page or shared chrome — half of the `(route, scope, path)` identity. @see brief.ts */
+    scope?: "page" | "layout";
+    path: string;
+    kind: string;
+    /** The whitespace-normalised copy that was matched. */
+    original: string;
+    /** Every source file that renders it. A value rendered twice must be bound twice. */
+    files: string[];
+}
+/** A brief path the source does not appear to render, with the reason it could not be placed. */
+interface UnlocatedPath {
+    route: string;
+    scope?: "page" | "layout";
+    path: string;
+    reason: "no-original" | "not-in-source";
+}
+/**
+ * Collapse whitespace for comparison.
+ *
+ * The same normalisation the annotator and the live-editor matcher use. A template wraps its copy
+ * across lines and indents it; the CMS holds one line. Comparing raw bytes would find nothing on a
+ * correctly formatted file, which is every file.
+ */
+declare const flat: (value: string) => string;
+/** The same text with tags removed — what a reader sees, not what the file says. */
+declare const stripTags: (value: string) => string;
+interface BriefLike {
+    pages: {
+        route: string;
+        paths: {
+            path: string;
+            kind: string;
+            original: string | null;
+            scope?: "page" | "layout";
+        }[];
+    }[];
+}
+interface LocateOptions {
+    /**
+     * Also match a path whose original is the element's TEXT rather than its markup.
+     *
+     * A richtext field's brief `original` is the first block's text — `Read this now` — while the
+     * template says `Read <strong>this</strong> now`. A literal search finds nothing, which is the
+     * right answer for the proposer (it must not demand a binding for a string it cannot point at)
+     * and the wrong one for the codemod, which can see the element. OFF by default so the moved
+     * implementation keeps its exact previous behaviour for `propose.ts`.
+     */
+    stripTags?: boolean;
+}
+/**
+ * Split the brief's paths into the ones the source renders and the ones it does not.
+ *
+ * Exported because the generator needs the SAME answer: the transformer is told which originals
+ * live in which file, and a second implementation of "where does this string appear" would drift
+ * from this one silently — the model would then be asked to bind a path in a file this module has
+ * already decided does not render it.
+ */
+declare function locate(brief: BriefLike, sources: SourceFile[], options?: LocateOptions): {
+    located: LocatedPath[];
+    unlocated: UnlocatedPath[];
+};
+
+/**
+ * What the conversion did, and — the half that matters — what it did not.
+ *
+ * A codemod that silently skips a path presents as a finished conversion and fails months later,
+ * when an editor changes a value and the page keeps rendering the old one. So every path in the
+ * brief lands in exactly one of four buckets, and the arithmetic saying so is asserted rather than
+ * believed: `declared === rewritten + alreadyDeclared + pending.length`.
+ *
+ * PATH IDENTITY IS `(route, scope, path)`. Occurrences are counted separately, because "this
+ * 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";
+interface PendingPath {
+    route: string;
+    scope: "page" | "layout";
+    path: string;
+    kind: string;
+    /** The file the reason is about, when the reason is about one. */
+    file?: string;
+    reason: PendingReason;
+    message?: string;
+}
+/** One file the conversion touched, and the tier that produced it. A file is exactly one tier. */
+interface ReceiptFile {
+    path: string;
+    bindings: string[];
+    tier: 1 | 2 | 3;
+}
+interface ConversionReceipt {
+    briefDigest: string;
+    paths: {
+        declared: number;
+        rewritten: number;
+        alreadyDeclared: number;
+        pending: PendingPath[];
+    };
+    occurrences: {
+        located: number;
+        rewritten: number;
+    };
+    files: ReceiptFile[];
+    /** Helper modules written or upgraded, by path. */
+    helpers: string[];
+    helperUpgraded: boolean;
+    /**
+     * Bindings declared as an EXPRESSION rather than as a literal path — informative ONLY.
+     *
+     * 🔴 THE PROPOSER NEVER TRUSTS THIS. It re-derives every entry from its own scan of the
+     * proposed files, because a receipt is a claim by the thing being checked. The list is here so
+     * a reviewer can see what to look for, and so the scan has somewhere to disagree with.
+     */
+    dynamicBindings: DynamicBinding[];
+}
+/**
+ * One binding whose `data-bcms-field` is an expression, and where its value is written literally.
+ *
+ * Two shapes produce one: a repeater's `` {`cards[${i}].title`} ``, whose call site is the loop in
+ * the same file, and a drilled prop's `{bcmsBindings?.title}`, whose call sites are every place
+ * the component is used with a literal in `bcmsBindings`.
+ */
+interface DynamicBinding {
+    /** The file carrying the expression. */
+    file: string;
+    /** The prop the expression reads, or null for a repeater. */
+    prop: string | null;
+    /** The path it resolves to — `cards[*].title` for a repeater, a real path for a prop. */
+    path: string;
+    /** Where the literal that makes it resolvable is written. */
+    callSites: {
+        file: string;
+        literal: string;
+    }[];
+}
+/** Raised when the receipt does not add up. Never caught inside this package. */
+declare class ReceiptInvariantError extends Error {
+    readonly code = "RECEIPT_INVARIANT";
+    constructor(message: string);
+}
+/**
+ * The invariant, checked where the receipt is built rather than where it is read.
+ *
+ * A path that is in none of the four buckets is a path the conversion forgot, and forgetting is
+ * exactly the failure mode this whole lane exists to make impossible. Refusing here means a bug in
+ * this package surfaces as a loud error on the developer's own fixture run, not as a coverage
+ * meter that reads 96 % forever.
+ */
+declare function assertReceipt(receipt: ConversionReceipt): ConversionReceipt;
+/** What a coverage meter reads: how much of the brief this conversion actually made editable. */
+declare function coverageOf(receipt: ConversionReceipt): {
+    briefDigest: string;
+    declared: number;
+    bound: number;
+    pending: {
+        path: string;
+        reason: PendingReason;
+    }[];
+};
+
+/**
+ * Which template language a file is written in — by EXTENSION, and nothing else.
+ *
+ * Sniffing content would let one badly named file decide which parser runs, and a parser that
+ * runs on the wrong grammar does not fail loudly: it returns a plausible tree with the wrong
+ * offsets, and the rewrite splices bytes into the middle of something. `content` is accepted
+ * because the callers all have it and one distinction will eventually need it (a `.js` file that
+ * is really JSX), and until then the answer must not depend on it.
+ */
+type Dialect = "html" | "astro" | "jsx" | "svelte" | "vue";
+declare function dialectOf(path: string, _content?: string): Dialect | null;
+
+/**
+ * The ONE matcher, and the neutral tree every dialect parser normalises into.
+ *
+ * Three parsers disagree about everything except the two facts this package needs: where an
+ * element's bytes are, and what text it renders. Normalising to that pair keeps "which element
+ * holds this sentence" written once — the alternative is the same subtle traversal in five files,
+ * where a rule fixed in one of them stays broken in the other four.
+ */
+interface Range {
+    start: number;
+    end: number;
+}
+interface AttrNode {
+    name: string;
+    /** The literal value, or "" for an expression / valueless attribute. */
+    value: string;
+    /** The value's own characters, quotes excluded. Null when there is nothing to replace. */
+    valueRange: Range | null;
+    /** `alt={x}` rather than `alt="x"` — never rewritten, never matched. */
+    expression: boolean;
+    /** The whole `name="value"` span, so an attribute can be replaced outright. */
+    range: Range;
+}
+type Node = {
+    type: "element";
+    tag: string;
+    /** The `<` of the open tag. */
+    start: 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. */
+    inner: Range | null;
+    attrs: AttrNode[];
+    children: Node[];
+    /** `<script>` / `<style>`: the children are code, not copy. */
+    raw: boolean;
+} | {
+    type: "text";
+    range: Range;
+    value: string;
+} | {
+    type: "comment";
+    range: Range;
+    value: string;
+}
+/**
+ * An expression the codemod does not read — but which may CONTAIN markup it has to see.
+ *
+ * `children` is populated with the elements nested inside (a `.map(…)` body, a ternary's
+ * branches) and is deliberately invisible to `collectSites`: the copy inside an expression is a
+ * program's, and matching it would bind a value to a branch that may not render. What does read
+ * it is the DECLARATION walk, because a loop this package itself wrote lives here, and a second
+ * run that could not see it would convert the same file twice.
+ */
+ | {
+    type: "expr";
+    range: Range;
+    value: string;
+    children: Node[];
+};
+type SiteWhere = "text" | "attr" | "prop" | "expr" | "script" | "comment" | "data";
+interface Site {
+    /** Filled in by the caller; `findSites` is given one file's bytes and does not know its name. */
+    file: string;
+    tag: string;
+    attrInsertAt: number;
+    /** The bytes this site's value occupies — a text node, an inner range, or an attribute value. */
+    range: Range;
+    /** The element's inner range, for the kinds that replace a whole subtree (richtext). */
+    inner: Range | null;
+    where: SiteWhere;
+    scope: "page";
+    attr?: string;
+    /** The whole `name="value"` span, so an attribute can be rewritten as an expression. */
+    attrRange?: Range;
+    existingAttrs: Record<string, string>;
+    /** The element renders something besides this literal — an icon, a nested element. */
+    mixed: boolean;
+    /** The one non-blank direct text child, when there is exactly one. The wrap target. */
+    textRange: Range | null;
+    /** The whitespace-flattened literal this site matched. */
+    literal: string;
+    /** The literal is only PART of what this element renders; rewriting it would eat the rest. */
+    partial: boolean;
+    /** Tag chain from the document root down to the element's parent, outermost first. */
+    ancestors: string[];
+    /** Index among the element's ELEMENT siblings. */
+    siblingIndex: number;
+    /**
+     * Reserved for `emitRepeater`: the sibling group this element belongs to. Set by nothing today —
+     * the group comes from the brief's locator, which is the derive lane's answer. @see loops.ts
+     */
+    repeat?: {
+        groupId: string;
+        index: number;
+        siblingRanges: Range[];
+    };
+    /**
+     * The `bcmsBindings={{ … }}` already on this element, when there is one.
+     *
+     * A second prop drilled into the same component must MERGE into that object rather than write a
+     * second attribute of the same name, which JSX takes the last of and Astro the first.
+     */
+    bindingsAttr?: Range;
+}
+/** A parser that refused. Never thrown across the package boundary — it selects the next tier. */
+interface ParserError {
+    code: "PARSE_ERROR" | "DIALECT_UNSUPPORTED";
+    message: string;
+}
+/**
+ * Where the helper's `import` goes, answered by the parser that already read the file.
+ *
+ * The rule differs per dialect (frontmatter top, after the last import, `<script>` top) and every
+ * version of it needs a position only a parse knows. Returning it with the sites keeps one parse
+ * per file, which is also what keeps the offsets in one coordinate system.
+ */
+interface ImportPoint {
+    at: number;
+    /**
+     * The file has no block to put an import IN, so the caller opens one around the import lines.
+     *
+     * Astro wants a frontmatter fence, Svelte and Vue want a `<script>`. One field rather than one
+     * boolean per dialect: the parser knows what its own language opens with, and `rewrite.ts` only
+     * has to splice what it is given.
+     */
+    wrap?: {
+        before: string;
+        after: string;
+    };
+}
+interface FindSitesResult {
+    sites: Site[];
+    error?: ParserError;
+    importAt?: ImportPoint;
+}
+/**
+ * ONE PARSE PER FILE, handed to everything that needs it.
+ *
+ * The matcher wants the neutral tree; prop drilling wants the module's own AST; the alias
+ * allocator wants its top-level bindings. Parsing three times would be three coordinate systems
+ * for one file, which is how a splice lands in the middle of a tag.
+ */
+interface ParsedFile {
+    roots: Node[];
+    error?: ParserError;
+    importAt?: ImportPoint;
+    /** The dialect's own AST, when it has one worth keeping (jsx: babel; astro: the frontmatter). */
+    ast?: unknown;
+    /** The file's TypeScript/JavaScript region, for the dialects that separate it from the markup. */
+    script?: {
+        code: string;
+        offset: number;
+    };
+}
+
+/**
+ * Tier 2: what can still be done for a file no parser would read.
+ *
+ * A template with a syntax error, or a dialect this build cannot parse, still has its copy sitting
+ * between a `>` and a `<`. That is enough to place a binding — and ONLY when the literal occurs
+ * exactly once in the file, because without a tree there is nothing to tell two copies apart and
+ * a wrong guess splices bytes into the middle of someone's markup.
+ *
+ * Everything this tier cannot answer is left to tier 3 or reported as pending. It never widens
+ * its own rules to cover one more case: the whole reason it is allowed to run on an unparsable
+ * file is that its rule is narrow enough to be obviously safe.
+ */
+
+declare function findSitesTolerant(content: string, literals: string[]): Site[];
+
+/** One entry point per dialect, chosen by a table rather than by a chain of ifs. */
+
+type Parser = (content: string) => ParsedFile | Promise<ParsedFile>;
+declare const PARSE_FILE: Record<Dialect, Parser>;
+/**
+ * ONE parse of one file, in the dialect's own parser. A parser that refuses returns an error on
+ * the result; it never throws at the caller, because a refusal SELECTS the next tier.
+ */
+declare const parseFile: (dialect: Dialect, content: string) => Promise<ParsedFile>;
+/** Tier 1 for one file: parse, then match. */
+declare const findSites: (dialect: Dialect, content: string, literals: string[]) => Promise<FindSitesResult>;
+
+/** One path, one place in one file, and what to write there. */
+interface Rewrite {
+    site: Site;
+    /**
+     * The receipt's path identity — `(route, scope, path)` — carried, never re-derived.
+     *
+     * 🔴 A PATH IS NOT AN IDENTITY. Two routes rendered by ONE file legitimately carry the same
+     * path, and recovering "which target is this?" by path alone picks whichever one sorted first:
+     * the page reads `bcmsAbout` while the file imports only `bcmsHome`, and the site does not
+     * build. Every consumer below takes the answer from the rewrite it is already holding.
+     */
+    key: string;
+    path: string;
+    /** The brief's kind: "text" | "richtext" | "image". */
+    kind: string;
+    /** The copy the repo renders today, kept as the in-code fallback. */
+    fallback: string;
+    /** The identifier this page's snapshot is imported under. */
+    snapshot: string;
+    /** The page slug that snapshot belongs to. The file's import set is derived from these. */
+    slug: string;
+    /** Page copy, or the shared chrome — which decides the attribute AND the helper. @see expr.ts */
+    scope: "page" | "layout";
+    dynamic: boolean;
+    /**
+     * A whole span replaced by text computed elsewhere — a repeater's loop.
+     *
+     * The loop's own leaves were rewritten against a COPY of the row, so its bytes arrive finished;
+     * splicing them here keeps every write to one file in one `magic-string` pass. @see loops.ts
+     */
+    raw?: string;
+    /**
+     * The literal half of a drilled prop: `bcmsBindings={{ title: "hero.title" }}` at the call site.
+     *
+     * Absent when hop 2 missed — the value still comes from the CMS, and nothing claims a binding
+     * that does not exist. @see props.ts
+     */
+    bindings?: {
+        prop: string;
+        path: string;
+    };
+    /**
+     * How the call site's existing `bcmsBindings` is joined, when it has one.
+     *
+     * `object` merges into `{{ … }}`; `spread` wraps whatever expression is there in a new object
+     * literal. A shape neither of those covers is refused by the caller before it reaches here.
+     */
+    bindingsMerge?: {
+        kind: "object" | "spread";
+        range: Range;
+        inner: string;
+        insertAt: number;
+        /** What goes before the new members — `", "`, or `" "` when the object already ends in one. */
+        separator: string;
+        /** What goes after them, so an empty object closes as `{{ … }}` rather than `{{ …}}`. */
+        trailing: string;
+    };
+}
+interface FileImports {
+    /** `bcmsHome` → `../../bcms-content/home.json`. */
+    snapshots: {
+        identifier: string;
+        specifier: string;
+    }[];
+    /** The helper module, relative to this file. Null when the dialect needs none. */
+    helper: string | null;
+    /** The name `bcms` is imported under here — `bcms` unless this module already binds it. */
+    read: string;
+    /** Every named helper this file uses, with the name it was imported under. */
+    helpers: {
+        name: string;
+        alias: string;
+    }[];
+    /** The name `bcmsLayout` is imported under here. */
+    layout: string;
+    /** How THIS file reads its route parameter, when it is a dynamic route. @see routes.ts */
+    slug: string | null;
+    /** Import lines something other than the helper needs — a route parameter's store. */
+    extra?: string[];
+    at: ImportPoint | undefined;
+}
+/**
+ * The rewrites whose ranges collide, which is how one element ends up claimed by two paths.
+ *
+ * Reported rather than resolved: splicing both would corrupt the file and picking one would be a
+ * coin flip the receipt could not explain. The caller drops them as `AMBIGUOUS_LITERAL` and the
+ * rest of the file still converts.
+ */
+declare function overlapping(rewrites: Rewrite[]): Rewrite[];
+/**
+ * Apply every rewrite to one file.
+ *
+ * Attribute insertions are grouped by element first: an `<img>` that binds both its `src` and its
+ * `alt` gets one `data-bcms-props`, not two attributes with the same name — which a browser
+ * silently keeps only the first of.
+ */
+declare function rewriteFile(content: string, dialect: Dialect, rewrites: Rewrite[], imports: FileImports, 
+/** Edits this file needs that no binding asked for — a page component's `{ params }`. */
+extra?: {
+    start: number;
+    end: number;
+    text: string;
+}[]): string;
+
+/**
+ * The two strings the codemod writes: the READ (how a template asks the CMS for a value) and the
+ * DECLARATION (the attributes that say which element holds it).
+ *
+ * Both are literal text on purpose. `data-bcms-field={paths.hero.title}` would be a binding
+ * nothing can verify before a release — the proposer refuses it by name — so this module never
+ * emits an expression where a path belongs, and the fallback is the exact copy the repo renders
+ * today so a build with an empty snapshot renders the site it rendered before.
+ */
+
+/** How a dialect spells the things that differ. Data, so a sixth dialect is a row. */
+interface DialectRule {
+    /** A value in TEXT position, or null when this dialect only ever writes attributes. */
+    text: ((expression: string) => string) | null;
+    /** The attribute that replaces an element's children with HTML. */
+    richtext: ((expression: string) => string) | null;
+    /** `alt={…}` — a value in ATTRIBUTE position. */
+    attr: ((name: string, expression: string) => string) | null;
+    /** How this dialect reads the route parameter on a dynamic route. */
+    slug: string | null;
+    /**
+     * How this dialect repeats one element over a list.
+     *
+     * TWO SHAPES, because the dialects genuinely have two: jsx, astro and svelte WRAP the row in a
+     * construct, vue puts `v-for` ON the row's open tag. One shape forced onto the other would mean
+     * emitting a `<template v-for>` wrapper nobody writes by hand, in a diff a human has to approve.
+     */
+    loop: {
+        kind: "wrap";
+        open: (rows: string, row: string, index: string) => string;
+        close: string;
+    } | {
+        kind: "attr";
+        attr: (rows: string, row: string, index: string) => string;
+    } | null;
+    /** An extra attribute every row carries — React's list key. Null where the dialect needs none. */
+    loopKey: ((index: string) => string) | null;
+    /** The helper module, repository-relative, or null when the dialect needs none. */
+    helper: string | null;
+    /** How an import statement is spelled, and where it goes. */
+    importAt: "frontmatter" | "afterImports" | null;
+}
+declare const DIALECT_RULES: Record<Dialect, DialectRule>;
+/**
+ * `bcms(<snapshot>, "<path>", <fallback>)` — the call a template makes.
+ *
+ * `page` is the IDENTIFIER the page's snapshot was imported under, not the snapshot itself: this
+ * module writes source, and the import is added once per file by `rewrite.ts`. Same for `fn`,
+ * the name the helper itself was imported under.
+ */
+declare function readExpr(dialect: Dialect, page: string, path: string, _kind: string, fallback: string, route: {
+    dynamic: boolean;
+    fn?: string;
+    slug?: string | null;
+}): string;
+/** Attribute bindings for one element: `{ alt: "hero.image.alt" }` → `data-bcms-props`. */
+interface AttrBinding {
+    attr: string;
+    path: string;
+    kind: BindingKind;
+    /** Page copy, or the shared chrome. Decides the prefix the ADDRESS carries. @see propsAttribute */
+    scope?: "page" | "layout";
+}
+/**
+ * The declaration, as attribute text ready to splice after an open tag's last attribute.
+ *
+ * A kind is emitted whenever the brief states one — which, for a brief built by `flattenBindings`,
+ * is ALWAYS: `kindOf` spells plain text `"text"`, not `""`. The proposer then requires
+ * `data-bcms-kind` on that element, so omitting it because the platform's prose says "plain text
+ * needs no kind" is what would get the conversion refused.
+ */
+declare function attrsFor(path: string, kind: string, props?: AttrBinding[], scope?: "page" | "layout"): string;
+/**
+ * `data-bcms-props` for a set of attribute bindings, or "" when there are none.
+ *
+ * 🔴 THE ADDRESS CARRIES ITS LANE HERE TOO. A value in an attribute — a promoted nav link's
+ * `href` — is declared on `data-bcms-props` rather than on a field attribute, and the raw path was
+ * written there with no `layout:` prefix. The release reader then classified a chrome address as a
+ * page one, found no page field by that name, and reported it unmatched on every release. One
+ * prefix, applied wherever an address is written.
+ */
+declare function propsAttribute(props: AttrBinding[]): string;
+
+/** Bumped whenever the emitted source changes. `isKnownHelper` upgrades anything older. */
+declare const HELPER_VERSION = 2;
+/** 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. */
+declare const CONTENT_DIR = "bcms-content";
+/** The stub the codemod commits, and the exact content the proposer's NEW_FILE exemption allows. */
+declare const STUB_CONTENT = "{}";
+/** `src/pages/index.astro` + `bcms-content/home.json` → `../../bcms-content/home.json`. */
+declare function relativeImport(fromFile: string, toFile: string): string;
+/**
+ * The helper, for one dialect.
+ *
+ * `bcms` takes the SNAPSHOT as its first argument because the import is page-scoped: a helper that
+ * imported every page's content would put a 4,974-entry workspace into one client bundle.
+ * `bcmsLayout` is the exception and imports directly, because the layout is one shared object by
+ * definition — that is what makes it the layout. `bcmsRows` is `bcms` for a value that is a LIST:
+ * a repeater's loop reads it once and each row reads its own leaves back through `bcms(card, …)`.
+ */
+declare function helperSource(dialect: Dialect): string;
+/**
+ * The version of a helper WE wrote, byte for byte, or null for anything else.
+ *
+ * Null covers both "somebody else's module lives here" and "our module, edited" — the caller
+ * 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;
+
+/**
+ * Which files in a repository can possibly render a page's copy.
+ *
+ * ONE list, shared by the CLI (which walks a working tree) and by the server lane's `acquire.ts`
+ * (which walks a GitHub tree). They were two copies of the same three arrays; a file kind added
+ * to one and not the other means the two lanes convert different sites from the same repository,
+ * and nothing would say so.
+ */
+/** Directories that never hold a template a human wrote. */
+declare const SKIP_DIRS: string[];
+/** Generated or machine-owned files. A lockfile can contain anything and means nothing. */
+declare const SKIP_FILES: string[];
+/**
+ * Extensions that can render copy. Everything else — images, fonts, data — is skipped unread.
+ *
+ * Wider than the five dialects the codemod can rewrite, deliberately: a literal that lives only
+ * in an `.md` or a `.liquid` has to be REPORTED as `DIALECT_UNSUPPORTED`, and a file nobody
+ * opened cannot be reported at all.
+ */
+declare const SOURCE_EXTENSIONS: string[];
+/** Is this repository-relative path a file worth opening? */
+declare function isSourceCandidate(path: string): boolean;
+
+/**
+ * The project's own `compilerOptions.paths`, when a tsconfig is among the files.
+ *
+ * 🔴 THE PROJECT'S, NEVER A DEFAULT. `@/` means `src/` in most Next projects and something else in
+ * plenty of others; assuming it would resolve `<Hero>` to a file that is not the one the build
+ * uses, and the edit would land in a component nobody renders. No tsconfig means relative
+ * specifiers only, which is a smaller conversion and a true one.
+ */
+declare function aliasesFrom(sources: SourceFile[]): Map<string, 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. */
+interface ImportedFrom {
+    specifier: string;
+    /** The exported name, or null for a default import. */
+    imported: string | null;
+}
+/**
+ * Local name → what it was imported from, for one file.
+ *
+ * From the parse: a regex over `import` lines cannot tell a real import from one inside a string
+ * or a comment, and this decides which file gets edited. The EXPORT is carried too, because a
+ * module legitimately exports several components and only one of them renders this prop.
+ */
+declare function importsIn(parsed: ParsedFile, _dialect: Dialect): Map<string, ImportedFrom>;
+
+/**
+ * A literal that reaches the page as a PROP — `<Hero title="Ship your site today" />` — and the
+ * element inside the component that actually renders it.
+ *
+ * 🔴 THE ATTRIBUTE ON `<Hero>` IS NOT A BINDING. React and Astro pass unknown props nowhere, so a
+ * `data-bcms-field` written there reaches no DOM node: every release reports the path unmatched,
+ * and the value the editor changes never appears. The declaration has to go on the `<h1>` inside
+ * `Hero`, which is in a different file — so the conversion is TWO HOPS, and it is one proposal
+ * because half of it is worse than neither half.
+ *
+ * WHAT THE SECOND HOP WRITES, and why an expression is unavoidable here. The component renders
+ * every call site, and different call sites carry different paths, so the element cannot declare a
+ * literal one: it declares `data-bcms-field={bcmsBindings?.title}`, and the LITERAL lives at each
+ * call site in `bcmsBindings={{ title: "hero.title" }}`. That is the one shape this package emits
+ * that a reader cannot verify by looking at the element alone — which is exactly why
+ * `proposeConversion` re-derives it from its OWN scan of every call site and never from the
+ * receipt.
+ *
+ * A MISS IS A REFUSAL, NOT A GUESS. If the component cannot be resolved, or nothing in it renders
+ * the prop, hop 1 still makes the value come from the CMS (the page is no worse off) but the
+ * bindings prop is DROPPED and the path is reported `PROP_TARGET_NOT_FOUND` — a declaration whose
+ * other half does not exist is a binding that reads as done and is not.
+ */
+
+/** The narrowed AST shape. @see sites/jsx.ts for the same narrowing, for the same reason. */
+interface AstNode {
+    type: string;
+    start?: number | null;
+    end?: number | null;
+    [key: string]: unknown;
+}
+/** Walk every node of an AST once. */
+declare function walkAst(node: unknown, visit: (node: AstNode) => void, seen?: Set<unknown>): void;
+/**
+ * The function behind ONE export of a module.
+ *
+ * 🔴 A MODULE IS NOT A COMPONENT. `Hero.tsx` legitimately exports `Hero`, a `HeroSkeleton` and a
+ * `useHero`, and scanning every function in it for a `title` prop answers with whichever one
+ * happened to have a parameter of that name — a declaration written into a component the call
+ * site does not render. The import said which export it wants; that is the one analysed.
+ */
+declare function exportedFunction(ast: unknown, imported: string | null): AstNode | null;
+
+/**
+ * Is THIS element already converted for THIS target — declaration and read, together?
+ *
+ * 🔴 A FILE-WIDE DECLARATION PLUS A FILE-WIDE READ IS NOT EVIDENCE OF EITHER. A page that renders
+ * two routes carries both, for different elements; a page converted for `/` and a hardcoded `<h2>`
+ * for `/about` satisfies "the file declares that path" and "the file reads that path" while the
+ * second sentence never reflects an edit again. And a `bcms(…)` sitting three elements away — or
+ * in an unused statement at the top of the module — answers the same way. So the question is
+ * asked of ONE element's own bytes, against identifiers this file actually imports.
+ *
+ * Used by both ends of the conversion: the per-file prefilter, which decides whether a target has
+ * already been done, and tier 3's verification, which decides whether a model's output may be
+ * believed. One implementation, because the two must not disagree about what "converted" means.
+ */
+
+/** The identity a declaration is compared against. */
+interface TargetIdentity {
+    scope: "page" | "layout";
+    path: string;
+    /** The page slug whose snapshot the read must name. Unused for layout scope. */
+    slug: string;
+}
+/** One element that declares something, and the bytes a reader of THAT element would see. */
+interface DeclaringElement {
+    scope: "page" | "layout";
+    path: string;
+    kind: string;
+    /** The open tag plus this element's OWN text and expressions — never a descendant's. */
+    own: string;
+}
+/** Every element in a parse that declares a binding, with its own bytes. */
+declare function declaringElements(roots: Node[], content: string): DeclaringElement[];
+/**
+ * Has this file already converted this target — on an element of its own, with a real read?
+ *
+ * Every half is required and every half is scoped: the DECLARATION has to be for this scope and
+ * this path, the READ has to be inside that same element, and the identifiers it names have to be
+ * ones this file imports. A repeater additionally needs the array read, which lives on the loop
+ * rather than on the row.
+ */
+declare function convertedHere(content: string, parsed: ParsedFile, dialect: Dialect, target: TargetIdentity, file: string): boolean;
+
+interface FileDeclaration {
+    scope: "page" | "layout";
+    path: string;
+}
+/** Every path one file declares, with the lane it declares it on. */
+declare function readDeclarations(file: string, content: string): Promise<FileDeclaration[]>;
+
+/** One file operation, exactly as `src/lib/github/plan-digest.ts` spells it. */
+interface PlanFile {
+    path: string;
+    operation: "modify" | "add";
+    content: string;
+}
+/**
+ * Tier 3, INJECTED by the server lane and never by this package.
+ *
+ * The CLI passes none: the coding agent running it IS tier 3, and the playbook tells it to take
+ * the `PARSE_ERROR` list itself.
+ */
+type LlmFallback = (file: SourceFile, remaining: LocatedPath[]) => Promise<string | null>;
+interface ConvertOptions {
+    llmFallback?: LlmFallback;
+    /** Replace a helper module this package did not write, instead of refusing. The CLI's flag. */
+    overwriteHelper?: boolean;
+}
+type ConvertErrorCode = "HELPER_CONFLICT";
+declare class ConvertError extends Error {
+    readonly code: ConvertErrorCode;
+    constructor(code: ConvertErrorCode, message: string);
+}
+/** One replacement in a file this conversion is not otherwise rewriting — a drilled component. */
+interface Splice {
+    start: number;
+    end: number;
+    text: string;
+}
+declare function convertSources(brief: 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 };