@synergenius/flow-weaver 0.2.0

package/dist/api/compile.js

@@ -0,0 +1,149 @@
+import * as fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+const require = createRequire(import.meta.url);
+const { version: COMPILER_VERSION } = require('../../package.json');
+import { generateCode } from './generate.js';
+import { generateInPlace } from './generate-in-place.js';
+import { parseWorkflow } from './parse.js';
+/**
+ * Compile a workflow file from TypeScript annotations to executable code.
+ *
+ * By default, compiles in-place (updates the source file with generated code).
+ * Set inPlace=false to generate to a separate file.
+ *
+ * @param filePath - Path to the workflow file
+ * @param options - Compilation options
+ * @returns CompileResult with code, AST, and metadata
+ *
+ * @example
+ * ```typescript
+ * // Compile in-place (default)
+ * const result = await compileWorkflow('./workflow.ts');
+ *
+ * // Generate to separate file for production
+ * const result = await compileWorkflow('./workflow.ts', {
+ *   inPlace: false,
+ *   outputFile: './dist/workflow.ts',
+ *   generate: { production: true }
+ * });
+ * ```
+ *
+ * @throws {Error} If parsing fails or workflow contains errors
+ */
+export async function compileWorkflow(filePath, options = {}) {
+    const startTime = Date.now();
+    const { inPlace = true } = options;
+    const parseResult = await parseWorkflow(filePath, options.parse);
+    if (parseResult.errors.length > 0) {
+        throw new Error(`Parse errors:\n${parseResult.errors.join('\n')}`);
+    }
+    // Validate before generating
+    const { validateWorkflow } = await import('./validate.js');
+    const validationResult = validateWorkflow(parseResult.ast);
+    if (validationResult.errors.length > 0) {
+        const errorMessages = validationResult.errors.map((e) => typeof e === 'string' ? e : e.message);
+        throw new Error(`Validation errors:\n${errorMessages.join('\n')}`);
+    }
+    let code;
+    let outputFile;
+    if (inPlace) {
+        // In-place compilation: update source file
+        const sourceCode = await fs.readFile(filePath, 'utf-8');
+        const result = generateInPlace(sourceCode, parseResult.ast, {
+            ...options.generate,
+            allWorkflows: parseResult.allWorkflows,
+            sourceFile: options.generate?.sourceFile || path.resolve(filePath),
+        });
+        code = result.code;
+        outputFile = filePath;
+        if (options.write !== false) {
+            await fs.writeFile(filePath, code, 'utf-8');
+        }
+    }
+    else {
+        // Separate file compilation
+        code = generateCode(parseResult.ast, options.generate);
+        outputFile = options.outputFile || getDefaultOutputFile(filePath);
+        if (options.write !== false) {
+            await fs.writeFile(outputFile, code, 'utf-8');
+        }
+    }
+    if (options.saveAST) {
+        const { saveASTAlongside } = await import('../ast/serialization-node.js');
+        await saveASTAlongside(parseResult.ast);
+    }
+    const result = {
+        code,
+        ast: parseResult.ast,
+        analysis: {
+            controlFlowGraph: { nodes: [], edges: [], inDegree: {}, outDegree: {} },
+            executionOrder: [],
+            branchingNodes: [],
+            branchRegions: [],
+            mergeNodes: [],
+            errors: [],
+            warnings: [],
+            unusedNodes: [],
+            inlineCandidates: [],
+        },
+        metadata: {
+            sourceFile: filePath,
+            outputFile,
+            compiledAt: new Date().toISOString(),
+            compilerVersion: COMPILER_VERSION,
+            generationTime: Date.now() - startTime,
+        },
+    };
+    return result;
+}
+function getDefaultOutputFile(sourceFile) {
+    const dir = path.dirname(sourceFile);
+    // Remove .ts extension to get basename
+    const basename = path.basename(sourceFile, '.ts');
+    return path.join(dir, `${basename}.generated.ts`);
+}
+/**
+ * Compile multiple workflow files in parallel
+ *
+ * @param filePaths - Array of workflow file paths to compile
+ * @param options - Compilation options applied to all files
+ * @returns Array of CompileResults for each file
+ *
+ * @example
+ * ```typescript
+ * const results = await compileWorkflows([
+ *   './workflow-1.ts',
+ *   './workflow-2.ts'
+ * ]);
+ * ```
+ */
+export async function compileWorkflows(filePaths, options = {}) {
+    return Promise.all(filePaths.map((filePath) => compileWorkflow(filePath, options)));
+}
+/**
+ * Compile all workflow files matching a glob pattern
+ *
+ * Uses the glob library to find matching files and compiles them in parallel.
+ *
+ * @param pattern - Glob pattern (e.g., "src/**\/*.ts")
+ * @param options - Compilation options applied to all files
+ * @returns Array of CompileResults for each matched file
+ *
+ * @example
+ * ```typescript
+ * // Compile all workflow files in src directory
+ * const results = await compilePattern('src/**\/*.ts');
+ *
+ * // Compile with custom options
+ * const results = await compilePattern('workflows/**\/*.ts', {
+ *   generate: { production: true }
+ * });
+ * ```
+ */
+export async function compilePattern(pattern, options = {}) {
+    const glob = await import('glob');
+    const files = await glob.glob(pattern);
+    return compileWorkflows(files, options);
+}
+//# sourceMappingURL=compile.js.map

package/dist/api/extract-types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Type Declaration Extraction
+ *
+ * Extracts interface and type alias declarations from TypeScript source code.
+ * Used by generateCode to preserve type definitions in generated output.
+ */
+export interface ExtractedTypes {
+    /** Interface declarations (e.g., "interface Foo { ... }") */
+    interfaces: string[];
+    /** Type alias declarations (e.g., "type Bar = ...") */
+    typeAliases: string[];
+    /** Combined declarations in source order */
+    all: string[];
+}
+/**
+ * Extract interface and type alias declarations from TypeScript source code.
+ *
+ * @param sourceCode - The TypeScript source code
+ * @returns Object containing extracted type declarations
+ */
+export declare function extractTypeDeclarations(sourceCode: string): ExtractedTypes;
+/**
+ * Extract type declarations from a source file path.
+ *
+ * @param filePath - Path to the TypeScript source file
+ * @returns Object containing extracted type declarations, or empty if file can't be read
+ */
+export declare function extractTypeDeclarationsFromFile(filePath: string): ExtractedTypes;
+//# sourceMappingURL=extract-types.d.ts.map

package/dist/api/extract-types.js

@@ -0,0 +1,57 @@
+/**
+ * Type Declaration Extraction
+ *
+ * Extracts interface and type alias declarations from TypeScript source code.
+ * Used by generateCode to preserve type definitions in generated output.
+ */
+import * as ts from "typescript";
+import * as fs from "fs";
+/**
+ * Extract interface and type alias declarations from TypeScript source code.
+ *
+ * @param sourceCode - The TypeScript source code
+ * @returns Object containing extracted type declarations
+ */
+export function extractTypeDeclarations(sourceCode) {
+    const sourceFile = ts.createSourceFile("temp.ts", sourceCode, ts.ScriptTarget.Latest, true);
+    const interfaces = [];
+    const typeAliases = [];
+    const all = [];
+    ts.forEachChild(sourceFile, (node) => {
+        // Interface declarations
+        if (ts.isInterfaceDeclaration(node)) {
+            const text = sourceCode.slice(node.getFullStart(), node.getEnd()).trim();
+            interfaces.push(text);
+            all.push({ text, pos: node.getFullStart(), kind: "interface" });
+        }
+        // Type alias declarations
+        if (ts.isTypeAliasDeclaration(node)) {
+            const text = sourceCode.slice(node.getFullStart(), node.getEnd()).trim();
+            typeAliases.push(text);
+            all.push({ text, pos: node.getFullStart(), kind: "type" });
+        }
+    });
+    // Sort by source position to maintain original order
+    all.sort((a, b) => a.pos - b.pos);
+    return {
+        interfaces,
+        typeAliases,
+        all: all.map((item) => item.text),
+    };
+}
+/**
+ * Extract type declarations from a source file path.
+ *
+ * @param filePath - Path to the TypeScript source file
+ * @returns Object containing extracted type declarations, or empty if file can't be read
+ */
+export function extractTypeDeclarationsFromFile(filePath) {
+    try {
+        const sourceCode = fs.readFileSync(filePath, "utf-8");
+        return extractTypeDeclarations(sourceCode);
+    }
+    catch {
+        return { interfaces: [], typeAliases: [], all: [] };
+    }
+}
+//# sourceMappingURL=extract-types.js.map

package/dist/api/generate-in-place.d.ts

@@ -0,0 +1,73 @@
+/**
+ * In-Place Code Generation
+ *
+ * Generates executable code directly into the source file while preserving
+ * user code (node functions). Updates:
+ * - Runtime section (between markers)
+ * - Workflow JSDoc annotations (when AST changes)
+ * - Function body (between markers)
+ */
+import type { TWorkflowAST, TModuleFormat } from '../ast/types.js';
+export declare const MARKERS: {
+    RUNTIME_START: string;
+    RUNTIME_END: string;
+    BODY_START: string;
+    BODY_END: string;
+};
+export interface InPlaceGenerateOptions {
+    /**
+     * Whether to generate production-optimized code (no debug events)
+     */
+    production?: boolean;
+    /**
+     * All workflows in the file (needed to avoid orphaning node types
+     * used by other workflows during multi-workflow compilation)
+     */
+    allWorkflows?: TWorkflowAST[];
+    /**
+     * Module format for generated code ('esm' or 'cjs')
+     * @default 'esm'
+     */
+    moduleFormat?: TModuleFormat;
+    /**
+     * Force inline runtime even when @synergenius/flow-weaver package is installed.
+     * When false/undefined, the compiler auto-detects the package and uses
+     * external imports when available (smaller generated code, shared runtime).
+     * @default false
+     */
+    inlineRuntime?: boolean;
+    /**
+     * Absolute path to the source file being compiled.
+     * Used to detect if @synergenius/flow-weaver is installed relative to the file.
+     * If not provided, falls back to process.cwd().
+     */
+    sourceFile?: string;
+    /**
+     * When true, omit @param/@returns annotations from the workflow JSDoc.
+     * The parser auto-infers Start/Exit ports from function signatures,
+     * so these annotations are redundant for non-visual-editor users.
+     */
+    skipParamReturns?: boolean;
+}
+export interface InPlaceGenerateResult {
+    code: string;
+    hasChanges: boolean;
+}
+/**
+ * Generate executable code in-place, preserving user code.
+ *
+ * @param sourceCode - The original source code
+ * @param ast - The parsed workflow AST
+ * @param options - Generation options
+ * @returns The updated source code with generated sections
+ */
+export declare function generateInPlace(sourceCode: string, ast: TWorkflowAST, options?: InPlaceGenerateOptions): InPlaceGenerateResult;
+/**
+ * Check if source code has in-place generation markers
+ */
+export declare function hasInPlaceMarkers(source: string): boolean;
+/**
+ * Remove all generated sections from source code
+ */
+export declare function stripGeneratedSections(source: string): string;
+//# sourceMappingURL=generate-in-place.d.ts.map