@transitrix/diagrams 1.0.0

package/src/repo-validate/index.ts

@@ -0,0 +1,2 @@
+export { validateRepoModel } from './validate-repo.js';
+export type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';

package/src/repo-validate/types.ts

@@ -0,0 +1,50 @@
+// Repo-scope validation types (vkgeorgia/transitrix-studio#141).
+//
+// `validate --scope=repo` runs whole-model checks over a loaded `canon/` tree —
+// referential integrity, atomicity, ID uniqueness, policy — the checks that the
+// methodology's Python `.validators/lint.py` owns today. This converges those
+// checks onto the shared TypeScript model so there is a single validation
+// runtime (methodology ADR
+// `2026-06-11-validation-two-axis-model.md`; Studio referencing ADR
+// `docs/decisions/2026-06-11-validation-runtime-convergence.md`).
+//
+// The finding shape is deliberately minimal — `{ scope, id, message }`. The
+// richer `target` / `category` reporting taxonomy is explicitly DEFERRED per the
+// ADR until a real consumer needs it; do not add it here.
+
+/** A single repo-scope validation finding. Shape is frozen at `{ scope, id, message }`. */
+export interface RepoFinding {
+  /** Always `'repo'` — the execution axis this finding came from. */
+  scope: 'repo';
+  /**
+   * The offending element/relation id, or `''` when the finding is not tied to
+   * a single id (e.g. a YAML syntax error in a file with no parseable id).
+   */
+  id: string;
+  /** Human-readable description of the violation. */
+  message: string;
+}
+
+/** A parsed canon document fed to the repo validator. IO (the filesystem walk)
+ *  lives in the CLI; the validator itself stays pure and testable. */
+export interface RepoDoc {
+  /** Source file path, relative to the scanned root — used in messages. */
+  path: string;
+  /**
+   * The parsed top-level YAML mapping, or `null` when the file failed to parse.
+   * A `null` data with a non-empty `parseError` produces a syntax finding.
+   */
+  data: Record<string, unknown> | null;
+  /** Set when the YAML failed to parse; surfaced as a syntax finding. */
+  parseError?: string;
+}
+
+/** The loaded repository model: element docs and relation docs, partitioned by
+ *  canon zone exactly as `lint.py` partitions them (`canon/elements/**` vs
+ *  `canon/relations/**`). */
+export interface RepoModelInput {
+  /** Documents found under `canon/elements/**`. */
+  elements: RepoDoc[];
+  /** Documents found under `canon/relations/**`. */
+  relations: RepoDoc[];
+}

package/src/repo-validate/validate-repo.ts

@@ -0,0 +1,196 @@
+// Repo-scope validator (vkgeorgia/transitrix-studio#141).
+//
+// Pure port of the whole-repo checks owned by the methodology's
+// `.validators/lint.py`, run over the shared TypeScript model instead of Python.
+// Parity reference: the `acme_corp` worked example, which `lint.py` passes with
+// zero findings — this validator must also produce zero findings on it.
+//
+// Ported checks (mirroring lint.py's phases):
+//   1. YAML syntax        (phase 1) — unparseable canon file -> finding.
+//   2. ID uniqueness                — same `id` defined in >1 file -> finding.
+//                                     (lint.py silently last-wins; we surface it,
+//                                      but acme_corp has no duplicates, so parity
+//                                      holds on the reference fixture.)
+//   3. Atomicity          (phase 3) — element file carrying a `relations:` key.
+//   4. Referential integ. (phase 4) — relation endpoint not resolving to a known
+//                                     element id. We resolve the canonical
+//                                     `from`/`to` keys (the real relation schema)
+//                                     and also accept lint.py's `source`/`target`.
+//   5. Semantic rules     (phase 5) — ArchiMate layer-semantics. lint.py ships
+//                                     this as a no-op stub; ported faithfully as a
+//                                     no-op (see `checkLayerSemantics`). Deferred
+//                                     until the methodology defines the rules.
+//   6. Policy             (phase 6) — element marked Active/Production with no
+//                                     owner.
+//
+// Findings stay `{ scope, id, message }` — no severity, no target/category
+// taxonomy (deferred per the ADR).
+
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+
+const PScope: RepoFinding['scope'] = 'repo';
+
+/** Statuses that, per lint.py's policy check, require an owner. */
+const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Read a string `id` from a parsed doc, or `null` if absent/non-string.
+ *  Mirrors lint.py, which only treats a doc as an element/relation when it has
+ *  a top-level `id` (sidecars such as versioned-attribute files have no `id`
+ *  and are ignored). */
+function docId(doc: RepoDoc): string | null {
+  if (!doc.data) return null;
+  const id = doc.data['id'];
+  return typeof id === 'string' && id.length > 0 ? id : null;
+}
+
+/** Resolve a relation endpoint, which may be a bare id string or a `{ id }`
+ *  mapping (lint.py accepts both). Returns the id string or `null`. */
+function endpointId(value: unknown): string | null {
+  if (typeof value === 'string') return value.length > 0 ? value : null;
+  if (isRecord(value)) {
+    const id = value['id'];
+    if (typeof id === 'string' && id.length > 0) return id;
+  }
+  return null;
+}
+
+/** Phase 1 — unparseable canon files surface as findings. */
+function checkSyntax(docs: RepoDoc[], findings: RepoFinding[]): void {
+  for (const doc of docs) {
+    if (doc.parseError) {
+      findings.push({
+        scope: PScope,
+        id: '',
+        message: `YAML syntax error in ${doc.path}: ${doc.parseError}`,
+      });
+    }
+  }
+}
+
+/** Phase 2 (as a check) — the same id defined in more than one file. */
+function checkIdUniqueness(input: RepoModelInput, findings: RepoFinding[]): void {
+  const filesById = new Map<string, string[]>();
+  for (const doc of [...input.elements, ...input.relations]) {
+    const id = docId(doc);
+    if (!id) continue;
+    const list = filesById.get(id);
+    if (list) list.push(doc.path);
+    else filesById.set(id, [doc.path]);
+  }
+  for (const [id, files] of filesById) {
+    if (files.length > 1) {
+      findings.push({
+        scope: PScope,
+        id,
+        message: `Duplicate id '${id}' defined in ${files.length} files: ${files.join(', ')}`,
+      });
+    }
+  }
+}
+
+/** Phase 3 — relations must live in their own files, not inline on elements. */
+function checkAtomicity(input: RepoModelInput, findings: RepoFinding[]): void {
+  for (const doc of input.elements) {
+    const id = docId(doc);
+    if (id && doc.data && 'relations' in doc.data) {
+      findings.push({
+        scope: PScope,
+        id,
+        message:
+          `Atomicity violation: element '${id}' (${doc.path}) contains a ` +
+          `'relations' section. Move relations to separate files under canon/relations/.`,
+      });
+    }
+  }
+}
+
+/** Phase 4 — every relation endpoint must resolve to a known element id. */
+function checkReferentialIntegrity(input: RepoModelInput, findings: RepoFinding[]): void {
+  const elementIds = new Set<string>();
+  for (const doc of input.elements) {
+    const id = docId(doc);
+    if (id) elementIds.add(id);
+  }
+
+  for (const doc of input.relations) {
+    if (!doc.data) continue;
+    const relId = docId(doc) ?? '';
+    // Canonical relation schema uses `from`/`to`; `source`/`target` accepted for
+    // lint.py compatibility.
+    const fromId = endpointId(doc.data['from']) ?? endpointId(doc.data['source']);
+    const toId = endpointId(doc.data['to']) ?? endpointId(doc.data['target']);
+
+    if (fromId && !elementIds.has(fromId)) {
+      findings.push({
+        scope: PScope,
+        id: relId,
+        message: `Referential integrity: relation '${relId || doc.path}' endpoint '${fromId}' (from) does not resolve to a known element.`,
+      });
+    }
+    if (toId && !elementIds.has(toId)) {
+      findings.push({
+        scope: PScope,
+        id: relId,
+        message: `Referential integrity: relation '${relId || doc.path}' endpoint '${toId}' (to) does not resolve to a known element.`,
+      });
+    }
+  }
+}
+
+/** Phase 5 — ArchiMate layer-semantics on relations.
+ *
+ * lint.py ships `_check_semantic_rules` as a no-op stub (`pass`). It is ported
+ * here faithfully as a no-op so repo-scope validation reaches parity with
+ * lint.py on the reference fixture. Real layer-semantics rules are DEFERRED
+ * until the methodology defines them; when it does, they land here (a relation
+ * whose `type` is illegal between its endpoints' ArchiMate layers). Kept as a
+ * named hook so the intent — and the gap — is explicit rather than missing. */
+function checkLayerSemantics(_input: RepoModelInput, _findings: RepoFinding[]): void {
+  // Intentionally empty — parity with lint.py's stubbed phase 5. Do not add
+  // rules here without coordinating the methodology semantics canon.
+}
+
+/** Phase 6 — an element that is Active/Production must declare an owner. */
+function checkPolicy(input: RepoModelInput, findings: RepoFinding[]): void {
+  for (const doc of input.elements) {
+    const id = docId(doc);
+    if (!id || !doc.data) continue;
+    const metadata = doc.data['metadata'];
+    if (!isRecord(metadata)) continue;
+    const status = metadata['status'];
+    const owner = metadata['owner'];
+    if (typeof status === 'string' && OWNER_REQUIRED_STATUSES.has(status) && !owner) {
+      findings.push({
+        scope: PScope,
+        id,
+        message: `Policy: element '${id}' has status '${status}' but no owner assigned.`,
+      });
+    }
+  }
+}
+
+/**
+ * Run all repo-scope checks over a loaded canon model and return the findings.
+ * Pure: no IO, deterministic order (syntax, uniqueness, atomicity, referential,
+ * semantics, policy). Reaches parity with `lint.py` on the `acme_corp` fixture
+ * (zero findings on a clean tree).
+ */
+export function validateRepoModel(input: RepoModelInput): RepoFinding[] {
+  const findings: RepoFinding[] = [];
+  checkSyntax([...input.elements, ...input.relations], findings);
+  // A syntax error means the model is not reliably loaded; skip the graph checks
+  // and report the syntax problems first (mirrors lint.py, which bails after
+  // phase 1 on syntax errors).
+  if (findings.length > 0) return findings;
+
+  checkIdUniqueness(input, findings);
+  checkAtomicity(input, findings);
+  checkReferentialIntegrity(input, findings);
+  checkLayerSemantics(input, findings);
+  checkPolicy(input, findings);
+  return findings;
+}

package/src/requirement/__tests__/example.test.ts

@@ -0,0 +1,24 @@
+// Conformance test for the shipped REQUIREMENT worked examples — the
+// acme_corp canon files mirrored under `tests/fixtures/notation-corpus/requirement/`. Pins the
+// success signal of vkgeorgia/strategy#84 Phase 1: the library consumes the
+// canonical example files without error.
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { validateRequirement } from '../validate.js';
+
+const dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus/requirement');
+const load = (f: string): unknown => yaml.load(readFileSync(path.join(dir, f), 'utf-8'));
+
+describe('requirement worked examples (acme_corp)', () => {
+  for (const f of ['REQUIREMENT-DATA-ERASURE-1.yaml', 'REQUIREMENT-AUDIT-LOG-RETENTION-1.yaml']) {
+    it(`validates ${f} without error`, () => {
+      const v = validateRequirement(load(f));
+      expect(v.valid, JSON.stringify(v.errors)).toBe(true);
+      expect(v.errors).toHaveLength(0);
+    });
+  }
+});

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

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import { validateRequirement } from '../validate.js';
+import type { CanonCatalog } from '../../typed-id.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'requirement',
+    id: 'REQUIREMENT-DATA-ERASURE-1',
+    name: 'Personal-data erasure within 30 days',
+    description: 'The controller must erase personal data within 30 days of a verified request.',
+    severity: 'high',
+    zone: 'canon',
+    admitted_at: '2026-05-28',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2017-05-01',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown, opts?: Parameters<typeof validateRequirement>[1]): string[] =>
+  validateRequirement(input, opts).errors.map(e => e.code);
+
+describe('validateRequirement — positive', () => {
+  it('accepts a well-formed requirement', () => {
+    const r = validateRequirement(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('accepts an internal-only requirement with no derived_from', () => {
+    const r = valid();
+    delete r.derived_from;
+    r.severity = 'medium';
+    expect(validateRequirement(r).valid).toBe(true);
+  });
+});
+
+describe('validateRequirement — REQ-001 (shape / id grammar)', () => {
+  it('flags a missing required field', () => {
+    const r = valid();
+    delete r.name;
+    expect(codes(r)).toContain('REQ-001');
+  });
+
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'REQUIREMENT-DATA-ERASURE-001' })).toContain('REQ-001'); // leading zero
+    expect(codes({ ...valid(), id: 'REQ-1' })).toContain('REQ-001'); // wrong TYPE
+    expect(codes({ ...valid(), id: 'requirement-data-1' })).toContain('REQ-001'); // lowercase TYPE
+  });
+
+  it('flags a wrong notation tag and a non-canon zone', () => {
+    expect(codes({ ...valid(), notation: 'req' })).toContain('REQ-001');
+    expect(codes({ ...valid(), zone: 'sandbox' })).toContain('REQ-001');
+  });
+
+  it('flags a missing valid_to key (distinct from a null value)', () => {
+    const r = valid();
+    delete r.valid_to;
+    expect(codes(r)).toContain('REQ-001');
+    expect(validateRequirement({ ...valid(), valid_to: null }).valid).toBe(true);
+  });
+
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['REQ-001']);
+    expect(codes('x')).toEqual(['REQ-001']);
+    expect(codes(['a'])).toEqual(['REQ-001']);
+  });
+});
+
+describe('validateRequirement — REQ-002 (derived_from resolution)', () => {
+  it('flags a well-formed allowed-type ref that does not resolve in the catalog', () => {
+    const catalog: CanonCatalog = { typeOf: () => undefined };
+    expect(codes({ ...valid(), derived_from: ['LAW-PERSONAL-DATA-2017-1'] }, { catalog })).toContain('REQ-002');
+  });
+
+  it('flags a malformed derived_from entry (cannot resolve)', () => {
+    expect(codes({ ...valid(), derived_from: ['not an id'] })).toContain('REQ-002');
+  });
+
+  it('does not flag REQ-002 without a catalog for a well-formed allowed-type ref', () => {
+    expect(codes({ ...valid(), derived_from: ['LAW-PERSONAL-DATA-2017-1'] })).not.toContain('REQ-002');
+  });
+});
+
+describe('validateRequirement — REQ-003 (derived_from TYPE)', () => {
+  it('flags a derived_from TYPE outside LAW/REGULATION/POLICY/INTERNAL_STANDARD', () => {
+    expect(codes({ ...valid(), derived_from: ['PRODUCT-MOBILE-1'] })).toContain('REQ-003');
+  });
+
+  it('accepts each permitted derived_from TYPE', () => {
+    for (const id of ['LAW-X-1', 'REGULATION-X-1', 'POLICY-X-1', 'INTERNAL_STANDARD-X-1']) {
+      expect(codes({ ...valid(), derived_from: [id] })).not.toContain('REQ-003');
+    }
+  });
+});

package/src/requirement/index.ts

@@ -0,0 +1,4 @@
+export type { Requirement, RequirementSeverity, GateChecks } from './types.js';
+export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+export { validateRequirement } from './validate.js';
+export type { RequirementValidateOptions } from './validate.js';

package/src/requirement/types.ts

@@ -0,0 +1,35 @@
+// REQUIREMENT — motivation-layer positive obligation.
+// Schema: methodology notations/elements/15-requirement.md §2.
+
+export type RequirementSeverity = 'high' | 'medium' | 'low';
+
+/** Standard canon admission gate checks (CONTRACT.md §6). */
+export interface GateChecks {
+  uniqueness?: string;
+  consistency?: string;
+  completeness?: string;
+}
+
+/** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
+export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'] as const;
+
+export interface Requirement {
+  notation: 'requirement';
+  id: string;
+  name: string;
+  description: string;
+  /** Organisation-defined priority. */
+  severity?: RequirementSeverity;
+  /** Typed IDs of the codex source documents this requirement is drawn from. */
+  derived_from?: 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/requirement/validate.ts

@@ -0,0 +1,92 @@
+// REQUIREMENT validator — methodology notations/elements/15-requirement.md §4.
+//
+// Implements REQ-001..003. The shared HDR-/LIFECYCLE-/REQ-COVERAGE rules are
+// cross-cutting concerns owned elsewhere (CONTRACT.md §8) and are out of scope
+// for this single-artefact validator.
+//
+// REQ-002/003 resolve `derived_from` against the codex zone. Resolution that
+// needs artefact *existence* (REQ-002) only runs when a `CanonCatalog` is
+// supplied; the TYPE check (REQ-003) is derivable from the id prefix and runs
+// either way.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+
+export interface RequirementValidateOptions {
+  /** When provided, REQ-002 enforces that each `derived_from` id is admitted. */
+  catalog?: CanonCatalog;
+}
+
+const REQUIRED_FIELDS = [
+  'notation', 'name', 'description', 'zone', 'admitted_at', 'admitted_by', 'gate_checks', 'valid_from',
+] as const;
+
+export function validateRequirement(input: unknown, options: RequirementValidateOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'REQ-001', message: 'Requirement must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const r = input as Record<string, unknown>;
+
+  // REQ-001 — id grammar.
+  if (!isCanonicalIdOfType(r.id, 'REQUIREMENT')) {
+    errors.push({ code: 'REQ-001', message: `id "${String(r.id)}" must match REQUIREMENT-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  // REQ-001 — fixed notation tag.
+  if (r.notation !== 'requirement') {
+    errors.push({ code: 'REQ-001', message: 'notation must be the fixed value "requirement".', path: 'notation' });
+  }
+  // REQ-001 — required fields present and non-empty (notation handled above).
+  for (const f of REQUIRED_FIELDS) {
+    if (f === 'notation') continue;
+    if (f === 'gate_checks') {
+      if (r.gate_checks === null || typeof r.gate_checks !== 'object') {
+        errors.push({ code: 'REQ-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+      }
+      continue;
+    }
+    const v = r[f];
+    if (typeof v !== 'string' || v.trim() === '') {
+      errors.push({ code: 'REQ-001', message: `${f} is required.`, path: f });
+    }
+  }
+  // REQ-001 — zone fixed value.
+  if (r.zone !== undefined && r.zone !== 'canon') {
+    errors.push({ code: 'REQ-001', message: 'zone must be "canon" for a REQUIREMENT.', path: 'zone' });
+  }
+  // REQ-001 — valid_to key must exist (string or null).
+  if (!('valid_to' in r) || !(typeof r.valid_to === 'string' || r.valid_to === null)) {
+    errors.push({ code: 'REQ-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+
+  // REQ-002 / REQ-003 — derived_from references.
+  if (r.derived_from !== undefined) {
+    if (!Array.isArray(r.derived_from)) {
+      errors.push({ code: 'REQ-001', message: 'derived_from must be a list of typed IDs.', path: 'derived_from' });
+    } else {
+      r.derived_from.forEach((ref, i) => {
+        const type = typeOfId(ref);
+        if (!type) {
+          // A malformed ref cannot resolve — REQ-002.
+          errors.push({ code: 'REQ-002', message: `derived_from[${i}] "${String(ref)}" is not a resolvable typed ID.`, path: `derived_from[${i}]` });
+          return;
+        }
+        if (!REQUIREMENT_DERIVED_FROM_TYPES.includes(type as typeof REQUIREMENT_DERIVED_FROM_TYPES[number])) {
+          // REQ-003 — TYPE not a permitted codex source type (prefix-derivable).
+          errors.push({ code: 'REQ-003', message: `derived_from[${i}] TYPE "${type}" is not one of ${REQUIREMENT_DERIVED_FROM_TYPES.join(', ')}.`, path: `derived_from[${i}]` });
+          return;
+        }
+        if (options.catalog && options.catalog.typeOf(ref as string) === undefined) {
+          // REQ-002 — well-formed but not admitted in the codex zone.
+          errors.push({ code: 'REQ-002', message: `derived_from[${i}] "${String(ref)}" does not resolve to an admitted codex artefact.`, path: `derived_from[${i}]` });
+        }
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}