@transitrix/diagrams 1.0.0

package/dist/goals/parse-canonical.js

@@ -0,0 +1,257 @@
+/**
+ * Canonical-form Goals parser + validator.
+ *
+ * Accepts the methodology's canonical Goals YAML shape (see
+ * `transitrix/methodology` `notations/04-goals.md`):
+ *
+ * - Flat top-level: `notation`, `id`, `name`, `goal_types[]`, `goals[]`.
+ *   No `goals_tree:` wrapper, no `root.goal_id` / `children:` nesting.
+ * - Typed string IDs (`GOAL-…`); document id `GOALS-[<middle>-]<INTEGER>`.
+ * - Hierarchy via `parent: GOAL-…` on each goal; omit for root.
+ * - Per-notation validation codes `GOALS-001 … GOALS-011`.
+ *
+ * Returns the validation result plus, on success, an internal `GoalTree`
+ * built from the canonical input — canonical typed-string IDs are
+ * mapped to internal sequential numbers, `parent: GOAL-X` becomes
+ * `parent_id: <numeric>`, `parent_id: 0` denotes a root.
+ *
+ * Strategy hub #63: this lives at the input boundary so the library's
+ * internal types (numeric IDs) stay where they are. Convergence on
+ * canonical typed-string IDs across all sister modules is a follow-up
+ * task.
+ */
+const GOAL_ID_RE = /^GOAL(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const GOALS_DOC_ID_RE = /^GOALS(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+export function parseCanonicalGoals(input) {
+    const errors = [];
+    const warnings = [];
+    if (!input || typeof input !== 'object') {
+        return {
+            valid: false,
+            errors: [{ code: 'GOALS-001', message: 'document root is not an object' }],
+            warnings,
+        };
+    }
+    const raw = input;
+    if ('notation' in raw && raw['notation'] !== 'goals') {
+        return {
+            valid: false,
+            errors: [
+                {
+                    code: 'GOALS-001',
+                    message: `notation must be "goals", got "${String(raw['notation'])}"`,
+                },
+            ],
+            warnings,
+        };
+    }
+    // GOALS-002 — document id.
+    if (raw['id'] !== undefined) {
+        if (!isNonEmptyString(raw['id']) || !GOALS_DOC_ID_RE.test(raw['id'])) {
+            errors.push({
+                code: 'GOALS-002',
+                message: `id "${String(raw['id'])}" must match GOALS-[<middle>-]<INTEGER>`,
+            });
+        }
+    }
+    else {
+        errors.push({ code: 'GOALS-002', message: 'document id is required' });
+    }
+    if (!isNonEmptyString(raw['name'])) {
+        errors.push({ code: 'GOALS-003', message: 'name is required' });
+    }
+    const goalTypesRaw = raw['goal_types'];
+    const goalsRaw = raw['goals'];
+    if (!Array.isArray(goalTypesRaw) || goalTypesRaw.length === 0) {
+        errors.push({ code: 'GOALS-004', message: 'goal_types must be a non-empty array', path: 'goal_types' });
+    }
+    if (!Array.isArray(goalsRaw) || goalsRaw.length === 0) {
+        errors.push({ code: 'GOALS-004', message: 'goals must be a non-empty array', path: 'goals' });
+    }
+    if (errors.length > 0)
+        return { valid: false, errors, warnings };
+    const gtArr = goalTypesRaw;
+    const gArr = goalsRaw;
+    // GOALS-005 — goal_types entries.
+    const typeByName = new Map();
+    const internalGoalTypes = [];
+    for (let i = 0; i < gtArr.length; i++) {
+        const el = gtArr[i];
+        const path = `goal_types[${i}]`;
+        if (!el || typeof el !== 'object') {
+            errors.push({ code: 'GOALS-005', message: `${path} must be an object`, path });
+            continue;
+        }
+        const o = el;
+        if (!isNonEmptyString(o['name'])) {
+            errors.push({ code: 'GOALS-005', message: `${path}.name is required`, path });
+            continue;
+        }
+        const lvl = o['level'];
+        if (typeof lvl !== 'number' || !Number.isInteger(lvl) || lvl < 0) {
+            errors.push({ code: 'GOALS-005', message: `${path}.level must be a non-negative integer`, path });
+            continue;
+        }
+        if (typeByName.has(o['name'])) {
+            errors.push({ code: 'GOALS-005', message: `${path}: duplicate goal_types name "${o['name']}"`, path });
+            continue;
+        }
+        typeByName.set(o['name'], lvl);
+        internalGoalTypes.push({ name: o['name'], level: lvl });
+    }
+    if (errors.length > 0)
+        return { valid: false, errors, warnings };
+    // GOALS-006 / 007 — goals entries.
+    const seenIds = new Set();
+    const goalById = new Map();
+    const checkedGoals = [];
+    for (let i = 0; i < gArr.length; i++) {
+        const el = gArr[i];
+        const path = `goals[${i}]`;
+        if (!el || typeof el !== 'object') {
+            errors.push({ code: 'GOALS-006', message: `${path} must be an object`, path });
+            continue;
+        }
+        const o = el;
+        if (!isNonEmptyString(o['id'])) {
+            errors.push({ code: 'GOALS-006', message: `${path}.id is required`, path });
+            continue;
+        }
+        if (!isNonEmptyString(o['name'])) {
+            errors.push({ code: 'GOALS-006', message: `${path}.name is required`, path });
+        }
+        if (!isNonEmptyString(o['type'])) {
+            errors.push({ code: 'GOALS-006', message: `${path}.type is required`, path });
+        }
+        const lvl = o['level'];
+        if (typeof lvl !== 'number' || !Number.isInteger(lvl) || lvl < 0) {
+            errors.push({ code: 'GOALS-006', message: `${path}.level must be a non-negative integer`, path });
+        }
+        if (!GOAL_ID_RE.test(o['id'])) {
+            errors.push({
+                code: 'GOALS-007',
+                message: `${path}.id "${o['id']}" must match GOAL-[<middle>-]<INTEGER>`,
+                path,
+            });
+            continue;
+        }
+        if (seenIds.has(o['id'])) {
+            errors.push({ code: 'GOALS-007', message: `${path}: duplicate goal id "${o['id']}"`, path });
+            continue;
+        }
+        seenIds.add(o['id']);
+        goalById.set(o['id'], o);
+        checkedGoals.push({ raw: o, path });
+    }
+    if (errors.length > 0)
+        return { valid: false, errors, warnings };
+    // GOALS-008 — type / level consistency.
+    for (const { raw: o, path } of checkedGoals) {
+        const t = o['type'];
+        const lvl = o['level'];
+        const expectedLvl = typeByName.get(t);
+        if (expectedLvl === undefined) {
+            errors.push({
+                code: 'GOALS-008',
+                message: `${path}.type "${t}" is not defined in goal_types[]`,
+                path,
+            });
+            continue;
+        }
+        if (expectedLvl !== lvl) {
+            errors.push({
+                code: 'GOALS-008',
+                message: `${path}.level ${lvl} does not match the level (${expectedLvl}) of goal_types entry "${t}"`,
+                path,
+            });
+        }
+    }
+    // GOALS-009 / 010 — parent references + cycle detection.
+    // Assign internal numeric ids (canonical → sequential).
+    const idToInternal = new Map();
+    let counter = 0;
+    for (const { raw: o } of checkedGoals) {
+        counter += 1;
+        idToInternal.set(o['id'], counter);
+    }
+    // GOALS-009: broken parent ref → warn (per spec, "treated as backlog").
+    // GOALS-011: non-root goal without parent → warn.
+    for (const { raw: o, path } of checkedGoals) {
+        const parent = o['parent'];
+        const lvl = o['level'];
+        if (parent === undefined || parent === null) {
+            if (lvl >= 1) {
+                warnings.push({
+                    code: 'GOALS-011',
+                    message: `${path}: non-root goal (level ${lvl}) has no parent — orphan / backlog`,
+                    path,
+                });
+            }
+            continue;
+        }
+        if (!isNonEmptyString(parent) || !GOAL_ID_RE.test(parent)) {
+            errors.push({
+                code: 'GOALS-007',
+                message: `${path}.parent "${String(parent)}" must match GOAL-[<middle>-]<INTEGER>`,
+                path,
+            });
+            continue;
+        }
+        if (!goalById.has(parent)) {
+            warnings.push({
+                code: 'GOALS-009',
+                message: `${path}.parent "${parent}" references an undefined goal — treated as orphan / backlog`,
+                path,
+            });
+        }
+    }
+    // GOALS-010 — cycle detection. Follow each goal's parent chain to a root
+    // (parent missing or undefined). If we revisit, that's a cycle.
+    for (const { raw: o } of checkedGoals) {
+        const startId = o['id'];
+        let curId = startId;
+        const visited = new Set();
+        while (curId) {
+            if (visited.has(curId)) {
+                errors.push({
+                    code: 'GOALS-010',
+                    message: `Cycle detected in parent chain involving goal "${startId}"`,
+                });
+                break;
+            }
+            visited.add(curId);
+            const cur = goalById.get(curId);
+            const p = cur?.['parent'];
+            if (!isNonEmptyString(p))
+                break;
+            if (!goalById.has(p))
+                break;
+            curId = p;
+        }
+    }
+    if (errors.length > 0)
+        return { valid: false, errors, warnings };
+    // Build internal GoalTree.
+    const internalGoals = checkedGoals.map(({ raw: o }) => {
+        const parent = o['parent'];
+        const parentId = isNonEmptyString(parent) && idToInternal.has(parent) ? idToInternal.get(parent) : 0;
+        return {
+            id: idToInternal.get(o['id']),
+            name: o['name'],
+            type: o['type'],
+            level: o['level'],
+            parent_id: parentId,
+            description: typeof o['description'] === 'string' ? o['description'] : undefined,
+            link: typeof o['link'] === 'string' ? o['link'] : undefined,
+            tag: typeof o['tag'] === 'string' ? o['tag'] : undefined,
+        };
+    });
+    const parsed = {
+        goal_types: internalGoalTypes,
+        goals: internalGoals,
+    };
+    return { valid: true, errors, warnings, parsed };
+}

package/dist/goals/types.d.ts

@@ -0,0 +1,71 @@
+export type ImpactType = 'opportunity' | 'positive' | 'risk' | 'negative' | 'mixed';
+export interface Factor {
+    id: number;
+    name: string;
+    description?: string;
+    segment?: string;
+    impact_type: ImpactType;
+}
+export interface Goal {
+    id: number;
+    name: string;
+    type: string;
+    level: number;
+    parent_id: number;
+    link?: string;
+    tag?: string;
+    description?: string;
+    factors?: Factor[];
+    created_at?: string;
+}
+export interface GoalType {
+    name: string;
+    level: number;
+}
+export interface GoalTree {
+    goal_types: GoalType[];
+    goals: Goal[];
+}
+export type { ValidationError, ValidationWarning, ValidationResult, } from '../validation-types.js';
+import type { ValidationError } from '../validation-types.js';
+export interface MutationResult<T> {
+    ok: boolean;
+    result?: T;
+    error?: ValidationError;
+}
+import type { Scope } from '../scope.js';
+export interface LayoutOptions {
+    rankdir?: 'LR' | 'TB';
+    nodeWidth?: number;
+    nodeHeight?: number;
+    rankSep?: number;
+    nodeSep?: number;
+    hideCollapsed?: number[];
+    viewDepth?: number | null;
+    /** Trim the tree to a level cap or a subtree root (vkgeorgia/strategy#77). Defaults to 'all'. */
+    scope?: Scope;
+}
+export interface LaidOutNode {
+    id: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    data: Goal;
+    isCollapsedRoot: boolean;
+    hasHiddenChildren: boolean;
+}
+export interface LaidOutEdge {
+    source: number;
+    target: number;
+}
+export interface GoalTreeLayout {
+    nodes: LaidOutNode[];
+    edges: LaidOutEdge[];
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

package/dist/goals/types.js

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

package/dist/goals/validate.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationResult } from './types.js';
+export declare function validateGoalTree(input: unknown): ValidationResult;

package/dist/goals/validate.js

@@ -0,0 +1,122 @@
+export function validateGoalTree(input) {
+    const errors = [];
+    const warnings = [];
+    if (!input || typeof input !== 'object') {
+        return { valid: false, errors: [{ code: 'SCHEMA_INVALID', message: 'Input must be an object' }], warnings: [] };
+    }
+    const raw = input;
+    if (!Array.isArray(raw.goals)) {
+        errors.push({ code: 'SCHEMA_INVALID', message: 'goals must be an array', path: 'goals' });
+    }
+    if (!Array.isArray(raw.goal_types)) {
+        errors.push({ code: 'SCHEMA_INVALID', message: 'goal_types must be an array', path: 'goal_types' });
+    }
+    if (errors.length > 0)
+        return { valid: false, errors, warnings };
+    const tree = raw;
+    // GOALS-013 — goal_types[].level values must be contiguous starting from 0.
+    // Per the N+1 rule (decision in vkgeorgia/strategy#66), the level set must
+    // be exactly {0, 1, …, N}; a gap breaks the parent→child level invariant
+    // and means GOALS-012 cannot be enforced consistently.
+    const levels = tree.goal_types
+        .map(gt => gt.level)
+        .filter(l => typeof l === 'number' && Number.isFinite(l));
+    if (levels.length > 0) {
+        const unique = Array.from(new Set(levels)).sort((a, b) => a - b);
+        const expected = Array.from({ length: unique.length }, (_, i) => i);
+        const contiguous = unique.length === expected.length && unique.every((v, i) => v === expected[i]);
+        if (!contiguous) {
+            errors.push({
+                code: 'GOALS-013',
+                message: `goal_types[].level values must be contiguous starting from 0; got [${unique.join(', ')}]`,
+                path: 'goal_types',
+            });
+        }
+    }
+    const maxLevel = Math.max(...tree.goal_types.map(gt => gt.level), 0);
+    const typeMap = new Map(tree.goal_types.map(gt => [gt.name, gt.level]));
+    const idSet = new Set();
+    const levelById = new Map();
+    for (let i = 0; i < tree.goals.length; i++) {
+        const g = tree.goals[i];
+        const path = `goals[${i}]`;
+        if (!g || typeof g !== 'object') {
+            errors.push({ code: 'SCHEMA_INVALID', message: 'goal entry must be an object', path });
+            continue;
+        }
+        const goal = g;
+        if (typeof goal.id !== 'number') {
+            errors.push({ code: 'SCHEMA_INVALID', message: 'goal id must be a number', path });
+            continue;
+        }
+        if (!goal.name || typeof goal.name !== 'string' || goal.name.trim() === '') {
+            errors.push({ code: 'EMPTY_NAME', message: `Goal ${goal.id} has empty name`, path });
+        }
+        if (idSet.has(goal.id)) {
+            errors.push({ code: 'DUPLICATE_ID', message: `Duplicate goal id: ${goal.id}`, path });
+        }
+        else {
+            idSet.add(goal.id);
+        }
+        if (typeof goal.level !== 'number' || !Number.isFinite(goal.level)) {
+            errors.push({ code: 'SCHEMA_INVALID', message: `Goal ${goal.id} level must be a finite number`, path });
+            continue;
+        }
+        if (goal.level > maxLevel) {
+            errors.push({ code: 'MAX_LEVEL_EXCEEDED', message: `Goal ${goal.id} level ${goal.level} exceeds max ${maxLevel}`, path });
+        }
+        levelById.set(goal.id, goal.level);
+        const expectedLevel = typeof goal.type === 'string' ? typeMap.get(goal.type) : undefined;
+        if (expectedLevel !== undefined && expectedLevel !== goal.level) {
+            warnings.push({ code: 'TYPE_LEVEL_MISMATCH', message: `Goal ${goal.id} type "${String(goal.type)}" expects level ${expectedLevel}, got ${goal.level}`, path });
+        }
+    }
+    if (errors.length > 0)
+        return { valid: false, errors, warnings };
+    // Check broken parent refs and cycles after all ids are collected
+    for (let i = 0; i < tree.goals.length; i++) {
+        const g = tree.goals[i];
+        const path = `goals[${i}]`;
+        if (!g || typeof g !== 'object')
+            continue;
+        if (g.parent_id !== 0 && !idSet.has(g.parent_id)) {
+            warnings.push({ code: 'BROKEN_PARENT_REF', message: `Goal ${g.id} references missing parent ${g.parent_id} — moved to backlog`, path });
+            continue;
+        }
+        // GOALS-012 — parent must be exactly one level above the child (N+1
+        // hierarchy, decision in vkgeorgia/strategy#66). Only enforced when the
+        // parent is resolvable; a missing parent is covered by BROKEN_PARENT_REF.
+        if (g.parent_id !== 0) {
+            const parentLevel = levelById.get(g.parent_id);
+            if (parentLevel !== undefined && g.level !== parentLevel + 1) {
+                errors.push({
+                    code: 'GOALS-012',
+                    message: `Goal ${g.id} (level ${g.level}) must have a parent at level ${g.level - 1}; parent ${g.parent_id} is at level ${parentLevel}`,
+                    path,
+                });
+            }
+        }
+    }
+    const cycleError = detectCycle(tree.goals);
+    if (cycleError)
+        errors.push(cycleError);
+    return { valid: errors.length === 0, errors, warnings };
+}
+function detectCycle(goals) {
+    const parentOf = new Map(goals.map(g => [g.id, g.parent_id]));
+    for (const g of goals) {
+        const visited = new Set();
+        let cur = g.id;
+        while (cur !== 0) {
+            if (visited.has(cur)) {
+                return { code: 'CYCLE_DETECTED', message: `Cycle detected involving goal ${g.id}` };
+            }
+            visited.add(cur);
+            const parent = parentOf.get(cur);
+            if (parent === undefined)
+                break;
+            cur = parent;
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export * from "./activities/index";
+export * from "./activity-card/index";
+export * from "./geometry";
+export * from "./applications/index";
+export * from "./assertion/index";
+export * from "./blocks/index";
+export * from "./capability-map/index";
+export * from "./compliance/index";
+export * from "./compliance-matrix/index";
+export * from "./confidence/index";
+export * from "./fgca/index";
+export * from "./goals/index";
+export * from "./process-blueprint/index";
+export * from "./process-map/index";
+export * from "./products/index";
+export * from "./repo-validate/index";
+export * from "./requirement/index";
+export * from "./scenarios/index";
+export { SCHEMA_VERSION } from "./schema-version";
+export * from "./theme/index";
+export * from "./typed-id";
+export * from "./validation-types";
+export { coerceDatesToIsoStrings } from "./yaml-normalize";

package/dist/index.js

@@ -0,0 +1,23 @@
+export * from "./activities/index";
+export * from "./activity-card/index";
+export * from "./geometry";
+export * from "./applications/index";
+export * from "./assertion/index";
+export * from "./blocks/index";
+export * from "./capability-map/index";
+export * from "./compliance/index";
+export * from "./compliance-matrix/index";
+export * from "./confidence/index";
+export * from "./fgca/index";
+export * from "./goals/index";
+export * from "./process-blueprint/index";
+export * from "./process-map/index";
+export * from "./products/index";
+export * from "./repo-validate/index";
+export * from "./requirement/index";
+export * from "./scenarios/index";
+export { SCHEMA_VERSION } from "./schema-version";
+export * from "./theme/index";
+export * from "./typed-id";
+export * from "./validation-types";
+export { coerceDatesToIsoStrings } from "./yaml-normalize";

package/dist/issues/__tests__/layout.test.d.ts

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

package/dist/issues/__tests__/layout.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { layoutIssues } from '../layout.js';
+function build(issues) {
+    return {
+        notation: 'issues',
+        issues_catalogue: {
+            id: 'ISSUES-CAT-1',
+            name: 'Test',
+            updated_at: '2026-05-25',
+            issues,
+        },
+    };
+}
+describe('layoutIssues', () => {
+    it('lays out one row per issue', () => {
+        const layout = layoutIssues(build([
+            { issue_id: 'ISSUE-1', name: 'A', status: 'open' },
+            { issue_id: 'ISSUE-2', name: 'B', status: 'open' },
+        ]));
+        expect(layout.rows).toHaveLength(2);
+    });
+    it('indents sub-issues by nesting depth', () => {
+        const layout = layoutIssues(build([
+            { issue_id: 'ISSUE-1', name: 'Root', status: 'open' },
+            { issue_id: 'ISSUE-2', name: 'Child', status: 'open', parent: 'ISSUE-1' },
+            { issue_id: 'ISSUE-3', name: 'Grandchild', status: 'open', parent: 'ISSUE-2' },
+        ]));
+        const byId = new Map(layout.rows.map((r) => [r.issue_id, r]));
+        expect(byId.get('ISSUE-1').depth).toBe(0);
+        expect(byId.get('ISSUE-2').depth).toBe(1);
+        expect(byId.get('ISSUE-3').depth).toBe(2);
+        expect(byId.get('ISSUE-2').x).toBeGreaterThan(byId.get('ISSUE-1').x);
+    });
+    it('renders pre-order: a child row follows its parent', () => {
+        const layout = layoutIssues(build([
+            { issue_id: 'ISSUE-1', name: 'Root', status: 'open' },
+            { issue_id: 'ISSUE-2', name: 'Child', status: 'open', parent: 'ISSUE-1' },
+        ]));
+        expect(layout.rows[0].issue_id).toBe('ISSUE-1');
+        expect(layout.rows[1].issue_id).toBe('ISSUE-2');
+        expect(layout.rows[0].hasChildren).toBe(true);
+        expect(layout.rows[1].hasChildren).toBe(false);
+    });
+    it('places a broken-parent issue at the root', () => {
+        const layout = layoutIssues(build([
+            { issue_id: 'ISSUE-1', name: 'Orphan', status: 'open', parent: 'ISSUE-99' },
+        ]));
+        expect(layout.rows[0].depth).toBe(0);
+    });
+    it('does not stack-overflow or drop nodes on a parent cycle', () => {
+        const layout = layoutIssues(build([
+            { issue_id: 'ISSUE-1', name: 'A', status: 'open', parent: 'ISSUE-2' },
+            { issue_id: 'ISSUE-2', name: 'B', status: 'open', parent: 'ISSUE-1' },
+        ]));
+        expect(layout.rows).toHaveLength(2);
+    });
+    it('returns empty bounds for an empty register', () => {
+        const layout = layoutIssues(build([]));
+        expect(layout.rows).toHaveLength(0);
+        expect(layout.bounds).toEqual({ x: 0, y: 0, width: 0, height: 0 });
+    });
+});

package/dist/issues/__tests__/validate.test.d.ts

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

package/dist/issues/__tests__/validate.test.js

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { validateIssues } from '../validate.js';
+const VALID = {
+    notation: 'issues',
+    issues_catalogue: {
+        id: 'ISSUES-CAT-1',
+        name: 'Test Register',
+        updated_at: '2026-05-25',
+        issues: [
+            { issue_id: 'ISSUE-1', name: 'Root issue', status: 'open' },
+            { issue_id: 'ISSUE-2', name: 'Sub issue', status: 'in_progress', parent: 'ISSUE-1' },
+        ],
+    },
+};
+function withIssues(issues) {
+    return { ...VALID, issues_catalogue: { ...VALID.issues_catalogue, issues } };
+}
+describe('validateIssues', () => {
+    it('passes on valid input', () => {
+        const r = validateIssues(VALID);
+        expect(r.valid).toBe(true);
+        expect(r.errors).toHaveLength(0);
+    });
+    it('ISS-000: rejects a non-object', () => {
+        expect(validateIssues(null).valid).toBe(false);
+        expect(validateIssues('x').errors[0].code).toBe('ISS-000');
+    });
+    it('ISS-000: rejects a wrong notation header', () => {
+        const r = validateIssues({ ...VALID, notation: 'goals' });
+        expect(r.errors.some(e => e.code === 'ISS-000')).toBe(true);
+    });
+    it('ISS-000: rejects a missing issues_catalogue', () => {
+        const r = validateIssues({ notation: 'issues' });
+        expect(r.errors.some(e => e.code === 'ISS-000')).toBe(true);
+    });
+    it('ISS-001: detects a duplicate issue_id', () => {
+        const r = validateIssues(withIssues([
+            { issue_id: 'ISSUE-1', name: 'A', status: 'open' },
+            { issue_id: 'ISSUE-1', name: 'B', status: 'open' },
+        ]));
+        expect(r.errors.some(e => e.code === 'ISS-001')).toBe(true);
+    });
+    it('ISS-002: detects a status outside the vocabulary', () => {
+        const r = validateIssues(withIssues([{ issue_id: 'ISSUE-1', name: 'A', status: 'wip' }]));
+        expect(r.errors.some(e => e.code === 'ISS-002')).toBe(true);
+    });
+    it('ISS-003: detects a missing or empty name', () => {
+        const r = validateIssues(withIssues([{ issue_id: 'ISSUE-1', name: '', status: 'open' }]));
+        expect(r.errors.some(e => e.code === 'ISS-003')).toBe(true);
+    });
+    it('ISS-004: warns on a broken parent reference and stays valid', () => {
+        const r = validateIssues(withIssues([
+            { issue_id: 'ISSUE-1', name: 'Orphan', status: 'open', parent: 'ISSUE-99' },
+        ]));
+        expect(r.valid).toBe(true);
+        expect(r.warnings.some(w => w.code === 'ISS-004')).toBe(true);
+    });
+    it('ISS-005: detects a parent cycle', () => {
+        const r = validateIssues(withIssues([
+            { issue_id: 'ISSUE-1', name: 'A', status: 'open', parent: 'ISSUE-2' },
+            { issue_id: 'ISSUE-2', name: 'B', status: 'open', parent: 'ISSUE-1' },
+        ]));
+        expect(r.errors.some(e => e.code === 'ISS-005')).toBe(true);
+    });
+    it('ISS-006: rejects a relates_to entry that is not an ACTIVITY-/GOAL- id', () => {
+        const r = validateIssues(withIssues([
+            { issue_id: 'ISSUE-1', name: 'A', status: 'open', relates_to: ['PRODUCT-1'] },
+        ]));
+        expect(r.errors.some(e => e.code === 'ISS-006')).toBe(true);
+    });
+    it('accepts valid ACTIVITY-/GOAL- relates_to ids', () => {
+        const r = validateIssues(withIssues([
+            { issue_id: 'ISSUE-1', name: 'A', status: 'open', relates_to: ['ACTIVITY-5', 'GOAL-CUST-1'] },
+        ]));
+        expect(r.valid).toBe(true);
+    });
+    it('tolerates a null element in issues[] without throwing', () => {
+        const r = validateIssues(withIssues([null]));
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'ISS-003')).toBe(true);
+    });
+});

package/dist/issues/index.d.ts

@@ -0,0 +1,4 @@
+export type { IssueStatus, Issue, IssuesCatalogue, IssuesFile, IssuesLayoutOptions, LaidOutIssue, IssuesLayoutBounds, IssuesLayout, } from './types.js';
+export { validateIssues } from './validate.js';
+export type { ValidationError as IssuesValidationError, ValidationWarning as IssuesValidationWarning, ValidationResult as IssuesValidationResult, } from './validate.js';
+export { layoutIssues } from './layout.js';

package/dist/issues/index.js

@@ -0,0 +1,2 @@
+export { validateIssues } from './validate.js';
+export { layoutIssues } from './layout.js';