@transitrix/diagrams 1.8.21 → 1.9.18

package/src/versioned-attribute/resolve.ts

@@ -0,0 +1,45 @@
+// Current-value resolution for a versioned attribute — CONTRACT.md §9.2.
+
+import type { AttributeVersionEntry, VersionedAttributeSidecar } from './types.js';
+
+/** Pick the entry with the largest `valid_from <= atDate`.
+ *  Returns `undefined` when no entry has taken effect yet as of `atDate`
+ *  (the attribute has not yet taken its first value — CONTRACT.md §9.2 rule
+ *  4). Returns `null` when the resolved entry is itself a gap marker
+ *  (`value: null` — attribute currently unset). */
+export function resolveAttributeValue(
+  entries: AttributeVersionEntry[] | undefined,
+  atDate: string,
+): unknown {
+  if (!entries || entries.length === 0) return undefined;
+  let best: AttributeVersionEntry | undefined;
+  for (const entry of entries) {
+    if (entry.valid_from <= atDate && (!best || entry.valid_from > best.valid_from)) {
+      best = entry;
+    }
+  }
+  return best ? best.value : undefined;
+}
+
+/** Resolve every attribute in a sidecar at `atDate`. An attribute with no
+ *  entry yet in effect is omitted from the result (equivalent to
+ *  `resolveAttributeValue` returning `undefined`) rather than reported as
+ *  `null`, which is reserved for an explicit gap marker. */
+export function resolveAttributes(
+  sidecar: VersionedAttributeSidecar | null | undefined,
+  atDate: string,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!sidecar) return out;
+  for (const name of Object.keys(sidecar.attribute_versions)) {
+    const value = resolveAttributeValue(sidecar.attribute_versions[name], atDate);
+    if (value !== undefined) out[name] = value;
+  }
+  return out;
+}
+
+/** Today, as a quoted-ISO-8601 date string — the default projection date
+ *  every resolver/renderer falls back to when the caller supplies none. */
+export function todayIso(): string {
+  return new Date().toISOString().slice(0, 10);
+}

package/src/versioned-attribute/types.ts

@@ -0,0 +1,19 @@
+// Versioned-attribute sidecar (CONTRACT.md §9) — shared shape across every
+// notation that declares a `time_varying` field. A sidecar is a co-located
+// `<primitive_id>.history.yaml` document: no `id`, no admission record, no
+// lifecycle of its own — its temporal window is governed by the target
+// primitive's own `valid_from`/`valid_to` (CONTRACT.md §9.1).
+
+/** One version entry in an attribute's history. `value: null` is a gap
+ *  marker — the attribute is unset from `valid_from` until the next entry. */
+export interface AttributeVersionEntry {
+  valid_from: string;
+  value: unknown;
+}
+
+/** A parsed sidecar document, keyed by attribute name. */
+export interface VersionedAttributeSidecar {
+  /** Canonical id of the primitive this sidecar versions. */
+  target: string;
+  attribute_versions: Record<string, AttributeVersionEntry[]>;
+}

package/src/versioned-attribute/validate.ts

@@ -0,0 +1,109 @@
+// Versioned-attribute sidecar validation — CONTRACT.md §9.3, `VERSIONED-00x`.
+//
+// Split by what each check needs to know:
+//   - `parseSidecar` + `validateAttributeArray` here cover VERSIONED-002/003/005,
+//     which only need the sidecar document itself (plus, for 005, the target
+//     primitive's own lifecycle window).
+//   - `VERSIONED-001` (target resolves to an admitted primitive) and
+//     `VERSIONED-004` (a time_varying field present inline on the primitive)
+//     both need cross-document knowledge — which ids exist, which notation a
+//     primitive is — that a single sidecar document doesn't carry. Those are
+//     repo-scope concerns; see `repo-validate/check-versioned-attributes.ts`.
+
+import type { AttributeVersionEntry, VersionedAttributeSidecar } from './types.js';
+
+export interface AttributeArrayFinding {
+  code: 'VERSIONED-002' | 'VERSIONED-003' | 'VERSIONED-005';
+  severity: 'error' | 'warning';
+  message: string;
+}
+
+function isAttributeVersionEntry(v: unknown): v is AttributeVersionEntry {
+  return typeof v === 'object' && v !== null && !Array.isArray(v) && typeof (v as Record<string, unknown>)['valid_from'] === 'string';
+}
+
+/** Parse a raw parsed-YAML mapping into a typed sidecar, or `null` if it
+ *  isn't shaped like one (missing `target` string or `attribute_versions`
+ *  map) — not every doc under `canon/elements/**` is a sidecar. */
+export function parseSidecar(data: Record<string, unknown> | null | undefined): VersionedAttributeSidecar | null {
+  if (!data) return null;
+  const target = data['target'];
+  const attributeVersions = data['attribute_versions'];
+  if (typeof target !== 'string' || target.trim() === '') return null;
+  if (typeof attributeVersions !== 'object' || attributeVersions === null || Array.isArray(attributeVersions)) return null;
+
+  const out: Record<string, AttributeVersionEntry[]> = {};
+  for (const [name, value] of Object.entries(attributeVersions as Record<string, unknown>)) {
+    if (!Array.isArray(value)) continue;
+    out[name] = value.filter(isAttributeVersionEntry);
+  }
+  return { target, attribute_versions: out };
+}
+
+/** VERSIONED-002/003/005 for one attribute's version array.
+ *  `targetValidFrom`/`targetValidTo` bound VERSIONED-005 — pass `undefined`
+ *  for either to skip that half of the check (e.g. the target element could
+ *  not be found, which is already reported separately as VERSIONED-001). */
+export function validateAttributeArray(
+  attributeName: string,
+  entries: AttributeVersionEntry[],
+  targetValidFrom?: string,
+  targetValidTo?: string | null,
+): AttributeArrayFinding[] {
+  const findings: AttributeArrayFinding[] = [];
+  const seen = new Set<string>();
+  let sorted = true;
+  let prev: string | undefined;
+
+  for (const entry of entries) {
+    if (seen.has(entry.valid_from)) {
+      findings.push({
+        code: 'VERSIONED-002',
+        severity: 'error',
+        message: `attribute '${attributeName}': duplicate valid_from '${entry.valid_from}'.`,
+      });
+    }
+    seen.add(entry.valid_from);
+
+    if (prev !== undefined && entry.valid_from < prev) sorted = false;
+    prev = entry.valid_from;
+
+    if (targetValidFrom !== undefined && entry.valid_from < targetValidFrom) {
+      findings.push({
+        code: 'VERSIONED-005',
+        severity: 'error',
+        message: `attribute '${attributeName}': entry valid_from '${entry.valid_from}' is before the target's valid_from '${targetValidFrom}'.`,
+      });
+    }
+    if (targetValidTo !== undefined && targetValidTo !== null && entry.valid_from > targetValidTo) {
+      findings.push({
+        code: 'VERSIONED-005',
+        severity: 'error',
+        message: `attribute '${attributeName}': entry valid_from '${entry.valid_from}' is after the target's valid_to '${targetValidTo}'.`,
+      });
+    }
+  }
+
+  if (!sorted) {
+    findings.push({
+      code: 'VERSIONED-003',
+      severity: 'warning',
+      message: `attribute '${attributeName}': entries are not sorted by valid_from ascending.`,
+    });
+  }
+
+  return findings;
+}
+
+/** Run VERSIONED-002/003/005 over every attribute in a parsed sidecar. */
+export function validateSidecar(
+  sidecar: VersionedAttributeSidecar,
+  targetValidFrom?: string,
+  targetValidTo?: string | null,
+): AttributeArrayFinding[] {
+  const findings: AttributeArrayFinding[] = [];
+  for (const [name, entries] of Object.entries(sidecar.attribute_versions)) {
+    findings.push(...validateAttributeArray(name, entries, targetValidFrom, targetValidTo));
+  }
+  return findings;
+}

package/src/webview/render-applications.ts

@@ -12,6 +12,8 @@ import type {
   ApplicationIntegration,
   ApplicationsCatalogueHeader,
 } from '../applications/types.js';
+import type { ResolvedApplicationAttributes } from '../applications/resolve-maturity.js';
+import { withResolvedAttributes } from '../applications/resolve-maturity.js';
 import { escHtml } from './render-util.js';
 
 const TYPE_LABEL: Record<string, string> = {
@@ -86,8 +88,28 @@ function renderRow(a: Application): string {
 </tr>`;
 }
 
-export function renderApplicationsHtml(catalogue: ApplicationsCatalogueHeader): string {
-  const rows = catalogue.applications.map(renderRow).join('\n');
+/**
+ * Resolved values for owner_role/vendor/maturity — sidecar-bound
+ * (CONTRACT.md §9.4) and never inline on an admitted catalogue entry
+ * (VERSIONED-004). The host resolves these upstream (see
+ * `applications/resolve-maturity.ts`) and passes the result in; this
+ * function stays a pure renderer of whatever it's given — no I/O, no
+ * write-back. `asOf` is the date the resolution ran at, shown so the view
+ * never states an undated value.
+ */
+export interface ApplicationsMaturityResolution {
+  asOf: string;
+  byAppId: Map<string, ResolvedApplicationAttributes>;
+}
+
+export function renderApplicationsHtml(
+  catalogue: ApplicationsCatalogueHeader,
+  resolution?: ApplicationsMaturityResolution,
+): string {
+  const applications = resolution
+    ? catalogue.applications.map((a) => withResolvedAttributes(a, resolution.byAppId))
+    : catalogue.applications;
+  const rows = applications.map(renderRow).join('\n');
   const emptyRow = catalogue.applications.length === 0
     ? `<tr><td colspan="7" class="empty-catalogue">No applications defined.</td></tr>`
     : '';
@@ -99,6 +121,7 @@ export function renderApplicationsHtml(catalogue: ApplicationsCatalogueHeader):
       ${catalogue.version ? `<span class="catalogue-version">v${escHtml(catalogue.version)}</span>` : ''}
     </div>
     ${catalogue.description ? `<div class="catalogue-subtitle">${escHtml(catalogue.description)}</div>` : ''}
+    ${resolution ? `<div class="catalogue-resolved-note">Owner Role, Vendor, Maturity resolved as of ${escHtml(resolution.asOf)}</div>` : ''}
   </header>`;
   return `<section class="tx-catalogue tx-applications">
 ${header}

package/src/webview/render-blocks.ts

@@ -163,8 +163,6 @@ export function renderBlocksSvg(doc: BlocksFile, options: RenderBlocksOptions =
  */
 const GRID_CELL_PAD_X = 8;
 const GRID_LINE_HEIGHT = 15;
-const GRID_EMBED_CSS = `
-.blocks-grid-border { fill: none; stroke: var(--ts-border, #cbd5e1); }`;
 
 function centeredGridCellTextSvg(
   lines: string[],
@@ -246,7 +244,13 @@ export function renderGridBody(layout: GridLayout, ox: number, oy: number): stri
     parts.push(`<line class="diagram-edge" x1="${colLineX}" y1="${gridY1}" x2="${colLineX}" y2="${gridY2}"/>`);
   }
 
-  parts.push(`<rect class="blocks-grid-border" x="${ox}" y="${oy}" width="${tw}" height="${th}"/>`);
+  // Explicit fill="none" alongside the class: this rect covers the full grid
+  // bounds and is the last (topmost) element emitted, so if `.blocks-grid-border`
+  // is ever missing from a host's CSS (as it was in the VS Code webview path —
+  // see the grid-preview regression), it must not fall back to SVG's default opaque black fill.
+  parts.push(
+    `<rect class="blocks-grid-border" fill="none" x="${ox}" y="${oy}" width="${tw}" height="${th}"/>`,
+  );
 
   return parts.join('\n');
 }
@@ -270,7 +274,7 @@ export function renderGridLayoutSvg(layout: GridLayout, options: RenderGridLayou
   const oy = PAD + topInset;
 
   const body = renderGridBody(layout, ox, oy);
-  const styleLine = embedCssTheme ? `\n<style>${generateSvgEmbedCss(embedCssTheme)}${GRID_EMBED_CSS}</style>` : '';
+  const styleLine = embedCssTheme ? `\n<style>${generateSvgEmbedCss(embedCssTheme)}</style>` : '';
 
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">${styleLine}
 ${title}

package/src/webview/render-capability-map.ts

@@ -4,6 +4,8 @@
  * HTML fragment for the JCEF host (Step 4 of ADR 0001).
  */
 import type { CapabilityMapHeader, CapabilityNode } from '../capability-map/types.js';
+import type { ResolvedCapabilityAttributes } from '../capability-map/resolve-maturity.js';
+import { withResolvedCapabilityMap } from '../capability-map/resolve-maturity.js';
 import { escHtml } from './render-util.js';
 
 const MATURITY_LABEL: Record<number, string> = {
@@ -62,7 +64,26 @@ function renderCapabilityCard(node: CapabilityNode, depth: number): string {
 </div>`;
 }
 
-export function renderCapabilityMapHtml(map: CapabilityMapHeader): string {
+/**
+ * Resolved values for current_maturity/target_maturity/owner_role/
+ * target_date — sidecar-bound (CONTRACT.md §9.4) on the standalone
+ * CAPABILITY-* primitive a nested entry references (the 2026-08-05
+ * packages decision). The host resolves
+ * these upstream (see `capability-map/resolve-maturity.ts`) and passes the
+ * result in; this function stays a pure renderer of whatever it's given —
+ * no I/O, no write-back. `asOf` is the date the resolution ran at, shown so
+ * the view never states an undated value.
+ */
+export interface CapabilityMapMaturityResolution {
+  asOf: string;
+  byId: Map<string, ResolvedCapabilityAttributes>;
+}
+
+export function renderCapabilityMapHtml(
+  rawMap: CapabilityMapHeader,
+  resolution?: CapabilityMapMaturityResolution,
+): string {
+  const map = resolution ? withResolvedCapabilityMap(rawMap, resolution.byId) : rawMap;
   const header = `<header class="catalogue-header">
     <div class="catalogue-title">${escHtml(map.name)}</div>
     <div class="catalogue-meta">
@@ -70,6 +91,7 @@ export function renderCapabilityMapHtml(map: CapabilityMapHeader): string {
       <span class="catalogue-updated">Assessed ${escHtml(map.assessment_date)}</span>
     </div>
     ${map.description ? `<div class="catalogue-subtitle">${escHtml(map.description)}</div>` : ''}
+    ${resolution ? `<div class="catalogue-resolved-note">Current Maturity, Target Maturity, Owner Role, Target Date resolved as of ${escHtml(resolution.asOf)}</div>` : ''}
   </header>`;
   if (map.capabilities.length === 0) {
     return `<section class="tx-catalogue tx-capability-map">

package/src/webview/render-process.ts

@@ -116,17 +116,17 @@ export const BPMN_PROCESS_CSS = `
 .bpmn-pool-name { fill: var(--ts-bg-elevated,#f1f5f9); stroke: var(--ts-node-stroke,#004d67); stroke-width: 0.75; }
 .bpmn-lane { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 0.75; }
 .bpmn-lane-header { fill: var(--ts-bg-elevated,#f1f5f9); stroke: var(--ts-node-stroke,#004d67); stroke-width: 0.75; }
-.bpmn-pool-label { fill: var(--ts-text-primary,#0d2b35); font-size: 11px; font-weight: 700; }
-.bpmn-lane-label { fill: var(--ts-text-primary,#0d2b35); font-size: 11px; font-weight: 600; }
+.bpmn-pool-label { fill: var(--ts-text-primary,#0d2b35); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 11px; font-weight: 700; }
+.bpmn-lane-label { fill: var(--ts-text-primary,#0d2b35); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 11px; font-weight: 600; }
 .bpmn-task { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; }
-.bpmn-task-name { fill: var(--ts-text-primary,#0d2b35); font-size: 11px; text-anchor: middle; }
+.bpmn-task-name { fill: var(--ts-text-primary,#0d2b35); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 11px; text-anchor: middle; }
 .bpmn-event { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); }
 .bpmn-event-start { stroke-width: 1.5; }
 .bpmn-event-end { stroke-width: 4; }
-.bpmn-event-label { fill: var(--ts-text-secondary,#516970); font-size: 10px; text-anchor: middle; }
+.bpmn-event-label { fill: var(--ts-text-secondary,#516970); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 10px; text-anchor: middle; }
 .bpmn-gateway { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; }
 .bpmn-gateway-marker { stroke: var(--ts-node-stroke,#004d67); stroke-width: 2.5; stroke-linecap: round; fill: none; }
-.bpmn-gateway-label { fill: var(--ts-text-secondary,#516970); font-size: 10px; text-anchor: middle; }
+.bpmn-gateway-label { fill: var(--ts-text-secondary,#516970); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 10px; text-anchor: middle; }
 .bpmn-seq-flow { fill: none; stroke: var(--ts-edge-stroke,#004d67); stroke-width: 1.5; }
 .bpmn-default-mark { stroke: var(--ts-edge-stroke,#004d67); stroke-width: 1.5; stroke-linecap: round; }
 .bpmn-assoc { fill: none; stroke: var(--ts-edge-stroke,#004d67); stroke-width: 1; stroke-dasharray: 4 2; }

package/src/webview/styles.css

@@ -140,6 +140,12 @@ body {
   color: var(--tx-fg);
 }
 
+.catalogue-resolved-note {
+  margin-top: 6px;
+  color: var(--tx-muted);
+  font-size: 11px;
+}
+
 .catalogue-table {
   width: 100%;
   border-collapse: collapse;