@transitrix/diagrams 1.0.0

package/dist/compliance/confidence.d.ts

@@ -0,0 +1,27 @@
+import type { ConfidenceDecayConfig, ScoringElement, ViewScore } from '../confidence/index.js';
+import type { IndexAssertion, IndexRequirement } from './types.js';
+/**
+ * Lifts a compliance projection (requirement / assertion) to the DQ-1
+ * ScoringElement shape. `sources` is intentionally left undefined here:
+ * resolving a canon element's `derived_from` to the source_quality of the
+ * cited field artefacts (§11.4) needs the field-zone provenance model
+ * that Studio's compliance scan does not yet ingest (the DSM equivalent
+ * is escalated as DQ-3/DQ-4/DQ-5 on the strategy hub). Until then the
+ * scorer treats every element as unsourced — counted separately per §11.5
+ * — so the headline honestly reports `0% sourced` rather than guessing a
+ * trust label. The freshness signal is fully wired and remains useful.
+ */
+export declare function requirementToScoringElement(r: IndexRequirement): ScoringElement;
+export declare function assertionToScoringElement(a: IndexAssertion): ScoringElement;
+/**
+ * Scores a compliance view composed of the given requirements + assertions.
+ * Pure / derived per §11.6 — recomputed on read, never stored.
+ */
+export declare function scoreComplianceView(requirements: IndexRequirement[], assertions: IndexAssertion[], today: string | Date, config?: ConfidenceDecayConfig): ViewScore;
+/**
+ * Convenience wrapper — scores the view and formats the §11.6 header line.
+ * Returns an empty string for an empty element set so the caller can suppress
+ * the header (e.g. a single-law tree with no requirements). Re-exports
+ * {@link formatConfidenceHeader} for callers that already hold a `ViewScore`.
+ */
+export declare function complianceConfidenceHeader(requirements: IndexRequirement[], assertions: IndexAssertion[], today: string | Date, config?: ConfidenceDecayConfig): string;

package/dist/compliance/confidence.js

@@ -0,0 +1,43 @@
+// Confidence bridge for the compliance views (vkgeorgia/strategy#162 — DQ-2).
+// Maps the compliance index projections (IndexRequirement / IndexAssertion) onto
+// the DQ-1 ScoringElement shape, scores the view, and renders the §11.6 header
+// line. Lives in @transitrix/diagrams so Studio and DSM share one bridge and
+// the headline reads the same on both surfaces.
+import { formatConfidenceHeader, scoreView, } from '../confidence/index.js';
+/**
+ * Lifts a compliance projection (requirement / assertion) to the DQ-1
+ * ScoringElement shape. `sources` is intentionally left undefined here:
+ * resolving a canon element's `derived_from` to the source_quality of the
+ * cited field artefacts (§11.4) needs the field-zone provenance model
+ * that Studio's compliance scan does not yet ingest (the DSM equivalent
+ * is escalated as DQ-3/DQ-4/DQ-5 on the strategy hub). Until then the
+ * scorer treats every element as unsourced — counted separately per §11.5
+ * — so the headline honestly reports `0% sourced` rather than guessing a
+ * trust label. The freshness signal is fully wired and remains useful.
+ */
+export function requirementToScoringElement(r) {
+    return { type: 'REQUIREMENT', admitted_at: r.admitted_at };
+}
+export function assertionToScoringElement(a) {
+    return { type: 'ASSERTION', admitted_at: a.admitted_at };
+}
+/**
+ * Scores a compliance view composed of the given requirements + assertions.
+ * Pure / derived per §11.6 — recomputed on read, never stored.
+ */
+export function scoreComplianceView(requirements, assertions, today, config) {
+    const elements = [
+        ...requirements.map(requirementToScoringElement),
+        ...assertions.map(assertionToScoringElement),
+    ];
+    return scoreView(elements, today, config);
+}
+/**
+ * Convenience wrapper — scores the view and formats the §11.6 header line.
+ * Returns an empty string for an empty element set so the caller can suppress
+ * the header (e.g. a single-law tree with no requirements). Re-exports
+ * {@link formatConfidenceHeader} for callers that already hold a `ViewScore`.
+ */
+export function complianceConfidenceHeader(requirements, assertions, today, config) {
+    return formatConfidenceHeader(scoreComplianceView(requirements, assertions, today, config));
+}

package/dist/compliance/coverage-metric.d.ts

@@ -0,0 +1,74 @@
+import type { ComplianceCanon } from './classify.js';
+export interface CoverageMetricSubjects {
+    products?: string[];
+}
+export interface CoverageMetricScope {
+    jurisdictions?: string[];
+    codex?: string[];
+    subjects?: CoverageMetricSubjects;
+}
+export interface CoverageMetricThresholds {
+    /** Coverage fraction (0–1) at or above which the status is green. */
+    green: number;
+    /** Coverage fraction at or above which the status is amber (below green). */
+    amber: number;
+}
+export interface CoverageMetricConfig {
+    id: string;
+    name: string;
+    description?: string;
+    date?: string;
+    version?: string;
+    scope: CoverageMetricScope;
+    thresholds: CoverageMetricThresholds;
+}
+export type ParseCoverageMetricResult = {
+    ok: true;
+    config: CoverageMetricConfig;
+} | {
+    ok: false;
+    errors: string[];
+};
+export type RagStatus = 'green' | 'amber' | 'red' | 'no_data';
+export interface CoverageRow {
+    codexId: string;
+    /** Jurisdiction from the scanned canon codex doc, if available. */
+    jurisdiction?: string;
+    totalRequirements: number;
+    compliant: number;
+    partial: number;
+    non_compliant: number;
+    under_review: number;
+    /** Requirements with no admitted assertion for the scoped products. */
+    gap: number;
+    /** compliant + partial. */
+    coveredCount: number;
+    /** coveredCount / totalRequirements (0–1). 0 when totalRequirements === 0. */
+    coveragePct: number;
+    ragStatus: RagStatus;
+}
+export interface CoverageMatrix {
+    id: string;
+    name: string;
+    description?: string;
+    date?: string;
+    version?: string;
+    rows: CoverageRow[];
+    thresholds: CoverageMetricThresholds;
+}
+/**
+ * Validate and normalise a raw (YAML-parsed) document into a
+ * `CoverageMetricConfig`. Accepts both the bare top-level object and the
+ * wrapped form (`{ coverage_metric: { … } }`).
+ */
+export declare function parseCoverageMetricConfig(raw: unknown): ParseCoverageMetricResult;
+/**
+ * Compute per-codex coverage statistics.
+ *
+ * For each law (codex ID) in `config.scope.codex`:
+ *  - Collect requirements whose `derived_from` includes that law.
+ *  - Optionally restrict to assertions for `config.scope.subjects.products`.
+ *  - Compute compliant / partial / non_compliant / under_review / gap counts.
+ *  - Compute coverage % = (compliant + partial) / total and apply RAG.
+ */
+export declare function buildCoverageMatrix(canon: ComplianceCanon, config: CoverageMetricConfig): CoverageMatrix;

package/dist/compliance/coverage-metric.js

@@ -0,0 +1,181 @@
+// Coverage-metric view renderer — methodology/notations/views/22-coverage-metric.md
+//
+// Builds a per-codex (law) coverage summary: for each law in scope, how many
+// of its requirements are covered by at least one compliant/partial assertion
+// across the scoped products, and what is the RAG status against the configured
+// thresholds.
+import { buildComplianceIndex } from './reverse-index.js';
+// ── Parser ───────────────────────────────────────────────────────────────────
+/**
+ * Validate and normalise a raw (YAML-parsed) document into a
+ * `CoverageMetricConfig`. Accepts both the bare top-level object and the
+ * wrapped form (`{ coverage_metric: { … } }`).
+ */
+export function parseCoverageMetricConfig(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, errors: ['coverage-metric: expected an object at the document root'] };
+    }
+    const top = raw;
+    // Unwrap optional `coverage_metric:` wrapper.
+    const v = 'coverage_metric' in top &&
+        top.coverage_metric &&
+        typeof top.coverage_metric === 'object' &&
+        !Array.isArray(top.coverage_metric)
+        ? top.coverage_metric
+        : top;
+    const errors = [];
+    if (!v.id || typeof v.id !== 'string')
+        errors.push('coverage_metric.id: required string');
+    if (!v.name || typeof v.name !== 'string')
+        errors.push('coverage_metric.name: required string');
+    if (errors.length)
+        return { ok: false, errors };
+    const rawScope = v.scope && typeof v.scope === 'object' && !Array.isArray(v.scope)
+        ? v.scope
+        : {};
+    const rawSubjects = rawScope.subjects && typeof rawScope.subjects === 'object' && !Array.isArray(rawScope.subjects)
+        ? rawScope.subjects
+        : {};
+    const rawThresholds = v.thresholds && typeof v.thresholds === 'object' && !Array.isArray(v.thresholds)
+        ? v.thresholds
+        : {};
+    const greenRaw = typeof rawThresholds.green === 'number' ? rawThresholds.green : 0.8;
+    const amberRaw = typeof rawThresholds.amber === 'number' ? rawThresholds.amber : 0.5;
+    const config = {
+        id: v.id,
+        name: v.name,
+        description: typeof v.description === 'string' ? v.description : undefined,
+        date: typeof v.date === 'string' ? v.date : undefined,
+        version: typeof v.version === 'string' ? v.version : undefined,
+        scope: {
+            jurisdictions: Array.isArray(rawScope.jurisdictions)
+                ? rawScope.jurisdictions.filter((x) => typeof x === 'string')
+                : undefined,
+            codex: Array.isArray(rawScope.codex)
+                ? rawScope.codex.filter((x) => typeof x === 'string')
+                : undefined,
+            subjects: {
+                products: Array.isArray(rawSubjects.products)
+                    ? rawSubjects.products.filter((x) => typeof x === 'string')
+                    : undefined,
+            },
+        },
+        thresholds: {
+            green: Math.max(0, Math.min(1, greenRaw)),
+            amber: Math.max(0, Math.min(1, amberRaw)),
+        },
+    };
+    return { ok: true, config };
+}
+// ── Builder ───────────────────────────────────────────────────────────────────
+const ADMITTED = new Set(['compliant', 'partial', 'non_compliant', 'under_review', 'n_a']);
+/** Worst-case aggregate across multiple assertions (excludes n_a when others exist). */
+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';
+}
+function ragFromPct(pct, thresholds, hasData) {
+    if (!hasData)
+        return 'no_data';
+    if (pct >= thresholds.green)
+        return 'green';
+    if (pct >= thresholds.amber)
+        return 'amber';
+    return 'red';
+}
+/**
+ * Compute per-codex coverage statistics.
+ *
+ * For each law (codex ID) in `config.scope.codex`:
+ *  - Collect requirements whose `derived_from` includes that law.
+ *  - Optionally restrict to assertions for `config.scope.subjects.products`.
+ *  - Compute compliant / partial / non_compliant / under_review / gap counts.
+ *  - Compute coverage % = (compliant + partial) / total and apply RAG.
+ */
+export function buildCoverageMatrix(canon, config) {
+    const index = buildComplianceIndex({
+        requirements: canon.requirements,
+        assertions: canon.assertions,
+    });
+    const codexList = config.scope.codex ?? [];
+    const productList = config.scope.subjects?.products ?? [];
+    const rows = [];
+    for (const codexId of codexList) {
+        const reqs = index.requirementsByLaw.get(codexId) ?? [];
+        const codexDoc = canon.codex.find(c => c.id === codexId);
+        const jurisdiction = codexDoc?.jurisdiction;
+        let compliant = 0;
+        let partial = 0;
+        let non_compliant = 0;
+        let under_review = 0;
+        let gap = 0;
+        for (const req of reqs) {
+            const allAssertions = index.assertionsByRequirement.get(req.id) ?? [];
+            // Filter to admitted statuses, then optionally to scoped products.
+            const admitted = allAssertions.filter(a => ADMITTED.has(a.status));
+            const scoped = productList.length > 0
+                ? admitted.filter(a => productList.includes(a.subject))
+                : admitted;
+            // Exclude pure n_a assertions from counting as coverage.
+            const active = scoped.filter(a => a.status !== 'n_a');
+            if (active.length === 0) {
+                gap++;
+                continue;
+            }
+            const status = aggregateStatus(active);
+            if (status === 'compliant')
+                compliant++;
+            else if (status === 'partial')
+                partial++;
+            else if (status === 'non_compliant')
+                non_compliant++;
+            else if (status === 'under_review')
+                under_review++;
+            else
+                gap++;
+        }
+        const total = reqs.length;
+        const coveredCount = compliant + partial;
+        const coveragePct = total > 0 ? coveredCount / total : 0;
+        rows.push({
+            codexId,
+            jurisdiction,
+            totalRequirements: total,
+            compliant,
+            partial,
+            non_compliant,
+            under_review,
+            gap,
+            coveredCount,
+            coveragePct,
+            ragStatus: ragFromPct(coveragePct, config.thresholds, total > 0),
+        });
+    }
+    return {
+        id: config.id,
+        name: config.name,
+        description: config.description,
+        date: config.date,
+        version: config.version,
+        rows,
+        thresholds: config.thresholds,
+    };
+}

package/dist/compliance/gap-report.d.ts

@@ -0,0 +1,20 @@
+import type { ComplianceIndex, IndexAssertion, IndexRequirement } from './types.js';
+export interface GapReport {
+    /** Requirements with no assertion about them, severity-sorted then id. */
+    requirementsWithoutAssertions: IndexRequirement[];
+    /** ASSERT-007: positive status (compliant/partial) with empty evidence. */
+    assertionsWithoutEvidence: IndexAssertion[];
+    /** ASSERT-008: next_review_at in the past (only when `today` is supplied). */
+    staleAssertions: IndexAssertion[];
+    /**
+     * CV-5: requirements whose `deadline` is `past_due` (deadline < today) AND
+     * that lack a fully-compliant assertion. Deadline-missed gaps, deadline-sorted
+     * (oldest first). Empty when `today` is not supplied.
+     */
+    pastDeadlineRequirements: IndexRequirement[];
+}
+export interface GapReportOptions {
+    /** Today as ISO `YYYY-MM-DD`; required for the stale-assertion list. */
+    today?: string;
+}
+export declare function buildGapReport(index: ComplianceIndex, options?: GapReportOptions): GapReport;

package/dist/compliance/gap-report.js

@@ -0,0 +1,64 @@
+// Gap dashboard report (vkgeorgia/strategy#84 Phase 4 / CV-5).
+//
+// Four operational gap lists computed from the shared reverse-index (Phase 3):
+//   1. Requirements with no Assertion targeting them (severity-sorted).
+//   2. Assertions without evidence — the ASSERT-007 case: status ∈
+//      {compliant, partial} AND no evidence. `under_review` / `non_compliant` /
+//      `n_a` are NOT positive statuses, so an empty-evidence assertion in those
+//      states is legitimate and is not flagged (matches 16-assertion.md §5).
+//   3. Stale Assertions — the ASSERT-008 case: `next_review_at` is in the past.
+//   4. Past-deadline requirements (CV-5) — REQUIREMENT.deadline < today AND
+//      the requirement has no fully-compliant assertion. Deadline-missed gaps.
+import { computeDeadlineStatus } from './impact.js';
+const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+function severityRank(s) {
+    return s !== undefined && s in SEVERITY_RANK ? SEVERITY_RANK[s] : 3;
+}
+/** Flattens the by-requirement index back to the full assertion set (each
+ *  assertion has exactly one `about`, so it appears once). */
+function allAssertions(index) {
+    const out = [];
+    for (const list of index.assertionsByRequirement.values())
+        out.push(...list);
+    return out;
+}
+export function buildGapReport(index, options = {}) {
+    const { today } = options;
+    const requirementsWithoutAssertions = [...index.requirementById.values()]
+        .filter(r => (index.assertionsByRequirement.get(r.id) ?? []).length === 0)
+        .sort((a, b) => {
+        const d = severityRank(a.severity) - severityRank(b.severity);
+        return d !== 0 ? d : a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+    const assertions = allAssertions(index);
+    const assertionsWithoutEvidence = assertions
+        .filter(a => (a.status === 'compliant' || a.status === 'partial') && (a.evidenceCount ?? 0) === 0)
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const staleAssertions = (today
+        ? assertions.filter(a => typeof a.next_review_at === 'string' && a.next_review_at < today)
+        : []).sort((a, b) => {
+        // Oldest review first — most overdue at the top.
+        const ra = a.next_review_at ?? '';
+        const rb = b.next_review_at ?? '';
+        return ra < rb ? -1 : ra > rb ? 1 : a.id < b.id ? -1 : 1;
+    });
+    // CV-5: past-deadline requirements — deadline < today, not fully compliant.
+    const pastDeadlineRequirements = today
+        ? [...index.requirementById.values()]
+            .filter(r => {
+            if (computeDeadlineStatus(r.deadline, today) !== 'past_due')
+                return false;
+            // Check if any assertion claims compliant status for this requirement.
+            const assertions = index.assertionsByRequirement.get(r.id) ?? [];
+            const hasCompliant = assertions.some(a => a.status === 'compliant');
+            return !hasCompliant;
+        })
+            .sort((a, b) => {
+            // Oldest deadline first — most overdue at the top.
+            const da = a.deadline ?? '';
+            const db = b.deadline ?? '';
+            return da < db ? -1 : da > db ? 1 : a.id < b.id ? -1 : 1;
+        })
+        : [];
+    return { requirementsWithoutAssertions, assertionsWithoutEvidence, staleAssertions, pastDeadlineRequirements };
+}

package/dist/compliance/html.d.ts

@@ -0,0 +1,22 @@
+import type { ComplianceCanon } from './classify.js';
+import type { ReportScope } from './markdown.js';
+import type { ImpactMatrix } from './impact.js';
+export interface HtmlOptions {
+    /** Today as ISO YYYY-MM-DD — enables the gap dashboard's stale-assertion list and is stamped in the footer. */
+    today?: string;
+    /** Title override; defaults to the per-scope title. */
+    title?: string;
+}
+/** Renders the requested compliance view from a scanned canon to a complete HTML document. */
+export declare function renderComplianceHtml(canon: ComplianceCanon, scope: ReportScope, options?: HtmlOptions): string;
+export interface ImpactMatrixHtmlOptions {
+    /** Today as ISO YYYY-MM-DD — stamped in the document header. */
+    today?: string;
+}
+/**
+ * Renders an `ImpactMatrix` (from `buildImpactMatrix`) as a self-contained
+ * A4 HTML document suitable for WeasyPrint PDF output.
+ *
+ * Used by `cervin export-compliance --report <id> --format pdf`.
+ */
+export declare function renderImpactMatrixHtml(matrix: ImpactMatrix, options?: ImpactMatrixHtmlOptions): string;