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

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

@@ -2,25 +2,65 @@ import type { Plugin } from "vite";
 import MagicString from "magic-string";
 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 {
+  normalizePath,
+  findMatchingParen,
+  findCallParenAfterGenerics,
+  skipStringOrComment,
+} from "../expose-id-utils.js";
+import { escapeRegExp } from "../../../regex-escape.js";
+import {
+  getImportedFnNames,
+  buildUnsupportedShapeWarning,
+} from "./export-analysis.js";
+import { codeMatchIndices } from "../../../build/route-types/source-scan.js";
 import { createRangoDebugger, createCounter, NS } from "../../debug.js";
 
 const debug = createRangoDebugger(NS.transform);
 
+/**
+ * Advance past leading whitespace and a single leading line/block comment so a
+ * `createRouter(/* opts *\/ { ... })` call still resolves to its `{`. Only the
+ * first comment-or-whitespace run is skipped (enough for the common prefix
+ * case); a non-trivia token after it stops the scan.
+ */
+function skipLeadingTrivia(code: string, start: number, end: number): number {
+  let i = start;
+  while (i < end) {
+    const skipped = skipStringOrComment(code, i);
+    // skipStringOrComment only advances for strings/comments, not whitespace.
+    if (skipped > i) {
+      i = skipped;
+      continue;
+    }
+    if (/\s/.test(code[i])) {
+      i++;
+      continue;
+    }
+    break;
+  }
+  return i;
+}
+
 export function transformRouter(
   code: string,
   filePath: string,
   routerFnNames: string[],
   absolutePath?: string,
+  warn?: (message: string) => void,
 ): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  // Match only the callee identifier; the generic list (which may be nested,
+  // e.g. createRouter<Config<Env>>(...)) and the opening paren are located
+  // separately via findCallParenAfterGenerics so a nested `>` does not defeat
+  // the scan (a `<[^>]*>` regex stopped at the first `>`).
   const pat = new RegExp(
-    `\\b(?:${routerFnNames.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\s*(?:<[^>]*>)?\\s*\\(`,
+    `\\b(?:${routerFnNames.map(escapeRegExp).join("|")})\\b`,
     "g",
   );
   let match: RegExpExecArray | null;
   const s = new MagicString(code);
   let changed = false;
+  const unsupportedSites: Array<{ line: number; column: number }> = [];
 
   // Compute the import path for the generated route names file.
   // filePath is relative to project root (e.g., "src/router.tsx")
@@ -28,45 +68,76 @@ export function transformRouter(
   const routeNamesImport = `./${basename}.named-routes.gen.js`;
   const routeNamesVar = `__rsc_rn`;
 
+  // Only inject at call sites in REAL code, not inside comments or string
+  // literals — e.g. a `createRouter({ ... })` snippet in a JSDoc example must
+  // not get a `$$id`/`.named-routes.gen` import injected. The sibling analysis
+  // path (export-analysis.ts) already uses this same comment/string-aware scan;
+  // the raw `pat.exec(code)` loop below would otherwise match in comments too.
+  const codeOffsets = new Set(codeMatchIndices(code, pat));
+  pat.lastIndex = 0;
+
   while ((match = pat.exec(code)) !== null) {
+    if (!codeOffsets.has(match.index)) continue;
     const callStart = match.index;
-    const parenPos = match.index + match[0].length - 1;
+    const calleeEnd = match.index + match[0].length;
+
+    // Resolve the call's opening paren, skipping an optional (possibly nested)
+    // generic argument list. A non-call reference (e.g. a bare identifier or a
+    // type position) yields -1 and is skipped.
+    const parenPos = findCallParenAfterGenerics(code, calleeEnd);
+    if (parenPos === -1) continue;
 
-    // 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;
+    // Skip ONLY a call we already injected into. The injected marker is the
+    // unique `$$routeNames: <var>` property; a bare `$$id` substring check
+    // would also match a user value/comment that merely contains the text
+    // "$$id" (e.g. `createRouter({ meta: { note: "see $$id docs" } })`),
+    // silently dropping named-route wiring for a legitimate config.
+    if (callArgs.includes(`$$routeNames: ${routeNamesVar}`)) continue;
 
-    // Compute line number for this call
+    const sourceFilePath = absolutePath ?? filePath;
     const lineNumber = code.slice(0, callStart).split("\n").length;
     const hash = createHash("sha256")
       .update(`${filePath}:${lineNumber}`)
       .digest("hex")
       .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},`;
 
-    const afterParen = callArgs.trimStart();
-    if (afterParen.startsWith("{")) {
-      const bracePos = code.indexOf("{", parenPos + 1);
-      s.appendRight(bracePos + 1, injected);
-    } else if (afterParen.startsWith(")")) {
+    // Skip a leading comment/whitespace run so `createRouter(/* c *\/ {...})`
+    // and a newline-then-comment prefix still resolve to the object literal.
+    // findMatchingParen returns one past the close `)`, so the matching paren
+    // sits at closeParen - 1 and empty args resolve to that `)`.
+    const argsContentStart = skipLeadingTrivia(code, parenPos + 1, closeParen);
+    const firstArgChar = code[argsContentStart];
+
+    if (firstArgChar === "{") {
+      changed = true;
+      s.appendRight(argsContentStart + 1, injected);
+    } else if (argsContentStart >= closeParen - 1) {
+      // Empty args: createRouter(). Wrap a fresh config object.
+      changed = true;
       s.appendRight(parenPos + 1, `{${injected} }`);
+    } else {
+      // Unsupported argument shape (bare identifier, spread, call, etc.). No
+      // stable $$id can be injected here. Record it so the plugin can warn —
+      // and crucially do NOT mark changed, so a dead named-routes.gen import is
+      // not prepended for a call we never touched.
+      const lastNl = code.lastIndexOf("\n", callStart - 1);
+      const column = callStart - (lastNl + 1) + 1;
+      unsupportedSites.push({ line: lineNumber, column });
     }
   }
 
+  if (unsupportedSites.length > 0 && warn) {
+    warn(
+      buildUnsupportedShapeWarning(filePath, "createRouter", unsupportedSites),
+    );
+  }
+
   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 +167,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,
@@ -113,11 +180,16 @@ export function exposeRouterId(): Plugin {
       try {
         const filePath = normalizePath(path.relative(projectRoot, id));
         const routerFnNames = getImportedFnNames(code, "createRouter");
+        const warn =
+          typeof this.warn === "function"
+            ? (message: string) => this.warn(message)
+            : undefined;
         return transformRouter(
           code,
           filePath,
           routerFnNames,
           normalizePath(id),
+          warn,
         );
       } finally {
         counter?.record(id, performance.now() - start);

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"]);
@@ -752,7 +762,6 @@ ${lazyImports.join(",\n")}
             transformHandles(
               getBindings(code, fnNames),
               s,
-              code,
               filePath,
               isBuild,
             ) || changed;

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)) {