@transitrix/diagrams 1.0.0

package/dist/process-blueprint/layout.js

@@ -0,0 +1,416 @@
+const ASPECT_CATEGORIES = ['systems', 'actors', 'equipment', 'information_entities'];
+const ASPECT_LABEL = {
+    systems: 'Systems',
+    actors: 'Actors',
+    equipment: 'Equipment',
+    information_entities: 'Information',
+};
+const DEFAULTS = {
+    legendColumnWidth: 140,
+    stageColumnWidth: 220,
+    stageHeaderHeight: 40,
+    goalRowHeight: 56,
+    resultRowHeight: 56,
+    aspectRowMinHeight: 60,
+    pillHeight: 28,
+    pillGap: 4,
+    cellPadding: 8,
+    textLineHeight: 15,
+    textCharWidth: 6.2,
+    cellTextPadX: 10,
+    cellTextPadY: 10,
+    maxTextLines: 6,
+};
+function resolveOptions(options) {
+    return { ...DEFAULTS, ...(options ?? {}) };
+}
+/**
+ * Greedy word-wrap to a max characters-per-line budget. Words longer than the
+ * budget are hard-split; if the result exceeds `maxLines`, the last kept line
+ * is truncated with an ellipsis so a single pathological cell can't grow the
+ * whole row unbounded.
+ */
+function wrapText(text, maxChars, maxLines) {
+    const trimmed = (text ?? '').trim();
+    if (trimmed.length === 0)
+        return [];
+    const budget = Math.max(1, maxChars);
+    const words = trimmed.split(/\s+/);
+    const lines = [];
+    let cur = '';
+    const flush = () => {
+        if (cur.length > 0) {
+            lines.push(cur);
+            cur = '';
+        }
+    };
+    for (const word of words) {
+        if (word.length > budget) {
+            // Token wider than the cell: hard-break it across lines.
+            flush();
+            let rest = word;
+            while (rest.length > budget) {
+                lines.push(rest.slice(0, budget));
+                rest = rest.slice(budget);
+            }
+            cur = rest;
+            continue;
+        }
+        const candidate = cur.length > 0 ? `${cur} ${word}` : word;
+        if (candidate.length > budget) {
+            flush();
+            cur = word;
+        }
+        else {
+            cur = candidate;
+        }
+    }
+    flush();
+    if (lines.length > maxLines) {
+        const capped = lines.slice(0, maxLines);
+        const last = capped[maxLines - 1];
+        const clipped = last.length > budget - 1 ? last.slice(0, budget - 1) : last;
+        capped[maxLines - 1] = `${clipped.replace(/…$/, '')}…`;
+        return capped;
+    }
+    return lines;
+}
+function buildStageIndex(stages) {
+    const idx = new Map();
+    for (let i = 0; i < stages.length; i++) {
+        const sid = typeof stages[i]?.id === 'string' ? stages[i].id.trim() : '';
+        if (sid.length > 0 && !idx.has(sid)) {
+            idx.set(sid, i);
+        }
+    }
+    return idx;
+}
+function pillsForEntry(category, entryIndex, entry, stageIndexById) {
+    if (!Array.isArray(entry.stages))
+        return [];
+    const idxs = [];
+    const seen = new Set();
+    for (const ref of entry.stages) {
+        if (typeof ref !== 'string')
+            continue;
+        const i = stageIndexById.get(ref.trim());
+        if (i === undefined)
+            continue;
+        if (seen.has(i))
+            continue;
+        seen.add(i);
+        idxs.push(i);
+    }
+    idxs.sort((a, b) => a - b);
+    const pills = [];
+    let runStart = null;
+    let runEnd = null;
+    for (const i of idxs) {
+        if (runStart === null || runEnd === null) {
+            runStart = i;
+            runEnd = i;
+            continue;
+        }
+        if (i === runEnd + 1) {
+            runEnd = i;
+        }
+        else {
+            pills.push({
+                category,
+                entryIndex,
+                name: entry.name,
+                id: entry.id,
+                startStageIndex: runStart,
+                endStageIndex: runEnd,
+            });
+            runStart = i;
+            runEnd = i;
+        }
+    }
+    if (runStart !== null && runEnd !== null) {
+        pills.push({
+            category,
+            entryIndex,
+            name: entry.name,
+            id: entry.id,
+            startStageIndex: runStart,
+            endStageIndex: runEnd,
+        });
+    }
+    return pills;
+}
+function packPillsIntoSlots(pills) {
+    // Greedy interval scheduling: stable order by startStageIndex.
+    const order = pills
+        .map((_, i) => i)
+        .sort((a, b) => {
+        const ds = pills[a].startStageIndex - pills[b].startStageIndex;
+        if (ds !== 0)
+            return ds;
+        return pills[a].endStageIndex - pills[b].endStageIndex;
+    });
+    const slotEndByLevel = []; // slotEndByLevel[s] = last endStageIndex placed in slot s
+    const slot = new Array(pills.length).fill(0);
+    let maxSlot = 0;
+    for (const i of order) {
+        const p = pills[i];
+        let placed = false;
+        for (let s = 0; s < slotEndByLevel.length; s++) {
+            if (slotEndByLevel[s] < p.startStageIndex) {
+                slot[i] = s;
+                slotEndByLevel[s] = p.endStageIndex;
+                placed = true;
+                break;
+            }
+        }
+        if (!placed) {
+            slot[i] = slotEndByLevel.length;
+            slotEndByLevel.push(p.endStageIndex);
+        }
+        if (slot[i] > maxSlot)
+            maxSlot = slot[i];
+    }
+    return { slot, maxSlot };
+}
+// ── Compliance lane derivation ────────────────────────────────────────────────
+/** ISO 8601 date comparison helper — no Date parsing, string comparison is valid for YYYY-MM-DD. */
+function deadlineStatus(deadline, today) {
+    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 <= 30 ? 'in_force' : 'upcoming';
+}
+/**
+ * Derive the laid-out compliance row for a process blueprint.
+ *
+ * For each stage, gathers the laws that bind that stage (via the
+ * assertion → requirement → derived_from chain), applies the jurisdiction
+ * filter, and computes the three orthogonal decorations per law chip.
+ */
+function deriveComplianceRow(stages, stageIndexById, input, opts, yStart) {
+    const { complianceLane: laneConfig, legendColumnWidth, stageColumnWidth, cellPadding, pillHeight, pillGap, aspectRowMinHeight, } = opts;
+    if (!laneConfig?.enabled)
+        return undefined;
+    const today = laneConfig.referenceDate ?? new Date().toISOString().slice(0, 10);
+    const filterJurisdictions = laneConfig.jurisdictions?.length ? new Set(laneConfig.jurisdictions) : null;
+    // Build requirement index: id → requirement.
+    const reqById = new Map();
+    for (const r of input.requirements) {
+        if (r?.id)
+            reqById.set(r.id, r);
+    }
+    const stageAccum = new Map();
+    for (const a of input.assertions) {
+        if (!a || typeof a !== 'object')
+            continue;
+        const realisedVia = Array.isArray(a.realised_via) ? a.realised_via : [];
+        if (realisedVia.length === 0)
+            continue;
+        const req = reqById.get(a.about);
+        if (!req)
+            continue;
+        const lawIds = Array.isArray(req.derived_from)
+            ? req.derived_from.filter((x) => typeof x === 'string')
+            : [];
+        if (lawIds.length === 0)
+            continue;
+        for (const stageRef of realisedVia) {
+            if (typeof stageRef !== 'string')
+                continue;
+            const idx = stageIndexById.get(stageRef.trim());
+            if (idx === undefined)
+                continue;
+            for (const lawId of lawIds) {
+                // Apply jurisdiction filter.
+                if (filterJurisdictions) {
+                    const jur = input.codexJurisdictions?.[lawId];
+                    if (!jur || !filterJurisdictions.has(jur))
+                        continue;
+                }
+                if (!stageAccum.has(idx))
+                    stageAccum.set(idx, new Map());
+                const lawMap = stageAccum.get(idx);
+                const existing = lawMap.get(lawId);
+                const isGap = a.status === 'non_compliant' || a.status === 'partial';
+                if (!existing) {
+                    lawMap.set(lawId, { gap: isGap, deadline: req.deadline });
+                }
+                else {
+                    existing.gap = existing.gap || isGap;
+                    // Keep the earlier deadline (more urgent).
+                    if (req.deadline && (!existing.deadline || req.deadline < existing.deadline)) {
+                        existing.deadline = req.deadline;
+                    }
+                }
+            }
+        }
+    }
+    if (stageAccum.size === 0)
+        return undefined;
+    // Determine how many slots (rows) per stage.
+    const slotsPerStage = new Map();
+    for (const [idx, lawMap] of stageAccum) {
+        slotsPerStage.set(idx, lawMap.size);
+    }
+    const maxSlots = Math.max(0, ...slotsPerStage.values());
+    if (maxSlots === 0)
+        return undefined;
+    const contentHeight = maxSlots * (pillHeight + pillGap) - pillGap;
+    const rowHeight = Math.max(aspectRowMinHeight, contentHeight + 2 * cellPadding);
+    const chips = [];
+    for (const [stageIdx, lawMap] of stageAccum) {
+        const prevLawIds = new Set(laneConfig.previousSnapshot?.[stages[stageIdx]?.id ?? ''] ?? []);
+        let slot = 0;
+        for (const [lawId, accum] of lawMap) {
+            const decorations = [];
+            if (!prevLawIds.has(lawId))
+                decorations.push('new');
+            if (accum.gap) {
+                decorations.push('gap');
+                const ds = deadlineStatus(accum.deadline, today);
+                if (ds !== 'none')
+                    decorations.push('deadline');
+            }
+            const x = legendColumnWidth + stageIdx * stageColumnWidth + cellPadding;
+            const width = stageColumnWidth - 2 * cellPadding;
+            const y = yStart + cellPadding + slot * (pillHeight + pillGap);
+            chips.push({ stageIndex: stageIdx, lawId, decorations, x, y, width, height: pillHeight });
+            slot++;
+        }
+    }
+    return { y: yStart, height: rowHeight, chips };
+}
+export function layoutProcessBlueprint(file, options) {
+    const opts = resolveOptions(options);
+    const pb = file.process_blueprint;
+    const stages = Array.isArray(pb?.stages) ? pb.stages : [];
+    const stageIndexById = buildStageIndex(stages);
+    // Stage headers
+    const stageHeaders = stages.map((s, i) => ({
+        stageIndex: i,
+        id: s?.id ?? '',
+        name: s?.name ?? '',
+        x: opts.legendColumnWidth + i * opts.stageColumnWidth,
+        y: 0,
+        width: opts.stageColumnWidth,
+        height: opts.stageHeaderHeight,
+    }));
+    // Goal + result rows. Text is word-wrapped to the column width, and each row
+    // grows to fit the tallest cell so nothing is clipped.
+    const maxCharsPerLine = Math.max(4, Math.floor((opts.stageColumnWidth - 2 * opts.cellTextPadX) / opts.textCharWidth));
+    const wrap = (text) => wrapText(text, maxCharsPerLine, opts.maxTextLines);
+    const rowHeightFor = (lineCounts, minHeight) => {
+        const maxLines = Math.max(1, ...lineCounts);
+        return Math.max(minHeight, maxLines * opts.textLineHeight + 2 * opts.cellTextPadY);
+    };
+    const goalLines = stages.map(s => wrap(s?.goal ?? ''));
+    const resultLines = stages.map(s => wrap(s?.result ?? ''));
+    const goalRowY = opts.stageHeaderHeight;
+    const goalRowHeight = rowHeightFor(goalLines.map(l => l.length), opts.goalRowHeight);
+    const resultRowY = goalRowY + goalRowHeight;
+    const resultRowHeight = rowHeightFor(resultLines.map(l => l.length), opts.resultRowHeight);
+    const goalCells = stages.map((s, i) => ({
+        stageIndex: i,
+        text: s?.goal ?? '',
+        lines: goalLines[i],
+        x: opts.legendColumnWidth + i * opts.stageColumnWidth,
+        y: goalRowY,
+        width: opts.stageColumnWidth,
+        height: goalRowHeight,
+    }));
+    const resultCells = stages.map((s, i) => ({
+        stageIndex: i,
+        text: s?.result ?? '',
+        lines: resultLines[i],
+        x: opts.legendColumnWidth + i * opts.stageColumnWidth,
+        y: resultRowY,
+        width: opts.stageColumnWidth,
+        height: resultRowHeight,
+    }));
+    const aspectsStartY = resultRowY + resultRowHeight;
+    // Aspect rows: only categories with at least one entry, in fixed order.
+    const aspectRows = [];
+    let aspectCursorY = aspectsStartY;
+    for (const category of ASPECT_CATEGORIES) {
+        const arr = pb?.[category];
+        if (!Array.isArray(arr) || arr.length === 0)
+            continue;
+        const rawPills = [];
+        for (let i = 0; i < arr.length; i++) {
+            const entry = arr[i];
+            if (!entry || typeof entry !== 'object')
+                continue;
+            rawPills.push(...pillsForEntry(category, i, entry, stageIndexById));
+        }
+        // If every entry in this category had no resolvable stage refs, drop the row.
+        if (rawPills.length === 0)
+            continue;
+        const { slot, maxSlot } = packPillsIntoSlots(rawPills);
+        const contentHeight = (maxSlot + 1) * (opts.pillHeight + opts.pillGap) - opts.pillGap;
+        const rowHeight = Math.max(opts.aspectRowMinHeight, contentHeight + 2 * opts.cellPadding);
+        const pills = rawPills.map((p, i) => {
+            const x = opts.legendColumnWidth + p.startStageIndex * opts.stageColumnWidth + opts.cellPadding;
+            const width = (p.endStageIndex - p.startStageIndex + 1) * opts.stageColumnWidth - 2 * opts.cellPadding;
+            const y = aspectCursorY + opts.cellPadding + slot[i] * (opts.pillHeight + opts.pillGap);
+            return {
+                category: p.category,
+                entryIndex: p.entryIndex,
+                name: p.name,
+                id: p.id,
+                startStageIndex: p.startStageIndex,
+                endStageIndex: p.endStageIndex,
+                x,
+                y,
+                width,
+                height: opts.pillHeight,
+            };
+        });
+        aspectRows.push({
+            category,
+            y: aspectCursorY,
+            height: rowHeight,
+            pills,
+        });
+        aspectCursorY += rowHeight;
+    }
+    // Compliance lane — derived from assertions/requirements, rendered after aspect rows.
+    let complianceRow;
+    if (opts.complianceLane?.enabled && opts.complianceInput) {
+        complianceRow = deriveComplianceRow(stages, stageIndexById, opts.complianceInput, opts, aspectCursorY);
+        if (complianceRow) {
+            aspectCursorY += complianceRow.height;
+        }
+    }
+    // Legend (left column labels): one entry per row.
+    const legend = [
+        { kind: 'goal', label: 'Goal', y: goalRowY, height: goalRowHeight },
+        { kind: 'result', label: 'Result', y: resultRowY, height: resultRowHeight },
+        ...aspectRows.map(row => ({
+            kind: 'aspect',
+            category: row.category,
+            label: ASPECT_LABEL[row.category],
+            y: row.y,
+            height: row.height,
+        })),
+        ...(complianceRow
+            ? [{ kind: 'compliance', label: 'Compliance', y: complianceRow.y, height: complianceRow.height }]
+            : []),
+    ];
+    const totalWidth = opts.legendColumnWidth + stages.length * opts.stageColumnWidth;
+    const totalHeight = aspectCursorY;
+    return {
+        bounds: { x: 0, y: 0, width: totalWidth, height: totalHeight },
+        legendColumnWidth: opts.legendColumnWidth,
+        stageColumnWidth: opts.stageColumnWidth,
+        textLineHeight: opts.textLineHeight,
+        cellTextPadX: opts.cellTextPadX,
+        legend,
+        stageHeaders,
+        goalCells,
+        resultCells,
+        aspectRows,
+        complianceRow,
+    };
+}

package/dist/process-blueprint/types.d.ts

@@ -0,0 +1,220 @@
+export type AspectCategory = 'systems' | 'actors' | 'equipment' | 'information_entities';
+/**
+ * One of the three orthogonal decoration signals that can appear on a compliance
+ * law chip (ADR 2026-06-09-compliance-impact-as-blueprint-lane §3):
+ * - `new`      — law's impact on this stage appeared since the previous snapshot
+ * - `gap`      — a bound assertion has status `non_compliant` or `partial`
+ * - `deadline` — gap is present AND the requirement carries a deadline that is
+ *                past, imminent, or in-force
+ */
+export type ComplianceDecoration = 'new' | 'gap' | 'deadline';
+/** Input shape for a requirement — minimal projection the compliance lane needs. */
+export interface ComplianceLaneRequirement {
+    id: string;
+    /** Typed IDs of codex sources (law IDs displayed as chips). */
+    derived_from?: string[];
+    /**
+     * ISO 8601 compliance deadline on the external regulatory source.
+     * Used to compute the `deadline` decoration.
+     */
+    deadline?: string;
+}
+/** Input shape for an assertion — minimal projection the compliance lane needs. */
+export interface ComplianceLaneAssertion {
+    /** Requirement ID this assertion is about. */
+    about: string;
+    /** Compliance realisation status. */
+    status: 'compliant' | 'partial' | 'non_compliant' | 'under_review' | 'n_a';
+    /**
+     * Typed IDs of stages / process steps where the requirement is realised.
+     * When empty/absent, the assertion covers the entire subject, not a specific stage.
+     */
+    realised_via?: string[];
+}
+/**
+ * Input data for the compliance lane derivation.
+ * Passed via `ProcessBlueprintLayoutOptions.complianceInput`.
+ */
+export interface ComplianceLaneInput {
+    assertions: ComplianceLaneAssertion[];
+    requirements: ComplianceLaneRequirement[];
+    /**
+     * Codex jurisdiction map: codexId → jurisdiction code.
+     * Required only when `ComplianceLaneConfig.jurisdictions` is non-empty.
+     */
+    codexJurisdictions?: Record<string, string>;
+}
+/**
+ * Runtime configuration for the compliance lane.
+ * Passed via `ProcessBlueprintLayoutOptions.complianceLane`.
+ */
+export interface ComplianceLaneConfig {
+    /** When false (default), the compliance lane is not rendered. */
+    enabled: boolean;
+    /**
+     * Jurisdiction filter: if non-empty, only show laws whose codex jurisdiction
+     * is in this list. Requires `ComplianceLaneInput.codexJurisdictions`.
+     */
+    jurisdictions?: string[];
+    /**
+     * Per-stage map of law IDs known from the previous generated snapshot.
+     * Key: stage ID; Value: array of law IDs.
+     * A law not present in the previous snapshot is decorated as `new`.
+     */
+    previousSnapshot?: Record<string, string[]>;
+    /**
+     * Reference date for deadline-status computation (YYYY-MM-DD).
+     * Defaults to today when not supplied.
+     */
+    referenceDate?: string;
+}
+/** One law chip rendered inside a compliance cell. */
+export interface ComplianceChip {
+    stageIndex: number;
+    /** Codex / law ID shown as the chip label. */
+    lawId: string;
+    /** Active decorations — a subset of the three orthogonal signals. */
+    decorations: ComplianceDecoration[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Laid-out compliance row (one per blueprint when the lane is enabled). */
+export interface ComplianceRow {
+    y: number;
+    height: number;
+    chips: ComplianceChip[];
+}
+export interface Stage {
+    id: string;
+    name: string;
+    goal: string;
+    result: string;
+    description?: string;
+}
+export interface AspectEntry {
+    id?: string;
+    name: string;
+    stages: string[];
+    description?: string;
+}
+/** Rendering-config block that selects which lanes are visible (spec §5 `lane_config:`). */
+export interface LaneConfig {
+    /** Enable the derived compliance lane. Default: false. */
+    compliance?: boolean;
+    compliance_filter?: {
+        /** ISO jurisdiction codes; empty array means all jurisdictions. */
+        jurisdictions?: string[];
+    };
+}
+export interface ProcessBlueprintHeader {
+    id: string;
+    name: string;
+    description?: string;
+    period?: string;
+    version?: string;
+    date?: string;
+    author?: string;
+    process?: string;
+    scenario?: string;
+    stages: Stage[];
+    systems?: AspectEntry[];
+    actors?: AspectEntry[];
+    equipment?: AspectEntry[];
+    information_entities?: AspectEntry[];
+    /** Optional rendering config selecting which lanes to show. */
+    lane_config?: LaneConfig;
+}
+export interface ProcessBlueprintFile {
+    notation: string;
+    spec_version?: string;
+    process_blueprint: ProcessBlueprintHeader;
+}
+export interface ProcessBlueprintLayoutOptions {
+    legendColumnWidth?: number;
+    stageColumnWidth?: number;
+    stageHeaderHeight?: number;
+    goalRowHeight?: number;
+    resultRowHeight?: number;
+    aspectRowMinHeight?: number;
+    pillHeight?: number;
+    pillGap?: number;
+    cellPadding?: number;
+    /** Vertical advance between wrapped text lines in goal/result cells (px). */
+    textLineHeight?: number;
+    /** Approximate glyph width used to estimate wrap width (px per char). */
+    textCharWidth?: number;
+    /** Horizontal text inset inside goal/result cells (px, both sides). */
+    cellTextPadX?: number;
+    /** Top+bottom padding added around wrapped goal/result text (px). */
+    cellTextPadY?: number;
+    /** Maximum wrapped lines per goal/result cell before truncating with an ellipsis. */
+    maxTextLines?: number;
+    /** Enable and configure the derived compliance lane. Default: disabled. */
+    complianceLane?: ComplianceLaneConfig;
+    /** Assertion + requirement data for the compliance lane derivation. */
+    complianceInput?: ComplianceLaneInput;
+}
+import type { LayoutBounds } from '../geometry.js';
+export type { LayoutBounds };
+export interface LegendCell {
+    kind: 'goal' | 'result' | 'aspect' | 'compliance';
+    category?: AspectCategory;
+    label: string;
+    y: number;
+    height: number;
+}
+export interface StageHeaderCell {
+    stageIndex: number;
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface StageTextCell {
+    stageIndex: number;
+    text: string;
+    /** Word-wrapped lines of `text`, pre-fitted to the cell width by the layout. */
+    lines: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface AspectPill {
+    category: AspectCategory;
+    entryIndex: number;
+    name: string;
+    id?: string;
+    startStageIndex: number;
+    endStageIndex: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface AspectRow {
+    category: AspectCategory;
+    y: number;
+    height: number;
+    pills: AspectPill[];
+}
+export interface ProcessBlueprintLayout {
+    bounds: LayoutBounds;
+    legendColumnWidth: number;
+    stageColumnWidth: number;
+    /** Vertical advance between wrapped text lines, so renderers stack tspans consistently. */
+    textLineHeight: number;
+    /** Horizontal text inset used for goal/result cells (px). */
+    cellTextPadX: number;
+    legend: LegendCell[];
+    stageHeaders: StageHeaderCell[];
+    goalCells: StageTextCell[];
+    resultCells: StageTextCell[];
+    aspectRows: AspectRow[];
+    /** Compliance lane row — present only when the lane is enabled and has data. */
+    complianceRow?: ComplianceRow;
+}

package/dist/process-blueprint/types.js

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

package/dist/process-blueprint/validate.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+export type { ValidationError, ValidationWarning, ValidationResult };
+export declare function validateProcessBlueprint(input: unknown): ValidationResult;