@transitrix/diagrams 1.0.0 → 1.1.0

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

@@ -1,196 +1,196 @@
-// Repo-scope validator (vkgeorgia/transitrix-studio#141).
-//
-// Pure port of the whole-repo checks owned by the methodology's
-// `.validators/lint.py`, run over the shared TypeScript model instead of Python.
-// Parity reference: the `acme_corp` worked example, which `lint.py` passes with
-// zero findings — this validator must also produce zero findings on it.
-//
-// Ported checks (mirroring lint.py's phases):
-//   1. YAML syntax        (phase 1) — unparseable canon file -> finding.
-//   2. ID uniqueness                — same `id` defined in >1 file -> finding.
-//                                     (lint.py silently last-wins; we surface it,
-//                                      but acme_corp has no duplicates, so parity
-//                                      holds on the reference fixture.)
-//   3. Atomicity          (phase 3) — element file carrying a `relations:` key.
-//   4. Referential integ. (phase 4) — relation endpoint not resolving to a known
-//                                     element id. We resolve the canonical
-//                                     `from`/`to` keys (the real relation schema)
-//                                     and also accept lint.py's `source`/`target`.
-//   5. Semantic rules     (phase 5) — ArchiMate layer-semantics. lint.py ships
-//                                     this as a no-op stub; ported faithfully as a
-//                                     no-op (see `checkLayerSemantics`). Deferred
-//                                     until the methodology defines the rules.
-//   6. Policy             (phase 6) — element marked Active/Production with no
-//                                     owner.
-//
-// Findings stay `{ scope, id, message }` — no severity, no target/category
-// taxonomy (deferred per the ADR).
-
-import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
-
-const PScope: RepoFinding['scope'] = 'repo';
-
-/** Statuses that, per lint.py's policy check, require an owner. */
-const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
-
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-
-/** Read a string `id` from a parsed doc, or `null` if absent/non-string.
- *  Mirrors lint.py, which only treats a doc as an element/relation when it has
- *  a top-level `id` (sidecars such as versioned-attribute files have no `id`
- *  and are ignored). */
-function docId(doc: RepoDoc): string | null {
-  if (!doc.data) return null;
-  const id = doc.data['id'];
-  return typeof id === 'string' && id.length > 0 ? id : null;
-}
-
-/** Resolve a relation endpoint, which may be a bare id string or a `{ id }`
- *  mapping (lint.py accepts both). Returns the id string or `null`. */
-function endpointId(value: unknown): string | null {
-  if (typeof value === 'string') return value.length > 0 ? value : null;
-  if (isRecord(value)) {
-    const id = value['id'];
-    if (typeof id === 'string' && id.length > 0) return id;
-  }
-  return null;
-}
-
-/** Phase 1 — unparseable canon files surface as findings. */
-function checkSyntax(docs: RepoDoc[], findings: RepoFinding[]): void {
-  for (const doc of docs) {
-    if (doc.parseError) {
-      findings.push({
-        scope: PScope,
-        id: '',
-        message: `YAML syntax error in ${doc.path}: ${doc.parseError}`,
-      });
-    }
-  }
-}
-
-/** Phase 2 (as a check) — the same id defined in more than one file. */
-function checkIdUniqueness(input: RepoModelInput, findings: RepoFinding[]): void {
-  const filesById = new Map<string, string[]>();
-  for (const doc of [...input.elements, ...input.relations]) {
-    const id = docId(doc);
-    if (!id) continue;
-    const list = filesById.get(id);
-    if (list) list.push(doc.path);
-    else filesById.set(id, [doc.path]);
-  }
-  for (const [id, files] of filesById) {
-    if (files.length > 1) {
-      findings.push({
-        scope: PScope,
-        id,
-        message: `Duplicate id '${id}' defined in ${files.length} files: ${files.join(', ')}`,
-      });
-    }
-  }
-}
-
-/** Phase 3 — relations must live in their own files, not inline on elements. */
-function checkAtomicity(input: RepoModelInput, findings: RepoFinding[]): void {
-  for (const doc of input.elements) {
-    const id = docId(doc);
-    if (id && doc.data && 'relations' in doc.data) {
-      findings.push({
-        scope: PScope,
-        id,
-        message:
-          `Atomicity violation: element '${id}' (${doc.path}) contains a ` +
-          `'relations' section. Move relations to separate files under canon/relations/.`,
-      });
-    }
-  }
-}
-
-/** Phase 4 — every relation endpoint must resolve to a known element id. */
-function checkReferentialIntegrity(input: RepoModelInput, findings: RepoFinding[]): void {
-  const elementIds = new Set<string>();
-  for (const doc of input.elements) {
-    const id = docId(doc);
-    if (id) elementIds.add(id);
-  }
-
-  for (const doc of input.relations) {
-    if (!doc.data) continue;
-    const relId = docId(doc) ?? '';
-    // Canonical relation schema uses `from`/`to`; `source`/`target` accepted for
-    // lint.py compatibility.
-    const fromId = endpointId(doc.data['from']) ?? endpointId(doc.data['source']);
-    const toId = endpointId(doc.data['to']) ?? endpointId(doc.data['target']);
-
-    if (fromId && !elementIds.has(fromId)) {
-      findings.push({
-        scope: PScope,
-        id: relId,
-        message: `Referential integrity: relation '${relId || doc.path}' endpoint '${fromId}' (from) does not resolve to a known element.`,
-      });
-    }
-    if (toId && !elementIds.has(toId)) {
-      findings.push({
-        scope: PScope,
-        id: relId,
-        message: `Referential integrity: relation '${relId || doc.path}' endpoint '${toId}' (to) does not resolve to a known element.`,
-      });
-    }
-  }
-}
-
-/** Phase 5 — ArchiMate layer-semantics on relations.
- *
- * lint.py ships `_check_semantic_rules` as a no-op stub (`pass`). It is ported
- * here faithfully as a no-op so repo-scope validation reaches parity with
- * lint.py on the reference fixture. Real layer-semantics rules are DEFERRED
- * until the methodology defines them; when it does, they land here (a relation
- * whose `type` is illegal between its endpoints' ArchiMate layers). Kept as a
- * named hook so the intent — and the gap — is explicit rather than missing. */
-function checkLayerSemantics(_input: RepoModelInput, _findings: RepoFinding[]): void {
-  // Intentionally empty — parity with lint.py's stubbed phase 5. Do not add
-  // rules here without coordinating the methodology semantics canon.
-}
-
-/** Phase 6 — an element that is Active/Production must declare an owner. */
-function checkPolicy(input: RepoModelInput, findings: RepoFinding[]): void {
-  for (const doc of input.elements) {
-    const id = docId(doc);
-    if (!id || !doc.data) continue;
-    const metadata = doc.data['metadata'];
-    if (!isRecord(metadata)) continue;
-    const status = metadata['status'];
-    const owner = metadata['owner'];
-    if (typeof status === 'string' && OWNER_REQUIRED_STATUSES.has(status) && !owner) {
-      findings.push({
-        scope: PScope,
-        id,
-        message: `Policy: element '${id}' has status '${status}' but no owner assigned.`,
-      });
-    }
-  }
-}
-
-/**
- * Run all repo-scope checks over a loaded canon model and return the findings.
- * Pure: no IO, deterministic order (syntax, uniqueness, atomicity, referential,
- * semantics, policy). Reaches parity with `lint.py` on the `acme_corp` fixture
- * (zero findings on a clean tree).
- */
-export function validateRepoModel(input: RepoModelInput): RepoFinding[] {
-  const findings: RepoFinding[] = [];
-  checkSyntax([...input.elements, ...input.relations], findings);
-  // A syntax error means the model is not reliably loaded; skip the graph checks
-  // and report the syntax problems first (mirrors lint.py, which bails after
-  // phase 1 on syntax errors).
-  if (findings.length > 0) return findings;
-
-  checkIdUniqueness(input, findings);
-  checkAtomicity(input, findings);
-  checkReferentialIntegrity(input, findings);
-  checkLayerSemantics(input, findings);
-  checkPolicy(input, findings);
-  return findings;
-}
+// Repo-scope validator (vkgeorgia/transitrix-studio#141).
+//
+// Pure port of the whole-repo checks owned by the methodology's
+// `.validators/lint.py`, run over the shared TypeScript model instead of Python.
+// Parity reference: the `acme_corp` worked example, which `lint.py` passes with
+// zero findings — this validator must also produce zero findings on it.
+//
+// Ported checks (mirroring lint.py's phases):
+//   1. YAML syntax        (phase 1) — unparseable canon file -> finding.
+//   2. ID uniqueness                — same `id` defined in >1 file -> finding.
+//                                     (lint.py silently last-wins; we surface it,
+//                                      but acme_corp has no duplicates, so parity
+//                                      holds on the reference fixture.)
+//   3. Atomicity          (phase 3) — element file carrying a `relations:` key.
+//   4. Referential integ. (phase 4) — relation endpoint not resolving to a known
+//                                     element id. We resolve the canonical
+//                                     `from`/`to` keys (the real relation schema)
+//                                     and also accept lint.py's `source`/`target`.
+//   5. Semantic rules     (phase 5) — ArchiMate layer-semantics. lint.py ships
+//                                     this as a no-op stub; ported faithfully as a
+//                                     no-op (see `checkLayerSemantics`). Deferred
+//                                     until the methodology defines the rules.
+//   6. Policy             (phase 6) — element marked Active/Production with no
+//                                     owner.
+//
+// Findings stay `{ scope, id, message }` — no severity, no target/category
+// taxonomy (deferred per the ADR).
+
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+
+const PScope: RepoFinding['scope'] = 'repo';
+
+/** Statuses that, per lint.py's policy check, require an owner. */
+const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Read a string `id` from a parsed doc, or `null` if absent/non-string.
+ *  Mirrors lint.py, which only treats a doc as an element/relation when it has
+ *  a top-level `id` (sidecars such as versioned-attribute files have no `id`
+ *  and are ignored). */
+function docId(doc: RepoDoc): string | null {
+  if (!doc.data) return null;
+  const id = doc.data['id'];
+  return typeof id === 'string' && id.length > 0 ? id : null;
+}
+
+/** Resolve a relation endpoint, which may be a bare id string or a `{ id }`
+ *  mapping (lint.py accepts both). Returns the id string or `null`. */
+function endpointId(value: unknown): string | null {
+  if (typeof value === 'string') return value.length > 0 ? value : null;
+  if (isRecord(value)) {
+    const id = value['id'];
+    if (typeof id === 'string' && id.length > 0) return id;
+  }
+  return null;
+}
+
+/** Phase 1 — unparseable canon files surface as findings. */
+function checkSyntax(docs: RepoDoc[], findings: RepoFinding[]): void {
+  for (const doc of docs) {
+    if (doc.parseError) {
+      findings.push({
+        scope: PScope,
+        id: '',
+        message: `YAML syntax error in ${doc.path}: ${doc.parseError}`,
+      });
+    }
+  }
+}
+
+/** Phase 2 (as a check) — the same id defined in more than one file. */
+function checkIdUniqueness(input: RepoModelInput, findings: RepoFinding[]): void {
+  const filesById = new Map<string, string[]>();
+  for (const doc of [...input.elements, ...input.relations]) {
+    const id = docId(doc);
+    if (!id) continue;
+    const list = filesById.get(id);
+    if (list) list.push(doc.path);
+    else filesById.set(id, [doc.path]);
+  }
+  for (const [id, files] of filesById) {
+    if (files.length > 1) {
+      findings.push({
+        scope: PScope,
+        id,
+        message: `Duplicate id '${id}' defined in ${files.length} files: ${files.join(', ')}`,
+      });
+    }
+  }
+}
+
+/** Phase 3 — relations must live in their own files, not inline on elements. */
+function checkAtomicity(input: RepoModelInput, findings: RepoFinding[]): void {
+  for (const doc of input.elements) {
+    const id = docId(doc);
+    if (id && doc.data && 'relations' in doc.data) {
+      findings.push({
+        scope: PScope,
+        id,
+        message:
+          `Atomicity violation: element '${id}' (${doc.path}) contains a ` +
+          `'relations' section. Move relations to separate files under canon/relations/.`,
+      });
+    }
+  }
+}
+
+/** Phase 4 — every relation endpoint must resolve to a known element id. */
+function checkReferentialIntegrity(input: RepoModelInput, findings: RepoFinding[]): void {
+  const elementIds = new Set<string>();
+  for (const doc of input.elements) {
+    const id = docId(doc);
+    if (id) elementIds.add(id);
+  }
+
+  for (const doc of input.relations) {
+    if (!doc.data) continue;
+    const relId = docId(doc) ?? '';
+    // Canonical relation schema uses `from`/`to`; `source`/`target` accepted for
+    // lint.py compatibility.
+    const fromId = endpointId(doc.data['from']) ?? endpointId(doc.data['source']);
+    const toId = endpointId(doc.data['to']) ?? endpointId(doc.data['target']);
+
+    if (fromId && !elementIds.has(fromId)) {
+      findings.push({
+        scope: PScope,
+        id: relId,
+        message: `Referential integrity: relation '${relId || doc.path}' endpoint '${fromId}' (from) does not resolve to a known element.`,
+      });
+    }
+    if (toId && !elementIds.has(toId)) {
+      findings.push({
+        scope: PScope,
+        id: relId,
+        message: `Referential integrity: relation '${relId || doc.path}' endpoint '${toId}' (to) does not resolve to a known element.`,
+      });
+    }
+  }
+}
+
+/** Phase 5 — ArchiMate layer-semantics on relations.
+ *
+ * lint.py ships `_check_semantic_rules` as a no-op stub (`pass`). It is ported
+ * here faithfully as a no-op so repo-scope validation reaches parity with
+ * lint.py on the reference fixture. Real layer-semantics rules are DEFERRED
+ * until the methodology defines them; when it does, they land here (a relation
+ * whose `type` is illegal between its endpoints' ArchiMate layers). Kept as a
+ * named hook so the intent — and the gap — is explicit rather than missing. */
+function checkLayerSemantics(_input: RepoModelInput, _findings: RepoFinding[]): void {
+  // Intentionally empty — parity with lint.py's stubbed phase 5. Do not add
+  // rules here without coordinating the methodology semantics canon.
+}
+
+/** Phase 6 — an element that is Active/Production must declare an owner. */
+function checkPolicy(input: RepoModelInput, findings: RepoFinding[]): void {
+  for (const doc of input.elements) {
+    const id = docId(doc);
+    if (!id || !doc.data) continue;
+    const metadata = doc.data['metadata'];
+    if (!isRecord(metadata)) continue;
+    const status = metadata['status'];
+    const owner = metadata['owner'];
+    if (typeof status === 'string' && OWNER_REQUIRED_STATUSES.has(status) && !owner) {
+      findings.push({
+        scope: PScope,
+        id,
+        message: `Policy: element '${id}' has status '${status}' but no owner assigned.`,
+      });
+    }
+  }
+}
+
+/**
+ * Run all repo-scope checks over a loaded canon model and return the findings.
+ * Pure: no IO, deterministic order (syntax, uniqueness, atomicity, referential,
+ * semantics, policy). Reaches parity with `lint.py` on the `acme_corp` fixture
+ * (zero findings on a clean tree).
+ */
+export function validateRepoModel(input: RepoModelInput): RepoFinding[] {
+  const findings: RepoFinding[] = [];
+  checkSyntax([...input.elements, ...input.relations], findings);
+  // A syntax error means the model is not reliably loaded; skip the graph checks
+  // and report the syntax problems first (mirrors lint.py, which bails after
+  // phase 1 on syntax errors).
+  if (findings.length > 0) return findings;
+
+  checkIdUniqueness(input, findings);
+  checkAtomicity(input, findings);
+  checkReferentialIntegrity(input, findings);
+  checkLayerSemantics(input, findings);
+  checkPolicy(input, findings);
+  return findings;
+}

package/src/requirement/__tests__/example.test.ts

@@ -1,24 +1,24 @@
-// Conformance test for the shipped REQUIREMENT worked examples — the
-// acme_corp canon files mirrored under `tests/fixtures/notation-corpus/requirement/`. Pins the
-// success signal of vkgeorgia/strategy#84 Phase 1: the library consumes the
-// canonical example files without error.
-
-import { describe, it, expect } from 'vitest';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-import yaml from 'js-yaml';
-import { validateRequirement } from '../validate.js';
-
-const dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus/requirement');
-const load = (f: string): unknown => yaml.load(readFileSync(path.join(dir, f), 'utf-8'));
-
-describe('requirement worked examples (acme_corp)', () => {
-  for (const f of ['REQUIREMENT-DATA-ERASURE-1.yaml', 'REQUIREMENT-AUDIT-LOG-RETENTION-1.yaml']) {
-    it(`validates ${f} without error`, () => {
-      const v = validateRequirement(load(f));
-      expect(v.valid, JSON.stringify(v.errors)).toBe(true);
-      expect(v.errors).toHaveLength(0);
-    });
-  }
-});
+// Conformance test for the shipped REQUIREMENT worked examples — the
+// acme_corp canon files mirrored under `tests/fixtures/notation-corpus/requirement/`. Pins the
+// success signal of vkgeorgia/strategy#84 Phase 1: the library consumes the
+// canonical example files without error.
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { validateRequirement } from '../validate.js';
+
+const dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus/requirement');
+const load = (f: string): unknown => yaml.load(readFileSync(path.join(dir, f), 'utf-8'));
+
+describe('requirement worked examples (acme_corp)', () => {
+  for (const f of ['REQUIREMENT-DATA-ERASURE-1.yaml', 'REQUIREMENT-AUDIT-LOG-RETENTION-1.yaml']) {
+    it(`validates ${f} without error`, () => {
+      const v = validateRequirement(load(f));
+      expect(v.valid, JSON.stringify(v.errors)).toBe(true);
+      expect(v.errors).toHaveLength(0);
+    });
+  }
+});

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

@@ -1,96 +1,96 @@
-import { describe, it, expect } from 'vitest';
-import { validateRequirement } from '../validate.js';
-import type { CanonCatalog } from '../../typed-id.js';
-
-function valid(): Record<string, unknown> {
-  return {
-    notation: 'requirement',
-    id: 'REQUIREMENT-DATA-ERASURE-1',
-    name: 'Personal-data erasure within 30 days',
-    description: 'The controller must erase personal data within 30 days of a verified request.',
-    severity: 'high',
-    zone: 'canon',
-    admitted_at: '2026-05-28',
-    admitted_by: 'v.korobeinikov',
-    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
-    valid_from: '2017-05-01',
-    valid_to: null,
-  };
-}
-
-const codes = (input: unknown, opts?: Parameters<typeof validateRequirement>[1]): string[] =>
-  validateRequirement(input, opts).errors.map(e => e.code);
-
-describe('validateRequirement — positive', () => {
-  it('accepts a well-formed requirement', () => {
-    const r = validateRequirement(valid());
-    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
-    expect(r.errors).toHaveLength(0);
-  });
-
-  it('accepts an internal-only requirement with no derived_from', () => {
-    const r = valid();
-    delete r.derived_from;
-    r.severity = 'medium';
-    expect(validateRequirement(r).valid).toBe(true);
-  });
-});
-
-describe('validateRequirement — REQ-001 (shape / id grammar)', () => {
-  it('flags a missing required field', () => {
-    const r = valid();
-    delete r.name;
-    expect(codes(r)).toContain('REQ-001');
-  });
-
-  it('flags an id that violates the grammar', () => {
-    expect(codes({ ...valid(), id: 'REQUIREMENT-DATA-ERASURE-001' })).toContain('REQ-001'); // leading zero
-    expect(codes({ ...valid(), id: 'REQ-1' })).toContain('REQ-001'); // wrong TYPE
-    expect(codes({ ...valid(), id: 'requirement-data-1' })).toContain('REQ-001'); // lowercase TYPE
-  });
-
-  it('flags a wrong notation tag and a non-canon zone', () => {
-    expect(codes({ ...valid(), notation: 'req' })).toContain('REQ-001');
-    expect(codes({ ...valid(), zone: 'sandbox' })).toContain('REQ-001');
-  });
-
-  it('flags a missing valid_to key (distinct from a null value)', () => {
-    const r = valid();
-    delete r.valid_to;
-    expect(codes(r)).toContain('REQ-001');
-    expect(validateRequirement({ ...valid(), valid_to: null }).valid).toBe(true);
-  });
-
-  it('rejects a non-object', () => {
-    expect(codes(null)).toEqual(['REQ-001']);
-    expect(codes('x')).toEqual(['REQ-001']);
-    expect(codes(['a'])).toEqual(['REQ-001']);
-  });
-});
-
-describe('validateRequirement — REQ-002 (derived_from resolution)', () => {
-  it('flags a well-formed allowed-type ref that does not resolve in the catalog', () => {
-    const catalog: CanonCatalog = { typeOf: () => undefined };
-    expect(codes({ ...valid(), derived_from: ['LAW-PERSONAL-DATA-2017-1'] }, { catalog })).toContain('REQ-002');
-  });
-
-  it('flags a malformed derived_from entry (cannot resolve)', () => {
-    expect(codes({ ...valid(), derived_from: ['not an id'] })).toContain('REQ-002');
-  });
-
-  it('does not flag REQ-002 without a catalog for a well-formed allowed-type ref', () => {
-    expect(codes({ ...valid(), derived_from: ['LAW-PERSONAL-DATA-2017-1'] })).not.toContain('REQ-002');
-  });
-});
-
-describe('validateRequirement — REQ-003 (derived_from TYPE)', () => {
-  it('flags a derived_from TYPE outside LAW/REGULATION/POLICY/INTERNAL_STANDARD', () => {
-    expect(codes({ ...valid(), derived_from: ['PRODUCT-MOBILE-1'] })).toContain('REQ-003');
-  });
-
-  it('accepts each permitted derived_from TYPE', () => {
-    for (const id of ['LAW-X-1', 'REGULATION-X-1', 'POLICY-X-1', 'INTERNAL_STANDARD-X-1']) {
-      expect(codes({ ...valid(), derived_from: [id] })).not.toContain('REQ-003');
-    }
-  });
-});
+import { describe, it, expect } from 'vitest';
+import { validateRequirement } from '../validate.js';
+import type { CanonCatalog } from '../../typed-id.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'requirement',
+    id: 'REQUIREMENT-DATA-ERASURE-1',
+    name: 'Personal-data erasure within 30 days',
+    description: 'The controller must erase personal data within 30 days of a verified request.',
+    severity: 'high',
+    zone: 'canon',
+    admitted_at: '2026-05-28',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2017-05-01',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown, opts?: Parameters<typeof validateRequirement>[1]): string[] =>
+  validateRequirement(input, opts).errors.map(e => e.code);
+
+describe('validateRequirement — positive', () => {
+  it('accepts a well-formed requirement', () => {
+    const r = validateRequirement(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('accepts an internal-only requirement with no derived_from', () => {
+    const r = valid();
+    delete r.derived_from;
+    r.severity = 'medium';
+    expect(validateRequirement(r).valid).toBe(true);
+  });
+});
+
+describe('validateRequirement — REQ-001 (shape / id grammar)', () => {
+  it('flags a missing required field', () => {
+    const r = valid();
+    delete r.name;
+    expect(codes(r)).toContain('REQ-001');
+  });
+
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'REQUIREMENT-DATA-ERASURE-001' })).toContain('REQ-001'); // leading zero
+    expect(codes({ ...valid(), id: 'REQ-1' })).toContain('REQ-001'); // wrong TYPE
+    expect(codes({ ...valid(), id: 'requirement-data-1' })).toContain('REQ-001'); // lowercase TYPE
+  });
+
+  it('flags a wrong notation tag and a non-canon zone', () => {
+    expect(codes({ ...valid(), notation: 'req' })).toContain('REQ-001');
+    expect(codes({ ...valid(), zone: 'sandbox' })).toContain('REQ-001');
+  });
+
+  it('flags a missing valid_to key (distinct from a null value)', () => {
+    const r = valid();
+    delete r.valid_to;
+    expect(codes(r)).toContain('REQ-001');
+    expect(validateRequirement({ ...valid(), valid_to: null }).valid).toBe(true);
+  });
+
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['REQ-001']);
+    expect(codes('x')).toEqual(['REQ-001']);
+    expect(codes(['a'])).toEqual(['REQ-001']);
+  });
+});
+
+describe('validateRequirement — REQ-002 (derived_from resolution)', () => {
+  it('flags a well-formed allowed-type ref that does not resolve in the catalog', () => {
+    const catalog: CanonCatalog = { typeOf: () => undefined };
+    expect(codes({ ...valid(), derived_from: ['LAW-PERSONAL-DATA-2017-1'] }, { catalog })).toContain('REQ-002');
+  });
+
+  it('flags a malformed derived_from entry (cannot resolve)', () => {
+    expect(codes({ ...valid(), derived_from: ['not an id'] })).toContain('REQ-002');
+  });
+
+  it('does not flag REQ-002 without a catalog for a well-formed allowed-type ref', () => {
+    expect(codes({ ...valid(), derived_from: ['LAW-PERSONAL-DATA-2017-1'] })).not.toContain('REQ-002');
+  });
+});
+
+describe('validateRequirement — REQ-003 (derived_from TYPE)', () => {
+  it('flags a derived_from TYPE outside LAW/REGULATION/POLICY/INTERNAL_STANDARD', () => {
+    expect(codes({ ...valid(), derived_from: ['PRODUCT-MOBILE-1'] })).toContain('REQ-003');
+  });
+
+  it('accepts each permitted derived_from TYPE', () => {
+    for (const id of ['LAW-X-1', 'REGULATION-X-1', 'POLICY-X-1', 'INTERNAL_STANDARD-X-1']) {
+      expect(codes({ ...valid(), derived_from: [id] })).not.toContain('REQ-003');
+    }
+  });
+});

package/src/requirement/index.ts

@@ -1,4 +1,4 @@
-export type { Requirement, RequirementSeverity, GateChecks } from './types.js';
-export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
-export { validateRequirement } from './validate.js';
-export type { RequirementValidateOptions } from './validate.js';
+export type { Requirement, RequirementSeverity, GateChecks } from './types.js';
+export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+export { validateRequirement } from './validate.js';
+export type { RequirementValidateOptions } from './validate.js';