@transitrix/diagrams 1.0.0

package/dist/yaml-normalize.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Coerce native `Date` instances inside a parsed YAML document into ISO
+ * `YYYY-MM-DD` strings.
+ *
+ * Background: per the YAML 1.1 timestamp tag, a bare `2026-06-01` is parsed
+ * by `js-yaml` as a native `Date`, not a string. Every notation validator in
+ * this package expects ISO date strings (`typeof === 'string'` +
+ * `YYYY-MM-DD` regex), so a Date reaching validation would falsely fail
+ * shape checks even though the user followed the spec, minus quotes.
+ *
+ * The canonical, methodology-correct form is the quoted ISO string. This
+ * coercion is a backstop so the unquoted form does not silently bite.
+ *
+ * UTC-safe: uses `getUTC*` so the JS process timezone cannot drift the day.
+ * A bare `2026-06-01` parses to midnight UTC and round-trips to
+ * `"2026-06-01"` regardless of `process.env.TZ`.
+ *
+ * Walks in place and returns the same reference for convenience.
+ */
+export declare function coerceDatesToIsoStrings<T>(value: T): T;

package/dist/yaml-normalize.js

@@ -0,0 +1,57 @@
+/**
+ * Coerce native `Date` instances inside a parsed YAML document into ISO
+ * `YYYY-MM-DD` strings.
+ *
+ * Background: per the YAML 1.1 timestamp tag, a bare `2026-06-01` is parsed
+ * by `js-yaml` as a native `Date`, not a string. Every notation validator in
+ * this package expects ISO date strings (`typeof === 'string'` +
+ * `YYYY-MM-DD` regex), so a Date reaching validation would falsely fail
+ * shape checks even though the user followed the spec, minus quotes.
+ *
+ * The canonical, methodology-correct form is the quoted ISO string. This
+ * coercion is a backstop so the unquoted form does not silently bite.
+ *
+ * UTC-safe: uses `getUTC*` so the JS process timezone cannot drift the day.
+ * A bare `2026-06-01` parses to midnight UTC and round-trips to
+ * `"2026-06-01"` regardless of `process.env.TZ`.
+ *
+ * Walks in place and returns the same reference for convenience.
+ */
+export function coerceDatesToIsoStrings(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (value instanceof Date) {
+        return dateToIsoYmd(value);
+    }
+    if (typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const v = value[i];
+            if (v instanceof Date) {
+                value[i] = dateToIsoYmd(v);
+            }
+            else if (v !== null && typeof v === 'object') {
+                coerceDatesToIsoStrings(v);
+            }
+        }
+        return value;
+    }
+    const obj = value;
+    for (const key of Object.keys(obj)) {
+        const v = obj[key];
+        if (v instanceof Date) {
+            obj[key] = dateToIsoYmd(v);
+        }
+        else if (v !== null && typeof v === 'object') {
+            coerceDatesToIsoStrings(v);
+        }
+    }
+    return value;
+}
+function dateToIsoYmd(d) {
+    const y = d.getUTCFullYear();
+    const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(d.getUTCDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@transitrix/diagrams",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
+  "license": "MIT",
+  "homepage": "https://github.com/transitrix/transitrix-studio/tree/main/packages/diagrams#readme",
+  "bugs": {
+    "url": "https://github.com/transitrix/transitrix-studio/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/transitrix/transitrix-studio.git",
+    "directory": "packages/diagrams"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "reactflow": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "reactflow": "^11.11.4",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/__tests__/edge-path.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { horizontalCubicEdgePath, EDGE_MIN_HANDLE } from '../edge-path.js';
+
+describe('horizontalCubicEdgePath', () => {
+  // A short horizontal edge: |dx|=40 < EDGE_MIN_HANDLE*2, |dy|=0, so the
+  // base handle is the floor (64).
+  const sx = 0, sy = 0, tx = 40, ty = 0;
+
+  it('curvature 1 uses the floor handle (historical appearance)', () => {
+    const d = horizontalCubicEdgePath(sx, sy, tx, ty, 1);
+    // handle = max(64, 20, 0) = 64
+    expect(d).toBe(`M0,0 C${EDGE_MIN_HANDLE},0 ${40 - EDGE_MIN_HANDLE},0 40,0`);
+  });
+
+  it('default curvature equals explicit curvature 1', () => {
+    expect(horizontalCubicEdgePath(sx, sy, tx, ty)).toBe(horizontalCubicEdgePath(sx, sy, tx, ty, 1));
+  });
+
+  it('curvature 0 collapses control points onto the endpoints (straight line)', () => {
+    const d = horizontalCubicEdgePath(sx, sy, tx, ty, 0);
+    expect(d).toBe('M0,0 C0,0 40,0 40,0');
+  });
+
+  it('changing curvature changes the path output (AC#6)', () => {
+    const a = horizontalCubicEdgePath(sx, sy, tx, ty, 1);
+    const b = horizontalCubicEdgePath(sx, sy, tx, ty, 2);
+    expect(b).not.toBe(a);
+  });
+
+  it('larger curvature pushes the control handles further out', () => {
+    const handleOf = (curv: number) => {
+      // First control point x is `sx + handle`; parse it back out.
+      const m = horizontalCubicEdgePath(0, 0, 40, 0, curv).match(/^M0,0 C(-?\d+(?:\.\d+)?),0/);
+      return Number(m![1]);
+    };
+    expect(handleOf(2)).toBeGreaterThan(handleOf(1));
+    expect(handleOf(0.5)).toBeLessThan(handleOf(1));
+    expect(handleOf(2)).toBe(2 * EDGE_MIN_HANDLE);
+  });
+
+  it('handle scales with the vertical span for stacked nodes', () => {
+    // |dy|=200 ⇒ base handle = max(64, 0, 160) = 160; ×1 = 160.
+    const d = horizontalCubicEdgePath(0, 0, 0, 200, 1);
+    expect(d).toBe('M0,0 C160,0 -160,200 0,200');
+  });
+});

package/src/__tests__/scope.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { checkScopeRoot, SCOPE_MISSING_ROOT_CODE, type Scope } from '../scope.js';
+
+describe('checkScopeRoot', () => {
+  it('returns null for non-root scopes', () => {
+    expect(checkScopeRoot({ mode: 'all' }, [1, 2])).toBeNull();
+    expect(checkScopeRoot({ mode: 'level', maxLevel: 1 }, [1, 2])).toBeNull();
+  });
+
+  it('returns null when the root id is present (numeric ids compared as strings)', () => {
+    const scope: Scope = { mode: 'root', rootGoalId: '2' };
+    expect(checkScopeRoot(scope, [1, 2, 3])).toBeNull();
+  });
+
+  it('returns a SCOPE-001 warning when the root id is absent', () => {
+    const scope: Scope = { mode: 'root', rootGoalId: '99' };
+    const w = checkScopeRoot(scope, [1, 2, 3]);
+    expect(w).not.toBeNull();
+    expect(w!.code).toBe(SCOPE_MISSING_ROOT_CODE);
+    expect(w!.message).toContain('99');
+  });
+
+  it('handles string goal ids', () => {
+    expect(checkScopeRoot({ mode: 'root', rootGoalId: 'g1' }, ['g1', 'g2'])).toBeNull();
+    expect(checkScopeRoot({ mode: 'root', rootGoalId: 'gX' }, ['g1', 'g2'])).not.toBeNull();
+  });
+});

package/src/__tests__/yaml-normalize.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import yaml from 'js-yaml';
+import { coerceDatesToIsoStrings } from '../yaml-normalize.js';
+import { validateActivities } from '../activities/index.js';
+
+describe('coerceDatesToIsoStrings', () => {
+  it('replaces top-level Date with ISO YYYY-MM-DD string', () => {
+    const out = coerceDatesToIsoStrings(new Date(Date.UTC(2026, 5, 1))); // 2026-06-01 UTC
+    expect(out).toBe('2026-06-01');
+  });
+
+  it('replaces Date values inside nested arrays of objects', () => {
+    const input = {
+      activities: [
+        { id: 'A-001', start_date: new Date(Date.UTC(2026, 5, 1)), end_date: new Date(Date.UTC(2026, 5, 5)) },
+        { id: 'A-002', start_date: '2026-06-06' },
+      ],
+    };
+    coerceDatesToIsoStrings(input);
+    expect(input.activities[0].start_date).toBe('2026-06-01');
+    expect(input.activities[0].end_date).toBe('2026-06-05');
+    expect(input.activities[1].start_date).toBe('2026-06-06');
+  });
+
+  it('walks objects recursively', () => {
+    const input = {
+      project: { start_date: new Date(Date.UTC(2026, 0, 15)) },
+    };
+    coerceDatesToIsoStrings(input);
+    expect(input.project.start_date).toBe('2026-01-15');
+  });
+
+  it('leaves non-Date values untouched', () => {
+    const input = {
+      notation: 'activities',
+      activities: [{ id: 'A-001', duration: 3, start_date: '2026-06-01' }],
+    };
+    const out = coerceDatesToIsoStrings(input);
+    expect(out).toBe(input);
+    expect(input.activities[0].start_date).toBe('2026-06-01');
+    expect(input.activities[0].duration).toBe(3);
+  });
+
+  it('handles null, undefined, and primitive scalars', () => {
+    expect(coerceDatesToIsoStrings(null)).toBe(null);
+    expect(coerceDatesToIsoStrings(undefined)).toBe(undefined);
+    expect(coerceDatesToIsoStrings('hello')).toBe('hello');
+    expect(coerceDatesToIsoStrings(42)).toBe(42);
+    expect(coerceDatesToIsoStrings(true)).toBe(true);
+  });
+
+  it('handles arrays that contain bare Date elements', () => {
+    const arr = [new Date(Date.UTC(2026, 5, 1)), 'x', { d: new Date(Date.UTC(2026, 5, 2)) }];
+    coerceDatesToIsoStrings(arr);
+    expect(arr[0]).toBe('2026-06-01');
+    expect(arr[1]).toBe('x');
+    expect((arr[2] as { d: unknown }).d).toBe('2026-06-02');
+  });
+});
+
+describe('coerceDatesToIsoStrings — js-yaml integration', () => {
+  it('quoted ISO dates are preserved untouched', () => {
+    const text = [
+      'notation: activities',
+      'activities:',
+      '  - id: "A-001"',
+      '    name: "Quoted dates"',
+      '    duration: 3',
+      '    start_date: "2026-06-01"',
+      '    end_date: "2026-06-03"',
+      '',
+    ].join('\n');
+    const parsed = yaml.load(text) as { activities: { start_date: unknown; end_date: unknown }[] };
+    coerceDatesToIsoStrings(parsed);
+    expect(parsed.activities[0].start_date).toBe('2026-06-01');
+    expect(parsed.activities[0].end_date).toBe('2026-06-03');
+    const v = validateActivities(parsed);
+    expect(v.valid).toBe(true);
+  });
+
+  it('bare ISO dates are coerced to ISO strings and pass validation', () => {
+    const text = [
+      'notation: activities',
+      'activities:',
+      '  - id: "A-001"',
+      '    name: "Bare dates"',
+      '    duration: 3',
+      '    start_date: 2026-06-01',
+      '    end_date: 2026-06-03',
+      '',
+    ].join('\n');
+    const parsed = yaml.load(text) as { activities: { start_date: unknown; end_date: unknown }[] };
+    // Without coercion, js-yaml returns Date instances and the validator
+    // would emit ACT-008 because typeof !== 'string'. Sanity-check that
+    // assumption before normalisation.
+    expect(parsed.activities[0].start_date).toBeInstanceOf(Date);
+    coerceDatesToIsoStrings(parsed);
+    expect(parsed.activities[0].start_date).toBe('2026-06-01');
+    expect(parsed.activities[0].end_date).toBe('2026-06-03');
+    const v = validateActivities(parsed);
+    expect(v.valid).toBe(true);
+  });
+});
+
+// The issue calls out the timezone trap: a Date built from a bare ISO
+// date is midnight UTC, but if we used `getFullYear / getMonth / getDate`
+// instead of the UTC variants, a non-UTC process timezone would shift the
+// day. Pin a non-UTC TZ for this block so the regression bites if anyone
+// later swaps to local-time accessors.
+describe('coerceDatesToIsoStrings — non-UTC timezone', () => {
+  const originalTz = process.env.TZ;
+  beforeAll(() => {
+    // Pacific/Auckland is UTC+12/+13 — the most aggressive eastward shift
+    // available without DST gymnastics. If local-time accessors are used,
+    // `2026-06-01` parsed as midnight UTC reads back as `2026-06-01 12:00
+    // local`, which is still the right day — so use a westward TZ for the
+    // real test below. Auckland is here as a sanity case.
+    process.env.TZ = 'Pacific/Auckland';
+  });
+  afterAll(() => {
+    if (originalTz === undefined) {
+      delete process.env.TZ;
+    } else {
+      process.env.TZ = originalTz;
+    }
+  });
+
+  it('does not drift the day forward in an eastward timezone', () => {
+    const text = 'd: 2026-06-01\n';
+    const parsed = yaml.load(text) as { d: unknown };
+    coerceDatesToIsoStrings(parsed);
+    expect(parsed.d).toBe('2026-06-01');
+  });
+});
+
+describe('coerceDatesToIsoStrings — westward (negative offset) timezone', () => {
+  const originalTz = process.env.TZ;
+  beforeAll(() => {
+    // Pacific/Honolulu is UTC-10, no DST. Midnight UTC `2026-06-01` reads
+    // back as `2026-05-31 14:00 local`. Local-time accessors would yield
+    // `2026-05-31` — wrong by one day. UTC accessors yield `2026-06-01`.
+    process.env.TZ = 'Pacific/Honolulu';
+  });
+  afterAll(() => {
+    if (originalTz === undefined) {
+      delete process.env.TZ;
+    } else {
+      process.env.TZ = originalTz;
+    }
+  });
+
+  it('does not drift the day backward in a westward timezone', () => {
+    const text = 'd: 2026-06-01\n';
+    const parsed = yaml.load(text) as { d: unknown };
+    coerceDatesToIsoStrings(parsed);
+    expect(parsed.d).toBe('2026-06-01');
+  });
+});

package/src/activities/__tests__/cpm.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import { computeCpm } from '../cpm.js';
+import type { Activity } from '../types.js';
+
+// PMBoK textbook example (5-activity network):
+//   A(5) → B(8) → D(7)
+//   A(5) → C(3) → D(7)
+//   D(7) → E(4)
+// Critical path: A→B→D→E = 5+8+7+4 = 24
+// A: ES=0, EF=5, LS=0, LF=5, slack=0 (critical)
+// B: ES=5, EF=13, LS=5, LF=13, slack=0 (critical)
+// C: ES=5, EF=8, LS=10, LF=13, slack=5
+// D: ES=13, EF=20, LS=13, LF=20, slack=0 (critical)
+// E: ES=20, EF=24, LS=20, LF=24, slack=0 (critical)
+
+const pmBokActivities: Activity[] = [
+  { id: 'A', name: 'A', duration: 5 },
+  { id: 'B', name: 'B', duration: 8, predecessors: ['A'] },
+  { id: 'C', name: 'C', duration: 3, predecessors: ['A'] },
+  { id: 'D', name: 'D', duration: 7, predecessors: ['B', 'C'] },
+  { id: 'E', name: 'E', duration: 4, predecessors: ['D'] },
+];
+
+describe('computeCpm — PMBoK textbook example', () => {
+  const result = computeCpm(pmBokActivities);
+
+  it('computes ES for each activity', () => {
+    expect(result.get('A')!.es).toBe(0);
+    expect(result.get('B')!.es).toBe(5);
+    expect(result.get('C')!.es).toBe(5);
+    expect(result.get('D')!.es).toBe(13);
+    expect(result.get('E')!.es).toBe(20);
+  });
+
+  it('computes EF for each activity', () => {
+    expect(result.get('A')!.ef).toBe(5);
+    expect(result.get('B')!.ef).toBe(13);
+    expect(result.get('C')!.ef).toBe(8);
+    expect(result.get('D')!.ef).toBe(20);
+    expect(result.get('E')!.ef).toBe(24);
+  });
+
+  it('computes LS for each activity', () => {
+    expect(result.get('A')!.ls).toBe(0);
+    expect(result.get('B')!.ls).toBe(5);
+    expect(result.get('C')!.ls).toBe(10);
+    expect(result.get('D')!.ls).toBe(13);
+    expect(result.get('E')!.ls).toBe(20);
+  });
+
+  it('computes LF for each activity', () => {
+    expect(result.get('A')!.lf).toBe(5);
+    expect(result.get('B')!.lf).toBe(13);
+    expect(result.get('C')!.lf).toBe(13);
+    expect(result.get('D')!.lf).toBe(20);
+    expect(result.get('E')!.lf).toBe(24);
+  });
+
+  it('computes slack', () => {
+    expect(result.get('A')!.slack).toBe(0);
+    expect(result.get('B')!.slack).toBe(0);
+    expect(result.get('C')!.slack).toBe(5);
+    expect(result.get('D')!.slack).toBe(0);
+    expect(result.get('E')!.slack).toBe(0);
+  });
+
+  it('marks critical path activities', () => {
+    expect(result.get('A')!.isCritical).toBe(true);
+    expect(result.get('B')!.isCritical).toBe(true);
+    expect(result.get('C')!.isCritical).toBe(false);
+    expect(result.get('D')!.isCritical).toBe(true);
+    expect(result.get('E')!.isCritical).toBe(true);
+  });
+});
+
+describe('computeCpm — edge cases', () => {
+  it('returns empty map for empty input', () => {
+    const result = computeCpm([]);
+    expect(result.size).toBe(0);
+  });
+
+  it('single node with no predecessors: ES=0, EF=duration, slack=0', () => {
+    const result = computeCpm([{ id: 'A', name: 'A', duration: 5 }]);
+    expect(result.get('A')!.es).toBe(0);
+    expect(result.get('A')!.ef).toBe(5);
+    expect(result.get('A')!.slack).toBe(0);
+    expect(result.get('A')!.isCritical).toBe(true);
+  });
+
+  it('activity with no duration treated as zero-duration', () => {
+    const result = computeCpm([{ id: 'A', name: 'Milestone' }]);
+    expect(result.get('A')!.ef).toBe(0);
+  });
+
+  it('linear chain A(3)→B(5)→C(2): total=10, all critical', () => {
+    const activities: Activity[] = [
+      { id: 'A', name: 'A', duration: 3 },
+      { id: 'B', name: 'B', duration: 5, predecessors: ['A'] },
+      { id: 'C', name: 'C', duration: 2, predecessors: ['B'] },
+    ];
+    const result = computeCpm(activities);
+    expect(result.get('A')!.ef).toBe(3);
+    expect(result.get('B')!.ef).toBe(8);
+    expect(result.get('C')!.ef).toBe(10);
+    expect(result.get('A')!.isCritical).toBe(true);
+    expect(result.get('B')!.isCritical).toBe(true);
+    expect(result.get('C')!.isCritical).toBe(true);
+  });
+
+  it('parallel paths: longer path is critical, shorter has positive slack', () => {
+    // A(1) → C(10)
+    // B(5) → C(10)
+    // merge at D(2): predecessors [C]
+    // path via A: 1+10+2=13; path via B: 5+10+2=17 → critical
+    const activities: Activity[] = [
+      { id: 'A', name: 'A', duration: 1 },
+      { id: 'B', name: 'B', duration: 5 },
+      { id: 'C', name: 'C', duration: 10, predecessors: ['A', 'B'] },
+      { id: 'D', name: 'D', duration: 2, predecessors: ['C'] },
+    ];
+    const result = computeCpm(activities);
+    // C.es = max(EF[A], EF[B]) = max(1,5) = 5
+    expect(result.get('C')!.es).toBe(5);
+    expect(result.get('A')!.isCritical).toBe(false);
+    expect(result.get('B')!.isCritical).toBe(true);
+    expect(result.get('C')!.isCritical).toBe(true);
+    expect(result.get('D')!.isCritical).toBe(true);
+    expect(result.get('A')!.slack).toBe(4);
+    expect(result.get('B')!.slack).toBe(0);
+  });
+});
+
+describe('computeCpm — cycle defence', () => {
+  // Pre-release should-fix: Kahn's topo-order silently omits cyclic nodes.
+  // The validator's ACT-006 is the authoritative cycle error, but
+  // layoutActivities is reachable without validation, so computeCpm must
+  // still produce an entry for every activity (filled with neutral values
+  // for omitted cyclic ones) — otherwise consumers see `undefined` and
+  // bars render without CPM data.
+
+  it('emits entries for every activity on a 2-node mutual cycle', () => {
+    const result = computeCpm([
+      { id: 'A', name: 'A', duration: 3, predecessors: ['B'] },
+      { id: 'B', name: 'B', duration: 2, predecessors: ['A'] },
+    ]);
+    expect(result.size).toBe(2);
+    expect(result.get('A')).toMatchObject({ es: 0, ef: 0, slack: 0, isCritical: false });
+    expect(result.get('B')).toMatchObject({ es: 0, ef: 0, slack: 0, isCritical: false });
+  });
+
+  it('keeps real CPM data for the acyclic prefix when a cycle exists downstream', () => {
+    // A → B is acyclic; C ↔ D is a mutual cycle disconnected from A/B.
+    const result = computeCpm([
+      { id: 'A', name: 'A', duration: 5 },
+      { id: 'B', name: 'B', duration: 3, predecessors: ['A'] },
+      { id: 'C', name: 'C', duration: 2, predecessors: ['D'] },
+      { id: 'D', name: 'D', duration: 2, predecessors: ['C'] },
+    ]);
+    expect(result.get('A')?.ef).toBe(5);
+    expect(result.get('B')?.ef).toBe(8);
+    expect(result.get('C')).toMatchObject({ es: 0, ef: 0, isCritical: false });
+    expect(result.get('D')).toMatchObject({ es: 0, ef: 0, isCritical: false });
+  });
+});