@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/vite/{expose-id-utils.ts → plugins/expose-id-utils.ts}

@@ -8,30 +8,26 @@ 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}`;
 }
 
-/**
- * Generate an 8-char hex hash for an inline static handler call site.
- * Uses file path and line number (plus optional index for same-line collisions).
- */
+export function makeStubId(
+  filePath: string,
+  exportName: string,
+  isBuild: boolean,
+): string {
+  return isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
+}
+
 export function hashInlineId(
   filePath: string,
-  lineNumber: number,
-  index?: number,
+  fnName: string,
+  index: number,
 ): string {
-  const input =
-    index !== undefined && index > 0
-      ? `${filePath}:${lineNumber}:${index}`
-      : `${filePath}:${lineNumber}`;
+  const input = `${filePath}:${fnName}:${index}`;
   return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
 }
 
@@ -45,11 +41,6 @@ export interface DetectedImports {
   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[]>();
 
@@ -89,10 +80,6 @@ export function buildExportMap(program: any): Map<string, string[]> {
   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 =
@@ -119,7 +106,6 @@ export function detectImports(code: string): DetectedImports {
     if (/\bcreateRouter\b/.test(imports)) result.router = true;
   }
 
-  // createRouter has a stricter check: only from "@rangojs/router" (not sub-paths)
   if (result.router) {
     result.router =
       /import\s*\{[^}]*\bcreateRouter\b[^}]*\}\s*from\s*["']@rangojs\/router["']/.test(
@@ -138,11 +124,6 @@ export function detectImports(code: string): DetectedImports {
   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];
 
@@ -200,11 +181,6 @@ export function skipStringOrComment(code: string, pos: number): number {
   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;
@@ -221,10 +197,6 @@ export function findMatchingParen(code: string, startPos: number): number {
   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,
@@ -238,7 +210,16 @@ export function countArgs(
   while (i < endPos) {
     const skipped = skipStringOrComment(code, i);
     if (skipped > i) {
-      hasContent = true;
+      // A comment is transparent: `createHandle(/* meta */)` has ZERO real
+      // arguments, so a comment-only region must NOT set hasContent (else the
+      // fallback path would count it as 1 arg and inject `, "id"` over an elided
+      // first slot — a syntax error). A string/template literal IS content.
+      const ch = code[i];
+      const isComment =
+        ch === "/" &&
+        i + 1 < code.length &&
+        (code[i + 1] === "/" || code[i + 1] === "*");
+      if (!isComment) hasContent = true;
       i = skipped;
       continue;
     }
@@ -260,10 +241,6 @@ export function countArgs(
   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])) {
@@ -275,48 +252,81 @@ export function findStatementEnd(code: string, pos: number): number {
   return i;
 }
 
-/**
- * Simple depth-counter paren matching. Does NOT skip strings/comments.
- * Used by loader and handle transforms where the simpler approach suffices.
- * Returns the index after the closing paren.
- */
-export function findClosingParen(code: string, startPos: number): number {
-  let depth = 1;
-  let i = startPos;
-  while (i < code.length && depth > 0) {
-    if (code[i] === "(") depth++;
-    if (code[i] === ")") depth--;
-    i++;
-  }
-  return i;
-}
+export { escapeRegExp } from "../../regex-escape.js";
 
 /**
- * Count arguments using simple depth counting (no string/comment awareness).
- * Used by the loader transform where the original code used this simpler approach.
+ * Given an index pointing just past a `create*` callee identifier, return the
+ * index of the call's opening `(`, accounting for an optional generic type
+ * argument list `<...>` with arbitrarily nested `<>`. Returns -1 when the next
+ * non-trivia token is neither `<` nor `(` (i.e. not a call site).
+ *
+ * Replaces the single-level `<[^>]*>` regex assumption, which stopped at the
+ * first `>` and so never reached `(` for `createRouter<Config<Env>>(`.
+ *
+ * Whitespace, comments, and strings between the callee and `(` are skipped via
+ * skipStringOrComment. The `<...>` scan only balances angle brackets; it does
+ * not attempt to parse full TS type syntax (sufficient for locating the paren).
  */
-export function countArgsSimple(
+export function findCallParenAfterGenerics(
   code: string,
-  startPos: number,
-  endPos: number,
+  afterCalleeIndex: number,
 ): number {
-  let depth = 0;
-  let argCount = 0;
-  let hasContent = false;
+  let i = afterCalleeIndex;
+  // Skip leading whitespace/comments/strings before `<` or `(`.
+  while (i < code.length) {
+    const skipped = skipStringOrComment(code, i);
+    if (skipped > i) {
+      i = skipped;
+      continue;
+    }
+    if (/\s/.test(code[i])) {
+      i++;
+      continue;
+    }
+    break;
+  }
 
-  for (let i = startPos; i < endPos; i++) {
-    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;
+  if (i >= code.length) return -1;
+
+  if (code[i] === "(") return i;
+
+  if (code[i] === "<") {
+    let depth = 0;
+    while (i < code.length) {
+      const skipped = skipStringOrComment(code, i);
+      if (skipped > i) {
+        i = skipped;
+        continue;
+      }
+      const ch = code[i];
+      if (ch === "<") {
+        depth++;
+      } else if (ch === ">") {
+        depth--;
+        if (depth === 0) {
+          i++;
+          break;
+        }
+      }
+      i++;
+    }
+    if (depth !== 0) return -1;
+    // After the balanced generic list, skip trivia and expect `(`.
+    while (i < code.length) {
+      const skipped = skipStringOrComment(code, i);
+      if (skipped > i) {
+        i = skipped;
+        continue;
+      }
+      if (/\s/.test(code[i])) {
+        i++;
+        continue;
+      }
+      break;
     }
+    if (i < code.length && code[i] === "(") return i;
+    return -1;
   }
 
-  return hasContent ? argCount + 1 : 0;
+  return -1;
 }

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

@@ -0,0 +1,363 @@
+import { parseAst } from "vite";
+import {
+  findMatchingParen,
+  countArgs,
+  findStatementEnd,
+  buildExportMap,
+  escapeRegExp,
+  findCallParenAfterGenerics,
+} from "../expose-id-utils.js";
+import { codeMatchIndices } from "../../../build/route-types/source-scan.js";
+import type { CreateExportBinding } from "./types.js";
+
+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);
+  }
+
+  if (/export\s*\*/.test(code)) return false;
+
+  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;
+  }
+
+  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;
+}
+
+// Matches the callee identifier only. The optional generic argument list
+// (which may be nested, e.g. createLoader<A<B>>(...)) and the call paren are
+// resolved per match via findCallParenAfterGenerics, so a nested `>` no longer
+// defeats the scan the way `<[^>]*>` did (it stopped at the first `>`).
+function createCallPattern(fnNames: string[]): RegExp {
+  return new RegExp(`\\b(?:${fnNames.map(escapeRegExp).join("|")})\\b`, "g");
+}
+
+/**
+ * Byte offsets of every create*-call site in real code: a callee-identifier
+ * match that is actually followed by a call `(` (after an optional nested
+ * generic list). Non-call references (type positions, the import specifier
+ * itself) yield -1 from findCallParenAfterGenerics and are dropped.
+ */
+function createCallStartIndices(code: string, fnNames: string[]): number[] {
+  return codeMatchIndices(code, createCallPattern(fnNames)).filter(
+    (index) =>
+      findCallParenAfterGenerics(
+        code,
+        index + matchedNameLength(code, index),
+      ) !== -1,
+  );
+}
+
+// Length of the identifier match at `index` (run of identifier chars).
+function matchedNameLength(code: string, index: number): number {
+  let i = index;
+  while (i < code.length && /[A-Za-z0-9_$]/.test(code[i])) i++;
+  return i - index;
+}
+
+export function countCreateCallsForNames(
+  code: string,
+  fnNames: string[],
+): number {
+  return createCallStartIndices(code, fnNames).length;
+}
+
+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 };
+}
+
+export function findUnsupportedCreateCallSites(
+  code: string,
+  fnNames: string[],
+  supportedBindings: CreateExportBinding[],
+): Array<{ line: number; column: number }> {
+  const supported = new Set(supportedBindings.map((b) => b.callExprStart));
+  return createCallStartIndices(code, 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;
+}
+
+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);
+    }
+  }
+
+  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}".`];
+
+  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");
+}