@transitrix/diagrams 1.8.11 → 1.8.18

package/src/repo-validate/types.ts

@@ -7,11 +7,30 @@
 // runtime (methodology ADR "Validation Two-Axis Model"; Studio decision
 // "Validation Runtime Convergence").
 //
-// The finding shape is deliberately minimal — `{ scope, id, message }`. The
-// richer `target` / `category` reporting taxonomy is explicitly DEFERRED per the
-// ADR until a real consumer needs it; do not add it here.
+// The finding shape was originally frozen minimal — `{ scope, id, message }` —
+// with the richer `target` / `category` reporting taxonomy explicitly DEFERRED
+// per the ADR until a real consumer needed it. This un-freezes one field,
+// `ruleId`: DSM (migrating off its own Go `Validate*` functions) needs a
+// stable code per finding to map onto its existing import-log rule taxonomy
+// (`api02/internal/importer/{goals,activities,fgca}.go`). The richer
+// `target`/`category` taxonomy stays deferred — only `ruleId` is added.
+// `ruleId` is optional: only checks with a stable, documented code set it
+// (`docs/validation.md` § repo-scope rule list); the original structural
+// checks (syntax/uniqueness/atomicity/referential-integrity/policy) stay
+// uncoded rather than being retrofitted with invented codes.
+//
+// A second field, `severity`, is un-frozen for the same reason: DSM's
+// warn-severity strategy-chain rules (GOALS-009/011, ACT-005, FGCA-012..014
+// — see check-strategy-chain.ts) are non-fatal by
+// DSM's own taxonomy ("import anyway, record the warning"); without a
+// severity field, porting them here would silently make them blocking,
+// since every existing repo-scope finding is implicitly blocking. `severity`
+// is optional and defaults to `'error'` when omitted — every finding from
+// before this field existed (syntax/uniqueness/atomicity/referential-
+// integrity/policy, plus the error-tier strategy-chain rules and
+// TSVC-003/INT-002) stays blocking with no code change at the call site.
 
-/** A single repo-scope validation finding. Shape is frozen at `{ scope, id, message }`. */
+/** A single repo-scope validation finding. */
 export interface RepoFinding {
   /** Always `'repo'` — the execution axis this finding came from. */
   scope: 'repo';
@@ -22,6 +41,19 @@ export interface RepoFinding {
   id: string;
   /** Human-readable description of the violation. */
   message: string;
+  /**
+   * Stable rule code (e.g. `GOALS-010`, `ACT-006`, `FGCA-008`), for a consumer
+   * that maps findings onto its own rule taxonomy (`docs/validation.md`).
+   * Omitted for checks that don't yet have one.
+   */
+  ruleId?: string;
+  /**
+   * `'error'` (blocking) or `'warning'` (advisory). Omitted is equivalent to
+   * `'error'` — every check that predates this field never sets it and must
+   * stay blocking. Only the warn-severity strategy-chain rules set this to
+   * `'warning'` today (`docs/validation.md` § repo-scope rule list).
+   */
+  severity?: 'error' | 'warning';
 }
 
 /** A parsed canon document fed to the repo validator. IO (the filesystem walk)
@@ -47,3 +79,62 @@ export interface RepoModelInput {
   /** Documents found under `canon/relations/**`. */
   relations: RepoDoc[];
 }
+
+/** One resolved canon element, projected from a `RepoDoc` for a non-JS
+ *  consumer (DSM's Go importer). The top-level fields below are a stable,
+ *  minimal identity projection — kept for backward compatibility with
+ *  consumers that only need `id`/`name`/`notation`/`type`/`layer`/`sourceFile`
+ *  (mirrors DSM's `methodology_element` table). `data` carries the complete
+ *  parsed element alongside it, so a consumer never needs an engine schema
+ *  change to read a canon-authored field the engine already parsed (a goal's
+ *  `level`/`parent`/`description`/`link`/`tags`, an action's scheduling and
+ *  ownership fields, etc.) — the engine owns each notation's field set
+ *  (ELEMENT_PRIMITIVES.md), so its output stays notation-shaped rather than
+ *  growing a bespoke field list per consumer. This is the faithful-projection
+ *  fallback: a typed per-notation shape may replace `data` later, but the
+ *  contract must not be curated down to what one consumer currently needs. */
+export interface ResolvedElementRecord {
+  /** Canonical id, e.g. `DRIVER-COMP-1`. */
+  id: string;
+  /** `name` field; `''` when absent (should not happen for an admitted element). */
+  name: string;
+  /** The element TYPE's short name — the doc's `notation` field, e.g. `driver`, `goal`, `capability`. */
+  notation: string;
+  /** Subtype from the TYPE's controlled vocabulary (ELEMENT_PRIMITIVES.md §3), e.g. `internal`/`external` for DRIVER. Omitted when the doc has none. */
+  type?: string;
+  /** `motivation` / `business` / `application` / `technology` / `implementation`. Read from the doc's `layer` field when present, else derived from the `canon/elements/<NN>_<layer>/…` folder. */
+  layer?: string;
+  /** Source file path, relative to the scanned root. */
+  sourceFile: string;
+  /** The full parsed element document — every field its author supplied,
+   *  unfiltered (including the admission/lifecycle envelope). The same
+   *  `RepoDoc.data` the repo-scope validator already consumes, so this
+   *  projection and the validation pass never see a different parse. */
+  data: Record<string, unknown>;
+}
+
+/** One resolved canon relation, projected from a `RepoDoc`. Only
+ *  emitted when both endpoints resolve to a non-empty id — an endpoint that
+ *  fails to resolve is already surfaced as a referential-integrity finding by
+ *  `validateRepoModel`; this projection does not duplicate that as a
+ *  half-resolved record. */
+export interface ResolvedRelationRecord {
+  /** Canonical id, e.g. `REL-EMP-PERSON-OPS-1`. `''` when the relation doc has no `id`. */
+  id: string;
+  /** The relation's `type` field, e.g. `employment`, `realizes`. Omitted when the doc has none. */
+  kind?: string;
+  /** Resolved `from` (or legacy `source`) endpoint id. */
+  source: string;
+  /** Resolved `to` (or legacy `target`) endpoint id. */
+  target: string;
+  /** Source file path, relative to the scanned root. */
+  sourceFile: string;
+}
+
+/** The resolved element/relation records for a repo-scope run —
+ *  the shape `transitrix validate --scope=repo --json --include-model` adds
+ *  alongside the validation findings. */
+export interface ResolvedRepoModel {
+  elements: ResolvedElementRecord[];
+  relations: ResolvedRelationRecord[];
+}

package/src/repo-validate/validate-repo.ts

@@ -23,9 +23,12 @@
 //   6. Policy             (phase 6) — element marked Active/Production with no
 //                                     owner.
 //
-// Findings stay `{ scope, id, message }` — no severity, no target/category
-// taxonomy (deferred per the ADR).
+// Findings stay `{ scope, id, message }` plus the two un-frozen optional
+// fields `ruleId` and `severity` — the richer target/category taxonomy stays
+// deferred per the ADR.
 
+import { checkStrategyChainSemantics } from './check-strategy-chain.js';
+import { checkElementHygiene } from './check-element-hygiene.js';
 import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
 
 const PScope: RepoFinding['scope'] = 'repo';
@@ -33,15 +36,16 @@ const PScope: RepoFinding['scope'] = 'repo';
 /** Statuses that, per lint.py's policy check, require an owner. */
 const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
 
-function isRecord(v: unknown): v is Record<string, unknown> {
+export function isRecord(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 
 /** Read a string `id` from a parsed doc, or `null` if absent/non-string.
  *  Mirrors lint.py, which only treats a doc as an element/relation when it has
  *  a top-level `id` (sidecars such as versioned-attribute files have no `id`
- *  and are ignored). */
-function docId(doc: RepoDoc): string | null {
+ *  and are ignored). Exported for reuse by `resolve-model.ts`, which needs the
+ *  same id/endpoint reading rules to stay in lockstep with this validator. */
+export function docId(doc: RepoDoc): string | null {
   if (!doc.data) return null;
   const id = doc.data['id'];
   return typeof id === 'string' && id.length > 0 ? id : null;
@@ -49,7 +53,7 @@ function docId(doc: RepoDoc): string | null {
 
 /** Resolve a relation endpoint, which may be a bare id string or a `{ id }`
  *  mapping (lint.py accepts both). Returns the id string or `null`. */
-function endpointId(value: unknown): string | null {
+export function endpointId(value: unknown): string | null {
   if (typeof value === 'string') return value.length > 0 ? value : null;
   if (isRecord(value)) {
     const id = value['id'];
@@ -345,6 +349,7 @@ function checkLayerSemantics(input: RepoModelInput, findings: RepoFinding[]): vo
       findings.push({
         scope: PScope,
         id: svcId,
+        ruleId: 'TSVC-003',
         message:
           `TSVC-003: TECHNOLOGY_SERVICE '${svcId}' node '${nodeRef}' ` +
           `must resolve to a NODE element; got notation='${resolved['notation']}'.`,
@@ -368,6 +373,7 @@ function checkLayerSemantics(input: RepoModelInput, findings: RepoFinding[]): vo
         findings.push({
           scope: PScope,
           id: intId,
+          ruleId: 'INT-002',
           message:
             `INT-002: INTEGRATION '${intId}' interface_semantics endpoint '${endpointId}' ` +
             `(${field}) must resolve to an APPLICATION element; got notation='${resolved['notation']}'.`,
@@ -399,8 +405,9 @@ function checkPolicy(input: RepoModelInput, findings: RepoFinding[]): void {
 /**
  * Run all repo-scope checks over a loaded canon model and return the findings.
  * Pure: no IO, deterministic order (syntax, uniqueness, atomicity, referential,
- * semantics, policy). Reaches parity with `lint.py` on the `acme_corp` fixture
- * (zero findings on a clean tree).
+ * semantics, policy, strategy-chain). Reaches parity with `lint.py` on the
+ * `acme_corp` fixture (zero findings on a clean tree from the original
+ * lint.py-ported phases).
  */
 export function validateRepoModel(input: RepoModelInput): RepoFinding[] {
   const findings: RepoFinding[] = [];
@@ -415,5 +422,11 @@ export function validateRepoModel(input: RepoModelInput): RepoFinding[] {
   checkReferentialIntegrity(input, findings);
   checkLayerSemantics(input, findings);
   checkPolicy(input, findings);
+  // Phase 7 — strategy-chain semantic rules ported from DSM's Go Validate*
+  // functions (GOALS-010, ACT-006..009, FGCA-008..011).
+  checkStrategyChainSemantics(input, findings);
+  // Phase 8 — standalone-element envelope rules ported from DSM's Go
+  // Validate*Element functions (GOAL-ELEM-001..003, ACTION-001/002/005).
+  checkElementHygiene(input, findings);
   return findings;
 }

package/src/webview/render-blocks.ts

@@ -12,14 +12,25 @@
  * the shared theme CSS embedded in a `<style>` element and a simple optional
  * title `<text>`.
  */
-import { layoutNestedBlocks } from '../blocks/layout.js';
-import type { BlocksFile, BlocksLayout, BlocksLayoutOptions, LaidOutBlock } from '../blocks/types.js';
+import { layoutNestedBlocks, layoutGrid } from '../blocks/layout.js';
+import type {
+  BlocksFile,
+  BlocksLayout,
+  BlocksLayoutOptions,
+  GridFile,
+  GridLayout,
+  GridLayoutOptions,
+  LaidOutBlock,
+} from '../blocks/types.js';
 import { parseNodeSizePreset, resolveBlocksLeafSize, type NodeSizePreset } from '../node-size-presets.js';
 import { generateSvgEmbedCss, type ThemeId } from '../theme/index.js';
 import {
+  CHAR_W_PRIMARY,
   emitCenteredTextSvg,
   layoutHeaderBlockText,
   layoutLeafBlockText,
+  maxCharsForInnerWidth,
+  wrapWords,
 } from './entity-text-layout.js';
 import { escXml } from './render-util.js';
 import { ENTITY_NODE_RX } from './notation-style.js';
@@ -141,3 +152,149 @@ export function renderBlocksSvg(doc: BlocksFile, options: RenderBlocksOptions =
 
   return renderBlocksLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
 }
+
+/**
+ * Matrix subset (08-blocks.md §4a) — first cut: a single-layer rectangular
+ * `grid:` document (the RACI-style matrix case) rendered as a plain
+ * HTML/CSS-table-like SVG grid. Layers, arbitrary
+ * (non-rectangular) cell sets, and nested sub-grids belong to the general
+ * layered-grid superset, which is still in design upstream (methodology) and
+ * out of scope here — see 08-blocks.md §4a / §8.
+ */
+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[],
+  cls: string,
+  cx: number,
+  cellTop: number,
+  cellHeight: number,
+): string {
+  const ls = lines.length > 0 ? lines : [''];
+  const firstY = cellTop + cellHeight / 2 - ((ls.length - 1) / 2) * GRID_LINE_HEIGHT;
+  const tspans = ls
+    .map((ln, i) => `<tspan x="${cx}" y="${firstY + i * GRID_LINE_HEIGHT}">${escXml(ln)}</tspan>`)
+    .join('');
+  return `<text class="${cls}" text-anchor="middle" dominant-baseline="central">${tspans}</text>`;
+}
+
+/**
+ * Emit the grid body (headers, cells, grid lines) at the given origin offset.
+ * Shared by the host-neutral wrapper below; VS Code's blocks preview wraps
+ * this the same way it wraps {@link renderBlocksLayoutSvg} for the tree form.
+ */
+export function renderGridBody(layout: GridLayout, ox: number, oy: number): string {
+  const tw = layout.bounds.width;
+  const th = layout.bounds.height;
+  const parts: string[] = [];
+
+  parts.push(`<rect class="diagram-node level-0" x="${ox}" y="${oy}" width="${tw}" height="${th}" stroke="none"/>`);
+
+  // Corner cell (above the row headers, left of the column headers).
+  parts.push(
+    `<rect class="diagram-node level-1" x="${ox}" y="${oy}" width="${layout.rowHeaderWidth}" height="${layout.headerHeight}" stroke="none"/>`,
+  );
+
+  for (const col of layout.columns) {
+    const x = col.x + ox;
+    parts.push(
+      `<rect class="diagram-node level-1" x="${x}" y="${oy}" width="${col.width}" height="${layout.headerHeight}" stroke="none"/>`,
+    );
+    const maxChars = maxCharsForInnerWidth(col.width - GRID_CELL_PAD_X * 2, CHAR_W_PRIMARY);
+    const lines = wrapWords(col.name, maxChars, 2);
+    parts.push(centeredGridCellTextSvg(lines, 'text-header', x + col.width / 2, oy, layout.headerHeight));
+  }
+
+  for (const row of layout.rows) {
+    const y = row.y + oy;
+    parts.push(
+      `<rect class="diagram-node level-2" x="${ox}" y="${y}" width="${layout.rowHeaderWidth}" height="${row.height}" stroke="none"/>`,
+    );
+    const maxChars = maxCharsForInnerWidth(layout.rowHeaderWidth - GRID_CELL_PAD_X * 2, CHAR_W_PRIMARY);
+    const lines = wrapWords(row.name, maxChars, 2);
+    parts.push(centeredGridCellTextSvg(lines, 'text-primary', ox + layout.rowHeaderWidth / 2, y, row.height));
+  }
+
+  for (const cell of layout.cells) {
+    if (cell.value === undefined) continue;
+    const cx = cell.x + ox + cell.width / 2;
+    const cy = cell.y + oy + cell.height / 2;
+    parts.push(
+      `<text class="text-secondary" x="${cx}" y="${cy}" text-anchor="middle" dominant-baseline="central">${escXml(cell.value)}</text>`,
+    );
+  }
+
+  const gridX1 = ox;
+  const gridX2 = ox + tw;
+  const gridY1 = oy;
+  const gridY2 = oy + th;
+
+  const headerBottomY = oy + layout.headerHeight;
+  parts.push(`<line class="diagram-edge" x1="${gridX1}" y1="${headerBottomY}" x2="${gridX2}" y2="${headerBottomY}"/>`);
+  for (const row of layout.rows) {
+    const rowBottomY = oy + row.y + row.height;
+    parts.push(`<line class="diagram-edge" x1="${gridX1}" y1="${rowBottomY}" x2="${gridX2}" y2="${rowBottomY}"/>`);
+  }
+
+  const rowHeaderLineX = ox + layout.rowHeaderWidth;
+  parts.push(`<line class="diagram-edge" x1="${rowHeaderLineX}" y1="${gridY1}" x2="${rowHeaderLineX}" y2="${gridY2}"/>`);
+  for (const col of layout.columns) {
+    const colLineX = ox + col.x + col.width;
+    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}"/>`);
+
+  return parts.join('\n');
+}
+
+export interface RenderGridLayoutOptions {
+  /** Extra vertical space reserved at the top of the canvas (e.g. for a title block). */
+  topInset?: number;
+  /** Raw SVG injected immediately after the opening tag — a header line or a full title block. */
+  title?: string;
+  /** When set, the theme CSS is embedded as `<style>` so the SVG is self-contained. */
+  embedCssTheme?: ThemeId;
+}
+
+/** The single grid (matrix subset) SVG emitter shared by every host. */
+export function renderGridLayoutSvg(layout: GridLayout, options: RenderGridLayoutOptions = {}): string {
+  const { topInset = 0, title = '', embedCssTheme } = options;
+
+  const w = layout.bounds.width + PAD * 2;
+  const h = layout.bounds.height + PAD * 2 + topInset;
+  const ox = PAD;
+  const oy = PAD + topInset;
+
+  const body = renderGridBody(layout, ox, oy);
+  const styleLine = embedCssTheme ? `\n<style>${generateSvgEmbedCss(embedCssTheme)}${GRID_EMBED_CSS}</style>` : '';
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">${styleLine}
+${title}
+${body}
+</svg>`;
+}
+
+export interface RenderGridOptions {
+  title?: string;
+  layoutOptions?: GridLayoutOptions;
+}
+
+/** Host-neutral grid (matrix subset) renderer (IntelliJ/UI). */
+export function renderGridSvg(doc: GridFile, options: RenderGridOptions = {}): string {
+  const { title = '', layoutOptions } = options;
+  const layout = layoutGrid(doc, layoutOptions);
+
+  if (layout.columns.length === 0 || layout.rows.length === 0) {
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
+  }
+
+  const titleSvg = title
+    ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(`Nested Blocks — ${title}`)}</text>`
+    : '';
+
+  return renderGridLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
+}