@rangojs/router 0.0.0-experimental.002d056c

package/src/vite/plugins/expose-internal-ids.ts

@@ -0,0 +1,569 @@
+import type { Plugin, ResolvedConfig } from "vite";
+import { parseAst } from "vite";
+import MagicString from "magic-string";
+import path from "node:path";
+import { normalizePath, hashId, detectImports } from "./expose-id-utils.js";
+import {
+  transformInlineHandlers,
+  type VirtualHandlerEntry,
+} from "../utils/ast-handler-extract.js";
+
+import type {
+  HandlerTransformConfig,
+  CreateExportBinding,
+} from "./expose-ids/types.js";
+import {
+  PRERENDER_CONFIG,
+  STATIC_CONFIG,
+  STRICT_CREATE_CONFIGS,
+  type ExposeInternalIdsApi,
+} from "./expose-ids/types.js";
+import {
+  countCreateCallsForNames,
+  getImportedFnNames,
+  collectCreateExportBindings,
+  buildUnsupportedShapeWarning,
+} from "./expose-ids/export-analysis.js";
+import {
+  hasCreateLoaderImport,
+  generateClientLoaderStubs,
+  transformLoaders,
+} from "./expose-ids/loader-transform.js";
+import {
+  transformHandles,
+  transformLocationState,
+  generateWholeFileStubs,
+  generateExprStubs,
+  transformHandlerIds,
+} from "./expose-ids/handler-transform.js";
+
+// Re-exports consumed by other packages/plugins
+export { exposeRouterId } from "./expose-ids/router-transform.js";
+export type { ExposeInternalIdsApi } from "./expose-ids/types.js";
+
+// ---------------------------------------------------------------------------
+// Virtual module for loader manifest
+// ---------------------------------------------------------------------------
+
+const VIRTUAL_LOADER_MANIFEST = "virtual:rsc-router/loader-manifest";
+const RESOLVED_VIRTUAL_LOADER_MANIFEST = "\0" + VIRTUAL_LOADER_MANIFEST;
+
+// ---------------------------------------------------------------------------
+// Virtual module prefix for extracted inline handlers
+// ---------------------------------------------------------------------------
+
+const VIRTUAL_HANDLER_PREFIX = "virtual:handler-extract:";
+
+// ---------------------------------------------------------------------------
+// Consolidated plugin
+// ---------------------------------------------------------------------------
+
+export function exposeInternalIds(options?: { forceBuild?: boolean }): Plugin {
+  let config: ResolvedConfig;
+  let isBuild = false;
+  let projectRoot = "";
+
+  // Loader registry: hashedId -> { filePath, exportName }
+  const loaderRegistry = new Map<
+    string,
+    { filePath: string; exportName: string }
+  >();
+
+  // Prerender handler module tracking (consumed via plugin API)
+  const prerenderHandlerModules: Map<string, string[]> = new Map();
+
+  // Static handler module tracking (consumed via plugin API)
+  const staticHandlerModules: Map<string, string[]> = new Map();
+
+  // Virtual module registry for inline handler extraction (both types)
+  const virtualHandlers = new Map<string, VirtualHandlerEntry>();
+  // De-duplicate unsupported shape warnings across repeated transforms.
+  const unsupportedShapeWarnings = new Set<string>();
+
+  return {
+    name: "@rangojs/router:expose-internal-ids",
+    enforce: "post",
+
+    api: {
+      prerenderHandlerModules,
+      staticHandlerModules,
+    } satisfies ExposeInternalIdsApi,
+
+    configResolved(resolved) {
+      config = resolved;
+      isBuild = options?.forceBuild || config.command === "build";
+      projectRoot = config.root;
+    },
+
+    // --------------- Virtual module support ---------------
+
+    resolveId(id, importer) {
+      if (id === VIRTUAL_LOADER_MANIFEST) {
+        return RESOLVED_VIRTUAL_LOADER_MANIFEST;
+      }
+      if (id.startsWith(VIRTUAL_HANDLER_PREFIX)) {
+        return "\0" + id;
+      }
+      // Resolve imports FROM virtual modules against the original file
+      if (importer?.startsWith("\0" + VIRTUAL_HANDLER_PREFIX)) {
+        const entry = virtualHandlers.get(importer);
+        if (entry) {
+          return this.resolve(id, entry.originalModuleId, { skipSelf: true });
+        }
+      }
+    },
+
+    load(id) {
+      // Virtual handler modules (both prerender and static)
+      if (id.startsWith("\0" + VIRTUAL_HANDLER_PREFIX)) {
+        const entry = virtualHandlers.get(id);
+        if (!entry) return null;
+        return (
+          [
+            ...entry.imports,
+            ...entry.declarations,
+            `export const ${entry.exportName} = ${entry.handlerCode};`,
+          ].join("\n") + "\n"
+        );
+      }
+
+      if (id !== RESOLVED_VIRTUAL_LOADER_MANIFEST) return;
+
+      if (!isBuild) {
+        return `import { setLoaderImports } from "@rangojs/router/server";
+
+// Dev mode: empty map, loaders are resolved dynamically via path parsing
+setLoaderImports({});
+`;
+      }
+
+      // Build mode: generate lazy import map
+      const lazyImports: string[] = [];
+
+      for (const [hashedId, { filePath, exportName }] of loaderRegistry) {
+        lazyImports.push(
+          `  "${hashedId}": () => import("/${filePath}").then(m => m.${exportName})`,
+        );
+      }
+
+      if (lazyImports.length === 0) {
+        return `import { setLoaderImports } from "@rangojs/router/server";
+
+// No fetchable loaders discovered during build
+setLoaderImports({});
+`;
+      }
+
+      return `import { setLoaderImports } from "@rangojs/router/server";
+
+// Lazy import map - loaders are loaded on-demand when first requested
+setLoaderImports({
+${lazyImports.join(",\n")}
+});
+`;
+    },
+
+    // --------------- Loader pre-scan (build mode) ---------------
+
+    async buildStart() {
+      if (!isBuild) return;
+
+      const fs = await import("node:fs/promises");
+
+      const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
+
+      async function scanDir(dir: string): Promise<string[]> {
+        const results: string[] = [];
+        try {
+          const entries = await fs.readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+              if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+                results.push(...(await scanDir(fullPath)));
+              }
+            } else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) {
+              results.push(fullPath);
+            }
+          }
+        } catch {
+          // Directory doesn't exist or not readable
+        }
+        return results;
+      }
+
+      try {
+        const files = await scanDir(projectRoot);
+
+        for (const filePath of files) {
+          const content = await fs.readFile(filePath, "utf-8");
+
+          if (!content.includes("createLoader")) continue;
+          if (!hasCreateLoaderImport(content)) continue;
+
+          const fnNames = getImportedFnNames(content, "createLoader");
+          const relativePath = normalizePath(
+            path.relative(projectRoot, filePath),
+          );
+          const bindings = collectCreateExportBindings(content, fnNames);
+
+          for (const binding of bindings) {
+            const exportName = binding.exportNames[0];
+            const hashedId = hashId(relativePath, exportName);
+            loaderRegistry.set(hashedId, {
+              filePath: relativePath,
+              exportName,
+            });
+          }
+        }
+      } catch (error) {
+        console.warn("[exposeInternalIds] Loader pre-scan failed:", error);
+      }
+    },
+
+    // --------------- Unified transform ---------------
+
+    transform(code, id) {
+      if (id.includes("/node_modules/")) return;
+
+      const filePath = normalizePath(path.relative(projectRoot, id));
+      const isRscEnv = this.environment?.name === "rsc";
+
+      // Warn if named-routes.gen is imported in a client component.
+      // NamedRoutes is server-only data and would bloat the client bundle.
+      if (
+        id.includes(".named-routes.gen.") &&
+        !isRscEnv &&
+        this.environment?.name === "client"
+      ) {
+        this.warn(
+          `\n` +
+            `!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n` +
+            `!!                                                              !!\n` +
+            `!!  WARNING: NamedRoutes imported in a CLIENT component!        !!\n` +
+            `!!                                                              !!\n` +
+            `!!  File: ${filePath.padEnd(53)}!!\n` +
+            `!!                                                              !!\n` +
+            `!!  NamedRoutes contains your entire route structure — every    !!\n` +
+            `!!  route name and URL pattern in your application. Shipping    !!\n` +
+            `!!  this to the browser exposes your full routing topology to   !!\n` +
+            `!!  the client, which is a security concern (internal/admin     !!\n` +
+            `!!  routes, API endpoints, hidden paths become visible).        !!\n` +
+            `!!                                                              !!\n` +
+            `!!  It also bloats the client bundle — this map contains all    !!\n` +
+            `!!  named routes in your application.                           !!\n` +
+            `!!                                                              !!\n` +
+            `!!  Fix: remove the import or move it to a server component.    !!\n` +
+            `!!                                                              !!\n` +
+            `!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n`,
+        );
+      }
+
+      // Fast exit: if the file doesn't import from @rangojs/router at all,
+      // skip all create* analysis and transforms.
+      if (!code.includes("@rangojs/router")) return;
+
+      // Detect all relevant imports in one pass
+      const has = detectImports(code);
+
+      // Quick bail-out: also check for raw create* identifiers.
+      // This is safe even with aliases (e.g., `import { createLoader as cl }`)
+      // because the import statement itself always contains the canonical name
+      // "createLoader", so code.includes("createLoader") will still match.
+      const hasLoaderCode = has.loader && code.includes("createLoader");
+      const hasHandleCode = has.handle && code.includes("createHandle");
+      const hasLocationStateCode =
+        has.locationState && code.includes("createLocationState");
+      const hasPrerenderHandlerCode =
+        has.prerenderHandler && code.includes("Prerender");
+      const hasStaticHandlerCode = has.staticHandler && code.includes("Static");
+      if (
+        !hasLoaderCode &&
+        !hasHandleCode &&
+        !hasLocationStateCode &&
+        !hasPrerenderHandlerCode &&
+        !hasStaticHandlerCode
+      ) {
+        return;
+      }
+
+      // Per-invocation caches to avoid redundant AST parsing.
+      // getImportedFnNames is cached by canonical name (imports never change).
+      // collectCreateExportBindings is cached by fnNames key; the cache is
+      // cleared when `code` changes (e.g., after inline handler extraction).
+      const _fnNamesCache = new Map<string, string[]>();
+      const _bindingsCache = new Map<string, CreateExportBinding[]>();
+      let _cachedAst: any;
+      let _astParseFailed = false;
+      let _astCodeRef = code;
+
+      const getFnNames = (canonicalName: string): string[] => {
+        let result = _fnNamesCache.get(canonicalName);
+        if (!result) {
+          result = getImportedFnNames(code, canonicalName);
+          _fnNamesCache.set(canonicalName, result);
+        }
+        return result;
+      };
+
+      // Lazy AST parse: parsed once and shared across all
+      // collectCreateExportBindings calls for the same code string.
+      const lazyAst = (): any | undefined => {
+        if (code !== _astCodeRef) {
+          _cachedAst = undefined;
+          _astParseFailed = false;
+          _astCodeRef = code;
+        }
+        if (_cachedAst !== undefined || _astParseFailed) return _cachedAst;
+        try {
+          _cachedAst = parseAst(code, { jsx: true });
+        } catch {
+          _astParseFailed = true;
+        }
+        return _cachedAst;
+      };
+
+      const getBindings = (
+        currentCode: string,
+        fnNames: string[],
+      ): CreateExportBinding[] => {
+        const key = fnNames.join("\0");
+        let result = _bindingsCache.get(key);
+        if (!result) {
+          result = collectCreateExportBindings(currentCode, fnNames, lazyAst());
+          _bindingsCache.set(key, result);
+        }
+        return result;
+      };
+
+      // Warn on create* declaration shapes that are currently unsupported by
+      // non-AST transforms (loader/handle/locationState only).
+      for (const cfg of STRICT_CREATE_CONFIGS) {
+        const hasCode =
+          cfg.fnName === "createLoader"
+            ? hasLoaderCode
+            : cfg.fnName === "createHandle"
+              ? hasHandleCode
+              : hasLocationStateCode;
+        if (!hasCode) continue;
+
+        const fnNames = getFnNames(cfg.fnName);
+        const totalCalls = countCreateCallsForNames(code, fnNames);
+        const supportedBindings = getBindings(code, fnNames).length;
+        if (totalCalls <= supportedBindings) continue;
+
+        const warnKey = `${id}::${cfg.fnName}`;
+        if (unsupportedShapeWarnings.has(warnKey)) continue;
+        unsupportedShapeWarnings.add(warnKey);
+        this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName));
+      }
+
+      // --- Loader: track for manifest (RSC env only) ---
+      if (hasLoaderCode && isRscEnv) {
+        const fnNames = getFnNames("createLoader");
+        const bindings = getBindings(code, fnNames);
+        for (const binding of bindings) {
+          const exportName = binding.exportNames[0];
+          const hashedId = hashId(filePath, exportName);
+          loaderRegistry.set(hashedId, {
+            filePath,
+            exportName,
+          });
+        }
+      }
+
+      // --- Loader: client stubs for non-RSC environments ---
+      if (hasLoaderCode && !isRscEnv) {
+        const fnNames = getFnNames("createLoader");
+        const bindings = getBindings(code, fnNames);
+        const stubResult = generateClientLoaderStubs(
+          bindings,
+          code,
+          filePath,
+          isBuild,
+        );
+        if (stubResult) return stubResult;
+      }
+
+      // --- PrerenderHandler: non-RSC stub replacement ---
+      if (hasPrerenderHandlerCode && !isRscEnv) {
+        const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
+        const bindings = getBindings(code, fnNames);
+        const wholeFile = generateWholeFileStubs(
+          PRERENDER_CONFIG,
+          bindings,
+          code,
+          filePath,
+          isBuild,
+        );
+        if (wholeFile) return wholeFile;
+
+        const exprStubs = generateExprStubs(
+          PRERENDER_CONFIG,
+          bindings,
+          code,
+          filePath,
+          id,
+          isBuild,
+        );
+        if (exprStubs) return exprStubs;
+      }
+
+      // --- 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
+      // export const patterns and the virtual modules independently.
+      //
+      // Cheap pre-check: count total fnName( occurrences vs export const
+      // patterns. If they match, every call is a named export and the
+      // regex fast path handles them -- skip the AST parse entirely.
+      //
+      // Each iteration creates a fresh MagicString so that AST positions
+      // from findHandlerCalls always match the string they were parsed from.
+      let changed = false;
+
+      const handlerConfigs = [
+        hasStaticHandlerCode && STATIC_CONFIG,
+        hasPrerenderHandlerCode && PRERENDER_CONFIG,
+      ]
+        .filter((c): c is HandlerTransformConfig => !!c)
+        .map((cfg) => {
+          const fnNames = getFnNames(cfg.fnName);
+          return { cfg, fnNames };
+        });
+
+      for (const { cfg, fnNames } of handlerConfigs) {
+        const totalCalls = countCreateCallsForNames(code, fnNames);
+        const supportedBindings = getBindings(code, fnNames).length;
+
+        if (totalCalls > supportedBindings) {
+          const iterS = new MagicString(code);
+          const result = transformInlineHandlers(
+            cfg.fnName,
+            VIRTUAL_HANDLER_PREFIX,
+            iterS,
+            code,
+            filePath,
+            virtualHandlers,
+            id,
+            parseAst,
+          );
+          if (result) {
+            changed = true;
+            code = iterS.toString();
+            _bindingsCache.clear();
+          }
+        }
+      }
+
+      // --- StaticHandler: non-RSC stub replacement ---
+      if (hasStaticHandlerCode && !isRscEnv) {
+        const fnNames = getFnNames(STATIC_CONFIG.fnName);
+        const bindings = getBindings(code, fnNames);
+        const wholeFile = generateWholeFileStubs(
+          STATIC_CONFIG,
+          bindings,
+          code,
+          filePath,
+          isBuild,
+        );
+        if (wholeFile) return wholeFile;
+
+        const exprStubs = generateExprStubs(
+          STATIC_CONFIG,
+          bindings,
+          code,
+          filePath,
+          id,
+          isBuild,
+        );
+        if (exprStubs) return exprStubs;
+      }
+
+      // --- 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);
+        }
+      }
+
+      // --- Unified MagicString transforms ---
+      // Single pipeline for all downstream transforms (loaders, handles,
+      // locationState, handler IDs). Uses the post-extraction code so
+      // positions are always consistent.
+      const s = new MagicString(code);
+
+      if (hasLoaderCode) {
+        const fnNames = getFnNames("createLoader");
+        changed =
+          transformLoaders(getBindings(code, fnNames), s, filePath, isBuild) ||
+          changed;
+      }
+      if (hasHandleCode) {
+        const fnNames = getFnNames("createHandle");
+        changed =
+          transformHandles(
+            getBindings(code, fnNames),
+            s,
+            code,
+            filePath,
+            isBuild,
+          ) || changed;
+      }
+      if (hasLocationStateCode) {
+        const fnNames = getFnNames("createLocationState");
+        changed =
+          transformLocationState(
+            getBindings(code, fnNames),
+            s,
+            filePath,
+            isBuild,
+          ) || changed;
+      }
+      if (hasPrerenderHandlerCode && isRscEnv) {
+        const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
+        changed =
+          transformHandlerIds(
+            PRERENDER_CONFIG,
+            getBindings(code, fnNames),
+            s,
+            filePath,
+            isBuild,
+          ) || changed;
+      }
+      if (hasStaticHandlerCode && isRscEnv) {
+        const fnNames = getFnNames(STATIC_CONFIG.fnName);
+        changed =
+          transformHandlerIds(
+            STATIC_CONFIG,
+            getBindings(code, fnNames),
+            s,
+            filePath,
+            isBuild,
+          ) || changed;
+      }
+
+      if (!changed) return;
+
+      return {
+        code: s.toString(),
+        map: s.generateMap({ source: id, includeContent: true }),
+      };
+    },
+  };
+}

package/src/vite/plugins/refresh-cmd.ts

@@ -0,0 +1,65 @@
+import type { Plugin } from "vite";
+
+/**
+ * Vite plugin that triggers a full browser reload when Ctrl+R is pressed
+ * in the terminal running the dev server.
+ *
+ * Usage:
+ * ```ts
+ * import { poke } from "@rangojs/router/vite";
+ *
+ * export default defineConfig({
+ *   plugins: [rango(), poke()],
+ * });
+ * ```
+ */
+export function poke(): Plugin {
+  return {
+    name: "vite-plugin-poke",
+    apply: "serve",
+
+    configureServer(server) {
+      const stdin = process.stdin;
+
+      // Raw mode delivers individual keystrokes as immediate single-byte
+      // events instead of waiting for Enter (cooked/line-buffered mode).
+      // Without it, Ctrl+R (0x12) is never delivered as a discrete byte.
+      // When stdin is a pipe (CI, spawned process) setRawMode is unavailable
+      // but data already arrives unbuffered, so the isTTY guard suffices.
+      const previousRawMode = stdin.isTTY ? stdin.isRaw : null;
+      if (stdin.isTTY) {
+        stdin.setRawMode(true);
+      }
+
+      const onData = (data: Buffer) => {
+        if (data.length !== 1) return;
+
+        // Ctrl+C (0x03) — defensive fallback. This plugin enables raw mode
+        // before Vite's internal stdin handler is registered (user plugins
+        // run first), so there is a brief window where Ctrl+C would be
+        // swallowed. Re-emit SIGINT so the process exits as expected.
+        if (data[0] === 0x03) {
+          process.emit("SIGINT", "SIGINT");
+          return;
+        }
+
+        // Ctrl+R = 0x12 in raw mode
+        if (data[0] === 0x12) {
+          server.hot.send({ type: "full-reload", path: "*" });
+          server.config.logger.info("  browser reload (ctrl+r)", {
+            timestamp: true,
+          });
+        }
+      };
+
+      stdin.on("data", onData);
+
+      server.httpServer?.on("close", () => {
+        stdin.off("data", onData);
+        if (stdin.isTTY && previousRawMode !== null) {
+          stdin.setRawMode(previousRawMode);
+        }
+      });
+    },
+  };
+}