@synergenius/flow-weaver 0.2.0

package/dist/annotation-generator.js

@@ -0,0 +1,557 @@
+import { mapToTypeScript } from "./type-mappings.js";
+import { isExecutePort, isSuccessPort, isFailurePort, isControlFlowPort } from "./constants.js";
+import { shouldUseStepTag } from "./utils/port-tag-utils.js";
+import { detectSugarPatterns, filterStaleMacros } from "./sugar-optimizer.js";
+export class AnnotationGenerator {
+    generate(workflow, options = {}) {
+        const { includeComments = true, includeMetadata = true, indentSize = 2, skipParamReturns = false, } = options;
+        const indent = " ".repeat(indentSize);
+        const lines = [];
+        if (includeComments) {
+            lines.push("");
+            lines.push("");
+        }
+        workflow.nodeTypes.forEach((nodeType) => {
+            // Skip the workflow's own IMPORTED_WORKFLOW entry (would create duplicate)
+            if (nodeType.variant === 'IMPORTED_WORKFLOW' && nodeType.functionName === workflow.functionName) {
+                return;
+            }
+            // Skip synthetic MAP_ITERATOR node types — they're generated from @map macros
+            if (nodeType.variant === 'MAP_ITERATOR') {
+                return;
+            }
+            lines.push(...this.generateNodeTypeAnnotation(nodeType, indent, includeComments, includeMetadata));
+            lines.push("");
+        });
+        lines.push(...this.generateWorkflowAnnotation(workflow, indent, includeComments, skipParamReturns));
+        lines.push("");
+        return lines.join("\n");
+    }
+    generateNodeTypeAnnotation(nodeType, indent, includeComments, includeMetadata) {
+        const lines = [];
+        // If functionText exists, it already includes the JSDoc - use it directly
+        if (nodeType.functionText) {
+            lines.push(nodeType.functionText);
+            return lines;
+        }
+        // Generate JSDoc comment block (only when no functionText)
+        lines.push("/**");
+        // Add description if present
+        if (includeComments && nodeType.description) {
+            lines.push(` * ${nodeType.description}`);
+            lines.push(` *`);
+        }
+        // @flowWeaver nodeType marker
+        lines.push(" * @flowWeaver nodeType");
+        // Add label if present
+        if (includeMetadata && nodeType.label) {
+            lines.push(` * @label ${nodeType.label}`);
+        }
+        // Add name if different from function name (preserves display name across save/reload)
+        if (includeMetadata && nodeType.name && nodeType.name !== nodeType.functionName) {
+            lines.push(` * @name ${nodeType.name}`);
+        }
+        // Add scope if present
+        if (nodeType.scope) {
+            lines.push(` * @scope ${nodeType.scope}`);
+        }
+        // Add pullExecution if present
+        if (nodeType.defaultConfig?.pullExecution) {
+            lines.push(` * @pullExecution ${nodeType.defaultConfig.pullExecution.triggerPort}`);
+        }
+        // Add input ports (with automatic ordering)
+        const inputEntries = this.assignPortOrders(Object.entries(nodeType.inputs), 'input');
+        inputEntries.forEach(([name, port]) => {
+            const portTag = this.generateJSDocPortTag(name, port, 'input');
+            lines.push(` * ${portTag}`);
+        });
+        // Add output ports (with automatic ordering)
+        const outputEntries = this.assignPortOrders(Object.entries(nodeType.outputs), 'output');
+        outputEntries.forEach(([name, port]) => {
+            const portTag = this.generateJSDocPortTag(name, port, 'output');
+            lines.push(` * ${portTag}`);
+        });
+        lines.push(" */");
+        // Generate function signature
+        lines.push(...this.generateFunctionSignature(nodeType));
+        return lines;
+    }
+    generateJSDocPortTag(name, port, direction, implicitOrder) {
+        return generateJSDocPortTag(name, port, direction, implicitOrder);
+    }
+    generateTPortDefinition(port, _indent) {
+        if (!port.optional &&
+            port.default === undefined &&
+            !port.expression &&
+            !port.label &&
+            !port.hidden &&
+            !port.failure) {
+            return `'${port.dataType}'`;
+        }
+        const props = [];
+        props.push(`type: '${port.dataType}'`);
+        if (port.optional) {
+            props.push(`optional: true`);
+        }
+        if (port.default !== undefined) {
+            props.push(`defaultValue: ${JSON.stringify(port.default)}`);
+        }
+        if (port.expression) {
+            props.push(`expression: \`${port.expression}\``);
+        }
+        if (port.label) {
+            props.push(`label: '${port.label}'`);
+        }
+        if (port.hidden) {
+            props.push(`hidden: true`);
+        }
+        if (port.failure) {
+            props.push(`failure: true`);
+        }
+        return `{ ${props.join(", ")} }`;
+    }
+    generateFunctionSignature(nodeType) {
+        const lines = [];
+        // Build parameters (excluding execute which will be first)
+        const params = ["execute: boolean"];
+        Object.entries(nodeType.inputs).forEach(([name, port]) => {
+            if (isExecutePort(name))
+                return;
+            const optional = port.optional ? "?" : "";
+            const defaultVal = port.default !== undefined ? ` = ${JSON.stringify(port.default)}` : "";
+            params.push(`${name}${optional}: ${this.mapDataTypeToTS(port.dataType)}${defaultVal}`);
+        });
+        // Build return type (including onSuccess/onFailure)
+        const returns = ["onSuccess: boolean", "onFailure: boolean"];
+        Object.entries(nodeType.outputs).forEach(([name, port]) => {
+            if (isSuccessPort(name) || isFailurePort(name))
+                return;
+            returns.push(`${name}: ${this.mapDataTypeToTS(port.dataType)}`);
+        });
+        lines.push(`function ${nodeType.functionName}(${params.join(", ")}) {`);
+        lines.push(`  if (!execute) return { onSuccess: false, onFailure: false };`);
+        lines.push(`  return { onSuccess: true, onFailure: false };`);
+        lines.push(`}`);
+        return lines;
+    }
+    generateWorkflowAnnotation(workflow, indent, includeComments, skipParamReturns = false) {
+        const lines = [];
+        // Build macro coverage sets for filtering (@map-specific)
+        const macroInstanceIds = new Set();
+        const macroChildIds = new Set();
+        const macroScopeNames = new Set();
+        if (workflow.macros && workflow.macros.length > 0) {
+            for (const macro of workflow.macros) {
+                if (macro.type === 'map') {
+                    macroInstanceIds.add(macro.instanceId);
+                    macroChildIds.add(macro.childId);
+                    macroScopeNames.add(`${macro.instanceId}.iterate`);
+                }
+            }
+        }
+        // Generate JSDoc comment block
+        lines.push("/**");
+        // Add description if present
+        if (includeComments && workflow.description) {
+            lines.push(` * ${workflow.description}`);
+            lines.push(` *`);
+        }
+        // @flowWeaver workflow marker
+        lines.push(" * @flowWeaver workflow");
+        // Add strictTypes option if enabled
+        if (workflow.options?.strictTypes) {
+            lines.push(" * @strictTypes");
+        }
+        // Add autoConnect option if enabled
+        if (workflow.options?.autoConnect) {
+            lines.push(" * @autoConnect");
+        }
+        // @trigger round-trip
+        if (workflow.options?.trigger) {
+            const t = workflow.options.trigger;
+            const parts = [];
+            if (t.event)
+                parts.push(`event="${t.event}"`);
+            if (t.cron)
+                parts.push(`cron="${t.cron}"`);
+            if (parts.length > 0)
+                lines.push(` * @trigger ${parts.join(' ')}`);
+        }
+        // @cancelOn round-trip
+        if (workflow.options?.cancelOn) {
+            const c = workflow.options.cancelOn;
+            let line = ` * @cancelOn event="${c.event}"`;
+            if (c.match)
+                line += ` match="${c.match}"`;
+            if (c.timeout)
+                line += ` timeout="${c.timeout}"`;
+            lines.push(line);
+        }
+        // @retries round-trip
+        if (workflow.options?.retries !== undefined) {
+            lines.push(` * @retries ${workflow.options.retries}`);
+        }
+        // @timeout round-trip
+        if (workflow.options?.timeout) {
+            lines.push(` * @timeout "${workflow.options.timeout}"`);
+        }
+        // @throttle round-trip
+        if (workflow.options?.throttle) {
+            const t = workflow.options.throttle;
+            let line = ` * @throttle limit=${t.limit}`;
+            if (t.period)
+                line += ` period="${t.period}"`;
+            lines.push(line);
+        }
+        // Add name if different from export name
+        if (workflow.name && workflow.name !== workflow.functionName) {
+            lines.push(` * @name ${workflow.name}`);
+        }
+        // Add description tag
+        if (workflow.description && includeComments) {
+            lines.push(` * @description ${workflow.description}`);
+        }
+        // Add node instances — skip synthetic MAP_ITERATOR instances, strip parent from macro children
+        workflow.instances.forEach((instance) => {
+            if (macroInstanceIds.has(instance.id))
+                return;
+            if (macroChildIds.has(instance.id) && instance.parent) {
+                const stripped = { ...instance, parent: undefined };
+                lines.push(generateNodeInstanceTag(stripped));
+            }
+            else {
+                lines.push(generateNodeInstanceTag(instance));
+            }
+        });
+        // Filter stale macros (e.g. paths whose connections were deleted)
+        const existingMacros = filterStaleMacros(workflow.macros || [], workflow.connections, workflow.instances);
+        // Auto-detect @path sugar patterns from connections
+        const detected = detectSugarPatterns(workflow.connections, workflow.instances, existingMacros, workflow.nodeTypes, workflow.startPorts, workflow.exitPorts);
+        // Merge detected macros with existing ones
+        const allMacros = [
+            ...existingMacros,
+            ...detected.paths,
+        ];
+        // Add @map and @path macros
+        if (allMacros.length > 0) {
+            for (const macro of allMacros) {
+                if (macro.type === 'map') {
+                    let mapLine = ` * @map ${macro.instanceId} ${macro.childId}`;
+                    if (macro.inputPort || macro.outputPort) {
+                        mapLine += `(${macro.inputPort} -> ${macro.outputPort})`;
+                    }
+                    mapLine += ` over ${macro.sourcePort}`;
+                    lines.push(mapLine);
+                }
+                else if (macro.type === 'path') {
+                    const stepsStr = macro.steps.map(s => s.route ? `${s.node}:${s.route}` : s.node).join(' -> ');
+                    lines.push(` * @path ${stepsStr}`);
+                }
+            }
+        }
+        // Add node positions (if they exist)
+        // Start with Start node position if present
+        if (workflow.ui?.startNode?.x !== undefined && workflow.ui?.startNode?.y !== undefined) {
+            lines.push(` * @position Start ${Math.round(workflow.ui.startNode.x)} ${Math.round(workflow.ui.startNode.y)}`);
+        }
+        // Add instance positions
+        workflow.instances.forEach((instance) => {
+            if (instance.config?.x !== undefined && instance.config?.y !== undefined) {
+                lines.push(` * @position ${instance.id} ${Math.round(instance.config.x)} ${Math.round(instance.config.y)}`);
+            }
+        });
+        // Add Exit node position if present
+        if (workflow.ui?.exitNode?.x !== undefined && workflow.ui?.exitNode?.y !== undefined) {
+            lines.push(` * @position Exit ${Math.round(workflow.ui.exitNode.x)} ${Math.round(workflow.ui.exitNode.y)}`);
+        }
+        // Add connections — skip connections covered by macros
+        if (!workflow.options?.autoConnect) {
+            workflow.connections.forEach((conn) => {
+                if (allMacros.length > 0 && isConnectionCoveredByMacroStatic(conn, allMacros))
+                    return;
+                const fromScope = conn.from.scope ? `:${conn.from.scope}` : '';
+                const toScope = conn.to.scope ? `:${conn.to.scope}` : '';
+                lines.push(` * @connect ${conn.from.node}.${conn.from.port}${fromScope} -> ${conn.to.node}.${conn.to.port}${toScope}`);
+            });
+        }
+        // Add @param annotations for start ports (workflow inputs)
+        if (!skipParamReturns && workflow.startPorts && Object.keys(workflow.startPorts).length > 0) {
+            const startPortEntries = this.assignPortOrders(Object.entries(workflow.startPorts), 'input');
+            startPortEntries.forEach(([name, port], index) => {
+                const paramTag = this.generateJSDocPortTag(name, port, 'input', index);
+                // Replace @input with @param for workflow-level JSDoc
+                lines.push(` * ${paramTag.replace('@input', '@param')}`);
+            });
+        }
+        // Add @returns annotations for exit ports (workflow outputs)
+        if (!skipParamReturns && workflow.exitPorts && Object.keys(workflow.exitPorts).length > 0) {
+            const exitPortEntries = this.assignPortOrders(Object.entries(workflow.exitPorts), 'output');
+            exitPortEntries.forEach(([name, port], index) => {
+                const returnTag = this.generateJSDocPortTag(name, port, 'output', index);
+                // Replace @output with @returns for workflow-level JSDoc
+                lines.push(` * ${returnTag.replace('@output', '@returns')}`);
+            });
+        }
+        // Add scopes — skip scopes covered by @map macros
+        if (workflow.scopes) {
+            Object.entries(workflow.scopes).forEach(([scopeName, children]) => {
+                if (macroScopeNames.has(scopeName))
+                    return;
+                lines.push(` * @scope ${scopeName} [${children.join(', ')}]`);
+            });
+        }
+        lines.push(" */");
+        // Add workflow function signature
+        lines.push(...this.generateWorkflowFunctionSignature(workflow));
+        return lines;
+    }
+    generateWorkflowFunctionSignature(workflow) {
+        const lines = [];
+        const startPorts = workflow.startPorts || {};
+        const exitPorts = workflow.exitPorts || {};
+        // Build parameter types (excluding execute)
+        const params = [];
+        Object.entries(startPorts).forEach(([name, port]) => {
+            if (isExecutePort(name))
+                return;
+            const optional = port.optional ? "?" : "";
+            params.push(`${name}${optional}: ${this.mapDataTypeToTS(port.dataType)}`);
+        });
+        // Build return types (including onSuccess/onFailure)
+        const returns = [];
+        Object.entries(exitPorts).forEach(([name, port]) => {
+            const optional = port.optional ? "?" : "";
+            returns.push(`${name}${optional}: ${this.mapDataTypeToTS(port.dataType)}`);
+        });
+        // Generate async function signature with execute parameter
+        lines.push(`export async function ${workflow.functionName}(`);
+        lines.push(`  execute: boolean,`);
+        lines.push(`  params: { ${params.join("; ")} }`);
+        lines.push(`): Promise<{ ${returns.join("; ")} }> {`);
+        lines.push(`  throw new Error('Not implemented');`);
+        lines.push("}");
+        return lines;
+    }
+    assignPortOrders(ports, direction) {
+        return assignPortOrders(ports, direction);
+    }
+    mapDataTypeToTS(dataType) {
+        return mapToTypeScript(dataType);
+    }
+}
+/**
+ * Generate JSDoc port tag (e.g., @input name - Description)
+ * Exported for reuse in generate-in-place.ts to maintain DRY principle
+ *
+ * New format (types derived from signature):
+ * - @input name - Description
+ * - @output name - Description
+ * - @step name - Description (for explicit STEP/control-flow ports)
+ *
+ * Reserved STEP ports (execute, onSuccess, onFailure) use @input/@output.
+ * Custom STEP ports use @step.
+ */
+export function generateJSDocPortTag(name, port, direction, _implicitOrder) {
+    // Determine tag: @step for explicit control flow, @input/@output for data
+    // Reserved STEP ports (execute, onSuccess, onFailure) stay as @input/@output
+    // Scoped mandatory ports (start, success, failure) with scope attribute also stay as @input/@output
+    const tag = shouldUseStepTag(name, port) ? 'step' : direction;
+    // Format: @input [name=default] - Description
+    // or: @input name - Expression: (ctx) => ...
+    let portStr = `@${tag} `;
+    // Handle optional with default value: [name=value]
+    if (port.optional && port.default !== undefined) {
+        portStr += `[${name}=${JSON.stringify(port.default)}]`;
+    }
+    // Handle optional without default: [name]
+    else if (port.optional) {
+        portStr += `[${name}]`;
+    }
+    // Handle required with default: name=value (though rare)
+    else if (port.default !== undefined) {
+        portStr += `${name}=${JSON.stringify(port.default)}`;
+    }
+    // Regular required port
+    else {
+        portStr += name;
+    }
+    // Add scope attribute if present (for per-port scoped architecture)
+    if (port.scope) {
+        portStr += ` scope:${port.scope}`;
+    }
+    // Add order metadata whenever it's explicitly set to preserve round-trip fidelity
+    // Even if order matches position, we must write it to avoid losing metadata on re-parse
+    if (port.metadata?.order !== undefined) {
+        portStr += ` [order:${port.metadata.order}]`;
+    }
+    // Add placement metadata when explicitly set
+    if (port.metadata?.placement !== undefined) {
+        portStr += ` [placement:${port.metadata.placement}]`;
+    }
+    if (port.expression) {
+        portStr += ` - Expression: ${port.expression}`;
+    }
+    else if (port.label && port.label !== name) {
+        // Only add label if it differs from the port name
+        portStr += ` - ${port.label}`;
+    }
+    return portStr;
+}
+/**
+ * Check if a connection is covered by a macro (and should not be written as @connect).
+ * Handles both @map and @path macros.
+ */
+function isConnectionCoveredByMacroStatic(conn, macros) {
+    for (const macro of macros) {
+        if (macro.type === 'map') {
+            const [sourceNode, sourcePort] = macro.sourcePort.split('.');
+            // Scoped connections between the map instance and its child
+            if ((conn.from.node === macro.instanceId || conn.from.node === macro.childId) &&
+                (conn.to.node === macro.instanceId || conn.to.node === macro.childId) &&
+                (conn.from.scope === 'iterate' || conn.to.scope === 'iterate')) {
+                return true;
+            }
+            // Upstream connection: source.port -> mapInstance.items
+            if (conn.from.node === sourceNode &&
+                conn.from.port === sourcePort &&
+                !conn.from.scope &&
+                conn.to.node === macro.instanceId &&
+                conn.to.port === 'items' &&
+                !conn.to.scope) {
+                return true;
+            }
+        }
+        else if (macro.type === 'path') {
+            if (conn.from.scope || conn.to.scope)
+                continue;
+            const steps = macro.steps;
+            const fromIdx = steps.findIndex(s => s.node === conn.from.node);
+            const toIdx = steps.findIndex(s => s.node === conn.to.node);
+            if (fromIdx === -1 || toIdx === -1 || fromIdx >= toIdx)
+                continue;
+            // Control flow: check consecutive pairs
+            if (toIdx === fromIdx + 1) {
+                const route = steps[fromIdx].route || 'ok';
+                // Start.execute -> next.execute
+                if (conn.from.node === 'Start' && conn.from.port === 'execute' && conn.to.port === 'execute')
+                    return true;
+                // To Exit: route determines which Exit port
+                if (conn.to.node === 'Exit') {
+                    if (route === 'fail' && conn.from.port === 'onFailure' && conn.to.port === 'onFailure')
+                        return true;
+                    if (route === 'ok' && conn.from.port === 'onSuccess' && conn.to.port === 'onSuccess')
+                        return true;
+                }
+                // Normal: onSuccess/onFailure -> execute
+                if (route === 'fail' && conn.from.port === 'onFailure' && conn.to.port === 'execute')
+                    return true;
+                if (route === 'ok' && conn.from.port === 'onSuccess' && conn.to.port === 'execute')
+                    return true;
+            }
+            // Data: same-name non-control-flow, from before to, to is not Exit
+            if (conn.to.node !== 'Exit' &&
+                !isControlFlowPort(conn.from.port) &&
+                !isControlFlowPort(conn.to.port) &&
+                conn.from.port === conn.to.port) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Simply return ports as-is to preserve exact order from the AST
+ * Don't compute or add any new metadata - only preserve what's already there
+ * This ensures perfect round-trip fidelity
+ * Exported for reuse in generate-in-place.ts to maintain DRY principle
+ */
+export function assignPortOrders(ports, _direction) {
+    return ports;
+}
+/**
+ * Generate @node tag for a single instance
+ * Exported for reuse in generate-in-place.ts to maintain DRY principle
+ */
+export function generateNodeInstanceTag(instance) {
+    const parent = instance.parent ? ` ${instance.parent.id}.${instance.parent.scope}` : '';
+    // Generate [label: ...] attribute if present and different from id
+    let labelAttr = '';
+    if (instance.config?.label && instance.config.label !== instance.id) {
+        // Escape quotes in the label
+        const escapedLabel = instance.config.label.replace(/"/g, '\\"');
+        labelAttr = ` [label: "${escapedLabel}"]`;
+    }
+    // Generate [portOrder: ...] attribute if present
+    let portOrderAttr = '';
+    if (instance.config?.portConfigs && instance.config.portConfigs.length > 0) {
+        const orderConfigs = instance.config.portConfigs
+            .filter(pc => pc.order !== undefined)
+            .map(pc => `${pc.portName}=${pc.order}`)
+            .join(',');
+        if (orderConfigs) {
+            portOrderAttr = ` [portOrder: ${orderConfigs}]`;
+        }
+    }
+    // Generate [portLabel: ...] attribute if present
+    let portLabelAttr = '';
+    if (instance.config?.portConfigs && instance.config.portConfigs.length > 0) {
+        const labelConfigs = instance.config.portConfigs
+            .filter(pc => pc.label !== undefined && pc.label !== '')
+            .map(pc => {
+            const escapedLabel = String(pc.label).replace(/"/g, '\\"');
+            return `${pc.portName}="${escapedLabel}"`;
+        })
+            .join(', ');
+        if (labelConfigs) {
+            portLabelAttr = ` [portLabel: ${labelConfigs}]`;
+        }
+    }
+    // Generate [expr: ...] attribute if any port has an expression
+    let exprAttr = '';
+    if (instance.config?.portConfigs && instance.config.portConfigs.length > 0) {
+        const exprConfigs = instance.config.portConfigs
+            .filter(pc => pc.expression !== undefined)
+            .map(pc => {
+            // Escape quotes and */ (which would close the JSDoc comment)
+            const escapedExpr = String(pc.expression)
+                .replace(/"/g, '\\"')
+                .replace(/\*\//g, '*\\/');
+            return `${pc.portName}="${escapedExpr}"`;
+        })
+            .join(', ');
+        if (exprConfigs) {
+            exprAttr = ` [expr: ${exprConfigs}]`;
+        }
+    }
+    // Generate [pullExecution: ...] attribute if present
+    let pullExecutionAttr = '';
+    if (instance.config?.pullExecution) {
+        pullExecutionAttr = ` [pullExecution: ${instance.config.pullExecution.triggerPort}]`;
+    }
+    // Generate [minimized] attribute if present
+    const minimizedAttr = instance.config?.minimized ? ' [minimized]' : '';
+    // Generate [color: "value"] attribute if present
+    let colorAttr = '';
+    if (instance.config?.color) {
+        colorAttr = ` [color: "${instance.config.color}"]`;
+    }
+    // Generate [icon: "value"] attribute if present
+    let iconAttr = '';
+    if (instance.config?.icon) {
+        iconAttr = ` [icon: "${instance.config.icon}"]`;
+    }
+    // Generate [tags: "label" "tooltip", "label2"] attribute if present
+    let tagsAttr = '';
+    if (instance.config?.tags?.length) {
+        const tagEntries = instance.config.tags.map(t => t.tooltip ? `"${t.label}" "${t.tooltip}"` : `"${t.label}"`).join(', ');
+        tagsAttr = ` [tags: ${tagEntries}]`;
+    }
+    // Generate [size: width height] attribute if present
+    let sizeAttr = '';
+    if (instance.config?.width !== undefined && instance.config?.height !== undefined) {
+        sizeAttr = ` [size: ${Math.round(instance.config.width)} ${Math.round(instance.config.height)}]`;
+    }
+    return ` * @node ${instance.id} ${instance.nodeType}${parent}${labelAttr}${portOrderAttr}${portLabelAttr}${exprAttr}${pullExecutionAttr}${minimizedAttr}${colorAttr}${iconAttr}${tagsAttr}${sizeAttr}`;
+}
+export const annotationGenerator = new AnnotationGenerator();
+//# sourceMappingURL=annotation-generator.js.map