@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.126

package/src/vite/plugins/expose-ids/loader-transform.ts

@@ -9,18 +9,6 @@ export function hasCreateLoaderImport(code: string): boolean {
   );
 }
 
-/**
- * Generate lightweight client stubs for loader files.
- *
- * When a loader file is imported from a client component (e.g., for useLoader()),
- * the client only needs { __brand: "loader", $$id: "..." } objects.
- * This function replaces the entire file contents with just those stub exports,
- * preventing server-only data (constants, DB queries, etc.) from leaking into
- * the client bundle.
- *
- * Only applies when ALL named exports are createLoader() calls (plus type exports
- * which are erased at compile time). Files with mixed exports are left untouched.
- */
 export function generateClientLoaderStubs(
   bindings: CreateExportBinding[],
   code: string,
@@ -56,9 +44,6 @@ export function transformLoaders(
 
     const loaderId = makeStubId(filePath, exportName, isBuild);
 
-    // Inject $$id as hidden third parameter.
-    // createLoader(fn) -> createLoader(fn, undefined, "id")
-    // createLoader(fn, true) -> createLoader(fn, true, "id")
     const paramInjection =
       binding.argCount === 1 ? `, undefined, "${loaderId}"` : `, "${loaderId}"`;
     s.appendLeft(binding.callCloseParenPos, paramInjection);

package/src/vite/plugins/expose-ids/router-transform.ts

@@ -32,15 +32,11 @@ export function transformRouter(
     const callStart = match.index;
     const parenPos = match.index + match[0].length - 1;
 
-    // Scope the $$id check to within this call's arguments only,
-    // not the entire remaining file.
     const closeParen = findMatchingParen(code, parenPos + 1);
     const callArgs = code.slice(parenPos + 1, closeParen);
 
-    // Skip if $$id is already present in this call
     if (callArgs.includes("$$id")) continue;
 
-    // Compute line number for this call
     const lineNumber = code.slice(0, callStart).split("\n").length;
     const hash = createHash("sha256")
       .update(`${filePath}:${lineNumber}`)
@@ -48,9 +44,6 @@ export function transformRouter(
       .slice(0, 8);
 
     changed = true;
-    // $$sourceFile uses the absolute path so that downstream consumers
-    // (virtual-module-codegen, runtime-discovery) can resolve gen file
-    // imports correctly via path.dirname / path.join.
     const sourceFilePath = absolutePath ?? filePath;
     const injected = ` $$id: "${hash}", $$sourceFile: "${sourceFilePath}", $$routeNames: ${routeNamesVar},`;
 
@@ -65,8 +58,6 @@ export function transformRouter(
 
   if (!changed) return null;
 
-  // Prepend the static import as the first line. MagicString tracks the
-  // offset so all downstream source maps remain correct.
   s.prepend(
     `import { NamedRoutes as ${routeNamesVar} } from "${routeNamesImport}";\n`,
   );
@@ -96,10 +87,6 @@ export function exposeRouterId(): Plugin {
     },
     transform(code, id) {
       if (!code.includes("createRouter")) return null;
-      // Accepts both @rangojs/router and @rangojs/router/server subpath.
-      // NOTE: detectImports in expose-id-utils has a stricter check that
-      // excludes /server for its router flag -- that's intentional since
-      // detectImports is only used in exposeInternalIds, not here.
       if (
         !/import\s*\{[^}]*\bcreateRouter\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(
           code,

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

@@ -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"]);

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

@@ -54,9 +54,6 @@ export function performanceTracksOptimizeDepsPlugin(): {
     /react-server-dom-webpack-client\.browser\.(development|production)\.js$/;
   return {
     name: "@rangojs/router:performance-tracks-optimize-deps",
-    // Vite 8 optimizes deps with Rolldown (Rollup-style plugin pipeline), so the
-    // pre-bundled RSDW client is patched via load() rather than esbuild's onLoad.
-    // Returning code overrides Rolldown's default filesystem read for the module.
     async load(id: string): Promise<{ code: string } | null> {
       const cleanId = id.split("?")[0] ?? id;
       if (!RSDW_CLIENT_RE.test(cleanId)) return null;

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

@@ -30,11 +30,6 @@ 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?)$/;
 
-/**
- * Grammar for a valid function-level directive: `use cache` optionally followed
- * by `: <profile-name>`. The single source of truth for both the transform and
- * the near-miss validator below.
- */
 export const USE_CACHE_DIRECTIVE_RE: RegExp = /^use cache(:\s*[\w-]+)?$/;
 
 export function useCacheTransform(): Plugin {
@@ -72,7 +67,6 @@ export function useCacheTransform(): Plugin {
 
       const start = counter ? performance.now() : 0;
       try {
-        // Lazy-load transform helpers
         if (!rscTransforms) {
           try {
             rscTransforms = await import("@vitejs/plugin-rsc/transforms");
@@ -87,7 +81,6 @@ export function useCacheTransform(): Plugin {
           transformHoistInlineDirective,
         } = rscTransforms;
 
-        // Parse AST
         let ast: any;
         try {
           const { parseAst } = await import("vite");
@@ -99,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,
@@ -112,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,
@@ -123,9 +113,6 @@ export function useCacheTransform(): Plugin {
           transformHoistInlineDirective,
         );
 
-        // Check for near-miss directives on the function-level path. The
-        // file-level branch above returns earlier (it wraps every export
-        // regardless), so this runs only when there is no file-level directive.
         warnOnNearMissDirectives(ast, id, this.warn.bind(this));
 
         if (functionResult) return functionResult;
@@ -145,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) => {
@@ -155,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) {
@@ -195,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(
@@ -244,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`,
     );
@@ -261,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 {
@@ -280,18 +266,8 @@ function findFileLevelDirective(
   return null;
 }
 
-/**
- * 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,
@@ -319,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

@@ -29,7 +29,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);
 
@@ -37,25 +36,10 @@ export function createVersionInjectorPlugin(
         return null;
       }
 
-      // Always prepend `import "virtual:rsc-router/routes-manifest"` as the
-      // first side-effect import. The manifest virtual module's `load()` hook
-      // awaits `s.discoveryDone` so that, by the time the rest of the entry
-      // including any module-level `router.reverse()` calls under `./router.js`
-      // evaluates, runtime discovery has rewritten `router.named-routes.gen.ts`
-      // with the full route table.
-      //
-      // ES module evaluation order matters here: while imports are *parsed*
-      // hoisted, side-effect imports are evaluated in source order in the
-      // dependency graph. A user-authored `import "virtual:rsc-router/..."`
-      // placed after `import "./router.js"` runs too late: the manifest
-      // gate fires after router.tsx has already crashed on a stale gen file.
-      // We always prepend; ESM dedups any user-written duplicate, so module
-      // initialization still runs once.
       const prepend: string[] = [
         `import "virtual:rsc-router/routes-manifest";`,
       ];
 
-      // Auto-inject VERSION if file uses createRSCHandler without version
       let newCode = code;
       const needsVersion =
         code.includes("createRSCHandler") &&
@@ -70,10 +54,6 @@ export function createVersionInjectorPlugin(
         );
       }
 
-      // Insert after any leading `/// <reference ... />` triple-slash
-      // directives (and surrounding blank lines). TypeScript requires those
-      // directives to precede all other code; putting our imports above
-      // them silently demotes the directives to plain comments.
       const lines = newCode.split("\n");
       let insertAt = 0;
       while (insertAt < lines.length) {

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

@@ -138,8 +138,6 @@ export function createVersionPlugin(): Plugin {
 
   let versionCounter = 0;
   const bumpVersion = (reason: string) => {
-    // Use timestamp + counter to guarantee uniqueness even when multiple
-    // bumps happen within the same millisecond (e.g. cascading HMR events).
     currentVersion = Date.now().toString(16) + String(++versionCounter);
     console.log(`[rango] ${reason}, version updated: ${currentVersion}`);
 
@@ -158,9 +156,6 @@ export function createVersionPlugin(): Plugin {
 
     configResolved(config) {
       isDev = config.command === "serve";
-      // Capture the resolved cacheDir so we can ignore optimizer-output
-      // writes inside it. Vite resolves cacheDir against the project root,
-      // so this is a stable absolute path for the lifetime of the server.
       resolvedCacheDir = config.cacheDir
         ? String(config.cacheDir).replace(/\\/g, "/")
         : undefined;
@@ -210,27 +205,15 @@ export function createVersionPlugin(): Plugin {
       return null;
     },
 
-    // Track RSC module changes and update version
     async hotUpdate(ctx) {
       if (!isDev) return;
 
-      // Check if this is an RSC environment update (not client/ssr)
-      // RSC modules affect server-rendered content and cached payloads
-      // In Vite 6, environment is accessed via `this.environment`
       const isRscModule = this.environment?.name === "rsc";
 
       if (!isRscModule) return;
 
-      // Skip Vite's own pre-bundled dep cache writes. The optimizer rewrites
-      // files inside the configured `cacheDir` on every discovery cycle
-      // (and when other dev servers under the same cwd populate their own
-      // isolated cache dirs). These are not user-source changes, so bumping
-      // the app version on them produces spurious version mismatches that
-      // surface as forced reloads on in-flight actions.
       if (isViteDepCachePath(ctx.file, resolvedCacheDir)) return;
 
-      // Skip re-bumping when the version virtual module itself is invalidated
-      // (our own bumpVersion() invalidates it, which re-triggers hotUpdate).
       if (
         ctx.modules.length === 1 &&
         ctx.modules[0].id === "\0" + VIRTUAL_IDS.version
@@ -245,9 +228,6 @@ export function createVersionPlugin(): Plugin {
           const source = await ctx.read();
           const nextSignature = getClientModuleSignature(source);
           if (nextSignature) {
-            // "use client" file — compare export signatures.
-            // client-component-hmr may have cleared ctx.modules, so we
-            // cannot rely on ctx.modules.length for these files.
             clientModuleSignatures.set(filePath, nextSignature);
             if (
               previousSignature &&
@@ -258,20 +238,11 @@ export function createVersionPlugin(): Plugin {
           } else {
             clientModuleSignatures.delete(filePath);
             if (!previousSignature) {
-              // Not and never was "use client" — use module graph check.
-              // ctx.modules is reliable for pure server files (only
-              // client-component-hmr clears it for "use client" modules).
               if (ctx.modules.length === 0) return;
             }
-            // Was "use client" but directive removed — boundary changed,
-            // bump below.
           }
-        } catch {
-          // Fail open: if we can't read or parse the update, invalidate.
-        }
+        } catch {}
       } else {
-        // Non-code file (json, css, etc.) — only bump if it's actually
-        // referenced by the RSC module graph.
         if (ctx.modules.length === 0) return;
       }
 
@@ -280,20 +251,6 @@ export function createVersionPlugin(): Plugin {
   };
 }
 
-/**
- * Match Vite's pre-bundled dep cache directories. These paths are rewritten
- * by the dep optimizer (and by isolated test fixtures sharing the same cwd),
- * not by user source changes, so they should not bump the app version (which
- * would force a client reload mid-request).
- *
- * Two checks:
- * 1. Anything inside the resolved `cacheDir` (precise — covers custom paths
- *    like the `RANGO_E2E_VITE_CACHE_DIR` overrides in the test fixtures).
- * 2. Heuristic match for any `node_modules/.vite*` directory or a
- *    `.vite-isolated/` segment anywhere in the path. This catches the
- *    *other* dev servers in the same cwd whose cacheDir we cannot read
- *    (we only see config of the server we're attached to).
- */
 export function isViteDepCachePath(
   filePath: string | undefined,
   cacheDir?: string,
@@ -311,11 +268,6 @@ export function isViteDepCachePath(
     }
   }
 
-  // Vite/optimizer convention: cache dirs always sit directly under
-  // `node_modules/` and start with `.vite` (e.g. `.vite`, `.vite-temp`,
-  // `.vite_rango_generate`, `.vite-e2e-test-app`). The `/.vite-isolated/`
-  // segment covers the test-fixture pattern that places the cache outside
-  // node_modules.
   return (
     /\/node_modules\/\.vite[^/]*\//.test(normalized) ||
     normalized.includes("/.vite-isolated/")

package/src/vite/plugins/virtual-entries.ts

@@ -1,8 +1,3 @@
-/**
- * Default virtual entry file contents for rsc-router.
- * These are used when users don't provide their own entry files.
- */
-
 export const VIRTUAL_ENTRY_BROWSER: string = `
 import {
   createFromReadableStream,
@@ -51,9 +46,6 @@ export const renderHTML = createSSRHandler({
 });
 `.trim();
 
-/**
- * Generate the RSC entry content with the specified router path
- */
 export function getVirtualEntryRSC(routerPath: string): string {
   return `
 import {
@@ -104,9 +96,6 @@ export default function handler(request, env) {
 `.trim();
 }
 
-/**
- * Virtual module IDs
- */
 export const VIRTUAL_IDS = {
   browser: "virtual:rsc-router/entry.browser.js",
   ssr: "virtual:rsc-router/entry.ssr.js",
@@ -114,10 +103,6 @@ export const VIRTUAL_IDS = {
   version: "@rangojs/router:version",
 } as const;
 
-/**
- * Virtual module content for version.
- * Exports VERSION - a timestamp that changes on server restart (dev) or at build time (production).
- */
 export function getVirtualVersionContent(version: string): string {
   return `export const VERSION = ${JSON.stringify(version)};`;
 }