octie-cli 1.0.0

package/dist/core/graph/cycle.js

@@ -0,0 +1,297 @@
+/**
+ * Graph cycle detection algorithms
+ *
+ * Implements DFS-based cycle detection with three-color marking.
+ * Detects all cycles and returns cycle paths for debugging.
+ * Time complexity: O(V + E) where V = vertices, E = edges
+ *
+ * @module core/graph/cycle
+ */
+import { CircularDependencyError } from '../../types/index.js';
+/** Node visitation states for DFS cycle detection */
+var VisitState;
+(function (VisitState) {
+    /** Node has not been visited */
+    VisitState[VisitState["WHITE"] = 0] = "WHITE";
+    /** Node is currently being visited (in recursion stack) */
+    VisitState[VisitState["GRAY"] = 1] = "GRAY";
+    /** Node and all descendants have been completely visited */
+    VisitState[VisitState["BLACK"] = 2] = "BLACK";
+})(VisitState || (VisitState = {}));
+/**
+ * Detect cycles using DFS with three-color marking
+ *
+ * Algorithm:
+ * 1. Mark all nodes as WHITE (unvisited)
+ * 2. For each WHITE node, start DFS traversal
+ * 3. Mark node as GRAY when entering, BLACK when exiting
+ * 4. If we encounter a GRAY node during traversal, we found a cycle
+ * 5. Check for self-loops (task blocking itself) before DFS
+ * 6. Reconstruct cycle path using parent pointers
+ *
+ * Time Complexity: O(V + E)
+ * Space Complexity: O(V) for recursion stack and state tracking
+ *
+ * @param graph - Task graph store
+ * @returns Cycle detection result with all detected cycles
+ *
+ * @example
+ * ```ts
+ * const result = detectCycle(graph);
+ * if (result.hasCycle) {
+ *   console.error('Found cycles:', result.cycles);
+ *   for (const cycle of result.cycles) {
+ *     console.error('Cycle:', cycle.join(' -> '));
+ *   }
+ * }
+ * ```
+ */
+export function detectCycle(graph) {
+    const cycles = [];
+    const color = new Map();
+    const parent = new Map();
+    // Initialize all nodes as WHITE
+    for (const taskId of graph.getAllTaskIds()) {
+        color.set(taskId, VisitState.WHITE);
+        parent.set(taskId, null);
+    }
+    /**
+     * DFS traversal to detect cycles
+     * @param nodeId - Current node being visited
+     * @returns true if a cycle was found (can continue to find more)
+     */
+    function dfs(nodeId) {
+        // Mark current node as being visited
+        color.set(nodeId, VisitState.GRAY);
+        // Check for self-loop (task blocks itself)
+        const task = graph.getNode(nodeId);
+        if (task && task.blockers.includes(nodeId)) {
+            cycles.push([nodeId, nodeId]); // Self-loop: A -> A
+            // Continue to find more cycles, don't return yet
+        }
+        // Visit all neighbors
+        const neighbors = graph.getOutgoingEdges(nodeId);
+        for (const neighbor of neighbors) {
+            const neighborState = color.get(neighbor) ?? VisitState.WHITE;
+            if (neighborState === VisitState.GRAY) {
+                // Found a cycle - reconstruct the path
+                const cycle = [neighbor];
+                // Backtrack from current node to the neighbor
+                let current = nodeId;
+                while (current && current !== neighbor) {
+                    cycle.unshift(current);
+                    current = parent.get(current) || null;
+                }
+                // Add neighbor at start to complete the cycle
+                cycle.unshift(neighbor);
+                cycles.push(cycle);
+                return true; // Continue to find more cycles
+            }
+            if (neighborState === VisitState.WHITE) {
+                // Set parent and continue DFS
+                parent.set(neighbor, nodeId);
+                if (dfs(neighbor)) {
+                    return true; // Continue searching
+                }
+            }
+            // BLACK nodes are already processed, skip them
+        }
+        // Mark node as completely visited
+        color.set(nodeId, VisitState.BLACK);
+        return false;
+    }
+    // Start DFS from all unvisited nodes
+    for (const taskId of graph.getAllTaskIds()) {
+        if ((color.get(taskId) ?? VisitState.WHITE) === VisitState.WHITE) {
+            dfs(taskId);
+        }
+    }
+    return {
+        hasCycle: cycles.length > 0,
+        cycles,
+    };
+}
+/**
+ * Check if a graph contains any cycles
+ * Convenience function that returns a boolean
+ *
+ * @param graph - Task graph store
+ * @returns true if graph contains at least one cycle
+ */
+export function hasCycle(graph) {
+    const result = detectCycle(graph);
+    return result.hasCycle;
+}
+/**
+ * Get all nodes involved in cycles
+ *
+ * @param graph - Task graph store
+ * @returns Set of task IDs that are part of at least one cycle
+ */
+export function getCyclicNodes(graph) {
+    const result = detectCycle(graph);
+    const cyclicNodes = new Set();
+    for (const cycle of result.cycles) {
+        for (const nodeId of cycle) {
+            cyclicNodes.add(nodeId);
+        }
+    }
+    return cyclicNodes;
+}
+/**
+ * Find the shortest cycle in the graph
+ * Useful for identifying the most critical circular dependency
+ *
+ * @param graph - Task graph store
+ * @returns Shortest cycle array, or empty array if no cycles
+ */
+export function findShortestCycle(graph) {
+    const result = detectCycle(graph);
+    if (result.cycles.length === 0) {
+        return [];
+    }
+    return result.cycles.reduce((shortest, current) => current.length < shortest.length ? current : shortest);
+}
+/**
+ * Find all cycles involving a specific task
+ *
+ * @param graph - Task graph store
+ * @param taskId - Task ID to find cycles for
+ * @returns Array of cycles that include the specified task
+ */
+export function findCyclesForTask(graph, taskId) {
+    const result = detectCycle(graph);
+    return result.cycles.filter(cycle => cycle.includes(taskId));
+}
+/**
+ * Validate that a graph is acyclic (DAG)
+ * Throws an error if cycles are detected
+ *
+ * @param graph - Task graph store
+ * @throws {CircularDependencyError} If graph contains cycles
+ */
+export function validateAcyclic(graph) {
+    const result = detectCycle(graph);
+    if (result.hasCycle) {
+        // Use the first cycle found for the error
+        const firstCycle = result.cycles[0];
+        if (firstCycle) {
+            throw new CircularDependencyError(firstCycle);
+        }
+    }
+}
+/**
+ * Get cycle statistics
+ *
+ * @param graph - Task graph store
+ * @returns Object with cycle count and nodes in cycles
+ */
+export function getCycleStatistics(graph) {
+    const result = detectCycle(graph);
+    const cyclicNodes = getCyclicNodes(graph);
+    const cyclesByLength = {};
+    for (const cycle of result.cycles) {
+        const len = cycle.length;
+        cyclesByLength[len] = (cyclesByLength[len] || 0) + 1;
+    }
+    return {
+        cycleCount: result.cycles.length,
+        nodesInCycles: cyclicNodes.size,
+        totalNodes: graph.size,
+        cyclesByLength,
+    };
+}
+/**
+ * Validate that all blocker references point to existing tasks
+ *
+ * Checks each task's blockers array to ensure all referenced tasks exist.
+ * This catches orphaned references that could occur from:
+ * - Manual JSON editing
+ * - Bugs in edge manipulation
+ * - Incomplete graph operations
+ *
+ * @param graph - Task graph store
+ * @returns Validation result with any invalid references found
+ *
+ * @example
+ * ```ts
+ * const result = validateReferences(graph);
+ * if (result.hasInvalidReferences) {
+ *   for (const ref of result.invalidReferences) {
+ *     console.error(`Task ${ref.taskId} has missing blocker: ${ref.invalidBlockerId}`);
+ *   }
+ * }
+ * ```
+ */
+export function validateReferences(graph) {
+    const invalidReferences = [];
+    for (const taskId of graph.getAllTaskIds()) {
+        const task = graph.getNode(taskId);
+        if (task) {
+            for (const blockerId of task.blockers) {
+                if (!graph.hasNode(blockerId)) {
+                    invalidReferences.push({ taskId, invalidBlockerId: blockerId });
+                }
+            }
+        }
+    }
+    return {
+        hasInvalidReferences: invalidReferences.length > 0,
+        invalidReferences,
+    };
+}
+/**
+ * Check if adding an edge would create a cycle
+ *
+ * When adding a blocker relationship (blockerId → taskId), this function
+ * checks if there's already a path from taskId to blockerId. If so,
+ * adding the edge would create a cycle.
+ *
+ * Also rejects self-blocking (taskId === blockerId).
+ *
+ * @param graph - Task graph store
+ * @param blockerId - The task that will block (source of edge)
+ * @param taskId - The task being blocked (target of edge)
+ * @returns true if adding this edge would create a cycle
+ *
+ * @example
+ * ```ts
+ * // Before adding blocker, check for cycle
+ * if (wouldCreateCycle(graph, blockerId, taskId)) {
+ *   console.error('Cannot add blocker: would create a cycle');
+ * } else {
+ *   task.addBlocker(blockerId);
+ *   graph.addEdge(blockerId, taskId);
+ * }
+ * ```
+ */
+export function wouldCreateCycle(graph, blockerId, taskId) {
+    // Self-blocking is always a cycle
+    if (blockerId === taskId) {
+        return true;
+    }
+    // Check if taskId can already reach blockerId through existing edges
+    // If so, adding blockerId → taskId would create a cycle
+    // We search 'forward' from taskId following outgoing edges
+    const visited = new Set();
+    const queue = [taskId];
+    while (queue.length > 0) {
+        const currentId = queue.shift();
+        if (currentId === blockerId) {
+            return true; // Found path from taskId to blockerId
+        }
+        if (visited.has(currentId)) {
+            continue;
+        }
+        visited.add(currentId);
+        // Follow outgoing edges (tasks that this task blocks)
+        const neighbors = graph.getOutgoingEdges(currentId);
+        for (const neighbor of neighbors) {
+            if (!visited.has(neighbor)) {
+                queue.push(neighbor);
+            }
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=cycle.js.map

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

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

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

@@ -0,0 +1,223 @@
+/**
+ * Task Graph data structure
+ *
+ * Implements a directed graph using adjacency lists for O(1) node lookup
+ * and O(k) edge traversal where k is the number of edges.
+ *
+ * Graph Structure:
+ * - nodes: Map<taskId, TaskNode> for O(1) node lookup
+ * - outgoingEdges: Map<taskId, Set<targetTaskIds>> for forward traversal
+ * - incomingEdges: Map<taskId, Set<sourceTaskIds>> for reverse traversal
+ *
+ * @module core/graph
+ */
+import type { TaskGraph, ProjectMetadata } from '../../types/index.js';
+import { TaskNode } from '../models/task-node.js';
+/**
+ * TaskGraphStore class
+ *
+ * Manages the task graph data structure with efficient lookup and traversal.
+ * Uses Map and Set for optimal performance:
+ * - O(1) node lookup by ID
+ * - O(k) edge traversal where k = edge count
+ * - O(1) edge existence checking
+ */
+export declare class TaskGraphStore {
+    /** Primary node storage (hash map for O(1) lookup) */
+    private _nodes;
+    /** Outgoing edges: node -> nodes it points to */
+    private _outgoingEdges;
+    /** Incoming edges: node -> nodes pointing to it */
+    private _incomingEdges;
+    /** Graph metadata */
+    private _metadata;
+    /**
+     * Create a new TaskGraphStore
+     * @param metadata - Optional project metadata
+     */
+    constructor(metadata?: ProjectMetadata);
+    /**
+     * Get the number of tasks in the graph
+     */
+    get size(): number;
+    /**
+     * Get the graph metadata
+     */
+    get metadata(): ProjectMetadata;
+    /**
+     * Update graph metadata
+     * @param metadata - New metadata values (partial update)
+     */
+    setMetadata(metadata: Partial<ProjectMetadata>): void;
+    /**
+     * Get a task node by ID
+     * @param id - Task ID to look up
+     * @returns Task node or undefined if not found
+     * @complexity O(1)
+     */
+    getNode(id: string): TaskNode | undefined;
+    /**
+     * Get a task node by ID or throw error
+     * @param id - Task ID to look up
+     * @returns Task node
+     * @throws {TaskNotFoundError} If task not found
+     * @complexity O(1)
+     */
+    getNodeOrThrow(id: string): TaskNode;
+    /**
+     * Check if a task exists
+     * @param id - Task ID to check
+     * @returns True if task exists
+     * @complexity O(1)
+     */
+    hasNode(id: string): boolean;
+    /**
+     * Get a task node by short UUID prefix (first 7-8 characters)
+     * @param prefix - Short UUID prefix to look up
+     * @returns Task node or undefined if not found
+     * @throws {AmbiguousIdError} If multiple tasks match the prefix
+     * @complexity O(n) where n is the number of tasks
+     */
+    getNodeByPrefix(prefix: string): TaskNode | undefined;
+    /**
+     * Get a task node by ID or prefix
+     * @param id - Task ID or short UUID prefix to look up
+     * @returns Task node or undefined if not found
+     * @complexity O(1) for full ID, O(n) for prefix
+     */
+    getNodeByIdOrPrefix(id: string): TaskNode | undefined;
+    /**
+     * Generate a unique task ID with collision detection
+     * Ensures that the first 7 characters of the UUID are unique across all tasks
+     * @returns A unique task ID
+     * @throws {Error} If unable to generate unique ID after many attempts
+     */
+    generateUniqueId(): string;
+    /**
+     * Get all task IDs in the graph
+     * @returns Array of task IDs
+     */
+    getAllTaskIds(): string[];
+    /**
+     * Get all task nodes in the graph
+     * @returns Array of task nodes
+     */
+    getAllTasks(): TaskNode[];
+    /**
+     * Add a task node to the graph
+     * @param node - Task node to add
+     * @throws {ValidationError} If task ID already exists
+     * @complexity O(1)
+     */
+    addNode(node: TaskNode): void;
+    /**
+     * Remove a task node from the graph
+     * @param id - Task ID to remove
+     * @throws {TaskNotFoundError} If task not found
+     * @complexity O(k) where k is the number of edges
+     */
+    removeNode(id: string): void;
+    /**
+     * Update a task node in the graph
+     * @param node - Task node with updated values
+     * @throws {TaskNotFoundError} If task not found
+     * @complexity O(1)
+     */
+    updateNode(node: TaskNode): void;
+    /**
+     * Get outgoing edges for a node
+     * @param nodeId - Source task ID
+     * @returns Array of target task IDs
+     * @complexity O(k) where k is the number of outgoing edges
+     */
+    getOutgoingEdges(nodeId: string): string[];
+    /**
+     * Get incoming edges for a node
+     * @param nodeId - Target task ID
+     * @returns Array of source task IDs
+     * @complexity O(k) where k is the number of incoming edges
+     */
+    getIncomingEdges(nodeId: string): string[];
+    /**
+     * Add an edge between two nodes
+     * @param fromId - Source task ID
+     * @param toId - Target task ID
+     * @throws {TaskNotFoundError} If either task not found
+     * @throws {ValidationError} If edge already exists
+     * @complexity O(1)
+     */
+    addEdge(fromId: string, toId: string): void;
+    /**
+     * Remove an edge between two nodes
+     * @param fromId - Source task ID
+     * @param toId - Target task ID
+     * @throws {TaskNotFoundError} If either task not found
+     * @throws {ValidationError} If edge doesn't exist
+     * @complexity O(1)
+     */
+    removeEdge(fromId: string, toId: string): void;
+    /**
+     * Check if an edge exists
+     * @param fromId - Source task ID
+     * @param toId - Target task ID
+     * @returns True if edge exists
+     * @complexity O(1)
+     */
+    hasEdge(fromId: string, toId: string): boolean;
+    /**
+     * Get root tasks (tasks with no incoming edges)
+     * @returns Array of root task IDs
+     * @complexity O(n) where n is the number of tasks
+     */
+    getRootTasks(): string[];
+    /**
+     * Get orphan tasks (tasks with no edges at all)
+     * @returns Array of orphan task IDs
+     * @complexity O(n) where n is the number of tasks
+     */
+    getOrphanTasks(): string[];
+    /**
+     * Get leaf tasks (tasks with no outgoing edges)
+     * @returns Array of leaf task IDs
+     * @complexity O(n) where n is the number of tasks
+     */
+    getLeafTasks(): string[];
+    /**
+     * Clear all tasks and edges from the graph
+     * Keeps metadata but resets the graph structure
+     */
+    clear(): void;
+    /**
+     * Convert graph to TaskGraph interface
+     * @returns TaskGraph interface representation
+     */
+    toInterface(): TaskGraph;
+    /**
+     * Create TaskGraphStore from TaskGraph interface
+     * @param graph - TaskGraph interface
+     * @returns New TaskGraphStore instance
+     */
+    static fromInterface(graph: TaskGraph): TaskGraphStore;
+    /**
+     * Serialize graph to JSON-compatible object
+     * @returns JSON-serializable object
+     */
+    toJSON(): {
+        nodes: Record<string, TaskNode>;
+        outgoingEdges: Record<string, string[]>;
+        incomingEdges: Record<string, string[]>;
+        metadata: ProjectMetadata;
+    };
+    /**
+     * Deserialize graph from JSON object
+     * @param json - JSON object from toJSON()
+     * @returns New TaskGraphStore instance
+     */
+    static fromJSON(json: {
+        nodes: Record<string, TaskNode>;
+        outgoingEdges: Record<string, string[]>;
+        incomingEdges: Record<string, string[]>;
+        metadata: ProjectMetadata;
+    }): TaskGraphStore;
+}
+//# sourceMappingURL=index.d.ts.map

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

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