@transitrix/diagrams 1.0.0

package/dist/process-blueprint/__tests__/layout.test.js

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import { layoutProcessBlueprint } from '../layout.js';
+function build(file) {
+    return {
+        notation: 'process-blueprint',
+        process_blueprint: {
+            id: 'PROCESS_BLUEPRINT-T-1',
+            name: 'Test',
+            stages: [],
+            ...file,
+        },
+    };
+}
+describe('layoutProcessBlueprint', () => {
+    it('lays out stage headers in input order across the legend offset', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [
+                { id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' },
+                { id: 'STAGE-2', name: 'B', goal: 'g', result: 'r' },
+                { id: 'STAGE-3', name: 'C', goal: 'g', result: 'r' },
+            ],
+        }));
+        expect(layout.stageHeaders).toHaveLength(3);
+        expect(layout.stageHeaders[0].x).toBe(layout.legendColumnWidth);
+        expect(layout.stageHeaders[1].x).toBe(layout.legendColumnWidth + layout.stageColumnWidth);
+        expect(layout.stageHeaders[2].x).toBe(layout.legendColumnWidth + 2 * layout.stageColumnWidth);
+        expect(layout.stageHeaders[0].name).toBe('A');
+    });
+    it('produces goal and result cells aligned under each stage column', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [
+                { id: 'STAGE-1', name: 'A', goal: 'gA', result: 'rA' },
+                { id: 'STAGE-2', name: 'B', goal: 'gB', result: 'rB' },
+            ],
+        }));
+        expect(layout.goalCells.map(c => c.text)).toEqual(['gA', 'gB']);
+        expect(layout.resultCells.map(c => c.text)).toEqual(['rA', 'rB']);
+        expect(layout.goalCells[0].y).toBeLessThan(layout.resultCells[0].y);
+        expect(layout.goalCells[0].x).toBe(layout.stageHeaders[0].x);
+    });
+    it('omits aspect rows for categories without any entries', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [{ id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' }],
+        }));
+        expect(layout.aspectRows).toHaveLength(0);
+    });
+    it('merges consecutive stages into a single spanning pill', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [
+                { id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' },
+                { id: 'STAGE-2', name: 'B', goal: 'g', result: 'r' },
+                { id: 'STAGE-3', name: 'C', goal: 'g', result: 'r' },
+            ],
+            systems: [
+                { id: 'APPLICATION-OMS-1', name: 'OMS', stages: ['STAGE-1', 'STAGE-2', 'STAGE-3'] },
+            ],
+        }));
+        expect(layout.aspectRows).toHaveLength(1);
+        const row = layout.aspectRows[0];
+        expect(row.category).toBe('systems');
+        expect(row.pills).toHaveLength(1);
+        expect(row.pills[0].startStageIndex).toBe(0);
+        expect(row.pills[0].endStageIndex).toBe(2);
+        expect(row.pills[0].width).toBeGreaterThan(layout.stageColumnWidth);
+    });
+    it('splits non-consecutive stages into separate pills', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [
+                { id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' },
+                { id: 'STAGE-2', name: 'B', goal: 'g', result: 'r' },
+                { id: 'STAGE-3', name: 'C', goal: 'g', result: 'r' },
+                { id: 'STAGE-4', name: 'D', goal: 'g', result: 'r' },
+            ],
+            systems: [
+                { id: 'APPLICATION-X-1', name: 'X', stages: ['STAGE-1', 'STAGE-3', 'STAGE-4'] },
+            ],
+        }));
+        const pills = layout.aspectRows[0].pills;
+        expect(pills).toHaveLength(2);
+        expect(pills[0].startStageIndex).toBe(0);
+        expect(pills[0].endStageIndex).toBe(0);
+        expect(pills[1].startStageIndex).toBe(2);
+        expect(pills[1].endStageIndex).toBe(3);
+    });
+    it('stacks overlapping pills into vertical slots inside the same row', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [
+                { id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' },
+                { id: 'STAGE-2', name: 'B', goal: 'g', result: 'r' },
+            ],
+            systems: [
+                { id: 'APPLICATION-A-1', name: 'A', stages: ['STAGE-1', 'STAGE-2'] },
+                { id: 'APPLICATION-B-1', name: 'B', stages: ['STAGE-1'] },
+            ],
+        }));
+        const row = layout.aspectRows[0];
+        expect(row.pills).toHaveLength(2);
+        // The two pills overlap at STAGE-1, so they should sit at different y.
+        expect(row.pills[0].y).not.toBe(row.pills[1].y);
+        // Row height must be tall enough for two stacked pills.
+        expect(row.height).toBeGreaterThan(row.pills[0].height);
+    });
+    it('preserves the fixed category order: systems, actors, equipment, information_entities', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [{ id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' }],
+            information_entities: [{ name: 'Doc', stages: ['STAGE-1'] }],
+            actors: [{ id: 'ROLE-X-1', name: 'X', stages: ['STAGE-1'] }],
+            systems: [{ id: 'APPLICATION-X-1', name: 'X', stages: ['STAGE-1'] }],
+            equipment: [{ name: 'Scanner', stages: ['STAGE-1'] }],
+        }));
+        expect(layout.aspectRows.map(r => r.category)).toEqual([
+            'systems',
+            'actors',
+            'equipment',
+            'information_entities',
+        ]);
+    });
+    it('builds the legend in row order: goal, result, then aspect categories', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [{ id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' }],
+            systems: [{ id: 'APPLICATION-X-1', name: 'X', stages: ['STAGE-1'] }],
+        }));
+        expect(layout.legend.map(l => l.kind)).toEqual(['goal', 'result', 'aspect']);
+        expect(layout.legend[2].category).toBe('systems');
+    });
+    it('total bounds cover the legend column plus every stage column', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [
+                { id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' },
+                { id: 'STAGE-2', name: 'B', goal: 'g', result: 'r' },
+            ],
+        }));
+        expect(layout.bounds.width).toBe(layout.legendColumnWidth + 2 * layout.stageColumnWidth);
+        expect(layout.bounds.height).toBeGreaterThan(0);
+    });
+    it('ignores aspect entries that reference undeclared stages', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [{ id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' }],
+            systems: [
+                { id: 'APPLICATION-X-1', name: 'X', stages: ['STAGE-1', 'STAGE-999'] },
+            ],
+        }));
+        const pills = layout.aspectRows[0].pills;
+        expect(pills).toHaveLength(1);
+        expect(pills[0].startStageIndex).toBe(0);
+        expect(pills[0].endStageIndex).toBe(0);
+    });
+    it('honours overridden LayoutOptions', () => {
+        const layout = layoutProcessBlueprint(build({
+            stages: [
+                { id: 'STAGE-1', name: 'A', goal: 'g', result: 'r' },
+                { id: 'STAGE-2', name: 'B', goal: 'g', result: 'r' },
+            ],
+        }), { legendColumnWidth: 200, stageColumnWidth: 300 });
+        expect(layout.legendColumnWidth).toBe(200);
+        expect(layout.stageColumnWidth).toBe(300);
+        expect(layout.stageHeaders[1].x).toBe(200 + 300);
+    });
+});

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

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

package/dist/process-blueprint/__tests__/validate.test.js

@@ -0,0 +1,280 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { validateProcessBlueprint } from '../validate.js';
+const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'process-blueprint');
+const VALID_BLUEPRINT = {
+    notation: 'process-blueprint',
+    spec_version: '0.1',
+    process_blueprint: {
+        id: 'PROCESS_BLUEPRINT-FULFIL-1',
+        name: 'Order fulfilment blueprint',
+        stages: [
+            { id: 'STAGE-1', name: 'Receive', goal: 'Capture order', result: 'Validated order' },
+            { id: 'STAGE-2', name: 'Pack', goal: 'Assemble', result: 'Packed shipment' },
+            { id: 'STAGE-3', name: 'Ship', goal: 'Hand to carrier', result: 'In transit' },
+        ],
+        systems: [
+            { id: 'APPLICATION-OMS-1', name: 'OMS', stages: ['STAGE-1', 'STAGE-2', 'STAGE-3'] },
+        ],
+        actors: [
+            { id: 'ROLE-WAREHOUSE-1', name: 'Warehouse op', stages: ['STAGE-2', 'STAGE-3'] },
+        ],
+        equipment: [
+            { name: 'Barcode scanner', stages: ['STAGE-2', 'STAGE-3'] },
+        ],
+        information_entities: [
+            { name: 'Customer order', stages: ['STAGE-1', 'STAGE-2', 'STAGE-3'] },
+        ],
+    },
+};
+describe('validateProcessBlueprint', () => {
+    it('passes on a valid blueprint', () => {
+        const r = validateProcessBlueprint(VALID_BLUEPRINT);
+        expect(r.valid).toBe(true);
+        expect(r.errors).toHaveLength(0);
+    });
+    it('BP-001: rejects non-object input', () => {
+        expect(validateProcessBlueprint(null).valid).toBe(false);
+        expect(validateProcessBlueprint(null).errors[0].code).toBe('BP-001');
+        expect(validateProcessBlueprint('string').errors[0].code).toBe('BP-001');
+    });
+    it('BP-001: rejects missing process_blueprint root key', () => {
+        const r = validateProcessBlueprint({ notation: 'process-blueprint' });
+        expect(r.errors.some(e => e.code === 'BP-001')).toBe(true);
+    });
+    it('BP-001: rejects wrong notation value', () => {
+        const r = validateProcessBlueprint({ ...VALID_BLUEPRINT, notation: 'goals' });
+        expect(r.errors.some(e => e.code === 'BP-001')).toBe(true);
+    });
+    it('BP-001: tolerates a missing notation field (header check is contract-level)', () => {
+        const { notation: _, ...rest } = VALID_BLUEPRINT;
+        const r = validateProcessBlueprint(rest);
+        expect(r.errors.some(e => e.code === 'BP-001')).toBe(false);
+    });
+    it('BP-002: rejects missing id', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: { ...VALID_BLUEPRINT.process_blueprint, id: '' },
+        });
+        expect(r.errors.some(e => e.code === 'BP-002')).toBe(true);
+    });
+    it('BP-002: rejects id that does not match PROCESS_BLUEPRINT grammar', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: { ...VALID_BLUEPRINT.process_blueprint, id: 'PB-1' },
+        });
+        expect(r.errors.some(e => e.code === 'BP-002')).toBe(true);
+    });
+    it('BP-003: rejects missing name', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: { ...VALID_BLUEPRINT.process_blueprint, name: '' },
+        });
+        expect(r.errors.some(e => e.code === 'BP-003')).toBe(true);
+    });
+    it('BP-004: rejects missing stages', () => {
+        const { stages: _, ...rest } = VALID_BLUEPRINT.process_blueprint;
+        const r = validateProcessBlueprint({ ...VALID_BLUEPRINT, process_blueprint: rest });
+        expect(r.errors.some(e => e.code === 'BP-004')).toBe(true);
+    });
+    it('BP-004: rejects empty stages array', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: { ...VALID_BLUEPRINT.process_blueprint, stages: [] },
+        });
+        expect(r.errors.some(e => e.code === 'BP-004')).toBe(true);
+    });
+    it('BP-005: rejects stage missing goal', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                stages: [{ id: 'STAGE-1', name: 'X', goal: '', result: 'R' }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-005' && /goal/.test(e.message))).toBe(true);
+    });
+    it('BP-005: rejects stage missing result', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                stages: [{ id: 'STAGE-1', name: 'X', goal: 'G', result: '' }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-005' && /result/.test(e.message))).toBe(true);
+    });
+    it('BP-006: rejects duplicate stage ids', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                stages: [
+                    { id: 'STAGE-1', name: 'A', goal: 'G', result: 'R' },
+                    { id: 'STAGE-1', name: 'B', goal: 'G', result: 'R' },
+                ],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-006' && /Duplicate/.test(e.message))).toBe(true);
+    });
+    it('BP-006: treats ids that differ only in surrounding whitespace as duplicates', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                stages: [
+                    { id: 'STAGE-1', name: 'A', goal: 'G', result: 'R' },
+                    { id: 'STAGE-1 ', name: 'B', goal: 'G', result: 'R' },
+                ],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-006' && /Duplicate/.test(e.message))).toBe(true);
+    });
+    it('BP-008: tolerates whitespace around aspect stage refs (matches trimmed stage ids)', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                stages: [{ id: 'STAGE-1', name: 'A', goal: 'G', result: 'R' }],
+                systems: [{ id: 'APPLICATION-X-1', name: 'X', stages: [' STAGE-1 '] }],
+                actors: undefined,
+                equipment: undefined,
+                information_entities: undefined,
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-008')).toBe(false);
+    });
+    it('BP-006: rejects stage id that does not match STAGE grammar', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                stages: [{ id: 'STG-1', name: 'A', goal: 'G', result: 'R' }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-006')).toBe(true);
+    });
+    it('BP-007: rejects aspect entry missing name', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                systems: [{ name: '', stages: ['STAGE-1'] }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-007' && /name/.test(e.message))).toBe(true);
+    });
+    it('BP-007: rejects aspect entry with empty stages array', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                systems: [{ name: 'X', stages: [] }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-007' && /stages/.test(e.message))).toBe(true);
+    });
+    it('BP-008: rejects aspect entry referencing undeclared stage', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                systems: [{ name: 'X', stages: ['STAGE-1', 'STAGE-999'] }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-008')).toBe(true);
+    });
+    it('BP-009: rejects aspect entry id that does not match canonical grammar', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                equipment: [{ id: 'lowercase-1', name: 'X', stages: ['STAGE-1'] }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-009')).toBe(true);
+    });
+    it('BP-009: accepts an id for equipment as long as it matches general grammar', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                equipment: [{ id: 'EQUIPMENT-SCANNER-1', name: 'Barcode scanner', stages: ['STAGE-2'] }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-009')).toBe(false);
+        expect(r.errors.some(e => e.code === 'BP-010')).toBe(false);
+    });
+    it('BP-010: rejects systems entry id without APPLICATION- prefix', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                systems: [{ id: 'SERVICE-OMS-1', name: 'OMS', stages: ['STAGE-1'] }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-010')).toBe(true);
+    });
+    it('BP-010: rejects actors entry id without ROLE- prefix', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                actors: [{ id: 'PERSON-1', name: 'X', stages: ['STAGE-1'] }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-010')).toBe(true);
+    });
+    it('BP-010: accepts free-form aspect entries without id', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                systems: [{ name: 'Legacy app', stages: ['STAGE-1'] }],
+            },
+        });
+        expect(r.errors.some(e => e.code === 'BP-009')).toBe(false);
+        expect(r.errors.some(e => e.code === 'BP-010')).toBe(false);
+    });
+    it('BP-011: warns when a stage has no aspect entries pointing at it', () => {
+        const r = validateProcessBlueprint({
+            ...VALID_BLUEPRINT,
+            process_blueprint: {
+                ...VALID_BLUEPRINT.process_blueprint,
+                stages: [
+                    { id: 'STAGE-1', name: 'A', goal: 'G', result: 'R' },
+                    { id: 'STAGE-99', name: 'Orphan', goal: 'G', result: 'R' },
+                ],
+                systems: [{ id: 'APPLICATION-OMS-1', name: 'OMS', stages: ['STAGE-1'] }],
+                actors: undefined,
+                equipment: undefined,
+                information_entities: undefined,
+            },
+        });
+        expect(r.warnings.some(w => w.code === 'BP-011' && /STAGE-99/.test(w.message))).toBe(true);
+        expect(r.valid).toBe(true);
+    });
+    // BP-012 was removed from the spec on 2026-05-21 (methodology PR #15):
+    // a single-stage aspect entry is normal, valid blueprint content and the
+    // warning fired on the common case. Studio side dropped to match.
+    it('happy path: surfaces no warnings on a well-formed multi-stage blueprint', () => {
+        const r = validateProcessBlueprint(VALID_BLUEPRINT);
+        expect(r.valid).toBe(true);
+        expect(r.warnings).toHaveLength(0);
+    });
+});
+describe('process-blueprint 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/process-blueprint/${file}`, () => {
+            const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+            const parsed = yaml.load(text);
+            const r = validateProcessBlueprint(parsed);
+            expect(r.errors).toEqual([]);
+            expect(r.valid).toBe(true);
+        });
+    }
+});

package/dist/process-blueprint/index.d.ts

@@ -0,0 +1,4 @@
+export type { AspectCategory, Stage, AspectEntry, LaneConfig, ProcessBlueprintHeader, ProcessBlueprintFile, ProcessBlueprintLayoutOptions, LegendCell, StageHeaderCell, StageTextCell, AspectPill, AspectRow, ProcessBlueprintLayout, ComplianceDecoration, ComplianceChip, ComplianceRow, ComplianceLaneConfig, ComplianceLaneAssertion, ComplianceLaneRequirement, ComplianceLaneInput, } from './types.js';
+export { validateProcessBlueprint } from './validate.js';
+export type { ValidationError as ProcessBlueprintValidationError, ValidationWarning as ProcessBlueprintValidationWarning, ValidationResult as ProcessBlueprintValidationResult, } from './validate.js';
+export { layoutProcessBlueprint } from './layout.js';

package/dist/process-blueprint/index.js

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

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

@@ -0,0 +1,2 @@
+import type { ProcessBlueprintLayoutOptions, ProcessBlueprintFile, ProcessBlueprintLayout } from './types.js';
+export declare function layoutProcessBlueprint(file: ProcessBlueprintFile, options?: ProcessBlueprintLayoutOptions): ProcessBlueprintLayout;