@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.13221847

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

@@ -1,1038 +1,36 @@
-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; search?: Record<string, string> }> {
-  const routes: Array<{ name: string; pattern: string; search?: Record<string, string> }> = [];
-  // Match `path(...)` and typed helpers like `path.json(...)`, `path.md(...)`.
-  // Keep this generic so new helpers are picked up without parser updates.
-  const regex = /\bpath(?:\.[a-zA-Z_$][\w$]*)?\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; search?: Record<string, 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, { pattern: string; search?: Record<string, string> }>();
-  for (const { name, pattern, search } of valid) {
-    deduped.set(name, { pattern, search });
-  }
-  const sorted = [...deduped.entries()]
-    .sort(([a], [b]) => a.localeCompare(b));
-  const body = sorted
-    .map(([name, { pattern, search }]) => {
-      // Quote names that aren't valid bare identifiers (dots, dashes, etc.)
-      const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
-      if (search && Object.keys(search).length > 0) {
-        const searchBody = Object.entries(search)
-          .map(([k, v]) => `${k}: "${v}"`)
-          .join(", ");
-        return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
-      }
-      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.
- */
-/**
- * Check if code at pos starts with `search` as a standalone identifier
- * followed by `:` (an object property).
- */
-function matchesSearchColon(code: string, pos: number): boolean {
-  if (code.slice(pos, pos + 6) !== "search") return false;
-  if (pos > 0 && /\w/.test(code[pos - 1])) return false;
-  const afterSearch = pos + 6;
-  if (afterSearch < code.length && /\w/.test(code[afterSearch])) return false;
-  let checkPos = afterSearch;
-  while (checkPos < code.length && isWhitespace(code[checkPos])) checkPos++;
-  return code[checkPos] === ":";
-}
-
-/**
- * Extract a search schema object literal after `search:`.
- * Parses { key: "type", key2: "type2" } at the position after `search:`.
- * Returns the parsed schema and end position, or null if not an object literal.
- */
-function extractSearchValue(
-  code: string,
-  pos: number
-): { value: Record<string, string>; end: number } | null {
-  pos += 6; // skip 'search'
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-  pos++; // skip ':'
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-
-  if (code[pos] !== "{") return null;
-  pos++; // skip '{'
-
-  const schema: Record<string, string> = {};
-
-  while (pos < code.length) {
-    while (pos < code.length && isWhitespace(code[pos])) pos++;
-    if (code[pos] === "}") return { value: schema, end: pos + 1 };
-    if (code[pos] === ",") { pos++; continue; }
-
-    // Parse key (identifier or string)
-    let key: string;
-    if (code[pos] === '"' || code[pos] === "'") {
-      const keyStr = readString(code, pos);
-      if (!keyStr) return null;
-      key = keyStr.value;
-      pos = keyStr.end;
-    } else {
-      const keyStart = pos;
-      while (pos < code.length && /[\w$]/.test(code[pos])) pos++;
-      if (pos === keyStart) return null;
-      key = code.slice(keyStart, pos);
-    }
-
-    // Skip colon
-    while (pos < code.length && isWhitespace(code[pos])) pos++;
-    if (code[pos] !== ":") return null;
-    pos++;
-    while (pos < code.length && isWhitespace(code[pos])) pos++;
-
-    // Parse value (must be a string literal)
-    const valStr = readString(code, pos);
-    if (!valStr) return null;
-    schema[key] = valStr.value;
-    pos = valStr.end;
-  }
-
-  return null;
-}
-
-function parsePathCall(
-  code: string,
-  pos: number
-): { name: string; pattern: string; search?: Record<string, 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: "..."` and `search: { ... }` at depth 2 (options object properties).
-  let depth = 1;
-  let name: string | null = null;
-  let search: Record<string, string> | undefined;
-
-  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: "..." and search: { ... }
-    if (depth === 2 && ch === "n" && matchesNameColon(code, pos)) {
-      const nameResult = extractNameValue(code, pos);
-      if (nameResult) {
-        name = nameResult.value;
-        pos = nameResult.end;
-        continue;
-      }
-    }
-
-    if (depth === 2 && ch === "s" && matchesSearchColon(code, pos)) {
-      const searchResult = extractSearchValue(code, pos);
-      if (searchResult) {
-        search = searchResult.value;
-        pos = searchResult.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, ...(search ? { search } : {}) };
-}
-
-/**
- * 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>,
-  searchSchemas?: Record<string, Record<string, string>>
-): string {
-  const entries = Object.entries(routeManifest).sort(([a], [b]) =>
-    a.localeCompare(b)
-  );
-
-  const objectBody = entries
-    .map(([name, pattern]) => {
-      const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
-      const search = searchSchemas?.[name];
-      if (search && Object.keys(search).length > 0) {
-        const searchBody = Object.entries(search)
-          .map(([k, v]) => `${k}: "${v}"`)
-          .join(", ");
-        return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
-      }
-      return `  ${key}: "${pattern}",`;
-    })
-    .join("\n");
-
-  return `// Auto-generated by @rangojs/router - do not edit
-export const NamedRoutes = {
-${objectBody}
-} as const;
-
-declare global {
-  namespace RSCRouter {
-    interface GeneratedRouteMap extends Readonly<typeof NamedRoutes> {}
-  }
-}
-`;
-}
-
-/** 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>,
-  searchSchemasOut?: Record<string, Record<string, string>>
-): Record<string, string> {
-  const routeMap: Record<string, string> = {};
-
-  // Extract local path() routes
-  const localRoutes = extractRoutesFromSource(block);
-  for (const { name, pattern, search } of localRoutes) {
-    routeMap[name] = pattern;
-    if (search && searchSchemasOut) {
-      searchSchemasOut[name] = search;
-    }
-  }
-
-  // Extract include() calls
-  const includes = extractIncludesFromSource(block);
-  for (const { pathPrefix, variableName, namePrefix } of includes) {
-    let childResult: { routes: Record<string, string>; searchSchemas: Record<string, Record<string, string>> };
-
-    // Try import resolution first
-    const imported = resolveImportedVariable(fullSource, variableName);
-    if (imported) {
-      const targetFile = resolveImportPath(imported.specifier, filePath);
-      if (!targetFile) continue;
-      childResult = buildCombinedRouteMapWithSearch(
-        targetFile,
-        imported.exportedName,
-        visited
-      );
-    } else {
-      // Same-file variable
-      childResult = buildCombinedRouteMapWithSearch(filePath, variableName, visited);
-    }
-
-    // Apply prefixes
-    for (const [name, pattern] of Object.entries(childResult.routes)) {
-      const prefixedName = namePrefix ? `${namePrefix}.${name}` : name;
-      let prefixedPattern: string;
-      if (pattern === "/") {
-        prefixedPattern = pathPrefix || "/";
-      } else if (pathPrefix.endsWith("/") && pattern.startsWith("/")) {
-        prefixedPattern = pathPrefix + pattern.slice(1);
-      } else {
-        prefixedPattern = pathPrefix + pattern;
-      }
-      routeMap[prefixedName] = prefixedPattern;
-      // Propagate search schemas with prefix
-      if (childResult.searchSchemas[name] && searchSchemasOut) {
-        searchSchemasOut[prefixedName] = childResult.searchSchemas[name];
-      }
-    }
-  }
-
-  return routeMap;
-}
-
-/**
- * Build route map and search schemas together.
- * Internal helper used by the include resolution path.
- */
-function buildCombinedRouteMapWithSearch(
-  filePath: string,
-  variableName?: string,
-  visited?: Set<string>
-): { routes: Record<string, string>; searchSchemas: Record<string, Record<string, string>> } {
-  visited = visited ?? new Set();
-  const realPath = resolve(filePath);
-  const key = variableName ? `${realPath}:${variableName}` : realPath;
-  if (visited.has(key)) return { routes: {}, searchSchemas: {} };
-  visited.add(key);
-
-  let source: string;
-  try {
-    source = readFileSync(realPath, "utf-8");
-  } catch {
-    return { routes: {}, searchSchemas: {} };
-  }
-
-  let block: string;
-  if (variableName) {
-    const extracted = extractUrlsBlockForVariable(source, variableName);
-    if (!extracted) return { routes: {}, searchSchemas: {} };
-    block = extracted;
-  } else {
-    block = source;
-  }
-
-  const searchSchemas: Record<string, Record<string, string>> = {};
-  const routes = buildRouteMapFromBlock(block, source, realPath, visited, searchSchemas);
-  return { routes, searchSchemas };
-}
-
-// ---------------------------------------------------------------------------
-// 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;
-}
-
-/**
- * Resolve routes and search schemas from a router source file by following the
- * variable passed to `.routes(...)` or `urls: ...` in createRouter options.
- */
-export function buildCombinedRouteMapForRouterFile(
-  routerFilePath: string,
-): { routes: Record<string, string>; searchSchemas: Record<string, Record<string, string>> } {
-  let routerSource: string;
-  try {
-    routerSource = readFileSync(routerFilePath, "utf-8");
-  } catch {
-    return { routes: {}, searchSchemas: {} };
-  }
-
-  const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-  if (!urlsVarName) {
-    return { routes: {}, searchSchemas: {} };
-  }
-
-  const imported = resolveImportedVariable(routerSource, urlsVarName);
-  if (imported) {
-    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-    if (!targetFile) {
-      return { routes: {}, searchSchemas: {} };
-    }
-    return buildCombinedRouteMapWithSearch(targetFile, imported.exportedName);
-  }
-
-  return buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
-}
-
-// ---------------------------------------------------------------------------
-// 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).
- */
-/**
- * Write named-routes.gen.ts files from static source parsing.
- * Dev-only: provides initial .gen.ts files for IDE types before runtime
- * discovery runs. Must NOT be called during production builds — runtime
- * discovery in buildStart produces the definitive file.
- */
-export function writeCombinedRouteTypes(root: string, knownRouterFiles?: string[], opts?: { preserveIfLarger?: boolean }): 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 result: { routes: Record<string, string>; searchSchemas: Record<string, 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;
-      result = buildCombinedRouteMapWithSearch(targetFile, imported.exportedName);
-    } else {
-      // Variable is defined in the same file
-      result = buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
-    }
-
-    const routerBasename = pathBasename(routerFilePath).replace(/\.(tsx?|jsx?)$/, "");
-    const outPath = join(dirname(routerFilePath), `${routerBasename}.named-routes.gen.ts`);
-    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({});
-        writeFileSync(outPath, emptySource);
-      }
-      continue;
-    }
-
-    const hasSearchSchemas = Object.keys(result.searchSchemas).length > 0;
-    const source = generateRouteTypesSource(
-      result.routes,
-      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 = (existing.match(/^\s+["a-zA-Z_$][^:]*:\s*"/gm) || []).length;
-        const newCount = Object.keys(result.routes).length;
-        if (existingCount > newCount) {
-          continue;
-        }
-      }
-      writeFileSync(outPath, source);
-      console.log(`[rsc-router] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`);
-    }
-  }
-}
+// Barrel re-export -- see route-types/ for implementations.
+export {
+  extractParamsFromPattern,
+  formatRouteEntry,
+} from "./route-types/param-extraction.js";
+export { extractRoutesFromSource } from "./route-types/ast-route-extraction.js";
+export {
+  generatePerModuleTypesSource,
+  generateRouteTypesSource,
+} from "./route-types/codegen.js";
+export {
+  DEFAULT_EXCLUDE_PATTERNS,
+  type ScanFilter,
+  createScanFilter,
+  findTsFiles,
+} from "./route-types/scan-filter.js";
+export {
+  writePerModuleRouteTypes,
+  writePerModuleRouteTypesForFile,
+} from "./route-types/per-module-writer.js";
+export {
+  type UnresolvableReason,
+  type UnresolvableInclude,
+  extractIncludesWithDiagnostics,
+} from "./route-types/include-resolution.js";
+export {
+  extractUrlsVariableFromRouter,
+  buildCombinedRouteMapForRouterFile,
+  detectUnresolvableIncludes,
+  detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
+  findRouterFiles,
+  writeCombinedRouteTypes,
+} from "./route-types/router-processing.js";
+export { findUrlsVariableNames } from "./route-types/per-module-writer.js";