@transitrix/diagrams 1.0.0 → 1.1.0

package/src/compliance-matrix/types.ts

@@ -1,102 +1,102 @@
-// Compliance matrix model (vkgeorgia/strategy#84 Phase 2).
-//
-// The matrix is Products × Requirements. Each cell is the status of the
-// (Product, Requirement) ASSERTION when one exists, or a gap when none does.
-// Pure data — the layout is computed by `build.ts`; the Studio preview renders
-// it. Non-product-subject assertions (CAPABILITY / PROCESS) belong to the
-// single-product / single-law views (Phase 3) and are ignored here.
-
-import type { AssertionStatus } from '../assertion/types.js';
-
-/** A row of the matrix — a discovered PRODUCT element. */
-export interface MatrixProduct {
-  id: string;
-  name: string;
-  /** True when the product was discovered only as an assertion subject (no
-   *  product element file resolves it) — a dangling subject reference. */
-  unresolved?: boolean;
-}
-
-/** A column of the matrix — a discovered REQUIREMENT. */
-export interface MatrixRequirement {
-  id: string;
-  name: string;
-  /** Organisation-defined priority (high | medium | low), used by the filter. */
-  severity?: string;
-  /** Typed IDs of the codex sources this requirement derives from (verbatim
-   *  from `derived_from`). Carried so the renderer can surface provenance and
-   *  resolve jurisdictions without re-scanning. */
-  derived_from?: string[];
-  /** Jurisdictions resolved by walking `derived_from` → codex artefacts and
-   *  collecting their `jurisdiction` (Codex §1.1). Unique, sorted. Empty when
-   *  no codex source resolves with a jurisdiction (internal-only requirements,
-   *  or codex artefacts the scan did not find / has no jurisdiction). The
-   *  toolbar jurisdiction filter (F16) keys on this set. */
-  jurisdictions?: string[];
-}
-
-/** A codex source document the matrix uses to resolve `Requirement.jurisdictions`. */
-export interface MatrixCodexDoc {
-  id: string;
-  jurisdiction?: string;
-}
-
-/** The assertion fields the matrix needs (a projection of the full Assertion). */
-export interface MatrixAssertionRef {
-  id: string;
-  about: string;
-  subject: string;
-  status: AssertionStatus;
-  assessed_at?: string;
-  next_review_at?: string;
-}
-
-/** One grid cell. `status === undefined` is a gap (no assertion for the pair). */
-export interface MatrixCell {
-  productId: string;
-  requirementId: string;
-  /** The assertion filling this cell, when one exists. */
-  assertionId?: string;
-  status?: AssertionStatus;
-  assessed_at?: string;
-  next_review_at?: string;
-}
-
-export interface ComplianceMatrix {
-  /** Rows, sorted by id. */
-  products: MatrixProduct[];
-  /** Columns, sorted by id. */
-  requirements: MatrixRequirement[];
-  /** `cells[rowIndex][colIndex]`, aligned to `products` × `requirements`. */
-  cells: MatrixCell[][];
-  /** Counts for the summary strip. */
-  summary: {
-    products: number;
-    requirements: number;
-    assertions: number;
-    /** Cells with no assertion (compliance gaps). */
-    gaps: number;
-  };
-}
-
-export interface ComplianceMatrixInput {
-  products: MatrixProduct[];
-  requirements: MatrixRequirement[];
-  assertions: MatrixAssertionRef[];
-  /** Codex source documents — used to resolve each Requirement's jurisdictions
-   *  by walking `derived_from`. Optional: when omitted the builder still works
-   *  and every requirement's `jurisdictions` is left empty. */
-  codex?: MatrixCodexDoc[];
-}
-
-/** Toolbar filter — empty/omitted fields mean "no filter on that dimension". */
-export interface MatrixFilter {
-  /** Keep only requirement columns whose severity is in this set. */
-  severities?: string[];
-  /** Keep only the cell status badges in this set; others render as filtered. */
-  statuses?: AssertionStatus[];
-  /** Keep only requirement columns whose resolved jurisdictions intersect this
-   *  set. Requirements with no resolved jurisdiction are filtered out when this
-   *  is non-empty (F16, epic #84). */
-  jurisdictions?: string[];
-}
+// Compliance matrix model (vkgeorgia/strategy#84 Phase 2).
+//
+// The matrix is Products × Requirements. Each cell is the status of the
+// (Product, Requirement) ASSERTION when one exists, or a gap when none does.
+// Pure data — the layout is computed by `build.ts`; the Studio preview renders
+// it. Non-product-subject assertions (CAPABILITY / PROCESS) belong to the
+// single-product / single-law views (Phase 3) and are ignored here.
+
+import type { AssertionStatus } from '../assertion/types.js';
+
+/** A row of the matrix — a discovered PRODUCT element. */
+export interface MatrixProduct {
+  id: string;
+  name: string;
+  /** True when the product was discovered only as an assertion subject (no
+   *  product element file resolves it) — a dangling subject reference. */
+  unresolved?: boolean;
+}
+
+/** A column of the matrix — a discovered REQUIREMENT. */
+export interface MatrixRequirement {
+  id: string;
+  name: string;
+  /** Organisation-defined priority (high | medium | low), used by the filter. */
+  severity?: string;
+  /** Typed IDs of the codex sources this requirement derives from (verbatim
+   *  from `derived_from`). Carried so the renderer can surface provenance and
+   *  resolve jurisdictions without re-scanning. */
+  derived_from?: string[];
+  /** Jurisdictions resolved by walking `derived_from` → codex artefacts and
+   *  collecting their `jurisdiction` (Codex §1.1). Unique, sorted. Empty when
+   *  no codex source resolves with a jurisdiction (internal-only requirements,
+   *  or codex artefacts the scan did not find / has no jurisdiction). The
+   *  toolbar jurisdiction filter (F16) keys on this set. */
+  jurisdictions?: string[];
+}
+
+/** A codex source document the matrix uses to resolve `Requirement.jurisdictions`. */
+export interface MatrixCodexDoc {
+  id: string;
+  jurisdiction?: string;
+}
+
+/** The assertion fields the matrix needs (a projection of the full Assertion). */
+export interface MatrixAssertionRef {
+  id: string;
+  about: string;
+  subject: string;
+  status: AssertionStatus;
+  assessed_at?: string;
+  next_review_at?: string;
+}
+
+/** One grid cell. `status === undefined` is a gap (no assertion for the pair). */
+export interface MatrixCell {
+  productId: string;
+  requirementId: string;
+  /** The assertion filling this cell, when one exists. */
+  assertionId?: string;
+  status?: AssertionStatus;
+  assessed_at?: string;
+  next_review_at?: string;
+}
+
+export interface ComplianceMatrix {
+  /** Rows, sorted by id. */
+  products: MatrixProduct[];
+  /** Columns, sorted by id. */
+  requirements: MatrixRequirement[];
+  /** `cells[rowIndex][colIndex]`, aligned to `products` × `requirements`. */
+  cells: MatrixCell[][];
+  /** Counts for the summary strip. */
+  summary: {
+    products: number;
+    requirements: number;
+    assertions: number;
+    /** Cells with no assertion (compliance gaps). */
+    gaps: number;
+  };
+}
+
+export interface ComplianceMatrixInput {
+  products: MatrixProduct[];
+  requirements: MatrixRequirement[];
+  assertions: MatrixAssertionRef[];
+  /** Codex source documents — used to resolve each Requirement's jurisdictions
+   *  by walking `derived_from`. Optional: when omitted the builder still works
+   *  and every requirement's `jurisdictions` is left empty. */
+  codex?: MatrixCodexDoc[];
+}
+
+/** Toolbar filter — empty/omitted fields mean "no filter on that dimension". */
+export interface MatrixFilter {
+  /** Keep only requirement columns whose severity is in this set. */
+  severities?: string[];
+  /** Keep only the cell status badges in this set; others render as filtered. */
+  statuses?: AssertionStatus[];
+  /** Keep only requirement columns whose resolved jurisdictions intersect this
+   *  set. Requirements with no resolved jurisdiction are filtered out when this
+   *  is non-empty (F16, epic #84). */
+  jurisdictions?: string[];
+}

package/src/edge-path.ts

@@ -1,44 +1,50 @@
-// Shared edge geometry for the static notation previews (Goals, FGCA, FGA,
-// Activities). All four render dependency/relationship edges as a single cubic
-// Bézier with horizontal control handles: each control point shares its
-// endpoint's Y, so the tangent is horizontal at both ends and the marker-end
-// arrow reads as perpendicular to the node's vertical edge.
-//
-// Pulling the path math here (rather than duplicating it inline in each
-// preview) makes the configurable-curvature behaviour (vkgeorgia/strategy#76)
-// unit-testable — the extension has no test harness.
-
-/**
- * Base handle length floor + span factors. The handle grows with both the
- * horizontal and vertical span so the curve stays visibly horizontal long
- * enough for the arrowhead to sit flush against the line.
- */
-export const EDGE_MIN_HANDLE = 64;
-const DX_FACTOR = 0.5;
-const DY_FACTOR = 0.8;
-
-/** Multiplier applied to the base handle length. 1 = historical appearance. */
-export const DEFAULT_EDGE_CURVATURE = 1;
-
-/**
- * Builds the SVG `d` for a horizontal-tangent cubic Bézier from (sx,sy) to
- * (tx,ty).
- *
- * `curvature` scales the control-handle length:
- *   - 0   → control points collapse onto the endpoints ⇒ a straight line.
- *   - 1   → the historical curve (no visual change from before #76).
- *   - >1  → progressively stronger arc.
- */
-export function horizontalCubicEdgePath(
-  sx: number,
-  sy: number,
-  tx: number,
-  ty: number,
-  curvature: number = DEFAULT_EDGE_CURVATURE,
-): string {
-  const dx = tx - sx;
-  const dy = ty - sy;
-  const baseHandle = Math.max(EDGE_MIN_HANDLE, Math.abs(dx) * DX_FACTOR, Math.abs(dy) * DY_FACTOR);
-  const handle = baseHandle * curvature;
-  return `M${sx},${sy} C${sx + handle},${sy} ${tx - handle},${ty} ${tx},${ty}`;
-}
+// Shared edge geometry for the static notation previews (Goals, FGCA, FGA,
+// Activities). All four render dependency/relationship edges as a single cubic
+// Bézier with horizontal control handles: each control point shares its
+// endpoint's Y, so the tangent is horizontal at both ends and the marker-end
+// arrow reads as perpendicular to the node's vertical edge.
+//
+// Pulling the path math here (rather than duplicating it inline in each
+// preview) makes the configurable-curvature behaviour (vkgeorgia/strategy#76)
+// unit-testable — the extension has no test harness.
+
+/**
+ * Base handle length floor + span factors. The handle grows with both the
+ * horizontal and vertical span so the curve stays visibly horizontal long
+ * enough for the arrowhead to sit flush against the line.
+ */
+export const EDGE_MIN_HANDLE = 64;
+const DX_FACTOR = 0.5;
+const DY_FACTOR = 0.8;
+
+/** Multiplier applied to the base handle length. 1 = historical appearance. */
+export const DEFAULT_EDGE_CURVATURE = 1;
+
+/**
+ * Builds the SVG `d` for a horizontal-tangent cubic Bézier from (sx,sy) to
+ * (tx,ty).
+ *
+ * `curvature` scales the exit control-handle (departure from source).
+ * `entryCurvature` scales the entry control-handle (arrival at target);
+ * defaults to `curvature` when omitted so callers that pass one value get
+ * symmetric handles (the historical behaviour).
+ *
+ *   - 0   → handle collapses onto its endpoint ⇒ straight at that end.
+ *   - 1   → the historical curve (no visual change from before #76).
+ *   - >1  → progressively stronger arc at that end.
+ */
+export function horizontalCubicEdgePath(
+  sx: number,
+  sy: number,
+  tx: number,
+  ty: number,
+  curvature: number = DEFAULT_EDGE_CURVATURE,
+  entryCurvature?: number,
+): string {
+  const dx = tx - sx;
+  const dy = ty - sy;
+  const baseHandle = Math.max(EDGE_MIN_HANDLE, Math.abs(dx) * DX_FACTOR, Math.abs(dy) * DY_FACTOR);
+  const exitHandle = baseHandle * curvature;
+  const entryHandle = baseHandle * (entryCurvature ?? curvature);
+  return `M${sx},${sy} C${sx + exitHandle},${sy} ${tx - entryHandle},${ty} ${tx},${ty}`;
+}

package/src/factor/__tests__/validate.test.ts

@@ -1,11 +1,12 @@
 import { describe, it, expect } from 'vitest';
 import { validateFactor } from '../validate.js';
+import type { CanonCatalog } from '../../typed-id.js';
 
-function valid(): Record<string, unknown> {
+function validExternal(): Record<string, unknown> {
   return {
-    notation: 'factor',
+    notation: 'driver',
     id: 'FACTOR-EU-REG-1',
-    name: 'EU regulatory window for market entry',
+    name: 'EU regulatory window',
     type: 'external',
     category: 'legal',
     description: 'Standing external driver — the EU regulatory regime.',
@@ -19,80 +20,114 @@ function valid(): Record<string, unknown> {
   };
 }
 
-const codes = (input: unknown): string[] => validateFactor(input).errors.map(e => e.code);
-const warns = (input: unknown): string[] => validateFactor(input).warnings.map(w => w.code);
+function validInternal(): Record<string, unknown> {
+  return {
+    notation: 'driver',
+    id: 'FACTOR-COMP-1',
+    name: 'Support response time',
+    type: 'internal',
+    description: 'Standing internal driver.',
+    zone: 'canon',
+    admitted_at: '2026-05-29',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2026-05-26',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown, opts?: Parameters<typeof validateFactor>[1]): string[] =>
+  validateFactor(input, opts).errors.map(e => e.code);
 
 describe('validateFactor — positive', () => {
-  it('accepts the worked-example FACTOR-EU-REG-1', () => {
-    const r = validateFactor(valid());
+  it('accepts a well-formed external PESTLE factor', () => {
+    const r = validateFactor(validExternal());
     expect(r.valid, JSON.stringify(r.errors)).toBe(true);
-    expect(r.errors).toHaveLength(0);
   });
 
-  it('accepts a minimal factor (no type/category/references)', () => {
-    const r = valid();
-    delete r.type;
-    delete r.category;
-    delete r.references_constraint;
-    expect(validateFactor(r).valid).toBe(true);
+  it('accepts a well-formed internal factor (no PESTLE category)', () => {
+    expect(validateFactor(validInternal()).valid).toBe(true);
   });
-});
 
-describe('validateFactor — FACTOR-001 (envelope / shape)', () => {
-  it('flags a non-object', () => {
-    expect(codes(null)).toEqual(['FACTOR-001']);
-    expect(codes(['x'])).toEqual(['FACTOR-001']);
+  it('accepts a minimal factor with no optional fields', () => {
+    const f = validInternal();
+    delete f.type;
+    delete f.description;
+    expect(validateFactor(f).valid).toBe(true);
   });
+});
 
-  it('flags a wrong notation tag', () => {
-    expect(codes({ ...valid(), notation: 'driver' })).toContain('FACTOR-001');
+describe('validateFactor — FACTOR-001 (shape / id grammar)', () => {
+  it('flags a missing required envelope field', () => {
+    const f = validExternal();
+    delete f.admitted_by;
+    expect(codes(f)).toContain('FACTOR-001');
   });
 
-  it('flags an id with the wrong TYPE prefix', () => {
-    expect(codes({ ...valid(), id: 'GOAL-EU-1' })).toContain('FACTOR-001');
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...validExternal(), id: 'FACTOR-EU-REG-001' })).toContain('FACTOR-001');
+    expect(codes({ ...validExternal(), id: 'FAC-1' })).toContain('FACTOR-001');
+    expect(codes({ ...validExternal(), id: 'factor-1' })).toContain('FACTOR-001');
   });
 
-  it('flags an id with a leading-zero terminal', () => {
-    expect(codes({ ...valid(), id: 'FACTOR-EU-REG-01' })).toContain('FACTOR-001');
+  it('flags a wrong notation tag and a non-canon zone', () => {
+    expect(codes({ ...validExternal(), notation: 'factor' })).toContain('FACTOR-001');
+    expect(codes({ ...validExternal(), zone: 'sandbox' })).toContain('FACTOR-001');
   });
 
   it('flags a missing valid_to key (distinct from a null value)', () => {
-    const r = valid();
-    delete r.valid_to;
-    expect(codes(r)).toContain('FACTOR-001');
-    expect(validateFactor({ ...valid(), valid_to: null }).valid).toBe(true);
+    const f = validExternal();
+    delete f.valid_to;
+    expect(codes(f)).toContain('FACTOR-001');
   });
 
-  it('flags references_constraint entries that are not CONSTRAINT typed ids', () => {
-    expect(codes({ ...valid(), references_constraint: ['GOAL-EU-1'] })).toContain('FACTOR-001');
-    expect(codes({ ...valid(), references_constraint: 'CONSTRAINT-X-1' })).toContain('FACTOR-001');
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['FACTOR-001']);
+    expect(codes(['a'])).toEqual(['FACTOR-001']);
   });
 });
 
 describe('validateFactor — FACTOR-002 (type enum)', () => {
-  it('flags a type outside external/internal', () => {
-    expect(codes({ ...valid(), type: 'driver' })).toContain('FACTOR-002');
+  it('flags a type value outside {external, internal}', () => {
+    expect(codes({ ...validExternal(), type: 'driver' })).toContain('FACTOR-002');
+  });
+});
+
+describe('validateFactor — FACTOR-003 (PESTLE category)', () => {
+  it('flags a category outside PESTLE', () => {
+    expect(codes({ ...validExternal(), category: 'cosmic' })).toContain('FACTOR-003');
   });
 
-  it('accepts each permitted type', () => {
-    for (const t of ['external', 'internal']) {
-      expect(codes({ ...valid(), type: t, category: undefined })).not.toContain('FACTOR-002');
+  it('flags PESTLE category on an internal factor', () => {
+    const f = validInternal();
+    f.category = 'legal';
+    expect(codes(f)).toContain('FACTOR-003');
+  });
+
+  it('accepts each permitted PESTLE category on an external factor', () => {
+    for (const cat of ['political', 'economic', 'social', 'technological', 'legal', 'environmental']) {
+      const f = validExternal();
+      f.category = cat;
+      expect(codes(f)).not.toContain('FACTOR-003');
     }
   });
 });
 
-describe('validateFactor — FACTOR-003 (PESTLE category)', () => {
-  it('flags a category outside the PESTLE classes', () => {
-    expect(codes({ ...valid(), category: 'cultural' })).toContain('FACTOR-003');
+describe('validateFactor — FACTOR-004 (references_constraint)', () => {
+  it('flags a malformed references_constraint entry', () => {
+    expect(codes({ ...validExternal(), references_constraint: ['not an id'] })).toContain('FACTOR-004');
   });
 
-  it('warns when category is set on an internal factor', () => {
-    expect(warns({ ...valid(), type: 'internal', category: 'economic' })).toContain('FACTOR-003');
+  it('flags a references_constraint entry of the wrong TYPE', () => {
+    expect(codes({ ...validExternal(), references_constraint: ['GOAL-X-1'] })).toContain('FACTOR-004');
   });
 
-  it('accepts each permitted PESTLE class', () => {
-    for (const c of ['political', 'economic', 'social', 'technological', 'legal', 'environmental']) {
-      expect(codes({ ...valid(), category: c })).not.toContain('FACTOR-003');
-    }
+  it('flags an unresolved id when a catalog is supplied', () => {
+    const catalog: CanonCatalog = { typeOf: () => undefined };
+    expect(codes(validExternal(), { catalog })).toContain('FACTOR-004');
+  });
+
+  it('does not flag without a catalog for a well-formed CONSTRAINT id', () => {
+    expect(codes(validExternal())).not.toContain('FACTOR-004');
   });
 });

package/src/factor/index.ts

@@ -1,8 +1,4 @@
-// The `Factor` type is re-exported under the alias `FactorPrimitive` at the
-// package surface to avoid a name collision with the legacy FGCA-inline
-// `Factor` shape exported from `./goals/index` (a v0.x view shape with
-// numeric ids — distinct from this element primitive). Both types remain
-// importable from their module subpaths.
-export type { Factor as FactorPrimitive, FactorType, FactorCategory } from './types.js';
-export { FACTOR_TYPES, FACTOR_CATEGORIES } from './types.js';
+export type { Factor, FactorType, FactorPestleCategory } from './types.js';
+export { FACTOR_PESTLE_CATEGORIES } from './types.js';
 export { validateFactor } from './validate.js';
+export type { FactorValidateOptions } from './validate.js';

package/src/factor/types.ts

@@ -1,41 +1,37 @@
-// FACTOR — motivation-layer driver primitive.
-// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.1 + envelope §3.
+// FACTOR — motivation-layer Driver (ArchiMate).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.1.
 
 import type { GateChecks } from '../requirement/types.js';
 
-/** Optional subtype — internal/external organisation force. */
 export type FactorType = 'external' | 'internal';
 
-export const FACTOR_TYPES = ['external', 'internal'] as const;
-
-/** PESTLE sub-classification — external factors only. Open-ended in practice
- *  but v1 fixes the six standard classes; an unknown category is flagged. */
-export type FactorCategory =
-  | 'political'
-  | 'economic'
-  | 'social'
-  | 'technological'
-  | 'legal'
-  | 'environmental';
-
-export const FACTOR_CATEGORIES = [
-  'political', 'economic', 'social', 'technological', 'legal', 'environmental',
+/** PESTLE sub-classification — external factors only (§7.1). */
+export const FACTOR_PESTLE_CATEGORIES = [
+  'political',
+  'economic',
+  'social',
+  'technological',
+  'legal',
+  'environmental',
 ] as const;
+export type FactorPestleCategory = typeof FACTOR_PESTLE_CATEGORIES[number];
 
 export interface Factor {
-  notation: 'factor';
+  notation: 'driver';
   id: string;
   name: string;
   type?: FactorType;
-  category?: FactorCategory;
+  category?: FactorPestleCategory;
   description?: string;
   references_constraint?: string[];
 
+  // Admission record (CONTRACT.md §6).
   zone: 'canon';
   admitted_at: string;
   admitted_by: string;
   gate_checks: GateChecks;
 
+  // Primitive lifecycle (CONTRACT.md §7).
   valid_from: string;
   valid_to: string | null;
 }