@transitrix/diagrams 1.0.0

package/src/activities/gantt.ts

@@ -0,0 +1,276 @@
+import type {
+  Activity,
+  ActivityDoc,
+  GanttBar,
+  GanttLayout,
+  GanttLink,
+  GanttResult,
+  ProjectCalendar,
+  Weekday,
+} from './types.js';
+import { computeCpm } from './cpm.js';
+
+// ── Calendar helpers (UTC midnight to avoid timezone shifts) ─────────────────
+
+const DEFAULT_WORKING_DAYS: Weekday[] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+const WEEKDAY_BY_INDEX: Weekday[] = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+
+interface ResolvedCalendar {
+  workingDays: Set<Weekday>;
+  holidays: Set<string>;
+}
+
+function resolveCalendar(cal: ProjectCalendar | undefined): ResolvedCalendar {
+  const wdRaw = Array.isArray(cal?.working_days) && cal!.working_days.length > 0
+    ? cal!.working_days
+    : DEFAULT_WORKING_DAYS;
+  const workingDays = new Set<Weekday>();
+  for (const d of wdRaw) {
+    if (typeof d === 'string') workingDays.add(d.toLowerCase() as Weekday);
+  }
+  const holidays = new Set<string>();
+  for (const h of cal?.holidays ?? []) {
+    if (typeof h === 'string') holidays.add(h);
+  }
+  return { workingDays, holidays };
+}
+
+function parseISO(s: string): Date {
+  const [y, m, d] = s.split('-').map((p) => Number.parseInt(p, 10));
+  return new Date(Date.UTC(y, m - 1, d));
+}
+
+function formatISO(d: Date): string {
+  const yyyy = d.getUTCFullYear().toString().padStart(4, '0');
+  const mm = (d.getUTCMonth() + 1).toString().padStart(2, '0');
+  const dd = d.getUTCDate().toString().padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+function addUtcDays(d: Date, n: number): Date {
+  const r = new Date(d.getTime());
+  r.setUTCDate(r.getUTCDate() + n);
+  return r;
+}
+
+function isWorkingDay(d: Date, cal: ResolvedCalendar): boolean {
+  if (cal.holidays.has(formatISO(d))) return false;
+  return cal.workingDays.has(WEEKDAY_BY_INDEX[d.getUTCDay()]);
+}
+
+/**
+ * Date of the n-th (0-indexed) working day at or after `startDate`.
+ *
+ * If `startDate` itself is a working day, that's index 0. Walks forward day
+ * by day, counting only working days. The loop is bounded by a sanity cap to
+ * avoid hangs if the calendar ever has zero working days (which the validator
+ * should already have flagged via ACT-014, but defending here too).
+ */
+function nthWorkingDay(startDate: string, n: number, cal: ResolvedCalendar): string {
+  if (n < 0) return startDate;
+  let cur = parseISO(startDate);
+  let count = 0;
+  const sanityLimit = Math.max(10, n) * 10 + 365;
+  for (let i = 0; i < sanityLimit; i++) {
+    if (isWorkingDay(cur, cal)) {
+      if (count === n) return formatISO(cur);
+      count++;
+    }
+    cur = addUtcDays(cur, 1);
+  }
+  return formatISO(cur);
+}
+
+// ── Mode detection + leaf classification ─────────────────────────────────────
+
+interface ActivityRoles {
+  childCount: Map<string, number>;
+  leaves: Activity[];
+  phases: Activity[];
+}
+
+function classifyActivities(activities: Activity[]): ActivityRoles {
+  const childCount = new Map<string, number>();
+  for (const a of activities) {
+    if (typeof a.parent === 'string' && a.parent.length > 0) {
+      childCount.set(a.parent, (childCount.get(a.parent) ?? 0) + 1);
+    }
+  }
+  const leaves: Activity[] = [];
+  const phases: Activity[] = [];
+  for (const a of activities) {
+    if ((childCount.get(a.id) ?? 0) > 0) phases.push(a);
+    else leaves.push(a);
+  }
+  return { childCount, leaves, phases };
+}
+
+function detectMode(doc: ActivityDoc, leaves: Activity[]): 'computed' | 'pinned' | null {
+  if (leaves.length === 0) return null;
+  const allPinned = leaves.every(
+    (a) => typeof a.start_date === 'string' && typeof a.end_date === 'string',
+  );
+  if (allPinned) return 'pinned';
+  const hasProjectStart =
+    typeof doc.project?.start_date === 'string' && doc.project.start_date.length > 0;
+  const allHaveDuration = leaves.every(
+    (a) => typeof a.duration === 'number' && Number.isFinite(a.duration) && a.duration >= 0,
+  );
+  if (hasProjectStart && allHaveDuration) return 'computed';
+  return null;
+}
+
+// ── Main entry ───────────────────────────────────────────────────────────────
+
+export function computeGanttLayout(doc: ActivityDoc): GanttResult {
+  const activities = doc.activities ?? [];
+  if (activities.length === 0) {
+    return { unavailable: true, reason: 'Document has no activities to render on a Gantt timeline.' };
+  }
+
+  const { leaves, phases } = classifyActivities(activities);
+  const mode = detectMode(doc, leaves);
+  if (mode === null) {
+    const reason = leaves.length === 0
+      ? 'All activities are parent (phase) activities — no leaf activities to place on the timeline.'
+      : 'Gantt view unavailable: provide either project.start_date plus durations on every leaf activity (computed mode), or per-activity start_date and end_date on every leaf (pinned mode).';
+    return { unavailable: true, reason };
+  }
+
+  const bars: GanttBar[] = [];
+  const barById = new Map<string, GanttBar>();
+
+  if (mode === 'pinned') {
+    for (const a of leaves) {
+      const startDate = a.start_date as string;
+      const endDate = a.end_date as string;
+      const isMilestone = a.duration === 0 || startDate === endDate;
+      const bar: GanttBar = {
+        id: a.id,
+        name: a.name,
+        kind: isMilestone ? 'milestone' : 'leaf',
+        startDate,
+        endDate,
+        isCritical: false, // pinned mode does not compute CPM
+        parent: typeof a.parent === 'string' ? a.parent : undefined,
+        data: a,
+      };
+      bars.push(bar);
+      barById.set(a.id, bar);
+    }
+  } else {
+    // computed: project.start_date + CPM ES + working-day calendar
+    const cpm = computeCpm(activities);
+    const projectStart = (doc.project!.start_date as string);
+    const calendar = resolveCalendar(doc.project?.calendar);
+    for (const a of leaves) {
+      const c = cpm.get(a.id);
+      const es = c?.es ?? 0;
+      const dur = a.duration ?? 0;
+      const startDate = nthWorkingDay(projectStart, es, calendar);
+      const endDate = dur === 0
+        ? startDate
+        : nthWorkingDay(projectStart, es + dur - 1, calendar);
+      const bar: GanttBar = {
+        id: a.id,
+        name: a.name,
+        kind: dur === 0 ? 'milestone' : 'leaf',
+        startDate,
+        endDate,
+        isCritical: c?.isCritical ?? false,
+        parent: typeof a.parent === 'string' ? a.parent : undefined,
+        data: a,
+      };
+      bars.push(bar);
+      barById.set(a.id, bar);
+    }
+  }
+
+  // Phase rollup — earliest child start to latest child end across all
+  // descendants. Walk depth-first so nested phases inherit grandchildren too.
+  if (phases.length > 0) {
+    const childrenOf = new Map<string, Activity[]>();
+    for (const a of activities) {
+      if (typeof a.parent === 'string' && a.parent.length > 0) {
+        if (!childrenOf.has(a.parent)) childrenOf.set(a.parent, []);
+        childrenOf.get(a.parent)!.push(a);
+      }
+    }
+
+    const phaseSpan = new Map<string, { startDate: string; endDate: string; isCritical: boolean }>();
+    function spanOf(activityId: string): { startDate: string; endDate: string; isCritical: boolean } | null {
+      const cached = phaseSpan.get(activityId);
+      if (cached) return cached;
+      const leaf = barById.get(activityId);
+      if (leaf) return { startDate: leaf.startDate, endDate: leaf.endDate, isCritical: leaf.isCritical };
+      const children = childrenOf.get(activityId) ?? [];
+      if (children.length === 0) return null;
+      let minStart: string | null = null;
+      let maxEnd: string | null = null;
+      let anyCritical = false;
+      for (const child of children) {
+        const s = spanOf(child.id);
+        if (!s) continue;
+        if (minStart === null || s.startDate < minStart) minStart = s.startDate;
+        if (maxEnd === null || s.endDate > maxEnd) maxEnd = s.endDate;
+        if (s.isCritical) anyCritical = true;
+      }
+      if (minStart === null || maxEnd === null) return null;
+      const span = { startDate: minStart, endDate: maxEnd, isCritical: anyCritical };
+      phaseSpan.set(activityId, span);
+      return span;
+    }
+
+    for (const p of phases) {
+      const span = spanOf(p.id);
+      if (!span) continue;
+      const bar: GanttBar = {
+        id: p.id,
+        name: p.name,
+        kind: 'phase',
+        startDate: span.startDate,
+        endDate: span.endDate,
+        isCritical: span.isCritical,
+        parent: typeof p.parent === 'string' ? p.parent : undefined,
+        data: p,
+      };
+      bars.push(bar);
+      barById.set(p.id, bar);
+    }
+  }
+
+  // Predecessor link lines. Only between leaves (phases derive their dates).
+  const links: GanttLink[] = [];
+  for (const a of leaves) {
+    for (const predId of a.predecessors ?? []) {
+      const sourceBar = barById.get(predId);
+      const targetBar = barById.get(a.id);
+      if (!sourceBar || !targetBar) continue;
+      links.push({
+        sourceId: predId,
+        targetId: a.id,
+        isCritical: sourceBar.isCritical && targetBar.isCritical,
+      });
+    }
+  }
+
+  // Timeline bounds — pure min/max over the bar set.
+  let timelineStart = bars[0].startDate;
+  let timelineEnd = bars[0].endDate;
+  for (const b of bars) {
+    if (b.startDate < timelineStart) timelineStart = b.startDate;
+    if (b.endDate > timelineEnd) timelineEnd = b.endDate;
+  }
+
+  return {
+    mode,
+    timelineStart,
+    timelineEnd,
+    bars,
+    links,
+  };
+}
+
+export function isGanttUnavailable(result: GanttResult): result is { unavailable: true; reason: string } {
+  return (result as { unavailable?: boolean }).unavailable === true;
+}

package/src/activities/index.ts

@@ -0,0 +1,28 @@
+export type {
+  Activity,
+  ActivityDoc,
+  ActivityValidationError,
+  ActivityValidationWarning,
+  ActivityValidationResult,
+  CpmValues,
+  CpmResult,
+  LayoutNode,
+  LayoutEdge,
+  ActivitiesLayout,
+  ActivitiesLayoutOptions,
+  Weekday,
+  ProjectCalendar,
+  ProjectBlock,
+  GanttMode,
+  GanttBarKind,
+  GanttBar,
+  GanttLink,
+  GanttLayout,
+  GanttUnavailable,
+  GanttResult,
+} from './types.js';
+
+export { validateActivities } from './validate.js';
+export { computeCpm } from './cpm.js';
+export { layoutActivities } from './layout.js';
+export { computeGanttLayout, isGanttUnavailable } from './gantt.js';

package/src/activities/layout.ts

@@ -0,0 +1,112 @@
+import type { ActivityDoc, Activity, ActivitiesLayout, ActivitiesLayoutOptions, LayoutNode, LayoutEdge } from './types.js';
+import { computeCpm } from './cpm.js';
+
+const NODE_W = 200;
+const NODE_H = 80;
+const H_GAP = 80;
+const V_GAP = 24;
+
+export function layoutActivities(doc: ActivityDoc, options: ActivitiesLayoutOptions = {}): ActivitiesLayout {
+  const { horizontalGap = H_GAP, verticalGap = V_GAP } = options;
+  const activities = doc.activities;
+  if (activities.length === 0) {
+    return { nodes: [], edges: [], bounds: { x: 0, y: 0, width: 0, height: 0 } };
+  }
+
+  const cpm = computeCpm(activities);
+
+  // Topological column assignment via Kahn's
+  const successors = new Map<string, string[]>();
+  const inDegree = new Map<string, number>();
+  for (const a of activities) {
+    successors.set(a.id, []);
+    inDegree.set(a.id, 0);
+  }
+  for (const a of activities) {
+    for (const pred of (a.predecessors ?? [])) {
+      successors.get(pred)?.push(a.id);
+      inDegree.set(a.id, (inDegree.get(a.id) ?? 0) + 1);
+    }
+  }
+
+  const column = new Map<string, number>();
+  const queue: string[] = [];
+  for (const a of activities) {
+    if ((inDegree.get(a.id) ?? 0) === 0) queue.push(a.id);
+  }
+
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    const col = column.get(id) ?? 0;
+    for (const succ of (successors.get(id) ?? [])) {
+      const newCol = Math.max(column.get(succ) ?? 0, col + 1);
+      column.set(succ, newCol);
+      const newDeg = (inDegree.get(succ) ?? 1) - 1;
+      inDegree.set(succ, newDeg);
+      if (newDeg === 0) queue.push(succ);
+    }
+  }
+
+  // Group activities by column, sort within each column by `sort` then `id`
+  const cols = new Map<number, Activity[]>();
+  for (const a of activities) {
+    const col = column.get(a.id) ?? 0;
+    if (!cols.has(col)) cols.set(col, []);
+    cols.get(col)!.push(a);
+  }
+  for (const list of cols.values()) {
+    list.sort((a, b) => {
+      const sortA = a.sort ?? Number.MAX_SAFE_INTEGER;
+      const sortB = b.sort ?? Number.MAX_SAFE_INTEGER;
+      if (sortA !== sortB) return sortA - sortB;
+      return a.id.localeCompare(b.id);
+    });
+  }
+
+  // Assign positions
+  const nodeMap = new Map<string, LayoutNode>();
+  const nodes: LayoutNode[] = [];
+  const colCount = Math.max(0, ...[...cols.keys()]) + 1;
+
+  for (let c = 0; c < colCount; c++) {
+    const list = cols.get(c) ?? [];
+    const x = c * (NODE_W + horizontalGap);
+    let y = 0;
+    for (const a of list) {
+      const node: LayoutNode = {
+        id: a.id,
+        x,
+        y,
+        width: NODE_W,
+        height: NODE_H,
+        data: a,
+        cpm: cpm.get(a.id),
+      };
+      nodes.push(node);
+      nodeMap.set(a.id, node);
+      y += NODE_H + verticalGap;
+    }
+  }
+
+  // Build edges
+  const edges: LayoutEdge[] = [];
+  for (const a of activities) {
+    for (const predId of (a.predecessors ?? [])) {
+      if (nodeMap.has(predId)) {
+        const predCpm = cpm.get(predId);
+        const succCpm = cpm.get(a.id);
+        const isCritical = (predCpm?.isCritical ?? false) && (succCpm?.isCritical ?? false);
+        edges.push({ sourceId: predId, targetId: a.id, isCritical });
+      }
+    }
+  }
+
+  if (nodes.length === 0) return { nodes, edges, bounds: { x: 0, y: 0, width: 0, height: 0 } };
+
+  const minX = Math.min(...nodes.map(n => n.x));
+  const minY = Math.min(...nodes.map(n => n.y));
+  const maxX = Math.max(...nodes.map(n => n.x + n.width));
+  const maxY = Math.max(...nodes.map(n => n.y + n.height));
+
+  return { nodes, edges, bounds: { x: minX, y: minY, width: maxX - minX, height: maxY - minY } };
+}

package/src/activities/types.ts

@@ -0,0 +1,148 @@
+// Activities historically exposed PREFIXED validation type names. Keep them
+// as aliases of the shared shape (`../validation-types.ts`) so external
+// consumers keep working.
+import type {
+  ValidationError as SharedValidationError,
+  ValidationWarning as SharedValidationWarning,
+  ValidationResult as SharedValidationResult,
+} from '../validation-types.js';
+
+export type ActivityValidationError = SharedValidationError;
+export type ActivityValidationWarning = SharedValidationWarning;
+export type ActivityValidationResult = SharedValidationResult;
+
+export interface Activity {
+  id: string;
+  name: string;
+  duration?: number;
+  activity_type?: string;
+  goals?: string[];
+  scenario?: string;
+  parent?: string;
+  predecessors?: string[];
+  owner?: string;
+  unit?: string;
+  employee?: string;
+  score?: number;
+  sort?: number;
+  tags?: string[];
+  start_date?: string;
+  end_date?: string;
+  labor_cost?: number;
+  resources_cost?: number;
+  effort?: number;
+  link?: string;
+  description?: string;
+  delivers_changes?: string[];
+}
+
+export type Weekday = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+
+export interface ProjectCalendar {
+  working_days?: Weekday[];
+  hours_per_day?: number;
+  holidays?: string[];
+}
+
+export interface ProjectBlock {
+  start_date?: string;
+  calendar?: ProjectCalendar;
+}
+
+export interface ActivityDoc {
+  notation: string;
+  spec_version?: string;
+  title?: string;
+  description?: string;
+  version?: string;
+  date?: string;
+  author?: string;
+  project?: ProjectBlock;
+  activities: Activity[];
+}
+
+export interface CpmValues {
+  es: number;
+  ef: number;
+  ls: number;
+  lf: number;
+  slack: number;
+  isCritical: boolean;
+}
+
+export type CpmResult = Map<string, CpmValues>;
+
+export interface LayoutNode {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  data: Activity;
+  cpm?: CpmValues;
+}
+
+export interface LayoutEdge {
+  sourceId: string;
+  targetId: string;
+  isCritical: boolean;
+}
+
+export interface ActivitiesLayout {
+  nodes: LayoutNode[];
+  edges: LayoutEdge[];
+  bounds: { x: number; y: number; width: number; height: number };
+}
+
+export interface ActivitiesLayoutOptions {
+  /** Horizontal gap (px) between CPM columns. Default matches the historical hardcoded value. */
+  horizontalGap?: number;
+  /** Vertical gap (px) between stacked activity nodes. Default matches the historical hardcoded value. */
+  verticalGap?: number;
+}
+
+// ── Gantt view (spec §9) ─────────────────────────────────────────────────────
+
+export type GanttMode = 'computed' | 'pinned';
+
+export type GanttBarKind = 'leaf' | 'milestone' | 'phase';
+
+export interface GanttBar {
+  id: string;
+  name: string;
+  kind: GanttBarKind;
+  /** Inclusive start date as ISO 8601 yyyy-mm-dd. */
+  startDate: string;
+  /** Inclusive end date as ISO 8601 yyyy-mm-dd. For milestones equals startDate. */
+  endDate: string;
+  /** True if the activity is on the critical path (only when CPM applies — computed mode). */
+  isCritical: boolean;
+  /** Optional parent activity id (for phase grouping). */
+  parent?: string;
+  /** Activity record. */
+  data: Activity;
+}
+
+export interface GanttLink {
+  sourceId: string;
+  targetId: string;
+  isCritical: boolean;
+}
+
+export interface GanttLayout {
+  /** Render mode that produced this layout. */
+  mode: GanttMode;
+  /** Inclusive timeline bounds as ISO 8601 yyyy-mm-dd. */
+  timelineStart: string;
+  timelineEnd: string;
+  bars: GanttBar[];
+  links: GanttLink[];
+}
+
+export interface GanttUnavailable {
+  unavailable: true;
+  /** Human-readable explanation of what is missing. */
+  reason: string;
+}
+
+export type GanttResult = GanttLayout | GanttUnavailable;