@transitrix/diagrams 1.0.0 → 1.1.0

package/src/stakeholder/validate.ts

@@ -1,61 +1,88 @@
-// STAKEHOLDER validator — methodology notations/ELEMENT_PRIMITIVES.md §7.15
-// + notations/elements/20-stakeholders.md.
+// STAKEHOLDER validator — methodology notations/elements/20-stakeholders.md §5.
 //
-// Implements STAKEHOLDER-001..004. Stake-in-a-specific-object lives on
-// `stakeholding` REL records (elements/17-relations.md §3) and is out of
-// scope for this single-artefact validator.
+// Codes:
+//   STAKE-001 — shape / id grammar / required envelope / interest|influence enum.
+//   STAKE-002 — `actor` missing, malformed, wrong TYPE, or unresolved in catalog.
+//   STAKE-003 — `type` outside {internal, external}.
 
-import type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
-import { typeOfId } from '../typed-id.js';
-import { validateElementEnvelope } from '../element-envelope.js';
-import { STAKEHOLDER_LEVELS, STAKEHOLDER_TYPES } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { STAKEHOLDER_TYPES, STAKEHOLDER_LEVELS } from './types.js';
 
-export function validateStakeholder(input: unknown): ValidationResult {
+export interface StakeholderValidateOptions {
+  /** When provided, STAKE-002 enforces that `actor` resolves to an admitted ACTOR. */
+  catalog?: CanonCatalog;
+}
+
+const REQUIRED_STRING_FIELDS = [
+  'name', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
+
+const TYPES: readonly string[] = STAKEHOLDER_TYPES;
+const LEVELS: readonly string[] = STAKEHOLDER_LEVELS;
+
+export function validateStakeholder(input: unknown, options: StakeholderValidateOptions = {}): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
-  const { record, errors: envErrors } = validateElementEnvelope(input, {
-    notation: 'stakeholder',
-    idType: 'STAKEHOLDER',
-    code: 'STAKEHOLDER-001',
-  });
-  errors.push(...envErrors);
-  if (!record) return { valid: false, errors, warnings };
-
-  // STAKEHOLDER-002 — type subtype required.
-  if (record.type === undefined || record.type === null) {
-    errors.push({ code: 'STAKEHOLDER-002', message: 'type is required (internal | external).', path: 'type' });
-  } else if (!STAKEHOLDER_TYPES.includes(record.type as never)) {
-    errors.push({
-      code: 'STAKEHOLDER-002',
-      message: `type "${String(record.type)}" must be one of ${STAKEHOLDER_TYPES.join(', ')}.`,
-      path: 'type',
-    });
-  }
-
-  // STAKEHOLDER-003 — actor identity binding (REQUIRED, must be ACTOR-…).
-  if (record.actor === undefined || record.actor === null || record.actor === '') {
-    errors.push({
-      code: 'STAKEHOLDER-003',
-      message: 'actor is required — identity lives in an ACTOR-… record, never inline.',
-      path: 'actor',
-    });
-  } else if (typeOfId(record.actor) !== 'ACTOR') {
-    errors.push({
-      code: 'STAKEHOLDER-003',
-      message: `actor "${String(record.actor)}" must be an ACTOR typed ID.`,
-      path: 'actor',
-    });
-  }
-
-  // STAKEHOLDER-004 — interest / influence level enums (optional fields).
-  for (const f of ['interest', 'influence'] as const) {
-    if (record[f] !== undefined && !STAKEHOLDER_LEVELS.includes(record[f] as never)) {
-      errors.push({
-        code: 'STAKEHOLDER-004',
-        message: `${f} "${String(record[f])}" must be one of ${STAKEHOLDER_LEVELS.join(', ')}.`,
-        path: f,
-      });
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'STAKE-001', message: 'Stakeholder must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const s = input as Record<string, unknown>;
+
+  // STAKE-001 — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(s.id, 'STAKEHOLDER')) {
+    errors.push({ code: 'STAKE-001', message: `id "${String(s.id)}" must match STAKEHOLDER-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (s.notation !== 'stakeholder') {
+    errors.push({ code: 'STAKE-001', message: 'notation must be the fixed value "stakeholder".', path: 'notation' });
+  }
+  if (s.zone !== undefined && s.zone !== 'canon') {
+    errors.push({ code: 'STAKE-001', message: 'zone must be "canon" for a STAKEHOLDER.', path: 'zone' });
+  } else if (s.zone === undefined) {
+    errors.push({ code: 'STAKE-001', message: 'zone is required.', path: 'zone' });
+  }
+  for (const field of REQUIRED_STRING_FIELDS) {
+    const v = s[field];
+    if (typeof v !== 'string' || v.trim() === '') {
+      errors.push({ code: 'STAKE-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (s.gate_checks === null || typeof s.gate_checks !== 'object') {
+    errors.push({ code: 'STAKE-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in s) || !(typeof s.valid_to === 'string' || s.valid_to === null)) {
+    errors.push({ code: 'STAKE-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+
+  // STAKE-003 — type enum (required field).
+  if (typeof s.type !== 'string' || s.type.trim() === '') {
+    errors.push({ code: 'STAKE-001', message: 'type is required.', path: 'type' });
+  } else if (!TYPES.includes(s.type)) {
+    errors.push({ code: 'STAKE-003', message: `type "${s.type}" must be one of ${TYPES.join(', ')}.`, path: 'type' });
+  }
+
+  // STAKE-002 — actor identity binding (required).
+  const actor = s.actor;
+  if (typeof actor !== 'string' || actor.trim() === '') {
+    errors.push({ code: 'STAKE-002', message: 'actor is required — identity must come from an ACTOR.', path: 'actor' });
+  } else if (typeOfId(actor) !== 'ACTOR') {
+    errors.push({ code: 'STAKE-002', message: `actor "${actor}" must be a typed ACTOR id.`, path: 'actor' });
+  } else if (options.catalog) {
+    const t = options.catalog.typeOf(actor);
+    if (t === undefined) {
+      errors.push({ code: 'STAKE-002', message: `actor "${actor}" does not resolve to an admitted ACTOR.`, path: 'actor' });
+    } else if (t !== 'ACTOR') {
+      errors.push({ code: 'STAKE-002', message: `actor "${actor}" resolves to a ${t}, not an ACTOR.`, path: 'actor' });
+    }
+  }
+
+  // STAKE-001 — interest / influence levels.
+  for (const field of ['interest', 'influence'] as const) {
+    const v = s[field];
+    if (v !== undefined && (typeof v !== 'string' || !LEVELS.includes(v))) {
+      errors.push({ code: 'STAKE-001', message: `${field} "${String(v)}" must be one of ${LEVELS.join(', ')}.`, path: field });
     }
   }
 

package/src/target-state/__tests__/validate.test.ts

@@ -1,12 +1,13 @@
 import { describe, it, expect } from 'vitest';
 import { validateTargetState } from '../validate.js';
+import type { CanonCatalog } from '../../typed-id.js';
 
 function valid(): Record<string, unknown> {
   return {
     notation: 'target-state',
     id: 'TARGET_STATE-EU-LIVE-1',
     name: 'EU operations live — three markets, localised CRM and payments',
-    description: 'The structural end-state in which Acme operates in three EU markets.',
+    description: 'The structural end-state.',
     capabilities: ['CAPABILITY-V1', 'CAPABILITY-V1.2', 'CAPABILITY-V2'],
     processes: ['PROCESS-CUST-ONBOARD-1', 'PROCESS-ORD-FULFILL-1'],
     applications: ['APPLICATION-CRM-1', 'APPLICATION-OMS-1'],
@@ -19,56 +20,76 @@ function valid(): Record<string, unknown> {
   };
 }
 
-const codes = (input: unknown): string[] => validateTargetState(input).errors.map(e => e.code);
+const codes = (input: unknown, opts?: Parameters<typeof validateTargetState>[1]): string[] =>
+  validateTargetState(input, opts).errors.map(e => e.code);
 
 describe('validateTargetState — positive', () => {
-  it('accepts the worked-example TARGET_STATE-EU-LIVE-1', () => {
+  it('accepts a well-formed target state', () => {
     const r = validateTargetState(valid());
     expect(r.valid, JSON.stringify(r.errors)).toBe(true);
-    expect(r.errors).toHaveLength(0);
   });
 
-  it('accepts a minimal target state (name + envelope only)', () => {
-    const r = valid();
-    delete r.capabilities;
-    delete r.processes;
-    delete r.applications;
-    expect(validateTargetState(r).valid).toBe(true);
+  it('accepts a target state with empty composition lists', () => {
+    const t = valid();
+    delete t.capabilities;
+    delete t.processes;
+    delete t.applications;
+    expect(validateTargetState(t).valid).toBe(true);
+  });
+
+  it('accepts CAPABILITY V/H ids without integer terminal', () => {
+    const t = valid();
+    t.capabilities = ['CAPABILITY-V1.2.3', 'CAPABILITY-H1.2'];
+    expect(validateTargetState(t).valid).toBe(true);
   });
 });
 
-describe('validateTargetState — TARGET_STATE-001 (envelope / shape)', () => {
-  it('flags a non-object', () => {
-    expect(codes(null)).toEqual(['TARGET_STATE-001']);
+describe('validateTargetState — TSTATE-001 (shape / id grammar)', () => {
+  it('flags a missing required envelope field', () => {
+    const t = valid();
+    delete t.name;
+    expect(codes(t)).toContain('TSTATE-001');
+  });
+
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'TARGET_STATE-EU-LIVE-001' })).toContain('TSTATE-001');
+    expect(codes({ ...valid(), id: 'TS-1' })).toContain('TSTATE-001');
   });
 
   it('flags a wrong notation tag', () => {
-    expect(codes({ ...valid(), notation: 'plateau' })).toContain('TARGET_STATE-001');
+    expect(codes({ ...valid(), notation: 'target_state' })).toContain('TSTATE-001');
   });
 
-  it('flags an id with the wrong TYPE prefix', () => {
-    expect(codes({ ...valid(), id: 'SCENARIO-EU-LIVE-1' })).toContain('TARGET_STATE-001');
+  it('flags a non-array composition list', () => {
+    expect(codes({ ...valid(), capabilities: 'CAPABILITY-V1' })).toContain('TSTATE-001');
   });
 
-  it('flags an inline goals field (it belongs on a REL)', () => {
-    expect(codes({ ...valid(), goals: ['GOAL-EU-1'] })).toContain('TARGET_STATE-001');
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['TSTATE-001']);
   });
 });
 
-describe('validateTargetState — TARGET_STATE-002 (composition refs)', () => {
-  it('flags a non-CAPABILITY id in capabilities', () => {
-    expect(codes({ ...valid(), capabilities: ['PROCESS-X-1'] })).toContain('TARGET_STATE-002');
+describe('validateTargetState — TSTATE-002 (composition TYPEs)', () => {
+  it('flags a capabilities entry of the wrong TYPE', () => {
+    expect(codes({ ...valid(), capabilities: ['PROCESS-X-1'] })).toContain('TSTATE-002');
   });
 
-  it('flags a non-PROCESS id in processes', () => {
-    expect(codes({ ...valid(), processes: ['CAPABILITY-V1'] })).toContain('TARGET_STATE-002');
+  it('flags a processes entry of the wrong TYPE', () => {
+    expect(codes({ ...valid(), processes: ['APPLICATION-X-1'] })).toContain('TSTATE-002');
   });
 
-  it('flags a non-APPLICATION id in applications', () => {
-    expect(codes({ ...valid(), applications: ['PRODUCT-X-1'] })).toContain('TARGET_STATE-002');
+  it('flags an applications entry of the wrong TYPE', () => {
+    expect(codes({ ...valid(), applications: ['CAPABILITY-V1'] })).toContain('TSTATE-002');
   });
 
-  it('flags a composition field that is not an array', () => {
-    expect(codes({ ...valid(), capabilities: 'CAPABILITY-V1' })).toContain('TARGET_STATE-002');
+  it('flags an unresolved id when a catalog is supplied', () => {
+    const catalog: CanonCatalog = { typeOf: () => undefined };
+    expect(codes(valid(), { catalog })).toContain('TSTATE-002');
+  });
+});
+
+describe('validateTargetState — TSTATE-003 (forbidden inline goals)', () => {
+  it('flags an inline goals field', () => {
+    expect(codes({ ...valid(), goals: ['GOAL-EU-1'] })).toContain('TSTATE-003');
   });
 });

package/src/target-state/index.ts

@@ -1,2 +1,4 @@
 export type { TargetState } from './types.js';
+export { TARGET_STATE_COMPOSITION_FIELDS } from './types.js';
 export { validateTargetState } from './validate.js';
+export type { TargetStateValidateOptions } from './validate.js';

package/src/target-state/types.ts

@@ -1,28 +1,32 @@
-// TARGET_STATE — implementation-layer plateau primitive (ArchiMate Plateau).
-// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.17 + envelope §3.
-//
-// The id TYPE prefix is `TARGET_STATE` (underscore — uppercase identifier in
-// IDS_AND_REFERENCES.md §3.1). The notation tag is the lowercased hyphenated
-// short name `target-state` (per ELEMENT_PRIMITIVES.md §4).
+// TARGET_STATE — implementation-layer Plateau (ArchiMate).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.18.
 
 import type { GateChecks } from '../requirement/types.js';
 
+/** Composition list field → expected TYPE prefix of each entry. */
+export const TARGET_STATE_COMPOSITION_FIELDS = {
+  capabilities: 'CAPABILITY',
+  processes: 'PROCESS',
+  applications: 'APPLICATION',
+} as const;
+
 export interface TargetState {
   notation: 'target-state';
   id: string;
   name: string;
-  /** Composition lists are inline; they are timeless on the element file. */
   capabilities?: string[];
   processes?: string[];
   applications?: string[];
   description?: string;
   link?: 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;
 }

package/src/target-state/validate.ts

@@ -1,64 +1,94 @@
-// TARGET_STATE validator — methodology notations/ELEMENT_PRIMITIVES.md §7.17.
+// TARGET_STATE validator — methodology notations/ELEMENT_PRIMITIVES.md §7.18.
 //
-// Implements TARGET_STATE-001..002. Goal-satisfaction lives on the
-// `target_state_satisfies_goal` REL kind (elements/17-relations.md §3) and is
-// never inline here; a `goals:` field on a TARGET_STATE is flagged.
+// Codes:
+//   TSTATE-001 — shape / id grammar / required envelope fields.
+//   TSTATE-002 — composition list entry malformed or wrong TYPE.
+//   TSTATE-003 — forbidden inline `goals` field — TARGET_STATE → GOAL
+//                satisfaction is a `target_state_satisfies_goal` REL
+//                (elements/17-relations.md §3), never inline here.
+//
+// CAPABILITY ids use the V/H sub-grammar (IDS_AND_REFERENCES.md §2): the
+// integer-terminal isCanonicalId would reject them. So the composition entry
+// check accepts any id whose TYPE prefix matches; existence is enforced only
+// when a `CanonCatalog` is supplied.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { TARGET_STATE_COMPOSITION_FIELDS } from './types.js';
 
-import type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
-import { typeOfId } from '../typed-id.js';
-import { validateElementEnvelope } from '../element-envelope.js';
+export interface TargetStateValidateOptions {
+  /** When provided, TSTATE-002 enforces that each composition id is admitted. */
+  catalog?: CanonCatalog;
+}
 
-/** Composition fields and the TYPE each entry must carry. */
-const COMPOSITION_TYPES = {
-  capabilities: 'CAPABILITY',
-  processes: 'PROCESS',
-  applications: 'APPLICATION',
-} as const;
+const REQUIRED_STRING_FIELDS = [
+  'name', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
 
-export function validateTargetState(input: unknown): ValidationResult {
+export function validateTargetState(input: unknown, options: TargetStateValidateOptions = {}): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
-  const { record, errors: envErrors } = validateElementEnvelope(input, {
-    notation: 'target-state',
-    idType: 'TARGET_STATE',
-    code: 'TARGET_STATE-001',
-  });
-  errors.push(...envErrors);
-  if (!record) return { valid: false, errors, warnings };
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'TSTATE-001', message: 'TargetState must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const t = input as Record<string, unknown>;
+
+  // TSTATE-001 — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(t.id, 'TARGET_STATE')) {
+    errors.push({ code: 'TSTATE-001', message: `id "${String(t.id)}" must match TARGET_STATE-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (t.notation !== 'target-state') {
+    errors.push({ code: 'TSTATE-001', message: 'notation must be the fixed value "target-state".', path: 'notation' });
+  }
+  if (t.zone !== undefined && t.zone !== 'canon') {
+    errors.push({ code: 'TSTATE-001', message: 'zone must be "canon" for a TARGET_STATE.', path: 'zone' });
+  } else if (t.zone === undefined) {
+    errors.push({ code: 'TSTATE-001', message: 'zone is required.', path: 'zone' });
+  }
+  for (const field of REQUIRED_STRING_FIELDS) {
+    const v = t[field];
+    if (typeof v !== 'string' || v.trim() === '') {
+      errors.push({ code: 'TSTATE-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (t.gate_checks === null || typeof t.gate_checks !== 'object') {
+    errors.push({ code: 'TSTATE-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in t) || !(typeof t.valid_to === 'string' || t.valid_to === null)) {
+    errors.push({ code: 'TSTATE-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
 
-  // TARGET_STATE-002 — composition entries must carry the right TYPE prefix.
-  for (const [field, expectedType] of Object.entries(COMPOSITION_TYPES)) {
-    const value = record[field];
-    if (value === undefined) continue;
-    if (!Array.isArray(value)) {
-      errors.push({
-        code: 'TARGET_STATE-002',
-        message: `${field} must be a list of ${expectedType} typed IDs.`,
-        path: field,
-      });
+  // TSTATE-002 — composition list TYPE checks.
+  for (const [field, expectedType] of Object.entries(TARGET_STATE_COMPOSITION_FIELDS)) {
+    const list = t[field];
+    if (list === undefined) continue;
+    if (!Array.isArray(list)) {
+      errors.push({ code: 'TSTATE-001', message: `${field} must be a list of typed IDs.`, path: field });
       continue;
     }
-    value.forEach((ref, i) => {
-      // CAPABILITY uses a V/H terminal (e.g. CAPABILITY-V1.2) rather than a
-      // plain integer; the prefix-TYPE gate is what this validator enforces,
-      // and the V/H grammar is owned by the capability-map module.
-      if (typeOfId(ref) !== expectedType) {
-        errors.push({
-          code: 'TARGET_STATE-002',
-          message: `${field}[${i}] "${String(ref)}" must be a ${expectedType} typed ID.`,
-          path: `${field}[${i}]`,
-        });
+    list.forEach((ref, i) => {
+      const refType = typeOfId(ref);
+      if (!refType) {
+        errors.push({ code: 'TSTATE-002', message: `${field}[${i}] "${String(ref)}" is not a resolvable typed ID.`, path: `${field}[${i}]` });
+        return;
+      }
+      if (refType !== expectedType) {
+        errors.push({ code: 'TSTATE-002', message: `${field}[${i}] TYPE "${refType}" must be ${expectedType}.`, path: `${field}[${i}]` });
+        return;
+      }
+      if (options.catalog && options.catalog.typeOf(ref as string) === undefined) {
+        errors.push({ code: 'TSTATE-002', message: `${field}[${i}] "${String(ref)}" does not resolve to an admitted ${expectedType}.`, path: `${field}[${i}]` });
       }
     });
   }
 
-  // TARGET_STATE-001 — `goals:` is not an inline field on this element. Goal
-  // satisfaction is a target_state_satisfies_goal REL (§7.17).
-  if ('goals' in record) {
+  // TSTATE-003 — `goals` is not an inline field on TARGET_STATE.
+  if ('goals' in t) {
     errors.push({
-      code: 'TARGET_STATE-001',
-      message: 'goals is not an inline field on TARGET_STATE — use a target_state_satisfies_goal REL.',
+      code: 'TSTATE-003',
+      message: 'goals must not be inline on a TARGET_STATE — TARGET_STATE → GOAL satisfaction is a target_state_satisfies_goal REL.',
       path: 'goals',
     });
   }

package/src/theme/index.ts

@@ -1,4 +1,4 @@
-export type { AdaptiveTokens } from './tokens.js';
-export { BRAND, FUNCTIONAL, LAYER_COLORS, LEVEL_COLORS, MATURITY_COLORS, STRUCTURAL, TYPOGRAPHY, CSS_VAR, getBaseResetCss } from './tokens.js';
-export type { ThemeId } from './themes.js';
-export { generateWebviewCss, generateSvgEmbedCss } from './themes.js';
+export type { AdaptiveTokens } from './tokens.js';
+export { BRAND, FUNCTIONAL, LAYER_COLORS, LEVEL_COLORS, MATURITY_COLORS, STRUCTURAL, TYPOGRAPHY, CSS_VAR, getBaseResetCss } from './tokens.js';
+export type { ThemeId } from './themes.js';
+export { generateWebviewCss, generateSvgEmbedCss } from './themes.js';