@transitrix/diagrams 1.0.0

package/src/blocks/layout.ts

@@ -0,0 +1,186 @@
+import type {
+  Block,
+  BlocksFile,
+  BlocksLayout,
+  BlocksLayoutOptions,
+  LaidOutBlock,
+} from './types.js';
+
+const DEFAULTS: Required<BlocksLayoutOptions> = {
+  leafWidth: 160,
+  leafHeight: 60,
+  padding: 12,
+  headerHeight: 28,
+  childGap: 12,
+  topLevelGap: 24,
+};
+
+interface MeasuredBlock {
+  width: number;
+  height: number;
+  cols: number;
+  rows: number;
+  colWidths: number[];
+  rowHeights: number[];
+  children: MeasuredBlock[];
+}
+
+function resolveOptions(options: BlocksLayoutOptions | undefined): Required<BlocksLayoutOptions> {
+  return { ...DEFAULTS, ...(options ?? {}) };
+}
+
+function measure(b: Block, opts: Required<BlocksLayoutOptions>): MeasuredBlock {
+  const children = Array.isArray(b.children) ? b.children : [];
+  if (children.length === 0) {
+    return {
+      width: opts.leafWidth,
+      height: opts.leafHeight,
+      cols: 0,
+      rows: 0,
+      colWidths: [],
+      rowHeights: [],
+      children: [],
+    };
+  }
+
+  const measuredChildren = children.map((c) => measure(c, opts));
+  const N = measuredChildren.length;
+
+  // Square-ish grid: cols = ceil(sqrt(N)), rows = ceil(N/cols).
+  // Variable column widths and row heights so heterogeneous children pack
+  // without forcing every cell to the largest size.
+  const cols = Math.max(1, Math.ceil(Math.sqrt(N)));
+  const rows = Math.ceil(N / cols);
+
+  const colWidths = new Array<number>(cols).fill(0);
+  const rowHeights = new Array<number>(rows).fill(0);
+
+  for (let i = 0; i < N; i++) {
+    const r = Math.floor(i / cols);
+    const c = i % cols;
+    const m = measuredChildren[i];
+    if (m.width > colWidths[c]) colWidths[c] = m.width;
+    if (m.height > rowHeights[r]) rowHeights[r] = m.height;
+  }
+
+  const contentWidth =
+    colWidths.reduce((s, w) => s + w, 0) + (cols - 1) * opts.childGap;
+  const contentHeight =
+    rowHeights.reduce((s, h) => s + h, 0) + (rows - 1) * opts.childGap;
+
+  // Outer block: padding on all four sides, plus a header strip on top that
+  // carries the block's name. Header height is not part of the children grid.
+  return {
+    width: contentWidth + 2 * opts.padding,
+    height: contentHeight + 2 * opts.padding + opts.headerHeight,
+    cols,
+    rows,
+    colWidths,
+    rowHeights,
+    children: measuredChildren,
+  };
+}
+
+function position(
+  b: Block,
+  m: MeasuredBlock,
+  x: number,
+  y: number,
+  depth: number,
+  opts: Required<BlocksLayoutOptions>,
+): LaidOutBlock {
+  const node: LaidOutBlock = {
+    id: b.id,
+    name: b.name,
+    description: b.description,
+    depth,
+    x,
+    y,
+    width: m.width,
+    height: m.height,
+    headerHeight: opts.headerHeight,
+    children: [],
+  };
+
+  const children = Array.isArray(b.children) ? b.children : [];
+  if (children.length === 0) return node;
+
+  const innerX0 = x + opts.padding;
+  const innerY0 = y + opts.headerHeight + opts.padding;
+
+  let yCursor = innerY0;
+  for (let r = 0; r < m.rows; r++) {
+    let xCursor = innerX0;
+    for (let c = 0; c < m.cols; c++) {
+      const i = r * m.cols + c;
+      if (i >= children.length) break;
+      // Centre each child within its grid cell so heterogeneous sizes look
+      // balanced (smaller blocks float in the middle of their cell rather
+      // than left-aligning, which looks ragged when the cell is larger than
+      // the child).
+      const cellW = m.colWidths[c];
+      const cellH = m.rowHeights[r];
+      const childM = m.children[i];
+      const cx = xCursor + (cellW - childM.width) / 2;
+      const cy = yCursor + (cellH - childM.height) / 2;
+      node.children.push(position(children[i], childM, cx, cy, depth + 1, opts));
+      xCursor += cellW + opts.childGap;
+    }
+    yCursor += m.rowHeights[r] + opts.childGap;
+  }
+
+  return node;
+}
+
+function maxDepthOf(node: LaidOutBlock): number {
+  let m = node.depth;
+  for (const c of node.children) {
+    const d = maxDepthOf(c);
+    if (d > m) m = d;
+  }
+  return m;
+}
+
+export function layoutNestedBlocks(
+  file: BlocksFile,
+  options?: BlocksLayoutOptions,
+): BlocksLayout {
+  const opts = resolveOptions(options);
+
+  const nb = file?.nested_blocks;
+  const tops = Array.isArray(nb?.blocks) ? nb.blocks : [];
+
+  // Top-level blocks stack vertically. They share a single x = 0 column;
+  // their widths can differ. Total bounds = max child width, sum of heights
+  // plus inter-block gaps.
+  const measuredTops = tops.map((b) => measure(b, opts));
+
+  let cursorY = 0;
+  let maxWidth = 0;
+  let maxDepth = 0;
+  const blocks: LaidOutBlock[] = [];
+  for (let i = 0; i < tops.length; i++) {
+    const m = measuredTops[i];
+    const laid = position(tops[i], m, 0, cursorY, 1, opts);
+    blocks.push(laid);
+    const d = maxDepthOf(laid);
+    if (d > maxDepth) maxDepth = d;
+    if (m.width > maxWidth) maxWidth = m.width;
+    cursorY += m.height + (i < tops.length - 1 ? opts.topLevelGap : 0);
+  }
+
+  return {
+    bounds: { x: 0, y: 0, width: maxWidth, height: cursorY },
+    blocks,
+    maxDepth,
+  };
+}
+
+/** Iterate every laid-out block (including nested children) in pre-order. */
+export function* iterateBlocks(layout: BlocksLayout): Iterable<LaidOutBlock> {
+  function* walk(b: LaidOutBlock): Iterable<LaidOutBlock> {
+    yield b;
+    for (const c of b.children) yield* walk(c);
+  }
+  for (const b of layout.blocks) yield* walk(b);
+}

package/src/blocks/types.ts

@@ -0,0 +1,62 @@
+export interface Block {
+  id: string;
+  name: string;
+  description?: string;
+  children?: Block[];
+}
+
+export interface NestedBlocksHeader {
+  id: string;
+  name: string;
+  description?: string;
+  version?: string;
+  date?: string;
+  author?: string;
+  blocks: Block[];
+}
+
+export interface BlocksFile {
+  notation: string;
+  spec_version?: string;
+  nested_blocks: NestedBlocksHeader;
+}
+
+export interface BlocksLayoutOptions {
+  /** Width of a leaf block (a block with no children). */
+  leafWidth?: number;
+  /** Height of a leaf block. */
+  leafHeight?: number;
+  /** Padding inside every block (between header / inner edges and children). */
+  padding?: number;
+  /** Header strip height that carries the block's name. */
+  headerHeight?: number;
+  /** Gap between sibling children inside the same parent. */
+  childGap?: number;
+  /** Gap between independent top-level blocks (vertical stacking). */
+  topLevelGap?: number;
+}
+
+export interface LaidOutBlock {
+  id: string;
+  name: string;
+  description?: string;
+  /** Tree depth starting at 1 for top-level blocks. */
+  depth: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  headerHeight: number;
+  children: LaidOutBlock[];
+}
+
+import type { LayoutBounds } from '../geometry.js';
+export type { LayoutBounds };
+
+export interface BlocksLayout {
+  bounds: LayoutBounds;
+  /** Top-level blocks; each carries its own subtree of laid-out children. */
+  blocks: LaidOutBlock[];
+  /** Maximum nesting depth in the laid-out tree (1-indexed). */
+  maxDepth: number;
+}

package/src/blocks/validate.ts

@@ -0,0 +1,206 @@
+import type { Block } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+export type { ValidationError, ValidationWarning, ValidationResult };
+
+/** Document-level ID grammar: BLOCKS-[<middle>-]<INTEGER>. */
+const BLOCKS_DOC_ID_RE = /^BLOCKS(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+
+/**
+ * Canonical cross-reference ID grammar — `<TYPE>-[<middle>-]<INTEGER>` with
+ * an uppercase TYPE prefix and a positive-integer terminal.
+ *
+ * Block IDs that match this shape are treated as cross-references to an
+ * organisational catalogue and must use a TYPE registered in
+ * IDS_AND_REFERENCES.md §3.1. IDs that do not match the shape (e.g.
+ * `APPLICATION_LAYER`, `FRONTEND`) are notation-local labels and are
+ * accepted as-is.
+ */
+const CANONICAL_ID_RE = /^[A-Z][A-Z0-9_]*(-[A-Z0-9][A-Z0-9_]*)+-\d+$/;
+
+/**
+ * `CAPABILITY` is the registered exception in IDS_AND_REFERENCES.md §2 — its
+ * terminal is a V/H diagram address (`V1`, `V1.2`, `V1.2.3`, `H1.2`), not a
+ * plain integer. A capability ID never matches CANONICAL_ID_RE because of the
+ * dot, so we recognise it separately.
+ */
+const CAPABILITY_ID_RE = /^CAPABILITY-[VH]\d+(\.\d+){0,2}$/;
+
+/** Element-level TYPE registry — IDS_AND_REFERENCES.md §3.1. */
+const REGISTERED_ELEMENT_TYPES = new Set<string>([
+  'FACTOR',
+  'GOAL',
+  'CHANGE',
+  'ACTIVITY',
+  'CAPABILITY',
+  'PROCESS',
+  'PRODUCT',
+  'APPLICATION',
+  'INTEGRATION',
+  'ROLE',
+  'UNIT',
+  'EMPLOYEE',
+  'SCENARIO',
+  'ISSUE',
+  'STAGE',
+]);
+
+/**
+ * Recommended maximum nesting depth (1-indexed). The spec warns at depth 6+;
+ * deeper nesting tends to produce inner boxes too small to read.
+ */
+const RECOMMENDED_MAX_DEPTH = 5;
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+function extractTypePrefix(id: string): string {
+  const dash = id.indexOf('-');
+  return dash >= 0 ? id.slice(0, dash) : id;
+}
+
+export function validateNestedBlocks(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return {
+      valid: false,
+      errors: [{ code: 'BL-001', message: 'Input must be an object' }],
+      warnings,
+    };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  if ('notation' in raw && raw['notation'] !== 'blocks') {
+    errors.push({
+      code: 'BL-001',
+      message: `notation must be "blocks", got "${String(raw['notation'])}"`,
+    });
+  }
+
+  if (!('nested_blocks' in raw) || !raw['nested_blocks'] || typeof raw['nested_blocks'] !== 'object') {
+    errors.push({ code: 'BL-001', message: 'Missing required root key: nested_blocks' });
+    return { valid: false, errors, warnings };
+  }
+
+  const nb = raw['nested_blocks'] as Record<string, unknown>;
+
+  if (!isNonEmptyString(nb['id'])) {
+    errors.push({ code: 'BL-002', message: 'nested_blocks.id is required' });
+  } else if (!BLOCKS_DOC_ID_RE.test(nb['id'])) {
+    errors.push({
+      code: 'BL-002',
+      message: `nested_blocks.id "${nb['id']}" must match BLOCKS-[<middle>-]<INTEGER>`,
+    });
+  }
+
+  if (!isNonEmptyString(nb['name'])) {
+    errors.push({ code: 'BL-003', message: 'nested_blocks.name is required' });
+  }
+
+  const topLevel = nb['blocks'];
+  if (!Array.isArray(topLevel) || topLevel.length === 0) {
+    errors.push({ code: 'BL-004', message: 'nested_blocks.blocks must be a non-empty array' });
+    return { valid: false, errors, warnings };
+  }
+
+  const seenIds = new Set<string>();
+  let maxDepthSeen = 0;
+
+  function walk(node: unknown, path: string, depth: number): void {
+    if (depth > maxDepthSeen) maxDepthSeen = depth;
+
+    if (!node || typeof node !== 'object') {
+      errors.push({ code: 'BL-005', message: `${path} must be an object`, path });
+      return;
+    }
+    const b = node as Record<string, unknown>;
+
+    if (!isNonEmptyString(b['id'])) {
+      errors.push({ code: 'BL-005', message: `${path}.id is required`, path });
+    } else {
+      const id = b['id'].trim();
+      if (seenIds.has(id)) {
+        errors.push({ code: 'BL-007', message: `Duplicate block id: "${id}"`, path });
+      } else {
+        seenIds.add(id);
+      }
+
+      // BL-006 — only enforce when the id LOOKS canonical (uppercase TYPE prefix
+      // + dashed segments + integer terminal, or the CAPABILITY V/H exception).
+      // Free-form local labels with whitespace, lowercase, etc. are accepted.
+      const looksCanonical = CANONICAL_ID_RE.test(id) || CAPABILITY_ID_RE.test(id);
+      if (looksCanonical) {
+        const typePrefix = extractTypePrefix(id);
+        if (!REGISTERED_ELEMENT_TYPES.has(typePrefix)) {
+          errors.push({
+            code: 'BL-006',
+            message: `${path}.id "${id}" uses TYPE prefix "${typePrefix}" which is not in the registered element-type list. Use a registered TYPE (FACTOR, GOAL, CAPABILITY, APPLICATION, …) or a free-form local label.`,
+            path,
+          });
+        }
+      } else if (/\s/.test(id)) {
+        errors.push({
+          code: 'BL-005',
+          message: `${path}.id "${id}" must not contain whitespace; use a slug-style local label or a canonical cross-reference id`,
+          path,
+        });
+      }
+    }
+
+    if (!isNonEmptyString(b['name'])) {
+      errors.push({ code: 'BL-005', message: `${path}.name is required`, path });
+    }
+
+    const children = b['children'];
+    if (children === undefined) return;
+    if (!Array.isArray(children)) {
+      errors.push({ code: 'BL-005', message: `${path}.children must be an array when present`, path });
+      return;
+    }
+    if (children.length === 0) {
+      warnings.push({
+        code: 'BL-009',
+        message: `${path}.children is an empty array — omit the key for leaf blocks`,
+        path,
+      });
+      return;
+    }
+    for (let i = 0; i < children.length; i++) {
+      walk(children[i], `${path}.children[${i}]`, depth + 1);
+    }
+  }
+
+  for (let i = 0; i < topLevel.length; i++) {
+    walk(topLevel[i], `blocks[${i}]`, 1);
+  }
+
+  if (maxDepthSeen > RECOMMENDED_MAX_DEPTH) {
+    warnings.push({
+      code: 'BL-008',
+      message: `Nesting depth ${maxDepthSeen} exceeds the recommended maximum of ${RECOMMENDED_MAX_DEPTH}; inner blocks may render too small to read`,
+    });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Convenience: validate a single `Block` subtree. Used by tests and by
+ * downstream consumers that need to check a sub-document.
+ */
+export function isWellFormedBlock(b: Block): boolean {
+  if (!b || typeof b !== 'object') return false;
+  if (typeof b.id !== 'string' || b.id.trim() === '') return false;
+  if (typeof b.name !== 'string' || b.name.trim() === '') return false;
+  if (b.children !== undefined) {
+    if (!Array.isArray(b.children)) return false;
+    for (const c of b.children) {
+      if (!isWellFormedBlock(c)) return false;
+    }
+  }
+  return true;
+}

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

@@ -0,0 +1,238 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { validateCapabilityMap } from '../validate.js';
+
+const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'capability-map');
+
+const VALID_MAP = {
+  notation: 'capability-map',
+  capability_map: {
+    id: 'CM-BUSINESS-001',
+    name: 'Business Capabilities Map',
+    assessment_date: '2026-05-08',
+    capabilities: [
+      {
+        id: 'V1',
+        name: 'Order Management',
+        type: 'domain',
+        current_maturity: 2,
+        target_maturity: 3,
+        target_date: '2026-12-31',
+        children: [
+          { id: 'V1.1', name: 'Order Intake', current_maturity: 3 },
+          { id: 'V1.2', name: 'Order Fulfilment', current_maturity: 2, target_maturity: 3 },
+        ],
+      },
+      {
+        id: 'H1',
+        name: 'Master Data Management',
+        type: 'supporting',
+        current_maturity: 1,
+        target_maturity: 3,
+      },
+    ],
+  },
+};
+
+describe('validateCapabilityMap', () => {
+  it('passes on valid input', () => {
+    const r = validateCapabilityMap(VALID_MAP);
+    expect(r.valid).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('CMAP-001: rejects non-object input', () => {
+    const r = validateCapabilityMap(null);
+    expect(r.errors[0].code).toBe('CMAP-001');
+  });
+
+  it('CMAP-001: rejects missing notation', () => {
+    const { notation: _, ...rest } = VALID_MAP;
+    const r = validateCapabilityMap(rest);
+    expect(r.errors.some(e => e.code === 'CMAP-001')).toBe(true);
+  });
+
+  it('CMAP-001: rejects wrong notation value', () => {
+    const r = validateCapabilityMap({ ...VALID_MAP, notation: 'goals' });
+    expect(r.errors.some(e => e.code === 'CMAP-001')).toBe(true);
+  });
+
+  it('CMAP-002: rejects missing capability_map', () => {
+    const r = validateCapabilityMap({ notation: 'capability-map' });
+    expect(r.errors.some(e => e.code === 'CMAP-002')).toBe(true);
+  });
+
+  it('CMAP-002: rejects missing id/name/assessment_date', () => {
+    const r = validateCapabilityMap({ notation: 'capability-map', capability_map: { capabilities: [] } });
+    expect(r.errors.filter(e => e.code === 'CMAP-002').length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('CMAP-002: rejects non-array capabilities', () => {
+    const map = { ...VALID_MAP.capability_map, capabilities: 'oops' };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-002')).toBe(true);
+  });
+
+  it('CMAP-003: rejects capability missing id/name/current_maturity', () => {
+    const map = { ...VALID_MAP.capability_map, capabilities: [{}] };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.filter(e => e.code === 'CMAP-003').length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('CMAP-004: rejects invalid type', () => {
+    const map = {
+      ...VALID_MAP.capability_map,
+      capabilities: [{ id: 'V1', name: 'X', type: 'core', current_maturity: 2 }],
+    };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-004')).toBe(true);
+  });
+
+  it('CMAP-004: accepts type domain/supporting', () => {
+    for (const type of ['domain', 'supporting']) {
+      const map = {
+        ...VALID_MAP.capability_map,
+        capabilities: [{ id: 'V1', name: 'X', type, current_maturity: 2 }],
+      };
+      const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+      expect(r.errors.some(e => e.code === 'CMAP-004')).toBe(false);
+    }
+  });
+
+  it('CMAP-005: rejects current_maturity out of range', () => {
+    const map = {
+      ...VALID_MAP.capability_map,
+      capabilities: [{ id: 'V1', name: 'X', current_maturity: 6 }],
+    };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-005')).toBe(true);
+  });
+
+  it('CMAP-005: rejects non-integer current_maturity', () => {
+    const map = {
+      ...VALID_MAP.capability_map,
+      capabilities: [{ id: 'V1', name: 'X', current_maturity: 2.5 }],
+    };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-005')).toBe(true);
+  });
+
+  it('CMAP-006: rejects target_maturity out of range', () => {
+    const map = {
+      ...VALID_MAP.capability_map,
+      capabilities: [{ id: 'V1', name: 'X', current_maturity: 2, target_maturity: 0 }],
+    };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-006')).toBe(true);
+  });
+
+  it('CMAP-007: rejects malformed assessment_date', () => {
+    const map = { ...VALID_MAP.capability_map, assessment_date: '08-05-2026' };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-007')).toBe(true);
+  });
+
+  it('CMAP-007: rejects malformed target_date on a node', () => {
+    const map = {
+      ...VALID_MAP.capability_map,
+      capabilities: [{ id: 'V1', name: 'X', current_maturity: 2, target_date: 'tomorrow' }],
+    };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-007')).toBe(true);
+  });
+
+  it('CMAP-008: rejects duplicate capability id across the tree', () => {
+    const map = {
+      ...VALID_MAP.capability_map,
+      capabilities: [
+        { id: 'V1', name: 'A', current_maturity: 2, children: [{ id: 'V1', name: 'B', current_maturity: 1 }] },
+      ],
+    };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-008')).toBe(true);
+  });
+
+  it('CMAP-009: rejects malformed capability id', () => {
+    const map = {
+      ...VALID_MAP.capability_map,
+      capabilities: [{ id: 'X1', name: 'A', current_maturity: 2 }],
+    };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-009')).toBe(true);
+  });
+
+  it('CMAP-009: accepts V/H ids with dotted levels', () => {
+    for (const id of ['V1', 'V1.2', 'V1.2.3', 'H1', 'H1.2', 'H10.20.30']) {
+      const map = {
+        ...VALID_MAP.capability_map,
+        capabilities: [{ id, name: 'A', current_maturity: 2 }],
+      };
+      const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+      expect(r.errors.some(e => e.code === 'CMAP-009')).toBe(false);
+    }
+  });
+
+  it('CMAP-009: accepts the canonical CAPABILITY- prefix', () => {
+    for (const id of ['CAPABILITY-V1', 'CAPABILITY-V1.2', 'CAPABILITY-V1.2.3', 'CAPABILITY-H1', 'CAPABILITY-H1.2']) {
+      const map = {
+        ...VALID_MAP.capability_map,
+        capabilities: [{ id, name: 'A', current_maturity: 2 }],
+      };
+      const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+      expect(r.errors.some(e => e.code === 'CMAP-009')).toBe(false);
+    }
+  });
+
+  it('validates children recursively', () => {
+    const map = {
+      ...VALID_MAP.capability_map,
+      capabilities: [{
+        id: 'V1', name: 'Root', current_maturity: 2,
+        children: [{ id: 'BAD_ID', name: 'X', current_maturity: 7 }],
+      }],
+    };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.errors.some(e => e.code === 'CMAP-009')).toBe(true);
+    expect(r.errors.some(e => e.code === 'CMAP-005')).toBe(true);
+  });
+
+  it('accepts empty capabilities array', () => {
+    const map = { ...VALID_MAP.capability_map, capabilities: [] };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.valid).toBe(true);
+  });
+
+  // Pre-release blocker regression (orchestrator review 2026-05-21).
+  it('[blocker] tolerates a null element in capabilities[] without throwing', () => {
+    const map = { ...VALID_MAP.capability_map, capabilities: [null] };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'CMAP-003')).toBe(true);
+  });
+
+  it('[blocker] tolerates a null child capability without throwing', () => {
+    const map = {
+      ...VALID_MAP.capability_map,
+      capabilities: [{ id: 'V1', name: 'X', current_maturity: 2, children: [null] }],
+    };
+    const r = validateCapabilityMap({ ...VALID_MAP, capability_map: map });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'CMAP-003')).toBe(true);
+  });
+});
+
+describe('capability-map 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/capability-map/${file}`, () => {
+      const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+      const parsed = yaml.load(text);
+      const r = validateCapabilityMap(parsed);
+      expect(r.errors).toEqual([]);
+      expect(r.valid).toBe(true);
+    });
+  }
+});

package/src/capability-map/index.ts

@@ -0,0 +1,8 @@
+export type {
+  CapabilityType,
+  CapabilityNode,
+  CapabilityMapHeader,
+  CapabilityMapFile,
+} from './types.js';
+
+export { validateCapabilityMap } from './validate.js';