@transitrix/diagrams 1.8.11 → 1.8.18

package/src/blocks/validate.ts

@@ -1,8 +1,27 @@
-import type { Block } from './types.js';
+import type { Block, GridColumn, GridHeader, GridRow } from './types.js';
 import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
 
 export type { ValidationError, ValidationWarning, ValidationResult };
 
+/**
+ * A template-level check over an already well-formed grid document (matrix
+ * subset, §4a). Templates built on the `grid:` root (e.g. RACI) supply their
+ * own `GridRule`s for vocabulary-specific invariants — the base validator
+ * intentionally does not fix what `assign` values mean (08-blocks.md §6a), so
+ * those invariants never live inside `validateGrid` itself.
+ */
+export interface GridRule {
+  /** Template-namespaced rule code, e.g. "RACI-001" — never a BL-0xx code. */
+  ruleId: string;
+  severity: 'error' | 'warning';
+  check(grid: GridHeader): Array<{ message: string; path?: string }>;
+}
+
+export interface ValidateGridOptions {
+  /** Extra template-level rules to run once the base grid is well-formed. */
+  rules?: GridRule[];
+}
+
 /** Document-level ID grammar: BLOCKS-[<middle>-]<INTEGER>. */
 const BLOCKS_DOC_ID_RE = /^BLOCKS(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 
@@ -188,6 +207,143 @@ export function validateNestedBlocks(input: unknown): ValidationResult {
   return { valid: errors.length === 0, errors, warnings };
 }
 
+/** Matrix subset (§4a): validate a `grid:` root document — BL-021..BL-025. */
+export function validateGrid(input: unknown, options: ValidateGridOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'BL-001', message: 'Input must be an object' }], warnings };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  if ('notation' in raw && raw['notation'] !== 'blocks') {
+    errors.push({
+      code: 'BL-001',
+      message: `notation must be "blocks", got "${String(raw['notation'])}"`,
+    });
+  }
+
+  if (!('grid' in raw) || !raw['grid'] || typeof raw['grid'] !== 'object') {
+    errors.push({ code: 'BL-020', message: 'Missing required root key: grid' });
+    return { valid: false, errors, warnings };
+  }
+
+  const grid = raw['grid'] as Record<string, unknown>;
+  const rawColumns = grid['columns'];
+  const rawRows = grid['rows'];
+
+  if (!Array.isArray(rawColumns) || rawColumns.length === 0) {
+    errors.push({ code: 'BL-021', message: 'grid.columns must be a non-empty array' });
+  }
+  if (!Array.isArray(rawRows) || rawRows.length === 0) {
+    errors.push({ code: 'BL-022', message: 'grid.rows must be a non-empty array' });
+  }
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  const columnIds = new Set<string>();
+  const columns: GridColumn[] = [];
+  (rawColumns as unknown[]).forEach((entry, i) => {
+    const path = `grid.columns[${i}]`;
+    const c = entry as Record<string, unknown>;
+    if (!entry || typeof entry !== 'object' || !isNonEmptyString(c['id']) || !isNonEmptyString(c['name'])) {
+      errors.push({ code: 'BL-023', message: `${path} must have non-empty id and name`, path });
+      return;
+    }
+    const id = c['id'].trim();
+    if (columnIds.has(id)) {
+      errors.push({ code: 'BL-024', message: `Duplicate column id: "${id}"`, path });
+    } else {
+      columnIds.add(id);
+    }
+    columns.push({ id, name: c['name'] });
+  });
+
+  const rowIds = new Set<string>();
+  const rows: GridRow[] = [];
+  (rawRows as unknown[]).forEach((entry, i) => {
+    const path = `grid.rows[${i}]`;
+    const r = entry as Record<string, unknown>;
+    if (!entry || typeof entry !== 'object' || !isNonEmptyString(r['id']) || !isNonEmptyString(r['name'])) {
+      errors.push({ code: 'BL-023', message: `${path} must have non-empty id and name`, path });
+      return;
+    }
+    const id = r['id'].trim();
+    if (rowIds.has(id)) {
+      errors.push({ code: 'BL-024', message: `Duplicate row id: "${id}"`, path });
+    } else {
+      rowIds.add(id);
+    }
+
+    const rawAssign = r['assign'];
+    let assign: Record<string, unknown> | undefined;
+    if (rawAssign !== undefined) {
+      if (!rawAssign || typeof rawAssign !== 'object' || Array.isArray(rawAssign)) {
+        errors.push({ code: 'BL-023', message: `${path}.assign must be a map when present`, path });
+      } else {
+        assign = rawAssign as Record<string, unknown>;
+        for (const colId of Object.keys(assign)) {
+          if (!columnIds.has(colId)) {
+            errors.push({
+              code: 'BL-025',
+              message: `${path}.assign references unknown column id "${colId}"`,
+              path,
+            });
+          }
+        }
+      }
+    }
+    rows.push({ id, name: r['name'], assign });
+  });
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  const grid_: GridHeader = { columns, rows };
+  for (const rule of options.rules ?? []) {
+    for (const finding of rule.check(grid_)) {
+      const entry = { code: rule.ruleId, message: finding.message, path: finding.path };
+      if (rule.severity === 'error') errors.push(entry);
+      else warnings.push(entry);
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+export interface ValidateBlocksOptions extends ValidateGridOptions {}
+
+/**
+ * Root-form dispatcher (§4/§4a): a document declares exactly one of
+ * `nested_blocks` (tree form) or `grid` (matrix subset) — never both, never
+ * neither (BL-020). Delegates to whichever form is present.
+ */
+export function validateBlocks(input: unknown, options: ValidateBlocksOptions = {}): ValidationResult {
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'BL-001', message: 'Input must be an object' }], warnings: [] };
+  }
+
+  const raw = input as Record<string, unknown>;
+  const hasNested = raw['nested_blocks'] !== undefined && raw['nested_blocks'] !== null;
+  const hasGrid = raw['grid'] !== undefined && raw['grid'] !== null;
+
+  if (hasNested && hasGrid) {
+    return {
+      valid: false,
+      errors: [{ code: 'BL-020', message: 'Document root must declare exactly one of nested_blocks or grid, not both' }],
+      warnings: [],
+    };
+  }
+  if (hasGrid) return validateGrid(input, options);
+  if (hasNested) return validateNestedBlocks(input);
+
+  return {
+    valid: false,
+    errors: [{ code: 'BL-020', message: 'Document root must declare exactly one of nested_blocks or grid' }],
+    warnings: [],
+  };
+}
+
 /**
  * Convenience: validate a single `Block` subtree. Used by tests and by
  * downstream consumers that need to check a sub-document.

package/src/capability-map/validate.ts

@@ -21,10 +21,17 @@ export function validateCapabilityMap(input: unknown): ValidationResult {
   }
   const raw = input as Record<string, unknown>;
 
+  // HDR-001/002 — DSM's own rule codes for the same header check CMAP-001
+  // already makes (api02/internal/importer/capabilities.go ValidateCapMap),
+  // added alongside it (not instead of it) so DSM can map a finding straight
+  // back onto its own import-log taxonomy while CMAP-001 stays the richer,
+  // pre-existing Studio-native code for this notation's own validator.
   if (!('notation' in raw)) {
     errors.push({ code: 'CMAP-001', message: 'Missing required field: notation' });
+    errors.push({ code: 'HDR-001', message: 'notation field is missing' });
   } else if (raw['notation'] !== 'capability-map') {
     errors.push({ code: 'CMAP-001', message: `notation must be "capability-map", got "${raw['notation']}"` });
+    errors.push({ code: 'HDR-002', message: `notation must be "capability-map", got "${raw['notation']}"` });
   }
   if (errors.length > 0) return { valid: false, errors, warnings };
 
@@ -116,6 +123,39 @@ function validateCapabilityTree(
     if (node['applications'] !== undefined && !Array.isArray(node['applications']))
       errors.push({ code: 'CMAP-003', message: `${nodePath}: applications must be an array` });
 
+    // LIFECYCLE-001/004 — DSM's own rule codes (capabilities.go
+    // ValidateCapMap/validateCapMapNodes) for `valid_from`/`valid_to`, the
+    // CONTRACT.md §7 primitive-lifecycle fields. Net new: this notation's own
+    // validator has no equivalent check today — `CapabilityNode` (types.ts)
+    // does not even declare these fields, since Studio's own schema tracks
+    // lifecycle via `target_date` instead. The fields are still read directly
+    // off the raw untyped node here because real capability-map documents
+    // (e.g. organizations/acme_corp) author them inline per §7 regardless.
+    {
+      const id = typeof node['id'] === 'string' ? (node['id'] as string) : nodePath;
+      const validFrom = node['valid_from'];
+      const validTo = node['valid_to'];
+      let fromDate: string | undefined;
+      let toDate: string | undefined;
+      if (validFrom !== undefined && validFrom !== null) {
+        if (typeof validFrom !== 'string' || !DATE_RE.test(validFrom)) {
+          errors.push({ code: 'LIFECYCLE-001', message: `capability ${id} valid_from "${String(validFrom)}" is not a valid YYYY-MM-DD date (must be quoted)` });
+        } else {
+          fromDate = validFrom;
+        }
+      }
+      if (validTo !== undefined && validTo !== null) {
+        if (typeof validTo !== 'string' || !DATE_RE.test(validTo)) {
+          errors.push({ code: 'LIFECYCLE-001', message: `capability ${id} valid_to "${String(validTo)}" is not a valid YYYY-MM-DD date (must be quoted)` });
+        } else {
+          toDate = validTo;
+        }
+      }
+      if (fromDate && toDate && toDate < fromDate) {
+        errors.push({ code: 'LIFECYCLE-004', message: `capability ${id} valid_to ${toDate} is before valid_from ${fromDate}` });
+      }
+    }
+
     if (node['children'] !== undefined) {
       if (!Array.isArray(node['children'])) {
         errors.push({ code: 'CMAP-003', message: `${nodePath}: children must be an array` });

package/src/fgca/parse-canonical.ts

@@ -130,6 +130,14 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
   }
   const activitiesRaw = asObjectArray(raw['actions']);
   if (activitiesRaw === null && 'activities' in raw) {
+    // DSM's Go ValidateFGCA (fgca.go) still accepts this as the deprecated
+    // "activities" key and promotes it with a DGCA-DEPR warning, not an
+    // error. Deliberately NOT matched here — PR #320 ("drop deprecated
+    // notation aliases fgca/fga/activities/activity-card") already removed
+    // that leniency from this validator on purpose. Re-introducing
+    // DGCA-DEPR would reverse a deliberate, shipped decision, not fill a
+    // gap; see docs/validation.md's "Standalone-element envelope rules"
+    // section for the full note.
     errors.push({ code: 'FGCA-004', message: '"activities" key is not accepted — rename to "actions"', path: 'actions' });
   }
 

package/src/repo-validate/check-element-hygiene.ts

@@ -0,0 +1,236 @@
+// Standalone-element envelope checks — the error-severity subset of DSM's Go
+// `Validate*Element` functions (`api02/internal/importer/{goal_element,
+// action_element}.go` in transitrix-dsm), ported onto the standalone-element
+// repo shape (`canon/elements/**`) that `validate --scope=repo` already
+// loads. Sibling to `check-strategy-chain.ts` (which covers cross-element
+// reference/cycle rules); this file covers the per-element envelope rules —
+// id presence/grammar, name presence, and the ACTION type vocabulary +
+// deprecated-alias warnings.
+//
+// DSM identifies "this file is a GOAL/ACTION element" by its folder location
+// during the import walk (`canon/elements/01_motivation/goals/`,
+// `canon/elements/05_implementation/actions/`) — the validator functions
+// receive an already-typed struct, so a wrong `notation` value on that
+// struct is still checkable (`GOAL-ELEM-001`/the notation branch of
+// `ACTION-001`). This repo-scope model has no such pre-typing
+// (`RepoModelInput.elements` is a flat, untyped list from `canon/elements/**`)
+// — candidate selection here is content-based (the element's own `notation`
+// field), same convention as `check-strategy-chain.ts`'s `collectByNotation`.
+// That means a candidate is by construction already notation-correct, so
+// GOAL-ELEM-001's and ACTION-001's "wrong notation" case can never fire here
+// — tried an id-prefix-based candidate signal instead (matching on a `GOAL-`/
+// `ACTION-` id TYPE prefix regardless of notation) to cover that case, but it
+// produced false positives against this repo's own test fixtures, which
+// reuse a `GOAL-`-prefixed id under a `goals/` path for an unrelated
+// notation as a referential-integrity test double
+// (`validate-repo.test.ts`'s `GOAL-OPS-1`/notation:'assessment' fixture) —
+// there is no reliable, adopter-folder-layout-independent way to tell
+// "misfiled element" from "id reused for something else" without DSM's own
+// folder-based typing. Flagged for a decision, same as `GOALS-008`: skip
+// permanently, or scope a follow-up once the repo-scope model gains
+// path-aware typing.
+//
+// Rule codes are DSM's own — not invented here — so DSM can map a CLI
+// finding straight back onto its import-log taxonomy (`RepoFinding.ruleId`).
+//
+// Ported (error-severity, blocking):
+//   GOAL-ELEM-002   — GOAL element `id` is missing.
+//   GOAL-ELEM-003   — GOAL element `name` is missing.
+//   ACTION-001      — ACTION element `id` or `name` is missing.
+//   ACTION-002      — ACTION element `type` is set but not one of
+//                      Initiative | Strategic Initiative | Programme |
+//                      Project | Task (Strategic Initiative is an accepted
+//                      alias for Initiative). DSM treats this as fatal — the
+//                      type vocabulary has real behavioural teeth downstream.
+//
+// Ported (warning-severity, advisory):
+//   GOAL-ELEM-002   — GOAL element `id` does not match the canonical
+//                      `GOAL-[<middle>-]<INTEGER>` grammar (non-fatal —
+//                      DSM still imports it).
+//   ACTION-001      — ACTION element `id` does not match the canonical
+//                      `ACTION-[<middle>-]<INTEGER>` grammar.
+//   ACTION-005      — ACTION element uses a deprecated alias: `notation:
+//                      activity` (pre-2026-06-25), an `ACTIVITY-` id prefix,
+//                      or the `activity_type` field (rename to `type`).
+//
+// Not ported: GOALS-007 (duplicate id) / ACT-004 (duplicate id) — already
+// covered generically by `validate-repo.ts`'s `checkIdUniqueness`, which
+// spans every canon element/relation id, not just GOAL/ACTION. Porting a
+// second, notation-scoped duplicate check here would just double-report the
+// same defect under two rule codes.
+
+import { docId } from './validate-repo.js';
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+
+const PScope: RepoFinding['scope'] = 'repo';
+
+const GOAL_ELEM_ID_RE = /^GOAL-([A-Z0-9]+-)*[0-9]+$/;
+const ACTION_ELEM_ID_RE = /^ACTION-([A-Z0-9]+-)*[0-9]+$/;
+
+/** ACTION scale-level vocabulary (elements/24-action.md §1). "Strategic
+ *  Initiative" is an accepted alias for "Initiative", matching DSM's
+ *  `actionTypeVocabulary` (action_element.go). */
+const ACTION_TYPE_VOCABULARY = new Set([
+  'Initiative',
+  'Strategic Initiative',
+  'Programme',
+  'Project',
+  'Task',
+]);
+
+function readString(data: Record<string, unknown>, key: string): string | undefined {
+  const v = data[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+interface ElementCandidate {
+  id: string | undefined;
+  doc: RepoDoc;
+  data: Record<string, unknown>;
+}
+
+function collectCandidates(
+  elements: RepoDoc[],
+  matches: (data: Record<string, unknown>) => boolean,
+): ElementCandidate[] {
+  const out: ElementCandidate[] = [];
+  for (const doc of elements) {
+    if (!doc.data) continue;
+    if (!matches(doc.data)) continue;
+    out.push({ id: docId(doc) ?? undefined, doc, data: doc.data });
+  }
+  return out;
+}
+
+/** GOAL-ELEM-002/003 — the GOAL element envelope: id presence + grammar,
+ *  name presence. Candidate selection is content-based (`notation === 'goal'`)
+ *  — see the module header for why `GOAL-ELEM-001` (wrong notation) isn't
+ *  ported here. */
+function checkGoalElements(elements: RepoDoc[], findings: RepoFinding[]): void {
+  const candidates = collectCandidates(elements, (data) => data['notation'] === 'goal');
+
+  for (const { id, data } of candidates) {
+    const where = id ?? '';
+
+    if (!id) {
+      findings.push({
+        scope: PScope,
+        id: '',
+        ruleId: 'GOAL-ELEM-002',
+        message: 'GOAL-ELEM-002: GOAL element id is missing.',
+      });
+    } else if (!GOAL_ELEM_ID_RE.test(id)) {
+      findings.push({
+        scope: PScope,
+        id,
+        ruleId: 'GOAL-ELEM-002',
+        severity: 'warning',
+        message: `GOAL-ELEM-002: goal id '${id}' does not match GOAL-[<middle>-]<INTEGER>.`,
+      });
+    }
+
+    if (!readString(data, 'name')) {
+      findings.push({
+        scope: PScope,
+        id: where,
+        ruleId: 'GOAL-ELEM-003',
+        message: `GOAL-ELEM-003: GOAL element '${where || '(no id)'}' name is missing.`,
+      });
+    }
+  }
+}
+
+/** ACTION-001/002/005 — the ACTION element envelope: id presence + grammar,
+ *  name presence, type vocabulary, and the pre-2026-06-25 deprecated aliases
+ *  (`notation: activity`, `ACTIVITY-` id prefix, `activity_type` field).
+ *  Candidate selection is content-based (`notation === 'action'` or the
+ *  deprecated `'activity'` alias) — see the module header for why
+ *  `ACTION-001`'s "wrong notation" case isn't ported here. */
+function checkActionElements(elements: RepoDoc[], findings: RepoFinding[]): void {
+  const candidates = collectCandidates(
+    elements,
+    (data) => data['notation'] === 'action' || data['notation'] === 'activity',
+  );
+
+  for (const { id, data } of candidates) {
+    const where = id ?? '';
+
+    if (data['notation'] === 'activity') {
+      findings.push({
+        scope: PScope,
+        id: where,
+        ruleId: 'ACTION-005',
+        severity: 'warning',
+        message: `ACTION-005: element '${where || '(no id)'}' notation 'activity' is deprecated; migrate to 'action'.`,
+      });
+    }
+
+    if (!id) {
+      findings.push({
+        scope: PScope,
+        id: '',
+        ruleId: 'ACTION-001',
+        message: 'ACTION-001: ACTION element id is missing.',
+      });
+    } else if (id.startsWith('ACTIVITY-')) {
+      findings.push({
+        scope: PScope,
+        id,
+        ruleId: 'ACTION-005',
+        severity: 'warning',
+        message: `ACTION-005: id '${id}' uses the deprecated ACTIVITY- prefix; migrate to ACTION-.`,
+      });
+    } else if (!ACTION_ELEM_ID_RE.test(id)) {
+      findings.push({
+        scope: PScope,
+        id,
+        ruleId: 'ACTION-001',
+        severity: 'warning',
+        message: `ACTION-001: action id '${id}' does not match ACTION-[<middle>-]<INTEGER>.`,
+      });
+    }
+
+    if (!readString(data, 'name')) {
+      findings.push({
+        scope: PScope,
+        id: where,
+        ruleId: 'ACTION-001',
+        message: `ACTION-001: ACTION element '${where || '(no id)'}' name is missing.`,
+      });
+    }
+
+    let actionType = readString(data, 'type');
+    if (!actionType) {
+      const legacy = readString(data, 'activity_type');
+      if (legacy) {
+        findings.push({
+          scope: PScope,
+          id: where,
+          ruleId: 'ACTION-005',
+          severity: 'warning',
+          message: `ACTION-005: element '${where || '(no id)'}' field 'activity_type' is deprecated; migrate to 'type'.`,
+        });
+        actionType = legacy;
+      }
+    }
+    if (actionType && !ACTION_TYPE_VOCABULARY.has(actionType)) {
+      findings.push({
+        scope: PScope,
+        id: where,
+        ruleId: 'ACTION-002',
+        message: `ACTION-002: element '${where || '(no id)'}' type '${actionType}' is not one of Initiative, Programme, Project, Task.`,
+      });
+    }
+  }
+}
+
+/**
+ * Run the standalone-element envelope checks (GOAL-ELEM-001..003,
+ * ACTION-001/002/005) over the loaded element set and append findings.
+ * Called from `validateRepoModel` alongside `checkStrategyChainSemantics`.
+ * Pure, deterministic order.
+ */
+export function checkElementHygiene(input: RepoModelInput, findings: RepoFinding[]): void {
+  checkGoalElements(input.elements, findings);
+  checkActionElements(input.elements, findings);
+}