@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/vite/plugins/expose-action-id.ts

@@ -3,10 +3,11 @@ import MagicString from "magic-string";
 import path from "node:path";
 import fs from "node:fs";
 import { normalizePath } from "./expose-id-utils.js";
+import { registerServerReferenceRegex } from "./server-reference-pattern.js";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
 
-/**
- * Type for the RSC plugin's manager API
- */
 interface RscPluginManager {
   serverReferenceMetaMap: Record<
     string,
@@ -23,14 +24,9 @@ interface RscPluginApi {
   manager: RscPluginManager;
 }
 
-/**
- * Get the RSC plugin's API from Vite config
- */
 function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
-  // Try by name first
   let plugin = config.plugins.find((p) => p.name === "rsc:minimal");
 
-  // Fallback: find by API structure if name lookup fails
   if (!plugin) {
     plugin = config.plugins.find(
       (p) =>
@@ -39,7 +35,7 @@ function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
     );
     if (plugin) {
       console.warn(
-        `[rsc-router:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
+        `[rango:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
           `Consider updating the name lookup if the plugin was renamed.`,
       );
     }
@@ -59,13 +55,11 @@ function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
 function isUseServerModule(filePath: string): boolean {
   try {
     const content = fs.readFileSync(filePath, "utf-8");
-    // Remove leading comments and whitespace to find the first meaningful content
     const trimmed = content
-      .replace(/^\s*\/\/[^\n]*\n/gm, "") // Remove single-line comments
-      .replace(/^\s*\/\*[\s\S]*?\*\/\s*/gm, "") // Remove multi-line comments
+      .replace(/^\s*\/\/[^\n]*\n/gm, "")
+      .replace(/^\s*\/\*[\s\S]*?\*\/\s*/gm, "")
       .trimStart();
 
-    // Check if the file starts with "use server" directive
     return (
       trimmed.startsWith('"use server"') || trimmed.startsWith("'use server'")
     );
@@ -74,18 +68,6 @@ function isUseServerModule(filePath: string): boolean {
   }
 }
 
-/**
- * Transform code to expose action IDs on createServerReference calls.
- * Wraps each call with an IIFE that attaches $id to the returned function.
- *
- * @param code - The source code to transform
- * @param sourceId - The source file identifier (for sourcemap)
- * @param hashToFileMap - Optional mapping from hash to file path (for server bundles)
- */
-/**
- * Apply createServerReference wrapping to a MagicString instance.
- * Returns true if any changes were made.
- */
 function applyServerReferenceWrapping(
   code: string,
   s: MagicString,
@@ -95,11 +77,6 @@ function applyServerReferenceWrapping(
     return false;
   }
 
-  // Match: createServerReference("hash#actionName", ...) or $$ReactClient.createServerReference(...)
-  // The RSC plugin uses $$ReactClient namespace in transformed code.
-  // Note: [^)]* cannot handle nested parens in trailing args. This is safe in practice
-  // because the RSC plugin always generates simple variable references (e.g., callServer)
-  // as the second argument, never nested function calls.
   const pattern =
     /((?:\$\$\w+\.)?createServerReference)\(("[^"]+#[^"]+")([^)]*)\)/g;
 
@@ -112,23 +89,19 @@ function applyServerReferenceWrapping(
     const start = match.index;
     const end = start + fullMatch.length;
 
-    // Parse the ID to potentially replace hash with file path
     let finalIdArg = idArg;
     if (hashToFileMap) {
-      // idArg is like '"hash#actionName"', extract the parts
       const idValue = idArg.slice(1, -1); // Remove quotes
       const hashMatch = idValue.match(/^([^#]+)#(.+)$/);
       if (hashMatch) {
         const [, hash, actionName] = hashMatch;
         const filePath = hashToFileMap.get(hash);
         if (filePath) {
-          // Replace hash with file path for server-side
           finalIdArg = `"${filePath}#${actionName}"`;
         }
       }
     }
 
-    // Wrap the createServerReference call to attach $$id to the returned function
     const replacement = `(function(fn) { fn.$$id = ${finalIdArg}; return fn; })(${fnCall}(${idArg}${rest}))`;
     s.overwrite(start, end, replacement);
   }
@@ -152,29 +125,6 @@ function transformServerReferences(
   };
 }
 
-/**
- * Transform registerServerReference calls in server bundles to use file paths instead of hashes.
- * Pattern: registerServerReference(fn, "hash", "exportName")
- * React's registerServerReference sets $$id = hash + "#" + exportName
- * By replacing the hash with file path, $$id will contain the file path for revalidation matching.
- *
- * Only actions from module-level "use server" files are transformed.
- * Inline actions (defined in RSC components with "use server" inside a function) are NOT in
- * hashToFileMap and keep their hashed IDs. This is intentional for client security:
- * - Module-level "use server" files: shared action modules, file path helps revalidation
- * - Inline actions: one-off actions in RSC, hash ID prevents file path exposure to client
- *
- * @param code - The source code to transform
- * @param sourceId - The source file identifier (for sourcemap)
- * @param hashToFileMap - Mapping from hash to file path (only module-level "use server" files)
- */
-/**
- * Apply registerServerReference wrapping to a MagicString instance.
- * Returns true if any changes were made.
- *
- * Only actions from module-level "use server" files are transformed.
- * Inline actions keep their hashed IDs for client security.
- */
 function applyRegisterReferenceWrapping(
   code: string,
   s: MagicString,
@@ -184,10 +134,7 @@ function applyRegisterReferenceWrapping(
     return false;
   }
 
-  // Match: registerServerReference(fn, "hash", "exportName")
-  // The hash is the second argument, exportName is the third
-  const pattern =
-    /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+  const pattern = registerServerReferenceRegex();
 
   let hasChanges = false;
   let match: RegExpExecArray | null;
@@ -197,15 +144,9 @@ function applyRegisterReferenceWrapping(
     const start = match.index;
     const end = start + fullMatch.length;
 
-    // Look up the file path for this hash
     const filePath = hashToFileMap.get(hash);
     if (filePath) {
       hasChanges = true;
-      // WRAP the call to add $id property with file path
-      // Keep the original hash for React's action registry (so loadServerAction works)
-      // Add $id (single dollar) with file path for revalidation matching
-      // Note: We use $id instead of $$id because React's registerServerReference
-      // sets $$id as a non-writable property
       const filePathId = `${filePath}#${exportName}`;
       const replacement = `(function(fn) { fn.$id = "${filePathId}"; return fn; })(registerServerReference(${fnArg}, "${hash}", "${exportName}"))`;
       s.overwrite(start, end, replacement);
@@ -254,6 +195,8 @@ export function exposeActionId(): Plugin {
   let isBuild = false;
   let hashToFileMap: Map<string, string> | undefined;
   let rscPluginApi: RscPluginApi | undefined;
+  const counterTransform = createCounter(debug, "expose-action-id transform");
+  const counterRender = createCounter(debug, "expose-action-id renderChunk");
 
   return {
     name: "@rangojs/router:expose-action-id",
@@ -268,6 +211,11 @@ export function exposeActionId(): Plugin {
       rscPluginApi = getRscPluginApi(config);
     },
 
+    buildEnd() {
+      counterTransform?.flush();
+      counterRender?.flush();
+    },
+
     buildStart() {
       // Verify RSC plugin is present at build start (after all config hooks have run)
       // This allows rsc-router:rsc-integration to dynamically add the RSC plugin
@@ -277,7 +225,7 @@ export function exposeActionId(): Plugin {
 
       if (!rscPluginApi) {
         throw new Error(
-          "[rsc-router] Could not find @vitejs/plugin-rsc. " +
+          "[rango] Could not find @vitejs/plugin-rsc. " +
             "@rangojs/router requires the Vite RSC plugin, which is included automatically by rango().",
         );
       }
@@ -324,40 +272,45 @@ export function exposeActionId(): Plugin {
         return;
       }
 
-      // Dev mode: no hash-to-file mapping needed (IDs are already file paths)
-      return transformServerReferences(code, id);
+      const start = counterTransform ? performance.now() : 0;
+      try {
+        return transformServerReferences(code, id);
+      } finally {
+        counterTransform?.record(id, performance.now() - start);
+      }
     },
 
-    // Build mode: renderChunk runs after all transforms and bundling complete
     renderChunk(code, chunk) {
-      // Only RSC bundle should get file paths for revalidation matching
-      // SSR bundle must NOT use file paths because client components run there
-      // and need to match the client bundle during hydration (otherwise: error #418)
-      const isRscEnv = this.environment?.name === "rsc";
-
-      // Only use file path mapping for RSC environment
-      const effectiveMap = isRscEnv ? hashToFileMap : undefined;
-
-      // For RSC bundles, both createServerReference and registerServerReference
-      // may need transforming. Use a single MagicString for correct sourcemaps.
-      if (isRscEnv && hashToFileMap) {
-        const s = new MagicString(code);
-        const changed1 = applyServerReferenceWrapping(code, s, effectiveMap);
-        const changed2 = applyRegisterReferenceWrapping(code, s, hashToFileMap);
-        if (changed1 || changed2) {
-          return {
-            code: s.toString(),
-            map: s.generateMap({
-              source: chunk.fileName,
-              includeContent: true,
-            }),
-          };
+      const start = counterRender ? performance.now() : 0;
+      try {
+        const isRscEnv = this.environment?.name === "rsc";
+
+        const effectiveMap = isRscEnv ? hashToFileMap : undefined;
+
+        if (isRscEnv && hashToFileMap) {
+          const s = new MagicString(code);
+          const changed1 = applyServerReferenceWrapping(code, s, effectiveMap);
+          const changed2 = applyRegisterReferenceWrapping(
+            code,
+            s,
+            hashToFileMap,
+          );
+          if (changed1 || changed2) {
+            return {
+              code: s.toString(),
+              map: s.generateMap({
+                source: chunk.fileName,
+                includeContent: true,
+              }),
+            };
+          }
+          return null;
         }
-        return null;
-      }
 
-      // Non-RSC environments: only transform createServerReference calls
-      return transformServerReferences(code, chunk.fileName, effectiveMap);
+        return transformServerReferences(code, chunk.fileName, effectiveMap);
+      } finally {
+        counterRender?.record(chunk.fileName, performance.now() - start);
+      }
     },
   };
 }

package/src/vite/plugins/expose-id-utils.ts

@@ -8,21 +8,12 @@ export function normalizePath(p: string): string {
   return p.split(path.sep).join("/");
 }
 
-/**
- * Generate a short hash for an ID.
- * Uses first 8 chars of SHA-256 hash for uniqueness while keeping IDs short.
- * Appends export name for easier debugging in production: "abc123#ExportName"
- */
 export function hashId(filePath: string, exportName: string): string {
   const input = `${filePath}#${exportName}`;
   const hash = crypto.createHash("sha256").update(input).digest("hex");
   return `${hash.slice(0, 8)}#${exportName}`;
 }
 
-/**
- * Build a stable ID for an export binding. Uses hashed IDs in production
- * builds (short + opaque) and readable path#name IDs in dev.
- */
 export function makeStubId(
   filePath: string,
   exportName: string,
@@ -31,19 +22,12 @@ export function makeStubId(
   return isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
 }
 
-/**
- * Generate an 8-char hex hash for an inline static handler call site.
- * Uses file path and line number (plus optional index for same-line collisions).
- */
 export function hashInlineId(
   filePath: string,
-  lineNumber: number,
-  index?: number,
+  fnName: string,
+  index: number,
 ): string {
-  const input =
-    index !== undefined && index > 0
-      ? `${filePath}:${lineNumber}:${index}`
-      : `${filePath}:${lineNumber}`;
+  const input = `${filePath}:${fnName}:${index}`;
   return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
 }
 
@@ -57,11 +41,6 @@ export interface DetectedImports {
   any: boolean;
 }
 
-/**
- * Build a map from local binding name to exported names by walking
- * ExportNamedDeclaration nodes. Handles `export const X`, `export { X }`,
- * and `export { X as Y }`. Skips re-exports (`export { X } from "..."`).
- */
 export function buildExportMap(program: any): Map<string, string[]> {
   const exportMap = new Map<string, string[]>();
 
@@ -101,10 +80,6 @@ export function buildExportMap(program: any): Map<string, string[]> {
   return exportMap;
 }
 
-/**
- * Single-pass detection of all create* imports from @rangojs/router.
- * Returns which create functions are imported so we can skip unnecessary transforms.
- */
 export function detectImports(code: string): DetectedImports {
   // Extract all import declarations from @rangojs/router in one scan
   const importPattern =
@@ -131,10 +106,6 @@ export function detectImports(code: string): DetectedImports {
     if (/\bcreateRouter\b/.test(imports)) result.router = true;
   }
 
-  // createRouter has a stricter check: only from "@rangojs/router" (not sub-paths).
-  // NOTE: This is intentional — detectImports is used as a fast pre-filter in
-  // exposeInternalIds (which does NOT handle router transforms). The separate
-  // exposeRouterId plugin handles createRouter and DOES accept the /server subpath.
   if (result.router) {
     result.router =
       /import\s*\{[^}]*\bcreateRouter\b[^}]*\}\s*from\s*["']@rangojs\/router["']/.test(
@@ -153,11 +124,6 @@ export function detectImports(code: string): DetectedImports {
   return result;
 }
 
-/**
- * Skip past a string literal, template literal, or comment starting at pos.
- * Returns the index after the closing delimiter, or pos if not at a
- * string/comment start. Handles escape sequences and nested ${} in templates.
- */
 export function skipStringOrComment(code: string, pos: number): number {
   const ch = code[pos];
 
@@ -215,11 +181,6 @@ export function skipStringOrComment(code: string, pos: number): number {
   return pos;
 }
 
-/**
- * Find the matching closing paren starting after an already-opened paren.
- * Skips strings, template literals, and comments so parens inside them
- * don't affect depth tracking. Returns the index after the closing paren.
- */
 export function findMatchingParen(code: string, startPos: number): number {
   let depth = 1;
   let i = startPos;
@@ -236,10 +197,6 @@ export function findMatchingParen(code: string, startPos: number): number {
   return i;
 }
 
-/**
- * Count the number of top-level arguments in a function call.
- * Skips nested parens, brackets, braces, strings, and comments.
- */
 export function countArgs(
   code: string,
   startPos: number,
@@ -253,7 +210,16 @@ export function countArgs(
   while (i < endPos) {
     const skipped = skipStringOrComment(code, i);
     if (skipped > i) {
-      hasContent = true;
+      // A comment is transparent: `createHandle(/* meta */)` has ZERO real
+      // arguments, so a comment-only region must NOT set hasContent (else the
+      // fallback path would count it as 1 arg and inject `, "id"` over an elided
+      // first slot — a syntax error). A string/template literal IS content.
+      const ch = code[i];
+      const isComment =
+        ch === "/" &&
+        i + 1 < code.length &&
+        (code[i + 1] === "/" || code[i + 1] === "*");
+      if (!isComment) hasContent = true;
       i = skipped;
       continue;
     }
@@ -275,10 +241,6 @@ export function countArgs(
   return hasContent ? argCount + 1 : 0;
 }
 
-/**
- * Find the end of a statement: skip whitespace and optional semicolon after
- * a closing paren position.
- */
 export function findStatementEnd(code: string, pos: number): number {
   let i = pos;
   while (i < code.length && /\s/.test(code[i])) {
@@ -290,10 +252,81 @@ export function findStatementEnd(code: string, pos: number): number {
   return i;
 }
 
+export { escapeRegExp } from "../../regex-escape.js";
+
 /**
- * Escape special regex characters in a string so it can be safely
- * interpolated into a RegExp pattern.
+ * Given an index pointing just past a `create*` callee identifier, return the
+ * index of the call's opening `(`, accounting for an optional generic type
+ * argument list `<...>` with arbitrarily nested `<>`. Returns -1 when the next
+ * non-trivia token is neither `<` nor `(` (i.e. not a call site).
+ *
+ * Replaces the single-level `<[^>]*>` regex assumption, which stopped at the
+ * first `>` and so never reached `(` for `createRouter<Config<Env>>(`.
+ *
+ * Whitespace, comments, and strings between the callee and `(` are skipped via
+ * skipStringOrComment. The `<...>` scan only balances angle brackets; it does
+ * not attempt to parse full TS type syntax (sufficient for locating the paren).
  */
-export function escapeRegExp(input: string): string {
-  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+export function findCallParenAfterGenerics(
+  code: string,
+  afterCalleeIndex: number,
+): number {
+  let i = afterCalleeIndex;
+  // Skip leading whitespace/comments/strings before `<` or `(`.
+  while (i < code.length) {
+    const skipped = skipStringOrComment(code, i);
+    if (skipped > i) {
+      i = skipped;
+      continue;
+    }
+    if (/\s/.test(code[i])) {
+      i++;
+      continue;
+    }
+    break;
+  }
+
+  if (i >= code.length) return -1;
+
+  if (code[i] === "(") return i;
+
+  if (code[i] === "<") {
+    let depth = 0;
+    while (i < code.length) {
+      const skipped = skipStringOrComment(code, i);
+      if (skipped > i) {
+        i = skipped;
+        continue;
+      }
+      const ch = code[i];
+      if (ch === "<") {
+        depth++;
+      } else if (ch === ">") {
+        depth--;
+        if (depth === 0) {
+          i++;
+          break;
+        }
+      }
+      i++;
+    }
+    if (depth !== 0) return -1;
+    // After the balanced generic list, skip trivia and expect `(`.
+    while (i < code.length) {
+      const skipped = skipStringOrComment(code, i);
+      if (skipped > i) {
+        i = skipped;
+        continue;
+      }
+      if (/\s/.test(code[i])) {
+        i++;
+        continue;
+      }
+      break;
+    }
+    if (i < code.length && code[i] === "(") return i;
+    return -1;
+  }
+
+  return -1;
 }