@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/vite/plugins/expose-ids/export-analysis.ts

@@ -9,12 +9,6 @@ import {
 import { codeMatchIndices } from "../../../build/route-types/source-scan.js";
 import type { CreateExportBinding } from "./types.js";
 
-/**
- * Check whether every non-type export in `code` is accounted for by the given
- * bindings. Returns false if any export exists that is not one of the known
- * create* call locals/exports, allowing callers to bail out for mixed-export
- * files.
- */
 export function isExportOnlyFile(
   code: string,
   bindings: CreateExportBinding[],
@@ -28,10 +22,8 @@ export function isExportOnlyFile(
     for (const e of b.exportNames) knownExports.add(e);
   }
 
-  // Bail on star re-exports (unknown exports)
   if (/export\s*\*/.test(code)) return false;
 
-  // Check `export const/let/var/function/class/default X` declarations
   const declExportPattern =
     /export\s+(const|let|var|function|class|default)\s+(\w+)/g;
   let match: RegExpExecArray | null;
@@ -39,8 +31,6 @@ export function isExportOnlyFile(
     if (!knownExports.has(match[2])) return false;
   }
 
-  // Check `export { X }` and `export { X as Y }` specifiers: the local name
-  // must reference a known create* binding.
   const specExportPattern = /export\s*\{([^}]+)\}/g;
   while ((match = specExportPattern.exec(code)) !== null) {
     const specifiers = match[1]
@@ -67,9 +57,6 @@ function createCallPattern(fnNames: string[]): RegExp {
   );
 }
 
-// Counts real create*() call sites, ignoring occurrences inside comments and
-// string literals. Used by the unsupported-shape warning heuristic and the
-// inline-extraction pre-check.
 export function countCreateCallsForNames(
   code: string,
   fnNames: string[],
@@ -77,7 +64,6 @@ export function countCreateCallsForNames(
   return codeMatchIndices(code, createCallPattern(fnNames)).length;
 }
 
-/** Convert a 0-based byte offset to a 1-based { line, column }. */
 export function offsetToLineColumn(
   code: string,
   index: number,
@@ -94,14 +80,6 @@ export function offsetToLineColumn(
   return { line, column: index - lineStart + 1 };
 }
 
-/**
- * Locate every real create*() call site (comment/string-free) that is NOT one
- * of the supported, id-injectable export bindings, returning each as a 1-based
- * { line, column }. The empty result means every call is in a supported shape.
- * Both binding-collection paths anchor `callExprStart` at the start of the
- * create* identifier — exactly where this pattern matches — so the set
- * difference is exact.
- */
 export function findUnsupportedCreateCallSites(
   code: string,
   fnNames: string[],
@@ -158,16 +136,6 @@ export function getCalledIdentifierFromCall(callExpr: any): string | null {
   return null;
 }
 
-/**
- * plugin-react's dev Fast Refresh wraps exports whose function body uses
- * hook-like calls in a signature-registration call. A loader/handle that calls
- * `ctx.use(...)` trips this heuristic, so `export const X = createLoader(...)`
- * becomes `export const X = _s(createLoader(...), "<sig>", true)` — the create*
- * call is the first argument of an unrelated wrapper call. Unwrap a single such
- * layer so ID injection still targets the inner create* call. The `$$id`
- * assignment is appended after the whole statement (against the export local),
- * which is unaffected by the wrapper since `_s(x)` returns `x`.
- */
 function unwrapSignatureWrappedCall(init: any, fnNameSet: Set<string>): any {
   if (init?.type !== "CallExpression") return init;
   const directId = getCalledIdentifierFromCall(init);
@@ -331,10 +299,6 @@ export function collectCreateExportBindings(
     }
   }
 
-  // When the JS parser misidentifies TypeScript generics (e.g.,
-  // createLocationState<{ text: string }>({...})) as binary expressions,
-  // the AST path finds 0 bindings even though calls exist. Fall back to
-  // regex-based detection which handles generics via <[^>]*> matching.
   if (bindings.length === 0) {
     return collectCreateExportBindingsFallback(code, fnNames);
   }
@@ -349,8 +313,6 @@ export function buildUnsupportedShapeWarning(
 ): string {
   const lines = [`[rango] Unsupported ${fnName} shape in "${filePath}".`];
 
-  // Point at the exact call(s) so the location is clickable in the terminal/IDE
-  // (file:line:column) instead of leaving the user to scan the whole file.
   if (sites.length === 1) {
     const s = sites[0];
     lines.push(

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

@@ -69,10 +69,6 @@ export function transformLocationState(
   return hasChanges;
 }
 
-/**
- * Replace the entire file with lightweight stubs when ALL non-type exports are
- * handler calls of the given type. Returns null for files with mixed exports.
- */
 export function generateWholeFileStubs(
   cfg: HandlerTransformConfig,
   bindings: CreateExportBinding[],
@@ -91,10 +87,6 @@ export function generateWholeFileStubs(
   return { code: stubs.join("\n") + "\n", map: null };
 }
 
-/**
- * Replace handler call expressions with lightweight stub objects on the shared
- * unified-pipeline MagicString so all transforms share one sourcemap.
- */
 export function stubHandlerExprs(
   cfg: HandlerTransformConfig,
   bindings: CreateExportBinding[],
@@ -117,9 +109,6 @@ export function stubHandlerExprs(
   return hasChanges;
 }
 
-/**
- * Inject $$id into export const handler calls in RSC environments.
- */
 export function transformHandlerIds(
   cfg: HandlerTransformConfig,
   bindings: CreateExportBinding[],
@@ -133,10 +122,6 @@ export function transformHandlerIds(
 
     const handlerId = makeStubId(filePath, exportName, isBuild);
 
-    // Injection strategy matches the runtime overload signatures:
-    //   0 args                              -> inject undefined, "id"
-    //   1 arg  (handler)                    -> inject , undefined, "id"
-    //   2+ args                             -> inject , "id"
     let paramInjection: string;
     if (binding.argCount === 0) {
       paramInjection = `undefined, "${handlerId}"`;

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/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,7 +132,6 @@ function transformFileLevelUseCache(
   isLayoutOrTemplate: boolean,
   transformWrapExport: (typeof import("@vitejs/plugin-rsc/transforms"))["transformWrapExport"],
 ) {
-  // Collect non-function exports to report after wrapping
   const nonFunctionExports: string[] = [];
 
   const { exportNames, output } = transformWrapExport(code, ast, {
@@ -155,9 +141,7 @@ 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);
         return false;
@@ -178,7 +162,6 @@ function transformFileLevelUseCache(
   }
 
   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 +178,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 +225,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 +239,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 +255,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 +284,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)};`;
 }