@rangojs/router 0.0.0-experimental.0f44aca1

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

@@ -0,0 +1,469 @@
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  unlinkSync,
+  readdirSync,
+} from "node:fs";
+import {
+  join,
+  dirname,
+  resolve,
+  sep,
+  basename as pathBasename,
+} from "node:path";
+import ts from "typescript";
+import { generateRouteTypesSource } from "./codegen.js";
+import type { ScanFilter } from "./scan-filter.js";
+import {
+  resolveImportedVariable,
+  resolveImportPath,
+  buildCombinedRouteMapWithSearch,
+  type UnresolvableInclude,
+} from "./include-resolution.js";
+import { findUrlsVariableNames } from "./per-module-writer.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
+
+function countPublicRouteEntries(source: string): number {
+  const matches =
+    source.matchAll(/^\s+(?:"([^"]+)"|([a-zA-Z_$][^:]*)):\s*["{]/gm) ?? [];
+  let count = 0;
+  for (const match of matches) {
+    const routeName = match[1] || match[2];
+    if (routeName && !isAutoGeneratedRouteName(routeName.trim())) {
+      count++;
+    }
+  }
+  return count;
+}
+
+const ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+
+function isRoutableSourceFile(name: string): boolean {
+  return (
+    (name.endsWith(".ts") ||
+      name.endsWith(".tsx") ||
+      name.endsWith(".js") ||
+      name.endsWith(".jsx")) &&
+    !name.includes(".gen.")
+  );
+}
+
+function findRouterFilesRecursive(
+  dir: string,
+  filter: ScanFilter | undefined,
+  results: string[],
+): void {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(
+      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+    );
+    return;
+  }
+
+  const childDirs: string[] = [];
+  const routerFilesInDir: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      childDirs.push(fullPath);
+      continue;
+    }
+
+    if (!isRoutableSourceFile(entry.name)) continue;
+    if (filter && !filter(fullPath)) continue;
+
+    try {
+      const source = readFileSync(fullPath, "utf-8");
+      if (ROUTER_CALL_PATTERN.test(source)) {
+        routerFilesInDir.push(fullPath);
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  // A directory that contains a router file is treated as a router root.
+  // Once found, deeper directories are skipped to avoid redundant scans.
+  if (routerFilesInDir.length > 0) {
+    results.push(...routerFilesInDir);
+    return;
+  }
+
+  for (const childDir of childDirs) {
+    findRouterFilesRecursive(childDir, filter, results);
+  }
+}
+
+export function findNestedRouterConflict(
+  routerFiles: string[],
+): { ancestor: string; nested: string } | null {
+  const routerDirs = [
+    ...new Set(routerFiles.map((filePath) => dirname(resolve(filePath)))),
+  ].sort((a, b) => a.length - b.length);
+
+  for (let i = 0; i < routerDirs.length; i++) {
+    const ancestorDir = routerDirs[i];
+    const prefix = ancestorDir.endsWith(sep)
+      ? ancestorDir
+      : `${ancestorDir}${sep}`;
+    for (let j = i + 1; j < routerDirs.length; j++) {
+      const nestedDir = routerDirs[j];
+      if (!nestedDir.startsWith(prefix)) continue;
+      const ancestorFile = routerFiles.find(
+        (filePath) => dirname(resolve(filePath)) === ancestorDir,
+      );
+      const nestedFile = routerFiles.find(
+        (filePath) => dirname(resolve(filePath)) === nestedDir,
+      );
+      if (ancestorFile && nestedFile) {
+        return { ancestor: ancestorFile, nested: nestedFile };
+      }
+    }
+  }
+
+  return null;
+}
+
+export function formatNestedRouterConflictError(
+  conflict: { ancestor: string; nested: string },
+  prefix = "[rsc-router]",
+): string {
+  return (
+    `${prefix} Nested router roots are not supported.\n` +
+    `Router root: ${conflict.ancestor}\n` +
+    `Nested router: ${conflict.nested}\n` +
+    `Move the nested router into a sibling directory or configure it as a separate app root.`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Router file URL extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the url patterns variable from a router file using AST.
+ * Detects two patterns:
+ *   1. createRouter(...).routes(variableName)
+ *   2. createRouter({ urls: variableName, ... })
+ * Returns the local variable name.
+ */
+export function extractUrlsVariableFromRouter(code: string): string | null {
+  const sourceFile = ts.createSourceFile(
+    "router.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  let result: string | null = null;
+
+  function isCreateRouterCall(node: ts.Node): boolean {
+    if (!ts.isCallExpression(node)) return false;
+    const callee = node.expression;
+    return ts.isIdentifier(callee) && callee.text === "createRouter";
+  }
+
+  function visit(node: ts.Node) {
+    if (result) return;
+
+    // Pattern 1: createRouter(...).routes(variableName)
+    // The AST shape is CallExpression(.routes) -> PropertyAccessExpression -> CallExpression(createRouter)
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      node.expression.name.text === "routes" &&
+      node.arguments.length >= 1 &&
+      ts.isIdentifier(node.arguments[0])
+    ) {
+      // Walk up the chain: createRouter().middleware(...).routes(x) etc.
+      // The innermost call should be createRouter(...)
+      let inner: ts.Expression = node.expression.expression;
+      while (
+        ts.isCallExpression(inner) &&
+        ts.isPropertyAccessExpression(inner.expression)
+      ) {
+        inner = inner.expression.expression;
+      }
+      if (isCreateRouterCall(inner)) {
+        result = (node.arguments[0] as ts.Identifier).text;
+        return;
+      }
+    }
+
+    // Pattern 2: createRouter({ urls: variableName, ... })
+    if (isCreateRouterCall(node)) {
+      const callExpr = node as ts.CallExpression;
+      for (const arg of callExpr.arguments) {
+        if (ts.isObjectLiteralExpression(arg)) {
+          for (const prop of arg.properties) {
+            if (
+              ts.isPropertyAssignment(prop) &&
+              ts.isIdentifier(prop.name) &&
+              prop.name.text === "urls" &&
+              ts.isIdentifier(prop.initializer)
+            ) {
+              result = prop.initializer.text;
+              return;
+            }
+          }
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return result;
+}
+
+/**
+ * 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);
+}
+
+// ---------------------------------------------------------------------------
+// Unresolvable include detection (full include tree walk)
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk the full include tree starting from a router file and detect
+ * all includes that the static parser cannot resolve.
+ * Returns an array of diagnostics; empty means fully resolvable.
+ */
+export function detectUnresolvableIncludes(
+  routerFilePath: string,
+): UnresolvableInclude[] {
+  const realPath = resolve(routerFilePath);
+  let source: string;
+  try {
+    source = readFileSync(realPath, "utf-8");
+  } catch {
+    return [];
+  }
+
+  // Extract the urls variable from the router file
+  const urlsVarName = extractUrlsVariableFromRouter(source);
+  if (!urlsVarName) return [];
+
+  // Resolve where the urls variable comes from
+  const imported = resolveImportedVariable(source, urlsVarName);
+  let targetFile: string;
+  let exportedName: string | undefined;
+
+  if (imported) {
+    const resolved = resolveImportPath(imported.specifier, realPath);
+    if (!resolved) {
+      return [
+        {
+          pathPrefix: "/",
+          namePrefix: null,
+          reason: "file-not-found",
+          sourceFile: realPath,
+          detail: `import "${imported.specifier}" resolved to no file`,
+        },
+      ];
+    }
+    targetFile = resolved;
+    exportedName = imported.exportedName;
+  } else {
+    // Same-file urls() definition
+    targetFile = realPath;
+    exportedName = urlsVarName;
+  }
+
+  const diagnostics: UnresolvableInclude[] = [];
+  buildCombinedRouteMapWithSearch(
+    targetFile,
+    exportedName,
+    new Set(),
+    diagnostics,
+  );
+  return diagnostics;
+}
+
+/**
+ * Walk the include tree for a standalone urls() module file and detect
+ * all unresolvable includes. Mirrors detectUnresolvableIncludes() but
+ * operates on urls() variable declarations instead of going through
+ * createRouter().
+ */
+export function detectUnresolvableIncludesForUrlsFile(
+  filePath: string,
+): UnresolvableInclude[] {
+  const realPath = resolve(filePath);
+  let source: string;
+  try {
+    source = readFileSync(realPath, "utf-8");
+  } catch {
+    return [];
+  }
+
+  const varNames = findUrlsVariableNames(source);
+  if (varNames.length === 0) return [];
+
+  const diagnostics: UnresolvableInclude[] = [];
+  for (const varName of varNames) {
+    buildCombinedRouteMapWithSearch(realPath, varName, new Set(), diagnostics);
+  }
+  return diagnostics;
+}
+
+// ---------------------------------------------------------------------------
+// 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 result: string[] = [];
+  findRouterFilesRecursive(root, filter, result);
+  return result;
+}
+
+/**
+ * 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;
+
+  const nestedRouterConflict = findNestedRouterConflict(routerFilePaths);
+  if (nestedRouterConflict) {
+    throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
+  }
+
+  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 = countPublicRouteEntries(existing);
+        const newCount = Object.keys(result.routes).filter(
+          (name) => !isAutoGeneratedRouteName(name),
+        ).length;
+        if (existingCount > newCount) {
+          continue;
+        }
+      }
+      writeFileSync(outPath, source);
+      console.log(
+        `[rsc-router] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
+      );
+    }
+  }
+}

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

@@ -0,0 +1,78 @@
+import { join, relative } from "node:path";
+import { readdirSync } from "node:fs";
+// @ts-ignore -- picomatch ships no .d.ts; types are trivial
+import picomatch from "picomatch";
+
+/** Default exclude patterns for route type scanning. */
+export const DEFAULT_EXCLUDE_PATTERNS: string[] = [
+  "**/__tests__/**",
+  "**/__mocks__/**",
+  "**/dist/**",
+  "**/coverage/**",
+  "**/*.test.{ts,tsx,js,jsx}",
+  "**/*.spec.{ts,tsx,js,jsx}",
+];
+
+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.endsWith(".js") ||
+        entry.name.endsWith(".jsx")) &&
+      !entry.name.includes(".gen.")
+    ) {
+      if (filter && !filter(fullPath)) continue;
+      results.push(fullPath);
+    }
+  }
+  return results;
+}