@rangojs/router 0.0.0-experimental.97 → 0.0.0-experimental.98914650

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,
@@ -275,10 +232,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 +243,6 @@ export function findStatementEnd(code: string, pos: number): number {
   return i;
 }
 
-/**
- * Escape special regex characters in a string so it can be safely
- * interpolated into a RegExp pattern.
- */
 export function escapeRegExp(input: string): string {
   return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

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

@@ -6,14 +6,9 @@ import {
   buildExportMap,
   escapeRegExp,
 } from "../expose-id-utils.js";
+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[],
@@ -27,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;
@@ -38,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]
@@ -59,19 +50,45 @@ 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",
+  );
+}
+
 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;
+}
+
+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 };
+}
+
+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 +136,18 @@ export function getCalledIdentifierFromCall(callExpr: any): string | null {
   return null;
 }
 
+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 +225,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 +241,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 +258,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 +276,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,
       });
     }
@@ -268,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);
   }
@@ -282,9 +309,23 @@ 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}".`];
+
+  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 +333,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 }
@@ -73,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[],
@@ -88,62 +80,13 @@ 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}" };`;
   });
 
   return { code: stubs.join("\n") + "\n", map: null };
 }
 
-/**
- * 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.
- */
 export function stubHandlerExprs(
   cfg: HandlerTransformConfig,
   bindings: CreateExportBinding[],
@@ -154,9 +97,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,
@@ -168,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[],
@@ -182,14 +120,8 @@ 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"
-    //   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

@@ -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";
 
@@ -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,
@@ -33,7 +21,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,13 +42,8 @@ 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")
-    // 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,