@critical-path/core 0.36.0 → 0.37.0

package/src/domain/workload.ts

@@ -1,457 +0,0 @@
-import type {
-  Task,
-  TimeEntry,
-  User,
-  Team,
-  WorkloadInterval,
-  WorkloadGroupBy,
-  WorkloadMetric,
-  WorkloadBucket,
-  WorkloadDistribution,
-  WorkloadDistributionOptions
-} from '../types/index.js';
-import {
-  DEFAULT_WORK_SCHEDULE,
-  getWorkingDaysList,
-  getNetAvailableCapacity,
-  getWorkingHoursInDay
-} from './calendar.js';
-
-export interface WorkloadContext {
-  tasks: Task[];
-  timeEntries?: TimeEntry[];
-  users?: User[];
-  teams?: Team[];
-  projectId?: string;
-}
-
-function toDateString(d: Date): string {
-  return d.toISOString().split('T')[0];
-}
-
-function parseDateOnly(isoString: string): Date {
-  const parts = isoString.split('T')[0].split('-');
-  return new Date(Date.UTC(parseInt(parts[0], 10), parseInt(parts[1], 10) - 1, parseInt(parts[2], 10)));
-}
-
-function addDays(d: Date, days: number): Date {
-  const res = new Date(d.getTime());
-  res.setUTCDate(res.getUTCDate() + days);
-  return res;
-}
-
-function startOfWeek(d: Date): Date {
-  const date = new Date(d.getTime());
-  const day = date.getUTCDay();
-  // Monday is day 1, Sunday is day 0 -> shift Sunday to 7
-  const diff = date.getUTCDate() - day + (day === 0 ? -6 : 1);
-  return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), diff));
-}
-
-function startOfMonth(d: Date): Date {
-  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1));
-}
-
-function nextBucketDate(d: Date, interval: WorkloadInterval): Date {
-  if (interval === 'day') {
-    return addDays(d, 1);
-  }
-  if (interval === 'week') {
-    return addDays(d, 7);
-  }
-  // month: next month 1st
-  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1));
-}
-
-function getBucketKey(d: Date, interval: WorkloadInterval): string {
-  if (interval === 'day') {
-    return toDateString(d);
-  }
-  if (interval === 'week') {
-    return toDateString(startOfWeek(d));
-  }
-  return toDateString(startOfMonth(d));
-}
-
-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;
-  }
-  return 1;
-}
-
-export function calculateWorkloadDistribution(
-  context: WorkloadContext,
-  options: WorkloadDistributionOptions = {}
-): WorkloadDistribution {
-  const { tasks, timeEntries = [], users = [], teams = [], projectId } = context;
-  const interval: WorkloadInterval = options.interval || 'week';
-  const groupBy: WorkloadGroupBy = options.groupBy || 'assignee';
-  const metric: WorkloadMetric = options.metric || 'blended';
-  const defaultWeeklyCapacity = options.defaultWeeklyCapacityHours ?? 40;
-
-  // Build lookups for human-readable labels
-  const userMap = new Map<string, User>(users.map((u) => [u.id, u]));
-  const teamMap = new Map<string, Team>(teams.map((t) => [t.id, t]));
-
-  // 1. Determine date range
-  let minDate: Date | null = options.startDate ? parseDateOnly(options.startDate) : null;
-  let maxDate: Date | null = options.endDate ? parseDateOnly(options.endDate) : null;
-
-  if (!minDate || !maxDate) {
-    const dates: number[] = [];
-    for (const t of tasks) {
-      if (t.plannedStartDate) dates.push(parseDateOnly(t.plannedStartDate).getTime());
-      if (t.actualStartDate) dates.push(parseDateOnly(t.actualStartDate).getTime());
-      if (t.dueDate) dates.push(parseDateOnly(t.dueDate).getTime());
-      if (t.actualEndDate) dates.push(parseDateOnly(t.actualEndDate).getTime());
-      if (t.createdAt) dates.push(parseDateOnly(t.createdAt).getTime());
-    }
-    for (const te of timeEntries) {
-      if (te.loggedAt) dates.push(parseDateOnly(te.loggedAt).getTime());
-    }
-
-    if (dates.length > 0) {
-      if (!minDate) minDate = new Date(Math.min(...dates));
-      if (!maxDate) maxDate = new Date(Math.max(...dates));
-    } else {
-      const now = new Date();
-      if (!minDate) minDate = addDays(now, -7);
-      if (!maxDate) maxDate = addDays(now, 28);
-    }
-  }
-
-  // Ensure minDate <= maxDate
-  if (minDate > maxDate) {
-    maxDate = new Date(minDate.getTime());
-  }
-
-  // Align start to bucket boundary
-  let cursor = interval === 'week' ? startOfWeek(minDate) : interval === 'month' ? startOfMonth(minDate) : minDate;
-  const endLimit = interval === 'week' ? startOfWeek(maxDate) : interval === 'month' ? startOfMonth(maxDate) : maxDate;
-
-  // Generate contiguous buckets
-  interface InternalBucket {
-    date: string;
-    startDate: Date;
-    endDate: Date;
-    timestamp: number;
-    values: Record<string, number>;
-  }
-
-  const bucketList: InternalBucket[] = [];
-  const bucketMap = new Map<string, InternalBucket>();
-
-  while (cursor <= endLimit || bucketList.length === 0) {
-    const dateStr = toDateString(cursor);
-    const nextDate = nextBucketDate(cursor, interval);
-    const b: InternalBucket = {
-      date: dateStr,
-      startDate: new Date(cursor.getTime()),
-      endDate: nextDate,
-      timestamp: cursor.getTime(),
-      values: {}
-    };
-    bucketList.push(b);
-    bucketMap.set(dateStr, b);
-    cursor = nextDate;
-  }
-
-  const seriesKeySet = new Set<string>();
-
-  const getDimensionKey = (task: Task, timeEntry?: TimeEntry): string => {
-    switch (groupBy) {
-      case 'assignee':
-        if (timeEntry?.userId) return timeEntry.userId;
-        return task.assigneeId || 'unassigned';
-      case 'team':
-        return task.teamId || (task.customFields?.teamId as string) || 'unassigned';
-      case 'taskType':
-        return task.taskType || (task.customFields?.type as string) || 'standard';
-      case 'priority':
-        return task.priority || 'none';
-      case 'status':
-        return task.status || 'todo';
-      default:
-        return 'unassigned';
-    }
-  };
-
-  const addValue = (bucket: InternalBucket, key: string, hours: number) => {
-    if (hours <= 0) return;
-    seriesKeySet.add(key);
-    bucket.values[key] = (bucket.values[key] || 0) + hours;
-  };
-
-  const todayStr = toDateString(new Date());
-  const taskMap = new Map<string, Task>(tasks.map((t) => [t.id, t]));
-
-  // 2. Process Logged Hours from TimeEntries
-  if (metric === 'logged' || metric === 'blended') {
-    for (const entry of timeEntries) {
-      if (!entry.hours || entry.hours <= 0) continue;
-      const entryDate = parseDateOnly(entry.loggedAt);
-      const bKey = getBucketKey(entryDate, interval);
-      const bucket = bucketMap.get(bKey);
-      if (bucket) {
-        const associatedTask = taskMap.get(entry.taskId) || ({
-          id: entry.taskId,
-          projectId: projectId || '',
-          title: '',
-          status: 'in_progress',
-          priority: 'medium',
-          createdAt: entry.loggedAt,
-          updatedAt: entry.loggedAt
-        } as Task);
-        const dimKey = getDimensionKey(associatedTask, entry);
-        addValue(bucket, dimKey, entry.hours);
-      }
-    }
-  }
-
-  // 3. Process Scheduled / Remaining / Blended Hours from Tasks
-  if (metric === 'scheduled' || metric === 'remaining' || metric === 'blended') {
-    for (const task of tasks) {
-      const estimated = getTaskDurationHours(task);
-      const logged = task.loggedHours || 0;
-      let hoursToDistribute = 0;
-
-      if (metric === 'scheduled') {
-        hoursToDistribute = estimated;
-      } else if (metric === 'remaining' || metric === 'blended') {
-        if (task.semanticStatus === 'completed' || task.semanticStatus === 'canceled') {
-          hoursToDistribute = 0;
-        } else {
-          hoursToDistribute = Math.max(0, estimated - logged);
-        }
-      }
-
-      if (hoursToDistribute <= 0) continue;
-
-      const dimKey = getDimensionKey(task);
-
-      // Determine task date range
-      let taskStart = task.plannedStartDate
-        ? parseDateOnly(task.plannedStartDate)
-        : task.actualStartDate
-          ? parseDateOnly(task.actualStartDate)
-          : task.createdAt
-            ? parseDateOnly(task.createdAt)
-            : minDate;
-
-      let taskEnd = task.dueDate
-        ? parseDateOnly(task.dueDate)
-        : taskStart
-          ? addDays(taskStart, Math.max(1, Math.ceil(hoursToDistribute / 8)))
-          : maxDate;
-
-      // In blended mode, uncompleted tasks' remaining hours start from today or planned start (whichever is later)
-      if (metric === 'blended') {
-        const today = parseDateOnly(todayStr);
-        if (taskStart < today) {
-          taskStart = today;
-        }
-        if (taskEnd < taskStart) {
-          taskEnd = addDays(taskStart, 1);
-        }
-      }
-
-      if (taskEnd < taskStart) {
-        taskEnd = taskStart;
-      }
-
-      // Resolve schedule for task assignee / team / project
-      const taskSchedule =
-        (task.assigneeId && options.userSchedules?.[task.assigneeId]) ||
-        (task.assigneeId && userMap.get(task.assigneeId)?.schedule) ||
-        (task.teamId && options.teamSchedules?.[task.teamId]) ||
-        (task.teamId && teamMap.get(task.teamId)?.schedule) ||
-        options.schedule ||
-        DEFAULT_WORK_SCHEDULE;
-
-      const workingDays = getWorkingDaysList(taskStart, taskEnd, taskSchedule);
-      const msPerDay = 1000 * 60 * 60 * 24;
-
-      if (workingDays.length > 0) {
-        const hoursPerWorkingDay = hoursToDistribute / workingDays.length;
-
-        for (const bucket of bucketList) {
-          const bucketStart = bucket.startDate.getTime();
-          const bucketEnd = bucket.endDate.getTime();
-
-          let workingDaysInBucket = 0;
-          for (const wdStr of workingDays) {
-            const wdTime = parseDateOnly(wdStr).getTime();
-            if (wdTime >= bucketStart && wdTime < bucketEnd) {
-              workingDaysInBucket++;
-            }
-          }
-
-          if (workingDaysInBucket > 0) {
-            const bucketEffort = workingDaysInBucket * hoursPerWorkingDay;
-            addValue(bucket, dimKey, bucketEffort);
-          }
-        }
-      } else {
-        // Fallback if no working days in range (e.g. task scheduled on an all-holiday window)
-        const totalDays = Math.max(1, Math.round((taskEnd.getTime() - taskStart.getTime()) / msPerDay) + 1);
-        const hoursPerDay = hoursToDistribute / totalDays;
-
-        for (const bucket of bucketList) {
-          const bucketLastDay = addDays(bucket.endDate, -1);
-          const overlapStart = new Date(Math.max(taskStart.getTime(), bucket.startDate.getTime()));
-          const overlapEnd = new Date(Math.min(taskEnd.getTime(), bucketLastDay.getTime()));
-
-          if (overlapStart <= overlapEnd) {
-            const overlapDays = Math.round((overlapEnd.getTime() - overlapStart.getTime()) / msPerDay) + 1;
-            const bucketEffort = overlapDays * hoursPerDay;
-            addValue(bucket, dimKey, bucketEffort);
-          }
-        }
-      }
-    }
-  }
-
-  // Ensure all registered users are in series keys if grouping by assignee
-  if (groupBy === 'assignee' && users.length > 0) {
-    for (const u of users) {
-      seriesKeySet.add(u.id);
-    }
-  }
-  if (groupBy === 'team' && teams.length > 0) {
-    for (const t of teams) {
-      seriesKeySet.add(t.id);
-    }
-  }
-
-  const seriesKeys = Array.from(seriesKeySet).sort();
-
-  // Create human-readable series labels
-  const seriesLabels: Record<string, string> = {};
-  for (const key of seriesKeys) {
-    if (groupBy === 'assignee') {
-      const u = userMap.get(key);
-      seriesLabels[key] = u ? u.name : key === 'unassigned' ? 'Unassigned' : key;
-    } else if (groupBy === 'team') {
-      const t = teamMap.get(key);
-      seriesLabels[key] = t ? t.name : key === 'unassigned' ? 'Unassigned' : key;
-    } else {
-      seriesLabels[key] = key.charAt(0).toUpperCase() + key.slice(1).replace(/_/g, ' ');
-    }
-  }
-
-  // 4. Calculate Capacity & Normalize Buckets
-  let totalDistributedHours = 0;
-  let sumCapacityAcrossBuckets = 0;
-
-  const buckets: WorkloadBucket[] = bucketList.map((ib) => {
-    const values: Record<string, number> = {};
-    const capacity: Record<string, number> = {};
-    let bucketTotalHours = 0;
-    let bucketTotalCapacity = 0;
-
-    for (const key of seriesKeys) {
-      const rawHours = ib.values[key] || 0;
-      const roundedHours = Math.round(rawHours * 100) / 100;
-      values[key] = roundedHours;
-      bucketTotalHours += roundedHours;
-
-      // Capacity calculation
-      const entitySchedule =
-        (groupBy === 'assignee' && (options.userSchedules?.[key] || userMap.get(key)?.schedule)) ||
-        (groupBy === 'team' && (options.teamSchedules?.[key] || teamMap.get(key)?.schedule)) ||
-        options.schedule ||
-        DEFAULT_WORK_SCHEDULE;
-
-      let weeklyCap = defaultWeeklyCapacity;
-      if (options.capacityOverrides && typeof options.capacityOverrides[key] === 'number') {
-        weeklyCap = options.capacityOverrides[key];
-      } else if (groupBy === 'assignee') {
-        const u = userMap.get(key);
-        if (u?.weeklyCapacityHours) weeklyCap = u.weeklyCapacityHours;
-        else if (key === 'unassigned') weeklyCap = 0;
-      } else if (groupBy === 'team') {
-        const t = teamMap.get(key);
-        if (t?.weeklyCapacityHours) {
-          weeklyCap = t.weeklyCapacityHours;
-        } else if (t?.memberIds?.length) {
-          weeklyCap = t.memberIds.length * defaultWeeklyCapacity;
-        } else if (key === 'unassigned') {
-          weeklyCap = 0;
-        }
-      }
-
-      let bucketCap = 0;
-      if (key === 'unassigned') {
-        bucketCap = 0;
-      } else if (interval === 'week') {
-        const netWeekCap = getNetAvailableCapacity(ib.startDate, addDays(ib.endDate, -1), entitySchedule);
-        const baseline = (entitySchedule.defaultHoursPerDay ?? 8) * 5;
-        const scale = baseline > 0 ? weeklyCap / baseline : 1;
-        bucketCap = Math.round(netWeekCap * scale * 100) / 100;
-      } else if (interval === 'day') {
-        const dayHours = getWorkingHoursInDay(ib.startDate, entitySchedule);
-        const baseline = (entitySchedule.defaultHoursPerDay ?? 8) * 5;
-        const scale = baseline > 0 ? weeklyCap / baseline : 1;
-        bucketCap = Math.round(dayHours * scale * 100) / 100;
-      } else if (interval === 'month') {
-        const netMonthCap = getNetAvailableCapacity(ib.startDate, addDays(ib.endDate, -1), entitySchedule);
-        const baseline = (entitySchedule.defaultHoursPerDay ?? 8) * 5;
-        const scale = baseline > 0 ? weeklyCap / baseline : 1;
-        bucketCap = Math.round(netMonthCap * scale * 100) / 100;
-      }
-
-      capacity[key] = bucketCap;
-      bucketTotalCapacity += bucketCap;
-    }
-
-    bucketTotalHours = Math.round(bucketTotalHours * 100) / 100;
-    bucketTotalCapacity = Math.round(bucketTotalCapacity * 100) / 100;
-    totalDistributedHours += bucketTotalHours;
-    sumCapacityAcrossBuckets += bucketTotalCapacity;
-
-    const utilizationRatio =
-      bucketTotalCapacity > 0
-        ? Math.round((bucketTotalHours / bucketTotalCapacity) * 1000) / 1000
-        : undefined;
-
-    return {
-      date: ib.date,
-      timestamp: ib.timestamp,
-      totalHours: bucketTotalHours,
-      values,
-      capacity,
-      totalCapacity: bucketTotalCapacity,
-      utilizationRatio
-    };
-  });
-
-  totalDistributedHours = Math.round(totalDistributedHours * 100) / 100;
-  sumCapacityAcrossBuckets = Math.round(sumCapacityAcrossBuckets * 100) / 100;
-
-  const averageUtilization =
-    sumCapacityAcrossBuckets > 0
-      ? Math.round((totalDistributedHours / sumCapacityAcrossBuckets) * 1000) / 1000
-      : undefined;
-
-  return {
-    projectId,
-    startDate: toDateString(minDate),
-    endDate: toDateString(maxDate),
-    interval,
-    groupBy,
-    metric,
-    seriesKeys,
-    seriesLabels,
-    buckets,
-    totalHours: totalDistributedHours,
-    totalCapacity: sumCapacityAcrossBuckets,
-    averageUtilization
-  };
-}

package/src/engine/actor.test.ts

@@ -1,63 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { CriticalPathEngine } from '../index.js';
-
-describe('CriticalPathEngine.withActor', () => {
-  it('attributes mutations to the scoped actor and ignores identity claimed in payloads', async () => {
-    const engine = new CriticalPathEngine();
-    const alice = engine.withActor({ userId: 'alice', username: 'Alice' });
-
-    const project = await alice.createProject({ key: 'ACT', name: 'Actors', ownerId: 'mallory' });
-    const task = await alice.createTask({ projectId: project.id, title: 'Scoped' });
-    expect(task.reporterId).toBe('alice');
-
-    // Identity in the payload is not part of the update type at all; cast to simulate an untyped caller
-    await alice.updateTask(task.id, { title: 'Renamed', actorId: 'ceo', actor: { userId: 'ceo' } } as any);
-    const comment = await alice.addComment({ taskId: task.id, content: 'hi', authorId: 'ceo', authorType: 'agent' });
-    const reacted = await alice.addCommentReaction(comment.id, { emoji: '👍', userId: 'ceo' });
-    const entry = await alice.logTime({ taskId: task.id, hours: 1, userId: 'ceo' } as any);
-    const attachment = await alice.createAttachment({
-      taskId: task.id,
-      uploaderId: 'ceo',
-      filename: 'spec.md',
-      mimeType: 'text/markdown',
-      sizeBytes: 1,
-      url: 'https://example.com/spec.md'
-    });
-
-    expect(comment.authorId).toBe('alice');
-    expect(comment.authorType).toBe('user');
-    expect(reacted?.reactions?.[0].userId).toBe('alice');
-    expect(entry.userId).toBe('alice');
-    expect(attachment.uploaderId).toBe('alice');
-
-    const activities = await engine.store.getActivities({ projectId: project.id });
-    expect(activities.length).toBeGreaterThan(0);
-    expect(activities.every((a) => a.actorId === 'alice')).toBe(true);
-  });
-
-  it('does not change the base engine, and concurrent views stay isolated', async () => {
-    const engine = new CriticalPathEngine();
-    const project = await engine.createProject({ key: 'ISO', name: 'Isolation' });
-
-    const [a, b] = await Promise.all([
-      engine.withActor({ userId: 'a' }).createTask({ projectId: project.id, title: 'A' }),
-      engine.withActor({ userId: 'b' }).createTask({ projectId: project.id, title: 'B' })
-    ]);
-    expect(a.reporterId).toBe('a');
-    expect(b.reporterId).toBe('b');
-    expect(engine.actor).toBeUndefined();
-
-    // Views share state with the base engine
-    expect(await engine.getTask(a.id)).not.toBeNull();
-  });
-
-  it('still lets explicit updateTask options override the scoped actor', async () => {
-    const engine = new CriticalPathEngine();
-    const project = await engine.createProject({ key: 'OPT', name: 'Options' });
-    const task = await engine.createTask({ projectId: project.id, title: 'T' });
-
-    await engine.withActor({ userId: 'alice' }).updateTask(task.id, { title: 'T2' }, { actorId: 'automation' });
-    const activities = await engine.store.getActivities({ taskId: task.id });
-    expect(activities.some((a) => a.actorId === 'automation')).toBe(true);
-  });
-});