@critical-path/core 0.5.2 → 0.6.0

package/src/domain/entities.ts

@@ -0,0 +1,390 @@
+import type {
+  Task,
+  Project,
+  Workflow,
+  TimeEntry,
+  Priority,
+  TaskStatus,
+  CustomFieldDefinition,
+  CreateTaskInput,
+  CreateProjectInput
+} from '../types/index.js';
+import type {
+  DomainEvent,
+  TaskCreatedEvent,
+  TaskStatusChangedEvent,
+  TaskUpdatedEvent,
+  TimeLoggedEvent,
+  ProjectCreatedEvent
+} from './events.js';
+import { validateTransition, WorkflowValidationError } from '../utils/workflow.js';
+import { resolveStatusDefinition } from '../utils/status.js';
+import { validateCustomFieldValues } from './custom-fields.js';
+import { generateProjectKey } from '../utils/key.js';
+
+export abstract class BaseEntity {
+  public readonly id: string;
+  public createdAt: string;
+  public updatedAt: string;
+  private uncommittedEvents: DomainEvent[] = [];
+
+  constructor(id: string, createdAt?: string, updatedAt?: string) {
+    const now = new Date().toISOString();
+    this.id = id;
+    this.createdAt = createdAt || now;
+    this.updatedAt = updatedAt || now;
+  }
+
+  protected raiseEvent(event: DomainEvent): void {
+    this.uncommittedEvents.push(event);
+  }
+
+  public getUncommittedEvents(): DomainEvent[] {
+    return [...this.uncommittedEvents];
+  }
+
+  public clearEvents(): void {
+    this.uncommittedEvents = [];
+  }
+
+  protected markUpdated(): void {
+    this.updatedAt = new Date().toISOString();
+  }
+}
+
+export class TaskEntity extends BaseEntity {
+  public projectId: string;
+  public key?: string;
+  public title: string;
+  public description?: string;
+  public status: TaskStatus;
+  public priority: Priority;
+  public taskType?: string;
+  public assigneeId?: string;
+  public reporterId?: string;
+  public reviewerId?: string;
+  public iterationId?: string;
+  public teamId?: string;
+  public containerId?: string;
+  public plannedStartDate?: string;
+  public actualStartDate?: string;
+  public actualEndDate?: string;
+  public dueDate?: string;
+  public estimatedHours?: number;
+  public loggedHours?: number;
+  public actualHours?: number;
+  public billableHours?: number;
+  public estimatedDurationMinutes?: number;
+  public actualDurationMinutes?: number;
+  public billableDurationMinutes?: number;
+  public progress?: number;
+  public tags?: string[];
+  public customFields?: Record<string, unknown>;
+  public parentId?: string;
+
+  constructor(data: Task) {
+    super(data.id, data.createdAt, data.updatedAt);
+    this.projectId = data.projectId;
+    this.key = data.key;
+    this.title = data.title;
+    this.description = data.description;
+    this.status = data.status;
+    this.priority = data.priority;
+    this.taskType = data.taskType;
+    this.assigneeId = data.assigneeId;
+    this.reporterId = data.reporterId;
+    this.reviewerId = data.reviewerId;
+    this.iterationId = data.iterationId;
+    this.teamId = data.teamId;
+    this.containerId = data.containerId;
+    this.plannedStartDate = data.plannedStartDate;
+    this.actualStartDate = data.actualStartDate;
+    this.actualEndDate = data.actualEndDate;
+    this.dueDate = data.dueDate;
+    this.estimatedHours = data.estimatedHours;
+    this.loggedHours = data.loggedHours ?? 0;
+    this.actualHours = data.actualHours;
+    this.billableHours = data.billableHours;
+    this.estimatedDurationMinutes = data.estimatedDurationMinutes;
+    this.actualDurationMinutes = data.actualDurationMinutes;
+    this.billableDurationMinutes = data.billableDurationMinutes;
+    this.progress = data.progress ?? 0;
+    this.tags = data.tags ? [...data.tags] : [];
+    this.customFields = data.customFields ? { ...data.customFields } : {};
+    this.parentId = data.parentId;
+  }
+
+  public static create(
+    input: CreateTaskInput,
+    options?: { id?: string; workflow?: Workflow; customFieldDefs?: CustomFieldDefinition[] }
+  ): TaskEntity {
+    const id = options?.id || `task_${Math.random().toString(36).substring(2, 9)}`;
+    const now = new Date().toISOString();
+
+    if (options?.customFieldDefs) {
+      validateCustomFieldValues(options.customFieldDefs, input.customFields);
+    }
+
+    const task = new TaskEntity({
+      ...input,
+      id,
+      createdAt: now,
+      updatedAt: now,
+      status: input.status || options?.workflow?.defaultStatusKey || 'todo',
+      priority: input.priority || 'medium',
+      loggedHours: input.loggedHours ?? 0,
+      progress: input.progress ?? 0,
+      tags: input.tags ?? [],
+      customFields: input.customFields ?? {}
+    });
+
+    const createdEvent: TaskCreatedEvent = {
+      id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+      name: 'task.created',
+      aggregateId: task.id,
+      aggregateType: 'Task',
+      occurredAt: now,
+      payload: { task: task.toPlain() }
+    };
+    task.raiseEvent(createdEvent);
+
+    return task;
+  }
+
+  public transitionTo(
+    newStatus: string,
+    workflow?: Workflow,
+    options?: { statusDefs?: Workflow['statuses']; actorId?: string }
+  ): this {
+    if (this.status === newStatus) return this;
+
+    const isValid = validateTransition(workflow, this.status, newStatus);
+    if (!isValid) {
+      throw new WorkflowValidationError(this.status, newStatus, workflow?.id);
+    }
+
+    const previousStatus = this.status;
+    this.status = newStatus;
+    const now = new Date().toISOString();
+
+    const statusDef = resolveStatusDefinition(newStatus, options?.statusDefs || workflow?.statuses);
+    if (statusDef.executionState === 'active' && !this.actualStartDate) {
+      this.actualStartDate = now;
+    }
+    if (statusDef.completionState === 'done') {
+      this.actualEndDate = now;
+      if (this.progress !== undefined && this.progress < 100) {
+        this.progress = 100;
+      }
+    }
+
+    this.markUpdated();
+
+    const event: TaskStatusChangedEvent = {
+      id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+      name: 'task.status_changed',
+      aggregateId: this.id,
+      aggregateType: 'Task',
+      occurredAt: now,
+      payload: {
+        task: this.toPlain(),
+        previousStatus,
+        newStatus
+      }
+    };
+    this.raiseEvent(event);
+
+    return this;
+  }
+
+  public logTime(
+    entry: { hours: number; isBillable?: boolean; userId?: string; description?: string }
+  ): TimeEntry {
+    if (entry.hours <= 0) {
+      throw new Error('Logged hours must be a positive number.');
+    }
+
+    this.loggedHours = (this.loggedHours || 0) + entry.hours;
+    this.actualHours = (this.actualHours || 0) + entry.hours;
+    if (entry.isBillable !== false) {
+      this.billableHours = (this.billableHours || 0) + entry.hours;
+    }
+
+    const now = new Date().toISOString();
+    this.markUpdated();
+
+    const timeEntry: TimeEntry = {
+      id: `time_${Math.random().toString(36).substring(2, 9)}`,
+      taskId: this.id,
+      userId: entry.userId || this.assigneeId || 'system',
+      hours: entry.hours,
+      isBillable: entry.isBillable ?? true,
+      description: entry.description,
+      loggedAt: now
+    };
+
+    const event: TimeLoggedEvent = {
+      id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+      name: 'time.logged',
+      aggregateId: this.id,
+      aggregateType: 'Task',
+      occurredAt: now,
+      payload: {
+        taskId: this.id,
+        timeEntry
+      }
+    };
+    this.raiseEvent(event);
+
+    return timeEntry;
+  }
+
+  public update(updates: Partial<Task>, customFieldDefs?: CustomFieldDefinition[]): this {
+    const previous = this.toPlain();
+
+    if (updates.customFields && customFieldDefs) {
+      validateCustomFieldValues(customFieldDefs, {
+        ...this.customFields,
+        ...updates.customFields
+      });
+    }
+
+    Object.assign(this, updates);
+    this.markUpdated();
+
+    const event: TaskUpdatedEvent = {
+      id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+      name: 'task.updated',
+      aggregateId: this.id,
+      aggregateType: 'Task',
+      occurredAt: new Date().toISOString(),
+      payload: {
+        task: this.toPlain(),
+        previous
+      }
+    };
+    this.raiseEvent(event);
+
+    return this;
+  }
+
+  public toPlain(): Task {
+    return {
+      id: this.id,
+      projectId: this.projectId,
+      key: this.key,
+      title: this.title,
+      description: this.description,
+      status: this.status,
+      priority: this.priority,
+      taskType: this.taskType,
+      assigneeId: this.assigneeId,
+      reporterId: this.reporterId,
+      reviewerId: this.reviewerId,
+      iterationId: this.iterationId,
+      teamId: this.teamId,
+      containerId: this.containerId,
+      plannedStartDate: this.plannedStartDate,
+      actualStartDate: this.actualStartDate,
+      actualEndDate: this.actualEndDate,
+      dueDate: this.dueDate,
+      estimatedHours: this.estimatedHours,
+      loggedHours: this.loggedHours,
+      actualHours: this.actualHours,
+      billableHours: this.billableHours,
+      estimatedDurationMinutes: this.estimatedDurationMinutes,
+      actualDurationMinutes: this.actualDurationMinutes,
+      billableDurationMinutes: this.billableDurationMinutes,
+      progress: this.progress,
+      tags: this.tags ? [...this.tags] : [],
+      customFields: this.customFields ? { ...this.customFields } : {},
+      parentId: this.parentId,
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt
+    };
+  }
+}
+
+export class ProjectEntity extends BaseEntity {
+  public key: string;
+  public name: string;
+  public description?: string;
+  public ownerId?: string;
+  public members?: string[];
+  public teamIds?: string[];
+  public workflowId?: string;
+  public workflow?: Workflow;
+  public taskTypes?: Project['taskTypes'];
+  public statusDefinitions?: Project['statusDefinitions'];
+  public priorityDefinitions?: Project['priorityDefinitions'];
+  public customFieldDefinitions?: CustomFieldDefinition[];
+
+  constructor(data: Project) {
+    super(data.id, data.createdAt, data.updatedAt);
+    this.key = data.key || generateProjectKey(data.name);
+    this.name = data.name;
+    this.description = data.description;
+    this.ownerId = data.ownerId;
+    this.members = data.members ? [...data.members] : [];
+    this.teamIds = data.teamIds ? [...data.teamIds] : [];
+    this.workflowId = data.workflowId;
+    this.workflow = data.workflow;
+    this.taskTypes = data.taskTypes;
+    this.statusDefinitions = data.statusDefinitions;
+    this.priorityDefinitions = data.priorityDefinitions;
+    this.customFieldDefinitions = data.customFieldDefinitions ? [...data.customFieldDefinitions] : [];
+  }
+
+  public static create(
+    input: CreateProjectInput,
+    options?: { id?: string }
+  ): ProjectEntity {
+    const id = options?.id || `proj_${Math.random().toString(36).substring(2, 9)}`;
+    const now = new Date().toISOString();
+    const key = input.key || generateProjectKey(input.name);
+
+    const project = new ProjectEntity({
+      ...input,
+      id,
+      key,
+      createdAt: now,
+      updatedAt: now
+    });
+
+    const event: ProjectCreatedEvent = {
+      id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+      name: 'project.created',
+      aggregateId: project.id,
+      aggregateType: 'Project',
+      occurredAt: now,
+      payload: { project: project.toPlain() }
+    };
+    project.raiseEvent(event);
+
+    return project;
+  }
+
+  public validateCustomFields(values?: Record<string, unknown>): void {
+    validateCustomFieldValues(this.customFieldDefinitions, values);
+  }
+
+  public toPlain(): Project {
+    return {
+      id: this.id,
+      key: this.key,
+      name: this.name,
+      description: this.description,
+      ownerId: this.ownerId,
+      members: this.members ? [...this.members] : [],
+      teamIds: this.teamIds ? [...this.teamIds] : [],
+      workflowId: this.workflowId,
+      workflow: this.workflow,
+      taskTypes: this.taskTypes,
+      statusDefinitions: this.statusDefinitions,
+      priorityDefinitions: this.priorityDefinitions,
+      customFieldDefinitions: this.customFieldDefinitions ? [...this.customFieldDefinitions] : [],
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt
+    };
+  }
+}

package/src/domain/events.ts

@@ -0,0 +1,171 @@
+import type {
+  Task,
+  Project,
+  Workflow,
+  Iteration,
+  Team,
+  TaskContainer,
+  TaskDependency,
+  TimeEntry,
+  Comment
+} from '../types/index.js';
+
+export interface DomainEvent<TPayload = Record<string, unknown>> {
+  readonly id: string;
+  readonly name: string;
+  readonly aggregateId: string;
+  readonly aggregateType: 'Task' | 'Project' | 'Workflow' | 'Iteration' | 'Team' | 'Container' | 'Dependency';
+  readonly occurredAt: string;
+  readonly payload: TPayload;
+}
+
+// Concrete Domain Events
+export interface TaskCreatedEvent extends DomainEvent<{ task: Task }> {
+  readonly name: 'task.created';
+  readonly aggregateType: 'Task';
+}
+
+export interface TaskUpdatedEvent extends DomainEvent<{ task: Task; previous: Task }> {
+  readonly name: 'task.updated';
+  readonly aggregateType: 'Task';
+}
+
+export interface TaskStatusChangedEvent extends DomainEvent<{
+  task: Task;
+  previousStatus: string;
+  newStatus: string;
+}> {
+  readonly name: 'task.status_changed';
+  readonly aggregateType: 'Task';
+}
+
+export interface TaskDeletedEvent extends DomainEvent<{ taskId: string; projectId: string; title: string }> {
+  readonly name: 'task.deleted';
+  readonly aggregateType: 'Task';
+}
+
+export interface TimeLoggedEvent extends DomainEvent<{ timeEntry: TimeEntry; taskId: string }> {
+  readonly name: 'time.logged';
+  readonly aggregateType: 'Task';
+}
+
+export interface CommentAddedEvent extends DomainEvent<{ comment: Comment; taskId: string }> {
+  readonly name: 'comment.created';
+  readonly aggregateType: 'Task';
+}
+
+export interface TaskDependencyAddedEvent extends DomainEvent<{ dependency: TaskDependency }> {
+  readonly name: 'dependency.added';
+  readonly aggregateType: 'Dependency';
+}
+
+export interface ProjectCreatedEvent extends DomainEvent<{ project: Project }> {
+  readonly name: 'project.created';
+  readonly aggregateType: 'Project';
+}
+
+export interface ProjectUpdatedEvent extends DomainEvent<{ project: Project; previous: Project }> {
+  readonly name: 'project.updated';
+  readonly aggregateType: 'Project';
+}
+
+export interface WorkflowCreatedEvent extends DomainEvent<{ workflow: Workflow }> {
+  readonly name: 'workflow.created';
+  readonly aggregateType: 'Workflow';
+}
+
+export interface WorkflowUpdatedEvent extends DomainEvent<{ workflow: Workflow; previous: Workflow }> {
+  readonly name: 'workflow.updated';
+  readonly aggregateType: 'Workflow';
+}
+
+export interface WorkflowDeletedEvent extends DomainEvent<{ workflowId: string; name: string }> {
+  readonly name: 'workflow.deleted';
+  readonly aggregateType: 'Workflow';
+}
+
+export interface IterationStartedEvent extends DomainEvent<{ iteration: Iteration }> {
+  readonly name: 'iteration.started';
+  readonly aggregateType: 'Iteration';
+}
+
+export interface IterationCompletedEvent extends DomainEvent<{ iteration: Iteration }> {
+  readonly name: 'iteration.completed';
+  readonly aggregateType: 'Iteration';
+}
+
+export interface TeamCreatedEvent extends DomainEvent<{ team: Team }> {
+  readonly name: 'team.created';
+  readonly aggregateType: 'Team';
+}
+
+export interface ContainerCreatedEvent extends DomainEvent<{ container: TaskContainer }> {
+  readonly name: 'container.created';
+  readonly aggregateType: 'Container';
+}
+
+export type CriticalPathDomainEvent =
+  | TaskCreatedEvent
+  | TaskUpdatedEvent
+  | TaskStatusChangedEvent
+  | TaskDeletedEvent
+  | TimeLoggedEvent
+  | CommentAddedEvent
+  | TaskDependencyAddedEvent
+  | ProjectCreatedEvent
+  | ProjectUpdatedEvent
+  | WorkflowCreatedEvent
+  | WorkflowUpdatedEvent
+  | WorkflowDeletedEvent
+  | IterationStartedEvent
+  | IterationCompletedEvent
+  | TeamCreatedEvent
+  | ContainerCreatedEvent;
+
+export type DomainEventHandler<T extends DomainEvent = DomainEvent> = (event: T) => Promise<void> | void;
+
+export class DomainEventBus {
+  private handlers = new Map<string, Array<DomainEventHandler<any>>>();
+
+  subscribe<T extends DomainEvent = DomainEvent>(
+    eventName: T['name'] | '*',
+    handler: DomainEventHandler<T>
+  ): () => void {
+    const list = this.handlers.get(eventName) || [];
+    list.push(handler);
+    this.handlers.set(eventName, list);
+
+    return () => {
+      const currentList = this.handlers.get(eventName) || [];
+      this.handlers.set(
+        eventName,
+        currentList.filter((h) => h !== handler)
+      );
+    };
+  }
+
+  async publish(event: DomainEvent): Promise<void> {
+    const directHandlers = this.handlers.get(event.name) || [];
+    const wildcardHandlers = this.handlers.get('*') || [];
+    const allHandlers = [...directHandlers, ...wildcardHandlers];
+
+    for (const handler of allHandlers) {
+      try {
+        await handler(event);
+      } catch (err) {
+        // Prevent subscriber failures from breaking event pipeline
+        console.error(`[DomainEventBus] Handler error on event "${event.name}":`, err);
+      }
+    }
+  }
+
+  async publishAll(events: DomainEvent[]): Promise<void> {
+    for (const event of events) {
+      await this.publish(event);
+    }
+  }
+
+  clear(): void {
+    this.handlers.clear();
+  }
+}

package/src/domain/graph.ts

@@ -0,0 +1,70 @@
+import type { TaskDependency } from '../types/index.js';
+
+export class CircularDependencyError extends Error {
+  public readonly taskId: string;
+  public readonly dependsOnTaskId: string;
+  public readonly cyclePath?: string[];
+
+  constructor(taskId: string, dependsOnTaskId: string, cyclePath?: string[]) {
+    const pathStr = cyclePath ? ` (Cycle detected: ${cyclePath.join(' -> ')})` : '';
+    super(`Cannot add dependency from "${taskId}" to "${dependsOnTaskId}" because it would create a circular dependency cycle${pathStr}.`);
+    this.name = 'CircularDependencyError';
+    this.taskId = taskId;
+    this.dependsOnTaskId = dependsOnTaskId;
+    this.cyclePath = cyclePath;
+  }
+}
+
+/**
+ * Validates that adding a dependency from taskId to dependsOnTaskId will not create a cycle in the task graph.
+ * A cycle occurs if dependsOnTaskId already transitively depends on taskId.
+ */
+export function detectDependencyCycle(
+  existingDependencies: TaskDependency[],
+  newDependency: { taskId: string; dependsOnTaskId: string }
+): { hasCycle: boolean; cyclePath?: string[] } {
+  const { taskId, dependsOnTaskId } = newDependency;
+
+  // Self-dependency check
+  if (taskId === dependsOnTaskId) {
+    return { hasCycle: true, cyclePath: [taskId, taskId] };
+  }
+
+  // Build adjacency list: node -> array of nodes it depends on
+  const adj = new Map<string, string[]>();
+  for (const dep of existingDependencies) {
+    const targets = adj.get(dep.taskId) || [];
+    targets.push(dep.dependsOnTaskId);
+    adj.set(dep.taskId, targets);
+  }
+
+  // Check if dependsOnTaskId can reach taskId via existing dependency paths
+  const visited = new Set<string>();
+  const path: string[] = [taskId, dependsOnTaskId];
+
+  function dfs(current: string): boolean {
+    if (current === taskId) {
+      return true;
+    }
+    if (visited.has(current)) {
+      return false;
+    }
+    visited.add(current);
+
+    const neighbors = adj.get(current) || [];
+    for (const next of neighbors) {
+      path.push(next);
+      if (dfs(next)) {
+        return true;
+      }
+      path.pop();
+    }
+    return false;
+  }
+
+  const hasCycle = dfs(dependsOnTaskId);
+  return {
+    hasCycle,
+    cyclePath: hasCycle ? path : undefined
+  };
+}

package/src/domain/index.ts

@@ -0,0 +1,4 @@
+export * from './events.js';
+export * from './custom-fields.js';
+export * from './graph.js';
+export * from './entities.js';