@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d5d3070a

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

@@ -28,6 +28,7 @@ import {
   getImportedFnNames,
   collectCreateExportBindings,
   buildUnsupportedShapeWarning,
+  findUnsupportedCreateCallSites,
   isExportOnlyFile,
 } from "./expose-ids/export-analysis.js";
 import {
@@ -39,7 +40,6 @@ import {
   transformHandles,
   transformLocationState,
   generateWholeFileStubs,
-  generateExprStubs,
   stubHandlerExprs,
   transformHandlerIds,
 } from "./expose-ids/handler-transform.js";
@@ -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"]);
@@ -335,7 +345,7 @@ ${lazyImports.join(",\n")}
           }
           if (_cachedAst !== undefined || _astParseFailed) return _cachedAst;
           try {
-            _cachedAst = parseAst(code, { jsx: true });
+            _cachedAst = parseAst(code, { lang: "tsx" });
           } catch {
             _astParseFailed = true;
           }
@@ -371,14 +381,21 @@ ${lazyImports.join(",\n")}
           if (!hasCode) continue;
 
           const fnNames = getFnNames(cfg.fnName);
-          const totalCalls = countCreateCallsForNames(code, fnNames);
-          const supportedBindings = getBindings(code, fnNames).length;
-          if (totalCalls <= supportedBindings) continue;
+          // Locate the real (comment/string-free) create* calls not covered by
+          // a supported, id-injectable export shape. Empty means every call is
+          // fine — in particular, a create*() token in a comment or string no
+          // longer trips a spurious warning.
+          const sites = findUnsupportedCreateCallSites(
+            code,
+            fnNames,
+            getBindings(code, fnNames),
+          );
+          if (sites.length === 0) continue;
 
           const warnKey = `${id}::${cfg.fnName}`;
           if (unsupportedShapeWarnings.has(warnKey)) continue;
           unsupportedShapeWarnings.add(warnKey);
-          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName));
+          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName, sites));
         }
 
         // --- Loader: track for manifest (RSC env only) ---
@@ -424,17 +441,6 @@ ${lazyImports.join(",\n")}
           if (wholeFile) return wholeFile;
         }
 
-        // --- PrerenderHandler: RSC build module tracking ---
-        if (hasPrerenderHandlerCode && isRscEnv && isBuild) {
-          const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-          const exportNames = getBindings(code, fnNames).map(
-            (b) => b.exportNames[0],
-          );
-          if (exportNames.length > 0) {
-            prerenderHandlerModules.set(id, exportNames);
-          }
-        }
-
         // --- Inline handler extraction to virtual modules ---
         // Runs before stubs/tracking so inline calls become imports, then
         // the existing regex fast path handles both the original file's
@@ -710,14 +716,27 @@ ${lazyImports.join(",\n")}
           }
         }
 
-        // --- StaticHandler: RSC build module tracking ---
-        if (hasStaticHandlerCode && isRscEnv && isBuild) {
-          const fnNames = getFnNames(STATIC_CONFIG.fnName);
-          const exportNames = getBindings(code, fnNames).map(
-            (b) => b.exportNames[0],
-          );
-          if (exportNames.length > 0) {
-            staticHandlerModules.set(id, exportNames);
+        // RSC build module tracking (prerender + static), consumed via the
+        // plugin API for prerender freezing. Export-binding sets are invariant
+        // across the inline-extraction loop, so tracking both here is equivalent
+        // to the pre-extraction prerender tracking this replaces.
+        if (isRscEnv && isBuild) {
+          const trackTypes: Array<
+            [boolean, HandlerTransformConfig, Map<string, string[]>]
+          > = [
+            [
+              hasPrerenderHandlerCode,
+              PRERENDER_CONFIG,
+              prerenderHandlerModules,
+            ],
+            [hasStaticHandlerCode, STATIC_CONFIG, staticHandlerModules],
+          ];
+          for (const [has, cfg, trackMap] of trackTypes) {
+            if (!has) continue;
+            const exportNames = getBindings(code, getFnNames(cfg.fnName)).map(
+              (b) => b.exportNames[0],
+            );
+            if (exportNames.length > 0) trackMap.set(id, exportNames);
           }
         }
 
@@ -743,7 +762,6 @@ ${lazyImports.join(",\n")}
             transformHandles(
               getBindings(code, fnNames),
               s,
-              code,
               filePath,
               isBuild,
             ) || changed;
@@ -758,48 +776,19 @@ ${lazyImports.join(",\n")}
               isBuild,
             ) || changed;
         }
-        if (hasPrerenderHandlerCode) {
-          const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-          const bindings = getBindings(code, fnNames);
-          if (isRscEnv) {
-            changed =
-              transformHandlerIds(
-                PRERENDER_CONFIG,
-                bindings,
-                s,
-                filePath,
-                isBuild,
-              ) || changed;
-          } else {
-            // Non-RSC mixed-export file: replace Prerender() calls with stubs
-            // on the shared MagicString so sourcemaps stay accurate.
-            changed =
-              stubHandlerExprs(
-                PRERENDER_CONFIG,
-                bindings,
-                s,
-                filePath,
-                isBuild,
-              ) || changed;
-          }
-        }
-        if (hasStaticHandlerCode) {
-          const fnNames = getFnNames(STATIC_CONFIG.fnName);
-          const bindings = getBindings(code, fnNames);
-          if (isRscEnv) {
-            changed =
-              transformHandlerIds(
-                STATIC_CONFIG,
-                bindings,
-                s,
-                filePath,
-                isBuild,
-              ) || changed;
-          } else {
-            changed =
-              stubHandlerExprs(STATIC_CONFIG, bindings, s, filePath, isBuild) ||
-              changed;
-          }
+        // Prerender + Static share the RSC inject-id vs non-RSC stub dispatch.
+        // Call sites are disjoint (distinct fnNames), so loop order is irrelevant.
+        const finalHandlerConfigs = [
+          hasPrerenderHandlerCode && PRERENDER_CONFIG,
+          hasStaticHandlerCode && STATIC_CONFIG,
+        ].filter((c): c is HandlerTransformConfig => !!c);
+        for (const cfg of finalHandlerConfigs) {
+          const bindings = getBindings(code, getFnNames(cfg.fnName));
+          changed =
+            (isRscEnv
+              ? transformHandlerIds(cfg, bindings, s, filePath, isBuild)
+              : stubHandlerExprs(cfg, bindings, s, filePath, isBuild)) ||
+            changed;
         }
 
         if (!changed) return;

package/src/vite/plugins/performance-tracks.ts

@@ -48,25 +48,18 @@ export function patchRsdwClientDebugInfoRecovery(code: string): {
 
 export function performanceTracksOptimizeDepsPlugin(): {
   name: string;
-  setup(build: any): void;
+  load(id: string): Promise<{ code: string } | null>;
 } {
+  const RSDW_CLIENT_RE =
+    /react-server-dom-webpack-client\.browser\.(development|production)\.js$/;
   return {
     name: "@rangojs/router:performance-tracks-optimize-deps",
-    setup(build: any): void {
-      build.onLoad(
-        {
-          filter:
-            /react-server-dom-webpack-client\.browser\.(development|production)\.js$/,
-        },
-        async (args: { path: string }) => {
-          const code = await readFile(args.path, "utf8");
-          const patched = patchRsdwClientDebugInfoRecovery(code);
-          return {
-            contents: patched.code,
-            loader: "js",
-          };
-        },
-      );
+    async load(id: string): Promise<{ code: string } | null> {
+      const cleanId = id.split("?")[0] ?? id;
+      if (!RSDW_CLIENT_RE.test(cleanId)) return null;
+      const code = await readFile(cleanId, "utf8");
+      const patched = patchRsdwClientDebugInfoRecovery(code);
+      return { code: patched.code };
     },
   };
 }

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,6 +30,8 @@ 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?)$/;
 
+export const USE_CACHE_DIRECTIVE_RE: RegExp = /^use cache(:\s*[\w-]+)?$/;
+
 export function useCacheTransform(): Plugin {
   let projectRoot = "";
   let isBuild = false;
@@ -65,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");
@@ -80,11 +81,10 @@ export function useCacheTransform(): Plugin {
           transformHoistInlineDirective,
         } = rscTransforms;
 
-        // Parse AST
         let ast: any;
         try {
           const { parseAst } = await import("vite");
-          ast = parseAst(code);
+          ast = parseAst(code, { lang: "tsx" });
         } catch {
           return;
         }
@@ -92,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,
@@ -105,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,
@@ -116,9 +113,6 @@ export function useCacheTransform(): Plugin {
           transformHoistInlineDirective,
         );
 
-        // Always check for near-miss directives, even when valid directives
-        // exist. A file may contain both valid and invalid "use cache" directives
-        // in different functions — the invalid ones should still warn.
         warnOnNearMissDirectives(ast, id, this.warn.bind(this));
 
         if (functionResult) return functionResult;
@@ -138,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) => {
@@ -148,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) {
@@ -188,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(
@@ -219,7 +218,7 @@ function transformFunctionLevelUseCache(
 ) {
   try {
     const { output, names } = transformHoistInlineDirective(code, ast, {
-      directive: /^use cache(:\s*[\w-]+)?$/,
+      directive: USE_CACHE_DIRECTIVE_RE,
       runtime: (
         value: string,
         name: string,
@@ -237,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`,
     );
@@ -254,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 {
@@ -273,23 +266,8 @@ function findFileLevelDirective(
   return null;
 }
 
-/**
- * The valid directive regex (must stay in sync with transformFunctionLevelUseCache).
- */
-const VALID_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
-
-/**
- * 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,
@@ -307,7 +285,7 @@ function warnOnNearMissDirectives(
       if (
         value.startsWith("use cache") &&
         NEAR_MISS_RE.test(value) &&
-        !VALID_DIRECTIVE_RE.test(value)
+        !USE_CACHE_DIRECTIVE_RE.test(value)
       ) {
         const profilePart = value.slice("use cache:".length).trim();
         warn(
@@ -317,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)) {