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

package/src/edges.ts

@@ -0,0 +1,334 @@
+/**
+ * Rohimporte → Kanten des Dateigraphen (spec.md §14.2).
+ *
+ * Diese Datei ist die Stelle, an der E4 konkret wird. Drei Faelle, die hier
+ * NICHT stillschweigend verschwinden:
+ *
+ * 1. Ein Import, der sich nicht aufloesen laesst, bleibt eine Kante. Er
+ *    behaelt seine Art (`import` bleibt `import`) und bekommt
+ *    `resolution.status: "unresolved"` mit benanntem Grund. So bleibt die
+ *    Import-Resolution-Rate (spec.md §14.4) eine ehrliche Zahl.
+ * 2. Ein Import OHNE Spezifizierer kann keine Kante werden — `rawSpecifier`
+ *    darf nie leer sein (`validateFileEdge`). Er wird deshalb zum
+ *    Ledger-Eintrag, nicht zu einer weggelassenen Zeile.
+ * 3. Eine Datei, deren Importe gar nicht erst extrahiert werden konnten
+ *    (`importsMissingReason`), erzeugt ebenfalls einen Ledger-Eintrag.
+ *    Ohne ihn saehe eine nicht geparste Datei wie eine importfreie aus.
+ */
+import type {
+  FileEdgeKind,
+  FileEdgeSiteV1,
+  FileEdgeV1,
+  RawImport,
+  RawImportKind,
+  SkipLedgerEntryV1,
+} from "@untangle-code/domain";
+import {
+  FILE_GRAPH_VERSION,
+  buildFileEdgeId,
+  buildSkipLedgerEntry,
+  compareCodepoints,
+} from "@untangle-code/domain";
+
+import { assignContainerService, assignPackage } from "./assignment.js";
+import { isAssetSpecifier } from "./resolve/candidates.js";
+import { resolveImport } from "./resolve/pipeline.js";
+import type {
+  ContainerServiceV1,
+  FileImportsV1,
+  ImportResolverV1,
+  ResolveContextV1,
+  WorkspacePackageCatalogV1,
+  WorkspacePackageV1,
+} from "./types.js";
+
+/** Abbildung der Parser-Importart auf die Kantenart des Graphen. */
+export const RAW_IMPORT_KIND_TO_EDGE_KIND: Readonly<Record<RawImportKind, FileEdgeKind>> = {
+  import: "import",
+  re_export: "re-export",
+  dynamic_import: "dynamic-import",
+  // `package_dependency` entsteht nicht im Quelltext, sondern aus einem
+  // Manifest. Als Bezug auf eine Konfigurationsdatei ist es genau das, was
+  // `config-reference` beschreibt — und NICHT `import`, weil kein Modul
+  // geladen wird.
+  package_dependency: "config-reference",
+};
+
+/**
+ * Zeichen, die einen dynamischen Spezifizierer als nicht statisch auswertbar
+ * ausweisen. Der Parser liefert bei `import(variable)` den Ausdruckstext; der
+ * ist ein ehrlicher Rohstring, aber kein Modulpfad.
+ */
+const NON_LITERAL_SPECIFIER = /[`$+(){}[\]\s]|\.\.\.|\?\?|&&|\|\|/;
+
+/** Alles, was der Kantenbau je Datei braucht. */
+export interface EdgeBuildContextV1 {
+  workspaceId: string;
+  graphGeneration: string;
+  packages: readonly WorkspacePackageV1[];
+  /** Repository-bewusster Paketkatalog; siehe `package-catalog.ts`. */
+  packageCatalog: WorkspacePackageCatalogV1;
+  services: readonly ContainerServiceV1[];
+  projectAliases: ResolveContextV1["projectAliases"];
+  configuredAliases: ResolveContextV1["configuredAliases"];
+  extensionOrder: readonly string[];
+  files: ResolveContextV1["files"];
+  /** repoId → refId, fuer die Zielangabe aufgeloester Kanten. */
+  refIdByRepoId: ReadonlyMap<string, string>;
+  /** repoId + Pfad → fileId. */
+  resolveFileId: (repoId: string, path: string) => string | null;
+  pipeline?: readonly ImportResolverV1[];
+}
+
+/** Ergebnis des Kantenbaus fuer EINE Datei. */
+export interface FileEdgesV1 {
+  edges: FileEdgeV1[];
+  skipped: SkipLedgerEntryV1[];
+}
+
+/** Baut alle Kanten einer einzelnen Datei. */
+export function buildEdgesForFile(file: FileImportsV1, context: EdgeBuildContextV1): FileEdgesV1 {
+  const edges: FileEdgeV1[] = [];
+  const skipped: SkipLedgerEntryV1[] = [];
+
+  if (file.importsMissingReason !== undefined) {
+    skipped.push(
+      buildSkipLedgerEntry({
+        stage: "file_graph",
+        subjectKind: "file",
+        subjectId: file.fileId,
+        path: file.path,
+        repoId: file.repoId,
+        refId: file.refId,
+        reason: "parse_failed",
+        detail: `imports of "${file.path}" were not extracted: ${file.importsMissingReason}`,
+        recoverable: true,
+      }),
+    );
+  }
+
+  const fromPackage = assignPackage(context.packages, file.repoId, file.path);
+  const fromService = assignContainerService(context.services, file.repoId, file.path);
+
+  const resolveContext: ResolveContextV1 = {
+    workspaceId: context.workspaceId,
+    fromRepoId: file.repoId,
+    fromRefId: file.refId,
+    fromPath: file.path,
+    fromLanguageId: file.languageId,
+    ...(fromPackage === null ? {} : { fromPackage }),
+    files: context.files,
+    packageCatalog: context.packageCatalog,
+    projectAliases: context.projectAliases,
+    configuredAliases: context.configuredAliases,
+    extensionOrder: context.extensionOrder,
+  };
+
+  const ordinals = new Map<string, number>();
+
+  for (const rawImport of file.imports) {
+    const specifier = rawImport.specifier;
+    if (specifier.trim() === "") {
+      skipped.push(
+        buildSkipLedgerEntry({
+          stage: "file_graph",
+          subjectKind: "file_edge",
+          path: file.path,
+          repoId: file.repoId,
+          refId: file.refId,
+          range: rawImport.range,
+          reason: "resolution_failed",
+          detail: `parser reported an import of kind "${rawImport.importKind}" without a specifier at line ${String(rawImport.range.startLine)}; an edge without a raw specifier would violate the file-edge invariant`,
+          recoverable: false,
+        }),
+      );
+      continue;
+    }
+
+    const kind = edgeKindOf(rawImport, specifier);
+    const ordinalKey = `${kind}\u001f${specifier}`;
+    const occurrenceOrdinal = ordinals.get(ordinalKey) ?? 0;
+    ordinals.set(ordinalKey, occurrenceOrdinal + 1);
+
+    const resolution = resolveSpecifier(rawImport, specifier, resolveContext, context);
+
+    const site: FileEdgeSiteV1 = {
+      range: rawImport.range,
+      ...(rawImport.importedNames !== undefined && rawImport.importedNames.length > 0
+        ? { importedNames: [...rawImport.importedNames] }
+        : {}),
+      ...(rawImport.typeOnly === undefined ? {} : { typeOnly: rawImport.typeOnly }),
+    };
+
+    // Die Grenzen werden aus der ENDGUELTIGEN Aufloesung abgeleitet, nicht aus
+    // der des Resolvers: `toDomainResolution` kann einen Treffer noch zu einem
+    // Fehlschlag herabstufen (wenn der Index keine `file_id` zum Pfad hat), und
+    // eine Kante mit `crossRepo: true` bei `status: "unresolved"` waere eine
+    // Behauptung ohne Grundlage.
+    const domainResolution = toDomainResolution(resolution, context);
+
+    let targetPackage: WorkspacePackageV1 | null = null;
+    let targetService: ContainerServiceV1 | null = null;
+    let externalPackageName: string | undefined;
+
+    if (domainResolution.status === "resolved") {
+      targetPackage = assignPackage(
+        context.packages,
+        domainResolution.targetRepoId,
+        domainResolution.targetPath,
+      );
+      targetService = assignContainerService(
+        context.services,
+        domainResolution.targetRepoId,
+        domainResolution.targetPath,
+      );
+    } else if (domainResolution.status === "external") {
+      externalPackageName = domainResolution.packageName;
+    }
+
+    const crossRepo =
+      domainResolution.status === "resolved" && domainResolution.targetRepoId !== file.repoId;
+    const toPackageName = targetPackage?.name ?? externalPackageName;
+    // Paketgleichheit ist NICHT Namensgleichheit: zwei Repositories eines
+    // Workspace duerfen ein gleichnamiges Paket fuehren, und eine Kante von
+    // einem ins andere ueberquert sehr wohl eine Paketgrenze. Verglichen wird
+    // deshalb die Identitaet (Repository + Verzeichnis), nicht der Name.
+    const crossPackage =
+      toPackageName !== undefined &&
+      (fromPackage === null ||
+        (targetPackage === null
+          ? fromPackage.name !== toPackageName
+          : packageKeyOf(fromPackage) !== packageKeyOf(targetPackage)));
+    const crossContainer =
+      fromService !== null && targetService !== null && fromService.name !== targetService.name;
+
+    const edge: FileEdgeV1 = {
+      schemaVersion: 1,
+      edgeId: buildFileEdgeId({
+        workspaceId: context.workspaceId,
+        fromFileId: file.fileId,
+        edgeKind: kind,
+        rawSpecifier: specifier,
+        occurrenceOrdinal,
+      }),
+      workspaceId: context.workspaceId,
+      repoId: file.repoId,
+      refId: file.refId,
+      fromFileId: file.fileId,
+      fromPath: file.path,
+      kind,
+      rawSpecifier: specifier,
+      resolution: domainResolution,
+      boundary: {
+        crossRepo,
+        crossPackage,
+        crossContainer,
+        ...(fromPackage === null ? {} : { fromPackageName: fromPackage.name }),
+        ...(toPackageName === undefined ? {} : { toPackageName }),
+        ...(fromService === null ? {} : { fromContainerService: fromService.name }),
+        ...(targetService === null ? {} : { toContainerService: targetService.name }),
+      },
+      sites: [site],
+      occurrenceOrdinal,
+      graphGeneration: context.graphGeneration,
+      graphVersion: FILE_GRAPH_VERSION,
+    };
+    edges.push(edge);
+  }
+
+  edges.sort(compareEdges);
+  return { edges, skipped };
+}
+
+/** Identitaet eines Pakets: Repository plus Verzeichnis, nicht der Name. */
+function packageKeyOf(entry: WorkspacePackageV1): string {
+  return `${entry.repoId}\u001f${entry.packageDir}`;
+}
+
+/** Stabile Kantenordnung: Quelle, Art, Rohstring, laufende Nummer. */
+export function compareEdges(left: FileEdgeV1, right: FileEdgeV1): number {
+  return (
+    compareCodepoints(left.fromFileId, right.fromFileId) ||
+    compareCodepoints(left.kind, right.kind) ||
+    compareCodepoints(left.rawSpecifier, right.rawSpecifier) ||
+    left.occurrenceOrdinal - right.occurrenceOrdinal ||
+    compareCodepoints(left.edgeId, right.edgeId)
+  );
+}
+
+function edgeKindOf(rawImport: RawImport, specifier: string): FileEdgeKind {
+  const base = RAW_IMPORT_KIND_TO_EDGE_KIND[rawImport.importKind];
+  // Ein Import einer Nicht-Code-Ressource bleibt eine echte Abhaengigkeit,
+  // ist aber keine Modulbeziehung — `asset-reference` macht sichtbar, dass
+  // die Zieldatei nie Symbole beitragen wird (spec.md §19/§20).
+  if ((base === "import" || base === "dynamic-import") && isAssetSpecifier(specifier)) {
+    return "asset-reference";
+  }
+  return base;
+}
+
+type LocalResolution = ReturnType<typeof resolveImport>["result"];
+
+function resolveSpecifier(
+  rawImport: RawImport,
+  specifier: string,
+  resolveContext: ResolveContextV1,
+  context: EdgeBuildContextV1,
+): LocalResolution {
+  if (rawImport.importKind === "dynamic_import" && NON_LITERAL_SPECIFIER.test(specifier)) {
+    return {
+      status: "unresolved",
+      reason: "dynamic_specifier_not_statically_analyzable",
+      detail: `dynamic import argument "${specifier}" is an expression, not a literal module specifier; the raw text is kept so the call site stays findable`,
+    };
+  }
+  return resolveImport(specifier, resolveContext, context.pipeline).result;
+}
+
+function toDomainResolution(
+  resolution: LocalResolution,
+  context: EdgeBuildContextV1,
+): FileEdgeV1["resolution"] {
+  if (resolution.status === "external") {
+    return {
+      status: "external",
+      mechanism: resolution.mechanism,
+      packageName: resolution.packageName,
+      ...(resolution.declaredVersion === undefined
+        ? {}
+        : { declaredVersion: resolution.declaredVersion }),
+    };
+  }
+  if (resolution.status === "unresolved") {
+    return {
+      status: "unresolved",
+      reason: resolution.reason,
+      detail: resolution.detail,
+      ...(resolution.rejectedCandidates === undefined
+        ? {}
+        : { rejectedCandidates: resolution.rejectedCandidates }),
+    };
+  }
+  const targetFileId = context.resolveFileId(resolution.targetRepoId, resolution.targetPath);
+  if (targetFileId === null) {
+    // Kann nur passieren, wenn der Index zwischen Probe und Kantenbau
+    // veraendert wurde. Der Fall wird zum benannten Fehlschlag, nicht zu
+    // einer Kante mit leerer Ziel-ID.
+    return {
+      status: "unresolved",
+      reason: "target_file_not_found",
+      detail: `resolver found "${resolution.targetPath}" in repository "${resolution.targetRepoId}", but the file index has no id for it`,
+    };
+  }
+  return {
+    status: "resolved",
+    mechanism: resolution.mechanism,
+    targetFileId,
+    targetRepoId: resolution.targetRepoId,
+    targetRefId: context.refIdByRepoId.get(resolution.targetRepoId) ?? "",
+    targetPath: resolution.targetPath,
+    ...(resolution.viaPackageName === undefined
+      ? {}
+      : { viaPackageName: resolution.viaPackageName }),
+  };
+}

package/src/file-index.ts

@@ -0,0 +1,127 @@
+/**
+ * Dateiverzeichnis: die einzige Nachschlagequelle der Aufloesung.
+ *
+ * Die gesamte Modulaufloesung arbeitet gegen diesen Index und NICHT gegen das
+ * Dateisystem. Grund: eine Aufloesung, die das Dateisystem befragt, haengt am
+ * Zustand der Platte zum Zeitpunkt des Laufs und ist damit weder
+ * reproduzierbar noch ohne echtes Repository testbar. Der Index wird einmal
+ * aus der Dateiliste des Scanners gebaut; ab da ist jede Aufloesung eine reine
+ * Funktion.
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+
+import { normalizePath } from "./paths.js";
+import type { FileImportsV1, FileLookupV1 } from "./types.js";
+
+/** Eintrag des Index — genau das, was die Aufloesung ueber eine Datei wissen muss. */
+export interface FileIndexEntryV1 {
+  fileId: string;
+  repoId: string;
+  refId: string;
+  path: string;
+  languageId: string;
+  contentHash: string;
+}
+
+export class FileIndex implements FileLookupV1 {
+  private readonly byRepoPath = new Map<string, FileIndexEntryV1>();
+  private readonly byFileId = new Map<string, FileIndexEntryV1>();
+  private readonly repos = new Set<string>();
+
+  static fromFiles(files: readonly FileImportsV1[]): FileIndex {
+    const index = new FileIndex();
+    for (const file of files) {
+      index.add({
+        fileId: file.fileId,
+        repoId: file.repoId,
+        refId: file.refId,
+        path: normalizePath(file.path),
+        languageId: file.languageId,
+        contentHash: file.contentHash,
+      });
+    }
+    return index;
+  }
+
+  /**
+   * Nimmt einen Eintrag auf und ERSETZT dabei jede fruehere Bindung derselben
+   * `file_id`.
+   *
+   * Der zweite Schritt ist der wichtige: eine Umbenennung erreicht den Index
+   * als `add()` mit neuem Pfad (`FileGraphChangeV1` kennt kein „renamed"). Wer
+   * dabei nur den neuen Schluessel setzt, laesst den alten stehen — der Index
+   * behauptet danach eine Datei unter einem Pfad, den keine Datei mehr hat,
+   * und die Aufloesung meldet eine Kante dorthin als `resolved`. Ein Phantom
+   * mit Aufloesungsrate 1 ist genau das stille Verschweigen, das E4 verbietet.
+   */
+  add(entry: FileIndexEntryV1): void {
+    const normalized: FileIndexEntryV1 = { ...entry, path: normalizePath(entry.path) };
+    const newKey = keyOf(normalized.repoId, normalized.path);
+    const previous = this.byFileId.get(normalized.fileId);
+    if (previous !== undefined) {
+      const previousKey = keyOf(previous.repoId, previous.path);
+      // Nur loeschen, wenn der alte Schluessel WIRKLICH noch auf diese Datei
+      // zeigt: hat inzwischen eine andere Datei den Pfad uebernommen, waere das
+      // Loeschen ein zweites Phantom — diesmal ein fehlendes statt eines
+      // ueberzaehligen.
+      if (
+        previousKey !== newKey &&
+        this.byRepoPath.get(previousKey)?.fileId === normalized.fileId
+      ) {
+        this.byRepoPath.delete(previousKey);
+      }
+    }
+    this.byRepoPath.set(newKey, normalized);
+    this.byFileId.set(normalized.fileId, normalized);
+    this.repos.add(normalized.repoId);
+  }
+
+  /** Entfernt einen Eintrag; True, wenn er vorhanden war. */
+  remove(fileId: string): boolean {
+    const entry = this.byFileId.get(fileId);
+    if (entry === undefined) {
+      return false;
+    }
+    this.byFileId.delete(fileId);
+    const key = keyOf(entry.repoId, entry.path);
+    // Denselben Grund wie in `add()`: den Pfadschluessel nur freigeben, wenn er
+    // noch auf genau diese Datei zeigt.
+    if (this.byRepoPath.get(key)?.fileId === fileId) {
+      this.byRepoPath.delete(key);
+    }
+    return true;
+  }
+
+  hasFile(repoId: string, path: string): boolean {
+    return this.byRepoPath.has(keyOf(repoId, normalizePath(path)));
+  }
+
+  fileIdOf(repoId: string, path: string): string | null {
+    return this.byRepoPath.get(keyOf(repoId, normalizePath(path)))?.fileId ?? null;
+  }
+
+  entryOf(repoId: string, path: string): FileIndexEntryV1 | null {
+    return this.byRepoPath.get(keyOf(repoId, normalizePath(path))) ?? null;
+  }
+
+  entryById(fileId: string): FileIndexEntryV1 | null {
+    return this.byFileId.get(fileId) ?? null;
+  }
+
+  repoIds(): readonly string[] {
+    return [...this.repos].sort(compareCodepoints);
+  }
+
+  get size(): number {
+    return this.byFileId.size;
+  }
+}
+
+/**
+ * U+001F als Trenner: derselbe Trenner, den `domain`s ID-Ableitung nutzt. Er
+ * kann in keinem Pfad und in keiner Repository-ID vorkommen, also kann der
+ * Schluessel von ("ab", "c") nie mit dem von ("a", "bc") kollidieren.
+ */
+function keyOf(repoId: string, path: string): string {
+  return `${repoId}\u001f${path}`;
+}