@transitrix/diagrams 1.0.0

package/src/goals/__tests__/validate.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect } from 'vitest';
+import { validateGoalTree } from '../validate.js';
+
+const VALID_TREE = {
+  goal_types: [
+    { name: 'Strategy', level: 0 },
+    { name: 'Business Goal', level: 1 },
+    { name: 'Project', level: 2 },
+  ],
+  goals: [
+    { id: 1, name: 'Triple revenue', type: 'Strategy', level: 0, parent_id: 0 },
+    { id: 2, name: 'Launch EU', type: 'Business Goal', level: 1, parent_id: 1 },
+    { id: 3, name: 'Open Berlin office', type: 'Project', level: 2, parent_id: 2 },
+  ],
+};
+
+describe('validateGoalTree', () => {
+  it('passes on valid input', () => {
+    const r = validateGoalTree(VALID_TREE);
+    expect(r.valid).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('SCHEMA_INVALID: rejects non-object', () => {
+    expect(validateGoalTree(null).valid).toBe(false);
+    expect(validateGoalTree('string').errors[0].code).toBe('SCHEMA_INVALID');
+  });
+
+  it('SCHEMA_INVALID: rejects missing goals array', () => {
+    const r = validateGoalTree({ goal_types: [] });
+    expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+  });
+
+  it('DUPLICATE_ID: detects duplicate goal ids', () => {
+    const tree = {
+      ...VALID_TREE,
+      goals: [
+        { id: 1, name: 'A', type: 'Strategy', level: 0, parent_id: 0 },
+        { id: 1, name: 'B', type: 'Strategy', level: 0, parent_id: 0 },
+      ],
+    };
+    const r = validateGoalTree(tree);
+    expect(r.errors.some(e => e.code === 'DUPLICATE_ID')).toBe(true);
+  });
+
+  it('EMPTY_NAME: detects empty name', () => {
+    const tree = {
+      ...VALID_TREE,
+      goals: [{ id: 1, name: '', type: 'Strategy', level: 0, parent_id: 0 }],
+    };
+    expect(validateGoalTree(tree).errors.some(e => e.code === 'EMPTY_NAME')).toBe(true);
+  });
+
+  it('MAX_LEVEL_EXCEEDED: detects level overflow', () => {
+    const tree = {
+      goal_types: [{ name: 'Strategy', level: 0 }],
+      goals: [{ id: 1, name: 'Too deep', type: 'Strategy', level: 5, parent_id: 0 }],
+    };
+    expect(validateGoalTree(tree).errors.some(e => e.code === 'MAX_LEVEL_EXCEEDED')).toBe(true);
+  });
+
+  it('TYPE_LEVEL_MISMATCH: warns when type level disagrees', () => {
+    const tree = {
+      ...VALID_TREE,
+      goals: [{ id: 1, name: 'Mismatch', type: 'Project', level: 0, parent_id: 0 }],
+    };
+    const r = validateGoalTree(tree);
+    expect(r.warnings.some(w => w.code === 'TYPE_LEVEL_MISMATCH')).toBe(true);
+  });
+
+  it('BROKEN_PARENT_REF: warns on missing parent (renders to backlog)', () => {
+    const tree = {
+      ...VALID_TREE,
+      goals: [
+        { id: 1, name: 'Root', type: 'Strategy', level: 0, parent_id: 0 },
+        { id: 2, name: 'Orphan', type: 'Business Goal', level: 1, parent_id: 99 },
+      ],
+    };
+    const r = validateGoalTree(tree);
+    expect(r.valid).toBe(true);
+    expect(r.warnings.some(w => w.code === 'BROKEN_PARENT_REF')).toBe(true);
+  });
+
+  it('CYCLE_DETECTED: detects direct cycle', () => {
+    const tree = {
+      goal_types: [{ name: 'S', level: 0 }, { name: 'B', level: 1 }],
+      goals: [
+        { id: 1, name: 'A', type: 'S', level: 0, parent_id: 2 },
+        { id: 2, name: 'B', type: 'B', level: 1, parent_id: 1 },
+      ],
+    };
+    expect(validateGoalTree(tree).errors.some(e => e.code === 'CYCLE_DETECTED')).toBe(true);
+  });
+
+  // Pre-release blocker regression tests (orchestrator review 2026-05-21).
+  it('[blocker] tolerates a null element in goals[] without throwing', () => {
+    const tree = { ...VALID_TREE, goals: [null] };
+    const r = validateGoalTree(tree);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+  });
+
+  it('[blocker] tolerates a non-object element in goals[] without throwing', () => {
+    const tree = { ...VALID_TREE, goals: ['x'] };
+    const r = validateGoalTree(tree);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+  });
+
+  it('[blocker] rejects non-numeric level (does not silently slip a string compare)', () => {
+    const tree = {
+      ...VALID_TREE,
+      goals: [{ id: 1, name: 'A', type: 'Strategy', level: '5', parent_id: 0 }],
+    };
+    const r = validateGoalTree(tree);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCHEMA_INVALID' && /level/.test(e.message))).toBe(true);
+  });
+
+  it('[blocker] rejects missing level (does not silently slip undefined > N)', () => {
+    const tree = {
+      ...VALID_TREE,
+      goals: [{ id: 1, name: 'A', type: 'Strategy', parent_id: 0 }],
+    };
+    const r = validateGoalTree(tree);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCHEMA_INVALID' && /level/.test(e.message))).toBe(true);
+  });
+
+  // GOALS-012 / GOALS-013 — N+1 parent/child hierarchy keyed on goal_types[]
+  // (decision in vkgeorgia/strategy#66; spec in transitrix/methodology
+  // notations/04-goals.md §6).
+  it('GOALS-012/013: accepts a contiguous goal_types + N+1 parent/child tree', () => {
+    const r = validateGoalTree(VALID_TREE);
+    expect(r.valid).toBe(true);
+    expect(r.errors.some(e => e.code === 'GOALS-012')).toBe(false);
+    expect(r.errors.some(e => e.code === 'GOALS-013')).toBe(false);
+  });
+
+  it('GOALS-013: rejects a gap in goal_types[].level', () => {
+    const tree = {
+      goal_types: [
+        { name: 'Strategy', level: 0 },
+        { name: 'Strategic Goal', level: 2 },
+        { name: 'Project Goal', level: 4 },
+      ],
+      goals: [
+        { id: 1, name: 'Root', type: 'Strategy', level: 0, parent_id: 0 },
+      ],
+    };
+    const r = validateGoalTree(tree);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'GOALS-013')).toBe(true);
+  });
+
+  it('GOALS-013: rejects goal_types[].level that does not start at 0', () => {
+    const tree = {
+      goal_types: [
+        { name: 'Mid', level: 1 },
+        { name: 'Deep', level: 2 },
+      ],
+      goals: [
+        { id: 1, name: 'A', type: 'Mid', level: 1, parent_id: 0 },
+      ],
+    };
+    const r = validateGoalTree(tree);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'GOALS-013')).toBe(true);
+  });
+
+  it('GOALS-012: rejects a parent–child level gap > 1', () => {
+    const tree = {
+      goal_types: [
+        { name: 'Strategy', level: 0 },
+        { name: 'Business Goal', level: 1 },
+        { name: 'Project', level: 2 },
+      ],
+      goals: [
+        { id: 1, name: 'Root', type: 'Strategy', level: 0, parent_id: 0 },
+        // Skips level 1: a Project (level 2) attached directly to a Strategy
+        // (level 0) violates N+1.
+        { id: 2, name: 'Sub', type: 'Project', level: 2, parent_id: 1 },
+      ],
+    };
+    const r = validateGoalTree(tree);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'GOALS-012')).toBe(true);
+  });
+
+  it('GOALS-012: does not fire when the parent reference is broken (BROKEN_PARENT_REF covers it)', () => {
+    const tree = {
+      ...VALID_TREE,
+      goals: [
+        { id: 1, name: 'Root', type: 'Strategy', level: 0, parent_id: 0 },
+        { id: 2, name: 'Orphan', type: 'Project', level: 2, parent_id: 99 },
+      ],
+    };
+    const r = validateGoalTree(tree);
+    expect(r.errors.some(e => e.code === 'GOALS-012')).toBe(false);
+    expect(r.warnings.some(w => w.code === 'BROKEN_PARENT_REF')).toBe(true);
+  });
+});

package/src/goals/index.ts

@@ -0,0 +1,21 @@
+export type {
+  Goal,
+  GoalType,
+  GoalTree,
+  Factor,
+  ImpactType,
+  ValidationResult,
+  ValidationError,
+  ValidationWarning,
+  MutationResult,
+  LayoutOptions,
+  LaidOutNode,
+  LaidOutEdge,
+  GoalTreeLayout,
+} from './types.js';
+
+export { validateGoalTree } from './validate.js';
+export { parseCanonicalGoals } from './parse-canonical.js';
+export type { CanonicalGoalsResult } from './parse-canonical.js';
+export { layoutGoalTree, selectScopedGoals } from './layout.js';
+export { reparent, addChild, deleteWithDescendants, moveToBacklog, restoreFromBacklog } from './mutations.js';

package/src/goals/layout.ts

@@ -0,0 +1,172 @@
+import type { Goal, GoalTree, LayoutOptions, GoalTreeLayout, LaidOutNode, LaidOutEdge } from './types.js';
+import type { Scope } from '../scope.js';
+
+const DEFAULT_NODE_WIDTH = 250;
+const DEFAULT_NODE_HEIGHT = 80;
+const DEFAULT_RANK_SEP = 80;
+const DEFAULT_NODE_SEP = 40;
+
+/**
+ * Trims a flat goal list to a scope (vkgeorgia/strategy#77).
+ *   - 'level' → goals with `level <= maxLevel`.
+ *   - 'root'  → the root goal (matched by string id) plus all its descendants
+ *               via `parent_id`; an empty list when the root is absent.
+ * Pure and exported so a future access-control layer can reuse it.
+ */
+export function selectScopedGoals(goals: Goal[], scope: Scope): Goal[] {
+  if (scope.mode === 'all') return goals;
+  if (scope.mode === 'level') return goals.filter(g => g.level <= scope.maxLevel);
+
+  // root mode: collect the subtree rooted at rootGoalId (descendants via parent_id).
+  const children = new Map<number, number[]>();
+  for (const g of goals) {
+    if (!children.has(g.parent_id)) children.set(g.parent_id, []);
+    children.get(g.parent_id)!.push(g.id);
+  }
+  const root = goals.find(g => String(g.id) === scope.rootGoalId);
+  if (!root) return [];
+  const keep = new Set<number>();
+  const stack = [root.id];
+  while (stack.length > 0) {
+    const id = stack.pop()!;
+    if (keep.has(id)) continue; // guard against malformed cycles
+    keep.add(id);
+    for (const c of children.get(id) ?? []) stack.push(c);
+  }
+  return goals.filter(g => keep.has(g.id));
+}
+
+export function layoutGoalTree(tree: GoalTree, options: LayoutOptions = {}): GoalTreeLayout {
+  const {
+    nodeWidth = DEFAULT_NODE_WIDTH,
+    nodeHeight = DEFAULT_NODE_HEIGHT,
+    rankSep = DEFAULT_RANK_SEP,
+    nodeSep = DEFAULT_NODE_SEP,
+    hideCollapsed = [],
+    viewDepth = null,
+    scope = { mode: 'all' },
+  } = options;
+
+  const hiddenSet = new Set(hideCollapsed);
+  const goals = selectScopedGoals(tree.goals, scope);
+
+  // Build parent→children map
+  const children = new Map<number, number[]>();
+  const goalById = new Map<number, Goal>();
+  for (const g of goals) {
+    goalById.set(g.id, g);
+    if (!children.has(g.parent_id)) children.set(g.parent_id, []);
+    children.get(g.parent_id)!.push(g.id);
+  }
+
+  // Compress the levels actually used into contiguous column ranks. The
+  // canonical N+1 rule (GOALS-013) keeps `level` contiguous from 0, so for
+  // conforming input this is the identity map. It only rescues legacy /
+  // non-canonical documents whose `goal_types` skip levels (e.g. 0, 2, 4):
+  // without it those gaps open phantom empty columns and double the
+  // horizontal spacing between rendered tiers.
+  const usedLevels = Array.from(new Set(goals.map(g => g.level))).sort((a, b) => a - b);
+  const levelToCol = new Map<number, number>();
+  usedLevels.forEach((lvl, i) => levelToCol.set(lvl, i));
+
+  // Find effective roots: level 0 or parent_id === 0 or broken ref
+  const allIds = new Set(goals.map(g => g.id));
+  const roots = goals.filter(g => g.parent_id === 0 || !allIds.has(g.parent_id));
+
+  // Determine hidden subtrees (collapsed or beyond viewDepth)
+  const hiddenSubtrees = new Set<number>();
+  function markHidden(id: number): void {
+    for (const child of children.get(id) ?? []) {
+      hiddenSubtrees.add(child);
+      markHidden(child);
+    }
+  }
+  for (const id of hiddenSet) markHidden(id);
+  if (viewDepth !== null) {
+    for (const g of goals) {
+      if (g.level > viewDepth) hiddenSubtrees.add(g.id);
+    }
+  }
+
+  const nodes: LaidOutNode[] = [];
+  const edges: LaidOutEdge[] = [];
+
+  // Recursive layout: assign y by counting vertical slots per column
+  const columnNextY = new Map<number, number>();
+
+  function getNextY(col: number): number {
+    return columnNextY.get(col) ?? 0;
+  }
+  function advanceY(col: number, delta: number): void {
+    columnNextY.set(col, (columnNextY.get(col) ?? 0) + delta);
+  }
+
+  const placed = new Set<number>();
+
+  function placeSubtree(id: number): { top: number; bottom: number } {
+    const goal = goalById.get(id);
+    if (!goal || hiddenSubtrees.has(id)) return { top: 0, bottom: 0 };
+    // Guard against cycles (parent-of-itself, mutual parenting). Without
+    // validateGoalTree() upstream, layoutGoalTree must not stack-overflow on
+    // malformed input — drop any subtree we've already placed.
+    if (placed.has(id)) return { top: 0, bottom: 0 };
+    placed.add(id);
+
+    const col = levelToCol.get(goal.level) ?? 0;
+    const childIds = (children.get(id) ?? []).filter(c => !hiddenSubtrees.has(c) && !placed.has(c));
+    const isCollapsedRoot = hiddenSet.has(id) && childIds.length > 0;
+    const hasHiddenChildren = childIds.length < (children.get(id) ?? []).length;
+
+    if (childIds.length === 0) {
+      // Leaf: place at current column Y
+      const y = getNextY(col);
+      advanceY(col, nodeHeight + nodeSep);
+      nodes.push({ id, x: col * (nodeWidth + rankSep), y, width: nodeWidth, height: nodeHeight, data: goal, isCollapsedRoot, hasHiddenChildren });
+      return { top: y, bottom: y + nodeHeight };
+    }
+
+    // Place children first to get their span
+    const spans: Array<{ top: number; bottom: number }> = [];
+    for (const cid of childIds) {
+      spans.push(placeSubtree(cid));
+    }
+
+    const spanTop = Math.min(...spans.map(s => s.top));
+    const spanBottom = Math.max(...spans.map(s => s.bottom));
+    const parentY = spanTop + (spanBottom - spanTop) / 2 - nodeHeight / 2;
+
+    // Make sure parent column is at least this far
+    const curColY = getNextY(col);
+    const finalY = Math.max(parentY, curColY);
+    advanceY(col, finalY - curColY + nodeHeight + nodeSep);
+
+    nodes.push({ id, x: col * (nodeWidth + rankSep), y: finalY, width: nodeWidth, height: nodeHeight, data: goal, isCollapsedRoot, hasHiddenChildren });
+
+    for (const cid of childIds) {
+      edges.push({ source: id, target: cid });
+    }
+
+    return { top: Math.min(finalY, spanTop), bottom: Math.max(finalY + nodeHeight, spanBottom) };
+  }
+
+  for (const root of roots) {
+    if (!hiddenSubtrees.has(root.id) && !placed.has(root.id)) {
+      placeSubtree(root.id);
+      // Add inter-root gap
+      for (const [col, y] of columnNextY) {
+        columnNextY.set(col, y + nodeSep);
+      }
+    }
+  }
+
+  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/goals/mutations.ts

@@ -0,0 +1,123 @@
+import type { GoalTree, Goal, MutationResult, ValidationError } from './types.js';
+import { validateGoalTree } from './validate.js';
+
+function cloneTree(tree: GoalTree): GoalTree {
+  return {
+    goal_types: tree.goal_types.map(gt => ({ ...gt })),
+    goals: tree.goals.map(g => ({ ...g, factors: g.factors ? g.factors.map(f => ({ ...f })) : undefined })),
+  };
+}
+
+function nextId(tree: GoalTree): number {
+  return Math.max(0, ...tree.goals.map(g => g.id)) + 1;
+}
+
+function getLevel(tree: GoalTree, goalId: number): number {
+  const goal = tree.goals.find(g => g.id === goalId);
+  return goal?.level ?? 0;
+}
+
+function getTypeForLevel(tree: GoalTree, level: number): string {
+  const gt = tree.goal_types.find(t => t.level === level);
+  return gt?.name ?? '';
+}
+
+function updateDescendantLevels(goals: Goal[], id: number, levelDelta: number): void {
+  for (const g of goals) {
+    if (g.parent_id === id) {
+      g.level += levelDelta;
+      g.type = '';
+      updateDescendantLevels(goals, g.id, levelDelta);
+    }
+  }
+}
+
+function hasPathTo(goals: Goal[], fromId: number, targetId: number): boolean {
+  const visited = new Set<number>();
+  const stack = [fromId];
+  while (stack.length > 0) {
+    const cur = stack.pop()!;
+    if (cur === targetId) return true;
+    if (visited.has(cur)) continue;
+    visited.add(cur);
+    for (const g of goals) {
+      if (g.parent_id === cur) stack.push(g.id);
+    }
+  }
+  return false;
+}
+
+function refusalError(message: string): MutationResult<GoalTree> {
+  const err: ValidationError = { code: 'MUTATION_REFUSED', message };
+  return { ok: false, error: err };
+}
+
+export function reparent(tree: GoalTree, sourceId: number, targetId: number): MutationResult<GoalTree> {
+  const clone = cloneTree(tree);
+  const source = clone.goals.find(g => g.id === sourceId);
+  const target = clone.goals.find(g => g.id === targetId);
+
+  if (!source) return refusalError(`Goal ${sourceId} not found`);
+  if (!target) return refusalError(`Target goal ${targetId} not found`);
+  if (sourceId === targetId) return refusalError('Cannot reparent to self');
+  if (hasPathTo(clone.goals, sourceId, targetId)) return refusalError('Cannot reparent: would create cycle');
+
+  const maxLevel = Math.max(...clone.goal_types.map(gt => gt.level), 0);
+  const newLevel = target.level + 1;
+  if (newLevel > maxLevel) return refusalError(`Reparent would exceed max level ${maxLevel}`);
+
+  const levelDelta = newLevel - source.level;
+  source.parent_id = targetId;
+  source.level = newLevel;
+  source.type = getTypeForLevel(clone, newLevel);
+  if (levelDelta !== 0) updateDescendantLevels(clone.goals, sourceId, levelDelta);
+
+  const v = validateGoalTree(clone);
+  if (!v.valid) return refusalError(v.errors[0]?.message ?? 'Validation failed after reparent');
+  return { ok: true, result: clone };
+}
+
+export function addChild(tree: GoalTree, parentId: number, newGoal: Omit<Goal, 'id'>): MutationResult<GoalTree> {
+  const clone = cloneTree(tree);
+  const parent = parentId === 0 ? null : clone.goals.find(g => g.id === parentId);
+
+  if (parentId !== 0 && !parent) return refusalError(`Parent goal ${parentId} not found`);
+
+  const maxLevel = Math.max(...clone.goal_types.map(gt => gt.level), 0);
+  const expectedLevel = parent ? parent.level + 1 : 0;
+  if (expectedLevel > maxLevel) return refusalError(`New child would exceed max level ${maxLevel}`);
+
+  const id = nextId(clone);
+  clone.goals.push({ ...newGoal, id, parent_id: parentId, level: expectedLevel, type: getTypeForLevel(clone, expectedLevel) || newGoal.type });
+
+  return { ok: true, result: clone };
+}
+
+export function deleteWithDescendants(tree: GoalTree, id: number): MutationResult<GoalTree> {
+  const clone = cloneTree(tree);
+  if (!clone.goals.find(g => g.id === id)) return refusalError(`Goal ${id} not found`);
+
+  const toDelete = new Set<number>();
+  const stack = [id];
+  while (stack.length > 0) {
+    const cur = stack.pop()!;
+    toDelete.add(cur);
+    for (const g of clone.goals) {
+      if (g.parent_id === cur) stack.push(g.id);
+    }
+  }
+  clone.goals = clone.goals.filter(g => !toDelete.has(g.id));
+  return { ok: true, result: clone };
+}
+
+export function moveToBacklog(tree: GoalTree, id: number): MutationResult<GoalTree> {
+  const clone = cloneTree(tree);
+  const goal = clone.goals.find(g => g.id === id);
+  if (!goal) return refusalError(`Goal ${id} not found`);
+  goal.parent_id = 0;
+  return { ok: true, result: clone };
+}
+
+export function restoreFromBacklog(tree: GoalTree, id: number, newParentId: number): MutationResult<GoalTree> {
+  return reparent(tree, id, newParentId);
+}