@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/cli/flow-weaver-chunk-BHCC5FE5.mjs

@@ -0,0 +1,17 @@
+import { createRequire as __createRequire } from "module";
+const require = __createRequire(import.meta.url);
+
+// src/generated-branding.ts
+var WEBSITE_URL = "https://github.com/synergenius-fw/flow-weaver";
+var DEFAULT = {
+  header: (cmd) => cmd ? `// Generated by Flow Weaver (${WEBSITE_URL}): ${cmd}` : `// Generated by Flow Weaver (${WEBSITE_URL})`,
+  markdown: `*Generated by [Flow Weaver](${WEBSITE_URL})*`
+};
+var _branding = DEFAULT;
+function getGeneratedBranding() {
+  return _branding;
+}
+
+export {
+  getGeneratedBranding
+};

package/dist/cli/flow-weaver-chunk-DM4BBRRU.mjs

@@ -0,0 +1,35 @@
+import { createRequire as __createRequire } from "module";
+const require = __createRequire(import.meta.url);
+
+// src/validation/rule-registry.ts
+var ValidationRuleRegistry = class {
+  ruleSets = [];
+  /** Register a validation rule set. */
+  register(ruleSet) {
+    this.ruleSets.push(ruleSet);
+  }
+  /**
+   * Get all validation rules applicable to the given workflow AST.
+   * Runs each registered detect predicate and collects rules from matching sets.
+   */
+  getApplicableRules(ast) {
+    const rules = [];
+    for (const ruleSet of this.ruleSets) {
+      if (ruleSet.detect(ast)) {
+        rules.push(...ruleSet.getRules());
+      }
+    }
+    return rules;
+  }
+  /** Get the number of registered rule sets. */
+  get size() {
+    return this.ruleSets.length;
+  }
+};
+
+// src/api/validation-registry.ts
+var validationRuleRegistry = new ValidationRuleRegistry();
+
+export {
+  validationRuleRegistry
+};

package/dist/cli/flow-weaver-chunk-DRN7KPWY.mjs

@@ -0,0 +1,168 @@
+import { createRequire as __createRequire } from "module";
+const require = __createRequire(import.meta.url);
+
+// src/constants.ts
+var MIN_NODE_MAJOR = 22;
+var RESERVED_NODE_NAMES = {
+  START: "Start",
+  EXIT: "Exit"
+};
+var RESERVED_PORT_NAMES = {
+  EXECUTE: "execute",
+  ON_SUCCESS: "onSuccess",
+  ON_FAILURE: "onFailure"
+};
+var SCOPED_PORT_NAMES = {
+  START: "start",
+  // OUTPUT - starts scope iteration
+  SUCCESS: "success",
+  // INPUT - success signal from scope
+  FAILURE: "failure"
+  // INPUT - failure signal from scope
+};
+var EXECUTION_STRATEGIES = {
+  CONJUNCTION: "CONJUNCTION",
+  DISJUNCTION: "DISJUNCTION",
+  CUSTOM: "CUSTOM"
+};
+function isReservedNodeName(name) {
+  return Object.values(RESERVED_NODE_NAMES).includes(name);
+}
+function isStartNode(nodeName) {
+  return nodeName === RESERVED_NODE_NAMES.START;
+}
+function isExitNode(nodeName) {
+  return nodeName === RESERVED_NODE_NAMES.EXIT;
+}
+function isPseudoNode(nodeName) {
+  return nodeName.startsWith("secret:");
+}
+function isExecutePort(portName) {
+  return portName === RESERVED_PORT_NAMES.EXECUTE;
+}
+function isSuccessPort(portName) {
+  return portName === RESERVED_PORT_NAMES.ON_SUCCESS;
+}
+function isFailurePort(portName) {
+  return portName === RESERVED_PORT_NAMES.ON_FAILURE;
+}
+function isScopedStartPort(portName) {
+  return portName === SCOPED_PORT_NAMES.START;
+}
+function isScopedSuccessPort(portName) {
+  return portName === SCOPED_PORT_NAMES.SUCCESS;
+}
+function isScopedFailurePort(portName) {
+  return portName === SCOPED_PORT_NAMES.FAILURE;
+}
+function isScopedMandatoryPort(portName) {
+  return isScopedStartPort(portName) || isScopedSuccessPort(portName) || isScopedFailurePort(portName);
+}
+function isControlFlowPort(portName) {
+  return isExecutePort(portName) || isSuccessPort(portName) || isFailurePort(portName);
+}
+var VALID_NODE_COLORS = [
+  "blue",
+  "purple",
+  "cyan",
+  "orange",
+  "pink",
+  "green",
+  "red",
+  "yellow",
+  "teal"
+];
+var KNOWN_NODETYPE_TAGS = /* @__PURE__ */ new Set([
+  "flowWeaver",
+  "name",
+  "label",
+  "description",
+  "color",
+  "icon",
+  "tag",
+  "executeWhen",
+  "scope",
+  "expression",
+  "pullExecution",
+  "input",
+  "output",
+  "step",
+  "durablePure",
+  "durableGate",
+  "durableEffect",
+  "resilience",
+  // Async is auto-detected from the TS signature but accepted as an explicit annotation
+  "async",
+  // Deployment annotations
+  "deploy"
+]);
+var KNOWN_WORKFLOW_TAGS = /* @__PURE__ */ new Set([
+  "flowWeaver",
+  "name",
+  "fwImport",
+  "description",
+  "strictTypes",
+  "autoConnect",
+  "node",
+  "connect",
+  "scope",
+  "map",
+  "path",
+  "fanOut",
+  "fanIn",
+  "coerce",
+  "trigger",
+  "http",
+  "cancelOn",
+  "retries",
+  "timeout",
+  "throttle",
+  "param",
+  "return",
+  "returns",
+  // Async is auto-detected from the TS signature but accepted as an explicit annotation
+  "async",
+  // Deployment annotations
+  "deploy"
+]);
+var STANDARD_JSDOC_TAGS = /* @__PURE__ */ new Set([
+  "example",
+  "see",
+  "deprecated",
+  "type",
+  "typedef",
+  "template",
+  "link",
+  "since",
+  "version",
+  "author"
+]);
+function getKnownWorkflowTags(extraTags) {
+  if (!extraTags || extraTags.length === 0) return KNOWN_WORKFLOW_TAGS;
+  return /* @__PURE__ */ new Set([...KNOWN_WORKFLOW_TAGS, ...extraTags]);
+}
+
+export {
+  MIN_NODE_MAJOR,
+  RESERVED_NODE_NAMES,
+  RESERVED_PORT_NAMES,
+  SCOPED_PORT_NAMES,
+  EXECUTION_STRATEGIES,
+  isReservedNodeName,
+  isStartNode,
+  isExitNode,
+  isPseudoNode,
+  isExecutePort,
+  isSuccessPort,
+  isFailurePort,
+  isScopedStartPort,
+  isScopedSuccessPort,
+  isScopedFailurePort,
+  isScopedMandatoryPort,
+  isControlFlowPort,
+  VALID_NODE_COLORS,
+  KNOWN_NODETYPE_TAGS,
+  KNOWN_WORKFLOW_TAGS,
+  STANDARD_JSDOC_TAGS,
+  getKnownWorkflowTags
+};

package/dist/cli/flow-weaver-chunk-EKWF27G6.mjs

@@ -0,0 +1,23 @@
+import { createRequire as __createRequire } from "module";
+const require = __createRequire(import.meta.url);
+
+// src/coordinator/params.ts
+function missingParams(ast, params) {
+  const given = params ?? {};
+  return Object.entries(ast.startPorts ?? {}).filter(([name, port]) => name !== "execute" && port.dataType !== "STEP" && !port.optional && port.defaultValue === void 0 && (!Object.hasOwn(given, name) || given[name] === void 0)).map(([name]) => name);
+}
+var MissingParamsError = class extends Error {
+  constructor(workflowName, missing) {
+    super(`${workflowName} needs ${missing.length === 1 ? "a parameter" : "parameters"} it was not given: ${missing.join(", ")}`);
+    this.workflowName = workflowName;
+    this.missing = missing;
+  }
+  workflowName;
+  missing;
+  name = "MissingParamsError";
+};
+
+export {
+  missingParams,
+  MissingParamsError
+};

package/dist/cli/flow-weaver-chunk-EM5HWQ4R.mjs

@@ -0,0 +1,338 @@
+import { createRequire as __createRequire } from "module";
+const require = __createRequire(import.meta.url);
+import {
+  findAllBranchingNodes,
+  findNodesInBranch,
+  getTopologicalOrder
+} from "./flow-weaver-chunk-Z44JK332.mjs";
+import {
+  RESERVED_PORT_NAMES,
+  isExecutePort,
+  isStartNode
+} from "./flow-weaver-chunk-DRN7KPWY.mjs";
+
+// src/api/durable-validation.ts
+function durableBranchPaths(workflow) {
+  const branchingNodes = findAllBranchingNodes(workflow, workflow.nodeTypes);
+  const allInstanceIds = new Set(workflow.instances.map((instance) => instance.id));
+  const regions = /* @__PURE__ */ new Map();
+  for (const branchNodeId of branchingNodes) {
+    regions.set(branchNodeId, {
+      successNodes: findNodesInBranch(
+        branchNodeId,
+        RESERVED_PORT_NAMES.ON_SUCCESS,
+        workflow,
+        allInstanceIds,
+        branchingNodes
+      ),
+      failureNodes: findNodesInBranch(
+        branchNodeId,
+        RESERVED_PORT_NAMES.ON_FAILURE,
+        workflow,
+        allInstanceIds,
+        branchingNodes
+      )
+    });
+  }
+  const nodesInMultipleRegions = /* @__PURE__ */ new Set();
+  for (const instanceId of allInstanceIds) {
+    let regionCount = 0;
+    for (const region of regions.values()) {
+      if (region.successNodes.has(instanceId) || region.failureNodes.has(instanceId)) {
+        regionCount++;
+      }
+    }
+    if (regionCount > 1) nodesInMultipleRegions.add(instanceId);
+  }
+  for (const region of regions.values()) {
+    for (const instanceId of nodesInMultipleRegions) {
+      region.successNodes.delete(instanceId);
+      region.failureNodes.delete(instanceId);
+    }
+  }
+  const promoted = /* @__PURE__ */ new Set();
+  for (const region of regions.values()) {
+    for (const nodeId of region.successNodes) {
+      if (region.failureNodes.has(nodeId)) promoted.add(nodeId);
+    }
+  }
+  for (const [branchNodeId, region] of regions) {
+    const branchNodes = /* @__PURE__ */ new Set([
+      ...region.successNodes,
+      ...region.failureNodes
+    ]);
+    for (const nodeId of branchNodes) {
+      const hasExternalDataDependency = workflow.connections.some((connection) => {
+        if (connection.to.node !== nodeId || connection.from.scope || connection.to.scope || connection.from.node === branchNodeId || isStartNode(connection.from.node) || isExecutePort(connection.to.port)) {
+          return false;
+        }
+        return !branchNodes.has(connection.from.node);
+      });
+      if (hasExternalDataDependency) promoted.add(nodeId);
+    }
+  }
+  for (const region of regions.values()) {
+    for (const nodeId of promoted) {
+      region.successNodes.delete(nodeId);
+      region.failureNodes.delete(nodeId);
+    }
+  }
+  const result = /* @__PURE__ */ new Map();
+  for (const [branchNodeId, region] of regions) {
+    for (const nodeId of region.successNodes) {
+      const requirements = result.get(nodeId) ?? [];
+      requirements.push({ nodeId: branchNodeId, arm: "success" });
+      result.set(nodeId, requirements);
+    }
+    for (const nodeId of region.failureNodes) {
+      const requirements = result.get(nodeId) ?? [];
+      requirements.push({ nodeId: branchNodeId, arm: "failure" });
+      result.set(nodeId, requirements);
+    }
+  }
+  const executionOrder = getTopologicalOrder(workflow, {
+    includeScopedChildren: true
+  });
+  const orderByNode = new Map(
+    executionOrder.map((nodeId, index) => [nodeId, index])
+  );
+  const resolved = /* @__PURE__ */ new Map();
+  const resolvePath = (nodeId, visiting = /* @__PURE__ */ new Set()) => {
+    const memoized = resolved.get(nodeId);
+    if (memoized !== void 0) return memoized;
+    if (visiting.has(nodeId) || visiting.size > workflow.instances.length) {
+      throw new Error(
+        `Durable branch ancestry for ${workflow.functionName}.${nodeId} is recursive`
+      );
+    }
+    visiting.add(nodeId);
+    const transitive = (result.get(nodeId) ?? []).flatMap((requirement) => [
+      ...resolvePath(requirement.nodeId, new Set(visiting)),
+      requirement
+    ]);
+    const unique = transitive.filter(
+      (requirement, index, all) => all.findIndex(
+        (candidate) => candidate.nodeId === requirement.nodeId && candidate.arm === requirement.arm
+      ) === index
+    );
+    unique.sort(
+      (left, right) => (orderByNode.get(left.nodeId) ?? Number.MAX_SAFE_INTEGER) - (orderByNode.get(right.nodeId) ?? Number.MAX_SAFE_INTEGER)
+    );
+    resolved.set(nodeId, unique);
+    return unique;
+  };
+  for (const instance of workflow.instances) resolvePath(instance.id);
+  return resolved;
+}
+function durableClassificationCount(nodeType) {
+  const isGate = nodeType?.durableGate !== void 0;
+  const isEffect = nodeType?.durableEffect === true;
+  const impliedPure = nodeType?.expression === true && !isGate && !isEffect;
+  const isPure = nodeType?.durablePure === true || impliedPure;
+  return [isGate, isEffect, isPure].filter(Boolean).length;
+}
+function scopeOwnerInvokesConcurrently(parentNodeType) {
+  const body = parentNodeType?.functionTextProduction ?? parentNodeType?.functionText;
+  if (body === void 0) return true;
+  const codeOnly = body.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ").replace(/`(?:\\[\s\S]|[^`\\])*`/g, "``").replace(/'(?:\\.|[^'\\])*'/g, "''").replace(/"(?:\\.|[^"\\])*"/g, '""');
+  return /\bPromise\s*\.\s*(all|allSettled|race|any)\b/.test(codeOnly);
+}
+function scopeHasVisibleAttemptLimit(workflow, parentNodeType) {
+  if (parentNodeType === void 0) return false;
+  const limitPattern = /max|limit|attempts|retries|count|iterations/i;
+  return Object.keys(parentNodeType.inputs).some((port) => limitPattern.test(port));
+}
+function validateDurableClosure(root, allWorkflows = [], options = {}) {
+  const workflows = [...allWorkflows];
+  if (!workflows.some((workflow) => workflow.functionName === root.functionName)) {
+    workflows.push(root);
+  }
+  const workflowsByName = new Map(
+    workflows.map((workflow) => [workflow.functionName, workflow])
+  );
+  const reachableNames = /* @__PURE__ */ new Set();
+  const collectReachable = (workflow) => {
+    if (reachableNames.has(workflow.functionName)) return;
+    reachableNames.add(workflow.functionName);
+    for (const instance of workflow.instances) {
+      if (instance.nodeType === "invokeWorkflow") {
+        for (const possibleTarget of workflows) collectReachable(possibleTarget);
+      }
+      const nested = workflowsByName.get(instance.nodeType);
+      if (nested !== void 0) collectReachable(nested);
+    }
+  };
+  collectReachable(root);
+  const reachable = workflows.filter(
+    (workflow) => reachableNames.has(workflow.functionName)
+  );
+  const nodeTypeFor = (workflow, nodeTypeName) => workflow.nodeTypes.find(
+    (candidate) => candidate.name === nodeTypeName || candidate.functionName === nodeTypeName
+  );
+  const hasDurableGate = reachable.some(
+    (workflow) => workflow.instances.some(
+      (instance) => nodeTypeFor(workflow, instance.nodeType)?.durableGate !== void 0
+    )
+  );
+  const hasDurableEffect = reachable.some(
+    (workflow) => workflow.instances.some(
+      (instance) => nodeTypeFor(workflow, instance.nodeType)?.durableEffect === true
+    )
+  );
+  if (options.enforce === false) {
+    return { hasDurableGate, hasDurableEffect, reachable };
+  }
+  const invalidEffectContracts = [
+    ...new Set(
+      reachable.flatMap(
+        (workflow) => workflow.nodeTypes.flatMap((nodeType) => {
+          if (nodeType.durableEffect !== true || nodeType.durableEffectContract === void 0 || nodeType.durableEffectContract.valid) {
+            return [];
+          }
+          const location = nodeType.sourceLocation === void 0 ? "" : ` (${nodeType.sourceLocation.file}:${nodeType.sourceLocation.line})`;
+          return nodeType.durableEffectContract.diagnostics.map(
+            (diagnostic) => `${nodeType.functionName}${location}: ${diagnostic}`
+          );
+        })
+      )
+    )
+  ].sort();
+  if (!hasDurableGate) {
+    if (invalidEffectContracts.length > 0) {
+      throw new Error(
+        `Durable effect contract errors:
+${invalidEffectContracts.join("\n")}`
+      );
+    }
+    return { hasDurableGate, hasDurableEffect, reachable };
+  }
+  const boundaryMemo = /* @__PURE__ */ new Map();
+  const workflowHasDurableBoundary = (workflowName, visiting = /* @__PURE__ */ new Set()) => {
+    const memoized = boundaryMemo.get(workflowName);
+    if (memoized !== void 0) return memoized;
+    if (visiting.has(workflowName)) return false;
+    visiting.add(workflowName);
+    const workflow = workflowsByName.get(workflowName);
+    if (workflow === void 0) return false;
+    const result = workflow.instances.some((instance) => {
+      const nodeType = nodeTypeFor(workflow, instance.nodeType);
+      if (nodeType?.durableGate !== void 0 || nodeType?.durableEffect === true) {
+        return true;
+      }
+      if (instance.nodeType === "invokeWorkflow") {
+        return workflows.some(
+          (candidate) => workflowHasDurableBoundary(candidate.functionName, new Set(visiting))
+        );
+      }
+      return workflowHasDurableBoundary(instance.nodeType, new Set(visiting));
+    });
+    boundaryMemo.set(workflowName, result);
+    return result;
+  };
+  const unboundedDurableScopes = [];
+  const concurrentDurableScopes = [];
+  const invalidClassifications = [];
+  const lazyNodes = [];
+  const convergenceBoundaries = [];
+  for (const workflow of reachable) {
+    const executionOrder = getTopologicalOrder(workflow, {
+      includeScopedChildren: true
+    });
+    const branchPaths = durableBranchPaths(workflow);
+    const branchingNodes = findAllBranchingNodes(workflow, workflow.nodeTypes);
+    const allInstanceIds = new Set(workflow.instances.map((instance) => instance.id));
+    const branchReach = /* @__PURE__ */ new Map();
+    for (const branchNodeId of branchingNodes) {
+      const reach = /* @__PURE__ */ new Set([
+        ...findNodesInBranch(branchNodeId, RESERVED_PORT_NAMES.ON_SUCCESS, workflow, allInstanceIds, branchingNodes),
+        ...findNodesInBranch(branchNodeId, RESERVED_PORT_NAMES.ON_FAILURE, workflow, allInstanceIds, branchingNodes)
+      ]);
+      branchReach.set(branchNodeId, reach);
+    }
+    const nodeReachesBoundary = (nodeTypeName) => {
+      const nodeType = nodeTypeFor(workflow, nodeTypeName);
+      return nodeType?.durableGate !== void 0 || nodeType?.durableEffect === true || nodeTypeName === "invokeWorkflow" || workflowHasDurableBoundary(nodeTypeName);
+    };
+    const durableScopes = /* @__PURE__ */ new Map();
+    for (const instance of workflow.instances) {
+      if (instance.parent === void 0 || instance.parent === null) continue;
+      if (!nodeReachesBoundary(instance.nodeType)) continue;
+      const scopeKey = `${instance.parent.id}::${instance.parent.scope}`;
+      if (!durableScopes.has(scopeKey)) {
+        durableScopes.set(scopeKey, { ownerId: instance.parent.id, scopeName: instance.parent.scope });
+      }
+    }
+    for (const { ownerId, scopeName } of durableScopes.values()) {
+      const ownerInstance = workflow.instances.find((candidate) => candidate.id === ownerId);
+      const ownerNodeType = ownerInstance === void 0 ? void 0 : nodeTypeFor(workflow, ownerInstance.nodeType);
+      const where = `${workflow.functionName}.${ownerId} (scope '${scopeName}')`;
+      if (!scopeHasVisibleAttemptLimit(workflow, ownerNodeType)) {
+        unboundedDurableScopes.push(where);
+      }
+      if (scopeOwnerInvokesConcurrently(ownerNodeType)) {
+        concurrentDurableScopes.push(where);
+      }
+    }
+    for (const instance of workflow.instances) {
+      const nodeType = nodeTypeFor(workflow, instance.nodeType);
+      const reachesBoundary = nodeReachesBoundary(instance.nodeType);
+      if (!workflowsByName.has(instance.nodeType)) {
+        const classifications = durableClassificationCount(nodeType);
+        if (classifications !== 1) {
+          invalidClassifications.push(
+            `${workflow.functionName}.${instance.id} (${instance.nodeType}): ${classifications === 0 ? "unclassified" : "conflicting classifications"}`
+          );
+        }
+      }
+      if (instance.config?.pullExecution || nodeType?.defaultConfig?.pullExecution) {
+        lazyNodes.push(`${workflow.functionName}.${instance.id}`);
+      }
+      const instanceOrder = executionOrder.indexOf(instance.id);
+      if (reachesBoundary && (branchPaths.get(instance.id)?.length ?? 0) === 0 && [...branchingNodes].some(
+        (branchNodeId) => executionOrder.indexOf(branchNodeId) < instanceOrder && branchReach.get(branchNodeId)?.has(instance.id) === true
+      )) {
+        convergenceBoundaries.push(`${workflow.functionName}.${instance.id}`);
+      }
+    }
+  }
+  if (concurrentDurableScopes.length > 0) {
+    const invalid = [...new Set(concurrentDurableScopes)].sort();
+    throw new Error(
+      `A loop that reaches a durable gate must iterate sequentially so each gate keeps a distinct, ordered iteration ordinal; this scope owner invokes its iterations concurrently (Promise.all/allSettled/race/any). Await the callback once per iteration instead. Invalid: ${invalid.join(", ")}`
+    );
+  }
+  if (unboundedDurableScopes.length > 0) {
+    const invalid = [...new Set(unboundedDurableScopes)].sort();
+    throw new Error(
+      `A loop that reaches a durable gate needs a visible attempt limit so a resumed run cannot diverge on replay. Add a max/limit/attempts/iterations input to the scope node. Invalid: ${invalid.join(", ")}`
+    );
+  }
+  if (invalidClassifications.length > 0) {
+    throw new Error(
+      `Durable classification errors:
+Every reachable node in a workflow with a durable gate must have exactly one compiler classification: @durablePure, @durableGate, or @durableEffect. Invalid: ${invalidClassifications.sort().join(", ")}`
+    );
+  }
+  if (invalidEffectContracts.length > 0) {
+    throw new Error(
+      `Durable effect contract errors:
+${invalidEffectContracts.join("\n")}`
+    );
+  }
+  if (lazyNodes.length > 0) {
+    throw new Error(
+      `Durable gate workflows do not support pull or lazy execution because a yielded continuation requires a complete compiled predecessor prefix. Invalid: ${lazyNodes.sort().join(", ")}`
+    );
+  }
+  if (convergenceBoundaries.length > 0) {
+    throw new Error(
+      `Durable boundaries after branch convergence are not supported because the continuation must retain an independently active branch path. Place the boundary inside the selected branch. Invalid: ${convergenceBoundaries.sort().join(", ")}`
+    );
+  }
+  return { hasDurableGate, hasDurableEffect, reachable };
+}
+
+export {
+  durableBranchPaths,
+  validateDurableClosure
+};