@ontrails/topography 0.2.0

package/src/wayfind/loader.ts

@@ -0,0 +1,443 @@
+import { existsSync } from 'node:fs';
+import {
+  NotFoundError,
+  ValidationError,
+  deriveTrailsDbPath,
+  openReadTrailsDb,
+} from '@ontrails/core';
+import type { TrailsDbLocationOptions } from '@ontrails/core';
+import { createTopoStore, TOPO_STORE_SCHEMA_VERSION } from '../topo-store.js';
+import { deriveSourceFingerprint } from '../source-fingerprint.js';
+import { deriveTopoGraphHash } from '../hash.js';
+import {
+  isTopoArtifactRegenerationError,
+  readLockManifest,
+  readTopoGraph,
+} from '../io.js';
+import { stripTopoGraphForces } from '../forces.js';
+import type {
+  TopoStoreEntityRecord,
+  TopoStoreExportRecord,
+  TopoStoreResourceRecord,
+  TopoStoreSignalDetailRecord,
+  TopoStoreTopoGraphEntryRecord,
+  TopoStoreTopoGraphRecord,
+  TopoStoreTrailDetailRecord,
+  TopoSnapshot,
+} from '../topo-store.js';
+import { TOPO_GRAPH_SCHEMA_VERSION } from '../types.js';
+import type {
+  LockManifest,
+  LockManifestSummary,
+  ReadOptions,
+  TopoGraph,
+} from '../types.js';
+
+import type {
+  WayfinderArtifactStatus,
+  WayfinderArtifactKind,
+  WayfinderStaleReason,
+} from './provenance.js';
+
+export type WayfinderArtifactLoaderOptions = ReadOptions &
+  TrailsDbLocationOptions;
+
+export interface WayfinderTopoStoreLoad {
+  readonly entities: readonly TopoStoreEntityRecord[];
+  readonly entries: readonly TopoStoreTopoGraphEntryRecord[];
+  readonly export: TopoStoreExportRecord | null;
+  readonly path: string;
+  readonly resources: readonly TopoStoreResourceRecord[];
+  readonly schemaVersion: number;
+  readonly signals: readonly TopoStoreSignalDetailRecord[];
+  readonly snapshot: TopoSnapshot;
+  readonly topoGraph: TopoStoreTopoGraphRecord | null;
+  readonly trails: readonly TopoStoreTrailDetailRecord[];
+}
+
+export interface WayfinderArtifactLoad {
+  readonly artifactStatus: WayfinderArtifactStatus;
+  /** @deprecated Use artifactStatus. */
+  readonly freshness: WayfinderArtifactStatus;
+  readonly lockManifest: LockManifest | null;
+  readonly topoGraph: TopoGraph | null;
+  readonly topoStore: WayfinderTopoStoreLoad | null;
+}
+
+const artifactLoad = (
+  load: Omit<WayfinderArtifactLoad, 'freshness'>
+): WayfinderArtifactLoad => ({
+  ...load,
+  freshness: load.artifactStatus,
+});
+
+type ArtifactRead<TValue> =
+  | {
+      readonly kind: 'ok';
+      readonly value: TValue | null;
+    }
+  | {
+      readonly artifact: WayfinderArtifactKind;
+      readonly kind: 'schema-version-drift';
+      readonly message: string;
+    };
+
+const resolveArtifactReadOptions = (
+  options?: WayfinderArtifactLoaderOptions
+): ReadOptions | undefined => {
+  if (options?.dir !== undefined) {
+    return { dir: options.dir };
+  }
+  if (options?.rootDir !== undefined) {
+    return { dir: options.rootDir };
+  }
+  return undefined;
+};
+
+const resolveTopoStoreLocation = (
+  options?: WayfinderArtifactLoaderOptions
+): TrailsDbLocationOptions | undefined => {
+  if (options?.path !== undefined) {
+    return options.rootDir === undefined
+      ? { path: options.path }
+      : { path: options.path, rootDir: options.rootDir };
+  }
+  if (options?.rootDir !== undefined) {
+    return { rootDir: options.rootDir };
+  }
+  if (options?.dir !== undefined) {
+    return undefined;
+  }
+  return {};
+};
+
+const readTopoArtifact = async (
+  options?: WayfinderArtifactLoaderOptions
+): Promise<ArtifactRead<TopoGraph>> => {
+  try {
+    return {
+      kind: 'ok',
+      value: await readTopoGraph(resolveArtifactReadOptions(options)),
+    };
+  } catch (error) {
+    if (isTopoArtifactRegenerationError(error)) {
+      return {
+        artifact: 'topoGraph',
+        kind: 'schema-version-drift',
+        message: error.message,
+      };
+    }
+    throw error;
+  }
+};
+
+const readLockArtifact = async (
+  options?: WayfinderArtifactLoaderOptions
+): Promise<ArtifactRead<LockManifest>> => {
+  try {
+    return {
+      kind: 'ok',
+      value: await readLockManifest(resolveArtifactReadOptions(options)),
+    };
+  } catch (error) {
+    if (isTopoArtifactRegenerationError(error)) {
+      return {
+        artifact: 'lockManifest',
+        kind: 'schema-version-drift',
+        message: error.message,
+      };
+    }
+    throw error;
+  }
+};
+
+const readTopoStoreArtifact = (
+  options?: WayfinderArtifactLoaderOptions
+): ArtifactRead<WayfinderTopoStoreLoad> => {
+  const location = resolveTopoStoreLocation(options);
+  if (location === undefined) {
+    return { kind: 'ok', value: null };
+  }
+  const path = deriveTrailsDbPath(location);
+  if (!existsSync(path)) {
+    return { kind: 'ok', value: null };
+  }
+
+  let actualVersion: number | undefined;
+  let db: ReturnType<typeof openReadTrailsDb> | undefined;
+  try {
+    db = openReadTrailsDb(location);
+    const row = db
+      .query<{ version: number }, [string]>(
+        'SELECT version FROM meta_schema_versions WHERE subsystem = ?'
+      )
+      .get('topo');
+    actualVersion = row?.version;
+  } catch {
+    return {
+      artifact: 'topoStore',
+      kind: 'schema-version-drift',
+      message: `Unsupported trails.db topo store schema; regenerate with \`trails compile\`. Expected ${TOPO_STORE_SCHEMA_VERSION}.`,
+    };
+  } finally {
+    db?.close();
+  }
+
+  if (actualVersion === undefined) {
+    return { kind: 'ok', value: null };
+  }
+
+  if (actualVersion !== TOPO_STORE_SCHEMA_VERSION) {
+    return {
+      artifact: 'topoStore',
+      kind: 'schema-version-drift',
+      message: `Unsupported trails.db topo store schema; regenerate with \`trails compile\`. Expected ${TOPO_STORE_SCHEMA_VERSION}, found ${actualVersion}.`,
+    };
+  }
+
+  const store = createTopoStore(location);
+  let snapshot: TopoSnapshot | undefined;
+  try {
+    snapshot = store.snapshots.latest();
+  } catch (error) {
+    if (error instanceof NotFoundError) {
+      return { kind: 'ok', value: null };
+    }
+    throw error;
+  }
+
+  if (snapshot === undefined) {
+    return { kind: 'ok', value: null };
+  }
+
+  const ref = { snapshotId: snapshot.id };
+  try {
+    return {
+      kind: 'ok',
+      value: {
+        entities: store.entities.list({ snapshot: ref }),
+        entries: store.entries.list({ snapshot: ref }),
+        export: store.exports.get(ref) ?? null,
+        path,
+        resources: store.resources.list({ snapshot: ref }),
+        schemaVersion: TOPO_STORE_SCHEMA_VERSION,
+        signals: store.signals
+          .list({ snapshot: ref })
+          .map((signal) => store.signals.get(signal.id, { snapshot: ref }))
+          .filter(
+            (signal): signal is TopoStoreSignalDetailRecord =>
+              signal !== undefined
+          ),
+        snapshot,
+        topoGraph: store.topoGraph.get(ref) ?? null,
+        trails: store.trails
+          .list({ snapshot: ref })
+          .map((trail) => store.trails.get(trail.id, { snapshot: ref }))
+          .filter(
+            (trail): trail is TopoStoreTrailDetailRecord => trail !== undefined
+          ),
+      },
+    };
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      return {
+        artifact: 'topoStore',
+        kind: 'schema-version-drift',
+        message: `${error.message} Regenerate the Topography store with \`trails compile\`.`,
+      };
+    }
+    throw error;
+  }
+};
+
+const countEntries = (
+  topoGraph: TopoGraph,
+  kind: TopoGraph['entries'][number]['kind']
+): number => topoGraph.entries.filter((entry) => entry.kind === kind).length;
+
+const summarizeTopoGraph = (topoGraph: TopoGraph): LockManifestSummary => ({
+  entities: countEntries(topoGraph, 'entity'),
+  resources: countEntries(topoGraph, 'resource'),
+  signals: countEntries(topoGraph, 'signal'),
+  trails: countEntries(topoGraph, 'trail'),
+});
+
+const summariesEqual = (
+  left: LockManifestSummary,
+  right: LockManifestSummary
+): boolean =>
+  left.entities === right.entities &&
+  left.resources === right.resources &&
+  left.signals === right.signals &&
+  left.trails === right.trails;
+
+const sourceFingerprintReason = (
+  topoStore: WayfinderTopoStoreLoad,
+  options?: WayfinderArtifactLoaderOptions
+): WayfinderStaleReason | undefined => {
+  const recorded = topoStore.snapshot.sourceFingerprint;
+  const rootDir = options?.rootDir;
+  if (recorded === undefined || rootDir === undefined) {
+    return undefined;
+  }
+  const current = deriveSourceFingerprint(rootDir);
+  if (current === recorded) {
+    return undefined;
+  }
+  return {
+    actual: current,
+    expected: recorded,
+    reason: 'topo-store-source-fingerprint-mismatch',
+    snapshotId: topoStore.snapshot.id,
+  };
+};
+
+const staleReasons = (
+  topoGraph: TopoGraph,
+  lockManifest: LockManifest,
+  topoStore: WayfinderTopoStoreLoad
+): readonly WayfinderStaleReason[] => {
+  const reasons: WayfinderStaleReason[] = [];
+  const actualHash = deriveTopoGraphHash(topoGraph);
+  const contractHash = deriveTopoGraphHash(stripTopoGraphForces(topoGraph));
+  const topoArtifact = lockManifest.artifacts.find(
+    (artifact) => artifact.role === 'topo' && artifact.path === 'topo.lock'
+  );
+
+  if (topoArtifact === undefined) {
+    reasons.push({ reason: 'lock-manifest-topo-artifact-missing' });
+  } else if (topoArtifact.sha256 !== actualHash) {
+    reasons.push({
+      actual: actualHash,
+      expected: topoArtifact.sha256,
+      reason: 'lock-manifest-hash-mismatch',
+    });
+  }
+
+  const storeExport = topoStore.export;
+  if (storeExport === null) {
+    reasons.push({ reason: 'topo-store-export-missing' });
+  } else if (storeExport.topoGraphHash !== contractHash) {
+    reasons.push({
+      actual: storeExport.topoGraphHash,
+      expected: contractHash,
+      reason: 'topo-store-hash-mismatch',
+      snapshotId: storeExport.snapshot.id,
+    });
+  }
+
+  const actualSummary = summarizeTopoGraph(topoGraph);
+  if (!summariesEqual(lockManifest.summary, actualSummary)) {
+    reasons.push({
+      actual: actualSummary,
+      expected: lockManifest.summary,
+      reason: 'lock-manifest-summary-mismatch',
+    });
+  }
+
+  return reasons;
+};
+
+export const loadWayfinderArtifacts = async (
+  options?: WayfinderArtifactLoaderOptions
+): Promise<WayfinderArtifactLoad> => {
+  const [topoGraphRead, lockManifestRead, topoStoreRead] = await Promise.all([
+    readTopoArtifact(options),
+    readLockArtifact(options),
+    readTopoStoreArtifact(options),
+  ]);
+
+  if (topoGraphRead.kind === 'schema-version-drift') {
+    return artifactLoad({
+      artifactStatus: {
+        artifact: topoGraphRead.artifact,
+        message: topoGraphRead.message,
+        status: 'schema-version-drift',
+      },
+      lockManifest:
+        lockManifestRead.kind === 'ok' ? lockManifestRead.value : null,
+      topoGraph: null,
+      topoStore: topoStoreRead.kind === 'ok' ? topoStoreRead.value : null,
+    });
+  }
+
+  if (lockManifestRead.kind === 'schema-version-drift') {
+    return artifactLoad({
+      artifactStatus: {
+        artifact: lockManifestRead.artifact,
+        message: lockManifestRead.message,
+        status: 'schema-version-drift',
+      },
+      lockManifest: null,
+      topoGraph: topoGraphRead.value,
+      topoStore: topoStoreRead.kind === 'ok' ? topoStoreRead.value : null,
+    });
+  }
+
+  if (topoStoreRead.kind === 'schema-version-drift') {
+    return artifactLoad({
+      artifactStatus: {
+        artifact: topoStoreRead.artifact,
+        message: topoStoreRead.message,
+        status: 'schema-version-drift',
+      },
+      lockManifest: lockManifestRead.value,
+      topoGraph: topoGraphRead.value,
+      topoStore: null,
+    });
+  }
+
+  const topoGraph = topoGraphRead.value;
+  const lockManifest = lockManifestRead.value;
+  const topoStore = topoStoreRead.value;
+  if (topoGraph === null || lockManifest === null || topoStore === null) {
+    const missing: WayfinderArtifactKind[] = [];
+    if (topoGraph === null) {
+      missing.push('topoGraph');
+    }
+    if (lockManifest === null) {
+      missing.push('lockManifest');
+    }
+    if (topoStore === null) {
+      missing.push('topoStore');
+    }
+    return artifactLoad({
+      artifactStatus: { artifacts: missing, status: 'missing' },
+      lockManifest,
+      topoGraph,
+      topoStore,
+    });
+  }
+
+  const fingerprintReason = sourceFingerprintReason(topoStore, options);
+  const reasons = [
+    ...staleReasons(topoGraph, lockManifest, topoStore),
+    ...(fingerprintReason === undefined ? [] : [fingerprintReason]),
+  ];
+  return artifactLoad({
+    artifactStatus:
+      reasons.length === 0 ? { status: 'fresh' } : { reasons, status: 'stale' },
+    lockManifest,
+    topoGraph,
+    topoStore,
+  });
+};
+
+export const wayfinderTopoGraphSource = (
+  options?: WayfinderArtifactLoaderOptions
+) => ({
+  kind: 'topoGraph' as const,
+  path: `${resolveArtifactReadOptions(options)?.dir ?? '.'}/trails.lock`,
+  schemaVersion: TOPO_GRAPH_SCHEMA_VERSION,
+});
+
+export const wayfinderTopoStoreSource = (
+  options?: WayfinderArtifactLoaderOptions
+) => {
+  const location = resolveTopoStoreLocation(options);
+  return {
+    kind: 'topoStore' as const,
+    ...(location === undefined ? {} : { path: deriveTrailsDbPath(location) }),
+    schemaVersion: TOPO_STORE_SCHEMA_VERSION,
+  };
+};

package/src/wayfind/navigation.ts

@@ -0,0 +1,265 @@
+import { Result } from '@ontrails/core';
+import type { AmbiguousError } from '@ontrails/core';
+import { z } from 'zod';
+
+import type { TopoGraph } from '../types.js';
+import {
+  filterWayfinderEntityRefs,
+  wayfinderEntityFilterSchema,
+} from './filters.js';
+import type {
+  WayfinderEntityFilterInput,
+  WayfinderEntityKind,
+  WayfinderEntityRef,
+} from './filters.js';
+import {
+  edgeTouches,
+  groupNearbyEdges,
+  impactFor,
+  refSummary,
+  relationEdges,
+  resolveEntityRef,
+} from './relations.js';
+import type {
+  ImpactDirection,
+  ImpactOptions,
+  RelationEdge,
+  RelationRef,
+} from './relations.js';
+
+export const wayfinderSourceModeSchema = z.enum(['locked', 'live']);
+
+export type WayfinderSourceMode = z.output<typeof wayfinderSourceModeSchema>;
+
+export const wayfinderResolverSchema = z.enum([
+  'id',
+  'pattern',
+  'query',
+  'file',
+]);
+
+export type WayfinderResolver = z.output<typeof wayfinderResolverSchema>;
+
+export const wayfinderViewSchema = z.enum([
+  'overview',
+  'list',
+  'summary',
+  'describe',
+  'contract',
+  'outline',
+  'map',
+]);
+
+export type WayfinderView = z.output<typeof wayfinderViewSchema>;
+
+export const wayfinderIncludeSchema = z.enum([
+  'adapters',
+  'errors',
+  'examples',
+  'surfaces',
+  'versions',
+]);
+
+export type WayfinderInclude = z.output<typeof wayfinderIncludeSchema>;
+
+export const wayfinderDriftStatusSchema = z.enum([
+  'absent',
+  'aligned',
+  'drifted',
+]);
+
+export type WayfinderDriftStatus = z.output<typeof wayfinderDriftStatusSchema>;
+
+export const wayfinderNavigationPlanSchema = z.object({
+  filters: wayfinderEntityFilterSchema.optional(),
+  include: z.array(wayfinderIncludeSchema).readonly().default([]),
+  limit: z.number().int().positive().max(500).default(100),
+  resolver: wayfinderResolverSchema,
+  source: wayfinderSourceModeSchema.default('locked'),
+  view: wayfinderViewSchema.default('list'),
+});
+
+export type WayfinderNavigationPlan = z.output<
+  typeof wayfinderNavigationPlanSchema
+>;
+
+export interface WayfinderPopulationInput {
+  readonly filters?: WayfinderEntityFilterInput | undefined;
+  readonly kind?: WayfinderEntityKind | undefined;
+  readonly limit: number;
+}
+
+export const resolveWayfinderPopulation = (
+  graph: TopoGraph,
+  input: WayfinderPopulationInput
+): readonly WayfinderEntityRef[] =>
+  filterWayfinderEntityRefs(graph, {
+    ...input.filters,
+    ...(input.kind === undefined ? {} : { kind: input.kind }),
+  }).slice(0, input.limit);
+
+export const wayfinderRelationModeSchema = z.enum([
+  'related',
+  'deps',
+  'impact',
+]);
+
+export type WayfinderRelationMode = z.output<
+  typeof wayfinderRelationModeSchema
+>;
+
+/** @deprecated Use WayfinderRelationMode. */
+export type WayfinderRelationResolver = WayfinderRelationMode;
+
+export interface WayfinderResolvedRelationInput {
+  readonly id: string;
+  readonly filters?: WayfinderEntityFilterInput | undefined;
+  readonly kind?: WayfinderEntityKind | undefined;
+  readonly limit: number;
+  readonly maxDepth: number;
+  readonly mode: WayfinderRelationMode;
+  readonly view?: 'groups' | 'impact' | undefined;
+}
+
+export interface WayfinderResolvedRelations {
+  readonly direction: ImpactDirection;
+  readonly edges: readonly RelationEdge[];
+  readonly groups: ReturnType<typeof groupNearbyEdges>;
+  readonly nodes:
+    | ReturnType<typeof impactFor>['nodes']
+    | readonly RelationRef[];
+  readonly target: RelationRef;
+}
+
+const relationDirection = (mode: WayfinderRelationMode): ImpactDirection => {
+  switch (mode) {
+    case 'related': {
+      return 'both';
+    }
+    case 'deps': {
+      return 'upstream';
+    }
+    case 'impact': {
+      return 'downstream';
+    }
+    default: {
+      mode satisfies never;
+      return 'both';
+    }
+  }
+};
+
+const relationOptions = (
+  input: WayfinderResolvedRelationInput
+): ImpactOptions => ({
+  direction: relationDirection(input.mode),
+  limit: input.limit,
+  maxDepth: input.maxDepth,
+});
+
+const refKey = (ref: RelationRef): string => `${ref.kind}:${ref.id}`;
+
+const filterRelationRefs = (
+  graph: TopoGraph,
+  refs: readonly RelationRef[],
+  filters: WayfinderEntityFilterInput | undefined
+): readonly RelationRef[] => {
+  if (filters === undefined || Object.keys(filters).length === 0) {
+    return refs;
+  }
+  const allowed = new Set(
+    filterWayfinderEntityRefs(graph, filters).map(refKey)
+  );
+  return refs.filter((ref) => allowed.has(refKey(ref)));
+};
+
+const edgeOtherRef = (
+  edge: RelationEdge,
+  target: RelationRef
+): RelationRef | undefined => {
+  if (edge.from.id === target.id && edge.from.kind === target.kind) {
+    return edge.to;
+  }
+  if (edge.to.id === target.id && edge.to.kind === target.kind) {
+    return edge.from;
+  }
+  return undefined;
+};
+
+const filterRelationEdges = (
+  graph: TopoGraph,
+  edges: readonly RelationEdge[],
+  target: RelationRef,
+  filters: WayfinderEntityFilterInput | undefined
+): readonly RelationEdge[] => {
+  if (filters === undefined || Object.keys(filters).length === 0) {
+    return edges;
+  }
+  const allowed = new Set(
+    filterWayfinderEntityRefs(graph, filters).map(refKey)
+  );
+  return edges.filter((edge) => {
+    const other = edgeOtherRef(edge, target);
+    return other !== undefined && allowed.has(refKey(other));
+  });
+};
+
+const filterImpactEdges = (
+  edges: readonly RelationEdge[],
+  target: RelationRef,
+  nodes: readonly RelationRef[],
+  filters: WayfinderEntityFilterInput | undefined
+): readonly RelationEdge[] => {
+  if (filters === undefined || Object.keys(filters).length === 0) {
+    return edges;
+  }
+  const allowed = new Set([refKey(target), ...nodes.map(refKey)]);
+  return edges.filter(
+    (edge) => allowed.has(refKey(edge.from)) && allowed.has(refKey(edge.to))
+  );
+};
+
+export const resolveWayfinderRelations = (
+  graph: TopoGraph,
+  input: WayfinderResolvedRelationInput
+): Result<WayfinderResolvedRelations | undefined, AmbiguousError> => {
+  const target = resolveEntityRef(graph, input);
+  if (target.isErr()) {
+    return target;
+  }
+  if (target.value === undefined) {
+    return Result.ok();
+  }
+  const summary = refSummary(target.value);
+  if (input.mode === 'related' && input.view === 'groups') {
+    const edges = filterRelationEdges(
+      graph,
+      relationEdges(graph).filter((edge) => edgeTouches(edge, summary)),
+      summary,
+      input.filters
+    );
+    const groups = groupNearbyEdges(edges, summary);
+    return Result.ok({
+      direction: 'both',
+      edges,
+      groups,
+      nodes: groups.flatMap((group) => group.refs),
+      target: summary,
+    });
+  }
+  const resolved = impactFor(graph, relationOptions(input), summary);
+  const nodes = filterRelationRefs(graph, resolved.nodes, input.filters);
+  const edges = filterImpactEdges(
+    resolved.edges,
+    summary,
+    nodes,
+    input.filters
+  );
+  return Result.ok({
+    direction: relationDirection(input.mode),
+    edges,
+    groups: [],
+    nodes,
+    target: summary,
+  });
+};