@octaviaflow/flow-rules 0.1.0 → 0.2.0

package/dist/rules/workflowValidator.js

@@ -1,358 +0,0 @@
-/**
- * Workflow Validation System — rules engine v2 (DEV-220)
- *
- * Validates nodes, edges, and overall workflow structure on every
- * STRUCTURAL canvas change (WorkflowContext applies it selectively —
- * selection/viewport/drag churn never re-runs it). Results feed:
- *   - the FlowToolbarIssues indicator (badge + hover overlay)
- *   - per-node error/warning badges (flowAdapter → DS BaseNode status)
- *   - activation gating (useFlowLifecycle: errors block Activate;
- *     Save is NEVER blocked; warnings never block anything)
- *
- * Severity model (ADR-flow-pause-and-rules-v2):
- *   error   → the flow cannot work as built (missing trigger, broken edge,
- *             cycle, missing required config). Blocks Activate.
- *   warning → it will run, but probably not the way the user thinks
- *             ("won't run" orphans, multi-flow canvas, duplicate edges).
- */
-import { getNodeConfigStatus } from './nodeConfigStatus';
-const nodeName = (n) => n.label || n.id;
-/**
- * Validate a single node.
- */
-export function validateNode(node, allNodes, allEdges) {
-    const errors = [];
-    // Check required fields
-    if (!node.id || node.id.trim().length === 0) {
-        errors.push({
-            id: `node-${node.id}-id`,
-            type: 'node',
-            severity: 'error',
-            message: 'Node ID is required',
-            nodeId: node.id,
-        });
-    }
-    if (!node.label || node.label.trim().length === 0) {
-        errors.push({
-            id: `node-${node.id}-label`,
-            type: 'node',
-            severity: 'error',
-            message: 'Node label is required',
-            nodeId: node.id,
-        });
-    }
-    // Config completeness — computed LIVE from the action definition's
-    // required fields (the persisted `isValid` flag goes stale between the
-    // loader and the current edit). Missing required fields are an ERROR and
-    // are named so the issues list is actionable.
-    const cfg = getNodeConfigStatus(node);
-    if (cfg.missingRequired.length > 0) {
-        const fields = cfg.missingRequired.slice(0, 4).join(', ');
-        const more = cfg.missingRequired.length > 4 ? ` +${cfg.missingRequired.length - 4} more` : '';
-        errors.push({
-            id: `node-${node.id}-config`,
-            type: 'node',
-            severity: 'error',
-            // Actionable for END USERS: name the exact fields AND the fix action.
-            message: `Missing required settings: ${fields}${more}. Open the step and fill them in.`,
-            nodeId: node.id,
-        });
-    }
-    // Trigger nodes must have at least one outgoing connection to be useful
-    const hasOutput = allEdges.some(edge => edge.source === node.id);
-    if (!hasOutput && node.type === 'trigger') {
-        errors.push({
-            id: `node-${node.id}-output`,
-            type: 'node',
-            severity: 'warning',
-            message: `Trigger "${nodeName(node)}" has no outgoing connections`,
-            nodeId: node.id,
-        });
-    }
-    return errors;
-}
-/**
- * Validate a single edge. `allEdges` powers real duplicate detection —
- * only the SECOND-and-later instance of a duplicate is flagged, so one
- * duplicate pair yields one warning, not two.
- */
-export function validateEdge(edge, allNodes, allEdges = []) {
-    const errors = [];
-    // Check if source node exists
-    const sourceNode = allNodes.find(n => n.id === edge.source);
-    if (!sourceNode) {
-        errors.push({
-            id: `edge-${edge.id}-source`,
-            type: 'edge',
-            severity: 'error',
-            message: `Source node "${edge.source}" does not exist`,
-            edgeId: edge.id,
-        });
-    }
-    // Check if target node exists
-    const targetNode = allNodes.find(n => n.id === edge.target);
-    if (!targetNode) {
-        errors.push({
-            id: `edge-${edge.id}-target`,
-            type: 'edge',
-            severity: 'error',
-            message: `Target node "${edge.target}" does not exist`,
-            edgeId: edge.id,
-        });
-    }
-    // Check for self-loops
-    if (edge.source === edge.target) {
-        errors.push({
-            id: `edge-${edge.id}-loop`,
-            type: 'edge',
-            severity: 'error',
-            message: 'Nodes cannot connect to themselves',
-            edgeId: edge.id,
-        });
-    }
-    // Duplicate edges: same source/target (and same handles when present).
-    // (v1 shipped with `duplicateCount = 1` hard-coded — the rule could
-    // never fire. DEV-220 fixed it.)
-    const key = (e) => `${e.source}|${e.sourceHandle ?? ''}→${e.target}|${e.targetHandle ?? ''}`;
-    const myKey = key(edge);
-    const firstIndex = allEdges.findIndex(e => key(e) === myKey);
-    const myIndex = allEdges.findIndex(e => e.id === edge.id);
-    if (firstIndex !== -1 && myIndex > firstIndex) {
-        errors.push({
-            id: `edge-${edge.id}-duplicate`,
-            type: 'edge',
-            severity: 'warning',
-            message: `Duplicate connection between "${sourceNode ? nodeName(sourceNode) : edge.source}" and "${targetNode ? nodeName(targetNode) : edge.target}"`,
-            edgeId: edge.id,
-        });
-    }
-    return errors;
-}
-/**
- * Validate entire workflow.
- */
-export function validateWorkflow(nodes, edges) {
-    const allErrors = [];
-    // Check for at least one trigger node
-    const hasTrigger = nodes.some(node => node.type === 'trigger');
-    if (!hasTrigger) {
-        allErrors.push({
-            id: 'workflow-trigger',
-            type: 'workflow',
-            severity: 'error',
-            message: 'Workflow must have at least one trigger node',
-        });
-    }
-    // Check for at least one action node
-    const hasAction = nodes.some(node => node.type === 'action');
-    if (!hasAction && nodes.length > 0) {
-        allErrors.push({
-            id: 'workflow-action',
-            type: 'workflow',
-            severity: 'warning',
-            message: 'Workflow should have at least one action node',
-        });
-    }
-    // Validate individual nodes
-    nodes.forEach(node => {
-        const nodeErrors = validateNode(node, nodes, edges);
-        allErrors.push(...nodeErrors);
-    });
-    // Validate individual edges
-    edges.forEach(edge => {
-        const edgeErrors = validateEdge(edge, nodes, edges);
-        allErrors.push(...edgeErrors);
-    });
-    // ── Cycle detection (DEV-220) ──
-    // Kahn's algorithm over the execution edges; anything the topological
-    // sort can't reach sits on (or strictly behind) a cycle. The Engine
-    // APPENDS such steps to the order silently, so a cycle produces
-    // undefined ordering at run time — an error here, not a curiosity.
-    if (nodes.length > 0 && edges.length > 0) {
-        const inDegree = new Map(nodes.map(n => [n.id, 0]));
-        const out = new Map();
-        for (const e of edges) {
-            if (e.source === e.target)
-                continue; // self-loops flagged per-edge already
-            if (!inDegree.has(e.source) || !inDegree.has(e.target))
-                continue; // dangling flagged already
-            inDegree.set(e.target, (inDegree.get(e.target) ?? 0) + 1);
-            const list = out.get(e.source);
-            if (list)
-                list.push(e.target);
-            else
-                out.set(e.source, [e.target]);
-        }
-        const queue = nodes.filter(n => (inDegree.get(n.id) ?? 0) === 0).map(n => n.id);
-        let visited = 0;
-        while (queue.length) {
-            const cur = queue.shift();
-            visited++;
-            for (const next of out.get(cur) ?? []) {
-                const d = (inDegree.get(next) ?? 1) - 1;
-                inDegree.set(next, d);
-                if (d === 0)
-                    queue.push(next);
-            }
-        }
-        if (visited < nodes.length) {
-            const stuck = nodes.filter(n => (inDegree.get(n.id) ?? 0) > 0);
-            const names = stuck.slice(0, 3).map(nodeName).join(', ');
-            const more = stuck.length > 3 ? ` +${stuck.length - 3} more` : '';
-            allErrors.push({
-                id: 'workflow-cycle',
-                type: 'workflow',
-                severity: 'error',
-                message: `Circular connection detected involving: ${names}${more}. Break the loop — execution order is undefined inside a cycle.`,
-                nodeId: stuck[0]?.id,
-            });
-        }
-    }
-    // ── DEV-207: "won't run" warnings ──
-    // Execution is reachability-from-entry: a node runs only if it is reachable,
-    // following edges, from a trigger. Flag configured nodes that WON'T run so
-    // the consequence is explicit (a stray, unconnected Slack step silently not
-    // firing is the exact footgun this prevents).
-    const isTrigger = (n) => n.type === 'trigger' || String(n.actionDefinitionId ?? '').endsWith('_trigger');
-    const triggerIds = nodes.filter(isTrigger).map(n => n.id);
-    // Forward reachability from every trigger, closed over parent/child so a
-    // container's body counts as reachable when the container is (mirrors the
-    // Engine's executionScope).
-    const adjacency = new Map();
-    for (const e of edges) {
-        const list = adjacency.get(e.source);
-        if (list)
-            list.push(e.target);
-        else
-            adjacency.set(e.source, [e.target]);
-    }
-    const reachable = new Set(triggerIds);
-    const queue = [...triggerIds];
-    while (queue.length) {
-        const cur = queue.shift();
-        for (const next of adjacency.get(cur) ?? []) {
-            if (!reachable.has(next)) {
-                reachable.add(next);
-                queue.push(next);
-            }
-        }
-    }
-    let changed = true;
-    while (changed) {
-        changed = false;
-        for (const n of nodes) {
-            if (reachable.has(n.id)) {
-                if (n.parentId && !reachable.has(n.parentId)) {
-                    reachable.add(n.parentId);
-                    changed = true;
-                }
-            }
-            else if (n.parentId && reachable.has(n.parentId)) {
-                reachable.add(n.id);
-                changed = true;
-            }
-        }
-    }
-    nodes.forEach(node => {
-        if (isTrigger(node))
-            return;
-        const isConnected = edges.some(e => e.source === node.id || e.target === node.id);
-        // With ≥1 trigger, "won't run" is precise: not reachable from any trigger.
-        // With NO trigger yet (a draft), fall back to the connectivity check so we
-        // still flag a fully-orphaned node without spamming every step of a
-        // trigger-less work-in-progress.
-        const wontRun = triggerIds.length > 0 ? !reachable.has(node.id) : !isConnected;
-        if (wontRun) {
-            allErrors.push({
-                id: `node-${node.id}-orphan`,
-                type: 'node',
-                severity: 'warning',
-                message: isConnected
-                    ? `"${nodeName(node)}" isn't reachable from a trigger and won't run.`
-                    : `"${nodeName(node)}" isn't connected to a flow and won't run.`,
-                nodeId: node.id,
-            });
-        }
-    });
-    // ── Multi-flow canvas advisory (DEV-220 / ADR multi-graph decision) ──
-    // Multiple disconnected trigger trees on one canvas are LEGAL (component-
-    // scoped execution isolates them), but usually a maintainability smell —
-    // warn, never block. Components are weakly-connected (undirected) with the
-    // same parent/child closure as reachability.
-    if (triggerIds.length > 1) {
-        const parentOf = new Map(nodes.filter(n => n.parentId).map(n => [n.id, n.parentId]));
-        const undirected = new Map();
-        const link = (a, b) => {
-            const la = undirected.get(a);
-            if (la)
-                la.push(b);
-            else
-                undirected.set(a, [b]);
-        };
-        for (const e of edges) {
-            link(e.source, e.target);
-            link(e.target, e.source);
-        }
-        for (const [child, parent] of parentOf) {
-            link(child, parent);
-            link(parent, child);
-        }
-        const seen = new Set();
-        let flowsWithTrigger = 0;
-        for (const t of triggerIds) {
-            if (seen.has(t))
-                continue;
-            flowsWithTrigger++;
-            const stack = [t];
-            seen.add(t);
-            while (stack.length) {
-                const cur = stack.pop();
-                for (const next of undirected.get(cur) ?? []) {
-                    if (!seen.has(next)) {
-                        seen.add(next);
-                        stack.push(next);
-                    }
-                }
-            }
-        }
-        if (flowsWithTrigger > 1) {
-            allErrors.push({
-                id: 'workflow-multi-flow',
-                type: 'workflow',
-                severity: 'warning',
-                message: `This canvas holds ${flowsWithTrigger} separate flows. Each trigger runs only its own flow — consider splitting them into separate flows for clarity.`,
-            });
-        }
-    }
-    const errors = allErrors.filter(e => e.severity === 'error');
-    const warnings = allErrors.filter(e => e.severity === 'warning');
-    return {
-        isValid: errors.length === 0,
-        errors,
-        warnings,
-    };
-}
-/**
- * Get validation status for a specific node
- */
-export function getNodeValidationStatus(nodeId, validationResult) {
-    const hasError = validationResult.errors.some(e => e.nodeId === nodeId);
-    if (hasError)
-        return 'error';
-    const hasWarning = validationResult.warnings.some(e => e.nodeId === nodeId);
-    if (hasWarning)
-        return 'warning';
-    return 'valid';
-}
-/**
- * Get validation status for a specific edge
- */
-export function getEdgeValidationStatus(edgeId, validationResult) {
-    const hasError = validationResult.errors.some(e => e.edgeId === edgeId);
-    if (hasError)
-        return 'error';
-    const hasWarning = validationResult.warnings.some(e => e.edgeId === edgeId);
-    if (hasWarning)
-        return 'warning';
-    return 'valid';
-}