@rangojs/router 0.0.0-experimental.0f44aca1

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

@@ -0,0 +1,411 @@
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import ts from "typescript";
+import { getStringValue } from "./ast-helpers.js";
+import { extractRoutesFromSource } from "./ast-route-extraction.js";
+
+// ---------------------------------------------------------------------------
+// Unresolvable include diagnostics
+// ---------------------------------------------------------------------------
+
+export type UnresolvableReason =
+  | "factory-call"
+  | "dynamic-expression"
+  | "unresolvable-import"
+  | "file-not-found";
+
+export interface UnresolvableInclude {
+  pathPrefix: string;
+  namePrefix: string | null;
+  reason: UnresolvableReason;
+  sourceFile: string;
+  detail: string;
+}
+
+// ---------------------------------------------------------------------------
+// AST-based include() parsing
+// ---------------------------------------------------------------------------
+
+function extractNamePrefixFromInclude(node: ts.CallExpression): string | null {
+  if (node.arguments.length >= 3) {
+    const thirdArg = node.arguments[2];
+    if (ts.isObjectLiteralExpression(thirdArg)) {
+      for (const prop of thirdArg.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const propName = ts.isIdentifier(prop.name) ? prop.name.text : null;
+        if (propName === "name") {
+          return getStringValue(prop.initializer);
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract include() calls with diagnostics for unresolvable ones.
+ * Returns both resolved includes (identifier second args) and unresolvable
+ * includes (factory calls, etc.) with reasons.
+ */
+export function extractIncludesWithDiagnostics(code: string): {
+  resolved: Array<{
+    pathPrefix: string;
+    variableName: string;
+    namePrefix: string | null;
+  }>;
+  unresolvable: Array<{
+    pathPrefix: string;
+    namePrefix: string | null;
+    reason: UnresolvableReason;
+    detail: string;
+  }>;
+} {
+  const sourceFile = ts.createSourceFile(
+    "input.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  const resolved: Array<{
+    pathPrefix: string;
+    variableName: string;
+    namePrefix: string | null;
+  }> = [];
+  const unresolvable: Array<{
+    pathPrefix: string;
+    namePrefix: string | null;
+    reason: UnresolvableReason;
+    detail: string;
+  }> = [];
+
+  function visit(node: ts.Node) {
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (ts.isIdentifier(callee) && callee.text === "include") {
+        if (node.arguments.length < 2) {
+          ts.forEachChild(node, visit);
+          return;
+        }
+
+        const pathPrefix = getStringValue(node.arguments[0]);
+        if (pathPrefix === null) {
+          ts.forEachChild(node, visit);
+          return;
+        }
+
+        const secondArg = node.arguments[1];
+        const namePrefix = extractNamePrefixFromInclude(node);
+
+        if (ts.isIdentifier(secondArg)) {
+          resolved.push({
+            pathPrefix,
+            variableName: secondArg.text,
+            namePrefix,
+          });
+        } else if (ts.isCallExpression(secondArg)) {
+          const callText = secondArg.expression.getText(sourceFile);
+          unresolvable.push({
+            pathPrefix,
+            namePrefix,
+            reason: "factory-call",
+            detail: `${callText}()`,
+          });
+        } else {
+          unresolvable.push({
+            pathPrefix,
+            namePrefix,
+            reason: "dynamic-expression",
+            detail: secondArg.getText(sourceFile),
+          });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return { resolved, unresolvable };
+}
+
+// ---------------------------------------------------------------------------
+// Import resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the import statement for a local variable name.
+ * Returns the import specifier and the exported name from the source module.
+ */
+export 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/.jsx extensions and tries .ts/.tsx/.js/.jsx candidates.
+ */
+export 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);
+  else if (base.endsWith(".jsx")) base = base.slice(0, -4);
+
+  const candidates = [
+    resolve(dir, base + ".ts"),
+    resolve(dir, base + ".tsx"),
+    resolve(dir, base + ".js"),
+    resolve(dir, base + ".jsx"),
+    resolve(dir, base + "/index.ts"),
+    resolve(dir, base + "/index.tsx"),
+    resolve(dir, base + "/index.js"),
+    resolve(dir, base + "/index.jsx"),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// urls() block extraction for same-file variables
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the source of a specific `const varName = urls(...)` call using
+ * the TypeScript AST. Returns the full text of the urls() call expression.
+ */
+function extractUrlsBlockForVariable(
+  code: string,
+  varName: string,
+): string | null {
+  const sourceFile = ts.createSourceFile(
+    "input.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  let result: string | null = null;
+
+  function visit(node: ts.Node) {
+    if (result) return;
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      node.name.text === varName &&
+      node.initializer &&
+      ts.isCallExpression(node.initializer)
+    ) {
+      const callee = node.initializer.expression;
+      if (ts.isIdentifier(callee) && callee.text === "urls") {
+        result = node.initializer.getText(sourceFile);
+        return;
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Combined route map building
+// ---------------------------------------------------------------------------
+
+function buildRouteMapFromBlock(
+  block: string,
+  fullSource: string,
+  filePath: string,
+  visited: Set<string>,
+  searchSchemasOut?: Record<string, Record<string, string>>,
+  diagnosticsOut?: UnresolvableInclude[],
+): 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 with diagnostics for unresolvable ones
+  const { resolved: includes, unresolvable } =
+    extractIncludesWithDiagnostics(block);
+
+  if (diagnosticsOut) {
+    for (const entry of unresolvable) {
+      diagnosticsOut.push({ ...entry, sourceFile: filePath });
+    }
+  }
+
+  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) {
+        if (diagnosticsOut) {
+          diagnosticsOut.push({
+            pathPrefix,
+            namePrefix,
+            reason: "file-not-found",
+            sourceFile: filePath,
+            detail: `import "${imported.specifier}" resolved to no file`,
+          });
+        }
+        continue;
+      }
+      childResult = buildCombinedRouteMapWithSearch(
+        targetFile,
+        imported.exportedName,
+        visited,
+        diagnosticsOut,
+      );
+    } else {
+      // Check if variable exists as a same-file urls() definition
+      const sameFileBlock = extractUrlsBlockForVariable(
+        fullSource,
+        variableName,
+      );
+      if (!sameFileBlock) {
+        if (diagnosticsOut) {
+          diagnosticsOut.push({
+            pathPrefix,
+            namePrefix,
+            reason: "unresolvable-import",
+            sourceFile: filePath,
+            detail: `variable "${variableName}" not found in imports or same-file scope`,
+          });
+        }
+        continue;
+      }
+      childResult = buildCombinedRouteMapWithSearch(
+        filePath,
+        variableName,
+        visited,
+        diagnosticsOut,
+      );
+    }
+
+    // Includes without a name keep their child names private to the mounted
+    // module. They remain active at runtime via an internal scope prefix, but
+    // they are intentionally omitted from generated public route maps.
+    if (namePrefix === null) {
+      continue;
+    }
+
+    // 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.
+ */
+export function buildCombinedRouteMapWithSearch(
+  filePath: string,
+  variableName?: string,
+  visited?: Set<string>,
+  diagnosticsOut?: UnresolvableInclude[],
+): {
+  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)) {
+    console.warn(`[rsc-router] Circular include detected, skipping: ${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,
+    diagnosticsOut,
+  );
+
+  // Remove from visited so sibling branches can include the same variable
+  // without false circular-include detection. Only ancestors in the current
+  // recursion path should trigger the cycle guard.
+  visited.delete(key);
+
+  return { routes, searchSchemas };
+}

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

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// Param extraction from route patterns
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract typed params from a route pattern string.
+ * Matches `:paramName` and `:paramName?` (optional).
+ * Custom regex constraints like `:id(\d+)` are ignored for type purposes.
+ */
+export function extractParamsFromPattern(
+  pattern: string,
+): Record<string, string> | undefined {
+  const params: Record<string, string> = {};
+  const regex = /:([a-zA-Z_$][\w$]*)(?:\([^)]+\))?(\?)?/g;
+  let match;
+  while ((match = regex.exec(pattern)) !== null) {
+    params[match[1]!] = match[2] ? "string?" : "string";
+  }
+  return Object.keys(params).length > 0 ? params : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Shared route entry formatter
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a single route entry for codegen output.
+ * Routes without search remain plain strings (params are extracted from
+ * the pattern at the type level by ExtractParams).
+ * Routes with search become objects with path and search fields.
+ */
+export function formatRouteEntry(
+  key: string,
+  pattern: string,
+  _params?: Record<string, string>,
+  search?: Record<string, string>,
+): string {
+  const hasSearch = search && Object.keys(search).length > 0;
+
+  if (!hasSearch) {
+    return `  ${key}: "${pattern}",`;
+  }
+
+  const searchBody = Object.entries(search!)
+    .map(([k, v]) => `${k}: "${v}"`)
+    .join(", ");
+  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
+}

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

@@ -0,0 +1,128 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+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 type { ScanFilter } from "./scan-filter.js";
+import { findTsFiles } from "./scan-filter.js";
+
+/**
+ * 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);
+  }
+}
+
+/**
+ * Find all variable names assigned to urls() calls in source code.
+ * e.g. `export const patterns = urls(...)` -> ["patterns"]
+ */
+export function findUrlsVariableNames(code: string): string[] {
+  const sourceFile = ts.createSourceFile(
+    "input.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  const names: string[] = [];
+
+  function visit(node: ts.Node) {
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      node.initializer &&
+      ts.isCallExpression(node.initializer)
+    ) {
+      const callee = node.initializer.expression;
+      if (ts.isIdentifier(callee) && callee.text === "urls") {
+        names.push(node.name.text);
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return names;
+}
+
+/**
+ * Generate per-module route types for a single url module file.
+ * Follows include() calls recursively to produce the full route tree.
+ * 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 varNames = findUrlsVariableNames(source);
+
+    type Route = {
+      name: string;
+      pattern: string;
+      params?: Record<string, string>;
+      search?: Record<string, string>;
+    };
+    let routes: Route[];
+
+    if (varNames.length > 0) {
+      // Follow includes recursively via the combined route map builder.
+      // The visited set in buildCombinedRouteMapWithSearch prevents infinite loops.
+      routes = [];
+      for (const varName of varNames) {
+        const { routes: routeMap, searchSchemas } =
+          buildCombinedRouteMapWithSearch(filePath, varName);
+        for (const [name, pattern] of Object.entries(routeMap)) {
+          const params = extractParamsFromPattern(pattern);
+          routes.push({
+            name,
+            pattern,
+            ...(params ? { params } : {}),
+            ...(searchSchemas[name] ? { search: searchSchemas[name] } : {}),
+          });
+        }
+      }
+    } else {
+      // Fallback: no urls() variable found, extract path() calls directly
+      routes = extractRoutesFromSource(source);
+    }
+
+    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+
+    // When a urls() variable was found but static resolution yields zero
+    // routes, write an empty placeholder so generated imports stay
+    // resolvable until runtime discovery fills them in.
+    if (routes.length === 0) {
+      if (varNames.length > 0 && !existsSync(genPath)) {
+        writeFileSync(genPath, generatePerModuleTypesSource([]));
+        console.log(
+          `[rsc-router] Generated route types (placeholder) -> ${genPath}`,
+        );
+      }
+      return;
+    }
+
+    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}`,
+    );
+  }
+}