@bettercms-ai/convert 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -197,6 +197,83 @@ declare function locate(brief: BriefLike, sources: SourceFile[], options?: Locat
     unlocated: UnlocatedPath[];
 };
 
+/**
+ * What to DO about a path this run could not bind — an instruction, never a category name.
+ *
+ * 🔴 A REASON IS A DIAGNOSIS AND AN AGENT CANNOT ACT ON ONE. `IN_EXPRESSION` tells a coding agent
+ * that something, somewhere, is an expression; it does not say which file, which line, or what to
+ * type. So every pending row leaves with a `fix`: one file, one line, the bytes that are there
+ * now, and the one edit that makes the path bindable on the next run. The closed `action` set is
+ * the contract the server validates (`src/lib/validation/schemas/conversion-receipt.ts`) and the
+ * loop `get_next_steps` reads — an unknown action is a 400, so it is minted in exactly one place.
+ */
+
+/**
+ * The edits an agent can be asked for, and nothing else.
+ *
+ * `wrap-span`         the value has no element of its own — wrap it in `<span data-bcms-field>`.
+ * `declare-attr`      the element is there — add `data-bcms-field` to it at file:line.
+ * `declare-richtext`  the container renders markup — bind it with the richtext helper.
+ * `bind-expression`   the value is computed — replace the expression with the helper's read.
+ * `bind-data`         the copy lives in a data file or a content entry — bind THAT field.
+ * `manual`            none of the above is true, and `why` says what a human has to decide.
+ */
+type FixAction = "wrap-span" | "declare-attr" | "bind-expression" | "declare-richtext" | "bind-data" | "manual";
+/** One mechanical instruction, at one place in one file. @see FixAction */
+interface PendingFix {
+    file: string;
+    /** 1-based. */
+    line: number;
+    /** 1-based, when the literal was found on the line. */
+    col?: number;
+    /** The bytes at `line`, trimmed — so the agent can see it is looking at the right place. */
+    snippet: string;
+    action: FixAction;
+    /** One sentence, present whenever the action alone does not say enough. */
+    why?: string;
+}
+/** Everything about one pending path a fix is derived from. Pure input; no filesystem. */
+interface FixInput {
+    /** The copy the repository renders, flattened. Empty when the brief captured none. */
+    literal: string;
+    kind: string;
+    /** The richtext value IS the element's whole inline subtree. @see brief.ts */
+    inline?: true;
+    /** Files this path's copy was found in, best first. May be empty. */
+    candidates: string[];
+    /** Source, by path — only the files named in `candidates` need be present. */
+    contents: ReadonlyMap<string, string>;
+    /** How many ROUTES share this `(scope, path)` in the pending list. @see sharedChrome */
+    routes: number;
+}
+/**
+ * Where `literal` sits in `content` — tolerant of the two things every template does to copy.
+ *
+ * A template wraps its copy across lines and indents it, and it puts inline markup in the middle
+ * of it (`Read <strong>this</strong> now`). Both are invisible to a reader and fatal to
+ * `indexOf`, so the words are matched with whitespace OR a tag between them. Bounded at
+ * `MAX_WORDS`, because a paragraph's first dozen words identify it as well as all ninety do.
+ */
+declare function findLiteral(content: string, literal: string): {
+    index: number;
+    length: number;
+} | null;
+/**
+ * The fix for one pending row. Always answers: a row without one is a row an agent cannot act on.
+ *
+ * The FILE is the row's own when it has one (the lane that refused named it), and otherwise the
+ * first candidate `locate` found — and when there is neither, the fix still names the route's page
+ * file with line 1, because "go and look here" beats "go and look".
+ */
+declare function fixFor(row: PendingPath, input: FixInput): PendingFix;
+/**
+ * How many ROUTES each `(scope, path)` is pending on — the shared-chrome tell. @see actionFor
+ *
+ * Counted over the whole pending list rather than per row: one nav label pending on twelve routes
+ * is one element, and the fix for every one of those rows is the same sentence about promotion.
+ */
+declare function routeCounts(pending: readonly PendingPath[]): Map<string, number>;
+
 /**
  * What the conversion did, and — the half that matters — what it did not.
  *
@@ -209,6 +286,7 @@ 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"
 /** An INLINE richtext value whose element holds a component, a `<slot>` or an expression. */
  | "SUBTREE_NOT_HTML" | "PROP_TARGET_NOT_FOUND" | "PROP_DRILLED_DEEP" | "REPEATER_FIXED_LENGTH"
@@ -231,6 +309,15 @@ interface PendingPath {
     line?: number;
     /** What to do about it, in prose — a recipe, not a diagnosis. @see message */
     hint?: string;
+    /**
+     * The EDIT that makes this path bindable on the next run — one file, one line, one action.
+     *
+     * 🔴 THE REASON IS A DIAGNOSIS AND NOBODY CAN ACT ON ONE. Every row carries this, because a
+     * conversion ends when nothing is pending and the only way an agent gets there is by being told
+     * what to type and where. OPTIONAL in the type so a receipt written by an older version of this
+     * package still parses; this package emits one for every row. @see fix.ts
+     */
+    fix?: PendingFix;
 }
 /**
  * One path that was already DECLARED before this run — and how honestly.
@@ -829,7 +916,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 = 6;
+declare const HELPER_VERSION = 7;
 /** 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. */
@@ -1416,6 +1503,11 @@ declare function carryFor(options: {
  * an unexpected extra key is simply carried past. The shape is frozen; the reader is not brittle.
  */
 interface ComponentizePlanField {
+    /**
+     * Where an instance holds this leaf's copy (`h2_latest`, `group_webgl[0].a_webgl`) — allocated by the
+     * server, which alone knows the dedupe suffixes and table keys. Absent from older plans.
+     */
+    overrideKey?: string;
     /** 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. */
@@ -1559,6 +1651,15 @@ interface ComponentizeReceipt {
     sections: SectionsReceipt;
     /** The component slugs this run wrote a file for, sorted. */
     components: string[];
+    /**
+     * The file each of those components was written to — what lets the server record a component's source
+     * (kind `section`) without anyone claiming it by hand. Additive: readers of `components` are unchanged.
+     */
+    componentFiles?: {
+        slug: string;
+        path: string;
+        export: "default";
+    }[];
     /**
      * Sections the SERVER already marked pending (`NO_GROUP_ROOT`, `ALREADY_COMPONENTIZED`, …).
      *
@@ -1706,4 +1807,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, 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 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, findSites, findSitesTolerant, flat, helperSource, importsIn, isDecorativeGlyph, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, measureUnaddressable, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, 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 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 };