@transitrix/diagrams 1.0.0

package/dist/process-blueprint/validate.js

@@ -0,0 +1,165 @@
+const ID_GRAMMAR_RE = /^[A-Z][A-Z_]*(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const PROCESS_BLUEPRINT_ID_RE = /^PROCESS_BLUEPRINT(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const STAGE_ID_RE = /^STAGE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const APPLICATION_ID_RE = /^APPLICATION(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const ROLE_ID_RE = /^ROLE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const ASPECT_CATEGORIES = ['systems', 'actors', 'equipment', 'information_entities'];
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+export function validateProcessBlueprint(input) {
+    const errors = [];
+    const warnings = [];
+    if (!input || typeof input !== 'object') {
+        return {
+            valid: false,
+            errors: [{ code: 'BP-001', message: 'Input must be an object' }],
+            warnings,
+        };
+    }
+    const raw = input;
+    if ('notation' in raw && raw['notation'] !== 'process-blueprint') {
+        errors.push({
+            code: 'BP-001',
+            message: `notation must be "process-blueprint", got "${String(raw['notation'])}"`,
+        });
+    }
+    if (!('process_blueprint' in raw) || !raw['process_blueprint'] || typeof raw['process_blueprint'] !== 'object') {
+        errors.push({ code: 'BP-001', message: 'Missing required root key: process_blueprint' });
+        return { valid: false, errors, warnings };
+    }
+    const pb = raw['process_blueprint'];
+    if (!isNonEmptyString(pb['id'])) {
+        errors.push({ code: 'BP-002', message: 'process_blueprint.id is required' });
+    }
+    else if (!PROCESS_BLUEPRINT_ID_RE.test(pb['id'])) {
+        errors.push({
+            code: 'BP-002',
+            message: `process_blueprint.id "${pb['id']}" must match PROCESS_BLUEPRINT-[<middle>-]<INTEGER>`,
+        });
+    }
+    if (!isNonEmptyString(pb['name'])) {
+        errors.push({ code: 'BP-003', message: 'process_blueprint.name is required' });
+    }
+    const stagesRaw = pb['stages'];
+    if (!Array.isArray(stagesRaw) || stagesRaw.length === 0) {
+        errors.push({ code: 'BP-004', message: 'process_blueprint.stages must be a non-empty array' });
+        return { valid: false, errors, warnings };
+    }
+    const stageIds = new Set();
+    for (let i = 0; i < stagesRaw.length; i++) {
+        const s = stagesRaw[i];
+        const path = `stages[${i}]`;
+        if (!s || typeof s !== 'object') {
+            errors.push({ code: 'BP-005', message: `${path} must be an object` });
+            continue;
+        }
+        if (!isNonEmptyString(s['id'])) {
+            errors.push({ code: 'BP-005', message: `${path}.id is required` });
+        }
+        else {
+            const sid = s['id'].trim();
+            if (stageIds.has(sid)) {
+                errors.push({ code: 'BP-006', message: `Duplicate stage id: "${sid}"` });
+            }
+            else {
+                stageIds.add(sid);
+            }
+            if (!STAGE_ID_RE.test(sid)) {
+                errors.push({
+                    code: 'BP-006',
+                    message: `${path}.id "${sid}" must match STAGE-[<middle>-]<INTEGER>`,
+                });
+            }
+        }
+        if (!isNonEmptyString(s['name'])) {
+            errors.push({ code: 'BP-005', message: `${path}.name is required` });
+        }
+        if (!isNonEmptyString(s['goal'])) {
+            errors.push({ code: 'BP-005', message: `${path}.goal is required` });
+        }
+        if (!isNonEmptyString(s['result'])) {
+            errors.push({ code: 'BP-005', message: `${path}.result is required` });
+        }
+    }
+    const usedStageIds = new Set();
+    for (const category of ASPECT_CATEGORIES) {
+        const arr = pb[category];
+        if (arr === undefined)
+            continue;
+        if (!Array.isArray(arr)) {
+            errors.push({ code: 'BP-007', message: `process_blueprint.${category} must be an array` });
+            continue;
+        }
+        for (let i = 0; i < arr.length; i++) {
+            const e = arr[i];
+            const path = `${category}[${i}]`;
+            if (!e || typeof e !== 'object') {
+                errors.push({ code: 'BP-007', message: `${path} must be an object` });
+                continue;
+            }
+            if (!isNonEmptyString(e['name'])) {
+                errors.push({ code: 'BP-007', message: `${path}.name is required` });
+            }
+            const entryStages = e['stages'];
+            if (!Array.isArray(entryStages) || entryStages.length === 0) {
+                errors.push({
+                    code: 'BP-007',
+                    message: `${path}.stages must be a non-empty array of STAGE-… ids`,
+                });
+            }
+            else {
+                for (let j = 0; j < entryStages.length; j++) {
+                    const ref = entryStages[j];
+                    if (typeof ref !== 'string') {
+                        errors.push({ code: 'BP-008', message: `${path}.stages[${j}] must be a string` });
+                        continue;
+                    }
+                    const refTrimmed = ref.trim();
+                    if (!stageIds.has(refTrimmed)) {
+                        errors.push({
+                            code: 'BP-008',
+                            message: `${path}.stages[${j}] references undeclared stage "${ref}"`,
+                        });
+                    }
+                    else {
+                        usedStageIds.add(refTrimmed);
+                    }
+                }
+            }
+            const entryId = e['id'];
+            if (entryId !== undefined) {
+                if (typeof entryId !== 'string') {
+                    errors.push({ code: 'BP-009', message: `${path}.id must be a string` });
+                }
+                else if (!ID_GRAMMAR_RE.test(entryId)) {
+                    errors.push({
+                        code: 'BP-009',
+                        message: `${path}.id "${entryId}" must match <TYPE>-[<middle>-]<INTEGER>`,
+                    });
+                }
+                else if (category === 'systems' && !APPLICATION_ID_RE.test(entryId)) {
+                    errors.push({
+                        code: 'BP-010',
+                        message: `${path}.id "${entryId}" must use the APPLICATION- prefix`,
+                    });
+                }
+                else if (category === 'actors' && !ROLE_ID_RE.test(entryId)) {
+                    errors.push({
+                        code: 'BP-010',
+                        message: `${path}.id "${entryId}" must use the ROLE- prefix`,
+                    });
+                }
+            }
+        }
+    }
+    for (const sid of stageIds) {
+        if (!usedStageIds.has(sid)) {
+            warnings.push({
+                code: 'BP-011',
+                message: `Stage "${sid}" has no aspect entries pointing at it — structurally empty`,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

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

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

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

@@ -0,0 +1,199 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { validateProcessMap } from '../validate.js';
+const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'process-map');
+const VALID_MAP = {
+    notation: 'process-map',
+    process_map: {
+        id: 'PM-ENT-001',
+        name: 'Enterprise Process Landscape',
+        updated_at: '2026-05-08',
+        groups: [
+            {
+                id: 'GRP-OPERATING',
+                name: 'Operating Processes',
+                type: 'operating',
+                processes: [
+                    { process_id: 'PROC-ORD-FULFILL-001', name: 'Order Fulfilment', status: 'Active', maturity: 2 },
+                    { process_id: 'PROC-CUST-ONBOARD-001', name: 'Customer Onboarding', status: 'Draft' },
+                ],
+            },
+            {
+                id: 'GRP-SUPPORTING',
+                name: 'Supporting Processes',
+                type: 'supporting',
+                processes: [
+                    { process_id: 'PROC-HR-RECRUIT-001', name: 'Recruitment', status: 'Active' },
+                ],
+            },
+        ],
+    },
+};
+describe('validateProcessMap', () => {
+    it('passes on valid input', () => {
+        const r = validateProcessMap(VALID_MAP);
+        expect(r.valid).toBe(true);
+        expect(r.errors).toHaveLength(0);
+    });
+    it('PMAP-001: rejects non-object input', () => {
+        const r = validateProcessMap(null);
+        expect(r.valid).toBe(false);
+        expect(r.errors[0].code).toBe('PMAP-001');
+    });
+    it('PMAP-001: rejects missing notation', () => {
+        const { notation: _, ...rest } = VALID_MAP;
+        const r = validateProcessMap(rest);
+        expect(r.errors.some(e => e.code === 'PMAP-001')).toBe(true);
+    });
+    it('PMAP-001: rejects wrong notation value', () => {
+        const r = validateProcessMap({ ...VALID_MAP, notation: 'goals' });
+        expect(r.errors.some(e => e.code === 'PMAP-001')).toBe(true);
+    });
+    it('PMAP-002: rejects missing process_map', () => {
+        const r = validateProcessMap({ notation: 'process-map' });
+        expect(r.errors.some(e => e.code === 'PMAP-002')).toBe(true);
+    });
+    it('PMAP-002: rejects missing id/name/updated_at', () => {
+        const r = validateProcessMap({ notation: 'process-map', process_map: { groups: [] } });
+        expect(r.errors.filter(e => e.code === 'PMAP-002').length).toBeGreaterThanOrEqual(3);
+    });
+    it('PMAP-002: rejects non-array groups', () => {
+        const map = { ...VALID_MAP.process_map, groups: 'oops' };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.errors.some(e => e.code === 'PMAP-002')).toBe(true);
+    });
+    it('PMAP-003: rejects group missing id/name/type', () => {
+        const map = { ...VALID_MAP.process_map, groups: [{ processes: [] }] };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.errors.filter(e => e.code === 'PMAP-003').length).toBeGreaterThanOrEqual(3);
+    });
+    it('PMAP-004: rejects invalid group type', () => {
+        const map = {
+            ...VALID_MAP.process_map,
+            groups: [{ id: 'g1', name: 'X', type: 'random', processes: [] }],
+        };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.errors.some(e => e.code === 'PMAP-004')).toBe(true);
+    });
+    it('PMAP-004: accepts all valid group types', () => {
+        for (const type of ['operating', 'supporting', 'management']) {
+            const map = {
+                ...VALID_MAP.process_map,
+                groups: [{ id: 'g1', name: 'X', type, processes: [] }],
+            };
+            const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+            expect(r.errors.some(e => e.code === 'PMAP-004')).toBe(false);
+        }
+    });
+    it('PMAP-005: rejects process missing process_id/name/status', () => {
+        const map = {
+            ...VALID_MAP.process_map,
+            groups: [{ id: 'g1', name: 'G', type: 'operating', processes: [{}] }],
+        };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.errors.filter(e => e.code === 'PMAP-005').length).toBeGreaterThanOrEqual(3);
+    });
+    it('PMAP-006: rejects invalid status', () => {
+        const map = {
+            ...VALID_MAP.process_map,
+            groups: [{ id: 'g1', name: 'G', type: 'operating', processes: [
+                        { process_id: 'p1', name: 'X', status: 'Retired' },
+                    ] }],
+        };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.errors.some(e => e.code === 'PMAP-006')).toBe(true);
+    });
+    it('PMAP-007: rejects out-of-range maturity', () => {
+        const map = {
+            ...VALID_MAP.process_map,
+            groups: [{ id: 'g1', name: 'G', type: 'operating', processes: [
+                        { process_id: 'p1', name: 'X', status: 'Active', maturity: 6 },
+                    ] }],
+        };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.errors.some(e => e.code === 'PMAP-007')).toBe(true);
+    });
+    it('PMAP-007: accepts maturity 1-5', () => {
+        for (const maturity of [1, 2, 3, 4, 5]) {
+            const map = {
+                ...VALID_MAP.process_map,
+                groups: [{ id: 'g1', name: 'G', type: 'operating', processes: [
+                            { process_id: 'p1', name: 'X', status: 'Active', maturity },
+                        ] }],
+            };
+            const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+            expect(r.errors.some(e => e.code === 'PMAP-007')).toBe(false);
+        }
+    });
+    it('PMAP-008: rejects malformed updated_at', () => {
+        const map = { ...VALID_MAP.process_map, updated_at: '13-05-2026' };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.errors.some(e => e.code === 'PMAP-008')).toBe(true);
+    });
+    it('PMAP-009: rejects duplicate process_id across groups', () => {
+        const map = {
+            ...VALID_MAP.process_map,
+            groups: [
+                { id: 'g1', name: 'A', type: 'operating', processes: [{ process_id: 'P1', name: 'X', status: 'Active' }] },
+                { id: 'g2', name: 'B', type: 'supporting', processes: [{ process_id: 'P1', name: 'Y', status: 'Active' }] },
+            ],
+        };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.errors.some(e => e.code === 'PMAP-009')).toBe(true);
+    });
+    it('PMAP-010: rejects duplicate group id', () => {
+        const map = {
+            ...VALID_MAP.process_map,
+            groups: [
+                { id: 'gdup', name: 'A', type: 'operating', processes: [] },
+                { id: 'gdup', name: 'B', type: 'supporting', processes: [] },
+            ],
+        };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.errors.some(e => e.code === 'PMAP-010')).toBe(true);
+    });
+    it('accepts empty groups array', () => {
+        const map = { ...VALID_MAP.process_map, groups: [] };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.valid).toBe(true);
+    });
+    it('accepts group with no processes field', () => {
+        const map = {
+            ...VALID_MAP.process_map,
+            groups: [{ id: 'g1', name: 'G', type: 'operating' }],
+        };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.valid).toBe(true);
+    });
+    // Pre-release blocker regression (orchestrator review 2026-05-21).
+    it('[blocker] tolerates a null element in groups[] without throwing', () => {
+        const map = { ...VALID_MAP.process_map, groups: [null] };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'PMAP-003')).toBe(true);
+    });
+    it('[blocker] tolerates a null element in processes[] without throwing', () => {
+        const map = {
+            ...VALID_MAP.process_map,
+            groups: [{ id: 'g1', name: 'G', type: 'operating', processes: [null] }],
+        };
+        const r = validateProcessMap({ ...VALID_MAP, process_map: map });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'PMAP-005')).toBe(true);
+    });
+});
+describe('process-map examples (regression)', () => {
+    const files = fs.readdirSync(EXAMPLES_DIR).filter(f => f.endsWith('.yaml'));
+    expect(files.length).toBeGreaterThan(0);
+    for (const file of files) {
+        it(`validates tests/fixtures/notation-corpus/process-map/${file}`, () => {
+            const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+            const parsed = yaml.load(text);
+            const r = validateProcessMap(parsed);
+            expect(r.errors).toEqual([]);
+            expect(r.valid).toBe(true);
+        });
+    }
+});

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

@@ -0,0 +1,2 @@
+export type { ProcessGroupType, ProcessStatus, MapProcess, ProcessGroup, ProcessMapHeader, ProcessMapFile, } from './types.js';
+export { validateProcessMap } from './validate.js';

package/dist/process-map/index.js

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

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

@@ -0,0 +1,32 @@
+export type ProcessGroupType = 'operating' | 'supporting' | 'management';
+export type ProcessStatus = 'Draft' | 'Active' | 'Deprecated';
+export interface MapProcess {
+    process_id: string;
+    name: string;
+    status: ProcessStatus;
+    owner_role?: string;
+    capability?: string;
+    maturity?: number;
+    bpmn_file?: string;
+    description?: string;
+}
+export interface ProcessGroup {
+    id: string;
+    name: string;
+    type: ProcessGroupType;
+    description?: string;
+    processes: MapProcess[];
+}
+export interface ProcessMapHeader {
+    id: string;
+    name: string;
+    description?: string;
+    version?: string;
+    updated_at: string;
+    groups: ProcessGroup[];
+}
+export interface ProcessMapFile {
+    notation: string;
+    spec_version?: string;
+    process_map: ProcessMapHeader;
+}

package/dist/process-map/types.js

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

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

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

package/dist/process-map/validate.js

@@ -0,0 +1,115 @@
+const VALID_GROUP_TYPES = new Set(['operating', 'supporting', 'management']);
+const VALID_STATUSES = new Set(['Draft', 'Active', 'Deprecated']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export function validateProcessMap(input) {
+    const errors = [];
+    const warnings = [];
+    if (!input || typeof input !== 'object') {
+        return { valid: false, errors: [{ code: 'PMAP-001', message: 'Input must be an object' }], warnings };
+    }
+    const raw = input;
+    if (!('notation' in raw)) {
+        errors.push({ code: 'PMAP-001', message: 'Missing required field: notation' });
+    }
+    else if (raw['notation'] !== 'process-map') {
+        errors.push({ code: 'PMAP-001', message: `notation must be "process-map", got "${raw['notation']}"` });
+    }
+    if (errors.length > 0)
+        return { valid: false, errors, warnings };
+    const map = raw['process_map'];
+    if (!map || typeof map !== 'object') {
+        errors.push({ code: 'PMAP-002', message: 'Missing required field: process_map' });
+        return { valid: false, errors, warnings };
+    }
+    const m = map;
+    if (!m['id'] || typeof m['id'] !== 'string' || !m['id'].trim()) {
+        errors.push({ code: 'PMAP-002', message: 'process_map.id is required' });
+    }
+    if (!m['name'] || typeof m['name'] !== 'string' || !m['name'].trim()) {
+        errors.push({ code: 'PMAP-002', message: 'process_map.name is required' });
+    }
+    if (!m['updated_at'] || typeof m['updated_at'] !== 'string') {
+        errors.push({ code: 'PMAP-002', message: 'process_map.updated_at is required' });
+    }
+    if (errors.length > 0)
+        return { valid: false, errors, warnings };
+    if (!DATE_RE.test(m['updated_at'])) {
+        errors.push({ code: 'PMAP-008', message: `process_map.updated_at must be YYYY-MM-DD, got "${m['updated_at']}"` });
+    }
+    const groups = m['groups'];
+    if (!Array.isArray(groups)) {
+        errors.push({ code: 'PMAP-002', message: 'process_map.groups must be an array' });
+        return { valid: false, errors, warnings };
+    }
+    const seenGroupIds = new Set();
+    const seenProcessIds = new Set();
+    for (let gi = 0; gi < groups.length; gi++) {
+        const rawGroup = groups[gi];
+        const gIdx = `groups[${gi}]`;
+        if (!rawGroup || typeof rawGroup !== 'object') {
+            errors.push({ code: 'PMAP-003', message: `${gIdx} must be an object` });
+            continue;
+        }
+        const g = rawGroup;
+        if (!g['id'] || typeof g['id'] !== 'string' || !g['id'].trim()) {
+            errors.push({ code: 'PMAP-003', message: `${gIdx}: id is required` });
+        }
+        else {
+            const gid = g['id'];
+            if (seenGroupIds.has(gid)) {
+                errors.push({ code: 'PMAP-010', message: `Duplicate group id: "${gid}"` });
+            }
+            seenGroupIds.add(gid);
+        }
+        if (!g['name'] || typeof g['name'] !== 'string' || !g['name'].trim()) {
+            errors.push({ code: 'PMAP-003', message: `${gIdx}: name is required` });
+        }
+        if (!g['type']) {
+            errors.push({ code: 'PMAP-003', message: `${gIdx}: type is required` });
+        }
+        else if (!VALID_GROUP_TYPES.has(g['type'])) {
+            errors.push({ code: 'PMAP-004', message: `${gIdx}: type "${g['type']}" must be one of: operating, supporting, management` });
+        }
+        const processes = g['processes'];
+        if (processes !== undefined && !Array.isArray(processes)) {
+            errors.push({ code: 'PMAP-003', message: `${gIdx}: processes must be an array` });
+            continue;
+        }
+        const list = (processes ?? []);
+        for (let pi = 0; pi < list.length; pi++) {
+            const rawProcess = list[pi];
+            const pIdx = `${gIdx}.processes[${pi}]`;
+            if (!rawProcess || typeof rawProcess !== 'object') {
+                errors.push({ code: 'PMAP-005', message: `${pIdx} must be an object` });
+                continue;
+            }
+            const p = rawProcess;
+            if (!p['process_id'] || typeof p['process_id'] !== 'string' || !p['process_id'].trim()) {
+                errors.push({ code: 'PMAP-005', message: `${pIdx}: process_id is required` });
+            }
+            else {
+                const pid = p['process_id'];
+                if (seenProcessIds.has(pid)) {
+                    errors.push({ code: 'PMAP-009', message: `Duplicate process_id: "${pid}"` });
+                }
+                seenProcessIds.add(pid);
+            }
+            if (!p['name'] || typeof p['name'] !== 'string' || !p['name'].trim()) {
+                errors.push({ code: 'PMAP-005', message: `${pIdx}: name is required` });
+            }
+            if (!p['status']) {
+                errors.push({ code: 'PMAP-005', message: `${pIdx}: status is required` });
+            }
+            else if (!VALID_STATUSES.has(p['status'])) {
+                errors.push({ code: 'PMAP-006', message: `${pIdx}: status "${p['status']}" must be one of: Draft, Active, Deprecated` });
+            }
+            if (p['maturity'] !== undefined) {
+                const mat = p['maturity'];
+                if (typeof mat !== 'number' || !Number.isInteger(mat) || mat < 1 || mat > 5) {
+                    errors.push({ code: 'PMAP-007', message: `${pIdx}: maturity must be an integer 1–5, got "${mat}"` });
+                }
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

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

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