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

package/src/vite/discovery/route-types-writer.ts

@@ -0,0 +1,214 @@
+/**
+ * Route Types Writer
+ *
+ * Generates and writes TypeScript route type files (named-routes.gen.ts)
+ * from discovered router manifests and static source parsing.
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
+import {
+  generateRouteTypesSource,
+  writeCombinedRouteTypes,
+  findRouterFiles,
+  buildCombinedRouteMapForRouterFile,
+  genFileTsPath,
+  resolveSearchSchemas,
+} from "../../build/generate-route-types.js";
+import type { DiscoveryState } from "./state.js";
+import { markSelfGenWrite } from "./self-gen-tracking.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
+
+/**
+ * Filter out auto-generated route names from a manifest.
+ * Unnamed routes get "$path_"-prefixed names at runtime (see path-helper.ts).
+ * These should not appear in the typed gen file. User-defined names
+ * containing "$" (e.g. "$admin") are valid and preserved.
+ */
+function filterUserNamedRoutes(
+  manifest: Record<string, string>,
+): Record<string, string> {
+  const filtered: Record<string, string> = {};
+  for (const [name, pattern] of Object.entries(manifest)) {
+    if (!isAutoGeneratedRouteName(name)) {
+      filtered[name] = pattern;
+    }
+  }
+  return filtered;
+}
+
+// Write a gen file only when content changed, marking the write as
+// self-generated BEFORE writeFileSync so the watcher distinguishes it from a
+// manual edit (the HMR self-gen-loop guard).
+function writeGenFileIfChanged(
+  state: DiscoveryState,
+  outPath: string,
+  source: string,
+  opts?: { log?: boolean },
+): void {
+  const existing = existsSync(outPath) ? readFileSync(outPath, "utf-8") : null;
+  if (existing === source) return;
+  markSelfGenWrite(state, outPath, source);
+  writeFileSync(outPath, source);
+  if (opts?.log) console.log(`[rango] Generated route types -> ${outPath}`);
+}
+
+/**
+ * Write combined route types for all router files.
+ * Only writes when content has changed to avoid triggering HMR loops.
+ */
+export function writeCombinedRouteTypesWithTracking(
+  state: DiscoveryState,
+  opts?: { preserveIfLarger?: boolean },
+): void {
+  const routerFiles =
+    state.cachedRouterFiles ??
+    findRouterFiles(state.projectRoot, state.scanFilter);
+  state.cachedRouterFiles = routerFiles;
+
+  // Mark each gen file as self-generated BEFORE it is written, via the onWrite
+  // callback fired at every writeFileSync site, so the watcher distinguishes
+  // self-triggered change events from manual edits. The callback fires only
+  // for files actually written, so unchanged files are never marked (stale
+  // entries interfere with multi-server setups such as a shared webServer plus
+  // an isolated HMR server).
+  writeCombinedRouteTypes(state.projectRoot, routerFiles, {
+    ...opts,
+    onWrite: (outPath, content) => markSelfGenWrite(state, outPath, content),
+  });
+}
+
+/**
+ * Write per-router route types files from runtime discovery data.
+ */
+export function writeRouteTypesFiles(state: DiscoveryState): void {
+  if (state.perRouterManifests.length === 0) return;
+
+  // Delete old combined named-routes.gen.ts if it exists
+  try {
+    const entryDir = dirname(
+      resolve(state.projectRoot, state.resolvedEntryPath!),
+    );
+    const oldCombinedPath = join(entryDir, "named-routes.gen.ts");
+    if (existsSync(oldCombinedPath)) {
+      unlinkSync(oldCombinedPath);
+      console.log(
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`,
+      );
+    }
+  } catch {}
+
+  for (const {
+    id,
+    routeManifest,
+    routeSearchSchemas,
+    sourceFile,
+  } of state.perRouterManifests) {
+    if (!sourceFile) continue;
+
+    // Validate sourceFile points to a real project file, not node_modules or
+    // a Vite internal path. A bad sourceFile leads to route types written to
+    // the wrong location, causing non-deterministic type resolution.
+    if (sourceFile.includes("node_modules")) {
+      throw new Error(
+        `[rango] Router "${id}" has sourceFile inside node_modules: ${sourceFile}\n` +
+          `This means createRouter() stack trace parsing matched a Vite internal frame.\n` +
+          `Set an explicit \`id\` on createRouter() or check the call site.`,
+      );
+    }
+
+    const outPath = genFileTsPath(sourceFile);
+
+    // Filter out auto-generated route names (e.g. "$path____debug_reverse-test")
+    // to match the static parser's output and prevent HMR oscillation.
+    const userRoutes = filterUserNamedRoutes(routeManifest);
+    const effectiveSearchSchemas = resolveSearchSchemas(
+      Object.keys(userRoutes),
+      routeSearchSchemas,
+      sourceFile,
+    );
+
+    const source = generateRouteTypesSource(
+      userRoutes,
+      effectiveSearchSchemas && Object.keys(effectiveSearchSchemas).length > 0
+        ? effectiveSearchSchemas
+        : undefined,
+    );
+    writeGenFileIfChanged(state, outPath, source, { log: true });
+  }
+}
+
+/**
+ * Supplement gen files with route groups from runtime manifests that the
+ * static parser cannot resolve (factory calls like createDocsPatterns()).
+ * Only adds groups whose dot-prefix (e.g. "docs.") is entirely absent
+ * from the static output. Groups partially visible to the static parser
+ * are left alone so renames/removals propagate immediately without
+ * requiring a server restart.
+ *
+ * The runtime manifest (cachedManifest / perRouterManifestMap) is updated
+ * automatically: the virtual:rsc-router/routes-manifest module imports the
+ * gen file, so when we write new content here, Vite's HMR invalidates the
+ * virtual module and re-evaluates it on the next request.
+ */
+export function supplementGenFilesWithRuntimeRoutes(
+  state: DiscoveryState,
+): void {
+  // Cache static parsing results to avoid redundant I/O + parsing per router.
+  const parseCache = new Map<
+    string,
+    ReturnType<typeof buildCombinedRouteMapForRouterFile>
+  >();
+  const getParsed = (file: string) => {
+    let cached = parseCache.get(file);
+    if (!cached) {
+      cached = buildCombinedRouteMapForRouterFile(file);
+      parseCache.set(file, cached);
+    }
+    return cached;
+  };
+
+  for (const {
+    routeManifest,
+    routeSearchSchemas,
+    sourceFile,
+    factoryOnlyPrefixes,
+  } of state.perRouterManifests) {
+    if (!sourceFile) continue;
+    if (!factoryOnlyPrefixes || factoryOnlyPrefixes.size === 0) continue;
+
+    const staticParsed = getParsed(sourceFile);
+
+    // Merge: static routes (authoritative) + factory-only groups from runtime.
+    const mergedRoutes: Record<string, string> = { ...staticParsed.routes };
+    const mergedSearchSchemas: Record<string, Record<string, string>> = {
+      ...staticParsed.searchSchemas,
+    };
+
+    for (const [name, pattern] of Object.entries(routeManifest)) {
+      // Skip internal runtime-only names from unnamed routes/includes.
+      if (isAutoGeneratedRouteName(name)) continue;
+      const dotIdx = name.indexOf(".");
+      if (dotIdx <= 0) continue;
+      const prefix = name.substring(0, dotIdx + 1);
+      if (factoryOnlyPrefixes.has(prefix)) {
+        mergedRoutes[name] = pattern;
+        // Also merge search schemas from factory-generated routes
+        if (routeSearchSchemas?.[name]) {
+          mergedSearchSchemas[name] = routeSearchSchemas[name];
+        }
+      }
+    }
+
+    const outPath = genFileTsPath(sourceFile);
+    const source = generateRouteTypesSource(
+      mergedRoutes,
+      Object.keys(mergedSearchSchemas).length > 0
+        ? mergedSearchSchemas
+        : undefined,
+    );
+    writeGenFileIfChanged(state, outPath, source);
+  }
+  // No manual manifest update needed: the virtual module imports the gen
+  // file, so Vite's HMR automatically re-evaluates it with fresh data.
+}

package/src/vite/discovery/self-gen-tracking.ts

@@ -0,0 +1,73 @@
+/**
+ * Self-Generated File Tracking
+ *
+ * Tracks gen files recently written by the discovery plugin so the
+ * file watcher can distinguish self-triggered change events from
+ * manual edits.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { DiscoveryState } from "./state.js";
+
+export function markSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+  content: string,
+): void {
+  const hash = createHash("sha256").update(content).digest("hex");
+  state.selfWrittenGenFiles.set(filePath, { at: Date.now(), hash });
+}
+
+export function consumeSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+): boolean {
+  return checkSelfGenWrite(state, filePath, true);
+}
+
+/**
+ * Non-consuming variant. Used by the `handleHotUpdate` plugin hook to
+ * suppress vite's HMR cascade for our own gen-file writes WITHOUT
+ * consuming the entry — `consumeSelfGenWrite` (called later from the
+ * chokidar `change` handler in `handleRouteFileChange`) still needs to
+ * see and consume the same entry to short-circuit our regen path.
+ *
+ * Both hooks fire for the same file change event:
+ *   - `handleHotUpdate` runs first (vite's HMR pipeline).
+ *   - chokidar `change` callback runs after (filesystem watcher).
+ */
+export function peekSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+): boolean {
+  return checkSelfGenWrite(state, filePath, false);
+}
+
+function checkSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+  consume: boolean,
+): boolean {
+  const info = state.selfWrittenGenFiles.get(filePath);
+  if (!info) return false;
+  if (Date.now() - info.at > state.SELF_WRITE_WINDOW_MS) {
+    state.selfWrittenGenFiles.delete(filePath);
+    return false;
+  }
+  try {
+    const current = readFileSync(filePath, "utf-8");
+    const currentHash = createHash("sha256").update(current).digest("hex");
+    if (currentHash === info.hash) {
+      if (consume) state.selfWrittenGenFiles.delete(filePath);
+      return true;
+    }
+    // Hash mismatch: file was changed externally. Keep the entry so a
+    // subsequent watcher event from our own write can still be consumed
+    // (e.g. when multiple Vite servers watch the same directory).
+    return false;
+  } catch {
+    state.selfWrittenGenFiles.delete(filePath);
+    return false;
+  }
+}

package/src/vite/discovery/state.ts

@@ -0,0 +1,161 @@
+/**
+ * Discovery State
+ *
+ * Shared mutable state for the router discovery plugin.
+ * Created once by createRouterDiscoveryPlugin() and passed
+ * to all extracted helper functions.
+ */
+
+import type { ScanFilter } from "../../build/generate-route-types.js";
+
+export const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
+
+export interface PluginOptions {
+  enableBuildPrerender?: boolean;
+  staticRouteTypesGeneration?: boolean;
+  // Mutable ref for deferred auto-discovery (node preset).
+  // The auto-discover config() hook populates this before configResolved.
+  routerPathRef?: { path?: string };
+  /** Build-time env option from rango() config. */
+  buildEnv?: import("../plugin-types.js").BuildEnvOption;
+  /** Deployment preset (needed for buildEnv "auto" resolution). */
+  preset?: "node" | "cloudflare";
+  /**
+   * Route-discovery scan filter (glob include/exclude) from rango() config.
+   * Compiled into `DiscoveryState.scanFilter` once `projectRoot` is known.
+   */
+  discovery?: { include?: string[]; exclude?: string[] };
+  /**
+   * What to do when a Prerender/Static render throws at build time, from
+   * rango({ prerender: { onError } }). "fail" (default) fails the build; "warn"
+   * logs and skips baking the URL. See {@link import("../plugin-types.js").RangoOptions}.
+   */
+  prerenderOnError?: "fail" | "warn";
+  /**
+   * Shared context the built-in clientChunks strategy reads. Discovery populates
+   * it (registered fallback hashes + single-router name) before the client build
+   * invokes the strategy. Present only when the built-in strategy is active
+   * (`clientChunks: true`/default); undefined for `false` or a custom function.
+   */
+  clientChunkCtx?: import("../utils/client-chunks.js").ClientChunkContext;
+}
+
+export interface PrecomputedEntry {
+  staticPrefix: string;
+  routes: Record<string, string>;
+}
+
+export interface ChunkInfo {
+  fileName: string;
+  exports: Array<{ name: string; handlerId: string; passthrough: boolean }>;
+}
+
+export interface PerRouterManifestEntry {
+  id: string;
+  routeManifest: Record<string, string>;
+  routeSearchSchemas?: Record<string, Record<string, string>>;
+  sourceFile?: string;
+  factoryOnlyPrefixes?: Set<string>;
+}
+
+export interface DiscoveryState {
+  resolvedEntryPath: string | undefined;
+  projectRoot: string;
+  isBuildMode: boolean;
+  userResolveAlias: any;
+  /**
+   * Data-only slice of the user's resolved config (resolve.* incl. native
+   * tsconfigPaths, define, oxc) mirrored into the discovery temp server so it
+   * resolves and transforms modules the same way the real environment does.
+   * See `utils/forward-user-plugins.ts`.
+   */
+  userRunnerConfig:
+    | import("../utils/forward-user-plugins.js").ForwardedRunnerConfig
+    | undefined;
+  /**
+   * User resolution plugins (resolveId/load), stripped to their resolution
+   * surface, forwarded into the discovery temp server. Lets third-party
+   * resolvers such as vite-tsconfig-paths participate in discovery.
+   */
+  userResolvePlugins: import("vite").Plugin[];
+  scanFilter: ScanFilter | undefined;
+  cachedRouterFiles: string[] | undefined;
+  opts: PluginOptions | undefined;
+
+  mergedRouteManifest: Record<string, string> | null;
+  perRouterManifests: PerRouterManifestEntry[];
+  mergedPrecomputedEntries: PrecomputedEntry[] | null;
+  mergedRouteTrie: any;
+
+  perRouterTrieMap: Map<string, any>;
+  perRouterPrecomputedMap: Map<string, PrecomputedEntry[]>;
+  perRouterManifestDataMap: Map<string, Record<string, string>>;
+
+  prerenderManifestEntries: Record<string, string> | null;
+  staticManifestEntries: Record<string, string> | null;
+  handlerChunkInfoMap: Map<string, ChunkInfo>;
+  staticHandlerChunkInfoMap: Map<string, ChunkInfo>;
+  rscEntryFileName: string | null;
+  resolvedPrerenderModules: Map<string, string[]> | undefined;
+  resolvedStaticModules: Map<string, string[]> | undefined;
+
+  discoveryDone: Promise<void> | null;
+  devServerOrigin: string | null;
+  devServer: any;
+  selfWrittenGenFiles: Map<string, { at: number; hash: string }>;
+  SELF_WRITE_WINDOW_MS: number;
+
+  /** Resolved build-time env bindings (set during buildStart/configureServer). */
+  resolvedBuildEnv?: Record<string, unknown>;
+  /** Cleanup function for build-time env resources (e.g., miniflare). */
+  buildEnvDispose?: (() => Promise<void> | void) | null;
+
+  /**
+   * Set when the most recent HMR re-discovery threw. Cleared on the next
+   * successful discovery. Surfaced via debug logs so we can detect "manifest
+   * frozen at last-good after error → user fix in non-route file → no
+   * rediscovery trigger" scenarios.
+   */
+  lastDiscoveryError?: { message: string; at: number } | null;
+}
+
+export function createDiscoveryState(
+  entryPath: string | undefined,
+  opts: PluginOptions | undefined,
+): DiscoveryState {
+  return {
+    resolvedEntryPath: entryPath,
+    projectRoot: "",
+    isBuildMode: false,
+    userResolveAlias: undefined,
+    userRunnerConfig: undefined,
+    userResolvePlugins: [],
+    scanFilter: undefined,
+    cachedRouterFiles: undefined,
+    opts,
+
+    mergedRouteManifest: null,
+    perRouterManifests: [],
+    mergedPrecomputedEntries: null,
+    mergedRouteTrie: null,
+
+    perRouterTrieMap: new Map(),
+    perRouterPrecomputedMap: new Map(),
+    perRouterManifestDataMap: new Map(),
+
+    prerenderManifestEntries: null,
+    staticManifestEntries: null,
+    handlerChunkInfoMap: new Map(),
+    staticHandlerChunkInfoMap: new Map(),
+    rscEntryFileName: null,
+    resolvedPrerenderModules: undefined,
+    resolvedStaticModules: undefined,
+
+    discoveryDone: null,
+    devServerOrigin: null,
+    devServer: null,
+    selfWrittenGenFiles: new Map(),
+    SELF_WRITE_WINDOW_MS: 5_000,
+    lastDiscoveryError: null,
+  };
+}

package/src/vite/discovery/virtual-module-codegen.ts

@@ -0,0 +1,183 @@
+/**
+ * Virtual Module Code Generation
+ *
+ * Generates the code for virtual:rsc-router/routes-manifest and
+ * per-router virtual modules used by the load() hook.
+ */
+
+import { dirname, basename, join } from "node:path";
+import { jsonParseExpression } from "../utils/manifest-utils.js";
+import { VIRTUAL_ROUTES_MANIFEST_ID } from "./state.js";
+import type { DiscoveryState } from "./state.js";
+
+/**
+ * Generate the code for the main virtual:rsc-router/routes-manifest module.
+ */
+export function generateRoutesManifestModule(state: DiscoveryState): string {
+  const hasManifest =
+    state.mergedRouteManifest &&
+    Object.keys(state.mergedRouteManifest).length > 0;
+
+  if (hasManifest) {
+    // Build gen file import statements for each router with a sourceFile.
+    // This creates a dependency in Vite's module graph: when the gen file
+    // changes (e.g. after HMR route edits), Vite invalidates this virtual
+    // module and re-evaluates it on the next request, calling
+    // setCachedManifest() with fresh data. No manual sync needed.
+    const genFileImports: string[] = [];
+    const genFileVars: string[] = [];
+    const routersWithoutGenFile: Array<{
+      id: string;
+      manifest: Record<string, string>;
+    }> = [];
+    let varIdx = 0;
+
+    for (const entry of state.perRouterManifests) {
+      if (entry.sourceFile) {
+        const routerDir = dirname(entry.sourceFile);
+        const routerBasename = basename(entry.sourceFile).replace(
+          /\.(tsx?|jsx?)$/,
+          "",
+        );
+        const genPath = join(
+          routerDir,
+          `${routerBasename}.named-routes.gen.js`,
+        ).replaceAll("\\", "/");
+        const varName = `_r${varIdx++}`;
+        genFileImports.push(
+          `import { NamedRoutes as ${varName} } from ${JSON.stringify(genPath)};`,
+        );
+        genFileVars.push(varName);
+      } else {
+        routersWithoutGenFile.push({
+          id: entry.id,
+          manifest: entry.routeManifest,
+        });
+      }
+    }
+
+    const lines = [
+      `import { setCachedManifest, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+      ...genFileImports,
+      // Clear stale per-router cached data (manifest, trie, precomputed entries)
+      // before re-populating. In Cloudflare dev mode, program reloads re-evaluate
+      // this virtual module but the route-map-builder singleton retains old data
+      // because it's not in the HMR invalidation chain. Without this clear, the
+      // handler finds stale trie data and never rebuilds from updated urlpatterns.
+      `clearAllRouterData();`,
+    ];
+
+    if (genFileVars.length > 0) {
+      lines.push(
+        `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`,
+      );
+    }
+
+    if (genFileVars.length === 1 && routersWithoutGenFile.length === 0) {
+      lines.push(`setCachedManifest(__flat(${genFileVars[0]}));`);
+    } else {
+      const parts: string[] = [];
+      for (const v of genFileVars) parts.push(`...__flat(${v})`);
+      for (const { manifest } of routersWithoutGenFile)
+        parts.push(`...${jsonParseExpression(manifest)}`);
+      lines.push(`setCachedManifest({ ${parts.join(", ")} });`);
+    }
+
+    let genVarIdx = 0;
+    for (const entry of state.perRouterManifests) {
+      if (entry.sourceFile) {
+        const varName = genFileVars[genVarIdx++];
+        lines.push(
+          `setRouterManifest(${JSON.stringify(entry.id)}, __flat(${varName}));`,
+        );
+      } else {
+        lines.push(
+          `setRouterManifest(${JSON.stringify(entry.id)}, ${jsonParseExpression(entry.routeManifest)});`,
+        );
+      }
+    }
+
+    // Per-router trie and precomputedEntries are NOT inlined eagerly.
+    // They live in the per-router lazy chunks (generatePerRouterModule) and
+    // are loaded via ensureRouterManifest(routerId), which is awaited before
+    // every request in router.fetch() and before findMatch is reached.
+    // Inlining the merged versions here would duplicate the per-router data
+    // (the merged trie/precomputedEntries equal the per-router data for
+    // single-router apps; for multi-router, the merged trie is dead code
+    // because find-match.ts only consumes per-router tries).
+    //
+    // In dev mode, the handler also falls back to Phase 2 regex matching
+    // against live router.urlpatterns, which is always correct after a
+    // program reload.
+
+    for (const routerId of state.perRouterManifestDataMap.keys()) {
+      lines.push(
+        `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`,
+      );
+    }
+    if (!state.isBuildMode && state.devServerOrigin) {
+      lines.push(
+        `globalThis.__PRERENDER_DEV_URL = ${JSON.stringify(state.devServerOrigin)};`,
+      );
+    }
+    return lines.join("\n");
+  }
+
+  if (!state.isBuildMode) {
+    const origin =
+      state.devServerOrigin ||
+      state.devServer?.resolvedUrls?.local?.[0]?.replace(/\/$/, "") ||
+      (state.devServer &&
+        `http://localhost:${state.devServer.config.server.port || 5173}`);
+    if (origin) {
+      state.devServerOrigin = origin;
+      return `globalThis.__PRERENDER_DEV_URL = ${JSON.stringify(origin)};`;
+    }
+  }
+  return `// Route manifest will be populated at runtime`;
+}
+
+/**
+ * Generate the code for a per-router virtual module.
+ */
+export function generatePerRouterModule(
+  state: DiscoveryState,
+  routerId: string,
+): string {
+  // Find the per-router entry to get the gen file path
+  const routerEntry = state.perRouterManifests.find((e) => e.id === routerId);
+  const trie = state.perRouterTrieMap.get(routerId);
+  const entries = state.perRouterPrecomputedMap.get(routerId);
+  const lines: string[] = [];
+
+  if (routerEntry?.sourceFile) {
+    const routerDir = dirname(routerEntry.sourceFile);
+    const routerBasename = basename(routerEntry.sourceFile).replace(
+      /\.(tsx?|jsx?)$/,
+      "",
+    );
+    const genPath = join(
+      routerDir,
+      `${routerBasename}.named-routes.gen.js`,
+    ).replaceAll("\\", "/");
+    lines.push(`import { NamedRoutes as _r } from ${JSON.stringify(genPath)};`);
+    lines.push(
+      `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`,
+    );
+    lines.push(`export const manifest = __flat(_r);`);
+  } else {
+    const manifest = state.perRouterManifestDataMap.get(routerId);
+    if (manifest) {
+      lines.push(`export const manifest = ${jsonParseExpression(manifest)};`);
+    }
+  }
+  if (trie) {
+    lines.push(`export const trie = ${jsonParseExpression(trie)};`);
+  }
+  if (entries && entries.length > 0) {
+    lines.push(
+      `export const precomputedEntries = ${jsonParseExpression(entries)};`,
+    );
+  }
+  return lines.join("\n") || "";
+}