@transitrix/diagrams 1.0.0

package/dist/issues/layout.d.ts

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

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

@@ -0,0 +1,61 @@
+/**
+ * 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

@@ -0,0 +1,6 @@
+/**
+ * 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

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

@@ -0,0 +1,143 @@
+/**
+ * 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 };
+}

package/dist/process-blueprint/__tests__/compliance-lane.test.d.ts

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

package/dist/process-blueprint/__tests__/compliance-lane.test.js

@@ -0,0 +1,272 @@
+import { describe, it, expect } from 'vitest';
+import { layoutProcessBlueprint } from '../layout.js';
+// ── fixtures ────────────────────────────────────────────────────────────────
+const STAGES = [
+    { id: 'STAGE-1', name: 'Receive', goal: 'g1', result: 'r1' },
+    { id: 'STAGE-2', name: 'Process', goal: 'g2', result: 'r2' },
+    { id: 'STAGE-3', name: 'Ship', goal: 'g3', result: 'r3' },
+];
+function buildFile(overrides = {}) {
+    return {
+        notation: 'process-blueprint',
+        process_blueprint: { id: 'PROCESS_BLUEPRINT-T-1', name: 'Test', stages: STAGES, ...overrides },
+    };
+}
+const REQ_A = { id: 'REQ-1', derived_from: ['LAW-GDPR-1'] };
+const REQ_B = { id: 'REQ-2', derived_from: ['LAW-GDPR-1', 'LAW-SOX-2'] };
+const REQ_DEADLINE = {
+    id: 'REQ-3',
+    derived_from: ['LAW-PCI-3'],
+    deadline: '2020-01-01', // past_due
+};
+// ── helpers ─────────────────────────────────────────────────────────────────
+function makeAssertion(about, status, realisedVia) {
+    return { about, status, realised_via: realisedVia };
+}
+function layout(file, input, overrides = {}) {
+    return layoutProcessBlueprint(file, {
+        complianceLane: { enabled: true, ...overrides },
+        complianceInput: input,
+    });
+}
+// ── tests ───────────────────────────────────────────────────────────────────
+describe('compliance lane derivation', () => {
+    it('returns no complianceRow when lane is disabled (default)', () => {
+        const l = layoutProcessBlueprint(buildFile(), {});
+        expect(l.complianceRow).toBeUndefined();
+    });
+    it('returns no complianceRow when enabled but no input provided', () => {
+        const l = layoutProcessBlueprint(buildFile(), { complianceLane: { enabled: true } });
+        expect(l.complianceRow).toBeUndefined();
+    });
+    it('returns no complianceRow when assertions have no realised_via matching stage IDs', () => {
+        const input = {
+            assertions: [makeAssertion('REQ-1', 'compliant', ['STEP-99'])],
+            requirements: [REQ_A],
+        };
+        const l = layout(buildFile(), input);
+        expect(l.complianceRow).toBeUndefined();
+    });
+    it('derives a chip for each law-stage pair', () => {
+        const input = {
+            assertions: [makeAssertion('REQ-1', 'compliant', ['STAGE-1'])],
+            requirements: [REQ_A],
+        };
+        const l = layout(buildFile(), input);
+        expect(l.complianceRow).toBeDefined();
+        const chips = l.complianceRow.chips;
+        expect(chips).toHaveLength(1);
+        expect(chips[0].lawId).toBe('LAW-GDPR-1');
+        expect(chips[0].stageIndex).toBe(0);
+    });
+    it('produces one chip per law per stage (same law, two stages → two chips)', () => {
+        const input = {
+            assertions: [makeAssertion('REQ-1', 'compliant', ['STAGE-1', 'STAGE-2'])],
+            requirements: [REQ_A],
+        };
+        const l = layout(buildFile(), input);
+        const chips = l.complianceRow.chips;
+        expect(chips).toHaveLength(2);
+        expect(chips.map(c => c.stageIndex).sort()).toEqual([0, 1]);
+        expect(chips.every(c => c.lawId === 'LAW-GDPR-1')).toBe(true);
+    });
+    it('merges multiple assertions for the same law-stage into one chip', () => {
+        const input = {
+            assertions: [
+                makeAssertion('REQ-1', 'compliant', ['STAGE-1']),
+                makeAssertion('REQ-1', 'partial', ['STAGE-1']),
+            ],
+            requirements: [REQ_A],
+        };
+        const l = layout(buildFile(), input);
+        expect(l.complianceRow.chips).toHaveLength(1);
+    });
+    describe('decoration: new', () => {
+        it('marks chip as new when law is not in previous snapshot', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-1', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input, { previousSnapshot: { 'STAGE-1': [] } });
+            expect(l.complianceRow.chips[0].decorations).toContain('new');
+        });
+        it('does not mark chip as new when law is in previous snapshot', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-1', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input, { previousSnapshot: { 'STAGE-1': ['LAW-GDPR-1'] } });
+            expect(l.complianceRow.chips[0].decorations).not.toContain('new');
+        });
+    });
+    describe('decoration: gap', () => {
+        it('marks chip as gap when assertion status is non_compliant', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-1', 'non_compliant', ['STAGE-1'])],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input);
+            expect(l.complianceRow.chips[0].decorations).toContain('gap');
+        });
+        it('marks chip as gap when assertion status is partial', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-1', 'partial', ['STAGE-2'])],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input);
+            expect(l.complianceRow.chips[0].decorations).toContain('gap');
+        });
+        it('does not mark chip as gap for compliant assertion', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-1', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input);
+            expect(l.complianceRow.chips[0].decorations).not.toContain('gap');
+        });
+        it('propagates gap if any assertion for the same law-stage is non-compliant', () => {
+            const input = {
+                assertions: [
+                    makeAssertion('REQ-1', 'compliant', ['STAGE-1']),
+                    makeAssertion('REQ-1', 'non_compliant', ['STAGE-1']),
+                ],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input);
+            expect(l.complianceRow.chips[0].decorations).toContain('gap');
+        });
+    });
+    describe('decoration: deadline', () => {
+        it('marks chip as deadline when gap exists and requirement deadline is past_due', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-3', 'non_compliant', ['STAGE-1'])],
+                requirements: [REQ_DEADLINE],
+            };
+            const l = layout(buildFile(), input);
+            const d = l.complianceRow.chips[0].decorations;
+            expect(d).toContain('gap');
+            expect(d).toContain('deadline');
+        });
+        it('does not mark deadline when gap is absent even if deadline is past_due', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-3', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_DEADLINE],
+            };
+            const l = layout(buildFile(), input);
+            expect(l.complianceRow.chips[0].decorations).not.toContain('deadline');
+        });
+        it('does not mark deadline when no deadline on requirement', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-1', 'non_compliant', ['STAGE-1'])],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input);
+            expect(l.complianceRow.chips[0].decorations).not.toContain('deadline');
+        });
+        it('all three decorations can stack on the same chip', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-3', 'non_compliant', ['STAGE-1'])],
+                requirements: [REQ_DEADLINE],
+            };
+            const l = layout(buildFile(), input, { previousSnapshot: { 'STAGE-1': [] } });
+            const d = l.complianceRow.chips[0].decorations;
+            expect(d).toContain('new');
+            expect(d).toContain('gap');
+            expect(d).toContain('deadline');
+        });
+    });
+    describe('jurisdiction filter', () => {
+        it('passes through all laws when no jurisdictions filter', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-2', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_B], // derived_from: [LAW-GDPR-1, LAW-SOX-2]
+                codexJurisdictions: { 'LAW-GDPR-1': 'EU', 'LAW-SOX-2': 'US' },
+            };
+            const l = layout(buildFile(), input, { jurisdictions: [] });
+            expect(l.complianceRow.chips).toHaveLength(2);
+        });
+        it('filters to only the selected jurisdictions', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-2', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_B],
+                codexJurisdictions: { 'LAW-GDPR-1': 'EU', 'LAW-SOX-2': 'US' },
+            };
+            const l = layout(buildFile(), input, { jurisdictions: ['EU'] });
+            expect(l.complianceRow.chips).toHaveLength(1);
+            expect(l.complianceRow.chips[0].lawId).toBe('LAW-GDPR-1');
+        });
+        it('returns no row when jurisdiction filter excludes all laws', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-2', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_B],
+                codexJurisdictions: { 'LAW-GDPR-1': 'EU', 'LAW-SOX-2': 'US' },
+            };
+            const l = layout(buildFile(), input, { jurisdictions: ['AU'] });
+            expect(l.complianceRow).toBeUndefined();
+        });
+    });
+    describe('null-guards', () => {
+        it('tolerates null assertion entries without throwing', () => {
+            const input = {
+                assertions: [null, makeAssertion('REQ-1', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_A],
+            };
+            expect(() => layout(buildFile(), input)).not.toThrow();
+        });
+        it('skips assertions with no realised_via', () => {
+            const input = {
+                assertions: [{ about: 'REQ-1', status: 'compliant' }],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input);
+            expect(l.complianceRow).toBeUndefined();
+        });
+        it('skips assertions whose requirement is not in the input', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-MISSING', 'non_compliant', ['STAGE-1'])],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input);
+            expect(l.complianceRow).toBeUndefined();
+        });
+    });
+    describe('legend', () => {
+        it('adds a compliance legend entry when the row is present', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-1', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input);
+            const complianceLegend = l.legend.find(entry => entry.kind === 'compliance');
+            expect(complianceLegend).toBeDefined();
+            expect(complianceLegend.label).toBe('Compliance');
+        });
+        it('does not add compliance legend when row is absent', () => {
+            const l = layoutProcessBlueprint(buildFile(), {});
+            expect(l.legend.some(e => e.kind === 'compliance')).toBe(false);
+        });
+    });
+    describe('layout geometry', () => {
+        it('total height grows by the compliance row height', () => {
+            const withoutLane = layoutProcessBlueprint(buildFile(), {});
+            const input = {
+                assertions: [makeAssertion('REQ-1', 'compliant', ['STAGE-1'])],
+                requirements: [REQ_A],
+            };
+            const withLane = layout(buildFile(), input);
+            expect(withLane.bounds.height).toBeGreaterThan(withoutLane.bounds.height);
+            expect(withLane.bounds.height).toBe(withoutLane.bounds.height + withLane.complianceRow.height);
+        });
+        it('chip x aligns to the stage column', () => {
+            const input = {
+                assertions: [makeAssertion('REQ-1', 'compliant', ['STAGE-2'])],
+                requirements: [REQ_A],
+            };
+            const l = layout(buildFile(), input);
+            const chip = l.complianceRow.chips[0];
+            // Chip x must be at the start of stage-2's column (index 1) + cellPadding.
+            const expectedX = l.legendColumnWidth + 1 * l.stageColumnWidth + 8; // default cellPadding = 8
+            expect(chip.x).toBe(expectedX);
+        });
+    });
+});

package/dist/process-blueprint/__tests__/layout.test.d.ts

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