@timo9378/flow2code 0.1.0

package/dist/compiler.d.ts

@@ -0,0 +1,1230 @@
+import { SourceFile, CodeBlockWriter } from 'ts-morph';
+
+/**
+ * Flow2Code Intermediate Representation (IR) Schema
+ *
+ * This is the sole contract between the visual canvas and the AST compiler.
+ * All node types, edges, and parameters are defined here.
+ *
+ * Design principles:
+ * 1. Fully decoupled from UI — IR contains no coordinate or style information
+ * 2. Type-safe — each node type has strictly typed parameters
+ * 3. Serializable — entire IR can be directly JSON.stringify/parse
+ */
+/** Current supported IR version number */
+declare const CURRENT_IR_VERSION = "1.0.0";
+/** Node unique identifier */
+type NodeId = string;
+/** Port identifier */
+type PortId = string;
+/** Supported data types */
+type FlowDataType = "string" | "number" | "boolean" | "object" | "array" | "any" | "void" | "Response";
+/** Input port */
+interface InputPort {
+    id: PortId;
+    label: string;
+    dataType: FlowDataType;
+    required: boolean;
+    /** Default value (JSON serialized) */
+    defaultValue?: string;
+}
+/** Output port */
+interface OutputPort {
+    id: PortId;
+    label: string;
+    dataType: FlowDataType;
+}
+/** Data flow connection between nodes */
+interface FlowEdge {
+    id: string;
+    /** Source node ID */
+    sourceNodeId: NodeId;
+    /** Source port ID */
+    sourcePortId: PortId;
+    /** Target node ID */
+    targetNodeId: NodeId;
+    /** Target port ID */
+    targetPortId: PortId;
+}
+declare enum NodeCategory {
+    /** Trigger: workflow entry point */
+    TRIGGER = "trigger",
+    /** Action: side-effect producing operation */
+    ACTION = "action",
+    /** Logic: branching, loops, exception handling */
+    LOGIC = "logic",
+    /** Variable: define or transform data */
+    VARIABLE = "variable",
+    /** Output: return result */
+    OUTPUT = "output"
+}
+declare enum TriggerType {
+    HTTP_WEBHOOK = "http_webhook",
+    CRON_JOB = "cron_job",
+    MANUAL = "manual"
+}
+declare enum ActionType {
+    FETCH_API = "fetch_api",
+    SQL_QUERY = "sql_query",
+    REDIS_CACHE = "redis_cache",
+    CUSTOM_CODE = "custom_code",
+    CALL_SUBFLOW = "call_subflow"
+}
+declare enum LogicType {
+    IF_ELSE = "if_else",
+    FOR_LOOP = "for_loop",
+    TRY_CATCH = "try_catch",
+    PROMISE_ALL = "promise_all"
+}
+declare enum VariableType {
+    DECLARE = "declare",
+    TRANSFORM = "transform"
+}
+declare enum OutputType {
+    RETURN_RESPONSE = "return_response"
+}
+/** HTTP Webhook trigger parameters */
+interface HttpWebhookParams {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Route path, e.g. "/api/users" */
+    routePath: string;
+    /** Whether to parse JSON body */
+    parseBody: boolean;
+    /** Query parameter definitions */
+    queryParams?: Array<{
+        name: string;
+        type: FlowDataType;
+        required: boolean;
+    }>;
+}
+/** Cron Job trigger parameters */
+interface CronJobParams {
+    /** Cron expression */
+    schedule: string;
+    /** Function name */
+    functionName: string;
+}
+/** Manual trigger parameters */
+interface ManualTriggerParams {
+    /** Exported function name */
+    functionName: string;
+    /** Function parameter definitions */
+    args: Array<{
+        name: string;
+        type: FlowDataType;
+    }>;
+}
+/** Fetch API action parameters */
+interface FetchApiParams {
+    /** Request URL (supports env var references like ${ENV_VAR}) */
+    url: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body (JSON string or reference expression) */
+    body?: string;
+    /** Whether to auto-parse JSON response */
+    parseJson: boolean;
+}
+/** SQL Query action parameters */
+interface SqlQueryParams {
+    /** ORM type */
+    orm: "drizzle" | "prisma" | "raw";
+    /** SQL or ORM query statement */
+    query: string;
+    /** Query parameter bindings */
+    params?: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/** Redis Cache action parameters */
+interface RedisCacheParams {
+    operation: "get" | "set" | "del";
+    key: string;
+    /** Value for set operation */
+    value?: string;
+    /** TTL (seconds) */
+    ttl?: number;
+}
+/** Custom code parameters */
+interface CustomCodeParams {
+    /** TypeScript code snippet */
+    code: string;
+    /** Name of the return variable */
+    returnVariable?: string;
+    /** Explicitly specify the return type (for type inference, e.g. "User[]" or "{ count: number }") */
+    returnType?: string;
+}
+/** Subflow call parameters */
+interface CallSubflowParams {
+    /** Import path of the subflow (combined with compiler-generated file) */
+    flowPath: string;
+    /** Exported function name of the subflow */
+    functionName: string;
+    /** Input parameter mapping: param name → expression (supports template syntax) */
+    inputMapping: Record<string, string>;
+    /** Explicit subflow return type (optional, defaults to TypeScript inference) */
+    returnType?: string;
+}
+/** If/Else logic control parameters */
+interface IfElseParams {
+    /** Condition expression (TypeScript expression string) */
+    condition: string;
+}
+/** For Loop logic control parameters */
+interface ForLoopParams {
+    /** Iteration target (variable reference expression) */
+    iterableExpression: string;
+    /** Iterator variable name */
+    itemVariable: string;
+    /** Index variable name (optional) */
+    indexVariable?: string;
+}
+/** Try/Catch logic control parameters */
+interface TryCatchParams {
+    /** Error variable name */
+    errorVariable: string;
+}
+/** Promise.all concurrency control parameters */
+interface PromiseAllParams {
+    /** No additional params. Concurrent tasks are determined by connected child nodes */
+    [key: string]: never;
+}
+/** Variable declaration parameters */
+interface DeclareVariableParams {
+    /** Variable name */
+    name: string;
+    /** Variable type */
+    dataType: FlowDataType;
+    /** Initial value expression */
+    initialValue?: string;
+    /** Whether const */
+    isConst: boolean;
+}
+/** Data transform parameters */
+interface TransformParams {
+    /** Transform expression (TypeScript expression) */
+    expression: string;
+}
+/** Return Response parameters */
+interface ReturnResponseParams {
+    /** HTTP status code */
+    statusCode: number;
+    /** Response body expression */
+    bodyExpression: string;
+    /** Custom response headers */
+    headers?: Record<string, string>;
+}
+interface NodeParamsMap {
+    [TriggerType.HTTP_WEBHOOK]: HttpWebhookParams;
+    [TriggerType.CRON_JOB]: CronJobParams;
+    [TriggerType.MANUAL]: ManualTriggerParams;
+    [ActionType.FETCH_API]: FetchApiParams;
+    [ActionType.SQL_QUERY]: SqlQueryParams;
+    [ActionType.REDIS_CACHE]: RedisCacheParams;
+    [ActionType.CUSTOM_CODE]: CustomCodeParams;
+    [ActionType.CALL_SUBFLOW]: CallSubflowParams;
+    [LogicType.IF_ELSE]: IfElseParams;
+    [LogicType.FOR_LOOP]: ForLoopParams;
+    [LogicType.TRY_CATCH]: TryCatchParams;
+    [LogicType.PROMISE_ALL]: PromiseAllParams;
+    [VariableType.DECLARE]: DeclareVariableParams;
+    [VariableType.TRANSFORM]: TransformParams;
+    [OutputType.RETURN_RESPONSE]: ReturnResponseParams;
+}
+type NodeType = keyof NodeParamsMap;
+/** Generic node, params type inferred from nodeType */
+interface FlowNode<T extends NodeType = NodeType> {
+    /** Node unique identifier */
+    id: NodeId;
+    /** Node type */
+    nodeType: T;
+    /** Category */
+    category: NodeCategory;
+    /** User-defined node label */
+    label: string;
+    /** Node parameters */
+    params: NodeParamsMap[T];
+    /** Input ports */
+    inputs: InputPort[];
+    /** Output ports */
+    outputs: OutputPort[];
+}
+/** Flow2Code IR Document — the sole contract between canvas and compiler */
+interface FlowIR {
+    /** IR version */
+    version: string;
+    /** Workflow summary */
+    meta: {
+        name: string;
+        description?: string;
+        createdAt: string;
+        updatedAt: string;
+    };
+    /** All nodes */
+    nodes: FlowNode[];
+    /** All edges */
+    edges: FlowEdge[];
+}
+
+/**
+ * Flow2Code Symbol Table
+ *
+ * Maps node IDs to human-readable variable names (derived from node labels).
+ * Enables "ejectable" code generation — generated TypeScript looks like hand-written code.
+ *
+ * Naming strategy:
+ *   "GET /api/hello"          → getApiHello
+ *   "Fetch Available Models"  → fetchAvailableModels
+ *   "Return Hello"            → returnHello
+ *   "Check Valid"             → checkValid
+ *   "Call External API"       → callExternalApi
+ *
+ * Conflict resolution: duplicate variable names auto-suffixed with _2, _3 ...
+ * Reserved word protection: JS/TS reserved words + common identifiers in generated code auto-suffixed with Result
+ */
+
+interface SymbolTable {
+    /** Get the human-readable variable name for a node */
+    getVarName(nodeId: NodeId): string;
+    /** Check if a node has a named variable */
+    hasVar(nodeId: NodeId): boolean;
+    /** Get all mappings */
+    getAllMappings(): ReadonlyMap<NodeId, string>;
+}
+
+/**
+ * Platform Adapter Interface
+ *
+ * Abstracts HTTP framework implementations so the compiler is no longer coupled to Next.js.
+ * Developers can choose different target platforms to generate corresponding code.
+ *
+ * Supported platforms:
+ *   - nextjs       (default) Next.js App Router
+ *   - express      Express.js
+ *   - cloudflare   Cloudflare Workers
+ *   - generic      Generic TypeScript (pure functions, framework-agnostic)
+ */
+
+interface PlatformAdapter {
+    /** Platform name */
+    readonly name: string;
+    /**
+     * Generate import statements.
+     * e.g. Next.js: `import { NextResponse } from "next/server"`
+     */
+    generateImports(sourceFile: SourceFile, trigger: FlowNode, context: PlatformContext): void;
+    /**
+     * Generate the exported main function (including signature, parameters, outer try/catch).
+     * The bodyGenerator callback is responsible for filling in the function body logic.
+     */
+    generateFunction(sourceFile: SourceFile, trigger: FlowNode, context: PlatformContext, bodyGenerator: (writer: CodeBlockWriter) => void): void;
+    /**
+     * Generate code that returns a Response.
+     */
+    generateResponse(writer: CodeBlockWriter, bodyExpr: string, statusCode: number, headers?: Record<string, string>): void;
+    /**
+     * Generate the error response code for the global error handler.
+     */
+    generateErrorResponse(writer: CodeBlockWriter): void;
+    /**
+     * Generate initialization code based on trigger type (parse request body/query, etc.).
+     * Each platform uses its own HTTP API (Next.js / Express / Cloudflare Workers).
+     */
+    generateTriggerInit(writer: CodeBlockWriter, trigger: FlowNode, context: TriggerInitContext): void;
+    /**
+     * Get the output file path.
+     */
+    getOutputFilePath(trigger: FlowNode): string;
+    /**
+     * Implicit npm dependencies for this platform.
+     */
+    getImplicitDependencies(): string[];
+}
+interface PlatformContext {
+    ir: FlowIR;
+    nodeMap: Map<NodeId, FlowNode>;
+    envVars: Set<string>;
+    imports: Map<string, Set<string>>;
+}
+interface TriggerInitContext {
+    symbolTable: SymbolTable;
+}
+/**
+ * Built-in platform names (extensible: third parties can register any string via registerPlatform).
+ */
+type BuiltinPlatformName = "nextjs" | "express" | "cloudflare";
+type PlatformName = BuiltinPlatformName | (string & {});
+/**
+ * Register a custom platform adapter.
+ *
+ * Allows users to extend the compiler's supported target platforms (e.g. Fastify, Koa, etc.).
+ * The factory function is lazily invoked on each compile to avoid global state pollution.
+ *
+ * @param name - Platform name, can use a built-in name or a custom string
+ * @param factory - Platform adapter factory function
+ *
+ * @example
+ * ```ts
+ * import { registerPlatform } from "flow2code";
+ *
+ * registerPlatform("fastify", () => ({
+ *   imports: () => ['import Fastify from "fastify";'],
+ *   routeWrapper: (method, path, body) => `app.${method}("${path}", async (req, reply) => {\n${body}\n});`,
+ *   response: (statusExpr, bodyExpr) => `reply.status(${statusExpr}).send(${bodyExpr});`,
+ *   appSetup: () => 'const app = Fastify();',
+ *   listen: (port) => `app.listen({ port: ${port} });`,
+ * }));
+ * ```
+ */
+declare function registerPlatform(name: PlatformName, factory: () => PlatformAdapter): void;
+declare function getPlatform(name: PlatformName): PlatformAdapter;
+declare function getAvailablePlatforms(): string[];
+
+/**
+ * Node Plugin Interface
+ *
+ * Allows developers to register custom node code generators without modifying compiler source code.
+ *
+ * Usage example:
+ * ```ts
+ * import { registerPlugin } from "flow2code/compiler";
+ *
+ * registerPlugin({
+ *   nodeType: "aws_ses_email",
+ *   generate(node, writer, context) {
+ *     writer.writeLine(`await ses.sendEmail({ ... });`);
+ *     writer.writeLine(`flowState['${node.id}'] = { sent: true };`);
+ *   },
+ *   getRequiredPackages: () => ["@aws-sdk/client-ses"],
+ *   getOutputType: () => "{ sent: boolean }",
+ * });
+ * ```
+ */
+
+interface PluginContext {
+    ir: FlowIR;
+    nodeMap: Map<NodeId, FlowNode>;
+    envVars: Set<string>;
+    imports: Map<string, Set<string>>;
+    requiredPackages: Set<string>;
+    /** Resolve template expressions (automatically uses expression parser) */
+    resolveExpression: (expr: string, currentNodeId?: NodeId) => string;
+    /** Resolve environment variable references */
+    resolveEnvVars: (url: string) => string;
+    /** Generate child node code (used for branching nodes like if/else, try/catch) */
+    generateChildNode: (writer: CodeBlockWriter, node: FlowNode) => void;
+    /** Get the human-readable variable name for a node (provided by Symbol Table) */
+    getVarName: (nodeId: NodeId) => string;
+    /**
+     * Push a local scope layer.
+     * Within this scope, all expression references to nodeId will resolve to scopeVar.
+     */
+    pushScope: (nodeId: NodeId, scopeVar: string) => void;
+    /**
+     * Pop the innermost local scope.
+     */
+    popScope: () => void;
+}
+interface NodePlugin {
+    /** Node type identifier (corresponds to FlowNode.nodeType) */
+    readonly nodeType: string;
+    /**
+     * Generate TypeScript code for this node.
+     */
+    generate(node: FlowNode, writer: CodeBlockWriter, context: PluginContext): void;
+    /**
+     * Declare npm packages required by this node.
+     * @returns Array of package names, e.g. ["@aws-sdk/client-ses"]
+     */
+    getRequiredPackages?(node: FlowNode): string[];
+    /**
+     * Infer the TypeScript type of this node's output value.
+     * Used to generate a typed flowState interface.
+     * @returns TypeScript type string, e.g. "{ sent: boolean }"
+     */
+    getOutputType?(node: FlowNode): string;
+}
+/**
+ * Plugin Registry instance.
+ * Each `compile()` call can create an independent registry to avoid global state pollution.
+ */
+interface PluginRegistry {
+    register(plugin: NodePlugin): void;
+    registerAll(plugins: NodePlugin[]): void;
+    get(nodeType: string): NodePlugin | undefined;
+    has(nodeType: string): boolean;
+    getAll(): Map<string, NodePlugin>;
+    clear(): void;
+}
+/**
+ * Create a new Plugin Registry instance.
+ */
+declare function createPluginRegistry(): PluginRegistry;
+/**
+ * Register a node plugin (global).
+ * If a plugin with the same name already exists, it will be overwritten (allows developers to replace built-in plugins).
+ */
+declare function registerPlugin(plugin: NodePlugin): void;
+/**
+ * Batch-register multiple plugins (global).
+ */
+declare function registerPlugins(plugins: NodePlugin[]): void;
+/**
+ * Get the plugin for a specific node type (global).
+ */
+declare function getPlugin(nodeType: string): NodePlugin | undefined;
+/**
+ * Get all registered plugins (global).
+ */
+declare function getAllPlugins(): Map<string, NodePlugin>;
+/**
+ * Clear all registered plugins (global, for testing).
+ */
+declare function clearPlugins(): void;
+/**
+ * Check if a specific node type is registered (global).
+ */
+declare function hasPlugin(nodeType: string): boolean;
+
+/**
+ * Built-in Node Plugins
+ *
+ * All built-in node code generators extracted from the compiler core.
+ * Each generator follows the NodePlugin interface and can be overridden by external plugins.
+ */
+
+declare const builtinPlugins: NodePlugin[];
+
+/**
+ * Flow2Code AST Compiler Core (v2)
+ *
+ * Architecture:
+ *   1. Platform Adapter — Decoupled from Next.js, supports Express / Cloudflare Workers
+ *   2. Plugin System — Node generation logic is externally registerable
+ *   3. Expression Parser — Recursive Descent Parser replaces regex
+ *   4. Type Inference — Generates typed FlowState interface instead of Record<string, any>
+ *   5. Scoped State — Loops/try-catch use local scope to prevent variable shadowing
+ *
+ * Public API (backward-compatible):
+ *   - compile(ir)                → CompileResult (default: nextjs platform)
+ *   - compile(ir, { platform })  → CompileResult (specified platform)
+ *   - traceLineToNode(sourceMap, line) → Reverse lookup node from line number
+ */
+
+interface CompileResult {
+    success: boolean;
+    code?: string;
+    errors?: string[];
+    /** Generated file path (relative) */
+    filePath?: string;
+    /** Dependency report */
+    dependencies?: DependencyReport;
+    /** Source Map (nodeId ↔ line number mapping) */
+    sourceMap?: SourceMap;
+}
+/** Dependency report */
+interface DependencyReport {
+    /** All required packages */
+    all: string[];
+    /** Missing packages (compared with package.json) */
+    missing: string[];
+    /** Suggested install command */
+    installCommand?: string;
+}
+/** Source Map: line number ↔ node ID mapping */
+interface SourceMap {
+    version: 1;
+    generatedFile: string;
+    /** nodeId → { startLine, endLine } */
+    mappings: Record<string, {
+        startLine: number;
+        endLine: number;
+    }>;
+}
+interface CompileOptions {
+    /** Target platform (default: "nextjs") */
+    platform?: PlatformName;
+    /** Additional Node Plugins */
+    plugins?: NodePlugin[];
+}
+/**
+ * Compiles FlowIR into TypeScript source code.
+ *
+ * Pipeline stages:
+ * 1. Validate IR structure
+ * 2. Topological sort + concurrency detection
+ * 3. Platform adaptation (Next.js / Express / Cloudflare etc.)
+ * 4. Plugin-based node code generation
+ * 5. IDE-friendly Source Map output
+ *
+ * @param ir - FlowIR input document
+ * @param options - Compile options (platform, plugins, output path etc.)
+ * @returns Compile result containing code, filePath, sourceMap, dependencies
+ *
+ * @example
+ * ```ts
+ * import { compile } from "flow2code";
+ *
+ * const result = compile(ir, { platform: "hono" });
+ * if (result.success) {
+ *   console.log(result.code);
+ * }
+ * ```
+ */
+declare function compile(ir: FlowIR, options?: CompileOptions): CompileResult;
+/**
+ * Given a line number, reverse-lookup the corresponding nodeId.
+ */
+declare function traceLineToNode(sourceMap: SourceMap, line: number): {
+    nodeId: string;
+    startLine: number;
+    endLine: number;
+} | null;
+
+/**
+ * Flow IR Validator
+ *
+ * Validates structural correctness of an IR document before compilation:
+ * 1. Must have exactly one Trigger node
+ * 2. All Edge source/target must reference existing nodes
+ * 3. No orphan nodes (except Trigger)
+ * 4. Graph must be a DAG (no cycles)
+ */
+
+interface ValidationError {
+    code: string;
+    message: string;
+    nodeId?: NodeId;
+    edgeId?: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    /** If the IR was auto-migrated, records the migration path */
+    migrated?: boolean;
+    migratedIR?: FlowIR;
+    migrationLog?: string[];
+}
+/**
+ * Validates the structural correctness of a FlowIR document.
+ * Auto-migrates older versions before validation if needed.
+ */
+declare function validateFlowIR(ir: FlowIR): ValidationResult;
+
+/**
+ * AI-Generated IR Security Check
+ *
+ * When IR is produced by AI/LLM, custom_code nodes may contain malicious code.
+ * This module intercepts at the "load/import" stage, earlier than the compile-time `DANGEROUS_CODE_PATTERNS`.
+ *
+ * @example
+ * ```ts
+ * import { validateIRSecurity } from "flow2code/compiler";
+ *
+ * const result = validateIRSecurity(aiGeneratedIR);
+ * if (!result.safe) {
+ *   console.warn("⚠️ Dangerous patterns:", result.findings);
+ * }
+ * ```
+ */
+
+interface SecurityFinding {
+    /** Severity level */
+    severity: "critical" | "warning" | "info";
+    /** Node ID */
+    nodeId: NodeId;
+    /** Node label */
+    nodeLabel: string;
+    /** Description of the detected pattern */
+    pattern: string;
+    /** Matched code snippet (truncated to 80 characters) */
+    match: string;
+}
+interface SecurityCheckResult {
+    /** Whether it is safe (no critical findings) */
+    safe: boolean;
+    /** All detection results */
+    findings: SecurityFinding[];
+    /** Number of nodes scanned */
+    nodesScanned: number;
+}
+/**
+ * Validate the security of all nodes in a FlowIR
+ *
+ * Specifically targets AI/LLM-generated IR, detecting malicious patterns at the load/import stage.
+ * Scan scope: custom_code, transform, if_else, return_response, fetch_api, and all other fields containing code/expressions.
+ *
+ * @param ir - The FlowIR to check
+ * @returns SecurityCheckResult - Contains safety verdict, all detection findings, and scan statistics
+ */
+declare function validateIRSecurity(ir: FlowIR): SecurityCheckResult;
+/**
+ * Format security check results into a human-readable string
+ */
+declare function formatSecurityReport(result: SecurityCheckResult): string;
+
+/**
+ * Topological Sort and Concurrency Detection Algorithm
+ *
+ * Features:
+ * 1. Compute node execution priority (topological sort)
+ * 2. Detect groups of concurrently executable nodes (for generating Promise.all)
+ * 3. Build Execution Plan
+ */
+
+/** Single execution step */
+interface ExecutionStep {
+    /** Step index */
+    index: number;
+    /**
+     * List of node IDs to execute in this step.
+     * If length > 1, they can be executed concurrently with Promise.all.
+     */
+    nodeIds: NodeId[];
+    /** Whether it can execute concurrently */
+    concurrent: boolean;
+}
+/** Complete execution plan */
+interface ExecutionPlan {
+    /** All steps (topologically sorted) */
+    steps: ExecutionStep[];
+    /** Topological sort result (flat) */
+    sortedNodeIds: NodeId[];
+    /** Incoming nodes for each node (dependency sources) */
+    dependencies: Map<NodeId, Set<NodeId>>;
+    /** Outgoing nodes for each node (dependency targets) */
+    dependents: Map<NodeId, Set<NodeId>>;
+}
+/**
+ * Perform topological sort using Kahn's algorithm,
+ * grouping nodes at the same level (indegree reaches zero simultaneously)
+ * to detect concurrently executable nodes.
+ */
+declare function topologicalSort(ir: FlowIR): ExecutionPlan;
+
+/**
+ * Flow2Code Expression Parser
+ *
+ * Replaces fragile Regex parsing with a Recursive Descent Parser for template expressions.
+ *
+ * Supported syntax:
+ *   {{nodeId}}                → flowState['nodeId']
+ *   {{nodeId.path.to.value}}  → flowState['nodeId'].path.to.value
+ *   {{nodeId.arr[0].name}}    → flowState['nodeId'].arr[0].name
+ *   {{$input}}                → auto-resolves upstream non-trigger node
+ *   {{$input.data.items}}     → same, with sub-path
+ *   {{$trigger}}              → trigger node's flowState
+ *   {{$trigger.body.userId}}  → flowState['triggerId'].body.userId
+ *
+ * Differences from Regex version:
+ *   - Correctly handles nested brackets e.g. {{node.arr[items[0]]}}
+ *   - Correctly handles whitespace e.g. {{ $input.data }}
+ *   - Clear error messages, no silent fallthrough
+ *   - Supports escape sequences \\{{ to output literal {{
+ */
+
+/**
+ * Scope Entry: describes the current scope during code generation.
+ * For example, inside a for-loop, the loop node's ID should resolve
+ * to _loopScope instead of flowState.
+ */
+interface ScopeEntry {
+    /** Node ID mapped by this scope */
+    nodeId: NodeId;
+    /** Variable name in generated code (e.g. _loopScope) */
+    scopeVar: string;
+}
+interface ExpressionContext {
+    /** Current IR */
+    ir: FlowIR;
+    /** Node ID → FlowNode mapping */
+    nodeMap: Map<NodeId, FlowNode>;
+    /** Current node ID (used for resolving $input) */
+    currentNodeId?: NodeId;
+    /** Symbol Table: when enabled, expressions use named variables instead of flowState['nodeId'] */
+    symbolTable?: SymbolTable;
+    /**
+     * Scope Stack: outermost to innermost scope entries.
+     * When a reference's base matches a scope's nodeId,
+     * it resolves to scopeVar['nodeId'] instead of flowState['nodeId'].
+     */
+    scopeStack?: ScopeEntry[];
+    /**
+     * Block-scoped node IDs: these nodes are generated inside sub-blocks
+     * (if/else, try/catch, for-loop body), and their Symbol Table aliases
+     * are not visible in the outer scope.
+     * Expression parsing must fallback to flowState['nodeId'].
+     */
+    blockScopedNodeIds?: Set<NodeId>;
+}
+/**
+ * Parses all {{...}} references in an expression string and replaces them
+ * with the corresponding flowState access expressions.
+ *
+ * @param expr - Raw expression (may contain {{...}} template syntax)
+ * @param context - Compiler context
+ * @returns Parsed TypeScript expression
+ */
+declare function parseExpression(expr: string, context: ExpressionContext): string;
+
+/**
+ * Flow2Code Type Inference Engine
+ *
+ * Infers TypeScript types for flowState based on FlowIR node definitions and port types.
+ * Replaces the crude `Record<string, any>` declaration to provide real type safety in generated code.
+ *
+ * Inference strategies:
+ *   1. Trigger nodes: inferred from trigger type and parameters (e.g. HTTP body, query, etc.)
+ *   2. Action nodes: inferred from the plugin's getOutputType()
+ *   3. Manual specification: uses the port's dataType as a fallback
+ *   4. Auto-narrowing: $input references are narrowed based on upstream node types
+ */
+
+interface FlowStateTypeInfo {
+    /** Complete TypeScript interface source code */
+    interfaceCode: string;
+    /** TypeScript type corresponding to each node ID */
+    nodeTypes: Map<string, string>;
+}
+/**
+ * Infer the output types of all nodes in a FlowIR and generate the corresponding TypeScript interface.
+ *
+ * @param ir - Flow IR
+ * @returns FlowStateTypeInfo containing the generated interface and per-node type mappings
+ */
+declare function inferFlowStateTypes(ir: FlowIR, registry?: PluginRegistry): FlowStateTypeInfo;
+
+/**
+ * Flow2Code Universal Decompiler — TypeScript → FlowIR
+ *
+ * Reverse-parses **any** TypeScript source code into FlowIR intermediate representation.
+ * Designed for AI Code Audit: accepts AI-generated TypeScript and visualizes its logic flow.
+ *
+ * Strategy:
+ *   1. AST Analysis (primary): ts-morph parses TS AST, pattern-matches known constructs
+ *   2. Data Flow Tracking: variable def-use chains build real edges (not linear chaining)
+ *   3. Source Map Hints (optional): if `// --- label [nodeType] [nodeId] ---` markers exist,
+ *      they enhance node labeling but are NOT required
+ *
+ * Supported patterns:
+ *   - Export functions / arrow functions / class methods → Triggers
+ *   - `await fetch(...)` → Fetch API nodes
+ *   - `if/else` → If/Else logic nodes
+ *   - `for...of` / `for...in` / `for` → Loop nodes
+ *   - `try/catch` → TryCatch nodes
+ *   - Variable declarations → Variable nodes
+ *   - Generic `await expr` → Custom code action nodes
+ *   - Return / Response statements → Output nodes
+ *
+ * Edge building:
+ *   - Data flow edges: tracks which variables are produced and consumed by each node
+ *   - Control flow edges: if/else branches, loop bodies, try/catch blocks
+ *   - Sequential edges: statements in the same scope with no explicit data dependency
+ */
+
+interface DecompileResult {
+    success: boolean;
+    ir?: FlowIR;
+    errors?: string[];
+    /** Confidence score 0-1 indicating decompilation accuracy */
+    confidence: number;
+    /** Audit hints: detected issues or notable patterns */
+    audit?: AuditHint[];
+}
+/** Audit hint: a detected issue or notable pattern in the code */
+interface AuditHint {
+    nodeId: string;
+    severity: "info" | "warning" | "error";
+    message: string;
+    /** Source line number (1-indexed) */
+    line?: number;
+}
+interface DecompileOptions {
+    /** File name or full file path (used for route inference) */
+    fileName?: string;
+    /** Target function name to decompile (omit to auto-detect) */
+    functionName?: string;
+    /** Enable audit hints (default: true) */
+    audit?: boolean;
+}
+/**
+ * Decompiles any TypeScript source code into FlowIR.
+ *
+ * @param code - TypeScript source code (arbitrary, not limited to flow2code output)
+ * @param options - Optional settings
+ * @returns DecompileResult with IR, confidence, and optional audit hints
+ */
+declare function decompile(code: string, options?: DecompileOptions): DecompileResult;
+
+/**
+ * Flow2Code Runtime Error Tracer
+ *
+ * Solves the "debugging experience gap" problem:
+ * When a compiled API Route throws a runtime error,
+ * it automatically intercepts the error stack, reverse-lookups the Source Map,
+ * and prints a clickable deep link to jump directly to the error node on the Flow2Code canvas.
+ *
+ * Usage:
+ * ```ts
+ * // 1. Next.js middleware / wrap handler
+ * import { withFlowTrace } from "flow2code/compiler";
+ *
+ * export const GET = withFlowTrace(handler, { flowFile: "my-flow.flow.json" });
+ *
+ * // 2. Global install (intercept uncaught errors)
+ * import { installFlowTracer } from "flow2code/compiler";
+ *
+ * installFlowTracer({ port: 3001 });
+ * ```
+ *
+ * Output example:
+ * ```
+ * ❌ Runtime Error in generated.ts:45
+ *    → Flow2Code Node: [fetch_api_1] "Fetch User Data"
+ *    → 🔗 http://localhost:3001?highlight=fetch_api_1
+ * ```
+ */
+
+interface TraceResult {
+    /** Matched node ID */
+    nodeId: string;
+    /** Node label */
+    nodeLabel: string;
+    /** Node type */
+    nodeType: string;
+    /** Source code line number range */
+    startLine: number;
+    endLine: number;
+    /** Clickable deep link (opens canvas and highlights node) */
+    deepLink: string;
+}
+interface TracerOptions {
+    /** Flow2Code editor URL (default: http://localhost:3001) */
+    editorUrl?: string;
+    /** Source Map object (if already in memory) */
+    sourceMap?: SourceMap;
+    /** FlowIR object (used to retrieve node labels) */
+    ir?: FlowIR;
+    /** Whether to print a readable error message to console (default: true) */
+    log?: boolean;
+}
+/**
+ * Extract all matching line numbers from an Error object's stack trace
+ * and reverse-lookup the corresponding Flow nodes via Source Map.
+ *
+ * @param error - Original Error object
+ * @param sourceMap - Source Map generated at compile time
+ * @param ir - FlowIR (used to retrieve label / nodeType)
+ * @param editorUrl - Editor URL
+ * @returns All matching TraceResults (in stack order)
+ */
+declare function traceError(error: Error, sourceMap: SourceMap, ir?: FlowIR, editorUrl?: string): TraceResult[];
+/**
+ * Format TraceResults into a readable console message.
+ */
+declare function formatTraceResults(error: Error, traces: TraceResult[], generatedFile: string): string;
+type AsyncHandler = (...args: unknown[]) => Promise<unknown>;
+/**
+ * Wrap an API handler to automatically intercept runtime errors and print Flow node traces.
+ *
+ * @example
+ * ```ts
+ * import { withFlowTrace } from "flow2code/compiler";
+ * import sourceMap from "./my-flow.flow.map.json";
+ *
+ * async function handler(req: Request) {
+ *   // ... generated code
+ * }
+ *
+ * export const GET = withFlowTrace(handler, { sourceMap });
+ * ```
+ */
+declare function withFlowTrace<T extends AsyncHandler>(handler: T, options: TracerOptions): T;
+/**
+ * Install the Flow2Code error tracer at the process level.
+ * Listens for `uncaughtException` and `unhandledRejection`,
+ * automatically printing deep links for errors matching the Source Map.
+ *
+ * @param options - TracerOptions (must include sourceMap)
+ * @returns Cleanup function (uninstall tracer)
+ *
+ * @example
+ * ```ts
+ * import { installFlowTracer } from "flow2code/compiler";
+ * import sourceMap from "./my-flow.flow.map.json";
+ *
+ * const uninstall = installFlowTracer({ sourceMap, editorUrl: "http://localhost:3001" });
+ *
+ * // Later, stop tracing
+ * uninstall();
+ * ```
+ */
+declare function installFlowTracer(options: TracerOptions & {
+    sourceMap: SourceMap;
+}): () => void;
+
+/**
+ * Flow2Code Dynamic Node Registry
+ *
+ * Solves the "core and nodes over-coupling" problem:
+ * Node definitions are no longer hardcoded in switch statements,
+ * but independently described via `NodeDefinition` and dynamically registered.
+ *
+ * Community extensions simply need to:
+ * ```ts
+ * import { nodeRegistry } from "flow2code/compiler";
+ *
+ * nodeRegistry.register({
+ *   nodeType: "action:s3_upload",
+ *   category: NodeCategory.ACTION,
+ *   label: "AWS S3 Upload",
+ *   icon: "☁️",
+ *   description: "Upload file to AWS S3 Bucket",
+ *   defaultPorts: {
+ *     inputs: [{ id: "file", label: "File", dataType: "object", required: true }],
+ *     outputs: [{ id: "url", label: "URL", dataType: "string" }],
+ *   },
+ *   defaultParams: { bucket: "", region: "us-east-1" },
+ * });
+ * ```
+ */
+
+interface NodeDefinition {
+    /** Node type identifier (corresponds to IR's nodeType) */
+    nodeType: string;
+    /** Node category */
+    category: NodeCategory;
+    /** Display label */
+    label: string;
+    /** Emoji / icon (for NodeLibrary) */
+    icon: string;
+    /** Node description (tooltip) */
+    description?: string;
+    /** Default ports */
+    defaultPorts: {
+        inputs: InputPort[];
+        outputs: OutputPort[];
+    };
+    /** Default parameters */
+    defaultParams: Record<string, unknown>;
+    /** Group name displayed in NodeLibrary; defaults to category group if omitted */
+    group?: string;
+    /** Sort weight (lower = higher priority), default 100 */
+    order?: number;
+}
+declare class NodeRegistry {
+    private definitions;
+    /** Register a single node definition */
+    register(def: NodeDefinition): void;
+    /** Batch register */
+    registerAll(defs: NodeDefinition[]): void;
+    /** Get a single node definition */
+    get(nodeType: string): NodeDefinition | undefined;
+    /** Get all node definitions */
+    getAll(): NodeDefinition[];
+    /** Get node definitions by category */
+    getByCategory(category: NodeCategory): NodeDefinition[];
+    /** Get all registered nodeType strings */
+    getRegisteredTypes(): string[];
+    /** Check if registered */
+    has(nodeType: string): boolean;
+    /** Remove (for testing or hot reload) */
+    unregister(nodeType: string): boolean;
+    /** Clear all (for testing) */
+    clear(): void;
+    /** Get node default ports (backward-compatible with getDefaultPorts) */
+    getDefaultPorts(nodeType: string): {
+        inputs: InputPort[];
+        outputs: OutputPort[];
+    };
+    /** Get node default parameters (backward-compatible with getDefaultParams) */
+    getDefaultParams(nodeType: string): Record<string, unknown>;
+    /** Get node default label (backward-compatible with getDefaultLabel) */
+    getDefaultLabel(nodeType: string): string;
+    /** Infer category from node type (backward-compatible with getCategoryForType) */
+    getCategoryForType(nodeType: string): NodeCategory;
+    /**
+     * Group nodes by group (for NodeLibrary UI)
+     * Return format is compatible with the original NodeLibrary.tsx nodeTemplates
+     */
+    getGroupedDefinitions(): Record<string, {
+        icon: string;
+        color: string;
+        templates: Array<{
+            nodeType: string;
+            label: string;
+            icon: string;
+            category: NodeCategory;
+        }>;
+    }>;
+}
+declare const nodeRegistry: NodeRegistry;
+
+/**
+ * Flow2Code Split Storage
+ *
+ * Solves keypoint.md #2 "JSON Diff Hell" problem.
+ *
+ * Splits a single .flow.json into a directory structure:
+ *
+ *   my-flow/
+ *   ├── meta.yaml        ← Workflow metadata
+ *   ├── edges.yaml        ← All edges
+ *   └── nodes/
+ *       ├── trigger_1.yaml
+ *       ├── fetch_1.yaml
+ *       └── response_1.yaml
+ *
+ * Each node is an independent file, greatly reducing Git merge conflict probability.
+ */
+
+/** Split file structure */
+interface SplitFiles {
+    /** meta.yaml content */
+    meta: string;
+    /** edges.yaml content */
+    edges: string;
+    /** Node files: filename → yaml content */
+    nodes: Map<string, string>;
+}
+/**
+ * Split FlowIR into multiple YAML files
+ */
+declare function splitIR(ir: FlowIR): SplitFiles;
+/**
+ * Merge YAML files into FlowIR
+ */
+declare function mergeIR(files: SplitFiles): FlowIR;
+
+/**
+ * Flow2Code FlowProject — Unified Flow load / save interface
+ *
+ * Solves the "Git version control workaround" problem:
+ * Developers don't need to manually run split / merge;
+ * all load / save operations auto-detect format and default to split YAML directory storage.
+ *
+ * Supports two formats:
+ * 1. **Split YAML (default)** — `my-flow/` directory (`meta.yaml` + `edges.yaml` + `nodes/*.yaml`)
+ * 2. **Single JSON (backward compatible)** — `my-flow.flow.json`
+ *
+ * @example
+ * ```ts
+ * import { loadFlowProject, saveFlowProject } from "flow2code/compiler";
+ *
+ * // Load (auto-detect format)
+ * const ir = loadFlowProject("./flows/my-flow");
+ *
+ * // Save (defaults to split YAML directory)
+ * saveFlowProject(ir, "./flows/my-flow");
+ *
+ * // Force save as .flow.json
+ * saveFlowProject(ir, "./flows/my-flow.flow.json", { format: "json" });
+ * ```
+ */
+
+type FlowProjectFormat = "split" | "json";
+interface SaveOptions {
+    /** Storage format, default "split" (YAML directory) */
+    format?: FlowProjectFormat;
+    /** Whether to clean orphaned node files in directory (default true) */
+    cleanOrphanNodes?: boolean;
+}
+interface FlowProjectInfo {
+    /** Actual loaded path */
+    path: string;
+    /** Detected format */
+    format: FlowProjectFormat;
+    /** Loaded IR */
+    ir: FlowIR;
+}
+/**
+ * Detect flow project format from path
+ *
+ * Detection order:
+ * 1. Path ends with `.flow.json` → json
+ * 2. Path is a directory containing `meta.yaml` → split
+ * 3. Path + `.flow.json` file exists → json
+ * 4. Path is a directory (assumed split) → split
+ */
+declare function detectFormat(inputPath: string): {
+    resolvedPath: string;
+    format: FlowProjectFormat;
+};
+/**
+ * Load Flow project (auto-detect format)
+ */
+declare function loadFlowProject(inputPath: string): FlowProjectInfo;
+/**
+ * Save Flow project
+ *
+ * @param format - Default "split". Pass "json" to save as single .flow.json.
+ */
+declare function saveFlowProject(ir: FlowIR, outputPath: string, options?: SaveOptions): string[];
+/**
+ * Migrate .flow.json to split YAML directory
+ * Returns list of written files. The original .flow.json is not deleted.
+ */
+declare function migrateToSplit(jsonPath: string): string[];
+
+/**
+ * Flow2Code Semantic Diff Engine
+ *
+ * Compares two FlowIR versions, producing human-readable semantic diff descriptions.
+ * Replaces the noise of raw JSON diffs, letting PR reviews see "what logic was added" instead of "which bytes changed".
+ *
+ * Comparison levels:
+ *   1. Meta: name, description changes
+ *   2. Nodes: added / removed / modified nodes
+ *   3. Edges: added / removed edges
+ *   4. Params: node parameter detail changes
+ */
+
+type ChangeType = "added" | "removed" | "modified";
+type ChangeCategory = "meta" | "node" | "edge";
+interface SemanticChange {
+    /** Change type */
+    type: ChangeType;
+    /** Change category */
+    category: ChangeCategory;
+    /** Affected ID (nodeId or edgeId) */
+    id: string;
+    /** Human-readable description */
+    description: string;
+    /** Detailed field differences for modifications */
+    details?: FieldDiff[];
+}
+interface FieldDiff {
+    /** Field path, e.g. "params.url" or "label" */
+    field: string;
+    /** Old value */
+    before: unknown;
+    /** New value */
+    after: unknown;
+}
+interface DiffSummary {
+    /** All changes */
+    changes: SemanticChange[];
+    /** Quick statistics */
+    stats: {
+        added: number;
+        removed: number;
+        modified: number;
+        total: number;
+    };
+}
+/**
+ * Compute semantic differences between two FlowIRs
+ *
+ * @param before - IR before changes
+ * @param after - IR after changes
+ * @returns Semantic diff summary
+ */
+declare function semanticDiff(before: FlowIR, after: FlowIR): DiffSummary;
+/**
+ * Format diff summary into a human-readable text report
+ */
+declare function formatDiff(summary: DiffSummary): string;
+
+export { ActionType, type AuditHint, type BuiltinPlatformName, CURRENT_IR_VERSION, type CallSubflowParams, type CompileOptions, type CompileResult, type CronJobParams, type CustomCodeParams, type DeclareVariableParams, type DecompileOptions, type DecompileResult, type DependencyReport, type ExecutionPlan, type ExecutionStep, type FetchApiParams, type FlowDataType, type FlowEdge, type FlowIR, type FlowNode, type FlowProjectFormat, type FlowProjectInfo, type ForLoopParams, type HttpWebhookParams, type IfElseParams, type InputPort, LogicType, type ManualTriggerParams, NodeCategory, type NodeDefinition, type NodeId, type NodePlugin, NodeRegistry, type NodeType, type OutputPort, OutputType, type PlatformAdapter, type PlatformContext, type PlatformName, type PluginContext, type PluginRegistry, type PortId, type RedisCacheParams, type ReturnResponseParams, type SaveOptions, type SecurityCheckResult, type SecurityFinding, type SourceMap, type SplitFiles, type SqlQueryParams, type TraceResult, type TracerOptions, type TransformParams, type TriggerInitContext, TriggerType, type TryCatchParams, VariableType, builtinPlugins, clearPlugins, compile, createPluginRegistry, decompile, detectFormat, formatDiff, formatSecurityReport, formatTraceResults, getAllPlugins, getAvailablePlatforms, getPlatform, getPlugin, hasPlugin, inferFlowStateTypes, installFlowTracer, loadFlowProject, mergeIR, migrateToSplit, nodeRegistry, parseExpression, registerPlatform, registerPlugin, registerPlugins, saveFlowProject, semanticDiff, splitIR, topologicalSort, traceError, traceLineToNode, validateFlowIR as validate, validateFlowIR, validateIRSecurity, withFlowTrace };