@task-mcp/shared 1.0.3 → 1.0.6

package/src/algorithms/critical-path.ts

@@ -102,35 +102,48 @@ function calculateProjectDuration(taskMap: Map<string, CPMTask>): number {
 }
 
 /**
- * Find tasks that have successors (are dependencies of other tasks)
+ * Build successor index: maps taskId -> list of tasks that depend on it
+ * This is O(n * d) where d is average dependencies, done once upfront
+ * Allows O(1) successor lookup instead of O(n) per task
  */
-function findTasksWithSuccessors(sortedTasks: Task[]): Set<string> {
-  const tasksWithSuccessors = new Set<string>();
+function buildSuccessorIndex(sortedTasks: Task[], taskMap: Map<string, CPMTask>): Map<string, CPMTask[]> {
+  const successorIndex = new Map<string, CPMTask[]>();
+
+  // Initialize empty arrays for all tasks
+  for (const task of sortedTasks) {
+    successorIndex.set(task.id, []);
+  }
 
+  // Build the index: if task A is blocked_by task B, then A is a successor of B
   for (const task of sortedTasks) {
     const deps = getBlockedByDeps(task);
+    const cpmTask = taskMap.get(task.id);
+    if (!cpmTask) continue;
+
     for (const depId of deps) {
-      tasksWithSuccessors.add(depId);
+      const successors = successorIndex.get(depId);
+      if (successors) {
+        successors.push(cpmTask);
+      }
     }
   }
 
-  return tasksWithSuccessors;
+  return successorIndex;
 }
 
 /**
- * Find successor tasks (tasks that depend on a given task)
+ * Find tasks that have successors (are dependencies of other tasks)
  */
-function findSuccessors(taskId: string, taskMap: Map<string, CPMTask>): CPMTask[] {
-  const successors: CPMTask[] = [];
+function findTasksWithSuccessors(successorIndex: Map<string, CPMTask[]>): Set<string> {
+  const tasksWithSuccessors = new Set<string>();
 
-  for (const other of taskMap.values()) {
-    const otherDeps = getBlockedByDeps(other);
-    if (otherDeps.includes(taskId)) {
-      successors.push(other);
+  for (const [taskId, successors] of successorIndex) {
+    if (successors.length > 0) {
+      tasksWithSuccessors.add(taskId);
     }
   }
 
-  return successors;
+  return tasksWithSuccessors;
 }
 
 /**
@@ -141,9 +154,10 @@ function findSuccessors(taskId: string, taskMap: Map<string, CPMTask>): CPMTask[
 function backwardPass(
   sortedTasks: Task[],
   taskMap: Map<string, CPMTask>,
+  successorIndex: Map<string, CPMTask[]>,
   projectDuration: number
 ): void {
-  const tasksWithSuccessors = findTasksWithSuccessors(sortedTasks);
+  const tasksWithSuccessors = findTasksWithSuccessors(successorIndex);
 
   // Initialize end tasks (tasks with no successors)
   for (const task of taskMap.values()) {
@@ -162,7 +176,7 @@ function backwardPass(
     if (!cpmTask) continue;
 
     const duration = getTaskDuration(task);
-    const successors = findSuccessors(task.id, taskMap);
+    const successors = successorIndex.get(task.id) ?? [];
 
     if (successors.length > 0) {
       // LF = min(LS of all successors)
@@ -187,14 +201,29 @@ function calculateSlackAndCritical(taskMap: Map<string, CPMTask>): void {
 }
 
 /**
- * Count dependents for bottleneck detection
+ * Count dependents for bottleneck detection using successor index
+ * Uses dynamic programming: dependentCount = direct successors + their dependentCounts
+ * O(n) instead of O(n³) with findDependents
  */
-function countDependents(sortedTasks: Task[], activeTasks: Task[], taskMap: Map<string, CPMTask>): void {
-  for (const task of sortedTasks) {
+function countDependents(
+  sortedTasks: Task[],
+  taskMap: Map<string, CPMTask>,
+  successorIndex: Map<string, CPMTask[]>
+): void {
+  // Process in reverse topological order so we compute children before parents
+  const reverseSorted = [...sortedTasks].reverse();
+
+  for (const task of reverseSorted) {
     const cpmTask = taskMap.get(task.id);
-    if (cpmTask) {
-      cpmTask.dependentCount = findDependents(activeTasks, task.id).length;
+    if (!cpmTask) continue;
+
+    const successors = successorIndex.get(task.id) ?? [];
+    // dependentCount = number of direct successors + sum of their dependentCounts
+    let count = successors.length;
+    for (const successor of successors) {
+      count += successor.dependentCount;
     }
+    cpmTask.dependentCount = count;
   }
 }
 
@@ -248,20 +277,23 @@ export function criticalPathAnalysis(tasks: Task[]): CPMResult {
   // Initialize CPM tasks
   const taskMap = initializeCPMTasks(sortedTasks);
 
+  // Build successor index once (O(n*d)) for O(1) lookups
+  const successorIndex = buildSuccessorIndex(sortedTasks, taskMap);
+
   // Forward pass: Calculate earliest start/finish
   forwardPass(sortedTasks, taskMap);
 
   // Calculate project duration
   const projectDuration = calculateProjectDuration(taskMap);
 
-  // Backward pass: Calculate latest start/finish
-  backwardPass(sortedTasks, taskMap, projectDuration);
+  // Backward pass: Calculate latest start/finish (uses successorIndex)
+  backwardPass(sortedTasks, taskMap, successorIndex, projectDuration);
 
   // Calculate slack and mark critical tasks
   calculateSlackAndCritical(taskMap);
 
-  // Count dependents for bottleneck detection
-  countDependents(sortedTasks, activeTasks, taskMap);
+  // Count dependents for bottleneck detection (uses successorIndex, O(n))
+  countDependents(sortedTasks, taskMap, successorIndex);
 
   // Extract critical path
   const criticalPath = extractCriticalPath(sortedTasks, taskMap);

package/src/algorithms/dependency-integrity.ts

@@ -0,0 +1,270 @@
+import type { Task } from "../schemas/task.js";
+import { wouldCreateCycle } from "./topological-sort.js";
+
+/**
+ * Error codes for dependency validation failures
+ */
+export enum DependencyErrorCode {
+  SELF_DEPENDENCY = "SELF_DEPENDENCY",
+  TASK_NOT_FOUND = "TASK_NOT_FOUND",
+  BLOCKER_NOT_FOUND = "BLOCKER_NOT_FOUND",
+  CIRCULAR_DEPENDENCY = "CIRCULAR_DEPENDENCY",
+  DUPLICATE_DEPENDENCY = "DUPLICATE_DEPENDENCY",
+}
+
+/**
+ * Result of dependency validation
+ */
+export interface DependencyValidationResult {
+  valid: boolean;
+  errorCode?: DependencyErrorCode;
+  errorMessage?: string;
+  suggestion?: string;
+}
+
+/**
+ * Options for dependency validation
+ */
+export interface ValidateDependencyOptions {
+  taskId: string;
+  blockedBy: string;
+  tasks: Task[];
+  checkDuplicates?: boolean;
+}
+
+/**
+ * Validates if a dependency can be added between two tasks
+ */
+export function validateDependency(
+  options: ValidateDependencyOptions
+): DependencyValidationResult {
+  const { taskId, blockedBy, tasks, checkDuplicates = true } = options;
+
+  // 1. Self-dependency check
+  if (taskId === blockedBy) {
+    return {
+      valid: false,
+      errorCode: DependencyErrorCode.SELF_DEPENDENCY,
+      errorMessage: `Task "${taskId}" cannot depend on itself`,
+      suggestion: "Specify a different blocker task",
+    };
+  }
+
+  // 2. Task existence check
+  const task = tasks.find((t) => t.id === taskId);
+  if (!task) {
+    return {
+      valid: false,
+      errorCode: DependencyErrorCode.TASK_NOT_FOUND,
+      errorMessage: `Task not found: "${taskId}"`,
+      suggestion: "Use task_list to find available tasks",
+    };
+  }
+
+  // 3. Blocker task existence check
+  const blocker = tasks.find((t) => t.id === blockedBy);
+  if (!blocker) {
+    return {
+      valid: false,
+      errorCode: DependencyErrorCode.BLOCKER_NOT_FOUND,
+      errorMessage: `Blocking task not found: "${blockedBy}"`,
+      suggestion: "Use task_list to find available tasks",
+    };
+  }
+
+  // 4. Duplicate dependency check
+  if (checkDuplicates) {
+    const existingDeps = task.dependencies ?? [];
+    const alreadyExists = existingDeps.some(
+      (d) => d.taskId === blockedBy && d.type === "blocked_by"
+    );
+    if (alreadyExists) {
+      return {
+        valid: false,
+        errorCode: DependencyErrorCode.DUPLICATE_DEPENDENCY,
+        errorMessage: `"${task.title}" is already blocked by "${blocker.title}"`,
+        suggestion: "This dependency already exists",
+      };
+    }
+  }
+
+  // 5. Circular dependency check
+  if (wouldCreateCycle(tasks, taskId, blockedBy)) {
+    return {
+      valid: false,
+      errorCode: DependencyErrorCode.CIRCULAR_DEPENDENCY,
+      errorMessage: "Adding this dependency would create a cycle",
+      suggestion: `"${blocker.title}" depends on "${task.title}". Use dependency_remove to break existing dependencies.`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Invalid dependency reference
+ */
+export interface InvalidDependencyReference {
+  taskId: string;
+  taskTitle: string;
+  invalidDependencyId: string;
+  type: "blocked_by" | "blocks" | "related";
+}
+
+/**
+ * Find all invalid dependency references (orphaned references)
+ */
+export function findInvalidDependencies(
+  tasks: Task[]
+): InvalidDependencyReference[] {
+  const taskIds = new Set(tasks.map((t) => t.id));
+  const invalid: InvalidDependencyReference[] = [];
+
+  for (const task of tasks) {
+    const deps = task.dependencies ?? [];
+    for (const dep of deps) {
+      if (!taskIds.has(dep.taskId)) {
+        invalid.push({
+          taskId: task.id,
+          taskTitle: task.title,
+          invalidDependencyId: dep.taskId,
+          type: dep.type,
+        });
+      }
+    }
+  }
+
+  return invalid;
+}
+
+/**
+ * Find tasks with self-dependencies
+ */
+export function findSelfDependencies(tasks: Task[]): string[] {
+  const selfDeps: string[] = [];
+
+  for (const task of tasks) {
+    const deps = task.dependencies ?? [];
+    if (deps.some((d) => d.taskId === task.id)) {
+      selfDeps.push(task.id);
+    }
+  }
+
+  return selfDeps;
+}
+
+/**
+ * Detect all circular dependency chains
+ */
+export function detectCircularDependencies(tasks: Task[]): string[][] {
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+  const visited = new Set<string>();
+  const recStack = new Set<string>();
+  const cycles: string[][] = [];
+
+  function dfs(taskId: string, path: string[]): void {
+    visited.add(taskId);
+    recStack.add(taskId);
+    path.push(taskId);
+
+    const task = taskMap.get(taskId);
+    if (!task) return;
+
+    const deps = (task.dependencies ?? [])
+      .filter((d) => d.type === "blocked_by")
+      .map((d) => d.taskId);
+
+    for (const depId of deps) {
+      if (!taskMap.has(depId)) continue;
+
+      if (!visited.has(depId)) {
+        dfs(depId, [...path]);
+      } else if (recStack.has(depId)) {
+        const cycleStart = path.indexOf(depId);
+        if (cycleStart !== -1) {
+          const cycle = path.slice(cycleStart);
+          const cycleKey = [...cycle].sort().join(",");
+          const exists = cycles.some(
+            (c) => [...c].sort().join(",") === cycleKey
+          );
+          if (!exists) {
+            cycles.push(cycle);
+          }
+        }
+      }
+    }
+
+    recStack.delete(taskId);
+  }
+
+  for (const task of tasks) {
+    if (!visited.has(task.id)) {
+      dfs(task.id, []);
+    }
+  }
+
+  return cycles;
+}
+
+/**
+ * Comprehensive dependency integrity report
+ */
+export interface DependencyIntegrityReport {
+  valid: boolean;
+  totalTasks: number;
+  totalDependencies: number;
+  issues: {
+    selfDependencies: string[];
+    invalidReferences: InvalidDependencyReference[];
+    circularDependencies: string[][];
+  };
+  summary: string;
+}
+
+/**
+ * Check overall dependency integrity of a project
+ */
+export function checkDependencyIntegrity(
+  tasks: Task[]
+): DependencyIntegrityReport {
+  const selfDeps = findSelfDependencies(tasks);
+  const invalidRefs = findInvalidDependencies(tasks);
+  const cycles = detectCircularDependencies(tasks);
+
+  const totalDependencies = tasks.reduce(
+    (sum, t) => sum + (t.dependencies?.length ?? 0),
+    0
+  );
+
+  const issueCount = selfDeps.length + invalidRefs.length + cycles.length;
+  const valid = issueCount === 0;
+
+  let summary: string;
+  if (valid) {
+    summary = `All ${totalDependencies} dependencies across ${tasks.length} tasks are valid.`;
+  } else {
+    const parts: string[] = [];
+    if (selfDeps.length > 0) {
+      parts.push(`${selfDeps.length} self-dependencies`);
+    }
+    if (invalidRefs.length > 0) {
+      parts.push(`${invalidRefs.length} invalid references`);
+    }
+    if (cycles.length > 0) {
+      parts.push(`${cycles.length} circular dependency chains`);
+    }
+    summary = `Found ${issueCount} issue(s): ${parts.join(", ")}.`;
+  }
+
+  return {
+    valid,
+    totalTasks: tasks.length,
+    totalDependencies,
+    issues: {
+      selfDependencies: selfDeps,
+      invalidReferences: invalidRefs,
+      circularDependencies: cycles,
+    },
+    summary,
+  };
+}

package/src/algorithms/index.ts

@@ -15,3 +15,31 @@ export {
   type CPMTask,
   type CPMResult,
 } from "./critical-path.js";
+
+export {
+  suggestSafeOrder,
+  findBreakingChanges,
+  findHighRiskTasks,
+  groupByTechArea,
+  getComplexitySummary,
+  getTechStackSummary,
+  suggestSubtaskCount,
+  type SafeOrderResult,
+  type SafeOrderPhase,
+  type ComplexityDistribution,
+  type ComplexitySummary,
+  type TechStackSummary,
+} from "./tech-analysis.js";
+
+export {
+  validateDependency,
+  findInvalidDependencies,
+  findSelfDependencies,
+  detectCircularDependencies,
+  checkDependencyIntegrity,
+  DependencyErrorCode,
+  type DependencyValidationResult,
+  type ValidateDependencyOptions,
+  type InvalidDependencyReference,
+  type DependencyIntegrityReport,
+} from "./dependency-integrity.js";