@synergenius/flow-weaver 0.33.2 → 0.44.0

package/dist/chunks/chunk-VP2P3BPA.js

@@ -0,0 +1,1002 @@
+import {
+  mapToTypeScript
+} from "./chunk-E5WN7IGO.js";
+import {
+  isControlFlowPort,
+  isExecutePort,
+  isFailurePort,
+  isScopedMandatoryPort,
+  isSuccessPort
+} from "./chunk-R4QGNK34.js";
+
+// src/parser/tag-registry.ts
+var TagHandlerRegistry = class {
+  handlers = /* @__PURE__ */ new Map();
+  serializers = /* @__PURE__ */ new Map();
+  /** Register a handler for one or more tag names. */
+  register(tags, namespace, scope, handler) {
+    const entry = { namespace, scope, handler };
+    for (const tag of tags) {
+      this.handlers.set(tag, entry);
+    }
+  }
+  /**
+   * Register (or clear) the serializer for a namespace. Passing `undefined`
+   * removes it, keeping round-trip emission symmetric with parsing.
+   */
+  registerSerializer(namespace, serializer) {
+    if (serializer) {
+      this.serializers.set(namespace, serializer);
+    } else {
+      this.serializers.delete(namespace);
+    }
+  }
+  /**
+   * Serialize a namespace's deploy data back to JSDoc annotation lines.
+   * Returns `[]` when no serializer is registered for the namespace or the
+   * serializer produced nothing.
+   */
+  serialize(namespace, deployData) {
+    const serializer = this.serializers.get(namespace);
+    if (!serializer) return [];
+    return serializer(deployData) ?? [];
+  }
+  /** Check if a handler is registered for the given tag. */
+  has(tagName) {
+    return this.handlers.has(tagName);
+  }
+  /** Get all registered tag names. */
+  getRegisteredTags() {
+    return [...this.handlers.keys()];
+  }
+  /**
+   * Handle a tag by delegating to the registered handler.
+   * The handler writes parsed data into `deployMap[namespace]`.
+   *
+   * @returns true if the tag was handled, false if no handler was found.
+   */
+  handle(tagName, comment, blockScope, deployMap, warnings) {
+    const entry = this.handlers.get(tagName);
+    if (!entry) return false;
+    if (entry.scope !== "both" && entry.scope !== blockScope) {
+      warnings.push(
+        `@${tagName} is registered for ${entry.scope} blocks, not ${blockScope} blocks.`
+      );
+      return true;
+    }
+    if (!deployMap[entry.namespace]) {
+      deployMap[entry.namespace] = {};
+    }
+    entry.handler(tagName, comment, {
+      deploy: deployMap[entry.namespace],
+      warnings
+    });
+    return true;
+  }
+};
+var tagHandlerRegistry = new TagHandlerRegistry();
+
+// src/utils/port-tag-utils.ts
+function shouldUseStepTag(portName, port) {
+  if (port.dataType !== "STEP") return false;
+  const isExternalReserved = isExecutePort(portName) || isSuccessPort(portName) || isFailurePort(portName);
+  if (isExternalReserved) return false;
+  if (port.scope && isScopedMandatoryPort(portName)) return false;
+  return true;
+}
+
+// src/parser/path-data-resolution.ts
+function isPathImpliedDataEdge(fromNode, fromPort, toNode, toPort) {
+  if (fromPort !== toPort) return false;
+  if (isControlFlowPort(fromPort) || isControlFlowPort(toPort)) return false;
+  if (toNode === "Exit" && fromNode === "Start") return false;
+  return true;
+}
+function impliedPathDataEdges(steps, ports) {
+  const edges = [];
+  for (let i = 0; i < steps.length - 1; i++) {
+    edges.push(...impliedPathDataEdgesInto(steps, i + 1, ports));
+  }
+  return edges;
+}
+function impliedPathDataEdgesInto(steps, stepIndex, ports) {
+  const edges = [];
+  const nextId = steps[stepIndex].node;
+  for (const inputName of Object.keys(ports.inputs(nextId))) {
+    if (isControlFlowPort(inputName)) continue;
+    for (let j = stepIndex - 1; j >= 0; j--) {
+      const ancestorId = steps[j].node;
+      if (!(inputName in ports.outputs(ancestorId))) continue;
+      if (isPathImpliedDataEdge(ancestorId, inputName, nextId, inputName)) {
+        edges.push({ from: { node: ancestorId, port: inputName }, to: { node: nextId, port: inputName } });
+      }
+      break;
+    }
+  }
+  return edges;
+}
+function pathDataEdgesSatisfied(steps, ports, connections) {
+  const keys = new Set(connections.map((c) => `${c.from.node}.${c.from.port}->${c.to.node}.${c.to.port}`));
+  const targets = new Set(connections.map((c) => `${c.to.node}.${c.to.port}`));
+  for (const edge of impliedPathDataEdges(steps, ports)) {
+    const key = `${edge.from.node}.${edge.from.port}->${edge.to.node}.${edge.to.port}`;
+    if (keys.has(key)) continue;
+    if (targets.has(`${edge.to.node}.${edge.to.port}`)) continue;
+    return false;
+  }
+  return true;
+}
+
+// src/generator/sugar-optimizer.ts
+function unscopedConnectionKeys(connections) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const conn of connections) {
+    if (!conn.from.scope && !conn.to.scope) {
+      keys.add(`${conn.from.node}.${conn.from.port}->${conn.to.node}.${conn.to.port}`);
+    }
+  }
+  return keys;
+}
+function stepPairEdgeKey(current, next) {
+  if (current.node === "Start") return `Start.execute->${next.node}.execute`;
+  const fromPort = current.route === "fail" ? "onFailure" : "onSuccess";
+  const toPort = next.node === "Exit" ? fromPort : "execute";
+  return `${current.node}.${fromPort}->${next.node}.${toPort}`;
+}
+function pathEdgeKeys(steps) {
+  const keys = [];
+  for (let i = 0; i < steps.length - 1; i++) {
+    keys.push(stepPairEdgeKey(steps[i], steps[i + 1]));
+  }
+  return keys;
+}
+function workflowPortLookup(instances, nodeTypes, startPorts, exitPorts) {
+  const instanceMap = new Map(instances.map((inst) => [inst.id, inst]));
+  const nodeTypeMap = /* @__PURE__ */ new Map();
+  for (const nt of nodeTypes) {
+    nodeTypeMap.set(nt.name, nt);
+    if (nt.functionName !== nt.name) {
+      nodeTypeMap.set(nt.functionName, nt);
+    }
+  }
+  const getNodeType = (nodeId) => {
+    const inst = instanceMap.get(nodeId);
+    if (!inst) return void 0;
+    return nodeTypeMap.get(inst.nodeType);
+  };
+  return {
+    inputs: (nodeId) => nodeId === "Exit" ? exitPorts : getNodeType(nodeId)?.inputs || {},
+    outputs: (nodeId) => nodeId === "Start" ? startPorts : getNodeType(nodeId)?.outputs || {}
+  };
+}
+function validatePathMacro(path, connections, instances, nodeTypes, startPorts, exitPorts) {
+  const instanceIds = new Set(instances.map((inst) => inst.id));
+  for (const step of path.steps) {
+    if (step.node === "Start" || step.node === "Exit") continue;
+    if (!instanceIds.has(step.node)) return false;
+  }
+  const connKeys = unscopedConnectionKeys(connections);
+  if (!pathEdgeKeys(path.steps).every((key) => connKeys.has(key))) {
+    return false;
+  }
+  if (nodeTypes && startPorts && exitPorts) {
+    const ports = workflowPortLookup(instances, nodeTypes, startPorts, exitPorts);
+    const unscoped = connections.filter((c) => !c.from.scope && !c.to.scope);
+    if (!pathDataEdgesSatisfied(path.steps, ports, unscoped)) {
+      return false;
+    }
+  }
+  return true;
+}
+function filterStaleMacros(macros, connections, instances, nodeTypes, startPorts, exitPorts) {
+  const instanceIds = new Set(instances.map((i) => i.id));
+  instanceIds.add("Start");
+  instanceIds.add("Exit");
+  const connKeys = unscopedConnectionKeys(connections);
+  return macros.filter((macro) => {
+    if (macro.type === "path") return validatePathMacro(macro, connections, instances, nodeTypes, startPorts, exitPorts);
+    if (macro.type === "fanOut") {
+      if (!instanceIds.has(macro.source.node)) return false;
+      return macro.targets.every((t) => {
+        if (!instanceIds.has(t.node)) return false;
+        const targetPort = t.port ?? macro.source.port;
+        return connKeys.has(`${macro.source.node}.${macro.source.port}->${t.node}.${targetPort}`);
+      });
+    }
+    if (macro.type === "fanIn") {
+      if (!instanceIds.has(macro.target.node)) return false;
+      return macro.sources.every((s) => {
+        if (!instanceIds.has(s.node)) return false;
+        const sourcePort = s.port ?? macro.target.port;
+        return connKeys.has(`${s.node}.${sourcePort}->${macro.target.node}.${macro.target.port}`);
+      });
+    }
+    if (macro.type === "coerce") {
+      const toCoerce = `${macro.source.node}.${macro.source.port}->${macro.instanceId}.value`;
+      const fromCoerce = `${macro.instanceId}.result->${macro.target.node}.${macro.target.port}`;
+      return connKeys.has(toCoerce) && connKeys.has(fromCoerce);
+    }
+    return true;
+  });
+}
+function detectSugarPatterns(connections, instances, existingMacros, nodeTypes, startPorts, exitPorts) {
+  const coveredByExistingMacro = buildExistingMacroCoverage(existingMacros);
+  const unscopedConns = connections.filter((c) => !c.from.scope && !c.to.scope);
+  const ports = workflowPortLookup(instances, nodeTypes, startPorts, exitPorts);
+  const adj = /* @__PURE__ */ new Map();
+  const multiTargetPorts = /* @__PURE__ */ new Set();
+  for (const conn of unscopedConns) {
+    const { from, to } = conn;
+    let edgeNode;
+    let edgeRoute;
+    if (from.node === "Start" && from.port === "execute" && to.port === "execute") {
+      edgeNode = "Start";
+      edgeRoute = "ok";
+    } else if (to.node === "Exit" && from.port === "onSuccess" && to.port === "onSuccess") {
+      edgeNode = from.node;
+      edgeRoute = "ok";
+    } else if (to.node === "Exit" && from.port === "onFailure" && to.port === "onFailure") {
+      edgeNode = from.node;
+      edgeRoute = "fail";
+    } else if (from.port === "onSuccess" && to.port === "execute") {
+      edgeNode = from.node;
+      edgeRoute = "ok";
+    } else if (from.port === "onFailure" && to.port === "execute") {
+      edgeNode = from.node;
+      edgeRoute = "fail";
+    }
+    if (edgeNode === void 0 || edgeRoute === void 0) continue;
+    const portKey = `${edgeNode}.${edgeRoute}`;
+    if (!adj.has(edgeNode)) {
+      adj.set(edgeNode, {});
+    }
+    const entry = adj.get(edgeNode);
+    if (entry[edgeRoute] !== void 0 && entry[edgeRoute] !== to.node) {
+      multiTargetPorts.add(portKey);
+      delete entry[edgeRoute];
+    } else if (!multiTargetPorts.has(portKey)) {
+      entry[edgeRoute] = to.node;
+    }
+  }
+  const candidateRoutes = [];
+  const MAX_ROUTES = 20;
+  function dfs(node, path, visited) {
+    if (candidateRoutes.length >= MAX_ROUTES) return;
+    if (node === "Exit") {
+      path.push({ node: "Exit" });
+      candidateRoutes.push([...path]);
+      path.pop();
+      return;
+    }
+    if (visited.has(node)) return;
+    visited.add(node);
+    const edges = adj.get(node);
+    if (!edges) {
+      visited.delete(node);
+      return;
+    }
+    if (edges.ok && !coveredByExistingMacro.has(edges.ok === "Exit" ? "" : edges.ok)) {
+      const step = node === "Start" ? { node: "Start" } : { node };
+      path.push(step);
+      dfs(edges.ok, path, visited);
+      path.pop();
+    }
+    if (edges.fail && !coveredByExistingMacro.has(edges.fail === "Exit" ? "" : edges.fail)) {
+      const step = { node, route: "fail" };
+      path.push(step);
+      dfs(edges.fail, path, visited);
+      path.pop();
+    }
+    visited.delete(node);
+  }
+  if (!coveredByExistingMacro.has("Start")) {
+    dfs("Start", [], /* @__PURE__ */ new Set());
+  }
+  const validRoutes = candidateRoutes.filter((route) => {
+    if (route.length < 2) return false;
+    return pathDataEdgesSatisfied(route, ports, unscopedConns);
+  });
+  const allCFEdges = /* @__PURE__ */ new Set();
+  for (const conn of unscopedConns) {
+    if (isControlFlowPort(conn.from.port) || conn.from.port === "execute") {
+      if (isControlFlowPort(conn.to.port) || conn.to.port === "execute") {
+        const portKey = conn.from.node === "Start" ? "Start.ok" : conn.from.port === "onSuccess" ? `${conn.from.node}.ok` : conn.from.port === "onFailure" ? `${conn.from.node}.fail` : null;
+        if (portKey && !multiTargetPorts.has(portKey)) {
+          allCFEdges.add(`${conn.from.node}.${conn.from.port}->${conn.to.node}.${conn.to.port}`);
+        }
+      }
+    }
+  }
+  for (const macro of existingMacros) {
+    if (macro.type === "path") {
+      for (const key of pathEdgeKeys(macro.steps)) allCFEdges.delete(key);
+    }
+  }
+  const sortedRoutes = [...validRoutes].sort((a, b) => b.length - a.length);
+  const selectedPaths = [];
+  const coveredEdges = /* @__PURE__ */ new Set();
+  for (const route of sortedRoutes) {
+    const routeEdges = pathEdgeKeys(route);
+    const newEdges = routeEdges.filter((e) => allCFEdges.has(e) && !coveredEdges.has(e));
+    if (newEdges.length > 0) {
+      selectedPaths.push({
+        type: "path",
+        steps: route.map((s) => s.route ? { node: s.node, route: s.route } : { node: s.node })
+      });
+      for (const e of routeEdges) {
+        coveredEdges.add(e);
+      }
+    }
+  }
+  return { paths: selectedPaths };
+}
+function buildExistingMacroCoverage(macros) {
+  const covered = /* @__PURE__ */ new Set();
+  for (const macro of macros) {
+    if (macro.type === "map") {
+      covered.add(macro.instanceId);
+      covered.add(macro.childId);
+    } else if (macro.type === "path") {
+      for (const step of macro.steps) {
+        covered.add(step.node);
+      }
+    } else if (macro.type === "fanOut") {
+      covered.add(macro.source.node);
+      for (const t of macro.targets) {
+        covered.add(t.node);
+      }
+    } else if (macro.type === "fanIn") {
+      for (const s of macro.sources) {
+        covered.add(s.node);
+      }
+      covered.add(macro.target.node);
+    }
+  }
+  return covered;
+}
+
+// src/parser/serialize-deploy-annotations.ts
+function serializePackDeployAnnotations(deploy) {
+  if (!deploy) return [];
+  const out = [];
+  for (const namespace of Object.keys(deploy).sort()) {
+    const data = deploy[namespace];
+    if (!data || typeof data !== "object") continue;
+    out.push(...tagHandlerRegistry.serialize(namespace, data));
+  }
+  return out;
+}
+
+// src/utils/port-ordering.ts
+function isMandatoryPort(portName, isScoped) {
+  if (isScoped) {
+    return isScopedMandatoryPort(portName);
+  }
+  return isExecutePort(portName) || isSuccessPort(portName) || isFailurePort(portName);
+}
+function assignImplicitPortOrders(ports) {
+  const scopeGroups = /* @__PURE__ */ new Map();
+  for (const [portName, portDef] of Object.entries(ports)) {
+    const scopeKey = portDef.scope;
+    if (!scopeGroups.has(scopeKey)) {
+      scopeGroups.set(scopeKey, []);
+    }
+    scopeGroups.get(scopeKey).push([portName, portDef]);
+  }
+  for (const [scope, portsInScope] of scopeGroups.entries()) {
+    let nextSlot2 = function(from) {
+      while (occupied.has(from)) from++;
+      occupied.add(from);
+      return from;
+    };
+    var nextSlot = nextSlot2;
+    const isScoped = scope !== void 0;
+    const occupied = /* @__PURE__ */ new Set();
+    for (const [, portDef] of portsInScope) {
+      const order = portDef.metadata?.order;
+      if (typeof order === "number") {
+        occupied.add(order);
+      }
+    }
+    const mandatoryNeedOrder = portsInScope.filter(
+      ([name, def]) => isMandatoryPort(name, isScoped) && def.metadata?.order === void 0
+    );
+    const regularNeedOrder = portsInScope.filter(
+      ([name, def]) => !isMandatoryPort(name, isScoped) && def.metadata?.order === void 0
+    );
+    let slot = -mandatoryNeedOrder.length;
+    for (const [, portDef] of mandatoryNeedOrder) {
+      if (!portDef.metadata) portDef.metadata = {};
+      slot = nextSlot2(slot);
+      portDef.metadata.order = slot;
+      slot++;
+    }
+    slot = Math.max(slot, 0);
+    for (const [, portDef] of regularNeedOrder) {
+      if (!portDef.metadata) portDef.metadata = {};
+      slot = nextSlot2(slot);
+      portDef.metadata.order = slot;
+      slot++;
+    }
+  }
+}
+
+// src/generator/annotation-generator.ts
+function formatJSDocDescription(description) {
+  return description.split("\n").map((line) => line.trim().length === 0 ? " *" : ` * ${line}`);
+}
+function httpRouteText(r) {
+  return `${r.method} ${r.path}${r.mode === "async" ? " mode=async" : ""}${r.auth === "none" ? " auth=none" : ""}${r.callback ? " callback" : ""}`;
+}
+var DEFAULT_MANDATORY_LABELS = {
+  execute: "Execute",
+  onSuccess: "On Success",
+  onFailure: "On Failure"
+};
+function isDefaultMandatoryPort(name, port) {
+  const defaultLabel = DEFAULT_MANDATORY_LABELS[name];
+  if (defaultLabel === void 0 || port.scope) return false;
+  if (port.label !== void 0 && port.label !== defaultLabel && port.label !== name) return false;
+  if (port.hidden || port.optional || port.default !== void 0 || port.expression) return false;
+  const metadataKeys = Object.keys(port.metadata ?? {}).filter((key) => key !== "order");
+  return metadataKeys.length === 0;
+}
+function planPortTags(entries) {
+  const inferred = {};
+  for (const [name, port] of entries) {
+    const { order: _order, ...rest } = port.metadata ?? {};
+    inferred[name] = { ...port, metadata: Object.keys(rest).length > 0 ? rest : void 0 };
+  }
+  assignImplicitPortOrders(inferred);
+  return entries.filter(([name, port]) => !isDefaultMandatoryPort(name, port)).map(([name, port]) => ({
+    name,
+    port,
+    writeOrder: port.metadata?.order !== void 0 && port.metadata.order !== inferred[name]?.metadata?.order
+  }));
+}
+var AnnotationGenerator = class {
+  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) => {
+      if (nodeType.variant === "IMPORTED_WORKFLOW" && nodeType.functionName === workflow.functionName) {
+        return;
+      }
+      if (nodeType.variant === "MAP_ITERATOR") {
+        return;
+      }
+      if (nodeType.variant === "COERCION") {
+        return;
+      }
+      if (nodeType.variant === "STUB" && nodeType.inferred) {
+        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 (nodeType.functionText) {
+      lines.push(nodeType.functionText);
+      return lines;
+    }
+    lines.push("/**");
+    if (includeComments && nodeType.description) {
+      lines.push(...formatJSDocDescription(nodeType.description));
+      lines.push(` *`);
+    }
+    const isStub = nodeType.variant === "STUB";
+    if (isStub || nodeType.expression) {
+      lines.push(" * @flowWeaver node");
+    } else {
+      lines.push(" * @flowWeaver nodeType");
+    }
+    if (includeMetadata && nodeType.label) {
+      lines.push(` * @label ${nodeType.label}`);
+    }
+    if (includeMetadata && nodeType.name && nodeType.name !== nodeType.functionName) {
+      lines.push(` * @name ${nodeType.name}`);
+    }
+    if (nodeType.scope) {
+      lines.push(` * @scope ${nodeType.scope}`);
+    }
+    if (nodeType.defaultConfig?.pullExecution) {
+      lines.push(` * @pullExecution ${nodeType.defaultConfig.pullExecution.triggerPort}`);
+    }
+    if (nodeType.resilience) {
+      const retries = nodeType.resilience.retries ? ` retries=${nodeType.resilience.retries}` : "";
+      const fallback = nodeType.resilience.fallback ? ` fallback="${nodeType.resilience.fallback.replace(/"/g, '\\"')}"` : "";
+      lines.push(` * @resilience${retries}${fallback}`);
+    }
+    if (nodeType.durableGate) {
+      lines.push(` * @durableGate ${nodeType.durableGate}`);
+    }
+    if (nodeType.durableEffect) {
+      lines.push(" * @durableEffect");
+    }
+    if (nodeType.durablePure) {
+      lines.push(" * @durablePure");
+    }
+    for (const { name, port, writeOrder } of planPortTags(Object.entries(nodeType.inputs))) {
+      lines.push(` * ${generateJSDocPortTag(name, port, "input", void 0, { writeOrder })}`);
+    }
+    for (const { name, port, writeOrder } of planPortTags(Object.entries(nodeType.outputs))) {
+      lines.push(` * ${generateJSDocPortTag(name, port, "output", void 0, { writeOrder })}`);
+    }
+    lines.push(" */");
+    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 === void 0 && !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 !== void 0) {
+      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) {
+    return generateFunctionSignature(nodeType);
+  }
+  generateWorkflowAnnotation(workflow, indent, includeComments, skipParamReturns = false) {
+    const lines = [];
+    const macroInstanceIds = /* @__PURE__ */ new Set();
+    const macroChildIds = /* @__PURE__ */ new Set();
+    const macroScopeNames = /* @__PURE__ */ new Set();
+    const coerceInstanceIds = /* @__PURE__ */ 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`);
+        } else if (macro.type === "coerce") {
+          coerceInstanceIds.add(macro.instanceId);
+        }
+      }
+    }
+    lines.push("/**");
+    if (includeComments && workflow.description) {
+      lines.push(...formatJSDocDescription(workflow.description));
+      lines.push(` *`);
+    }
+    lines.push(" * @flowWeaver workflow");
+    if (workflow.options?.strictTypes) {
+      lines.push(" * @strictTypes");
+    }
+    if (workflow.options?.autoConnect) {
+      lines.push(" * @autoConnect");
+    }
+    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(" ")}`);
+    }
+    for (const r of workflow.options?.http ?? []) lines.push(` * @http ${httpRouteText(r)}`);
+    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);
+    }
+    if (workflow.options?.retries !== void 0) {
+      lines.push(` * @retries ${workflow.options.retries}`);
+    }
+    if (workflow.options?.timeout) {
+      lines.push(` * @timeout "${workflow.options.timeout}"`);
+    }
+    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);
+    }
+    lines.push(...serializePackDeployAnnotations(workflow.options?.deploy));
+    if (workflow.name && workflow.name !== workflow.functionName) {
+      lines.push(` * @name ${workflow.name}`);
+    }
+    workflow.instances.forEach((instance) => {
+      if (macroInstanceIds.has(instance.id)) return;
+      if (coerceInstanceIds.has(instance.id)) return;
+      if (macroChildIds.has(instance.id) && instance.parent) {
+        const stripped = { ...instance, parent: void 0 };
+        lines.push(generateNodeInstanceTag(stripped));
+      } else {
+        lines.push(generateNodeInstanceTag(instance));
+      }
+    });
+    const authoredConnections = workflow.connections.filter((conn) => !conn.derived);
+    const existingMacros = filterStaleMacros(
+      workflow.macros || [],
+      authoredConnections,
+      workflow.instances,
+      workflow.nodeTypes,
+      workflow.startPorts,
+      workflow.exitPorts
+    );
+    const survivingCoerceIds = /* @__PURE__ */ new Set();
+    for (const macro of existingMacros) {
+      if (macro.type === "coerce") survivingCoerceIds.add(macro.instanceId);
+    }
+    const droppedCoerceIds = /* @__PURE__ */ new Set();
+    for (const id of coerceInstanceIds) {
+      if (!survivingCoerceIds.has(id)) droppedCoerceIds.add(id);
+    }
+    const detected = detectSugarPatterns(
+      authoredConnections,
+      workflow.instances,
+      existingMacros,
+      workflow.nodeTypes,
+      workflow.startPorts,
+      workflow.exitPorts
+    );
+    const allMacros = [
+      ...existingMacros,
+      ...detected.paths
+    ];
+    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}`);
+        } else if (macro.type === "fanOut") {
+          const src = `${macro.source.node}.${macro.source.port}`;
+          const tgts = macro.targets.map((t) => t.port ? `${t.node}.${t.port}` : t.node).join(", ");
+          lines.push(` * @fanOut ${src} -> ${tgts}`);
+        } else if (macro.type === "fanIn") {
+          const srcs = macro.sources.map((s) => s.port ? `${s.node}.${s.port}` : s.node).join(", ");
+          const tgt = `${macro.target.node}.${macro.target.port}`;
+          lines.push(` * @fanIn ${srcs} -> ${tgt}`);
+        } else if (macro.type === "coerce") {
+          const src = `${macro.source.node}.${macro.source.port}`;
+          const tgt = `${macro.target.node}.${macro.target.port}`;
+          lines.push(` * @coerce ${macro.instanceId} ${src} -> ${tgt} as ${macro.targetType}`);
+        }
+      }
+    }
+    if (!workflow.options?.autoConnect) {
+      authoredConnections.forEach((conn) => {
+        if (allMacros.length > 0 && isConnectionCoveredByMacroStatic(conn, allMacros)) return;
+        if (droppedCoerceIds.has(conn.from.node) || droppedCoerceIds.has(conn.to.node)) 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}`);
+      });
+    }
+    if (!skipParamReturns && workflow.startPorts && Object.keys(workflow.startPorts).length > 0) {
+      for (const { name, port, writeOrder } of planPortTags(Object.entries(workflow.startPorts))) {
+        const paramTag = generateJSDocPortTag(name, port, "input", void 0, { writeOrder });
+        lines.push(` * ${paramTag.replace("@input", "@param")}`);
+      }
+    }
+    if (!skipParamReturns && workflow.exitPorts && Object.keys(workflow.exitPorts).length > 0) {
+      for (const { name, port, writeOrder } of planPortTags(Object.entries(workflow.exitPorts))) {
+        const returnTag = generateJSDocPortTag(name, port, "output", void 0, { writeOrder });
+        lines.push(` * ${returnTag.replace("@output", "@returns")}`);
+      }
+    }
+    if (workflow.scopes) {
+      Object.entries(workflow.scopes).forEach(([scopeName, children]) => {
+        if (macroScopeNames.has(scopeName)) return;
+        lines.push(` * @scope ${scopeName} [${children.join(", ")}]`);
+      });
+    }
+    lines.push(" */");
+    lines.push(...this.generateWorkflowFunctionSignature(workflow));
+    return lines;
+  }
+  generateWorkflowFunctionSignature(workflow) {
+    const lines = [];
+    if (workflow.stub) {
+      lines.push(`export const ${workflow.functionName} = 'flowWeaver:draft';`);
+      return lines;
+    }
+    const startPorts = workflow.startPorts || {};
+    const exitPorts = workflow.exitPorts || {};
+    const params = [];
+    Object.entries(startPorts).forEach(([name, port]) => {
+      if (isExecutePort(name)) return;
+      const optional = port.optional ? "?" : "";
+      params.push(`${name}${optional}: ${this.mapDataTypeToTS(port.dataType)}`);
+    });
+    const returns = [];
+    Object.entries(exitPorts).forEach(([name, port]) => {
+      const optional = port.optional ? "?" : "";
+      returns.push(
+        `${name}${optional}: ${this.mapDataTypeToTS(port.dataType)}`
+      );
+    });
+    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);
+  }
+};
+function generateJSDocPortTag(rawName, port, direction, _implicitOrder, options = {}) {
+  const name = port._realName ?? rawName;
+  const tag = shouldUseStepTag(name, port) ? "step" : direction;
+  let portStr = `@${tag} `;
+  if (port.optional && port.default !== void 0) {
+    portStr += `[${name}=${JSON.stringify(port.default)}]`;
+  } else if (port.optional) {
+    portStr += `[${name}]`;
+  } else if (port.default !== void 0) {
+    portStr += `${name}=${JSON.stringify(port.default)}`;
+  } else {
+    portStr += name;
+  }
+  if (port.scope) {
+    portStr += ` scope:${port.scope}`;
+  }
+  if (options.writeOrder !== false && port.metadata?.order !== void 0) {
+    portStr += ` [order:${port.metadata.order}]`;
+  }
+  if (port.metadata?.placement !== void 0) {
+    portStr += ` [placement:${port.metadata.placement}]`;
+  }
+  if (port.expression) {
+    portStr += ` - Expression: ${port.expression}`;
+  } else if (port.label && port.label !== name) {
+    portStr += ` - ${port.label}`;
+  }
+  return portStr;
+}
+function isConnectionCoveredByMacroStatic(conn, macros) {
+  for (const macro of macros) {
+    if (macro.type === "map") {
+      const [sourceNode, sourcePort] = macro.sourcePort.split(".");
+      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;
+      }
+      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;
+      if (toIdx === fromIdx + 1) {
+        const route = steps[fromIdx].route || "ok";
+        if (conn.from.node === "Start" && conn.from.port === "execute" && conn.to.port === "execute") return true;
+        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;
+        }
+        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;
+      }
+      if (isPathImpliedDataEdge(conn.from.node, conn.from.port, conn.to.node, conn.to.port)) {
+        return true;
+      }
+    } else if (macro.type === "fanOut") {
+      if (conn.from.scope || conn.to.scope) continue;
+      if (conn.from.node === macro.source.node && conn.from.port === macro.source.port) {
+        for (const target of macro.targets) {
+          const targetPort = target.port ?? macro.source.port;
+          if (conn.to.node === target.node && conn.to.port === targetPort) {
+            return true;
+          }
+        }
+      }
+    } else if (macro.type === "fanIn") {
+      if (conn.from.scope || conn.to.scope) continue;
+      if (conn.to.node === macro.target.node && conn.to.port === macro.target.port) {
+        for (const source of macro.sources) {
+          const sourcePort = source.port ?? macro.target.port;
+          if (conn.from.node === source.node && conn.from.port === sourcePort) {
+            return true;
+          }
+        }
+      }
+    } else if (macro.type === "coerce") {
+      if (conn.from.scope || conn.to.scope) continue;
+      if (conn.to.node === macro.instanceId || conn.from.node === macro.instanceId) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function assignPortOrders(ports, _direction) {
+  return ports;
+}
+function generateNodeInstanceTag(instance) {
+  const parent = instance.parent ? ` ${instance.parent.id}.${instance.parent.scope}` : "";
+  let labelAttr = "";
+  if (instance.config?.label && instance.config.label !== instance.id) {
+    const escapedLabel = instance.config.label.replace(/"/g, '\\"');
+    labelAttr = ` [label: "${escapedLabel}"]`;
+  }
+  let portOrderAttr = "";
+  if (instance.config?.portConfigs && instance.config.portConfigs.length > 0) {
+    const orderConfigs = instance.config.portConfigs.filter((pc) => pc.order !== void 0).map((pc) => `${pc.portName}=${pc.order}`).join(",");
+    if (orderConfigs) {
+      portOrderAttr = ` [portOrder: ${orderConfigs}]`;
+    }
+  }
+  let portLabelAttr = "";
+  if (instance.config?.portConfigs && instance.config.portConfigs.length > 0) {
+    const labelConfigs = instance.config.portConfigs.filter((pc) => pc.label !== void 0 && pc.label !== "").map((pc) => {
+      const escapedLabel = String(pc.label).replace(/"/g, '\\"');
+      return `${pc.portName}="${escapedLabel}"`;
+    }).join(", ");
+    if (labelConfigs) {
+      portLabelAttr = ` [portLabel: ${labelConfigs}]`;
+    }
+  }
+  let exprAttr = "";
+  if (instance.config?.portConfigs && instance.config.portConfigs.length > 0) {
+    const exprConfigs = instance.config.portConfigs.filter((pc) => pc.expression !== void 0).map((pc) => {
+      const escapedExpr = String(pc.expression).replace(/"/g, '\\"').replace(/\*\//g, "*\\/");
+      return `${pc.portName}="${escapedExpr}"`;
+    }).join(", ");
+    if (exprConfigs) {
+      exprAttr = ` [expr: ${exprConfigs}]`;
+    }
+  }
+  let pullExecutionAttr = "";
+  if (instance.config?.pullExecution) {
+    pullExecutionAttr = ` [pullExecution: ${instance.config.pullExecution.triggerPort}]`;
+  }
+  const minimizedAttr = instance.config?.minimized ? " [minimized]" : "";
+  let colorAttr = "";
+  if (instance.config?.color) {
+    colorAttr = ` [color: "${instance.config.color}"]`;
+  }
+  let iconAttr = "";
+  if (instance.config?.icon) {
+    iconAttr = ` [icon: "${instance.config.icon}"]`;
+  }
+  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}]`;
+  }
+  let suppressAttr = "";
+  if (instance.config?.suppressWarnings?.length) {
+    const codes = instance.config.suppressWarnings.map((c) => `"${c}"`).join(", ");
+    suppressAttr = ` [suppress: ${codes}]`;
+  }
+  let sizeAttr = "";
+  if (instance.config?.width !== void 0 && instance.config?.height !== void 0) {
+    sizeAttr = ` [size: ${Math.round(instance.config.width)} ${Math.round(instance.config.height)}]`;
+  }
+  let customAttrs = "";
+  if (instance.attributes) {
+    for (const key of Object.keys(instance.attributes).sort()) {
+      customAttrs += ` [${key}: "${instance.attributes[key]}"]`;
+    }
+  }
+  return ` * @node ${instance.id} ${instance.nodeType}${parent}${labelAttr}${portOrderAttr}${portLabelAttr}${exprAttr}${pullExecutionAttr}${minimizedAttr}${colorAttr}${iconAttr}${tagsAttr}${suppressAttr}${sizeAttr}${customAttrs}`;
+}
+function generateFunctionSignature(nodeType) {
+  const lines = [];
+  const isStub = nodeType.variant === "STUB";
+  const isExpression = isStub || nodeType.expression;
+  if (isExpression) {
+    const params = [];
+    Object.entries(nodeType.inputs).forEach(([name, port]) => {
+      if (isExecutePort(name)) return;
+      const optional = port.optional ? "?" : "";
+      params.push(`${name}${optional}: ${mapToTypeScript(port.dataType)}`);
+    });
+    const returns = [];
+    Object.entries(nodeType.outputs).forEach(([name, port]) => {
+      if (isSuccessPort(name) || isFailurePort(name)) return;
+      returns.push(`${name}: ${mapToTypeScript(port.dataType)}`);
+    });
+    const returnType = returns.length === 1 ? mapToTypeScript(Object.entries(nodeType.outputs).find(([n]) => !isSuccessPort(n) && !isFailurePort(n))?.[1].dataType || "ANY") : `{ ${returns.join("; ")} }`;
+    if (isStub) {
+      lines.push(`declare function ${nodeType.functionName}(${params.join(", ")}): ${returnType};`);
+    } else {
+      lines.push(`function ${nodeType.functionName}(${params.join(", ")}): ${returnType} {`);
+      lines.push(`  // TODO: implement`);
+      lines.push(`  throw new Error('Not implemented');`);
+      lines.push(`}`);
+    }
+  } else {
+    const params = ["execute: boolean"];
+    Object.entries(nodeType.inputs).forEach(([name, port]) => {
+      if (isExecutePort(name)) return;
+      const optional = port.optional ? "?" : "";
+      const defaultVal = port.default !== void 0 ? ` = ${JSON.stringify(port.default)}` : "";
+      params.push(`${name}${optional}: ${mapToTypeScript(port.dataType)}${defaultVal}`);
+    });
+    const returns = ["onSuccess: boolean", "onFailure: boolean"];
+    Object.entries(nodeType.outputs).forEach(([name, port]) => {
+      if (isSuccessPort(name) || isFailurePort(name)) return;
+      returns.push(`${name}: ${mapToTypeScript(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;
+}
+var annotationGenerator = new AnnotationGenerator();
+
+export {
+  TagHandlerRegistry,
+  tagHandlerRegistry,
+  assignImplicitPortOrders,
+  isPathImpliedDataEdge,
+  impliedPathDataEdgesInto,
+  filterStaleMacros,
+  detectSugarPatterns,
+  serializePackDeployAnnotations,
+  formatJSDocDescription,
+  httpRouteText,
+  planPortTags,
+  AnnotationGenerator,
+  generateJSDocPortTag,
+  assignPortOrders,
+  generateNodeInstanceTag
+};