@critical-path/core 0.15.2 → 0.17.0

package/src/domain/cpm.ts

@@ -0,0 +1,215 @@
+import type {
+  Task,
+  TaskDependency,
+  TaskCriticalPathSchedule,
+  CriticalPathAnalysis
+} from '../types/index.js';
+
+export function getTaskDurationHours(task: Task): number {
+  if (typeof task.estimatedHours === 'number' && task.estimatedHours >= 0) {
+    return task.estimatedHours;
+  }
+  if (typeof task.estimatedDurationMinutes === 'number' && task.estimatedDurationMinutes >= 0) {
+    return task.estimatedDurationMinutes / 60;
+  }
+  if (typeof task.actualHours === 'number' && task.actualHours > 0) {
+    return task.actualHours;
+  }
+  // Default to 1 hour for non-empty tasks without explicit estimate
+  return 1;
+}
+
+/**
+ * Calculates the Critical Path Method (CPM) schedule for a set of tasks and their dependencies.
+ * - Forward Pass: computes earlyStart and earlyFinish
+ * - Backward Pass: computes lateStart, lateFinish, and totalSlack
+ * - Identifies critical tasks (totalSlack === 0) that dictate the minimum project duration.
+ */
+export function calculateCPM(
+  projectId: string,
+  tasks: Task[],
+  dependencies: TaskDependency[]
+): CriticalPathAnalysis {
+  const calculatedAt = new Date().toISOString();
+
+  if (tasks.length === 0) {
+    return {
+      projectId,
+      calculatedAt,
+      totalDurationHours: 0,
+      criticalTaskIds: [],
+      tasks: []
+    };
+  }
+
+  const taskMap = new Map<string, Task>(tasks.map((t) => [t.id, t]));
+  const taskIds = Array.from(taskMap.keys());
+
+  // Build adjacency graph:
+  // prerequisites[v] = tasks that v depends on (must finish before v starts)
+  // successors[u] = tasks that depend on u (can only start after u finishes)
+  const prerequisites = new Map<string, Set<string>>();
+  const successors = new Map<string, Set<string>>();
+
+  for (const id of taskIds) {
+    prerequisites.set(id, new Set<string>());
+    successors.set(id, new Set<string>());
+  }
+
+  for (const dep of dependencies) {
+    let sourceId: string | null = null;
+    let targetId: string | null = null;
+
+    if (dep.type === 'blocking') {
+      // taskId depends on dependsOnTaskId (dependsOnTaskId -> taskId)
+      sourceId = dep.dependsOnTaskId;
+      targetId = dep.taskId;
+    } else if (dep.type === 'blocked_by') {
+      // dependsOnTaskId is blocked by taskId (taskId -> dependsOnTaskId)
+      sourceId = dep.taskId;
+      targetId = dep.dependsOnTaskId;
+    }
+
+    if (sourceId && targetId && taskMap.has(sourceId) && taskMap.has(targetId) && sourceId !== targetId) {
+      prerequisites.get(targetId)!.add(sourceId);
+      successors.get(sourceId)!.add(targetId);
+    }
+  }
+
+  // Topological sorting via Kahn's algorithm
+  const inDegree = new Map<string, number>();
+  for (const id of taskIds) {
+    inDegree.set(id, prerequisites.get(id)!.size);
+  }
+
+  const queue: string[] = [];
+  for (const [id, deg] of inDegree.entries()) {
+    if (deg === 0) {
+      queue.push(id);
+    }
+  }
+
+  const topoOrder: string[] = [];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    topoOrder.push(current);
+
+    for (const next of successors.get(current)!) {
+      const updatedDeg = inDegree.get(next)! - 1;
+      inDegree.set(next, updatedDeg);
+      if (updatedDeg === 0) {
+        queue.push(next);
+      }
+    }
+  }
+
+  // If there's a cycle or disconnected nodes not processed in topoOrder, append them
+  if (topoOrder.length < taskIds.length) {
+    for (const id of taskIds) {
+      if (!topoOrder.includes(id)) {
+        topoOrder.push(id);
+      }
+    }
+  }
+
+  // --- FORWARD PASS ---
+  const earlyStart = new Map<string, number>();
+  const earlyFinish = new Map<string, number>();
+
+  for (const id of topoOrder) {
+    const task = taskMap.get(id)!;
+    const duration = getTaskDurationHours(task);
+    const prereqs = prerequisites.get(id) || new Set();
+
+    let maxPrereqFinish = 0;
+    for (const p of prereqs) {
+      const pFinish = earlyFinish.get(p) ?? 0;
+      if (pFinish > maxPrereqFinish) {
+        maxPrereqFinish = pFinish;
+      }
+    }
+
+    const es = maxPrereqFinish;
+    const ef = es + duration;
+
+    earlyStart.set(id, es);
+    earlyFinish.set(id, ef);
+  }
+
+  // Total project duration
+  let totalDurationHours = 0;
+  for (const ef of earlyFinish.values()) {
+    if (ef > totalDurationHours) {
+      totalDurationHours = ef;
+    }
+  }
+
+  // --- BACKWARD PASS ---
+  const lateStart = new Map<string, number>();
+  const lateFinish = new Map<string, number>();
+
+  // Process in reverse topological order
+  for (let i = topoOrder.length - 1; i >= 0; i--) {
+    const id = topoOrder[i];
+    const task = taskMap.get(id)!;
+    const duration = getTaskDurationHours(task);
+    const succs = successors.get(id) || new Set();
+
+    let minSuccLateStart = totalDurationHours;
+    if (succs.size > 0) {
+      minSuccLateStart = Infinity;
+      for (const s of succs) {
+        const sLateStart = lateStart.get(s);
+        if (sLateStart !== undefined && sLateStart < minSuccLateStart) {
+          minSuccLateStart = sLateStart;
+        }
+      }
+      if (!Number.isFinite(minSuccLateStart)) {
+        minSuccLateStart = totalDurationHours;
+      }
+    }
+
+    const lf = minSuccLateStart;
+    const ls = lf - duration;
+
+    lateFinish.set(id, lf);
+    lateStart.set(id, ls);
+  }
+
+  // --- SLACK & CRITICAL PATH ---
+  const schedules: TaskCriticalPathSchedule[] = [];
+  const criticalTaskIds: string[] = [];
+
+  for (const id of taskIds) {
+    const es = earlyStart.get(id) ?? 0;
+    const ef = earlyFinish.get(id) ?? 0;
+    const ls = lateStart.get(id) ?? 0;
+    const lf = lateFinish.get(id) ?? 0;
+
+    const rawSlack = lf - ef;
+    const totalSlack = Math.round(rawSlack * 100) / 100;
+    const isCritical = totalSlack <= 0.001;
+
+    if (isCritical) {
+      criticalTaskIds.push(id);
+    }
+
+    schedules.push({
+      taskId: id,
+      earlyStart: Math.round(es * 100) / 100,
+      earlyFinish: Math.round(ef * 100) / 100,
+      lateStart: Math.round(ls * 100) / 100,
+      lateFinish: Math.round(lf * 100) / 100,
+      totalSlack,
+      isCritical
+    });
+  }
+
+  return {
+    projectId,
+    calculatedAt,
+    totalDurationHours: Math.round(totalDurationHours * 100) / 100,
+    criticalTaskIds,
+    tasks: schedules
+  };
+}

package/src/domain/entities.ts

@@ -189,6 +189,12 @@ export class TaskEntity extends BaseEntity {
     const statusDef = resolveStatusDefinition(newStatus, options?.statusDefs || workflow?.statuses);
     this.semanticStatus = statusDef.category;
 
+    const prevStatusDef = resolveStatusDefinition(previousStatus, options?.statusDefs || workflow?.statuses);
+    if ((prevStatusDef.category === 'completed' || prevStatusDef.category === 'canceled') &&
+        (statusDef.category === 'in_progress' || statusDef.category === 'not_started')) {
+      this.actualEndDate = undefined;
+    }
+
     if (statusDef.category === 'in_progress' && !this.actualStartDate) {
       this.actualStartDate = now;
     }

package/src/domain/index.ts

@@ -2,3 +2,7 @@ export * from './events.js';
 export * from './custom-fields.js';
 export * from './graph.js';
 export * from './entities.js';
+export * from './cpm.js';
+export * from './ladder.js';
+export * from './metrics.js';
+

package/src/domain/ladder.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect } from 'vitest';
+import { CriticalPathEngine } from '../engine/index.js';
+import {
+  aggregateConcreteEvidenceForTask,
+  computeMacroPhases,
+  buildTimelineLadder
+} from './ladder.js';
+import type { Task, TaskContainer, Attachment, Deliverable, TimeEntry } from '../types/index.js';
+
+describe('Ladder of Abstraction Domain Logic', () => {
+  const now = '2026-09-11T10:00:00.000Z';
+
+  it('aggregates concrete evidence, daily effort distribution, and reality delta for a task', () => {
+    const task: Task = {
+      id: 'task-design',
+      projectId: 'proj-1',
+      title: 'Design Checkout Flow',
+      status: 'in_progress',
+      semanticStatus: 'in_progress',
+      priority: 'high',
+      plannedStartDate: '2026-09-01T09:00:00.000Z',
+      actualStartDate: '2026-09-02T10:00:00.000Z',
+      dueDate: '2026-09-15T18:00:00.000Z',
+      estimatedHours: 20,
+      todos: [
+        { id: 'todo-1', title: 'Sketch wireframes', completed: true, completedAt: '2026-09-03T12:00:00.000Z' },
+        { id: 'todo-2', title: 'Component specs', completed: false }
+      ],
+      createdAt: now,
+      updatedAt: now
+    };
+
+    const attachments: Attachment[] = [
+      {
+        id: 'att-1',
+        taskId: 'task-design',
+        uploaderId: 'user-1',
+        filename: 'checkout_mockup.png',
+        mimeType: 'image/png',
+        sizeBytes: 204800,
+        url: 'https://cdn.example.com/checkout_mockup.png',
+        artifactType: 'deliverable',
+        createdAt: now,
+        updatedAt: now
+      }
+    ];
+
+    const deliverables: Deliverable[] = [
+      {
+        id: 'deliv-1',
+        projectId: 'proj-1',
+        title: 'Checkout Prototype',
+        status: 'in_production',
+        format: 'Figma',
+        outputUrls: ['https://figma.com/file/12345'],
+        createdAt: now,
+        updatedAt: now
+      }
+    ];
+    task.deliverableId = 'deliv-1';
+
+    const timeEntries: TimeEntry[] = [
+      { id: 'te-1', taskId: 'task-design', userId: 'user-1', hours: 4, loggedAt: '2026-09-02T16:00:00.000Z' },
+      { id: 'te-2', taskId: 'task-design', userId: 'user-1', hours: 6, loggedAt: '2026-09-03T17:00:00.000Z' },
+      { id: 'te-3', taskId: 'task-design', userId: 'user-1', hours: 3, loggedAt: '2026-09-03T19:00:00.000Z' }
+    ];
+
+    const evidence = aggregateConcreteEvidenceForTask(
+      task,
+      attachments,
+      deliverables,
+      timeEntries,
+      []
+    );
+
+    expect(evidence.taskId).toBe('task-design');
+    expect(evidence.attachments).toHaveLength(1);
+    expect(evidence.deliverables).toHaveLength(1);
+    expect(evidence.todos).toHaveLength(2);
+    expect(evidence.timeEntries).toHaveLength(3);
+
+    // Check daily effort distribution (aggregated by day)
+    expect(evidence.dailyEffortDistribution).toEqual([
+      { date: '2026-09-02', hours: 4 },
+      { date: '2026-09-03', hours: 9 } // 6 + 3
+    ]);
+
+    // Evidence summary
+    expect(evidence.evidenceSummary.attachmentCount).toBe(1);
+    expect(evidence.evidenceSummary.deliverableCount).toBe(1);
+    expect(evidence.evidenceSummary.completedTodoCount).toBe(1);
+    expect(evidence.evidenceSummary.totalLoggedHours).toBe(13);
+    expect(evidence.evidenceSummary.hasVisualAsset).toBe(true);
+
+    // Reality delta
+    expect(evidence.realityDelta.plannedStartDate).toBe('2026-09-01T09:00:00.000Z');
+    expect(evidence.realityDelta.actualStartDate).toBe('2026-09-02T10:00:00.000Z');
+    expect(evidence.realityDelta.estimatedHours).toBe(20);
+    expect(evidence.realityDelta.loggedHours).toBe(13);
+    expect(evidence.realityDelta.varianceHours).toBe(-7); // Under budget by 7h
+    expect(evidence.realityDelta.isOverEstimate).toBe(false);
+  });
+
+  it('computes macro phase rollups across containers with dates and progress weighting', () => {
+    const containers: TaskContainer[] = [
+      { id: 'c-research', projectId: 'p1', name: 'Research Phase', createdAt: now, updatedAt: now },
+      { id: 'c-dev', projectId: 'p1', name: 'Development Phase', createdAt: now, updatedAt: now }
+    ];
+
+    const tasks: Task[] = [
+      {
+        id: 't-1',
+        projectId: 'p1',
+        containerId: 'c-research',
+        title: 'User Interviews',
+        status: 'done',
+        semanticStatus: 'completed',
+        priority: 'medium',
+        progress: 100,
+        plannedStartDate: '2026-09-01',
+        dueDate: '2026-09-05',
+        estimatedHours: 10,
+        loggedHours: 10,
+        createdAt: now,
+        updatedAt: now
+      },
+      {
+        id: 't-2',
+        projectId: 'p1',
+        containerId: 'c-dev',
+        title: 'API Setup',
+        status: 'in_progress',
+        semanticStatus: 'in_progress',
+        priority: 'high',
+        progress: 50,
+        plannedStartDate: '2026-09-06',
+        dueDate: '2026-09-20',
+        estimatedHours: 40,
+        loggedHours: 20,
+        createdAt: now,
+        updatedAt: now
+      }
+    ];
+
+    const criticalTaskIds = new Set(['t-2']);
+    const phases = computeMacroPhases(tasks, containers, [], criticalTaskIds);
+
+    expect(phases).toHaveLength(2);
+
+    const researchPhase = phases.find((p) => p.id === 'c-research')!;
+    expect(researchPhase.name).toBe('Research Phase');
+    expect(researchPhase.startDate).toBe('2026-09-01');
+    expect(researchPhase.endDate).toBe('2026-09-05');
+    expect(researchPhase.progressPercentage).toBe(100);
+    expect(researchPhase.health).toBe('completed');
+    expect(researchPhase.isCritical).toBe(false);
+
+    const devPhase = phases.find((p) => p.id === 'c-dev')!;
+    expect(devPhase.name).toBe('Development Phase');
+    expect(devPhase.startDate).toBe('2026-09-06');
+    expect(devPhase.endDate).toBe('2026-09-20');
+    expect(devPhase.progressPercentage).toBe(50);
+    expect(devPhase.isCritical).toBe(true);
+    expect(devPhase.criticalTaskCount).toBe(1);
+  });
+
+  it('integrates seamlessly with CriticalPathEngine APIs', async () => {
+    const engine = new CriticalPathEngine();
+    const project = await engine.createProject({ name: 'Timeline Ladder Project' });
+
+    const c1 = await engine.store.createContainer({
+      projectId: project.id,
+      name: 'Phase 1: Design'
+    });
+
+    const t1 = await engine.createTask({
+      projectId: project.id,
+      containerId: c1.id,
+      title: 'Wireframes',
+      status: 'done',
+      estimatedHours: 5,
+      progress: 100,
+      plannedStartDate: '2026-09-01',
+      dueDate: '2026-09-05'
+    });
+
+    const t2 = await engine.createTask({
+      projectId: project.id,
+      containerId: c1.id,
+      title: 'Visual Assets',
+      status: 'in_progress',
+      estimatedHours: 15,
+      progress: 30,
+      plannedStartDate: '2026-09-06',
+      dueDate: '2026-09-12'
+    });
+
+    await engine.addDependency({
+      taskId: t2.id,
+      dependsOnTaskId: t1.id,
+      type: 'blocking'
+    });
+
+    await engine.logTime({
+      taskId: t2.id,
+      userId: 'designer-1',
+      hours: 4.5,
+      loggedAt: '2026-09-07T12:00:00Z'
+    });
+
+    // 1. Calculate CPM
+    const cpmAnalysis = await engine.calculateCriticalPath(project.id);
+    expect(cpmAnalysis.totalDurationHours).toBe(20);
+    expect(cpmAnalysis.criticalTaskIds).toEqual([t1.id, t2.id]);
+
+    // 2. Query full Timeline Ladder
+    const ladder = await engine.getTimelineLadder(project.id);
+    expect(ladder.macro).toBeDefined();
+    expect(ladder.macro?.projectName).toBe('Timeline Ladder Project');
+    expect(ladder.macro?.criticalPathDurationHours).toBe(20);
+    expect(ladder.macro?.phases).toHaveLength(1);
+    expect(ladder.macro?.phases[0].name).toBe('Phase 1: Design');
+
+    expect(ladder.standard).toBeDefined();
+    expect(ladder.standard?.tasks).toHaveLength(2);
+    const standardT2 = ladder.standard?.tasks.find((t) => t.id === t2.id)!;
+    expect(standardT2.cpm?.earlyStart).toBe(5);
+    expect(standardT2.cpm?.earlyFinish).toBe(20);
+    expect(standardT2.blockingTaskIds).toEqual([t1.id]);
+    expect(standardT2.concreteEvidenceSummary.timeEntryCount).toBe(1);
+
+    expect(ladder.concrete).toBeDefined();
+    const concreteT2 = ladder.concrete?.[t2.id]!;
+    expect(concreteT2.timeEntries).toHaveLength(1);
+    expect(concreteT2.dailyEffortDistribution).toEqual([{ date: '2026-09-07', hours: 4.5 }]);
+    expect(concreteT2.realityDelta.loggedHours).toBe(4.5);
+
+    // 3. Query filtered ladder levels
+    const macroOnly = await engine.getTimelineLadder(project.id, { level: 'macro' });
+    expect(macroOnly.macro).toBeDefined();
+    expect(macroOnly.standard).toBeUndefined();
+    expect(macroOnly.concrete).toBeUndefined();
+
+    // 4. Query single task ladder zoom
+    const taskLadder = await engine.getTaskLadder(t2.id);
+    expect(taskLadder).not.toBeNull();
+    expect(taskLadder?.macroPhase?.name).toBe('Phase 1: Design');
+    expect(taskLadder?.standard.id).toBe(t2.id);
+    expect(taskLadder?.concrete.dailyEffortDistribution).toEqual([{ date: '2026-09-07', hours: 4.5 }]);
+  });
+});