@transitrix/diagrams 1.0.0

package/dist/compliance/__tests__/impact.test.js

@@ -0,0 +1,410 @@
+import { describe, it, expect } from 'vitest';
+import { emptyCanon } from '../classify.js';
+import { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, computeDeadlineStatus, } from '../impact.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() {
+    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 = {
+    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, subject) => {
+            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) => 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/dist/compliance/__tests__/markdown.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/compliance/__tests__/markdown.test.js

@@ -0,0 +1,85 @@
+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 } from '../classify.js';
+function synthetic() {
+    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, dir) {
+    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/dist/compliance/__tests__/views.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/compliance/__tests__/views.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { buildComplianceIndex } from '../reverse-index.js';
+import { buildLawTree, buildProductView } from '../views.js';
+const input = {
+    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([]);
+    });
+});

package/dist/compliance/classify.d.ts

@@ -0,0 +1,27 @@
+import type { IndexAssertion, IndexRequirement } from './types.js';
+export interface ComplianceProduct {
+    id: string;
+    name: string;
+}
+export interface ComplianceCodexDoc {
+    id: string;
+    name: string;
+    type?: string;
+    jurisdiction?: string;
+}
+/** The bucketed result of scanning a repo for compliance canon. */
+export interface ComplianceCanon {
+    products: ComplianceProduct[];
+    requirements: IndexRequirement[];
+    assertions: IndexAssertion[];
+    codex: ComplianceCodexDoc[];
+}
+export declare function emptyCanon(): ComplianceCanon;
+/**
+ * Classifies one parsed YAML document and, if it is a compliance artefact,
+ * pushes its projection into `canon`. Products / requirements / assertions are
+ * identified by their `notation` tag; codex source documents by `zone: codex`.
+ * Returns the artefact id when ingested (so the caller can record its path), or
+ * null when the document is not a (well-formed) compliance artefact.
+ */
+export declare function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): string | null;

package/dist/compliance/classify.js

@@ -0,0 +1,60 @@
+// Canon-artefact classification (vkgeorgia/strategy#84). The single authority
+// for "what is a compliance artefact" — used by both the Studio extension scan
+// (webview previews) and the CLI scan (`export-compliance`), so the recognition
+// rules live once. Pure: takes a parsed YAML document, no IO.
+export function emptyCanon() {
+    return { products: [], requirements: [], assertions: [], codex: [] };
+}
+const str = (v) => (typeof v === 'string' ? v : undefined);
+const strArray = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined;
+/**
+ * Classifies one parsed YAML document and, if it is a compliance artefact,
+ * pushes its projection into `canon`. Products / requirements / assertions are
+ * identified by their `notation` tag; codex source documents by `zone: codex`.
+ * Returns the artefact id when ingested (so the caller can record its path), or
+ * null when the document is not a (well-formed) compliance artefact.
+ */
+export function ingestComplianceDoc(canon, doc) {
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc))
+        return null;
+    const d = doc;
+    const id = str(d.id);
+    if (!id)
+        return null;
+    if (d.notation === 'product') {
+        canon.products.push({ id, name: str(d.name) ?? id });
+        return id;
+    }
+    if (d.notation === 'requirement') {
+        canon.requirements.push({
+            id,
+            name: str(d.name) ?? id,
+            severity: str(d.severity),
+            derived_from: strArray(d.derived_from),
+            admitted_at: str(d.admitted_at),
+            deadline: str(d.deadline),
+        });
+        return id;
+    }
+    if (d.notation === 'assertion') {
+        const about = str(d.about);
+        const subject = str(d.subject);
+        const status = str(d.status);
+        if (!about || !subject || !status)
+            return null;
+        canon.assertions.push({
+            id, about, subject, status,
+            assessed_at: str(d.assessed_at),
+            next_review_at: str(d.next_review_at),
+            evidenceCount: Array.isArray(d.evidence) ? d.evidence.length : 0,
+            admitted_at: str(d.admitted_at),
+            realised_via: strArray(d.realised_via),
+        });
+        return id;
+    }
+    if (d.zone === 'codex') {
+        canon.codex.push({ id, name: str(d.name) ?? id, type: str(d.type), jurisdiction: str(d.jurisdiction) });
+        return id;
+    }
+    return null;
+}