@transitrix/diagrams 1.0.0

package/dist/compliance/impact.js

@@ -0,0 +1,464 @@
+// Compliance-impact matrix derivation + markdown renderer
+// (vkgeorgia/strategy#166 — interim renderer; CV-1 view-config wiring
+// per strategy#84 decomposition refresh).
+//
+// Implements the render contract from
+// methodology/notations/views/21-compliance-impact.md §5 at the coarsest grain
+// (`product` columns × `obligation` rows). Stage / task grouping is planned
+// for CV-3a and intentionally out of scope here.
+import { buildComplianceIndex } from './reverse-index.js';
+// ── Pinned defaults ─────────────────────────────────────────────────────────
+/**
+ * Explicit defaults for every optional field in ImpactViewConfig.
+ *
+ * When a view config omits a field, COMPLIANCE_IMPACT_DEFAULTS defines the
+ * assumed behaviour. The CLI prints these so re-runs without a full config
+ * are auditable ("what I assumed").
+ */
+export const COMPLIANCE_IMPACT_DEFAULTS = {
+    /** Accept all four active statuses + n_a in cell aggregation. */
+    status_display: {
+        show: ['compliant', 'partial', 'non_compliant', 'under_review', 'n_a'],
+    },
+    /** Order rows by canonical REQUIREMENT ID (lexicographic). */
+    order_rows_by: 'id',
+    /** §5.3 empty-cell labels. */
+    empty_cells: {
+        no_obligation_label: 'No mapped obligation (current model)',
+        no_obligation_applies_label: 'No obligation applies',
+    },
+    /** Obligation scope: all known REQUIREMENTs in the canon (no filter). */
+    obligations: { include: undefined, filter: undefined },
+    /** Subjects: empty — must be supplied explicitly in the view config. */
+    subjects: { products: [], processes: [] },
+    /** Column grain: one column per business object (no stage decomposition). */
+    grouping: { columns: 'object' },
+};
+/**
+ * Validate and normalise a raw (YAML-parsed) value into an ImpactViewConfig.
+ *
+ * Accepts both the bare config object and the view-config file shape
+ * (`{ view: { id, name, … } }`) — the top-level `view:` wrapper is unwrapped
+ * automatically.
+ *
+ * Every optional field is filled from COMPLIANCE_IMPACT_DEFAULTS, so callers
+ * can rely on the returned config being complete without any `??` chains.
+ *
+ * Returns `{ ok: false, errors }` on schema violations rather than throwing,
+ * so the CLI can surface a clean error message without a stack trace.
+ */
+export function parseImpactViewConfig(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, errors: ['view config: expected an object at the document root'] };
+    }
+    const top = raw;
+    // Unwrap optional `view:` wrapper (view-config YAML files use this key).
+    const v = 'view' in top && top.view && typeof top.view === 'object' && !Array.isArray(top.view)
+        ? top.view
+        : top;
+    const errors = [];
+    if (!v.id || typeof v.id !== 'string')
+        errors.push('view.id: required string');
+    if (!v.name || typeof v.name !== 'string')
+        errors.push('view.name: required string');
+    if (v.subjects !== undefined && (typeof v.subjects !== 'object' || Array.isArray(v.subjects))) {
+        errors.push('view.subjects: expected an object');
+    }
+    if (errors.length)
+        return { ok: false, errors };
+    const subjects = v.subjects && typeof v.subjects === 'object' && !Array.isArray(v.subjects)
+        ? v.subjects
+        : {};
+    const obligations = v.obligations && typeof v.obligations === 'object' && !Array.isArray(v.obligations)
+        ? v.obligations
+        : {};
+    const obFilter = obligations.filter && typeof obligations.filter === 'object' && !Array.isArray(obligations.filter)
+        ? obligations.filter
+        : null;
+    const statusDisplay = v.status_display && typeof v.status_display === 'object' && !Array.isArray(v.status_display)
+        ? v.status_display
+        : {};
+    const emptyCells = v.empty_cells && typeof v.empty_cells === 'object' && !Array.isArray(v.empty_cells)
+        ? v.empty_cells
+        : {};
+    const config = {
+        id: v.id,
+        name: v.name,
+        description: typeof v.description === 'string' ? v.description : undefined,
+        snapshot_at: typeof v.snapshot_at === 'string' ? v.snapshot_at : undefined,
+        subjects: {
+            products: Array.isArray(subjects.products)
+                ? subjects.products.filter((x) => typeof x === 'string')
+                : [...COMPLIANCE_IMPACT_DEFAULTS.subjects.products],
+            processes: Array.isArray(subjects.processes)
+                ? subjects.processes.filter((x) => typeof x === 'string')
+                : [...COMPLIANCE_IMPACT_DEFAULTS.subjects.processes],
+        },
+        obligations: {
+            include: Array.isArray(obligations.include)
+                ? obligations.include.filter((x) => typeof x === 'string')
+                : undefined,
+            filter: obFilter
+                ? {
+                    derived_from_codex: Array.isArray(obFilter.derived_from_codex)
+                        ? obFilter.derived_from_codex.filter((x) => typeof x === 'string')
+                        : undefined,
+                }
+                : undefined,
+        },
+        status_display: {
+            show: Array.isArray(statusDisplay.show)
+                ? statusDisplay.show.filter((x) => typeof x === 'string')
+                : [...COMPLIANCE_IMPACT_DEFAULTS.status_display.show],
+        },
+        empty_cells: {
+            no_obligation_label: typeof emptyCells.no_obligation_label === 'string'
+                ? emptyCells.no_obligation_label
+                : COMPLIANCE_IMPACT_DEFAULTS.empty_cells.no_obligation_label,
+            no_obligation_applies_label: typeof emptyCells.no_obligation_applies_label === 'string'
+                ? emptyCells.no_obligation_applies_label
+                : COMPLIANCE_IMPACT_DEFAULTS.empty_cells.no_obligation_applies_label,
+        },
+        order_rows_by: v.order_rows_by === 'name' ? 'name' : COMPLIANCE_IMPACT_DEFAULTS.order_rows_by,
+    };
+    return { ok: true, config };
+}
+const DEFAULT_NO_OBLIGATION_LABEL = 'No mapped obligation (current model)';
+const DEFAULT_NO_OBLIGATION_APPLIES_LABEL = 'No obligation applies';
+// ── Deadline temporal status (CV-3) ─────────────────────────────────────────
+/** Number of days within which a deadline is considered "in force" (imminent). */
+const IN_FORCE_HORIZON_DAYS = 30;
+/**
+ * Classify a REQUIREMENT deadline relative to a reference date.
+ *
+ * @param deadline  ISO 8601 date string (YYYY-MM-DD), or undefined.
+ * @param today     Reference date string (YYYY-MM-DD); defaults to today.
+ */
+export function computeDeadlineStatus(deadline, today = new Date().toISOString().slice(0, 10)) {
+    if (!deadline)
+        return 'none';
+    if (deadline < today)
+        return 'past_due';
+    const daysAway = Math.round((new Date(deadline).getTime() - new Date(today).getTime()) / (1000 * 60 * 60 * 24));
+    return daysAway <= IN_FORCE_HORIZON_DAYS ? 'in_force' : 'upcoming';
+}
+function byId(a, b) {
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function resolveObligations(config, index, allRequirements) {
+    // `include` wins over `filter` per §4 (and COMPIMP-007).
+    if (config.obligations.include?.length) {
+        const out = [];
+        for (const id of config.obligations.include) {
+            const r = index.requirementById.get(id);
+            if (r)
+                out.push(r);
+        }
+        return out;
+    }
+    const codices = config.obligations.filter?.derived_from_codex ?? [];
+    if (codices.length === 0)
+        return [...allRequirements].sort(byId);
+    const seen = new Set();
+    const out = [];
+    for (const codex of codices) {
+        for (const r of index.requirementsByLaw.get(codex) ?? []) {
+            if (!seen.has(r.id)) {
+                seen.add(r.id);
+                out.push(r);
+            }
+        }
+    }
+    return out;
+}
+function orderRows(rows, key) {
+    const sorted = [...rows];
+    if (key === 'name') {
+        sorted.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    }
+    else {
+        sorted.sort(byId);
+    }
+    return sorted;
+}
+/** Aggregate multiple matching assertions into one cell value, per §5.2 step 4.
+ *  Assumes at least one assertion matches an allowed status; caller filters. */
+function aggregateStatus(assertions) {
+    let sawPartial = false;
+    let sawUnderReview = false;
+    let sawCompliant = false;
+    for (const a of assertions) {
+        if (a.status === 'non_compliant')
+            return 'non_compliant';
+        if (a.status === 'partial')
+            sawPartial = true;
+        else if (a.status === 'under_review')
+            sawUnderReview = true;
+        else if (a.status === 'compliant')
+            sawCompliant = true;
+    }
+    if (sawPartial)
+        return 'partial';
+    if (sawUnderReview)
+        return 'under_review';
+    if (sawCompliant)
+        return 'compliant';
+    return 'n_a';
+}
+// ── Column builder helpers (CV-3a) ──────────────────────────────────────────
+function buildProductColumns(config) {
+    const subjects = [...(config.subjects.products ?? []), ...(config.subjects.processes ?? [])];
+    return subjects.map(id => ({ subjectId: id, label: id }));
+}
+function buildObjectDetailColumns(config, objectDetails) {
+    const detailMap = new Map(objectDetails.map(d => [d.objectId, d.details]));
+    const subjects = [...(config.subjects.products ?? []), ...(config.subjects.processes ?? [])];
+    const cols = [];
+    for (const subjectId of subjects) {
+        const details = detailMap.get(subjectId);
+        if (!details || details.length === 0) {
+            cols.push({ subjectId, label: subjectId });
+        }
+        else {
+            for (const detail of details) {
+                cols.push({ subjectId, stageId: detail.id, label: `${subjectId}:${detail.id}` });
+            }
+        }
+    }
+    return cols;
+}
+/**
+ * Returns true when assertion `a` contributes to column `col`.
+ *
+ * At `'product'` grain: `a.subject` must match `col.subjectId`.
+ * At `'product-stage'` grain: `a.subject` must match AND either
+ * `a.realised_via` is absent (claim covers the whole subject, so every stage
+ * inherits it) OR `col.stageId` ∈ `a.realised_via`.
+ */
+function assertionMatchesColumn(a, col) {
+    if (a.subject !== col.subjectId)
+        return false;
+    if (!col.stageId)
+        return true;
+    if (!a.realised_via || a.realised_via.length === 0)
+        return true;
+    return a.realised_via.includes(col.stageId);
+}
+/**
+ * Build the matrix per §5.2.
+ *
+ * At the default `grouping.columns: 'product'` grain, one column per subject.
+ * At `grouping.columns: 'product-stage'`, pass `objectDetails` to expand each
+ * subject into per-stage sub-columns (typically extracted from a
+ * process-blueprint document via `extractObjectDetails`).  Subjects with no
+ * stage mapping fall back to a single product-grain column automatically.
+ *
+ * Subjects are taken from `config.subjects.products` and
+ * `config.subjects.processes` (in that order).  Subjects with no binding
+ * obligation still appear as columns so the gap is visible.
+ */
+export function buildImpactMatrix(canon, config, objectDetails) {
+    const index = buildComplianceIndex({
+        requirements: canon.requirements,
+        assertions: canon.assertions,
+    });
+    const obligations = orderRows(resolveObligations(config, index, canon.requirements), config.order_rows_by);
+    const useStageGrain = config.grouping?.columns === 'object-details' && objectDetails && objectDetails.length > 0;
+    const columns = useStageGrain
+        ? buildObjectDetailColumns(config, objectDetails)
+        : buildProductColumns(config);
+    const allowedStatuses = new Set(config.status_display?.show ?? ['compliant', 'partial', 'non_compliant', 'under_review', 'n_a']);
+    const rowIndex = new Set(obligations.map(r => r.id));
+    const cells = obligations.map(() => columns.map(() => emptyCell()));
+    for (let c = 0; c < columns.length; c++) {
+        const col = columns[c];
+        const subjectAssertions = index.assertionsBySubject.get(col.subjectId) ?? [];
+        for (const a of subjectAssertions) {
+            if (!rowIndex.has(a.about))
+                continue;
+            if (!allowedStatuses.has(a.status))
+                continue;
+            if (!assertionMatchesColumn(a, col))
+                continue;
+            const rowIdx = obligations.findIndex(r => r.id === a.about);
+            if (rowIdx < 0)
+                continue;
+            cells[rowIdx][c].assertions.push(a);
+        }
+    }
+    // Resolve each cell to a status / kind.
+    for (let r = 0; r < cells.length; r++) {
+        for (let c = 0; c < cells[r].length; c++) {
+            const cell = cells[r][c];
+            cell.assertions.sort(byId);
+            if (cell.assertions.length === 0) {
+                cell.kind = 'gap';
+                cell.status = null;
+                continue;
+            }
+            if (cell.assertions.every(a => a.status === 'n_a')) {
+                cell.kind = 'n_a_only';
+                cell.status = 'n_a';
+                continue;
+            }
+            cell.kind = 'bound';
+            cell.status = aggregateStatus(cell.assertions);
+        }
+    }
+    // ── CV-3 decorations ────────────────────────────────────────────────────
+    const today = new Date().toISOString().slice(0, 10);
+    for (let r = 0; r < cells.length; r++) {
+        const req = obligations[r];
+        const deadlineStatus = computeDeadlineStatus(req.deadline, today);
+        // "new" = requirement admitted after the snapshot date.
+        const isNew = !!config.snapshot_at &&
+            !!req.admitted_at &&
+            req.admitted_at > config.snapshot_at;
+        for (let c = 0; c < cells[r].length; c++) {
+            const cell = cells[r][c];
+            const isUrgent = cell.kind === 'gap' &&
+                (deadlineStatus === 'past_due' || deadlineStatus === 'in_force');
+            cell.decoration = { isNew, isUrgent, deadlineStatus };
+        }
+    }
+    // ── CV-3 derived obligations lane ───────────────────────────────────────
+    // For each column: collect codex source IDs from non-gap rows.
+    const obligationsLane = columns.map((_, c) => {
+        const codexIds = new Set();
+        for (let r = 0; r < cells.length; r++) {
+            if (cells[r][c].kind !== 'gap') {
+                for (const src of obligations[r].derived_from ?? []) {
+                    codexIds.add(src);
+                }
+            }
+        }
+        return [...codexIds].sort();
+    });
+    return {
+        viewId: config.id,
+        viewName: config.name,
+        description: config.description,
+        snapshotAt: config.snapshot_at,
+        rows: obligations,
+        columns,
+        cells,
+        emptyLabels: {
+            no_obligation_label: config.empty_cells?.no_obligation_label ?? DEFAULT_NO_OBLIGATION_LABEL,
+            no_obligation_applies_label: config.empty_cells?.no_obligation_applies_label ?? DEFAULT_NO_OBLIGATION_APPLIES_LABEL,
+        },
+        obligationsLane,
+    };
+}
+function emptyCell() {
+    return {
+        status: null,
+        kind: 'gap',
+        assertions: [],
+        decoration: { isNew: false, isUrgent: false, deadlineStatus: 'none' },
+    };
+}
+// ── Process-blueprint stage extractor (CV-3a) ───────────────────────────────
+/**
+ * Extract `ObjectDetailInput` from a raw (YAML-parsed) process-blueprint document.
+ *
+ * Accepts both the bare document object and the wrapped form
+ * (`{ process_blueprint: { id, stages: […] } }`).
+ * Returns `null` when the document is not a recognisable process-blueprint or
+ * has no `id` / `stages` array so callers can skip unrecognised files safely.
+ *
+ * Pass the returned value into `buildImpactMatrix` as part of the
+ * `objectDetails` array when `grouping.columns: 'product-stage'` is configured.
+ */
+export function extractObjectDetails(doc) {
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        return null;
+    const top = doc;
+    const bp = top.notation === 'process_blueprint'
+        ? top
+        : top.process_blueprint && typeof top.process_blueprint === 'object' && !Array.isArray(top.process_blueprint)
+            ? top.process_blueprint
+            : null;
+    if (!bp)
+        return null;
+    const id = typeof bp.id === 'string' ? bp.id : null;
+    if (!id)
+        return null;
+    if (!Array.isArray(bp.stages))
+        return null;
+    const details = [];
+    for (const s of bp.stages) {
+        if (!s || typeof s !== 'object' || Array.isArray(s))
+            continue;
+        const sid = typeof s.id === 'string' ? s.id : null;
+        if (!sid)
+            continue;
+        details.push({ id: sid, name: typeof s.name === 'string' ? s.name : sid });
+    }
+    return { objectId: id, details };
+}
+// ── Markdown rendering ──────────────────────────────────────────────────────
+const STATUS_GLYPH = {
+    compliant: 'OK',
+    partial: 'PARTIAL',
+    non_compliant: 'FAIL',
+    under_review: 'REVIEW',
+    n_a: 'N/A',
+};
+function escMd(s) {
+    return s.replace(/\|/g, '\\|');
+}
+/**
+ * Render the matrix as a GitHub-flavoured markdown table.
+ *
+ * Cell display:
+ *   - `bound`    → the §5.2 deterministic status label.
+ *   - `n_a_only` → the "No obligation applies" label (or `view.empty_cells`
+ *                  override).
+ *   - `gap`      → the "No mapped obligation (current model)" label (or
+ *                  override).
+ */
+export function renderImpactMarkdown(matrix) {
+    const lines = [];
+    lines.push(`# ${matrix.viewName}`);
+    lines.push('');
+    lines.push(`View ID: \`${matrix.viewId}\``);
+    if (matrix.snapshotAt)
+        lines.push(`Report snapshot: ${matrix.snapshotAt}`);
+    if (matrix.description) {
+        lines.push('');
+        lines.push(matrix.description);
+    }
+    lines.push('');
+    if (matrix.rows.length === 0) {
+        lines.push('_No obligations in scope — the configured filter / include selected zero REQUIREMENTs._');
+        return lines.join('\n') + '\n';
+    }
+    if (matrix.columns.length === 0) {
+        lines.push('_No subjects in scope — `view.subjects` is empty._');
+        return lines.join('\n') + '\n';
+    }
+    const header = ['Obligation', ...matrix.columns.map(col => escMd(col.label))];
+    lines.push('| ' + header.join(' | ') + ' |');
+    lines.push('|' + header.map(() => '---').join('|') + '|');
+    for (let r = 0; r < matrix.rows.length; r++) {
+        const row = matrix.rows[r];
+        const rowLabel = `${row.id}${row.name && row.name !== row.id ? ` — ${row.name}` : ''}`;
+        const cells = matrix.cells[r].map(cell => renderCell(cell, matrix.emptyLabels));
+        lines.push('| ' + [escMd(rowLabel), ...cells].join(' | ') + ' |');
+    }
+    // Legend — the §5.3 distinction must be visible in the rendered output.
+    lines.push('');
+    lines.push('## Legend');
+    lines.push('');
+    lines.push('- **OK / PARTIAL / FAIL / REVIEW / N/A** — aggregated `ASSERTION.status` per §5.2.');
+    lines.push(`- **${escMd(matrix.emptyLabels.no_obligation_label)}** — modelling gap; no admitted ASSERTION binds this (obligation, subject) pair.`);
+    lines.push(`- **${escMd(matrix.emptyLabels.no_obligation_applies_label)}** — modelled fact; an admitted ASSERTION with status \`n_a\` excludes this pair.`);
+    return lines.join('\n') + '\n';
+}
+function renderCell(cell, labels) {
+    if (cell.kind === 'gap')
+        return escMd(labels.no_obligation_label);
+    if (cell.kind === 'n_a_only')
+        return escMd(labels.no_obligation_applies_label);
+    return STATUS_GLYPH[cell.status];
+}

package/dist/compliance/index.d.ts

@@ -0,0 +1,16 @@
+export { buildComplianceIndex } from './reverse-index.js';
+export { buildLawTree, buildProductView } from './views.js';
+export { buildGapReport } from './gap-report.js';
+export type { GapReport, GapReportOptions } from './gap-report.js';
+export { emptyCanon, ingestComplianceDoc } from './classify.js';
+export type { ComplianceCanon, ComplianceProduct, ComplianceCodexDoc } from './classify.js';
+export { renderComplianceMarkdown } from './markdown.js';
+export type { ReportScope, MarkdownOptions } from './markdown.js';
+export { renderComplianceHtml, renderImpactMatrixHtml } from './html.js';
+export type { HtmlOptions, ImpactMatrixHtmlOptions } from './html.js';
+export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, computeDeadlineStatus } from './impact.js';
+export type { ImpactCell, ImpactColumn, ImpactEmptyCellLabels, ImpactGrouping, ImpactMatrix, ImpactObligationFilter, ImpactStatusDisplay, ImpactSubjects, ImpactViewConfig, ParseImpactViewConfigResult, } from './impact.js';
+export { assertionToScoringElement, complianceConfidenceHeader, requirementToScoringElement, scoreComplianceView, } from './confidence.js';
+export { parseCoverageMetricConfig, buildCoverageMatrix, } from './coverage-metric.js';
+export type { CoverageMetricConfig, CoverageMetricScope, CoverageMetricSubjects, CoverageMetricThresholds, CoverageMatrix, CoverageRow, ParseCoverageMetricResult, RagStatus, } from './coverage-metric.js';
+export type { ComplianceIndex, ComplianceIndexInput, DeadlineStatus, IndexRequirement, IndexAssertion, LawTree, LawTreeRequirement, ProductView, ProductRequirementStatus, ObjectDetailDef, ObjectDetailInput, } from './types.js';

package/dist/compliance/index.js

@@ -0,0 +1,9 @@
+export { buildComplianceIndex } from './reverse-index.js';
+export { buildLawTree, buildProductView } from './views.js';
+export { buildGapReport } from './gap-report.js';
+export { emptyCanon, ingestComplianceDoc } from './classify.js';
+export { renderComplianceMarkdown } from './markdown.js';
+export { renderComplianceHtml, renderImpactMatrixHtml } from './html.js';
+export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, computeDeadlineStatus } from './impact.js';
+export { assertionToScoringElement, complianceConfidenceHeader, requirementToScoringElement, scoreComplianceView, } from './confidence.js';
+export { parseCoverageMetricConfig, buildCoverageMatrix, } from './coverage-metric.js';

package/dist/compliance/markdown.d.ts

@@ -0,0 +1,18 @@
+import type { ComplianceCanon } from './classify.js';
+export type ReportScope = {
+    mode: 'matrix';
+} | {
+    mode: 'law';
+    id: string;
+} | {
+    mode: 'product';
+    id: string;
+} | {
+    mode: 'gap';
+};
+export interface MarkdownOptions {
+    /** Today as ISO YYYY-MM-DD — enables the gap dashboard's stale-assertion list. */
+    today?: string;
+}
+/** Renders the requested compliance view from a scanned canon to Markdown. */
+export declare function renderComplianceMarkdown(canon: ComplianceCanon, scope: ReportScope, options?: MarkdownOptions): string;

package/dist/compliance/markdown.js

@@ -0,0 +1,129 @@
+// Markdown renderers for the compliance views (vkgeorgia/strategy#84 Phase 5).
+// Pure string builders consumed by the `transitrix export-compliance` CLI.
+// PDF rendering lives in `html.ts` (HTML doc fed to WeasyPrint by the CLI).
+import { buildComplianceMatrix } from '../compliance-matrix/index.js';
+import { buildComplianceIndex } from './reverse-index.js';
+import { buildLawTree, buildProductView } from './views.js';
+import { buildGapReport } from './gap-report.js';
+const STATUS_LABELS = {
+    compliant: 'Compliant',
+    partial: 'Partial',
+    non_compliant: 'Non-compliant',
+    under_review: 'Under review',
+    n_a: 'N/A',
+};
+/** Escapes a value for a Markdown table cell (pipes + newlines). */
+function cell(s) {
+    return s.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+/** Renders the requested compliance view from a scanned canon to Markdown. */
+export function renderComplianceMarkdown(canon, scope, options = {}) {
+    switch (scope.mode) {
+        case 'matrix': return matrixMarkdown(canon);
+        case 'law': return lawMarkdown(canon, scope.id);
+        case 'product': return productMarkdown(canon, scope.id);
+        case 'gap': return gapMarkdown(canon, options.today);
+    }
+}
+function matrixMarkdown(canon) {
+    const m = buildComplianceMatrix({ products: canon.products, requirements: canon.requirements, assertions: canon.assertions });
+    const out = ['# Compliance Matrix', ''];
+    out.push(`_${m.summary.products} products × ${m.summary.requirements} requirements · ${m.summary.gaps} gaps · ${m.summary.assertions} assertions_`, '');
+    if (m.products.length === 0 || m.requirements.length === 0) {
+        out.push('_No products or requirements found in the scanned canon._', '');
+        return out.join('\n');
+    }
+    out.push(`| Product \\ Requirement | ${m.requirements.map(r => cell(r.name)).join(' | ')} |`);
+    out.push(`|---|${m.requirements.map(() => '---').join('|')}|`);
+    m.products.forEach((p, ri) => {
+        const cells = m.requirements.map((_r, ci) => {
+            const c = m.cells[ri][ci];
+            return c.status ? STATUS_LABELS[c.status] : '—';
+        });
+        const name = cell(p.name) + (p.unresolved ? ' ⚠' : '');
+        out.push(`| ${name} | ${cells.join(' | ')} |`);
+    });
+    out.push('');
+    return out.join('\n');
+}
+function lawMarkdown(canon, lawId) {
+    const index = buildComplianceIndex({ requirements: canon.requirements, assertions: canon.assertions });
+    const tree = buildLawTree(lawId, index);
+    const law = canon.codex.find(c => c.id === lawId);
+    const out = [`# Compliance — ${law ? law.name : lawId}`, ''];
+    out.push(`\`${lawId}\` · ${tree.requirements.length} requirement(s)`, '');
+    if (tree.requirements.length === 0) {
+        out.push(`_No requirements derive from \`${lawId}\`._`, '');
+        return out.join('\n');
+    }
+    for (const node of tree.requirements) {
+        const sev = node.requirement.severity ? ` — severity: ${node.requirement.severity}` : '';
+        out.push(`## ${node.requirement.name} (\`${node.requirement.id}\`)${sev}`, '');
+        if (node.assertions.length === 0) {
+            out.push('_No assertion — compliance gap._', '');
+            continue;
+        }
+        for (const a of node.assertions) {
+            const meta = [a.assessed_at ? `assessed ${a.assessed_at}` : null, a.next_review_at ? `review by ${a.next_review_at}` : null].filter(Boolean).join(', ');
+            out.push(`- **${STATUS_LABELS[a.status]}** — \`${a.id}\` (subject \`${a.subject}\`${meta ? `; ${meta}` : ''})`);
+        }
+        out.push('');
+    }
+    return out.join('\n');
+}
+function productMarkdown(canon, productId) {
+    const index = buildComplianceIndex({ requirements: canon.requirements, assertions: canon.assertions });
+    const view = buildProductView(productId, index);
+    const product = canon.products.find(p => p.id === productId);
+    const out = [`# Compliance — ${product ? product.name : productId}`, ''];
+    out.push(`\`${productId}\` · ${view.requirements.length} requirement(s) asserted`, '');
+    if (view.requirements.length === 0) {
+        out.push('_No assertion names this product as its subject._', '');
+        return out.join('\n');
+    }
+    out.push('| Requirement | Status | Assertion | Next review |', '|---|---|---|---|');
+    for (const { requirement, assertion } of view.requirements) {
+        out.push(`| ${cell(requirement.name)} (\`${requirement.id}\`) | ${STATUS_LABELS[assertion.status]} | \`${assertion.id}\` | ${assertion.next_review_at ?? '—'} |`);
+    }
+    out.push('');
+    return out.join('\n');
+}
+function gapMarkdown(canon, today) {
+    const index = buildComplianceIndex({ requirements: canon.requirements, assertions: canon.assertions });
+    const report = buildGapReport(index, { today });
+    const total = report.requirementsWithoutAssertions.length + report.assertionsWithoutEvidence.length + report.staleAssertions.length + report.pastDeadlineRequirements.length;
+    const out = ['# Compliance Gap Dashboard', '', `_${total} gap(s) across 4 checks_`, ''];
+    out.push(`## Requirements without assertions (${report.requirementsWithoutAssertions.length})`, '');
+    if (report.requirementsWithoutAssertions.length === 0)
+        out.push('_✓ none_', '');
+    else {
+        for (const r of report.requirementsWithoutAssertions)
+            out.push(`- [ ] \`${r.id}\` ${r.name}${r.severity ? ` — severity: ${r.severity}` : ''}${r.deadline ? ` — deadline: ${r.deadline}` : ''}`);
+        out.push('');
+    }
+    out.push(`## Assertions without evidence — ASSERT-007 (${report.assertionsWithoutEvidence.length})`, '');
+    if (report.assertionsWithoutEvidence.length === 0)
+        out.push('_✓ none_', '');
+    else {
+        for (const a of report.assertionsWithoutEvidence)
+            out.push(`- [ ] \`${a.id}\` — about \`${a.about}\`, subject \`${a.subject}\`, status ${a.status}`);
+        out.push('');
+    }
+    out.push(`## Stale assertions — ASSERT-008 (${report.staleAssertions.length})`, '');
+    if (report.staleAssertions.length === 0)
+        out.push('_✓ none_', '');
+    else {
+        for (const a of report.staleAssertions)
+            out.push(`- [ ] \`${a.id}\` — review due ${a.next_review_at ?? '—'}, subject \`${a.subject}\``);
+        out.push('');
+    }
+    out.push(`## Past-deadline requirements — CV-5 (${report.pastDeadlineRequirements.length})`, '');
+    if (report.pastDeadlineRequirements.length === 0)
+        out.push('_✓ none_', '');
+    else {
+        for (const r of report.pastDeadlineRequirements)
+            out.push(`- [ ] \`${r.id}\` ${r.name} — deadline: ${r.deadline ?? '—'}${r.severity ? `, severity: ${r.severity}` : ''}`);
+        out.push('');
+    }
+    return out.join('\n');
+}

package/dist/compliance/reverse-index.d.ts

@@ -0,0 +1,8 @@
+import type { ComplianceIndex, ComplianceIndexInput } from './types.js';
+/**
+ * Builds the reverse indexes used by every compliance view. Pure; the input
+ * arrays are read, not mutated. Requirements with no `derived_from` simply do
+ * not appear under any law; assertions are indexed by both their requirement
+ * (`about`) and their subject.
+ */
+export declare function buildComplianceIndex(input: ComplianceIndexInput): ComplianceIndex;