@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/src/build/route-types/codegen.ts

@@ -23,7 +23,7 @@ export function generatePerModuleTypesSource(
   const valid = routes.filter(({ name }) => {
     if (!name || /["'\\`\n\r]/.test(name)) {
       console.warn(
-        `[rsc-router] Skipping route with invalid name: ${JSON.stringify(name)}`,
+        `[rango] Skipping route with invalid name: ${JSON.stringify(name)}`,
       );
       return false;
     }
@@ -42,7 +42,7 @@ export function generatePerModuleTypesSource(
   for (const { name, pattern, params, search } of valid) {
     if (deduped.has(name)) {
       console.warn(
-        `[rsc-router] Duplicate route name "${name}" — keeping first definition`,
+        `[rango] Duplicate route name "${name}" — keeping first definition`,
       );
       continue;
     }
@@ -59,7 +59,7 @@ export function generatePerModuleTypesSource(
 }
 
 /**
- * Generates a .ts file that augments RSCRouter.GeneratedRouteMap
+ * Generates a .ts file that augments Rango.GeneratedRouteMap
  * with route name -> pattern mappings. This enables Handler<"routeName">
  * without circular references since the file has no imports from the app.
  */
@@ -88,14 +88,25 @@ export function generateRouteTypesSource(
     })
     .join("\n");
 
+  // The global augmentation extends an alias of `typeof NamedRoutes` rather than
+  // `Readonly<typeof NamedRoutes>`. `as const` already makes the members readonly,
+  // so the two are behaviour-identical, but `Readonly<>` is a homomorphic mapped
+  // type the compiler instantiates once per route at the augmentation site
+  // (~4 instantiations/route). An interface `extends` clause cannot name a bare
+  // `typeof` query, so the alias is what lets us drop the wrapper. Measured: ~35%
+  // fewer type instantiations on a 14k-route app; negligible (but free) on small.
   return `// Auto-generated by @rangojs/router - do not edit
 export const NamedRoutes = {
 ${objectBody}
 } as const;
 
+// Aliased so the augmentation below does not pay a homomorphic mapped-type
+// instantiation per route; \`as const\` already makes the members readonly.
+type NamedRoutesShape = typeof NamedRoutes;
+
 declare global {
-  namespace RSCRouter {
-    interface GeneratedRouteMap extends Readonly<typeof NamedRoutes> {}
+  namespace Rango {
+    interface GeneratedRouteMap extends NamedRoutesShape {}
   }
 }
 `;

package/src/build/route-types/include-resolution.ts

@@ -22,6 +22,61 @@ export interface UnresolvableInclude {
   detail: string;
 }
 
+// ---------------------------------------------------------------------------
+// Per-scan memo
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-scan memo shared across the include-resolution recursion. Keys are
+ * absolute file paths; values cache the readFileSync result and the
+ * ts.SourceFile parsed from the FULL file source. A separate blockSources map
+ * caches parses of extracted sub-blocks (urls() call text), keyed by the exact
+ * block string, so the two extractors (routes + includes) for the same block
+ * share a single parse.
+ *
+ * The memo is purely a performance accelerator: same input -> same parse, so
+ * generated output is identical to the un-memoized path. A fresh memo is
+ * created per top-level scan entry, so stale file edits between scans are never
+ * served.
+ */
+export interface ScanMemo {
+  files: Map<string, string>;
+  blockSourceFiles: Map<string, ts.SourceFile>;
+}
+
+export function createScanMemo(): ScanMemo {
+  return { files: new Map(), blockSourceFiles: new Map() };
+}
+
+function parseBlock(memo: ScanMemo | undefined, block: string): ts.SourceFile {
+  if (memo) {
+    const cached = memo.blockSourceFiles.get(block);
+    if (cached) return cached;
+  }
+  const sf = ts.createSourceFile(
+    "input.tsx",
+    block,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  if (memo) memo.blockSourceFiles.set(block, sf);
+  return sf;
+}
+
+function readSourceMemoized(
+  memo: ScanMemo | undefined,
+  realPath: string,
+): string {
+  if (memo) {
+    const cached = memo.files.get(realPath);
+    if (cached !== undefined) return cached;
+  }
+  const source = readFileSync(realPath, "utf-8");
+  if (memo) memo.files.set(realPath, source);
+  return source;
+}
+
 // ---------------------------------------------------------------------------
 // AST-based include() parsing
 // ---------------------------------------------------------------------------
@@ -47,7 +102,10 @@ function extractNamePrefixFromInclude(node: ts.CallExpression): string | null {
  * Returns both resolved includes (identifier second args) and unresolvable
  * includes (factory calls, etc.) with reasons.
  */
-export function extractIncludesWithDiagnostics(code: string): {
+export function extractIncludesWithDiagnostics(
+  code: string,
+  sourceFileArg?: ts.SourceFile,
+): {
   resolved: Array<{
     pathPrefix: string;
     variableName: string;
@@ -60,13 +118,16 @@ export function extractIncludesWithDiagnostics(code: string): {
     detail: string;
   }>;
 } {
-  const sourceFile = ts.createSourceFile(
-    "input.tsx",
-    code,
-    ts.ScriptTarget.Latest,
-    true,
-    ts.ScriptKind.TSX,
-  );
+  // Reuse a caller-provided SourceFile (parsed once per scan) when given.
+  const sourceFile =
+    sourceFileArg ??
+    ts.createSourceFile(
+      "input.tsx",
+      code,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
   const resolved: Array<{
     pathPrefix: string;
     variableName: string;
@@ -140,7 +201,13 @@ export function resolveImportedVariable(
   code: string,
   localName: string,
 ): { specifier: string; exportedName: string } | null {
-  const importRegex = /import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+  // Allow an optional leading default binding before the named-import brace so
+  // a combined `import Foo, { bar } from "..."` is matched (the named members
+  // are the only part we resolve; the default binding is skipped). Without the
+  // optional `(?:[\w$]+\s*,\s*)?` segment, the `Foo, ` prefix breaks the match
+  // and a legitimate static named import surfaces as `unresolvable-import`.
+  const importRegex =
+    /import\s*(?:[\w$]+\s*,\s*)?\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
   let match;
 
   while ((match = importRegex.exec(code)) !== null) {
@@ -206,14 +273,18 @@ export function resolveImportPath(
 function extractUrlsBlockForVariable(
   code: string,
   varName: string,
+  sourceFileArg?: ts.SourceFile,
 ): string | null {
-  const sourceFile = ts.createSourceFile(
-    "input.tsx",
-    code,
-    ts.ScriptTarget.Latest,
-    true,
-    ts.ScriptKind.TSX,
-  );
+  // Reuse a caller-provided full-source SourceFile (parsed once per scan).
+  const sourceFile =
+    sourceFileArg ??
+    ts.createSourceFile(
+      "input.tsx",
+      code,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
   let result: string | null = null;
 
   function visit(node: ts.Node) {
@@ -249,11 +320,15 @@ function buildRouteMapFromBlock(
   visited: Set<string>,
   searchSchemasOut?: Record<string, Record<string, string>>,
   diagnosticsOut?: UnresolvableInclude[],
+  memo?: ScanMemo,
 ): Record<string, string> {
   const routeMap: Record<string, string> = {};
 
+  // Parse the block once and share the SourceFile between both extractors.
+  const blockSourceFile = parseBlock(memo, block);
+
   // Extract local path() routes
-  const localRoutes = extractRoutesFromSource(block);
+  const localRoutes = extractRoutesFromSource(block, blockSourceFile);
   for (const { name, pattern, search } of localRoutes) {
     routeMap[name] = pattern;
     if (search && searchSchemasOut) {
@@ -262,8 +337,10 @@ function buildRouteMapFromBlock(
   }
 
   // Extract include() calls with diagnostics for unresolvable ones
-  const { resolved: includes, unresolvable } =
-    extractIncludesWithDiagnostics(block);
+  const { resolved: includes, unresolvable } = extractIncludesWithDiagnostics(
+    block,
+    blockSourceFile,
+  );
 
   if (diagnosticsOut) {
     for (const entry of unresolvable) {
@@ -298,12 +375,17 @@ function buildRouteMapFromBlock(
         imported.exportedName,
         visited,
         diagnosticsOut,
+        undefined,
+        memo,
       );
     } else {
-      // Check if variable exists as a same-file urls() definition
+      // Check if variable exists as a same-file urls() definition. Share the
+      // full-source SourceFile parse via the memo (block === fullSource hits the
+      // same cache entry already used above).
       const sameFileBlock = extractUrlsBlockForVariable(
         fullSource,
         variableName,
+        parseBlock(memo, fullSource),
       );
       if (!sameFileBlock) {
         if (diagnosticsOut) {
@@ -322,6 +404,8 @@ function buildRouteMapFromBlock(
         variableName,
         visited,
         diagnosticsOut,
+        undefined,
+        memo,
       );
     }
 
@@ -361,6 +445,9 @@ function buildRouteMapFromBlock(
  * @param inlineBlock - Optional pre-extracted code block (e.g. from an inline
  *   builder function). When provided, variableName is ignored and the block
  *   is parsed directly for path()/include() calls.
+ * @param memo - Per-scan readFileSync/parse memo. A fresh one is created at the
+ *   top-level entry and threaded through the recursion so each file is read and
+ *   parsed once per scan. Behavior-preserving (same input -> same output).
  */
 export function buildCombinedRouteMapWithSearch(
   filePath: string,
@@ -368,22 +455,24 @@ export function buildCombinedRouteMapWithSearch(
   visited?: Set<string>,
   diagnosticsOut?: UnresolvableInclude[],
   inlineBlock?: string,
+  memo?: ScanMemo,
 ): {
   routes: Record<string, string>;
   searchSchemas: Record<string, Record<string, string>>;
 } {
   visited = visited ?? new Set();
+  memo = memo ?? createScanMemo();
   const realPath = resolve(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
   if (visited.has(key)) {
-    console.warn(`[rsc-router] Circular include detected, skipping: ${key}`);
+    console.warn(`[rango] Circular include detected, skipping: ${key}`);
     return { routes: {}, searchSchemas: {} };
   }
   visited.add(key);
 
   let source: string;
   try {
-    source = readFileSync(realPath, "utf-8");
+    source = readSourceMemoized(memo, realPath);
   } catch {
     return { routes: {}, searchSchemas: {} };
   }
@@ -392,7 +481,11 @@ export function buildCombinedRouteMapWithSearch(
   if (inlineBlock) {
     block = inlineBlock;
   } else if (variableName) {
-    const extracted = extractUrlsBlockForVariable(source, variableName);
+    const extracted = extractUrlsBlockForVariable(
+      source,
+      variableName,
+      parseBlock(memo, source),
+    );
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;
   } else {
@@ -407,6 +500,7 @@ export function buildCombinedRouteMapWithSearch(
     visited,
     searchSchemas,
     diagnosticsOut,
+    memo,
   );
 
   // Remove from visited so sibling branches can include the same variable

package/src/build/route-types/param-extraction.ts

@@ -37,12 +37,15 @@ export function formatRouteEntry(
 ): string {
   const hasSearch = search && Object.keys(search).length > 0;
 
+  // JSON.stringify the pattern and search values so backslashes and quotes in a
+  // route pattern (e.g. a custom regex constraint) survive interpolation into
+  // both the type-level string and the runtime NamedRoutes value.
   if (!hasSearch) {
-    return `  ${key}: "${pattern}",`;
+    return `  ${key}: ${JSON.stringify(pattern)},`;
   }
 
   const searchBody = Object.entries(search!)
-    .map(([k, v]) => `${k}: "${v}"`)
+    .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
     .join(", ");
-  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
+  return `  ${key}: { path: ${JSON.stringify(pattern)}, search: { ${searchBody} } },`;
 }

package/src/build/route-types/per-module-writer.ts

@@ -3,7 +3,10 @@ import ts from "typescript";
 import { extractParamsFromPattern } from "./param-extraction.js";
 import { extractRoutesFromSource } from "./ast-route-extraction.js";
 import { generatePerModuleTypesSource } from "./codegen.js";
-import { buildCombinedRouteMapWithSearch } from "./include-resolution.js";
+import {
+  buildCombinedRouteMapWithSearch,
+  createScanMemo,
+} from "./include-resolution.js";
 import type { ScanFilter } from "./scan-filter.js";
 import { findTsFiles } from "./scan-filter.js";
 
@@ -78,10 +81,20 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
     if (varNames.length > 0) {
       // Follow includes recursively via the combined route map builder.
       // The visited set in buildCombinedRouteMapWithSearch prevents infinite loops.
+      // Share one per-file scan memo across all urls() variables so a shared
+      // include target is read+parsed once for this file, not once per variable.
       routes = [];
+      const memo = createScanMemo();
       for (const varName of varNames) {
         const { routes: routeMap, searchSchemas } =
-          buildCombinedRouteMapWithSearch(filePath, varName);
+          buildCombinedRouteMapWithSearch(
+            filePath,
+            varName,
+            undefined,
+            undefined,
+            undefined,
+            memo,
+          );
         for (const [name, pattern] of Object.entries(routeMap)) {
           const params = extractParamsFromPattern(pattern);
           routes.push({
@@ -97,7 +110,10 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       routes = extractRoutesFromSource(source);
     }
 
-    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    // Match .ts/.tsx/.js/.jsx (same as router-processing.ts / router-transform.ts).
+    // Without the jsx? branch a .jsx/.js source produced genPath === filePath,
+    // overwriting the source file instead of writing a sibling .gen.ts.
+    const genPath = filePath.replace(/\.(tsx?|jsx?)$/, ".gen.ts");
 
     // When a urls() variable was found but static resolution yields zero
     // routes, write an empty placeholder so generated imports stay
@@ -106,7 +122,7 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       if (varNames.length > 0 && !existsSync(genPath)) {
         writeFileSync(genPath, generatePerModuleTypesSource([]));
         console.log(
-          `[rsc-router] Generated route types (placeholder) -> ${genPath}`,
+          `[rango] Generated route types (placeholder) -> ${genPath}`,
         );
       }
       return;
@@ -118,11 +134,11 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       : null;
     if (existing !== genSource) {
       writeFileSync(genPath, genSource);
-      console.log(`[rsc-router] Generated route types -> ${genPath}`);
+      console.log(`[rango] Generated route types -> ${genPath}`);
     }
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to generate route types for ${filePath}: ${(err as Error).message}`,
+      `[rango] Failed to generate route types for ${filePath}: ${(err as Error).message}`,
     );
   }
 }

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

@@ -15,6 +15,7 @@ import {
 import ts from "typescript";
 import { generateRouteTypesSource } from "./codegen.js";
 import type { ScanFilter } from "./scan-filter.js";
+import { firstCodeMatchIndex } from "./source-scan.js";
 import {
   resolveImportedVariable,
   resolveImportPath,
@@ -38,6 +39,8 @@ function countPublicRouteEntries(source: string): number {
 }
 
 const ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+// Global variant for the code-region scan (firstCodeMatchIndex sets lastIndex).
+const ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
 
 function isRoutableSourceFile(name: string): boolean {
   return (
@@ -61,7 +64,7 @@ function findRouterFilesRecursive(
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return;
   }
@@ -90,7 +93,17 @@ function findRouterFilesRecursive(
 
     try {
       const source = readFileSync(fullPath, "utf-8");
-      if (ROUTER_CALL_PATTERN.test(source)) {
+      // Fast path: most files contain no `createRouter(` at all, so the cheap
+      // raw regex short-circuits before the code-region scan. Only a file that
+      // mentions the token (real call OR a comment/string mention) is rescanned
+      // over code regions — allocation-free, never building a stripped copy —
+      // so a mention inside a comment or string is not mistaken for a real
+      // router file (which previously triggered a spurious "Multiple routers
+      // found" error).
+      if (
+        ROUTER_CALL_PATTERN.test(source) &&
+        firstCodeMatchIndex(source, ROUTER_CALL_PATTERN_G) >= 0
+      ) {
         routerFilesInDir.push(fullPath);
       }
     } catch {
@@ -142,7 +155,7 @@ export function findNestedRouterConflict(
 
 export function formatNestedRouterConflictError(
   conflict: { ancestor: string; nested: string },
-  prefix = "[rsc-router]",
+  prefix = "[rango]",
 ): string {
   return (
     `${prefix} Nested router roots are not supported.\n` +
@@ -309,12 +322,6 @@ export function extractBasenameFromRouter(code: string): string | undefined {
   return result;
 }
 
-/** @deprecated Use extractUrlsFromRouter instead */
-export function extractUrlsVariableFromRouter(code: string): string | null {
-  const result = extractUrlsFromRouter(code);
-  return result?.kind === "variable" ? result.name : null;
-}
-
 /** Apply a basename prefix to all route patterns in a result set. */
 function applyBasenameToRoutes(
   result: {
@@ -339,6 +346,36 @@ function applyBasenameToRoutes(
   return { routes: prefixed, searchSchemas: result.searchSchemas };
 }
 
+// Filesystem path of the generated route-types file for a router source file.
+// Native separators — matches the self-gen-tracking Map key the watcher compares.
+export function genFileTsPath(sourceFile: string): string {
+  const base = pathBasename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+  return join(dirname(sourceFile), `${base}.named-routes.gen.ts`);
+}
+
+// Search schemas for the gen file: prefer the runtime manifest's; when it omits
+// them (some module-runner flows) fall back to static parsing filtered to the
+// public route-name set. Returns the runtime value unchanged otherwise.
+export function resolveSearchSchemas(
+  publicRouteNames: string[],
+  runtimeSchemas: Record<string, Record<string, string>> | undefined,
+  sourceFile: string,
+): Record<string, Record<string, string>> | undefined {
+  if (runtimeSchemas && Object.keys(runtimeSchemas).length > 0) {
+    return runtimeSchemas;
+  }
+  const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
+  if (Object.keys(staticParsed.searchSchemas).length === 0) {
+    return runtimeSchemas;
+  }
+  const filtered: Record<string, Record<string, string>> = {};
+  for (const name of publicRouteNames) {
+    const schema = staticParsed.searchSchemas[name];
+    if (schema) filtered[name] = schema;
+  }
+  return Object.keys(filtered).length > 0 ? filtered : runtimeSchemas;
+}
+
 /**
  * Resolve routes and search schemas from a router source file by following the
  * variable passed to `.routes(...)` or `urls: ...` in createRouter options,
@@ -528,7 +565,10 @@ export function findRouterFiles(root: string, filter?: ScanFilter): string[] {
 export function writeCombinedRouteTypes(
   root: string,
   knownRouterFiles?: string[],
-  opts?: { preserveIfLarger?: boolean },
+  opts?: {
+    preserveIfLarger?: boolean;
+    onWrite?: (outPath: string, content: string) => void;
+  },
 ): void {
   // Delete old combined named-routes.gen.ts if it exists (stale from older versions)
   try {
@@ -536,7 +576,7 @@ export function writeCombinedRouteTypes(
     if (existsSync(oldCombinedPath)) {
       unlinkSync(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`,
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`,
       );
     }
   } catch {}
@@ -566,24 +606,15 @@ export function writeCombinedRouteTypes(
       if (!extractUrlsFromRouter(routerSource)) continue;
     }
 
-    const routerBasename = pathBasename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      "",
-    );
-    const outPath = join(
-      dirname(routerFilePath),
-      `${routerBasename}.named-routes.gen.ts`,
-    );
+    const outPath = genFileTsPath(routerFilePath);
     const existing = existsSync(outPath)
       ? readFileSync(outPath, "utf-8")
       : null;
 
-    // When the static parser can't extract routes (e.g. callback-style urls()),
-    // write an empty placeholder so the build-time transform's injected import
-    // resolves. Runtime discovery will overwrite this with the real routes.
     if (Object.keys(result.routes).length === 0) {
       if (!existing) {
         const emptySource = generateRouteTypesSource({});
+        opts?.onWrite?.(outPath, emptySource);
         writeFileSync(outPath, emptySource);
       }
       continue;
@@ -595,11 +626,6 @@ export function writeCombinedRouteTypes(
       hasSearchSchemas ? result.searchSchemas : undefined,
     );
     if (existing !== source) {
-      // On initial dev startup, don't overwrite a file from runtime discovery
-      // (which has all dynamic routes) with a smaller set from the static
-      // parser. The static parser can't see routes generated by Array.from()
-      // or other dynamic code. During HMR (file watcher), always write so
-      // newly added routes appear immediately.
       if (opts?.preserveIfLarger && existing) {
         const existingCount = countPublicRouteEntries(existing);
         const newCount = Object.keys(result.routes).filter(
@@ -609,9 +635,10 @@ export function writeCombinedRouteTypes(
           continue;
         }
       }
+      opts?.onWrite?.(outPath, source);
       writeFileSync(outPath, source);
       console.log(
-        `[rsc-router] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
+        `[rango] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
       );
     }
   }

package/src/build/route-types/scan-filter.ts

@@ -54,7 +54,7 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return results;
   }