@scenario-labs/sdk 3.1.0 → 3.3.0

package/src/lib/workflow_validator.ts

@@ -8,18 +8,27 @@ const VALID_NODE_TYPES = new Set([
   'remove-background',
   'transform',
   'user-approval',
+  'user-selection',
   'workflow',
 ]);
 
+const USER_SELECTION_MIN_SELECT = 1;
+const USER_SELECTION_MAX_SELECT = 100;
+const USER_SELECTION_INPUT_TYPES = new Set(['file_array', 'string_array']);
+
 type RawRef = {
   node?: unknown;
+  equal?: unknown;
   conditional?: unknown;
 };
 
 type RawInput = {
   name?: unknown;
+  type?: unknown;
   ref?: RawRef;
   items?: unknown[][];
+  min?: unknown;
+  max?: unknown;
 };
 
 type RawNode = {
@@ -47,12 +56,19 @@ type RawNode = {
  *       - custom-model → modelId
  *       - workflow     → workflowId
  *       - logic        → logicType
- *       - for-each     → loopBodyNodeIds (non-empty) OR count (>0)
+ *       - for-each        → loopBodyNodeIds (non-empty) OR count (>0)
+ *       - user-selection  → exactly one file_array/string_array input (optional connection);
+ *                           input.min ≤ input.max
  *  5. Cross-references all point to node IDs that exist in the flow:
  *       - dependsOn entries
  *       - input ref.node (excluding "workflow" which is a reserved keyword)
  *       - input ref.conditional entries
  *       - loopBodyNodeIds entries
+ *  6. A node an if-else branch can skip is read through a plain `ref.node` only by nodes
+ *     gated by the same branch. A node is skippable when it has a `connection` input on that
+ *     branch, or when every target of one of its `ref.conditional` inputs is skippable on it.
+ *     Any other reader never resolves when the branch is not taken, and the workflow job
+ *     never completes. A `ref.conditional` merge reads whichever branch ran, so it is allowed.
  */
 export function validateWorkflowFlow(flow: unknown[]): void {
   const nodeIds = new Set<string>();
@@ -101,6 +117,9 @@ export function validateWorkflowFlow(flow: unknown[]): void {
         );
       }
     }
+    if (type === 'user-selection') {
+      validateUserSelectionNode(label, node);
+    }
   }
 
   // Pass 2 — cross-reference checks (all node IDs are now collected)
@@ -130,6 +149,115 @@ export function validateWorkflowFlow(flow: unknown[]): void {
       }
     }
   }
+
+  // Pass 3 — readers of branch-gated nodes must be gated by the same branch
+  const branchGates = collectBranchGates(flow as RawNode[]);
+  if (branchGates.size === 0) return;
+
+  for (const rawNode of flow) {
+    const node = rawNode as RawNode;
+    const nodeId = node.id as string;
+    if (!Array.isArray(node.inputs)) continue;
+    const readerGates = branchGates.get(nodeId);
+
+    for (const { inputName, refNode } of collectPlainRefs(node.inputs as RawInput[])) {
+      const producerGates = branchGates.get(refNode);
+      if (!producerGates) continue;
+      const missing = [...producerGates].find((gate) => !readerGates?.has(gate));
+      if (missing) {
+        throw new Error(
+          `Node "${nodeId}" input "${inputName}" reads node "${refNode}", which the if-else branch ${missing} can skip, ` +
+            `but "${nodeId}" is not gated by that branch, so it would never run and the workflow job would never complete. ` +
+            `Gate "${nodeId}" through the same branch, or merge the branches with a conditional ref.`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Maps each node an if-else branch can skip to its gates, formatted as `"<ifElseId>" == "<value>"`.
+ * Direct gates come from `connection` inputs. A `ref.conditional` input whose targets all share a
+ * gate is skipped with them, so its node inherits the shared gates, through chains too.
+ */
+function collectBranchGates(flow: RawNode[]): Map<string, Set<string>> {
+  const ifElseIds = new Set(
+    flow.filter((n) => n.type === 'logic' && n.logicType === 'if-else').map((n) => n.id as string),
+  );
+  const gates = new Map<string, Set<string>>();
+  if (ifElseIds.size === 0) return gates;
+
+  for (const node of flow) {
+    if (!Array.isArray(node.inputs)) continue;
+    for (const input of node.inputs as RawInput[]) {
+      const ref = input.ref;
+      if (input.type !== 'connection' || typeof ref?.node !== 'string' || !ifElseIds.has(ref.node)) continue;
+      const gate = `"${ref.node}" == "${String(ref.equal)}"`;
+      const nodeGates = gates.get(node.id as string) ?? new Set<string>();
+      nodeGates.add(gate);
+      gates.set(node.id as string, nodeGates);
+    }
+  }
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const node of flow) {
+      if (!Array.isArray(node.inputs)) continue;
+      for (const targets of collectConditionalRefs(node.inputs as RawInput[])) {
+        const targetGates = targets.map((id) => gates.get(id));
+        if (targetGates.length === 0 || targetGates.some((g) => !g)) continue;
+        const [first, ...rest] = targetGates as Set<string>[];
+        const shared = [...first!].filter((gate) => rest.every((g) => g.has(gate)));
+        const nodeGates = gates.get(node.id as string) ?? new Set<string>();
+        for (const gate of shared) {
+          if (!nodeGates.has(gate)) {
+            nodeGates.add(gate);
+            changed = true;
+          }
+        }
+        if (nodeGates.size > 0) gates.set(node.id as string, nodeGates);
+      }
+    }
+  }
+  return gates;
+}
+
+/** Target lists of a node's `ref.conditional` inputs, INPUTS_ARRAY sub-inputs included. */
+function collectConditionalRefs(inputs: RawInput[]): string[][] {
+  const lists: string[][] = [];
+  for (const input of inputs) {
+    const conditional = input.ref?.conditional;
+    if (Array.isArray(conditional)) {
+      lists.push(conditional.filter((id): id is string => typeof id === 'string'));
+    }
+    if (Array.isArray(input.items)) {
+      for (const item of input.items) {
+        if (Array.isArray(item)) lists.push(...collectConditionalRefs(item as RawInput[]));
+      }
+    }
+  }
+  return lists;
+}
+
+/** Plain `ref.node` data refs of a node's inputs, INPUTS_ARRAY sub-inputs included; `connection` inputs excluded. */
+function collectPlainRefs(inputs: RawInput[]): Array<{ inputName: string; refNode: string }> {
+  const refs: Array<{ inputName: string; refNode: string }> = [];
+  for (const input of inputs) {
+    const refNode = input.ref?.node;
+    if (input.type !== 'connection' && typeof refNode === 'string' && refNode !== 'workflow') {
+      refs.push({
+        inputName: typeof input.name === 'string' && input.name ? input.name : '(unnamed)',
+        refNode,
+      });
+    }
+    if (Array.isArray(input.items)) {
+      for (const item of input.items) {
+        if (Array.isArray(item)) refs.push(...collectPlainRefs(item as RawInput[]));
+      }
+    }
+  }
+  return refs;
 }
 
 function validateInputRefs(nodeId: string, input: RawInput, nodeIds: Set<string>): void {
@@ -165,3 +293,57 @@ function validateInputRefs(nodeId: string, input: RawInput, nodeIds: Set<string>
     }
   }
 }
+
+function validateUserSelectionNode(label: string, node: RawNode): void {
+  const inputs = Array.isArray(node.inputs) ? (node.inputs as RawInput[]) : [];
+  const selectionInputs = inputs.filter(
+    (input) => typeof input.type === 'string' && USER_SELECTION_INPUT_TYPES.has(input.type),
+  );
+  const otherInputs = inputs.filter(
+    (input) => !(typeof input.type === 'string' && USER_SELECTION_INPUT_TYPES.has(input.type)),
+  );
+
+  if (selectionInputs.length !== 1) {
+    throw new Error(
+      `Node ${label} (user-selection) must have exactly one input of type file_array or string_array`,
+    );
+  }
+  for (const input of otherInputs) {
+    if (input.type !== 'connection') {
+      throw new Error(
+        `Node ${label} (user-selection) only allows an optional connection input besides the selection array, got "${String(
+          input.type,
+        )}"`,
+      );
+    }
+  }
+
+  const input = selectionInputs[0]!;
+
+  const min = input.min === undefined ? USER_SELECTION_MIN_SELECT : input.min;
+  const max = input.max === undefined ? USER_SELECTION_MAX_SELECT : input.max;
+
+  if (
+    typeof min !== 'number' ||
+    !Number.isInteger(min) ||
+    min < USER_SELECTION_MIN_SELECT ||
+    min > USER_SELECTION_MAX_SELECT
+  ) {
+    throw new Error(
+      `Node ${label} (user-selection) input.min must be an integer between ${USER_SELECTION_MIN_SELECT} and ${USER_SELECTION_MAX_SELECT}`,
+    );
+  }
+  if (
+    typeof max !== 'number' ||
+    !Number.isInteger(max) ||
+    max < USER_SELECTION_MIN_SELECT ||
+    max > USER_SELECTION_MAX_SELECT
+  ) {
+    throw new Error(
+      `Node ${label} (user-selection) input.max must be an integer between ${USER_SELECTION_MIN_SELECT} and ${USER_SELECTION_MAX_SELECT}`,
+    );
+  }
+  if (min > max) {
+    throw new Error(`Node ${label} (user-selection) input.min (${min}) must be <= input.max (${max})`);
+  }
+}