octie-cli 1.0.0

package/dist/core/graph/sort.js

@@ -0,0 +1,254 @@
+/**
+ * Graph topological sort algorithms
+ *
+ * Implements Kahn's algorithm for topological sorting with cycle detection.
+ * Time complexity: O(V + E) where V = vertices, E = edges
+ *
+ * @module core/graph/sort
+ */
+import { CircularDependencyError } from '../../types/index.js';
+/** Cache for topological sort results */
+const sortCache = new Map();
+/** Cache TTL in milliseconds (5 seconds) */
+const CACHE_TTL = 5000;
+/**
+ * Generate a cache key for the graph
+ * @param graph - Task graph store
+ * @returns Cache key string
+ */
+function generateCacheKey(graph) {
+    const taskIds = graph.getAllTaskIds().sort().join(',');
+    const metadata = graph.metadata;
+    return `${metadata.project_name}:${metadata.version}:${taskIds}:${graph.size}`;
+}
+/**
+ * Clear the topological sort cache
+ * Call this after modifying the graph structure
+ */
+export function clearSortCache() {
+    sortCache.clear();
+}
+/**
+ * Perform topological sort using Kahn's algorithm
+ *
+ * Algorithm steps:
+ * 1. Calculate in-degree for all nodes
+ * 2. Initialize queue with nodes having zero in-degree
+ * 3. Process queue: remove node, add to result, reduce neighbors' in-degree
+ * 4. Add any neighbors with zero in-degree to queue
+ * 5. Detect cycle if result doesn't contain all nodes
+ *
+ * Time Complexity: O(V + E)
+ * Space Complexity: O(V)
+ *
+ * @param graph - Task graph store
+ * @param useCache - Whether to use memoization cache (default: true)
+ * @returns Topological sort result with sorted order and cycle detection
+ *
+ * @example
+ * ```ts
+ * const result = topologicalSort(graph);
+ * if (result.hasCycle) {
+ *   console.error('Cycle detected:', result.cycleNodes);
+ * } else {
+ *   console.log('Execution order:', result.sorted);
+ * }
+ * ```
+ */
+export function topologicalSort(graph, useCache = true) {
+    // Check cache
+    if (useCache) {
+        const cacheKey = generateCacheKey(graph);
+        const cached = sortCache.get(cacheKey);
+        if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+            return cached.result;
+        }
+    }
+    const result = kahnSort(graph);
+    // Update cache
+    if (useCache) {
+        const cacheKey = generateCacheKey(graph);
+        sortCache.set(cacheKey, { result, timestamp: Date.now() });
+    }
+    return result;
+}
+/**
+ * Internal implementation of Kahn's algorithm
+ * @param graph - Task graph store
+ * @returns Topological sort result
+ */
+function kahnSort(graph) {
+    // Step 1: Initialize in-degree map
+    const inDegree = new Map();
+    const allTaskIds = graph.getAllTaskIds();
+    for (const taskId of allTaskIds) {
+        inDegree.set(taskId, 0);
+    }
+    // Step 2: Calculate in-degrees from outgoing edges
+    for (const taskId of allTaskIds) {
+        const outgoingEdges = graph.getOutgoingEdges(taskId);
+        for (const targetId of outgoingEdges) {
+            inDegree.set(targetId, (inDegree.get(targetId) || 0) + 1);
+        }
+    }
+    // Step 3: Initialize queue with zero in-degree nodes
+    const queue = [];
+    for (const [taskId, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(taskId);
+        }
+    }
+    // Step 4: Process queue
+    const sorted = [];
+    while (queue.length > 0) {
+        // Remove first node from queue
+        const nodeId = queue.shift();
+        sorted.push(nodeId);
+        // Reduce in-degree of all neighbors
+        const neighbors = graph.getOutgoingEdges(nodeId);
+        for (const neighbor of neighbors) {
+            const newDegree = (inDegree.get(neighbor) || 0) - 1;
+            inDegree.set(neighbor, newDegree);
+            // Add to queue if in-degree becomes zero
+            if (newDegree === 0) {
+                queue.push(neighbor);
+            }
+        }
+    }
+    // Step 5: Detect cycle
+    const hasCycle = sorted.length !== graph.size;
+    const cycleNodes = hasCycle
+        ? allTaskIds.filter(id => !sorted.includes(id))
+        : [];
+    return {
+        sorted,
+        hasCycle,
+        cycleNodes,
+    };
+}
+/**
+ * Find the critical path (longest path) in the DAG
+ * Uses topological sort and dynamic programming
+ *
+ * Time Complexity: O(V + E)
+ *
+ * @param graph - Task graph store
+ * @param taskDuration - Duration for each task (default: 1)
+ * @returns Object with path array and total duration
+ * @throws {CircularDependencyError} If graph contains cycles
+ */
+export function findCriticalPath(graph, taskDuration = 1) {
+    // First, verify no cycles exist
+    const sortResult = topologicalSort(graph, false);
+    if (sortResult.hasCycle) {
+        throw new CircularDependencyError(sortResult.cycleNodes);
+    }
+    // Calculate earliest start times using DP
+    const earliestStart = new Map();
+    const getDuration = typeof taskDuration === 'number'
+        ? () => taskDuration
+        : (id) => taskDuration.get(id) || 1;
+    // Initialize all start times to 0
+    for (const taskId of graph.getAllTaskIds()) {
+        earliestStart.set(taskId, 0);
+    }
+    // Process in topological order
+    for (const nodeId of sortResult.sorted) {
+        const predecessors = graph.getIncomingEdges(nodeId);
+        const maxPredFinish = predecessors.length === 0
+            ? 0
+            : Math.max(...predecessors.map(p => (earliestStart.get(p) || 0) + getDuration(p)));
+        earliestStart.set(nodeId, maxPredFinish);
+    }
+    // Find node with maximum finish time
+    let maxFinish = 0;
+    let endNode = '';
+    for (const [nodeId, start] of earliestStart) {
+        const finish = start + getDuration(nodeId);
+        if (finish > maxFinish) {
+            maxFinish = finish;
+            endNode = nodeId;
+        }
+    }
+    // Backtrack to find critical path
+    const criticalPath = [endNode];
+    let current = endNode;
+    while (true) {
+        const predecessors = graph.getIncomingEdges(current);
+        if (predecessors.length === 0)
+            break;
+        // Find predecessor on critical path
+        const currentStart = earliestStart.get(current) || 0;
+        const criticalPred = predecessors.find(p => {
+            const predFinish = (earliestStart.get(p) || 0) + getDuration(p);
+            return predFinish === currentStart;
+        });
+        if (!criticalPred)
+            break;
+        criticalPath.unshift(criticalPred);
+        current = criticalPred;
+    }
+    return {
+        path: criticalPath,
+        duration: maxFinish,
+    };
+}
+/**
+ * Validate that a graph is a valid DAG
+ * Convenience wrapper around topologicalSort
+ *
+ * @param graph - Task graph store
+ * @returns true if graph is a valid DAG, false otherwise
+ */
+export function isValidDAG(graph) {
+    const result = topologicalSort(graph, false);
+    return !result.hasCycle;
+}
+/**
+ * Get task execution levels (parallelizable stages)
+ * Tasks at the same level have no dependencies between them
+ *
+ * @param graph - Task graph store
+ * @returns Array of task ID arrays (each level is a parallelizable stage)
+ * @throws {CircularDependencyError} If graph contains cycles
+ */
+export function getExecutionLevels(graph) {
+    const sortResult = topologicalSort(graph, false);
+    if (sortResult.hasCycle) {
+        const { CircularDependencyError } = require('../../types/index.js');
+        throw new CircularDependencyError(sortResult.cycleNodes);
+    }
+    const levels = [];
+    const inDegree = new Map();
+    const remaining = new Set(sortResult.sorted);
+    // Calculate initial in-degrees
+    for (const taskId of sortResult.sorted) {
+        inDegree.set(taskId, graph.getIncomingEdges(taskId).length);
+    }
+    // Process level by level
+    while (remaining.size > 0) {
+        const currentLevel = [];
+        // Find all nodes with zero in-degree from remaining nodes
+        for (const taskId of remaining) {
+            if ((inDegree.get(taskId) || 0) === 0) {
+                currentLevel.push(taskId);
+            }
+        }
+        if (currentLevel.length === 0) {
+            // This shouldn't happen if graph is valid
+            break;
+        }
+        levels.push(currentLevel);
+        // Remove current level and update in-degrees
+        for (const taskId of currentLevel) {
+            remaining.delete(taskId);
+            for (const neighbor of graph.getOutgoingEdges(taskId)) {
+                if (remaining.has(neighbor)) {
+                    inDegree.set(neighbor, (inDegree.get(neighbor) || 0) - 1);
+                }
+            }
+        }
+    }
+    return levels;
+}
+//# sourceMappingURL=sort.js.map

package/dist/core/graph/sort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.js","sourceRoot":"","sources":["../../../src/core/graph/sort.ts"],"names":[],"mappings":"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"}

package/dist/core/graph/traversal.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Graph traversal algorithms
+ *
+ * Implements BFS and DFS traversal methods for path finding and
+ * reachable node discovery.
+ * Time complexity: O(V + E) where V = vertices, E = edges
+ *
+ * @module core/graph/traversal
+ */
+import type { TaskGraphStore } from './index.js';
+/**
+ * Breadth-First Search traversal
+ *
+ * Explores nodes layer by layer, finding all reachable nodes from a start node.
+ * Useful for finding all descendants (forward) or ancestors (backward).
+ *
+ * Time Complexity: O(V + E) in worst case
+ * Space Complexity: O(V) for visited set and queue
+ *
+ * @param graph - Task graph store
+ * @param startId - Starting task ID
+ * @param direction - Traversal direction: 'forward' (outgoing) or 'backward' (incoming)
+ * @returns Array of reachable task IDs in order of discovery
+ * @throws {TaskNotFoundError} If start node doesn't exist
+ *
+ * @example
+ * ```ts
+ * // Find all tasks that depend on the start task
+ * const descendants = bfsTraversal(graph, 'task-001', 'forward');
+ *
+ * // Find all tasks that the start task depends on
+ * const ancestors = bfsTraversal(graph, 'task-001', 'backward');
+ * ```
+ */
+export declare function bfsTraversal(graph: TaskGraphStore, startId: string, direction?: 'forward' | 'backward'): string[];
+/**
+ * Depth-First Search to find path between two nodes
+ *
+ * Attempts to find a path from start to end using DFS with backtracking.
+ * Returns the first path found, or null if no path exists.
+ *
+ * Time Complexity: O(V + E) in worst case
+ * Space Complexity: O(V) for recursion stack and visited set
+ *
+ * @param graph - Task graph store
+ * @param startId - Starting task ID
+ * @param endId - Target task ID
+ * @param direction - Search direction: 'forward' (follow outgoing) or 'backward' (follow incoming)
+ * @returns Path array from start to end, or null if no path exists
+ * @throws {TaskNotFoundError} If either node doesn't exist
+ *
+ * @example
+ * ```ts
+ * // Find path from task-001 to task-005
+ * const path = dfsFindPath(graph, 'task-001', 'task-005');
+ * if (path) {
+ *   console.log('Path:', path.join(' -> '));
+ *   // Output: Path: task-001 -> task-002 -> task-004 -> task-005
+ * }
+ * ```
+ */
+export declare function dfsFindPath(graph: TaskGraphStore, startId: string, endId: string, direction?: 'forward' | 'backward'): string[] | null;
+/**
+ * Find all paths between two nodes
+ *
+ * Uses DFS to find all possible paths from start to end.
+ * Warning: Can be expensive on dense graphs with many paths.
+ *
+ * @param graph - Task graph store
+ * @param startId - Starting task ID
+ * @param endId - Target task ID
+ * @param direction - Search direction: 'forward' or 'backward'
+ * @param maxPaths - Maximum number of paths to find (default: 100, prevents explosion)
+ * @returns Array of paths (each path is an array of task IDs)
+ * @throws {TaskNotFoundError} If either node doesn't exist
+ */
+export declare function findAllPaths(graph: TaskGraphStore, startId: string, endId: string, direction?: 'forward' | 'backward', maxPaths?: number): string[][];
+/**
+ * Get shortest path between two nodes using BFS
+ *
+ * BFS naturally finds the shortest path in unweighted graphs.
+ *
+ * @param graph - Task graph store
+ * @param startId - Starting task ID
+ * @param endId - Target task ID
+ * @param direction - Search direction: 'forward' or 'backward'
+ * @returns Shortest path array, or null if no path exists
+ * @throws {TaskNotFoundError} If either node doesn't exist
+ */
+export declare function findShortestPath(graph: TaskGraphStore, startId: string, endId: string, direction?: 'forward' | 'backward'): string[] | null;
+/**
+ * Check if two nodes are connected (path exists)
+ *
+ * @param graph - Task graph store
+ * @param fromId - Source task ID
+ * @param toId - Target task ID
+ * @param direction - Search direction: 'forward' or 'backward'
+ * @returns true if a path exists between the nodes
+ */
+export declare function areConnected(graph: TaskGraphStore, fromId: string, toId: string, direction?: 'forward' | 'backward'): boolean;
+/**
+ * Get distance (number of edges) between two nodes
+ *
+ * @param graph - Task graph store
+ * @param fromId - Source task ID
+ * @param toId - Target task ID
+ * @param direction - Search direction: 'forward' or 'backward'
+ * @returns Number of edges in shortest path, or -1 if no path exists
+ */
+export declare function getDistance(graph: TaskGraphStore, fromId: string, toId: string, direction?: 'forward' | 'backward'): number;
+/**
+ * Get connected components in the graph
+ *
+ * Identifies groups of nodes that are reachable from each other.
+ * For directed graphs, uses weakly connected components
+ * (treating edges as undirected).
+ *
+ * @param graph - Task graph store
+ * @returns Array of connected components (each is an array of task IDs)
+ */
+export declare function getConnectedComponents(graph: TaskGraphStore): string[][];
+//# sourceMappingURL=traversal.d.ts.map

package/dist/core/graph/traversal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traversal.d.ts","sourceRoot":"","sources":["../../../src/core/graph/traversal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,GAAG,UAAsB,GAC5C,MAAM,EAAE,CA4CV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,SAAS,GAAG,UAAsB,GAC5C,MAAM,EAAE,GAAG,IAAI,CAyDjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,SAAS,GAAG,UAAsB,EAC7C,QAAQ,SAAM,GACb,MAAM,EAAE,EAAE,CAsDZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,SAAS,GAAG,UAAsB,GAC5C,MAAM,EAAE,GAAG,IAAI,CA2CjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,SAAS,GAAG,UAAsB,GAC5C,OAAO,CAOT;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,SAAS,GAAG,UAAsB,GAC5C,MAAM,CAGR;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,EAAE,EAAE,CAyCxE"}