@transitrix/diagrams 1.2.0 → 1.4.0

package/dist/node/validate.d.ts

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

package/dist/node/validate.js

@@ -0,0 +1,53 @@
+// NODE validator — methodology notations/elements/25-nodes.md §5.
+//
+// Implements NOD-001, NOD-002. The shared HDR-/LIFECYCLE- rules are
+// cross-cutting concerns (CONTRACT.md §8) and out of scope for the
+// single-artefact validator.
+import { isCanonicalIdOfType } from '../typed-id.js';
+import { NODE_TYPES } from './types.js';
+const REQUIRED_STRING_FIELDS = [
+    'name', 'admitted_at', 'admitted_by', 'valid_from',
+];
+const TYPES = NODE_TYPES;
+export function validateNode(input) {
+    const errors = [];
+    const warnings = [];
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        errors.push({ code: 'NOD-001', message: 'Node must be a YAML mapping.' });
+        return { valid: false, errors, warnings };
+    }
+    const a = input;
+    // NOD-001 — id grammar + notation tag + envelope.
+    if (!isCanonicalIdOfType(a.id, 'NODE')) {
+        errors.push({ code: 'NOD-001', message: `id "${String(a.id)}" must match NODE-[<middle>-]<INTEGER>.`, path: 'id' });
+    }
+    if (a.notation !== 'node') {
+        errors.push({ code: 'NOD-001', message: 'notation must be the fixed value "node".', path: 'notation' });
+    }
+    if (a.zone !== undefined && a.zone !== 'canon') {
+        errors.push({ code: 'NOD-001', message: 'zone must be "canon" for a NODE.', path: 'zone' });
+    }
+    else if (a.zone === undefined) {
+        errors.push({ code: 'NOD-001', message: 'zone is required.', path: 'zone' });
+    }
+    for (const field of REQUIRED_STRING_FIELDS) {
+        const v = a[field];
+        if (typeof v !== 'string' || v.trim() === '') {
+            errors.push({ code: 'NOD-001', message: `${field} is required.`, path: field });
+        }
+    }
+    if (a.gate_checks === null || typeof a.gate_checks !== 'object') {
+        errors.push({ code: 'NOD-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+    }
+    if (!('valid_to' in a) || !(typeof a.valid_to === 'string' || a.valid_to === null)) {
+        errors.push({ code: 'NOD-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+    }
+    if (typeof a.type !== 'string' || a.type.trim() === '') {
+        errors.push({ code: 'NOD-001', message: 'type is required.', path: 'type' });
+    }
+    else if (!TYPES.includes(a.type)) {
+        // NOD-002 — type enum.
+        errors.push({ code: 'NOD-002', message: `type "${a.type}" must be one of ${TYPES.join(', ')}.`, path: 'type' });
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

package/dist/repo-validate/__tests__/validate-repo.test.js

@@ -130,3 +130,447 @@ describe('validateRepoModel — syntax', () => {
         expect(findings[0].message).toContain('broken.yaml');
     });
 });
+describe('validateRepoModel — layer-semantics (unit_located_at / located_at)', () => {
+    function locationModel() {
+        const model = cleanModel();
+        model.elements.push(el('canon/elements/02_business/actors/ACTOR-OPS-1.yaml', {
+            notation: 'actor',
+            id: 'ACTOR-OPS-1',
+            type: 'business_unit',
+        }), el('canon/elements/02_business/actors/ACTOR-JANE-1.yaml', {
+            notation: 'actor',
+            id: 'ACTOR-JANE-1',
+            type: 'person',
+        }), el('canon/elements/02_business/locations/LOCATION-TBILISI-1.yaml', {
+            notation: 'location',
+            id: 'LOCATION-TBILISI-1',
+        }));
+        return model;
+    }
+    it('accepts a valid unit_located_at (business_unit → LOCATION)', () => {
+        const model = locationModel();
+        model.relations.push(el('canon/relations/REL-LOC-1.yaml', {
+            notation: 'relation',
+            id: 'REL-LOC-1',
+            type: 'unit_located_at',
+            from: 'ACTOR-OPS-1',
+            to: 'LOCATION-TBILISI-1',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('accepts a valid located_at for a business_unit', () => {
+        const model = locationModel();
+        model.relations.push(el('canon/relations/REL-LOC-2.yaml', {
+            notation: 'relation',
+            id: 'REL-LOC-2',
+            type: 'located_at',
+            from: 'ACTOR-OPS-1',
+            to: 'LOCATION-TBILISI-1',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('accepts a valid located_at for a person', () => {
+        const model = locationModel();
+        model.relations.push(el('canon/relations/REL-LOC-3.yaml', {
+            notation: 'relation',
+            id: 'REL-LOC-3',
+            type: 'located_at',
+            from: 'ACTOR-JANE-1',
+            to: 'LOCATION-TBILISI-1',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('flags unit_located_at with a wrong from type (person instead of business_unit)', () => {
+        const model = locationModel();
+        model.relations.push(el('canon/relations/REL-BAD-1.yaml', {
+            notation: 'relation',
+            id: 'REL-BAD-1',
+            type: 'unit_located_at',
+            from: 'ACTOR-JANE-1',
+            to: 'LOCATION-TBILISI-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-BAD-1' });
+        expect(findings[0].message).toContain('unit_located_at');
+        expect(findings[0].message).toContain('business_unit');
+    });
+    it('flags unit_located_at with a non-ACTOR from element', () => {
+        const model = locationModel();
+        model.relations.push(el('canon/relations/REL-BAD-2.yaml', {
+            notation: 'relation',
+            id: 'REL-BAD-2',
+            type: 'unit_located_at',
+            from: 'GOAL-OPS-1',
+            to: 'LOCATION-TBILISI-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-BAD-2' });
+        expect(findings[0].message).toContain('unit_located_at');
+    });
+    it('flags unit_located_at with a non-LOCATION to element', () => {
+        const model = locationModel();
+        model.relations.push(el('canon/relations/REL-BAD-3.yaml', {
+            notation: 'relation',
+            id: 'REL-BAD-3',
+            type: 'unit_located_at',
+            from: 'ACTOR-OPS-1',
+            to: 'GOAL-OPS-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-BAD-3' });
+        expect(findings[0].message).toContain('LOCATION');
+    });
+    it('flags located_at with a non-actor from element', () => {
+        const model = locationModel();
+        model.relations.push(el('canon/relations/REL-BAD-4.yaml', {
+            notation: 'relation',
+            id: 'REL-BAD-4',
+            type: 'located_at',
+            from: 'CAPABILITY-V1',
+            to: 'LOCATION-TBILISI-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-BAD-4' });
+        expect(findings[0].message).toContain('located_at');
+    });
+    it('does not emit layer-semantic findings for unknown endpoints (ref-integrity handles those)', () => {
+        const model = locationModel();
+        model.relations.push(el('canon/relations/REL-MISSING.yaml', {
+            notation: 'relation',
+            id: 'REL-MISSING',
+            type: 'unit_located_at',
+            from: 'ACTOR-UNKNOWN-99',
+            to: 'LOCATION-UNKNOWN-99',
+        }));
+        const findings = validateRepoModel(model);
+        // ref-integrity fires for missing endpoints; no duplicate layer-semantic finding
+        expect(findings.every((f) => !f.message.includes('Layer-semantics'))).toBe(true);
+        expect(findings.some((f) => f.message.includes('ACTOR-UNKNOWN-99'))).toBe(true);
+    });
+});
+describe('validateRepoModel — layer-semantics (offers / realizes)', () => {
+    function serviceModel() {
+        const model = cleanModel();
+        model.elements.push(el('canon/elements/02_business/actors/ACTOR-OPS-1.yaml', {
+            notation: 'actor',
+            id: 'ACTOR-OPS-1',
+            type: 'business_unit',
+        }), el('canon/elements/02_business/roles/ROLE-OWNER-1.yaml', {
+            notation: 'role',
+            id: 'ROLE-OWNER-1',
+        }), el('canon/elements/02_business/business-services/BUSINESS_SERVICE-CRM-1.yaml', {
+            notation: 'business-service',
+            id: 'BUSINESS_SERVICE-CRM-1',
+        }), el('canon/elements/02_business/capabilities/CAPABILITY-V2.yaml', {
+            notation: 'capability',
+            id: 'CAPABILITY-V2',
+        }));
+        return model;
+    }
+    it('accepts a valid offers (ACTOR(business_unit) → BUSINESS_SERVICE)', () => {
+        const model = serviceModel();
+        model.relations.push(el('canon/relations/REL-SVC-1.yaml', {
+            notation: 'relation',
+            id: 'REL-SVC-1',
+            type: 'offers',
+            from: 'ACTOR-OPS-1',
+            to: 'BUSINESS_SERVICE-CRM-1',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('accepts a valid offers (ROLE → BUSINESS_SERVICE)', () => {
+        const model = serviceModel();
+        model.relations.push(el('canon/relations/REL-SVC-2.yaml', {
+            notation: 'relation',
+            id: 'REL-SVC-2',
+            type: 'offers',
+            from: 'ROLE-OWNER-1',
+            to: 'BUSINESS_SERVICE-CRM-1',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('accepts a valid realizes (BUSINESS_SERVICE → CAPABILITY)', () => {
+        const model = serviceModel();
+        model.relations.push(el('canon/relations/REL-SVC-3.yaml', {
+            notation: 'relation',
+            id: 'REL-SVC-3',
+            type: 'realizes',
+            from: 'BUSINESS_SERVICE-CRM-1',
+            to: 'CAPABILITY-V2',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('flags offers with a non-ACTOR/non-ROLE from element', () => {
+        const model = serviceModel();
+        model.relations.push(el('canon/relations/REL-SVC-BAD-1.yaml', {
+            notation: 'relation',
+            id: 'REL-SVC-BAD-1',
+            type: 'offers',
+            from: 'CAPABILITY-V2',
+            to: 'BUSINESS_SERVICE-CRM-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-SVC-BAD-1' });
+        expect(findings[0].message).toContain('offers');
+        expect(findings[0].message).toContain('ACTOR');
+    });
+    it('flags offers with a non-BUSINESS_SERVICE to element', () => {
+        const model = serviceModel();
+        model.relations.push(el('canon/relations/REL-SVC-BAD-2.yaml', {
+            notation: 'relation',
+            id: 'REL-SVC-BAD-2',
+            type: 'offers',
+            from: 'ACTOR-OPS-1',
+            to: 'CAPABILITY-V2',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-SVC-BAD-2' });
+        expect(findings[0].message).toContain('BUSINESS_SERVICE');
+    });
+    it('flags realizes with a non-BUSINESS_SERVICE from element', () => {
+        const model = serviceModel();
+        model.relations.push(el('canon/relations/REL-SVC-BAD-3.yaml', {
+            notation: 'relation',
+            id: 'REL-SVC-BAD-3',
+            type: 'realizes',
+            from: 'ACTOR-OPS-1',
+            to: 'CAPABILITY-V2',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-SVC-BAD-3' });
+        expect(findings[0].message).toContain('realizes');
+        expect(findings[0].message).toContain('BUSINESS_SERVICE');
+    });
+});
+describe('validateRepoModel — layer-semantics (INT-002 integration endpoints)', () => {
+    function integrationModel() {
+        const model = cleanModel();
+        model.elements.push(el('canon/elements/03_application/applications/APPLICATION-OMS-1.yaml', {
+            notation: 'application',
+            id: 'APPLICATION-OMS-1',
+        }), el('canon/elements/03_application/applications/APPLICATION-CRM-1.yaml', {
+            notation: 'application',
+            id: 'APPLICATION-CRM-1',
+        }), el('canon/elements/02_business/actors/ACTOR-OPS-1.yaml', {
+            notation: 'actor',
+            id: 'ACTOR-OPS-1',
+            type: 'business_unit',
+        }));
+        return model;
+    }
+    it('accepts an interface_semantics integration whose endpoints resolve to APPLICATION elements', () => {
+        const model = integrationModel();
+        model.elements.push(el('canon/elements/03_application/integrations/INTEGRATION-OMS-EVENTS-1.yaml', {
+            notation: 'integration',
+            id: 'INTEGRATION-OMS-EVENTS-1',
+            interface_semantics: true,
+            source: 'APPLICATION-OMS-1',
+            target: 'APPLICATION-CRM-1',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('does not fire INT-002 for an integration without interface_semantics', () => {
+        const model = integrationModel();
+        model.elements.push(el('canon/elements/03_application/integrations/INTEGRATION-PLAIN-1.yaml', {
+            notation: 'integration',
+            id: 'INTEGRATION-PLAIN-1',
+            source: 'ACTOR-OPS-1',
+            target: 'APPLICATION-CRM-1',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('flags INT-002 when source resolves to a non-APPLICATION element', () => {
+        const model = integrationModel();
+        model.elements.push(el('canon/elements/03_application/integrations/INTEGRATION-BAD-1.yaml', {
+            notation: 'integration',
+            id: 'INTEGRATION-BAD-1',
+            interface_semantics: true,
+            source: 'ACTOR-OPS-1',
+            target: 'APPLICATION-CRM-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'INTEGRATION-BAD-1' });
+        expect(findings[0].message).toContain('INT-002');
+        expect(findings[0].message).toContain('ACTOR-OPS-1');
+        expect(findings[0].message).toContain('source');
+    });
+    it('flags INT-002 when target resolves to a non-APPLICATION element', () => {
+        const model = integrationModel();
+        model.elements.push(el('canon/elements/03_application/integrations/INTEGRATION-BAD-2.yaml', {
+            notation: 'integration',
+            id: 'INTEGRATION-BAD-2',
+            interface_semantics: true,
+            source: 'APPLICATION-OMS-1',
+            target: 'ACTOR-OPS-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'INTEGRATION-BAD-2' });
+        expect(findings[0].message).toContain('INT-002');
+        expect(findings[0].message).toContain('ACTOR-OPS-1');
+        expect(findings[0].message).toContain('target');
+    });
+    it('flags INT-002 for both endpoints when neither resolves to APPLICATION', () => {
+        const model = integrationModel();
+        model.elements.push(el('canon/elements/03_application/integrations/INTEGRATION-BAD-3.yaml', {
+            notation: 'integration',
+            id: 'INTEGRATION-BAD-3',
+            interface_semantics: true,
+            source: 'ACTOR-OPS-1',
+            target: 'GOAL-OPS-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(2);
+        expect(findings.every(f => f.message.includes('INT-002'))).toBe(true);
+    });
+    it('does not flag INT-002 when endpoint id is not in the element registry', () => {
+        // Unresolved IDs are caught by phase 4 (referential integrity), not INT-002.
+        const model = integrationModel();
+        model.elements.push(el('canon/elements/03_application/integrations/INTEGRATION-UNRESOLVED-1.yaml', {
+            notation: 'integration',
+            id: 'INTEGRATION-UNRESOLVED-1',
+            interface_semantics: true,
+            source: 'APPLICATION-MISSING-99',
+            target: 'APPLICATION-CRM-1',
+        }));
+        const findings = validateRepoModel(model).filter(f => f.message.includes('INT-002'));
+        expect(findings).toHaveLength(0);
+    });
+});
+describe('validateRepoModel — layer-semantics (hosts / uses / TSVC-003)', () => {
+    function techModel() {
+        const model = cleanModel();
+        model.elements.push(el('canon/elements/04_technology/nodes/NODE-KAFKA-HOST-1.yaml', {
+            notation: 'node',
+            id: 'NODE-KAFKA-HOST-1',
+            type: 'cloud_instance',
+        }), el('canon/elements/04_technology/services/TECHNOLOGY_SERVICE-KAFKA-1.yaml', {
+            notation: 'technology-service',
+            id: 'TECHNOLOGY_SERVICE-KAFKA-1',
+            type: 'messaging',
+            node: 'NODE-KAFKA-HOST-1',
+        }), el('canon/elements/03_application/applications/APPLICATION-OMS-1.yaml', {
+            notation: 'application',
+            id: 'APPLICATION-OMS-1',
+        }));
+        return model;
+    }
+    it('accepts a valid hosts relation (NODE → TECHNOLOGY_SERVICE)', () => {
+        const model = techModel();
+        model.relations.push(el('canon/relations/REL-HOSTS-1.yaml', {
+            notation: 'relation',
+            id: 'REL-HOSTS-1',
+            type: 'hosts',
+            from: 'NODE-KAFKA-HOST-1',
+            to: 'TECHNOLOGY_SERVICE-KAFKA-1',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('accepts a valid uses relation (APPLICATION → TECHNOLOGY_SERVICE)', () => {
+        const model = techModel();
+        model.relations.push(el('canon/relations/REL-USES-1.yaml', {
+            notation: 'relation',
+            id: 'REL-USES-1',
+            type: 'uses',
+            from: 'APPLICATION-OMS-1',
+            to: 'TECHNOLOGY_SERVICE-KAFKA-1',
+        }));
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('flags hosts with a non-NODE from element', () => {
+        const model = techModel();
+        model.relations.push(el('canon/relations/REL-HOSTS-BAD-1.yaml', {
+            notation: 'relation',
+            id: 'REL-HOSTS-BAD-1',
+            type: 'hosts',
+            from: 'APPLICATION-OMS-1',
+            to: 'TECHNOLOGY_SERVICE-KAFKA-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-HOSTS-BAD-1' });
+        expect(findings[0].message).toContain('hosts');
+        expect(findings[0].message).toContain('NODE');
+    });
+    it('flags hosts with a non-TECHNOLOGY_SERVICE to element', () => {
+        const model = techModel();
+        model.relations.push(el('canon/relations/REL-HOSTS-BAD-2.yaml', {
+            notation: 'relation',
+            id: 'REL-HOSTS-BAD-2',
+            type: 'hosts',
+            from: 'NODE-KAFKA-HOST-1',
+            to: 'APPLICATION-OMS-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-HOSTS-BAD-2' });
+        expect(findings[0].message).toContain('hosts');
+        expect(findings[0].message).toContain('TECHNOLOGY_SERVICE');
+    });
+    it('flags uses with a non-APPLICATION from element', () => {
+        const model = techModel();
+        model.relations.push(el('canon/relations/REL-USES-BAD-1.yaml', {
+            notation: 'relation',
+            id: 'REL-USES-BAD-1',
+            type: 'uses',
+            from: 'NODE-KAFKA-HOST-1',
+            to: 'TECHNOLOGY_SERVICE-KAFKA-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-USES-BAD-1' });
+        expect(findings[0].message).toContain('uses');
+        expect(findings[0].message).toContain('APPLICATION');
+    });
+    it('flags uses with a non-TECHNOLOGY_SERVICE to element', () => {
+        const model = techModel();
+        model.relations.push(el('canon/relations/REL-USES-BAD-2.yaml', {
+            notation: 'relation',
+            id: 'REL-USES-BAD-2',
+            type: 'uses',
+            from: 'APPLICATION-OMS-1',
+            to: 'NODE-KAFKA-HOST-1',
+        }));
+        const findings = validateRepoModel(model);
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-USES-BAD-2' });
+        expect(findings[0].message).toContain('uses');
+        expect(findings[0].message).toContain('TECHNOLOGY_SERVICE');
+    });
+    it('TSVC-003: does not flag a technology-service whose node resolves to a NODE element', () => {
+        const model = techModel();
+        expect(validateRepoModel(model)).toEqual([]);
+    });
+    it('TSVC-003: flags a technology-service whose node resolves to a non-NODE element', () => {
+        const model = techModel();
+        model.elements.push(el('canon/elements/04_technology/services/TECHNOLOGY_SERVICE-BAD-1.yaml', {
+            notation: 'technology-service',
+            id: 'TECHNOLOGY_SERVICE-BAD-1',
+            type: 'messaging',
+            node: 'APPLICATION-OMS-1',
+        }));
+        const findings = validateRepoModel(model).filter(f => f.message.includes('TSVC-003'));
+        expect(findings).toHaveLength(1);
+        expect(findings[0]).toMatchObject({ scope: 'repo', id: 'TECHNOLOGY_SERVICE-BAD-1' });
+        expect(findings[0].message).toContain('APPLICATION-OMS-1');
+    });
+    it('TSVC-003: does not flag a technology-service with an unresolved node (phase 4 handles that)', () => {
+        const model = techModel();
+        model.elements.push(el('canon/elements/04_technology/services/TECHNOLOGY_SERVICE-UNRESOLVED-1.yaml', {
+            notation: 'technology-service',
+            id: 'TECHNOLOGY_SERVICE-UNRESOLVED-1',
+            type: 'storage',
+            node: 'NODE-MISSING-99',
+        }));
+        const findings = validateRepoModel(model).filter(f => f.message.includes('TSVC-003'));
+        expect(findings).toHaveLength(0);
+    });
+});