@ontrails/topography 0.2.0

package/src/derive.ts

@@ -0,0 +1,690 @@
+/**
+ * Derive a deterministic topo graph from a Topo.
+ */
+
+import {
+  DETOUR_MAX_ATTEMPTS_CAP,
+  activationSourceKey,
+  deriveStructuredSignalExamples,
+  deriveStructuredTrailExamples,
+  deriveTrailCliCommandRendering,
+  getEntityReferences,
+  deriveActivationSourceFacts,
+  validateEstablishedTopo,
+  signalDiagnosticDefinitions,
+  zodToJsonSchema,
+} from '@ontrails/core';
+import type {
+  ActivationEntry,
+  ActivationSource,
+  AnyEntity,
+  AnyResource,
+  CliSurfaceBindingAliases,
+  FieldOverride,
+  Layer,
+  Signal,
+  Topo,
+  Trail,
+} from '@ontrails/core';
+
+import { addPermitRequirement } from './permit.js';
+import { deriveTopoGraphLibrary } from './library-derivation.js';
+import { collectTopoGraphOverlays } from './overlays.js';
+import {
+  resolveCliAliasInputsFromOverlays,
+  resolveTrailheadEntriesFromOverlays,
+} from './surface-bindings.js';
+import { TOPO_GRAPH_SCHEMA_VERSION } from './types.js';
+import { deriveTrailVersions } from './versioning.js';
+import type {
+  DeriveTopoGraphOptions,
+  JsonSchema,
+  TopoGraph,
+  TopoGraphActivationEdge,
+  TopoGraphActivationGraph,
+  TopoGraphActivationSource,
+  TopoGraphEntry,
+  TopoGraphFieldOverride,
+  TopoGraphFieldOverrideKey,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Sort object keys lexicographically (shallow). */
+const sortKeys = <T extends Record<string, unknown>>(obj: T): T => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj).toSorted()) {
+    sorted[key] = obj[key];
+  }
+  return sorted as T;
+};
+
+/** Sort object keys recursively for deterministic JSON Schema output. */
+const deepSortKeys = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(deepSortKeys);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = deepSortKeys((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+};
+
+const canonicalLeaf = (value: unknown): unknown => {
+  switch (typeof value) {
+    case 'bigint': {
+      return value.toString();
+    }
+    case 'function': {
+      return `[Function:${value.name || 'anonymous'}]`;
+    }
+    case 'symbol': {
+      return `[Symbol:${value.description ?? ''}]`;
+    }
+    case 'undefined': {
+      return '[Undefined]';
+    }
+    default: {
+      return value;
+    }
+  }
+};
+
+const canonicalObject = (
+  value: Record<string, unknown>,
+  visit: (value: unknown) => unknown
+): Record<string, unknown> => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value).toSorted()) {
+    const next = value[key];
+    sorted[key] = next === undefined ? '[Undefined]' : visit(next);
+  }
+  return sorted;
+};
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof RegExp) {
+    return value.toString();
+  }
+  if (value !== null && typeof value === 'object') {
+    return canonicalObject(value as Record<string, unknown>, canonicalize);
+  }
+  return canonicalLeaf(value);
+};
+
+/** Convert a Zod schema to a deterministically-keyed JSON Schema. */
+const toSortedJsonSchema = (schema: unknown): JsonSchema => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const raw = zodToJsonSchema(schema as any);
+  return deepSortKeys(raw) as JsonSchema;
+};
+
+interface SignalGraphRelations {
+  readonly consumers: readonly string[];
+  readonly producers: readonly string[];
+}
+
+const EMPTY_SIGNAL_RELATIONS: SignalGraphRelations = {
+  consumers: [],
+  producers: [],
+};
+
+const SIGNAL_DIAGNOSTIC_CODES = Object.keys(
+  signalDiagnosticDefinitions
+).toSorted();
+
+const SIGNAL_DIAGNOSTIC_HOOKS = {
+  codes: SIGNAL_DIAGNOSTIC_CODES,
+  strictMode: true,
+} as const;
+
+const SIGNAL_GOVERNANCE_HOOKS = {
+  consumers: 'trail.on',
+  payload: 'signal.payload',
+  producers: 'trail.fires',
+} as const;
+
+const deriveActivationSource = (
+  source: ActivationSource
+): TopoGraphActivationSource =>
+  deriveActivationSourceFacts(source) as TopoGraphActivationSource;
+
+const deriveActivationEdge = (
+  trailId: string,
+  activation: ActivationEntry
+): TopoGraphActivationEdge => {
+  const sourceKey = activationSourceKey(activation.source);
+  const edge: Record<string, unknown> = {
+    hasWhere: activation.where !== undefined,
+    sourceId: activation.source.id,
+    sourceKey,
+    sourceKind: activation.source.kind,
+    trailId,
+  };
+
+  if (activation.meta !== undefined) {
+    edge['meta'] = canonicalize(activation.meta);
+  }
+  if (activation.where !== undefined) {
+    edge['where'] = { predicate: true };
+  }
+
+  return sortKeys(edge) as TopoGraphActivationEdge;
+};
+
+const collectActivationSourceCatalog = (
+  topo: Topo
+): readonly TopoGraphActivationSource[] => {
+  const sources = new Map<string, TopoGraphActivationSource>();
+  for (const trail of topo.trails.values()) {
+    for (const activation of trail.activationSources) {
+      const derived = deriveActivationSource(activation.source);
+      sources.set(derived.key, derived);
+    }
+  }
+  return [...sources.values()].toSorted((a, b) => a.key.localeCompare(b.key));
+};
+
+const collectActivationGraphEdges = (
+  topo: Topo
+): readonly TopoGraphActivationEdge[] => {
+  const edges = new Map<string, TopoGraphActivationEdge>();
+  for (const trail of topo.trails.values()) {
+    for (const activation of trail.activationSources) {
+      const edge = deriveActivationEdge(trail.id, activation);
+      const key = `${edge.sourceKey}\0${edge.trailId}`;
+      const previous = edges.get(key);
+      edges.set(
+        key,
+        previous === undefined || (!previous.hasWhere && edge.hasWhere)
+          ? edge
+          : previous
+      );
+    }
+  }
+
+  return [...edges.values()].toSorted(
+    (a, b) =>
+      a.sourceKey.localeCompare(b.sourceKey) ||
+      a.trailId.localeCompare(b.trailId)
+  );
+};
+
+const buildActivationGraph = (
+  edges: readonly TopoGraphActivationEdge[],
+  sources: readonly TopoGraphActivationSource[]
+): TopoGraphActivationGraph =>
+  sortKeys({
+    edgeCount: edges.length,
+    edges,
+    sourceCount: sources.length,
+    sourceKeys: sources.map((source) => source.key),
+    trailIds: [...new Set(edges.map((edge) => edge.trailId))].toSorted(),
+  }) as TopoGraphActivationGraph;
+
+const collectSignalGraphRelations = (
+  topo: Topo
+): ReadonlyMap<string, SignalGraphRelations> => {
+  const producers = new Map<string, Set<string>>();
+  const consumers = new Map<string, Set<string>>();
+
+  for (const trail of topo.trails.values()) {
+    for (const signalId of trail.fires) {
+      const current = producers.get(signalId) ?? new Set<string>();
+      current.add(trail.id);
+      producers.set(signalId, current);
+    }
+    for (const signalId of trail.on) {
+      const current = consumers.get(signalId) ?? new Set<string>();
+      current.add(trail.id);
+      consumers.set(signalId, current);
+    }
+  }
+
+  return new Map(
+    [...topo.signals.keys()].map((signalId) => [
+      signalId,
+      {
+        consumers: [...(consumers.get(signalId) ?? [])].toSorted(),
+        producers: [...(producers.get(signalId) ?? [])].toSorted(),
+      },
+    ])
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Entry builders
+// ---------------------------------------------------------------------------
+
+/** Extract surfaces from a raw object. */
+const extractSurfaces = (raw: Record<string, unknown>): string[] =>
+  Array.isArray(raw['surfaces'])
+    ? (raw['surfaces'] as string[]).toSorted()
+    : [];
+
+/** Add optional schemas to an entry. */
+const addSchemas = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown, unknown>
+): void => {
+  if (t.input) {
+    entry['input'] = toSortedJsonSchema(t.input);
+  }
+  if (t.output) {
+    entry['output'] = toSortedJsonSchema(t.output);
+  }
+};
+
+const addEntitySchema = (
+  entry: Record<string, unknown>,
+  entity: AnyEntity
+): void => {
+  entry['schema'] = toSortedJsonSchema(entity);
+};
+
+/** Add safety markers to an entry. */
+const addSafetyMarkers = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown, unknown>
+): void => {
+  if (t.intent !== 'write') {
+    entry['intent'] = t.intent;
+  }
+  if (t.idempotent === true) {
+    entry['idempotent'] = true;
+  }
+  if (t.dryRun === true) {
+    entry['dryRunCapable'] = true;
+  }
+};
+
+/** Add deprecation and detours to an entry. */
+const addExtendedMetadata = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown, unknown>,
+  raw: Record<string, unknown>
+): void => {
+  if (raw['deprecated'] === true) {
+    entry['deprecated'] = true;
+  }
+  if (typeof raw['replacedBy'] === 'string') {
+    entry['replacedBy'] = raw['replacedBy'];
+  }
+  if (t.detours.length > 0) {
+    entry['detours'] = t.detours.map((d) => ({
+      maxAttempts: Math.max(
+        1,
+        Math.min(d.maxAttempts ?? 1, DETOUR_MAX_ATTEMPTS_CAP)
+      ),
+      on: d.on.name,
+    }));
+  }
+};
+
+/** Add optional meta fields to an entry. */
+const addMetadata = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown, unknown>,
+  raw: Record<string, unknown>
+): void => {
+  if (t.description !== undefined) {
+    entry['description'] = t.description;
+  }
+  if (t.pattern !== undefined) {
+    entry['pattern'] = t.pattern;
+  }
+  addSafetyMarkers(entry, t);
+  addExtendedMetadata(entry, t, raw);
+};
+
+const addTrailRelations = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown, unknown>
+): void => {
+  if (t.activationSources.length > 0) {
+    entry['activationSources'] = t.activationSources.map((activation) =>
+      sortKeys({
+        ...(activation.meta === undefined
+          ? {}
+          : { meta: canonicalize(activation.meta) }),
+        source: deriveActivationSource(activation.source),
+        ...(activation.where === undefined
+          ? {}
+          : { where: sortKeys({ predicate: true }) }),
+      })
+    );
+  }
+  if (t.composes.length > 0) {
+    entry['composes'] = t.composes.toSorted();
+  }
+  if (t.fires.length > 0) {
+    entry['fires'] = t.fires.toSorted();
+  }
+  if (t.on.length > 0) {
+    entry['on'] = t.on.toSorted();
+  }
+  if (t.entities.length > 0) {
+    entry['entities'] = t.entities.map((entity) => entity.name).toSorted();
+  }
+  if (t.resources.length > 0) {
+    entry['resources'] = t.resources.map((resource) => resource.id).toSorted();
+  }
+};
+
+const layerToReference = (
+  scope: 'topo' | 'trail',
+  layer: Layer
+): Record<string, unknown> => {
+  const reference: Record<string, unknown> = {
+    name: layer.name,
+    scope,
+  };
+  if (layer.input !== undefined) {
+    reference['input'] = toSortedJsonSchema(layer.input);
+  }
+  return sortKeys(reference);
+};
+
+const addLayerAttachments = (
+  entry: Record<string, unknown>,
+  topoLayers: readonly Layer[],
+  t: Trail<unknown, unknown, unknown>
+): void => {
+  const layers = [
+    ...topoLayers.map((layer) => layerToReference('topo', layer)),
+    ...t.layers.map((layer) => layerToReference('trail', layer)),
+  ].toSorted((left, right) => {
+    const scope = String(left['scope']).localeCompare(String(right['scope']));
+    return scope === 0
+      ? String(left['name']).localeCompare(String(right['name']))
+      : scope;
+  });
+
+  if (layers.length > 0) {
+    entry['layers'] = layers;
+  }
+};
+
+const FIELD_OVERRIDE_KEYS: readonly TopoGraphFieldOverrideKey[] = [
+  'hint',
+  'label',
+  'message',
+  'options',
+];
+
+const collectFieldOverrideKeys = (
+  override: FieldOverride
+): readonly TopoGraphFieldOverrideKey[] =>
+  FIELD_OVERRIDE_KEYS.filter((key) => override[key] !== undefined);
+
+const deriveFieldOverrides = (
+  fields: Readonly<Record<string, FieldOverride>> | undefined
+): readonly TopoGraphFieldOverride[] | undefined => {
+  if (fields === undefined) {
+    return undefined;
+  }
+
+  const overrides = Object.entries(fields)
+    .flatMap(([field, override]) => {
+      const overrideKeys = collectFieldOverrideKeys(override);
+      if (overrideKeys.length === 0) {
+        return [];
+      }
+      return [
+        {
+          field,
+          overrides: overrideKeys,
+          provenance: { source: 'trail.fields' as const },
+        },
+      ];
+    })
+    .toSorted((a, b) => a.field.localeCompare(b.field));
+
+  return overrides.length > 0 ? overrides : undefined;
+};
+
+const addFieldOverrides = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown, unknown>
+): void => {
+  const fieldOverrides = deriveFieldOverrides(t.fields);
+  if (fieldOverrides !== undefined) {
+    entry['fieldOverrides'] = fieldOverrides;
+  }
+};
+
+const addExamples = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown, unknown>
+): void => {
+  const examples = deriveStructuredTrailExamples(t.examples);
+  if (examples !== undefined) {
+    entry['examples'] = examples;
+  }
+};
+
+const addVersioning = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown, unknown>
+): void => {
+  if (t.version === undefined) {
+    return;
+  }
+  const derivation = deriveTrailVersions(t, toSortedJsonSchema);
+  if (derivation === undefined) {
+    return;
+  }
+
+  entry['marker'] = derivation.marker;
+  entry['supports'] = derivation.supports;
+  entry['version'] = derivation.version;
+  if (derivation.versions !== undefined) {
+    entry['versions'] = derivation.versions;
+  }
+};
+
+const trailToEntry = (
+  t: Trail<unknown, unknown, unknown>,
+  topoLayers: readonly Layer[],
+  surfaceAliases: CliSurfaceBindingAliases | undefined
+): TopoGraphEntry => {
+  const raw = t as unknown as Record<string, unknown>;
+  const surfaces = extractSurfaces(raw);
+  const entry: Record<string, unknown> = {
+    cli: deriveTrailCliCommandRendering(t, {
+      aliasSource: 'surface',
+      aliases: surfaceAliases?.[t.id],
+    }),
+    exampleCount: Array.isArray(t.examples) ? t.examples.length : 0,
+    id: t.id,
+    kind: t.kind,
+    surfaces,
+  };
+
+  addSchemas(entry, t);
+  addMetadata(entry, t, raw);
+  addPermitRequirement(entry, t);
+  addTrailRelations(entry, t);
+  addLayerAttachments(entry, topoLayers, t);
+  addFieldOverrides(entry, t);
+  addExamples(entry, t);
+  addVersioning(entry, t);
+
+  return sortKeys(entry) as unknown as TopoGraphEntry;
+};
+
+/** Add optional signal-specific fields. */
+const addSignalFields = (
+  entry: Record<string, unknown>,
+  e: Signal<unknown>,
+  raw: Record<string, unknown>,
+  relations: SignalGraphRelations
+): void => {
+  if (e.payload) {
+    const payload = toSortedJsonSchema(e.payload);
+    entry['input'] = payload;
+    entry['payload'] = payload;
+  }
+  if (e.description !== undefined) {
+    entry['description'] = e.description;
+  }
+  if (e.meta !== undefined) {
+    entry['meta'] = e.meta;
+  }
+  if (e.from !== undefined && e.from.length > 0) {
+    entry['from'] = e.from.toSorted();
+  }
+  entry['consumers'] = relations.consumers;
+  entry['diagnostics'] = SIGNAL_DIAGNOSTIC_HOOKS;
+  entry['governance'] = SIGNAL_GOVERNANCE_HOOKS;
+  entry['producers'] = relations.producers;
+  const examples = deriveStructuredSignalExamples(e.examples);
+  if (examples !== undefined) {
+    entry['examples'] = examples;
+  }
+  if (raw['deprecated'] === true) {
+    entry['deprecated'] = true;
+  }
+  if (typeof raw['replacedBy'] === 'string') {
+    entry['replacedBy'] = raw['replacedBy'];
+  }
+};
+
+const signalToEntry = (
+  e: Signal<unknown>,
+  relations: SignalGraphRelations
+): TopoGraphEntry => {
+  const raw = e as unknown as Record<string, unknown>;
+  const surfaces = extractSurfaces(raw);
+  const entry: Record<string, unknown> = {
+    exampleCount: e.examples?.length ?? 0,
+    id: e.id,
+    kind: 'signal',
+    surfaces,
+  };
+  addSignalFields(entry, e, raw, relations);
+  return sortKeys(entry) as unknown as TopoGraphEntry;
+};
+
+const resourceToEntry = (resource: AnyResource): TopoGraphEntry => {
+  const entry: Record<string, unknown> = {
+    exampleCount: 0,
+    id: resource.id,
+    kind: 'resource',
+    surfaces: [],
+  };
+
+  if (resource.description !== undefined) {
+    entry['description'] = resource.description;
+  }
+  if (resource.health !== undefined) {
+    entry['healthcheck'] = true;
+  }
+
+  return sortKeys(entry) as unknown as TopoGraphEntry;
+};
+
+const entityToEntry = (entity: AnyEntity): TopoGraphEntry => {
+  const entry: Record<string, unknown> = {
+    exampleCount: entity.examples?.length ?? 0,
+    id: entity.name,
+    identity: entity.identity,
+    kind: 'entity',
+    surfaces: [],
+  };
+
+  addEntitySchema(entry, entity);
+
+  const references = getEntityReferences(entity);
+  if (references.length > 0) {
+    entry['references'] = references;
+  }
+
+  return sortKeys(entry) as unknown as TopoGraphEntry;
+};
+
+const assertEstablishedTopo = (topo: Topo): void => {
+  const validated = validateEstablishedTopo(topo);
+  if (validated.isErr()) {
+    throw validated.error;
+  }
+};
+
+const collectEntries = (
+  topo: Topo,
+  surfaceAliases: CliSurfaceBindingAliases | undefined
+): TopoGraphEntry[] => {
+  const signalRelations = collectSignalGraphRelations(topo);
+  return [
+    ...[...topo.entities.values()].map((entity) => entityToEntry(entity)),
+    ...[...topo.trails.values()].map((trail) =>
+      trailToEntry(
+        trail as Trail<unknown, unknown, unknown>,
+        topo.layers,
+        surfaceAliases
+      )
+    ),
+    ...[...topo.signals.values()].map((signal) =>
+      signalToEntry(
+        signal as Signal<unknown>,
+        signalRelations.get(signal.id) ?? EMPTY_SIGNAL_RELATIONS
+      )
+    ),
+    ...[...topo.resources.values()].map((resource) =>
+      resourceToEntry(resource)
+    ),
+  ];
+};
+
+/**
+ * Derive a deterministic topo graph from a Topo.
+ *
+ * Entries are sorted alphabetically by id. Object keys within each entry
+ * are sorted lexicographically for stable serialization.
+ */
+export const deriveTopoGraph = (
+  topo: Topo,
+  options?: DeriveTopoGraphOptions
+): TopoGraph => {
+  assertEstablishedTopo(topo);
+  const surfaceAliases = resolveCliAliasInputsFromOverlays(
+    topo,
+    options?.overlays
+  );
+  const sorted = collectEntries(topo, surfaceAliases).toSorted((a, b) =>
+    a.id.localeCompare(b.id)
+  );
+  const activationSources = collectActivationSourceCatalog(topo);
+  const activationEdges = collectActivationGraphEdges(topo);
+  const trailheads = resolveTrailheadEntriesFromOverlays(
+    topo,
+    options?.overlays
+  );
+  const overlays = collectTopoGraphOverlays(topo, options?.overlays);
+  const library = deriveTopoGraphLibrary(topo);
+
+  return {
+    activationGraph: buildActivationGraph(activationEdges, activationSources),
+    activationSources: Object.fromEntries(
+      activationSources.map((source) => [source.key, source])
+    ),
+    entries: sorted,
+    ...(trailheads === undefined ? {} : { trailheads }),
+    ...(overlays === undefined ? {} : { overlays }),
+    generatedAt: new Date().toISOString(),
+    library,
+    topoGraphSchemaVersion: TOPO_GRAPH_SCHEMA_VERSION,
+  };
+};