@critical-path/core 0.17.0 → 0.19.0

package/src/domain/ladder.ts

@@ -17,9 +17,11 @@ import type {
   ConcreteTaskEvidence,
   ConcreteEvidenceSummary,
   RealityDelta,
-  TaskLadderView
+  TaskLadderView,
+  WorkSchedule
 } from '../types/index.js';
 import { calculateCPM, getTaskDurationHours } from './cpm.js';
+import { DEFAULT_WORK_SCHEDULE, getWorkingDaysBetween } from './calendar.js';
 
 export interface LadderContext {
   project: Project;
@@ -31,6 +33,7 @@ export interface LadderContext {
   attachments?: Attachment[];
   timeEntries?: TimeEntry[];
   activities?: Activity[];
+  schedule?: WorkSchedule;
 }
 
 export function aggregateConcreteEvidenceForTask(
@@ -38,7 +41,8 @@ export function aggregateConcreteEvidenceForTask(
   attachments: Attachment[] = [],
   deliverables: Deliverable[] = [],
   timeEntries: TimeEntry[] = [],
-  activities: Activity[] = []
+  activities: Activity[] = [],
+  schedule?: WorkSchedule
 ): ConcreteTaskEvidence {
   const taskAttachments = attachments.filter((a) => a.taskId === task.id);
   const taskDeliverables = deliverables.filter(
@@ -70,10 +74,19 @@ export function aggregateConcreteEvidenceForTask(
   const isOverEstimate = Boolean(estimatedHours > 0 && effectiveLoggedHours > estimatedHours);
 
   let scheduleVarianceDays: number | undefined;
+  let scheduleVarianceWorkingDays: number | undefined;
   if (task.dueDate && task.actualEndDate) {
     const dueTime = new Date(task.dueDate).getTime();
     const actualTime = new Date(task.actualEndDate).getTime();
     scheduleVarianceDays = Math.round((actualTime - dueTime) / (1000 * 60 * 60 * 24));
+    const effectiveSched = schedule || DEFAULT_WORK_SCHEDULE;
+    if (actualTime > dueTime) {
+      scheduleVarianceWorkingDays = Math.max(0, getWorkingDaysBetween(task.dueDate, task.actualEndDate, effectiveSched) - 1);
+    } else if (actualTime < dueTime) {
+      scheduleVarianceWorkingDays = -Math.max(0, getWorkingDaysBetween(task.actualEndDate, task.dueDate, effectiveSched) - 1);
+    } else {
+      scheduleVarianceWorkingDays = 0;
+    }
   }
 
   let durationVarianceHours: number | undefined;
@@ -100,6 +113,7 @@ export function aggregateConcreteEvidenceForTask(
     effortVarianceHours: varianceHours,
     durationVarianceHours,
     scheduleVarianceDays,
+    scheduleVarianceWorkingDays,
     accuracyRatio,
     isOverdue,
     isOverEstimate
@@ -309,8 +323,14 @@ export function buildTimelineLadder(
   const targetLevel = options.level || 'all';
   const generatedAt = new Date().toISOString();
 
+  const effectiveSchedule = context.schedule || project.schedule || DEFAULT_WORK_SCHEDULE;
+  const projectStartDate = project.startDate || (tasks.length > 0 ? tasks.find((t) => t.plannedStartDate)?.plannedStartDate : undefined);
+
   // Run Critical Path Method (CPM)
-  const cpm = calculateCPM(project.id, tasks, dependencies);
+  const cpm = calculateCPM(project.id, tasks, dependencies, {
+    schedule: effectiveSchedule,
+    projectStartDate
+  });
   const criticalSet = new Set(cpm.criticalTaskIds);
   const scheduleMap = new Map(cpm.tasks.map((s) => [s.taskId, s]));
 
@@ -352,7 +372,8 @@ export function buildTimelineLadder(
       attachments,
       deliverables,
       timeEntries,
-      activities
+      activities,
+      effectiveSchedule
     );
   }
 

package/src/domain/metrics.test.ts

@@ -148,6 +148,8 @@ describe('Task Metrics Domain', () => {
   });
 
   describe('reconstructTaskProgressHistory & Curve Profile', () => {
+    const referenceDate = new Date('2026-09-09T12:00:00Z');
+
     it('detects linear progress', () => {
       const activities: Activity[] = [
         { id: 'a1', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 25 }, createdAt: '2026-09-02T10:00:00Z' },
@@ -156,7 +158,7 @@ describe('Task Metrics Domain', () => {
         { id: 'a4', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 100 }, createdAt: '2026-09-08T10:00:00Z' }
       ];
       const task: Task = { ...baseTask, progress: 100, updatedAt: '2026-09-08T10:00:00Z' };
-      const history = reconstructTaskProgressHistory(task, activities);
+      const history = reconstructTaskProgressHistory(task, activities, { referenceDate });
 
       expect(history.points.length).toBeGreaterThanOrEqual(4);
       expect(history.curveProfile).toBe('linear');
@@ -170,7 +172,7 @@ describe('Task Metrics Domain', () => {
         { id: 'a4', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 95 }, createdAt: '2026-09-09T10:00:00Z' }
       ];
       const task: Task = { ...baseTask, progress: 95, updatedAt: '2026-09-09T10:00:00Z' };
-      const history = reconstructTaskProgressHistory(task, activities);
+      const history = reconstructTaskProgressHistory(task, activities, { referenceDate });
 
       expect(history.curveProfile).toBe('s_curve');
     });
@@ -182,7 +184,7 @@ describe('Task Metrics Domain', () => {
         { id: 'a3', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 78 }, createdAt: '2026-09-08T10:00:00Z' }
       ];
       const task: Task = { ...baseTask, progress: 78, updatedAt: '2026-09-08T10:00:00Z' };
-      const history = reconstructTaskProgressHistory(task, activities);
+      const history = reconstructTaskProgressHistory(task, activities, { referenceDate });
 
       expect(history.curveProfile).toBe('early_surge');
     });
@@ -194,7 +196,7 @@ describe('Task Metrics Domain', () => {
         { id: 'a3', taskId: 'task-1', actorId: 'u1', action: 'task.updated', details: { progress: 90 }, createdAt: '2026-09-08T10:00:00Z' }
       ];
       const task: Task = { ...baseTask, progress: 90, updatedAt: '2026-09-08T10:00:00Z' };
-      const history = reconstructTaskProgressHistory(task, activities);
+      const history = reconstructTaskProgressHistory(task, activities, { referenceDate });
 
       expect(history.curveProfile).toBe('late_rush');
     });

package/src/domain/workload.test.ts

@@ -0,0 +1,311 @@
+import { describe, it, expect } from 'vitest';
+import { calculateWorkloadDistribution } from './workload.js';
+import { CriticalPathEngine } from '../engine/index.js';
+import { InMemoryStore } from '../store/index.js';
+import type { Task, TimeEntry, User, Team } from '../types/index.js';
+
+describe('calculateWorkloadDistribution', () => {
+  const users: User[] = [
+    { id: 'u1', name: 'Alice', email: 'alice@example.com', role: 'contributor', weeklyCapacityHours: 35, createdAt: '2026-09-01' },
+    { id: 'u2', name: 'Bob', email: 'bob@example.com', role: 'contributor', weeklyCapacityHours: 40, createdAt: '2026-09-01' }
+  ];
+
+  const teams: Team[] = [
+    { id: 'team_frontend', name: 'Frontend', memberIds: ['u1'], createdAt: '2026-09-01', updatedAt: '2026-09-01' },
+    { id: 'team_backend', name: 'Backend', memberIds: ['u2'], weeklyCapacityHours: 50, createdAt: '2026-09-01', updatedAt: '2026-09-01' }
+  ];
+
+  it('aggregates logged time entries accurately by assignee across weekly buckets', () => {
+    const tasks: Task[] = [
+      {
+        id: 't1',
+        projectId: 'p1',
+        title: 'Task 1',
+        status: 'in_progress',
+        priority: 'high',
+        assigneeId: 'u1',
+        createdAt: '2026-09-01',
+        updatedAt: '2026-09-01'
+      }
+    ];
+
+    const timeEntries: TimeEntry[] = [
+      { id: 'te1', taskId: 't1', userId: 'u1', hours: 4.5, loggedAt: '2026-09-08' },
+      { id: 'te2', taskId: 't1', userId: 'u1', hours: 3.5, loggedAt: '2026-09-09' },
+      { id: 'te3', taskId: 't1', userId: 'u2', hours: 6.0, loggedAt: '2026-09-15' }
+    ];
+
+    const result = calculateWorkloadDistribution(
+      { tasks, timeEntries, users, teams },
+      {
+        startDate: '2026-09-07',
+        endDate: '2026-09-21',
+        interval: 'week',
+        groupBy: 'assignee',
+        metric: 'logged'
+      }
+    );
+
+    expect(result.interval).toBe('week');
+    expect(result.groupBy).toBe('assignee');
+    expect(result.metric).toBe('logged');
+    expect(result.seriesKeys).toContain('u1');
+    expect(result.seriesKeys).toContain('u2');
+    expect(result.seriesLabels.u1).toBe('Alice');
+    expect(result.seriesLabels.u2).toBe('Bob');
+
+    // Week 1: 2026-09-07 (contains 09-08 and 09-09)
+    const week1 = result.buckets.find((b) => b.date === '2026-09-07');
+    expect(week1).toBeDefined();
+    expect(week1?.values.u1).toBe(8.0);
+    expect(week1?.values.u2).toBe(0);
+    expect(week1?.totalHours).toBe(8.0);
+    expect(week1?.capacity?.u1).toBe(35);
+    expect(week1?.capacity?.u2).toBe(40);
+
+    // Week 2: 2026-09-14 (contains 09-15)
+    const week2 = result.buckets.find((b) => b.date === '2026-09-14');
+    expect(week2).toBeDefined();
+    expect(week2?.values.u2).toBe(6.0);
+    expect(week2?.values.u1).toBe(0);
+    expect(week2?.totalHours).toBe(6.0);
+
+    // Total
+    expect(result.totalHours).toBe(14.0);
+  });
+
+  it('distributes scheduled estimated hours evenly across task duration', () => {
+    const tasks: Task[] = [
+      {
+        id: 't1',
+        projectId: 'p1',
+        title: 'Multi-day Task',
+        status: 'todo',
+        priority: 'high',
+        assigneeId: 'u1',
+        estimatedHours: 40,
+        plannedStartDate: '2026-09-07', // Monday
+        dueDate: '2026-09-11', // Friday (5 days total = 8h/day)
+        createdAt: '2026-09-01',
+        updatedAt: '2026-09-01'
+      }
+    ];
+
+    const result = calculateWorkloadDistribution(
+      { tasks, users },
+      {
+        startDate: '2026-09-07',
+        endDate: '2026-09-11',
+        interval: 'day',
+        groupBy: 'assignee',
+        metric: 'scheduled'
+      }
+    );
+
+    expect(result.buckets.length).toBe(5);
+    for (const b of result.buckets) {
+      expect(b.values.u1).toBe(8);
+      expect(b.totalHours).toBe(8);
+      expect(b.capacity?.u1).toBe(7); // 35 / 5 = 7h/day
+    }
+    expect(result.totalHours).toBe(40);
+  });
+
+  it('handles grouping by team with custom team capacity and unassigned tasks', () => {
+    const tasks: Task[] = [
+      {
+        id: 't1',
+        projectId: 'p1',
+        title: 'Frontend Task',
+        status: 'in_progress',
+        priority: 'medium',
+        teamId: 'team_frontend',
+        estimatedHours: 20,
+        plannedStartDate: '2026-09-07',
+        dueDate: '2026-09-07',
+        createdAt: '2026-09-01',
+        updatedAt: '2026-09-01'
+      },
+      {
+        id: 't2',
+        projectId: 'p1',
+        title: 'Unassigned Task',
+        status: 'todo',
+        priority: 'low',
+        estimatedHours: 10,
+        plannedStartDate: '2026-09-07',
+        dueDate: '2026-09-07',
+        createdAt: '2026-09-01',
+        updatedAt: '2026-09-01'
+      }
+    ];
+
+    const result = calculateWorkloadDistribution(
+      { tasks, teams },
+      {
+        startDate: '2026-09-07',
+        endDate: '2026-09-13',
+        interval: 'week',
+        groupBy: 'team',
+        metric: 'scheduled'
+      }
+    );
+
+    expect(result.seriesKeys).toContain('team_frontend');
+    expect(result.seriesKeys).toContain('unassigned');
+    expect(result.seriesLabels.team_frontend).toBe('Frontend');
+    expect(result.seriesLabels.unassigned).toBe('Unassigned');
+
+    const bucket = result.buckets[0];
+    expect(bucket.values.team_frontend).toBe(20);
+    expect(bucket.values.unassigned).toBe(10);
+    expect(bucket.totalHours).toBe(30);
+  });
+
+  it('calculates streamgraph-ready tabular structure without gaps for D3 stack', () => {
+    const tasks: Task[] = [
+      {
+        id: 't1',
+        projectId: 'p1',
+        title: 'Task A',
+        status: 'done',
+        priority: 'high',
+        assigneeId: 'u1',
+        createdAt: '2026-09-01',
+        updatedAt: '2026-09-01'
+      }
+    ];
+
+    const timeEntries: TimeEntry[] = [
+      { id: 'te1', taskId: 't1', userId: 'u1', hours: 5, loggedAt: '2026-09-01' },
+      { id: 'te2', taskId: 't1', userId: 'u2', hours: 8, loggedAt: '2026-09-08' }
+    ];
+
+    const result = calculateWorkloadDistribution(
+      { tasks, timeEntries, users },
+      {
+        startDate: '2026-09-01',
+        endDate: '2026-09-14',
+        interval: 'week',
+        groupBy: 'assignee',
+        metric: 'logged'
+      }
+    );
+
+    // Verify all buckets contain numerical values (0, not undefined) for every series key
+    for (const bucket of result.buckets) {
+      for (const key of result.seriesKeys) {
+        expect(typeof bucket.values[key]).toBe('number');
+        expect(bucket.values[key]).toBeGreaterThanOrEqual(0);
+      }
+    }
+  });
+
+  it('integrates with CriticalPathEngine.getWorkloadDistribution', async () => {
+    const store = new InMemoryStore();
+    const engine = new CriticalPathEngine({ store });
+
+    const project = await engine.createProject({ name: 'Workload Project' });
+    const task = await engine.createTask({
+      projectId: project.id,
+      title: 'Dev Task',
+      status: 'in_progress',
+      assigneeId: 'u1',
+      estimatedHours: 15,
+      plannedStartDate: '2026-09-07',
+      dueDate: '2026-09-07'
+    });
+
+    await engine.logTime({
+      taskId: task.id,
+      userId: 'u1',
+      hours: 5,
+      loggedAt: '2026-09-07T10:00:00.000Z'
+    });
+
+    const distribution = await engine.getWorkloadDistribution(project.id, {
+      startDate: '2026-09-07',
+      endDate: '2026-09-13',
+      interval: 'week',
+      metric: 'blended'
+    });
+
+    expect(distribution.projectId).toBe(project.id);
+    expect(distribution.totalHours).toBeGreaterThan(0);
+    expect(distribution.buckets.length).toBeGreaterThan(0);
+    expect(distribution.seriesKeys).toContain('u1');
+  });
+
+  it('distributes task effort only on working days and reduces capacity on holidays', () => {
+    // Friday 2026-09-18 to Tuesday 2026-09-22 (5 calendar days: Fri, Sat, Sun, Mon, Tue)
+    // Monday 2026-09-21 is a Holiday!
+    // Active working days: Friday 2026-09-18 and Tuesday 2026-09-22 (2 days total)
+    // 16 estimated hours should be divided into 8h on Fri, 0h on Sat, 0h on Sun, 0h on Mon, 8h on Tue!
+    const customSchedule = {
+      name: 'Holiday Calendar',
+      defaultHoursPerDay: 8,
+      days: [
+        { dayOfWeek: 0, isWorkingDay: false },
+        { dayOfWeek: 1, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 2, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 3, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 4, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 5, isWorkingDay: true, hours: [{ start: '09:00', end: '17:00' }] },
+        { dayOfWeek: 6, isWorkingDay: false }
+      ],
+      holidays: [{ date: '2026-09-21', name: 'Monday Holiday' }]
+    };
+
+    const tasks: Task[] = [
+      {
+        id: 't_holiday',
+        projectId: 'p1',
+        title: 'Holiday Spanning Task',
+        status: 'todo',
+        priority: 'high',
+        assigneeId: 'u2',
+        estimatedHours: 16,
+        plannedStartDate: '2026-09-18', // Friday
+        dueDate: '2026-09-22',          // Tuesday
+        createdAt: '2026-09-01',
+        updatedAt: '2026-09-01'
+      }
+    ];
+
+    const result = calculateWorkloadDistribution(
+      { tasks, users },
+      {
+        startDate: '2026-09-18',
+        endDate: '2026-09-22',
+        interval: 'day',
+        groupBy: 'assignee',
+        metric: 'scheduled',
+        schedule: customSchedule
+      }
+    );
+
+    const fri = result.buckets.find((b) => b.date === '2026-09-18');
+    const sat = result.buckets.find((b) => b.date === '2026-09-19');
+    const sun = result.buckets.find((b) => b.date === '2026-09-20');
+    const mon = result.buckets.find((b) => b.date === '2026-09-21');
+    const tue = result.buckets.find((b) => b.date === '2026-09-22');
+
+    expect(fri?.values.u2).toBe(8);
+    expect(fri?.capacity?.u2).toBe(8);
+
+    expect(sat?.values.u2).toBe(0);
+    expect(sat?.capacity?.u2).toBe(0);
+
+    expect(sun?.values.u2).toBe(0);
+    expect(sun?.capacity?.u2).toBe(0);
+
+    // Monday is holiday: 0 scheduled effort, 0 capacity
+    expect(mon?.values.u2).toBe(0);
+    expect(mon?.capacity?.u2).toBe(0);
+
+    expect(tue?.values.u2).toBe(8);
+    expect(tue?.capacity?.u2).toBe(8);
+
+    expect(result.totalHours).toBe(16);
+  });
+});