@transitrix/diagrams 1.3.0 → 1.5.0

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 };
+}