@transitrix/diagrams 1.8.8 → 1.8.13

package/src/goals/resolver.ts

@@ -0,0 +1,186 @@
+/**
+ * Goals Tree canon resolver — assembles a flat canonical Goals document from
+ * a view_config projection and a canon element store (methodology
+ * `notations/views/04-goals.md` §4 "Projection form (Full tier —
+ * post-promotion)"). Mirrors `fgca/resolver.ts`'s `resolveFGCA`/`isFGCAViewDoc`
+ * and `activities/resolver.ts`'s `resolveAction`/`isActionViewDoc` pattern
+ * for the `goals` notation.
+ *
+ * Output shape matches the flat inline form `parseCanonicalGoals` expects:
+ * top-level `goal_types[]` + `goals[]`. Filesystem-free — callable from unit
+ * tests without vscode.
+ *
+ * `goal_types[]` synthesis: when `view_config.goal_types` is present it is
+ * used as-is (the documented projection-form shape always includes it) and
+ * each goal keeps its own authored `level`, validated against that table as
+ * usual. When absent, §5.2 says the renderer "infers levels from the parent
+ * chain depth (root goals at 0, each step deeper adds 1)" — this resolver
+ * implements that literally (`parentChainDepth`), overriding each selected
+ * goal's `level` with its structural depth, rather than trusting the
+ * element's own stored `level` field. A stored `level` can't be trusted here:
+ * nothing enforces cross-element consistency on it (ELEMENT_PRIMITIVES.md
+ * §7.2: `type`/`level` are independent, both-optional per-element fields),
+ * and worse, using it made the synthesized table's chosen level depend on
+ * which element the canon loader happened to enumerate first — the CLI
+ * (`readdirSync`, unsorted) and the VS Code preview
+ * (`vscode.workspace.fs.readDirectory`, unsorted) can enumerate the same
+ * canon store in different orders, so the two surfaces could disagree on
+ * `GOALS-008` findings for identical input. Structural depth has no such
+ * dependency. A goal with no `type` still surfaces as a genuine `GOALS-006`
+ * finding — this resolver never synthesizes a type label to paper over one.
+ */
+
+import { isObject, str, strArray, descendantsOf, parentChainDepth, stripEnvelope } from '../canon-resolver-utils.js';
+
+export interface GoalsViewConfig {
+  scope?: {
+    root_goal?: string | null;
+    period?: string | null;
+    type_filter?: string[] | null;
+    valid_at?: string | null;
+  };
+  goal_types?: Array<{ name: string; level: number }>;
+  display?: {
+    depth?: number | null;
+    collapsed?: string[];
+  };
+}
+
+export interface GoalsCanonSources {
+  elements: unknown[];
+}
+
+/** GOAL elements by id (`notation: goal`). */
+function collectGoalElements(docs: unknown[]): Map<string, Record<string, unknown>> {
+  const out = new Map<string, Record<string, unknown>>();
+  for (const doc of docs) {
+    if (!isObject(doc)) continue;
+    if (str(doc['notation']) !== 'goal') continue;
+    const id = str(doc['id']);
+    if (!id) continue;
+    if (!out.has(id)) out.set(id, doc); // first definition wins
+  }
+  return out;
+}
+
+/**
+ * Returns true when the parsed view document uses the canon-projection form
+ * (`view_config` key present, no inline `goals[]`). Used by the preview and
+ * CLI to decide whether to run the resolver or fall back to direct
+ * `parseCanonicalGoals` on the inline document.
+ */
+export function isGoalsViewDoc(parsed: unknown): boolean {
+  if (!isObject(parsed)) return false;
+  return 'view_config' in parsed && !('goals' in parsed);
+}
+
+/**
+ * Assemble a flat canonical Goals document from the canon GOAL element
+ * store, filtered by the view document's `view_config.scope`. The return
+ * value is ready to pass to `parseCanonicalGoals`.
+ */
+export function resolveGoals(
+  viewDoc: unknown,
+  sources: GoalsCanonSources,
+): Record<string, unknown> {
+  if (!isObject(viewDoc)) {
+    return { notation: 'goals', goal_types: [], goals: [] };
+  }
+
+  const vc = isObject(viewDoc['view_config']) ? viewDoc['view_config'] : {};
+  const scope = isObject(vc['scope']) ? vc['scope'] : {};
+
+  const allGoals = collectGoalElements(sources.elements);
+
+  // 1. Scope by root_goal (this goal + its descendants), or every goal when
+  // omitted (§5.1: "Omit to show all root goals").
+  const rootGoal = str(scope['root_goal']);
+  let candidateIds: Set<string>;
+  if (rootGoal) {
+    candidateIds = allGoals.has(rootGoal) ? descendantsOf(rootGoal, allGoals) : new Set();
+  } else {
+    candidateIds = new Set(allGoals.keys());
+  }
+
+  // 2. Narrow by period — matched against the element's own `period` field
+  // when present (the GOAL element schema, ELEMENT_PRIMITIVES.md §7.2, does
+  // not define this field explicitly; treated as a forward-compatible tag).
+  const period = str(scope['period']);
+  if (period) {
+    candidateIds = new Set(
+      [...candidateIds].filter((id) => str(allGoals.get(id)?.['period']) === period),
+    );
+  }
+
+  // 3. Narrow by type_filter — only goals of a listed type.
+  const typeFilter = strArray(scope['type_filter']);
+  if (typeFilter.length > 0) {
+    candidateIds = new Set(
+      [...candidateIds].filter((id) => {
+        const t = str(allGoals.get(id)?.['type']);
+        return t !== undefined && typeFilter.includes(t);
+      }),
+    );
+  }
+
+  // 4. Narrow by valid_at — only goals in effect on that date. Goals with no
+  // valid_from are not lifecycle-tracked and are kept (permissive default,
+  // matching the action/dgca resolvers' stance).
+  const validAt = str(scope['valid_at']);
+  if (validAt) {
+    candidateIds = new Set(
+      [...candidateIds].filter((id) => {
+        const el = allGoals.get(id);
+        const from = str(el?.['valid_from']);
+        const to = str(el?.['valid_to']);
+        if (from && validAt < from) return false;
+        if (to && validAt > to) return false;
+        return true;
+      }),
+    );
+  }
+
+  const explicitGoalTypes = Array.isArray(vc['goal_types'])
+    ? (vc['goal_types'] as unknown[]).filter(isObject)
+    : undefined;
+
+  // Element fields map onto Goal fields unchanged — the admission/lifecycle
+  // envelope fields carry no rendering meaning for `parseCanonicalGoals` and
+  // are dropped.
+  let selectedGoals: Array<Record<string, unknown>>;
+  let goalTypes: Array<Record<string, unknown>>;
+
+  if (explicitGoalTypes) {
+    // Main-line case: goals keep their own authored `level`, validated
+    // against the explicit table by parseCanonicalGoals as usual.
+    selectedGoals = [...candidateIds].map((id) => ({ ...stripEnvelope(allGoals.get(id)!), id }));
+    goalTypes = explicitGoalTypes;
+  } else {
+    // §5.2 fallback: level is the goal's structural depth in the parent
+    // chain, not its (untrustworthy, order-dependent) stored `level` field.
+    const depthMemo = new Map<string, number>();
+    selectedGoals = [...candidateIds].map((id) => {
+      const { level: _level, ...rest } = stripEnvelope(allGoals.get(id)!);
+      return { ...rest, id, level: parentChainDepth(id, allGoals, depthMemo) };
+    });
+    const seen = new Map<string, number>();
+    for (const g of selectedGoals) {
+      const name = typeof g['type'] === 'string' ? g['type'] : undefined;
+      if (name !== undefined && !seen.has(name)) {
+        seen.set(name, g['level'] as number);
+      }
+    }
+    goalTypes = [...seen.entries()].map(([name, level]) => ({ name, level }));
+  }
+
+  return {
+    notation: 'goals',
+    id: viewDoc['id'],
+    name: viewDoc['name'],
+    spec_version: viewDoc['spec_version'],
+    description: viewDoc['description'],
+    period: viewDoc['period'],
+    goal_types: goalTypes,
+    goals: selectedGoals,
+  };
+}

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'];