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

package/src/topology/manifest.ts

@@ -0,0 +1,132 @@
+/**
+ * Paketmanifest (`package.json`) → auswertbare Form.
+ *
+ * Nur die Felder, die fuer Aufloesung und Topologie zaehlen. Alles andere
+ * bleibt unangetastet; `exports`/`imports` werden ABSICHTLICH als `unknown`
+ * durchgereicht, weil ihre Grammatik (verschachtelte Bedingungen, Arrays,
+ * Subpath-Muster) im Resolver ausgewertet wird und eine Vorab-Normalisierung
+ * hier Information vernichten wuerde.
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+
+import { isJsonObject, parseJsonc, stringField, stringRecordField } from "./jsonc.js";
+
+/** Abhaengigkeitsbloecke eines Manifests, in Auswertungsreihenfolge. */
+export const DEPENDENCY_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+] as const;
+
+export type DependencyField = (typeof DEPENDENCY_FIELDS)[number];
+
+/** Ausgewertetes Manifest. */
+export interface ManifestV1 {
+  name?: string;
+  version?: string;
+  main?: string;
+  module?: string;
+  types?: string;
+  exports?: unknown;
+  imports?: unknown;
+  /** Block → (Paketname → Versionsangabe). */
+  dependencies: Record<DependencyField, Record<string, string>>;
+  /** `workspaces`-Feld (npm/Yarn), falls vorhanden. */
+  workspaceGlobs: string[];
+}
+
+export type ManifestParseResult = { ok: true; manifest: ManifestV1 } | { ok: false; error: string };
+
+/** Liest ein Manifest. Wirft nie — ein kaputtes Manifest ist ein Befund, kein Absturz. */
+export function parseManifest(text: string): ManifestParseResult {
+  const parsed = parseJsonc(text);
+  if (!parsed.ok) {
+    return { ok: false, error: parsed.error };
+  }
+  if (!isJsonObject(parsed.value)) {
+    return { ok: false, error: "manifest root is not a JSON object" };
+  }
+  const root = parsed.value;
+  const dependencies = {} as Record<DependencyField, Record<string, string>>;
+  for (const field of DEPENDENCY_FIELDS) {
+    dependencies[field] = stringRecordField(root, field);
+  }
+  const manifest: ManifestV1 = {
+    dependencies,
+    workspaceGlobs: readWorkspaceGlobs(root),
+  };
+  const name = stringField(root, "name");
+  if (name !== undefined) manifest.name = name;
+  const version = stringField(root, "version");
+  if (version !== undefined) manifest.version = version;
+  const main = stringField(root, "main");
+  if (main !== undefined) manifest.main = main;
+  const moduleField = stringField(root, "module");
+  if (moduleField !== undefined) manifest.module = moduleField;
+  const types = stringField(root, "types");
+  if (types !== undefined) manifest.types = types;
+  if (root["exports"] !== undefined) manifest.exports = root["exports"];
+  if (root["imports"] !== undefined) manifest.imports = root["imports"];
+  return { ok: true, manifest };
+}
+
+/**
+ * `workspaces` kennt zwei Schreibweisen: eine Liste von Globmustern und ein
+ * Objekt mit `packages`. Beide werden gelesen — die Objektform stammt aus
+ * Yarn und faellt sonst still unter den Tisch.
+ */
+function readWorkspaceGlobs(root: Record<string, unknown>): string[] {
+  const value = root["workspaces"];
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === "string");
+  }
+  if (isJsonObject(value) && Array.isArray(value["packages"])) {
+    return (value["packages"] as unknown[]).filter(
+      (entry): entry is string => typeof entry === "string",
+    );
+  }
+  return [];
+}
+
+/**
+ * True, wenn eine Versionsangabe auf ein Paket DESSELBEN Workspace zeigt.
+ *
+ * `workspace:*` ist das pnpm-/Yarn-Protokoll. `link:` und `file:` zeigen
+ * ebenfalls in den Workspace, sind aber keine Katalogeintraege — sie werden
+ * hier bewusst NICHT als Workspace-Abhaengigkeit gezaehlt, weil ihr Ziel ein
+ * Pfad und kein Paketname ist; der Pfadfall gehoert in den Resolver, nicht in
+ * die Topologie.
+ */
+export function isWorkspaceProtocol(range: string): boolean {
+  return range.startsWith("workspace:");
+}
+
+/** Alle deklarierten Abhaengigkeiten, dedupliziert und codepoint-sortiert. */
+export function declaredDependencyNames(manifest: ManifestV1): string[] {
+  const names = new Set<string>();
+  for (const field of DEPENDENCY_FIELDS) {
+    for (const name of Object.keys(manifest.dependencies[field])) {
+      names.add(name);
+    }
+  }
+  return [...names].sort(compareCodepoints);
+}
+
+/**
+ * Versionsangabe eines Pakets im ersten Block, der es nennt. Reihenfolge ist
+ * `DEPENDENCY_FIELDS`, damit dieselbe Antwort unabhaengig von der
+ * Schluesselreihenfolge im JSON herauskommt.
+ */
+export function declaredRangeOf(
+  manifest: ManifestV1,
+  packageName: string,
+): { field: DependencyField; range: string } | null {
+  for (const field of DEPENDENCY_FIELDS) {
+    const range = manifest.dependencies[field][packageName];
+    if (range !== undefined) {
+      return { field, range };
+    }
+  }
+  return null;
+}

package/src/topology/project-config.ts

@@ -0,0 +1,183 @@
+/**
+ * Projektkonfiguration (`tsconfig.json` und Verwandte) → Pfad-Aliase und
+ * Ausgabeverzeichnisse.
+ *
+ * Zwei Dinge braucht der Dateigraph daraus:
+ *
+ * 1. `baseUrl` + `paths` — die Pfad-Aliase, die Schritt 3 der Resolver-
+ *    Pipeline (architecture.md §16.2) aufloest.
+ * 2. `rootDir` + `outDir` — die Rueckabbildung von Build-Ausgabe auf Quelle.
+ *    Ohne sie zeigt jeder Workspace-Import ueber eine `exports`-Map auf
+ *    `dist/index.js`, also auf eine Datei, die im Quellindex gar nicht
+ *    vorkommt; die Kante waere dann „unresolved", obwohl das Ziel bekannt
+ *    ist. Mit ihr wird `dist/index.js` zu `src/index.ts`.
+ *
+ * `extends` wird verfolgt, weil in einem Monorepo praktisch jede
+ * Paketkonfiguration von einer gemeinsamen Basis erbt und `paths` fast immer
+ * genau dort steht.
+ */
+import { dirnameOf, joinRelative, normalizePath } from "../paths.js";
+
+import { isJsonObject, parseJsonc, stringField } from "./jsonc.js";
+
+/** Ausgewertete Projektkonfiguration eines Verzeichnisses. */
+export interface ProjectConfigV1 {
+  /** repo-relativer Pfad der Konfigurationsdatei. */
+  configPath: string;
+  /** repo-relativ aufgeloester `baseUrl`; `undefined`, wenn nicht gesetzt. */
+  baseUrl?: string;
+  /** Aliasmuster → repo-relative Ziele. */
+  paths: Record<string, string[]>;
+  /** repo-relativ aufgeloester `rootDir`. */
+  rootDir?: string;
+  /** repo-relativ aufgeloester `outDir`. */
+  outDir?: string;
+  /** Konfigurationen, von denen geerbt wurde, in Erbfolge. */
+  extendsChain: string[];
+}
+
+/** Eine einzelne, bereits gelesene Konfigurationsdatei. */
+export interface RawProjectConfigV1 {
+  /** repo-relativer Pfad. */
+  path: string;
+  text: string;
+}
+
+export type ProjectConfigResult =
+  { ok: true; config: ProjectConfigV1; warnings: string[] } | { ok: false; error: string };
+
+/**
+ * Wertet eine Projektkonfiguration samt `extends`-Kette aus.
+ *
+ * `readConfig` liefert den Text einer Konfigurationsdatei oder `null`, wenn es
+ * sie nicht gibt. Ein fehlendes `extends`-Ziel ist KEIN Abbruch, sondern eine
+ * Warnung im Ergebnis — sonst verlieren wir wegen einer nicht eingecheckten
+ * Basisdatei die Aliase des ganzen Pakets, ohne dass es jemand merkt (E4).
+ */
+export function resolveProjectConfig(
+  configPath: string,
+  readConfig: (path: string) => string | null,
+): ProjectConfigResult {
+  const warnings: string[] = [];
+  const extendsChain: string[] = [];
+  const seen = new Set<string>();
+
+  // Von der Wurzel der Erbkette zum konkreten Projekt hin sammeln, damit
+  // spaetere (spezifischere) Werte frueher gelesene ueberschreiben.
+  const layers: { path: string; options: Record<string, unknown> }[] = [];
+
+  let current: string | null = normalizePath(configPath);
+  let depth = 0;
+  while (current !== null) {
+    if (seen.has(current)) {
+      return { ok: false, error: `circular "extends" chain at ${current}` };
+    }
+    seen.add(current);
+    depth += 1;
+    if (depth > 32) {
+      return { ok: false, error: `"extends" chain longer than 32 at ${current}` };
+    }
+    const text = readConfig(current);
+    if (text === null) {
+      if (layers.length === 0) {
+        return { ok: false, error: `configuration file not found: ${current}` };
+      }
+      warnings.push(`extends target not found: ${current}`);
+      break;
+    }
+    const parsed = parseJsonc(text);
+    if (!parsed.ok) {
+      if (layers.length === 0) {
+        return { ok: false, error: `${current}: ${parsed.error}` };
+      }
+      warnings.push(`extends target unreadable (${current}): ${parsed.error}`);
+      break;
+    }
+    if (!isJsonObject(parsed.value)) {
+      warnings.push(`${current}: root is not a JSON object`);
+      break;
+    }
+    const root = parsed.value;
+    const options = isJsonObject(root["compilerOptions"]) ? root["compilerOptions"] : {};
+    layers.push({ path: current, options });
+
+    const extendsValue = stringField(root, "extends");
+    if (extendsValue === undefined) {
+      break;
+    }
+    const next = joinRelative(dirnameOf(current), extendsValue);
+    if (next === null) {
+      warnings.push(`extends target escapes the repository root: ${extendsValue}`);
+      break;
+    }
+    extendsChain.push(next);
+    // `extends` ohne Erweiterung meint eine JSON-Datei.
+    current = /\.json$/i.test(next) ? next : `${next}.json`;
+  }
+
+  const config: ProjectConfigV1 = {
+    configPath: normalizePath(configPath),
+    paths: {},
+    extendsChain,
+  };
+
+  // Von der Basis (letzte Schicht) zum Projekt (erste Schicht) anwenden.
+  for (const layer of [...layers].reverse()) {
+    const dir = dirnameOf(layer.path);
+    const baseUrl = stringField(layer.options, "baseUrl");
+    if (baseUrl !== undefined) {
+      const resolved = joinRelative(dir, baseUrl);
+      if (resolved === null) {
+        warnings.push(`baseUrl escapes the repository root in ${layer.path}: ${baseUrl}`);
+      } else {
+        config.baseUrl = resolved;
+      }
+    }
+    const rootDir = stringField(layer.options, "rootDir");
+    if (rootDir !== undefined) {
+      const resolved = joinRelative(dir, rootDir);
+      if (resolved === null) {
+        warnings.push(`rootDir escapes the repository root in ${layer.path}: ${rootDir}`);
+      } else {
+        config.rootDir = resolved;
+      }
+    }
+    const outDir = stringField(layer.options, "outDir");
+    if (outDir !== undefined) {
+      const resolved = joinRelative(dir, outDir);
+      if (resolved === null) {
+        warnings.push(`outDir escapes the repository root in ${layer.path}: ${outDir}`);
+      } else {
+        config.outDir = resolved;
+      }
+    }
+    const pathsValue = layer.options["paths"];
+    if (isJsonObject(pathsValue)) {
+      // `paths` ist relativ zu `baseUrl`, ersatzweise zum Verzeichnis der
+      // Datei, in der `paths` steht (TypeScript-Verhalten seit 4.1).
+      const anchor = config.baseUrl ?? dir;
+      for (const [pattern, targets] of Object.entries(pathsValue)) {
+        if (!Array.isArray(targets)) {
+          warnings.push(`paths["${pattern}"] in ${layer.path} is not an array`);
+          continue;
+        }
+        const resolvedTargets: string[] = [];
+        for (const target of targets) {
+          if (typeof target !== "string") {
+            warnings.push(`paths["${pattern}"] in ${layer.path} contains a non-string target`);
+            continue;
+          }
+          const resolved = joinRelative(anchor, target);
+          if (resolved === null) {
+            warnings.push(`paths["${pattern}"] target escapes the repository root: ${target}`);
+            continue;
+          }
+          resolvedTargets.push(resolved);
+        }
+        config.paths[pattern] = resolvedTargets;
+      }
+    }
+  }
+
+  return { ok: true, config, warnings };
+}

package/src/topology/workspace-definition.ts

@@ -0,0 +1,115 @@
+/**
+ * Workspace-Definition und Globabgleich.
+ *
+ * Quellen fuer die Liste der Teilprojekte, in dieser Reihenfolge:
+ * 1. `pnpm-workspace.yaml` (`packages:`) — das pnpm-Protokoll;
+ * 2. `workspaces` im Wurzelmanifest (npm/Yarn).
+ *
+ * Der Globabgleich deckt genau das ab, was Workspace-Definitionen wirklich
+ * benutzen: `*` (ein Segment), `**` (beliebig viele Segmente), `?` (ein
+ * Zeichen) und ein fuehrendes `!` als Ausschluss. Ein vollstaendiger
+ * Glob-Dialekt waere hier ueberdimensioniert — und ein NICHT unterstuetztes
+ * Muster wird gemeldet statt still ignoriert (E4).
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+import { parse as parseYaml } from "yaml";
+
+import { normalizePath } from "../paths.js";
+
+export type WorkspaceDefinitionResult =
+  { ok: true; globs: string[] } | { ok: false; error: string };
+
+/** Liest die `packages:`-Liste einer pnpm-Workspace-Definition. */
+export function parsePnpmWorkspace(text: string): WorkspaceDefinitionResult {
+  let document: unknown;
+  try {
+    document = parseYaml(text) as unknown;
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+  if (typeof document !== "object" || document === null || Array.isArray(document)) {
+    return { ok: false, error: "workspace document root is not a mapping" };
+  }
+  const packages = (document as Record<string, unknown>)["packages"];
+  if (packages === undefined) {
+    return { ok: false, error: 'workspace document has no "packages" list' };
+  }
+  if (!Array.isArray(packages)) {
+    return { ok: false, error: '"packages" is not a list' };
+  }
+  const globs = packages.filter((entry): entry is string => typeof entry === "string");
+  if (globs.length !== packages.length) {
+    return { ok: false, error: '"packages" contains non-string entries' };
+  }
+  return { ok: true, globs };
+}
+
+/** Zerlegt eine Globliste in Einschluesse und Ausschluesse. */
+export interface GlobSelectionV1 {
+  include: string[];
+  exclude: string[];
+}
+
+export function splitGlobs(globs: readonly string[]): GlobSelectionV1 {
+  const include: string[] = [];
+  const exclude: string[] = [];
+  for (const glob of globs) {
+    if (glob.startsWith("!")) {
+      exclude.push(normalizePath(glob.slice(1)));
+    } else {
+      include.push(normalizePath(glob));
+    }
+  }
+  return { include: include.sort(compareCodepoints), exclude: exclude.sort(compareCodepoints) };
+}
+
+/**
+ * Uebersetzt ein Workspace-Glob in einen Regulaerausdruck ueber Pfadsegmente.
+ *
+ * `**` frisst beliebig viele Segmente einschliesslich null, `*` genau ein
+ * Segment ohne `/`, `?` genau ein Zeichen ohne `/`. Alles andere wird
+ * woertlich verglichen.
+ */
+export function globToRegExp(glob: string): RegExp {
+  const normalized = normalizePath(glob);
+  let pattern = "";
+  let index = 0;
+  while (index < normalized.length) {
+    const char = normalized[index] as string;
+    if (char === "*") {
+      const isDoubleStar = normalized[index + 1] === "*";
+      if (isDoubleStar) {
+        // `a/**/b` und `a/**` sollen auch `a/b` bzw. `a` treffen.
+        if (normalized[index + 2] === "/") {
+          pattern += "(?:.*/)?";
+          index += 3;
+          continue;
+        }
+        pattern += ".*";
+        index += 2;
+        continue;
+      }
+      pattern += "[^/]*";
+      index += 1;
+      continue;
+    }
+    if (char === "?") {
+      pattern += "[^/]";
+      index += 1;
+      continue;
+    }
+    pattern += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    index += 1;
+  }
+  return new RegExp(`^${pattern}$`);
+}
+
+/** True, wenn `directory` von der Globauswahl erfasst wird. */
+export function matchesGlobSelection(selection: GlobSelectionV1, directory: string): boolean {
+  const candidate = normalizePath(directory);
+  const included = selection.include.some((glob) => globToRegExp(glob).test(candidate));
+  if (!included) {
+    return false;
+  }
+  return !selection.exclude.some((glob) => globToRegExp(glob).test(candidate));
+}

package/src/traverse.ts

@@ -0,0 +1,232 @@
+/**
+ * Die Traversierung des Dateigraphen als FREIE FUNKTION — losgeloest von der
+ * Frage, ob der Graph gerade gebaut oder aus einem Abbild zurueckgeladen
+ * wurde.
+ *
+ * WARUM SIE HIER STEHT UND NICHT MEHR IN `graph.ts`: Der Lesepfad
+ * (`readGraphSnapshot` → `restoreFileGraph`) braucht exakt dieselbe
+ * Traversierung wie der Schreibpfad. Eine zweite, „nur fuer die Anzeige"
+ * geschriebene Fassung waere eine zweite Wahrheit ueber Zyklen und Budgets —
+ * und Zyklenmeldung wie Abschneidegrund sind genau die Aussagen, an denen ein
+ * Werkzeug luegt, wenn es sie zweimal implementiert. `FileDependencyGraph`
+ * und `RestoredFileGraph` rufen deshalb DIESELBE Funktion.
+ *
+ * Die drei Zusagen der Traversierung sind unveraendert:
+ *
+ * 1. Tiefensuche, nicht Breitensuche: nur ein Pfadstapel kann echte Zyklen
+ *    BENENNEN statt bloss „hier war ich schon" zu vermerken.
+ * 2. Ein Zyklus wird gemeldet, nicht aufgebrochen.
+ * 3. Ein abgeschnittenes Ergebnis sagt, DASS und WARUM es abgeschnitten ist
+ *    (`truncated` + `truncationReason`, E4). Die Tiefengrenze beschneidet nur
+ *    den betrachteten Ast; ein erschoepftes GLOBALES Budget beendet den Lauf
+ *    und nennt die nie angefassten Wurzeln.
+ */
+import type { TraversalDirection, TraversalLimitsV1 } from "@untangle-code/domain";
+import { uniqueSortedByCodepoints } from "@untangle-code/domain";
+
+import type { AdjacencyV1 } from "./metrics.js";
+import type { FileTraversalResultV1 } from "./types.js";
+
+/** Standardbudgets einer Traversierung. */
+export const DEFAULT_TRAVERSAL_LIMITS: TraversalLimitsV1 = {
+  maxDepth: 16,
+  maxNodes: 5_000,
+  maxEdges: 20_000,
+  maxWallTimeMs: 5_000,
+};
+
+/** Uhr fuer Zeitbudgets. Injizierbar, damit Tests nicht auf echte Zeit warten. */
+export type MonotonicClock = () => number;
+
+/**
+ * Was die Traversierung vom Graphen wissen muss — und sonst nichts.
+ *
+ * `edgeIdBetween` ist bewusst eine Funktion und keine fertige Karte: der
+ * gebaute Graph beantwortet sie ueber seinen Kantenindex, der
+ * zurueckgeladene ueber die Kanten des Abbilds. Beide antworten dasselbe.
+ */
+export interface FileGraphNeighborhoodV1 {
+  readonly adjacency: AdjacencyV1;
+  edgeIdBetween(from: string, to: string, direction: TraversalDirection): string | null;
+}
+
+export interface TraverseFileGraphOptionsV1 {
+  direction: TraversalDirection;
+  limits?: Partial<TraversalLimitsV1>;
+  now?: MonotonicClock;
+}
+
+function defaultClock(): number {
+  // `performance.now()` ist monoton und wird ausschliesslich fuer die
+  // Budgetentscheidung benutzt — kein Zeitwert landet je in Ergebnisdaten.
+  return performance.now();
+}
+
+/** Tiefensuche mit Budget und Zyklenmeldung. */
+export function traverseFileGraph(
+  neighborhood: FileGraphNeighborhoodV1,
+  rootFileIds: readonly string[],
+  options: TraverseFileGraphOptionsV1,
+): FileTraversalResultV1 {
+  const limits: TraversalLimitsV1 = { ...DEFAULT_TRAVERSAL_LIMITS, ...options.limits };
+  const now = options.now ?? defaultClock;
+  const startedAt = now();
+  const neighbors =
+    options.direction === "forward"
+      ? neighborhood.adjacency.forward
+      : neighborhood.adjacency.reverse;
+
+  const roots = uniqueSortedByCodepoints([...rootFileIds]);
+  const visited = new Set<string>(roots);
+  const visitedOrder: string[] = [];
+  const edgeIds: string[] = [];
+  const revisitSkipped: string[] = [];
+  const cycles: string[][] = [];
+  const seenCycleKeys = new Set<string>();
+  let depthReached = 0;
+  let truncated = false;
+  let truncationReason: FileTraversalResultV1["truncationReason"];
+  /**
+   * GLOBALES Budget erschoepft (Knoten, Kanten, Zeit) — im Unterschied zur
+   * Tiefengrenze, die NUR den gerade betrachteten Ast beschneidet. Beides in
+   * einem Flag zu fuehren war der Fehler: eine erreichte Tiefe in der ersten
+   * Wurzel warf alle weiteren Wurzeln weg, obwohl auf deren Aesten die
+   * Tiefengrenze noch gar nicht erreicht war.
+   */
+  let budgetExhausted = false;
+
+  const stop = (reason: NonNullable<FileTraversalResultV1["truncationReason"]>): void => {
+    truncated = true;
+    // WP-196: NICHT der erste Grund, sondern der, an dem tatsaechlich etwas
+    // verloren ging. `max_depth` beschneidet nur den gerade betrachteten Ast
+    // und laesst die Traversierung weiterlaufen; ein erschoepftes GLOBALES
+    // Budget beendet sie. Wer beide in der Reihenfolge ihres Auftretens
+    // aufhebt, meldet bei „erst Tiefe, dann Knotenbudget" die Tiefe — und
+    // schickt den Leser damit an die falsche Stellschraube, waehrend die
+    // Wurzeln in `unvisitedRootFileIds` von einem Budget erzaehlen, das im
+    // Abschneidegrund gar nicht vorkommt.
+    if (
+      truncationReason === undefined ||
+      (truncationReason === "max_depth" && reason !== "max_depth")
+    ) {
+      truncationReason = reason;
+    }
+    if (reason !== "max_depth") budgetExhausted = true;
+  };
+
+  /**
+   * WP-194: Wurzeln, die der Graph GAR NICHT KENNT.
+   *
+   * `buildAdjacency` legt fuer jeden Knoten einen Eintrag an — auch fuer einen
+   * ohne jede Kante. Ein fehlender Eintrag heisst deshalb nicht „isolierter
+   * Knoten", sondern „diese Datei ist im Graphen nicht vorhanden". Bisher
+   * landete eine solche Wurzel unbesehen in `rootFileIds` und sah dort aus wie
+   * jede andere bearbeitete Wurzel: null Nachbarn, kein Hinweis. Wer nach
+   * einem Tippfehler im Pfad sucht, bekam ein leeres, unauffaelliges Ergebnis
+   * — die Frage wurde nie gestellt, und niemand sagte es.
+   */
+  const unknownRoots: string[] = [];
+
+  const unvisitedRoots: string[] = [];
+  for (const root of roots) {
+    if (!neighborhood.adjacency.forward.has(root)) {
+      unknownRoots.push(root);
+      continue;
+    }
+    if (budgetExhausted) {
+      // Nicht stillschweigend fallen lassen: diese Wurzeln wurden nie
+      // angefasst, und `rootFileIds` allein saehe so aus, als waeren sie
+      // bearbeitet worden (E4).
+      unvisitedRoots.push(root);
+      continue;
+    }
+    const path: string[] = [root];
+    const onPath = new Set<string>([root]);
+    const work: { node: string; childIndex: number; depth: number }[] = [
+      { node: root, childIndex: 0, depth: 0 },
+    ];
+
+    while (work.length > 0) {
+      if (now() - startedAt > limits.maxWallTimeMs) {
+        stop("max_wall_time");
+        break;
+      }
+      const frame = work[work.length - 1] as { node: string; childIndex: number; depth: number };
+      const children = neighbors.get(frame.node) ?? [];
+      if (frame.childIndex >= children.length) {
+        work.pop();
+        const removed = path.pop();
+        if (removed !== undefined) onPath.delete(removed);
+        continue;
+      }
+      const child = children[frame.childIndex] as string;
+      frame.childIndex += 1;
+
+      if (onPath.has(child)) {
+        // Zyklus GEFUNDEN — nicht aufgebrochen, sondern benannt.
+        const cycle = path.slice(path.indexOf(child));
+        const key = cycle.join("/");
+        if (!seenCycleKeys.has(key)) {
+          seenCycleKeys.add(key);
+          cycles.push(cycle);
+        }
+        revisitSkipped.push(child);
+        continue;
+      }
+
+      const edgeId = neighborhood.edgeIdBetween(frame.node, child, options.direction);
+      if (edgeId !== null) {
+        if (edgeIds.length >= limits.maxEdges) {
+          stop("max_edges");
+          break;
+        }
+        edgeIds.push(edgeId);
+      }
+
+      if (visited.has(child)) {
+        revisitSkipped.push(child);
+        continue;
+      }
+      if (visitedOrder.length >= limits.maxNodes) {
+        stop("max_nodes");
+        break;
+      }
+      visited.add(child);
+      visitedOrder.push(child);
+
+      const childDepth = frame.depth + 1;
+      depthReached = Math.max(depthReached, childDepth);
+      if (childDepth >= limits.maxDepth) {
+        // Die Tiefengrenze ist erreicht: der Knoten zaehlt als besucht, seine
+        // Nachbarn werden nicht mehr betrachtet — und genau das wird gemeldet.
+        if ((neighbors.get(child) ?? []).length > 0) {
+          stop("max_depth");
+        }
+        continue;
+      }
+      path.push(child);
+      onPath.add(child);
+      work.push({ node: child, childIndex: 0, depth: childDepth });
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    direction: options.direction,
+    rootFileIds: roots,
+    visitedFileIds: visitedOrder,
+    edgeIds,
+    depthReached,
+    truncated,
+    ...(truncationReason === undefined ? {} : { truncationReason }),
+    revisitSkippedFileIds: uniqueSortedByCodepoints(revisitSkipped),
+    cycles,
+    ...(unvisitedRoots.length === 0
+      ? {}
+      : { unvisitedRootFileIds: uniqueSortedByCodepoints(unvisitedRoots) }),
+    ...(unknownRoots.length === 0
+      ? {}
+      : { unknownRootFileIds: uniqueSortedByCodepoints(unknownRoots) }),
+    limits,
+  };
+}