@transitrix/diagrams 1.0.0 → 1.0.1

package/src/yaml-normalize.ts

@@ -1,56 +1,56 @@
-/**
- * Coerce native `Date` instances inside a parsed YAML document into ISO
- * `YYYY-MM-DD` strings.
- *
- * Background: per the YAML 1.1 timestamp tag, a bare `2026-06-01` is parsed
- * by `js-yaml` as a native `Date`, not a string. Every notation validator in
- * this package expects ISO date strings (`typeof === 'string'` +
- * `YYYY-MM-DD` regex), so a Date reaching validation would falsely fail
- * shape checks even though the user followed the spec, minus quotes.
- *
- * The canonical, methodology-correct form is the quoted ISO string. This
- * coercion is a backstop so the unquoted form does not silently bite.
- *
- * UTC-safe: uses `getUTC*` so the JS process timezone cannot drift the day.
- * A bare `2026-06-01` parses to midnight UTC and round-trips to
- * `"2026-06-01"` regardless of `process.env.TZ`.
- *
- * Walks in place and returns the same reference for convenience.
- */
-export function coerceDatesToIsoStrings<T>(value: T): T {
-  if (value === null || value === undefined) return value;
-  if (value instanceof Date) {
-    return dateToIsoYmd(value) as unknown as T;
-  }
-  if (typeof value !== 'object') return value;
-
-  if (Array.isArray(value)) {
-    for (let i = 0; i < value.length; i++) {
-      const v = value[i];
-      if (v instanceof Date) {
-        value[i] = dateToIsoYmd(v) as unknown as typeof v;
-      } else if (v !== null && typeof v === 'object') {
-        coerceDatesToIsoStrings(v);
-      }
-    }
-    return value;
-  }
-
-  const obj = value as Record<string, unknown>;
-  for (const key of Object.keys(obj)) {
-    const v = obj[key];
-    if (v instanceof Date) {
-      obj[key] = dateToIsoYmd(v);
-    } else if (v !== null && typeof v === 'object') {
-      coerceDatesToIsoStrings(v);
-    }
-  }
-  return value;
-}
-
-function dateToIsoYmd(d: Date): string {
-  const y = d.getUTCFullYear();
-  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
-  const day = String(d.getUTCDate()).padStart(2, '0');
-  return `${y}-${m}-${day}`;
-}
+/**
+ * Coerce native `Date` instances inside a parsed YAML document into ISO
+ * `YYYY-MM-DD` strings.
+ *
+ * Background: per the YAML 1.1 timestamp tag, a bare `2026-06-01` is parsed
+ * by `js-yaml` as a native `Date`, not a string. Every notation validator in
+ * this package expects ISO date strings (`typeof === 'string'` +
+ * `YYYY-MM-DD` regex), so a Date reaching validation would falsely fail
+ * shape checks even though the user followed the spec, minus quotes.
+ *
+ * The canonical, methodology-correct form is the quoted ISO string. This
+ * coercion is a backstop so the unquoted form does not silently bite.
+ *
+ * UTC-safe: uses `getUTC*` so the JS process timezone cannot drift the day.
+ * A bare `2026-06-01` parses to midnight UTC and round-trips to
+ * `"2026-06-01"` regardless of `process.env.TZ`.
+ *
+ * Walks in place and returns the same reference for convenience.
+ */
+export function coerceDatesToIsoStrings<T>(value: T): T {
+  if (value === null || value === undefined) return value;
+  if (value instanceof Date) {
+    return dateToIsoYmd(value) as unknown as T;
+  }
+  if (typeof value !== 'object') return value;
+
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const v = value[i];
+      if (v instanceof Date) {
+        value[i] = dateToIsoYmd(v) as unknown as typeof v;
+      } else if (v !== null && typeof v === 'object') {
+        coerceDatesToIsoStrings(v);
+      }
+    }
+    return value;
+  }
+
+  const obj = value as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    const v = obj[key];
+    if (v instanceof Date) {
+      obj[key] = dateToIsoYmd(v);
+    } else if (v !== null && typeof v === 'object') {
+      coerceDatesToIsoStrings(v);
+    }
+  }
+  return value;
+}
+
+function dateToIsoYmd(d: Date): string {
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}

package/dist/element-envelope.d.ts

@@ -1,15 +0,0 @@
-import type { ValidationError } from './validation-types.js';
-export interface EnvelopeOptions {
-    /** Fixed `notation:` tag — lowercased TYPE short name (e.g. `factor`). */
-    notation: string;
-    /** Required `id:` TYPE prefix (e.g. `FACTOR`). */
-    idType: string;
-    /** Error code used for every envelope failure (e.g. `FACTOR-001`). */
-    code: string;
-}
-export interface EnvelopeResult {
-    /** The input narrowed to a record on success; `null` when the input is not a mapping. */
-    record: Record<string, unknown> | null;
-    errors: ValidationError[];
-}
-export declare function validateElementEnvelope(input: unknown, opts: EnvelopeOptions): EnvelopeResult;

package/dist/element-envelope.js

@@ -1,55 +0,0 @@
-// Shared §3 envelope validator for standalone element primitives.
-//
-// Every standalone element file in the methodology canon carries the same
-// envelope: a fixed `notation` tag, a canonical `id` whose TYPE prefix matches
-// the element TYPE, `name`, an admission record (`zone`/`admitted_at`/
-// `admitted_by`/`gate_checks`), and a primitive lifecycle
-// (`valid_from`/`valid_to`). Per-TYPE fields (§7) sit between.
-//
-// Each per-TYPE validator delegates envelope checks here so the §3 rule lives
-// in one place; per-TYPE fields (subtype enums, cross-references) are checked
-// in the TYPE's own validator. The error `code` is parameterised so an
-// envelope failure surfaces under the TYPE's own code (e.g. `FACTOR-001`,
-// `CHANGE-001`), preserving per-TYPE attribution.
-import { isCanonicalIdOfType } from './typed-id.js';
-export function validateElementEnvelope(input, opts) {
-    const errors = [];
-    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
-        errors.push({ code: opts.code, message: `${opts.idType} must be a YAML mapping.` });
-        return { record: null, errors };
-    }
-    const r = input;
-    if (r.notation !== opts.notation) {
-        errors.push({
-            code: opts.code,
-            message: `notation must be the fixed value "${opts.notation}".`,
-            path: 'notation',
-        });
-    }
-    if (!isCanonicalIdOfType(r.id, opts.idType)) {
-        errors.push({
-            code: opts.code,
-            message: `id "${String(r.id)}" must match ${opts.idType}-[<middle>-]<INTEGER>.`,
-            path: 'id',
-        });
-    }
-    for (const f of ['name', 'admitted_at', 'admitted_by', 'valid_from']) {
-        if (typeof r[f] !== 'string' || r[f].trim() === '') {
-            errors.push({ code: opts.code, message: `${f} is required.`, path: f });
-        }
-    }
-    if (r.zone !== 'canon') {
-        errors.push({ code: opts.code, message: 'zone is required and must be "canon".', path: 'zone' });
-    }
-    if (r.gate_checks === null || typeof r.gate_checks !== 'object' || Array.isArray(r.gate_checks)) {
-        errors.push({ code: opts.code, message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
-    }
-    if (!('valid_to' in r) || !(typeof r.valid_to === 'string' || r.valid_to === null)) {
-        errors.push({
-            code: opts.code,
-            message: 'valid_to is required (an ISO date string or null).',
-            path: 'valid_to',
-        });
-    }
-    return { record: r, errors };
-}

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

@@ -1,62 +0,0 @@
-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

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

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

@@ -1,82 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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

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

package/dist/issues/layout.d.ts

@@ -1,10 +0,0 @@
-import type { IssuesFile, IssuesLayout, IssuesLayoutOptions } from './types.js';
-/**
- * Lays an Issues document out as a nested outline: one row per issue, in
- * pre-order, with x indented by nesting depth and y stacked top-to-bottom.
- *
- * Robust to malformed input — a broken `parent` reference is treated as a
- * root, and a `parent` cycle cannot stack-overflow or drop nodes (a
- * `placed` guard ensures every issue is laid out exactly once).
- */
-export declare function layoutIssues(file: IssuesFile, options?: IssuesLayoutOptions): IssuesLayout;

package/dist/issues/layout.js

@@ -1,82 +0,0 @@
-const DEFAULTS = {
-    rowHeight: 44,
-    rowGap: 10,
-    indentWidth: 32,
-    nodeWidth: 460,
-    paddingX: 0,
-    paddingY: 0,
-};
-/**
- * Lays an Issues document out as a nested outline: one row per issue, in
- * pre-order, with x indented by nesting depth and y stacked top-to-bottom.
- *
- * Robust to malformed input — a broken `parent` reference is treated as a
- * root, and a `parent` cycle cannot stack-overflow or drop nodes (a
- * `placed` guard ensures every issue is laid out exactly once).
- */
-export function layoutIssues(file, options = {}) {
-    const o = { ...DEFAULTS, ...options };
-    const issues = file?.issues_catalogue?.issues ?? [];
-    const byId = new Map();
-    for (const it of issues) {
-        if (it && typeof it.issue_id === 'string')
-            byId.set(it.issue_id, it);
-    }
-    const childrenOf = new Map();
-    const roots = [];
-    for (const it of issues) {
-        if (!it || typeof it.issue_id !== 'string')
-            continue;
-        const parent = it.parent;
-        if (typeof parent === 'string' && byId.has(parent) && parent !== it.issue_id) {
-            const arr = childrenOf.get(parent) ?? [];
-            arr.push(it.issue_id);
-            childrenOf.set(parent, arr);
-        }
-        else {
-            roots.push(it.issue_id);
-        }
-    }
-    const rows = [];
-    const placed = new Set();
-    let y = o.paddingY;
-    function place(id, depth) {
-        if (placed.has(id))
-            return; // cycle / duplicate guard
-        const issue = byId.get(id);
-        if (!issue)
-            return;
-        placed.add(id);
-        const kids = childrenOf.get(id) ?? [];
-        rows.push({
-            issue_id: id,
-            depth,
-            x: o.paddingX + depth * o.indentWidth,
-            y,
-            width: o.nodeWidth,
-            height: o.rowHeight,
-            data: issue,
-            hasChildren: kids.length > 0,
-        });
-        y += o.rowHeight + o.rowGap;
-        for (const childId of kids)
-            place(childId, depth + 1);
-    }
-    for (const rootId of roots)
-        place(rootId, 0);
-    // Any issue not reached above (e.g. trapped inside a parent cycle) is
-    // still laid out, at the root level, so nothing silently disappears.
-    for (const it of issues) {
-        if (it && typeof it.issue_id === 'string' && !placed.has(it.issue_id)) {
-            place(it.issue_id, 0);
-        }
-    }
-    if (rows.length === 0) {
-        return { rows: [], bounds: { x: 0, y: 0, width: 0, height: 0 } };
-    }
-    const minX = Math.min(...rows.map((r) => r.x));
-    const minY = Math.min(...rows.map((r) => r.y));
-    const maxX = Math.max(...rows.map((r) => r.x + r.width));
-    const maxY = Math.max(...rows.map((r) => r.y + r.height));
-    return { rows, bounds: { x: minX, y: minY, width: maxX - minX, height: maxY - minY } };
-}

package/dist/issues/types.d.ts

@@ -1,61 +0,0 @@
-/**
- * Issues notation — a text-native register of issues (problems, defects,
- * open questions) with parent/child nesting. See methodology spec
- * `notations/12-issues.md`.
- */
-export type IssueStatus = 'open' | 'in_progress' | 'blocked' | 'resolved' | 'closed';
-export interface Issue {
-    issue_id: string;
-    name: string;
-    status: IssueStatus;
-    /** issue_id of the parent issue — the nesting mechanism. */
-    parent?: string;
-    description?: string;
-    /** Typed IDs of ACTIVITY / GOAL elements this issue concerns. */
-    relates_to?: string[];
-    /** ROLE element ID of the role accountable for the issue. */
-    owner_role?: string;
-}
-export interface IssuesCatalogue {
-    id: string;
-    name: string;
-    description?: string;
-    version?: string;
-    updated_at: string;
-    issues: Issue[];
-}
-export interface IssuesFile {
-    notation: string;
-    spec_version?: string;
-    issues_catalogue: IssuesCatalogue;
-}
-export interface IssuesLayoutOptions {
-    rowHeight?: number;
-    rowGap?: number;
-    indentWidth?: number;
-    nodeWidth?: number;
-    paddingX?: number;
-    paddingY?: number;
-}
-export interface LaidOutIssue {
-    issue_id: string;
-    /** 0 for a root issue, +1 per nesting level. */
-    depth: number;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    data: Issue;
-    hasChildren: boolean;
-}
-export interface IssuesLayoutBounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-export interface IssuesLayout {
-    rows: LaidOutIssue[];
-    bounds: IssuesLayoutBounds;
-}
-export type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';

package/dist/issues/types.js

@@ -1,6 +0,0 @@
-/**
- * Issues notation — a text-native register of issues (problems, defects,
- * open questions) with parent/child nesting. See methodology spec
- * `notations/12-issues.md`.
- */
-export {};

package/dist/issues/validate.d.ts

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

package/dist/issues/validate.js

@@ -1,143 +0,0 @@
-/**
- * Validates an Issues document against `notations/12-issues.md`.
- *
- * Error codes:
- *  - ISS-000  structural / header problem (not an object, wrong notation,
- *             missing issues_catalogue, missing catalogue fields)
- *  - ISS-001  duplicate issue_id
- *  - ISS-002  status outside the vocabulary
- *  - ISS-003  issue_id or name missing or empty
- *  - ISS-004  parent references a missing issue (warning)
- *  - ISS-005  cycle in the parent chain
- *  - ISS-006  relates_to entry is not an ACTIVITY- / GOAL- id
- */
-const STATUS_VALUES = ['open', 'in_progress', 'blocked', 'resolved', 'closed'];
-const RELATES_TO_RE = /^(ACTIVITY|GOAL)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
-function isNonEmptyString(v) {
-    return typeof v === 'string' && v.trim().length > 0;
-}
-export function validateIssues(input) {
-    const errors = [];
-    const warnings = [];
-    if (!input || typeof input !== 'object') {
-        return { valid: false, errors: [{ code: 'ISS-000', message: 'Input must be an object' }], warnings };
-    }
-    const raw = input;
-    if ('notation' in raw && raw['notation'] !== 'issues') {
-        errors.push({ code: 'ISS-000', message: `notation must be "issues", got "${String(raw['notation'])}"` });
-    }
-    const catRaw = raw['issues_catalogue'];
-    if (!catRaw || typeof catRaw !== 'object') {
-        errors.push({ code: 'ISS-000', message: 'Missing required root key: issues_catalogue' });
-        return { valid: false, errors, warnings };
-    }
-    const cat = catRaw;
-    if (!isNonEmptyString(cat['id'])) {
-        errors.push({ code: 'ISS-000', message: 'issues_catalogue.id is required', path: 'issues_catalogue.id' });
-    }
-    if (!isNonEmptyString(cat['name'])) {
-        errors.push({ code: 'ISS-000', message: 'issues_catalogue.name is required', path: 'issues_catalogue.name' });
-    }
-    if (!isNonEmptyString(cat['updated_at'])) {
-        errors.push({ code: 'ISS-000', message: 'issues_catalogue.updated_at is required', path: 'issues_catalogue.updated_at' });
-    }
-    const issuesRaw = cat['issues'];
-    if (!Array.isArray(issuesRaw)) {
-        errors.push({ code: 'ISS-000', message: 'issues_catalogue.issues must be an array', path: 'issues_catalogue.issues' });
-        return { valid: false, errors, warnings };
-    }
-    const idSet = new Set();
-    for (let i = 0; i < issuesRaw.length; i++) {
-        const it = issuesRaw[i];
-        const path = `issues_catalogue.issues[${i}]`;
-        if (!it || typeof it !== 'object') {
-            errors.push({ code: 'ISS-003', message: `${path} must be an object`, path });
-            continue;
-        }
-        const issue = it;
-        const idOk = isNonEmptyString(issue['issue_id']);
-        if (!idOk) {
-            errors.push({ code: 'ISS-003', message: `${path}.issue_id is missing or empty`, path });
-        }
-        if (!isNonEmptyString(issue['name'])) {
-            errors.push({ code: 'ISS-003', message: `${path}.name is missing or empty`, path });
-        }
-        if (idOk) {
-            const id = issue['issue_id'].trim();
-            if (idSet.has(id)) {
-                errors.push({ code: 'ISS-001', message: `Duplicate issue_id: "${id}"`, path });
-            }
-            else {
-                idSet.add(id);
-            }
-        }
-        const status = issue['status'];
-        if (!STATUS_VALUES.includes(status)) {
-            errors.push({
-                code: 'ISS-002',
-                message: `${path}.status "${String(status)}" must be one of: ${STATUS_VALUES.join(', ')}`,
-                path,
-            });
-        }
-        const relates = issue['relates_to'];
-        if (relates !== undefined) {
-            if (!Array.isArray(relates)) {
-                errors.push({ code: 'ISS-006', message: `${path}.relates_to must be an array`, path });
-            }
-            else {
-                for (let j = 0; j < relates.length; j++) {
-                    const ref = relates[j];
-                    if (typeof ref !== 'string' || !RELATES_TO_RE.test(ref)) {
-                        errors.push({
-                            code: 'ISS-006',
-                            message: `${path}.relates_to[${j}] "${String(ref)}" must be an ACTIVITY- or GOAL- id`,
-                            path,
-                        });
-                    }
-                }
-            }
-        }
-    }
-    // parent reference + cycle checks — run once all ids are collected.
-    const parentOf = new Map();
-    for (let i = 0; i < issuesRaw.length; i++) {
-        const it = issuesRaw[i];
-        if (!it || typeof it !== 'object')
-            continue;
-        const issue = it;
-        const parent = issue['parent'];
-        const path = `issues_catalogue.issues[${i}]`;
-        if (parent === undefined)
-            continue;
-        if (typeof parent !== 'string' || !idSet.has(parent.trim())) {
-            warnings.push({
-                code: 'ISS-004',
-                message: `${path}.parent "${String(parent)}" does not resolve to a known issue — rendered at the root`,
-                path,
-            });
-            continue;
-        }
-        if (isNonEmptyString(issue['issue_id'])) {
-            parentOf.set(issue['issue_id'].trim(), parent.trim());
-        }
-    }
-    let cycleNode;
-    for (const start of parentOf.keys()) {
-        if (cycleNode)
-            break;
-        const seen = new Set();
-        let cur = start;
-        while (cur !== undefined) {
-            if (seen.has(cur)) {
-                cycleNode = cur;
-                break;
-            }
-            seen.add(cur);
-            cur = parentOf.get(cur);
-        }
-    }
-    if (cycleNode) {
-        errors.push({ code: 'ISS-005', message: `Cycle detected in the parent chain involving issue "${cycleNode}"` });
-    }
-    return { valid: errors.length === 0, errors, warnings };
-}