@transitrix/diagrams 1.8.11 → 1.8.13

package/dist/repo-validate/index.d.ts

@@ -1,2 +1,3 @@
 export { validateRepoModel } from './validate-repo.js';
-export type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+export { resolveRepoModel } from './resolve-model.js';
+export type { RepoDoc, RepoFinding, RepoModelInput, ResolvedElementRecord, ResolvedRelationRecord, ResolvedRepoModel } from './types.js';

package/dist/repo-validate/index.js

@@ -1 +1,2 @@
 export { validateRepoModel } from './validate-repo.js';
+export { resolveRepoModel } from './resolve-model.js';

package/dist/repo-validate/resolve-model.d.ts

@@ -0,0 +1,5 @@
+import type { RepoModelInput, ResolvedRepoModel } from './types.js';
+/** Project a loaded canon model into the resolved element/relation records a
+ *  non-JS consumer can read directly, without depending on this repo's YAML
+ *  parsing internals. Pure: no IO. */
+export declare function resolveRepoModel(input: RepoModelInput): ResolvedRepoModel;

package/dist/repo-validate/resolve-model.js

@@ -0,0 +1,71 @@
+// Resolved element/relation records for `validate --scope=repo --json --include-model`.
+// A non-JS consumer (DSM's Go backend) needs the canon model this CLI already
+// parses without re-implementing the notation schema — this is a pure
+// projection over the same `RepoModelInput` the repo-scope validator
+// consumes, not a second parse pass, so the two never drift out of sync.
+import { docId, endpointId } from './validate-repo.js';
+/** Matches the `<NN>_<layer>` folder segment under `canon/elements/`, e.g.
+ *  `01_motivation` -> `motivation` (ELEMENT_PRIMITIVES.md §2/§6). */
+const LAYER_FOLDER_RE = /^\d+_(.+)$/;
+function readString(data, key) {
+    const v = data[key];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** Derive `layer` from the `canon/elements/<NN>_<layer>/…` folder segment when
+ *  the doc has no explicit `layer` field — the folder is authoritative
+ *  (ELEMENT_PRIMITIVES.md §3, `ELEM-003`). */
+function layerFromPath(path) {
+    const segs = path.split('/');
+    const layerSeg = segs[2]; // canon / elements / <NN>_<layer> / …
+    if (!layerSeg)
+        return undefined;
+    const m = LAYER_FOLDER_RE.exec(layerSeg);
+    return m ? m[1] : undefined;
+}
+function resolveElement(doc) {
+    const id = docId(doc);
+    if (!id || !doc.data)
+        return null;
+    return {
+        id,
+        name: readString(doc.data, 'name') ?? '',
+        notation: readString(doc.data, 'notation') ?? '',
+        type: readString(doc.data, 'type'),
+        layer: readString(doc.data, 'layer') ?? layerFromPath(doc.path),
+        sourceFile: doc.path,
+        data: doc.data,
+    };
+}
+function resolveRelation(doc) {
+    if (!doc.data)
+        return null;
+    const source = endpointId(doc.data['from']) ?? endpointId(doc.data['source']);
+    const target = endpointId(doc.data['to']) ?? endpointId(doc.data['target']);
+    if (!source || !target)
+        return null;
+    return {
+        id: docId(doc) ?? '',
+        kind: readString(doc.data, 'type'),
+        source,
+        target,
+        sourceFile: doc.path,
+    };
+}
+/** Project a loaded canon model into the resolved element/relation records a
+ *  non-JS consumer can read directly, without depending on this repo's YAML
+ *  parsing internals. Pure: no IO. */
+export function resolveRepoModel(input) {
+    const elements = [];
+    for (const doc of input.elements) {
+        const rec = resolveElement(doc);
+        if (rec)
+            elements.push(rec);
+    }
+    const relations = [];
+    for (const doc of input.relations) {
+        const rec = resolveRelation(doc);
+        if (rec)
+            relations.push(rec);
+    }
+    return { elements, relations };
+}

package/dist/repo-validate/types.d.ts

@@ -32,3 +32,59 @@ export interface RepoModelInput {
     /** Documents found under `canon/relations/**`. */
     relations: RepoDoc[];
 }
+/** One resolved canon element, projected from a `RepoDoc` for a non-JS
+ *  consumer (DSM's Go importer). The top-level fields below are a stable,
+ *  minimal identity projection — kept for backward compatibility with
+ *  consumers that only need `id`/`name`/`notation`/`type`/`layer`/`sourceFile`
+ *  (mirrors DSM's `methodology_element` table). `data` carries the complete
+ *  parsed element alongside it, so a consumer never needs an engine schema
+ *  change to read a canon-authored field the engine already parsed (a goal's
+ *  `level`/`parent`/`description`/`link`/`tags`, an action's scheduling and
+ *  ownership fields, etc.) — the engine owns each notation's field set
+ *  (ELEMENT_PRIMITIVES.md), so its output stays notation-shaped rather than
+ *  growing a bespoke field list per consumer. This is the faithful-projection
+ *  fallback: a typed per-notation shape may replace `data` later, but the
+ *  contract must not be curated down to what one consumer currently needs. */
+export interface ResolvedElementRecord {
+    /** Canonical id, e.g. `DRIVER-COMP-1`. */
+    id: string;
+    /** `name` field; `''` when absent (should not happen for an admitted element). */
+    name: string;
+    /** The element TYPE's short name — the doc's `notation` field, e.g. `driver`, `goal`, `capability`. */
+    notation: string;
+    /** Subtype from the TYPE's controlled vocabulary (ELEMENT_PRIMITIVES.md §3), e.g. `internal`/`external` for DRIVER. Omitted when the doc has none. */
+    type?: string;
+    /** `motivation` / `business` / `application` / `technology` / `implementation`. Read from the doc's `layer` field when present, else derived from the `canon/elements/<NN>_<layer>/…` folder. */
+    layer?: string;
+    /** Source file path, relative to the scanned root. */
+    sourceFile: string;
+    /** The full parsed element document — every field its author supplied,
+     *  unfiltered (including the admission/lifecycle envelope). The same
+     *  `RepoDoc.data` the repo-scope validator already consumes, so this
+     *  projection and the validation pass never see a different parse. */
+    data: Record<string, unknown>;
+}
+/** One resolved canon relation, projected from a `RepoDoc`. Only
+ *  emitted when both endpoints resolve to a non-empty id — an endpoint that
+ *  fails to resolve is already surfaced as a referential-integrity finding by
+ *  `validateRepoModel`; this projection does not duplicate that as a
+ *  half-resolved record. */
+export interface ResolvedRelationRecord {
+    /** Canonical id, e.g. `REL-EMP-PERSON-OPS-1`. `''` when the relation doc has no `id`. */
+    id: string;
+    /** The relation's `type` field, e.g. `employment`, `realizes`. Omitted when the doc has none. */
+    kind?: string;
+    /** Resolved `from` (or legacy `source`) endpoint id. */
+    source: string;
+    /** Resolved `to` (or legacy `target`) endpoint id. */
+    target: string;
+    /** Source file path, relative to the scanned root. */
+    sourceFile: string;
+}
+/** The resolved element/relation records for a repo-scope run —
+ *  the shape `transitrix validate --scope=repo --json --include-model` adds
+ *  alongside the validation findings. */
+export interface ResolvedRepoModel {
+    elements: ResolvedElementRecord[];
+    relations: ResolvedRelationRecord[];
+}

package/dist/repo-validate/validate-repo.d.ts

@@ -1,4 +1,14 @@
-import type { RepoFinding, RepoModelInput } from './types.js';
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+/** 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). Exported for reuse by `resolve-model.ts`, which needs the
+ *  same id/endpoint reading rules to stay in lockstep with this validator. */
+export declare function docId(doc: RepoDoc): string | 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`. */
+export declare function endpointId(value: unknown): string | null;
 /**
  * Run all repo-scope checks over a loaded canon model and return the findings.
  * Pure: no IO, deterministic order (syntax, uniqueness, atomicity, referential,

package/dist/repo-validate/validate-repo.js

@@ -28,14 +28,15 @@
 const PScope = 'repo';
 /** Statuses that, per lint.py's policy check, require an owner. */
 const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
-function isRecord(v) {
+export function isRecord(v) {
     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) {
+ *  and are ignored). Exported for reuse by `resolve-model.ts`, which needs the
+ *  same id/endpoint reading rules to stay in lockstep with this validator. */
+export function docId(doc) {
     if (!doc.data)
         return null;
     const id = doc.data['id'];
@@ -43,7 +44,7 @@ function docId(doc) {
 }
 /** 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) {
+export function endpointId(value) {
     if (typeof value === 'string')
         return value.length > 0 ? value : null;
     if (isRecord(value)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.8.11",
+  "version": "1.8.13",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/repo-validate/index.ts

@@ -1,2 +1,3 @@
 export { validateRepoModel } from './validate-repo.js';
-export type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+export { resolveRepoModel } from './resolve-model.js';
+export type { RepoDoc, RepoFinding, RepoModelInput, ResolvedElementRecord, ResolvedRelationRecord, ResolvedRepoModel } from './types.js';

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

@@ -0,0 +1,79 @@
+// Resolved element/relation records for `validate --scope=repo --json --include-model`.
+// A non-JS consumer (DSM's Go backend) needs the canon model this CLI already
+// parses without re-implementing the notation schema — this is a pure
+// projection over the same `RepoModelInput` the repo-scope validator
+// consumes, not a second parse pass, so the two never drift out of sync.
+
+import { docId, endpointId } from './validate-repo.js';
+import type {
+  RepoDoc,
+  RepoModelInput,
+  ResolvedElementRecord,
+  ResolvedRelationRecord,
+  ResolvedRepoModel,
+} from './types.js';
+
+/** Matches the `<NN>_<layer>` folder segment under `canon/elements/`, e.g.
+ *  `01_motivation` -> `motivation` (ELEMENT_PRIMITIVES.md §2/§6). */
+const LAYER_FOLDER_RE = /^\d+_(.+)$/;
+
+function readString(data: Record<string, unknown>, key: string): string | undefined {
+  const v = data[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+/** Derive `layer` from the `canon/elements/<NN>_<layer>/…` folder segment when
+ *  the doc has no explicit `layer` field — the folder is authoritative
+ *  (ELEMENT_PRIMITIVES.md §3, `ELEM-003`). */
+function layerFromPath(path: string): string | undefined {
+  const segs = path.split('/');
+  const layerSeg = segs[2]; // canon / elements / <NN>_<layer> / …
+  if (!layerSeg) return undefined;
+  const m = LAYER_FOLDER_RE.exec(layerSeg);
+  return m ? m[1] : undefined;
+}
+
+function resolveElement(doc: RepoDoc): ResolvedElementRecord | null {
+  const id = docId(doc);
+  if (!id || !doc.data) return null;
+  return {
+    id,
+    name: readString(doc.data, 'name') ?? '',
+    notation: readString(doc.data, 'notation') ?? '',
+    type: readString(doc.data, 'type'),
+    layer: readString(doc.data, 'layer') ?? layerFromPath(doc.path),
+    sourceFile: doc.path,
+    data: doc.data,
+  };
+}
+
+function resolveRelation(doc: RepoDoc): ResolvedRelationRecord | null {
+  if (!doc.data) return null;
+  const source = endpointId(doc.data['from']) ?? endpointId(doc.data['source']);
+  const target = endpointId(doc.data['to']) ?? endpointId(doc.data['target']);
+  if (!source || !target) return null;
+  return {
+    id: docId(doc) ?? '',
+    kind: readString(doc.data, 'type'),
+    source,
+    target,
+    sourceFile: doc.path,
+  };
+}
+
+/** Project a loaded canon model into the resolved element/relation records a
+ *  non-JS consumer can read directly, without depending on this repo's YAML
+ *  parsing internals. Pure: no IO. */
+export function resolveRepoModel(input: RepoModelInput): ResolvedRepoModel {
+  const elements: ResolvedElementRecord[] = [];
+  for (const doc of input.elements) {
+    const rec = resolveElement(doc);
+    if (rec) elements.push(rec);
+  }
+  const relations: ResolvedRelationRecord[] = [];
+  for (const doc of input.relations) {
+    const rec = resolveRelation(doc);
+    if (rec) relations.push(rec);
+  }
+  return { elements, relations };
+}

package/src/repo-validate/types.ts

@@ -47,3 +47,62 @@ export interface RepoModelInput {
   /** Documents found under `canon/relations/**`. */
   relations: RepoDoc[];
 }
+
+/** One resolved canon element, projected from a `RepoDoc` for a non-JS
+ *  consumer (DSM's Go importer). The top-level fields below are a stable,
+ *  minimal identity projection — kept for backward compatibility with
+ *  consumers that only need `id`/`name`/`notation`/`type`/`layer`/`sourceFile`
+ *  (mirrors DSM's `methodology_element` table). `data` carries the complete
+ *  parsed element alongside it, so a consumer never needs an engine schema
+ *  change to read a canon-authored field the engine already parsed (a goal's
+ *  `level`/`parent`/`description`/`link`/`tags`, an action's scheduling and
+ *  ownership fields, etc.) — the engine owns each notation's field set
+ *  (ELEMENT_PRIMITIVES.md), so its output stays notation-shaped rather than
+ *  growing a bespoke field list per consumer. This is the faithful-projection
+ *  fallback: a typed per-notation shape may replace `data` later, but the
+ *  contract must not be curated down to what one consumer currently needs. */
+export interface ResolvedElementRecord {
+  /** Canonical id, e.g. `DRIVER-COMP-1`. */
+  id: string;
+  /** `name` field; `''` when absent (should not happen for an admitted element). */
+  name: string;
+  /** The element TYPE's short name — the doc's `notation` field, e.g. `driver`, `goal`, `capability`. */
+  notation: string;
+  /** Subtype from the TYPE's controlled vocabulary (ELEMENT_PRIMITIVES.md §3), e.g. `internal`/`external` for DRIVER. Omitted when the doc has none. */
+  type?: string;
+  /** `motivation` / `business` / `application` / `technology` / `implementation`. Read from the doc's `layer` field when present, else derived from the `canon/elements/<NN>_<layer>/…` folder. */
+  layer?: string;
+  /** Source file path, relative to the scanned root. */
+  sourceFile: string;
+  /** The full parsed element document — every field its author supplied,
+   *  unfiltered (including the admission/lifecycle envelope). The same
+   *  `RepoDoc.data` the repo-scope validator already consumes, so this
+   *  projection and the validation pass never see a different parse. */
+  data: Record<string, unknown>;
+}
+
+/** One resolved canon relation, projected from a `RepoDoc`. Only
+ *  emitted when both endpoints resolve to a non-empty id — an endpoint that
+ *  fails to resolve is already surfaced as a referential-integrity finding by
+ *  `validateRepoModel`; this projection does not duplicate that as a
+ *  half-resolved record. */
+export interface ResolvedRelationRecord {
+  /** Canonical id, e.g. `REL-EMP-PERSON-OPS-1`. `''` when the relation doc has no `id`. */
+  id: string;
+  /** The relation's `type` field, e.g. `employment`, `realizes`. Omitted when the doc has none. */
+  kind?: string;
+  /** Resolved `from` (or legacy `source`) endpoint id. */
+  source: string;
+  /** Resolved `to` (or legacy `target`) endpoint id. */
+  target: string;
+  /** Source file path, relative to the scanned root. */
+  sourceFile: string;
+}
+
+/** The resolved element/relation records for a repo-scope run —
+ *  the shape `transitrix validate --scope=repo --json --include-model` adds
+ *  alongside the validation findings. */
+export interface ResolvedRepoModel {
+  elements: ResolvedElementRecord[];
+  relations: ResolvedRelationRecord[];
+}

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

@@ -33,15 +33,16 @@ 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> {
+export 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 {
+ *  and are ignored). Exported for reuse by `resolve-model.ts`, which needs the
+ *  same id/endpoint reading rules to stay in lockstep with this validator. */
+export 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;
@@ -49,7 +50,7 @@ function docId(doc: RepoDoc): string | 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 {
+export function endpointId(value: unknown): string | null {
   if (typeof value === 'string') return value.length > 0 ? value : null;
   if (isRecord(value)) {
     const id = value['id'];