feat: add execution ordering analysis functions (topologicalOrder, parallelGroups, criticalPath, reachableFrom, ancestors, descendants)

src/analysis/index.ts

@@ -5,6 +5,14 @@ export {
   resolveDefaultNodeAttrs,
 } from "./defaults.js";
 export { typeCompat, type TypeCompatResult, type TypeMismatch } from "./type-compat.js";
+export {
+  topologicalOrder,
+  parallelGroups,
+  criticalPath,
+  reachableFrom,
+  ancestors,
+  descendants,
+} from "./ordering.js";
 export { buildTypeEdges } from "../graph/construction.js";
 export {
   validateSchema,

src/analysis/ordering.ts

@@ -0,0 +1,86 @@
+import { topologicalSort, topologicalGenerations, hasCycle } from "graphology-dag";
+import type { FlowGraph } from "../graph/construction.js";
+import { CycleError, NodeNotFoundError } from "../error/index.js";
+import { findCycles as findCyclesQuery, reachableFrom as reachableFromQuery, ancestors as ancestorsQuery, descendants as descendantsQuery } from "../graph/queries.js";
+
+export function topologicalOrder(graph: FlowGraph): string[] {
+  if (hasCycle(graph.graph)) {
+    const cycles = findCyclesQuery(graph.graph);
+    throw new CycleError(cycles);
+  }
+  return topologicalSort(graph.graph);
+}
+
+export function parallelGroups(graph: FlowGraph): string[][] {
+  if (hasCycle(graph.graph)) {
+    const cycles = findCyclesQuery(graph.graph);
+    throw new CycleError(cycles);
+  }
+  return topologicalGenerations(graph.graph);
+}
+
+export function criticalPath(graph: FlowGraph): string[] {
+  if (hasCycle(graph.graph)) {
+    const cycles = findCyclesQuery(graph.graph);
+    throw new CycleError(cycles);
+  }
+  const dg = graph.graph;
+  const depth = new Map<string, number>();
+  const topo = topologicalSort(dg);
+  for (const node of topo) {
+    const inNeighbors = dg.inNeighbors(node) ?? [];
+    let maxPredDepth = -1;
+    for (const pred of inNeighbors) {
+      const predDepth = depth.get(pred!) ?? 0;
+      if (predDepth > maxPredDepth) {
+        maxPredDepth = predDepth;
+      }
+    }
+    depth.set(node, maxPredDepth + 1);
+  }
+  let maxDepth = -1;
+  let endNode = "";
+  for (const node of topo) {
+    const d = depth.get(node) ?? 0;
+    if (d > maxDepth) {
+      maxDepth = d;
+      endNode = node;
+    }
+  }
+  if (topo.length === 0) return [];
+  const path: string[] = [endNode];
+  let current = endNode;
+  while (depth.get(current)! > 0) {
+    const inNeighbors = dg.inNeighbors(current) ?? [];
+    let bestPred = "";
+    let bestDepth = -1;
+    for (const pred of inNeighbors) {
+      const predDepth = depth.get(pred!) ?? 0;
+      if (predDepth > bestDepth) {
+        bestDepth = predDepth;
+        bestPred = pred!;
+      }
+    }
+    path.unshift(bestPred);
+    current = bestPred;
+  }
+  return path;
+}
+
+export function reachableFrom(graph: FlowGraph, nodeIds: string[]): Set<string> {
+  return reachableFromQuery(graph.graph, nodeIds);
+}
+
+export function ancestors(graph: FlowGraph, nodeId: string): string[] {
+  if (!graph.hasNode(nodeId)) {
+    throw new NodeNotFoundError(nodeId);
+  }
+  return ancestorsQuery(graph.graph, nodeId);
+}
+
+export function descendants(graph: FlowGraph, nodeId: string): string[] {
+  if (!graph.hasNode(nodeId)) {
+    throw new NodeNotFoundError(nodeId);
+  }
+  return descendantsQuery(graph.graph, nodeId);
+}