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

package/src/metrics.ts

@@ -0,0 +1,350 @@
+/**
+ * Graphmetriken des Dateigraphen (spec.md §14.4).
+ *
+ * Alle Verfahren sind ITERATIV implementiert, nicht rekursiv. Ein Monorepo
+ * mit zehntausenden Dateien hat Ketten, die jeden Aufrufstapel sprengen; ein
+ * `RangeError` mitten in der Statistik waere ein Totalausfall der Kennzahlen.
+ *
+ * ZYKLEN: Die Aufzaehlung elementarer Zyklen ist im schlechtesten Fall
+ * exponentiell. Sie laeuft deshalb gegen ein Budget — und wenn das Budget
+ * greift, steht das in `truncationReason`. Eine abgeschnittene Zyklusliste
+ * darf nie wie eine vollstaendige aussehen (E4).
+ */
+import type {
+  FileEdgeV1,
+  FileGraphCentralityEntryV1,
+  FileGraphMetricsV1,
+  FileNodeV1,
+} from "@untangle-code/domain";
+import { FILE_GRAPH_VERSION, compareCodepoints } from "@untangle-code/domain";
+
+import type { FileGraphLimitsV1 } from "./types.js";
+
+/** Benannte Formel hinter `FileGraphCentralityEntryV1.centrality`. */
+export const CENTRALITY_FORMULA =
+  "degree-centrality-v1: (inDegree + outDegree) / (2 * max(1, nodeCount - 1)), clamped to [0, 1]";
+
+export const DEFAULT_GRAPH_LIMITS: FileGraphLimitsV1 = {
+  maxCycles: 1_000,
+  topCentralCount: 25,
+  maxCycleSearchNodes: 200_000,
+};
+
+/** Gerichtete Nachbarschaftslisten, aus aufgeloesten Kanten gebaut. */
+export interface AdjacencyV1 {
+  /** fileId → Ziel-fileIds, codepoint-sortiert und dedupliziert. */
+  forward: Map<string, string[]>;
+  /** fileId → Quell-fileIds, codepoint-sortiert und dedupliziert. */
+  reverse: Map<string, string[]>;
+}
+
+/**
+ * Baut die Nachbarschaft aus den Kanten.
+ *
+ * Nur `resolved`-Kanten mit einem Ziel INNERHALB der Knotenmenge zaehlen —
+ * eine externe Abhaengigkeit hat keinen Knoten, und eine unaufgeloeste erst
+ * recht nicht. Beide bleiben als Kante erhalten und in der
+ * Import-Resolution-Rate sichtbar, sie sind nur keine Graphverbindung.
+ */
+export function buildAdjacency(
+  nodeIds: readonly string[],
+  edges: readonly FileEdgeV1[],
+): AdjacencyV1 {
+  const known = new Set(nodeIds);
+  const forwardSets = new Map<string, Set<string>>();
+  const reverseSets = new Map<string, Set<string>>();
+  for (const id of nodeIds) {
+    forwardSets.set(id, new Set());
+    reverseSets.set(id, new Set());
+  }
+  for (const edge of edges) {
+    if (edge.resolution.status !== "resolved") continue;
+    const target = edge.resolution.targetFileId;
+    if (!known.has(edge.fromFileId) || !known.has(target)) continue;
+    forwardSets.get(edge.fromFileId)?.add(target);
+    reverseSets.get(target)?.add(edge.fromFileId);
+  }
+  const forward = new Map<string, string[]>();
+  const reverse = new Map<string, string[]>();
+  for (const id of nodeIds) {
+    forward.set(id, [...(forwardSets.get(id) ?? [])].sort(compareCodepoints));
+    reverse.set(id, [...(reverseSets.get(id) ?? [])].sort(compareCodepoints));
+  }
+  return { forward, reverse };
+}
+
+/**
+ * Stark zusammenhaengende Komponenten nach Tarjan, iterativ.
+ *
+ * Ergebnis enthaelt NUR Komponenten mit mehr als einem Knoten — eine
+ * einelementige Komponente ohne Selbstschleife ist kein Befund. Selbstbezuege
+ * kommen ueber `findCycles` als einelementige Zyklen zurueck.
+ */
+export function stronglyConnectedComponents(
+  nodeIds: readonly string[],
+  forward: ReadonlyMap<string, readonly string[]>,
+): string[][] {
+  const index = new Map<string, number>();
+  const lowlink = new Map<string, number>();
+  const onStack = new Set<string>();
+  const stack: string[] = [];
+  const components: string[][] = [];
+  let counter = 0;
+
+  for (const root of nodeIds) {
+    if (index.has(root)) continue;
+    const work: { node: string; childIndex: number }[] = [{ node: root, childIndex: 0 }];
+    index.set(root, counter);
+    lowlink.set(root, counter);
+    counter += 1;
+    stack.push(root);
+    onStack.add(root);
+
+    while (work.length > 0) {
+      const frame = work[work.length - 1] as { node: string; childIndex: number };
+      const children = forward.get(frame.node) ?? [];
+      if (frame.childIndex < children.length) {
+        const child = children[frame.childIndex] as string;
+        frame.childIndex += 1;
+        if (!index.has(child)) {
+          index.set(child, counter);
+          lowlink.set(child, counter);
+          counter += 1;
+          stack.push(child);
+          onStack.add(child);
+          work.push({ node: child, childIndex: 0 });
+        } else if (onStack.has(child)) {
+          lowlink.set(
+            frame.node,
+            Math.min(lowlink.get(frame.node) as number, index.get(child) as number),
+          );
+        }
+        continue;
+      }
+      work.pop();
+      const parent = work[work.length - 1];
+      if (parent !== undefined) {
+        lowlink.set(
+          parent.node,
+          Math.min(lowlink.get(parent.node) as number, lowlink.get(frame.node) as number),
+        );
+      }
+      if (lowlink.get(frame.node) === index.get(frame.node)) {
+        const component: string[] = [];
+        for (;;) {
+          const popped = stack.pop() as string;
+          onStack.delete(popped);
+          component.push(popped);
+          if (popped === frame.node) break;
+        }
+        if (component.length > 1) {
+          components.push(component.sort(compareCodepoints));
+        }
+      }
+    }
+  }
+
+  components.sort((left, right) => compareCodepoints(left[0] as string, right[0] as string));
+  return components;
+}
+
+/** Ergebnis der Zyklensuche. */
+export interface CycleSearchResultV1 {
+  /** Jeder Zyklus als geordnete Liste seiner file_ids, ohne Wiederholung des Startknotens. */
+  cycles: string[][];
+  /** Gesetzt, wenn ein Budget die Suche beendet hat. */
+  truncationReason?: string;
+}
+
+/**
+ * Zaehlt elementare Zyklen auf, komponentenweise und gegen ein Budget.
+ *
+ * Vorgehen: je stark zusammenhaengender Komponente wird von jedem Knoten aus
+ * gesucht, aber nur ueber Knoten, die in der komponenteninternen Ordnung NICHT
+ * VOR dem Startknoten liegen. Damit wird jeder Zyklus genau einmal gefunden
+ * (an seinem kleinsten Knoten) statt einmal je Rotation.
+ */
+export function findCycles(
+  nodeIds: readonly string[],
+  forward: ReadonlyMap<string, readonly string[]>,
+  components: readonly (readonly string[])[],
+  limits: FileGraphLimitsV1,
+): CycleSearchResultV1 {
+  const cycles: string[][] = [];
+  let steps = 0;
+  let truncationReason: string | undefined;
+
+  // Selbstbezuege: eine Datei, die sich selbst importiert. Auch sie zaehlen
+  // gegen das Budget — sonst koennte eine Liste voller Selbstbezuege das
+  // Limit ueberschreiten, ohne dass es jemand erfaehrt.
+  for (const node of nodeIds) {
+    if (!(forward.get(node) ?? []).includes(node)) continue;
+    if (cycles.length >= limits.maxCycles) {
+      truncationReason = `cycle enumeration stopped at maxCycles=${String(limits.maxCycles)}; more elementary cycles exist`;
+      break;
+    }
+    cycles.push([node]);
+  }
+
+  for (const component of components) {
+    if (truncationReason !== undefined) break;
+    const members = [...component].sort(compareCodepoints);
+    const rank = new Map(members.map((id, position) => [id, position]));
+
+    for (const start of members) {
+      if (truncationReason !== undefined) break;
+      const startRank = rank.get(start) as number;
+      const path: string[] = [start];
+      const onPath = new Set<string>([start]);
+      const work: { node: string; childIndex: number }[] = [{ node: start, childIndex: 0 }];
+
+      while (work.length > 0) {
+        if (cycles.length >= limits.maxCycles) {
+          truncationReason = `cycle enumeration stopped at maxCycles=${String(limits.maxCycles)}; more elementary cycles exist`;
+          break;
+        }
+        if (steps >= limits.maxCycleSearchNodes) {
+          truncationReason = `cycle enumeration stopped at maxCycleSearchNodes=${String(limits.maxCycleSearchNodes)}; the cycle list is incomplete`;
+          break;
+        }
+        steps += 1;
+        const frame = work[work.length - 1] as { node: string; childIndex: number };
+        const children = forward.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;
+        const childRank = rank.get(child);
+        if (childRank === undefined || childRank < startRank) continue;
+        if (child === start) {
+          if (path.length > 1) {
+            cycles.push([...path]);
+          }
+          continue;
+        }
+        if (onPath.has(child)) continue;
+        path.push(child);
+        onPath.add(child);
+        work.push({ node: child, childIndex: 0 });
+      }
+    }
+  }
+
+  cycles.sort(
+    (left, right) =>
+      left.length - right.length || compareCodepoints(left.join("/"), right.join("/")),
+  );
+  return truncationReason === undefined ? { cycles } : { cycles, truncationReason };
+}
+
+/** Berechnet die vollstaendige Metrikaufstellung. */
+export function computeFileGraphMetrics(input: {
+  workspaceId: string;
+  graphGeneration: string;
+  nodes: readonly FileNodeV1[];
+  edges: readonly FileEdgeV1[];
+  adjacency: AdjacencyV1;
+  limits: FileGraphLimitsV1;
+}): FileGraphMetricsV1 {
+  const nodeIds = input.nodes.map((node) => node.fileId).sort(compareCodepoints);
+  const components = stronglyConnectedComponents(nodeIds, input.adjacency.forward);
+  const cycleSearch = findCycles(nodeIds, input.adjacency.forward, components, input.limits);
+
+  const orphanFileIds: string[] = [];
+  const centrality: FileGraphCentralityEntryV1[] = [];
+  const denominator = 2 * Math.max(1, nodeIds.length - 1);
+  const pathById = new Map(input.nodes.map((node) => [node.fileId, node.filePath]));
+
+  for (const id of nodeIds) {
+    const outDegree = (input.adjacency.forward.get(id) ?? []).length;
+    const inDegree = (input.adjacency.reverse.get(id) ?? []).length;
+    if (outDegree === 0 && inDegree === 0) {
+      orphanFileIds.push(id);
+    }
+    centrality.push({
+      fileId: id,
+      filePath: pathById.get(id) ?? "",
+      inDegree,
+      outDegree,
+      centrality: Math.min(1, (inDegree + outDegree) / denominator),
+    });
+  }
+
+  const topCentralFiles = [...centrality]
+    .sort(
+      (left, right) =>
+        right.centrality - left.centrality ||
+        right.inDegree - left.inDegree ||
+        compareCodepoints(left.fileId, right.fileId),
+    )
+    .slice(0, Math.max(0, input.limits.topCentralCount));
+
+  let resolvedCount = 0;
+  let externalCount = 0;
+  let unresolvedCount = 0;
+  for (const edge of input.edges) {
+    switch (edge.resolution.status) {
+      case "resolved":
+        resolvedCount += 1;
+        break;
+      case "external":
+        externalCount += 1;
+        break;
+      case "unresolved":
+        unresolvedCount += 1;
+        break;
+    }
+  }
+  const total = resolvedCount + externalCount + unresolvedCount;
+
+  const repositoryDistribution: Record<string, number> = {};
+  const languageDistribution: Record<string, number> = {};
+  for (const node of [...input.nodes].sort((left, right) =>
+    compareCodepoints(left.fileId, right.fileId),
+  )) {
+    repositoryDistribution[node.repoId] = (repositoryDistribution[node.repoId] ?? 0) + 1;
+    languageDistribution[node.language] = (languageDistribution[node.language] ?? 0) + 1;
+  }
+
+  return {
+    schemaVersion: 1,
+    workspaceId: input.workspaceId,
+    graphGeneration: input.graphGeneration,
+    graphVersion: FILE_GRAPH_VERSION,
+    nodeCount: input.nodes.length,
+    edgeCount: input.edges.length,
+    orphanFileIds,
+    stronglyConnectedComponents: components,
+    cycles: cycleSearch.cycles,
+    importResolution: {
+      resolvedCount,
+      externalCount,
+      unresolvedCount,
+      rate: total === 0 ? 0 : resolvedCount / total,
+    },
+    repositoryDistribution: sortRecord(repositoryDistribution),
+    languageDistribution: sortRecord(languageDistribution),
+    topCentralFiles,
+    centralityFormula: CENTRALITY_FORMULA,
+    ...(cycleSearch.truncationReason === undefined
+      ? {}
+      : { truncationReason: cycleSearch.truncationReason }),
+  };
+}
+
+/**
+ * Kanonische Schluesselreihenfolge eines Zaehlerobjekts. Ohne sie haengt die
+ * Reihenfolge von der Einfuegereihenfolge ab — und damit das kanonische JSON
+ * und jeder daraus abgeleitete Hash.
+ */
+function sortRecord(record: Record<string, number>): Record<string, number> {
+  const sorted: Record<string, number> = {};
+  for (const key of Object.keys(record).sort(compareCodepoints)) {
+    sorted[key] = record[key] as number;
+  }
+  return sorted;
+}

package/src/package-catalog.ts

@@ -0,0 +1,145 @@
+/**
+ * Der Paketkatalog des Workspace — nach Repository UND Name geschluesselt.
+ *
+ * WARUM NICHT NACH NAMEN ALLEIN: Ein Workspace darf aus mehreren Repositories
+ * bestehen (genau das ist der Cross-Repo-Fall, den dieses Paket koennen soll).
+ * Paketnamen sind dann NICHT eindeutig: zwei Repositories duerfen beide ein
+ * `shared-lib` enthalten, und in einem realen Bestand tun sie es auch — ein
+ * abgespaltener Fork, eine geteilte Bibliothek in zwei Staenden, ein
+ * gleichnamiges internes Hilfspaket. Ein `Map<name, package>` verliert in
+ * diesem Moment das frueher eingefuegte Paket ERSATZLOS: seine
+ * Abhaengigkeiten werden aus dem fremden Manifest gefuellt, seine Dateien
+ * werden nie mehr ueber den Katalog gefunden, und ein Import auf den Namen
+ * loest ins falsche Repository auf — gezaehlt als Erfolg.
+ *
+ * Der Katalog haelt deshalb ALLE gleichnamigen Pakete und beantwortet jede
+ * Frage aus der Sicht eines fragenden Repositories. Mehrdeutigkeit wird
+ * gemeldet, nicht aufgeloest (E4).
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+
+import type { PackageLookupV1, WorkspacePackageCatalogV1, WorkspacePackageV1 } from "./types.js";
+
+/** Stabile Ordnung des Katalogs: Name, Repository, Verzeichnis. */
+export function comparePackages(left: WorkspacePackageV1, right: WorkspacePackageV1): number {
+  return (
+    compareCodepoints(left.name, right.name) ||
+    compareCodepoints(left.repoId, right.repoId) ||
+    compareCodepoints(left.packageDir, right.packageDir) ||
+    compareCodepoints(left.manifestPath, right.manifestPath)
+  );
+}
+
+export class WorkspacePackageCatalog implements WorkspacePackageCatalogV1 {
+  private readonly entries: WorkspacePackageV1[];
+  private readonly byName = new Map<string, WorkspacePackageV1[]>();
+  private readonly byRepoAndName = new Map<string, WorkspacePackageV1[]>();
+
+  constructor(packages: readonly WorkspacePackageV1[]) {
+    this.entries = [...packages].sort(comparePackages);
+    for (const entry of this.entries) {
+      const bucket = this.byName.get(entry.name);
+      if (bucket === undefined) {
+        this.byName.set(entry.name, [entry]);
+      } else {
+        bucket.push(entry);
+      }
+      // Auch innerhalb EINES Repositories ist der Name nicht garantiert
+      // eindeutig: zwei Verzeichnisse duerfen dasselbe `name`-Feld tragen
+      // (ein kopiertes Paket, ein halb vollzogener Umzug). Das ist ein Fehler
+      // des Bestandes — aber ihn zu glaetten, indem der erste in kanonischer
+      // Ordnung gewinnt, ist GERATEN: der Bereich im Manifest des
+      // Importierenden kann sehr wohl auf das zweite zeigen. Der Katalog
+      // haelt deshalb auch hier ALLE Eintraege und laesst `lookup` melden
+      // statt entscheiden (E4).
+      const key = keyOf(entry.repoId, entry.name);
+      const owned = this.byRepoAndName.get(key);
+      if (owned === undefined) {
+        this.byRepoAndName.set(key, [entry]);
+      } else {
+        owned.push(entry);
+      }
+    }
+  }
+
+  all(): readonly WorkspacePackageV1[] {
+    return this.entries;
+  }
+
+  byPackageName(name: string): readonly WorkspacePackageV1[] {
+    return this.byName.get(name) ?? [];
+  }
+
+  /**
+   * Das Paket dieses Namens in diesem Repository — nur wenn es GENAU EINES
+   * gibt. Bei mehreren gleichnamigen Manifesten desselben Repositories ist
+   * `null` die einzige ehrliche Antwort; welches gemeint ist, steht nirgends,
+   * und `lookup` meldet den Fall als `ambiguous`.
+   */
+  inRepo(repoId: string, name: string): WorkspacePackageV1 | null {
+    const owned = this.byRepoAndName.get(keyOf(repoId, name)) ?? [];
+    return owned.length === 1 ? (owned[0] as WorkspacePackageV1) : null;
+  }
+
+  /** Alle Pakete dieses Namens in diesem Repository, kanonisch geordnet. */
+  inRepoAll(repoId: string, name: string): readonly WorkspacePackageV1[] {
+    return this.byRepoAndName.get(keyOf(repoId, name)) ?? [];
+  }
+
+  has(name: string): boolean {
+    return this.byName.has(name);
+  }
+
+  /**
+   * Sucht `name` aus der Sicht von `fromRepoId`.
+   *
+   * REIHENFOLGE UND IHR GRUND: Das eigene Repository zuerst — ein Manifest, das
+   * `shared-lib` deklariert, meint zuerst das `shared-lib`, das neben ihm
+   * liegt. Gibt es dort keines und genau EIN fremdes, ist der Cross-Repo-Bezug
+   * die einzige moegliche Lesart und damit ein Treffer. Gibt es mehrere
+   * fremde, ist der Bezug ohne weitere Angabe nicht entscheidbar — und dann
+   * wird geraten oder gemeldet. Geraten wird nicht.
+   */
+  lookup(fromRepoId: string, name: string): PackageLookupV1 {
+    const own = this.inRepoAll(fromRepoId, name);
+    if (own.length === 1) {
+      return { status: "found", entry: own[0] as WorkspacePackageV1, crossRepo: false };
+    }
+    // Mehrere gleichnamige Pakete im EIGENEN Repository: nicht auf das erste
+    // ausweichen und erst recht nicht ins fremde Repository weitersuchen —
+    // beides waere geraten. Die Kandidaten sind die des eigenen Repositories.
+    if (own.length > 1) return { status: "ambiguous", candidates: own };
+    const candidates = this.byPackageName(name);
+    if (candidates.length === 0) return { status: "absent" };
+    if (candidates.length === 1) {
+      return { status: "found", entry: candidates[0] as WorkspacePackageV1, crossRepo: true };
+    }
+    return { status: "ambiguous", candidates };
+  }
+
+  /**
+   * Namen, die von MEHR ALS EINEM Manifest deklariert werden,
+   * codepoint-sortiert.
+   *
+   * Frueher wurde hier `repos.size > 1` gefragt — damit blieb die Doppelung
+   * INNERHALB eines Repositories unsichtbar, obwohl genau sie einen Import
+   * unentscheidbar macht. Massstab ist die Zahl der Manifeste, nicht die der
+   * Repositories.
+   */
+  ambiguousNames(): readonly string[] {
+    const names: string[] = [];
+    for (const [name, bucket] of this.byName) {
+      if (bucket.length > 1) names.push(name);
+    }
+    return names.sort(compareCodepoints);
+  }
+}
+
+/**
+ * U+001F als Trenner: derselbe Trenner wie in `file-index.ts`. Er kommt weder
+ * in einer Repository-ID noch in einem Paketnamen vor, also kann der
+ * Schluessel von ("ab", "c") nie mit dem von ("a", "bc") kollidieren.
+ */
+function keyOf(repoId: string, name: string): string {
+  return `${repoId}\u001f${name}`;
+}

package/src/paths.ts

@@ -0,0 +1,138 @@
+/**
+ * Pfadhilfen des Dateigraphen — ausschliesslich POSIX, ausschliesslich
+ * repo-relativ.
+ *
+ * Warum eigene Helfer statt `node:path`: der Dateigraph rechnet nie auf
+ * Betriebssystempfaden. Er kennt nur `"/"`-normalisierte, repo-relative
+ * Pfade (spec.md §5.4), und `node:path` auf Windows wuerde aus `a/b`
+ * beim Zusammensetzen `a\b` machen — damit haette dieselbe Codebasis auf
+ * zwei Maschinen zwei verschiedene `file_id`s. `node:path/posix` deckt
+ * einen Teil ab, liefert aber `".."`-Ergebnisse ausserhalb der Wurzel
+ * still zurueck; hier wird das zu `null` und damit zu einem benannten
+ * Fehlschlag (E4).
+ */
+
+/** Normalisiert Trennzeichen und entfernt fuehrende `"./"` sowie Mehrfachslashes. */
+export function normalizePath(path: string): string {
+  const forward = path.replace(/\\/g, "/");
+  const collapsed = forward.replace(/\/{2,}/g, "/");
+  const withoutLeadingDot = collapsed.startsWith("./") ? collapsed.slice(2) : collapsed;
+  const withoutLeadingSlash = withoutLeadingDot.startsWith("/")
+    ? withoutLeadingDot.slice(1)
+    : withoutLeadingDot;
+  return withoutLeadingSlash.endsWith("/") && withoutLeadingSlash.length > 1
+    ? withoutLeadingSlash.slice(0, -1)
+    : withoutLeadingSlash;
+}
+
+/** Verzeichnisanteil eines repo-relativen Pfades; `""` fuer Dateien in der Wurzel. */
+export function dirnameOf(path: string): string {
+  const normalized = normalizePath(path);
+  const index = normalized.lastIndexOf("/");
+  return index === -1 ? "" : normalized.slice(0, index);
+}
+
+/** Dateiname ohne Verzeichnisanteil. */
+export function basenameOf(path: string): string {
+  const normalized = normalizePath(path);
+  const index = normalized.lastIndexOf("/");
+  return index === -1 ? normalized : normalized.slice(index + 1);
+}
+
+/** Erweiterung inklusive Punkt, kleingeschrieben; `""` bei Dotfiles und ohne Punkt. */
+export function extensionOf(path: string): string {
+  const name = basenameOf(path);
+  const index = name.lastIndexOf(".");
+  if (index <= 0) {
+    return "";
+  }
+  return name.slice(index).toLowerCase();
+}
+
+/**
+ * Setzt einen Basispfad und ein Segment zusammen und loest `.`/`..` auf.
+ *
+ * Gibt `null` zurueck, wenn die Aufloesung ueber die Repositorywurzel
+ * hinauslaeuft. Ein Import wie `"../../../../etc/passwd"` aus `src/a.ts`
+ * ist damit ein benannter Fehlschlag und kein still auf `etc/passwd`
+ * gekuerzter Treffer.
+ */
+export function joinRelative(baseDir: string, segment: string): string | null {
+  const base = normalizePath(baseDir);
+  const parts = base === "" ? [] : base.split("/");
+  const stack: string[] = [...parts];
+  for (const raw of normalizePath(segment).split("/")) {
+    if (raw === "" || raw === ".") {
+      continue;
+    }
+    if (raw === "..") {
+      if (stack.length === 0) {
+        return null;
+      }
+      stack.pop();
+      continue;
+    }
+    stack.push(raw);
+  }
+  return stack.join("/");
+}
+
+/** True, wenn `path` unterhalb von `directory` liegt (oder gleich ist). */
+export function isWithin(directory: string, path: string): boolean {
+  const dir = normalizePath(directory);
+  const target = normalizePath(path);
+  if (dir === "" || dir === ".") {
+    return true;
+  }
+  return target === dir || target.startsWith(`${dir}/`);
+}
+
+/**
+ * Pfad von `path` relativ zu `directory`; `null`, wenn `path` nicht darunter
+ * liegt. Bewusst kein `..`-Ergebnis: der Aufrufer will hier wissen, ob etwas
+ * INNERHALB eines Verzeichnisses liegt, nicht wie man hinaufkommt.
+ */
+export function relativeWithin(directory: string, path: string): string | null {
+  if (!isWithin(directory, path)) {
+    return null;
+  }
+  const dir = normalizePath(directory);
+  const target = normalizePath(path);
+  if (dir === "" || dir === ".") {
+    return target;
+  }
+  return target === dir ? "" : target.slice(dir.length + 1);
+}
+
+/** True fuer `"./x"`, `"../x"` und `"."`/`".."` selbst. */
+export function isRelativeSpecifier(specifier: string): boolean {
+  return specifier === "." || specifier === ".." || /^\.\.?\//.test(specifier);
+}
+
+/**
+ * Normalisiert nur die Trennzeichen und laesst einen fuehrenden `"/"` stehen.
+ *
+ * `normalizePath` ist fuer REPO-RELATIVE Pfade gedacht und entfernt deshalb
+ * einen fuehrenden Schraegstrich. Auf einen absoluten Wurzelpfad angewandt
+ * wuerde daraus ein relativer — und jeder Lesezugriff ginge ins Leere. Fuer
+ * absolute Pfade (Repositorywurzeln, Eintraege des Dateisystemports) gilt
+ * diese Funktion.
+ */
+export function normalizeSeparators(path: string): string {
+  const forward = path.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+  return forward.length > 1 && forward.endsWith("/") ? forward.slice(0, -1) : forward;
+}
+
+/**
+ * Pfad von `path` relativ zur absoluten Wurzel `root`; `null`, wenn `path`
+ * nicht darunter liegt. Beide Angaben sind absolut.
+ */
+export function relativeToRoot(root: string, path: string): string | null {
+  const normalizedRoot = normalizeSeparators(root);
+  const normalizedPath = normalizeSeparators(path);
+  if (normalizedPath === normalizedRoot) {
+    return "";
+  }
+  const prefix = normalizedRoot.endsWith("/") ? normalizedRoot : `${normalizedRoot}/`;
+  return normalizedPath.startsWith(prefix) ? normalizedPath.slice(prefix.length) : null;
+}