@synergenius/flow-weaver 0.5.0 → 0.6.0

package/dist/validator.js

@@ -1,6 +1,7 @@
 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';
+import { checkTypeCompatibilityFromStrings } from './type-checker.js';
 export class WorkflowValidator {
     errors = [];
     warnings = [];
@@ -383,12 +384,14 @@ export class WorkflowValidator {
             }
             const sourceType = sourcePortDef.dataType;
             const targetType = targetPortDef.dataType;
+            const sourceTsType = sourcePortDef.tsType;
+            const targetTsType = targetPortDef.tsType;
             // 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}"`,
+                    message: `STEP port "${fromPort}" on node "${fromNode}" cannot connect to non-STEP port "${toPort}" (${this.formatType(targetType, targetTsType)}) on node "${toNode}"`,
                     connection: conn,
                     location: connLocation,
                 });
@@ -398,7 +401,7 @@ export class WorkflowValidator {
                 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}"`,
+                    message: `Non-STEP port "${fromPort}" (${this.formatType(sourceType, sourceTsType)}) on node "${fromNode}" cannot connect to STEP port "${toPort}" on node "${toNode}"`,
                     connection: conn,
                     location: connLocation,
                 });
@@ -412,15 +415,20 @@ export class WorkflowValidator {
             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,
-                        });
+                    const normalizedSource = this.normalizeTypeString(sourcePortDef.tsType);
+                    const normalizedTarget = this.normalizeTypeString(targetPortDef.tsType);
+                    if (normalizedSource !== normalizedTarget) {
+                        // Use string-based compatibility check to suppress false positives (e.g. when one side is 'any')
+                        const compat = checkTypeCompatibilityFromStrings(sourcePortDef.tsType, targetPortDef.tsType);
+                        if (!compat.isCompatible) {
+                            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;
@@ -451,7 +459,7 @@ export class WorkflowValidator {
                     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.`,
+                        message: `Lossy type coercion from ${this.formatType(sourceType, sourceTsType)} to ${this.formatType(targetType, targetTsType)} in connection ${fromNode}.${fromPort} → ${toNode}.${toPort}. ${reason}. Add @strictTypes to your workflow annotation to enforce type safety.`,
                         connection: conn,
                         location: connLocation,
                     }, true);
@@ -474,7 +482,7 @@ export class WorkflowValidator {
                     pushTypeIssue({
                         type: 'warning',
                         code: 'UNUSUAL_TYPE_COERCION',
-                        message: `Unusual type coercion from ${sourceType} to ${targetType} in connection ${fromNode}.${fromPort} → ${toNode}.${toPort}. ${reason}.`,
+                        message: `Unusual type coercion from ${this.formatType(sourceType, sourceTsType)} to ${this.formatType(targetType, targetTsType)} in connection ${fromNode}.${fromPort} → ${toNode}.${toPort}. ${reason}.`,
                         connection: conn,
                         location: connLocation,
                     }, true);
@@ -485,7 +493,7 @@ export class WorkflowValidator {
             pushTypeIssue({
                 type: 'warning',
                 code: 'TYPE_MISMATCH',
-                message: `Type mismatch in connection ${fromNode}.${fromPort} (${sourceType}) → ${toNode}.${toPort} (${targetType}). Runtime coercion will be attempted.`,
+                message: `Type mismatch in connection ${fromNode}.${fromPort} (${this.formatType(sourceType, sourceTsType)}) → ${toNode}.${toPort} (${this.formatType(targetType, targetTsType)}). Runtime coercion will be attempted.`,
                 connection: conn,
                 location: connLocation,
             }, true);
@@ -979,6 +987,31 @@ export class WorkflowValidator {
             }
             if (scopeNames.size === 0)
                 continue;
+            // Check: connections with scope qualifiers must reference valid scope names on this instance
+            for (const conn of workflow.connections) {
+                if (conn.from.scope && conn.from.node === instance.id) {
+                    if (!scopeNames.has(conn.from.scope)) {
+                        this.errors.push({
+                            type: 'error',
+                            code: 'SCOPE_WRONG_SCOPE_NAME',
+                            message: `Connection from "${instance.id}.${conn.from.port}" uses scope qualifier ":${conn.from.scope}" but node "${instance.id}" does not define scope "${conn.from.scope}". Available scopes: ${[...scopeNames].join(', ')}.`,
+                            connection: conn,
+                            location: this.getConnectionLocation(conn),
+                        });
+                    }
+                }
+                if (conn.to.scope && conn.to.node === instance.id) {
+                    if (!scopeNames.has(conn.to.scope)) {
+                        this.errors.push({
+                            type: 'error',
+                            code: 'SCOPE_WRONG_SCOPE_NAME',
+                            message: `Connection to "${instance.id}.${conn.to.port}" uses scope qualifier ":${conn.to.scope}" but node "${instance.id}" does not define scope "${conn.to.scope}". Available scopes: ${[...scopeNames].join(', ')}.`,
+                            connection: conn,
+                            location: this.getConnectionLocation(conn),
+                        });
+                    }
+                }
+            }
             for (const scopeName of scopeNames) {
                 // Find children in this scope
                 const childIds = [];
@@ -996,6 +1029,119 @@ export class WorkflowValidator {
                     (conn.to.scope === scopeName && conn.to.node === instance.id) ||
                     (conn.from.scope === scopeName && childIds.includes(conn.from.node)) ||
                     (conn.to.scope === scopeName && childIds.includes(conn.to.node)));
+                // Check: scoped connections reference actual scoped ports on the parent
+                for (const conn of scopedConnections) {
+                    if (conn.from.node === instance.id && conn.from.scope === scopeName) {
+                        const portDef = nodeType.outputs[conn.from.port];
+                        if (!portDef) {
+                            const availablePorts = Object.entries(nodeType.outputs)
+                                .filter(([, p]) => p.scope === scopeName)
+                                .map(([n]) => n);
+                            this.errors.push({
+                                type: 'error',
+                                code: 'SCOPE_UNKNOWN_PORT',
+                                message: `Scoped connection references non-existent output port "${conn.from.port}" on "${instance.id}" in scope "${scopeName}". Available scoped outputs: ${availablePorts.join(', ') || 'none'}.`,
+                                connection: conn,
+                                location: this.getConnectionLocation(conn),
+                            });
+                        }
+                        else if (portDef.scope !== scopeName) {
+                            this.errors.push({
+                                type: 'error',
+                                code: 'SCOPE_UNKNOWN_PORT',
+                                message: `Output port "${conn.from.port}" on "${instance.id}" is not a scoped port of scope "${scopeName}"${portDef.scope ? ` (it belongs to scope "${portDef.scope}")` : ' (it is an unscoped port)'}.`,
+                                connection: conn,
+                                location: this.getConnectionLocation(conn),
+                            });
+                        }
+                    }
+                    if (conn.to.node === instance.id && conn.to.scope === scopeName) {
+                        const portDef = nodeType.inputs[conn.to.port];
+                        if (!portDef) {
+                            const availablePorts = Object.entries(nodeType.inputs)
+                                .filter(([, p]) => p.scope === scopeName)
+                                .map(([n]) => n);
+                            this.errors.push({
+                                type: 'error',
+                                code: 'SCOPE_UNKNOWN_PORT',
+                                message: `Scoped connection references non-existent input port "${conn.to.port}" on "${instance.id}" in scope "${scopeName}". Available scoped inputs: ${availablePorts.join(', ') || 'none'}.`,
+                                connection: conn,
+                                location: this.getConnectionLocation(conn),
+                            });
+                        }
+                        else if (portDef.scope !== scopeName) {
+                            this.errors.push({
+                                type: 'error',
+                                code: 'SCOPE_UNKNOWN_PORT',
+                                message: `Input port "${conn.to.port}" on "${instance.id}" is not a scoped port of scope "${scopeName}"${portDef.scope ? ` (it belongs to scope "${portDef.scope}")` : ' (it is an unscoped port)'}.`,
+                                connection: conn,
+                                location: this.getConnectionLocation(conn),
+                            });
+                        }
+                    }
+                }
+                // Check: scoped connections must stay within the scope boundary
+                for (const conn of scopedConnections) {
+                    if (conn.from.scope === scopeName && childIds.includes(conn.from.node)) {
+                        if (conn.to.node !== instance.id && !childIds.includes(conn.to.node)) {
+                            this.errors.push({
+                                type: 'error',
+                                code: 'SCOPE_CONNECTION_OUTSIDE',
+                                message: `Scoped connection from "${conn.from.node}.${conn.from.port}" targets "${conn.to.node}" which is not inside scope "${scopeName}" of "${instance.id}".`,
+                                connection: conn,
+                                location: this.getConnectionLocation(conn),
+                            });
+                        }
+                    }
+                    if (conn.to.scope === scopeName && childIds.includes(conn.to.node)) {
+                        if (conn.from.node !== instance.id && !childIds.includes(conn.from.node)) {
+                            this.errors.push({
+                                type: 'error',
+                                code: 'SCOPE_CONNECTION_OUTSIDE',
+                                message: `Scoped connection to "${conn.to.node}.${conn.to.port}" sources from "${conn.from.node}" which is not inside scope "${scopeName}" of "${instance.id}".`,
+                                connection: conn,
+                                location: this.getConnectionLocation(conn),
+                            });
+                        }
+                    }
+                }
+                // Check: type compatibility for scoped connections between parent and children
+                for (const conn of scopedConnections) {
+                    // Parent scoped output -> child input
+                    if (conn.from.node === instance.id && conn.from.scope === scopeName) {
+                        const parentPort = nodeType.outputs[conn.from.port];
+                        const childType = instanceMap.get(conn.to.node);
+                        const childPort = childType?.inputs[conn.to.port];
+                        if (parentPort && childPort && parentPort.dataType !== 'STEP' && childPort.dataType !== 'STEP') {
+                            if (parentPort.dataType !== childPort.dataType && parentPort.dataType !== 'ANY' && childPort.dataType !== 'ANY') {
+                                this.warnings.push({
+                                    type: 'warning',
+                                    code: 'SCOPE_PORT_TYPE_MISMATCH',
+                                    message: `Type mismatch in scope "${scopeName}": "${instance.id}.${conn.from.port}" outputs ${this.formatType(parentPort.dataType, parentPort.tsType)} but "${conn.to.node}.${conn.to.port}" expects ${this.formatType(childPort.dataType, childPort.tsType)}.`,
+                                    connection: conn,
+                                    location: this.getConnectionLocation(conn),
+                                });
+                            }
+                        }
+                    }
+                    // Child output -> parent scoped input
+                    if (conn.to.node === instance.id && conn.to.scope === scopeName) {
+                        const parentPort = nodeType.inputs[conn.to.port];
+                        const childType = instanceMap.get(conn.from.node);
+                        const childPort = childType?.outputs[conn.from.port];
+                        if (parentPort && childPort && parentPort.dataType !== 'STEP' && childPort.dataType !== 'STEP') {
+                            if (parentPort.dataType !== childPort.dataType && parentPort.dataType !== 'ANY' && childPort.dataType !== 'ANY') {
+                                this.warnings.push({
+                                    type: 'warning',
+                                    code: 'SCOPE_PORT_TYPE_MISMATCH',
+                                    message: `Type mismatch in scope "${scopeName}": "${conn.from.node}.${conn.from.port}" outputs ${this.formatType(childPort.dataType, childPort.tsType)} but "${instance.id}.${conn.to.port}" expects ${this.formatType(parentPort.dataType, parentPort.tsType)}.`,
+                                    connection: conn,
+                                    location: this.getConnectionLocation(conn),
+                                });
+                            }
+                        }
+                    }
+                }
                 // Check: each child's required inputs must be satisfied within the scope
                 for (const childId of childIds) {
                     const childType = instanceMap.get(childId);
@@ -1042,9 +1188,37 @@ export class WorkflowValidator {
                         });
                     }
                 }
+                // Check: each child should have at least one scoped connection to/from the parent
+                for (const childId of childIds) {
+                    const hasConnectionFromParent = scopedConnections.some((conn) => conn.from.node === instance.id &&
+                        conn.from.scope === scopeName &&
+                        conn.to.node === childId);
+                    const hasConnectionToParent = scopedConnections.some((conn) => conn.to.node === instance.id &&
+                        conn.to.scope === scopeName &&
+                        conn.from.node === childId);
+                    if (!hasConnectionFromParent && !hasConnectionToParent) {
+                        this.warnings.push({
+                            type: 'warning',
+                            code: 'SCOPE_ORPHANED_CHILD',
+                            message: `Child node "${childId}" is declared inside scope "${scopeName}" of "${instance.id}" but has no scoped connections to or from the parent. It is disconnected from the scope's data flow.`,
+                            node: childId,
+                            location: this.getInstanceLocation(workflow, childId),
+                        });
+                    }
+                }
             }
         }
     }
+    /**
+     * Format a type for display in error messages.
+     * Prefers the structural TypeScript type when available, falling back to the enum name.
+     */
+    formatType(dataType, tsType) {
+        if (tsType) {
+            return `${tsType} (${dataType})`;
+        }
+        return dataType;
+    }
     normalizeTypeString(type) {
         let n = type;
         // Remove all whitespace

package/docs/reference/advanced-annotations.md

@@ -1,7 +1,7 @@
 ---
 name: Advanced Annotations
-description: Pull execution, execution strategies, merge strategies, auto-connect, strict types, path and map sugar, node attributes, and multi-workflow files
-keywords: [pullExecution, executeWhen, mergeStrategy, autoConnect, strictTypes, path, map, sugar, attributes, expr, portOrder, portLabel, minimized, multi-workflow, CONJUNCTION, DISJUNCTION, FIRST, LAST, COLLECT, MERGE, CONCAT]
+description: Pull execution, execution strategies, merge strategies, auto-connect, strict types, path, map, fan-out, fan-in, node attributes, and multi-workflow files
+keywords: [pullExecution, executeWhen, mergeStrategy, autoConnect, strictTypes, path, map, fanOut, fanIn, sugar, attributes, expr, portOrder, portLabel, minimized, multi-workflow, CONJUNCTION, DISJUNCTION, FIRST, LAST, COLLECT, MERGE, CONCAT]
 ---
 
 # Advanced Annotations
@@ -178,6 +178,75 @@ This is equivalent to manually writing:
 
 ---
 
+## Fan-Out / Fan-In (`@fanOut`, `@fanIn`)
+
+Fan macros reduce boilerplate when broadcasting a single output to many targets, or merging many sources into a single input. Both expand to individual `@connect` lines during compilation.
+
+### `@fanOut` — One to Many
+
+Broadcasts a single output port to multiple targets:
+
+```typescript
+/**
+ * @flowWeaver workflow
+ * @node a processA
+ * @node b processB
+ * @node c processC
+ *
+ * @fanOut Start.data -> a, b, c
+ * @connect a.result -> Exit.resultA
+ * @connect b.result -> Exit.resultB
+ * @connect c.result -> Exit.resultC
+ */
+```
+
+This expands to:
+```
+@connect Start.data -> a.data
+@connect Start.data -> b.data
+@connect Start.data -> c.data
+```
+
+You can specify explicit target ports when the names don't match the source:
+
+```
+@fanOut Start.data -> a.input1, b.input2, c.rawData
+```
+
+Without an explicit port, the target port defaults to the source port name.
+
+### `@fanIn` — Many to One
+
+Merges multiple output ports into a single target:
+
+```typescript
+/**
+ * @flowWeaver workflow
+ * @node a processA
+ * @node b processB
+ * @node c processC
+ * @node agg aggregate
+ *
+ * @fanIn a.result, b.result, c.result -> agg.items
+ * @connect agg.merged -> Exit.result
+ */
+```
+
+This expands to:
+```
+@connect a.result -> agg.items
+@connect b.result -> agg.items
+@connect c.result -> agg.items
+```
+
+The target port should have a `[mergeStrategy:COLLECT]` (or another merge strategy) to combine multiple inputs — otherwise the validator will flag `MULTIPLE_CONNECTIONS_TO_INPUT`.
+
+### Round-Trip Preservation
+
+Both macros are preserved through parse-regenerate round-trips. The compiler stores the original macro and regenerates the annotation rather than expanding to individual `@connect` lines.
+
+---
+
 ## Strict Types (`@strictTypes`)
 
 By default, type mismatches between connected ports produce warnings. With `@strictTypes`, they become errors.

package/docs/reference/error-codes.md

@@ -657,6 +657,10 @@ These codes apply to AI agent workflows that use LLM, tool-executor, and memory
 | MISSING_REQUIRED_INPUT | Required input has no connection/default/expression |
 | CYCLE_DETECTED | Graph contains a loop |
 | INVALID_EXIT_PORT_TYPE | Exit onSuccess/onFailure is not STEP type |
+| SCOPE_MISSING_REQUIRED_INPUT | Required input port on a scoped child has no connection |
+| SCOPE_WRONG_SCOPE_NAME | Connection uses a scope name not defined on the node |
+| SCOPE_CONNECTION_OUTSIDE | Scoped connection references a node outside the scope |
+| SCOPE_UNKNOWN_PORT | Connection references a port that is not a scoped port of the specified scope |
 | AGENT_LLM_MISSING_ERROR_HANDLER | LLM node's onFailure port is unconnected |
 <!-- AUTO:END error_summary_table -->
 
@@ -679,6 +683,9 @@ These codes apply to AI agent workflows that use LLM, tool-executor, and memory
 | UNUSED_OUTPUT_PORT | Output port data is discarded |
 | UNREACHABLE_EXIT_PORT | Exit port has no incoming connection |
 | MULTIPLE_EXIT_CONNECTIONS | Exit port has multiple sources |
+| SCOPE_UNUSED_INPUT | Scoped input port has no connection from inner nodes |
+| SCOPE_PORT_TYPE_MISMATCH | Type mismatch between scoped port and connected child port |
+| SCOPE_ORPHANED_CHILD | Child node in scope has no scoped connections to parent |
 | AGENT_UNGUARDED_TOOL_EXECUTOR | Tool executor has no upstream human-approval gate |
 | AGENT_MISSING_MEMORY_IN_LOOP | Loop has LLM but no conversation memory node |
 | AGENT_LLM_NO_FALLBACK | LLM onFailure routes directly to Exit |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",