@synergenius/flow-weaver 0.2.0

package/dist/validator.js

@@ -0,0 +1,970 @@
+import { RESERVED_NODE_NAMES, isStartNode, isExitNode, isExecutePort, isReservedNodeName, } from './constants.js';
+import { findClosestMatches } from './utils/string-distance.js';
+import { parseFunctionSignature } from './jsdoc-port-sync/signature-parser.js';
+export class WorkflowValidator {
+    errors = [];
+    warnings = [];
+    strictMode = false;
+    /** Look up instance sourceLocation by instance ID */
+    getInstanceLocation(workflow, instanceId) {
+        const instance = workflow.instances.find((inst) => inst.id === instanceId);
+        return instance?.sourceLocation;
+    }
+    /** Look up connection sourceLocation */
+    getConnectionLocation(conn) {
+        return conn.sourceLocation;
+    }
+    /**
+     * Validate a single node type for scoped port requirements
+     *
+     * Scoped Port Architecture Rules:
+     * - Scope names must be valid JavaScript identifiers
+     *
+     * Per-Port Scope Architecture:
+     * - Scoped OUTPUT ports become callback PARAMETERS (data flows to children)
+     * - Scoped INPUT ports become callback RETURN VALUES (data flows from children)
+     * - Scoped ports can be ANY data type - they're not functions themselves
+     * - The callback function is passed as a function parameter (e.g., forEach's itemProcessor)
+     *
+     * NOTE: execute/onSuccess/onFailure ports are mandatory base interface ports
+     * that are auto-added to ALL nodes - no validation needed for those.
+     */
+    validateNodeType(nodeType) {
+        const errors = [];
+        // Get all scoped ports (both INPUT and OUTPUT)
+        const scopedPorts = [
+            ...Object.entries(nodeType.inputs).filter(([_, portDef]) => portDef.scope !== undefined),
+            ...Object.entries(nodeType.outputs).filter(([_, portDef]) => portDef.scope !== undefined),
+        ];
+        // Rule: Validate scope names are valid JavaScript identifiers
+        const scopeNameRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+        scopedPorts.forEach(([portName, portDef]) => {
+            if (portDef.scope && !scopeNameRegex.test(portDef.scope)) {
+                errors.push(`Port "${portName}" has invalid scope name "${portDef.scope}". Scope names must be valid JavaScript identifiers (letters, numbers, underscore, dollar sign; cannot start with number).`);
+            }
+        });
+        // Note: Scoped ports can be ANY data type in the per-port scope architecture
+        // They become callback parameters/returns, not functions themselves
+        return errors;
+    }
+    validate(workflow, options) {
+        this.errors = [];
+        this.warnings = [];
+        this.strictMode = options?.strictMode ?? false;
+        const nodeTypeMap = new Map();
+        // Map by both functionName and name to support npm nodes (name='npm/pkg/func', functionName='func')
+        workflow.nodeTypes.forEach((nodeType) => {
+            nodeTypeMap.set(nodeType.functionName, nodeType);
+            if (nodeType.name !== nodeType.functionName) {
+                nodeTypeMap.set(nodeType.name, nodeType);
+            }
+        });
+        // Build instance map: instance ID -> node type
+        const instanceMap = new Map();
+        workflow.instances.forEach((instance) => {
+            // Check both name (for npm nodes like 'npm/pkg/func') and functionName (for local nodes)
+            const nodeType = workflow.nodeTypes.find((nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType);
+            if (nodeType) {
+                instanceMap.set(instance.id, nodeType);
+            }
+            else {
+                // Check if the function exists but is unannotated
+                const isUnannotatedFunction = workflow.availableFunctionNames?.includes(instance.nodeType) ?? false;
+                let hint;
+                if (isUnannotatedFunction) {
+                    hint = ` Function "${instance.nodeType}" exists but has no @flowWeaver nodeType annotation. Add /** @flowWeaver nodeType */ above it.`;
+                }
+                else {
+                    const availableTypes = workflow.nodeTypes.map((nt) => nt.functionName);
+                    const suggestions = findClosestMatches(instance.nodeType, availableTypes);
+                    hint = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                }
+                this.errors.push({
+                    type: 'error',
+                    code: 'UNKNOWN_NODE_TYPE',
+                    message: `Node "${instance.id}" references unknown node type "${instance.nodeType}".${hint}`,
+                    node: instance.id,
+                    location: instance.sourceLocation,
+                });
+            }
+        });
+        // Info diagnostic for auto-inferred node types
+        workflow.instances.forEach((instance) => {
+            // Check both name (for npm nodes like 'npm/pkg/func') and functionName (for local nodes)
+            const nodeType = workflow.nodeTypes.find((nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType);
+            if (nodeType?.inferred) {
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'INFERRED_NODE_TYPE',
+                    message: `Node type "${instance.nodeType}" was auto-inferred from function signature (expression mode). Add @flowWeaver nodeType for explicit port control.`,
+                    node: instance.id,
+                    location: instance.sourceLocation,
+                });
+            }
+        });
+        // Structural validation
+        this.validateStructure(workflow);
+        this.validateDuplicateNodeNames(workflow);
+        this.validateMutableBindings(workflow);
+        // Connection and node validation
+        this.validateReservedNames(workflow, nodeTypeMap);
+        this.validateConnections(workflow, instanceMap);
+        this.validateNodeReferences(workflow, instanceMap);
+        this.validateTypeCompatibility(workflow, instanceMap);
+        this.validateRequiredInputs(workflow, instanceMap);
+        this.detectUnusedNodes(workflow, instanceMap);
+        this.validateStartAndExit(workflow);
+        this.validateDataFlow(workflow, instanceMap);
+        this.validateCycles(workflow);
+        this.validateMultipleInputConnections(workflow, instanceMap);
+        this.validateAnnotationSignatureConsistency(workflow);
+        // Deduplicate cascading errors: if a node has UNKNOWN_NODE_TYPE,
+        // suppress UNKNOWN_SOURCE_NODE, UNKNOWN_TARGET_NODE, and UNDEFINED_NODE
+        // that reference the same node IDs (they're just noise).
+        const unknownTypeInstanceIds = new Set(workflow.instances.filter((inst) => !nodeTypeMap.has(inst.nodeType)).map((inst) => inst.id));
+        if (unknownTypeInstanceIds.size > 0) {
+            this.errors = this.errors.filter((error) => {
+                if (error.code === 'UNKNOWN_NODE_TYPE')
+                    return true; // Always keep root cause
+                // Suppress cascading errors that reference unknown-type instances
+                const cascadingCodes = new Set([
+                    'UNKNOWN_SOURCE_NODE',
+                    'UNKNOWN_TARGET_NODE',
+                    'UNDEFINED_NODE',
+                    'MISSING_REQUIRED_INPUT',
+                ]);
+                if (!cascadingCodes.has(error.code))
+                    return true;
+                // Check if this error references an unknown-type instance
+                if (error.node && unknownTypeInstanceIds.has(error.node))
+                    return false;
+                if (error.connection) {
+                    if (unknownTypeInstanceIds.has(error.connection.from.node))
+                        return false;
+                    if (unknownTypeInstanceIds.has(error.connection.to.node))
+                        return false;
+                }
+                return true;
+            });
+        }
+        return {
+            valid: this.errors.length === 0,
+            errors: this.errors,
+            warnings: this.warnings,
+        };
+    }
+    validateStructure(workflow) {
+        if (!workflow.name) {
+            this.errors.push({
+                type: 'error',
+                code: 'MISSING_WORKFLOW_NAME',
+                message: 'Workflow must have a name',
+            });
+        }
+        if (!workflow.functionName) {
+            this.errors.push({
+                type: 'error',
+                code: 'MISSING_FUNCTION_NAME',
+                message: 'Workflow must have a functionName',
+            });
+        }
+    }
+    validateDuplicateNodeNames(workflow) {
+        const nodeNames = new Set();
+        workflow.nodeTypes.forEach((nodeType) => {
+            if (nodeNames.has(nodeType.functionName)) {
+                this.errors.push({
+                    type: 'error',
+                    code: 'DUPLICATE_NODE_NAME',
+                    message: `Duplicate node type name: "${nodeType.functionName}"`,
+                    node: nodeType.functionName,
+                    location: nodeType.sourceLocation,
+                });
+            }
+            nodeNames.add(nodeType.functionName);
+        });
+    }
+    validateMutableBindings(workflow) {
+        workflow.nodeTypes.forEach((nodeType) => {
+            if (nodeType.declarationKind && nodeType.declarationKind !== 'const') {
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'MUTABLE_NODE_TYPE_BINDING',
+                    message: `Node type "${nodeType.functionName}" is declared with "${nodeType.declarationKind}" instead of "const". Use "const" to prevent accidental reassignment.`,
+                    node: nodeType.functionName,
+                    location: nodeType.sourceLocation,
+                });
+            }
+        });
+    }
+    validateReservedNames(workflow, nodeTypeMap) {
+        // Check for node types with reserved names (Start, Exit)
+        // Note: Port name validation is done during parsing
+        nodeTypeMap.forEach((nodeType, nodeName) => {
+            if (isReservedNodeName(nodeName)) {
+                this.errors.push({
+                    type: 'error',
+                    code: 'RESERVED_NODE_NAME',
+                    message: `Node type name "${nodeName}" is reserved. Reserved node names: ${Object.values(RESERVED_NODE_NAMES).join(', ')}`,
+                    node: nodeName,
+                    location: nodeType.sourceLocation,
+                });
+            }
+        });
+        // Check for instances with reserved IDs
+        workflow.instances.forEach((instance) => {
+            if (isReservedNodeName(instance.id)) {
+                this.errors.push({
+                    type: 'error',
+                    code: 'RESERVED_INSTANCE_ID',
+                    message: `Instance ID "${instance.id}" is reserved. Reserved names: ${Object.values(RESERVED_NODE_NAMES).join(', ')}`,
+                    node: instance.id,
+                    location: instance.sourceLocation,
+                });
+            }
+        });
+    }
+    validateConnections(workflow, instanceMap) {
+        workflow.connections.forEach((conn, _index) => {
+            const fromNode = conn.from.node;
+            const fromPort = conn.from.port;
+            const connLocation = this.getConnectionLocation(conn);
+            if (!isStartNode(fromNode) && !instanceMap.has(fromNode)) {
+                const instanceIds = [...instanceMap.keys()];
+                const suggestions = findClosestMatches(fromNode, instanceIds);
+                const suggestion = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                this.errors.push({
+                    type: 'error',
+                    code: 'UNKNOWN_SOURCE_NODE',
+                    message: `Connection references unknown source node: "${fromNode}"${suggestion}`,
+                    connection: conn,
+                    location: connLocation,
+                });
+            }
+            const toNode = conn.to.node;
+            const toPort = conn.to.port;
+            if (!isExitNode(toNode) && !instanceMap.has(toNode)) {
+                const instanceIds = [...instanceMap.keys()];
+                const suggestions = findClosestMatches(toNode, instanceIds);
+                const suggestion = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                this.errors.push({
+                    type: 'error',
+                    code: 'UNKNOWN_TARGET_NODE',
+                    message: `Connection references unknown target node: "${toNode}"${suggestion}`,
+                    connection: conn,
+                    location: connLocation,
+                });
+            }
+            if (!isStartNode(fromNode)) {
+                const sourceNode = instanceMap.get(fromNode);
+                if (sourceNode && !sourceNode.outputs.hasOwnProperty(fromPort)) {
+                    const portNames = Object.keys(sourceNode.outputs);
+                    const suggestions = findClosestMatches(fromPort, portNames);
+                    const suggestion = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                    this.errors.push({
+                        type: 'error',
+                        code: 'UNKNOWN_SOURCE_PORT',
+                        message: `Node "${fromNode}" does not have output port "${fromPort}"${suggestion}`,
+                        node: fromNode,
+                        connection: conn,
+                        location: connLocation,
+                    });
+                }
+            }
+            else {
+                // Validate Start output port against declared @param ports
+                // 'execute' is always implicit on Start
+                const validStartPorts = new Set(['execute', ...Object.keys(workflow.startPorts)]);
+                if (!validStartPorts.has(fromPort)) {
+                    const portNames = Array.from(validStartPorts);
+                    const suggestions = findClosestMatches(fromPort, portNames);
+                    let hint;
+                    if (suggestions.length > 0) {
+                        hint = ` Did you mean "${suggestions[0]}"?`;
+                    }
+                    else {
+                        hint = `\nAdd '@param ${fromPort}' to the workflow JSDoc and include it in the params object:\n(execute: boolean, params: { ${fromPort}: type, ... })`;
+                    }
+                    this.errors.push({
+                        type: 'error',
+                        code: 'UNKNOWN_SOURCE_PORT',
+                        message: `Start node does not have output port "${fromPort}".${hint}`,
+                        node: fromNode,
+                        connection: conn,
+                        location: connLocation,
+                    });
+                }
+            }
+            if (!isExitNode(toNode)) {
+                const targetNode = instanceMap.get(toNode);
+                if (targetNode && !targetNode.inputs.hasOwnProperty(toPort)) {
+                    const portNames = Object.keys(targetNode.inputs);
+                    const suggestions = findClosestMatches(toPort, portNames);
+                    const suggestion = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                    this.errors.push({
+                        type: 'error',
+                        code: 'UNKNOWN_TARGET_PORT',
+                        message: `Node "${toNode}" does not have input port "${toPort}"${suggestion}`,
+                        node: toNode,
+                        connection: conn,
+                        location: connLocation,
+                    });
+                }
+            }
+            else {
+                // Validate Exit input port against declared @returns ports
+                // 'onSuccess' and 'onFailure' are always implicit on Exit
+                const validExitPorts = new Set([
+                    'onSuccess',
+                    'onFailure',
+                    ...Object.keys(workflow.exitPorts),
+                ]);
+                if (!validExitPorts.has(toPort)) {
+                    const portNames = Array.from(validExitPorts);
+                    const suggestions = findClosestMatches(toPort, portNames);
+                    const suggestion = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                    this.errors.push({
+                        type: 'error',
+                        code: 'UNKNOWN_TARGET_PORT',
+                        message: `Exit node does not have input port "${toPort}"${suggestion}`,
+                        node: toNode,
+                        connection: conn,
+                        location: connLocation,
+                    });
+                }
+            }
+        });
+    }
+    /**
+     * Validate type compatibility for connections with coercion support
+     *
+     * Type coercion rules:
+     * - ANY type connections always allowed (no warning)
+     * - Safe coercions: NUMBER → STRING, BOOLEAN → STRING (no warning)
+     * - Lossy coercions: STRING → NUMBER, STRING → BOOLEAN, OBJECT → STRING (warning or error in strict mode)
+     * - Unusual coercions: NUMBER → BOOLEAN, BOOLEAN → NUMBER (warning or error in strict mode)
+     * - Same type connections always allowed (no warning)
+     *
+     * Strict types mode (@strictTypes):
+     * - When enabled, type incompatibilities are errors instead of warnings
+     */
+    validateTypeCompatibility(workflow, instanceMap) {
+        const strictTypes = this.strictMode || workflow.options?.strictTypes === true;
+        // Helper to push to errors or warnings based on strictTypes mode
+        const pushTypeIssue = (issue, isIncompatible = false) => {
+            if (strictTypes && isIncompatible) {
+                this.errors.push({ ...issue, type: 'error', code: 'TYPE_INCOMPATIBLE' });
+            }
+            else {
+                this.warnings.push(issue);
+            }
+        };
+        workflow.connections.forEach((conn) => {
+            const fromNode = conn.from.node;
+            const fromPort = conn.from.port;
+            const toNode = conn.to.node;
+            const toPort = conn.to.port;
+            const connLocation = this.getConnectionLocation(conn);
+            // Skip Start and Exit nodes (they handle types dynamically)
+            if (isStartNode(fromNode) || isExitNode(toNode)) {
+                return;
+            }
+            // Get source and target port types
+            const sourceNode = instanceMap.get(fromNode);
+            const targetNode = instanceMap.get(toNode);
+            if (!sourceNode || !targetNode) {
+                return; // Already caught by validateConnections
+            }
+            const sourcePortDef = sourceNode.outputs[fromPort];
+            const targetPortDef = targetNode.inputs[toPort];
+            if (!sourcePortDef || !targetPortDef) {
+                return; // Already caught by validateConnections
+            }
+            const sourceType = sourcePortDef.dataType;
+            const targetType = targetPortDef.dataType;
+            // Validate STEP port connections - STEP must connect to STEP only
+            if (sourceType === 'STEP' && targetType !== 'STEP') {
+                this.errors.push({
+                    type: 'error',
+                    code: 'STEP_PORT_TYPE_MISMATCH',
+                    message: `STEP port "${fromPort}" on node "${fromNode}" cannot connect to non-STEP port "${toPort}" (${targetType}) on node "${toNode}"`,
+                    connection: conn,
+                    location: connLocation,
+                });
+                return;
+            }
+            if (targetType === 'STEP' && sourceType !== 'STEP') {
+                this.errors.push({
+                    type: 'error',
+                    code: 'STEP_PORT_TYPE_MISMATCH',
+                    message: `Non-STEP port "${fromPort}" (${sourceType}) on node "${fromNode}" cannot connect to STEP port "${toPort}" on node "${toNode}"`,
+                    connection: conn,
+                    location: connLocation,
+                });
+                return;
+            }
+            // Skip further type checking for STEP-to-STEP (valid control flow)
+            if (sourceType === 'STEP' && targetType === 'STEP') {
+                return;
+            }
+            // Same type - check for structural compatibility if both are OBJECT
+            if (sourceType === targetType) {
+                // For OBJECT types, check if tsType differs (structural mismatch)
+                if (sourceType === 'OBJECT' && sourcePortDef.tsType && targetPortDef.tsType) {
+                    // If both have tsType and they differ (after normalization), warn about potential mismatch
+                    if (this.normalizeTypeString(sourcePortDef.tsType) !== this.normalizeTypeString(targetPortDef.tsType)) {
+                        this.warnings.push({
+                            type: 'warning',
+                            code: 'OBJECT_TYPE_MISMATCH',
+                            message: `Structural type mismatch: ${fromNode}.${fromPort} outputs "${sourcePortDef.tsType}" but ${toNode}.${toPort} expects "${targetPortDef.tsType}". Verify the object shapes are compatible.`,
+                            connection: conn,
+                            location: connLocation,
+                        });
+                    }
+                }
+                return;
+            }
+            // ANY type - always compatible (no warning)
+            if (sourceType === 'ANY' || targetType === 'ANY') {
+                return;
+            }
+            // Safe coercions (no warning)
+            const safeCoercions = [
+                ['NUMBER', 'STRING'],
+                ['BOOLEAN', 'STRING'],
+            ];
+            for (const [from, to] of safeCoercions) {
+                if (sourceType === from && targetType === to) {
+                    return; // Safe coercion, no warning
+                }
+            }
+            // Lossy coercions (warning)
+            const lossyCoercions = [
+                ['STRING', 'NUMBER', 'May result in NaN if string is not a valid number'],
+                ['STRING', 'BOOLEAN', 'Will use JavaScript truthy/falsy conversion'],
+                ['OBJECT', 'STRING', 'Will use JSON.stringify()'],
+                ['ARRAY', 'STRING', 'Will use JSON.stringify()'],
+            ];
+            for (const [from, to, reason] of lossyCoercions) {
+                if (sourceType === from && targetType === to) {
+                    pushTypeIssue({
+                        type: 'warning',
+                        code: 'LOSSY_TYPE_COERCION',
+                        message: `Lossy type coercion from ${sourceType} to ${targetType} in connection ${fromNode}.${fromPort} → ${toNode}.${toPort}. ${reason}. Add @strictTypes to your workflow annotation to enforce type safety.`,
+                        connection: conn,
+                        location: connLocation,
+                    }, true);
+                    return;
+                }
+            }
+            // Unusual coercions (warning)
+            const unusualCoercions = [
+                [
+                    'NUMBER',
+                    'BOOLEAN',
+                    'Will use JavaScript truthy/falsy conversion (0 = false, non-zero = true)',
+                ],
+                ['BOOLEAN', 'NUMBER', 'Will convert false to 0, true to 1'],
+                ['STRING', 'OBJECT', 'May fail if string is not valid JSON'],
+                ['STRING', 'ARRAY', 'May fail if string is not valid JSON array'],
+            ];
+            for (const [from, to, reason] of unusualCoercions) {
+                if (sourceType === from && targetType === to) {
+                    pushTypeIssue({
+                        type: 'warning',
+                        code: 'UNUSUAL_TYPE_COERCION',
+                        message: `Unusual type coercion from ${sourceType} to ${targetType} in connection ${fromNode}.${fromPort} → ${toNode}.${toPort}. ${reason}.`,
+                        connection: conn,
+                        location: connLocation,
+                    }, true);
+                    return;
+                }
+            }
+            // All other type mismatches
+            pushTypeIssue({
+                type: 'warning',
+                code: 'TYPE_MISMATCH',
+                message: `Type mismatch in connection ${fromNode}.${fromPort} (${sourceType}) → ${toNode}.${toPort} (${targetType}). Runtime coercion will be attempted.`,
+                connection: conn,
+                location: connLocation,
+            }, true);
+        });
+    }
+    validateNodeReferences(workflow, instanceMap) {
+        const referencedNodes = new Set();
+        workflow.connections.forEach((conn) => {
+            const fromNode = conn.from.node;
+            const toNode = conn.to.node;
+            if (!isStartNode(fromNode) && !isExitNode(fromNode)) {
+                referencedNodes.add(fromNode);
+            }
+            if (!isStartNode(toNode) && !isExitNode(toNode)) {
+                referencedNodes.add(toNode);
+            }
+        });
+        referencedNodes.forEach((nodeName) => {
+            if (!instanceMap.has(nodeName)) {
+                this.errors.push({
+                    type: 'error',
+                    code: 'UNDEFINED_NODE',
+                    message: `Workflow references undefined node: "${nodeName}"`,
+                    node: nodeName,
+                });
+            }
+        });
+    }
+    validateRequiredInputs(workflow, instanceMap) {
+        instanceMap.forEach((nodeType, instanceId) => {
+            // Find the instance to check for port-level constant expressions
+            const instance = workflow.instances.find((inst) => inst.id === instanceId);
+            Object.entries(nodeType.inputs).forEach(([portName, portConfig]) => {
+                if (isExecutePort(portName))
+                    return;
+                // Skip scoped INPUT ports - they're provided by scope function execution, not external connections
+                if (portConfig.scope)
+                    return;
+                // Check if instance has an expression for this port
+                const instancePortConfig = instance?.config?.portConfigs?.find((pc) => pc.portName === portName && (pc.direction == null || pc.direction === 'INPUT'));
+                const hasInstanceExpression = instancePortConfig?.expression !== undefined;
+                const isRequired = !portConfig.optional &&
+                    portConfig.default === undefined &&
+                    !portConfig.expression &&
+                    !hasInstanceExpression;
+                if (isRequired) {
+                    const isConnected = workflow.connections.some((conn) => {
+                        return conn.to.node === instanceId && conn.to.port === portName;
+                    });
+                    if (!isConnected) {
+                        this.errors.push({
+                            type: 'error',
+                            code: 'MISSING_REQUIRED_INPUT',
+                            message: `Node "${instanceId}" has unconnected required input port "${portName}". Connect a value to it, or mark it optional with @input [${portName}].`,
+                            node: instanceId,
+                            location: instance?.sourceLocation,
+                        });
+                    }
+                }
+            });
+        });
+    }
+    detectUnusedNodes(workflow, instanceMap) {
+        const usedNodes = new Set();
+        workflow.connections.forEach((conn) => {
+            const fromNode = conn.from.node;
+            const toNode = conn.to.node;
+            if (!isStartNode(fromNode) && !isExitNode(fromNode)) {
+                usedNodes.add(fromNode);
+            }
+            if (!isStartNode(toNode) && !isExitNode(toNode)) {
+                usedNodes.add(toNode);
+            }
+        });
+        instanceMap.forEach((_nodeType, instanceId) => {
+            if (!usedNodes.has(instanceId)) {
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'UNUSED_NODE',
+                    message: `Node "${instanceId}" is defined but never used in workflow`,
+                    node: instanceId,
+                    location: this.getInstanceLocation(workflow, instanceId),
+                });
+            }
+        });
+    }
+    validateStartAndExit(workflow) {
+        const hasStartConnections = workflow.connections.some((conn) => {
+            return isStartNode(conn.from.node);
+        });
+        if (!hasStartConnections) {
+            this.warnings.push({
+                type: 'warning',
+                code: 'NO_START_CONNECTIONS',
+                message: 'Workflow has no connections from Start node',
+            });
+        }
+        const hasExitConnections = workflow.connections.some((conn) => {
+            return isExitNode(conn.to.node);
+        });
+        if (!hasExitConnections) {
+            this.warnings.push({
+                type: 'warning',
+                code: 'NO_EXIT_CONNECTIONS',
+                message: 'Workflow has no connections to Exit node (no return value)',
+            });
+        }
+        // Validate that onSuccess and onFailure exit ports are STEP type
+        if (workflow.exitPorts.onSuccess) {
+            if (workflow.exitPorts.onSuccess.dataType !== 'STEP') {
+                this.errors.push({
+                    type: 'error',
+                    code: 'INVALID_EXIT_PORT_TYPE',
+                    message: "Exit port 'onSuccess' must be of type STEP (control flow), found: " +
+                        workflow.exitPorts.onSuccess.dataType,
+                });
+            }
+        }
+        if (workflow.exitPorts.onFailure) {
+            if (workflow.exitPorts.onFailure.dataType !== 'STEP') {
+                this.errors.push({
+                    type: 'error',
+                    code: 'INVALID_EXIT_PORT_TYPE',
+                    message: "Exit port 'onFailure' must be of type STEP (control flow), found: " +
+                        workflow.exitPorts.onFailure.dataType,
+                });
+            }
+        }
+    }
+    /**
+     * Validate data flow in the workflow
+     *
+     * Checks for:
+     * - Unused output ports (data produced but never consumed)
+     * - Unreachable Exit ports (Exit expects data but no connection provides it)
+     * - Dead-end data paths (data that never reaches Exit)
+     */
+    validateDataFlow(workflow, instanceMap) {
+        // Track which output ports are connected
+        const connectedOutputPorts = new Set();
+        workflow.connections.forEach((conn) => {
+            const portKey = `${conn.from.node}.${conn.from.port}`;
+            connectedOutputPorts.add(portKey);
+        });
+        // Check for unused output ports (excluding control flow ports and scoped ports)
+        instanceMap.forEach((nodeType, instanceId) => {
+            Object.keys(nodeType.outputs).forEach((portName) => {
+                const portKey = `${instanceId}.${portName}`;
+                const portDef = nodeType.outputs[portName];
+                // Skip control flow ports (onSuccess, onFailure)
+                if (portDef.isControlFlow || portDef.failure) {
+                    return;
+                }
+                // Skip scoped output ports - they flow through the scope function, not external connections
+                if (portDef.scope) {
+                    return;
+                }
+                if (!connectedOutputPorts.has(portKey)) {
+                    this.warnings.push({
+                        type: 'warning',
+                        code: 'UNUSED_OUTPUT_PORT',
+                        message: `Output port "${portName}" of node "${instanceId}" is never connected. Data will be discarded.`,
+                        node: instanceId,
+                        location: this.getInstanceLocation(workflow, instanceId),
+                    });
+                }
+            });
+        });
+        // Check for unreachable Exit ports and multiple connections to same Exit port
+        // Build a map of Exit ports to their incoming connections
+        const exitPortConnections = new Map();
+        workflow.connections.forEach((conn) => {
+            if (isExitNode(conn.to.node)) {
+                const port = conn.to.port;
+                if (!exitPortConnections.has(port)) {
+                    exitPortConnections.set(port, []);
+                }
+                exitPortConnections.get(port).push(conn);
+            }
+        });
+        // Check if all Exit ports have connections
+        Object.entries(workflow.exitPorts).forEach(([portName, portDef]) => {
+            // Skip control flow ports
+            if (portDef.isControlFlow) {
+                return;
+            }
+            if (!exitPortConnections.has(portName)) {
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'UNREACHABLE_EXIT_PORT',
+                    message: `Exit port "${portName}" has no incoming connection. Return value will be undefined.`,
+                });
+            }
+        });
+        // Check for multiple connections to the same Exit port
+        exitPortConnections.forEach((connections, portName) => {
+            if (connections.length > 1) {
+                const sourceNodes = connections.map((c) => c.from.node);
+                if (this.areMutuallyExclusive(sourceNodes, workflow, instanceMap)) {
+                    return; // Suppress — mutually exclusive branches
+                }
+                const sources = connections.map((c) => `${c.from.node}.${c.from.port}`).join(', ');
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'MULTIPLE_EXIT_CONNECTIONS',
+                    message: `Exit port "${portName}" has ${connections.length} incoming connections (${sources}). Only one value will be used - consider using separate Exit ports.`,
+                });
+            }
+        });
+    }
+    /**
+     * Validate for cycles (loops) in the workflow graph.
+     * Cycles are connections that form a loop back to an earlier node.
+     * Scoped nodes handle loops internally, so cycles within same scope are checked.
+     */
+    validateCycles(workflow) {
+        // Group instances by parent (scope layer)
+        const instancesByParent = new Map();
+        instancesByParent.set(null, []);
+        for (const instance of workflow.instances) {
+            const parentId = instance.parent?.id || null;
+            if (!instancesByParent.has(parentId)) {
+                instancesByParent.set(parentId, []);
+            }
+            instancesByParent.get(parentId).push(instance);
+        }
+        // Group connections by parent (only connections where both ends are in same scope)
+        const connectionsByParent = new Map();
+        connectionsByParent.set(null, []);
+        for (const connection of workflow.connections) {
+            const sourceInstance = workflow.instances.find((n) => n.id === connection.from.node);
+            const targetInstance = workflow.instances.find((n) => n.id === connection.to.node);
+            // Skip connections involving Start/Exit (they're virtual)
+            if (!sourceInstance || !targetInstance)
+                continue;
+            const sourceParent = sourceInstance.parent?.id || null;
+            const targetParent = targetInstance.parent?.id || null;
+            // Only check connections within the same scope
+            if (sourceParent === targetParent) {
+                if (!connectionsByParent.has(sourceParent)) {
+                    connectionsByParent.set(sourceParent, []);
+                }
+                connectionsByParent.get(sourceParent).push(connection);
+            }
+        }
+        // Run cycle detection per scope layer
+        for (const [parentId, instances] of instancesByParent.entries()) {
+            const connections = connectionsByParent.get(parentId) || [];
+            this.detectCyclesInLayer(parentId, instances, connections);
+        }
+    }
+    detectCyclesInLayer(parentId, instances, connections) {
+        const visited = new Set();
+        const recursionStack = new Set();
+        const reportedCycles = new Set(); // Track reported cycles to avoid duplicates
+        // Self-loops are allowed (used for iteration patterns)
+        const selfLoopNodes = new Set(connections.filter((c) => c.from.node === c.to.node).map((c) => c.from.node));
+        // Exclude self-loops from cycle detection
+        const nonSelfLoopConnections = connections.filter((c) => c.from.node !== c.to.node);
+        const dfs = (nodeName, path) => {
+            if (recursionStack.has(nodeName)) {
+                // Node with self-loop is not considered a cycle entry point
+                if (selfLoopNodes.has(nodeName)) {
+                    return false;
+                }
+                const cycleStart = path.indexOf(nodeName);
+                const cyclePath = [...path.slice(cycleStart), nodeName];
+                // Normalize cycle for deduplication (start from smallest node name)
+                const cycleNodes = cyclePath.slice(0, -1); // Remove duplicate end node
+                const sortedCycle = [...cycleNodes].sort();
+                const cycleKey = sortedCycle.join(',');
+                // Only report if not already reported
+                if (!reportedCycles.has(cycleKey)) {
+                    reportedCycles.add(cycleKey);
+                    const parentContext = parentId ? ` in scope "${parentId}"` : '';
+                    const instance = instances.find((n) => n.id === nodeName);
+                    this.errors.push({
+                        type: 'error',
+                        code: 'CYCLE_DETECTED',
+                        message: `Loop detected${parentContext}: ${cyclePath.join(' -> ')}`,
+                        node: nodeName,
+                        location: instance?.sourceLocation,
+                    });
+                }
+                return true;
+            }
+            if (visited.has(nodeName)) {
+                return false;
+            }
+            recursionStack.add(nodeName);
+            const newPath = [...path, nodeName];
+            const instance = instances.find((n) => n.id === nodeName);
+            if (!instance) {
+                recursionStack.delete(nodeName);
+                return false;
+            }
+            const outgoing = nonSelfLoopConnections.filter((c) => c.from.node === nodeName);
+            let hasCycle = false;
+            for (const conn of outgoing) {
+                if (dfs(conn.to.node, newPath)) {
+                    hasCycle = true;
+                }
+            }
+            recursionStack.delete(nodeName);
+            if (!hasCycle) {
+                visited.add(nodeName);
+            }
+            return hasCycle;
+        };
+        // Run DFS from each node (but use shared visited/reportedCycles sets)
+        for (const instance of instances) {
+            if (!visited.has(instance.id)) {
+                dfs(instance.id, []);
+            }
+        }
+    }
+    /**
+     * Validate that no input port has multiple connections.
+     * Only one value can be received per input port.
+     * (STEP ports can have multiple connections as they're control flow)
+     */
+    validateMultipleInputConnections(workflow, instanceMap) {
+        const inputConnections = new Map();
+        for (const conn of workflow.connections) {
+            const targetKey = `${conn.to.node}.${conn.to.port}`;
+            // Skip Exit node (handled separately in validateDataFlow)
+            if (isExitNode(conn.to.node))
+                continue;
+            // Get target port type to check if it's STEP or has mergeStrategy
+            const targetNodeType = instanceMap.get(conn.to.node);
+            if (targetNodeType) {
+                const targetPortDef = targetNodeType.inputs[conn.to.port];
+                // STEP ports can have multiple connections (control flow)
+                if (targetPortDef?.dataType === 'STEP')
+                    continue;
+                // Ports with mergeStrategy can have multiple connections (fan-in)
+                if (targetPortDef?.mergeStrategy)
+                    continue;
+            }
+            if (!inputConnections.has(targetKey)) {
+                inputConnections.set(targetKey, []);
+            }
+            inputConnections.get(targetKey).push(conn);
+        }
+        for (const [, connections] of inputConnections) {
+            if (connections.length > 1) {
+                const [firstConn] = connections;
+                const sources = connections.map((c) => `${c.from.node}.${c.from.port}`).join(', ');
+                this.errors.push({
+                    type: 'error',
+                    code: 'MULTIPLE_CONNECTIONS_TO_INPUT',
+                    message: `Input port "${firstConn.to.port}" on node "${firstConn.to.node}" has ${connections.length} connections (${sources}). Only one value can be received.`,
+                    node: firstConn.to.node,
+                    connection: firstConn,
+                    location: this.getConnectionLocation(firstConn),
+                });
+            }
+        }
+    }
+    /**
+     * Cross-check @input annotations against TypeScript function signatures.
+     * Warns on optionality and type mismatches between annotations and actual code.
+     */
+    validateAnnotationSignatureConsistency(workflow) {
+        for (const nodeType of workflow.nodeTypes) {
+            if (!nodeType.functionText)
+                continue;
+            let sigParams;
+            try {
+                const sig = parseFunctionSignature(nodeType.functionText);
+                sigParams = sig.params;
+            }
+            catch {
+                continue; // Can't parse signature, skip
+            }
+            // Skip the first param (execute: boolean) - it's a control flow param
+            const sigParamMap = new Map();
+            for (const p of sigParams.slice(1)) {
+                sigParamMap.set(p.name, p);
+            }
+            for (const [portName, portDef] of Object.entries(nodeType.inputs)) {
+                if (portName === 'execute')
+                    continue; // Skip control flow port
+                const sigParam = sigParamMap.get(portName);
+                if (!sigParam)
+                    continue; // Port not in signature (may be added by framework)
+                // Check optionality mismatch: annotation says required but sig says optional
+                if (!portDef.optional && sigParam.optional) {
+                    this.warnings.push({
+                        type: 'warning',
+                        code: 'ANNOTATION_SIGNATURE_MISMATCH',
+                        message: `Port "${portName}" in node type "${nodeType.functionName}" is optional in signature but required in annotation. Consider using @input [${portName}] to mark it optional.`,
+                        node: nodeType.functionName,
+                        location: nodeType.sourceLocation,
+                    });
+                }
+                // Check type mismatch: annotation specifies a type that differs from signature
+                if (portDef.tsType && sigParam.tsType) {
+                    const annotationType = this.normalizeTypeString(portDef.tsType);
+                    const signatureType = this.normalizeTypeString(sigParam.tsType);
+                    // Skip if no real type info (untyped JS)
+                    if (!signatureType || signatureType === 'any')
+                        continue;
+                    if (annotationType !== signatureType) {
+                        this.warnings.push({
+                            type: 'warning',
+                            code: 'ANNOTATION_SIGNATURE_TYPE_MISMATCH',
+                            message: `Port "${portName}" in node type "${nodeType.functionName}" has type "${portDef.tsType}" in annotation but "${sigParam.tsType}" in function signature.`,
+                            node: nodeType.functionName,
+                            location: nodeType.sourceLocation,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Check if a set of source nodes are mutually exclusive — i.e., they descend
+     * from opposite branches (onSuccess vs onFailure) of the same branching node.
+     */
+    areMutuallyExclusive(sourceNodes, workflow, instanceMap) {
+        if (sourceNodes.length < 2)
+            return false;
+        // Build reverse connection map: targetNode -> [{fromNode, fromPort}]
+        const reverseMap = new Map();
+        for (const conn of workflow.connections) {
+            if (!reverseMap.has(conn.to.node)) {
+                reverseMap.set(conn.to.node, []);
+            }
+            reverseMap.get(conn.to.node).push({ fromNode: conn.from.node, fromPort: conn.from.port });
+        }
+        const findBranchAncestor = (nodeId) => {
+            const visited = new Set();
+            const queue = [nodeId];
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (visited.has(current))
+                    continue;
+                visited.add(current);
+                const incomingEdges = reverseMap.get(current);
+                if (!incomingEdges)
+                    continue;
+                for (const edge of incomingEdges) {
+                    // Check if this incoming edge is from a branching port
+                    if (edge.fromPort === 'onSuccess' || edge.fromPort === 'onFailure') {
+                        const parentNodeType = instanceMap.get(edge.fromNode);
+                        if (parentNodeType?.hasSuccessPort && parentNodeType?.hasFailurePort) {
+                            return { branchNode: edge.fromNode, branch: edge.fromPort };
+                        }
+                    }
+                    queue.push(edge.fromNode);
+                }
+            }
+            return null;
+        };
+        // Get branch info for all source nodes
+        const branchInfos = sourceNodes.map(findBranchAncestor);
+        // All must have a branch ancestor
+        if (branchInfos.some((info) => info === null))
+            return false;
+        // All must share the same branch node
+        const branchNode = branchInfos[0].branchNode;
+        if (!branchInfos.every((info) => info.branchNode === branchNode))
+            return false;
+        // They must be on different branches (not all on the same one)
+        const branches = new Set(branchInfos.map((info) => info.branch));
+        return branches.size > 1;
+    }
+    normalizeTypeString(type) {
+        let n = type;
+        // Remove all whitespace
+        n = n.replace(/\s+/g, '');
+        // Normalize Array<T> → T[]
+        n = n.replace(/Array<(.+?)>/g, '$1[]');
+        // Remove trailing semicolons before closing braces/brackets
+        n = n.replace(/;(?=[}\]])/g, '');
+        // Lowercase for case-insensitive compare
+        n = n.toLowerCase();
+        return n;
+    }
+}
+export const validator = new WorkflowValidator();
+//# sourceMappingURL=validator.js.map