@critical-path/core 0.36.0 → 0.37.0

package/src/domain/ladder.ts

@@ -1,474 +0,0 @@
-import type {
-  Project,
-  Task,
-  TaskDependency,
-  TaskContainer,
-  Iteration,
-  Deliverable,
-  Attachment,
-  TimeEntry,
-  Activity,
-  TimelineLadder,
-  TimelineLadderOptions,
-  MacroTimelineSummary,
-  MacroPhaseRollup,
-  MacroPhaseHealth,
-  StandardTaskTimelineItem,
-  ConcreteTaskEvidence,
-  ConcreteEvidenceSummary,
-  RealityDelta,
-  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;
-  tasks: Task[];
-  dependencies: TaskDependency[];
-  containers?: TaskContainer[];
-  iterations?: Iteration[];
-  deliverables?: Deliverable[];
-  attachments?: Attachment[];
-  timeEntries?: TimeEntry[];
-  activities?: Activity[];
-  schedule?: WorkSchedule;
-}
-
-export function aggregateConcreteEvidenceForTask(
-  task: Task,
-  attachments: Attachment[] = [],
-  deliverables: Deliverable[] = [],
-  timeEntries: TimeEntry[] = [],
-  activities: Activity[] = [],
-  schedule?: WorkSchedule
-): ConcreteTaskEvidence {
-  const taskAttachments = attachments.filter((a) => a.taskId === task.id);
-  const taskDeliverables = deliverables.filter(
-    (d) => d.id === task.deliverableId || (task.customFields?.deliverableId === d.id)
-  );
-  const taskTimeEntries = timeEntries.filter((te) => te.taskId === task.id);
-  const taskActivities = activities.filter((act) => act.taskId === task.id);
-  const todos = task.todos || [];
-
-  // Group time entries by date for daily effort distribution
-  const effortByDate = new Map<string, number>();
-  for (const entry of taskTimeEntries) {
-    const dateStr = entry.loggedAt.includes('T') ? entry.loggedAt.split('T')[0] : entry.loggedAt.substring(0, 10);
-    const existing = effortByDate.get(dateStr) || 0;
-    effortByDate.set(dateStr, Math.round((existing + entry.hours) * 100) / 100);
-  }
-
-  const dailyEffortDistribution = Array.from(effortByDate.entries())
-    .map(([date, hours]) => ({ date, hours }))
-    .sort((a, b) => a.date.localeCompare(b.date));
-
-  const loggedHoursFromEntries = taskTimeEntries.reduce((sum, e) => sum + e.hours, 0);
-  const effectiveLoggedHours = Math.max(loggedHoursFromEntries, task.loggedHours || 0, task.actualHours || 0);
-  const estimatedHours = task.estimatedHours || (task.estimatedDurationMinutes ? task.estimatedDurationMinutes / 60 : 0);
-  const varianceHours = Math.round((effectiveLoggedHours - estimatedHours) * 100) / 100;
-
-  const nowIso = new Date().toISOString();
-  const isOverdue = Boolean(task.dueDate && task.dueDate < nowIso && task.semanticStatus !== 'completed' && task.semanticStatus !== 'canceled');
-  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;
-  if (task.actualStartDate && task.actualEndDate && task.plannedStartDate && task.dueDate) {
-    const actualDuration = (new Date(task.actualEndDate).getTime() - new Date(task.actualStartDate).getTime()) / (1000 * 60 * 60);
-    const plannedDuration = (new Date(task.dueDate).getTime() - new Date(task.plannedStartDate).getTime()) / (1000 * 60 * 60);
-    if (!isNaN(actualDuration) && !isNaN(plannedDuration)) {
-      durationVarianceHours = Math.round((actualDuration - plannedDuration) * 100) / 100;
-    }
-  }
-
-  const accuracyRatio = estimatedHours > 0
-    ? Math.round((effectiveLoggedHours / estimatedHours) * 100) / 100
-    : undefined;
-
-  const realityDelta: RealityDelta = {
-    plannedStartDate: task.plannedStartDate,
-    actualStartDate: task.actualStartDate,
-    dueDate: task.dueDate,
-    actualEndDate: task.actualEndDate,
-    estimatedHours: Math.round(estimatedHours * 100) / 100,
-    loggedHours: Math.round(effectiveLoggedHours * 100) / 100,
-    varianceHours,
-    effortVarianceHours: varianceHours,
-    durationVarianceHours,
-    scheduleVarianceDays,
-    scheduleVarianceWorkingDays,
-    accuracyRatio,
-    isOverdue,
-    isOverEstimate
-  };
-
-  const hasVisualAsset = taskAttachments.some(
-    (a) => a.mimeType?.startsWith('image/') || a.mimeType?.startsWith('video/')
-  ) || taskDeliverables.some((d) => (d.outputUrls && d.outputUrls.length > 0) || Boolean(d.format));
-
-  const timestamps = [
-    ...taskActivities.map((a) => a.createdAt),
-    ...taskTimeEntries.map((te) => te.loggedAt),
-    task.updatedAt
-  ].filter(Boolean);
-  timestamps.sort();
-  const lastActivityAt = timestamps.length > 0 ? timestamps[timestamps.length - 1] : undefined;
-
-  const completedTodoCount = todos.filter((t) => t.completed).length;
-
-  const evidenceSummary: ConcreteEvidenceSummary = {
-    attachmentCount: taskAttachments.length,
-    deliverableCount: taskDeliverables.length,
-    todoCount: todos.length,
-    completedTodoCount,
-    timeEntryCount: taskTimeEntries.length,
-    totalLoggedHours: Math.round(effectiveLoggedHours * 100) / 100,
-    hasVisualAsset,
-    lastActivityAt
-  };
-
-  return {
-    taskId: task.id,
-    attachments: taskAttachments,
-    deliverables: taskDeliverables,
-    todos,
-    timeEntries: taskTimeEntries,
-    dailyEffortDistribution,
-    activities: taskActivities,
-    realityDelta,
-    evidenceSummary
-  };
-}
-
-export function computeMacroPhases(
-  tasks: Task[],
-  containers: TaskContainer[] = [],
-  iterations: Iteration[] = [],
-  criticalTaskIds: Set<string>
-): MacroPhaseRollup[] {
-  const containerMap = new Map<string, TaskContainer>(containers.map((c) => [c.id, c]));
-  const iterationMap = new Map<string, Iteration>(iterations.map((it) => [it.id, it]));
-
-  // Group tasks by container if any exist; fallback to iteration or unassigned
-  const phaseBuckets = new Map<string, { type: 'container' | 'iteration' | 'phase'; name: string; description?: string; tasks: Task[] }>();
-
-  if (containers.length > 0) {
-    for (const c of containers) {
-      phaseBuckets.set(c.id, {
-        type: 'container',
-        name: c.name,
-        description: c.description,
-        tasks: []
-      });
-    }
-  } else if (iterations.length > 0) {
-    for (const it of iterations) {
-      phaseBuckets.set(it.id, {
-        type: 'iteration',
-        name: it.name,
-        description: it.goal,
-        tasks: []
-      });
-    }
-  }
-
-  // Populate tasks into buckets
-  for (const t of tasks) {
-    let bucketId: string | null = null;
-    if (t.containerId && phaseBuckets.has(t.containerId)) {
-      bucketId = t.containerId;
-    } else if (t.iterationId && phaseBuckets.has(t.iterationId)) {
-      bucketId = t.iterationId;
-    }
-
-    if (!bucketId) {
-      const fallbackId = 'unassigned';
-      if (!phaseBuckets.has(fallbackId)) {
-        phaseBuckets.set(fallbackId, {
-          type: 'phase',
-          name: containers.length > 0 || iterations.length > 0 ? 'General Tasks' : 'All Tasks',
-          tasks: []
-        });
-      }
-      bucketId = fallbackId;
-    }
-
-    phaseBuckets.get(bucketId)!.tasks.push(t);
-  }
-
-  const nowIso = new Date().toISOString();
-  const phases: MacroPhaseRollup[] = [];
-
-  for (const [id, bucket] of phaseBuckets.entries()) {
-    const bucketTasks = bucket.tasks;
-    if (bucketTasks.length === 0 && id === 'unassigned') continue;
-
-    const taskIds = bucketTasks.map((t) => t.id);
-    const totalTasks = bucketTasks.length;
-    const completedTasks = bucketTasks.filter((t) => t.semanticStatus === 'completed' || t.status === 'done').length;
-    const inProgressTasks = bucketTasks.filter((t) => t.semanticStatus === 'in_progress' || t.status === 'in_progress').length;
-    const blockedTasks = bucketTasks.filter((t) => t.tags?.includes('blocked') || (t as any).isBlocked).length;
-
-    let totalEstimatedHours = 0;
-    let totalLoggedHours = 0;
-    let weightedProgressSum = 0;
-    let totalProgressWeight = 0;
-
-    const startDates: string[] = [];
-    const endDates: string[] = [];
-
-    // Inherit container/iteration dates if set
-    if (bucket.type === 'iteration' && iterationMap.has(id)) {
-      const it = iterationMap.get(id)!;
-      if (it.startDate) startDates.push(it.startDate);
-      if (it.endDate) endDates.push(it.endDate);
-    }
-
-    let criticalCount = 0;
-
-    for (const t of bucketTasks) {
-      const duration = getTaskDurationHours(t);
-      const est = t.estimatedHours || duration;
-      const logged = t.loggedHours || 0;
-      totalEstimatedHours += est;
-      totalLoggedHours += logged;
-
-      const progress = typeof t.progress === 'number'
-        ? t.progress
-        : (t.semanticStatus === 'completed' || t.status === 'done' ? 100 : 0);
-
-      weightedProgressSum += progress * Math.max(est, 1);
-      totalProgressWeight += Math.max(est, 1);
-
-      if (t.plannedStartDate) startDates.push(t.plannedStartDate);
-      if (t.actualStartDate) startDates.push(t.actualStartDate);
-      if (t.dueDate) endDates.push(t.dueDate);
-      if (t.actualEndDate) endDates.push(t.actualEndDate);
-
-      if (criticalTaskIds.has(t.id)) {
-        criticalCount++;
-      }
-    }
-
-    startDates.sort();
-    endDates.sort();
-
-    const startDate = startDates.length > 0 ? startDates[0] : undefined;
-    const endDate = endDates.length > 0 ? endDates[endDates.length - 1] : undefined;
-
-    const progressPercentage = totalProgressWeight > 0
-      ? Math.round(weightedProgressSum / totalProgressWeight)
-      : (totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0);
-
-    // Derive health
-    let health: MacroPhaseHealth = 'on_track';
-    if (totalTasks > 0 && completedTasks === totalTasks) {
-      health = 'completed';
-    } else if (blockedTasks > 0) {
-      health = 'blocked';
-    } else if (endDate && endDate < nowIso) {
-      health = 'overdue';
-    } else if (criticalCount > 0 && progressPercentage < 50 && endDate && (new Date(endDate).getTime() - Date.now() < 3 * 24 * 3600 * 1000)) {
-      health = 'at_risk';
-    }
-
-    phases.push({
-      id,
-      type: bucket.type,
-      name: bucket.name,
-      description: bucket.description,
-      startDate,
-      endDate,
-      durationHours: Math.round(totalEstimatedHours * 100) / 100,
-      totalTasks,
-      completedTasks,
-      inProgressTasks,
-      blockedTasks,
-      progressPercentage,
-      totalEstimatedHours: Math.round(totalEstimatedHours * 100) / 100,
-      totalLoggedHours: Math.round(totalLoggedHours * 100) / 100,
-      isCritical: criticalCount > 0,
-      criticalTaskCount: criticalCount,
-      health,
-      taskIds
-    });
-  }
-
-  return phases;
-}
-
-export function buildTimelineLadder(
-  context: LadderContext,
-  options: TimelineLadderOptions = {}
-): TimelineLadder {
-  const { project, tasks, dependencies, containers = [], iterations = [], deliverables = [], attachments = [], timeEntries = [], activities = [] } = context;
-
-  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, {
-    schedule: effectiveSchedule,
-    projectStartDate
-  });
-  const criticalSet = new Set(cpm.criticalTaskIds);
-  const scheduleMap = new Map(cpm.tasks.map((s) => [s.taskId, s]));
-
-  // Adjacency for dependencies
-  const blockingMap = new Map<string, string[]>();
-  const dependentMap = new Map<string, string[]>();
-  for (const t of tasks) {
-    blockingMap.set(t.id, []);
-    dependentMap.set(t.id, []);
-  }
-
-  for (const dep of dependencies) {
-    if (dep.type === 'blocking') {
-      // dep.taskId depends on dep.dependsOnTaskId
-      // dep.dependsOnTaskId blocks dep.taskId
-      blockingMap.get(dep.taskId)?.push(dep.dependsOnTaskId);
-      dependentMap.get(dep.dependsOnTaskId)?.push(dep.taskId);
-    } else if (dep.type === 'blocked_by') {
-      blockingMap.get(dep.dependsOnTaskId)?.push(dep.taskId);
-      dependentMap.get(dep.taskId)?.push(dep.dependsOnTaskId);
-    }
-  }
-
-  // Subtask hierarchy (parentId -> children)
-  const childMap = new Map<string, string[]>();
-  for (const t of tasks) {
-    if (t.parentId) {
-      const list = childMap.get(t.parentId) || [];
-      list.push(t.id);
-      childMap.set(t.parentId, list);
-    }
-  }
-
-  // 1. Concrete View (Grounding)
-  const concreteRecords: Record<string, ConcreteTaskEvidence> = {};
-  for (const t of tasks) {
-    concreteRecords[t.id] = aggregateConcreteEvidenceForTask(
-      t,
-      attachments,
-      deliverables,
-      timeEntries,
-      activities,
-      effectiveSchedule
-    );
-  }
-
-  // 2. Standard View (Tasks & CPM)
-  const standardTasks: StandardTaskTimelineItem[] = tasks.map((t) => {
-    const evidence = concreteRecords[t.id];
-    return {
-      ...t,
-      cpm: scheduleMap.get(t.id),
-      blockingTaskIds: blockingMap.get(t.id) || [],
-      dependentTaskIds: dependentMap.get(t.id) || [],
-      childTaskIds: childMap.get(t.id) || [],
-      concreteEvidenceSummary: evidence.evidenceSummary
-    };
-  });
-
-  // 3. Macro View (Phases & Project Envelope)
-  const phases = computeMacroPhases(tasks, containers, iterations, criticalSet);
-
-  const startDates = phases.map((p) => p.startDate).filter(Boolean) as string[];
-  const endDates = phases.map((p) => p.endDate).filter(Boolean) as string[];
-  startDates.sort();
-  endDates.sort();
-
-  const overallStartDate = startDates.length > 0 ? startDates[0] : undefined;
-  const overallEndDate = endDates.length > 0 ? endDates[endDates.length - 1] : undefined;
-
-  const totalTasks = tasks.length;
-  const completedTasks = tasks.filter((t) => t.semanticStatus === 'completed' || t.status === 'done').length;
-  const inProgressTasks = tasks.filter((t) => t.semanticStatus === 'in_progress' || t.status === 'in_progress').length;
-  const blockedTasks = tasks.filter((t) => t.tags?.includes('blocked') || (t as any).isBlocked).length;
-  const totalEstimatedHours = standardTasks.reduce((sum, t) => sum + (t.estimatedHours || 0), 0);
-  const totalLoggedHours = standardTasks.reduce((sum, t) => sum + (t.loggedHours || 0), 0);
-
-  const weightedProgress = standardTasks.reduce(
-    (sum, t) => sum + ((t.progress || 0) * Math.max(t.estimatedHours || 1, 1)),
-    0
-  );
-  const totalWeight = standardTasks.reduce((sum, t) => sum + Math.max(t.estimatedHours || 1, 1), 0);
-  const overallProgressPercentage = totalWeight > 0
-    ? Math.round(weightedProgress / totalWeight)
-    : (totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0);
-
-  let overallHealth: MacroPhaseHealth = 'on_track';
-  if (totalTasks > 0 && completedTasks === totalTasks) {
-    overallHealth = 'completed';
-  } else if (phases.some((p) => p.health === 'blocked')) {
-    overallHealth = 'blocked';
-  } else if (phases.some((p) => p.health === 'overdue')) {
-    overallHealth = 'overdue';
-  } else if (phases.some((p) => p.health === 'at_risk')) {
-    overallHealth = 'at_risk';
-  }
-
-  const macro: MacroTimelineSummary = {
-    projectId: project.id,
-    projectName: project.name,
-    overallStartDate,
-    overallEndDate,
-    projectedFinishDate: overallEndDate,
-    totalDurationHours: Math.round(totalEstimatedHours * 100) / 100,
-    criticalPathDurationHours: cpm.totalDurationHours,
-    overallProgressPercentage,
-    health: overallHealth,
-    totalTasks,
-    completedTasks,
-    inProgressTasks,
-    blockedTasks,
-    totalEstimatedHours: Math.round(totalEstimatedHours * 100) / 100,
-    totalLoggedHours: Math.round(totalLoggedHours * 100) / 100,
-    phases
-  };
-
-  const ladder: TimelineLadder = {
-    projectId: project.id,
-    generatedAt,
-    level: targetLevel
-  };
-
-  if (targetLevel === 'all' || targetLevel === 'macro') {
-    ladder.macro = macro;
-  }
-
-  if (targetLevel === 'all' || targetLevel === 'standard') {
-    ladder.standard = {
-      tasks: standardTasks,
-      criticalPathTaskIds: cpm.criticalTaskIds,
-      dependencies,
-      totalDurationHours: cpm.totalDurationHours
-    };
-  }
-
-  if (targetLevel === 'all' || targetLevel === 'concrete') {
-    ladder.concrete = concreteRecords;
-  }
-
-  return ladder;
-}