@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/src/vite/plugins/expose-id-utils.ts

@@ -0,0 +1,303 @@
+import path from "node:path";
+import crypto from "node:crypto";
+
+/**
+ * Normalize path to forward slashes.
+ */
+export function normalizePath(p: string): string {
+  return p.split(path.sep).join("/");
+}
+
+/**
+ * Generate a short hash for an ID.
+ * Uses first 8 chars of SHA-256 hash for uniqueness while keeping IDs short.
+ * Appends export name for easier debugging in production: "abc123#ExportName"
+ */
+export function hashId(filePath: string, exportName: string): string {
+  const input = `${filePath}#${exportName}`;
+  const hash = crypto.createHash("sha256").update(input).digest("hex");
+  return `${hash.slice(0, 8)}#${exportName}`;
+}
+
+/**
+ * Build a stable ID for an export binding. Uses hashed IDs in production
+ * builds (short + opaque) and readable path#name IDs in dev.
+ */
+export function makeStubId(
+  filePath: string,
+  exportName: string,
+  isBuild: boolean,
+): string {
+  return isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
+}
+
+/**
+ * Generate an 8-char hex hash for an inline handler call site.
+ *
+ * Keyed on the source-order INDEX of the call (the Nth inline `fnName(...)` in
+ * the file), NOT its line number. Line numbers shift between the prerender
+ * build context and the production build context (preceding transforms differ,
+ * e.g. plugin-react boilerplate), which would desync the prerender manifest key
+ * from the runtime handler id and break prerender/static freezing. The
+ * source-order index is invariant to line shifts; `fnName` keeps Static and
+ * Prerender inline ids from colliding at the same index.
+ */
+export function hashInlineId(
+  filePath: string,
+  fnName: string,
+  index: number,
+): string {
+  const input = `${filePath}:${fnName}:${index}`;
+  return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
+}
+
+export interface DetectedImports {
+  loader: boolean;
+  handle: boolean;
+  locationState: boolean;
+  prerenderHandler: boolean;
+  staticHandler: boolean;
+  router: boolean;
+  any: boolean;
+}
+
+/**
+ * Build a map from local binding name to exported names by walking
+ * ExportNamedDeclaration nodes. Handles `export const X`, `export { X }`,
+ * and `export { X as Y }`. Skips re-exports (`export { X } from "..."`).
+ */
+export function buildExportMap(program: any): Map<string, string[]> {
+  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]);
+  };
+
+  for (const node of program.body ?? []) {
+    if (node?.type !== "ExportNamedDeclaration") continue;
+
+    if (node.declaration?.type === "VariableDeclaration") {
+      for (const decl of node.declaration.declarations ?? []) {
+        if (decl?.id?.type === "Identifier") {
+          pushExport(decl.id.name, decl.id.name);
+        }
+      }
+    }
+
+    if (!node.source && Array.isArray(node.specifiers)) {
+      for (const spec of node.specifiers) {
+        if (
+          spec?.type === "ExportSpecifier" &&
+          spec.local?.type === "Identifier" &&
+          spec.exported?.type === "Identifier"
+        ) {
+          pushExport(spec.local.name, spec.exported.name);
+        }
+      }
+    }
+  }
+
+  return exportMap;
+}
+
+/**
+ * Single-pass detection of all create* imports from @rangojs/router.
+ * Returns which create functions are imported so we can skip unnecessary transforms.
+ */
+export function detectImports(code: string): DetectedImports {
+  // Extract all import declarations from @rangojs/router in one scan
+  const importPattern =
+    /import\s*\{([^}]*)\}\s*from\s*["']@rangojs\/router(?:\/[^"']*)?["']/g;
+
+  const result: DetectedImports = {
+    loader: false,
+    handle: false,
+    locationState: false,
+    prerenderHandler: false,
+    staticHandler: false,
+    router: false,
+    any: false,
+  };
+
+  let match: RegExpExecArray | null;
+  while ((match = importPattern.exec(code)) !== null) {
+    const imports = match[1];
+    if (/\bcreateLoader\b/.test(imports)) result.loader = true;
+    if (/\bcreateHandle\b/.test(imports)) result.handle = true;
+    if (/\bcreateLocationState\b/.test(imports)) result.locationState = true;
+    if (/\bPrerender\b/.test(imports)) result.prerenderHandler = true;
+    if (/\bStatic\b/.test(imports)) result.staticHandler = true;
+    if (/\bcreateRouter\b/.test(imports)) result.router = true;
+  }
+
+  // createRouter has a stricter check: only from "@rangojs/router" (not sub-paths).
+  // NOTE: This is intentional — detectImports is used as a fast pre-filter in
+  // exposeInternalIds (which does NOT handle router transforms). The separate
+  // exposeRouterId plugin handles createRouter and DOES accept the /server subpath.
+  if (result.router) {
+    result.router =
+      /import\s*\{[^}]*\bcreateRouter\b[^}]*\}\s*from\s*["']@rangojs\/router["']/.test(
+        code,
+      );
+  }
+
+  result.any =
+    result.loader ||
+    result.handle ||
+    result.locationState ||
+    result.prerenderHandler ||
+    result.staticHandler ||
+    result.router;
+
+  return result;
+}
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+}
+
+/**
+ * Find the end of a statement: skip whitespace and optional semicolon after
+ * a closing paren position.
+ */
+export function findStatementEnd(code: string, pos: number): number {
+  let i = pos;
+  while (i < code.length && /\s/.test(code[i])) {
+    i++;
+  }
+  if (i < code.length && code[i] === ";") {
+    i++;
+  }
+  return i;
+}
+
+/**
+ * Escape special regex characters in a string so it can be safely
+ * interpolated into a RegExp pattern.
+ */
+export function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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

@@ -0,0 +1,376 @@
+import { parseAst } from "vite";
+import {
+  findMatchingParen,
+  countArgs,
+  findStatementEnd,
+  buildExportMap,
+  escapeRegExp,
+} from "../expose-id-utils.js";
+import { codeMatchIndices } from "../../../build/route-types/source-scan.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;
+}
+
+function createCallPattern(fnNames: string[]): RegExp {
+  return new RegExp(
+    `\\b(?:${fnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`,
+    "g",
+  );
+}
+
+// Counts real create*() call sites, ignoring occurrences inside comments and
+// string literals. Used by the unsupported-shape warning heuristic and the
+// inline-extraction pre-check.
+export function countCreateCallsForNames(
+  code: string,
+  fnNames: string[],
+): number {
+  return codeMatchIndices(code, createCallPattern(fnNames)).length;
+}
+
+/** Convert a 0-based byte offset to a 1-based { line, column }. */
+export function offsetToLineColumn(
+  code: string,
+  index: number,
+): { line: number; column: number } {
+  let line = 1;
+  let lineStart = 0;
+  const end = Math.min(index, code.length);
+  for (let i = 0; i < end; i++) {
+    if (code[i] === "\n") {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: index - lineStart + 1 };
+}
+
+/**
+ * Locate every real create*() call site (comment/string-free) that is NOT one
+ * of the supported, id-injectable export bindings, returning each as a 1-based
+ * { line, column }. The empty result means every call is in a supported shape.
+ * Both binding-collection paths anchor `callExprStart` at the start of the
+ * create* identifier — exactly where this pattern matches — so the set
+ * difference is exact.
+ */
+export function findUnsupportedCreateCallSites(
+  code: string,
+  fnNames: string[],
+  supportedBindings: CreateExportBinding[],
+): Array<{ line: number; column: number }> {
+  const supported = new Set(supportedBindings.map((b) => b.callExprStart));
+  return codeMatchIndices(code, createCallPattern(fnNames))
+    .filter((index) => !supported.has(index))
+    .map((index) => offsetToLineColumn(code, index));
+}
+
+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;
+}
+
+/**
+ * plugin-react's dev Fast Refresh wraps exports whose function body uses
+ * hook-like calls in a signature-registration call. A loader/handle that calls
+ * `ctx.use(...)` trips this heuristic, so `export const X = createLoader(...)`
+ * becomes `export const X = _s(createLoader(...), "<sig>", true)` — the create*
+ * call is the first argument of an unrelated wrapper call. Unwrap a single such
+ * layer so ID injection still targets the inner create* call. The `$$id`
+ * assignment is appended after the whole statement (against the export local),
+ * which is unaffected by the wrapper since `_s(x)` returns `x`.
+ */
+function unwrapSignatureWrappedCall(init: any, fnNameSet: Set<string>): any {
+  if (init?.type !== "CallExpression") return init;
+  const directId = getCalledIdentifierFromCall(init);
+  if (directId && fnNameSet.has(directId)) return init;
+  const firstArg = init.arguments?.[0];
+  if (firstArg?.type === "CallExpression") {
+    const innerId = getCalledIdentifierFromCall(firstArg);
+    if (innerId && fnNameSet.has(innerId)) return firstArg;
+  }
+  return init;
+}
+
+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, { lang: "tsx" });
+    } 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 ?? []) {
+      // Unwrap a Fast Refresh signature wrapper (`_s(createLoader(...), ...)`)
+      // so injection targets the inner create* call. Falls back to decl.init.
+      const callExpr = unwrapSignatureWrappedCall(decl?.init, fnNameSet);
+      const calledIdentifier = getCalledIdentifierFromCall(callExpr);
+      if (
+        decl?.id?.type !== "Identifier" ||
+        callExpr?.type !== "CallExpression" ||
+        !calledIdentifier ||
+        !fnNameSet.has(calledIdentifier)
+      ) {
+        continue;
+      }
+
+      const localName = decl.id.name;
+      const exportNames = exportMap.get(localName) ?? [];
+      if (exportNames.length === 0) continue;
+
+      const callEnd = callExpr.end as number;
+      const calleeEnd = callExpr.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: callExpr.start as number,
+        callOpenParenPos: openParenPos,
+        callCloseParenPos: closeParenPos,
+        argCount: callExpr.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,
+  sites: Array<{ line: number; column: number }> = [],
+): string {
+  const lines = [`[rango] Unsupported ${fnName} shape in "${filePath}".`];
+
+  // Point at the exact call(s) so the location is clickable in the terminal/IDE
+  // (file:line:column) instead of leaving the user to scan the whole file.
+  if (sites.length === 1) {
+    const s = sites[0];
+    lines.push(
+      `The ${fnName}(...) call at ${filePath}:${s.line}:${s.column} has no stable $$id injected — it is not in a supported shape.`,
+    );
+  } else if (sites.length > 1) {
+    lines.push(
+      `These ${fnName}(...) calls have no stable $$id injected — they are not in a supported shape:`,
+    );
+    for (const s of sites) lines.push(`  - ${filePath}:${s.line}:${s.column}`);
+  }
+
+  lines.push(
+    `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`,
+  );
+  return lines.join("\n");
+}