@bettercms-ai/convert 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -175,6 +175,29 @@ interface PendingPath {
     reason: PendingReason;
     message?: string;
 }
+/**
+ * One path that was already DECLARED before this run — and how honestly.
+ *
+ * 🔴 `readsFromCms: false` IS THE INTERESTING ROW. An element carrying a `data-bcms-field` (or a
+ * `data-bcms-props` / `data-bcms-layout-field`) that gets its copy some other way — a hand-written
+ * declaration on markup that still renders a literal, or reads it from the project's own data
+ * module — is DECLARED: the publisher writes into it and the editor can click it. It is simply not
+ * reading through this package's helper. Reporting it `NO_ORIGINAL` said the opposite of the truth
+ * — a path nobody had declared — and sent an agent to convert an element that was already done.
+ *
+ * The row is informative; `paths.alreadyDeclared` is the number the arithmetic uses, and both
+ * shapes count towards it.
+ */
+interface DeclaredPath {
+    route: string;
+    scope: "page" | "layout";
+    path: string;
+    kind: string;
+    /** The file the declaration was found on. */
+    file?: string;
+    /** Does the declaring element read this value through the committed helper? */
+    readsFromCms: boolean;
+}
 /** One file the conversion touched, and the tier that produced it. A file is exactly one tier. */
 interface ReceiptFile {
     path: string;
@@ -187,6 +210,13 @@ interface ConversionReceipt {
         declared: number;
         rewritten: number;
         alreadyDeclared: number;
+        /**
+         * One row per already-declared path, saying whether it reads from the CMS. @see DeclaredPath
+         *
+         * OPTIONAL, because a receipt written by an older version of this package does not carry it and
+         * a reader must not require it. The COUNT above is the contract; this is the detail.
+         */
+        declarations?: DeclaredPath[];
         pending: PendingPath[];
     };
     occurrences: {
@@ -205,6 +235,8 @@ interface ConversionReceipt {
      * a reviewer can see what to look for, and so the scan has somewhere to disagree with.
      */
     dynamicBindings: DynamicBinding[];
+    /** Facts about the repository that shaped this run. OPTIONAL: an older receipt carries none. */
+    notes?: ReceiptNote[];
 }
 /**
  * One binding whose `data-bcms-field` is an expression, and where its value is written literally.
@@ -226,6 +258,19 @@ interface DynamicBinding {
         literal: string;
     }[];
 }
+/**
+ * Something about the REPOSITORY that changed what this run could see, named rather than swallowed.
+ *
+ * Not a path and not a refusal: a note is about a file the conversion READ, and it explains why a
+ * later reason may name the wrong cause. `TSCONFIG_UNREADABLE` is the first — a project config this
+ * package could not parse declares no `paths` aliases as far as it is concerned, so every aliased
+ * import resolves to nothing and the component behind it reads as one the page does not import.
+ */
+interface ReceiptNote {
+    code: "TSCONFIG_UNREADABLE";
+    file: string;
+    message: string;
+}
 /** Raised when the receipt does not add up. Never caught inside this package. */
 declare class ReceiptInvariantError extends Error {
     readonly code = "RECEIPT_INVARIANT";
@@ -712,6 +757,14 @@ declare function isSourceCandidate(path: string): boolean;
  * specifiers only, which is a smaller conversion and a true one.
  */
 declare function aliasesFrom(sources: SourceFile[]): Map<string, string[]>;
+/**
+ * The project configs this package could not read, by path — a receipt NOTE, never a silent skip.
+ *
+ * A config that fails even the tolerant reader is one whose `paths` aliases nobody can resolve, so
+ * an aliased import reads as "not imported" and the refusal that follows names the wrong cause.
+ * The note says which file to look at. @see ConversionReceipt.notes
+ */
+declare function unreadableConfigs(sources: SourceFile[]): 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. */
@@ -963,6 +1016,9 @@ interface ComponentizePlan {
  *   `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.
+ *   `REGISTRY_UNREADABLE`        the registry IS ours, and its tables cannot be read back. It is
+ *                                rewritten whole every run, so rebuilding it from what this run
+ *                                happened to see would drop the components it already names.
  *   `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.
@@ -971,7 +1027,7 @@ interface ComponentizePlan {
  *   `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";
+type SectionPendingReason = "SECTION_ROOT_AMBIGUOUS" | "SECTION_NOT_CONTIGUOUS" | "SECTION_FREE_IDENTIFIERS" | "COMPONENT_CONFLICT" | "REGISTRY_CONFLICT" | "REGISTRY_UNREADABLE" | "ROUTE_FILE_AMBIGUOUS" | "DIALECT_UNSUPPORTED" | "HELPER_CONFLICT" | "SNAPSHOT_INVALID" | "NOT_IN_SOURCE";
 interface PendingSection {
     route: string;
     groupKey: string;
@@ -998,6 +1054,17 @@ interface SectionsReceipt {
      * account for every section of the plan if "done earlier" is a bucket of its own.
      */
     alreadyExtracted: number;
+    /**
+     * The repository ALREADY has the component: the page imports it, and the registry now names it.
+     *
+     * 🔴 ITS OWN BUCKET, AND ORTHOGONAL TO PLACEMENT. Nothing was written for these — the file was
+     * somebody's before this run and stays theirs — so counting them `extracted` would claim
+     * authorship of bytes this package never produced, and counting them `pending` would say the CMS
+     * has no component for a section it plainly does. Whether the page's call sites were then
+     * replaced by the loop is a separate question, answered by `extracted` for the sections this run
+     * did cut.
+     */
+    registered: number;
     pending: PendingSection[];
 }
 interface ComponentizeReceipt {
@@ -1013,6 +1080,15 @@ interface ComponentizeReceipt {
      * that does not place them has done exactly what it was told.
      */
     planPending: number;
+    /**
+     * Facts about the repository that shaped this run — the same list the conversion receipt carries.
+     *
+     * A tsconfig this package cannot read declares no `paths` aliases as far as it is concerned, and
+     * THIS lane resolves a page's `<Hero />` through exactly those aliases: the section then reads as
+     * one the page does not import, and `SECTION_ROOT_AMBIGUOUS` names the wrong cause. The note is
+     * what points at the real one.
+     */
+    notes?: ReceiptNote[];
 }
 /** Raised when the receipt does not account for every section. Never caught inside this package. */
 declare class SectionInvariantError extends Error {
@@ -1126,4 +1202,4 @@ declare function convertSources(briefIn: Brief, sources: SourceFile[], options?:
     receipt: ConversionReceipt;
 }>;
 
-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 };
+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 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, 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, unreadableConfigs, walkAst };