@transitrix/diagrams 1.0.0

package/dist/blocks/layout.js

@@ -0,0 +1,145 @@
+const DEFAULTS = {
+    leafWidth: 160,
+    leafHeight: 60,
+    padding: 12,
+    headerHeight: 28,
+    childGap: 12,
+    topLevelGap: 24,
+};
+function resolveOptions(options) {
+    return { ...DEFAULTS, ...(options ?? {}) };
+}
+function measure(b, opts) {
+    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(cols).fill(0);
+    const rowHeights = new Array(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, m, x, y, depth, opts) {
+    const node = {
+        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) {
+    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, options) {
+    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 = [];
+    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) {
+    function* walk(b) {
+        yield b;
+        for (const c of b.children)
+            yield* walk(c);
+    }
+    for (const b of layout.blocks)
+        yield* walk(b);
+}

package/dist/blocks/types.d.ts

@@ -0,0 +1,56 @@
+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/dist/blocks/types.js

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

package/dist/blocks/validate.d.ts

@@ -0,0 +1,9 @@
+import type { Block } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+export type { ValidationError, ValidationWarning, ValidationResult };
+export declare function validateNestedBlocks(input: unknown): ValidationResult;
+/**
+ * Convenience: validate a single `Block` subtree. Used by tests and by
+ * downstream consumers that need to check a sub-document.
+ */
+export declare function isWellFormedBlock(b: Block): boolean;

package/dist/blocks/validate.js

@@ -0,0 +1,186 @@
+/** 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([
+    '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) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+function extractTypePrefix(id) {
+    const dash = id.indexOf('-');
+    return dash >= 0 ? id.slice(0, dash) : id;
+}
+export function validateNestedBlocks(input) {
+    const errors = [];
+    const warnings = [];
+    if (!input || typeof input !== 'object') {
+        return {
+            valid: false,
+            errors: [{ code: 'BL-001', message: 'Input must be an object' }],
+            warnings,
+        };
+    }
+    const raw = input;
+    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'];
+    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();
+    let maxDepthSeen = 0;
+    function walk(node, path, depth) {
+        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;
+        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) {
+    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/dist/capability-map/__tests__/validate.test.d.ts

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

package/dist/capability-map/__tests__/validate.test.js

@@ -0,0 +1,212 @@
+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/dist/capability-map/index.d.ts

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

package/dist/capability-map/index.js

@@ -0,0 +1 @@
+export { validateCapabilityMap } from './validate.js';

package/dist/capability-map/types.d.ts

@@ -0,0 +1,26 @@
+export type CapabilityType = 'domain' | 'supporting';
+export interface CapabilityNode {
+    id: string;
+    name: string;
+    type?: CapabilityType;
+    description?: string;
+    current_maturity: number;
+    target_maturity?: number;
+    target_date?: string;
+    owner_role?: string;
+    business_process?: string;
+    applications?: string[];
+    children?: CapabilityNode[];
+}
+export interface CapabilityMapHeader {
+    id: string;
+    name: string;
+    description?: string;
+    assessment_date: string;
+    capabilities: CapabilityNode[];
+}
+export interface CapabilityMapFile {
+    notation: string;
+    spec_version?: string;
+    capability_map: CapabilityMapHeader;
+}

package/dist/capability-map/types.js

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

package/dist/capability-map/validate.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+export type { ValidationError, ValidationWarning, ValidationResult };
+export declare function validateCapabilityMap(input: unknown): ValidationResult;