@transitrix/diagrams 1.0.0

package/src/process-map/validate.ts

@@ -0,0 +1,135 @@
+import type { ProcessGroupType, ProcessStatus } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+export type { ValidationError, ValidationWarning, ValidationResult };
+
+const VALID_GROUP_TYPES = new Set<ProcessGroupType>(['operating', 'supporting', 'management']);
+const VALID_STATUSES = new Set<ProcessStatus>(['Draft', 'Active', 'Deprecated']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function validateProcessMap(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'PMAP-001', message: 'Input must be an object' }], warnings };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  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 as Record<string, unknown>;
+
+  if (!m['id'] || typeof m['id'] !== 'string' || !(m['id'] as string).trim()) {
+    errors.push({ code: 'PMAP-002', message: 'process_map.id is required' });
+  }
+  if (!m['name'] || typeof m['name'] !== 'string' || !(m['name'] as string).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'] as string)) {
+    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<string>();
+  const seenProcessIds = new Set<string>();
+
+  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 as Record<string, unknown>;
+
+    if (!g['id'] || typeof g['id'] !== 'string' || !(g['id'] as string).trim()) {
+      errors.push({ code: 'PMAP-003', message: `${gIdx}: id is required` });
+    } else {
+      const gid = g['id'] as string;
+      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'] as string).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'] as ProcessGroupType)) {
+      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 ?? []) as unknown[];
+    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 as Record<string, unknown>;
+
+      if (!p['process_id'] || typeof p['process_id'] !== 'string' || !(p['process_id'] as string).trim()) {
+        errors.push({ code: 'PMAP-005', message: `${pIdx}: process_id is required` });
+      } else {
+        const pid = p['process_id'] as string;
+        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'] as string).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'] as ProcessStatus)) {
+        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/src/products/__tests__/validate.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from 'vitest';
+import { validateProductsCatalogue } from '../validate.js';
+
+const VALID_CATALOGUE = {
+  notation: 'products',
+  products_catalogue: {
+    id: 'cat-2026',
+    name: 'Portfolio 2026',
+    updated_at: '2026-05-13',
+    products: [
+      {
+        product_id: 'prod-001',
+        name: 'Analytics Platform',
+        type: 'platform',
+        status: 'Active',
+        domain: 'Data',
+        maturity: 3,
+      },
+      {
+        product_id: 'prod-002',
+        name: 'HR Service',
+        type: 'service',
+        status: 'Draft',
+      },
+    ],
+  },
+};
+
+describe('validateProductsCatalogue', () => {
+  it('passes on valid input', () => {
+    const r = validateProductsCatalogue(VALID_CATALOGUE);
+    expect(r.valid).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('PROD-001: rejects non-object input', () => {
+    const r = validateProductsCatalogue(null);
+    expect(r.valid).toBe(false);
+    expect(r.errors[0].code).toBe('PROD-001');
+  });
+
+  it('PROD-001: rejects missing notation field', () => {
+    const { notation: _, ...rest } = VALID_CATALOGUE;
+    const r = validateProductsCatalogue(rest);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-001')).toBe(true);
+  });
+
+  it('PROD-001: rejects wrong notation value', () => {
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, notation: 'goals' });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-001')).toBe(true);
+  });
+
+  it('PROD-002: rejects missing products_catalogue', () => {
+    const r = validateProductsCatalogue({ notation: 'products' });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-002')).toBe(true);
+  });
+
+  it('PROD-002: rejects missing catalogue id', () => {
+    const cat = { ...VALID_CATALOGUE.products_catalogue, id: '' };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-002' && e.message.includes('id'))).toBe(true);
+  });
+
+  it('PROD-002: rejects missing catalogue name', () => {
+    const cat = { ...VALID_CATALOGUE.products_catalogue, name: '   ' };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-002' && e.message.includes('name'))).toBe(true);
+  });
+
+  it('PROD-002: rejects missing updated_at', () => {
+    const { updated_at: _, ...cat } = VALID_CATALOGUE.products_catalogue;
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-002' && e.message.includes('updated_at'))).toBe(true);
+  });
+
+  it('PROD-002: rejects non-array products', () => {
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products: 'not-an-array' };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-002')).toBe(true);
+  });
+
+  it('PROD-003: rejects missing product_id', () => {
+    const products = [{ name: 'X', type: 'service', status: 'Active' }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-003' && e.message.includes('product_id'))).toBe(true);
+  });
+
+  it('PROD-003: rejects missing name', () => {
+    const products = [{ product_id: 'p1', name: '', type: 'service', status: 'Active' }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-003' && e.message.includes('name'))).toBe(true);
+  });
+
+  it('PROD-003: rejects missing type', () => {
+    const products = [{ product_id: 'p1', name: 'X', status: 'Active' }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-003' && e.message.includes('type'))).toBe(true);
+  });
+
+  it('PROD-003: rejects missing status', () => {
+    const products = [{ product_id: 'p1', name: 'X', type: 'service' }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-003' && e.message.includes('status'))).toBe(true);
+  });
+
+  it('PROD-004: rejects invalid type', () => {
+    const products = [{ product_id: 'p1', name: 'X', type: 'hardware', status: 'Active' }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-004')).toBe(true);
+  });
+
+  it('PROD-004: accepts all valid types', () => {
+    for (const type of ['digital_product', 'service', 'platform', 'bundle']) {
+      const products = [{ product_id: 'p1', name: 'X', type, status: 'Active' }];
+      const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+      const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+      expect(r.errors.some(e => e.code === 'PROD-004')).toBe(false);
+    }
+  });
+
+  it('PROD-005: rejects invalid status', () => {
+    const products = [{ product_id: 'p1', name: 'X', type: 'service', status: 'Active2' }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-005')).toBe(true);
+  });
+
+  it('PROD-005: accepts all valid statuses', () => {
+    for (const status of ['Draft', 'Active', 'Deprecated']) {
+      const products = [{ product_id: 'p1', name: 'X', type: 'service', status }];
+      const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+      const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+      expect(r.errors.some(e => e.code === 'PROD-005')).toBe(false);
+    }
+  });
+
+  it('PROD-006: rejects maturity < 1', () => {
+    const products = [{ product_id: 'p1', name: 'X', type: 'service', status: 'Active', maturity: 0 }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-006')).toBe(true);
+  });
+
+  it('PROD-006: rejects maturity > 5', () => {
+    const products = [{ product_id: 'p1', name: 'X', type: 'service', status: 'Active', maturity: 6 }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-006')).toBe(true);
+  });
+
+  it('PROD-006: rejects non-integer maturity', () => {
+    const products = [{ product_id: 'p1', name: 'X', type: 'service', status: 'Active', maturity: 2.5 }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-006')).toBe(true);
+  });
+
+  it('PROD-006: accepts valid maturity range 1-5', () => {
+    for (const maturity of [1, 2, 3, 4, 5]) {
+      const products = [{ product_id: 'p1', name: 'X', type: 'service', status: 'Active', maturity }];
+      const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+      const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+      expect(r.errors.some(e => e.code === 'PROD-006')).toBe(false);
+    }
+  });
+
+  it('PROD-007: rejects malformed updated_at', () => {
+    const cat = { ...VALID_CATALOGUE.products_catalogue, updated_at: '13-05-2026' };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-007')).toBe(true);
+  });
+
+  it('PROD-007: accepts YYYY-MM-DD format', () => {
+    const cat = { ...VALID_CATALOGUE.products_catalogue, updated_at: '2026-01-01' };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'PROD-007')).toBe(false);
+  });
+
+  it('PROD-008: rejects duplicate product_id', () => {
+    const products = [
+      { product_id: 'p1', name: 'X', type: 'service', status: 'Active' },
+      { product_id: 'p1', name: 'Y', type: 'platform', status: 'Draft' },
+    ];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-008')).toBe(true);
+  });
+
+  it('accepts empty products array', () => {
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products: [] };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(true);
+  });
+
+  it('accepts optional fields when absent', () => {
+    const products = [{ product_id: 'p1', name: 'X', type: 'service', status: 'Active' }];
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(true);
+  });
+
+  // Pre-release blocker regression (orchestrator review 2026-05-21).
+  it('[blocker] tolerates a null element in products[] without throwing', () => {
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products: [null] };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-003')).toBe(true);
+  });
+
+  it('[blocker] tolerates a string element in products[] without throwing', () => {
+    const cat = { ...VALID_CATALOGUE.products_catalogue, products: ['x'] };
+    const r = validateProductsCatalogue({ ...VALID_CATALOGUE, products_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'PROD-003')).toBe(true);
+  });
+});

package/src/products/index.ts

@@ -0,0 +1,9 @@
+export type {
+  ProductType,
+  ProductStatus,
+  Product,
+  ProductsCatalogueHeader,
+  ProductsCatalogueFile,
+} from './types.js';
+
+export { validateProductsCatalogue } from './validate.js';

package/src/products/types.ts

@@ -0,0 +1,31 @@
+export type ProductType = 'digital_product' | 'service' | 'platform' | 'bundle';
+export type ProductStatus = 'Draft' | 'Active' | 'Deprecated';
+
+export interface Product {
+  product_id: string;
+  name: string;
+  type: ProductType;
+  status: ProductStatus;
+  domain?: string;
+  owner_role?: string;
+  maturity?: number;
+  description?: string;
+  capabilities?: string[];
+  processes?: string[];
+  supporting_apps?: string[];
+}
+
+export interface ProductsCatalogueHeader {
+  id: string;
+  name: string;
+  description?: string;
+  version?: string;
+  updated_at: string;
+  products: Product[];
+}
+
+export interface ProductsCatalogueFile {
+  notation: string;
+  spec_version?: string;
+  products_catalogue: ProductsCatalogueHeader;
+}

package/src/products/validate.ts

@@ -0,0 +1,112 @@
+import type { ProductsCatalogueFile, ProductType, ProductStatus } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+export type { ValidationError, ValidationWarning, ValidationResult };
+
+const VALID_TYPES = new Set<ProductType>(['digital_product', 'service', 'platform', 'bundle']);
+const VALID_STATUSES = new Set<ProductStatus>(['Draft', 'Active', 'Deprecated']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function validateProductsCatalogue(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'PROD-001', message: 'Input must be an object' }], warnings };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  // PROD-001: notation header
+  if (!('notation' in raw)) {
+    errors.push({ code: 'PROD-001', message: 'Missing required field: notation' });
+  } else if (raw['notation'] !== 'products') {
+    errors.push({ code: 'PROD-001', message: `notation must be "products", got "${raw['notation']}"` });
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // PROD-002: catalogue header fields
+  const cat = (raw['products_catalogue'] ?? {}) as Record<string, unknown>;
+  if (!raw['products_catalogue'] || typeof raw['products_catalogue'] !== 'object') {
+    errors.push({ code: 'PROD-002', message: 'Missing required field: products_catalogue' });
+    return { valid: false, errors, warnings };
+  }
+  if (!cat['id'] || typeof cat['id'] !== 'string' || !(cat['id'] as string).trim()) {
+    errors.push({ code: 'PROD-002', message: 'products_catalogue.id is required' });
+  }
+  if (!cat['name'] || typeof cat['name'] !== 'string' || !(cat['name'] as string).trim()) {
+    errors.push({ code: 'PROD-002', message: 'products_catalogue.name is required' });
+  }
+  if (!cat['updated_at'] || typeof cat['updated_at'] !== 'string') {
+    errors.push({ code: 'PROD-002', message: 'products_catalogue.updated_at is required' });
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // PROD-007: updated_at format
+  if (!DATE_RE.test(cat['updated_at'] as string)) {
+    errors.push({ code: 'PROD-007', message: `products_catalogue.updated_at must be YYYY-MM-DD, got "${cat['updated_at']}"` });
+  }
+
+  const products = cat['products'];
+  if (!Array.isArray(products)) {
+    errors.push({ code: 'PROD-002', message: 'products_catalogue.products must be an array' });
+    return { valid: false, errors, warnings };
+  }
+
+  // PROD-008: unique product_id
+  const seenIds = new Set<string>();
+
+  for (let i = 0; i < products.length; i++) {
+    const rawProduct = products[i];
+    const idx = `products[${i}]`;
+
+    if (!rawProduct || typeof rawProduct !== 'object') {
+      errors.push({ code: 'PROD-003', message: `${idx} must be an object` });
+      continue;
+    }
+    const p = rawProduct as Record<string, unknown>;
+
+    // PROD-003: required per-product fields
+    if (!p['product_id'] || typeof p['product_id'] !== 'string' || !(p['product_id'] as string).trim()) {
+      errors.push({ code: 'PROD-003', message: `${idx}: product_id is required` });
+    } else {
+      const pid = p['product_id'] as string;
+      if (seenIds.has(pid)) {
+        errors.push({ code: 'PROD-008', message: `Duplicate product_id: "${pid}"` });
+      }
+      seenIds.add(pid);
+    }
+
+    if (!p['name'] || typeof p['name'] !== 'string' || !(p['name'] as string).trim()) {
+      errors.push({ code: 'PROD-003', message: `${idx}: name is required` });
+    }
+    if (!p['type']) {
+      errors.push({ code: 'PROD-003', message: `${idx}: type is required` });
+    }
+    if (!p['status']) {
+      errors.push({ code: 'PROD-003', message: `${idx}: status is required` });
+    }
+
+    // PROD-004: type enum
+    if (p['type'] && !VALID_TYPES.has(p['type'] as ProductType)) {
+      errors.push({ code: 'PROD-004', message: `${idx}: type "${p['type']}" must be one of: digital_product, service, platform, bundle` });
+    }
+
+    // PROD-005: status enum
+    if (p['status'] && !VALID_STATUSES.has(p['status'] as ProductStatus)) {
+      errors.push({ code: 'PROD-005', message: `${idx}: status "${p['status']}" must be one of: Draft, Active, Deprecated` });
+    }
+
+    // PROD-006: maturity range
+    if (p['maturity'] !== undefined) {
+      const m = p['maturity'];
+      if (typeof m !== 'number' || !Number.isInteger(m) || m < 1 || m > 5) {
+        errors.push({ code: 'PROD-006', message: `${idx}: maturity must be an integer 1–5, got "${m}"` });
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/repo-validate/__tests__/validate-repo.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest';
+import { validateRepoModel } from '../validate-repo.js';
+import type { RepoDoc, RepoModelInput } from '../types.js';
+
+function el(path: string, data: Record<string, unknown> | null, parseError?: string): RepoDoc {
+  return { path, data, parseError };
+}
+
+/** A small clean model mirroring the acme_corp shape: relations use `from`/`to`
+ *  and every endpoint resolves to an element. Should produce zero findings —
+ *  the parity bar against lint.py on the worked example. */
+function cleanModel(): RepoModelInput {
+  return {
+    elements: [
+      el('canon/elements/01_motivation/goals/GOAL-OPS-1.yaml', { notation: 'goal', id: 'GOAL-OPS-1' }),
+      el('canon/elements/01_motivation/assessments/ASSESSMENT-1.yaml', { notation: 'assessment', id: 'ASSESSMENT-1' }),
+      el('canon/elements/02_business/capabilities/CAPABILITY-V1.yaml', { notation: 'capability', id: 'CAPABILITY-V1' }),
+      // sidecar with no `id` — must be ignored (no duplicate, not an element)
+      el('canon/elements/02_business/capabilities/CAPABILITY-V1.history.yaml', { target: 'CAPABILITY-V1', attribute_versions: [] }),
+    ],
+    relations: [
+      el('canon/relations/REL-1.yaml', { notation: 'relation', id: 'REL-1', from: 'ASSESSMENT-1', to: 'GOAL-OPS-1' }),
+    ],
+  };
+}
+
+describe('validateRepoModel — parity / clean tree', () => {
+  it('produces zero findings on a clean model (acme_corp parity)', () => {
+    expect(validateRepoModel(cleanModel())).toEqual([]);
+  });
+
+  it('ignores sidecar docs without an id (no false duplicate)', () => {
+    const findings = validateRepoModel(cleanModel());
+    expect(findings.filter((f) => f.message.includes('Duplicate'))).toEqual([]);
+  });
+
+  it('every finding carries the frozen { scope, id, message } shape', () => {
+    const model = cleanModel();
+    model.relations.push(el('canon/relations/REL-BAD.yaml', { notation: 'relation', id: 'REL-BAD', from: 'NOPE', to: 'GOAL-OPS-1' }));
+    const findings = validateRepoModel(model);
+    expect(findings.length).toBeGreaterThan(0);
+    for (const f of findings) {
+      expect(Object.keys(f).sort()).toEqual(['id', 'message', 'scope']);
+      expect(f.scope).toBe('repo');
+    }
+  });
+});
+
+describe('validateRepoModel — referential integrity', () => {
+  it('flags a relation whose `from` endpoint is unknown', () => {
+    const model = cleanModel();
+    model.relations = [el('canon/relations/REL-X.yaml', { notation: 'relation', id: 'REL-X', from: 'MISSING-1', to: 'GOAL-OPS-1' })];
+    const findings = validateRepoModel(model);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ scope: 'repo', id: 'REL-X' });
+    expect(findings[0].message).toContain('MISSING-1');
+    expect(findings[0].message).toContain('(from)');
+  });
+
+  it('flags a relation whose `to` endpoint is unknown', () => {
+    const model = cleanModel();
+    model.relations = [el('canon/relations/REL-Y.yaml', { notation: 'relation', id: 'REL-Y', from: 'GOAL-OPS-1', to: 'MISSING-2' })];
+    const findings = validateRepoModel(model);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].message).toContain('(to)');
+  });
+
+  it('accepts lint.py-style `source`/`target` endpoint keys', () => {
+    const model = cleanModel();
+    model.relations = [el('canon/relations/REL-ST.yaml', { id: 'REL-ST', source: 'ASSESSMENT-1', target: 'GOAL-OPS-1' })];
+    expect(validateRepoModel(model)).toEqual([]);
+  });
+
+  it('resolves `{ id }` object endpoints', () => {
+    const model = cleanModel();
+    model.relations = [el('canon/relations/REL-OBJ.yaml', { id: 'REL-OBJ', from: { id: 'ASSESSMENT-1' }, to: { id: 'GOAL-OPS-1' } })];
+    expect(validateRepoModel(model)).toEqual([]);
+  });
+});
+
+describe('validateRepoModel — atomicity', () => {
+  it('flags an element file that contains an inline `relations` section', () => {
+    const model = cleanModel();
+    model.elements.push(el('canon/elements/02_business/E.yaml', { id: 'ELEMENT-1', relations: [{ to: 'GOAL-OPS-1' }] }));
+    const findings = validateRepoModel(model);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ scope: 'repo', id: 'ELEMENT-1' });
+    expect(findings[0].message).toContain('Atomicity');
+  });
+});
+
+describe('validateRepoModel — id uniqueness', () => {
+  it('flags the same id defined in two files', () => {
+    const model = cleanModel();
+    model.elements.push(el('canon/elements/dupe-a.yaml', { id: 'DUP-1' }));
+    model.elements.push(el('canon/elements/dupe-b.yaml', { id: 'DUP-1' }));
+    const findings = validateRepoModel(model);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ scope: 'repo', id: 'DUP-1' });
+    expect(findings[0].message).toContain('dupe-a.yaml');
+    expect(findings[0].message).toContain('dupe-b.yaml');
+  });
+
+  it('flags an element/relation id collision across zones', () => {
+    const model = cleanModel();
+    model.elements.push(el('canon/elements/clash.yaml', { id: 'CLASH-1' }));
+    model.relations.push(el('canon/relations/clash.yaml', { id: 'CLASH-1', from: 'GOAL-OPS-1', to: 'ASSESSMENT-1' }));
+    const findings = validateRepoModel(model);
+    expect(findings.filter((f) => f.id === 'CLASH-1')).toHaveLength(1);
+  });
+});
+
+describe('validateRepoModel — policy', () => {
+  it('flags an Active element with no owner', () => {
+    const model = cleanModel();
+    model.elements.push(el('canon/elements/svc.yaml', { id: 'SVC-1', metadata: { status: 'Active' } }));
+    const findings = validateRepoModel(model);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ scope: 'repo', id: 'SVC-1' });
+    expect(findings[0].message).toContain('Policy');
+  });
+
+  it('does not flag an Active element that has an owner', () => {
+    const model = cleanModel();
+    model.elements.push(el('canon/elements/svc.yaml', { id: 'SVC-2', metadata: { status: 'Active', owner: 'team-a' } }));
+    expect(validateRepoModel(model)).toEqual([]);
+  });
+
+  it('does not flag elements using the canon admission record (no metadata.status)', () => {
+    // acme_corp elements use `zone`/`admitted_by`, not `metadata.status` — must not fire.
+    const model = cleanModel();
+    model.elements.push(el('canon/elements/g.yaml', { id: 'GOAL-X', zone: 'canon', admitted_by: 'v.korobeinikov' }));
+    expect(validateRepoModel(model)).toEqual([]);
+  });
+});
+
+describe('validateRepoModel — syntax', () => {
+  it('reports a parse error and skips graph checks', () => {
+    const model = cleanModel();
+    model.elements.push(el('canon/elements/broken.yaml', null, 'bad indentation'));
+    // also add a dangling relation that would otherwise fire — it must be suppressed
+    model.relations.push(el('canon/relations/REL-Z.yaml', { id: 'REL-Z', from: 'MISSING', to: 'GOAL-OPS-1' }));
+    const findings = validateRepoModel(model);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ scope: 'repo', id: '' });
+    expect(findings[0].message).toContain('YAML syntax error');
+    expect(findings[0].message).toContain('broken.yaml');
+  });
+});