@synergenius/flow-weaver 0.21.16 → 0.21.17

package/dist/annotation-generator.d.ts

@@ -28,7 +28,7 @@ export declare class AnnotationGenerator {
  * Reserved STEP ports (execute, onSuccess, onFailure) use @input/@output.
  * Custom STEP ports use @step.
  */
-export declare function generateJSDocPortTag(name: string, port: TPortDefinition, direction: 'input' | 'output', _implicitOrder?: number): string;
+export declare function generateJSDocPortTag(rawName: string, port: TPortDefinition, direction: 'input' | 'output', _implicitOrder?: number): string;
 /**
  * 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

package/dist/annotation-generator.js

@@ -380,7 +380,9 @@ export class AnnotationGenerator {
  * Reserved STEP ports (execute, onSuccess, onFailure) use @input/@output.
  * Custom STEP ports use @step.
  */
-export function generateJSDocPortTag(name, port, direction, _implicitOrder) {
+export function generateJSDocPortTag(rawName, port, direction, _implicitOrder) {
+    // Support scoped key format: use _realName if present (for multi-scope mandatory ports)
+    const name = port._realName ?? rawName;
     // 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

package/dist/ast/types.d.ts

@@ -721,6 +721,8 @@ export type TPortDefinition = {
     order?: number;
     /** Additional metadata */
     metadata?: Record<string, unknown>;
+    /** Internal: real port name when stored under a scoped composite key (multi-scope mandatory ports) */
+    _realName?: string;
 };
 /**
  * Data Type - The type of data a port carries.

package/dist/cli/flow-weaver.mjs

@@ -9671,7 +9671,7 @@ var VERSION;
 var init_generated_version = __esm({
   "src/generated-version.ts"() {
     "use strict";
-    VERSION = "0.21.16";
+    VERSION = "0.21.17";
   }
 });
 
@@ -18434,7 +18434,8 @@ var init_sugar_optimizer = __esm({
 });
 
 // src/annotation-generator.ts
-function generateJSDocPortTag(name, port, direction, _implicitOrder) {
+function generateJSDocPortTag(rawName, port, direction, _implicitOrder) {
+  const name = port._realName ?? rawName;
   const tag = shouldUseStepTag(name, port) ? "step" : direction;
   let portStr = `@${tag} `;
   if (port.optional && port.default !== void 0) {
@@ -93230,7 +93231,7 @@ function displayInstalledPackage(pkg) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.21.16" : "0.0.0-dev";
+var version2 = true ? "0.21.17" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("fw").description("Flow Weaver Annotations - Compile and validate workflow files").option("-v, --version", "Output the current version").option("--no-color", "Disable colors").option("--color", "Force colors").on("option:version", () => {
   logger.banner(version2);

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.21.16";
+export declare const VERSION = "0.21.17";
 //# sourceMappingURL=generated-version.d.ts.map

package/dist/generated-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.ts — do not edit manually
-export const VERSION = '0.21.16';
+export const VERSION = '0.21.17';
 //# sourceMappingURL=generated-version.js.map

package/dist/jsdoc-port-sync/sync.js

@@ -151,47 +151,56 @@ export function syncSignatureToJSDoc(functionText) {
         .map((p) => p.name);
     const signatureInputOrder = rawParamOrder.length >= parsedOrder.length ? rawParamOrder : parsedOrder;
     // ==========================================================================
-    // Auto-generate mandatory scoped ports for declared @scope tags
+    // Auto-generate mandatory scoped ports for all scopes
+    // Collects from both @scope tags AND per-port scope:name annotations
     // ==========================================================================
+    const declaredScopes = new Set();
+    // From @scope tags
     const jsdocMatch = functionText.match(JSDOC_BLOCK_REGEX);
     if (jsdocMatch) {
         const jsdoc = jsdocMatch[0];
-        const declaredScopes = new Set();
         SCOPE_TAG_REGEX.lastIndex = 0;
         let scopeMatch;
         while ((scopeMatch = SCOPE_TAG_REGEX.exec(jsdoc)) != null) {
             declaredScopes.add(scopeMatch[1]);
         }
-        // For each declared scope, ensure mandatory ports exist
-        for (const scopeName of declaredScopes) {
-            // Mandatory OUTPUT: start (STEP)
-            if (!finalOutputs[SCOPED_PORT_NAMES.START] || finalOutputs[SCOPED_PORT_NAMES.START].scope !== scopeName) {
-                // Check if 'start' exists with this scope
-                const hasStart = Object.entries(finalOutputs).some(([name, port]) => name === SCOPED_PORT_NAMES.START && port.scope === scopeName);
-                if (!hasStart) {
-                    finalOutputs[SCOPED_PORT_NAMES.START] = {
-                        dataType: "STEP",
-                        scope: scopeName,
-                    };
-                }
-            }
-            // Mandatory INPUT: success (STEP)
-            const hasSuccess = Object.entries(finalInputs).some(([name, port]) => name === SCOPED_PORT_NAMES.SUCCESS && port.scope === scopeName);
-            if (!hasSuccess) {
-                finalInputs[SCOPED_PORT_NAMES.SUCCESS] = {
-                    dataType: "STEP",
-                    scope: scopeName,
-                };
-            }
-            // Mandatory INPUT: failure (STEP)
-            const hasFailure = Object.entries(finalInputs).some(([name, port]) => name === SCOPED_PORT_NAMES.FAILURE && port.scope === scopeName);
-            if (!hasFailure) {
-                finalInputs[SCOPED_PORT_NAMES.FAILURE] = {
-                    dataType: "STEP",
-                    scope: scopeName,
-                };
-            }
-        }
+    }
+    // From per-port scope annotations, but ONLY when the scope has a matching
+    // callback parameter (confirming it's a real scope, not just a labeled port)
+    for (const port of Object.values(finalInputs)) {
+        if (port.scope && callbackInfo.has(port.scope))
+            declaredScopes.add(port.scope);
+    }
+    for (const port of Object.values(finalOutputs)) {
+        if (port.scope && callbackInfo.has(port.scope))
+            declaredScopes.add(port.scope);
+    }
+    // For each scope, ensure mandatory ports exist.
+    // Port Records use name as key. When multiple scopes need the same mandatory port
+    // (e.g., "start" for scope "a" and "start" for scope "b"), we use a scoped key
+    // format "name\0scope" for the second+ scope. generateJSDocPortTag receives the
+    // real name via the port definition's _realName field.
+    for (const scopeName of declaredScopes) {
+        // Helper: find if mandatory port exists for this specific scope
+        const hasPortForScope = (ports, portName, scope) => Object.entries(ports).some(([name, port]) => (name === portName || port._realName === portName) && port.scope === scope);
+        // Helper: add a mandatory port, using a scoped key if the base key is taken by another scope
+        const addMandatoryPort = (ports, portName, scope, extra) => {
+            if (hasPortForScope(ports, portName, scope))
+                return;
+            // Use base key if available, otherwise use scoped key
+            const key = !ports[portName] || ports[portName].scope === scope
+                ? portName
+                : `${portName}\0${scope}`;
+            ports[key] = {
+                dataType: "STEP",
+                scope,
+                ...(key !== portName && { _realName: portName }),
+                ...extra,
+            };
+        };
+        addMandatoryPort(finalOutputs, SCOPED_PORT_NAMES.START, scopeName);
+        addMandatoryPort(finalInputs, SCOPED_PORT_NAMES.SUCCESS, scopeName);
+        addMandatoryPort(finalInputs, SCOPED_PORT_NAMES.FAILURE, scopeName, { failure: true });
     }
     return updatePortsInFunctionText(functionText, finalInputs, finalOutputs, signatureInputOrder);
 }

package/package.json

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