@untangle-code/file-graph 0.0.0-stage → 0.1.1

package/src/resolve/resolvers.ts

@@ -0,0 +1,468 @@
+/**
+ * Die einzelnen Schritte der Resolver-Pipeline (architecture.md §16.2).
+ *
+ * Jeder Resolver ist rein: gleiche Eingabe, gleiche Ausgabe, kein
+ * Dateisystem, keine Uhr. Er liefert entweder ein Ergebnis (Treffer,
+ * externes Ziel oder benannter Fehlschlag) oder `null` — und `null` heisst
+ * genau „nicht meine Zustaendigkeit", nie „nicht gefunden". Diese
+ * Unterscheidung ist der Grund, warum ein nicht aufloesbarer Import am Ende
+ * einen SPRECHENDEN Grund traegt statt eines pauschalen „unresolved" (E4).
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+
+import { dirnameOf, isRelativeSpecifier, joinRelative, normalizePath } from "../paths.js";
+import type { ImportResolverV1, ResolveContextV1, ResolveResultV1 } from "../types.js";
+
+import { probeCandidates } from "./candidates.js";
+import type { SubpathResolution } from "./package-exports.js";
+import {
+  resolvePackageImports,
+  resolvePackageSubpath,
+  splitPackageSpecifier,
+} from "./package-exports.js";
+
+/**
+ * Modulnamen, die die Laufzeit selbst mitbringt. Bewusst als Liste und nicht
+ * ueber `node:module`s `builtinModules`: die Liste haengt sonst von der
+ * Node-Version der ANALYSIERENDEN Maschine ab, und dieselbe Codebasis haette
+ * je nach Rechner eine andere Import-Resolution-Rate.
+ */
+export const RUNTIME_BUILTIN_MODULES = new Set([
+  "assert",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "diagnostics_channel",
+  "dns",
+  "domain",
+  "events",
+  "fs",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "repl",
+  "stream",
+  "string_decoder",
+  "sys",
+  "timers",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib",
+]);
+
+/** Baut ein `unresolved`-Ergebnis mit Pflichtdetail und geprueften Kandidaten. */
+function unresolved(
+  reason: Extract<ResolveResultV1, { status: "unresolved" }>["reason"],
+  detail: string,
+  tried: readonly string[] = [],
+): ResolveResultV1 {
+  return {
+    status: "unresolved",
+    reason,
+    detail,
+    ...(tried.length > 0 ? { rejectedCandidates: [...tried].sort(compareCodepoints) } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 1. Relative Pfade
+// ---------------------------------------------------------------------------
+
+export const relativePathResolver: ImportResolverV1 = {
+  name: "relative-path",
+  supports(specifier) {
+    return isRelativeSpecifier(specifier);
+  },
+  resolve(specifier, context) {
+    const base = joinRelative(dirnameOf(context.fromPath), specifier);
+    if (base === null) {
+      return unresolved(
+        "target_file_not_found",
+        `relative specifier "${specifier}" from "${context.fromPath}" points above the repository root`,
+      );
+    }
+    const probe = probeCandidates(context, context.fromRepoId, base);
+    if (probe.path === null) {
+      return unresolved(
+        "target_file_not_found",
+        `no file matched relative specifier "${specifier}" from "${context.fromPath}"`,
+        probe.tried,
+      );
+    }
+    return {
+      status: "resolved",
+      mechanism: "relative-path",
+      targetRepoId: context.fromRepoId,
+      targetPath: probe.path,
+    };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 2. Sprachaliase: Laufzeitmodule und `#`-Subpath-Imports
+// ---------------------------------------------------------------------------
+
+export const runtimeBuiltinResolver: ImportResolverV1 = {
+  name: "runtime-builtin",
+  supports(specifier) {
+    return (
+      specifier.startsWith("node:") || RUNTIME_BUILTIN_MODULES.has(specifier.split("/")[0] ?? "")
+    );
+  },
+  resolve(specifier) {
+    return {
+      status: "external",
+      mechanism: "language-alias",
+      packageName: specifier.startsWith("node:") ? specifier : `node:${specifier}`,
+    };
+  },
+};
+
+export const subpathImportResolver: ImportResolverV1 = {
+  name: "subpath-import",
+  supports(specifier) {
+    return specifier.startsWith("#");
+  },
+  resolve(specifier, context) {
+    const owner = context.fromPackage;
+    if (owner === undefined) {
+      return unresolved(
+        "package_not_in_workspace_catalog",
+        `subpath import "${specifier}" requires an owning package, but "${context.fromPath}" is not assigned to one`,
+      );
+    }
+    const matched = resolvePackageImports(owner, specifier);
+    return targetOrFailure(matched, context, owner.repoId, specifier, "language-alias", owner.name);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 3./4. Projekt-Aliase und konfigurierte Aliase
+// ---------------------------------------------------------------------------
+
+function aliasResolver(
+  name: string,
+  mechanism: "project-alias" | "configured-alias",
+  pick: (
+    context: ResolveContextV1,
+  ) => readonly { pattern: string; targets: string[]; repoId: string; source: string }[],
+): ImportResolverV1 {
+  return {
+    name,
+    supports(specifier, context) {
+      return pick(context).some(
+        (rule) =>
+          rule.repoId === context.fromRepoId && matchAlias(rule.pattern, specifier) !== null,
+      );
+    },
+    resolve(specifier, context) {
+      const tried: string[] = [];
+      for (const rule of pick(context)) {
+        if (rule.repoId !== context.fromRepoId) continue;
+        const captured = matchAlias(rule.pattern, specifier);
+        if (captured === null) continue;
+        for (const target of rule.targets) {
+          const base = target.includes("*") ? target.split("*").join(captured) : target;
+          const probe = probeCandidates(context, context.fromRepoId, base);
+          tried.push(...probe.tried);
+          if (probe.path !== null) {
+            return {
+              status: "resolved",
+              mechanism,
+              targetRepoId: context.fromRepoId,
+              targetPath: probe.path,
+            };
+          }
+        }
+      }
+      return unresolved(
+        "alias_configured_but_target_missing",
+        `an alias rule matched "${specifier}" but none of its targets exists`,
+        tried,
+      );
+    },
+  };
+}
+
+export const projectAliasResolver = aliasResolver(
+  "project-alias",
+  "project-alias",
+  (context) => context.projectAliases,
+);
+
+export const configuredAliasResolver = aliasResolver(
+  "configured-alias",
+  "configured-alias",
+  (context) => context.configuredAliases,
+);
+
+/** `"@app/*"` gegen `"@app/util"` → `"util"`; ohne `*` exakter Vergleich. */
+export function matchAlias(pattern: string, specifier: string): string | null {
+  const starIndex = pattern.indexOf("*");
+  if (starIndex === -1) {
+    return pattern === specifier ? "" : null;
+  }
+  const prefix = pattern.slice(0, starIndex);
+  const suffix = pattern.slice(starIndex + 1);
+  if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix)) {
+    return null;
+  }
+  if (specifier.length < prefix.length + suffix.length) {
+    return null;
+  }
+  return specifier.slice(prefix.length, specifier.length - suffix.length);
+}
+
+// ---------------------------------------------------------------------------
+// 5. Workspace-Paketkatalog (architecture.md §16.3)
+// ---------------------------------------------------------------------------
+
+export const workspacePackageResolver: ImportResolverV1 = {
+  name: "workspace-package",
+  supports(specifier, context) {
+    const split = splitPackageSpecifier(specifier);
+    return split !== null && context.packageCatalog.has(split.name);
+  },
+  resolve(specifier, context) {
+    const split = splitPackageSpecifier(specifier);
+    if (split === null) {
+      return unresolved(
+        "no_resolver_supports_specifier",
+        `"${specifier}" is not a usable package specifier`,
+      );
+    }
+    // Aus der Sicht des IMPORTIERENDEN Repositories nachschlagen: derselbe
+    // Paketname kann in mehreren Repositories eines Workspace liegen, und
+    // gemeint ist dann zuerst das eigene.
+    const lookup = context.packageCatalog.lookup(context.fromRepoId, split.name);
+    if (lookup.status === "absent") {
+      return unresolved(
+        "package_not_in_workspace_catalog",
+        `package "${split.name}" is not part of the workspace catalog`,
+      );
+    }
+    if (lookup.status === "ambiguous") {
+      // NICHT raten. Weder zwei fremde Repositories mit demselben Paketnamen
+      // noch zwei gleichnamige Manifeste im EIGENEN Repository sind ohne
+      // weitere Angabe entscheidbar; eine willkuerlich gewaehlte Kante saehe
+      // wie ein Erfolg aus und zeigte auf das falsche Paket.
+      return unresolved(
+        "ambiguous_candidates",
+        `package "${split.name}" is declared by ${String(lookup.candidates.length)} manifests [${lookup.candidates
+          .map((entry) => `${entry.repoId}:${entry.manifestPath}`)
+          .join(
+            ", ",
+          )}] and none of them is the single candidate for "${context.fromPath}" in repository "${context.fromRepoId}"; the reference cannot be attributed`,
+        lookup.candidates.map((entry) => entry.manifestPath).sort(compareCodepoints),
+      );
+    }
+    const target = lookup.entry;
+    const matched = resolvePackageSubpath(target, split.subpath);
+    const mechanism =
+      matched.status === "target" && matched.via === "exports"
+        ? "package-exports"
+        : "workspace-package";
+    return targetOrFailure(matched, context, target.repoId, specifier, mechanism, target.name);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 6. Installierte Pakete (ausserhalb des Workspace)
+// ---------------------------------------------------------------------------
+
+export const installedPackageResolver: ImportResolverV1 = {
+  name: "installed-package",
+  supports(specifier, context) {
+    const split = splitPackageSpecifier(specifier);
+    if (split === null) return false;
+    return declaredRange(context, split.name) !== null;
+  },
+  resolve(specifier, context) {
+    const split = splitPackageSpecifier(specifier);
+    if (split === null) {
+      return unresolved(
+        "no_resolver_supports_specifier",
+        `"${specifier}" is not a usable package specifier`,
+      );
+    }
+    const range = declaredRange(context, split.name);
+    if (range === null) {
+      return unresolved(
+        "package_not_installed",
+        `package "${split.name}" is declared by no manifest reachable from "${context.fromPath}"`,
+      );
+    }
+    return {
+      status: "external",
+      mechanism: "installed-package",
+      packageName: split.name,
+      declaredVersion: range,
+    };
+  },
+};
+
+function declaredRange(context: ResolveContextV1, packageName: string): string | null {
+  const owner = context.fromPackage;
+  if (owner !== undefined) {
+    const declared = owner.externalDependencies[packageName];
+    if (declared !== undefined) return declared;
+  }
+  // Fallback auf die Wurzel des Repositories: in einem Monorepo stehen
+  // Werkzeuge und geteilte Bibliotheken oft nur dort.
+  for (const entry of context.packageCatalog.all()) {
+    if (entry.repoId !== context.fromRepoId || entry.packageDir !== "") continue;
+    const declared = entry.externalDependencies[packageName];
+    if (declared !== undefined) return declared;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// 7. Python-Module
+// ---------------------------------------------------------------------------
+
+/**
+ * Python schreibt Importe punktiert (`from ..pkg.mod import x` → `"..pkg.mod"`).
+ * Fuehrende Punkte sind relative Schritte nach oben, der Rest ist ein Pfad.
+ * Ohne diesen Resolver waere in einem Python-Teilprojekt JEDER Import
+ * unaufgeloest — mit ihm ist wenigstens der relative Fall exakt.
+ */
+export const pythonModuleResolver: ImportResolverV1 = {
+  name: "python-module",
+  supports(specifier, context) {
+    if (context.fromLanguageId !== "python") return false;
+    return specifier !== "" && !specifier.includes("/");
+  },
+  resolve(specifier, context) {
+    const leadingDots = /^\.+/.exec(specifier)?.[0].length ?? 0;
+    const rest = specifier.slice(leadingDots);
+    const segments = rest === "" ? [] : rest.split(".");
+
+    if (leadingDots > 0) {
+      // Ein Punkt = das eigene Paketverzeichnis, jeder weitere eine Ebene hoeher.
+      let directory: string | null = dirnameOf(context.fromPath);
+      for (let step = 1; step < leadingDots; step += 1) {
+        directory = directory === null ? null : joinRelative(directory, "..");
+      }
+      if (directory === null) {
+        return unresolved(
+          "target_file_not_found",
+          `relative python import "${specifier}" from "${context.fromPath}" points above the repository root`,
+        );
+      }
+      const base = segments.length === 0 ? directory : joinRelative(directory, segments.join("/"));
+      if (base === null) {
+        return unresolved(
+          "target_file_not_found",
+          `relative python import "${specifier}" from "${context.fromPath}" points above the repository root`,
+        );
+      }
+      const probe = probeCandidates(context, context.fromRepoId, base);
+      if (probe.path === null) {
+        return unresolved(
+          "target_file_not_found",
+          `no module file matched relative python import "${specifier}" from "${context.fromPath}"`,
+          probe.tried,
+        );
+      }
+      return {
+        status: "resolved",
+        mechanism: "relative-path",
+        targetRepoId: context.fromRepoId,
+        targetPath: probe.path,
+      };
+    }
+
+    // Absoluter, punktierter Modulpfad: gegen die Repositorywurzel und gegen
+    // jedes Paketverzeichnis des Repositories probieren.
+    const relativePath = segments.join("/");
+    const roots = ["", ...packageDirsOf(context)];
+    const tried: string[] = [];
+    for (const root of roots) {
+      const base = root === "" ? relativePath : joinRelative(root, relativePath);
+      if (base === null) continue;
+      const probe = probeCandidates(context, context.fromRepoId, base);
+      tried.push(...probe.tried);
+      if (probe.path !== null) {
+        return {
+          status: "resolved",
+          mechanism: "language-alias",
+          targetRepoId: context.fromRepoId,
+          targetPath: probe.path,
+        };
+      }
+    }
+    return unresolved(
+      "package_not_installed",
+      `python module "${specifier}" was not found on any module root of repository "${context.fromRepoId}"; it is most likely an installed distribution`,
+      tried,
+    );
+  },
+};
+
+function packageDirsOf(context: ResolveContextV1): string[] {
+  const dirs = new Set<string>();
+  for (const entry of context.packageCatalog.all()) {
+    if (entry.repoId !== context.fromRepoId) continue;
+    if (entry.packageDir !== "") dirs.add(entry.packageDir);
+    if (entry.rootDir !== undefined) dirs.add(entry.rootDir);
+  }
+  return [...dirs].sort(compareCodepoints);
+}
+
+// ---------------------------------------------------------------------------
+// gemeinsame Nachbereitung
+// ---------------------------------------------------------------------------
+
+function targetOrFailure(
+  matched: SubpathResolution,
+  context: ResolveContextV1,
+  targetRepoId: string,
+  specifier: string,
+  mechanism: "package-exports" | "workspace-package" | "language-alias",
+  viaPackageName: string,
+): ResolveResultV1 {
+  if (matched.status === "blocked") {
+    return unresolved("excluded_by_configuration", `${matched.detail} (specifier "${specifier}")`);
+  }
+  if (matched.status === "no_match") {
+    return unresolved("target_file_not_found", `${matched.detail} (specifier "${specifier}")`);
+  }
+  const probe = probeCandidates(context, targetRepoId, normalizePath(matched.target));
+  if (probe.path === null) {
+    return unresolved(
+      "target_file_not_found",
+      `package "${viaPackageName}" maps "${specifier}" to "${matched.target}", but no such file is indexed`,
+      probe.tried,
+    );
+  }
+  return {
+    status: "resolved",
+    mechanism,
+    targetRepoId,
+    targetPath: probe.path,
+    viaPackageName,
+  };
+}

package/src/restore.ts

@@ -0,0 +1,201 @@
+/**
+ * Der LESEPFAD des Dateigraphen: aus einem Abbild (`FileGraphSnapshotV1`)
+ * wieder einen abfragbaren Graphen machen.
+ *
+ * WARUM ES DAS BRAUCHT: `untangle index` baut den Graphen und legt ihn ueber
+ * `writeGraphSnapshot` ab. Bis hierher gab es nur `FileDependencyGraph.build`
+ * — und der braucht die ROHIMPORTE jeder Datei, die im Abbild gar nicht
+ * stehen (das Abbild traegt fertige Kanten, keine Spezifizierer mit
+ * Quellpositionen). Ein Leser haette den Graphen also neu bauen muessen, was
+ * ohne die Quelldateien nicht geht, oder sich eine eigene Traversierung
+ * schreiben muessen — die zweite Wahrheit ueber Zyklen und Budgets, die
+ * `traverse.ts` gerade verhindert.
+ *
+ * WAS EIN ZURUECKGELADENER GRAPH KANN UND WAS NICHT — und warum das hier
+ * ausdruecklich steht statt in einer Fussnote:
+ *
+ *   KANN:  Knoten, Kanten, Metriken, Topologie, Skip-Ledger, Traversierung in
+ *          beide Richtungen mit Budget, Zyklenmeldung und Abschneidegrund.
+ *   KANN NICHT: `applyChanges`. Fortschreiben heisst Kanten NEU AUFLOESEN,
+ *          und dafuer braucht es die Rohimporte samt Quellpositionen. Sie
+ *          fehlen im Abbild. Der zurueckgeladene Graph bietet die Methode
+ *          deshalb gar nicht erst an, statt sie mit halber Eingabe falsch
+ *          auszufuehren (E4).
+ */
+import type {
+  FileEdgeV1,
+  FileGraphMetricsV1,
+  FileNodeV1,
+  SkipLedgerV1,
+  TraversalDirection,
+  TraversalLimitsV1,
+} from "@untangle-code/domain";
+import { compareCodepoints } from "@untangle-code/domain";
+
+import { compareEdges } from "./edges.js";
+import type { AdjacencyV1 } from "./metrics.js";
+import { buildAdjacency } from "./metrics.js";
+import { normalizePath } from "./paths.js";
+import type { FileGraphNeighborhoodV1, MonotonicClock } from "./traverse.js";
+import { traverseFileGraph } from "./traverse.js";
+import type { FileGraphSnapshotV1, FileTraversalResultV1, WorkspaceTopologyV1 } from "./types.js";
+
+/**
+ * Ein aus einem Abbild zurueckgeladener Dateigraph — lesend.
+ *
+ * Die Abfragemethoden heissen wie die von {@link FileDependencyGraph} und
+ * antworten dasselbe; das ist Absicht, damit ein Aufrufer nicht zwei
+ * Vokabulare lernen muss.
+ */
+export class RestoredFileGraph {
+  private readonly nodesById: Map<string, FileNodeV1>;
+  private readonly edgesById: Map<string, FileEdgeV1>;
+  private readonly edgeIdsByFrom: Map<string, string[]>;
+  private readonly adjacency: AdjacencyV1;
+  private readonly nodeIdsByPath: Map<string, string[]>;
+
+  constructor(readonly snapshot: FileGraphSnapshotV1) {
+    this.nodesById = new Map(snapshot.nodes.map((node) => [node.fileId, node]));
+    this.edgesById = new Map(snapshot.edges.map((edge) => [edge.edgeId, edge]));
+    this.edgeIdsByFrom = new Map();
+    for (const edge of [...snapshot.edges].sort(compareEdges)) {
+      const list = this.edgeIdsByFrom.get(edge.fromFileId);
+      if (list === undefined) this.edgeIdsByFrom.set(edge.fromFileId, [edge.edgeId]);
+      else list.push(edge.edgeId);
+    }
+    const nodeIds = [...this.nodesById.keys()].sort(compareCodepoints);
+    // Aus den KANTEN gebaut, nicht aus `node.dependencies` — dieselbe Quelle,
+    // aus der der gebaute Graph seine Nachbarschaft nimmt. Zwei Wege zu
+    // derselben Aussage waeren zwei Gelegenheiten, verschieden zu antworten.
+    this.adjacency = buildAdjacency(nodeIds, snapshot.edges);
+    this.nodeIdsByPath = new Map();
+    for (const node of snapshot.nodes) {
+      const key = normalizePath(node.filePath);
+      const list = this.nodeIdsByPath.get(key);
+      if (list === undefined) this.nodeIdsByPath.set(key, [node.fileId]);
+      else list.push(node.fileId);
+    }
+  }
+
+  get workspaceId(): string {
+    return this.snapshot.workspaceId;
+  }
+
+  get graphGeneration(): string {
+    return this.snapshot.graphGeneration;
+  }
+
+  get topology(): WorkspaceTopologyV1 {
+    return this.snapshot.topology;
+  }
+
+  nodes(): FileNodeV1[] {
+    return [...this.nodesById.values()].sort((left, right) =>
+      compareCodepoints(left.fileId, right.fileId),
+    );
+  }
+
+  edges(): FileEdgeV1[] {
+    return [...this.edgesById.values()].sort(compareEdges);
+  }
+
+  node(fileId: string): FileNodeV1 | null {
+    return this.nodesById.get(fileId) ?? null;
+  }
+
+  edge(edgeId: string): FileEdgeV1 | null {
+    return this.edgesById.get(edgeId) ?? null;
+  }
+
+  /** Kanten, deren Quelle `fileId` ist, in kanonischer Ordnung. */
+  edgesFrom(fileId: string): FileEdgeV1[] {
+    return (this.edgeIdsByFrom.get(fileId) ?? [])
+      .map((edgeId) => this.edgesById.get(edgeId))
+      .filter((edge): edge is FileEdgeV1 => edge !== undefined)
+      .sort(compareEdges);
+  }
+
+  /**
+   * Alle Dateien dieses Pfades — eine LISTE, weil derselbe repo-relative Pfad
+   * in mehreren Repositories eines Workspace existieren darf. Wer hier einen
+   * einzelnen Knoten zurueckgaebe, muesste heimlich einen auswaehlen.
+   */
+  nodesAtPath(filePath: string): FileNodeV1[] {
+    return (this.nodeIdsByPath.get(normalizePath(filePath)) ?? [])
+      .map((fileId) => this.nodesById.get(fileId))
+      .filter((node): node is FileNodeV1 => node !== undefined)
+      .sort((left, right) => compareCodepoints(left.fileId, right.fileId));
+  }
+
+  metrics(): FileGraphMetricsV1 {
+    return this.snapshot.metrics;
+  }
+
+  skipLedger(): SkipLedgerV1 {
+    return this.snapshot.skipped;
+  }
+
+  /** Woran haenge ich (vorwaerts, ueber `dependencies`). */
+  dependenciesOf(
+    fileId: string,
+    limits?: Partial<TraversalLimitsV1>,
+    now?: MonotonicClock,
+  ): FileTraversalResultV1 {
+    return this.traverse([fileId], {
+      direction: "forward",
+      ...(limits === undefined ? {} : { limits }),
+      ...(now === undefined ? {} : { now }),
+    });
+  }
+
+  /** Wer haengt an mir (rueckwaerts, ueber `dependents`) — die Wirkungsfrage. */
+  dependentsOf(
+    fileId: string,
+    limits?: Partial<TraversalLimitsV1>,
+    now?: MonotonicClock,
+  ): FileTraversalResultV1 {
+    return this.traverse([fileId], {
+      direction: "reverse",
+      ...(limits === undefined ? {} : { limits }),
+      ...(now === undefined ? {} : { now }),
+    });
+  }
+
+  traverse(
+    rootFileIds: readonly string[],
+    options: {
+      direction: TraversalDirection;
+      limits?: Partial<TraversalLimitsV1>;
+      now?: MonotonicClock;
+    },
+  ): FileTraversalResultV1 {
+    const neighborhood: FileGraphNeighborhoodV1 = {
+      adjacency: this.adjacency,
+      edgeIdBetween: (from, to, direction) => this.edgeIdBetween(from, to, direction),
+    };
+    return traverseFileGraph(neighborhood, rootFileIds, options);
+  }
+
+  /** Direkte Nachbarn in Traversierungsrichtung, codepoint-sortiert. */
+  neighborsOf(fileId: string, direction: TraversalDirection): readonly string[] {
+    const map = direction === "forward" ? this.adjacency.forward : this.adjacency.reverse;
+    return map.get(fileId) ?? [];
+  }
+
+  private edgeIdBetween(from: string, to: string, direction: TraversalDirection): string | null {
+    const source = direction === "forward" ? from : to;
+    const target = direction === "forward" ? to : from;
+    for (const edgeId of this.edgeIdsByFrom.get(source) ?? []) {
+      const edge = this.edgesById.get(edgeId);
+      if (edge?.resolution.status === "resolved" && edge.resolution.targetFileId === target) {
+        return edgeId;
+      }
+    }
+    return null;
+  }
+}
+
+/** Kurzform des Zurueckladens. */
+export function restoreFileGraph(snapshot: FileGraphSnapshotV1): RestoredFileGraph {
+  return new RestoredFileGraph(snapshot);
+}