@fictjs/compiler 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import * as BabelCore from '@babel/core';
+import { SourceLocation, Node, ClassBody, LVal } from '@babel/types';
 
 interface CompilerWarning {
     code: string;
@@ -146,6 +147,397 @@ declare function resolveModuleMetadata(source: string, importer: string | undefi
 declare function setModuleMetadata(fileName: string | undefined, metadata: ModuleReactiveMetadata, options?: FictCompilerOptions): void;
 declare function clearModuleMetadata(options?: FictCompilerOptions): void;
 
+type TraceMarkerKind = 'once' | 'reactive' | 'effect';
+interface TraceMarker {
+    kind: TraceMarkerKind;
+    label: string;
+    deps?: string[];
+    regionId?: number;
+    runCount?: number;
+    lastDurationMs?: number;
+}
+interface LineTrace {
+    line: number;
+    markers: TraceMarker[];
+}
+interface RegionInfoSerializable {
+    id: number;
+    startLine?: number;
+    startColumn?: number;
+    endLine?: number;
+    endColumn?: number;
+    dependencies: string[];
+    declarations: string[];
+    hasControlFlow: boolean;
+    hasReactiveWrites: boolean;
+    children?: RegionInfoSerializable[];
+}
+interface AnalyzeDiagnostic {
+    code: string;
+    message: string;
+    severity: 'error' | 'warning' | 'info' | 'hint';
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+}
+interface ComponentAnalysis {
+    name: string;
+    startLine: number;
+    endLine: number;
+    trace: LineTrace[];
+    regions?: RegionInfoSerializable[];
+}
+interface AnalyzeOptions {
+    includeRegions?: boolean;
+    includeDiagnostics?: boolean;
+    verbosity?: 'minimal' | 'verbose';
+    compilerOptions?: Partial<FictCompilerOptions>;
+}
+interface AnalyzeResult {
+    fileName: string;
+    components: ComponentAnalysis[];
+    diagnostics: AnalyzeDiagnostic[];
+}
+
+declare function analyzeFictFile(code: string, fileName: string, options?: AnalyzeOptions): AnalyzeResult;
+
+/**
+ * Type alias for class body members from Babel AST.
+ */
+type BabelClassMember = ClassBody['body'][number];
+/**
+ * Type alias for function parameter nodes from Babel AST.
+ * These are preserved for proper props pattern lowering.
+ * Includes Identifier, Pattern (ObjectPattern, ArrayPattern), and RestElement.
+ */
+type BabelParamNode = Node;
+type BlockId = number;
+interface SourceInfo {
+    loc?: SourceLocation | null;
+}
+/** Terminator of a basic block */
+type Terminator = ({
+    kind: 'Return';
+    argument?: Expression;
+} & SourceInfo) | ({
+    kind: 'Throw';
+    argument: Expression;
+} & SourceInfo) | ({
+    kind: 'Jump';
+    target: BlockId;
+} & SourceInfo) | ({
+    kind: 'Branch';
+    test: Expression;
+    consequent: BlockId;
+    alternate: BlockId;
+} & SourceInfo) | ({
+    kind: 'Switch';
+    discriminant: Expression;
+    cases: {
+        test?: Expression;
+        target: BlockId;
+    }[];
+} & SourceInfo) | ({
+    kind: 'Unreachable';
+} & SourceInfo) | ({
+    kind: 'Break';
+    target: BlockId;
+    label?: string;
+} & SourceInfo) | ({
+    kind: 'Continue';
+    target: BlockId;
+    label?: string;
+} & SourceInfo) | ({
+    kind: 'ForOf';
+    variable: string;
+    /** Variable declaration kind (const, let, var) */
+    variableKind: 'const' | 'let' | 'var';
+    /** Original pattern for destructuring (stored as Babel AST node) */
+    pattern?: LVal;
+    iterable: Expression;
+    body: BlockId;
+    exit: BlockId;
+} & SourceInfo) | ({
+    kind: 'ForIn';
+    variable: string;
+    /** Variable declaration kind (const, let, var) */
+    variableKind: 'const' | 'let' | 'var';
+    /** Original pattern for destructuring (stored as Babel AST node) */
+    pattern?: LVal;
+    object: Expression;
+    body: BlockId;
+    exit: BlockId;
+} & SourceInfo) | ({
+    kind: 'Try';
+    tryBlock: BlockId;
+    catchBlock?: BlockId;
+    catchParam?: string;
+    finallyBlock?: BlockId;
+    exit: BlockId;
+} & SourceInfo);
+/** Instruction interfaces for proper type narrowing */
+interface AssignInstruction extends SourceInfo {
+    kind: 'Assign';
+    target: Identifier;
+    value: Expression;
+    declarationKind?: 'const' | 'let' | 'var' | 'function';
+}
+interface ExpressionInstruction extends SourceInfo {
+    kind: 'Expression';
+    value: Expression;
+}
+interface PhiInstruction extends SourceInfo {
+    kind: 'Phi';
+    variable: string;
+    target: Identifier;
+    sources: {
+        block: BlockId;
+        id: Identifier;
+    }[];
+}
+/** A single HIR instruction */
+type Instruction = AssignInstruction | ExpressionInstruction | PhiInstruction;
+/** Minimal expression placeholder; future work will refine variants */
+type Expression = Identifier | Literal | ImportExpression | MetaProperty | CallExpression | MemberExpression | BinaryExpression | UnaryExpression | ConditionalExpression | LogicalExpression | ArrayExpression | ObjectExpression | JSXElementExpression | ArrowFunctionExpression | FunctionExpression | AssignmentExpression | UpdateExpression | TemplateLiteral | SpreadElement | AwaitExpression | NewExpression | SequenceExpression | YieldExpression | OptionalCallExpression | TaggedTemplateExpression | ClassExpression | ThisExpression | SuperExpression | OptionalMemberExpression;
+interface Identifier extends SourceInfo {
+    kind: 'Identifier';
+    name: string;
+}
+interface Literal extends SourceInfo {
+    kind: 'Literal';
+    value: string | number | boolean | bigint | null | undefined | RegExp;
+}
+interface ImportExpression extends SourceInfo {
+    kind: 'ImportExpression';
+    source: Expression;
+}
+interface MetaProperty extends SourceInfo {
+    kind: 'MetaProperty';
+    meta: Identifier;
+    property: Identifier;
+}
+interface CallExpression extends SourceInfo {
+    kind: 'CallExpression';
+    callee: Expression;
+    arguments: Expression[];
+    /** Optional purity hint (e.g., from @__PURE__ annotations) */
+    pure?: boolean;
+}
+interface MemberExpression extends SourceInfo {
+    kind: 'MemberExpression';
+    object: Expression;
+    property: Expression;
+    computed: boolean;
+    optional?: boolean;
+}
+interface BinaryExpression extends SourceInfo {
+    kind: 'BinaryExpression';
+    operator: string;
+    left: Expression;
+    right: Expression;
+}
+interface UnaryExpression extends SourceInfo {
+    kind: 'UnaryExpression';
+    operator: string;
+    argument: Expression;
+    prefix: boolean;
+}
+interface ConditionalExpression extends SourceInfo {
+    kind: 'ConditionalExpression';
+    test: Expression;
+    consequent: Expression;
+    alternate: Expression;
+}
+interface LogicalExpression extends SourceInfo {
+    kind: 'LogicalExpression';
+    operator: '&&' | '||' | '??';
+    left: Expression;
+    right: Expression;
+}
+interface ArrayExpression extends SourceInfo {
+    kind: 'ArrayExpression';
+    elements: Expression[];
+}
+interface ObjectProperty extends SourceInfo {
+    kind: 'Property';
+    key: Expression;
+    computed?: boolean;
+    value: Expression;
+    shorthand?: boolean;
+    /**
+     * Property kind for object methods/getters/setters.
+     * Undefined or 'init' indicates a standard property initializer.
+     */
+    propertyKind?: 'init' | 'method' | 'get' | 'set';
+}
+interface ObjectExpression extends SourceInfo {
+    kind: 'ObjectExpression';
+    properties: (ObjectProperty | SpreadElement)[];
+}
+interface JSXElementExpression extends SourceInfo {
+    kind: 'JSXElement';
+    tagName: string | Expression;
+    isComponent: boolean;
+    attributes: JSXAttribute[];
+    children: JSXChild[];
+}
+interface JSXAttribute extends SourceInfo {
+    name: string;
+    value: Expression | null;
+    isSpread?: boolean;
+    spreadExpr?: Expression;
+}
+type JSXChild = {
+    kind: 'text';
+    value: string;
+    loc?: SourceLocation | null;
+} | {
+    kind: 'expression';
+    value: Expression;
+    loc?: SourceLocation | null;
+} | {
+    kind: 'element';
+    value: JSXElementExpression;
+    loc?: SourceLocation | null;
+};
+interface ArrowFunctionExpression extends SourceInfo {
+    kind: 'ArrowFunction';
+    params: Identifier[];
+    /** Original Babel param AST nodes for preserving patterns/rest params */
+    rawParams?: BabelParamNode[];
+    body: Expression | BasicBlock[];
+    isExpression: boolean;
+    isAsync?: boolean;
+    /** Marks this function as a reactive scope callback (e.g., renderHook(() => ...)). */
+    reactiveScope?: string;
+}
+interface FunctionExpression extends SourceInfo {
+    kind: 'FunctionExpression';
+    name?: string;
+    params: Identifier[];
+    /** Original Babel param AST nodes for preserving patterns/rest params */
+    rawParams?: BabelParamNode[];
+    body: BasicBlock[];
+    isAsync?: boolean;
+    /** Marks this function as a reactive scope callback (e.g., renderHook(() => ...)). */
+    reactiveScope?: string;
+}
+interface AssignmentExpression extends SourceInfo {
+    kind: 'AssignmentExpression';
+    operator: string;
+    left: Expression;
+    right: Expression;
+}
+interface UpdateExpression extends SourceInfo {
+    kind: 'UpdateExpression';
+    operator: '++' | '--';
+    argument: Expression;
+    prefix: boolean;
+}
+interface TemplateLiteral extends SourceInfo {
+    kind: 'TemplateLiteral';
+    quasis: string[];
+    expressions: Expression[];
+}
+interface SpreadElement extends SourceInfo {
+    kind: 'SpreadElement';
+    argument: Expression;
+}
+interface AwaitExpression extends SourceInfo {
+    kind: 'AwaitExpression';
+    argument: Expression;
+}
+interface NewExpression extends SourceInfo {
+    kind: 'NewExpression';
+    callee: Expression;
+    arguments: Expression[];
+}
+interface SequenceExpression extends SourceInfo {
+    kind: 'SequenceExpression';
+    expressions: Expression[];
+}
+interface YieldExpression extends SourceInfo {
+    kind: 'YieldExpression';
+    argument: Expression | null;
+    delegate: boolean;
+}
+interface OptionalCallExpression extends SourceInfo {
+    kind: 'OptionalCallExpression';
+    callee: Expression;
+    arguments: Expression[];
+    optional: boolean;
+    /** Optional purity hint (e.g., from @__PURE__ annotations) */
+    pure?: boolean;
+}
+interface TaggedTemplateExpression extends SourceInfo {
+    kind: 'TaggedTemplateExpression';
+    tag: Expression;
+    quasi: TemplateLiteral;
+}
+interface ClassExpression extends SourceInfo {
+    kind: 'ClassExpression';
+    name?: string;
+    superClass?: Expression;
+    /** Class body elements - stored as Babel AST nodes */
+    body: BabelClassMember[];
+}
+interface ThisExpression extends SourceInfo {
+    kind: 'ThisExpression';
+}
+interface SuperExpression extends SourceInfo {
+    kind: 'SuperExpression';
+}
+interface OptionalMemberExpression extends SourceInfo {
+    kind: 'OptionalMemberExpression';
+    object: Expression;
+    property: Expression;
+    computed: boolean;
+    optional: boolean;
+}
+interface BasicBlock {
+    id: BlockId;
+    instructions: Instruction[];
+    terminator: Terminator;
+}
+interface HIRFunction extends SourceInfo {
+    name?: string;
+    params: Identifier[];
+    blocks: BasicBlock[];
+    /** Original Babel param AST nodes for proper props pattern lowering */
+    rawParams?: BabelParamNode[];
+    /** Optional SSA version map for consumers */
+    ssaMap?: Map<string, number>;
+    /** Optional metadata about the origin of this function */
+    meta?: {
+        fromExpression?: boolean;
+        isArrow?: boolean;
+        hasExpressionBody?: boolean;
+        isAsync?: boolean;
+        noMemo?: boolean;
+        pure?: boolean;
+        /**
+         * Hook return info parsed from @fictReturn JSDoc annotation.
+         * Allows cross-module hook return type declarations.
+         */
+        hookReturnInfo?: {
+            objectProps?: Map<string, 'signal' | 'memo'>;
+            arrayProps?: Map<number, 'signal' | 'memo'>;
+            directAccessor?: 'signal' | 'memo';
+        };
+    };
+}
+
+interface InferTraceInput {
+    fn: HIRFunction;
+    sourceLines: string[];
+    startLine: number;
+    endLine: number;
+    verbosity: 'minimal' | 'verbose';
+    regions?: RegionInfoSerializable[];
+}
+declare function inferTraceMarkersForComponent(input: InferTraceInput): LineTrace[];
+
 declare const createFictPlugin: (api: object, options: FictCompilerOptions | null | undefined, dirname: string) => BabelCore.PluginObj<BabelCore.PluginPass>;
 
-export { type CompilerWarning, type FictCompilerOptions, type HookReturnInfoSerializable, type ModuleReactiveMetadata, type ReactiveExportKind, clearModuleMetadata, createFictPlugin, createFictPlugin as default, resolveModuleMetadata, setModuleMetadata };
+export { type AnalyzeDiagnostic, type AnalyzeOptions, type AnalyzeResult, type CompilerWarning, type ComponentAnalysis, type FictCompilerOptions, type HookReturnInfoSerializable, type LineTrace, type ModuleReactiveMetadata, type ReactiveExportKind, type RegionInfoSerializable, type TraceMarker, type TraceMarkerKind, analyzeFictFile, clearModuleMetadata, createFictPlugin, createFictPlugin as default, inferTraceMarkersForComponent, resolveModuleMetadata, setModuleMetadata };