@transitrix/diagrams 1.0.0

package/src/compliance/__tests__/demo-scenario.test.ts

@@ -0,0 +1,273 @@
+// Conformance test for the NorthBay Retail EU compliance demo scenario
+// (strategy hub #178). Validates that the demo data files load without errors,
+// produce the expected matrix shape, and exercise all four compliance statuses.
+
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { buildComplianceIndex } from '../reverse-index.js';
+import { buildLawTree, buildProductView } from '../views.js';
+import { buildGapReport } from '../gap-report.js';
+import { parseImpactViewConfig, buildImpactMatrix } from '../impact.js';
+import { emptyCanon, ingestComplianceDoc } from '../classify.js';
+import type { IndexAssertion, IndexRequirement, ComplianceIndex } from '../types.js';
+
+const EXAMPLES = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus');
+
+function loadYamlDir(dir: string): Record<string, unknown>[] {
+  const full = path.join(EXAMPLES, dir);
+  return readdirSync(full)
+    .filter(f => f.endsWith('.yaml'))
+    .map(f => yaml.load(readFileSync(path.join(full, f), 'utf-8')) as Record<string, unknown>);
+}
+
+function loadYamlFile(relPath: string): unknown {
+  return yaml.load(readFileSync(path.join(EXAMPLES, relPath), 'utf-8'));
+}
+
+// ── Build the demo canon ─────────────────────────────────────────────────────
+
+const requirements: IndexRequirement[] = loadYamlDir('compliance/requirements').map(r => ({
+  id: String(r.id),
+  name: String(r.name),
+  severity: r.severity as string | undefined,
+  derived_from: Array.isArray(r.derived_from) ? (r.derived_from as string[]) : undefined,
+  deadline: typeof r.deadline === 'string' ? r.deadline : undefined,
+}));
+
+const assertions: IndexAssertion[] = loadYamlDir('compliance/assertions').map(a => ({
+  id: String(a.id),
+  about: String(a.about),
+  subject: String(a.subject),
+  status: a.status as IndexAssertion['status'],
+  realised_via: Array.isArray(a.realised_via) ? (a.realised_via as string[]) : undefined,
+  assessed_at: typeof a.assessed_at === 'string' ? a.assessed_at : undefined,
+  next_review_at: typeof a.next_review_at === 'string' ? a.next_review_at : undefined,
+  evidenceCount: Array.isArray(a.evidence) ? (a.evidence as unknown[]).length : 0,
+}));
+
+const index: ComplianceIndex = buildComplianceIndex({ requirements, assertions });
+
+// ── Demo data integrity ──────────────────────────────────────────────────────
+
+describe('demo scenario — data integrity', () => {
+  it('loads 5 requirements from the demo scenario', () => {
+    expect(requirements).toHaveLength(5);
+    const ids = requirements.map(r => r.id).sort();
+    expect(ids).toEqual([
+      'REQUIREMENT-GDPR-CONSENT-1',
+      'REQUIREMENT-GDPR-DATA-ERASURE-1',
+      'REQUIREMENT-GDPR-PORTABILITY-1',
+      'REQUIREMENT-NIS2-INCIDENT-REPORT-1',
+      'REQUIREMENT-NIS2-SUPPLY-CHAIN-1',
+    ]);
+  });
+
+  it('loads 5 assertions covering all four compliance statuses', () => {
+    expect(assertions).toHaveLength(5);
+    const statuses = assertions.map(a => a.status).sort();
+    expect(statuses).toContain('compliant');
+    expect(statuses).toContain('partial');
+    expect(statuses).toContain('non_compliant');
+    expect(statuses).toContain('under_review');
+  });
+
+  it('requirements have deadline fields on 3 of 5', () => {
+    const withDeadline = requirements.filter(r => r.deadline != null);
+    expect(withDeadline).toHaveLength(3);
+    const ids = withDeadline.map(r => r.id).sort();
+    expect(ids).toEqual([
+      'REQUIREMENT-GDPR-CONSENT-1',
+      'REQUIREMENT-GDPR-DATA-ERASURE-1',
+      'REQUIREMENT-NIS2-INCIDENT-REPORT-1',
+    ]);
+  });
+
+  it('REQUIREMENT-GDPR-DATA-ERASURE-1 has a past-due deadline', () => {
+    const req = requirements.find(r => r.id === 'REQUIREMENT-GDPR-DATA-ERASURE-1');
+    expect(req?.deadline).toBe('2025-12-31');
+    // 2025-12-31 is in the past relative to any 2026+ date
+    expect(req!.deadline! < '2026-01-01').toBe(true);
+  });
+});
+
+// ── Single-law trees ─────────────────────────────────────────────────────────
+
+describe('single-law tree — LAW-GDPR-1', () => {
+  const tree = buildLawTree('LAW-GDPR-1', index);
+
+  it('has 3 GDPR requirements', () => {
+    expect(tree.requirements).toHaveLength(3);
+    const ids = tree.requirements.map(r => r.requirement.id).sort();
+    expect(ids).toEqual([
+      'REQUIREMENT-GDPR-CONSENT-1',
+      'REQUIREMENT-GDPR-DATA-ERASURE-1',
+      'REQUIREMENT-GDPR-PORTABILITY-1',
+    ]);
+  });
+
+  it('erasure requirement has 2 assertions (one per product)', () => {
+    const erasure = tree.requirements.find(r => r.requirement.id === 'REQUIREMENT-GDPR-DATA-ERASURE-1');
+    expect(erasure).toBeDefined();
+    expect(erasure!.assertions).toHaveLength(2);
+    const statuses = erasure!.assertions.map(a => a.status).sort();
+    expect(statuses).toEqual(['compliant', 'non_compliant']);
+  });
+
+  it('consent requirement has exactly one partial assertion', () => {
+    const consent = tree.requirements.find(r => r.requirement.id === 'REQUIREMENT-GDPR-CONSENT-1');
+    expect(consent!.assertions).toHaveLength(1);
+    expect(consent!.assertions[0].status).toBe('partial');
+  });
+
+  it('portability requirement is compliant', () => {
+    const portability = tree.requirements.find(r => r.requirement.id === 'REQUIREMENT-GDPR-PORTABILITY-1');
+    expect(portability!.assertions).toHaveLength(1);
+    expect(portability!.assertions[0].status).toBe('compliant');
+  });
+});
+
+describe('single-law tree — LAW-NIS2-1', () => {
+  const tree = buildLawTree('LAW-NIS2-1', index);
+
+  it('has 2 NIS2 requirements', () => {
+    expect(tree.requirements).toHaveLength(2);
+    const ids = tree.requirements.map(r => r.requirement.id).sort();
+    expect(ids).toEqual([
+      'REQUIREMENT-NIS2-INCIDENT-REPORT-1',
+      'REQUIREMENT-NIS2-SUPPLY-CHAIN-1',
+    ]);
+  });
+
+  it('incident-report requirement has one under_review assertion', () => {
+    const incident = tree.requirements.find(r => r.requirement.id === 'REQUIREMENT-NIS2-INCIDENT-REPORT-1');
+    expect(incident!.assertions).toHaveLength(1);
+    expect(incident!.assertions[0].status).toBe('under_review');
+  });
+
+  it('supply-chain requirement has no assertions — deliberate gap', () => {
+    const supplyChain = tree.requirements.find(r => r.requirement.id === 'REQUIREMENT-NIS2-SUPPLY-CHAIN-1');
+    expect(supplyChain!.assertions).toHaveLength(0);
+  });
+});
+
+// ── Single-product views ─────────────────────────────────────────────────────
+
+describe('single-product view — PRODUCT-ECOMM-1', () => {
+  const view = buildProductView('PRODUCT-ECOMM-1', index);
+
+  it('covers 4 requirements (4 assertions with PRODUCT-ECOMM-1 as subject)', () => {
+    expect(view.requirements).toHaveLength(4);
+  });
+
+  it('includes non_compliant erasure status', () => {
+    const erasure = view.requirements.find(r => r.requirement.id === 'REQUIREMENT-GDPR-DATA-ERASURE-1');
+    expect(erasure).toBeDefined();
+    expect(erasure!.assertion.status).toBe('non_compliant');
+  });
+});
+
+describe('single-product view — PRODUCT-SUPPORT-1', () => {
+  const view = buildProductView('PRODUCT-SUPPORT-1', index);
+
+  it('has exactly 1 assertion (erasure only)', () => {
+    expect(view.requirements).toHaveLength(1);
+    expect(view.requirements[0].requirement.id).toBe('REQUIREMENT-GDPR-DATA-ERASURE-1');
+    expect(view.requirements[0].assertion.status).toBe('compliant');
+  });
+});
+
+// ── Gap report ───────────────────────────────────────────────────────────────
+
+describe('gap report', () => {
+  const today = '2026-06-10';
+  const report = buildGapReport(index, { today });
+
+  it('NIS2 supply-chain requirement appears in requirements-without-assertions', () => {
+    const gap = report.requirementsWithoutAssertions.find(
+      r => r.id === 'REQUIREMENT-NIS2-SUPPLY-CHAIN-1',
+    );
+    expect(gap).toBeDefined();
+  });
+
+  it('non_compliant erasure requirement is NOT in requirements-without-assertions', () => {
+    const gap = report.requirementsWithoutAssertions.find(
+      r => r.id === 'REQUIREMENT-GDPR-DATA-ERASURE-1',
+    );
+    expect(gap).toBeUndefined();
+  });
+
+  it('erasure requirement is NOT in pastDeadlineRequirements — it has a compliant assertion for PRODUCT-SUPPORT-1', () => {
+    // buildGapReport only surfaces a past-deadline req when ALL its assertions
+    // are non-compliant. PRODUCT-SUPPORT-1 has a compliant assertion for erasure,
+    // so the requirement is excluded from the past-deadline gap list even though
+    // PRODUCT-ECOMM-1 is non_compliant.
+    const overdue = report.pastDeadlineRequirements.find(
+      r => r.id === 'REQUIREMENT-GDPR-DATA-ERASURE-1',
+    );
+    expect(overdue).toBeUndefined();
+  });
+});
+
+// ── Compliance-impact view-config ────────────────────────────────────────────
+
+describe('compliance-impact view-config — gdpr-nis2', () => {
+  const raw = loadYamlFile('compliance-impact/gdpr-nis2.compliance-impact.view.yaml');
+  const result = parseImpactViewConfig(raw);
+
+  it('parses without errors', () => {
+    expect(result.ok).toBe(true);
+  });
+
+  it('scopes to PRODUCT-ECOMM-1 and PRODUCT-SUPPORT-1', () => {
+    if (!result.ok) throw new Error('parse failed');
+    expect(result.config.subjects.products).toEqual(['PRODUCT-ECOMM-1', 'PRODUCT-SUPPORT-1']);
+  });
+
+  it('filters obligations to LAW-GDPR-1 and LAW-NIS2-1', () => {
+    if (!result.ok) throw new Error('parse failed');
+    expect(result.config.obligations.filter?.derived_from_codex).toEqual(['LAW-GDPR-1', 'LAW-NIS2-1']);
+  });
+
+  it('builds a matrix with 2 products and 5 requirements scoped to the two laws', () => {
+    if (!result.ok) throw new Error('parse failed');
+
+    // Build the canon using ingestComplianceDoc (same path as the Studio extension).
+    const canon = emptyCanon();
+    for (const r of loadYamlDir('compliance/requirements')) ingestComplianceDoc(canon, r);
+    for (const a of loadYamlDir('compliance/assertions')) ingestComplianceDoc(canon, a);
+    // Add the two products.
+    canon.products.push({ id: 'PRODUCT-ECOMM-1', name: 'E-Commerce Platform' });
+    canon.products.push({ id: 'PRODUCT-SUPPORT-1', name: 'Customer Support Service' });
+
+    const matrix = buildImpactMatrix(canon, result.config);
+    expect(matrix.columns).toHaveLength(2);
+    // 5 requirements are split: 3 GDPR + 2 NIS2 — all 5 should appear.
+    expect(matrix.rows).toHaveLength(5);
+  });
+});
+
+// ── Regression: existing worked examples unaffected ─────────────────────────
+
+describe('regression — existing tests/fixtures/notation-corpus/requirement + tests/fixtures/notation-corpus/assertion unchanged', () => {
+  const reqs: IndexRequirement[] = loadYamlDir('requirement').map(r => ({
+    id: String(r.id),
+    name: String(r.name),
+    derived_from: Array.isArray(r.derived_from) ? (r.derived_from as string[]) : undefined,
+  }));
+  const asns: IndexAssertion[] = loadYamlDir('assertion').map(a => ({
+    id: String(a.id),
+    about: String(a.about),
+    subject: String(a.subject),
+    status: a.status as IndexAssertion['status'],
+  }));
+  const idx = buildComplianceIndex({ requirements: reqs, assertions: asns });
+
+  it('original LAW-PERSONAL-DATA-2017-1 tree still resolves correctly', () => {
+    const tree = buildLawTree('LAW-PERSONAL-DATA-2017-1', idx);
+    expect(tree.requirements.map(r => r.requirement.id)).toEqual(['REQUIREMENT-DATA-ERASURE-1']);
+    expect(tree.requirements[0].assertions).toHaveLength(3);
+  });
+});

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

@@ -0,0 +1,57 @@
+// Conformance — single-law tree + single-product view on the acme_corp worked
+// examples (mirrored under tests/fixtures/notation-corpus/requirement, tests/fixtures/notation-corpus/assertion). Pins the
+// #84 Phase 3 acceptance.
+
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { buildComplianceIndex } from '../reverse-index.js';
+import { buildLawTree, buildProductView } from '../views.js';
+import type { IndexAssertion, IndexRequirement } from '../types.js';
+
+const examples = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus');
+function loadAll(dir: string): Record<string, unknown>[] {
+  const full = path.join(examples, dir);
+  return readdirSync(full).filter(f => f.endsWith('.yaml')).map(f => yaml.load(readFileSync(path.join(full, f), 'utf-8')) as Record<string, unknown>);
+}
+
+const requirements: IndexRequirement[] = loadAll('requirement').map(r => ({
+  id: String(r.id), name: String(r.name),
+  severity: r.severity as string | undefined,
+  derived_from: Array.isArray(r.derived_from) ? (r.derived_from as string[]) : undefined,
+}));
+const assertions: IndexAssertion[] = loadAll('assertion').map(a => ({
+  id: String(a.id), about: String(a.about), subject: String(a.subject),
+  status: a.status as IndexAssertion['status'],
+  evidenceCount: Array.isArray(a.evidence) ? a.evidence.length : 0,
+}));
+const index = buildComplianceIndex({ requirements, assertions });
+
+describe('single-law tree — LAW-PERSONAL-DATA-2017-1', () => {
+  const tree = buildLawTree('LAW-PERSONAL-DATA-2017-1', index);
+  it('derives the data-erasure requirement with its three assertions', () => {
+    expect(tree.requirements.map(r => r.requirement.id)).toEqual(['REQUIREMENT-DATA-ERASURE-1']);
+    const node = tree.requirements[0];
+    expect(node.assertions.map(a => a.id)).toEqual([
+      'ASSERTION-CRM-DATA-ERASURE-1',
+      'ASSERTION-MOBILE-DATA-ERASURE-1',
+      'ASSERTION-ONBOARD-DATA-ERASURE-1',
+    ]);
+    expect(node.assertions.map(a => a.status).sort()).toEqual(['compliant', 'partial', 'under_review']);
+  });
+  it('the internal-only audit-log requirement is not under any law', () => {
+    expect(index.requirementsByLaw.has('LAW-PERSONAL-DATA-2017-1')).toBe(true);
+    expect(tree.requirements.some(r => r.requirement.id === 'REQUIREMENT-AUDIT-LOG-RETENTION-1')).toBe(false);
+  });
+});
+
+describe('single-product view — PRODUCT-MOBILE-1', () => {
+  it('shows the data-erasure requirement as compliant', () => {
+    const view = buildProductView('PRODUCT-MOBILE-1', index);
+    expect(view.requirements.map(r => r.requirement.id)).toEqual(['REQUIREMENT-DATA-ERASURE-1']);
+    expect(view.requirements[0].assertion.status).toBe('compliant');
+    expect(view.requirements[0].requirement.name).toBe('Personal-data erasure on request within 30 days');
+  });
+});

package/src/compliance/__tests__/gap-report.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { buildComplianceIndex } from '../reverse-index.js';
+import { buildGapReport } from '../gap-report.js';
+import type { ComplianceIndexInput, IndexAssertion, IndexRequirement } from '../types.js';
+
+const input: ComplianceIndexInput = {
+  requirements: [
+    { id: 'REQUIREMENT-A-1', name: 'A', severity: 'high' },   // has assertions
+    { id: 'REQUIREMENT-B-1', name: 'B', severity: 'low' },    // orphan
+    { id: 'REQUIREMENT-C-1', name: 'C', severity: 'medium' }, // orphan
+    { id: 'REQUIREMENT-D-1', name: 'D' },                     // orphan, no severity
+  ],
+  assertions: [
+    { id: 'ASSERTION-1', about: 'REQUIREMENT-A-1', subject: 'PRODUCT-1', status: 'compliant', evidenceCount: 0 }, // 007
+    { id: 'ASSERTION-2', about: 'REQUIREMENT-A-1', subject: 'PRODUCT-2', status: 'under_review', evidenceCount: 0 }, // NOT 007
+    { id: 'ASSERTION-3', about: 'REQUIREMENT-A-1', subject: 'PRODUCT-3', status: 'partial', evidenceCount: 2, next_review_at: '2025-01-01' }, // stale
+  ],
+};
+
+describe('buildGapReport', () => {
+  const index = buildComplianceIndex(input);
+  const report = buildGapReport(index, { today: '2026-06-02' });
+
+  it('lists requirements without assertions, severity-sorted (high→medium→low→none)', () => {
+    expect(report.requirementsWithoutAssertions.map(r => r.id)).toEqual([
+      'REQUIREMENT-C-1', // medium
+      'REQUIREMENT-B-1', // low
+      'REQUIREMENT-D-1', // none
+    ]);
+  });
+
+  it('flags only compliant/partial assertions with empty evidence (ASSERT-007)', () => {
+    expect(report.assertionsWithoutEvidence.map(a => a.id)).toEqual(['ASSERTION-1']);
+    // under_review with empty evidence is legitimate — not flagged.
+    expect(report.assertionsWithoutEvidence.map(a => a.id)).not.toContain('ASSERTION-2');
+  });
+
+  it('flags assertions whose next_review_at is past today (ASSERT-008)', () => {
+    expect(report.staleAssertions.map(a => a.id)).toEqual(['ASSERTION-3']);
+  });
+
+  it('produces no stale list when today is not supplied (clock-free)', () => {
+    expect(buildGapReport(index, {}).staleAssertions).toEqual([]);
+  });
+});
+
+// ── Conformance on the acme_corp worked examples ────────────────────────────
+
+const examples = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus');
+function loadAll(dir: string): Record<string, unknown>[] {
+  const full = path.join(examples, dir);
+  return readdirSync(full).filter(f => f.endsWith('.yaml')).map(f => yaml.load(readFileSync(path.join(full, f), 'utf-8')) as Record<string, unknown>);
+}
+
+describe('gap report — acme_corp worked examples', () => {
+  const requirements: IndexRequirement[] = loadAll('requirement').map(r => ({
+    id: String(r.id), name: String(r.name), severity: r.severity as string | undefined,
+    derived_from: Array.isArray(r.derived_from) ? (r.derived_from as string[]) : undefined,
+  }));
+  const assertions: IndexAssertion[] = loadAll('assertion').map(a => ({
+    id: String(a.id), about: String(a.about), subject: String(a.subject),
+    status: a.status as IndexAssertion['status'],
+    next_review_at: a.next_review_at as string | undefined,
+    evidenceCount: Array.isArray(a.evidence) ? a.evidence.length : 0,
+  }));
+  const report = buildGapReport(buildComplianceIndex({ requirements, assertions }), { today: '2026-06-02' });
+
+  it('surfaces the internal audit-log requirement as an un-asserted gap', () => {
+    expect(report.requirementsWithoutAssertions.map(r => r.id)).toEqual(['REQUIREMENT-AUDIT-LOG-RETENTION-1']);
+  });
+
+  it('does not flag the under_review empty-evidence assertion under ASSERT-007', () => {
+    expect(report.assertionsWithoutEvidence).toEqual([]);
+  });
+
+  it('has no stale assertions (all acme reviews are in the future)', () => {
+    expect(report.staleAssertions).toEqual([]);
+  });
+});
+
+describe('CV-5 -- pastDeadlineRequirements', () => {
+  it('lists requirements with past deadline and no compliant assertion', () => {
+    const indexLocal = buildComplianceIndex({
+      requirements: [
+        { id: 'REQ-PD-1', name: 'Past deadline, no assertion', deadline: '2020-01-01' },
+        { id: 'REQ-PD-2', name: 'Past deadline, non-compliant assertion', deadline: '2020-01-01' },
+        { id: 'REQ-PD-3', name: 'Past deadline, compliant assertion', deadline: '2020-01-01' },
+        { id: 'REQ-FU-1', name: 'Future deadline', deadline: '2099-01-01' },
+        { id: 'REQ-ND-1', name: 'No deadline' },
+      ],
+      assertions: [
+        { id: 'ASS-2', about: 'REQ-PD-2', subject: 'S', status: 'non_compliant' },
+        { id: 'ASS-3', about: 'REQ-PD-3', subject: 'S', status: 'compliant' },
+      ],
+    });
+    const r = buildGapReport(indexLocal, { today: '2026-06-09' });
+    // REQ-PD-1 and REQ-PD-2 are past-deadline without full compliance
+    expect(r.pastDeadlineRequirements.map(x => x.id)).toEqual(['REQ-PD-1', 'REQ-PD-2']);
+    // REQ-PD-3 has a compliant assertion -> excluded
+    expect(r.pastDeadlineRequirements.map(x => x.id)).not.toContain('REQ-PD-3');
+    // Future or no deadline -> excluded
+    expect(r.pastDeadlineRequirements.map(x => x.id)).not.toContain('REQ-FU-1');
+    expect(r.pastDeadlineRequirements.map(x => x.id)).not.toContain('REQ-ND-1');
+  });
+
+  it('is empty when no today is supplied (clock-free)', () => {
+    const idx2 = buildComplianceIndex({
+      requirements: [{ id: 'REQ-PD-1', name: 'Past', deadline: '2020-01-01' }],
+      assertions: [],
+    });
+    expect(buildGapReport(idx2, {}).pastDeadlineRequirements).toEqual([]);
+  });
+
+  it('sorts oldest deadline first', () => {
+    const idx3 = buildComplianceIndex({
+      requirements: [
+        { id: 'REQ-A', name: 'A', deadline: '2022-06-01' },
+        { id: 'REQ-B', name: 'B', deadline: '2019-01-01' },
+      ],
+      assertions: [],
+    });
+    const r3 = buildGapReport(idx3, { today: '2026-06-09' });
+    expect(r3.pastDeadlineRequirements.map(x => x.id)).toEqual(['REQ-B', 'REQ-A']);
+  });
+});

package/src/compliance/__tests__/html.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import { renderComplianceHtml } from '../html.js';
+import { emptyCanon, ingestComplianceDoc, type ComplianceCanon } from '../classify.js';
+
+function synthetic(): ComplianceCanon {
+  const canon = emptyCanon();
+  ingestComplianceDoc(canon, { notation: 'product', id: 'PRODUCT-M-1', name: 'Mobile App' });
+  ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQUIREMENT-ERASURE-1', name: 'Erasure', severity: 'high', derived_from: ['LAW-X-1'] });
+  ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQUIREMENT-LOG-1', name: 'Logs', severity: 'low' });
+  ingestComplianceDoc(canon, {
+    notation: 'assertion',
+    id: 'ASSERTION-1',
+    about: 'REQUIREMENT-ERASURE-1',
+    subject: 'PRODUCT-M-1',
+    status: 'compliant',
+    evidence: [{ kind: 'note', text: 'x' }],
+    next_review_at: '2026-09-01',
+  });
+  ingestComplianceDoc(canon, { id: 'LAW-X-1', name: 'Privacy Law', zone: 'codex', type: 'LAW' });
+  return canon;
+}
+
+describe('renderComplianceHtml — document shell', () => {
+  it('produces a complete HTML document with branded header and stamp', () => {
+    const html = renderComplianceHtml(synthetic(), { mode: 'matrix' }, { today: '2026-06-03' });
+    expect(html.startsWith('<!doctype html>')).toBe(true);
+    expect(html).toContain('<title>Compliance Matrix</title>');
+    expect(html).toContain('<div class="cmp-eyebrow">Transitrix · Compliance</div>');
+    expect(html).toContain('<h1>Compliance Matrix</h1>');
+    expect(html).toContain('Generated 2026-06-03');
+    expect(html).toContain('@page');
+    expect(html).toContain('size: A4 portrait');
+  });
+
+  it('escapes HTML in product and requirement names', () => {
+    const canon = emptyCanon();
+    ingestComplianceDoc(canon, { notation: 'product', id: 'PRODUCT-X-1', name: '<Mobile> & "Web"' });
+    ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQUIREMENT-X-1', name: 'A & B' });
+    const html = renderComplianceHtml(canon, { mode: 'matrix' });
+    expect(html).not.toMatch(/<Mobile>/);
+    expect(html).toContain('&lt;Mobile&gt; &amp; &quot;Web&quot;');
+    expect(html).toContain('A &amp; B');
+  });
+});
+
+describe('renderComplianceHtml — matrix', () => {
+  it('renders a table with status badges and gap cells', () => {
+    const html = renderComplianceHtml(synthetic(), { mode: 'matrix' });
+    expect(html).toContain('<table class="cmp-matrix">');
+    expect(html).toContain('<th>Erasure</th>');
+    expect(html).toContain('<th>Logs</th>');
+    expect(html).toContain('<span class="cmp-badge cmp-compliant">Compliant</span>');
+    expect(html).toMatch(/cmp-cell-gap/);
+    expect(html).toContain('1 products × 2 requirements');
+  });
+
+  it('shows an empty-state message when nothing was scanned', () => {
+    const html = renderComplianceHtml(emptyCanon(), { mode: 'matrix' });
+    expect(html).toContain('No products or requirements found');
+  });
+});
+
+describe('renderComplianceHtml — law', () => {
+  it('renders the law name, requirement block, and assertion bullet with badge', () => {
+    const html = renderComplianceHtml(synthetic(), { mode: 'law', id: 'LAW-X-1' });
+    expect(html).toContain('<h1>Compliance — Privacy Law</h1>');
+    expect(html).toContain('class="cmp-req-name">Erasure');
+    expect(html).toContain('class="cmp-req-id">REQUIREMENT-ERASURE-1');
+    expect(html).toContain('cmp-sev cmp-sev-high');
+    expect(html).toContain('cmp-badge cmp-compliant');
+    expect(html).toContain('review by 2026-09-01');
+  });
+
+  it('handles an unknown law id with an empty-state message', () => {
+    const html = renderComplianceHtml(synthetic(), { mode: 'law', id: 'LAW-NONE' });
+    expect(html).toContain('<h1>Compliance — LAW-NONE</h1>');
+    expect(html).toContain('No requirements derive from');
+  });
+});
+
+describe('renderComplianceHtml — product', () => {
+  it('renders the product table of asserted requirements', () => {
+    const html = renderComplianceHtml(synthetic(), { mode: 'product', id: 'PRODUCT-M-1' });
+    expect(html).toContain('<h1>Compliance — Mobile App</h1>');
+    expect(html).toContain('<th>Requirement</th>');
+    expect(html).toContain('<th>Status</th>');
+    expect(html).toContain('cmp-badge cmp-compliant');
+    expect(html).toContain('2026-09-01');
+  });
+});
+
+describe('renderComplianceHtml — gap', () => {
+  it('lists the un-asserted requirement and shows ✓ none for clean sections', () => {
+    const html = renderComplianceHtml(synthetic(), { mode: 'gap' }, { today: '2026-06-02' });
+    expect(html).toContain('Requirements without assertions');
+    expect(html).toContain('REQUIREMENT-LOG-1');
+    expect(html).toContain('severity low');
+    expect(html).toContain('Assertions without evidence — ASSERT-007');
+    expect(html).toContain('Stale assertions — ASSERT-008');
+    expect(html).toContain('class="cmp-ok">✓ none');
+  });
+
+  it('counts gaps in the summary line', () => {
+    const html = renderComplianceHtml(synthetic(), { mode: 'gap' });
+    expect(html).toMatch(/1 gap\(s\)/);
+  });
+});
+
+// ── CV-6: renderImpactMatrixHtml ─────────────────────────────────────────────
+
+import { renderImpactMatrixHtml } from '../html.js';
+import { buildImpactMatrix } from '../impact.js';
+
+describe('renderImpactMatrixHtml (CV-6)', () => {
+  it('returns a complete HTML document with matrix title and table', () => {
+    const canon = emptyCanon();
+    ingestComplianceDoc(canon, { notation: 'product', id: 'PROD-1', name: 'Product One' });
+    ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQ-1', name: 'Req One', severity: 'high' });
+    ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASS-1', about: 'REQ-1', subject: 'PROD-1', status: 'compliant' });
+    const matrix = buildImpactMatrix(
+      { products: canon.products, requirements: canon.requirements, assertions: canon.assertions, codex: canon.codex },
+      { id: 'VIEW-1', name: 'My View', subjects: { products: ['PROD-1'] }, obligations: {} },
+    );
+    const html = renderImpactMatrixHtml(matrix, { today: '2026-06-09' });
+    expect(html).toContain('<table>');
+    expect(html).toContain('My View');
+    expect(html).toContain('VIEW-1');
+    expect(html).toContain('OK');
+  });
+
+  it('renders gap cells with no_obligation_label text', () => {
+    const canon = emptyCanon();
+    ingestComplianceDoc(canon, { notation: 'product', id: 'PROD-1', name: 'P1' });
+    ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQ-1', name: 'R1' });
+    const matrix = buildImpactMatrix(
+      { products: canon.products, requirements: canon.requirements, assertions: canon.assertions, codex: canon.codex },
+      { id: 'V2', name: 'V2', subjects: { products: ['PROD-1'] }, obligations: {} },
+    );
+    const html = renderImpactMatrixHtml(matrix);
+    expect(html).toContain('No mapped obligation');
+  });
+});