@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.91

package/src/vite/expose-prerender-handler-id.ts

@@ -1,429 +0,0 @@
-import type { Plugin, ResolvedConfig } from "vite";
-import MagicString from "magic-string";
-import path from "node:path";
-import crypto from "node:crypto";
-
-/**
- * Normalize path to forward slashes
- */
-function normalizePath(p: string): string {
-  return p.split(path.sep).join("/");
-}
-
-/**
- * Generate a short hash for a prerender handler ID.
- * Uses first 8 chars of SHA-256 hash for uniqueness while keeping IDs short.
- * Appends export name for easier debugging: "abc123#DocsPage"
- */
-function hashPrerenderHandlerId(filePath: string, exportName: string): string {
-  const input = `${filePath}#${exportName}`;
-  const hash = crypto.createHash("sha256").update(input).digest("hex");
-  return `${hash.slice(0, 8)}#${exportName}`;
-}
-
-/**
- * Check if file imports createPrerenderHandler from @rangojs/router
- */
-function hasCreatePrerenderHandlerImport(code: string): boolean {
-  const pattern =
-    /import\s*\{[^}]*\bcreatePrerenderHandler\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/[^"']+)?["']/;
-  return pattern.test(code);
-}
-
-/**
- * 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.
- */
-function skipStringOrComment(code: string, pos: number): number {
-  const ch = code[pos];
-
-  if (ch === '"' || ch === "'") {
-    for (let j = pos + 1; j < code.length; j++) {
-      if (code[j] === "\\") { j++; continue; }
-      if (code[j] === ch) return j + 1;
-    }
-    return code.length;
-  }
-
-  if (ch === "`") {
-    let j = pos + 1;
-    while (j < code.length) {
-      if (code[j] === "\\") { j += 2; continue; }
-      if (code[j] === "`") return j + 1;
-      if (code[j] === "$" && j + 1 < code.length && code[j + 1] === "{") {
-        j += 2;
-        let braceDepth = 1;
-        while (j < code.length && braceDepth > 0) {
-          const inner = skipStringOrComment(code, j);
-          if (inner > j) { j = inner; continue; }
-          if (code[j] === "{") braceDepth++;
-          else if (code[j] === "}") braceDepth--;
-          if (braceDepth > 0) j++;
-        }
-        if (braceDepth === 0) j++;
-        continue;
-      }
-      j++;
-    }
-    return j;
-  }
-
-  if (ch === "/" && pos + 1 < code.length) {
-    if (code[pos + 1] === "/") {
-      const eol = code.indexOf("\n", pos + 2);
-      return eol === -1 ? code.length : eol + 1;
-    }
-    if (code[pos + 1] === "*") {
-      const end = code.indexOf("*/", pos + 2);
-      return end === -1 ? code.length : end + 2;
-    }
-  }
-
-  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.
- */
-function findMatchingParen(code: string, startPos: number): number {
-  let depth = 1;
-  let i = startPos;
-  while (i < code.length && depth > 0) {
-    const skipped = skipStringOrComment(code, i);
-    if (skipped > i) { i = skipped; continue; }
-    if (code[i] === "(") depth++;
-    if (code[i] === ")") depth--;
-    i++;
-  }
-  return i;
-}
-
-/**
- * Count the number of top-level arguments in a function call.
- * Skips nested parens, brackets, braces, strings, and comments.
- */
-function countArgs(code: string, startPos: number, endPos: number): number {
-  let depth = 0;
-  let argCount = 0;
-  let hasContent = false;
-  let i = startPos;
-
-  while (i < endPos) {
-    const skipped = skipStringOrComment(code, i);
-    if (skipped > i) { hasContent = true; i = skipped; continue; }
-
-    const char = code[i];
-    if (char === "(" || char === "[" || char === "{") {
-      depth++;
-      hasContent = true;
-    } else if (char === ")" || char === "]" || char === "}") {
-      depth--;
-    } else if (char === "," && depth === 0) {
-      argCount++;
-    } else if (!/\s/.test(char)) {
-      hasContent = true;
-    }
-    i++;
-  }
-
-  return hasContent ? argCount + 1 : 0;
-}
-
-/**
- * Transform export const X = createPrerenderHandler(...) patterns to inject $$id.
- *
- * Overload shapes:
- *   1 arg  (handler)                 -> inject undefined, "id"  (pad for options + id)
- *   2 args (getParams+handler OR handler+options) -> inject , "id"
- *   3 args (getParams+handler+options)            -> inject , "id"
- *
- * The __injectedId is always the LAST parameter.
- */
-function transformPrerenderHandlerExports(
-  code: string,
-  filePath: string,
-  sourceId?: string,
-  isBuild: boolean = false,
-): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
-  if (!code.includes("createPrerenderHandler")) {
-    return null;
-  }
-
-  if (!hasCreatePrerenderHandlerImport(code)) {
-    return null;
-  }
-
-  // Match: export const X = createPrerenderHandler<...>(
-  const pattern =
-    /export\s+const\s+(\w+)\s*=\s*createPrerenderHandler\s*(?:<[^>]*>)?\s*\(/g;
-
-  const s = new MagicString(code);
-  let hasChanges = false;
-  let match: RegExpExecArray | null;
-
-  while ((match = pattern.exec(code)) !== null) {
-    const exportName = match[1];
-    const matchEnd = match.index + match[0].length;
-
-    // Find the matching closing paren (string/comment aware)
-    const afterClose = findMatchingParen(code, matchEnd);
-    const closeParenPos = afterClose - 1;
-    const argCount = countArgs(code, matchEnd, closeParenPos);
-
-    // Find statement end (after ; or whitespace)
-    let statementEnd = afterClose;
-    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
-      statementEnd++;
-    }
-    if (code[statementEnd] === ";") {
-      statementEnd++;
-    }
-
-    const handlerId = isBuild
-      ? hashPrerenderHandlerId(filePath, exportName)
-      : `${filePath}#${exportName}`;
-
-    // Inject $$id as the last parameter.
-    // createPrerenderHandler(handler) -> createPrerenderHandler(handler, undefined, "id")
-    // createPrerenderHandler(handler, opts) -> createPrerenderHandler(handler, opts, "id")
-    // createPrerenderHandler(getP, handler) -> createPrerenderHandler(getP, handler, undefined, "id")
-    // createPrerenderHandler(getP, handler, opts) -> createPrerenderHandler(getP, handler, opts, "id")
-    //
-    // The runtime implementation accepts __injectedId as:
-    //   Overload 1 (1 fn): 3rd param (after handler, options)
-    //   Overload 2 (2 fn): 4th param (after getParams, handler, options)
-    //
-    // We cannot statically distinguish between (handler, options) and (getParams, handler)
-    // when there are 2 args. However the runtime resolves this by checking typeof of the
-    // second arg. The __injectedId is always a string, so it can appear in either the
-    // options or id slot — the runtime handles both via typeof checks.
-    let paramInjection: string;
-    if (argCount === 0) {
-      paramInjection = `undefined, "${handlerId}"`;
-    } else if (argCount === 1) {
-      // 1 arg (handler only): need to pad for options slot
-      paramInjection = `, undefined, "${handlerId}"`;
-    } else {
-      // 2+ args: just append id
-      paramInjection = `, "${handlerId}"`;
-    }
-    s.appendLeft(closeParenPos, paramInjection);
-
-    // Set $$id property for external access
-    const propInjection = `\n${exportName}.$$id = "${handlerId}";`;
-    s.appendRight(statementEnd, propInjection);
-    hasChanges = true;
-  }
-
-  if (!hasChanges) {
-    return null;
-  }
-
-  return {
-    code: s.toString(),
-    map: s.generateMap({ source: sourceId, includeContent: true, hires: "boundary" }),
-  };
-}
-
-/**
- * Replace the entire file with lightweight stubs when ALL non-type exports are
- * createPrerenderHandler calls. This is the most aggressive eviction — all imports,
- * module-level data, and handler bodies are removed from non-RSC bundles.
- *
- * Returns null for files with mixed exports (non-handler value exports),
- * falling back to per-expression replacement.
- */
-function generateWholeFileHandlerStubs(
-  code: string,
-  filePath: string,
-  isBuild: boolean,
-): { code: string; map: null } | null {
-  const handlerPattern =
-    /export\s+const\s+(\w+)\s*=\s*createPrerenderHandler\s*(?:<[^>]*>)?\s*\(/g;
-  const handlers: string[] = [];
-  let match: RegExpExecArray | null;
-
-  while ((match = handlerPattern.exec(code)) !== null) {
-    handlers.push(match[1]);
-  }
-
-  if (handlers.length === 0) return null;
-
-  // Bail out if the file has re-exports or destructured exports that
-  // the declaration pattern below wouldn't catch. Replacing the whole
-  // file would silently drop these exports.
-  if (/export\s*\{/.test(code) || /export\s*\*/.test(code)) {
-    return null;
-  }
-
-  // Check that every non-type export declaration is a createPrerenderHandler call.
-  const allExports =
-    /export\s+(const|let|var|function|class|default)\s+(\w+)/g;
-  let exportMatch: RegExpExecArray | null;
-
-  while ((exportMatch = allExports.exec(code)) !== null) {
-    const name = exportMatch[2];
-    if (!handlers.includes(name)) {
-      // Mixed exports — can't replace the whole file
-      return null;
-    }
-  }
-
-  const stubs = handlers.map((name) => {
-    const handlerId = isBuild
-      ? hashPrerenderHandlerId(filePath, name)
-      : `${filePath}#${name}`;
-    return `export const ${name} = { __brand: "prerenderHandler", $$id: "${handlerId}" };`;
-  });
-
-  return { code: stubs.join("\n") + "\n", map: null };
-}
-
-/**
- * Replace createPrerenderHandler(...) call expressions with lightweight stub objects
- * in non-RSC environments. Other exports, imports, and module-level code remain
- * untouched — only the call expression is replaced.
- *
- * This prevents handler rendering code and build-only dependencies from shipping
- * to client/SSR bundles where handlers never execute.
- */
-function generatePrerenderHandlerStubs(
-  code: string,
-  filePath: string,
-  sourceId?: string,
-  isBuild: boolean = false,
-): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
-  // Match: export const X = createPrerenderHandler<...>(
-  const pattern =
-    /export\s+const\s+(\w+)\s*=\s*(createPrerenderHandler\s*(?:<[^>]*>)?\s*\()/g;
-
-  const s = new MagicString(code);
-  let hasChanges = false;
-  let match: RegExpExecArray | null;
-
-  while ((match = pattern.exec(code)) !== null) {
-    const exportName = match[1];
-    // callStart points to 'c' in 'createPrerenderHandler'
-    const callStart = match.index + match[0].length - match[2].length;
-
-    // Find the matching closing paren (string/comment aware)
-    const openParenPos = match.index + match[0].length;
-    const afterCloseParen = findMatchingParen(code, openParenPos);
-
-    const handlerId = isBuild
-      ? hashPrerenderHandlerId(filePath, exportName)
-      : `${filePath}#${exportName}`;
-
-    // Replace createPrerenderHandler<...>(...) with stub object
-    s.overwrite(
-      callStart,
-      afterCloseParen,
-      `{ __brand: "prerenderHandler", $$id: "${handlerId}" }`,
-    );
-    hasChanges = true;
-  }
-
-  if (!hasChanges) return null;
-
-  return {
-    code: s.toString(),
-    map: s.generateMap({ source: sourceId, includeContent: true, hires: "boundary" }),
-  };
-}
-
-/**
- * Plugin API type for expose-prerender-handler-id.
- * Accessed by other plugins via config.plugins.find(p => p.name === "...").api
- */
-export interface ExposePrerenderHandlerIdApi {
-  /** 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[]>;
-}
-
-/**
- * Vite plugin that exposes $$id on createPrerenderHandler calls.
- *
- * When users create prerender handlers with createPrerenderHandler(), this plugin:
- * - RSC environment: Injects $$id into the call and sets a $$id property on the export
- * - Non-RSC environments (client/SSR): Replaces createPrerenderHandler(...) call
- *   expressions with lightweight { __brand, $$id } stubs, keeping other exports intact
- *
- * Requirements:
- * - Must use direct import: import { createPrerenderHandler } from "@rangojs/router"
- * - Must use named export: export const MyPage = createPrerenderHandler(...)
- *
- * Other plugins can read handler module data via the plugin API:
- *   config.plugins.find(p => p.name === "@rangojs/router:expose-prerender-handler-id")?.api
- */
-export function exposePrerenderHandlerId(): Plugin {
-  let config: ResolvedConfig;
-  let isBuild = false;
-  const prerenderHandlerModules: Map<string, string[]> = new Map();
-
-  return {
-    name: "@rangojs/router:expose-prerender-handler-id",
-    enforce: "post",
-
-    api: {
-      prerenderHandlerModules,
-    } satisfies ExposePrerenderHandlerIdApi,
-
-    configResolved(resolvedConfig) {
-      config = resolvedConfig;
-      isBuild = config.command === "build";
-    },
-
-    transform(code, id) {
-      // Skip node_modules
-      if (id.includes("/node_modules/")) {
-        return;
-      }
-
-      // Quick bail-out
-      if (!code.includes("createPrerenderHandler")) {
-        return;
-      }
-
-      // Must have direct import from @rangojs/router
-      if (!hasCreatePrerenderHandlerImport(code)) {
-        return;
-      }
-
-      // Get relative path for the ID
-      const relativePath = normalizePath(path.relative(config.root, id));
-
-      const isRscEnv = this.environment?.name === "rsc";
-
-      if (!isRscEnv) {
-        // Non-RSC: try whole-file replacement first (all exports are handlers),
-        // fall back to per-expression replacement for mixed-export files
-        return (
-          generateWholeFileHandlerStubs(code, relativePath, isBuild) ??
-          generatePrerenderHandlerStubs(code, relativePath, id, isBuild)
-        );
-      }
-
-      // RSC build: record this module and its handler export names for chunk isolation
-      if (isBuild) {
-        const handlerPattern =
-          /export\s+const\s+(\w+)\s*=\s*createPrerenderHandler\s*(?:<[^>]*>)?\s*\(/g;
-        const exportNames: string[] = [];
-        let m: RegExpExecArray | null;
-        while ((m = handlerPattern.exec(code)) !== null) {
-          exportNames.push(m[1]);
-        }
-        if (exportNames.length > 0) {
-          prerenderHandlerModules.set(id, exportNames);
-        }
-      }
-
-      // RSC: inject $$id into calls (existing behavior)
-      return transformPrerenderHandlerExports(code, relativePath, id, isBuild);
-    },
-  };
-}