@transitrix/diagrams 1.0.0

package/dist/activities/__tests__/layout.test.d.ts

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

package/dist/activities/__tests__/layout.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest';
+import { layoutActivities } from '../layout.js';
+const diamondDoc = {
+    notation: 'activities',
+    activities: [
+        { id: 'A', name: 'Start', duration: 3 },
+        { id: 'B', name: 'Left', duration: 5, predecessors: ['A'] },
+        { id: 'C', name: 'Right', duration: 2, predecessors: ['A'] },
+        { id: 'D', name: 'Merge', duration: 4, predecessors: ['B', 'C'] },
+    ],
+};
+describe('layoutActivities', () => {
+    it('returns empty layout for empty activities', () => {
+        const layout = layoutActivities({ notation: 'activities', activities: [] });
+        expect(layout.nodes).toHaveLength(0);
+        expect(layout.edges).toHaveLength(0);
+    });
+    it('assigns each node a unique position', () => {
+        const layout = layoutActivities(diamondDoc);
+        const positions = layout.nodes.map(n => `${n.x},${n.y}`);
+        const unique = new Set(positions);
+        expect(unique.size).toBe(layout.nodes.length);
+    });
+    it('assigns predecessors to strictly lower column indices than successors', () => {
+        const layout = layoutActivities(diamondDoc);
+        const colOf = new Map(layout.nodes.map(n => [n.id, Math.round(n.x / 280)]));
+        // A is in col 0; B and C are in col 1; D is in col 2
+        expect(colOf.get('A')).toBeLessThan(colOf.get('B'));
+        expect(colOf.get('A')).toBeLessThan(colOf.get('C'));
+        expect(colOf.get('B')).toBeLessThan(colOf.get('D'));
+        expect(colOf.get('C')).toBeLessThan(colOf.get('D'));
+    });
+    it('produces edges connecting predecessors to successors', () => {
+        const layout = layoutActivities(diamondDoc);
+        const edgePairs = layout.edges.map(e => `${e.sourceId}->${e.targetId}`);
+        expect(edgePairs).toContain('A->B');
+        expect(edgePairs).toContain('A->C');
+        expect(edgePairs).toContain('B->D');
+        expect(edgePairs).toContain('C->D');
+    });
+    it('marks critical edges correctly', () => {
+        // A(3)→B(5)→D(4): critical path = 3+5+4=12; C(2) has slack
+        const layout = layoutActivities(diamondDoc);
+        const edgeMap = new Map(layout.edges.map(e => [`${e.sourceId}->${e.targetId}`, e.isCritical]));
+        expect(edgeMap.get('A->B')).toBe(true);
+        expect(edgeMap.get('B->D')).toBe(true);
+        expect(edgeMap.get('A->C')).toBe(false);
+        expect(edgeMap.get('C->D')).toBe(false);
+    });
+    it('attaches CPM values to nodes', () => {
+        const layout = layoutActivities(diamondDoc);
+        const nodeA = layout.nodes.find(n => n.id === 'A');
+        expect(nodeA.cpm).toBeDefined();
+        expect(nodeA.cpm.es).toBe(0);
+        expect(nodeA.cpm.ef).toBe(3);
+        expect(nodeA.cpm.isCritical).toBe(true);
+    });
+    it('respects sort field for ordering within a column', () => {
+        const doc = {
+            notation: 'activities',
+            activities: [
+                { id: 'A', name: 'Root', duration: 1 },
+                { id: 'B', name: 'Second', duration: 1, predecessors: ['A'], sort: 20 },
+                { id: 'C', name: 'First', duration: 1, predecessors: ['A'], sort: 10 },
+            ],
+        };
+        const layout = layoutActivities(doc);
+        const col1Nodes = layout.nodes.filter(n => n.id === 'B' || n.id === 'C').sort((a, b) => a.y - b.y);
+        // C (sort=10) should appear above B (sort=20)
+        expect(col1Nodes[0].id).toBe('C');
+        expect(col1Nodes[1].id).toBe('B');
+    });
+    it('computes non-empty bounds for non-empty activities', () => {
+        const layout = layoutActivities(diamondDoc);
+        expect(layout.bounds.width).toBeGreaterThan(0);
+        expect(layout.bounds.height).toBeGreaterThan(0);
+    });
+    // vkgeorgia/strategy#75 — configurable spacing.
+    it('empty options reproduce the default no-arg layout', () => {
+        const a = layoutActivities(diamondDoc);
+        const b = layoutActivities(diamondDoc, {});
+        expect(b.nodes.map(n => `${n.id}:${n.x},${n.y}`)).toEqual(a.nodes.map(n => `${n.id}:${n.x},${n.y}`));
+    });
+    it('larger horizontalGap pushes downstream columns further right', () => {
+        const xOfD = (h) => layoutActivities(diamondDoc, { horizontalGap: h }).nodes.find(n => n.id === 'D').x;
+        expect(xOfD(200)).toBeGreaterThan(xOfD(80));
+    });
+    it('larger verticalGap increases the gap between stacked column nodes', () => {
+        const gapOf = (v) => {
+            const ys = layoutActivities(diamondDoc, { verticalGap: v })
+                .nodes.filter(n => n.id === 'B' || n.id === 'C')
+                .map(n => n.y)
+                .sort((a, b) => a - b);
+            return ys[1] - ys[0];
+        };
+        expect(gapOf(100)).toBeGreaterThan(gapOf(24));
+    });
+});

package/dist/activities/__tests__/validate.test.d.ts

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

package/dist/activities/__tests__/validate.test.js

@@ -0,0 +1,363 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { validateActivities } from '../validate.js';
+const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'activities');
+const minimalValid = {
+    notation: 'activities',
+    activities: [
+        { id: 'A-001', name: 'Start', duration: 3 },
+        { id: 'A-002', name: 'End', duration: 2, predecessors: ['A-001'] },
+    ],
+};
+describe('validateActivities', () => {
+    it('ACT-001 — accepts valid notation field', () => {
+        const r = validateActivities(minimalValid);
+        expect(r.valid).toBe(true);
+    });
+    it('ACT-001 — rejects missing notation', () => {
+        const r = validateActivities({ activities: [] });
+        expect(r.valid).toBe(false);
+        expect(r.errors[0].code).toBe('ACT-001');
+    });
+    it('ACT-001 — rejects wrong notation value', () => {
+        const r = validateActivities({ notation: 'bpmn', activities: [] });
+        expect(r.valid).toBe(false);
+        expect(r.errors[0].code).toBe('ACT-001');
+        expect(r.errors[0].message).toContain('"bpmn"');
+    });
+    it('ACT-002 — rejects activity with missing id', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ name: 'No ID', duration: 1 }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-002')).toBe(true);
+    });
+    it('ACT-002 — rejects activity with empty id', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ id: '  ', name: 'Empty ID', duration: 1 }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-002')).toBe(true);
+    });
+    it('ACT-003 — rejects activity with missing name', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ id: 'A-001', duration: 1 }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-003')).toBe(true);
+    });
+    it('ACT-004 — rejects duplicate ids', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-001', name: 'First', duration: 1 },
+                { id: 'A-001', name: 'Duplicate', duration: 2 },
+            ],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-004')).toBe(true);
+    });
+    it('ACT-005 — rejects unknown predecessor reference', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ id: 'A-001', name: 'Task', duration: 1, predecessors: ['MISSING'] }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-005')).toBe(true);
+    });
+    it('ACT-005 — passes when predecessor exists', () => {
+        const r = validateActivities(minimalValid);
+        expect(r.valid).toBe(true);
+        expect(r.errors.some(e => e.code === 'ACT-005')).toBe(false);
+    });
+    it('ACT-006 — rejects cyclic dependency', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-001', name: 'Task A', duration: 1, predecessors: ['A-002'] },
+                { id: 'A-002', name: 'Task B', duration: 1, predecessors: ['A-001'] },
+            ],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-006')).toBe(true);
+    });
+    it('ACT-007 — rejects self-loop', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ id: 'A-001', name: 'Task', duration: 1, predecessors: ['A-001'] }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-007')).toBe(true);
+    });
+    it('ACT-008 — rejects end_date before start_date', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-001', name: 'Task', duration: 5, start_date: '2026-06-10', end_date: '2026-06-01' },
+            ],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-008')).toBe(true);
+    });
+    it('ACT-008 — accepts end_date equal to start_date', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-001', name: 'Task', duration: 0, start_date: '2026-06-01', end_date: '2026-06-01' },
+            ],
+        });
+        expect(r.errors.some(e => e.code === 'ACT-008')).toBe(false);
+    });
+    it('ACT-008 — rejects non-ISO start_date format', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-001', name: 'Task', duration: 5, start_date: 'June 1 2026' },
+            ],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-008' && /start_date/.test(e.message))).toBe(true);
+    });
+    it('ACT-008 — rejects non-ISO end_date format', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-001', name: 'Task', duration: 5, end_date: '2026/06/30' },
+            ],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-008' && /end_date/.test(e.message))).toBe(true);
+    });
+    it('ACT-008 — does not raise the order-compare error when dates are malformed', () => {
+        // If start_date and end_date are both wrongly formatted, the file already
+        // has two ACT-008 format errors — adding a third "end < start" complaint
+        // on top would be misleading because the lexicographic compare is
+        // meaningless on non-ISO strings.
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-001', name: 'Task', duration: 5, start_date: 'tomorrow', end_date: 'yesterday' },
+            ],
+        });
+        expect(r.errors.filter(e => e.code === 'ACT-008').length).toBe(2);
+        expect(r.errors.every(e => /must be ISO 8601 YYYY-MM-DD/.test(e.message))).toBe(true);
+    });
+    it('ACT-009 — rejects negative duration', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ id: 'A-001', name: 'Task', duration: -1 }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-009')).toBe(true);
+    });
+    it('ACT-009 — accepts zero duration', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ id: 'A-001', name: 'Milestone', duration: 0 }],
+        });
+        expect(r.errors.some(e => e.code === 'ACT-009')).toBe(false);
+    });
+    it('ACT-010 — rejects singular "goal:" field', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ id: 'A-001', name: 'Task', duration: 1, goal: 'GOAL-001' }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-010')).toBe(true);
+    });
+    it('ACT-010 — rejects singular "predecessor:" field', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-001', name: 'First', duration: 1 },
+                { id: 'A-002', name: 'Task', duration: 1, predecessor: 'A-001' },
+            ],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-010')).toBe(true);
+    });
+    it('ACT-010 — rejects singular "tag:" field', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ id: 'A-001', name: 'Task', duration: 1, tag: 'q3' }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-010')).toBe(true);
+    });
+    it('ACT-011 — warns when duration is absent', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [{ id: 'A-001', name: 'No duration' }],
+        });
+        expect(r.valid).toBe(true);
+        expect(r.warnings.some(w => w.code === 'ACT-011')).toBe(true);
+    });
+    it('ACT-013 — warns on structurally orphan activity', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-001', name: 'Connected', duration: 1 },
+                { id: 'A-002', name: 'Orphan', duration: 1 },
+                { id: 'A-003', name: 'End', duration: 1, predecessors: ['A-001'] },
+            ],
+        });
+        expect(r.valid).toBe(true);
+        const orphanWarnings = r.warnings.filter(w => w.code === 'ACT-013');
+        expect(orphanWarnings.some(w => w.message.includes('A-002'))).toBe(true);
+    });
+    it('full valid example passes with no errors', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            title: 'Test Project',
+            activities: [
+                { id: 'A', name: 'Start', duration: 3 },
+                { id: 'B', name: 'Middle', duration: 5, predecessors: ['A'] },
+                { id: 'C', name: 'End', duration: 2, predecessors: ['B'] },
+            ],
+        });
+        expect(r.valid).toBe(true);
+        expect(r.errors).toHaveLength(0);
+    });
+    // ── Project block + calendar (ACT-014, ACT-015) ───────────────────────────
+    it('ACT-014 — rejects unknown weekday in working_days', () => {
+        const r = validateActivities({
+            ...minimalValid,
+            project: { start_date: '2026-06-01', calendar: { working_days: ['mon', 'funday'] } },
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-014' && /funday/.test(e.message))).toBe(true);
+    });
+    it('ACT-014 — rejects duplicate weekday entries', () => {
+        const r = validateActivities({
+            ...minimalValid,
+            project: { calendar: { working_days: ['mon', 'tue', 'mon'] } },
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-014' && /duplicate/i.test(e.message))).toBe(true);
+    });
+    it('ACT-014 — accepts mixed-case weekday names', () => {
+        const r = validateActivities({
+            ...minimalValid,
+            project: { start_date: '2026-06-01', calendar: { working_days: ['MON', 'Tue', 'wed', 'thu', 'fri'] } },
+        });
+        expect(r.errors.some(e => e.code === 'ACT-014')).toBe(false);
+    });
+    it('ACT-015 — rejects non-ISO holiday date', () => {
+        const r = validateActivities({
+            ...minimalValid,
+            project: { start_date: '2026-06-01', calendar: { holidays: ['2026-07-04', 'July 4 2026'] } },
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-015' && /July 4 2026/.test(e.message))).toBe(true);
+    });
+    it('ACT-015 — accepts an array of ISO dates', () => {
+        const r = validateActivities({
+            ...minimalValid,
+            project: { start_date: '2026-06-01', calendar: { holidays: ['2026-07-04', '2026-12-25'] } },
+        });
+        expect(r.errors.some(e => e.code === 'ACT-015')).toBe(false);
+    });
+    // ── Milestone date equality (ACT-016) ─────────────────────────────────────
+    it('ACT-016 — rejects milestone with mismatched start/end dates', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'M-1', name: 'Launch', duration: 0, start_date: '2026-06-01', end_date: '2026-06-02' },
+            ],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ACT-016')).toBe(true);
+    });
+    it('ACT-016 — accepts milestone with equal start/end dates', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'M-1', name: 'Launch', duration: 0, start_date: '2026-06-01', end_date: '2026-06-01' },
+            ],
+        });
+        expect(r.errors.some(e => e.code === 'ACT-016')).toBe(false);
+    });
+    // ── Phase warnings (ACT-017, ACT-018) ─────────────────────────────────────
+    it('ACT-017 — warns when a referenced-as-parent activity carries its own duration', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'PHASE-1', name: 'Design', duration: 5 },
+                { id: 'A-1', name: 'Child', duration: 3, parent: 'PHASE-1' },
+            ],
+        });
+        expect(r.valid).toBe(true);
+        expect(r.warnings.some(w => w.code === 'ACT-017' && /PHASE-1/.test(w.message))).toBe(true);
+    });
+    it('ACT-017 — no warning when phase omits duration/dates and rolls up from children', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'PHASE-1', name: 'Design' },
+                { id: 'A-1', name: 'Child', duration: 3, parent: 'PHASE-1' },
+            ],
+        });
+        expect(r.warnings.some(w => w.code === 'ACT-017')).toBe(false);
+    });
+    it('ACT-018 — warns when an activity with no duration is not referenced as parent', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-1', name: 'Has duration', duration: 3 },
+                { id: 'P-EMPTY', name: 'Looks like phase but no children' },
+            ],
+        });
+        expect(r.warnings.some(w => w.code === 'ACT-018' && /P-EMPTY/.test(w.message))).toBe(true);
+    });
+    it('ACT-018 — no warning when the no-duration activity has at least one child', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'PHASE-1', name: 'Phase' },
+                { id: 'A-1', name: 'Child', duration: 3, parent: 'PHASE-1' },
+            ],
+        });
+        expect(r.warnings.some(w => w.code === 'ACT-018')).toBe(false);
+    });
+    // ── Gantt-renderability notice (ACT-019) ──────────────────────────────────
+    it('ACT-019 — warns when neither project.start_date nor pinned dates exist', () => {
+        const r = validateActivities(minimalValid);
+        expect(r.warnings.some(w => w.code === 'ACT-019')).toBe(true);
+    });
+    it('ACT-019 — no warning when project.start_date is set', () => {
+        const r = validateActivities({ ...minimalValid, project: { start_date: '2026-06-01' } });
+        expect(r.warnings.some(w => w.code === 'ACT-019')).toBe(false);
+    });
+    it('ACT-019 — no warning when every activity has pinned dates', () => {
+        const r = validateActivities({
+            notation: 'activities',
+            activities: [
+                { id: 'A-1', name: 'A', duration: 3, start_date: '2026-06-01', end_date: '2026-06-04' },
+            ],
+        });
+        expect(r.warnings.some(w => w.code === 'ACT-019')).toBe(false);
+    });
+    it('[blocker] tolerates a null element in activities[] without throwing', () => {
+        const r = validateActivities({ ...minimalValid, activities: [null] });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+    });
+});
+describe('activities examples (regression)', () => {
+    const files = fs.readdirSync(EXAMPLES_DIR).filter(f => f.endsWith('.yaml'));
+    expect(files.length).toBeGreaterThan(0);
+    for (const file of files) {
+        it(`validates tests/fixtures/notation-corpus/activities/${file}`, () => {
+            const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+            const parsed = yaml.load(text);
+            const r = validateActivities(parsed);
+            expect(r.errors).toEqual([]);
+            expect(r.valid).toBe(true);
+        });
+    }
+});

package/dist/activities/cpm.d.ts

@@ -0,0 +1,2 @@
+import type { Activity, CpmResult } from './types.js';
+export declare function computeCpm(activities: Activity[]): CpmResult;

package/dist/activities/cpm.js

@@ -0,0 +1,86 @@
+export function computeCpm(activities) {
+    const result = new Map();
+    if (activities.length === 0)
+        return result;
+    // Build successor map and in-degree for topological sort
+    const successors = new Map();
+    const predecessors = new Map();
+    for (const a of activities) {
+        successors.set(a.id, []);
+        predecessors.set(a.id, a.predecessors?.filter(p => p !== a.id) ?? []);
+    }
+    for (const a of activities) {
+        for (const pred of (predecessors.get(a.id) ?? [])) {
+            successors.get(pred)?.push(a.id);
+        }
+    }
+    // Topological sort (Kahn's)
+    const inDegree = new Map();
+    for (const a of activities) {
+        inDegree.set(a.id, (predecessors.get(a.id) ?? []).length);
+    }
+    const queue = [];
+    for (const a of activities) {
+        if ((inDegree.get(a.id) ?? 0) === 0)
+            queue.push(a.id);
+    }
+    const topoOrder = [];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        topoOrder.push(id);
+        for (const succ of (successors.get(id) ?? [])) {
+            const newDeg = (inDegree.get(succ) ?? 1) - 1;
+            inDegree.set(succ, newDeg);
+            if (newDeg === 0)
+                queue.push(succ);
+        }
+    }
+    const actById = new Map(activities.map(a => [a.id, a]));
+    // Forward pass
+    const es = new Map();
+    const ef = new Map();
+    for (const id of topoOrder) {
+        const a = actById.get(id);
+        const dur = a.duration ?? 0;
+        const maxPredEf = Math.max(0, ...(predecessors.get(id) ?? []).map(p => ef.get(p) ?? 0));
+        es.set(id, maxPredEf);
+        ef.set(id, maxPredEf + dur);
+    }
+    // Project finish
+    const projectFinish = Math.max(0, ...[...ef.values()]);
+    // Backward pass
+    const ls = new Map();
+    const lf = new Map();
+    for (const id of [...topoOrder].reverse()) {
+        const a = actById.get(id);
+        const dur = a.duration ?? 0;
+        const succs = successors.get(id) ?? [];
+        const minSuccLs = succs.length === 0 ? projectFinish : Math.min(...succs.map(s => ls.get(s) ?? projectFinish));
+        lf.set(id, minSuccLs);
+        ls.set(id, minSuccLs - dur);
+    }
+    // Assemble result
+    for (const id of topoOrder) {
+        const esV = es.get(id) ?? 0;
+        const efV = ef.get(id) ?? 0;
+        const lsV = ls.get(id) ?? 0;
+        const lfV = lf.get(id) ?? 0;
+        const slack = lsV - esV;
+        result.set(id, { es: esV, ef: efV, ls: lsV, lf: lfV, slack, isCritical: slack <= 0 });
+    }
+    // Cycle defence: Kahn's topo-order silently omits any activity that's part
+    // of a cycle (its in-degree never reaches zero), and the forward/backward
+    // passes above skip those nodes. The validator's ACT-006 is the
+    // authoritative cycle error — but layoutActivities is reachable without
+    // validation, so fill the omitted nodes with neutral CPM values so
+    // downstream consumers don't see `undefined` entries. Cyclic activities
+    // simply render without critical-path highlighting.
+    if (topoOrder.length < activities.length) {
+        for (const a of activities) {
+            if (!result.has(a.id)) {
+                result.set(a.id, { es: 0, ef: 0, ls: 0, lf: 0, slack: 0, isCritical: false });
+            }
+        }
+    }
+    return result;
+}

package/dist/activities/gantt.d.ts

@@ -0,0 +1,6 @@
+import type { ActivityDoc, GanttResult } from './types.js';
+export declare function computeGanttLayout(doc: ActivityDoc): GanttResult;
+export declare function isGanttUnavailable(result: GanttResult): result is {
+    unavailable: true;
+    reason: string;
+};