@transitrix/diagrams 1.0.0

package/dist/activities/gantt.js

@@ -0,0 +1,250 @@
+import { computeCpm } from './cpm.js';
+// ── Calendar helpers (UTC midnight to avoid timezone shifts) ─────────────────
+const DEFAULT_WORKING_DAYS = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+const WEEKDAY_BY_INDEX = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+function resolveCalendar(cal) {
+    const wdRaw = Array.isArray(cal?.working_days) && cal.working_days.length > 0
+        ? cal.working_days
+        : DEFAULT_WORKING_DAYS;
+    const workingDays = new Set();
+    for (const d of wdRaw) {
+        if (typeof d === 'string')
+            workingDays.add(d.toLowerCase());
+    }
+    const holidays = new Set();
+    for (const h of cal?.holidays ?? []) {
+        if (typeof h === 'string')
+            holidays.add(h);
+    }
+    return { workingDays, holidays };
+}
+function parseISO(s) {
+    const [y, m, d] = s.split('-').map((p) => Number.parseInt(p, 10));
+    return new Date(Date.UTC(y, m - 1, d));
+}
+function formatISO(d) {
+    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, n) {
+    const r = new Date(d.getTime());
+    r.setUTCDate(r.getUTCDate() + n);
+    return r;
+}
+function isWorkingDay(d, cal) {
+    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, n, cal) {
+    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);
+}
+function classifyActivities(activities) {
+    const childCount = new Map();
+    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 = [];
+    const phases = [];
+    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, leaves) {
+    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) {
+    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 = [];
+    const barById = new Map();
+    if (mode === 'pinned') {
+        for (const a of leaves) {
+            const startDate = a.start_date;
+            const endDate = a.end_date;
+            const isMilestone = a.duration === 0 || startDate === endDate;
+            const bar = {
+                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;
+        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 = {
+                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();
+        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();
+        function spanOf(activityId) {
+            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 = null;
+            let maxEnd = 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 = {
+                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 = [];
+    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) {
+    return result.unavailable === true;
+}

package/dist/activities/index.d.ts

@@ -0,0 +1,5 @@
+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/dist/activities/index.js

@@ -0,0 +1,4 @@
+export { validateActivities } from './validate.js';
+export { computeCpm } from './cpm.js';
+export { layoutActivities } from './layout.js';
+export { computeGanttLayout, isGanttUnavailable } from './gantt.js';

package/dist/activities/layout.d.ts

@@ -0,0 +1,2 @@
+import type { ActivityDoc, ActivitiesLayout, ActivitiesLayoutOptions } from './types.js';
+export declare function layoutActivities(doc: ActivityDoc, options?: ActivitiesLayoutOptions): ActivitiesLayout;

package/dist/activities/layout.js

@@ -0,0 +1,103 @@
+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, options = {}) {
+    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();
+    const inDegree = new Map();
+    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();
+    const queue = [];
+    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();
+    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();
+    const nodes = [];
+    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 = {
+                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 = [];
+    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/dist/activities/types.d.ts

@@ -0,0 +1,125 @@
+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;
+}
+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;

package/dist/activities/types.js

@@ -0,0 +1 @@
+export {};

package/dist/activities/validate.d.ts

@@ -0,0 +1,2 @@
+import type { ActivityValidationResult } from './types.js';
+export declare function validateActivities(input: unknown): ActivityValidationResult;