@transitrix/diagrams 1.0.0

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

@@ -0,0 +1,482 @@
+import { describe, it, expect } from 'vitest';
+import { emptyCanon } from '../classify.js';
+import {
+  buildImpactMatrix,
+  renderImpactMarkdown,
+  parseImpactViewConfig,
+  COMPLIANCE_IMPACT_DEFAULTS,
+  extractObjectDetails,
+  computeDeadlineStatus,
+  type ImpactViewConfig,
+} from '../impact.js';
+import type { ComplianceCanon } from '../classify.js';
+
+// Industry- and regime-agnostic synthetic fixture: opaque ids only, no real
+// regulator / product names, per #166 acceptance ("Output is aggregates only —
+// no subject/obligation names tied to any real corpus").
+function buildCanon(): ComplianceCanon {
+  const canon = emptyCanon();
+  canon.products.push({ id: 'PRODUCT-A-1', name: 'Product A' });
+  canon.products.push({ id: 'PRODUCT-B-1', name: 'Product B' });
+  canon.requirements.push(
+    { id: 'REQUIREMENT-FOO-1', name: 'Foo', derived_from: ['LAW-X-1'] },
+    { id: 'REQUIREMENT-BAR-1', name: 'Bar', derived_from: ['LAW-X-1', 'REGULATION-Y-1'] },
+    { id: 'REQUIREMENT-BAZ-1', name: 'Baz', derived_from: ['REGULATION-Y-1'] },
+    // Internal-only requirement, no codex derivation:
+    { id: 'REQUIREMENT-INT-1', name: 'Internal-only' },
+  );
+  canon.assertions.push(
+    // (PRODUCT-A-1, FOO) — two assertions; partial wins over compliant per §5.2 step 4.
+    { id: 'ASSERTION-1', about: 'REQUIREMENT-FOO-1', subject: 'PRODUCT-A-1', status: 'compliant' },
+    { id: 'ASSERTION-2', about: 'REQUIREMENT-FOO-1', subject: 'PRODUCT-A-1', status: 'partial' },
+    // (PRODUCT-A-1, BAR) — single n_a → modelled fact ("No obligation applies").
+    { id: 'ASSERTION-3', about: 'REQUIREMENT-BAR-1', subject: 'PRODUCT-A-1', status: 'n_a' },
+    // (PRODUCT-B-1, BAR) — non_compliant.
+    { id: 'ASSERTION-4', about: 'REQUIREMENT-BAR-1', subject: 'PRODUCT-B-1', status: 'non_compliant' },
+    // (PRODUCT-B-1, BAZ) — under_review beats compliant.
+    { id: 'ASSERTION-5', about: 'REQUIREMENT-BAZ-1', subject: 'PRODUCT-B-1', status: 'under_review' },
+    { id: 'ASSERTION-6', about: 'REQUIREMENT-BAZ-1', subject: 'PRODUCT-B-1', status: 'compliant' },
+  );
+  return canon;
+}
+
+const baseConfig: ImpactViewConfig = {
+  id: 'COMPLIANCE_IMPACT-FIXTURE-1',
+  name: 'Fixture matrix',
+  subjects: { products: ['PRODUCT-A-1', 'PRODUCT-B-1'] },
+  obligations: {},
+};
+
+describe('buildImpactMatrix', () => {
+  it('aggregates statuses per §5.2 step 4 — non_compliant > partial > under_review > compliant', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      obligations: { include: ['REQUIREMENT-FOO-1', 'REQUIREMENT-BAR-1', 'REQUIREMENT-BAZ-1'] },
+    });
+    expect(matrix.columns.map(c => c.label)).toEqual(['PRODUCT-A-1', 'PRODUCT-B-1']);
+    expect(matrix.rows.map(r => r.id)).toEqual(['REQUIREMENT-BAR-1', 'REQUIREMENT-BAZ-1', 'REQUIREMENT-FOO-1']);
+
+    const cellFor = (req: string, subject: string) => {
+      const r = matrix.rows.findIndex(x => x.id === req);
+      const c = matrix.columns.findIndex(col => col.label === subject);
+      return matrix.cells[r][c];
+    };
+
+    expect(cellFor('REQUIREMENT-FOO-1', 'PRODUCT-A-1').status).toBe('partial');
+    expect(cellFor('REQUIREMENT-FOO-1', 'PRODUCT-A-1').kind).toBe('bound');
+    expect(cellFor('REQUIREMENT-BAR-1', 'PRODUCT-A-1').kind).toBe('n_a_only');
+    expect(cellFor('REQUIREMENT-BAR-1', 'PRODUCT-B-1').status).toBe('non_compliant');
+    expect(cellFor('REQUIREMENT-BAZ-1', 'PRODUCT-B-1').status).toBe('under_review');
+    expect(cellFor('REQUIREMENT-FOO-1', 'PRODUCT-B-1').kind).toBe('gap');
+    expect(cellFor('REQUIREMENT-BAZ-1', 'PRODUCT-A-1').kind).toBe('gap');
+  });
+
+  it('selects obligations by `filter.derived_from_codex`', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      obligations: { filter: { derived_from_codex: ['REGULATION-Y-1'] } },
+    });
+    expect(matrix.rows.map(r => r.id)).toEqual(['REQUIREMENT-BAR-1', 'REQUIREMENT-BAZ-1']);
+  });
+
+  it('`include` wins when both `include` and `filter` are present (COMPIMP-007)', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      obligations: {
+        include: ['REQUIREMENT-INT-1'],
+        filter: { derived_from_codex: ['LAW-X-1'] },
+      },
+    });
+    expect(matrix.rows.map(r => r.id)).toEqual(['REQUIREMENT-INT-1']);
+  });
+
+  it('distinguishes modelling gap from n_a-only per §5.3', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      obligations: { include: ['REQUIREMENT-BAR-1'] },
+    });
+    const aCell = matrix.cells[0][matrix.columns.findIndex(c => c.label === 'PRODUCT-A-1')];
+    const bCell = matrix.cells[0][matrix.columns.findIndex(c => c.label === 'PRODUCT-B-1')];
+    expect(aCell.kind).toBe('n_a_only');
+    expect(bCell.kind).toBe('bound');
+    expect(bCell.status).toBe('non_compliant');
+  });
+
+  it('respects `status_display.show` — filtered-out statuses leave the cell as a gap', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      obligations: { include: ['REQUIREMENT-BAZ-1'] },
+      status_display: { show: ['non_compliant'] }, // under_review + compliant filtered out
+    });
+    const cell = matrix.cells[0][matrix.columns.findIndex(c => c.label === 'PRODUCT-B-1')];
+    expect(cell.kind).toBe('gap');
+  });
+
+  it('keeps subjects with no binding obligation as columns so the gap is visible', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      subjects: { products: ['PRODUCT-A-1', 'PRODUCT-B-1', 'PRODUCT-NONE-1'] },
+      obligations: { include: ['REQUIREMENT-FOO-1'] },
+    });
+    expect(matrix.columns.map(c => c.label)).toContain('PRODUCT-NONE-1');
+    const cell = matrix.cells[0][matrix.columns.findIndex(c => c.label === 'PRODUCT-NONE-1')];
+    expect(cell.kind).toBe('gap');
+  });
+
+  it('orders rows alphabetically by name when `order_rows_by: name`', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      obligations: { include: ['REQUIREMENT-FOO-1', 'REQUIREMENT-BAR-1', 'REQUIREMENT-BAZ-1'] },
+      order_rows_by: 'name',
+    });
+    expect(matrix.rows.map(r => r.name)).toEqual(['Bar', 'Baz', 'Foo']);
+  });
+});
+
+describe('renderImpactMarkdown', () => {
+  it('renders a header, table, and §5.3 legend', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      obligations: { include: ['REQUIREMENT-FOO-1', 'REQUIREMENT-BAR-1'] },
+    });
+    const md = renderImpactMarkdown(matrix);
+    expect(md).toContain('# Fixture matrix');
+    expect(md).toContain('View ID: `COMPLIANCE_IMPACT-FIXTURE-1`');
+    expect(md).toContain('| Obligation | PRODUCT-A-1 | PRODUCT-B-1 |');
+    expect(md).toContain('PARTIAL');
+    expect(md).toContain('FAIL');
+    expect(md).toContain('No mapped obligation (current model)');
+    expect(md).toContain('No obligation applies');
+    expect(md).toContain('## Legend');
+  });
+
+  it('honours custom empty-cell labels', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      obligations: { include: ['REQUIREMENT-FOO-1', 'REQUIREMENT-BAR-1'] },
+      empty_cells: {
+        no_obligation_label: 'GAP',
+        no_obligation_applies_label: 'EXCLUDED',
+      },
+    });
+    const md = renderImpactMarkdown(matrix);
+    expect(md).toContain('GAP');
+    expect(md).toContain('EXCLUDED');
+    expect(md).not.toContain('No mapped obligation (current model)');
+  });
+
+  it('renders a placeholder when zero obligations are selected', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, {
+      ...baseConfig,
+      obligations: { include: ['REQUIREMENT-DOES-NOT-EXIST-1'] },
+    });
+    const md = renderImpactMarkdown(matrix);
+    expect(md).toContain('No obligations in scope');
+  });
+
+  it('propagates snapshot_at into the matrix and renders it', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, { ...baseConfig, snapshot_at: '2026-06-09' });
+    expect(matrix.snapshotAt).toBe('2026-06-09');
+    const md = renderImpactMarkdown(matrix);
+    expect(md).toContain('Report snapshot: 2026-06-09');
+  });
+});
+
+// ── parseImpactViewConfig ───────────────────────────────────────────────────
+
+describe('parseImpactViewConfig', () => {
+  it('returns ok:false for a non-object', () => {
+    const r = parseImpactViewConfig(null);
+    expect(r.ok).toBe(false);
+  });
+
+  it('returns ok:false when id is missing', () => {
+    const r = parseImpactViewConfig({ name: 'X', subjects: {} });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.errors.some(e => e.includes('id'))).toBe(true);
+  });
+
+  it('returns ok:false when name is missing', () => {
+    const r = parseImpactViewConfig({ id: 'X', subjects: {} });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.errors.some(e => e.includes('name'))).toBe(true);
+  });
+
+  it('unwraps the top-level view: wrapper', () => {
+    const r = parseImpactViewConfig({ view: { id: 'V-1', name: 'My view', subjects: {} } });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.config.id).toBe('V-1');
+  });
+
+  it('fills all optional fields from COMPLIANCE_IMPACT_DEFAULTS', () => {
+    const r = parseImpactViewConfig({ id: 'V-1', name: 'My view', subjects: {} });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    const c = r.config;
+    expect(c.subjects.products).toEqual([]);
+    expect(c.subjects.processes).toEqual([]);
+    expect(c.status_display?.show).toEqual(COMPLIANCE_IMPACT_DEFAULTS.status_display.show);
+    expect(c.order_rows_by).toBe('id');
+    expect(c.empty_cells?.no_obligation_label).toBe(
+      COMPLIANCE_IMPACT_DEFAULTS.empty_cells.no_obligation_label,
+    );
+    expect(c.empty_cells?.no_obligation_applies_label).toBe(
+      COMPLIANCE_IMPACT_DEFAULTS.empty_cells.no_obligation_applies_label,
+    );
+  });
+
+  it('preserves explicit subject lists and snapshot_at', () => {
+    const r = parseImpactViewConfig({
+      id: 'V-2',
+      name: 'View 2',
+      snapshot_at: '2026-01-01',
+      subjects: { products: ['PRODUCT-A-1', 'PRODUCT-B-1'] },
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.config.subjects.products).toEqual(['PRODUCT-A-1', 'PRODUCT-B-1']);
+    expect(r.config.snapshot_at).toBe('2026-01-01');
+  });
+
+  it('applies custom order_rows_by:name', () => {
+    const r = parseImpactViewConfig({ id: 'V-3', name: 'V', subjects: {}, order_rows_by: 'name' });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.config.order_rows_by).toBe('name');
+  });
+
+  it('parses obligation filter correctly', () => {
+    const r = parseImpactViewConfig({
+      id: 'V-4',
+      name: 'V',
+      subjects: {},
+      obligations: { filter: { derived_from_codex: ['LAW-X-1'] } },
+    });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.config.obligations.filter?.derived_from_codex).toEqual(['LAW-X-1']);
+  });
+});
+
+describe('CV-3a — stage grouping (ImpactColumn, extractObjectDetails, buildImpactMatrix stage grain)', () => {
+  it('default product grain: columns are plain ImpactColumn with label=subjectId', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(canon, baseConfig);
+    expect(matrix.columns.map(c => c.subjectId)).toEqual(['PRODUCT-A-1', 'PRODUCT-B-1']);
+    expect(matrix.columns.map(c => c.label)).toEqual(['PRODUCT-A-1', 'PRODUCT-B-1']);
+    expect(matrix.columns.every(c => !c.stageId)).toBe(true);
+  });
+
+  it('product-stage grain: expands columns by stage, label is subjectId:stageId', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(
+      canon,
+      { ...baseConfig, subjects: { products: ['PRODUCT-A-1'] }, grouping: { columns: 'object-details' } },
+      [{ objectId: 'PRODUCT-A-1', details: [{ id: 'STAGE-1', name: 'Stage One' }, { id: 'STAGE-2', name: 'Stage Two' }] }],
+    );
+    expect(matrix.columns.map(c => c.label)).toEqual(['PRODUCT-A-1:STAGE-1', 'PRODUCT-A-1:STAGE-2']);
+    expect(matrix.columns.map(c => c.stageId)).toEqual(['STAGE-1', 'STAGE-2']);
+  });
+
+  it('assertion without realised_via fills every stage column for its subject', () => {
+    const canon = emptyCanon();
+    canon.requirements.push({ id: 'REQ-1', name: 'R1' });
+    // Assertion with no realised_via — covers the whole subject.
+    canon.assertions.push({ id: 'ASS-1', about: 'REQ-1', subject: 'PROD-1', status: 'compliant' });
+    const matrix = buildImpactMatrix(
+      canon,
+      {
+        id: 'V', name: 'V',
+        subjects: { products: ['PROD-1'] },
+        obligations: {},
+        grouping: { columns: 'object-details' },
+      },
+      [{ objectId: 'PROD-1', details: [{ id: 'S1', name: 's1' }, { id: 'S2', name: 's2' }] }],
+    );
+    // Both stage columns should be bound (no realised_via means all stages inherit).
+    expect(matrix.cells[0][0].kind).toBe('bound');
+    expect(matrix.cells[0][1].kind).toBe('bound');
+  });
+
+  it('assertion with realised_via fills only the matching stage column', () => {
+    const canon = emptyCanon();
+    canon.requirements.push({ id: 'REQ-1', name: 'R1' });
+    // Assertion only covers STAGE-A.
+    canon.assertions.push({
+      id: 'ASS-1', about: 'REQ-1', subject: 'PROD-1', status: 'compliant',
+      realised_via: ['STAGE-A'],
+    });
+    const matrix = buildImpactMatrix(
+      canon,
+      {
+        id: 'V', name: 'V',
+        subjects: { products: ['PROD-1'] },
+        obligations: {},
+        grouping: { columns: 'object-details' },
+      },
+      [{ objectId: 'PROD-1', details: [{ id: 'STAGE-A', name: 'a' }, { id: 'STAGE-B', name: 'b' }] }],
+    );
+    expect(matrix.cells[0][0].kind).toBe('bound');   // STAGE-A: covered
+    expect(matrix.cells[0][1].kind).toBe('gap');     // STAGE-B: gap
+  });
+
+  it('subject with no stage mapping falls back to single product-grain column', () => {
+    const canon = buildCanon();
+    const matrix = buildImpactMatrix(
+      canon,
+      {
+        ...baseConfig,
+        subjects: { products: ['PRODUCT-A-1', 'PRODUCT-B-1'] },
+        grouping: { columns: 'object-details' },
+      },
+      // Only provide stages for A — B falls back to a single column.
+      [{ objectId: 'PRODUCT-A-1', details: [{ id: 'S1', name: 's1' }] }],
+    );
+    expect(matrix.columns.map(c => c.label)).toEqual(['PRODUCT-A-1:S1', 'PRODUCT-B-1']);
+    // PRODUCT-B-1 fallback column: no stageId.
+    expect(matrix.columns[1].stageId).toBeUndefined();
+  });
+
+  it('extractObjectDetails — returns null for non-blueprint docs', () => {
+    expect(extractObjectDetails(null)).toBeNull();
+    expect(extractObjectDetails({ notation: 'requirement', id: 'R1' })).toBeNull();
+    expect(extractObjectDetails({ process_blueprint: { details: [{ id: 'S1' }] } })).toBeNull(); // missing id
+  });
+
+  it('extractObjectDetails — extracts subjectId and stages from process_blueprint wrapper', () => {
+    const doc = { process_blueprint: { id: 'PROC-1', notation: 'process_blueprint', stages: [{ id: 'S1', name: 'Stage One' }, { id: 'S2', name: 'Stage Two' }] } };
+    const sg = extractObjectDetails(doc);
+    expect(sg).not.toBeNull();
+    expect(sg!.objectId).toBe('PROC-1');
+    expect(sg!.details.map((s: { id: string }) => s.id)).toEqual(['S1', 'S2']);
+  });
+
+  it('renderImpactMarkdown uses column labels in the table header', () => {
+    const canon = emptyCanon();
+    canon.requirements.push({ id: 'REQ-1', name: 'Req' });
+    canon.assertions.push({ id: 'ASS-1', about: 'REQ-1', subject: 'PROD-1', status: 'compliant' });
+    const matrix = buildImpactMatrix(
+      canon,
+      {
+        id: 'V', name: 'Stage Report',
+        subjects: { products: ['PROD-1'] },
+        obligations: {},
+        grouping: { columns: 'object-details' },
+      },
+      [{ objectId: 'PROD-1', details: [{ id: 'S1', name: 'Stage One' }] }],
+    );
+    const md = renderImpactMarkdown(matrix);
+    expect(md).toContain('PROD-1:S1');
+  });
+});
+
+describe('CV-3 -- blueprint-lane decorations + obligations lane', () => {
+  it('computeDeadlineStatus function is available', () => {
+    expect(typeof computeDeadlineStatus).toBe('function');
+  });
+
+  it('cell.decoration.isNew = false when no snapshot_at', () => {
+    const canon = emptyCanon();
+    canon.requirements.push({ id: 'REQ-1', name: 'R1', admitted_at: '2026-01-01' });
+    canon.assertions.push({ id: 'ASS-1', about: 'REQ-1', subject: 'PROD-1', status: 'compliant' });
+    const matrix = buildImpactMatrix(canon, {
+      id: 'V', name: 'V',
+      subjects: { products: ['PROD-1'] },
+      obligations: {},
+    });
+    expect(matrix.cells[0][0].decoration.isNew).toBe(false);
+  });
+
+  it('cell.decoration.isNew = true when req admitted after snapshot_at', () => {
+    const canon = emptyCanon();
+    canon.requirements.push({ id: 'REQ-1', name: 'R1', admitted_at: '2026-06-01' });
+    canon.assertions.push({ id: 'ASS-1', about: 'REQ-1', subject: 'PROD-1', status: 'compliant' });
+    const matrix = buildImpactMatrix(canon, {
+      id: 'V', name: 'V',
+      snapshot_at: '2026-05-01',
+      subjects: { products: ['PROD-1'] },
+      obligations: {},
+    });
+    // admitted_at (2026-06-01) > snapshot_at (2026-05-01) -> isNew
+    expect(matrix.cells[0][0].decoration.isNew).toBe(true);
+  });
+
+  it('cell.decoration.isUrgent = true when gap + past_due deadline', () => {
+    const canon = emptyCanon();
+    canon.requirements.push({ id: 'REQ-1', name: 'R1', deadline: '2000-01-01' });
+    // No assertion -> gap cell
+    const matrix = buildImpactMatrix(canon, {
+      id: 'V', name: 'V',
+      subjects: { products: ['PROD-1'] },
+      obligations: {},
+    });
+    expect(matrix.cells[0][0].kind).toBe('gap');
+    expect(matrix.cells[0][0].decoration.isUrgent).toBe(true);
+    expect(matrix.cells[0][0].decoration.deadlineStatus).toBe('past_due');
+  });
+
+  it('cell.decoration.isUrgent = false on bound cell even with past deadline', () => {
+    const canon = emptyCanon();
+    canon.requirements.push({ id: 'REQ-1', name: 'R1', deadline: '2000-01-01' });
+    canon.assertions.push({ id: 'ASS-1', about: 'REQ-1', subject: 'PROD-1', status: 'compliant' });
+    const matrix = buildImpactMatrix(canon, {
+      id: 'V', name: 'V',
+      subjects: { products: ['PROD-1'] },
+      obligations: {},
+    });
+    expect(matrix.cells[0][0].kind).toBe('bound');
+    // Not urgent: cell is bound, not a gap
+    expect(matrix.cells[0][0].decoration.isUrgent).toBe(false);
+  });
+
+  it('obligationsLane lists derived_from codex IDs for non-gap columns', () => {
+    const canon = emptyCanon();
+    canon.requirements.push({ id: 'REQ-1', name: 'R1', derived_from: ['LAW-X', 'REG-Y'] });
+    canon.requirements.push({ id: 'REQ-2', name: 'R2', derived_from: ['LAW-X'] });
+    // Only REQ-1 is bound in PROD-1 column; REQ-2 is a gap
+    canon.assertions.push({ id: 'ASS-1', about: 'REQ-1', subject: 'PROD-1', status: 'compliant' });
+    const matrix = buildImpactMatrix(canon, {
+      id: 'V', name: 'V',
+      subjects: { products: ['PROD-1'] },
+      obligations: {},
+    });
+    // obligationsLane[0] (PROD-1 column): REQ-1 is bound -> derived_from -> LAW-X, REG-Y sorted
+    expect(matrix.obligationsLane[0]).toEqual(['LAW-X', 'REG-Y']);
+  });
+
+  it('obligationsLane is empty for columns with only gap cells', () => {
+    const canon = emptyCanon();
+    canon.requirements.push({ id: 'REQ-1', name: 'R1', derived_from: ['LAW-X'] });
+    // No assertions -> all gaps
+    const matrix = buildImpactMatrix(canon, {
+      id: 'V', name: 'V',
+      subjects: { products: ['PROD-1'] },
+      obligations: {},
+    });
+    expect(matrix.obligationsLane[0]).toEqual([]);
+  });
+});
+
+describe('computeDeadlineStatus', () => {
+  it('returns none for missing deadline', () => {
+    expect(computeDeadlineStatus(undefined, '2026-06-01')).toBe('none');
+  });
+  it('returns past_due when deadline < today', () => {
+    expect(computeDeadlineStatus('2026-01-01', '2026-06-01')).toBe('past_due');
+  });
+  it('returns in_force within 30 days', () => {
+    expect(computeDeadlineStatus('2026-06-20', '2026-06-01')).toBe('in_force');
+  });
+  it('returns upcoming more than 30 days away', () => {
+    expect(computeDeadlineStatus('2026-12-31', '2026-06-01')).toBe('upcoming');
+  });
+});

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

@@ -0,0 +1,95 @@
+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 { renderComplianceMarkdown } from '../markdown.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('renderComplianceMarkdown — matrix', () => {
+  it('renders a table with status cells and gap dashes', () => {
+    const md = renderComplianceMarkdown(synthetic(), { mode: 'matrix' });
+    expect(md).toContain('# Compliance Matrix');
+    expect(md).toContain('| Product \\ Requirement | Erasure | Logs |');
+    expect(md).toMatch(/\| Mobile App \| Compliant \| — \|/);
+  });
+});
+
+describe('renderComplianceMarkdown — law', () => {
+  it('renders the law name and its requirement with the assertion bullet', () => {
+    const md = renderComplianceMarkdown(synthetic(), { mode: 'law', id: 'LAW-X-1' });
+    expect(md).toContain('# Compliance — Privacy Law');
+    expect(md).toContain('## Erasure (`REQUIREMENT-ERASURE-1`) — severity: high');
+    expect(md).toContain('- **Compliant** — `ASSERTION-1`');
+  });
+});
+
+describe('renderComplianceMarkdown — product', () => {
+  it('renders the product table of asserted requirements', () => {
+    const md = renderComplianceMarkdown(synthetic(), { mode: 'product', id: 'PRODUCT-M-1' });
+    expect(md).toContain('# Compliance — Mobile App');
+    expect(md).toContain('| Requirement | Status | Assertion | Next review |');
+    expect(md).toMatch(/\| Erasure \(`REQUIREMENT-ERASURE-1`\) \| Compliant \| `ASSERTION-1` \| 2026-09-01 \|/);
+  });
+});
+
+describe('renderComplianceMarkdown — gap', () => {
+  it('lists the un-asserted requirement as a checklist item', () => {
+    const md = renderComplianceMarkdown(synthetic(), { mode: 'gap' }, { today: '2026-06-02' });
+    expect(md).toContain('## Requirements without assertions (1)');
+    expect(md).toContain('- [ ] `REQUIREMENT-LOG-1` Logs — severity: low');
+    expect(md).toContain('## Assertions without evidence — ASSERT-007 (0)');
+  });
+});
+
+// ── Conformance: build canon by ingesting the acme example files ────────────
+
+const examples = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus');
+function ingestDir(canon: ComplianceCanon, dir: string): void {
+  const full = path.join(examples, dir);
+  for (const f of readdirSync(full)) {
+    if (!f.endsWith('.yaml')) continue;
+    ingestComplianceDoc(canon, yaml.load(readFileSync(path.join(full, f), 'utf-8')));
+  }
+}
+
+describe('renderComplianceMarkdown — acme conformance', () => {
+  const canon = emptyCanon();
+  ingestDir(canon, 'product');
+  ingestDir(canon, 'requirement');
+  ingestDir(canon, 'assertion');
+
+  it('matrix marks the dangling PRODUCT-MOBILE-1 row and shows compliant + gaps', () => {
+    const md = renderComplianceMarkdown(canon, { mode: 'matrix' });
+    expect(md).toContain('PRODUCT-MOBILE-1 ⚠');
+    expect(md).toContain('Compliant');
+    expect(md).toContain('—'); // at least one gap dash
+  });
+
+  it('gap report surfaces the un-asserted audit-log requirement', () => {
+    const md = renderComplianceMarkdown(canon, { mode: 'gap' }, { today: '2026-06-02' });
+    expect(md).toContain('`REQUIREMENT-AUDIT-LOG-RETENTION-1`');
+  });
+});
+
+describe('gapMarkdown CV-5 pastDeadlineRequirements section', () => {
+  it('includes the 4th section in output', () => {
+    const canon = emptyCanon();
+    ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQ-PD-1', name: 'Past', deadline: '2020-01-01' });
+    const md = renderComplianceMarkdown(canon, { mode: 'gap' }, { today: '2026-06-09' });
+    expect(md).toContain('Past-deadline requirements');
+    expect(md).toContain('REQ-PD-1');
+    expect(md).toContain('2020-01-01');
+    expect(md).toContain('4 checks');
+  });
+});

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

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { buildComplianceIndex } from '../reverse-index.js';
+import { buildLawTree, buildProductView } from '../views.js';
+import type { ComplianceIndexInput } from '../types.js';
+
+const input: ComplianceIndexInput = {
+  requirements: [
+    { id: 'REQUIREMENT-A-1', name: 'A', severity: 'high', derived_from: ['LAW-X-1'] },
+    { id: 'REQUIREMENT-B-1', name: 'B', severity: 'low', derived_from: ['LAW-X-1', 'REGULATION-Y-1'] },
+    { id: 'REQUIREMENT-C-1', name: 'C' }, // internal-only, no law
+  ],
+  assertions: [
+    { id: 'ASSERTION-2', about: 'REQUIREMENT-A-1', subject: 'PRODUCT-M-1', status: 'compliant' },
+    { id: 'ASSERTION-1', about: 'REQUIREMENT-A-1', subject: 'CAPABILITY-V2', status: 'under_review' },
+    { id: 'ASSERTION-3', about: 'REQUIREMENT-B-1', subject: 'PRODUCT-M-1', status: 'partial' },
+  ],
+};
+
+describe('buildComplianceIndex', () => {
+  const idx = buildComplianceIndex(input);
+  it('indexes requirements by the laws they derive from', () => {
+    expect(idx.requirementsByLaw.get('LAW-X-1')?.map(r => r.id)).toEqual(['REQUIREMENT-A-1', 'REQUIREMENT-B-1']);
+    expect(idx.requirementsByLaw.get('REGULATION-Y-1')?.map(r => r.id)).toEqual(['REQUIREMENT-B-1']);
+    expect(idx.requirementsByLaw.has('LAW-NONE-1')).toBe(false);
+  });
+  it('indexes assertions by requirement and by subject', () => {
+    expect(idx.assertionsByRequirement.get('REQUIREMENT-A-1')?.map(a => a.id).sort()).toEqual(['ASSERTION-1', 'ASSERTION-2']);
+    expect(idx.assertionsBySubject.get('PRODUCT-M-1')?.map(a => a.id).sort()).toEqual(['ASSERTION-2', 'ASSERTION-3']);
+  });
+});
+
+describe('buildLawTree', () => {
+  const idx = buildComplianceIndex(input);
+  it('lists requirements derived from the law, each with its id-sorted assertions', () => {
+    const tree = buildLawTree('LAW-X-1', idx);
+    expect(tree.requirements.map(r => r.requirement.id)).toEqual(['REQUIREMENT-A-1', 'REQUIREMENT-B-1']);
+    expect(tree.requirements[0].assertions.map(a => a.id)).toEqual(['ASSERTION-1', 'ASSERTION-2']);
+    expect(tree.requirements[0].assertions.map(a => a.status)).toEqual(['under_review', 'compliant']);
+  });
+  it('returns an empty tree for an unknown law', () => {
+    expect(buildLawTree('LAW-NONE-1', idx).requirements).toEqual([]);
+  });
+});
+
+describe('buildProductView', () => {
+  const idx = buildComplianceIndex(input);
+  it('lists the requirements the product is asserted against, with status, requirement-id-sorted', () => {
+    const view = buildProductView('PRODUCT-M-1', idx);
+    expect(view.requirements.map(r => r.requirement.id)).toEqual(['REQUIREMENT-A-1', 'REQUIREMENT-B-1']);
+    expect(view.requirements.map(r => r.assertion.status)).toEqual(['compliant', 'partial']);
+    expect(view.requirements[0].requirement.name).toBe('A');
+  });
+  it('falls back to the id as name when the requirement is not in the scan (dangling about)', () => {
+    const idx2 = buildComplianceIndex({
+      requirements: [],
+      assertions: [{ id: 'ASSERTION-9', about: 'REQUIREMENT-GONE-1', subject: 'PRODUCT-M-1', status: 'n_a' }],
+    });
+    const view = buildProductView('PRODUCT-M-1', idx2);
+    expect(view.requirements[0].requirement).toEqual({ id: 'REQUIREMENT-GONE-1', name: 'REQUIREMENT-GONE-1' });
+  });
+  it('returns an empty view for a product with no assertions', () => {
+    expect(buildProductView('PRODUCT-NONE-1', idx).requirements).toEqual([]);
+  });
+});