svelte-origin 0.0.0 → 1.0.0-next.49

package/dist/transform/ast-parser.d.ts

@@ -0,0 +1,282 @@
+/**
+ * AST Parser utilities for svelte-origin
+ *
+ * Uses acorn + @sveltejs/acorn-typescript for reliable TypeScript/JavaScript parsing.
+ * This provides future-safe parsing for complex expressions that regex can't handle.
+ *
+ * Why acorn + @sveltejs/acorn-typescript?
+ * - Maintained by Svelte team (Rich Harris et al.)
+ * - 0 dependencies (the TypeScript plugin)
+ * - Small bundle: acorn ~27KB gzip, plugin ~16KB gzip
+ * - Supports full TypeScript syntax, decorators, JSX/TSX
+ *
+ * @see https://github.com/sveltejs/acorn-typescript
+ */
+import { type Options } from 'acorn';
+import type * as ESTree from 'estree';
+/**
+ * Acorn nodes include start/end positions not in ESTree types
+ */
+export type AcornNode<T extends ESTree.Node = ESTree.Node> = T & {
+    start: number;
+    end: number;
+};
+/**
+ * Parse result with error handling
+ */
+export type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Helper to safely get node positions (acorn adds these)
+ */
+export declare function getNodePosition(node: ESTree.Node): {
+    start: number;
+    end: number;
+};
+/**
+ * Parse TypeScript/JavaScript source code into an AST
+ */
+export declare function parse(source: string, options?: Partial<Options>): ESTree.Program;
+/**
+ * Safely parse source, returning a result type instead of throwing
+ */
+export declare function tryParse(source: string, options?: Partial<Options>): ParseResult<ESTree.Program>;
+/**
+ * Parse a single expression (for parsing values, defaults, etc.)
+ */
+export declare function parseExpression(source: string, options?: Partial<Options>): ESTree.Expression;
+/**
+ * Safely parse an expression, returning a result type instead of throwing
+ */
+export declare function tryParseExpression(source: string, options?: Partial<Options>): ParseResult<ESTree.Expression>;
+/**
+ * Parse an object literal expression from source like `{ a: 1, b: 2 }`
+ * Wraps in parens to allow parsing as expression
+ */
+export declare function parseObjectLiteral(source: string): ParseResult<AcornNode<ESTree.ObjectExpression>>;
+/**
+ * Generate code from an AST node
+ */
+export declare function generate(node: ESTree.Node): string;
+/**
+ * Parsed object member with full metadata
+ */
+export interface ParsedObjectMember {
+    /** The property key (name or computed expression source) */
+    key: string;
+    /** The kind of member */
+    kind: 'property' | 'method' | 'getter' | 'setter';
+    /** The value source code */
+    value: string;
+    /** Whether the key is computed [expr] */
+    computed: boolean;
+    /** Whether it's an async method */
+    async: boolean;
+    /** Whether it's a generator method */
+    generator: boolean;
+    /** Start position in original source (adjusted for wrapper) */
+    start: number;
+    /** End position in original source (adjusted for wrapper) */
+    end: number;
+    /** The raw AST node for advanced use */
+    node: ESTree.Property | ESTree.SpreadElement;
+}
+/**
+ * Parse an object literal and extract its members with full metadata.
+ * Uses AST for reliable parsing of complex expressions.
+ *
+ * @param objectSource - The content inside {...}, not including braces
+ * @returns Array of parsed members, or null if parsing fails
+ */
+export declare function parseObjectMembersAST(objectSource: string): ParsedObjectMember[] | null;
+/**
+ * Result from analyzing an expression
+ */
+export interface ExpressionAnalysis {
+    type: ESTree.Node['type'];
+    hasThisReferences: boolean;
+    hasSuperReferences: boolean;
+    identifiers: Set<string>;
+    memberExpressions: Array<{
+        object: string;
+        property: string;
+        start: number;
+        end: number;
+    }>;
+    callExpressions: Array<{
+        callee: string;
+        start: number;
+        end: number;
+    }>;
+}
+/**
+ * Analyze an expression for references and structure
+ */
+export declare function analyzeExpression(source: string): ExpressionAnalysis;
+/**
+ * Find all `this.propertyName` references in an expression
+ * Returns an array of property names
+ */
+export declare function findThisReferences(source: string): string[];
+/**
+ * Position and metadata for a this.* reference
+ */
+export interface ThisReference {
+    /** Property name being accessed (e.g., 'count' in this.count) */
+    property: string;
+    /** Start position in source */
+    start: number;
+    /** End position in source */
+    end: number;
+    /** Whether this is part of a member chain (e.g., this.props.x) */
+    isChained: boolean;
+    /** The full chain if chained (e.g., ['props', 'x']) */
+    chain: string[];
+}
+/**
+ * Collect all this.* references with their positions
+ * Uses AST for accurate identification
+ */
+export declare function collectThisReferences(source: string): ThisReference[];
+/**
+ * Transform `this.x` references in source code using AST-based identification.
+ * Much more reliable than regex for complex expressions.
+ *
+ * @param source - Source code containing this.* references
+ * @param transform - Function to transform each reference
+ */
+export declare function transformThisReferences(source: string, transform: (ref: ThisReference) => string): string;
+/**
+ * Check if source contains any `this` references
+ */
+export declare function hasThisReferences(source: string): boolean;
+/**
+ * Check if source contains any `super` references
+ */
+export declare function hasSuperReferences(source: string): boolean;
+/**
+ * Result of extracting $bindable from an expression
+ */
+export interface BindableExtraction {
+    isBindable: boolean;
+    /** The inner value (argument to $bindable) */
+    innerValue: string;
+    /** Any generic type parameter, e.g., '<number>' */
+    genericType: string | null;
+}
+/**
+ * Extract $bindable from a value expression using AST.
+ * Handles complex cases like $bindable<Map<K, V>>(new Map())
+ */
+export declare function extractBindableAST(value: string): BindableExtraction;
+/**
+ * Information about a call expression
+ */
+export interface CallExpressionInfo {
+    /** The callee name or chain (e.g., '$state', '$derived.by') */
+    callee: string;
+    /** Arguments as source strings */
+    arguments: string[];
+    /** Generic type parameters if any */
+    typeParams: string | null;
+    /** Start position */
+    start: number;
+    /** End position */
+    end: number;
+}
+/**
+ * Parse a call expression and extract its components
+ */
+export declare function parseCallExpression(source: string): CallExpressionInfo | null;
+/**
+ * Result of extracting $state from an expression
+ */
+export interface StateExtraction {
+    isState: boolean;
+    /** The variant: '$state', '$state.raw', '$state.frozen' */
+    variant: string;
+    /** The initial value argument */
+    initialValue: string;
+    /** Any generic type parameter */
+    genericType: string | null;
+}
+/**
+ * Extract $state (and variants) from a value expression using AST.
+ */
+export declare function extractStateAST(value: string): StateExtraction;
+/**
+ * Result of extracting $derived from an expression
+ */
+export interface DerivedExtraction {
+    isDerived: boolean;
+    /** The variant: '$derived' or '$derived.by' */
+    variant: string;
+    /** The expression or function argument */
+    argument: string;
+}
+/**
+ * Extract $derived (and variants) from a value expression using AST.
+ */
+export declare function extractDerivedAST(value: string): DerivedExtraction;
+/**
+ * Strip TypeScript type annotations from an expression
+ * Useful for extracting runtime values from typed code
+ */
+export declare function stripTypeAnnotations(source: string): string;
+/**
+ * Split object literal content by top-level commas using AST.
+ * Much more reliable than regex for complex expressions.
+ *
+ * @param objectContent - The content inside {...}, not including braces
+ * @returns Array of member source strings, or null if parsing fails
+ */
+export declare function splitObjectMembersAST(objectContent: string): string[] | null;
+/**
+ * Find matching bracket using AST-based depth tracking.
+ * More reliable than character-by-character scanning.
+ *
+ * @param source - Full source code
+ * @param openIndex - Position of opening bracket
+ * @param openChar - The opening bracket character
+ * @param closeChar - The closing bracket character
+ * @returns Position of matching close bracket, or -1 if not found
+ */
+export declare function findMatchingBracketAST(source: string, openIndex: number, openChar?: string, closeChar?: string): number;
+/**
+ * Find the position of top-level 'as' type assertion using AST awareness
+ * Returns -1 if not found at top level
+ */
+export declare function findTopLevelAsAST(value: string): number;
+/**
+ * Parse a function body and extract return statement value
+ * Useful for analyzing getter functions
+ */
+export declare function extractReturnValue(functionBody: string): string | null;
+/** Type guard for SpreadElement */
+export declare function isSpreadElement(node: ESTree.Node): node is ESTree.SpreadElement;
+/** Type guard for Property */
+export declare function isProperty(node: ESTree.Node): node is ESTree.Property;
+/** Type guard for Identifier */
+export declare function isIdentifier(node: ESTree.Node): node is ESTree.Identifier;
+/** Type guard for CallExpression */
+export declare function isCallExpression(node: ESTree.Node): node is ESTree.CallExpression;
+/** Type guard for MemberExpression */
+export declare function isMemberExpression(node: ESTree.Node): node is ESTree.MemberExpression;
+/** Type guard for FunctionExpression */
+export declare function isFunctionExpression(node: ESTree.Node): node is ESTree.FunctionExpression;
+/** Type guard for ArrowFunctionExpression */
+export declare function isArrowFunctionExpression(node: ESTree.Node): node is ESTree.ArrowFunctionExpression;
+/**
+ * Check if a string is a valid TypeScript/JavaScript expression
+ */
+export declare function isValidExpression(source: string): boolean;
+/**
+ * Check if a string is a valid TypeScript/JavaScript program
+ */
+export declare function isValidProgram(source: string): boolean;
+export type { ESTree };

package/dist/transform/attrs-for-transform.d.ts

@@ -0,0 +1,17 @@
+/**
+ * $origin.for() transformation logic.
+ *
+ * This module handles transforming $origin.for(X) calls which support:
+ * - $origin.for(OriginFactory) - get attrs for an origin factory
+ * - $origin.for('input') - get typed element attrs
+ */
+import type MagicString from 'magic-string';
+import { type SchemaResolver } from './schema';
+/**
+ * Transform $origin.for(X) calls - sync fallback version.
+ */
+export declare function transformAttrsForCallsSync(s: MagicString, source: string, neededImports: Set<string>): boolean;
+/**
+ * Transform $origin.for(X) calls - async version with schema resolution.
+ */
+export declare function transformAttrsForCalls(s: MagicString, source: string, neededImports: Set<string>, schemaResolver?: SchemaResolver): Promise<boolean>;

package/dist/transform/attrs-origin-transform.d.ts

@@ -0,0 +1,38 @@
+/**
+ * $origin.component() transformation logic.
+ *
+ * This module handles transforming $origin.component(Factory)
+ * calls in component scripts into proper $props() destructuring and factory calls.
+ */
+import type MagicString from 'magic-string';
+import { type SchemaResolver } from './schema';
+/**
+ * Information about a tracked origin instance (for destructuring transform)
+ */
+export interface TrackedOriginInstance {
+    /** Variable name holding the origin instance */
+    varName: string;
+    /** The factory name/expression used to create it */
+    factoryExpr: string;
+    /** Start position in source */
+    startPos: number;
+    /** End position in source */
+    endPos: number;
+}
+/**
+ * Result from transformAttrsOriginCalls including $$Props info for later injection
+ */
+export interface AttrsOriginTransformResult {
+    changed: boolean;
+    propsTypeDeclaration: string | null;
+    /** Tracked origin instances for destructuring transform */
+    originInstances: Map<string, TrackedOriginInstance>;
+}
+/**
+ * Transform $origin.component(X) calls - sync fallback version.
+ */
+export declare function transformAttrsOriginCallsSync(s: MagicString, source: string, neededImports: Set<string>): AttrsOriginTransformResult;
+/**
+ * Transform $origin.component(X) calls - async version with schema resolution.
+ */
+export declare function transformAttrsOriginCalls(s: MagicString, source: string, neededImports: Set<string>, schemaResolver?: SchemaResolver): Promise<AttrsOriginTransformResult>;

package/dist/transform/attrs-schema.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Attribute schema parsing and generation utilities.
+ *
+ * This module handles parsing $origin.props({...}) content and generating
+ * the __attrSchema object that describes each attribute's metadata.
+ */
+/**
+ * Parsed attribute details for code generation
+ */
+export interface AttrDetail {
+    key: string;
+    defaultValue: string;
+    bindable: boolean;
+    hasDefault: boolean;
+}
+/**
+ * Generate __attrSchema code from the attrs source.
+ *
+ * Input: 'label: "Counter", count: $bindable(0), step: undefined as undefined | number'
+ * Output: '{ label: { default: "Counter", bindable: false, hasDefault: true }, ... }'
+ */
+export declare function generateAttrSchemaFromSource(attrsSource: string): string;
+/**
+ * Parse attrs source and return structured details for each attr.
+ *
+ * Input: 'label: "Counter", count: $bindable(0), step: 1 as number'
+ * Output: [{ key: 'label', defaultValue: '"Counter"', bindable: false, hasDefault: true }, ...]
+ */
+export declare function parseAttrsSource(attrsSource: string): AttrDetail[];
+/**
+ * Split attrs source by top-level commas.
+ * Uses the shared splitByTopLevelCommas from comments.ts.
+ */
+export { splitByTopLevelCommas as splitAttrsSource } from './comments';
+/**
+ * Parse members from an object literal source.
+ * This is the type definition for parsed members.
+ */
+export interface ObjectMember {
+    key: string;
+    value: string;
+    isGetter: boolean;
+    isSetter: boolean;
+    isMethod: boolean;
+    isAsync: boolean;
+    isGenerator: boolean;
+    isComputed: boolean;
+}
+/**
+ * Parse members from an object literal source.
+ *
+ * This regex-based parser handles:
+ * - Methods, getters, setters
+ * - Async and generator functions
+ * - Computed property names
+ * - Complex expressions in values
+ *
+ * Note: An AST-based version exists in ast-parser.ts (parseObjectMembersAST) but
+ * produces different output format for methods (value excludes opening paren).
+ * Downstream code expects value to include `(params) { body }` for methods,
+ * so the regex parser is used here.
+ */
+export declare function parseObjectMembers(source: string): ObjectMember[];

package/dist/transform/codegen.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Code generation utilities for svelte-origin transformations
+ */
+/**
+ * Generate the import statement for runtime functions.
+ *
+ * @example
+ * generateRuntimeImport(['__createOrigin', '__attrsFor'])
+ * // Returns: "import { __createOrigin, __attrsFor } from 'svelte-origin/runtime'"
+ */
+export declare function generateRuntimeImport(functions: string[]): string;
+/**
+ * Indent each line of code by a given amount
+ */
+export declare function indent(code: string, tabs?: number): string;

package/dist/transform/comments.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared comment stripping utilities.
+ *
+ * These functions handle stripping comments from source code strings,
+ * used by both schema.ts and attrs-schema.ts for parsing attr definitions.
+ */
+/**
+ * Strip leading comments (JSDoc, block, line) from a string.
+ */
+export declare function stripLeadingComments(str: string): string;
+/**
+ * Find orphaned block-comment close markers that exist without a corresponding open.
+ * Returns the index where to cut, or -1 if none found.
+ */
+export declare function findOrphanedCommentClose(str: string): number;
+/**
+ * Find where corrupted comment content starts before an orphaned close marker.
+ * Scans forward to find the last position that looks like valid JS.
+ */
+export declare function findCorruptedContentStart(str: string, closeMarkerIdx: number): number;
+/**
+ * Strip trailing inline comments from a value string.
+ * Handles block comments at the end of a value.
+ * Must be careful not to strip comments inside strings or nested structures.
+ */
+export declare function stripTrailingComments(str: string): string;
+/**
+ * Split content by top-level commas (not inside nested structures).
+ * Handles strings, comments, and generics correctly.
+ */
+export declare function splitByTopLevelCommas(source: string): string[];

package/dist/transform/core.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Core transformation logic for svelte-origin
+ *
+ * Main entry point for transformations that convert macro syntax into runtime calls.
+ */
+import MagicString from 'magic-string';
+import type { SchemaResolver } from './schema';
+export type { SchemaResolver } from './schema';
+export type { AttrDetail } from './attrs-schema';
+export type { AttrsOriginTransformResult } from './attrs-origin-transform';
+export interface TransformOptions {
+    filename?: string;
+    isComponent?: boolean;
+    schemaResolver?: SchemaResolver;
+}
+export interface TransformResult {
+    code: string;
+    changed: boolean;
+    map?: ReturnType<MagicString['generateMap']>;
+}
+/**
+ * Transform a script/module containing svelte-origin macros.
+ *
+ * @overload Sync version when no schemaResolver is provided
+ * @overload Async version when schemaResolver is provided
+ */
+export declare function transformScript(source: string, options?: TransformOptions & {
+    schemaResolver?: undefined;
+}): TransformResult;
+export declare function transformScript(source: string, options: TransformOptions & {
+    schemaResolver: SchemaResolver;
+}): Promise<TransformResult>;
+/**
+ * Transform script content from the script hook.
+ * Designed for preprocessor script hook where content is already extracted.
+ */
+export declare function transformScriptContent(source: string, options: TransformOptions): Promise<TransformResult>;

package/dist/transform/declaration-parser.d.ts

@@ -0,0 +1,77 @@
+/**
+ * TypeScript/JavaScript declaration parsing utilities.
+ *
+ * This module handles parsing variable declarations from source code,
+ * with full support for TypeScript type annotations, generics, and exports.
+ */
+/**
+ * Information about a variable declaration found in source code.
+ * Handles all TypeScript declaration variants:
+ *
+ * Basic:
+ *   let x = value
+ *   const x = value
+ *
+ * With type annotation:
+ *   let x: Type = value
+ *   const x: Type<T> = value
+ *   const x: Type<T, U<V>> = value
+ *
+ * With export:
+ *   export let x = value
+ *   export const x: Type = value
+ *
+ * Complex types:
+ *   let x: Type | Other = value
+ *   let x: Type & Other = value
+ *   let x: () => Type = value
+ */
+export interface VariableDeclaration {
+    /** The variable name */
+    varName: string;
+    /** Start index of the entire declaration (including export/let/const) */
+    startIndex: number;
+    /** Index where the value expression starts (after =) */
+    valueStartIndex: number;
+    /** Whether it has 'export' keyword */
+    hasExport: boolean;
+    /** The type annotation if present (without the colon) */
+    typeAnnotation: string | null;
+}
+/**
+ * Find all variable declarations that are assigned a specific macro call.
+ * Handles all TypeScript declaration patterns:
+ *
+ * - let x = $macro(...)
+ * - const x = $macro(...)
+ * - let x: Type = $macro(...)
+ * - const x: Type<T> = $macro(...)
+ * - export let x = $macro(...)
+ * - export const x: Type = $macro(...)
+ *
+ * @param source The source code to search
+ * @param macroPattern The macro to find (e.g., '$origin.component', '$origin.for', '$origin')
+ * @returns Array of declarations with their metadata
+ */
+export declare function findVariableDeclarationsWithMacro(source: string, macroPattern: string): (VariableDeclaration & {
+    macroOpenParen: number;
+})[];
+/**
+ * Look backwards from a position to find a variable declaration.
+ * Handles: [export] (let|const) varName [: Type] =
+ */
+export declare function findDeclarationBefore(source: string, beforeIndex: number): VariableDeclaration | null;
+/**
+ * Check if the source already has a $$Props type declaration.
+ * Looks for 'type $$Props' or 'interface $$Props' patterns.
+ */
+export declare function hasExistingPropsDeclaration(source: string): boolean;
+/**
+ * Find the position right after imports to inject $$Props.
+ * Returns the position after the last import statement, or after the script tag.
+ *
+ * Handles both single-line and multi-line imports:
+ * - import { x } from 'y'
+ * - import {\n  x,\n  y\n} from 'z'
+ */
+export declare function findPropsInjectionPosition(source: string): number;

package/dist/transform/element-types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Get the svelte/elements type import for an HTML element name.
+ *
+ * Uses svelteHTML.IntrinsicElements for type-checking compatibility with Svelte's
+ * internal createElement function, which expects IntrinsicElements types.
+ *
+ * @param element - The HTML element name (e.g., 'input', 'button', 'div')
+ * @returns The full type expression using svelteHTML.IntrinsicElements
+ */
+export declare function getElementTypeImport(element: string): string;

package/dist/transform/expression-utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Expression parsing utilities for svelte-origin transforms
+ *
+ * Shared utilities for parsing and manipulating TypeScript expressions.
+ */
+/**
+ * Check if an expression is a function call (ends with parentheses).
+ *
+ * This correctly handles:
+ * - Simple calls: `Factory()`
+ * - Generic calls: `Factory<T>()`
+ * - Nested calls: `outer(inner())`
+ *
+ * @example
+ * isCallExpression('Factory()') // true
+ * isCallExpression('Factory<T>()') // true
+ * isCallExpression('Factory') // false
+ * isCallExpression('Factory<T>') // false (generic type, not a call)
+ */
+export declare function isCallExpression(expr: string): boolean;
+/**
+ * Extract the factory expression from a call expression by stripping the trailing `()`.
+ *
+ * @example
+ * extractFactoryFromCall('List<T>()') // 'List<T>'
+ * extractFactoryFromCall('MyFactory()') // 'MyFactory'
+ * extractFactoryFromCall('outer(inner)') // 'outer'
+ */
+export declare function extractFactoryFromCall(expr: string): string;
+/**
+ * Check if an expression has generic type parameters.
+ *
+ * @example
+ * hasGenericTypeParams('Factory<T>') // true
+ * hasGenericTypeParams('Factory<T>()') // true
+ * hasGenericTypeParams('Factory') // false
+ * hasGenericTypeParams('Factory()') // false
+ */
+export declare function hasGenericTypeParams(expr: string): boolean;
+/**
+ * Extract the base factory name without generic type parameters or call parentheses.
+ *
+ * @example
+ * extractBaseFactoryName('Factory<T>()') // 'Factory'
+ * extractBaseFactoryName('Factory<T>') // 'Factory'
+ * extractBaseFactoryName('Factory()') // 'Factory'
+ * extractBaseFactoryName('Factory') // 'Factory'
+ */
+export declare function extractBaseFactoryName(expr: string): string;
+/**
+ * Normalize a factory expression to ensure it's callable.
+ * Adds `()` if expression has generic params but no call parens.
+ *
+ * @example
+ * normalizeFactoryCall('Factory<T>') // 'Factory<T>()'
+ * normalizeFactoryCall('Factory<T>()') // 'Factory<T>()'
+ * normalizeFactoryCall('Factory') // 'Factory'
+ */
+export declare function normalizeFactoryCall(expr: string): string;