@rangojs/router 0.0.0-experimental.9eb4192e → 0.0.0-experimental.a014d2b7

package/src/vite/plugins/expose-internal-ids.ts

@@ -28,6 +28,7 @@ import {
   getImportedFnNames,
   collectCreateExportBindings,
   buildUnsupportedShapeWarning,
+  findUnsupportedCreateCallSites,
   isExportOnlyFile,
 } from "./expose-ids/export-analysis.js";
 import {
@@ -39,13 +40,12 @@ import {
   transformHandles,
   transformLocationState,
   generateWholeFileStubs,
-  generateExprStubs,
   stubHandlerExprs,
   transformHandlerIds,
 } from "./expose-ids/handler-transform.js";
-import { createRangoDebugger, createCounter } from "../debug.js";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
 
-const debug = createRangoDebugger("rango:transform");
+const debug = createRangoDebugger(NS.transform);
 
 // Re-exports consumed by other packages/plugins
 export { exposeRouterId } from "./expose-ids/router-transform.js";
@@ -184,6 +184,16 @@ ${lazyImports.join(",\n")}
     async buildStart() {
       if (!isBuild) return;
 
+      // The loader pre-scan walks and reads the entire project, but the
+      // loaderRegistry it populates is consumed only by the RSC loader-manifest
+      // virtual module (and the transform hook already gates its registry writes
+      // with isRscEnv). plugin-rsc runs ~5 build passes (rsc-scan, ssr-scan, rsc,
+      // client, ssr) over this single shared plugin instance; without this gate
+      // the full-tree I/O ran on every pass with no consumer on the non-RSC
+      // ones. Skip only when the environment is known and not RSC, so an
+      // unavailable environment still falls through (no empty registry).
+      if (this.environment && this.environment.name !== "rsc") return;
+
       const fs = await import("node:fs/promises");
 
       const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
@@ -335,7 +345,7 @@ ${lazyImports.join(",\n")}
           }
           if (_cachedAst !== undefined || _astParseFailed) return _cachedAst;
           try {
-            _cachedAst = parseAst(code, { jsx: true });
+            _cachedAst = parseAst(code, { lang: "tsx" });
           } catch {
             _astParseFailed = true;
           }
@@ -371,14 +381,21 @@ ${lazyImports.join(",\n")}
           if (!hasCode) continue;
 
           const fnNames = getFnNames(cfg.fnName);
-          const totalCalls = countCreateCallsForNames(code, fnNames);
-          const supportedBindings = getBindings(code, fnNames).length;
-          if (totalCalls <= supportedBindings) continue;
+          // Locate the real (comment/string-free) create* calls not covered by
+          // a supported, id-injectable export shape. Empty means every call is
+          // fine — in particular, a create*() token in a comment or string no
+          // longer trips a spurious warning.
+          const sites = findUnsupportedCreateCallSites(
+            code,
+            fnNames,
+            getBindings(code, fnNames),
+          );
+          if (sites.length === 0) continue;
 
           const warnKey = `${id}::${cfg.fnName}`;
           if (unsupportedShapeWarnings.has(warnKey)) continue;
           unsupportedShapeWarnings.add(warnKey);
-          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName));
+          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName, sites));
         }
 
         // --- Loader: track for manifest (RSC env only) ---
@@ -424,17 +441,6 @@ ${lazyImports.join(",\n")}
           if (wholeFile) return wholeFile;
         }
 
-        // --- PrerenderHandler: RSC build module tracking ---
-        if (hasPrerenderHandlerCode && isRscEnv && isBuild) {
-          const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-          const exportNames = getBindings(code, fnNames).map(
-            (b) => b.exportNames[0],
-          );
-          if (exportNames.length > 0) {
-            prerenderHandlerModules.set(id, exportNames);
-          }
-        }
-
         // --- Inline handler extraction to virtual modules ---
         // Runs before stubs/tracking so inline calls become imports, then
         // the existing regex fast path handles both the original file's
@@ -710,14 +716,27 @@ ${lazyImports.join(",\n")}
           }
         }
 
-        // --- StaticHandler: RSC build module tracking ---
-        if (hasStaticHandlerCode && isRscEnv && isBuild) {
-          const fnNames = getFnNames(STATIC_CONFIG.fnName);
-          const exportNames = getBindings(code, fnNames).map(
-            (b) => b.exportNames[0],
-          );
-          if (exportNames.length > 0) {
-            staticHandlerModules.set(id, exportNames);
+        // RSC build module tracking (prerender + static), consumed via the
+        // plugin API for prerender freezing. Export-binding sets are invariant
+        // across the inline-extraction loop, so tracking both here is equivalent
+        // to the pre-extraction prerender tracking this replaces.
+        if (isRscEnv && isBuild) {
+          const trackTypes: Array<
+            [boolean, HandlerTransformConfig, Map<string, string[]>]
+          > = [
+            [
+              hasPrerenderHandlerCode,
+              PRERENDER_CONFIG,
+              prerenderHandlerModules,
+            ],
+            [hasStaticHandlerCode, STATIC_CONFIG, staticHandlerModules],
+          ];
+          for (const [has, cfg, trackMap] of trackTypes) {
+            if (!has) continue;
+            const exportNames = getBindings(code, getFnNames(cfg.fnName)).map(
+              (b) => b.exportNames[0],
+            );
+            if (exportNames.length > 0) trackMap.set(id, exportNames);
           }
         }
 
@@ -743,7 +762,6 @@ ${lazyImports.join(",\n")}
             transformHandles(
               getBindings(code, fnNames),
               s,
-              code,
               filePath,
               isBuild,
             ) || changed;
@@ -758,48 +776,19 @@ ${lazyImports.join(",\n")}
               isBuild,
             ) || changed;
         }
-        if (hasPrerenderHandlerCode) {
-          const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-          const bindings = getBindings(code, fnNames);
-          if (isRscEnv) {
-            changed =
-              transformHandlerIds(
-                PRERENDER_CONFIG,
-                bindings,
-                s,
-                filePath,
-                isBuild,
-              ) || changed;
-          } else {
-            // Non-RSC mixed-export file: replace Prerender() calls with stubs
-            // on the shared MagicString so sourcemaps stay accurate.
-            changed =
-              stubHandlerExprs(
-                PRERENDER_CONFIG,
-                bindings,
-                s,
-                filePath,
-                isBuild,
-              ) || changed;
-          }
-        }
-        if (hasStaticHandlerCode) {
-          const fnNames = getFnNames(STATIC_CONFIG.fnName);
-          const bindings = getBindings(code, fnNames);
-          if (isRscEnv) {
-            changed =
-              transformHandlerIds(
-                STATIC_CONFIG,
-                bindings,
-                s,
-                filePath,
-                isBuild,
-              ) || changed;
-          } else {
-            changed =
-              stubHandlerExprs(STATIC_CONFIG, bindings, s, filePath, isBuild) ||
-              changed;
-          }
+        // Prerender + Static share the RSC inject-id vs non-RSC stub dispatch.
+        // Call sites are disjoint (distinct fnNames), so loop order is irrelevant.
+        const finalHandlerConfigs = [
+          hasPrerenderHandlerCode && PRERENDER_CONFIG,
+          hasStaticHandlerCode && STATIC_CONFIG,
+        ].filter((c): c is HandlerTransformConfig => !!c);
+        for (const cfg of finalHandlerConfigs) {
+          const bindings = getBindings(code, getFnNames(cfg.fnName));
+          changed =
+            (isRscEnv
+              ? transformHandlerIds(cfg, bindings, s, filePath, isBuild)
+              : stubHandlerExprs(cfg, bindings, s, filePath, isBuild)) ||
+            changed;
         }
 
         if (!changed) return;

package/src/vite/plugins/performance-tracks.ts

@@ -14,9 +14,9 @@
 
 import type { Plugin } from "vite";
 import { readFile } from "node:fs/promises";
-import { createRangoDebugger, createCounter } from "../debug.js";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
 
-const debug = createRangoDebugger("rango:transform");
+const debug = createRangoDebugger(NS.transform);
 
 const RSDW_PATCH_RE =
   /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
@@ -48,25 +48,18 @@ export function patchRsdwClientDebugInfoRecovery(code: string): {
 
 export function performanceTracksOptimizeDepsPlugin(): {
   name: string;
-  setup(build: any): void;
+  load(id: string): Promise<{ code: string } | null>;
 } {
+  const RSDW_CLIENT_RE =
+    /react-server-dom-webpack-client\.browser\.(development|production)\.js$/;
   return {
     name: "@rangojs/router:performance-tracks-optimize-deps",
-    setup(build: any): void {
-      build.onLoad(
-        {
-          filter:
-            /react-server-dom-webpack-client\.browser\.(development|production)\.js$/,
-        },
-        async (args: { path: string }) => {
-          const code = await readFile(args.path, "utf8");
-          const patched = patchRsdwClientDebugInfoRecovery(code);
-          return {
-            contents: patched.code,
-            loader: "js",
-          };
-        },
-      );
+    async load(id: string): Promise<{ code: string } | null> {
+      const cleanId = id.split("?")[0] ?? id;
+      if (!RSDW_CLIENT_RE.test(cleanId)) return null;
+      const code = await readFile(cleanId, "utf8");
+      const patched = patchRsdwClientDebugInfoRecovery(code);
+      return { code: patched.code };
     },
   };
 }

package/src/vite/plugins/refresh-cmd.ts

@@ -20,7 +20,7 @@ import type { Plugin } from "vite";
  */
 export function poke(): Plugin {
   return {
-    name: "vite-plugin-poke",
+    name: "@rangojs/router:poke",
     apply: "serve",
 
     configureServer(server) {

package/src/vite/plugins/use-cache-transform.ts

@@ -20,9 +20,9 @@ import type { Plugin } from "vite";
 import path from "node:path";
 import MagicString from "magic-string";
 import { normalizePath, hashId } from "./expose-id-utils.js";
-import { createRangoDebugger, createCounter } from "../debug.js";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
 
-const debug = createRangoDebugger("rango:transform");
+const debug = createRangoDebugger(NS.transform);
 
 const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 
@@ -30,6 +30,8 @@ const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 // and should not be wrapped (children can't be cache-keyed).
 const LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
 
+export const USE_CACHE_DIRECTIVE_RE: RegExp = /^use cache(:\s*[\w-]+)?$/;
+
 export function useCacheTransform(): Plugin {
   let projectRoot = "";
   let isBuild = false;
@@ -63,10 +65,8 @@ export function useCacheTransform(): Plugin {
       // Only JS/TS files
       if (!/\.(tsx?|jsx?|mjs)$/.test(id)) return;
 
-      // Past cheap bails — measure from here (real AST work below)
       const start = counter ? performance.now() : 0;
       try {
-        // Lazy-load transform helpers
         if (!rscTransforms) {
           try {
             rscTransforms = await import("@vitejs/plugin-rsc/transforms");
@@ -81,11 +81,10 @@ export function useCacheTransform(): Plugin {
           transformHoistInlineDirective,
         } = rscTransforms;
 
-        // Parse AST
         let ast: any;
         try {
           const { parseAst } = await import("vite");
-          ast = parseAst(code);
+          ast = parseAst(code, { lang: "tsx" });
         } catch {
           return;
         }
@@ -93,7 +92,6 @@ export function useCacheTransform(): Plugin {
         const filePath = normalizePath(path.relative(projectRoot, id));
         const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
 
-        // Check for file-level "use cache"
         if (hasDirective(ast.body, "use cache")) {
           return transformFileLevelUseCache(
             code,
@@ -106,8 +104,6 @@ export function useCacheTransform(): Plugin {
           );
         }
 
-        // Check for function-level "use cache" / "use cache: profileName"
-        // (only if there's no file-level directive but code still contains the string)
         const functionResult = transformFunctionLevelUseCache(
           code,
           ast,
@@ -117,9 +113,6 @@ export function useCacheTransform(): Plugin {
           transformHoistInlineDirective,
         );
 
-        // Always check for near-miss directives, even when valid directives
-        // exist. A file may contain both valid and invalid "use cache" directives
-        // in different functions — the invalid ones should still warn.
         warnOnNearMissDirectives(ast, id, this.warn.bind(this));
 
         if (functionResult) return functionResult;
@@ -139,8 +132,7 @@ function transformFileLevelUseCache(
   isLayoutOrTemplate: boolean,
   transformWrapExport: (typeof import("@vitejs/plugin-rsc/transforms"))["transformWrapExport"],
 ) {
-  // Collect non-function exports to report after wrapping
-  const nonFunctionExports: string[] = [];
+  const unconfirmedExports: string[] = [];
 
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value: string, name: string) => {
@@ -149,30 +141,38 @@ function transformFileLevelUseCache(
     },
     rejectNonAsyncFunction: false,
     filter: (name: string, meta: { isFunction?: boolean }) => {
-      // Skip default export of layout/template files (they receive children)
       if (name === "default" && isLayoutOrTemplate) return false;
-      // Non-function exports cannot be wrapped with registerCachedFunction
-      if (meta.isFunction === false) {
-        nonFunctionExports.push(name);
+      // isFunction is boolean | undefined: true = confirmed function, false =
+      // confirmed non-function, undefined = cannot tell statically (e.g. a
+      // factory/HOF initializer `const x = makeCached(fn)`). Deliberate policy:
+      // require a confirmed function and reject everything else, including
+      // indeterminate initializers that may be functions at runtime -- rewrite
+      // those as direct async functions. (Pre-#1246 plugin-rsc reported false,
+      // not undefined, here, so === false would wrongly wrap them post-bump.)
+      if (meta.isFunction !== true) {
+        unconfirmedExports.push(name);
         return false;
       }
       return true;
     },
   });
 
-  if (nonFunctionExports.length > 0) {
+  if (unconfirmedExports.length > 0) {
+    const plural = unconfirmedExports.length > 1;
     throw new Error(
-      `[rango:use-cache] File-level "use cache" in ${sourceId} cannot wrap ` +
-        `non-function export${nonFunctionExports.length > 1 ? "s" : ""}: ` +
-        `${nonFunctionExports.map((n) => `"${n}"`).join(", ")}. ` +
-        `Only function exports can be cached. Either remove "use cache" from ` +
-        `the file level and add it inside individual functions, or move the ` +
-        `non-function exports to a separate module.`,
+      `[rango:use-cache] File-level "use cache" in ${sourceId} only wraps ` +
+        `exports that are statically-confirmed functions. ` +
+        `${plural ? "These exports are" : "This export is"} not: ` +
+        `${unconfirmedExports.map((n) => `"${n}"`).join(", ")}. ` +
+        `Declare them directly (export async function foo() {} or ` +
+        `export const foo = async () => {}). A factory or otherwise ` +
+        `statically-indeterminate initializer (export const foo = makeCached(fn)) ` +
+        `is rejected even if it returns a function at runtime -- rewrite it as a ` +
+        `direct async function, or move non-function exports to a separate module.`,
     );
   }
 
   if (exportNames.length === 0) {
-    // Even if no exports were wrapped, strip the directive
     const s = new MagicString(code);
     const directive = findFileLevelDirective(ast);
     if (directive) {
@@ -189,12 +189,10 @@ function transformFileLevelUseCache(
     return;
   }
 
-  // Prepend the import
   output.prepend(
     `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};\n`,
   );
 
-  // Replace the directive with a comment
   const directive = findFileLevelDirective(ast);
   if (directive) {
     output.overwrite(
@@ -220,7 +218,7 @@ function transformFunctionLevelUseCache(
 ) {
   try {
     const { output, names } = transformHoistInlineDirective(code, ast, {
-      directive: /^use cache(:\s*[\w-]+)?$/,
+      directive: USE_CACHE_DIRECTIVE_RE,
       runtime: (
         value: string,
         name: string,
@@ -238,9 +236,6 @@ function transformFunctionLevelUseCache(
 
     if (names.length === 0) return;
 
-    // Use a top-level import instead of await import() — the hoisted wrapper
-    // may be placed in a non-async context (e.g., inside a synchronous
-    // urls() callback) where await is not allowed.
     output.prepend(
       `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};\n`,
     );
@@ -255,9 +250,6 @@ function transformFunctionLevelUseCache(
   }
 }
 
-/**
- * Find the file-level "use cache" directive AST node for removal.
- */
 function findFileLevelDirective(
   ast: any,
 ): { start: number; end: number } | null {
@@ -274,23 +266,8 @@ function findFileLevelDirective(
   return null;
 }
 
-/**
- * The valid directive regex (must stay in sync with transformFunctionLevelUseCache).
- */
-const VALID_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
-
-/**
- * Regex for near-miss: starts with "use cache:" but has invalid tokens.
- */
 const NEAR_MISS_RE = /^use cache:\s*.+$/;
 
-/**
- * Walk the AST looking for string literals that look like malformed
- * "use cache" directives and emit a Vite warning for each.
- *
- * This catches cases like `"use cache: bad.name"` or `"use cache: "`
- * that the transform regex silently ignores.
- */
 function warnOnNearMissDirectives(
   ast: any,
   fileId: string,
@@ -308,7 +285,7 @@ function warnOnNearMissDirectives(
       if (
         value.startsWith("use cache") &&
         NEAR_MISS_RE.test(value) &&
-        !VALID_DIRECTIVE_RE.test(value)
+        !USE_CACHE_DIRECTIVE_RE.test(value)
       ) {
         const profilePart = value.slice("use cache:".length).trim();
         warn(
@@ -318,7 +295,6 @@ function warnOnNearMissDirectives(
       }
     }
 
-    // Walk into function bodies where directives appear
     for (const key of Object.keys(node)) {
       const child = node[key];
       if (Array.isArray(child)) {

package/src/vite/plugins/version-injector.ts

@@ -1,12 +1,26 @@
 import type { Plugin } from "vite";
 import { resolve } from "node:path";
 import * as Vite from "vite";
+import { resolveRscEntryFromConfig } from "../utils/shared-utils.js";
+import { RSC_ENTRY_BOOTSTRAP_IMPORTS } from "./virtual-entries.js";
 
 /**
- * Plugin that auto-injects VERSION and routes-manifest into custom entry.rsc files.
- * If a custom entry.rsc file uses createRSCHandler but doesn't pass version,
- * this transform adds the import and property automatically.
- * Also ensures the routes-manifest virtual module is always imported.
+ * Plugin that auto-injects VERSION, routes-manifest, and loader-manifest into
+ * custom entry.rsc files. If a custom entry.rsc file uses createRSCHandler but
+ * doesn't pass version, this transform adds the import and property
+ * automatically. It also ensures the routes-manifest and loader-manifest
+ * virtual modules are always imported.
+ *
+ * The loader-manifest import is what makes fetchable loaders resolvable on a
+ * custom worker entry. The virtual RSC entry (getVirtualEntryRSC) imports the
+ * loader manifest itself, but a hand-written entry (e.g. a Cloudflare
+ * worker.rsc.tsx) does not — so without this injection, setLoaderImports() is
+ * never bundled, lazyLoaderImports stays null at runtime, and a fetchable
+ * loader that is never imported by the server graph (not registered via
+ * loader(), reachable only through a client component) cannot be found by the
+ * _rsc_loader endpoint in production. Dev still works because it resolves
+ * loaders by parsing their id into a file path; only production relied on the
+ * manifest, hence the production-only failure this fixes.
  * @internal
  */
 export function createVersionInjectorPlugin(
@@ -20,18 +34,7 @@ export function createVersionInjectorPlugin(
 
     configResolved(config) {
       let entryPath = rscEntryPath;
-      // Cloudflare preset: read entry from resolved environment config.
-      // The @cloudflare/vite-plugin reads wrangler config (toml/json/jsonc)
-      // and sets optimizeDeps.entries on the RSC environment.
-      if (!entryPath) {
-        const rscEnvConfig = (config.environments as any)?.["rsc"];
-        const entries = rscEnvConfig?.optimizeDeps?.entries;
-        if (typeof entries === "string") {
-          entryPath = entries;
-        } else if (Array.isArray(entries) && entries.length > 0) {
-          entryPath = entries[0];
-        }
-      }
+      if (!entryPath) entryPath = resolveRscEntryFromConfig(config);
       if (entryPath) {
         resolvedEntryPath = resolve(config.root, entryPath);
       }
@@ -39,7 +42,6 @@ export function createVersionInjectorPlugin(
 
     transform(code, id) {
       if (!resolvedEntryPath) return null;
-      // Only transform the RSC entry file
       const normalizedId = Vite.normalizePath(id);
       const normalizedEntry = Vite.normalizePath(resolvedEntryPath);
 
@@ -47,16 +49,13 @@ export function createVersionInjectorPlugin(
         return null;
       }
 
-      // Prepend imports at the top of the file. ES imports are hoisted
-      // by the module system, so source position is irrelevant.
-      const prepend: string[] = [];
-      let newCode = code;
-
-      if (!code.includes("virtual:rsc-router/routes-manifest")) {
-        prepend.push(`import "virtual:rsc-router/routes-manifest";`);
-      }
+      // Same startup bootstrap imports the generated virtual RSC entry uses,
+      // from the single shared list so the two paths cannot drift.
+      const prepend: string[] = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+        (id) => `import "${id}";`,
+      );
 
-      // Auto-inject VERSION if file uses createRSCHandler without version
+      let newCode = code;
       const needsVersion =
         code.includes("createRSCHandler") &&
         !code.includes("@rangojs/router:version") &&
@@ -70,9 +69,21 @@ export function createVersionInjectorPlugin(
         );
       }
 
-      if (prepend.length === 0 && newCode === code) return null;
-
-      newCode = prepend.join("\n") + (prepend.length > 0 ? "\n" : "") + newCode;
+      const lines = newCode.split("\n");
+      let insertAt = 0;
+      while (insertAt < lines.length) {
+        const trimmed = lines[insertAt]!.trim();
+        if (trimmed === "" || /^\/\/\/\s*<reference\b/.test(trimmed)) {
+          insertAt++;
+        } else {
+          break;
+        }
+      }
+      newCode = [
+        ...lines.slice(0, insertAt),
+        ...prepend,
+        ...lines.slice(insertAt),
+      ].join("\n");
 
       return {
         code: newCode,