@transitrix/diagrams 1.0.0 → 1.1.0

package/src/factor/validate.ts

@@ -1,70 +1,96 @@
 // FACTOR validator — methodology notations/ELEMENT_PRIMITIVES.md §7.1.
 //
-// Implements FACTOR-001..003. Cross-cutting HDR-/LIFECYCLE-/policy rules
-// (CONTRACT.md §8) are owned elsewhere and out of scope for this
-// single-artefact validator.
+// Codes:
+//   FACTOR-001 — shape / id grammar / required envelope fields.
+//   FACTOR-002 — `type` outside {external, internal}.
+//   FACTOR-003 — `category` outside PESTLE vocabulary, or PESTLE applied to a
+//                non-external factor (PESTLE applies only to external drivers).
+//   FACTOR-004 — `references_constraint` entry malformed or wrong TYPE.
+//
+// `references_constraint` existence (resolves to an admitted artefact) runs
+// only when a `CanonCatalog` is supplied; the prefix-TYPE check runs either way.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { FACTOR_PESTLE_CATEGORIES } from './types.js';
+
+export interface FactorValidateOptions {
+  /** When provided, enforces that each `references_constraint` id is admitted. */
+  catalog?: CanonCatalog;
+}
+
+const REQUIRED_STRING_FIELDS = [
+  'name', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
 
-import type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
-import { typeOfId } from '../typed-id.js';
-import { validateElementEnvelope } from '../element-envelope.js';
-import { FACTOR_CATEGORIES, FACTOR_TYPES } from './types.js';
+const PESTLE: readonly string[] = FACTOR_PESTLE_CATEGORIES;
 
-export function validateFactor(input: unknown): ValidationResult {
+export function validateFactor(input: unknown, options: FactorValidateOptions = {}): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
-  const { record, errors: envErrors } = validateElementEnvelope(input, {
-    notation: 'factor',
-    idType: 'FACTOR',
-    code: 'FACTOR-001',
-  });
-  errors.push(...envErrors);
-  if (!record) return { valid: false, errors, warnings };
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'FACTOR-001', message: 'Factor must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const f = input as Record<string, unknown>;
 
-  // FACTOR-002 — type subtype enum (optional field).
-  if (record.type !== undefined && !FACTOR_TYPES.includes(record.type as never)) {
-    errors.push({
-      code: 'FACTOR-002',
-      message: `type "${String(record.type)}" must be one of ${FACTOR_TYPES.join(', ')}.`,
-      path: 'type',
-    });
+  // FACTOR-001 — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(f.id, 'FACTOR')) {
+    errors.push({ code: 'FACTOR-001', message: `id "${String(f.id)}" must match FACTOR-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (f.notation !== 'driver') {
+    errors.push({ code: 'FACTOR-001', message: 'notation must be the fixed value "driver".', path: 'notation' });
+  }
+  if (f.zone !== undefined && f.zone !== 'canon') {
+    errors.push({ code: 'FACTOR-001', message: 'zone must be "canon" for a FACTOR.', path: 'zone' });
+  } else if (f.zone === undefined) {
+    errors.push({ code: 'FACTOR-001', message: 'zone is required.', path: 'zone' });
+  }
+  for (const field of REQUIRED_STRING_FIELDS) {
+    const v = f[field];
+    if (typeof v !== 'string' || v.trim() === '') {
+      errors.push({ code: 'FACTOR-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (f.gate_checks === null || typeof f.gate_checks !== 'object') {
+    errors.push({ code: 'FACTOR-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in f) || !(typeof f.valid_to === 'string' || f.valid_to === null)) {
+    errors.push({ code: 'FACTOR-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
   }
 
-  // FACTOR-003 — PESTLE category enum on external factors; warn on internal.
-  if (record.category !== undefined) {
-    if (!FACTOR_CATEGORIES.includes(record.category as never)) {
-      errors.push({
-        code: 'FACTOR-003',
-        message: `category "${String(record.category)}" must be a PESTLE class (${FACTOR_CATEGORIES.join(', ')}).`,
-        path: 'category',
-      });
-    } else if (record.type === 'internal') {
-      // §7.1: "Omit on internal factors — PESTLE does not apply."
-      warnings.push({
-        code: 'FACTOR-003',
-        message: 'category is set on an internal factor; PESTLE applies to external drivers only.',
-        path: 'category',
-      });
+  // FACTOR-002 — type enum (optional field; only check when present).
+  if (f.type !== undefined && f.type !== 'external' && f.type !== 'internal') {
+    errors.push({ code: 'FACTOR-002', message: `type "${String(f.type)}" must be one of external, internal.`, path: 'type' });
+  }
+
+  // FACTOR-003 — category PESTLE vocabulary + external-only constraint.
+  if (f.category !== undefined) {
+    if (typeof f.category !== 'string' || !PESTLE.includes(f.category)) {
+      errors.push({ code: 'FACTOR-003', message: `category "${String(f.category)}" must be one of ${PESTLE.join(', ')}.`, path: 'category' });
+    } else if (f.type === 'internal') {
+      errors.push({ code: 'FACTOR-003', message: 'category is PESTLE — applies only to external factors; omit on internal factors.', path: 'category' });
     }
   }
 
-  // FACTOR-001 — references_constraint shape + TYPE on each entry.
-  if (record.references_constraint !== undefined) {
-    if (!Array.isArray(record.references_constraint)) {
-      errors.push({
-        code: 'FACTOR-001',
-        message: 'references_constraint must be a list of typed CONSTRAINT IDs.',
-        path: 'references_constraint',
-      });
+  // FACTOR-004 — references_constraint refs.
+  if (f.references_constraint !== undefined) {
+    if (!Array.isArray(f.references_constraint)) {
+      errors.push({ code: 'FACTOR-001', message: 'references_constraint must be a list of typed IDs.', path: 'references_constraint' });
     } else {
-      record.references_constraint.forEach((ref, i) => {
+      f.references_constraint.forEach((ref, i) => {
         const type = typeOfId(ref);
+        if (!type) {
+          errors.push({ code: 'FACTOR-004', message: `references_constraint[${i}] "${String(ref)}" is not a resolvable typed ID.`, path: `references_constraint[${i}]` });
+          return;
+        }
         if (type !== 'CONSTRAINT') {
-          errors.push({
-            code: 'FACTOR-001',
-            message: `references_constraint[${i}] "${String(ref)}" must be a CONSTRAINT typed ID.`,
-            path: `references_constraint[${i}]`,
-          });
+          errors.push({ code: 'FACTOR-004', message: `references_constraint[${i}] TYPE "${type}" must be CONSTRAINT.`, path: `references_constraint[${i}]` });
+          return;
+        }
+        if (options.catalog && options.catalog.typeOf(ref as string) === undefined) {
+          errors.push({ code: 'FACTOR-004', message: `references_constraint[${i}] "${String(ref)}" does not resolve to an admitted artefact.`, path: `references_constraint[${i}]` });
         }
       });
     }

package/src/fgca/__tests__/chain-table.test.ts

@@ -1,172 +1,172 @@
-import { describe, it, expect } from 'vitest';
-import { buildChainTable, type ChainTable, type ChainColumn } from '../chain-table.js';
-import type { FGCAPreviewDoc } from '../preview-layout.js';
-
-// Renders a ChainTable to a compact text grid for readable assertions. Each
-// cell shows "label×rowSpan" (×1 omitted); a position covered by a span above
-// shows "·".
-function asGrid(t: ChainTable): string[][] {
-  return t.rows.map(row =>
-    row.map(c => {
-      if (c === null) return '·';
-      const label = c.cell ? c.cell.label : '∅';
-      return c.rowSpan > 1 ? `${label}×${c.rowSpan}` : label;
-    }),
-  );
-}
-
-describe('buildChainTable — worked example (FGCA)', () => {
-  // F1 → G1, G2 ; G1 → C1 → A1 ; G2 → C2 → A2, A3
-  const doc: FGCAPreviewDoc = {
-    factors: [{ id: 1, name: 'F1' }],
-    goals: [
-      { id: 10, name: 'G1', factor: [{ id: 1 }] },
-      { id: 11, name: 'G2', factor: [{ id: 1 }] },
-    ],
-    changes: [
-      { id: 20, name: 'C1', goal_id: 10, activity_ids: [30] },
-      { id: 21, name: 'C2', goal_id: 11, activity_ids: [31, 32] },
-    ],
-    activities: [
-      { id: 30, name: 'A1', goal_id: 10 },
-      { id: 31, name: 'A2', goal_id: 11 },
-      { id: 32, name: 'A3', goal_id: 11 },
-    ],
-  };
-
-  it('produces the spec grid with F1 spanning 3 and G2/C2 spanning 2', () => {
-    const t = buildChainTable(doc);
-    expect(t.columns).toEqual<ChainColumn[]>(['factor', 'goal', 'change', 'activity']);
-    expect(asGrid(t)).toEqual([
-      ['F1×3', 'G1', 'C1', 'A1'],
-      ['·', 'G2×2', 'C2×2', 'A2'],
-      ['·', '·', '·', 'A3'],
-    ]);
-  });
-
-  it('orders the merged cells with correct rowSpans on the model', () => {
-    const t = buildChainTable(doc);
-    // Factor cell spans all three rows.
-    expect(t.rows[0][0]).toMatchObject({ rowSpan: 3, cell: { label: 'F1' } });
-    // Covered positions are null (no <td> emitted).
-    expect(t.rows[1][0]).toBeNull();
-    expect(t.rows[2][1]).toBeNull();
-  });
-});
-
-describe('buildChainTable — FGA (no Change column)', () => {
-  // FGA links Goal → Activity directly via activity.goal_id; no changes.
-  const doc: FGCAPreviewDoc = {
-    factors: [{ id: 1, name: 'F1' }],
-    goals: [{ id: 10, name: 'G1', factor: [{ id: 1 }] }],
-    activities: [
-      { id: 30, name: 'A1', goal_id: 10 },
-      { id: 31, name: 'A2', goal_id: 10 },
-    ],
-  };
-
-  it('emits three columns and merges Factor/Goal across the two activities', () => {
-    const t = buildChainTable(doc, { hideChanges: true });
-    expect(t.columns).toEqual<ChainColumn[]>(['factor', 'goal', 'activity']);
-    expect(asGrid(t)).toEqual([
-      ['F1×2', 'G1×2', 'A1'],
-      ['·', '·', 'A2'],
-    ]);
-  });
-});
-
-describe('buildChainTable — missing downstream links (gaps stay visible)', () => {
-  it('shows a factor with no goal, a goal with no change, and a change with no activity', () => {
-    const doc: FGCAPreviewDoc = {
-      factors: [
-        { id: 1, name: 'F1' },
-        { id: 2, name: 'F2' }, // no goals
-      ],
-      goals: [
-        { id: 10, name: 'G1', factor: [{ id: 1 }] }, // no change, no activity
-        { id: 11, name: 'G2', factor: [{ id: 1 }] }, // has a change with no activity
-      ],
-      changes: [{ id: 20, name: 'C1', goal_id: 11, activity_ids: [] }],
-      activities: [],
-    };
-    const t = buildChainTable(doc);
-    expect(asGrid(t)).toEqual([
-      ['F1×2', 'G1', '∅', '∅'],
-      ['·', 'G2', 'C1', '∅'],
-      ['F2', '∅', '∅', '∅'],
-    ]);
-  });
-
-  it('renders a change-less direct goal→activity path with an empty Change cell', () => {
-    const doc: FGCAPreviewDoc = {
-      factors: [{ id: 1, name: 'F1' }],
-      goals: [{ id: 10, name: 'G1', factor: [{ id: 1 }] }],
-      // activity bound straight to the goal, not covered by any change
-      changes: [],
-      activities: [{ id: 30, name: 'A1', goal_id: 10 }],
-    };
-    const t = buildChainTable(doc);
-    expect(asGrid(t)).toEqual([['F1', 'G1', '∅', 'A1']]);
-  });
-});
-
-describe('buildChainTable — orphans (broken refs are warnings, not errors)', () => {
-  it('places a goal with a missing factor in a trailing empty-Factor row', () => {
-    const doc: FGCAPreviewDoc = {
-      factors: [{ id: 1, name: 'F1' }],
-      goals: [
-        { id: 10, name: 'G1', factor: [{ id: 1 }] },
-        { id: 11, name: 'Gx', factor: [{ id: 99 }] }, // factor 99 does not exist
-        { id: 12, name: 'Gy' }, // no factor at all
-      ],
-      changes: [{ id: 20, name: 'C1', goal_id: 10, activity_ids: [30] }],
-      activities: [{ id: 30, name: 'A1', goal_id: 10 }],
-    };
-    const t = buildChainTable(doc);
-    expect(asGrid(t)).toEqual([
-      ['F1', 'G1', 'C1', 'A1'],
-      ['∅×2', 'Gx', '∅', '∅'],
-      ['·', 'Gy', '∅', '∅'],
-    ]);
-  });
-
-  it('surfaces an unlinked activity as a trailing row with empty cells to its left', () => {
-    const doc: FGCAPreviewDoc = {
-      factors: [{ id: 1, name: 'F1' }],
-      goals: [{ id: 10, name: 'G1', factor: [{ id: 1 }] }],
-      changes: [{ id: 20, name: 'C1', goal_id: 10, activity_ids: [30] }],
-      activities: [
-        { id: 30, name: 'A1', goal_id: 10 },
-        { id: 99, name: 'Aorphan' }, // no goal, no change
-      ],
-    };
-    const t = buildChainTable(doc);
-    expect(asGrid(t)).toEqual([
-      ['F1', 'G1', 'C1', 'A1'],
-      ['∅', '∅', '∅', 'Aorphan'],
-    ]);
-  });
-
-  it('surfaces a change whose goal is missing as an empty Factor+Goal row', () => {
-    const doc: FGCAPreviewDoc = {
-      factors: [],
-      goals: [],
-      changes: [{ id: 20, name: 'Cx', goal_id: 999, activity_ids: [30] }],
-      activities: [{ id: 30, name: 'A1' }],
-    };
-    const t = buildChainTable(doc);
-    expect(asGrid(t)).toEqual([['∅', '∅', 'Cx', 'A1']]);
-  });
-});
-
-describe('buildChainTable — name fallback', () => {
-  it('falls back to the id when an element has an empty name', () => {
-    const doc: FGCAPreviewDoc = {
-      factors: [{ id: 7, name: '' }],
-      goals: [],
-      activities: [],
-    };
-    const t = buildChainTable(doc);
-    expect(t.rows[0][0]?.cell?.label).toBe('7');
-  });
-});
+import { describe, it, expect } from 'vitest';
+import { buildChainTable, type ChainTable, type ChainColumn } from '../chain-table.js';
+import type { FGCAPreviewDoc } from '../preview-layout.js';
+
+// Renders a ChainTable to a compact text grid for readable assertions. Each
+// cell shows "label×rowSpan" (×1 omitted); a position covered by a span above
+// shows "·".
+function asGrid(t: ChainTable): string[][] {
+  return t.rows.map(row =>
+    row.map(c => {
+      if (c === null) return '·';
+      const label = c.cell ? c.cell.label : '∅';
+      return c.rowSpan > 1 ? `${label}×${c.rowSpan}` : label;
+    }),
+  );
+}
+
+describe('buildChainTable — worked example (FGCA)', () => {
+  // F1 → G1, G2 ; G1 → C1 → A1 ; G2 → C2 → A2, A3
+  const doc: FGCAPreviewDoc = {
+    factors: [{ id: 1, name: 'F1' }],
+    goals: [
+      { id: 10, name: 'G1', factor: [{ id: 1 }] },
+      { id: 11, name: 'G2', factor: [{ id: 1 }] },
+    ],
+    changes: [
+      { id: 20, name: 'C1', goal_id: 10, activity_ids: [30] },
+      { id: 21, name: 'C2', goal_id: 11, activity_ids: [31, 32] },
+    ],
+    activities: [
+      { id: 30, name: 'A1', goal_id: 10 },
+      { id: 31, name: 'A2', goal_id: 11 },
+      { id: 32, name: 'A3', goal_id: 11 },
+    ],
+  };
+
+  it('produces the spec grid with F1 spanning 3 and G2/C2 spanning 2', () => {
+    const t = buildChainTable(doc);
+    expect(t.columns).toEqual<ChainColumn[]>(['driver', 'goal', 'change', 'activity']);
+    expect(asGrid(t)).toEqual([
+      ['F1×3', 'G1', 'C1', 'A1'],
+      ['·', 'G2×2', 'C2×2', 'A2'],
+      ['·', '·', '·', 'A3'],
+    ]);
+  });
+
+  it('orders the merged cells with correct rowSpans on the model', () => {
+    const t = buildChainTable(doc);
+    // Factor cell spans all three rows.
+    expect(t.rows[0][0]).toMatchObject({ rowSpan: 3, cell: { label: 'F1' } });
+    // Covered positions are null (no <td> emitted).
+    expect(t.rows[1][0]).toBeNull();
+    expect(t.rows[2][1]).toBeNull();
+  });
+});
+
+describe('buildChainTable — FGA (no Change column)', () => {
+  // FGA links Goal → Activity directly via activity.goal_id; no changes.
+  const doc: FGCAPreviewDoc = {
+    factors: [{ id: 1, name: 'F1' }],
+    goals: [{ id: 10, name: 'G1', factor: [{ id: 1 }] }],
+    activities: [
+      { id: 30, name: 'A1', goal_id: 10 },
+      { id: 31, name: 'A2', goal_id: 10 },
+    ],
+  };
+
+  it('emits three columns and merges Factor/Goal across the two activities', () => {
+    const t = buildChainTable(doc, { hideChanges: true });
+    expect(t.columns).toEqual<ChainColumn[]>(['driver', 'goal', 'activity']);
+    expect(asGrid(t)).toEqual([
+      ['F1×2', 'G1×2', 'A1'],
+      ['·', '·', 'A2'],
+    ]);
+  });
+});
+
+describe('buildChainTable — missing downstream links (gaps stay visible)', () => {
+  it('shows a factor with no goal, a goal with no change, and a change with no activity', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [
+        { id: 1, name: 'F1' },
+        { id: 2, name: 'F2' }, // no goals
+      ],
+      goals: [
+        { id: 10, name: 'G1', factor: [{ id: 1 }] }, // no change, no activity
+        { id: 11, name: 'G2', factor: [{ id: 1 }] }, // has a change with no activity
+      ],
+      changes: [{ id: 20, name: 'C1', goal_id: 11, activity_ids: [] }],
+      activities: [],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([
+      ['F1×2', 'G1', '∅', '∅'],
+      ['·', 'G2', 'C1', '∅'],
+      ['F2', '∅', '∅', '∅'],
+    ]);
+  });
+
+  it('renders a change-less direct goal→activity path with an empty Change cell', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [{ id: 1, name: 'F1' }],
+      goals: [{ id: 10, name: 'G1', factor: [{ id: 1 }] }],
+      // activity bound straight to the goal, not covered by any change
+      changes: [],
+      activities: [{ id: 30, name: 'A1', goal_id: 10 }],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([['F1', 'G1', '∅', 'A1']]);
+  });
+});
+
+describe('buildChainTable — orphans (broken refs are warnings, not errors)', () => {
+  it('places a goal with a missing factor in a trailing empty-Factor row', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [{ id: 1, name: 'F1' }],
+      goals: [
+        { id: 10, name: 'G1', factor: [{ id: 1 }] },
+        { id: 11, name: 'Gx', factor: [{ id: 99 }] }, // factor 99 does not exist
+        { id: 12, name: 'Gy' }, // no factor at all
+      ],
+      changes: [{ id: 20, name: 'C1', goal_id: 10, activity_ids: [30] }],
+      activities: [{ id: 30, name: 'A1', goal_id: 10 }],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([
+      ['F1', 'G1', 'C1', 'A1'],
+      ['∅×2', 'Gx', '∅', '∅'],
+      ['·', 'Gy', '∅', '∅'],
+    ]);
+  });
+
+  it('surfaces an unlinked activity as a trailing row with empty cells to its left', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [{ id: 1, name: 'F1' }],
+      goals: [{ id: 10, name: 'G1', factor: [{ id: 1 }] }],
+      changes: [{ id: 20, name: 'C1', goal_id: 10, activity_ids: [30] }],
+      activities: [
+        { id: 30, name: 'A1', goal_id: 10 },
+        { id: 99, name: 'Aorphan' }, // no goal, no change
+      ],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([
+      ['F1', 'G1', 'C1', 'A1'],
+      ['∅', '∅', '∅', 'Aorphan'],
+    ]);
+  });
+
+  it('surfaces a change whose goal is missing as an empty Factor+Goal row', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [],
+      goals: [],
+      changes: [{ id: 20, name: 'Cx', goal_id: 999, activity_ids: [30] }],
+      activities: [{ id: 30, name: 'A1' }],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([['∅', '∅', 'Cx', 'A1']]);
+  });
+});
+
+describe('buildChainTable — name fallback', () => {
+  it('falls back to the id when an element has an empty name', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [{ id: 7, name: '' }],
+      goals: [],
+      activities: [],
+    };
+    const t = buildChainTable(doc);
+    expect(t.rows[0][0]?.cell?.label).toBe('7');
+  });
+});