@transitrix/diagrams 1.4.0 → 1.6.0

package/src/capability-map/__tests__/CapabilityMapView.test.tsx

@@ -0,0 +1,232 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import React from 'react';
+import { render, screen, cleanup, waitFor } from '@testing-library/react';
+import { CapabilityMapView, computeDragOutcome } from '../CapabilityMapView.js';
+import type { CapabilityMap } from '../dsm-schema.js';
+import type { CapabilityMapChange } from '../CapabilityMapView.js';
+
+// See goals/__tests__/GoalTreeView.test.tsx for why these three shims are
+// needed — reactflow keeps a node `visibility: hidden` (and inert to
+// drag/measurement logic) until ResizeObserver reports its size, and reads
+// the computed transform back out via DOMMatrixReadOnly; jsdom has neither.
+class MockResizeObserver {
+  #callback: ResizeObserverCallback;
+  constructor(callback: ResizeObserverCallback) {
+    this.#callback = callback;
+  }
+  observe(target: Element) {
+    queueMicrotask(() => {
+      this.#callback([{ target, contentRect: target.getBoundingClientRect() } as ResizeObserverEntry], this as unknown as ResizeObserver);
+    });
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+class MockDOMMatrixReadOnly {
+  m41 = 0;
+  m42 = 0;
+  constructor(transform?: string) {
+    if (!transform || transform === 'none') return;
+    const t = /translate\((-?[\d.]+)px,\s*(-?[\d.]+)px\)/.exec(transform);
+    if (t) {
+      this.m41 = Number(t[1]);
+      this.m42 = Number(t[2]);
+    }
+  }
+}
+
+function makeMap(): CapabilityMap {
+  return {
+    organisation: 'Acme Corp',
+    set_id: 'v1.0',
+    capabilities: [
+      { id: 1, name: 'Customer Acquisition', address: '1.0.0', maturity: [{ date: '2026-04-01', level: 3 }] },
+      { id: 2, name: 'Lead Qualification', address: '1.1.0' },
+      { id: 3, name: 'Inbound Lead Scoring', address: '1.1.1' },
+    ],
+  };
+}
+
+beforeEach(() => {
+  (global as unknown as { ResizeObserver: unknown }).ResizeObserver = MockResizeObserver;
+  (window as unknown as { DOMMatrixReadOnly: unknown }).DOMMatrixReadOnly = MockDOMMatrixReadOnly;
+  vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(function (this: Element) {
+    const isNode = this.classList?.contains('react-flow__node');
+    const width = isNode ? 250 : 1000;
+    const height = isNode ? 64 : 800;
+    return { width, height, top: 0, left: 0, right: width, bottom: height, x: 0, y: 0, toJSON() { return this; } } as DOMRect;
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('CapabilityMapView', () => {
+  it('renders the virtual root and every on-diagram capability', async () => {
+    render(<CapabilityMapView map={makeMap()} />);
+    await waitFor(() => {
+      expect(screen.getByText('Acme Corp')).toBeTruthy();
+      expect(screen.getByText('Customer Acquisition')).toBeTruthy();
+      expect(screen.getByText('Lead Qualification')).toBeTruthy();
+      expect(screen.getByText('Inbound Lead Scoring')).toBeTruthy();
+    });
+  });
+
+  it('renders a maturity dot only for capabilities with a maturity snapshot', async () => {
+    render(<CapabilityMapView map={makeMap()} />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    expect(screen.getByLabelText('Maturity 3')).toBeTruthy();
+    expect(screen.queryByLabelText(/Maturity/, { selector: '[aria-label="Maturity undefined"]' })).toBeNull();
+  });
+
+  it('shows backlog capabilities in the sidebar, not on canvas', async () => {
+    const map: CapabilityMap = {
+      organisation: 'Acme Corp',
+      set_id: 'v1.0',
+      capabilities: [
+        { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+        { id: 2, name: 'Parked idea', address: '0.0.0', backlog: true },
+      ],
+    };
+    render(<CapabilityMapView map={map} showBacklog />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    expect(screen.getByText('Backlog')).toBeTruthy();
+    expect(screen.getByText('Parked idea')).toBeTruthy();
+  });
+
+  it('does not render add/delete affordances when readOnly', async () => {
+    render(<CapabilityMapView map={makeMap()} readOnly />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    expect(screen.queryByLabelText('Add child capability')).toBeNull();
+    expect(screen.queryByLabelText('Delete capability')).toBeNull();
+  });
+
+  it('fires onChange with kind "addChild" when the add-child button is clicked', async () => {
+    const onChange = vi.fn<(e: CapabilityMapChange) => void>();
+    render(<CapabilityMapView map={makeMap()} onChange={onChange} />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    const rootCard = document.querySelector('.react-flow__node[data-id="1"]')!;
+    rootCard.querySelector<HTMLElement>('[aria-label="Add child capability"]')!
+      .dispatchEvent(new MouseEvent('click', { bubbles: true }));
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    const event = onChange.mock.calls[0][0];
+    expect(event.kind).toBe('addChild');
+    if (event.kind === 'addChild') {
+      expect(event.newCap.address).toBe('1.2.0');
+    }
+  });
+
+  it('fires onChange with kind "delete" when the delete button is clicked', async () => {
+    const onChange = vi.fn<(e: CapabilityMapChange) => void>();
+    render(<CapabilityMapView map={makeMap()} onChange={onChange} />);
+    await waitFor(() => expect(screen.getByText('Inbound Lead Scoring')).toBeTruthy());
+    const leafCard = document.querySelector('.react-flow__node[data-id="3"]')!;
+    leafCard.querySelector<HTMLElement>('[aria-label="Delete capability"]')!
+      .dispatchEvent(new MouseEvent('click', { bubbles: true }));
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    expect(onChange.mock.calls[0][0].kind).toBe('delete');
+  });
+
+  it('fires onEditRequest on double-click', async () => {
+    const onEditRequest = vi.fn();
+    render(<CapabilityMapView map={makeMap()} onEditRequest={onEditRequest} />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    document.querySelector('.react-flow__node[data-id="1"]')!
+      .dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+
+    await waitFor(() => expect(onEditRequest).toHaveBeenCalledTimes(1));
+    expect(onEditRequest.mock.calls[0][0]).toMatchObject({ id: 1, name: 'Customer Acquisition' });
+  });
+
+  it('fires onChange with kind "normaliseAddresses" from the toolbar button', async () => {
+    const onChange = vi.fn<(e: CapabilityMapChange) => void>();
+    render(<CapabilityMapView map={makeMap()} onChange={onChange} />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    screen.getByText('Normalise addresses').dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    expect(onChange.mock.calls[0][0].kind).toBe('normaliseAddresses');
+  });
+
+  it('fires onChange with kind "restoreFromBacklog" when a backlog card is dropped onto a canvas card', async () => {
+    const map: CapabilityMap = {
+      organisation: 'Acme Corp',
+      set_id: 'v1.0',
+      capabilities: [
+        { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+        { id: 2, name: 'Parked idea', address: '0.0.0', backlog: true },
+      ],
+    };
+    const onChange = vi.fn<(e: CapabilityMapChange) => void>();
+    render(<CapabilityMapView map={map} onChange={onChange} showBacklog />);
+    await waitFor(() => expect(screen.getByText('Parked idea')).toBeTruthy());
+
+    const store = new Map<string, string>();
+    const dataTransfer = { setData: (k: string, v: string) => store.set(k, v), getData: (k: string) => store.get(k) ?? '', effectAllowed: 'move' };
+    function fireDnd(el: Element, type: string, coords: { clientX: number; clientY: number }) {
+      const event = new Event(type, { bubbles: true, cancelable: true });
+      Object.defineProperty(event, 'dataTransfer', { value: dataTransfer });
+      Object.assign(event, coords);
+      el.dispatchEvent(event);
+    }
+
+    const backlogItem = screen.getByText('Parked idea').closest('div[draggable]')!;
+    const rootCard = document.querySelector('.react-flow__node[data-id="1"]')!;
+    document.elementFromPoint = vi.fn().mockReturnValue(rootCard);
+
+    fireDnd(backlogItem, 'dragstart', { clientX: 0, clientY: 0 });
+    fireDnd(rootCard, 'drop', { clientX: 10, clientY: 10 });
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    const event = onChange.mock.calls[0][0];
+    expect(event.kind).toBe('restoreFromBacklog');
+    if (event.kind === 'restoreFromBacklog') {
+      expect(event.id).toBe(2);
+      expect(event.parentId).toBe(1);
+    }
+  });
+});
+
+// Dragging a card is choreographed by reactflow's own pointer/DOM-measurement
+// machinery — see the equivalent note in goals/__tests__/GoalTreeView.test.tsx.
+// computeDragOutcome() is the pure decision this component's onNodeDragStop
+// calls once reactflow reports a drag, tested directly here.
+describe('computeDragOutcome (reparent / moveBranchToBacklog decision logic)', () => {
+  const map = makeMap();
+
+  it('fires a "reparent" change when dropped onto another card', () => {
+    const change = computeDragOutcome(map, 3, { kind: 'node', id: 1 });
+    expect(change?.kind).toBe('reparent');
+    if (change?.kind === 'reparent') {
+      expect(change.sourceId).toBe(3);
+      expect(change.targetId).toBe(1);
+    }
+  });
+
+  it('fires a "reparent" change (promotion to L1) when dropped on the root', () => {
+    const change = computeDragOutcome(map, 2, { kind: 'root' });
+    expect(change?.kind).toBe('reparent');
+    if (change?.kind === 'reparent') {
+      expect(change.targetId).toBe(0);
+      expect(change.result.capabilities.find((c) => c.id === 2)?.address).toBe('2.0.0');
+    }
+  });
+
+  it('fires a "moveBranchToBacklog" change when dropped on the backlog zone', () => {
+    const change = computeDragOutcome(map, 2, { kind: 'backlog' });
+    expect(change?.kind).toBe('moveBranchToBacklog');
+  });
+
+  it('is a no-op when dropped nowhere in particular', () => {
+    expect(computeDragOutcome(map, 2, null)).toBeNull();
+  });
+
+  it('is a no-op when dropped on itself', () => {
+    expect(computeDragOutcome(map, 2, { kind: 'node', id: 2 })).toBeNull();
+  });
+});

package/src/capability-map/__tests__/address.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { parseAddress, formatAddress, getLevel, getParentAddress, getFirstFreeAddress, isAddressTaken } from '../address.js';
+import type { Capability } from '../dsm-schema.js';
+
+function cap(id: number, address: string, backlog = false): Capability {
+  return { id, name: `Cap ${id}`, address, backlog };
+}
+
+describe('parseAddress / formatAddress', () => {
+  it('round-trips X.Y.Z', () => {
+    for (const addr of ['1.0.0', '1.2.0', '1.2.3', '0.0.0', '42.7.19']) {
+      expect(formatAddress(parseAddress(addr))).toBe(addr);
+    }
+  });
+
+  it('throws on malformed input', () => {
+    expect(() => parseAddress('1.2')).toThrow();
+    expect(() => parseAddress('1.2.3.4')).toThrow();
+    expect(() => parseAddress('a.b.c')).toThrow();
+  });
+});
+
+describe('getLevel', () => {
+  it('classifies each address shape', () => {
+    expect(getLevel('1.0.0')).toBe(1);
+    expect(getLevel('1.2.0')).toBe(2);
+    expect(getLevel('1.2.3')).toBe(3);
+    expect(getLevel('0.0.0')).toBe('backlog');
+  });
+});
+
+describe('getParentAddress', () => {
+  it('walks up one level at a time', () => {
+    expect(getParentAddress('1.2.3')).toBe('1.2.0');
+    expect(getParentAddress('1.2.0')).toBe('1.0.0');
+    expect(getParentAddress('1.0.0')).toBeNull();
+  });
+});
+
+describe('getFirstFreeAddress / isAddressTaken', () => {
+  it('finds the first unused L2 slot under an L1 parent', () => {
+    const caps = [cap(1, '1.0.0'), cap(2, '1.1.0'), cap(3, '1.2.0')];
+    expect(getFirstFreeAddress('1.0.0', caps)).toBe('1.3.0');
+  });
+
+  it('finds the first unused L3 slot under an L2 parent', () => {
+    const caps = [cap(1, '1.0.0'), cap(2, '1.1.0'), cap(3, '1.1.1')];
+    expect(getFirstFreeAddress('1.1.0', caps)).toBe('1.1.2');
+  });
+
+  it('ignores backlog entries when checking occupancy', () => {
+    const caps = [cap(1, '1.0.0'), cap(2, '0.0.0', true)];
+    expect(isAddressTaken('1.1.0', caps)).toBe(false);
+  });
+
+  it('rejects an L3 address as a parent', () => {
+    expect(() => getFirstFreeAddress('1.1.1', [])).toThrow();
+  });
+});

package/src/capability-map/__tests__/dsm-layout.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { layoutCapabilityMap } from '../dsm-layout.js';
+import type { CapabilityMap } from '../dsm-schema.js';
+
+function map(): CapabilityMap {
+  return {
+    organisation: 'Acme Corp',
+    set_id: 'v1.0',
+    capabilities: [
+      { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+      { id: 2, name: 'Lead Qualification', address: '1.1.0' },
+      { id: 3, name: 'Inbound Lead Scoring', address: '1.1.1' },
+      { id: 4, name: 'Order Management', address: '2.0.0' },
+      { id: 5, name: 'Parked idea', address: '0.0.0', backlog: true },
+    ],
+  };
+}
+
+describe('layoutCapabilityMap', () => {
+  it('lays out a virtual root plus every on-diagram capability, one column per level', () => {
+    const layout = layoutCapabilityMap(map());
+    expect(layout.rootNode.data).toBeNull();
+    expect(layout.nodes).toHaveLength(4); // backlog entry excluded
+    const byId = new Map(layout.nodes.map((n) => [n.id, n]));
+    expect(byId.get(1)!.x).toBe(byId.get(4)!.x); // both L1s share a column
+    expect(byId.get(2)!.x).toBeGreaterThan(byId.get(1)!.x); // L2 one column further right
+    expect(byId.get(3)!.x).toBeGreaterThan(byId.get(2)!.x); // L3 further still
+    expect(byId.get(1)!.x).toBeGreaterThan(layout.rootNode.x); // root sits left of the L1s
+  });
+
+  it('connects the root to every L1 and each parent to its children', () => {
+    const layout = layoutCapabilityMap(map());
+    const edgeSet = new Set(layout.edges.map((e) => `${e.source}->${e.target}`));
+    expect(edgeSet.has('root->1')).toBe(true);
+    expect(edgeSet.has('root->4')).toBe(true);
+    expect(edgeSet.has('1->2')).toBe(true);
+    expect(edgeSet.has('2->3')).toBe(true);
+  });
+
+  it('marks a node as having hidden children when its subtree is collapsed', () => {
+    const layout = layoutCapabilityMap(map(), { hideCollapsed: [2] });
+    const cap2 = layout.nodes.find((n) => n.id === 2)!;
+    expect(cap2.hasHiddenChildren).toBe(true);
+    expect(layout.nodes.some((n) => n.id === 3)).toBe(false); // hidden subtree omitted
+  });
+
+  it('returns just the root when there are no on-diagram capabilities', () => {
+    const layout = layoutCapabilityMap({ organisation: 'Empty Co', set_id: 'v1', capabilities: [] });
+    expect(layout.nodes).toHaveLength(0);
+    expect(layout.rootNode.data).toBeNull();
+  });
+});

package/src/capability-map/__tests__/dsm-mutations.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from 'vitest';
+import { reparent, addChild, deleteWithDescendants, moveBranchToBacklog, restoreFromBacklog, normaliseAddresses } from '../dsm-mutations.js';
+import type { CapabilityMap } from '../dsm-schema.js';
+
+function baseMap(): CapabilityMap {
+  return {
+    organisation: 'Acme Corp',
+    set_id: 'v1.0',
+    capabilities: [
+      { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+      { id: 2, name: 'Lead Qualification', address: '1.1.0' },
+      { id: 3, name: 'Inbound Lead Scoring', address: '1.1.1' },
+      { id: 4, name: 'Order Management', address: '2.0.0' },
+    ],
+  };
+}
+
+describe('reparent', () => {
+  it('moves an L3 under a different L2 (no cascade)', () => {
+    const map = baseMap();
+    const r = reparent(map, 3, 4); // Inbound Lead Scoring (L3) -> Order Management (L1)... newLevel would be 2
+    expect(r.ok).toBe(true);
+    const moved = r.result!.capabilities.find((c) => c.id === 3)!;
+    expect(moved.address).toBe('2.1.0'); // now an L2 under capability 4
+  });
+
+  it('promotes an L2 to L1 and cascades its L3 children to L2 (spec §9)', () => {
+    const map = baseMap();
+    const r = reparent(map, 2, 0); // Lead Qualification (L2, id 2) -> virtual root
+    expect(r.ok).toBe(true);
+    const promoted = r.result!.capabilities.find((c) => c.id === 2)!;
+    const child = r.result!.capabilities.find((c) => c.id === 3)!;
+    expect(promoted.address).toBe('3.0.0'); // first free L1 slot (1 and 2 taken)
+    expect(child.address).toBe('3.1.0'); // cascaded from L3 to L2 under the new L1
+  });
+
+  it('refuses a demotion that would push a grandchild past L3', () => {
+    const map = baseMap();
+    // Capability 1 (L1) has descendant 2 (L2) and 3 (L3, a grandchild).
+    // Demoting 1 under 4 (making 1 an L2) would need 3 to become L4.
+    const r = reparent(map, 1, 4);
+    expect(r.ok).toBe(false);
+  });
+
+  it('refuses reparenting onto its own descendant (cycle)', () => {
+    const map = baseMap();
+    const r = reparent(map, 2, 3); // Lead Qualification onto its own child
+    expect(r.ok).toBe(false);
+  });
+
+  it('refuses reparenting onto itself', () => {
+    const map = baseMap();
+    expect(reparent(map, 1, 1).ok).toBe(false);
+  });
+
+  it('leaves the original map untouched', () => {
+    const map = baseMap();
+    reparent(map, 3, 4);
+    expect(map.capabilities.find((c) => c.id === 3)!.address).toBe('1.1.1');
+  });
+});
+
+describe('addChild', () => {
+  it('assigns the first free address under the parent', () => {
+    const map = baseMap();
+    const r = addChild(map, 1, { name: 'New L2' });
+    expect(r.ok).toBe(true);
+    const added = r.result!.capabilities.find((c) => c.name === 'New L2')!;
+    expect(added.address).toBe('1.2.0');
+    expect(added.backlog).toBe(false);
+  });
+
+  it('assigns a new L1 address when parentId is 0 (root)', () => {
+    const map = baseMap();
+    const r = addChild(map, 0, { name: 'New L1' });
+    expect(r.ok).toBe(true);
+    expect(r.result!.capabilities.find((c) => c.name === 'New L1')!.address).toBe('3.0.0');
+  });
+
+  it('refuses adding a child under an L3 (would exceed max depth)', () => {
+    const map = baseMap();
+    const r = addChild(map, 3, { name: 'Too deep' });
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe('deleteWithDescendants', () => {
+  it('removes the capability and every descendant', () => {
+    const map = baseMap();
+    const r = deleteWithDescendants(map, 2); // Lead Qualification + its L3 child
+    expect(r.ok).toBe(true);
+    const ids = r.result!.capabilities.map((c) => c.id);
+    expect(ids).not.toContain(2);
+    expect(ids).not.toContain(3);
+    expect(ids).toContain(1);
+    expect(ids).toContain(4);
+  });
+});
+
+describe('moveBranchToBacklog / restoreFromBacklog', () => {
+  it('moves a branch to the backlog and back', () => {
+    const map = baseMap();
+    const toBacklog = moveBranchToBacklog(map, 2);
+    expect(toBacklog.ok).toBe(true);
+    const backlogged = toBacklog.result!.capabilities.filter((c) => c.id === 2 || c.id === 3);
+    expect(backlogged.every((c) => c.backlog && c.address === '0.0.0')).toBe(true);
+
+    const restored = restoreFromBacklog(toBacklog.result!, 2, 4);
+    expect(restored.ok).toBe(true);
+    const cap2 = restored.result!.capabilities.find((c) => c.id === 2)!;
+    expect(cap2.backlog).toBe(false);
+    expect(cap2.address).toBe('2.1.0');
+    // Restoring the parent doesn't automatically restore its backlogged
+    // children — matches deleteWithDescendants/addChild's scope (this
+    // mutation acts on the single named id only).
+    expect(restored.result!.capabilities.find((c) => c.id === 3)!.backlog).toBe(true);
+  });
+});
+
+describe('normaliseAddresses', () => {
+  it('moves a capability with an unresolvable parent address to the backlog', () => {
+    const map: CapabilityMap = {
+      organisation: 'Acme Corp',
+      set_id: 'v1.0',
+      capabilities: [
+        { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+        { id: 2, name: 'Dangling L2', address: '9.1.0' }, // no capability at 9.0.0
+      ],
+    };
+    const result = normaliseAddresses(map);
+    const dangling = result.capabilities.find((c) => c.id === 2)!;
+    expect(dangling.backlog).toBe(true);
+    expect(dangling.address).toBe('0.0.0');
+  });
+
+  it('leaves a well-formed hierarchy unchanged', () => {
+    const map = baseMap();
+    const result = normaliseAddresses(map);
+    expect(result.capabilities).toEqual(map.capabilities);
+  });
+});

package/src/capability-map/__tests__/dsm-validate.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { validateCapabilityMapData } from '../dsm-validate.js';
+import type { CapabilityMap } from '../dsm-schema.js';
+
+function validMap(): CapabilityMap {
+  return {
+    organisation: 'Acme Corp',
+    set_id: 'v1.0',
+    capabilities: [
+      { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+      { id: 2, name: 'Lead Qualification', address: '1.1.0' },
+      { id: 3, name: 'Inbound Lead Scoring', address: '1.1.1' },
+    ],
+  };
+}
+
+describe('validateCapabilityMapData', () => {
+  it('accepts a well-formed map', () => {
+    expect(validateCapabilityMapData(validMap()).valid).toBe(true);
+  });
+
+  it('flags a duplicate id', () => {
+    const map = validMap();
+    map.capabilities[1].id = 1;
+    const result = validateCapabilityMapData(map);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.code === 'DUPLICATE_ID')).toBe(true);
+  });
+
+  it('flags a malformed address', () => {
+    const map = validMap();
+    map.capabilities[0].address = 'not-an-address';
+    const result = validateCapabilityMapData(map);
+    expect(result.errors.some((e) => e.code === 'INVALID_ADDRESS_FORMAT')).toBe(true);
+  });
+
+  it('flags a too-deep address as MAX_DEPTH_EXCEEDED, not INVALID_ADDRESS_FORMAT', () => {
+    const map = validMap();
+    map.capabilities[0].address = '1.2.3.4';
+    const result = validateCapabilityMapData(map);
+    expect(result.errors.some((e) => e.code === 'MAX_DEPTH_EXCEEDED')).toBe(true);
+    expect(result.errors.some((e) => e.code === 'INVALID_ADDRESS_FORMAT')).toBe(false);
+  });
+
+  it('flags a duplicate on-diagram address', () => {
+    const map = validMap();
+    map.capabilities[1].address = '1.0.0';
+    const result = validateCapabilityMapData(map);
+    expect(result.errors.some((e) => e.code === 'DUPLICATE_ADDRESS')).toBe(true);
+  });
+
+  it('warns on a missing parent by address', () => {
+    const map = validMap();
+    map.capabilities[1].address = '9.1.0'; // no capability at 9.0.0
+    const result = validateCapabilityMapData(map);
+    expect(result.warnings.some((w) => w.code === 'MISSING_PARENT_BY_ADDRESS')).toBe(true);
+  });
+
+  it('does not flag a backlog entry\'s address as a duplicate or requiring a parent', () => {
+    const map = validMap();
+    map.capabilities.push({ id: 4, name: 'Parked idea', address: '0.0.0', backlog: true });
+    const result = validateCapabilityMapData(map);
+    expect(result.valid).toBe(true);
+  });
+});

package/src/capability-map/address.ts

@@ -0,0 +1,48 @@
+import type { Capability } from './dsm-schema.js';
+
+/** 'X.Y.Z' -> [X, Y, Z]. Throws on malformed input — callers on untrusted
+ *  data should validate with validateCapabilityMapData first. */
+export function parseAddress(address: string): [number, number, number] {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(address.trim());
+  if (!m) throw new Error(`parseAddress: expected 'X.Y.Z', got "${address}"`);
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+export function formatAddress(triple: [number, number, number]): string {
+  return triple.join('.');
+}
+
+/** X.0.0 -> L1, X.Y.0 -> L2, X.Y.Z -> L3, 0.0.0 -> backlog. */
+export function getLevel(address: string): 1 | 2 | 3 | 'backlog' {
+  const [x, y, z] = parseAddress(address);
+  if (x === 0) return 'backlog';
+  if (y === 0) return 1;
+  if (z === 0) return 2;
+  return 3;
+}
+
+/** '1.2.3' -> '1.2.0'; '1.2.0' -> '1.0.0'; '1.0.0' -> null (L1 has no parent). */
+export function getParentAddress(address: string): string | null {
+  const [x, y, z] = parseAddress(address);
+  if (z !== 0) return formatAddress([x, y, 0]);
+  if (y !== 0) return formatAddress([x, 0, 0]);
+  return null;
+}
+
+/** First address under `parent` (an L1 or L2 address) not already taken. */
+export function getFirstFreeAddress(parent: string, capabilities: Capability[]): string {
+  const [x, y] = parseAddress(parent);
+  const level = getLevel(parent);
+  if (level !== 1 && level !== 2) {
+    throw new Error(`getFirstFreeAddress: parent must be an L1 or L2 address, got "${parent}" (${level})`);
+  }
+  for (let n = 1; n < 1000; n++) {
+    const candidate = level === 1 ? formatAddress([x, n, 0]) : formatAddress([x, y, n]);
+    if (!isAddressTaken(candidate, capabilities)) return candidate;
+  }
+  throw new Error(`getFirstFreeAddress: no free address under "${parent}" (searched 1..999)`);
+}
+
+export function isAddressTaken(address: string, capabilities: Capability[]): boolean {
+  return capabilities.some((c) => !c.backlog && c.address === address);
+}