@rangojs/router 0.30.1 → 0.31.0

package/src/build/route-types/router-processing.ts

@@ -26,6 +26,8 @@ import {
 } from "./include-resolution.js";
 import { findUrlsVariableNames } from "./per-module-writer.js";
 import { isAutoGeneratedRouteName } from "../../route-name.js";
+import { normalizeBasename } from "../../router/basename.js";
+import { getStringValue } from "./ast-helpers.js";
 
 function countPublicRouteEntries(source: string): number {
   const matches =
@@ -232,15 +234,16 @@ function collectCreateRouterCallChain(
   }
 }
 
-function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
-  const sourceFile = ts.createSourceFile(
-    "router.tsx",
-    code,
-    ts.ScriptTarget.Latest,
-    true,
-    ts.ScriptKind.TSX,
-  );
-  let result: UrlsExtractionResult[] | null = null;
+// The first createRouter chain (in source order) that mounts urls, with its
+// extractions in runtime order. Route types and basename both come from it.
+function findRouterUrls(sourceFile: ts.SourceFile): {
+  createRouterCall: ts.CallExpression;
+  extractions: UrlsExtractionResult[];
+} | null {
+  let result: {
+    createRouterCall: ts.CallExpression;
+    extractions: UrlsExtractionResult[];
+  } | null = null;
 
   function visit(node: ts.Node) {
     if (result) return;
@@ -279,7 +282,7 @@ function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
         }
 
         if (extracted.length > 0) {
-          result = extracted;
+          result = { createRouterCall, extractions: extracted };
           return;
         }
       }
@@ -288,7 +291,18 @@ function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
   }
 
   visit(sourceFile);
-  return result ?? [];
+  return result;
+}
+
+function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
+  const sourceFile = ts.createSourceFile(
+    "router.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  return findRouterUrls(sourceFile)?.extractions ?? [];
 }
 
 /**
@@ -307,48 +321,189 @@ export function extractUrlsFromRouter(
   return extractions[extractions.length - 1] ?? null;
 }
 
+function unwrapTypeOperators(expr: ts.Expression): ts.Expression {
+  while (ts.isAsExpression(expr) || ts.isSatisfiesExpression(expr)) {
+    expr = expr.expression;
+  }
+  return expr;
+}
+
+function hasModifier(statement: ts.Statement, kind: ts.SyntaxKind): boolean {
+  return (
+    ts.canHaveModifiers(statement) &&
+    (ts.getModifiers(statement)?.some((m) => m.kind === kind) ?? false)
+  );
+}
+
+// `exported` limits the lookup to `export const name = ...`; an export list or
+// re-export is not followed.
+function findTopLevelConst(
+  sourceFile: ts.SourceFile,
+  name: string,
+  exported: boolean,
+): ts.Expression | undefined {
+  for (const statement of sourceFile.statements) {
+    if (
+      ts.isVariableStatement(statement) &&
+      statement.declarationList.flags & ts.NodeFlags.Const &&
+      !hasModifier(statement, ts.SyntaxKind.DeclareKeyword) &&
+      (!exported || hasModifier(statement, ts.SyntaxKind.ExportKeyword))
+    ) {
+      for (const decl of statement.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && decl.name.text === name) {
+          return decl.initializer && unwrapTypeOperators(decl.initializer);
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+// The value import binding `name` in the router file: a named import
+// (`import { X }` / `import { Y as X }`). Read from the AST, so a commented-out
+// or quoted import never matches. Default and namespace imports are not read.
+function findNamedImport(
+  sourceFile: ts.SourceFile,
+  name: string,
+): { specifier: string; exportedName: string } | undefined {
+  for (const statement of sourceFile.statements) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      statement.importClause?.isTypeOnly
+    ) {
+      continue;
+    }
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const el of bindings.elements) {
+      if (!el.isTypeOnly && el.name.text === name) {
+        return {
+          specifier: statement.moduleSpecifier.text,
+          exportedName: el.propertyName?.text ?? name,
+        };
+      }
+    }
+  }
+  return undefined;
+}
+
+// The top-level const `name` refers to: declared in the router file or
+// exported as a const by a relative module it is imported from by name.
+function resolveTopLevelConst(
+  name: string,
+  sourceFile: ts.SourceFile,
+  routerFilePath: string,
+): ts.Expression | undefined {
+  const local = findTopLevelConst(sourceFile, name, false);
+  if (local) return local;
+  const imported = findNamedImport(sourceFile, name);
+  if (!imported) return undefined;
+  const target = resolveImportPath(imported.specifier, routerFilePath);
+  if (!target) return undefined;
+  const targetSource = readFileSync(target, "utf-8");
+  return findTopLevelConst(
+    ts.createSourceFile(target, targetSource, ts.ScriptTarget.Latest, true),
+    imported.exportedName,
+    true,
+  );
+}
+
+// Inside any nested scope a local declaration can shadow the top-level
+// binding, and resolving it anyway would emit a wrong prefix.
+function isTopLevelScope(node: ts.Node): boolean {
+  for (let p = node.parent; !ts.isSourceFile(p); p = p.parent) {
+    if (
+      ts.isFunctionLike(p) ||
+      ts.isClassLike(p) ||
+      ts.isBlock(p) ||
+      ts.isCaseBlock(p) ||
+      ts.isModuleBlock(p) ||
+      ts.isIterationStatement(p, false)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
- * Extract the `basename` string literal from createRouter({ basename: "..." }).
- * Returns the basename value or undefined if not present.
+ * Read inline createRouter({ basename: X }) where X is a string literal, a
+ * top-level const, or `Const.prop` on a top-level const object literal.
+ * `unresolved` is the source of any other X.
  */
-export function extractBasenameFromRouter(code: string): string | undefined {
+function resolveRouterBasename(
+  routerSource: string,
+  routerFilePath: string,
+): { value?: string; unresolved?: string } {
   const sourceFile = ts.createSourceFile(
-    "router.tsx",
-    code,
+    routerFilePath,
+    routerSource,
     ts.ScriptTarget.Latest,
     true,
     ts.ScriptKind.TSX,
   );
-  let result: string | undefined;
-
-  function visit(node: ts.Node) {
-    if (result !== undefined) return;
-    if (
-      ts.isCallExpression(node) &&
-      ts.isIdentifier(node.expression) &&
-      node.expression.text === "createRouter"
+  // Read from the createRouter call whose urls the route types use. Only an
+  // explicit `basename` key counts: one inside a spread
+  // (`createRouter({ ...shared })`) or a non-literal options argument stays
+  // unread and unreported.
+  const options = findRouterUrls(sourceFile)?.createRouterCall.arguments[0];
+  const prop =
+    options && ts.isObjectLiteralExpression(options)
+      ? options.properties.find(
+          (p): p is ts.PropertyAssignment | ts.ShorthandPropertyAssignment =>
+            (ts.isPropertyAssignment(p) ||
+              ts.isShorthandPropertyAssignment(p)) &&
+            ts.isIdentifier(p.name) &&
+            p.name.text === "basename",
+        )
+      : undefined;
+  if (!prop) return {};
+
+  const valueExpr = ts.isPropertyAssignment(prop)
+    ? prop.initializer
+    : prop.name;
+  const expr = unwrapTypeOperators(valueExpr);
+  let value = getStringValue(expr);
+  if (value === null && isTopLevelScope(prop)) {
+    if (ts.isIdentifier(expr)) {
+      const init = resolveTopLevelConst(expr.text, sourceFile, routerFilePath);
+      value = init ? getStringValue(init) : null;
+    } else if (
+      ts.isPropertyAccessExpression(expr) &&
+      ts.isIdentifier(expr.expression)
     ) {
-      for (const arg of node.arguments) {
-        if (ts.isObjectLiteralExpression(arg)) {
-          for (const prop of arg.properties) {
-            if (
-              ts.isPropertyAssignment(prop) &&
-              ts.isIdentifier(prop.name) &&
-              prop.name.text === "basename" &&
-              ts.isStringLiteral(prop.initializer)
-            ) {
-              result = prop.initializer.text;
-              return;
-            }
-          }
-        }
-      }
+      const owner = resolveTopLevelConst(
+        expr.expression.text,
+        sourceFile,
+        routerFilePath,
+      );
+      value = owner ? resolveConstMember(owner, expr.name.text) : null;
     }
-    ts.forEachChild(node, visit);
   }
+  return value === null
+    ? { unresolved: valueExpr.getText(sourceFile).replace(/\s+/g, " ") }
+    : { value };
+}
 
-  visit(sourceFile);
-  return result;
+// String value of `owner.name` when owner is an object literal. A spread may
+// override the property, so an owner containing one is not resolved.
+function resolveConstMember(owner: ts.Expression, name: string): string | null {
+  if (
+    !ts.isObjectLiteralExpression(owner) ||
+    owner.properties.some(ts.isSpreadAssignment)
+  ) {
+    return null;
+  }
+  const member = owner.properties.find(
+    (p): p is ts.PropertyAssignment =>
+      ts.isPropertyAssignment(p) &&
+      ts.isIdentifier(p.name) &&
+      p.name.text === name,
+  );
+  return member
+    ? getStringValue(unwrapTypeOperators(member.initializer))
+    : null;
 }
 
 /** Apply a basename prefix to all route patterns in a result set. */
@@ -496,11 +651,9 @@ export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
     return { routes: {}, searchSchemas: {} };
   }
 
-  // Detect basename from createRouter({ basename: "..." })
-  const rawBasename = extractBasenameFromRouter(routerSource);
-  const basename = rawBasename
-    ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "")
-    : undefined;
+  const basename = normalizeBasename(
+    resolveRouterBasename(routerSource, routerFilePath).value,
+  );
 
   const result: RouteMapWithSearch = { routes: {}, searchSchemas: {} };
   const memo = createScanMemo();
@@ -531,8 +684,9 @@ export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
 
 /**
  * Walk the full include tree starting from a router file and detect
- * all includes that the static parser cannot resolve.
- * Returns an array of diagnostics; empty means fully resolvable.
+ * all includes that the static parser cannot resolve, plus an explicit
+ * createRouter `basename` it cannot read (every pattern would lack the
+ * prefix). Returns an array of diagnostics; empty means fully resolvable.
  */
 export function detectUnresolvableIncludes(
   routerFilePath: string,
@@ -559,6 +713,16 @@ export function detectUnresolvableIncludes(
       memo,
     );
   }
+  const { unresolved } = resolveRouterBasename(source, realPath);
+  if (unresolved !== undefined) {
+    diagnostics.push({
+      pathPrefix: "/",
+      namePrefix: null,
+      reason: "unresolvable-basename",
+      sourceFile: realPath,
+      detail: `basename \`${unresolved}\` is not a string literal or top-level const; every pattern would lack the prefix`,
+    });
+  }
   return diagnostics;
 }
 

package/src/build/runtime-discovery.ts

@@ -1,5 +1,6 @@
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type { Plugin, PluginOption, ViteDevServer } from "vite";
 import {
   generateRouteTypesSource,
   genFileTsPath,
@@ -35,13 +36,10 @@ export async function discoverAndWriteRouteTypes(
   routeCount: number;
   outputFiles: string[];
 }> {
-  let createViteServer: typeof import("vite").createServer;
   let loadConfigFromFile: typeof import("vite").loadConfigFromFile;
-  let rsc: any;
 
   try {
     const vite = await import("vite");
-    createViteServer = vite.createServer;
     loadConfigFromFile = vite.loadConfigFromFile;
   } catch {
     throw new Error(
@@ -50,61 +48,57 @@ export async function discoverAndWriteRouteTypes(
   }
 
   try {
-    const rscMod = await import("@vitejs/plugin-rsc");
-    rsc = rscMod.default;
+    await import("@vitejs/plugin-rsc");
   } catch {
     throw new Error(
       "Runtime discovery requires '@vitejs/plugin-rsc'. Install it with: pnpm add -D @vitejs/plugin-rsc",
     );
   }
 
-  const { createVersionPlugin } =
-    await import("../vite/plugins/version-plugin.ts");
-  const { createVirtualStubPlugin } =
-    await import("../vite/plugins/virtual-stub-plugin.ts");
+  const { createTempRscServer } = await import("../vite/temp-rsc-server.js");
+  const { createDiscoveryState } = await import("../vite/discovery/state.js");
+  const { discoverClientUrlProjections } =
+    await import("../vite/discovery/client-urls-projection.js");
+  const { pickForwardedRunnerConfig, selectForwardableResolvePlugins } =
+    await import("../vite/utils/forward-user-plugins.js");
 
-  // Load user's vite config to get resolve.alias (unless provided directly)
-  let userResolveAlias: any = opts.resolveAlias;
-  if (!userResolveAlias) {
-    const configPath = opts.configFile;
+  // The discovery temp server of `vite dev/build` (expose-internal-ids, the
+  // cloudflare:* stubs, the user's resolver plugins and resolve/define/oxc).
+  // The config stays unresolved: resolving it would run rango()'s
+  // configResolved, which writes the static gen files. Forwarded resolvers
+  // therefore run without their own config/configResolved hooks.
+  const entryPath = resolve(opts.entry);
+  const state = createDiscoveryState(entryPath, undefined);
+  state.projectRoot = opts.root;
+  state.userResolveAlias = opts.resolveAlias;
+  if (!opts.resolveAlias) {
     try {
       const loaded = await loadConfigFromFile(
         { command: "serve", mode: "development" },
-        configPath,
+        opts.configFile,
         opts.root,
       );
-      if (loaded?.config?.resolve?.alias) {
-        userResolveAlias = loaded.config.resolve.alias;
+      if (loaded) {
+        state.userRunnerConfig = pickForwardedRunnerConfig(loaded.config);
+        state.userResolvePlugins = selectForwardableResolvePlugins(
+          await flattenPluginOptions(loaded.config.plugins),
+        );
       }
-    } catch {
-      // Config loading failed; proceed without aliases
+    } catch (err: any) {
+      // Discovery without the app's resolvers fails later on an unrelated
+      // import; name the cause here.
+      console.warn(
+        `[rango] Could not load the Vite config (${err?.message ?? err}); discovering without its resolve config and plugins`,
+      );
     }
   }
 
-  const entryPath = resolve(opts.entry);
-  let tempServer: any = null;
+  let tempServer: ViteDevServer | null = null;
 
   try {
-    tempServer = await createViteServer({
-      root: opts.root,
-      configFile: false,
-      server: { middlewareMode: true },
-      appType: "custom",
-      logLevel: "silent",
+    tempServer = await createTempRscServer(state, {
       cacheDir: "node_modules/.vite_rango_generate",
-      resolve: userResolveAlias ? { alias: userResolveAlias } : undefined,
-      esbuild: { jsx: "automatic", jsxImportSource: "react" },
-      plugins: [
-        rsc({
-          entries: {
-            client: "virtual:entry-client",
-            ssr: "virtual:entry-ssr",
-            rsc: entryPath,
-          },
-        }),
-        createVersionPlugin(),
-        createVirtualStubPlugin(),
-      ],
+      plugins: [missingGenFileStubPlugin()],
     });
 
     const rscEnv = (tempServer.environments as any)?.rsc;
@@ -125,6 +119,14 @@ export async function discoverAndWriteRouteTypes(
       );
     }
 
+    // include() of a clientUrls() module resolves from these projections.
+    await discoverClientUrlProjections(
+      state,
+      (tempServer.environments as any)?.ssr,
+      serverMod,
+      rscEnv,
+    );
+
     // Import build utilities for manifest generation
     const buildMod = await rscEnv.runner.import("@rangojs/router/build");
     const generateManifestFull = buildMod.generateManifestFull;
@@ -149,7 +151,11 @@ export async function discoverAndWriteRouteTypes(
       const mountManifests = [];
       for (const mount of mounts) {
         mountManifests.push(
-          await generateManifestFull(mount.patterns, globalMountIndex),
+          await generateManifestFull(
+            mount.patterns,
+            globalMountIndex,
+            router.__basename ? { urlPrefix: router.__basename } : undefined,
+          ),
         );
         globalMountIndex++;
       }
@@ -232,3 +238,46 @@ export async function discoverAndWriteRouteTypes(
     }
   }
 }
+
+const MISSING_GEN_PREFIX = "\0rango-missing-named-routes-gen:";
+
+/**
+ * expose-router-id makes every createRouter() file import its sibling
+ * `./<name>.named-routes.gen.js`. `vite dev/build` write those from static
+ * parsing before discovery; the CLI does not, so a missing one resolves to an
+ * empty NamedRoutes here and discovery writes the real file. An existing gen
+ * file loads from disk as usual.
+ */
+function missingGenFileStubPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:missing-gen-file-stub",
+    enforce: "pre",
+    resolveId(id, importer) {
+      if (!importer || !id.endsWith(".named-routes.gen.js")) return null;
+      const genPath = genFileTsPath(importer.split("?", 1)[0]);
+      if (id !== `./${basename(genPath, ".ts")}.js` || existsSync(genPath)) {
+        return null;
+      }
+      return MISSING_GEN_PREFIX + genPath;
+    },
+    load(id) {
+      return id.startsWith(MISSING_GEN_PREFIX)
+        ? "export const NamedRoutes = {};\n"
+        : null;
+    },
+  };
+}
+
+/**
+ * Flatten an unresolved `plugins` option (nested arrays, promises, falsy
+ * entries) the way Vite's config resolution does, without running any hook.
+ */
+async function flattenPluginOptions(
+  option: PluginOption | undefined,
+): Promise<Plugin[]> {
+  const value = await option;
+  if (Array.isArray(value)) {
+    return (await Promise.all(value.map(flattenPluginOptions))).flat();
+  }
+  return value ? [value as Plugin] : [];
+}

package/src/client-urls/server-projection.ts

@@ -170,8 +170,10 @@ function serializeSearchSchema(
     throw projectionError(route, 'path option "search" must be an object');
   }
 
+  // Source order, not sorted: the build writes the gen file's search keys from
+  // this projection and must match `rango generate`'s static parse (#1322).
   const entries: Array<[string, SearchSchemaValue]> = [];
-  for (const key of Object.keys(value).sort()) {
+  for (const key of Object.keys(value)) {
     const schemaValue = (value as Record<string, unknown>)[key];
     if (
       typeof schemaValue !== "string" ||

package/src/vite/temp-rsc-server.ts

@@ -1,12 +1,14 @@
 /**
  * The discovery temp RSC server: a minimal Vite server whose module runner
  * imports the user's router files. Shared by dev discovery
- * (discovery/dev-server-phase.ts) and build discovery
- * (discovery/build-discovery-phase.ts).
+ * (discovery/dev-server-phase.ts), build discovery
+ * (discovery/build-discovery-phase.ts) and `rango generate --runtime`
+ * (build/runtime-discovery.ts).
  *
  * Sits in src/vite/, not src/vite/discovery/: the loader hook URL below
- * resolves against this module's import.meta.url, and the published bundle
- * (dist/vite/index.js) ships the hook at the same relative path.
+ * resolves against this module's import.meta.url, and the published bundles
+ * (dist/vite/index.js, dist/bin/rango.js) ship the hook at the same relative
+ * path.
  */
 
 import type { ViteDevServer } from "vite";
@@ -103,6 +105,8 @@ export async function createTempRscServer(
      * shell capture actually runs.
      */
     realSsrEntry?: boolean;
+    /** Caller-specific plugins, appended after the forwarded user plugins. */
+    plugins?: import("vite").Plugin[];
   } = {},
 ): Promise<ViteDevServer> {
   // Install the Node ESM loader hook before any module evaluation so
@@ -218,6 +222,7 @@ export async function createTempRscServer(
       // IMPORT_REWRITE_PLUGINS) and placed last so framework resolution runs first;
       // Vite re-sorts by `enforce`, so `enforce: "pre"` resolvers still lead.
       ...state.userResolvePlugins,
+      ...(options.plugins ?? []),
     ],
   });
 }

package/src/vite/utils/forward-user-plugins.ts

@@ -139,6 +139,8 @@ export interface ForwardedRunnerConfig {
 /**
  * Extract the data-only config slice to mirror into the discovery temp server.
  * `alias` is included here so callers no longer need to thread it separately.
+ * Accepts the unresolved config too: `rango generate --runtime` must not
+ * resolve it (that runs rango()'s configResolved, which writes gen files).
  *
  * `tsconfigPaths` is forwarded so Vite 8's native tsconfig `paths` resolution
  * (a top-level `resolve` flag, off by default) reaches the temp server. The
@@ -154,9 +156,9 @@ export interface ForwardedRunnerConfig {
  * forward `oxc` exclusively — no `esbuild` field is touched.
  */
 export function pickForwardedRunnerConfig(
-  config: ResolvedConfig,
+  config: Pick<ResolvedConfig | UserConfig, "resolve" | "define" | "oxc">,
 ): ForwardedRunnerConfig {
-  const r = config.resolve ?? ({} as ResolvedConfig["resolve"]);
+  const r = config.resolve ?? {};
   const resolve: NonNullable<UserConfig["resolve"]> = {};
   if (r.alias !== undefined) resolve.alias = r.alias as any;
   if (r.dedupe !== undefined) resolve.dedupe = r.dedupe;