@redvars/peacock 3.5.1 → 3.6.1

package/src/flow-designer/validation.ts

@@ -0,0 +1,284 @@
+import type { Workflow, WorkflowNode, ValidationError } from './types.js';
+import {
+  findNodeById,
+  getAllNodes,
+  getNodePath,
+  isDescendant,
+} from './workflow-utils.js';
+
+/**
+ * Workflow validation - checks for common errors and inconsistencies
+ */
+
+export class WorkflowValidator {
+  /**
+   * Validate entire workflow
+   */
+  static validate(workflow: Workflow): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    // Check root node exists and is a trigger
+    if (!workflow.nodes) {
+      errors.push({
+        nodeId: 'root',
+        type: 'orphaned_node',
+        message: 'Workflow has no root node',
+        severity: 'error',
+      });
+      return errors;
+    }
+
+    // Validate all nodes
+    const allNodes = getAllNodes(workflow.nodes);
+
+    // Check for circular loops
+    errors.push(...this._checkCircularLoops(workflow.nodes, allNodes));
+
+    // Check for orphaned nodes
+    errors.push(...this._checkOrphanedNodes(workflow.nodes, allNodes));
+
+    // Check valid branches
+    errors.push(...this._checkValidBranches(workflow.nodes, allNodes));
+
+    // Check missing targets
+    errors.push(...this._checkMissingTargets(workflow, allNodes));
+
+    // Check invalid fork/join pairs
+    errors.push(...this._checkForkJoinPairs(workflow.nodes, allNodes));
+
+    return errors;
+  }
+
+  /**
+   * Detect circular loop references
+   * A loop_end cannot point to a node that is its own descendant (after the loop_start)
+   */
+  private static _checkCircularLoops(
+    rootNode: WorkflowNode,
+    allNodes: WorkflowNode[]
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    for (const node of allNodes) {
+      // Only check loop_end nodes
+      if (node.type !== 'loop_end') continue;
+
+      const targetId = node.target_id;
+      if (!targetId) continue;
+
+      // Check if target exists
+      const targetNode = findNodeById(rootNode, targetId);
+      if (!targetNode) continue;
+
+      // If loop_end is a descendant of its target, it's circular
+      if (isDescendant(rootNode, targetId, node.id)) {
+        // This is the intended behavior - loop_end should be a descendant of loop_start
+        // So this is actually valid. Skip this check.
+      }
+
+      // However, if the loop_end's target is a descendant of the loop_end, that's circular
+      if (isDescendant(rootNode, node.id, targetId)) {
+        errors.push({
+          nodeId: node.id,
+          type: 'circular_loop',
+          message: `Loop cannot point to a node (${targetId}) that executes after the loop_end`,
+          severity: 'error',
+        });
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Check for orphaned nodes (not reachable from root)
+   */
+  private static _checkOrphanedNodes(
+    rootNode: WorkflowNode,
+    allNodes: WorkflowNode[]
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+    const paths = new Map<string, string[]>();
+
+    for (const node of allNodes) {
+      const path = getNodePath(rootNode, node.id);
+      if (path.length === 0 && node.id !== rootNode.id) {
+        errors.push({
+          nodeId: node.id,
+          type: 'orphaned_node',
+          message: `Node "${node.label}" is not reachable from the root trigger`,
+          severity: 'error',
+        });
+      }
+      paths.set(node.id, path);
+    }
+
+    // Check nodes in branches - all branch paths must be reachable
+    // This is typically valid by structure, but warn if branch has no exit
+    for (const node of allNodes) {
+      if (!node.branches) continue;
+
+      for (const [branchKey, branchNodes] of Object.entries(node.branches)) {
+        if (branchNodes.length === 0) {
+          errors.push({
+            nodeId: node.id,
+            type: 'invalid_branch',
+            message: `Branch "${branchKey}" is empty - no nodes to execute`,
+            severity: 'warning',
+          });
+        }
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Check that decision nodes have valid branches
+   */
+  private static _checkValidBranches(
+    rootNode: WorkflowNode,
+    allNodes: WorkflowNode[]
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    for (const node of allNodes) {
+      if (node.type !== 'decision') continue;
+
+      if (!node.branches) {
+        errors.push({
+          nodeId: node.id,
+          type: 'invalid_branch',
+          message: `Decision node "${node.label}" has no branches defined`,
+          severity: 'error',
+        });
+        continue;
+      }
+
+      // Standard decision should have "yes" and "no"
+      const branchKeys = Object.keys(node.branches);
+      if (!branchKeys.includes('yes') || !branchKeys.includes('no')) {
+        errors.push({
+          nodeId: node.id,
+          type: 'invalid_branch',
+          message: `Decision node "${node.label}" should have "yes" and "no" branches`,
+          severity: 'warning',
+        });
+      }
+
+      // Check for empty branches
+      for (const [branchKey, branchNodes] of Object.entries(node.branches)) {
+        if (branchNodes.length === 0) {
+          errors.push({
+            nodeId: node.id,
+            type: 'invalid_branch',
+            message: `Decision branch "${branchKey}" is empty`,
+            severity: 'warning',
+          });
+        }
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Check that loop_end nodes reference valid loop_start nodes
+   */
+  private static _checkMissingTargets(
+    workflow: Workflow,
+    allNodes: WorkflowNode[]
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    for (const node of allNodes) {
+      if (node.type === 'loop_end') {
+        if (!node.target_id) {
+          errors.push({
+            nodeId: node.id,
+            type: 'missing_target',
+            message: `Loop end "${node.label}" does not specify a target loop_start`,
+            severity: 'error',
+          });
+        } else {
+          const target = findNodeById(workflow.nodes, node.target_id);
+          if (!target || target.type !== 'loop_start') {
+            errors.push({
+              nodeId: node.id,
+              type: 'missing_target',
+              message: `Loop end "${node.label}" references non-existent or non-loop_start node "${node.target_id}"`,
+              severity: 'error',
+            });
+          }
+        }
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Check that fork nodes have corresponding join nodes
+   */
+  private static _checkForkJoinPairs(
+    rootNode: WorkflowNode,
+    allNodes: WorkflowNode[]
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    for (const node of allNodes) {
+      if (node.type === 'fork') {
+        if (!node.join) {
+          errors.push({
+            nodeId: node.id,
+            type: 'invalid_fork_join',
+            message: `Fork node "${node.label}" does not have a corresponding join node`,
+            severity: 'error',
+          });
+        } else if (node.join.type !== 'join') {
+          errors.push({
+            nodeId: node.id,
+            type: 'invalid_fork_join',
+            message: `Fork node "${node.label}" join is not a join node`,
+            severity: 'error',
+          });
+        }
+
+        if (!node.tasks || node.tasks.length === 0) {
+          errors.push({
+            nodeId: node.id,
+            type: 'invalid_fork_join',
+            message: `Fork node "${node.label}" has no parallel tasks`,
+            severity: 'warning',
+          });
+        }
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Check if workflow would create a valid execution path
+   */
+  static isExecutable(workflow: Workflow): boolean {
+    const errors = this.validate(workflow);
+    return errors.filter((e) => e.severity === 'error').length === 0;
+  }
+
+  /**
+   * Get validation warnings only
+   */
+  static getWarnings(workflow: Workflow): ValidationError[] {
+    const errors = this.validate(workflow);
+    return errors.filter((e) => e.severity === 'warning');
+  }
+
+  /**
+   * Get validation errors only
+   */
+  static getErrors(workflow: Workflow): ValidationError[] {
+    const errors = this.validate(workflow);
+    return errors.filter((e) => e.severity === 'error');
+  }
+}

package/src/flow-designer/workflow-utils.ts

@@ -0,0 +1,282 @@
+import type { Workflow, WorkflowNode } from './types.js';
+
+/**
+ * Workflow utility functions for tree traversal and manipulation
+ */
+
+/**
+ * Deep clone a workflow to ensure immutability
+ */
+export function cloneWorkflow(workflow: Workflow): Workflow {
+  return JSON.parse(JSON.stringify(workflow));
+}
+
+/**
+ * Deep clone a workflow node
+ */
+export function cloneNode(node: WorkflowNode): WorkflowNode {
+  return JSON.parse(JSON.stringify(node));
+}
+
+/**
+ * Find a node by ID anywhere in the workflow tree
+ */
+export function findNodeById(
+  node: WorkflowNode,
+  id: string
+): WorkflowNode | null {
+  if (node.id === id) return node;
+
+  // Search children
+  if (node.children) {
+    for (const child of node.children) {
+      const found = findNodeById(child, id);
+      if (found) return found;
+    }
+  }
+
+  // Search tasks
+  if (node.tasks) {
+    for (const task of node.tasks) {
+      const found = findNodeById(task, id);
+      if (found) return found;
+    }
+  }
+
+  // Search branches
+  if (node.branches) {
+    for (const branchNodes of Object.values(node.branches)) {
+      for (const branchNode of branchNodes) {
+        const found = findNodeById(branchNode, id);
+        if (found) return found;
+      }
+    }
+  }
+
+  // Search join
+  if (node.join) {
+    const found = findNodeById(node.join, id);
+    if (found) return found;
+  }
+
+  return null;
+}
+
+/**
+ * Remove a node by ID from the workflow tree
+ */
+export function removeNodeById(
+  node: WorkflowNode,
+  id: string
+): WorkflowNode {
+  const result = cloneNode(node);
+
+  // Remove from children
+  if (result.children) {
+    result.children = result.children.filter((child) => {
+      if (child.id === id) return false;
+      removeNodeById(child, id);
+      return true;
+    });
+  }
+
+  // Remove from tasks
+  if (result.tasks) {
+    result.tasks = result.tasks.filter((task) => {
+      if (task.id === id) return false;
+      removeNodeById(task, id);
+      return true;
+    });
+  }
+
+  // Remove from branches
+  if (result.branches) {
+    for (const [branchKey, branchNodes] of Object.entries(result.branches)) {
+      result.branches[branchKey] = branchNodes.filter((branchNode) => {
+        if (branchNode.id === id) return false;
+        removeNodeById(branchNode, id);
+        return true;
+      });
+    }
+  }
+
+  // Recursively clean empty nodes
+  for (const branchNode of result.children || []) {
+    removeNodeById(branchNode, id);
+  }
+  for (const taskNode of result.tasks || []) {
+    removeNodeById(taskNode, id);
+  }
+  for (const branchNodes of Object.values(result.branches || {})) {
+    for (const branchNode of branchNodes) {
+      removeNodeById(branchNode, id);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Insert a node into the workflow tree at a specific location
+ */
+export function insertNodeIntoWorkflow(
+  parent: WorkflowNode,
+  nodeToInsert: WorkflowNode,
+  connectionType: 'child' | 'branch' | 'task' = 'child',
+  branchKey?: string
+): void {
+  switch (connectionType) {
+    case 'child':
+      if (!parent.children) parent.children = [];
+      parent.children.push(cloneNode(nodeToInsert));
+      break;
+
+    case 'task':
+      if (!parent.tasks) parent.tasks = [];
+      parent.tasks.push(cloneNode(nodeToInsert));
+      break;
+
+    case 'branch':
+      if (!parent.branches) parent.branches = {};
+      if (!branchKey) branchKey = 'default';
+      if (!parent.branches[branchKey]) parent.branches[branchKey] = [];
+      parent.branches[branchKey].push(cloneNode(nodeToInsert));
+      break;
+  }
+}
+
+/**
+ * Collect all nodes in the workflow (depth-first)
+ */
+export function getAllNodes(node: WorkflowNode): WorkflowNode[] {
+  const result: WorkflowNode[] = [node];
+
+  if (node.children) {
+    for (const child of node.children) {
+      result.push(...getAllNodes(child));
+    }
+  }
+
+  if (node.tasks) {
+    for (const task of node.tasks) {
+      result.push(...getAllNodes(task));
+    }
+  }
+
+  if (node.branches) {
+    for (const branchNodes of Object.values(node.branches)) {
+      for (const branchNode of branchNodes) {
+        result.push(...getAllNodes(branchNode));
+      }
+    }
+  }
+
+  if (node.join) {
+    result.push(...getAllNodes(node.join));
+  }
+
+  return result;
+}
+
+/**
+ * Get all parent node IDs for a given node (path from root to node)
+ */
+export function getNodePath(
+  rootNode: WorkflowNode,
+  targetId: string
+): string[] {
+  const path: string[] = [];
+
+  function traverse(node: WorkflowNode): boolean {
+    path.push(node.id);
+
+    if (node.id === targetId) return true;
+
+    // Search children
+    if (node.children) {
+      for (const child of node.children) {
+        if (traverse(child)) return true;
+      }
+    }
+
+    // Search tasks
+    if (node.tasks) {
+      for (const task of node.tasks) {
+        if (traverse(task)) return true;
+      }
+    }
+
+    // Search branches
+    if (node.branches) {
+      for (const branchNodes of Object.values(node.branches)) {
+        for (const branchNode of branchNodes) {
+          if (traverse(branchNode)) return true;
+        }
+      }
+    }
+
+    // Search join
+    if (node.join) {
+      if (traverse(node.join)) return true;
+    }
+
+    path.pop();
+    return false;
+  }
+
+  traverse(rootNode);
+  return path;
+}
+
+/**
+ * Check if a node is a descendant of another node
+ */
+export function isDescendant(
+  rootNode: WorkflowNode,
+  potentialParentId: string,
+  nodeId: string
+): boolean {
+  const path = getNodePath(rootNode, nodeId);
+  return path.includes(potentialParentId);
+}
+
+/**
+ * Replace a node in the tree
+ */
+export function replaceNode(
+  node: WorkflowNode,
+  targetId: string,
+  replacement: WorkflowNode
+): WorkflowNode {
+  if (node.id === targetId) {
+    return cloneNode(replacement);
+  }
+
+  const result = cloneNode(node);
+
+  if (result.children) {
+    result.children = result.children.map((child) =>
+      replaceNode(child, targetId, replacement)
+    );
+  }
+
+  if (result.tasks) {
+    result.tasks = result.tasks.map((task) =>
+      replaceNode(task, targetId, replacement)
+    );
+  }
+
+  if (result.branches) {
+    for (const [branchKey, branchNodes] of Object.entries(result.branches)) {
+      result.branches[branchKey] = branchNodes.map((branchNode) =>
+        replaceNode(branchNode, targetId, replacement)
+      );
+    }
+  }
+
+  if (result.join) {
+    result.join = replaceNode(result.join, targetId, replacement);
+  }
+
+  return result;
+}