@fjall/generator 0.89.4 → 0.89.6

package/dist/src/codemod/fileRewriter/builders.d.ts

@@ -0,0 +1,57 @@
+import { type namedTypes as n } from "ast-types";
+/** Quote styles recognised by the builders — mirrors T4b's detectQuoteStyle. */
+export type QuoteStyle = "double" | "single";
+/**
+ * Key/value pair for {@link buildFactoryStatement}. Keys are identifier
+ * names (already validated upstream — no quoting logic here).
+ */
+export interface ObjectPropertyInput {
+    key: string;
+    value: n.Property["value"];
+}
+export interface BuildFactoryStatementParams {
+    /** Factory identifier, e.g. `"DatabaseFactory"`. */
+    factory: string;
+    /** Resource name, used as the first argument literal. */
+    name: string;
+    /** Configuration object properties. */
+    properties: ObjectPropertyInput[];
+    /** Quote style for NEW string literals the builder synthesises. */
+    quoteStyle: QuoteStyle;
+}
+/**
+ * Build an `ExpressionStatement` wrapping `XFactory.build("Name", { … })`.
+ *
+ * The factory identifier is emitted as a bare `Identifier` so the caller
+ * controls whether to add an `ImportDeclaration` separately (via
+ * {@link buildImportDeclaration} / {@link appendSpecifier}). The resource
+ * name literal honours `quoteStyle` via `extra.raw` on the literal.
+ */
+export declare function buildFactoryStatement(params: BuildFactoryStatementParams): n.ExpressionStatement;
+/**
+ * Build an object `Property` with a bare-identifier key. If `key` is
+ * not a valid JS identifier (e.g. contains a hyphen), the key is
+ * emitted as a quoted StringLiteral instead, honouring `quoteStyle`.
+ */
+export declare function buildObjectProperty(key: string, value: n.Property["value"], quoteStyle: QuoteStyle): n.Property;
+/**
+ * Build an `ImportDeclaration` for `import { a, b } from "module"` with
+ * the supplied specifier names. The module source literal honours
+ * `quoteStyle`. Specifiers are emitted as `ImportSpecifier` (named
+ * imports only) — namespace or default imports are out of scope for
+ * the Phase 1 codemod surface.
+ */
+export declare function buildImportDeclaration(specifiers: string[], module: string, quoteStyle?: QuoteStyle): n.ImportDeclaration;
+/**
+ * Build a `MemberExpression` for `object.property` shapes such as
+ * `app.addStorage(...)`. Both arguments are bare identifiers — the
+ * engine never emits computed member access.
+ */
+export declare function buildMemberExpression(object: string, property: string): n.MemberExpression;
+/**
+ * Mutate `importDecl` to add a named `ImportSpecifier` for `name`.
+ * Dedupes by the imported (NOT local) identifier — re-adding an
+ * existing specifier is a no-op. Preserves specifier order so the
+ * printed output stays stable across repeated invocations.
+ */
+export declare function appendSpecifier(importDecl: n.ImportDeclaration, name: string): void;

package/dist/src/codemod/fileRewriter/builders.js

@@ -0,0 +1 @@
+import{builders as i}from"ast-types";function d(e){const t=i.memberExpression(i.identifier(e.factory),i.identifier("build"),!1),r=c(e.name,e.quoteStyle),n=i.objectExpression(e.properties.map(o=>f(o.key,o.value,e.quoteStyle))),s=i.callExpression(t,[r,n]);return i.expressionStatement(s)}function f(e,t,r){const n=u(e)?i.identifier(e):c(e,r);return i.property("init",n,t)}function b(e,t,r="double"){const n=e.map(o=>i.importSpecifier(i.identifier(o))),s=c(t,r);return i.importDeclaration(n,s)}function m(e,t){return i.memberExpression(i.identifier(e),i.identifier(t),!1)}function x(e,t){Array.isArray(e.specifiers)||(e.specifiers=[]);for(const r of e.specifiers)if(a(r)&&r.imported.name===t)return;e.specifiers.push(i.importSpecifier(i.identifier(t)))}function c(e,t){const r=t==="single"?"'":'"',n=`${r}${p(e,t)}${r}`;return i.stringLiteral.from({value:e,extra:{rawValue:e,raw:n}})}function p(e,t){const r=e.replace(/\\/g,"\\\\");return t==="single"?r.replace(/'/g,"\\'"):r.replace(/"/g,'\\"')}function u(e){return/^[$_\p{ID_Start}][$_\u200C\u200D\p{ID_Continue}]*$/u.test(e)}function a(e){return e!==null&&typeof e=="object"&&"type"in e&&e.type==="ImportSpecifier"}export{x as appendSpecifier,d as buildFactoryStatement,b as buildImportDeclaration,m as buildMemberExpression,f as buildObjectProperty};

package/dist/src/codemod/fileRewriter/index.d.ts

@@ -0,0 +1,4 @@
+export { parse, type ParsedFile, type ParseError } from "./parse.js";
+export { detectLineTerminator, detectQuoteStyle, printFile } from "./print.js";
+export { appendSpecifier, buildFactoryStatement, buildImportDeclaration, buildMemberExpression, buildObjectProperty, type BuildFactoryStatementParams, type ObjectPropertyInput, type QuoteStyle, } from "./builders.js";
+export { locateByLineColumn, locateByRange, type LineColumnHint, type NodeLocation, } from "./locateByRange.js";

package/dist/src/codemod/fileRewriter/index.js

@@ -0,0 +1 @@
+import{parse as r}from"./parse.js";import{detectLineTerminator as i,detectQuoteStyle as p,printFile as a}from"./print.js";import{appendSpecifier as n,buildFactoryStatement as m,buildImportDeclaration as c,buildMemberExpression as d,buildObjectProperty as b}from"./builders.js";import{locateByLineColumn as f,locateByRange as x}from"./locateByRange.js";export{n as appendSpecifier,m as buildFactoryStatement,c as buildImportDeclaration,d as buildMemberExpression,b as buildObjectProperty,i as detectLineTerminator,p as detectQuoteStyle,f as locateByLineColumn,x as locateByRange,r as parse,a as printFile};

package/dist/src/codemod/fileRewriter/locateByRange.d.ts

@@ -0,0 +1,65 @@
+import type * as recast from "recast";
+import type { NodeLocation } from "../types.js";
+export type { NodeLocation } from "../types.js";
+/**
+ * Optional line/column coordinates used by the fallback path. Line is
+ * 1-based (matching recast's `loc.start.line`); column is 0-based
+ * (matching recast's `loc.start.column`).
+ */
+export interface LineColumnHint {
+    line?: number;
+    column?: number;
+}
+/**
+ * Minimal AST-node shape the walkers read. Mirrors the shallow record
+ * used by `lineColumnFallback.test.ts` and `print.ts` — keeps this file
+ * free of `@babel/types` as a runtime dependency.
+ */
+interface NodeShape {
+    type?: string;
+    start?: number | null;
+    end?: number | null;
+    value?: unknown;
+    loc?: {
+        start?: {
+            line?: number;
+            column?: number;
+        };
+        end?: {
+            line?: number;
+            column?: number;
+        };
+    };
+    [key: string]: unknown;
+}
+/** Parsed file shape, mirroring `parse.ts`'s `ParsedFile` without importing it. */
+type ParsedFile = ReturnType<typeof recast.parse>;
+/**
+ * Locate an `ast-types` node whose byte range matches `loc` exactly.
+ * On miss, invoke the line/column fallback if `hint` carries coords.
+ *
+ * Returns `undefined` on total miss (neither exact nor fallback found a
+ * candidate) — the caller decides whether that is an error or a skip.
+ *
+ * Semantic contract: the `length` field MUST equal `node.end - node.start`
+ * for the matching node. For `StringLiteral` nodes this span INCLUDES the
+ * enclosing quote characters, matching `locateByShape`'s use of
+ * `firstArg.getWidth()` (ts-morph) — so a `StringLiteral` carrying
+ * `"PrimaryDb"` has `length === 11` (9 letters + 2 quotes).
+ */
+export declare function locateByRange(file: ParsedFile, loc: NodeLocation, hint?: LineColumnHint): NodeShape | undefined;
+/**
+ * Fallback locator ported verbatim from Phase 0
+ * `__tests__/lineColumnFallback.test.ts`'s `findLocationByLineColumn`.
+ *
+ * Walks the AST for `StringLiteral` nodes whose `value` equals
+ * `loc.symbolName` and whose `loc.start.line` is within ±2 lines of
+ * `loc.line`. Disambiguates same-line candidates by column proximity,
+ * then by earliest `start` offset for determinism.
+ *
+ * Adaptation from Phase 0: return type becomes the `ast-types` node
+ * itself (the production contract) rather than `{ start, length }` (the
+ * Phase 0 test shape). The parity test in `locateByRange.test.ts`
+ * asserts the adapted result shape still round-trips byte-for-byte.
+ */
+export declare function locateByLineColumn(file: ParsedFile, loc: NodeLocation & LineColumnHint): NodeShape | undefined;

package/dist/src/codemod/fileRewriter/locateByRange.js

@@ -0,0 +1 @@
+function b(u,r,i){const n=m(u,r);if(n!==void 0)return n;if(i?.line!==void 0)return p(u,{...r,...i})}function p(u,r){if(r.line===void 0)return;const i=r.line,n=r.column??0,e=[];if(y(u,t=>{if(t.type!=="StringLiteral"||typeof t.value!="string"||t.value!==r.symbolName||typeof t.start!="number"||typeof t.end!="number")return;const s=t.loc?.start?.line,f=t.loc?.start?.column;typeof s!="number"||typeof f!="number"||Math.abs(s-i)>2||e.push({node:t,line:s,column:f,start:t.start})}),e.length!==0)return e.sort((t,s)=>{const f=Math.abs(t.line-i),o=Math.abs(s.line-i);if(f!==o)return f-o;const c=Math.abs(t.column-n),l=Math.abs(s.column-n);return c!==l?c-l:t.start-s.start}),e[0]?.node}function m(u,r){const i=r.start+r.length;let n;return y(u,e=>{n===void 0&&(typeof e.start!="number"||typeof e.end!="number"||e.start===r.start&&e.end===i&&(n=e))}),n}function y(u,r){const i=[u];for(;i.length>0;){const n=i.pop();if(!(!a(n)||typeof n.type!="string")){r(n);for(const e of Object.keys(n)){if(e==="loc"||e==="comments"||e==="tokens")continue;const t=n[e];if(Array.isArray(t))for(const s of t)a(s)&&typeof s.type=="string"&&i.push(s);else a(t)&&typeof t.type=="string"&&i.push(t)}}}}function a(u){return typeof u=="object"&&u!==null&&!Array.isArray(u)}export{p as locateByLineColumn,b as locateByRange};

package/dist/src/codemod/fileRewriter/parse.d.ts

@@ -0,0 +1,18 @@
+import * as recast from "recast";
+import { type Result } from "../../types/Result.js";
+import type { ParseError } from "../types.js";
+export type { ParseError } from "../types.js";
+export type ParsedFile = ReturnType<typeof recast.parse>;
+/**
+ * Parse `content` with the correct recast parser for the file shape.
+ *
+ * Dispatch rules (Phase 0 carry-over #1):
+ *   - `filePath` ends in `.tsx` OR `content` matches the JSX heuristic
+ *     → `recast/parsers/babel-ts`.
+ *   - Otherwise → try `recast/parsers/typescript`; on failure fall back
+ *     to `recast/parsers/babel-ts` ONCE. If both fail, surface the
+ *     original typescript-parser error via `ParseError`.
+ *
+ * Never throws — every failure path returns `failure(ParseError)`.
+ */
+export declare function parse(content: string, filePath?: string): Result<ParsedFile, ParseError>;

package/dist/src/codemod/fileRewriter/parse.js

@@ -0,0 +1,2 @@
+import*as d from"recast";import x from"recast/parsers/typescript.js";import a from"recast/parsers/babel-ts.js";import{failure as E,success as y}from"../../types/Result.js";const m=1,l=120;function I(n,t){if((t?.endsWith(".tsx")??!1)||b(n))return f(n,a,t);const e=f(n,x,t);if(e.success)return e;const s=f(n,a,t);return s.success?s:e}function b(n){return/<[A-Z][A-Za-z0-9]*[\s/>]|<>/.test(n)}function f(n,t,r){try{const e=d.parse(n,{parser:t});return y(e)}catch(e){return E(g(e,n,r))}}function g(n,t,r){const e=n instanceof Error?n.message:String(n),s=S(n),o=s?.line,c=s?.column;return{kind:"ParseError",file:r,line:o,column:c,message:e,sourceSnippet:h(t,o)}}function S(n){if(typeof n!="object"||n===null)return;const t=n.loc;if(typeof t!="object"||t===null)return;const r=t.line,e=t.column;return{line:typeof r=="number"?r:void 0,column:typeof e=="number"?e:void 0}}function h(n,t){const r=n.split(/\r?\n/);if(r.length===0)return"";const e=t!==void 0&&t>=1&&t<=r.length?t-1:0,s=Math.max(0,e-m),o=Math.min(r.length-1,e+m),c=[];for(let u=s;u<=o;u+=1){const i=r[u]??"",p=i.length>l?`${i.slice(0,l)}\u2026`:i;c.push(p)}return c.join(`
+`)}export{I as parse};

package/dist/src/codemod/fileRewriter/print.d.ts

@@ -0,0 +1,46 @@
+import * as recast from "recast";
+/**
+ * Print `ast` back to source, preserving the original line terminator
+ * and a leading UTF-8 BOM when the caller passes them via `source`.
+ *
+ * `source` is the ORIGINAL file text (pre-parse). We inspect it twice:
+ *   1. BOM detection via `charCodeAt(0)`. Recast's reprint normally
+ *      carries the BOM through via its reuse-original-whitespace cache,
+ *      so we only re-prepend `\uFEFF` when the printed output has lost
+ *      it. The idempotent check avoids doubling the BOM on the common
+ *      pure-round-trip path.
+ *   2. Line-terminator detection via `detectLineTerminator(source)` —
+ *      the first `\r\n` sighting wins. Passed through to
+ *      `recast.print`'s `lineTerminator` option so CRLF fixtures survive
+ *      on non-Windows hosts.
+ *
+ * The printer consults the AST's dominant quote style via
+ * `detectQuoteStyle` and threads it through `recast.print`'s `quote`
+ * option. Unchanged nodes reprint from recast's whitespace cache (so
+ * byte-equality round-trip is preserved regardless of the option),
+ * while newly-synthesised nodes without a cached print inherit the
+ * dominant style — honouring extra.raw on builder-emitted literals.
+ */
+export declare function printFile(ast: recast.types.ASTNode, source: string): string;
+/**
+ * Detect the dominant line terminator in `source`. The first `\r\n`
+ * sighting wins; otherwise returns `\n`. Defaults to `\n` for empty or
+ * single-line input so recast's printer has a deterministic answer.
+ *
+ * This MUST NOT consult `os.EOL` — Phase 0 proved that relying on
+ * `os.EOL` silently rewrites CRLF fixtures to LF on Linux CI and LF
+ * fixtures to CRLF on Windows CI.
+ */
+export declare function detectLineTerminator(source: string): "\n" | "\r\n";
+/**
+ * Count `StringLiteral` nodes in `ast` by quote style (read from
+ * `extra.raw`'s first character) and return the majority. Ties break
+ * to `"double"`; a source with zero string literals also returns
+ * `"double"` as a neutral default.
+ *
+ * Consumed by T7 builders when they emit new literals. We deliberately
+ * do NOT pass the result back into `recast.print({ quote })` — recast's
+ * reprint mechanics keep each original literal's quotes verbatim, and
+ * forcing a global style would violate byte-equality round-trip.
+ */
+export declare function detectQuoteStyle(ast: recast.types.ASTNode): "double" | "single";

package/dist/src/codemod/fileRewriter/print.js

@@ -0,0 +1,4 @@
+import*as u from"recast";const p="\uFEFF",f=65279;function m(t,c){const o=a(c),e=l(t),r=u.print(t,{quote:e,lineTerminator:o,trailingComma:!0}).code,n=c.charCodeAt(0)===f,i=r.charCodeAt(0)===f;return n&&!i?`${p}${r}`:r}function a(t){return t.includes(`\r
+`)?`\r
+`:`
+`}function l(t){let c=0,o=0;return y(t,e=>{if(e.type!=="StringLiteral"&&e.type!=="Literal")return;const r=e.extra;if(!s(r))return;const n=r.raw;if(typeof n!="string"||n.length===0)return;const i=n.charAt(0);i==="'"?c+=1:i==='"'&&(o+=1)}),c>o?"single":"double"}function y(t,c){const o=[t];for(;o.length>0;){const e=o.pop();if(!(!s(e)||typeof e.type!="string")){c(e);for(const r of Object.keys(e)){if(r==="loc"||r==="comments"||r==="tokens")continue;const n=e[r];if(Array.isArray(n))for(const i of n)s(i)&&typeof i.type=="string"&&o.push(i);else s(n)&&typeof n.type=="string"&&o.push(n)}}}}function s(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}export{a as detectLineTerminator,l as detectQuoteStyle,m as printFile};

package/dist/src/codemod/historyPaths.d.ts

@@ -0,0 +1,2 @@
+export declare function backupPath(sourcePath: string): string;
+export declare function historyEntryPath(historyDir: string, timestamp: Date): string;

package/dist/src/codemod/historyPaths.js

@@ -0,0 +1 @@
+function o(t){return`${t}.bak`}function a(t,r){const n=r.toISOString().replaceAll(":","");return`${t}/${n}.ts`}export{o as backupPath,a as historyEntryPath};

package/dist/src/codemod/index.d.ts

@@ -0,0 +1,7 @@
+export { addResource, type AddResourceError, type AddResourceSuccess, } from "./edits/addResource.js";
+export { removeResource, type RemoveResourceError, type RemoveResourceSuccess, } from "./edits/removeResource.js";
+export { modifyResource, type ModifyResourceError, type ModifyResourceSuccess, } from "./edits/modifyResource.js";
+export { listResources, type ListResourcesError } from "./listResources.js";
+export { parse } from "./fileRewriter/parse.js";
+export { StatementTypeSchema } from "./types.js";
+export type { AddOptions, CodemodError, CodemodSuccess, DuplicateResourceError, InvalidPropertyError, LinesChanged, ModifyOptions, NodeLocation, ParseError, ReferenceLocation, ReferencesRemainError, RemoveOptions, ResourceListing, ResourceListingEntry, ResourceName, ResourceNotFoundError, SemanticQueryError, StatementType, TemplateLiteralNameError, } from "./types.js";

package/dist/src/codemod/index.js

@@ -0,0 +1 @@
+import{addResource as r}from"./edits/addResource.js";import{removeResource as t}from"./edits/removeResource.js";import{modifyResource as f}from"./edits/modifyResource.js";import{listResources as x}from"./listResources.js";import{parse as a}from"./fileRewriter/parse.js";import{StatementTypeSchema as R}from"./types.js";export{R as StatementTypeSchema,r as addResource,x as listResources,f as modifyResource,a as parse,t as removeResource};

package/dist/src/codemod/listResources.d.ts

@@ -0,0 +1,4 @@
+import { type Result } from "../types/Result.js";
+import type { ResourceListing, SemanticQueryError, TemplateLiteralNameError } from "./types.js";
+export type ListResourcesError = TemplateLiteralNameError | SemanticQueryError;
+export declare function listResources(content: string, filePath?: string): Result<ResourceListing, ListResourcesError>;

package/dist/src/codemod/listResources.js

@@ -0,0 +1 @@
+import{failure as a,success as c}from"../types/Result.js";import{DEFAULT_FILE_PATH as m}from"./_internal.js";import{locateAllShapes as l}from"./semanticIndex/index.js";function f(t,s=m){const r=l(t,s);if(!r.success)return a(r.error);const o=r.data.map(e=>({type:e.type,name:e.symbolName,filePath:e.filePath,start:e.start,length:e.length}));return c({filePath:s,resources:o})}export{f as listResources};

package/dist/src/codemod/semanticIndex/findReferences.d.ts

@@ -0,0 +1,15 @@
+import { type Result } from "../../types/Result.js";
+import type { NodeLocation, ReferenceLocation, SemanticQueryError } from "../types.js";
+export type { ReferenceLocation } from "../types.js";
+export type FindReferencesError = SemanticQueryError;
+/**
+ * Resolves every reference to the variable declaration identified by
+ * `declaration.start` within `content`. Uses ts-morph's language-service
+ * reference finder and filters the results by symbol identity so shadowed
+ * bindings with the same text never cross-pollinate.
+ *
+ * Returns `success([])` when the declaration has no symbol (e.g. destructuring
+ * initialiser) or no live references. Returns `failure(...)` only when
+ * ts-morph throws during traversal or the content cannot be loaded.
+ */
+export declare function findReferences(content: string, declaration: NodeLocation, filePath?: string): Result<ReferenceLocation[], FindReferencesError>;

package/dist/src/codemod/semanticIndex/findReferences.js

@@ -0,0 +1,2 @@
+import{Node as d,SyntaxKind as m}from"ts-morph";import{failure as a,success as l}from"../../types/Result.js";import{DEFAULT_FILE_PATH as y}from"../_internal.js";import{getProject as S}from"./projectCache.js";const f=120;function T(r,n,e=y){let i;try{i=S().createSourceFile(e,r,{overwrite:!0})}catch(t){return a({kind:"SemanticQueryError",reason:"Failed to create source file",cause:t})}let o;try{o=p(i,n.start)}catch(t){return a({kind:"SemanticQueryError",reason:"Failed to resolve declaration at the supplied offset",cause:t})}if(o===void 0)return l([]);let s;try{s=o.getSymbol()}catch(t){return a({kind:"SemanticQueryError",reason:"Failed to resolve symbol for declaration",cause:t})}if(s===void 0)return l([]);let c;try{c=o.findReferencesAsNodes()}catch(t){return a({kind:"SemanticQueryError",reason:"findReferencesAsNodes failed",cause:t})}const u=[];try{for(const t of c)g(t,s)&&(F(t,o)||u.push(b(t)))}catch(t){return a({kind:"SemanticQueryError",reason:"Failed to map references to plain-data locations",cause:t})}return l(u)}function p(r,n){const e=r.getDescendantAtPos(n);return e===void 0?void 0:d.isVariableDeclaration(e)?e:e.getFirstAncestorByKind(m.VariableDeclaration)}function g(r,n){const e=r.getSymbol();return e===void 0?!1:e===n?!0:e.compilerSymbol===n.compilerSymbol}function F(r,n){const e=n.getNameNode();return r===e||r.getStart()===e.getStart()}function b(r){const n=r.getStart(),{line:e,column:i}=r.getSourceFile().getLineAndColumnAtPos(n),c=r.getSourceFile().getFullText().split(`
+`)[e-1]??"",u=c.length>f?c.slice(0,f):c;return{line:e,column:i,context:u}}export{T as findReferences};

package/dist/src/codemod/semanticIndex/index.d.ts

@@ -0,0 +1,4 @@
+export { locateByShape, locateAllShapes, type NodeLocation, type StatementType, type LocateByShapeError, } from "./locateByShape.js";
+export { findReferences, type ReferenceLocation, type FindReferencesError, } from "./findReferences.js";
+export { getProject, resetProjectForTest } from "./projectCache.js";
+export { listImports, type ImportInfo, type ListImportsError, } from "./listImports.js";

package/dist/src/codemod/semanticIndex/index.js

@@ -0,0 +1 @@
+import{locateByShape as r,locateAllShapes as t}from"./locateByShape.js";import{findReferences as f}from"./findReferences.js";import{getProject as c,resetProjectForTest as l}from"./projectCache.js";import{listImports as a}from"./listImports.js";export{f as findReferences,c as getProject,a as listImports,t as locateAllShapes,r as locateByShape,l as resetProjectForTest};

package/dist/src/codemod/semanticIndex/listImports.d.ts

@@ -0,0 +1,24 @@
+import { type Result } from "../../types/Result.js";
+import type { NodeLocation, SemanticQueryError } from "../types.js";
+/**
+ * `specifiers` contains the IMPORTED names (the original identifier on
+ * the module), not the local alias — matching the dedupe contract in
+ * `fileRewriter.appendSpecifier`.
+ */
+export interface ImportInfo {
+    module: string;
+    specifiers: string[];
+    location: NodeLocation;
+}
+export type ListImportsError = SemanticQueryError;
+/**
+ * Walk every top-level `ImportDeclaration` in `content` and return a
+ * plain-data `ImportInfo[]` in source order. Declarations with a
+ * non-literal module specifier are skipped; declarations with no named
+ * bindings (side-effect `import "x"`, default-only, namespace-only) are
+ * included with an empty `specifiers` array so callers can still detect
+ * their presence.
+ *
+ * Never throws — every failure path returns `failure(ListImportsError)`.
+ */
+export declare function listImports(content: string, filePath?: string): Result<ImportInfo[], ListImportsError>;

package/dist/src/codemod/semanticIndex/listImports.js

@@ -0,0 +1 @@
+import{Node as s}from"ts-morph";import{failure as c,success as a}from"../../types/Result.js";import{DEFAULT_FILE_PATH as u}from"../_internal.js";import{getProject as m}from"./projectCache.js";function S(t,i=u){let r;try{r=m().createSourceFile(i,t,{overwrite:!0})}catch(e){return c({kind:"SemanticQueryError",reason:"Failed to create source file",cause:e})}const o=[];try{for(const e of r.getImportDeclarations()){const n=f(e,i);n!==void 0&&o.push(n)}}catch(e){return c({kind:"SemanticQueryError",reason:"Failed to enumerate import declarations",cause:e})}return a(o)}function f(t,i){const r=t.getModuleSpecifier();if(!s.isStringLiteral(r))return;const o=r.getLiteralValue(),e=t.getNamedImports().map(n=>n.getNameNode().getText());return{module:o,specifiers:e,location:{filePath:i,start:t.getStart(),length:t.getWidth(),symbolName:o}}}export{S as listImports};

package/dist/src/codemod/semanticIndex/locateByShape.d.ts

@@ -0,0 +1,28 @@
+import { type Result } from "../../types/Result.js";
+import type { NodeLocation, StatementType, TemplateLiteralNameError, SemanticQueryError } from "../types.js";
+export type { NodeLocation, StatementType } from "../types.js";
+export type LocateByShapeError = TemplateLiteralNameError | SemanticQueryError;
+/**
+ * Locates a single `XFactory.build("Name", ...)` call matching the
+ * supplied `{ type, name }` query. Returns `success(undefined)` when
+ * the file contains no matching call; returns `failure(...)` only for
+ * template-literal factory names (Joint 1 rejection) or a genuine
+ * semantic-query error from ts-morph.
+ */
+export declare function locateByShape(content: string, query: {
+    type: StatementType;
+    name: string;
+}, filePath?: string): Result<NodeLocation | undefined, LocateByShapeError>;
+/**
+ * Walks every call expression in the source and returns a
+ * `NodeLocation & { type }` for each `XFactory.build("Name", ...)`
+ * shape. The traversal descends into `IfStatement`, `Block`,
+ * `ForStatement`, and function bodies via `forEachDescendant`.
+ *
+ * Emits `TemplateLiteralNameError` for the first non-plain-string
+ * factory name encountered — the engine cannot safely locate a
+ * template-literal name by shape.
+ */
+export declare function locateAllShapes(content: string, filePath?: string): Result<Array<NodeLocation & {
+    type: StatementType;
+}>, LocateByShapeError>;

package/dist/src/codemod/semanticIndex/locateByShape.js

@@ -0,0 +1 @@
+import{Node as s,SyntaxKind as a}from"ts-morph";import{failure as c,success as l}from"../../types/Result.js";import{DEFAULT_FILE_PATH as u}from"../_internal.js";import{getProject as m}from"./projectCache.js";const f={DatabaseFactory:"database",StorageFactory:"storage",ComputeFactory:"compute",MessagingFactory:"messaging",CdnFactory:"cdn",NetworkFactory:"network",PatternFactory:"pattern"};function g(n){return Object.prototype.hasOwnProperty.call(f,n)}function b(n,t,e=u){const o=y(n,e);if(!o.success)return o;const r=o.data.find(i=>i.type===t.type&&i.symbolName===t.name);return l(r)}function y(n,t=u){let e;try{e=m().createSourceFile(t,n,{overwrite:!0})}catch(r){return c({kind:"SemanticQueryError",reason:"Failed to create source file",cause:r})}const o=[];try{e.forEachDescendant(r=>{if(!s.isCallExpression(r))return;const i=h(r);if(i!=="not-factory-call"&&i.kind!=="binding-pattern-declared"){if(i.kind==="template-literal-name")throw new d(r,i.type);o.push({filePath:t,start:i.nameStart,length:i.nameLength,symbolName:i.name,type:i.type})}})}catch(r){return r instanceof d?c(r.toError(t)):c({kind:"SemanticQueryError",reason:"forEachDescendant traversal failed",cause:r})}return l(o)}function h(n){const t=n.getExpression();if(!s.isPropertyAccessExpression(t))return"not-factory-call";const e=E(t);if(e===void 0||F(n))return"not-factory-call";if(S(n))return{kind:"binding-pattern-declared"};const r=n.getArguments()[0];return r===void 0?"not-factory-call":s.isTemplateExpression(r)||s.isNoSubstitutionTemplateLiteral(r)?{kind:"template-literal-name",type:e}:s.isStringLiteral(r)?{kind:"match",type:e,name:r.getLiteralValue(),nameStart:r.getStart(),nameLength:r.getWidth()}:"not-factory-call"}function E(n){const t=n.getExpression();if(!s.isIdentifier(t)||n.getName()!=="build")return;const e=t.getText();if(g(e))return f[e]}function F(n){let t=n.getParent();for(;t!==void 0;){const e=t.getKind();if(e===a.TypeReference||e===a.TypeQuery||e===a.TypeLiteral||e===a.TypeAliasDeclaration||e===a.InterfaceDeclaration||e===a.TypeParameter||e===a.PropertySignature||e===a.MethodSignature||e===a.JsxOpeningElement||e===a.JsxClosingElement||e===a.JsxSelfClosingElement||e===a.JsxAttribute)return!0;t=t.getParent()}return!1}function S(n){const t=n.getFirstAncestorByKind(a.VariableDeclaration);if(t===void 0)return!1;const o=t.getNameNode().getKind();return o===a.ObjectBindingPattern||o===a.ArrayBindingPattern}class d extends Error{call;type;constructor(t,e){super("Template-literal factory name detected"),this.call=t,this.type=e,this.name="TemplateLiteralMarker"}toError(t){const o=this.call.getArguments()[0]?.getStart()??this.call.getStart(),r=this.call.getSourceFile(),{line:i,column:p}=r.getLineAndColumnAtPos(o);return{kind:"TemplateLiteralNameError",file:t,line:i,column:p,suggestion:"Replace the template literal with a plain string literal so the resource name can be resolved statically."}}}export{y as locateAllShapes,b as locateByShape};

package/dist/src/codemod/semanticIndex/projectCache.d.ts

@@ -0,0 +1,14 @@
+import { Project } from "ts-morph";
+/**
+ * Returns the shared ts-morph `Project`, creating it lazily on first call.
+ * Subsequent calls reuse the same instance.
+ */
+export declare function getProject(): Project;
+/**
+ * Clears the cached `Project`. Tests call this in `beforeEach` to
+ * guarantee isolation across describe blocks that exercise different
+ * source shapes.
+ *
+ * @internal — production code must not depend on this.
+ */
+export declare function resetProjectForTest(): void;

package/dist/src/codemod/semanticIndex/projectCache.js

@@ -0,0 +1 @@
+import{Project as t,ScriptTarget as r}from"ts-morph";let e;function i(){return e===void 0&&(e=new t({useInMemoryFileSystem:!0,skipAddingFilesFromTsConfig:!0,compilerOptions:{target:r.ES2022}})),e}function n(){e=void 0}export{i as getProject,n as resetProjectForTest};

package/dist/src/codemod/types.d.ts

@@ -0,0 +1,172 @@
+import { z } from "zod";
+/**
+ * The wider `StatementTypeSchema` in `schemas/baseSchemas.ts` also
+ * carries non-factory kinds (import, app-init, tags, custom) that the
+ * codemod never locates by factory shape.
+ */
+export declare const StatementTypeSchema: z.ZodEnum<{
+    storage: "storage";
+    database: "database";
+    compute: "compute";
+    pattern: "pattern";
+    network: "network";
+    messaging: "messaging";
+    cdn: "cdn";
+}>;
+export type StatementType = z.infer<typeof StatementTypeSchema>;
+export declare const ResourceNameSchema: z.ZodString;
+export type ResourceName = z.infer<typeof ResourceNameSchema>;
+export declare const AddOptionsSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        storage: "storage";
+        database: "database";
+        compute: "compute";
+        pattern: "pattern";
+        network: "network";
+        messaging: "messaging";
+        cdn: "cdn";
+    }>;
+    name: z.ZodString;
+    properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    filePath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AddOptions = z.infer<typeof AddOptionsSchema>;
+export declare const RemoveOptionsSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        storage: "storage";
+        database: "database";
+        compute: "compute";
+        pattern: "pattern";
+        network: "network";
+        messaging: "messaging";
+        cdn: "cdn";
+    }>;
+    name: z.ZodString;
+    filePath: z.ZodOptional<z.ZodString>;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type RemoveOptions = z.infer<typeof RemoveOptionsSchema>;
+export declare const ModifyOptionsSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        storage: "storage";
+        database: "database";
+        compute: "compute";
+        pattern: "pattern";
+        network: "network";
+        messaging: "messaging";
+        cdn: "cdn";
+    }>;
+    name: z.ZodString;
+    properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    filePath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ModifyOptions = z.infer<typeof ModifyOptionsSchema>;
+export declare const ReferenceLocationSchema: z.ZodObject<{
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+    context: z.ZodString;
+}, z.core.$strict>;
+export type ReferenceLocation = z.infer<typeof ReferenceLocationSchema>;
+export declare const LinesChangedSchema: z.ZodObject<{
+    added: z.ZodNumber;
+    removed: z.ZodNumber;
+}, z.core.$strict>;
+export type LinesChanged = z.infer<typeof LinesChangedSchema>;
+export declare const ResourceListingEntrySchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        storage: "storage";
+        database: "database";
+        compute: "compute";
+        pattern: "pattern";
+        network: "network";
+        messaging: "messaging";
+        cdn: "cdn";
+    }>;
+    name: z.ZodString;
+    filePath: z.ZodString;
+    start: z.ZodNumber;
+    length: z.ZodNumber;
+}, z.core.$strict>;
+export type ResourceListingEntry = z.infer<typeof ResourceListingEntrySchema>;
+export declare const ResourceListingSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    resources: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            storage: "storage";
+            database: "database";
+            compute: "compute";
+            pattern: "pattern";
+            network: "network";
+            messaging: "messaging";
+            cdn: "cdn";
+        }>;
+        name: z.ZodString;
+        filePath: z.ZodString;
+        start: z.ZodNumber;
+        length: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ResourceListing = z.infer<typeof ResourceListingSchema>;
+export declare const CodemodSuccessSchema: z.ZodObject<{
+    content: z.ZodString;
+    linesChanged: z.ZodObject<{
+        added: z.ZodNumber;
+        removed: z.ZodNumber;
+    }, z.core.$strict>;
+    references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        line: z.ZodNumber;
+        column: z.ZodNumber;
+        context: z.ZodString;
+    }, z.core.$strict>>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type CodemodSuccess = z.infer<typeof CodemodSuccessSchema>;
+/** @internal Bridging tuple across the ts-morph / recast boundary (ADR §1). */
+export interface NodeLocation {
+    filePath: string;
+    start: number;
+    length: number;
+    symbolName: string;
+}
+export interface ParseError {
+    kind: "ParseError";
+    file: string | undefined;
+    line: number | undefined;
+    column: number | undefined;
+    message: string;
+    sourceSnippet: string;
+}
+export interface TemplateLiteralNameError {
+    kind: "TemplateLiteralNameError";
+    file: string;
+    line: number;
+    column: number;
+    suggestion: string;
+}
+export interface DuplicateResourceError {
+    kind: "DuplicateResourceError";
+    type: StatementType;
+    name: string;
+}
+export interface ResourceNotFoundError {
+    kind: "ResourceNotFoundError";
+    type: StatementType;
+    name: string;
+    knownNames: string[];
+}
+export interface ReferencesRemainError {
+    kind: "ReferencesRemainError";
+    variable: string;
+    references: ReferenceLocation[];
+}
+export interface InvalidPropertyError {
+    kind: "InvalidPropertyError";
+    property: string;
+    reason: string;
+}
+export interface SemanticQueryError {
+    kind: "SemanticQueryError";
+    reason: string;
+    cause?: unknown;
+}
+export type CodemodError = ParseError | TemplateLiteralNameError | DuplicateResourceError | ResourceNotFoundError | ReferencesRemainError | InvalidPropertyError | SemanticQueryError;

package/dist/src/codemod/types.js

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=e.enum(["database","storage","compute","messaging","cdn","network","pattern"]),n=e.string().regex(/^[A-Z][A-Za-z0-9]*$/,"Resource name must start with an uppercase letter and contain only alphanumerics (PascalCase)."),o=e.record(e.string(),e.unknown()),c=e.object({type:t,name:n,properties:o,filePath:e.string().optional()}).strict(),m=e.object({type:t,name:n,filePath:e.string().optional(),force:e.boolean().optional()}).strict(),p=e.object({type:t,name:n,properties:o,filePath:e.string().optional()}).strict(),r=e.object({line:e.number().int().nonnegative(),column:e.number().int().nonnegative(),context:e.string()}).strict(),a=e.object({added:e.number().int().nonnegative(),removed:e.number().int().nonnegative()}).strict(),i=e.object({type:t,name:e.string(),filePath:e.string(),start:e.number().int().nonnegative(),length:e.number().int().nonnegative()}).strict(),g=e.object({filePath:e.string(),resources:e.array(i)}).strict(),h=e.object({content:e.string(),linesChanged:a,references:e.array(r).optional(),warnings:e.array(e.string()).optional()}).strict();export{c as AddOptionsSchema,h as CodemodSuccessSchema,a as LinesChangedSchema,p as ModifyOptionsSchema,r as ReferenceLocationSchema,m as RemoveOptionsSchema,i as ResourceListingEntrySchema,g as ResourceListingSchema,n as ResourceNameSchema,t as StatementTypeSchema};