@rangojs/router 0.0.0-experimental.dfa55db4 → 0.0.0-experimental.e16b7c00

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

@@ -3,6 +3,9 @@ import MagicString from "magic-string";
 import path from "node:path";
 import fs from "node:fs";
 import { normalizePath } from "./expose-id-utils.js";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
 
 /**
  * Type for the RSC plugin's manager API
@@ -39,7 +42,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.`,
       );
     }
@@ -254,6 +257,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 +273,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 +287,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 +334,54 @@ 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 {
+        // Dev mode: no hash-to-file mapping needed (IDs are already file paths)
+        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 {
+        // 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,
+              }),
+            };
+          }
+          return null;
         }
-        return null;
-      }
 
-      // Non-RSC environments: only transform createServerReference calls
-      return transformServerReferences(code, chunk.fileName, effectiveMap);
+        // Non-RSC environments: only transform createServerReference calls
+        return transformServerReferences(code, chunk.fileName, effectiveMap);
+      } finally {
+        counterRender?.record(chunk.fileName, performance.now() - start);
+      }
     },
   };
 }

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

@@ -20,18 +20,34 @@ export function hashId(filePath: string, exportName: string): string {
 }
 
 /**
- * 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).
+ * 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,
+  isBuild: boolean,
+): string {
+  return isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
+}
+
+/**
+ * Generate an 8-char hex hash for an inline handler call site.
+ *
+ * Keyed on the source-order INDEX of the call (the Nth inline `fnName(...)` in
+ * the file), NOT its line number. Line numbers shift between the prerender
+ * build context and the production build context (preceding transforms differ,
+ * e.g. plugin-react boilerplate), which would desync the prerender manifest key
+ * from the runtime handler id and break prerender/static freezing. The
+ * source-order index is invariant to line shifts; `fnName` keeps Static and
+ * Prerender inline ids from colliding at the same index.
  */
 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);
 }
 

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

@@ -6,6 +6,7 @@ import {
   buildExportMap,
   escapeRegExp,
 } from "../expose-id-utils.js";
+import { codeMatchIndices } from "../../../build/route-types/source-scan.js";
 import type { CreateExportBinding } from "./types.js";
 
 /**
@@ -59,19 +60,57 @@ export function isExportOnlyFile(
   return true;
 }
 
-// NOTE: This regex may over-count when the fn name appears inside strings or
-// comments, but it's only used for the warning heuristic (totalCalls >
-// supportedBindings) and the inline-extraction pre-check, so over-counting
-// triggers a harmless extra AST parse rather than affecting correctness.
+function createCallPattern(fnNames: string[]): RegExp {
+  return new RegExp(
+    `\\b(?:${fnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`,
+    "g",
+  );
+}
+
+// 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[],
 ): number {
-  const pattern = new RegExp(
-    `\\b(?:${fnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`,
-    "g",
-  );
-  return (code.match(pattern) || []).length;
+  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,
+): { line: number; column: number } {
+  let line = 1;
+  let lineStart = 0;
+  const end = Math.min(index, code.length);
+  for (let i = 0; i < end; i++) {
+    if (code[i] === "\n") {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  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[],
+  supportedBindings: CreateExportBinding[],
+): Array<{ line: number; column: number }> {
+  const supported = new Set(supportedBindings.map((b) => b.callExprStart));
+  return codeMatchIndices(code, createCallPattern(fnNames))
+    .filter((index) => !supported.has(index))
+    .map((index) => offsetToLineColumn(code, index));
 }
 
 export function getImportedFnNames(
@@ -119,6 +158,28 @@ 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);
+  if (directId && fnNameSet.has(directId)) return init;
+  const firstArg = init.arguments?.[0];
+  if (firstArg?.type === "CallExpression") {
+    const innerId = getCalledIdentifierFromCall(firstArg);
+    if (innerId && fnNameSet.has(innerId)) return firstArg;
+  }
+  return init;
+}
+
 export function collectCreateExportBindingsFallback(
   code: string,
   fnNames: string[],
@@ -196,7 +257,7 @@ export function collectCreateExportBindings(
 ): CreateExportBinding[] {
   if (!program) {
     try {
-      program = parseAst(code, { jsx: true });
+      program = parseAst(code, { lang: "tsx" });
     } catch {
       return collectCreateExportBindingsFallback(code, fnNames);
     }
@@ -212,10 +273,13 @@ export function collectCreateExportBindings(
     }
 
     for (const decl of varDecl.declarations ?? []) {
-      const calledIdentifier = getCalledIdentifierFromCall(decl?.init);
+      // Unwrap a Fast Refresh signature wrapper (`_s(createLoader(...), ...)`)
+      // so injection targets the inner create* call. Falls back to decl.init.
+      const callExpr = unwrapSignatureWrappedCall(decl?.init, fnNameSet);
+      const calledIdentifier = getCalledIdentifierFromCall(callExpr);
       if (
         decl?.id?.type !== "Identifier" ||
-        decl?.init?.type !== "CallExpression" ||
+        callExpr?.type !== "CallExpression" ||
         !calledIdentifier ||
         !fnNameSet.has(calledIdentifier)
       ) {
@@ -226,9 +290,8 @@ export function collectCreateExportBindings(
       const exportNames = exportMap.get(localName) ?? [];
       if (exportNames.length === 0) continue;
 
-      const callStart = decl.init.start as number;
-      const callEnd = decl.init.end as number;
-      const calleeEnd = decl.init.callee.end as number;
+      const callEnd = callExpr.end as number;
+      const calleeEnd = callExpr.callee.end as number;
 
       let openParenPos = -1;
       for (let i = calleeEnd; i < callEnd; i++) {
@@ -245,10 +308,10 @@ export function collectCreateExportBindings(
       bindings.push({
         localName,
         exportNames,
-        callExprStart: decl.init.start as number,
+        callExprStart: callExpr.start as number,
         callOpenParenPos: openParenPos,
         callCloseParenPos: closeParenPos,
-        argCount: decl.init.arguments?.length ?? 0,
+        argCount: callExpr.arguments?.length ?? 0,
         statementEnd,
       });
     }
@@ -282,9 +345,25 @@ export function collectCreateExportBindings(
 export function buildUnsupportedShapeWarning(
   filePath: string,
   fnName: string,
+  sites: Array<{ line: number; column: number }> = [],
 ): string {
-  return [
-    `[rsc-router] Unsupported ${fnName} shape in "${filePath}".`,
+  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(
+      `The ${fnName}(...) call at ${filePath}:${s.line}:${s.column} has no stable $$id injected — it is not in a supported shape.`,
+    );
+  } else if (sites.length > 1) {
+    lines.push(
+      `These ${fnName}(...) calls have no stable $$id injected — they are not in a supported shape:`,
+    );
+    for (const s of sites) lines.push(`  - ${filePath}:${s.line}:${s.column}`);
+  }
+
+  lines.push(
     `Supported shapes are:`,
     `  - export const X = ${fnName}(...)`,
     `  - const X = ${fnName}(...); export { X }`,
@@ -292,5 +371,6 @@ export function buildUnsupportedShapeWarning(
     `Potentially unsupported forms include:`,
     `  - export let/var X = ${fnName}(...)`,
     `  - inline ${fnName}(...) calls`,
-  ].join("\n");
+  );
+  return lines.join("\n");
 }

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

@@ -1,5 +1,5 @@
 import MagicString from "magic-string";
-import { hashId } from "../expose-id-utils.js";
+import { makeStubId } from "../expose-id-utils.js";
 import type { HandlerTransformConfig, CreateExportBinding } from "./types.js";
 import { isExportOnlyFile } from "./export-analysis.js";
 
@@ -28,9 +28,7 @@ export function transformHandles(
       binding.callCloseParenPos,
     );
 
-    const handleId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const handleId = makeStubId(filePath, exportName, isBuild);
 
     let paramInjection: string;
     if (!args.hasArgs) {
@@ -58,9 +56,7 @@ export function transformLocationState(
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
 
-    const stateKey = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const stateKey = makeStubId(filePath, exportName, isBuild);
 
     // Key is injected as a property assignment (not as a function argument).
     // This allows createLocationState to accept options like { flash: true }
@@ -88,7 +84,7 @@ export function generateWholeFileStubs(
 
   const exportNames = bindings.flatMap((b) => b.exportNames);
   const stubs = exportNames.map((name) => {
-    const handlerId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+    const handlerId = makeStubId(filePath, name, isBuild);
     return `export const ${name} = { __brand: "${cfg.brand}", $$id: "${handlerId}" };`;
   });
 
@@ -96,53 +92,8 @@ export function generateWholeFileStubs(
 }
 
 /**
- * Replace handler call expressions with lightweight stub objects in non-RSC
- * environments. Other exports, imports, and module-level code remain untouched.
- */
-export function generateExprStubs(
-  cfg: HandlerTransformConfig,
-  bindings: CreateExportBinding[],
-  code: string,
-  filePath: string,
-  sourceId: string,
-  isBuild: boolean,
-): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
-  if (bindings.length === 0) return null;
-
-  const s = new MagicString(code);
-  let hasChanges = false;
-
-  for (const binding of bindings) {
-    const exportName = binding.exportNames[0];
-    const handlerId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
-
-    s.overwrite(
-      binding.callExprStart,
-      binding.callCloseParenPos + 1,
-      `{ __brand: "${cfg.brand}", $$id: "${handlerId}" }`,
-    );
-    hasChanges = true;
-  }
-
-  if (!hasChanges) return null;
-
-  return {
-    code: s.toString(),
-    map: s.generateMap({
-      source: sourceId,
-      includeContent: true,
-      hires: "boundary",
-    }),
-  };
-}
-
-/**
- * Replace handler call expressions with lightweight stub objects on an
- * existing MagicString. Unlike generateExprStubs (which creates its own
- * MagicString and returns the full result), this integrates into the
- * unified transform pipeline so all transforms share one sourcemap.
+ * 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,
@@ -154,9 +105,7 @@ export function stubHandlerExprs(
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
-    const handlerId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const handlerId = makeStubId(filePath, exportName, isBuild);
 
     s.overwrite(
       binding.callExprStart,
@@ -182,9 +131,7 @@ export function transformHandlerIds(
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
 
-    const handlerId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const handlerId = makeStubId(filePath, exportName, isBuild);
 
     // Injection strategy matches the runtime overload signatures:
     //   0 args                              -> inject undefined, "id"

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

@@ -1,5 +1,5 @@
 import type MagicString from "magic-string";
-import { hashId } from "../expose-id-utils.js";
+import { makeStubId } from "../expose-id-utils.js";
 import type { CreateExportBinding } from "./types.js";
 import { isExportOnlyFile } from "./export-analysis.js";
 
@@ -33,7 +33,7 @@ export function generateClientLoaderStubs(
 
   for (const binding of bindings) {
     for (const name of binding.exportNames) {
-      const loaderId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+      const loaderId = makeStubId(filePath, name, isBuild);
       lines.push(
         `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`,
       );
@@ -54,9 +54,7 @@ export function transformLoaders(
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
 
-    const loaderId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const loaderId = makeStubId(filePath, exportName, isBuild);
 
     // Inject $$id as hidden third parameter.
     // createLoader(fn) -> createLoader(fn, undefined, "id")

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

@@ -4,6 +4,9 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import { normalizePath, findMatchingParen } from "../expose-id-utils.js";
 import { getImportedFnNames } from "./export-analysis.js";
+import { createRangoDebugger, createCounter, NS } from "../../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
 
 export function transformRouter(
   code: string,
@@ -82,11 +85,15 @@ export function transformRouter(
  */
 export function exposeRouterId(): Plugin {
   let projectRoot = "";
+  const counter = createCounter(debug, "expose-router-id");
   return {
     name: "@rangojs/router:expose-router-id",
     configResolved(config) {
       projectRoot = config.root;
     },
+    buildEnd() {
+      counter?.flush();
+    },
     transform(code, id) {
       if (!code.includes("createRouter")) return null;
       // Accepts both @rangojs/router and @rangojs/router/server subpath.
@@ -102,9 +109,19 @@ export function exposeRouterId(): Plugin {
       }
       if (id.includes("node_modules")) return null;
 
-      const filePath = normalizePath(path.relative(projectRoot, id));
-      const routerFnNames = getImportedFnNames(code, "createRouter");
-      return transformRouter(code, filePath, routerFnNames, normalizePath(id));
+      const start = counter ? performance.now() : 0;
+      try {
+        const filePath = normalizePath(path.relative(projectRoot, id));
+        const routerFnNames = getImportedFnNames(code, "createRouter");
+        return transformRouter(
+          code,
+          filePath,
+          routerFnNames,
+          normalizePath(id),
+        );
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
     },
   };
 }