@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/vite/discovery/discover-routers.ts

@@ -0,0 +1,389 @@
+/**
+ * Router Discovery
+ *
+ * Core discovery logic: imports the user's entry file via the RSC
+ * environment's module runner, generates manifests for each discovered
+ * router, and builds route tries for O(path_length) matching.
+ */
+
+import {
+  buildCombinedRouteMapForRouterFile,
+  formatNestedRouterConflictError,
+  findNestedRouterConflict,
+} from "../../build/generate-route-types.js";
+// Pure data transforms over generateManifestFull's output. Imported directly
+// from source (not the public ./build barrel, and not the runner) because they
+// are realm-independent: buildRouteTrie/buildPerRouterTrie operate on plain
+// manifest data, and collectFallbackClientRefs keys on the global-registry
+// Symbol.for("react.client.reference"), so it detects client references in a
+// boundary tree regardless of which realm imported the walker. Only
+// generateManifestFull must stay on the runner (it invokes user handlers via
+// RangoContext from the runner realm) — see the runner.import below.
+import { buildRouteTrie, buildPerRouterTrie } from "../../build/route-trie.js";
+import { collectFallbackClientRefs } from "../../build/collect-fallback-refs.js";
+import {
+  flattenLeafEntries,
+  buildRouteToStaticPrefix,
+} from "../utils/manifest-utils.js";
+import type { DiscoveryState, PrecomputedEntry } from "./state.js";
+import {
+  expandPrerenderRoutes,
+  renderStaticHandlers,
+} from "./prerender-collection.js";
+import {
+  resolveHostRouterHandlers,
+  DiscoveryError,
+  type CaughtDiscoveryError,
+} from "./discovery-errors.js";
+import { createRangoDebugger, timed, NS } from "../debug.js";
+import { computeProductionHash } from "../plugins/client-ref-hashing.js";
+
+const debug = createRangoDebugger(NS.discovery);
+
+/**
+ * Import the user's entry via RSC runner, generate manifests for each
+ * discovered router, build route tries, and optionally run prerender
+ * expansion and static handler rendering (build mode only).
+ *
+ * Returns the imported `@rangojs/router/server` module so the caller
+ * can access the RouterRegistry and manifest setters.
+ */
+export async function discoverRouters(
+  state: DiscoveryState,
+  rscEnv: any,
+): Promise<any> {
+  if (!state.resolvedEntryPath) return;
+
+  // Import the entry file via RSC environment.
+  // For node preset: this is the router file (createRouter() registers in RouterRegistry).
+  // For cloudflare preset: this is the worker entry (which imports the router).
+  await timed(debug, "inner: import entry", () =>
+    rscEnv.runner.import(state.resolvedEntryPath),
+  );
+
+  // Import the router package to access the registry
+  const serverMod = await timed(
+    debug,
+    "inner: import @rangojs/router/server",
+    () => rscEnv.runner.import("@rangojs/router/server"),
+  );
+  let registry: Map<string, any> = serverMod.RouterRegistry;
+
+  if (!registry || registry.size === 0) {
+    // No RSC routers found directly. Check for host routers with lazy handlers
+    // that need to be resolved to trigger sub-app createRouter() calls.
+    //
+    // Handler failures are collected rather than swallowed: when the registry
+    // is still empty afterwards, these errors (typically a sub-app whose router
+    // module failed to import) are the most likely cause and are surfaced in
+    // the terminal "No routers found" error below.
+    const discoveryErrors: CaughtDiscoveryError[] = [];
+    try {
+      const hostRegistry: Map<string, any> | undefined =
+        serverMod.HostRouterRegistry;
+
+      if (hostRegistry && hostRegistry.size > 0) {
+        console.log(
+          `[rango] Found ${hostRegistry.size} host router(s), resolving lazy handlers...`,
+        );
+
+        const handlerErrors = await resolveHostRouterHandlers(hostRegistry);
+        discoveryErrors.push(...handlerErrors);
+        for (const { context, error } of handlerErrors) {
+          debug?.("caught error while resolving %s: %O", context, error);
+        }
+
+        // Re-read RouterRegistry - sub-app createRouter() calls should have populated it
+        const freshServerMod = await rscEnv.runner.import(
+          "@rangojs/router/server",
+        );
+        const freshRegistry: Map<string, any> = freshServerMod.RouterRegistry;
+
+        if (freshRegistry && freshRegistry.size > 0) {
+          // Update references so the manifest generation below uses the fresh data
+          Object.assign(serverMod, freshServerMod);
+          registry = freshRegistry;
+        }
+      }
+    } catch (error) {
+      // Host-router discovery is best-effort; record the failure so it can be
+      // surfaced if no routers are found.
+      discoveryErrors.push({ context: "host-router discovery", error });
+    }
+
+    // If still no routers after host router resolution, fail
+    if (!registry || registry.size === 0) {
+      throw new DiscoveryError(state.resolvedEntryPath, discoveryErrors);
+    }
+  }
+
+  // generateManifestFull must run in the RSC runner realm: it invokes the
+  // user's urlpatterns.handler() via RangoContext, consuming router instances
+  // from the runner. The trie/fallback-ref builders are pure transforms over
+  // its output and are imported directly from source above.
+  const buildMod = await timed(
+    debug,
+    "inner: import @rangojs/router/build",
+    () => rscEnv.runner.import("@rangojs/router/build"),
+  );
+  const generateManifestFull = buildMod.generateManifestFull;
+
+  debug?.("inner: found %d router(s) in registry", registry.size);
+
+  const nestedRouterConflict = findNestedRouterConflict(
+    [...registry.values()]
+      .map((router) => router.__sourceFile)
+      .filter(
+        (sourceFile): sourceFile is string => typeof sourceFile === "string",
+      ),
+  );
+  if (nestedRouterConflict) {
+    throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
+  }
+
+  // Build into local variables first. Only commit to state after the
+  // full pass succeeds, so a failed re-discovery preserves the last
+  // known-good state instead of leaving it partially wiped.
+  const newMergedRouteManifest: Record<string, string> = {};
+  const newMergedPrecomputedEntries: PrecomputedEntry[] = [];
+  const newPerRouterManifests: typeof state.perRouterManifests = [];
+  const newPerRouterManifestDataMap = new Map<string, any>();
+  const newPerRouterPrecomputedMap = new Map<string, PrecomputedEntry[]>();
+  const newPerRouterTrieMap = new Map<string, any>();
+  let mergedRouteAncestry: Record<string, string[]> = {};
+  let mergedRouteTrailingSlash: Record<string, string> = {};
+
+  let routerMountIndex = 0;
+  // Collect all manifests for trie building (avoid re-running generateManifest)
+  const allManifests: Array<{ id: string; manifest: any }> = [];
+
+  // Built-in clientChunks context (present only when the built-in strategy is
+  // active). Collect the production hashes of "use client" error/notFound
+  // fallback modules so the strategy can route them into app-fallback.
+  const clientChunkCtx = state.opts?.clientChunkCtx;
+  const collectClientFallbackRef = clientChunkCtx
+    ? (refKey: string) =>
+        clientChunkCtx.fallbackRefs.add(
+          computeProductionHash(state.projectRoot, refKey),
+        )
+    : undefined;
+  // Router-level boundary defaults (`createRouter({ defaultErrorBoundary, ... })`)
+  // are NOT in EntryData, so generateManifestFull's walk misses them. Collect any
+  // "use client" default boundary directly off the router instance. The value is
+  // commonly a handler function wrapping the client boundary in server providers,
+  // so collectFallbackClientRefs invokes + walks the tree. The walker keys on the
+  // global-registry Symbol.for("react.client.reference"), so it detects client
+  // references in a runner-realm boundary tree even when imported here directly.
+  const collectFromBoundaryNode = (node: unknown): void => {
+    if (collectClientFallbackRef) {
+      collectFallbackClientRefs(node, collectClientFallbackRef);
+    }
+  };
+
+  const manifestGenStart = debug ? performance.now() : 0;
+  for (const [id, router] of registry) {
+    if (!router.urlpatterns || !generateManifestFull) {
+      continue;
+    }
+
+    const manifest = await generateManifestFull(
+      router.urlpatterns,
+      routerMountIndex,
+      {
+        ...(router.__basename ? { urlPrefix: router.__basename } : {}),
+        ...(collectClientFallbackRef ? { collectClientFallbackRef } : {}),
+      },
+    );
+    routerMountIndex++;
+    allManifests.push({ id, manifest });
+
+    // Router-level "use client" boundary defaults -> app-fallback (the
+    // route-tree errorBoundary()/notFoundBoundary() helpers are already
+    // collected inside generateManifestFull via collectClientFallbackRef).
+    if (collectClientFallbackRef) {
+      collectFromBoundaryNode(router.__defaultErrorBoundary);
+      collectFromBoundaryNode(router.__defaultNotFoundBoundary);
+      collectFromBoundaryNode(router.__notFound);
+    }
+
+    const routeCount = Object.keys(manifest.routeManifest).length;
+    const staticRoutes = Object.values(manifest.routeManifest).filter(
+      (p: any) => !p.includes(":") && !p.includes("*"),
+    ).length;
+    const dynamicRoutes = routeCount - staticRoutes;
+
+    // Merge into the combined manifest
+    Object.assign(newMergedRouteManifest, manifest.routeManifest);
+
+    // Compute factory-only prefixes: dot-prefixed groups in the runtime
+    // manifest that the static parser cannot see. These are routes created
+    // by factory functions (e.g. createDocsPatterns()) and should always be
+    // supplemented on file change since HMR won't re-discover them.
+    let factoryOnlyPrefixes: Set<string> | undefined;
+    if (router.__sourceFile) {
+      const staticParsed = buildCombinedRouteMapForRouterFile(
+        router.__sourceFile,
+      );
+      const staticNames = new Set(Object.keys(staticParsed.routes));
+      factoryOnlyPrefixes = new Set<string>();
+      for (const name of Object.keys(manifest.routeManifest)) {
+        if (staticNames.has(name)) continue;
+        const dotIdx = name.indexOf(".");
+        if (dotIdx <= 0) continue;
+        const prefix = name.substring(0, dotIdx + 1);
+        if ([...staticNames].some((n) => n.startsWith(prefix))) continue;
+        factoryOnlyPrefixes.add(prefix);
+      }
+      if (factoryOnlyPrefixes.size === 0) factoryOnlyPrefixes = undefined;
+    }
+
+    newPerRouterManifests.push({
+      id,
+      routeManifest: manifest.routeManifest,
+      routeSearchSchemas: manifest.routeSearchSchemas,
+      sourceFile: router.__sourceFile,
+      factoryOnlyPrefixes,
+    });
+
+    // Merge ancestry (internal field, used only for trie building)
+    if (manifest._routeAncestry) {
+      Object.assign(mergedRouteAncestry, manifest._routeAncestry);
+    }
+    // Merge trailing slash config
+    if (manifest.routeTrailingSlash) {
+      Object.assign(mergedRouteTrailingSlash, manifest.routeTrailingSlash);
+    }
+
+    // Flatten prefix tree leaf nodes into precomputed entries.
+    // Leaf nodes (no children) can have their routes used directly by
+    // evaluateLazyEntry() without running the handler at runtime.
+    // Walk once into a per-router array, then fold it into the merged array;
+    // the merged and per-router entries are identical, so a second walk is
+    // redundant. Append order is preserved within and across routers.
+    const routerPrecomputed: PrecomputedEntry[] = [];
+    flattenLeafEntries(
+      manifest.prefixTree,
+      manifest.routeManifest,
+      routerPrecomputed,
+    );
+    newMergedPrecomputedEntries.push(...routerPrecomputed);
+
+    // Store per-router manifest and precomputed entries for isolated virtual modules.
+    newPerRouterManifestDataMap.set(id, manifest.routeManifest);
+    newPerRouterPrecomputedMap.set(id, routerPrecomputed);
+
+    console.log(
+      `[rango] Router "${id}" -> ${routeCount} routes ` +
+        `(${staticRoutes} static, ${dynamicRoutes} dynamic)`,
+    );
+  }
+
+  // Warn if multiple routers use auto-generated IDs (router_0, router_1, ...).
+  // Auto-IDs are assigned by counter and depend on module evaluation order,
+  // which can differ between build time and runtime (especially with dynamic
+  // imports in host routers). This causes per-router data to be loaded into
+  // the wrong router at runtime.
+  if (registry.size > 1) {
+    const autoIds = [...registry.keys()].filter((id) =>
+      /^router_\d+$/.test(id),
+    );
+    if (autoIds.length > 1) {
+      console.warn(
+        `[rango] WARNING: ${autoIds.length} routers use auto-generated IDs (${autoIds.join(", ")}). ` +
+          `In multi-router setups, each createRouter() must have an explicit \`id\` option ` +
+          `to ensure per-router manifest data is matched correctly at runtime. ` +
+          `Example: createRouter({ id: "site", ... })`,
+      );
+    }
+  }
+
+  debug?.(
+    "inner: generated manifests for %d router(s) (%sms)",
+    allManifests.length,
+    (performance.now() - manifestGenStart).toFixed(1),
+  );
+
+  // Build route trie from merged manifest + ancestry
+  let newMergedRouteTrie: any = null;
+  const trieStart = debug ? performance.now() : 0;
+  if (Object.keys(newMergedRouteManifest).length > 0) {
+    if (mergedRouteAncestry) {
+      // Build routeToStaticPrefix from saved manifests
+      const routeToStaticPrefix: Record<string, string> = {};
+      for (const { manifest } of allManifests) {
+        // Root-level routes have empty static prefix
+        for (const name of Object.keys(manifest.routeManifest)) {
+          if (!(name in routeToStaticPrefix)) {
+            routeToStaticPrefix[name] = "";
+          }
+        }
+        buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
+      }
+
+      // Collect prerender route names and response type routes from all manifests
+      const prerenderRouteNames = new Set<string>();
+      const passthroughRouteNames = new Set<string>();
+      const mergedResponseTypeRoutes: Record<string, string> = {};
+      for (const { manifest } of allManifests) {
+        if (manifest.prerenderRoutes) {
+          for (const name of manifest.prerenderRoutes) {
+            prerenderRouteNames.add(name);
+          }
+        }
+        if (manifest.passthroughRoutes) {
+          for (const name of manifest.passthroughRoutes) {
+            passthroughRouteNames.add(name);
+          }
+        }
+        if (manifest.responseTypeRoutes) {
+          Object.assign(mergedResponseTypeRoutes, manifest.responseTypeRoutes);
+        }
+      }
+
+      // buildRouteTrie reads these via ?.has / ?.[] — empty is observationally
+      // identical to undefined, so no empty->undefined coercion is needed.
+      newMergedRouteTrie = buildRouteTrie(
+        newMergedRouteManifest,
+        mergedRouteAncestry,
+        routeToStaticPrefix,
+        mergedRouteTrailingSlash,
+        prerenderRouteNames,
+        passthroughRouteNames,
+        mergedResponseTypeRoutes,
+      );
+
+      // Build per-router tries for multi-router isolation. Uses the single
+      // shared buildPerRouterTrie so the production serialized trie is built by
+      // exactly the same code as the dev/HMR runtime rebuild (manifest-init.ts).
+      // Returns null for route-less manifests (route-trie.ts).
+      for (const { id, manifest } of allManifests) {
+        const perRouterTrie = buildPerRouterTrie(manifest);
+        if (perRouterTrie) {
+          newPerRouterTrieMap.set(id, perRouterTrie);
+        }
+      }
+    }
+  }
+
+  debug?.(
+    "inner: trie build done (%sms)",
+    (performance.now() - trieStart).toFixed(1),
+  );
+
+  // Commit all local state to the shared discovery state atomically.
+  // This ensures a failed re-discovery (e.g. from a transient module
+  // evaluation error) preserves the last known-good state.
+  state.mergedRouteManifest = newMergedRouteManifest;
+  state.mergedPrecomputedEntries = newMergedPrecomputedEntries;
+  state.perRouterManifests = newPerRouterManifests;
+  state.perRouterManifestDataMap = newPerRouterManifestDataMap;
+  state.perRouterPrecomputedMap = newPerRouterPrecomputedMap;
+  state.perRouterTrieMap = newPerRouterTrieMap;
+  state.mergedRouteTrie = newMergedRouteTrie;
+
+  // Expand prerender routes and render static handlers (build mode only)
+  await expandPrerenderRoutes(state, rscEnv, registry, allManifests);
+  await renderStaticHandlers(state, rscEnv, registry);
+
+  return serverMod;
+}

package/src/vite/discovery/discovery-errors.ts

@@ -0,0 +1,255 @@
+/**
+ * Router discovery error aggregation.
+ *
+ * During host-router discovery the lazy mounts registered by a host router are
+ * invoked to trigger each sub-app's createRouter() registration. Some mount
+ * failures are expected in the temporary discovery server context (a sub-app may
+ * reference runtime-only bindings), so each is invoked defensively and its error
+ * is collected rather than thrown.
+ *
+ * Previously these errors were discarded with an empty `catch {}`. When a real
+ * failure - typically a sub-app whose router module fails to import - left the
+ * registry empty, discovery reported the misleading "No routers found" message
+ * with no trace of the underlying cause. The collected errors are now surfaced
+ * via the `DiscoveryError` thrown at the end of discovery (issue #499).
+ *
+ * Which entries to invoke is taken from the consumer's declared intent, not
+ * inferred from the function's shape. A host route is registered either with
+ * `.map((request) => Response)` (an inline request handler, `kind: "handler"`)
+ * or `.lazy(() => import("./sub-app"))` (a lazy mount, `kind: "lazy"`). Only
+ * `kind === "lazy"` entries are invoked here; inline handlers are never invoked
+ * during discovery (they need a Request and register no routers). Because a lazy
+ * entry is known to be a module loader, ANY failure it produces - a synchronous
+ * throw or a rejected promise - is a genuine discovery failure and is collected.
+ */
+
+/** An error caught (and previously swallowed) while resolving host routers. */
+export interface CaughtDiscoveryError {
+  /** Human-readable description of where the error was caught. */
+  context: string;
+  /** The caught value (an Error or otherwise). */
+  error: unknown;
+}
+
+/**
+ * Minimal shape of a host registry entry needed for mount resolution.
+ * Mirrors the runtime HostRouterRegistry value without coupling to its type.
+ */
+interface HostRegistryRoute {
+  handler?: unknown;
+  kind?: string;
+}
+interface HostRegistryEntry {
+  routes: HostRegistryRoute[];
+  fallback?: HostRegistryRoute | null;
+}
+
+/** Indent every non-empty line of `text` by `pad`. */
+function indent(text: string, pad: string): string {
+  return text
+    .split("\n")
+    .map((line) => (line.length > 0 ? pad + line : line))
+    .join("\n");
+}
+
+/**
+ * Invoke a single lazy mount to trigger its sub-app import (and createRouter()
+ * registration), collecting any failure under `context`. The entry is known to
+ * be a loader (`kind === "lazy"`), so both a synchronous throw and a rejected
+ * promise are genuine failures - no shape heuristics are needed.
+ */
+async function invokeLazyMount(
+  loader: () => unknown,
+  context: string,
+  errors: CaughtDiscoveryError[],
+): Promise<void> {
+  try {
+    await loader();
+  } catch (error) {
+    errors.push({ context, error });
+  }
+}
+
+/** Whether a registry route is a `.lazy()` mount with an invokable loader. */
+function isLazyMount(
+  route: HostRegistryRoute | null | undefined,
+): route is { handler: () => unknown; kind: "lazy" } {
+  return (
+    !!route && route.kind === "lazy" && typeof route.handler === "function"
+  );
+}
+
+/**
+ * Invoke every lazy mount in the host registry to trigger sub-app
+ * createRouter() registration, collecting (not throwing) any failures.
+ *
+ * Only `.lazy()` entries are invoked; `.map()` inline request handlers are
+ * skipped (they need a Request and register no routers). Failures are returned
+ * rather than thrown because some mounts legitimately fail in the temporary
+ * discovery server context; the caller decides whether the failures matter,
+ * which is only when discovery finds no routers at all.
+ */
+export async function resolveHostRouterHandlers(
+  hostRegistry: Map<string, HostRegistryEntry>,
+): Promise<CaughtDiscoveryError[]> {
+  const errors: CaughtDiscoveryError[] = [];
+
+  for (const [hostId, entry] of hostRegistry) {
+    for (const route of entry.routes) {
+      if (isLazyMount(route)) {
+        await invokeLazyMount(
+          route.handler,
+          `host "${hostId}" route handler`,
+          errors,
+        );
+      }
+    }
+    if (isLazyMount(entry.fallback)) {
+      await invokeLazyMount(
+        entry.fallback.handler,
+        `host "${hostId}" fallback handler`,
+        errors,
+      );
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Build the terminal "No routers found" message, appending any errors caught
+ * during host-router discovery so the real cause is visible.
+ *
+ * The aggregated errors are inlined into the message (in addition to being
+ * attached via `cause` on `DiscoveryError`) so they survive every caller: the
+ * dev/HMR paths log `err.message`, and the build path re-throws using
+ * `err.stack`, which begins with the message. None of those callers traverse
+ * `cause`, so the message must carry the detail. Each error includes its stack
+ * when available.
+ */
+export function formatNoRoutersError(
+  entryPath: string | undefined,
+  errors: CaughtDiscoveryError[],
+): string {
+  const base = `[rango] No routers found in registry after importing ${entryPath}`;
+  if (errors.length === 0) {
+    return base;
+  }
+
+  const formatted = errors
+    .map(({ context, error }) => {
+      const err = error instanceof Error ? error : new Error(String(error));
+      const detail = err.stack ?? err.message;
+      return `  - while resolving ${context}:\n${indent(detail, "      ")}`;
+    })
+    .join("\n");
+
+  return (
+    `${base}\n\n` +
+    `${errors.length} error(s) were caught during host-router discovery and ` +
+    `likely explain why no routers were registered:\n${formatted}`
+  );
+}
+
+/**
+ * Reduce the caught errors to an `ErrorOptions.cause`: a single failure becomes
+ * the direct cause; multiple failures are wrapped in an `AggregateError` so
+ * each underlying error remains reachable. No errors -> no cause.
+ */
+function toCause(errors: CaughtDiscoveryError[]): unknown {
+  if (errors.length === 0) return undefined;
+  if (errors.length === 1) return errors[0].error;
+  return new AggregateError(
+    errors.map((e) => e.error),
+    "Multiple host-router handlers failed during discovery",
+  );
+}
+
+/**
+ * Thrown when router discovery completes without finding any routers.
+ *
+ * Carries the entry path and the individual failures caught while resolving
+ * host-router lazy handlers. The formatted detail is embedded in `message` (for
+ * callers that log `err.message`/`err.stack`) and the underlying error(s) are
+ * also attached via `cause` (a single failure directly, multiple wrapped in an
+ * `AggregateError`) for cause-aware tooling such as the Vite error overlay.
+ */
+export class DiscoveryError extends Error {
+  /** The entry file that was imported before discovery gave up. */
+  readonly entryPath: string | undefined;
+  /** Individual failures caught while resolving host-router handlers. */
+  readonly caught: CaughtDiscoveryError[];
+
+  constructor(entryPath: string | undefined, caught: CaughtDiscoveryError[]) {
+    super(formatNoRoutersError(entryPath, caught));
+    const cause = toCause(caught);
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+    this.name = "DiscoveryError";
+    this.entryPath = entryPath;
+    this.caught = caught;
+    Object.setPrototypeOf(this, DiscoveryError.prototype);
+  }
+}
+
+/** How the dev caller should surface a discovery failure. */
+export interface DiscoveryFailureReport {
+  level: "error" | "warn";
+  message: string;
+}
+
+/**
+ * Decide how to surface a dev-boot discovery failure in the terminal.
+ *
+ * The bare "no routers found" case (a DiscoveryError with no caught host-handler
+ * failures) is ambiguous. It is either:
+ *   - a genuine misconfiguration — the entry never calls createRouter(), or the
+ *     configured entry path is wrong; or
+ *   - a transient artifact of a Vite dependency re-optimization racing with boot
+ *     discovery (a module read before the entry import resolves to the
+ *     pre-optimize copy of the runner graph while createRouter() populated the
+ *     post-optimize copy — see router-discovery.ts).
+ *
+ * We can only tell them apart when the caller observed the dep optimizer's
+ * `browserHash` change across the discovery attempt (`reoptimizeObserved`): a
+ * reload-causing re-optimization landed mid-flight, so the empty read was
+ * transient and the app self-heals per-request (handler.ts builds the trie from
+ * the router's live urlpatterns) with discovery re-running on the next boot.
+ *
+ * A DiscoveryError that DOES carry caught host-handler failures already embeds
+ * the real cause in its message, and any non-DiscoveryError is a hard failure;
+ * both stay loud with full detail.
+ */
+export function describeDiscoveryFailure(
+  err: unknown,
+  opts: { reoptimizeObserved?: boolean } = {},
+): DiscoveryFailureReport {
+  if (err instanceof DiscoveryError && err.caught.length === 0) {
+    const entry = err.entryPath ?? "the router entry";
+    if (opts.reoptimizeObserved) {
+      return {
+        level: "warn",
+        message:
+          `[rango] No routers found while Vite was re-optimizing dependencies on ` +
+          `dev boot. This is transient: routes are served per-request and ` +
+          `discovery re-runs automatically, so it clears on the next boot. If ` +
+          `routes still 404, confirm ${entry} calls createRouter().`,
+      };
+    }
+    return {
+      level: "error",
+      message:
+        `${err.message}\n` +
+        `  Ensure ${entry} calls createRouter() at module top level and that the ` +
+        `configured router entry path is correct.`,
+    };
+  }
+
+  const e = err as { stack?: string; message?: string };
+  const detail = e?.stack ?? e?.message ?? String(err);
+  return {
+    level: "error",
+    message: `[rango] Router discovery failed: ${detail}`,
+  };
+}