@transitrix/diagrams 1.0.0

package/src/activity-card/types.ts

@@ -0,0 +1,237 @@
+// Activity Card notation — single-project narrative view.
+//
+// Spec: transitrix/methodology `notations/views/18-activity-card.md` (v0.1).
+// Epic vkgeorgia/strategy#97, Studio track #134.
+//
+// The Activity Card is the first MULTI-DOCUMENT Studio notation. The card
+// YAML itself holds only `id`, `project` (an Activity ID), `description`,
+// and `milestones[]`. Everything painted on the card — the project name,
+// dates, motivation chain (Factors → Goals → Changes), and child activities
+// — is pulled BY REFERENCE at view time from the canonical ELEMENT and
+// RELATION store (`canon/elements/**`, `canon/relations/**`), never from
+// other view documents. This honours the view-purity invariant: a view is a
+// projection over elements + relations (methodology ELEMENT_PRIMITIVES.md §1).
+// See `resolver.ts`.
+//
+// This file declares two model layers:
+//   1. the RAW card document (what the YAML parses into), and
+//   2. the ASSEMBLED card view-model (what the resolver produces and the
+//      layout consumes).
+
+import type {
+  ValidationError as SharedValidationError,
+  ValidationWarning as SharedValidationWarning,
+  ValidationResult as SharedValidationResult,
+} from '../validation-types.js';
+
+// Keep PREFIXED aliases consistent with the other notation modules so
+// external consumers can name the activity-card result types directly.
+export type ActivityCardValidationError = SharedValidationError;
+export type ActivityCardValidationWarning = SharedValidationWarning;
+export type ActivityCardValidationResult = SharedValidationResult;
+
+// ── Raw card document (the `*.activity-card.transitrix.yaml` shape) ──────────
+
+export interface RawMilestone {
+  id: string;
+  name: string;
+  /** Quoted ISO 8601 date (YYYY-MM-DD) when the milestone is reached. */
+  date: string;
+  description?: string;
+  /** CHANGE-… IDs; each must be a subset of the project Activity's delivers_changes. */
+  delivers_changes?: string[];
+}
+
+export interface ActivityCardBlock {
+  id: string;
+  /** Canonical ID of the referenced project Activity (ACTIVITY-…). */
+  project: string;
+  description?: string;
+  milestones?: RawMilestone[];
+}
+
+export interface ActivityCardDoc {
+  notation: string;
+  spec_version?: string;
+  activity_card: ActivityCardBlock;
+}
+
+// ── Canon sources consumed by the resolver ──────────────────────────────────
+//
+// View-purity invariant (methodology ELEMENT_PRIMITIVES.md §1): a view is a
+// projection over the canonical ELEMENTS + RELATIONS, never over other view
+// documents. The Activity Card therefore resolves its project, child
+// activities, and motivation chain from the canon element store
+// (`canon/elements/**` — one ACTIVITY / FACTOR / GOAL / CHANGE element per
+// file, each a `notation: <type>` document carrying its own `id`) and the
+// relation store (`canon/relations/**` — `notation: relation` files), NOT from
+// sibling `*.activities.*` / `*.fgca.*` view documents.
+//
+// The resolver is filesystem-free: the extension reads + parses the element and
+// relation files and hands the parsed objects in. We model them as `unknown[]`
+// at the boundary and narrow defensively inside the resolver, so a malformed
+// element / relation degrades to a resolution error rather than a crash.
+
+export interface ActivityCardSources {
+  /** Parsed canon element documents — one element per file (`notation: activity|factor|goal|change|…`). */
+  elements: unknown[];
+  /** Parsed canon relation documents (`notation: relation`). */
+  relations: unknown[];
+}
+
+// ── Assembled card view-model (resolver output → layout input) ───────────────
+
+export interface ResolvedProject {
+  id: string;
+  name: string;
+  /** Full description from the Activity (the card's own `description` is separate). */
+  description?: string;
+  /** Lifecycle: decision-to-initiate date (CONTRACT.md §7). */
+  valid_from?: string;
+  /** Lifecycle: when the project ceased effect, or undefined if active. */
+  valid_to?: string;
+  /** Planned work range. */
+  start_date?: string;
+  end_date?: string;
+}
+
+export interface ResolvedMilestone {
+  id: string;
+  name: string;
+  date: string;
+  description?: string;
+  /** CHANGE-… IDs this milestone delivers (subset of the project's). */
+  deliversChanges: string[];
+}
+
+export interface ResolvedFactor {
+  id: string;
+  name: string;
+}
+
+export interface ResolvedGoal {
+  id: string;
+  name: string;
+  /** FACTOR-… IDs that motivate this goal (canonical `goal.factors`). */
+  factorIds: string[];
+}
+
+export interface ResolvedChange {
+  id: string;
+  name: string;
+  /** GOAL-… IDs this change advances (canonical `change.goals`). */
+  goalIds: string[];
+}
+
+/** Motivation chain: Factors → Goals → Changes, scoped to the project. */
+export interface ResolvedMotivation {
+  factors: ResolvedFactor[];
+  goals: ResolvedGoal[];
+  changes: ResolvedChange[];
+}
+
+export interface ResolvedChildActivity {
+  id: string;
+  name: string;
+  activity_type?: string;
+  start_date?: string;
+  end_date?: string;
+  owner?: string;
+}
+
+export interface ResolvedActivityCard {
+  cardId: string;
+  /** The card's own executive-summary description (distinct from the project's). */
+  cardDescription?: string;
+  project: ResolvedProject;
+  /** Sorted ascending by `date`. */
+  milestones: ResolvedMilestone[];
+  motivation: ResolvedMotivation;
+  /** Activities whose `parent` = the project Activity id. */
+  childActivities: ResolvedChildActivity[];
+}
+
+// ── Layout geometry (pure; the preview turns this into SVG) ───────────────────
+
+import type { LayoutBounds } from '../geometry.js';
+export type { LayoutBounds };
+
+/** A boxed value-pair shown in the dates band. */
+export interface DateField {
+  label: string;
+  value: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** One milestone marker on the timeline. */
+export interface MilestoneMarker {
+  id: string;
+  name: string;
+  date: string;
+  /** ArchiMate class label appended by the renderer (§5.1). */
+  archimateClass: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** One node in a motivation-chain column. */
+export interface ChainNode {
+  id: string;
+  name: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** An edge between two chain nodes (factor→goal or goal→change). */
+export interface ChainEdge {
+  sourceId: string;
+  targetId: string;
+}
+
+export interface ChildActivityRow {
+  id: string;
+  name: string;
+  /** ArchiMate class label appended by the renderer (§5.1). */
+  archimateClass: string;
+  meta: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface SectionHeader {
+  label: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface ActivityCardLayoutOptions {
+  /** Outer card width (px). */
+  cardWidth?: number;
+  /** Horizontal gap (px) between the three motivation-chain columns. */
+  columnGap?: number;
+  /** Vertical gap (px) between stacked rows within a section. */
+  rowGap?: number;
+}
+
+export interface ActivityCardLayout {
+  bounds: LayoutBounds;
+  title: { name: string; x: number; y: number };
+  dateFields: DateField[];
+  sectionHeaders: SectionHeader[];
+  milestones: MilestoneMarker[];
+  /** Three columns of the motivation chain, in F→G→C order. */
+  chainColumns: { factors: ChainNode[]; goals: ChainNode[]; changes: ChainNode[] };
+  chainEdges: ChainEdge[];
+  childActivities: ChildActivityRow[];
+}

package/src/activity-card/validate.ts

@@ -0,0 +1,158 @@
+// Activity Card — document-local structural validation.
+//
+// This validator checks only what can be known from the card document ALONE:
+// the header, the `activity_card` block shape, the project-reference grammar
+// (PC-001's "missing or malformed" half), and each milestone's shape.
+//
+// The cross-document rules — PC-001 "does not resolve", PC-002
+// (activity_type), PC-003 (milestone changes ⊆ project changes), PC-004
+// (milestone date within the project lifecycle window) and the LIFECYCLE-*
+// checks — require the sibling `*.activities.*` / `*.fgca.*` documents and so
+// live in `resolver.ts`. The preview merges both result sets.
+//
+// Codes:
+//   AC-001   document structure (root object, `activity_card` block)
+//   AC-002   `activity_card.id` grammar
+//   AC-003   milestone structure (missing id / name / date)
+//   AC-004   milestone id grammar / duplicate
+//   AC-005   milestone date format
+//   AC-006   milestone `delivers_changes` shape / grammar
+//   HDR-001  missing `notation`           (CONTRACT.md §2)
+//   HDR-002  wrong `notation`             (CONTRACT.md §2)
+//   PC-001   `project` missing or malformed (the document-local half; the
+//            "does not resolve" half is emitted by the resolver)
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+export type { ValidationError, ValidationWarning, ValidationResult };
+
+const ACTIVITY_CARD_ID_RE = /^ACTIVITY_CARD(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const ACTIVITY_ID_RE = /^ACTIVITY(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const MILESTONE_ID_RE = /^MILESTONE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const CHANGE_ID_RE = /^CHANGE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+export function validateActivityCard(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'AC-001', message: 'document root is not an object' }], warnings };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  // ── Header (CONTRACT.md §2) ────────────────────────────────────────────────
+  if (!('notation' in raw)) {
+    errors.push({ code: 'HDR-001', message: 'notation field is required' });
+  } else if (raw['notation'] !== 'activity-card') {
+    errors.push({
+      code: 'HDR-002',
+      message: `notation must be "activity-card", got "${String(raw['notation'])}"`,
+    });
+  }
+
+  // ── activity_card block ─────────────────────────────────────────────────────
+  const block = raw['activity_card'];
+  if (!block || typeof block !== 'object' || Array.isArray(block)) {
+    errors.push({ code: 'AC-001', message: 'Missing required root key: activity_card (object)' });
+    return { valid: false, errors, warnings };
+  }
+  const card = block as Record<string, unknown>;
+
+  if (!isNonEmptyString(card['id'])) {
+    errors.push({ code: 'AC-002', message: 'activity_card.id is required' });
+  } else if (!ACTIVITY_CARD_ID_RE.test(card['id'])) {
+    errors.push({
+      code: 'AC-002',
+      message: `activity_card.id "${card['id']}" must match ACTIVITY_CARD-[<middle>-]<INTEGER>`,
+    });
+  }
+
+  // PC-001 (document-local half): project present + well-formed.
+  if (!isNonEmptyString(card['project'])) {
+    errors.push({ code: 'PC-001', message: 'activity_card.project is required (an ACTIVITY-… id)' });
+  } else if (!ACTIVITY_ID_RE.test(card['project'])) {
+    errors.push({
+      code: 'PC-001',
+      message: `activity_card.project "${card['project']}" is malformed; must match ACTIVITY-[<middle>-]<INTEGER>`,
+    });
+  }
+
+  if (card['description'] !== undefined && typeof card['description'] !== 'string') {
+    errors.push({ code: 'AC-001', message: 'activity_card.description must be a string' });
+  }
+
+  // ── milestones[] (optional) ─────────────────────────────────────────────────
+  const milestonesRaw = card['milestones'];
+  if (milestonesRaw !== undefined) {
+    if (!Array.isArray(milestonesRaw)) {
+      errors.push({ code: 'AC-003', message: 'activity_card.milestones must be an array', path: 'milestones' });
+    } else {
+      const seenIds = new Set<string>();
+      milestonesRaw.forEach((el, i) => {
+        const p = `milestones[${i}]`;
+        if (!el || typeof el !== 'object' || Array.isArray(el)) {
+          errors.push({ code: 'AC-003', message: `${p} must be an object`, path: p });
+          return;
+        }
+        const m = el as Record<string, unknown>;
+
+        if (!isNonEmptyString(m['id'])) {
+          errors.push({ code: 'AC-003', message: `${p}.id is required`, path: p });
+        } else {
+          const mid = m['id'].trim();
+          if (!MILESTONE_ID_RE.test(mid)) {
+            errors.push({ code: 'AC-004', message: `${p}.id "${mid}" must match MILESTONE-[<middle>-]<INTEGER>`, path: p });
+          }
+          if (seenIds.has(mid)) {
+            errors.push({ code: 'AC-004', message: `Duplicate milestone id "${mid}"`, path: p });
+          } else {
+            seenIds.add(mid);
+          }
+        }
+
+        if (!isNonEmptyString(m['name'])) {
+          errors.push({ code: 'AC-003', message: `${p}.name is required`, path: p });
+        }
+
+        if (!isNonEmptyString(m['date'])) {
+          errors.push({ code: 'AC-003', message: `${p}.date is required`, path: p });
+        } else if (!DATE_RE.test(m['date'])) {
+          errors.push({
+            code: 'AC-005',
+            message: `${p}.date "${m['date']}" must be a quoted ISO 8601 date (YYYY-MM-DD)`,
+            path: p,
+          });
+        }
+
+        if (m['description'] !== undefined && typeof m['description'] !== 'string') {
+          errors.push({ code: 'AC-003', message: `${p}.description must be a string`, path: p });
+        }
+
+        const dc = m['delivers_changes'];
+        if (dc !== undefined) {
+          if (!Array.isArray(dc)) {
+            errors.push({ code: 'AC-006', message: `${p}.delivers_changes must be an array of CHANGE-… ids`, path: p });
+          } else {
+            dc.forEach((c) => {
+              if (typeof c !== 'string' || !CHANGE_ID_RE.test(c)) {
+                errors.push({
+                  code: 'AC-006',
+                  message: `${p}.delivers_changes[] entry "${String(c)}" must match CHANGE-[<middle>-]<INTEGER>`,
+                  path: p,
+                });
+              }
+            });
+          }
+        }
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

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

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { validateActor } from '../validate.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'actor',
+    id: 'ACTOR-PERSON-1',
+    name: 'Alex Doe (example)',
+    type: 'person',
+    description: 'Synthetic person actor demonstrating identity-vs-engagement.',
+    contact: 'alex.doe@example.test',
+    zone: 'canon',
+    admitted_at: '2026-05-29',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2025-03-01',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown): string[] => validateActor(input).errors.map(e => e.code);
+
+describe('validateActor — positive', () => {
+  it('accepts the worked-example ACTOR-PERSON-1', () => {
+    const r = validateActor(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('accepts each permitted type', () => {
+    for (const t of ['person', 'business_unit', 'system']) {
+      expect(validateActor({ ...valid(), type: t }).valid).toBe(true);
+    }
+  });
+});
+
+describe('validateActor — ACTOR-001 (envelope / shape)', () => {
+  it('flags a non-object', () => {
+    expect(codes(null)).toEqual(['ACTOR-001']);
+  });
+
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'agent' })).toContain('ACTOR-001');
+  });
+
+  it('flags an id with the wrong TYPE prefix', () => {
+    expect(codes({ ...valid(), id: 'ROLE-CEO-1' })).toContain('ACTOR-001');
+  });
+
+  it('flags missing name', () => {
+    const r = valid();
+    delete r.name;
+    expect(codes(r)).toContain('ACTOR-001');
+  });
+});
+
+describe('validateActor — ACTOR-002 (identity discriminator)', () => {
+  it('flags a missing type (the identity discriminator is required)', () => {
+    const r = valid();
+    delete r.type;
+    expect(codes(r)).toContain('ACTOR-002');
+  });
+
+  it('flags a type outside person/business_unit/system', () => {
+    expect(codes({ ...valid(), type: 'employee' })).toContain('ACTOR-002');
+  });
+});

package/src/actor/index.ts

@@ -0,0 +1,3 @@
+export type { Actor, ActorType } from './types.js';
+export { ACTOR_TYPES } from './types.js';
+export { validateActor } from './validate.js';

package/src/actor/types.ts

@@ -0,0 +1,29 @@
+// ACTOR — business-layer identity primitive (ArchiMate Business Actor).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.10 +
+//         notations/elements/19-actors.md + envelope §3.
+
+import type { GateChecks } from '../requirement/types.js';
+
+/** Identity discriminator — what kind of actor (person, business_unit, system). */
+export type ActorType = 'person' | 'business_unit' | 'system';
+
+export const ACTOR_TYPES = ['person', 'business_unit', 'system'] as const;
+
+export interface Actor {
+  notation: 'actor';
+  id: string;
+  name: string;
+  /** Required identity discriminator. */
+  type: ActorType;
+  description?: string;
+  contact?: string;
+  external_ref?: string;
+
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/actor/validate.ts

@@ -0,0 +1,38 @@
+// ACTOR validator — methodology notations/ELEMENT_PRIMITIVES.md §7.10 +
+// notations/elements/19-actors.md.
+//
+// Implements ACTOR-001..002. Employment / role-assignment / unit-parent
+// relations live in first-class time-aware REL files (elements/17-relations.md
+// §3) and are out of scope for this single-artefact validator.
+
+import type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
+import { validateElementEnvelope } from '../element-envelope.js';
+import { ACTOR_TYPES } from './types.js';
+
+export function validateActor(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  const { record, errors: envErrors } = validateElementEnvelope(input, {
+    notation: 'actor',
+    idType: 'ACTOR',
+    code: 'ACTOR-001',
+  });
+  errors.push(...envErrors);
+  if (!record) return { valid: false, errors, warnings };
+
+  // ACTOR-002 — `type` is required (the identity discriminator) and must be
+  // one of person / business_unit / system. The split with the former UNIT /
+  // EMPLOYEE TYPEs (Actors decision, 2026-05-29; §7.11) hinges on this.
+  if (record.type === undefined || record.type === null) {
+    errors.push({ code: 'ACTOR-002', message: 'type is required (person | business_unit | system).', path: 'type' });
+  } else if (!ACTOR_TYPES.includes(record.type as never)) {
+    errors.push({
+      code: 'ACTOR-002',
+      message: `type "${String(record.type)}" must be one of ${ACTOR_TYPES.join(', ')}.`,
+      path: 'type',
+    });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}