@transitrix/diagrams 1.8.8 → 1.8.13

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.8",
+  "version": "1.8.13",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/activities/index.ts

@@ -26,3 +26,5 @@ export { validateActivities } from './validate.js';
 export { computeCpm } from './cpm.js';
 export { layoutActivities } from './layout.js';
 export { computeGanttLayout, isGanttUnavailable } from './gantt.js';
+export { resolveAction, isActionViewDoc } from './resolver.js';
+export type { ActionViewConfig, ActionCanonSources } from './resolver.js';

package/src/activities/resolver.ts

@@ -0,0 +1,208 @@
+/**
+ * Action Schedule canon resolver — assembles a flat canonical Action document
+ * from a view_config projection and a canon element store (methodology
+ * `notations/views/07-action.md` §4 "Projection form (Full tier —
+ * post-promotion)"). Mirrors `fgca/resolver.ts`'s `resolveFGCA`/`isFGCAViewDoc`
+ * pattern for the `action` notation.
+ *
+ * Output shape matches the flat inline form `validateActivities` expects:
+ * top-level `project` block + `actions[]`, with ACTION element fields carried
+ * through unchanged except `type` → `activity_type` (the internal Activity
+ * field name; `type` is the canonical element field per elements/24-action.md
+ * §2). Filesystem-free — callable from unit tests without vscode.
+ */
+
+import { isObject, str, strArray, descendantsOf, stripEnvelope } from '../canon-resolver-utils.js';
+
+export interface ActionViewConfig {
+  scope?: {
+    root_action?: string;
+    goals?: string[];
+    type_filter?: string[];
+    valid_at?: string | null;
+  };
+  schedule?: {
+    start_date?: string;
+    calendar?: {
+      working_days?: string[];
+      hours_per_day?: number;
+      holidays?: string[];
+    };
+  };
+  display?: {
+    view?: 'network' | 'gantt' | 'both';
+    depth?: number | null;
+    collapsed?: string[];
+  };
+}
+
+export interface ActionCanonSources {
+  elements: unknown[];
+  /** `canon/relations/**` docs (`notation: relation`). Optional — omit for
+   *  canon stores with no relations tree; `action_goal` links then fall back
+   *  to each element's inline `goals[]`. */
+  relations?: unknown[];
+}
+
+/** ACTION elements by id. `notation: action` is canonical; `notation: activity`
+ *  is the deprecated pre-2026-06-25 alias (elements/24-action.md §"Deprecated
+ *  alias") — accepted the same way `collectByNotation` callers elsewhere do. */
+function collectActionElements(docs: unknown[]): Map<string, Record<string, unknown>> {
+  const out = new Map<string, Record<string, unknown>>();
+  for (const doc of docs) {
+    if (!isObject(doc)) continue;
+    const notation = str(doc['notation']);
+    if (notation !== 'action' && notation !== 'activity') continue;
+    const id = str(doc['id']);
+    if (!id) continue;
+    if (!out.has(id)) out.set(id, doc); // first definition wins
+  }
+  return out;
+}
+
+/**
+ * GOAL ids reached by an *active* `action_goal` (or legacy `activity_goal`)
+ * relation originating at `fromId`. A relation with a non-null `valid_to` has
+ * ended (the action was re-aimed) and is excluded. Mirrors
+ * `activity-card/resolver.ts`'s `activeActivityGoals` — the canonical, preferred
+ * source per elements/24-action.md §3 ("renderers prefer REL files when both
+ * are present").
+ */
+function activeActionGoalRelations(relations: unknown[], fromId: string): string[] {
+  const out: string[] = [];
+  for (const doc of relations) {
+    if (!isObject(doc)) continue;
+    if (str(doc['notation']) !== 'relation') continue;
+    const type = str(doc['type']);
+    if (type !== 'action_goal' && type !== 'activity_goal') continue;
+    if (str(doc['from']) !== fromId) continue;
+    const to = str(doc['to']);
+    if (!to) continue;
+    const validTo = doc['valid_to'];
+    if (validTo !== undefined && validTo !== null) continue; // ended relation
+    if (!out.includes(to)) out.push(to);
+  }
+  return out;
+}
+
+/**
+ * Returns true when the parsed view document uses the canon-projection form
+ * (`view_config` key present, no inline `actions[]`). Used by the preview and
+ * CLI to decide whether to run the resolver or fall back to direct
+ * `validateActivities` on the inline document.
+ */
+export function isActionViewDoc(parsed: unknown): boolean {
+  if (!isObject(parsed)) return false;
+  return 'view_config' in parsed && !('actions' in parsed);
+}
+
+/**
+ * Assemble a flat canonical Action document from the canon ACTION element
+ * store, filtered by the view document's `view_config.scope`. The return
+ * value is ready to pass to `validateActivities`.
+ */
+export function resolveAction(
+  viewDoc: unknown,
+  sources: ActionCanonSources,
+): Record<string, unknown> {
+  if (!isObject(viewDoc)) {
+    return { notation: 'action', actions: [] };
+  }
+
+  const vc = isObject(viewDoc['view_config']) ? viewDoc['view_config'] : {};
+  const scope = isObject(vc['scope']) ? vc['scope'] : {};
+  const schedule = isObject(vc['schedule']) ? vc['schedule'] : {};
+
+  const allActions = collectActionElements(sources.elements);
+  const relations = sources.relations ?? [];
+
+  /** Effective `goals[]` for an action — the active `action_goal` REL targets
+   *  when any exist, else the element's transitional inline `goals[]`. */
+  function effectiveGoals(id: string, el: Record<string, unknown>): string[] {
+    const relGoals = activeActionGoalRelations(relations, id);
+    return relGoals.length > 0 ? relGoals : strArray(el['goals']);
+  }
+
+  // 1. Scope by root_action (this action + its descendants), or the full
+  // catalogue when omitted (§5.1: "Omit to include elements from the full
+  // catalogue (or use goals/type_filter for other scoping)").
+  const rootAction = str(scope['root_action']);
+  let candidateIds: Set<string>;
+  if (rootAction) {
+    candidateIds = allActions.has(rootAction) ? descendantsOf(rootAction, allActions) : new Set();
+  } else {
+    candidateIds = new Set(allActions.keys());
+  }
+
+  // 2. Narrow by goals — only actions linked to at least one listed GOAL
+  // (via an active action_goal relation, or inline goals[] when no relation
+  // exists for that action).
+  const goalsFilter = strArray(scope['goals']);
+  if (goalsFilter.length > 0) {
+    candidateIds = new Set(
+      [...candidateIds].filter((id) => effectiveGoals(id, allActions.get(id)!).some((g) => goalsFilter.includes(g))),
+    );
+  }
+
+  // 3. Narrow by type_filter — only actions of a listed type.
+  const typeFilter = strArray(scope['type_filter']);
+  if (typeFilter.length > 0) {
+    candidateIds = new Set(
+      [...candidateIds].filter((id) => {
+        const el = allActions.get(id);
+        const t = str(el?.['type']) ?? str(el?.['activity_type']);
+        return t !== undefined && typeFilter.includes(t);
+      }),
+    );
+  }
+
+  // 4. Narrow by valid_at — only actions in effect on that date. Actions with
+  // no valid_from are not lifecycle-tracked and are kept (permissive default,
+  // matching the resolver's general "missing = not excluded" stance).
+  const validAt = str(scope['valid_at']);
+  if (validAt) {
+    candidateIds = new Set(
+      [...candidateIds].filter((id) => {
+        const el = allActions.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;
+      }),
+    );
+  }
+
+  // Element fields map onto Activity fields unchanged, except the canonical
+  // `type` (elements/24-action.md §2) which becomes the internal `activity_type`
+  // (types.ts `Activity.activity_type`), and `goals` which is resolved via
+  // `effectiveGoals` (REL-preferred). The admission/lifecycle envelope fields
+  // carry no schedule/render meaning for `validateActivities` and are dropped.
+  const selectedActions = [...candidateIds].map((id) => {
+    const el = allActions.get(id)!;
+    const { type, activity_type, goals: _inlineGoals, ...rest } = stripEnvelope(el);
+    const resolvedType = type ?? activity_type;
+    return {
+      ...rest,
+      id,
+      goals: effectiveGoals(id, el),
+      ...(resolvedType !== undefined ? { activity_type: resolvedType } : {}),
+    };
+  });
+
+  const project: Record<string, unknown> = {};
+  const startDate = str(schedule['start_date']);
+  if (startDate) project['start_date'] = startDate;
+  if (isObject(schedule['calendar'])) project['calendar'] = schedule['calendar'];
+
+  const out: Record<string, unknown> = {
+    notation: 'action',
+    id: viewDoc['id'],
+    title: viewDoc['name'],
+    spec_version: viewDoc['spec_version'],
+    description: viewDoc['description'],
+    actions: selectedActions,
+  };
+  if (Object.keys(project).length > 0) out['project'] = project;
+  return out;
+}

package/src/canon-resolver-utils.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared primitives for the per-notation canon-projection resolvers
+ * (activities/resolver.ts, goals/resolver.ts — fgca/resolver.ts predates this
+ * module and keeps its own copies). Each resolver assembles a flat document
+ * from a canon element store filtered by a view_config.scope block; these
+ * helpers are the parts that don't vary by notation.
+ */
+
+export function isObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** A non-empty string, trimmed. */
+export function str(v: unknown): string | undefined {
+  if (typeof v !== 'string') return undefined;
+  const t = v.trim();
+  return t.length > 0 ? t : undefined;
+}
+
+export function strArray(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  return v.filter((x): x is string => typeof x === 'string' && x.trim().length > 0);
+}
+
+/** `rootId` and every element reachable by following `parent` links downward,
+ *  per the element map's own `parent` field. Used to scope a projection to a
+ *  root element and its transitive descendants (WBS / goal hierarchy / etc). */
+export function descendantsOf(
+  rootId: string,
+  all: Map<string, Record<string, unknown>>,
+): Set<string> {
+  const childrenByParent = new Map<string, string[]>();
+  for (const [id, el] of all) {
+    const parent = str(el['parent']);
+    if (!parent) continue;
+    const list = childrenByParent.get(parent) ?? [];
+    list.push(id);
+    childrenByParent.set(parent, list);
+  }
+  const result = new Set<string>();
+  const queue: string[] = [rootId];
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    if (result.has(id)) continue;
+    result.add(id);
+    for (const child of childrenByParent.get(id) ?? []) queue.push(child);
+  }
+  return result;
+}
+
+/** Depth of `id` in its `parent` chain within `all` (root = 0, each step up
+ *  adds 1). Cycle-safe (a cycle resolves the entering node to depth 0) and
+ *  memoized across calls via the shared `memo` map. */
+export function parentChainDepth(
+  id: string,
+  all: Map<string, Record<string, unknown>>,
+  memo: Map<string, number> = new Map(),
+  visiting: Set<string> = new Set(),
+): number {
+  const cached = memo.get(id);
+  if (cached !== undefined) return cached;
+  if (visiting.has(id)) {
+    memo.set(id, 0);
+    return 0;
+  }
+  const el = all.get(id);
+  const parent = el ? str(el['parent']) : undefined;
+  if (!parent || !all.has(parent)) {
+    memo.set(id, 0);
+    return 0;
+  }
+  visiting.add(id);
+  const level = parentChainDepth(parent, all, memo, visiting) + 1;
+  visiting.delete(id);
+  memo.set(id, level);
+  return level;
+}
+
+/** The admission/lifecycle envelope fields (CONTRACT.md §6-7) every canon
+ *  element carries but that carry no rendering/validation meaning once
+ *  projected into a flat notation-specific document. */
+const ENVELOPE_FIELDS = ['notation', 'zone', 'admitted_at', 'admitted_by', 'gate_checks', 'valid_from', 'valid_to'] as const;
+
+/** `el` with the admission/lifecycle envelope fields removed. */
+export function stripEnvelope(el: Record<string, unknown>): Record<string, unknown> {
+  const rest = { ...el };
+  for (const field of ENVELOPE_FIELDS) delete rest[field];
+  return rest;
+}

package/src/fgca/resolver.ts

@@ -91,7 +91,11 @@ export function resolveFGCA(
   const factorElems = new Map([...factorElemsLegacy, ...factorElemsNew]);
   const goalElems = collectByNotation(sources.elements, 'goal');
   const changeElems = collectByNotation(sources.elements, 'change');
-  const activityElems = collectByNotation(sources.elements, 'activity');
+  // `action` is canonical since methodology 1.0; `activity` is the deprecated
+  // pre-rename alias, still accepted (elements/24-action.md §"Deprecated alias").
+  const activityElemsLegacy = collectByNotation(sources.elements, 'activity');
+  const activityElemsNew = collectByNotation(sources.elements, 'action');
+  const activityElems = new Map([...activityElemsLegacy, ...activityElemsNew]);
 
   // 1. Select goal set
   const goalsFilter = str(goalsConf['filter']) ?? 'all';

package/src/goals/index.ts

@@ -16,6 +16,8 @@ export type {
 export { validateGoalTree } from './validate.js';
 export { parseCanonicalGoals } from './parse-canonical.js';
 export type { CanonicalGoalsResult } from './parse-canonical.js';
+export { resolveGoals, isGoalsViewDoc } from './resolver.js';
+export type { GoalsViewConfig, GoalsCanonSources } from './resolver.js';
 export { layoutGoalTree, selectScopedGoals } from './layout.js';
 export { reparent, addChild, deleteWithDescendants, moveToBacklog, restoreFromBacklog } from './mutations.js';