@task-mcp/shared 0.1.0

package/src/algorithms/critical-path.ts

@@ -0,0 +1,413 @@
+import type { Task } from "../schemas/task.js";
+import { topologicalSort, findDependents } from "./topological-sort.js";
+
+/**
+ * Task with computed CPM (Critical Path Method) values
+ */
+export interface CPMTask extends Task {
+  // Computed values
+  earliestStart: number; // Minutes from project start
+  earliestFinish: number;
+  latestStart: number;
+  latestFinish: number;
+  slack: number; // Float time
+  isCritical: boolean; // On critical path if slack === 0
+  dependentCount: number; // Number of tasks blocked by this
+}
+
+/**
+ * Result of critical path analysis
+ */
+export interface CPMResult {
+  tasks: CPMTask[];
+  criticalPath: CPMTask[]; // Tasks on the critical path, in order
+  projectDuration: number; // Total project duration in minutes
+  bottlenecks: CPMTask[]; // Critical tasks that block the most downstream work
+}
+
+/** Default task duration if no estimate provided */
+const DEFAULT_DURATION = 30;
+
+/**
+ * Get task duration with fallback to default
+ */
+function getTaskDuration(task: Task): number {
+  return task.estimate?.expected ?? DEFAULT_DURATION;
+}
+
+/**
+ * Get blocked_by dependencies for a task
+ */
+function getBlockedByDeps(task: Task): string[] {
+  return (task.dependencies ?? [])
+    .filter((d) => d.type === "blocked_by")
+    .map((d) => d.taskId);
+}
+
+/**
+ * Initialize CPM tasks with default values
+ */
+function initializeCPMTasks(sortedTasks: Task[]): Map<string, CPMTask> {
+  const taskMap = new Map<string, CPMTask>();
+
+  for (const task of sortedTasks) {
+    const duration = getTaskDuration(task);
+    taskMap.set(task.id, {
+      ...task,
+      earliestStart: 0,
+      earliestFinish: duration,
+      latestStart: Infinity,
+      latestFinish: Infinity,
+      slack: 0,
+      isCritical: false,
+      dependentCount: 0,
+    });
+  }
+
+  return taskMap;
+}
+
+/**
+ * Forward pass: Calculate earliest start/finish times
+ * ES = max(EF of all predecessors)
+ * EF = ES + duration
+ */
+function forwardPass(sortedTasks: Task[], taskMap: Map<string, CPMTask>): void {
+  for (const task of sortedTasks) {
+    const cpmTask = taskMap.get(task.id);
+    if (!cpmTask) continue;
+
+    const duration = getTaskDuration(task);
+    const deps = getBlockedByDeps(task);
+
+    // Find maximum EF among predecessors
+    let maxPredecessorEF = 0;
+    for (const depId of deps) {
+      const dep = taskMap.get(depId);
+      if (dep) {
+        maxPredecessorEF = Math.max(maxPredecessorEF, dep.earliestFinish);
+      }
+    }
+
+    cpmTask.earliestStart = maxPredecessorEF;
+    cpmTask.earliestFinish = cpmTask.earliestStart + duration;
+  }
+}
+
+/**
+ * Calculate project duration (maximum earliest finish)
+ */
+function calculateProjectDuration(taskMap: Map<string, CPMTask>): number {
+  return Math.max(...Array.from(taskMap.values()).map((t) => t.earliestFinish));
+}
+
+/**
+ * Find tasks that have successors (are dependencies of other tasks)
+ */
+function findTasksWithSuccessors(sortedTasks: Task[]): Set<string> {
+  const tasksWithSuccessors = new Set<string>();
+
+  for (const task of sortedTasks) {
+    const deps = getBlockedByDeps(task);
+    for (const depId of deps) {
+      tasksWithSuccessors.add(depId);
+    }
+  }
+
+  return tasksWithSuccessors;
+}
+
+/**
+ * Find successor tasks (tasks that depend on a given task)
+ */
+function findSuccessors(taskId: string, taskMap: Map<string, CPMTask>): CPMTask[] {
+  const successors: CPMTask[] = [];
+
+  for (const other of taskMap.values()) {
+    const otherDeps = getBlockedByDeps(other);
+    if (otherDeps.includes(taskId)) {
+      successors.push(other);
+    }
+  }
+
+  return successors;
+}
+
+/**
+ * Backward pass: Calculate latest start/finish times
+ * LF = min(LS of all successors) or projectDuration for end tasks
+ * LS = LF - duration
+ */
+function backwardPass(
+  sortedTasks: Task[],
+  taskMap: Map<string, CPMTask>,
+  projectDuration: number
+): void {
+  const tasksWithSuccessors = findTasksWithSuccessors(sortedTasks);
+
+  // Initialize end tasks (tasks with no successors)
+  for (const task of taskMap.values()) {
+    if (!tasksWithSuccessors.has(task.id)) {
+      const duration = getTaskDuration(task);
+      task.latestFinish = projectDuration;
+      task.latestStart = task.latestFinish - duration;
+    }
+  }
+
+  // Process in reverse topological order
+  const reverseSorted = [...sortedTasks].reverse();
+
+  for (const task of reverseSorted) {
+    const cpmTask = taskMap.get(task.id);
+    if (!cpmTask) continue;
+
+    const duration = getTaskDuration(task);
+    const successors = findSuccessors(task.id, taskMap);
+
+    if (successors.length > 0) {
+      // LF = min(LS of all successors)
+      cpmTask.latestFinish = Math.min(...successors.map((s) => s.latestStart));
+      cpmTask.latestStart = cpmTask.latestFinish - duration;
+    }
+  }
+}
+
+/**
+ * Calculate slack and mark critical tasks
+ * Slack = LS - ES (or LF - EF)
+ * Critical = slack ≈ 0
+ */
+function calculateSlackAndCritical(taskMap: Map<string, CPMTask>): void {
+  const FLOAT_TOLERANCE = 0.001;
+
+  for (const task of taskMap.values()) {
+    task.slack = task.latestStart - task.earliestStart;
+    task.isCritical = Math.abs(task.slack) < FLOAT_TOLERANCE;
+  }
+}
+
+/**
+ * Count dependents for bottleneck detection
+ */
+function countDependents(sortedTasks: Task[], activeTasks: Task[], taskMap: Map<string, CPMTask>): void {
+  for (const task of sortedTasks) {
+    const cpmTask = taskMap.get(task.id);
+    if (cpmTask) {
+      cpmTask.dependentCount = findDependents(activeTasks, task.id).length;
+    }
+  }
+}
+
+/**
+ * Extract critical path tasks in topological order
+ */
+function extractCriticalPath(sortedTasks: Task[], taskMap: Map<string, CPMTask>): CPMTask[] {
+  return sortedTasks
+    .map((t) => taskMap.get(t.id))
+    .filter((t): t is CPMTask => t !== undefined && t.isCritical);
+}
+
+/**
+ * Find top bottlenecks (critical tasks blocking the most downstream work)
+ */
+function findBottlenecks(criticalPath: CPMTask[], limit = 5): CPMTask[] {
+  return [...criticalPath]
+    .sort((a, b) => b.dependentCount - a.dependentCount)
+    .slice(0, limit);
+}
+
+/**
+ * Perform Critical Path Method analysis
+ *
+ * CPM calculates:
+ * - Earliest Start (ES): Earliest a task can start
+ * - Earliest Finish (EF): ES + duration
+ * - Latest Finish (LF): Latest a task can finish without delaying project
+ * - Latest Start (LS): LF - duration
+ * - Slack: LS - ES (or LF - EF)
+ * - Critical Path: Tasks with slack = 0
+ */
+export function criticalPathAnalysis(tasks: Task[]): CPMResult {
+  // Filter to only pending/in_progress tasks
+  const activeTasks = tasks.filter(
+    (t) => t.status === "pending" || t.status === "in_progress"
+  );
+
+  if (activeTasks.length === 0) {
+    return {
+      tasks: [],
+      criticalPath: [],
+      projectDuration: 0,
+      bottlenecks: [],
+    };
+  }
+
+  // Sort topologically
+  const sortedTasks = topologicalSort(activeTasks);
+
+  // Initialize CPM tasks
+  const taskMap = initializeCPMTasks(sortedTasks);
+
+  // 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);
+
+  // Calculate slack and mark critical tasks
+  calculateSlackAndCritical(taskMap);
+
+  // Count dependents for bottleneck detection
+  countDependents(sortedTasks, activeTasks, taskMap);
+
+  // Extract critical path
+  const criticalPath = extractCriticalPath(sortedTasks, taskMap);
+
+  // Find bottlenecks
+  const bottlenecks = findBottlenecks(criticalPath);
+
+  return {
+    tasks: sortedTasks.map((t) => taskMap.get(t.id)!),
+    criticalPath,
+    projectDuration,
+    bottlenecks,
+  };
+}
+
+/**
+ * Find tasks that can be executed in parallel (no dependencies between them)
+ */
+export function findParallelTasks(tasks: Task[]): Task[][] {
+  const activeTasks = tasks.filter(
+    (t) => t.status === "pending" || t.status === "in_progress"
+  );
+
+  if (activeTasks.length === 0) return [];
+
+  // Find tasks with no uncompleted dependencies
+  const completedIds = new Set(
+    tasks.filter((t) => t.status === "completed").map((t) => t.id)
+  );
+
+  const available = activeTasks.filter((task) => {
+    const deps = getBlockedByDeps(task);
+    return deps.every((depId) => completedIds.has(depId));
+  });
+
+  if (available.length <= 1) return [available];
+
+  // Group tasks that don't depend on each other
+  const groups: Task[][] = [];
+  const processed = new Set<string>();
+
+  for (const task of available) {
+    if (processed.has(task.id)) continue;
+
+    const group: Task[] = [task];
+    processed.add(task.id);
+
+    for (const other of available) {
+      if (processed.has(other.id)) continue;
+
+      // Check if these tasks are independent
+      const taskDeps = (task.dependencies ?? []).map((d) => d.taskId);
+      const otherDeps = (other.dependencies ?? []).map((d) => d.taskId);
+
+      const independent =
+        !taskDeps.includes(other.id) && !otherDeps.includes(task.id);
+
+      if (independent) {
+        group.push(other);
+        processed.add(other.id);
+      }
+    }
+
+    groups.push(group);
+  }
+
+  return groups;
+}
+
+/**
+ * Suggest the next best task to work on
+ */
+export function suggestNextTask(
+  tasks: Task[],
+  options: {
+    contexts?: string[];
+    maxMinutes?: number;
+  } = {}
+): Task | null {
+  const activeTasks = tasks.filter(
+    (t) => t.status === "pending" || t.status === "in_progress"
+  );
+
+  if (activeTasks.length === 0) return null;
+
+  // Get CPM analysis
+  const cpm = criticalPathAnalysis(tasks);
+
+  // Filter by availability (all dependencies completed)
+  const completedIds = new Set(
+    tasks.filter((t) => t.status === "completed").map((t) => t.id)
+  );
+
+  let candidates = cpm.tasks.filter((task) => {
+    const deps = getBlockedByDeps(task);
+    return deps.every((depId) => completedIds.has(depId));
+  });
+
+  // Filter by context if specified
+  if (options.contexts?.length) {
+    const contextSet = new Set(options.contexts);
+    const contextFiltered = candidates.filter((t) =>
+      (t.contexts ?? []).some((c) => contextSet.has(c))
+    );
+    if (contextFiltered.length > 0) {
+      candidates = contextFiltered;
+    }
+  }
+
+  // Filter by time if specified
+  if (options.maxMinutes) {
+    const timeFiltered = candidates.filter(
+      (t) => getTaskDuration(t) <= options.maxMinutes!
+    );
+    if (timeFiltered.length > 0) {
+      candidates = timeFiltered;
+    }
+  }
+
+  if (candidates.length === 0) return null;
+
+  // Score and rank candidates
+  // Priority: Critical path > High priority > Most dependents > Shortest duration
+  const scored = candidates.map((task) => {
+    let score = 0;
+    if (task.isCritical) score += 1000;
+    score += task.dependentCount * 100;
+    score += priorityScore(task.priority) * 10;
+    // Prefer shorter tasks (quick wins)
+    score += Math.max(0, 100 - getTaskDuration(task));
+    return { task, score };
+  });
+
+  scored.sort((a, b) => b.score - a.score);
+  return scored[0]?.task ?? null;
+}
+
+/**
+ * Convert priority to numeric score
+ */
+function priorityScore(priority: string): number {
+  const scores: Record<string, number> = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+  };
+  return scores[priority] ?? 2;
+}

package/src/algorithms/index.ts

@@ -0,0 +1,17 @@
+export {
+  topologicalSort,
+  wouldCreateCycle,
+  findDependents,
+  findDependencies,
+  priorityToNumber,
+  taskToNode,
+  type TaskNode,
+} from "./topological-sort.js";
+
+export {
+  criticalPathAnalysis,
+  findParallelTasks,
+  suggestNextTask,
+  type CPMTask,
+  type CPMResult,
+} from "./critical-path.js";

package/src/algorithms/topological-sort.test.ts

@@ -0,0 +1,190 @@
+import { describe, test, expect } from "bun:test";
+import {
+  priorityToNumber,
+  topologicalSort,
+  wouldCreateCycle,
+  findDependents,
+  findDependencies,
+} from "./topological-sort.js";
+import type { Task } from "../schemas/task.js";
+
+// Helper to create mock tasks
+function createTask(id: string, priority: string = "medium", deps: string[] = []): Task {
+  return {
+    id,
+    title: `Task ${id}`,
+    status: "pending",
+    priority: priority as Task["priority"],
+    projectId: "test-project",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    dependencies: deps.map((depId) => ({ taskId: depId, type: "blocked_by" as const })),
+  };
+}
+
+describe("priorityToNumber", () => {
+  test("converts critical to 4", () => {
+    expect(priorityToNumber("critical")).toBe(4);
+  });
+
+  test("converts high to 3", () => {
+    expect(priorityToNumber("high")).toBe(3);
+  });
+
+  test("converts medium to 2", () => {
+    expect(priorityToNumber("medium")).toBe(2);
+  });
+
+  test("converts low to 1", () => {
+    expect(priorityToNumber("low")).toBe(1);
+  });
+
+  test("defaults to 2 for unknown priority", () => {
+    expect(priorityToNumber("unknown")).toBe(2);
+  });
+});
+
+describe("topologicalSort", () => {
+  test("returns empty array for empty input", () => {
+    const result = topologicalSort([]);
+    expect(result).toEqual([]);
+  });
+
+  test("returns single task unchanged", () => {
+    const tasks = [createTask("A")];
+    const result = topologicalSort(tasks);
+    expect(result.length).toBe(1);
+    expect(result[0]!.id).toBe("A");
+  });
+
+  test("sorts by dependency order", () => {
+    // B depends on A, so A should come first
+    const tasks = [createTask("B", "high", ["A"]), createTask("A", "low")];
+    const result = topologicalSort(tasks);
+    expect(result[0]!.id).toBe("A");
+    expect(result[1]!.id).toBe("B");
+  });
+
+  test("respects priority when no dependencies", () => {
+    const tasks = [
+      createTask("A", "low"),
+      createTask("B", "critical"),
+      createTask("C", "high"),
+    ];
+    const result = topologicalSort(tasks);
+    expect(result[0]!.id).toBe("B"); // critical first
+    expect(result[1]!.id).toBe("C"); // then high
+    expect(result[2]!.id).toBe("A"); // then low
+  });
+
+  test("handles chain of dependencies", () => {
+    // C -> B -> A (C depends on B, B depends on A)
+    const tasks = [
+      createTask("C", "critical", ["B"]),
+      createTask("B", "high", ["A"]),
+      createTask("A", "low"),
+    ];
+    const result = topologicalSort(tasks);
+    expect(result.map((t) => t.id)).toEqual(["A", "B", "C"]);
+  });
+
+  test("throws on circular dependency", () => {
+    // A -> B -> A
+    const tasks = [createTask("A", "medium", ["B"]), createTask("B", "medium", ["A"])];
+    expect(() => topologicalSort(tasks)).toThrow(/Circular dependency/);
+  });
+
+  test("handles diamond dependency", () => {
+    // D depends on B and C, both depend on A
+    const tasks = [
+      createTask("D", "medium", ["B", "C"]),
+      createTask("B", "high", ["A"]),
+      createTask("C", "low", ["A"]),
+      createTask("A", "medium"),
+    ];
+    const result = topologicalSort(tasks);
+    // A must come first, D must come last
+    expect(result[0]!.id).toBe("A");
+    expect(result[3]!.id).toBe("D");
+  });
+});
+
+describe("wouldCreateCycle", () => {
+  test("returns false for valid dependency", () => {
+    const tasks = [createTask("A"), createTask("B")];
+    // Adding B blocked_by A should not create cycle
+    expect(wouldCreateCycle(tasks, "B", "A")).toBe(false);
+  });
+
+  test("returns true for direct cycle", () => {
+    const tasks = [createTask("A", "medium", ["B"]), createTask("B")];
+    // B is already blocking A, so A blocking B would create cycle
+    expect(wouldCreateCycle(tasks, "B", "A")).toBe(true);
+  });
+
+  test("returns true for indirect cycle", () => {
+    const tasks = [
+      createTask("A", "medium", ["B"]),
+      createTask("B", "medium", ["C"]),
+      createTask("C"),
+    ];
+    // A <- B <- C, adding C <- A would create cycle
+    expect(wouldCreateCycle(tasks, "C", "A")).toBe(true);
+  });
+});
+
+describe("findDependents", () => {
+  test("returns empty for task with no dependents", () => {
+    const tasks = [createTask("A"), createTask("B")];
+    const result = findDependents(tasks, "A");
+    expect(result).toEqual([]);
+  });
+
+  test("finds direct dependents", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "medium", ["A"]),
+      createTask("C", "medium", ["A"]),
+    ];
+    const result = findDependents(tasks, "A");
+    expect(result.map((t) => t.id).sort()).toEqual(["B", "C"]);
+  });
+
+  test("finds transitive dependents", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "medium", ["A"]),
+      createTask("C", "medium", ["B"]),
+    ];
+    const result = findDependents(tasks, "A");
+    expect(result.map((t) => t.id).sort()).toEqual(["B", "C"]);
+  });
+});
+
+describe("findDependencies", () => {
+  test("returns empty for task with no dependencies", () => {
+    const tasks = [createTask("A"), createTask("B")];
+    const result = findDependencies(tasks, "A");
+    expect(result).toEqual([]);
+  });
+
+  test("finds direct dependencies", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B"),
+      createTask("C", "medium", ["A", "B"]),
+    ];
+    const result = findDependencies(tasks, "C");
+    expect(result.map((t) => t.id).sort()).toEqual(["A", "B"]);
+  });
+
+  test("finds transitive dependencies", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "medium", ["A"]),
+      createTask("C", "medium", ["B"]),
+    ];
+    const result = findDependencies(tasks, "C");
+    expect(result.map((t) => t.id).sort()).toEqual(["A", "B"]);
+  });
+});