@rangojs/router 0.0.0-experimental.10

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

@@ -0,0 +1,828 @@
+import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from "node:fs";
+import { join, dirname, resolve, relative, basename as pathBasename } from "node:path";
+// @ts-ignore -- picomatch ships no .d.ts; types are trivial
+import picomatch from "picomatch";
+
+/**
+ * Extract route definitions from source code by statically parsing path() calls.
+ * No code execution needed -- works on raw source text.
+ *
+ * Handles multi-line handlers with JSX, nested braces, string literals,
+ * and comments. Skips unnamed paths (no { name: "..." }).
+ */
+export function extractRoutesFromSource(
+  code: string
+): Array<{ name: string; pattern: string }> {
+  const routes: Array<{ name: string; pattern: string }> = [];
+  const regex = /\bpath(?:\.(?:json|text|html|xml|image|stream|any))?\s*\(/g;
+  let match;
+
+  while ((match = regex.exec(code)) !== null) {
+    const result = parsePathCall(code, match.index + match[0].length);
+    if (result) routes.push(result);
+  }
+
+  return routes;
+}
+
+/**
+ * Generate a per-module types file from extracted routes.
+ * Output has zero imports, preventing circular references.
+ */
+export function generatePerModuleTypesSource(
+  routes: Array<{ name: string; pattern: string }>
+): string {
+  const valid = routes.filter(({ name }) => {
+    if (!name || /["'\\`\n\r]/.test(name)) {
+      console.warn(`[rsc-router] Skipping route with invalid name: ${JSON.stringify(name)}`);
+      return false;
+    }
+    return true;
+  });
+
+  // Deduplicate by name (last definition wins for same name)
+  const deduped = new Map<string, string>();
+  for (const { name, pattern } of valid) {
+    deduped.set(name, pattern);
+  }
+  const sorted = [...deduped.entries()]
+    .sort(([a], [b]) => a.localeCompare(b));
+  const body = sorted
+    .map(([name, pattern]) => {
+      // Quote names that aren't valid bare identifiers (dots, dashes, etc.)
+      const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
+      return `  ${key}: "${pattern}",`;
+    })
+    .join("\n");
+  return `// Auto-generated by @rangojs/router - do not edit\nexport const routes = {\n${body}\n} as const;\nexport type routes = typeof routes;\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Mini-parser internals
+// ---------------------------------------------------------------------------
+
+function isWhitespace(ch: string): boolean {
+  return ch === " " || ch === "\t" || ch === "\n" || ch === "\r";
+}
+
+/** Read a single- or double-quoted string literal starting at pos. */
+function readString(
+  code: string,
+  pos: number
+): { value: string; end: number } | null {
+  const quote = code[pos];
+  if (quote !== '"' && quote !== "'") return null;
+
+  let value = "";
+  pos++;
+  while (pos < code.length) {
+    if (code[pos] === "\\") {
+      pos++;
+      if (pos < code.length) {
+        value += code[pos];
+        pos++;
+      }
+      continue;
+    }
+    if (code[pos] === quote) {
+      return { value, end: pos + 1 };
+    }
+    value += code[pos];
+    pos++;
+  }
+  return null;
+}
+
+/** Skip past any string literal (single, double, or template). */
+function skipStringLiteral(code: string, pos: number): number {
+  const quote = code[pos];
+
+  if (quote === "`") {
+    pos++;
+    while (pos < code.length) {
+      if (code[pos] === "\\") {
+        pos += 2;
+        continue;
+      }
+      if (code[pos] === "`") return pos + 1;
+      if (code[pos] === "$" && pos + 1 < code.length && code[pos + 1] === "{") {
+        pos += 2;
+        let braceDepth = 1;
+        while (pos < code.length && braceDepth > 0) {
+          if (code[pos] === "{") braceDepth++;
+          else if (code[pos] === "}") braceDepth--;
+          else if (code[pos] === "\\") pos++;
+          else if (
+            code[pos] === '"' ||
+            code[pos] === "'" ||
+            code[pos] === "`"
+          ) {
+            pos = skipStringLiteral(code, pos);
+            continue;
+          }
+          if (braceDepth > 0) pos++;
+        }
+        continue;
+      }
+      pos++;
+    }
+    return pos;
+  }
+
+  // Simple single/double quoted string
+  pos++;
+  while (pos < code.length) {
+    if (code[pos] === "\\") {
+      pos += 2;
+      continue;
+    }
+    if (code[pos] === quote) return pos + 1;
+    pos++;
+  }
+  return pos;
+}
+
+/**
+ * Check if code at pos starts with `name` as a standalone identifier
+ * followed by `:` (an object property).
+ */
+function matchesNameColon(code: string, pos: number): boolean {
+  if (code.slice(pos, pos + 4) !== "name") return false;
+  if (pos > 0 && /\w/.test(code[pos - 1])) return false;
+  const afterName = pos + 4;
+  if (afterName < code.length && /\w/.test(code[afterName])) return false;
+  let checkPos = afterName;
+  while (checkPos < code.length && isWhitespace(code[checkPos])) checkPos++;
+  return code[checkPos] === ":";
+}
+
+/** Extract the string value after `name:` starting at the `n` of `name`. */
+function extractNameValue(
+  code: string,
+  pos: number
+): { value: string; end: number } | null {
+  pos += 4; // skip 'name'
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  pos++; // skip ':'
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  return readString(code, pos);
+}
+
+/**
+ * Parse a single path() call starting right after the opening paren.
+ * Returns { name, pattern } or null if the call is unnamed.
+ */
+function parsePathCall(
+  code: string,
+  pos: number
+): { name: string; pattern: string } | null {
+  // Skip whitespace to first argument
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+
+  // First argument must be a string literal (the pattern)
+  const patternStr = readString(code, pos);
+  if (!patternStr) return null;
+  const pattern = patternStr.value;
+  pos = patternStr.end;
+
+  // Scan the rest of the call tracking depth.
+  // depth=1: inside path(), depth=2: inside an object/paren at top level of call.
+  // We look for `name: "..."` at depth 2 (options object properties).
+  let depth = 1;
+  let name: string | null = null;
+
+  while (pos < code.length && depth > 0) {
+    const ch = code[pos];
+
+    if (isWhitespace(ch)) {
+      pos++;
+      continue;
+    }
+
+    // Line comment
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
+      pos += 2;
+      while (pos < code.length && code[pos] !== "\n") pos++;
+      continue;
+    }
+
+    // Block comment
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
+      pos += 2;
+      while (
+        pos < code.length - 1 &&
+        !(code[pos] === "*" && code[pos + 1] === "/")
+      )
+        pos++;
+      pos += 2;
+      continue;
+    }
+
+    // At depth 2 (inside an object at call top-level), look for name: "..."
+    if (depth === 2 && ch === "n" && matchesNameColon(code, pos)) {
+      const nameResult = extractNameValue(code, pos);
+      if (nameResult) {
+        name = nameResult.value;
+        pos = nameResult.end;
+        continue;
+      }
+    }
+
+    // Skip string literals.
+    // Treat ' preceded by a word char as an apostrophe (e.g. "shouldn't"),
+    // not a string delimiter. In valid JS/TS, opening ' is never preceded
+    // by a word character.
+    if (ch === '"' || ch === "`" || (ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1])))) {
+      pos = skipStringLiteral(code, pos);
+      continue;
+    }
+
+    // Track depth
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+
+    pos++;
+  }
+
+  if (name === null) return null;
+  return { name, pattern };
+}
+
+/**
+ * Generates a .ts file that augments RSCRouter.GeneratedRouteMap
+ * with route name -> pattern mappings. This enables Handler<"routeName">
+ * without circular references since the file has no imports from the app.
+ */
+export function generateRouteTypesSource(
+  routeManifest: Record<string, string>
+): string {
+  const entries = Object.entries(routeManifest).sort(([a], [b]) =>
+    a.localeCompare(b)
+  );
+
+  const interfaceBody = entries
+    .map(([name, pattern]) => `      "${name}": "${pattern}";`)
+    .join("\n");
+
+  return `// Auto-generated by @rangojs/router - do not edit
+export {};
+
+declare global {
+  namespace RSCRouter {
+    interface GeneratedRouteMap {
+${interfaceBody}
+    }
+  }
+}
+`;
+}
+
+/** Default exclude patterns for route type scanning. */
+export const DEFAULT_EXCLUDE_PATTERNS: string[] = [
+  "**/__tests__/**",
+  "**/__mocks__/**",
+  "**/dist/**",
+  "**/coverage/**",
+  "**/*.test.{ts,tsx}",
+  "**/*.spec.{ts,tsx}",
+];
+
+export type ScanFilter = (absolutePath: string) => boolean;
+
+/**
+ * Compile include/exclude glob patterns into a single predicate.
+ * Paths are made root-relative before matching.
+ * Returns undefined when no filtering is needed (no include, default exclude).
+ */
+export function createScanFilter(
+  root: string,
+  opts: { include?: string[]; exclude?: string[] },
+): ScanFilter | undefined {
+  const { include, exclude } = opts;
+  const hasInclude = include && include.length > 0;
+  const hasCustomExclude = exclude !== undefined;
+
+  if (!hasInclude && !hasCustomExclude) return undefined;
+
+  const effectiveExclude = exclude ?? DEFAULT_EXCLUDE_PATTERNS;
+  const includeMatcher = hasInclude ? picomatch(include) : null;
+  const excludeMatcher = effectiveExclude.length > 0 ? picomatch(effectiveExclude) : null;
+
+  return (absolutePath: string) => {
+    const rel = relative(root, absolutePath);
+    if (excludeMatcher && excludeMatcher(rel)) return false;
+    if (includeMatcher) return includeMatcher(rel);
+    return true;
+  };
+}
+
+/**
+ * Recursively find .ts/.tsx files under a directory, skipping node_modules
+ * and .gen. files.
+ */
+export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
+  const results: string[] = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(`[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`);
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      results.push(...findTsFiles(fullPath, filter));
+    } else if (
+      (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) &&
+      !entry.name.includes(".gen.")
+    ) {
+      if (filter && !filter(fullPath)) continue;
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Generate per-module route type files by statically parsing url module source.
+ * Scans for files containing `urls(` and writes a sibling `.gen.ts` with the
+ * extracted route name/pattern pairs. Only writes when content has changed.
+ */
+export function writePerModuleRouteTypes(root: string, filter?: ScanFilter): void {
+  const files = findTsFiles(root, filter);
+  for (const filePath of files) {
+    writePerModuleRouteTypesForFile(filePath);
+  }
+}
+
+/**
+ * Generate per-module route types for a single url module file.
+ * No-ops if the file doesn't contain `urls(` or has no named routes.
+ */
+export function writePerModuleRouteTypesForFile(filePath: string): void {
+  try {
+    const source = readFileSync(filePath, "utf-8");
+    if (!source.includes("urls(")) return;
+
+    const routes = extractRoutesFromSource(source);
+    if (routes.length === 0) return;
+
+    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    const genSource = generatePerModuleTypesSource(routes);
+    const existing = existsSync(genPath) ? readFileSync(genPath, "utf-8") : null;
+    if (existing !== genSource) {
+      writeFileSync(genPath, genSource);
+      console.log(`[rsc-router] Generated route types -> ${genPath}`);
+    }
+  } catch (err) {
+    console.warn(`[rsc-router] Failed to generate route types for ${filePath}: ${(err as Error).message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Static include() parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract include() calls from source code by statically parsing.
+ * Returns the path prefix, variable name, and optional name prefix for each.
+ */
+export function extractIncludesFromSource(
+  code: string
+): Array<{ pathPrefix: string; variableName: string; namePrefix: string | null }> {
+  const results: Array<{
+    pathPrefix: string;
+    variableName: string;
+    namePrefix: string | null;
+  }> = [];
+  const regex = /\binclude\s*\(/g;
+  let match;
+
+  while ((match = regex.exec(code)) !== null) {
+    const result = parseIncludeCall(code, match.index + match[0].length);
+    if (result) results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * Parse a single include() call starting right after the opening paren.
+ * Expects: include("prefix", variableName, { name: "prefix" })
+ */
+function parseIncludeCall(
+  code: string,
+  pos: number
+): {
+  pathPrefix: string;
+  variableName: string;
+  namePrefix: string | null;
+} | null {
+  // Skip whitespace to first argument
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+
+  // First arg: string literal (pathPrefix)
+  const prefixStr = readString(code, pos);
+  if (!prefixStr) return null;
+  const pathPrefix = prefixStr.value;
+  pos = prefixStr.end;
+
+  // Comma
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  if (pos >= code.length || code[pos] !== ",") return null;
+  pos++;
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+
+  // Second arg: identifier (variableName)
+  const varStart = pos;
+  while (pos < code.length && /[\w$]/.test(code[pos])) pos++;
+  if (pos === varStart) return null;
+  const variableName = code.slice(varStart, pos);
+
+  // Scan rest of call for optional { name: "..." }
+  let namePrefix: string | null = null;
+  let depth = 1; // inside include()
+
+  while (pos < code.length && depth > 0) {
+    const ch = code[pos];
+
+    if (isWhitespace(ch)) {
+      pos++;
+      continue;
+    }
+
+    // Line comment
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
+      pos += 2;
+      while (pos < code.length && code[pos] !== "\n") pos++;
+      continue;
+    }
+
+    // Block comment
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
+      pos += 2;
+      while (
+        pos < code.length - 1 &&
+        !(code[pos] === "*" && code[pos + 1] === "/")
+      )
+        pos++;
+      pos += 2;
+      continue;
+    }
+
+    // At depth 2 (inside options object), look for name: "..."
+    if (depth === 2 && ch === "n" && matchesNameColon(code, pos)) {
+      const nameResult = extractNameValue(code, pos);
+      if (nameResult) {
+        namePrefix = nameResult.value;
+        pos = nameResult.end;
+        continue;
+      }
+    }
+
+    // Skip string literals
+    if (
+      ch === '"' ||
+      ch === "`" ||
+      (ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1])))
+    ) {
+      pos = skipStringLiteral(code, pos);
+      continue;
+    }
+
+    // Track depth
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+
+    pos++;
+  }
+
+  return { pathPrefix, variableName, namePrefix };
+}
+
+// ---------------------------------------------------------------------------
+// Import resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the import statement for a local variable name.
+ * Returns the import specifier and the exported name from the source module.
+ */
+function resolveImportedVariable(
+  code: string,
+  localName: string
+): { specifier: string; exportedName: string } | null {
+  const importRegex = /import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+  let match;
+
+  while ((match = importRegex.exec(code)) !== null) {
+    const imports = match[1];
+    const specifier = match[2];
+
+    const parts = imports
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    for (const part of parts) {
+      const asMatch = part.match(/^(\w+)\s+as\s+(\w+)$/);
+      if (asMatch && asMatch[2] === localName)
+        return { specifier, exportedName: asMatch[1] };
+      if (part === localName) return { specifier, exportedName: localName };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve an import specifier relative to the importing file.
+ * Strips .js/.mjs extensions and tries .ts/.tsx candidates.
+ */
+function resolveImportPath(
+  importSpec: string,
+  fromFile: string
+): string | null {
+  if (!importSpec.startsWith(".")) return null;
+
+  const dir = dirname(fromFile);
+  let base = importSpec;
+  if (base.endsWith(".js")) base = base.slice(0, -3);
+  else if (base.endsWith(".mjs")) base = base.slice(0, -4);
+
+  const candidates = [
+    resolve(dir, base + ".ts"),
+    resolve(dir, base + ".tsx"),
+    resolve(dir, base + "/index.ts"),
+    resolve(dir, base + "/index.tsx"),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// urls() block extraction for same-file variables
+// ---------------------------------------------------------------------------
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Extract the source of a specific `const varName = urls(...)` block.
+ * Used for same-file variables where include() references a urls() defined
+ * in the same module rather than imported.
+ */
+function extractUrlsBlockForVariable(
+  code: string,
+  varName: string
+): string | null {
+  const pattern = new RegExp(
+    `(?:export\\s+)?(?:const|let|var)\\s+${escapeRegExp(varName)}\\s*=\\s*urls\\s*\\(`
+  );
+  const match = pattern.exec(code);
+  if (!match) return null;
+
+  // Start from the opening paren of urls(
+  const openParen = match.index + match[0].length - 1;
+  let depth = 1;
+  let pos = openParen + 1;
+
+  while (pos < code.length && depth > 0) {
+    const ch = code[pos];
+
+    // Skip strings
+    if (
+      ch === '"' ||
+      ch === "`" ||
+      (ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1])))
+    ) {
+      pos = skipStringLiteral(code, pos);
+      continue;
+    }
+
+    // Line comment
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
+      pos += 2;
+      while (pos < code.length && code[pos] !== "\n") pos++;
+      continue;
+    }
+
+    // Block comment
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
+      pos += 2;
+      while (
+        pos < code.length - 1 &&
+        !(code[pos] === "*" && code[pos + 1] === "/")
+      )
+        pos++;
+      pos += 2;
+      continue;
+    }
+
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+
+    pos++;
+  }
+
+  return code.slice(openParen, pos);
+}
+
+// ---------------------------------------------------------------------------
+// Combined route map building
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively build a route map from a urls module file.
+ * Extracts local path() routes and follows include() calls to sub-modules.
+ * Handles both imported and same-file variables.
+ */
+export function buildCombinedRouteMap(
+  filePath: string,
+  variableName?: string,
+  visited?: Set<string>
+): Record<string, string> {
+  visited = visited ?? new Set();
+  const realPath = resolve(filePath);
+  const key = variableName ? `${realPath}:${variableName}` : realPath;
+  if (visited.has(key)) return {};
+  visited.add(key);
+
+  let source: string;
+  try {
+    source = readFileSync(realPath, "utf-8");
+  } catch {
+    return {};
+  }
+
+  // If a specific variable is requested, extract just its urls() block
+  let block: string;
+  if (variableName) {
+    const extracted = extractUrlsBlockForVariable(source, variableName);
+    if (!extracted) return {};
+    block = extracted;
+  } else {
+    block = source;
+  }
+
+  return buildRouteMapFromBlock(block, source, realPath, visited);
+}
+
+function buildRouteMapFromBlock(
+  block: string,
+  fullSource: string,
+  filePath: string,
+  visited: Set<string>
+): Record<string, string> {
+  const routeMap: Record<string, string> = {};
+
+  // Extract local path() routes
+  const localRoutes = extractRoutesFromSource(block);
+  for (const { name, pattern } of localRoutes) {
+    routeMap[name] = pattern;
+  }
+
+  // Extract include() calls
+  const includes = extractIncludesFromSource(block);
+  for (const { pathPrefix, variableName, namePrefix } of includes) {
+    let childRoutes: Record<string, string>;
+
+    // Try import resolution first
+    const imported = resolveImportedVariable(fullSource, variableName);
+    if (imported) {
+      const targetFile = resolveImportPath(imported.specifier, filePath);
+      if (!targetFile) continue;
+      childRoutes = buildCombinedRouteMap(
+        targetFile,
+        imported.exportedName,
+        visited
+      );
+    } else {
+      // Same-file variable
+      childRoutes = buildCombinedRouteMap(filePath, variableName, visited);
+    }
+
+    // Apply prefixes
+    for (const [name, pattern] of Object.entries(childRoutes)) {
+      const prefixedName = namePrefix ? `${namePrefix}.${name}` : name;
+      const prefixedPattern =
+        pattern === "/" ? pathPrefix || "/" : pathPrefix + pattern;
+      routeMap[prefixedName] = prefixedPattern;
+    }
+  }
+
+  return routeMap;
+}
+
+// ---------------------------------------------------------------------------
+// Router file URL extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the url patterns variable from a router file.
+ * Looks for patterns like:
+ *   .routes(variableName)
+ *   urls: variableName
+ * Returns the local variable name and optional import info.
+ */
+function extractUrlsVariableFromRouter(
+  code: string
+): string | null {
+  // Pattern 1: .routes(variableName) where variableName is an identifier (not a string)
+  const routesCallMatch = code.match(/\.routes\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/);
+  if (routesCallMatch) return routesCallMatch[1];
+
+  // Pattern 2: urls: variableName in createRouter options
+  const urlsOptionMatch = code.match(/urls\s*:\s*([a-zA-Z_$][\w$]*)/);
+  if (urlsOptionMatch) return urlsOptionMatch[1];
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Per-router named-routes.gen.ts writer
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan for files containing createRouter() and return their paths.
+ * Call once at startup; the result can be reused on subsequent watcher triggers.
+ */
+export function findRouterFiles(root: string, filter?: ScanFilter): string[] {
+  const files = findTsFiles(root, filter);
+  const result: string[] = [];
+  for (const filePath of files) {
+    if (filePath.includes(".gen.")) continue;
+    try {
+      const source = readFileSync(filePath, "utf-8");
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
+        result.push(filePath);
+      }
+    } catch {
+      continue;
+    }
+  }
+  return result;
+}
+
+/**
+ * Generate per-router named-routes.gen.ts files from known router file paths.
+ * Re-reads each router file and resolves url patterns via static source parsing.
+ *
+ * Pass `knownRouterFiles` from a previous `findRouterFiles()` call to skip the
+ * full directory scan. If omitted, falls back to scanning (startup path).
+ */
+export function writeCombinedRouteTypes(root: string, knownRouterFiles?: string[]): void {
+  // Delete old combined named-routes.gen.ts if it exists (stale from older versions)
+  try {
+    const oldCombinedPath = join(root, "src", "named-routes.gen.ts");
+    if (existsSync(oldCombinedPath)) {
+      unlinkSync(oldCombinedPath);
+      console.log(`[rsc-router] Removed stale combined route types: ${oldCombinedPath}`);
+    }
+  } catch {}
+
+  const routerFilePaths = knownRouterFiles ?? findRouterFiles(root);
+  if (routerFilePaths.length === 0) return;
+
+  for (const routerFilePath of routerFilePaths) {
+    let routerSource: string;
+    try {
+      routerSource = readFileSync(routerFilePath, "utf-8");
+    } catch {
+      continue;
+    }
+    // Extract the urls variable name from .routes(varName) or urls: varName
+    const urlsVarName = extractUrlsVariableFromRouter(routerSource);
+    if (!urlsVarName) continue;
+
+    // Resolve the variable to its source module
+    let routeMap: Record<string, string>;
+
+    const imported = resolveImportedVariable(routerSource, urlsVarName);
+    if (imported) {
+      // Variable is imported from another module
+      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+      if (!targetFile) continue;
+      routeMap = buildCombinedRouteMap(targetFile, imported.exportedName);
+    } else {
+      // Variable is defined in the same file
+      routeMap = buildCombinedRouteMap(routerFilePath, urlsVarName);
+    }
+
+    if (Object.keys(routeMap).length === 0) continue;
+
+    const routerBasename = pathBasename(routerFilePath).replace(/\.(tsx?|jsx?)$/, "");
+    const outPath = join(dirname(routerFilePath), `${routerBasename}.named-routes.gen.ts`);
+    const source = generateRouteTypesSource(routeMap);
+    const existing = existsSync(outPath) ? readFileSync(outPath, "utf-8") : null;
+    if (existing !== source) {
+      writeFileSync(outPath, source);
+      console.log(`[rsc-router] Generated route types (${Object.keys(routeMap).length} routes) -> ${outPath}`);
+    }
+  }
+}