@rangojs/router 0.0.0-experimental.002d056c

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

@@ -0,0 +1,296 @@
+import { parseAst } from "vite";
+import {
+  findMatchingParen,
+  countArgs,
+  findStatementEnd,
+  buildExportMap,
+  escapeRegExp,
+} from "../expose-id-utils.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[],
+): boolean {
+  if (bindings.length === 0) return false;
+
+  const knownLocals = new Set<string>();
+  const knownExports = new Set<string>();
+  for (const b of bindings) {
+    knownLocals.add(b.localName);
+    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;
+  while ((match = declExportPattern.exec(code)) !== null) {
+    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]
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    for (const spec of specifiers) {
+      const m = spec.match(
+        /^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/,
+      );
+      if (!m) continue;
+      const local = m[1];
+      if (!knownLocals.has(local)) return false;
+    }
+  }
+
+  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.
+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;
+}
+
+export function getImportedFnNames(
+  code: string,
+  importedName: string,
+): string[] {
+  const importPattern =
+    /import\s*\{([^}]*)\}\s*from\s*["']@rangojs\/router(?:\/[^"']*)?["']/g;
+
+  const localNames = new Set<string>();
+  let match: RegExpExecArray | null;
+
+  while ((match = importPattern.exec(code)) !== null) {
+    const specList = match[1]
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    for (const spec of specList) {
+      const m = spec.match(
+        /^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/,
+      );
+      if (!m) continue;
+      const imported = m[1];
+      const local = m[2] || imported;
+      if (imported === importedName) {
+        localNames.add(local);
+      }
+    }
+  }
+
+  const names = Array.from(localNames);
+  return names.length > 0 ? names : [importedName];
+}
+
+export function getCalledIdentifierFromCall(callExpr: any): string | null {
+  const callee = callExpr?.callee;
+  if (callee?.type === "Identifier") return callee.name;
+  if (
+    callee?.type === "TSInstantiationExpression" &&
+    callee.expression?.type === "Identifier"
+  ) {
+    return callee.expression.name;
+  }
+  return null;
+}
+
+export function collectCreateExportBindingsFallback(
+  code: string,
+  fnNames: string[],
+): CreateExportBinding[] {
+  const alternation = fnNames.map(escapeRegExp).join("|");
+  const exportConstPattern = new RegExp(
+    `export\\s+const\\s+(\\w+)\\s*=\\s*(?:${alternation})\\s*(?:<[^>]*>)?\\s*\\(`,
+    "g",
+  );
+  const localDeclPattern = new RegExp(
+    `\\bconst\\s+(\\w+)\\s*=\\s*((?:${alternation})\\s*(?:<[^>]*>)?\\s*\\()`,
+    "g",
+  );
+  const exportSpecPattern = /export\s*\{([^}]+)\}/g;
+
+  const exportMap = new Map<string, string[]>();
+  const pushExport = (local: string, exported: string) => {
+    const list = exportMap.get(local);
+    if (list) {
+      if (!list.includes(exported)) list.push(exported);
+      return;
+    }
+    exportMap.set(local, [exported]);
+  };
+
+  let match: RegExpExecArray | null;
+  while ((match = exportConstPattern.exec(code)) !== null) {
+    pushExport(match[1], match[1]);
+  }
+
+  while ((match = exportSpecPattern.exec(code)) !== null) {
+    const specifiers = match[1]
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    for (const specifier of specifiers) {
+      const specMatch = specifier.match(
+        /^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/,
+      );
+      if (!specMatch) continue;
+      const local = specMatch[1];
+      const exported = specMatch[2] || local;
+      pushExport(local, exported);
+    }
+  }
+
+  const bindings: CreateExportBinding[] = [];
+  while ((match = localDeclPattern.exec(code)) !== null) {
+    const localName = match[1];
+    const exportNames = exportMap.get(localName) ?? [];
+    if (exportNames.length === 0) continue;
+
+    const openParenPos = match.index + match[0].length - 1;
+    const closeParenPos = findMatchingParen(code, openParenPos + 1) - 1;
+    if (closeParenPos <= openParenPos) continue;
+
+    bindings.push({
+      localName,
+      exportNames,
+      callExprStart: match.index + match[0].length - match[2].length,
+      callOpenParenPos: openParenPos,
+      callCloseParenPos: closeParenPos,
+      argCount: countArgs(code, openParenPos + 1, closeParenPos),
+      statementEnd: findStatementEnd(code, closeParenPos + 1),
+    });
+  }
+
+  return bindings;
+}
+
+export function collectCreateExportBindings(
+  code: string,
+  fnNames: string[],
+  program?: any,
+): CreateExportBinding[] {
+  if (!program) {
+    try {
+      program = parseAst(code, { jsx: true });
+    } catch {
+      return collectCreateExportBindingsFallback(code, fnNames);
+    }
+  }
+
+  const exportMap = buildExportMap(program);
+  const fnNameSet = new Set(fnNames);
+  const bindings: CreateExportBinding[] = [];
+
+  const collectFromVarDecl = (varDecl: any, statementEnd: number) => {
+    if (varDecl?.type !== "VariableDeclaration" || varDecl.kind !== "const") {
+      return;
+    }
+
+    for (const decl of varDecl.declarations ?? []) {
+      const calledIdentifier = getCalledIdentifierFromCall(decl?.init);
+      if (
+        decl?.id?.type !== "Identifier" ||
+        decl?.init?.type !== "CallExpression" ||
+        !calledIdentifier ||
+        !fnNameSet.has(calledIdentifier)
+      ) {
+        continue;
+      }
+
+      const localName = decl.id.name;
+      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;
+
+      let openParenPos = -1;
+      for (let i = calleeEnd; i < callEnd; i++) {
+        if (code[i] === "(") {
+          openParenPos = i;
+          break;
+        }
+      }
+      if (openParenPos === -1) continue;
+
+      const closeParenPos = findMatchingParen(code, openParenPos + 1) - 1;
+      if (closeParenPos <= openParenPos) continue;
+
+      bindings.push({
+        localName,
+        exportNames,
+        callExprStart: decl.init.start as number,
+        callOpenParenPos: openParenPos,
+        callCloseParenPos: closeParenPos,
+        argCount: decl.init.arguments?.length ?? 0,
+        statementEnd,
+      });
+    }
+  };
+
+  for (const node of program.body ?? []) {
+    if (node?.type === "VariableDeclaration") {
+      collectFromVarDecl(node, node.end as number);
+      continue;
+    }
+
+    if (
+      node?.type === "ExportNamedDeclaration" &&
+      node.declaration?.type === "VariableDeclaration"
+    ) {
+      collectFromVarDecl(node.declaration, node.end as number);
+    }
+  }
+
+  // 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);
+  }
+
+  return bindings;
+}
+
+export function buildUnsupportedShapeWarning(
+  filePath: string,
+  fnName: string,
+): string {
+  return [
+    `[rsc-router] Unsupported ${fnName} shape in "${filePath}".`,
+    `Supported shapes are:`,
+    `  - export const X = ${fnName}(...)`,
+    `  - const X = ${fnName}(...); export { X }`,
+    `  - const X = ${fnName}(...); export { X as Y }`,
+    `Potentially unsupported forms include:`,
+    `  - export let/var X = ${fnName}(...)`,
+    `  - inline ${fnName}(...) calls`,
+  ].join("\n");
+}

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

@@ -0,0 +1,179 @@
+import MagicString from "magic-string";
+import { hashId } from "../expose-id-utils.js";
+import type { HandlerTransformConfig, CreateExportBinding } from "./types.js";
+import { isExportOnlyFile } from "./export-analysis.js";
+
+function analyzeCreateHandleArgs(
+  code: string,
+  startPos: number,
+  endPos: number,
+): { hasArgs: boolean } {
+  const content = code.slice(startPos, endPos).trim();
+  return { hasArgs: content.length > 0 };
+}
+
+export function transformHandles(
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  code: string,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+    const args = analyzeCreateHandleArgs(
+      code,
+      binding.callOpenParenPos + 1,
+      binding.callCloseParenPos,
+    );
+
+    const handleId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    let paramInjection: string;
+    if (!args.hasArgs) {
+      paramInjection = `undefined, "${handleId}"`;
+    } else {
+      paramInjection = `, "${handleId}"`;
+    }
+    s.appendLeft(binding.callCloseParenPos, paramInjection);
+
+    const propInjection = `\n${binding.localName}.$$id = "${handleId}";`;
+    s.appendRight(binding.statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  return hasChanges;
+}
+
+export function transformLocationState(
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+
+    const stateKey = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    // Key is injected as a property assignment (not as a function argument).
+    // This allows createLocationState to accept options like { flash: true }
+    // without conflicting with key injection.
+    const propInjection = `\n${binding.localName}.__rsc_ls_key = "__rsc_ls_${stateKey}";`;
+    s.appendRight(binding.statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  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[],
+  code: string,
+  filePath: string,
+  isBuild: boolean,
+): { code: string; map: null } | null {
+  if (!isExportOnlyFile(code, bindings)) return null;
+
+  const exportNames = bindings.flatMap((b) => b.exportNames);
+  const stubs = exportNames.map((name) => {
+    const handlerId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+    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",
+    }),
+  };
+}
+
+/**
+ * Inject $$id into export const handler calls in RSC environments.
+ */
+export function transformHandlerIds(
+  cfg: HandlerTransformConfig,
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+
+    const handlerId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    // 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}"`;
+    } else if (binding.argCount === 1) {
+      paramInjection = `, undefined, "${handlerId}"`;
+    } else {
+      paramInjection = `, "${handlerId}"`;
+    }
+    s.appendLeft(binding.callCloseParenPos, paramInjection);
+
+    const propInjection = `\n${binding.localName}.$$id = "${handlerId}";`;
+    s.appendRight(binding.statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  return hasChanges;
+}

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

@@ -0,0 +1,74 @@
+import type MagicString from "magic-string";
+import { hashId } from "../expose-id-utils.js";
+import type { CreateExportBinding } from "./types.js";
+import { isExportOnlyFile } from "./export-analysis.js";
+
+export function hasCreateLoaderImport(code: string): boolean {
+  return /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(
+    code,
+  );
+}
+
+/**
+ * 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,
+  filePath: string,
+  isBuild: boolean,
+): { code: string; map?: undefined } | null {
+  if (!isExportOnlyFile(code, bindings)) return null;
+
+  const lines: string[] = [];
+
+  for (const binding of bindings) {
+    for (const name of binding.exportNames) {
+      const loaderId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+      lines.push(
+        `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`,
+      );
+    }
+  }
+
+  return { code: lines.join("\n") + "\n" };
+}
+
+export function transformLoaders(
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+
+    const loaderId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    // 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);
+
+    const propInjection = `\n${binding.localName}.$$id = "${loaderId}";`;
+    s.appendRight(binding.statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  return hasChanges;
+}

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

@@ -0,0 +1,110 @@
+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";
+
+export function transformRouter(
+  code: string,
+  filePath: string,
+  routerFnNames: string[],
+  absolutePath?: string,
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  const pat = new RegExp(
+    `\\b(?:${routerFnNames.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\s*(?:<[^>]*>)?\\s*\\(`,
+    "g",
+  );
+  let match: RegExpExecArray | null;
+  const s = new MagicString(code);
+  let changed = false;
+
+  // Compute the import path for the generated route names file.
+  // filePath is relative to project root (e.g., "src/router.tsx")
+  const basename = path.basename(filePath).replace(/\.(tsx?|jsx?)$/, "");
+  const routeNamesImport = `./${basename}.named-routes.gen.js`;
+  const routeNamesVar = `__rsc_rn`;
+
+  while ((match = pat.exec(code)) !== null) {
+    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}`)
+      .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(")")) {
+      s.appendRight(parenPos + 1, `{${injected} }`);
+    }
+  }
+
+  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`,
+  );
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({ hires: true }),
+  };
+}
+
+/**
+ * Inject stable $$id into createRouter() calls at compile time.
+ * This must be a separate plugin without enforce:"post" because running
+ * at "post" priority changes Vite's dep optimization timing and can cause
+ * ERR_OUTDATED_OPTIMIZED_DEP / React dual-instance issues.
+ */
+export function exposeRouterId(): Plugin {
+  let projectRoot = "";
+  return {
+    name: "@rangojs/router:expose-router-id",
+    configResolved(config) {
+      projectRoot = config.root;
+    },
+    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,
+        )
+      ) {
+        return null;
+      }
+      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));
+    },
+  };
+}

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

@@ -0,0 +1,45 @@
+export interface HandlerTransformConfig {
+  fnName: string;
+  brand: string;
+}
+
+export interface CreateExportBinding {
+  localName: string;
+  exportNames: string[];
+  callExprStart: number;
+  callOpenParenPos: number;
+  callCloseParenPos: number;
+  argCount: number;
+  statementEnd: number;
+}
+
+export interface StrictCreateTransformConfig {
+  fnName: "createLoader" | "createHandle" | "createLocationState";
+}
+
+export const PRERENDER_CONFIG: HandlerTransformConfig = {
+  fnName: "Prerender",
+  brand: "prerenderHandler",
+};
+
+export const STATIC_CONFIG: HandlerTransformConfig = {
+  fnName: "Static",
+  brand: "staticHandler",
+};
+
+export const STRICT_CREATE_CONFIGS: StrictCreateTransformConfig[] = [
+  { fnName: "createLoader" },
+  { fnName: "createHandle" },
+  { fnName: "createLocationState" },
+];
+
+export interface ExposeInternalIdsApi {
+  /** Tracks absolute module IDs that contain prerender handler exports.
+   *  key: absolute module ID (filesystem path)
+   *  value: array of export names (e.g., ["ArticlesIndex", "ArticleDetail"]) */
+  prerenderHandlerModules: Map<string, string[]>;
+  /** Tracks absolute module IDs that contain static handler exports.
+   *  key: absolute module ID (filesystem path)
+   *  value: array of export names (e.g., ["DocsNav", "DocShell"]) */
+  staticHandlerModules: Map<string, string[]>;
+}