@synergenius/flow-weaver 0.2.0

package/dist/function-like.js

@@ -0,0 +1,83 @@
+/**
+ * FunctionLike interface
+ *
+ * Abstracts over FunctionDeclaration and arrow/function-expression variable
+ * declarations so the JSDoc parser and annotation parser can handle both
+ * syntactic forms uniformly.
+ */
+import { Node, SyntaxKind, VariableDeclarationKind, } from 'ts-morph';
+function wrapFunctionDeclaration(fn) {
+    return {
+        getJsDocs: () => fn.getJsDocs(),
+        getName: () => fn.getName(),
+        isAsync: () => fn.isAsync(),
+        getParameters: () => fn.getParameters(),
+        getReturnType: () => fn.getReturnType(),
+        getStartLineNumber: (inc) => fn.getStartLineNumber(inc),
+        getText: (inc) => fn.getText(inc),
+        getSourceFile: () => fn.getSourceFile(),
+        getTypeResolutionNode: () => fn,
+    };
+}
+/**
+ * Scan a source file and return every function-like declaration that could
+ * carry @flowWeaver annotations:
+ *
+ *  1. Classic `function foo() {}`         — FunctionDeclaration (existing)
+ *  2. `const foo = () => {}`              — ArrowFunction assigned to variable
+ *  3. `const foo = function() {}`         — FunctionExpression assigned to variable
+ *
+ * The returned list preserves source order.
+ */
+export function extractFunctionLikes(sourceFile) {
+    const results = [];
+    // 1. Regular function declarations — wrapped to satisfy getTypeResolutionNode()
+    for (const fn of sourceFile.getFunctions()) {
+        results.push(wrapFunctionDeclaration(fn));
+    }
+    // 2. Variable declarations with arrow/function expression initializers
+    for (const varDecl of sourceFile.getVariableDeclarations()) {
+        const initializer = varDecl.getInitializer();
+        if (!initializer)
+            continue;
+        const kind = initializer.getKind();
+        if (kind !== SyntaxKind.ArrowFunction && kind !== SyntaxKind.FunctionExpression)
+            continue;
+        const fnExpr = initializer;
+        // Walk up: VariableDeclaration -> VariableDeclarationList -> VariableStatement
+        const varDeclList = varDecl.getParent();
+        if (!Node.isVariableDeclarationList(varDeclList))
+            continue;
+        const varStatement = varDeclList.getParent();
+        if (!Node.isVariableStatement(varStatement))
+            continue;
+        // Determine declaration kind (const/let/var)
+        const declKindEnum = varDeclList.getDeclarationKind();
+        const declKind = declKindEnum === VariableDeclarationKind.Let
+            ? 'let'
+            : declKindEnum === VariableDeclarationKind.Var
+                ? 'var'
+                : 'const';
+        const adapter = {
+            getName: () => varDecl.getName(),
+            getJsDocs: () => varStatement.getJsDocs(),
+            isAsync: () => fnExpr.isAsync(),
+            getParameters: () => fnExpr.getParameters(),
+            getReturnType: () => fnExpr.getReturnType(),
+            getStartLineNumber: () => varStatement.getStartLineNumber(false),
+            getText: () => {
+                // Return the variable statement text without JSDoc (consistent with FunctionDeclaration.getText()).
+                // The parser code manually prepends JSDoc via getJsDocs().
+                return varStatement.getText(false);
+            },
+            getSourceFile: () => sourceFile,
+            getDeclarationKind: () => declKind,
+            getTypeResolutionNode: () => varDecl,
+        };
+        results.push(adapter);
+    }
+    // Sort by source position to preserve declaration order
+    results.sort((a, b) => a.getStartLineNumber(false) - b.getStartLineNumber(false));
+    return results;
+}
+//# sourceMappingURL=function-like.js.map

package/dist/generated-branding.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Configurable branding for generated output.
+ *
+ * The library ships with generic defaults. The root project (app/CLI)
+ * calls {@link configureGeneratedBranding} at startup to inject
+ * organisation-specific values (URLs, attribution text, etc.).
+ */
+export interface GeneratedBranding {
+    /** Single-line comment placed at the top of generated code files */
+    header: (command?: string) => string;
+    /** Markdown attribution line for generated documentation */
+    markdown: string;
+}
+export declare function configureGeneratedBranding(branding: GeneratedBranding): void;
+export declare function getGeneratedBranding(): GeneratedBranding;
+//# sourceMappingURL=generated-branding.d.ts.map

package/dist/generated-branding.js

@@ -0,0 +1,22 @@
+/**
+ * Configurable branding for generated output.
+ *
+ * The library ships with generic defaults. The root project (app/CLI)
+ * calls {@link configureGeneratedBranding} at startup to inject
+ * organisation-specific values (URLs, attribution text, etc.).
+ */
+const WEBSITE_URL = 'https://flowweaver.ai';
+const DEFAULT = {
+    header: (cmd) => cmd
+        ? `// Generated by Flow Weaver (${WEBSITE_URL}) — ${cmd}`
+        : `// Generated by Flow Weaver (${WEBSITE_URL})`,
+    markdown: `*Generated by [Flow Weaver](${WEBSITE_URL})*`,
+};
+let _branding = DEFAULT;
+export function configureGeneratedBranding(branding) {
+    _branding = branding;
+}
+export function getGeneratedBranding() {
+    return _branding;
+}
+//# sourceMappingURL=generated-branding.js.map

package/dist/generator/async-detection.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Async Detection Logic
+ * Determines whether a workflow should be generated as async based on node composition
+ */
+import { TWorkflowAST, TNodeTypeAST } from "../ast/types.js";
+/**
+ * Determines if a workflow should be async based on its node composition
+ * Rule: Workflow is async if ANY node in its execution graph is async
+ *
+ * @param workflow - The workflow AST
+ * @param nodeTypes - Available node types
+ * @returns true if any node in the workflow is async, false otherwise
+ */
+export declare function shouldWorkflowBeAsync(workflow: TWorkflowAST, nodeTypes: TNodeTypeAST[]): boolean;
+/**
+ * Validates workflow async mode and returns final decision with optional warning
+ * Respects user's intent but ensures correctness
+ *
+ * @param workflow - The workflow AST
+ * @param nodeTypes - Available node types
+ * @returns Object with shouldBeAsync decision and optional warning
+ */
+export declare function validateWorkflowAsync(workflow: TWorkflowAST, nodeTypes: TNodeTypeAST[]): {
+    shouldBeAsync: boolean;
+    warning?: string;
+};
+//# sourceMappingURL=async-detection.d.ts.map

package/dist/generator/async-detection.js

@@ -0,0 +1,56 @@
+/**
+ * Async Detection Logic
+ * Determines whether a workflow should be generated as async based on node composition
+ */
+/**
+ * Determines if a workflow should be async based on its node composition
+ * Rule: Workflow is async if ANY node in its execution graph is async
+ *
+ * @param workflow - The workflow AST
+ * @param nodeTypes - Available node types
+ * @returns true if any node in the workflow is async, false otherwise
+ */
+export function shouldWorkflowBeAsync(workflow, nodeTypes) {
+    // Build map of node type name -> isAsync
+    // Map both nt.name and nt.functionName to support npm nodes where instance.nodeType uses nt.name
+    const nodeTypeMap = new Map();
+    for (const nt of nodeTypes) {
+        nodeTypeMap.set(nt.name, nt.isAsync);
+        if (nt.functionName && nt.functionName !== nt.name) {
+            nodeTypeMap.set(nt.functionName, nt.isAsync);
+        }
+    }
+    // Check if ANY instance uses an async node type
+    for (const instance of workflow.instances) {
+        const isAsync = nodeTypeMap.get(instance.nodeType);
+        if (isAsync === true) {
+            return true; // Found an async node
+        }
+    }
+    return false; // All nodes are sync (or no nodes)
+}
+/**
+ * Validates workflow async mode and returns final decision with optional warning
+ * Respects user's intent but ensures correctness
+ *
+ * @param workflow - The workflow AST
+ * @param nodeTypes - Available node types
+ * @returns Object with shouldBeAsync decision and optional warning
+ */
+export function validateWorkflowAsync(workflow, nodeTypes) {
+    const computedAsync = shouldWorkflowBeAsync(workflow, nodeTypes);
+    const userAsync = workflow.userSpecifiedAsync ?? true; // Default to async for backwards compat
+    if (!userAsync && computedAsync) {
+        // User wrote sync function, but workflow contains async nodes
+        return {
+            shouldBeAsync: true, // Force async for correctness
+            warning: `Workflow function '${workflow.functionName}' was declared as sync, but contains async nodes. Generating as async function.`
+        };
+    }
+    // Either:
+    // - User wrote async and nodes are async (correct)
+    // - User wrote async and nodes are sync (honor user's choice, slight overhead but safe)
+    // - User wrote sync and nodes are sync (correct)
+    return { shouldBeAsync: computedAsync || userAsync };
+}
+//# sourceMappingURL=async-detection.js.map

package/dist/generator/code-utils.d.ts

@@ -0,0 +1,76 @@
+import type { TNodeTypeAST, TWorkflowAST, TMergeStrategy } from '../ast/index.js';
+/**
+ * Sanitize a node ID to be a valid JavaScript identifier.
+ * Replaces non-alphanumeric characters (except _ and $) with underscores.
+ *
+ * @param nodeId - The node ID (may contain slashes, etc.)
+ * @returns A valid JavaScript identifier
+ */
+export declare function toValidIdentifier(nodeId: string): string;
+/**
+ * Build a JavaScript expression that merges multiple source values based on strategy.
+ *
+ * @param sources - Array of source variable names
+ * @param strategy - Merge strategy to apply
+ * @returns JavaScript expression string
+ */
+export declare function buildMergeExpression(sources: string[], strategy: TMergeStrategy): string;
+export type TBuildNodeArgsOptions = {
+    node: TNodeTypeAST;
+    workflow: TWorkflowAST;
+    id: string;
+    lines: string[];
+    indent?: string;
+    getCall?: string;
+    isAsync?: boolean;
+    instanceParent?: string;
+    skipPorts?: Set<string>;
+    emitInputEvents?: boolean;
+    setCall?: string;
+    nodeTypeName?: string;
+    bundleMode?: boolean;
+};
+/**
+ * Builds the argument list for a node function call by resolving input port values.
+ *
+ * This function is central to code generation - it determines where each input port
+ * gets its value from: connections, expressions, defaults, or execution strategies.
+ *
+ * ## Resolution Priority (per port):
+ * 1. **Skip Ports**: If port is in skipPorts set, use pre-declared variable
+ * 2. **Instance Expression**: Check instance.config.portConfigs for evaluateConstantAs
+ * 3. **Connection**: Get value from connected output port via ctx.getVariable()
+ * 4. **Node Type Expression**: Check nodeType.inputs[port].expression
+ * 5. **Default Value**: Use nodeType.inputs[port].default if available
+ * 6. **Undefined**: No value source found (may cause runtime error)
+ *
+ * ## Special Handling:
+ * - **execute port**: Always first, handles CONJUNCTION/DISJUNCTION strategies
+ * - **Scoped INPUT ports**: Skipped (they're return values from scope functions)
+ * - **STEP ports (onSuccess/onFailure)**: Use executionSignal config if present
+ * - **Scope functions**: Generated via generateScopeFunctionClosure() for FUNCTION ports
+ *
+ * ## STEP Port Execution Strategies:
+ * - **CONJUNCTION (AND)**: `execute = stepA && stepB && stepC`
+ * - **DISJUNCTION (OR)**: `execute = stepA || stepB || stepC`
+ * - **CUSTOM**: Uses evaluateExecutionSignalAs expression
+ *
+ * @param opts - Configuration object with node, workflow, and generation settings
+ * @param opts.node - The node type definition with input/output port specs
+ * @param opts.workflow - The workflow AST containing connections and instances
+ * @param opts.id - The node instance ID being generated
+ * @param opts.lines - Array to push generated code lines into
+ * @param opts.indent - Indentation prefix for generated lines (default: "    ")
+ * @param opts.getCall - Method to get variables (default: "await ctx.getVariable")
+ * @param opts.isAsync - Whether generating async code
+ * @param opts.instanceParent - Parent node ID if this node is in a scope
+ * @param opts.skipPorts - Ports to skip (already pre-handled)
+ * @param opts.emitInputEvents - Whether to emit VARIABLE_SET events for inputs
+ * @param opts.setCall - Method to set variables (default: "await ctx.setVariable")
+ * @param opts.nodeTypeName - Override for node type name in events
+ * @returns Array of argument expressions to pass to the node function
+ */
+export declare function buildNodeArgumentsWithContext(opts: TBuildNodeArgsOptions): string[];
+export declare function generateNodeWithExecutionContext(node: TNodeTypeAST, workflow: TWorkflowAST, lines: string[], isAsync: boolean, indent?: string): void;
+export declare function buildExecutionContextReturnForBranch(workflow: TWorkflowAST, lines: string[], isAsync: boolean, branchName: string, indent: string, executedNodes: string[]): string;
+//# sourceMappingURL=code-utils.d.ts.map