@transitrix/diagrams 1.2.0 → 1.4.0

package/src/integration/validate.ts

@@ -0,0 +1,104 @@
+// INTEGRATION validator — methodology notations/ELEMENT_PRIMITIVES.md §7.8.
+//
+// Implements INT-001 (conditional field enforcement when interface_semantics: true)
+// and INT-002 (endpoint APPLICATION type check). The shared HDR-/LIFECYCLE- rules
+// are cross-cutting concerns (CONTRACT.md §8) and out of scope for the
+// single-artefact validator.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { isCanonicalIdOfType } from '../typed-id.js';
+
+const REQUIRED_STRING_FIELDS = [
+  'source', 'target', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
+
+const VALID_DIRECTIONS = new Set(['inbound', 'outbound', 'bidirectional']);
+const VALID_SENSITIVITY = new Set(['public', 'internal', 'confidential', 'restricted']);
+const VALID_DIRECTIONALITY = new Set(['producer', 'consumer', 'request_reply', 'bidirectional_stream']);
+
+const IFACE_CONDITIONAL = ['protocol', 'payload_class', 'sensitivity', 'directionality'] as const;
+
+export function validateIntegration(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'INT-001', message: 'Integration must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const a = input as Record<string, unknown>;
+
+  // Shape — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(a.id, 'INTEGRATION')) {
+    errors.push({ code: 'INT-001', message: `id "${String(a.id)}" must match INTEGRATION-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (a.notation !== 'integration') {
+    errors.push({ code: 'INT-001', message: 'notation must be the fixed value "integration".', path: 'notation' });
+  }
+  if (a.zone !== undefined && a.zone !== 'canon') {
+    errors.push({ code: 'INT-001', message: 'zone must be "canon" for a standalone INTEGRATION.', path: 'zone' });
+  } else if (a.zone === undefined) {
+    errors.push({ code: 'INT-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: 'INT-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (a.gate_checks === null || typeof a.gate_checks !== 'object') {
+    errors.push({ code: 'INT-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: 'INT-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+  if (a.direction !== undefined && !VALID_DIRECTIONS.has(a.direction as string)) {
+    errors.push({ code: 'INT-001', message: `direction "${a.direction}" must be one of inbound, outbound, bidirectional.`, path: 'direction' });
+  }
+
+  // INT-001 — interface_semantics: true triggers conditional field enforcement.
+  if (a.interface_semantics === true) {
+    for (const field of IFACE_CONDITIONAL) {
+      const v = a[field];
+      if (typeof v !== 'string' || v.trim() === '') {
+        errors.push({
+          code: 'INT-001',
+          message: `${field} is required when interface_semantics is true.`,
+          path: field,
+        });
+      }
+    }
+    if (typeof a.sensitivity === 'string' && !VALID_SENSITIVITY.has(a.sensitivity)) {
+      errors.push({
+        code: 'INT-001',
+        message: `sensitivity "${a.sensitivity}" must be one of public, internal, confidential, restricted.`,
+        path: 'sensitivity',
+      });
+    }
+    if (typeof a.directionality === 'string' && !VALID_DIRECTIONALITY.has(a.directionality)) {
+      errors.push({
+        code: 'INT-001',
+        message: `directionality "${a.directionality}" must be one of producer, consumer, request_reply, bidirectional_stream.`,
+        path: 'directionality',
+      });
+    }
+
+    // INT-002 — source and target must be APPLICATION-… IDs.
+    if (typeof a.source === 'string' && a.source.trim() !== '' && !isCanonicalIdOfType(a.source, 'APPLICATION')) {
+      errors.push({
+        code: 'INT-002',
+        message: `source "${a.source}" must be an APPLICATION-… canonical id when interface_semantics is true.`,
+        path: 'source',
+      });
+    }
+    if (typeof a.target === 'string' && a.target.trim() !== '' && !isCanonicalIdOfType(a.target, 'APPLICATION')) {
+      errors.push({
+        code: 'INT-002',
+        message: `target "${a.target}" must be an APPLICATION-… canonical id when interface_semantics is true.`,
+        path: 'target',
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/location/__tests__/validate.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import { validateLocation } from '../validate.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'location',
+    id: 'LOCATION-TBILISI-1',
+    name: 'Tbilisi Office',
+    type: 'office',
+    address: '14 Rustaveli Ave, Tbilisi 0108, Georgia',
+    country_code: 'GE',
+    timezone: 'Asia/Tbilisi',
+    zone: 'canon',
+    admitted_at: '2026-06-28',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2024-01-01',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown): string[] =>
+  validateLocation(input).errors.map(e => e.code);
+
+describe('validateLocation — positive', () => {
+  it('accepts a well-formed office location', () => {
+    const r = validateLocation(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+  });
+
+  it('accepts a country with no optional fields', () => {
+    const a = valid();
+    a.id = 'LOCATION-GE-1';
+    a.name = 'Georgia';
+    a.type = 'country';
+    delete a.address;
+    delete a.country_code;
+    delete a.timezone;
+    expect(validateLocation(a).valid).toBe(true);
+  });
+
+  it('accepts a virtual location', () => {
+    const a = valid();
+    a.id = 'LOCATION-VIRTUAL-1';
+    a.name = 'Remote';
+    a.type = 'virtual';
+    expect(validateLocation(a).valid).toBe(true);
+  });
+
+  it('accepts a location with a valid parent reference', () => {
+    expect(validateLocation({ ...valid(), parent: 'LOCATION-GE-1' }).valid).toBe(true);
+  });
+
+  it('accepts valid_to as a date string', () => {
+    expect(validateLocation({ ...valid(), valid_to: '2026-12-31' }).valid).toBe(true);
+  });
+});
+
+describe('validateLocation — LOC-001 (shape / id grammar)', () => {
+  it('flags a missing required envelope field (name)', () => {
+    const a = valid();
+    delete a.name;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'LOCATION-001' })).toContain('LOC-001');
+    expect(codes({ ...valid(), id: 'LOC-1' })).toContain('LOC-001');
+  });
+
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'place' })).toContain('LOC-001');
+  });
+
+  it('flags a non-canon zone', () => {
+    expect(codes({ ...valid(), zone: 'sandbox' })).toContain('LOC-001');
+  });
+
+  it('flags a missing zone', () => {
+    const a = valid();
+    delete a.zone;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('flags a missing type', () => {
+    const a = valid();
+    delete a.type;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('flags a missing valid_to key', () => {
+    const a = valid();
+    delete a.valid_to;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('flags missing gate_checks', () => {
+    const a = valid();
+    delete a.gate_checks;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['LOC-001']);
+  });
+});
+
+describe('validateLocation — LOC-002 (type enum)', () => {
+  it('flags a type outside the allowed enum', () => {
+    expect(codes({ ...valid(), type: 'building' })).toContain('LOC-002');
+    expect(codes({ ...valid(), type: 'facility' })).toContain('LOC-002');
+  });
+});
+
+describe('validateLocation — LOC-003 (parent grammar)', () => {
+  it('flags a parent that is not a LOCATION-… id', () => {
+    expect(codes({ ...valid(), parent: 'ACTOR-OPS-1' })).toContain('LOC-003');
+    expect(codes({ ...valid(), parent: 'not-an-id' })).toContain('LOC-003');
+  });
+
+  it('accepts a null or absent parent without error', () => {
+    expect(codes({ ...valid(), parent: undefined })).not.toContain('LOC-003');
+    const a = valid();
+    delete a.parent;
+    expect(codes(a)).not.toContain('LOC-003');
+  });
+});

package/src/location/index.ts

@@ -0,0 +1,3 @@
+export type { Location, LocationType } from './types.js';
+export { LOCATION_TYPES } from './types.js';
+export { validateLocation } from './validate.js';

package/src/location/types.ts

@@ -0,0 +1,29 @@
+// LOCATION — physical and virtual place primitive (ArchiMate Location/Facility).
+// Schema: methodology notations/elements/21-locations.md
+
+import type { GateChecks } from '../requirement/types.js';
+
+export const LOCATION_TYPES = ['country', 'region', 'city', 'site', 'office', 'virtual'] as const;
+export type LocationType = typeof LOCATION_TYPES[number];
+
+export interface Location {
+  notation: 'location';
+  id: string;
+  name: string;
+  type: LocationType;
+  address?: string;
+  country_code?: string;
+  timezone?: string;
+  parent?: string;
+  description?: string;
+
+  // Admission record (CONTRACT.md §6).
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  // Primitive lifecycle (CONTRACT.md §7).
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/location/validate.ts

@@ -0,0 +1,70 @@
+// LOCATION validator — methodology notations/elements/21-locations.md §6.
+//
+// Implements LOC-001..003. The shared HDR-/LIFECYCLE- rules are
+// cross-cutting concerns (CONTRACT.md §8) and out of scope for the
+// single-artefact validator.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { isCanonicalIdOfType, typeOfId } from '../typed-id.js';
+import { LOCATION_TYPES } from './types.js';
+
+const REQUIRED_STRING_FIELDS = [
+  'name', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
+
+const TYPES: readonly string[] = LOCATION_TYPES;
+
+export function validateLocation(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'LOC-001', message: 'Location must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const a = input as Record<string, unknown>;
+
+  // LOC-001 — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(a.id, 'LOCATION')) {
+    errors.push({ code: 'LOC-001', message: `id "${String(a.id)}" must match LOCATION-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (a.notation !== 'location') {
+    errors.push({ code: 'LOC-001', message: 'notation must be the fixed value "location".', path: 'notation' });
+  }
+  if (a.zone !== undefined && a.zone !== 'canon') {
+    errors.push({ code: 'LOC-001', message: 'zone must be "canon" for a LOCATION.', path: 'zone' });
+  } else if (a.zone === undefined) {
+    errors.push({ code: 'LOC-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: 'LOC-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (a.gate_checks === null || typeof a.gate_checks !== 'object') {
+    errors.push({ code: 'LOC-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: 'LOC-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: 'LOC-001', message: 'type is required.', path: 'type' });
+  } else if (!TYPES.includes(a.type)) {
+    // LOC-002 — type enum.
+    errors.push({ code: 'LOC-002', message: `type "${a.type}" must be one of ${TYPES.join(', ')}.`, path: 'type' });
+  }
+
+  // LOC-003 — parent must resolve to a LOCATION when present.
+  if ('parent' in a && a.parent !== undefined && a.parent !== null) {
+    if (typeof a.parent !== 'string' || !isCanonicalIdOfType(a.parent, 'LOCATION')) {
+      errors.push({
+        code: 'LOC-003',
+        message: `parent "${String(a.parent)}" must be a canonical LOCATION-… id.`,
+        path: 'parent',
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/node/__tests__/validate.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest';
+import { validateNode } from '../validate.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'node',
+    id: 'NODE-KAFKA-HOST-1',
+    name: 'Kafka Cluster Host',
+    type: 'cloud_instance',
+    description: 'AWS EC2 auto-scaling group hosting the Kafka broker cluster.',
+    provider: 'AWS',
+    region: 'eu-central-1',
+    zone: 'canon',
+    admitted_at: '2026-06-28',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2024-01-01',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown): string[] =>
+  validateNode(input).errors.map(e => e.code);
+
+describe('validateNode — positive', () => {
+  it('accepts a well-formed cloud_instance node with all optional fields', () => {
+    const r = validateNode(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+  });
+
+  it('accepts a server node with no optional fields', () => {
+    const a = valid();
+    a.id = 'NODE-DB-1';
+    a.name = 'Primary DB Server';
+    a.type = 'server';
+    delete a.description;
+    delete a.provider;
+    delete a.region;
+    expect(validateNode(a).valid).toBe(true);
+  });
+
+  it('accepts all five type values', () => {
+    for (const t of ['server', 'cloud_instance', 'container_platform', 'database_server', 'network_device']) {
+      expect(validateNode({ ...valid(), type: t }).valid).toBe(true);
+    }
+  });
+
+  it('accepts valid_to as a date string', () => {
+    expect(validateNode({ ...valid(), valid_to: '2026-12-31' }).valid).toBe(true);
+  });
+});
+
+describe('validateNode — NOD-001 (shape / id grammar)', () => {
+  it('flags a non-object input', () => {
+    expect(codes(null)).toEqual(['NOD-001']);
+    expect(codes('string')).toEqual(['NOD-001']);
+  });
+
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'NODE-001' })).toContain('NOD-001');
+    expect(codes({ ...valid(), id: 'NOD-1' })).toContain('NOD-001');
+    expect(codes({ ...valid(), id: 'node-kafka-1' })).toContain('NOD-001');
+  });
+
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'nodes' })).toContain('NOD-001');
+    expect(codes({ ...valid(), notation: 'infrastructure' })).toContain('NOD-001');
+  });
+
+  it('flags a non-canon zone', () => {
+    expect(codes({ ...valid(), zone: 'sandbox' })).toContain('NOD-001');
+  });
+
+  it('flags a missing zone', () => {
+    const a = valid();
+    delete a.zone;
+    expect(codes(a)).toContain('NOD-001');
+  });
+
+  it('flags a missing name', () => {
+    const a = valid();
+    delete a.name;
+    expect(codes(a)).toContain('NOD-001');
+  });
+
+  it('flags a missing valid_to key', () => {
+    const a = valid();
+    delete a.valid_to;
+    expect(codes(a)).toContain('NOD-001');
+  });
+
+  it('flags missing gate_checks', () => {
+    const a = valid();
+    delete a.gate_checks;
+    expect(codes(a)).toContain('NOD-001');
+  });
+
+  it('flags a missing type', () => {
+    const a = valid();
+    delete a.type;
+    expect(codes(a)).toContain('NOD-001');
+  });
+});
+
+describe('validateNode — NOD-002 (type enum)', () => {
+  it('flags a type outside the allowed enum', () => {
+    expect(codes({ ...valid(), type: 'virtual_machine' })).toContain('NOD-002');
+    expect(codes({ ...valid(), type: 'storage' })).toContain('NOD-002');
+    expect(codes({ ...valid(), type: 'cluster' })).toContain('NOD-002');
+  });
+
+  it('does not flag a missing type with NOD-002 (NOD-001 fires instead)', () => {
+    const a = valid();
+    delete a.type;
+    expect(codes(a)).not.toContain('NOD-002');
+    expect(codes(a)).toContain('NOD-001');
+  });
+});

package/src/node/index.ts

@@ -0,0 +1,2 @@
+export { validateNode } from './validate.js';
+export type { Node, NodeType } from './types.js';

package/src/node/types.ts

@@ -0,0 +1,27 @@
+// NODE — technology-layer infrastructure node primitive (ArchiMate Technology Node).
+// Schema: methodology notations/elements/25-nodes.md
+
+import type { GateChecks } from '../requirement/types.js';
+
+export const NODE_TYPES = ['server', 'cloud_instance', 'container_platform', 'database_server', 'network_device'] as const;
+export type NodeType = typeof NODE_TYPES[number];
+
+export interface Node {
+  notation: 'node';
+  id: string;
+  name: string;
+  type: NodeType;
+  description?: string;
+  provider?: string;
+  region?: string;
+
+  // Admission record (CONTRACT.md §6).
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  // Primitive lifecycle (CONTRACT.md §7).
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/node/validate.ts

@@ -0,0 +1,59 @@
+// 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 type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { isCanonicalIdOfType } from '../typed-id.js';
+import { NODE_TYPES } from './types.js';
+
+const REQUIRED_STRING_FIELDS = [
+  'name', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
+
+const TYPES: readonly string[] = NODE_TYPES;
+
+export function validateNode(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  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 as Record<string, unknown>;
+
+  // 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 };
+}