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

package/src/resolve/candidates.ts

@@ -0,0 +1,230 @@
+/**
+ * Kandidatenbildung: aus einem Pfad ohne Erweiterung die Liste der Dateien,
+ * die gemeint sein koennen — in fester Reihenfolge.
+ *
+ * DREI DINGE, DIE HIER PASSIEREN und ohne die jeder zweite Import dieses
+ * Repositories „unresolved" waere:
+ *
+ * 1. ERWEITERUNGSPROBE. `"./util"` kann `util.ts`, `util.tsx`, `util.js`,
+ *    … oder `util/index.ts` meinen.
+ *
+ * 2. RUECKABBILDUNG DER ESM-ENDUNG. TypeScript unter `NodeNext` schreibt
+ *    `import "./registry.js"` und meint `registry.ts`. Wer nur exakt
+ *    vergleicht, findet in einem modernen TypeScript-Monorepo praktisch
+ *    keinen einzigen relativen Import.
+ *
+ * 3. RUECKABBILDUNG DER BUILD-AUSGABE. Eine `exports`-Map zeigt auf
+ *    `dist/index.js`. Im Quellindex gibt es nur `src/index.ts`. Mit
+ *    `rootDir`/`outDir` aus der Projektkonfiguration wird daraus wieder eine
+ *    Quelldatei — und der Workspace-Import zeigt auf echten Quelltext statt
+ *    auf ein Artefakt, das gar nicht indiziert ist.
+ *
+ * Jede Probe, die NICHT getroffen hat, wird mitgefuehrt und landet als
+ * `rejectedCandidates` an der unaufgeloesten Kante (E4): wer die Aufloesung
+ * spaeter debuggt, sieht, wonach gesucht wurde.
+ */
+import { basenameOf, extensionOf, joinRelative, normalizePath, relativeWithin } from "../paths.js";
+import type { ResolveContextV1, WorkspacePackageV1 } from "../types.js";
+
+/** Erweiterungen in Probierreihenfolge. Quelltext vor Build-Ausgabe. */
+export const DEFAULT_EXTENSION_ORDER = [
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".d.ts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".json",
+  ".py",
+  ".vue",
+] as const;
+
+/**
+ * Endung, wie sie im Spezifizierer steht → Endungen, die tatsaechlich gemeint
+ * sein koennen. Die geschriebene Endung steht bewusst mit in der Liste, denn
+ * es gibt Projekte, in denen `./bundle.js` wirklich `bundle.js` meint.
+ *
+ * WELCHE ZUERST PROBIERT WIRD, haengt an der Sprache der QUELLDATEI
+ * (`preferSourceExtension`): in einer TypeScript-Datei meint `./util.js`
+ * unter `NodeNext` die Datei `util.ts`, also gewinnt dort die Quellendung.
+ * In einer JavaScript-Datei ist `./util.js` woertlich gemeint, also gewinnt
+ * dort die geschriebene Endung. Liegen `util.ts` und `util.js` nebeneinander,
+ * ist das der einzige Fall, in dem die Reihenfolge ueberhaupt zaehlt — und
+ * dann ist sie so, wie der jeweilige Uebersetzer sie auch waehlt.
+ */
+export const ESM_EXTENSION_REMAP: Readonly<Record<string, readonly string[]>> = {
+  ".js": [".ts", ".tsx", ".d.ts", ".js"],
+  ".jsx": [".tsx", ".jsx"],
+  ".mjs": [".mts", ".d.mts", ".mjs"],
+  ".cjs": [".cts", ".d.cts", ".cjs"],
+};
+
+/** Erweiterungen, die als „nicht ausfuehrbarer Inhalt" gelten (spec.md §19/§20). */
+export const ASSET_EXTENSIONS = new Set([
+  ".avif",
+  ".css",
+  ".gif",
+  ".graphql",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".less",
+  ".md",
+  ".mdx",
+  ".png",
+  ".sass",
+  ".scss",
+  ".svg",
+  ".txt",
+  ".webp",
+  ".woff",
+  ".woff2",
+]);
+
+/** Ergebnis einer Kandidatenprobe. */
+export interface CandidateProbeV1 {
+  /** Gefundener repo-relativer Pfad; `null`, wenn keine Probe traf. */
+  path: string | null;
+  /** Alle geprueften Pfade in Probierreihenfolge — auch der Treffer. */
+  tried: string[];
+}
+
+/**
+ * Bildet alle Kandidatenpfade zu einem Basispfad, ohne den Index zu befragen.
+ * Reihenfolge ist Teil des Vertrags: sie entscheidet, welche Datei gewinnt,
+ * wenn mehrere existieren.
+ */
+export function candidatePaths(
+  basePath: string,
+  extensionOrder: readonly string[] = DEFAULT_EXTENSION_ORDER,
+  options: { preferSourceExtension?: boolean } = {},
+): string[] {
+  const preferSourceExtension = options.preferSourceExtension ?? true;
+  const normalized = normalizePath(basePath);
+  const candidates: string[] = [];
+  const push = (candidate: string): void => {
+    if (!candidates.includes(candidate)) {
+      candidates.push(candidate);
+    }
+  };
+
+  const written = extensionOf(normalized);
+  if (written !== "") {
+    const remap = ESM_EXTENSION_REMAP[written];
+    if (remap === undefined || !preferSourceExtension) {
+      push(normalized);
+    }
+    if (remap !== undefined) {
+      const stem = normalized.slice(0, normalized.length - written.length);
+      for (const extension of remap) {
+        push(`${stem}${extension}`);
+      }
+      push(normalized);
+    }
+    // Ein Punkt im Namen ist NICHT immer eine Erweiterung: `./vitest.config`
+    // meint `vitest.config.ts`. Deshalb wird nur dann noch eine Erweiterung
+    // angehaengt, wenn der geschriebene Suffix keine bekannte ist — sonst
+    // entstuenden Unsinnskandidaten wie `context.js.cts`, die die
+    // `rejectedCandidates` unlesbar machen.
+    if (!isKnownExtension(written, extensionOrder)) {
+      for (const extension of extensionOrder) {
+        push(`${normalized}${extension}`);
+      }
+    }
+    // Auch ein Pfad mit Punkt kann ein Verzeichnis sein.
+    for (const extension of extensionOrder) {
+      push(`${normalized}/index${extension}`);
+    }
+    return candidates;
+  }
+
+  push(normalized);
+  for (const extension of extensionOrder) {
+    push(`${normalized}${extension}`);
+  }
+  for (const extension of extensionOrder) {
+    push(`${normalized}/index${extension}`);
+  }
+  // Python: ein Paketverzeichnis wird ueber seine Initialisierungsdatei erreicht.
+  push(`${normalized}/__init__.py`);
+  return candidates;
+}
+
+/**
+ * Bildet einen Pfad in der Build-Ausgabe eines Pakets auf den entsprechenden
+ * Quellpfad ab. `null`, wenn der Pfad nicht in einer bekannten Build-Ausgabe
+ * liegt oder das Paket keine Abbildung deklariert.
+ */
+export function reverseBuildOutput(
+  packages: Iterable<WorkspacePackageV1>,
+  repoId: string,
+  path: string,
+): string | null {
+  const normalized = normalizePath(path);
+  for (const entry of packages) {
+    if (entry.repoId !== repoId) continue;
+    if (entry.outDir === undefined || entry.rootDir === undefined) continue;
+    const withinOutput = relativeWithin(entry.outDir, normalized);
+    if (withinOutput === null || withinOutput === "") continue;
+    const mapped = joinRelative(entry.rootDir, withinOutput);
+    if (mapped !== null) {
+      return mapped;
+    }
+  }
+  return null;
+}
+
+/**
+ * Sucht die erste existierende Datei zu einem Basispfad.
+ *
+ * Zuerst die direkten Kandidaten, danach — und nur, wenn keiner traf — die
+ * ueber `rootDir`/`outDir` zurueckgebildeten. Diese Reihenfolge ist wichtig:
+ * existiert die Build-Ausgabe wirklich im Index (weil jemand `dist/` mit
+ * indiziert hat), gewinnt sie, und wir erfinden keine Quelldatei.
+ */
+export function probeCandidates(
+  context: ResolveContextV1,
+  repoId: string,
+  basePath: string,
+): CandidateProbeV1 {
+  const tried: string[] = [];
+  // In einer JavaScript-Quelle ist die geschriebene Endung woertlich gemeint;
+  // in einer TypeScript-Quelle ist sie die Endung der BUILD-Ausgabe.
+  const probeOptions = { preferSourceExtension: context.fromLanguageId !== "javascript" };
+  const direct = candidatePaths(basePath, context.extensionOrder, probeOptions);
+  for (const candidate of direct) {
+    tried.push(candidate);
+    if (context.files.hasFile(repoId, candidate)) {
+      return { path: candidate, tried };
+    }
+  }
+  const mapped = reverseBuildOutput(context.packageCatalog.all(), repoId, basePath);
+  if (mapped === null) {
+    return { path: null, tried };
+  }
+  for (const candidate of candidatePaths(mapped, context.extensionOrder, probeOptions)) {
+    if (tried.includes(candidate)) continue;
+    tried.push(candidate);
+    if (context.files.hasFile(repoId, candidate)) {
+      return { path: candidate, tried };
+    }
+  }
+  return { path: null, tried };
+}
+
+function isKnownExtension(extension: string, extensionOrder: readonly string[]): boolean {
+  return (
+    extensionOrder.includes(extension) ||
+    extension in ESM_EXTENSION_REMAP ||
+    ASSET_EXTENSIONS.has(extension)
+  );
+}
+
+/** True, wenn der Spezifizierer auf eine Nicht-Code-Ressource zeigt. */
+export function isAssetSpecifier(specifier: string): boolean {
+  const withoutQuery = specifier.split("?")[0] ?? specifier;
+  return ASSET_EXTENSIONS.has(extensionOf(basenameOf(withoutQuery)));
+}

package/src/resolve/package-exports.ts

@@ -0,0 +1,268 @@
+/**
+ * Auswertung der `exports`- und `imports`-Karten eines Paketmanifests
+ * (spec.md §14.3 „Node Package Exports").
+ *
+ * Was hier abgedeckt ist: die String-Kurzform, die Bedingungsobjekte
+ * (`types`/`node`/`import`/`require`/`default`), die Subpfadkarte, die
+ * Musterform mit `*`, Arrays als Fallbackliste und `null` als bewusste
+ * Sperre eines Subpfads.
+ *
+ * BEDINGUNGSREIHENFOLGE: Laufzeitbedingungen kommen VOR `types`. Grund: ein
+ * `types`-Treffer zeigt auf eine Deklarationsdatei (`.d.ts`), und die ist im
+ * Quellindex eines Monorepos praktisch nie vorhanden — die Kante waere
+ * unaufgeloest, obwohl das Paket eindeutig bestimmt ist. Ueber die
+ * Laufzeitbedingung landet man auf der Build-Ausgabe, und die
+ * `rootDir`/`outDir`-Rueckabbildung fuehrt von dort zur Quelldatei.
+ *
+ * `null` als Ziel ist KEIN „nicht gefunden": es ist die ausdrueckliche
+ * Aussage des Paketautors, dass dieser Subpfad nicht importiert werden darf.
+ * Das wird als eigener Grund gemeldet und nicht mit einem Fehlschlag
+ * verwechselt (E4).
+ */
+import { joinRelative, normalizePath } from "../paths.js";
+import type { WorkspacePackageV1 } from "../types.js";
+
+/** Bedingungen in Auswertungsreihenfolge. */
+export const DEFAULT_EXPORT_CONDITIONS = ["node", "import", "require", "default", "types"] as const;
+
+/** Ergebnis der Subpfadauswertung. */
+export type SubpathResolution =
+  | { status: "target"; target: string; via: "exports" | "imports" | "manifest-field" | "direct" }
+  | { status: "blocked"; detail: string }
+  | { status: "no_match"; detail: string };
+
+/**
+ * Loest einen Subpfad eines Pakets auf einen repo-relativen Basispfad auf.
+ *
+ * `subpath` ist `"."` fuer den Paketwurzel-Import oder `"./unter/pfad"`.
+ * Das Ergebnis ist ein Pfad OHNE Existenzpruefung — die uebernimmt
+ * `probeCandidates`.
+ */
+export function resolvePackageSubpath(
+  entry: WorkspacePackageV1,
+  subpath: string,
+  conditions: readonly string[] = DEFAULT_EXPORT_CONDITIONS,
+): SubpathResolution {
+  const normalizedSubpath = subpath === "" ? "." : subpath;
+
+  if (entry.exports !== undefined) {
+    const matched = matchExportsMap(entry.exports, normalizedSubpath, conditions);
+    if (matched.status === "target") {
+      const joined = joinRelative(entry.packageDir, matched.target);
+      if (joined === null) {
+        return {
+          status: "no_match",
+          detail: `exports target "${matched.target}" escapes the package directory "${entry.packageDir}"`,
+        };
+      }
+      return { status: "target", target: joined, via: "exports" };
+    }
+    if (matched.status === "blocked") {
+      return matched;
+    }
+    // Kein Subpfadtreffer in einer vorhandenen exports-Karte: das Paket
+    // kapselt seinen Inhalt, der Import ist ungueltig. Kein stiller Rueckfall
+    // auf den Verzeichnispfad — das waere geraten.
+    return {
+      status: "no_match",
+      detail: `package "${entry.name}" declares "exports" but no entry matches subpath "${normalizedSubpath}"`,
+    };
+  }
+
+  if (normalizedSubpath === ".") {
+    for (const field of ["module", "main", "types"] as const) {
+      const value = entry[field];
+      if (value === undefined) continue;
+      const joined = joinRelative(entry.packageDir, value);
+      if (joined !== null) {
+        return { status: "target", target: joined, via: "manifest-field" };
+      }
+    }
+    const indexPath = joinRelative(entry.packageDir, "index");
+    if (indexPath === null) {
+      return {
+        status: "no_match",
+        detail: `package directory "${entry.packageDir}" is not usable`,
+      };
+    }
+    return { status: "target", target: indexPath, via: "direct" };
+  }
+
+  const joined = joinRelative(entry.packageDir, normalizedSubpath);
+  if (joined === null) {
+    return {
+      status: "no_match",
+      detail: `subpath "${normalizedSubpath}" escapes the package directory "${entry.packageDir}"`,
+    };
+  }
+  return { status: "target", target: joined, via: "direct" };
+}
+
+/** Loest einen `#`-Subpath-Import gegen die `imports`-Karte eines Pakets auf. */
+export function resolvePackageImports(
+  entry: WorkspacePackageV1,
+  specifier: string,
+  conditions: readonly string[] = DEFAULT_EXPORT_CONDITIONS,
+): SubpathResolution {
+  if (entry.imports === undefined) {
+    return {
+      status: "no_match",
+      detail: `package "${entry.name}" declares no "imports" map for "${specifier}"`,
+    };
+  }
+  const matched = matchExportsMap(entry.imports, specifier, conditions);
+  if (matched.status !== "target") {
+    return matched;
+  }
+  const joined = joinRelative(entry.packageDir, matched.target);
+  if (joined === null) {
+    return {
+      status: "no_match",
+      detail: `imports target "${matched.target}" escapes the package directory "${entry.packageDir}"`,
+    };
+  }
+  return { status: "target", target: joined, via: "imports" };
+}
+
+type MapMatch =
+  | { status: "target"; target: string }
+  | { status: "blocked"; detail: string }
+  | { status: "no_match"; detail: string };
+
+function matchExportsMap(map: unknown, key: string, conditions: readonly string[]): MapMatch {
+  // Kurzform: `"exports": "./dist/index.js"` gilt nur fuer ".".
+  if (typeof map === "string") {
+    return key === "."
+      ? { status: "target", target: map }
+      : { status: "no_match", detail: `string "exports" only covers subpath "."` };
+  }
+  if (map === null) {
+    return { status: "blocked", detail: `"exports" is null — the package blocks all subpaths` };
+  }
+  if (Array.isArray(map)) {
+    return selectFromList(map, key, conditions);
+  }
+  if (typeof map !== "object") {
+    return { status: "no_match", detail: `"exports" is neither string, array nor object` };
+  }
+
+  const record = map as Record<string, unknown>;
+  const keys = Object.keys(record);
+  const isSubpathMap = keys.some(
+    (entry) => entry === "." || entry.startsWith("./") || entry.startsWith("#"),
+  );
+
+  if (!isSubpathMap) {
+    // Reines Bedingungsobjekt: gilt fuer ".".
+    if (key !== ".") {
+      return { status: "no_match", detail: `condition-only "exports" only covers subpath "."` };
+    }
+    return selectCondition(record, conditions);
+  }
+
+  const exact = record[key];
+  if (exact !== undefined) {
+    return resolveConditionValue(exact, conditions, key);
+  }
+
+  // Musterform: "./features/*": "./dist/features/*.js"
+  let best: { pattern: string; value: unknown; captured: string } | null = null;
+  for (const pattern of keys) {
+    const starIndex = pattern.indexOf("*");
+    if (starIndex === -1) continue;
+    const prefix = pattern.slice(0, starIndex);
+    const suffix = pattern.slice(starIndex + 1);
+    if (!key.startsWith(prefix) || !key.endsWith(suffix)) continue;
+    if (key.length < prefix.length + suffix.length) continue;
+    const captured = key.slice(prefix.length, key.length - suffix.length);
+    // Node waehlt bei mehreren Mustern das mit dem laengsten Praefix.
+    if (best === null || prefix.length > best.pattern.indexOf("*")) {
+      best = { pattern, value: record[pattern], captured };
+    }
+  }
+  if (best === null) {
+    return { status: "no_match", detail: `no "exports" entry matches "${key}"` };
+  }
+  const resolved = resolveConditionValue(best.value, conditions, key);
+  if (resolved.status !== "target") {
+    return resolved;
+  }
+  return { status: "target", target: resolved.target.split("*").join(best.captured) };
+}
+
+function resolveConditionValue(
+  value: unknown,
+  conditions: readonly string[],
+  key: string,
+): MapMatch {
+  if (value === null) {
+    return {
+      status: "blocked",
+      detail: `"exports" entry for "${key}" is null — import is forbidden`,
+    };
+  }
+  if (typeof value === "string") {
+    return { status: "target", target: value };
+  }
+  if (Array.isArray(value)) {
+    return selectFromList(value, key, conditions);
+  }
+  if (typeof value === "object") {
+    return selectCondition(value as Record<string, unknown>, conditions);
+  }
+  return { status: "no_match", detail: `"exports" entry for "${key}" has an unusable type` };
+}
+
+function selectFromList(
+  list: readonly unknown[],
+  key: string,
+  conditions: readonly string[],
+): MapMatch {
+  const details: string[] = [];
+  for (const candidate of list) {
+    const resolved = resolveConditionValue(candidate, conditions, key);
+    if (resolved.status === "target") {
+      return resolved;
+    }
+    details.push(resolved.detail);
+  }
+  return {
+    status: "no_match",
+    detail: `no usable entry in "exports" array for "${key}" (${details.join("; ")})`,
+  };
+}
+
+function selectCondition(record: Record<string, unknown>, conditions: readonly string[]): MapMatch {
+  for (const condition of conditions) {
+    if (!(condition in record)) continue;
+    const value = record[condition];
+    const resolved = resolveConditionValue(value, conditions, condition);
+    if (resolved.status === "target" || resolved.status === "blocked") {
+      return resolved;
+    }
+  }
+  return {
+    status: "no_match",
+    detail: `none of the conditions [${conditions.join(", ")}] is present in [${Object.keys(record).join(", ")}]`,
+  };
+}
+
+/** Zerlegt einen Paketspezifizierer in Paketname und Subpfad. */
+export function splitPackageSpecifier(specifier: string): { name: string; subpath: string } | null {
+  const normalized = normalizePath(specifier);
+  if (normalized === "") {
+    return null;
+  }
+  const segments = normalized.split("/");
+  if (normalized.startsWith("@")) {
+    if (segments.length < 2 || segments[1] === undefined || segments[1] === "") {
+      return null;
+    }
+    const name = `${segments[0] as string}/${segments[1]}`;
+    const rest = segments.slice(2).join("/");
+    return { name, subpath: rest === "" ? "." : `./${rest}` };
+  }
+  const name = segments[0] as string;
+  const rest = segments.slice(1).join("/");
+  return { name, subpath: rest === "" ? "." : `./${rest}` };
+}

package/src/resolve/pipeline.ts

@@ -0,0 +1,140 @@
+/**
+ * Die Resolver-Pipeline (architecture.md §16.2).
+ *
+ * Reihenfolge wie dort festgelegt: relativer Pfad → Sprachaliase →
+ * Projektaliase → Workspace-Paketkarte → installierte Paketmetadaten →
+ * Klassifikation als extern/unaufgeloest.
+ *
+ * DER WICHTIGE TEIL IST DAS SCHEITERN. Ein Resolver, der zustaendig war und
+ * NICHT getroffen hat, beendet die Suche nicht: der naechste zustaendige darf
+ * es versuchen. Erst wenn keiner mehr uebrig ist, entsteht eine unaufgeloeste
+ * Kante — und die traegt dann den Grund des ERSTEN zustaendigen Resolvers,
+ * ergaenzt um die Namen aller weiteren Versuche und die Vereinigung aller
+ * geprueften Kandidaten. Ein pauschales „konnte nicht aufgeloest werden" ohne
+ * diese Spur waere genau die stille Ausblendung, die E4 verbietet.
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+
+import type { ImportResolverV1, ResolveContextV1, ResolveResultV1 } from "../types.js";
+
+import {
+  configuredAliasResolver,
+  installedPackageResolver,
+  projectAliasResolver,
+  pythonModuleResolver,
+  relativePathResolver,
+  runtimeBuiltinResolver,
+  subpathImportResolver,
+  workspacePackageResolver,
+} from "./resolvers.js";
+
+/** Die Standardpipeline in der Reihenfolge von architecture.md §16.2. */
+export const DEFAULT_RESOLVER_PIPELINE: readonly ImportResolverV1[] = [
+  relativePathResolver,
+  runtimeBuiltinResolver,
+  subpathImportResolver,
+  pythonModuleResolver,
+  projectAliasResolver,
+  configuredAliasResolver,
+  workspacePackageResolver,
+  installedPackageResolver,
+];
+
+/** Ergebnis eines Pipelinelaufs samt der Spur der befragten Resolver. */
+export interface PipelineOutcomeV1 {
+  result: ResolveResultV1;
+  /** Namen aller Resolver, die sich zustaendig erklaert haben, in Reihenfolge. */
+  attemptedResolvers: string[];
+}
+
+export function resolveImport(
+  specifier: string,
+  context: ResolveContextV1,
+  pipeline: readonly ImportResolverV1[] = DEFAULT_RESOLVER_PIPELINE,
+): PipelineOutcomeV1 {
+  const attempted: string[] = [];
+  const failures: {
+    resolver: string;
+    result: Extract<ResolveResultV1, { status: "unresolved" }>;
+  }[] = [];
+
+  for (const resolver of pipeline) {
+    let supports: boolean;
+    try {
+      supports = resolver.supports(specifier, context);
+    } catch (error) {
+      // Ein werfender Resolver darf die Kette nicht abbrechen — der Fehler
+      // wird zum benannten Fehlschlag, nicht zum verschluckten Ausnahmefall.
+      attempted.push(resolver.name);
+      failures.push({
+        resolver: resolver.name,
+        result: {
+          status: "unresolved",
+          reason: "no_resolver_supports_specifier",
+          detail: `resolver "${resolver.name}" threw while deciding support: ${messageOf(error)}`,
+        },
+      });
+      continue;
+    }
+    if (!supports) continue;
+    attempted.push(resolver.name);
+
+    let outcome: ResolveResultV1 | null;
+    try {
+      outcome = resolver.resolve(specifier, context);
+    } catch (error) {
+      failures.push({
+        resolver: resolver.name,
+        result: {
+          status: "unresolved",
+          reason: "target_file_not_found",
+          detail: `resolver "${resolver.name}" threw: ${messageOf(error)}`,
+        },
+      });
+      continue;
+    }
+    if (outcome === null) continue;
+    if (outcome.status !== "unresolved") {
+      return { result: outcome, attemptedResolvers: attempted };
+    }
+    failures.push({ resolver: resolver.name, result: outcome });
+  }
+
+  if (failures.length === 0) {
+    return {
+      result: {
+        status: "unresolved",
+        reason: "no_resolver_supports_specifier",
+        detail: `no resolver in [${pipeline.map((entry) => entry.name).join(", ")}] claims specifier "${specifier}" from "${context.fromPath}"`,
+      },
+      attemptedResolvers: attempted,
+    };
+  }
+
+  const first = failures[0] as {
+    resolver: string;
+    result: Extract<ResolveResultV1, { status: "unresolved" }>;
+  };
+  const rejected = new Set<string>();
+  for (const failure of failures) {
+    for (const candidate of failure.result.rejectedCandidates ?? []) {
+      rejected.add(candidate);
+    }
+  }
+  const trail = failures
+    .map((failure) => `${failure.resolver}: ${failure.result.detail}`)
+    .join(" | ");
+  return {
+    result: {
+      status: "unresolved",
+      reason: first.result.reason,
+      detail: trail,
+      ...(rejected.size > 0 ? { rejectedCandidates: [...rejected].sort(compareCodepoints) } : {}),
+    },
+    attemptedResolvers: attempted,
+  };
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}