@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.15

package/dist/vite/index.js

@@ -10,225 +10,85 @@ import { mkdirSync, writeFileSync as writeFileSync2, readFileSync as readFileSyn
 import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from "node:fs";
 import { join, dirname, resolve, relative, basename as pathBasename } from "node:path";
 import picomatch from "picomatch";
-function extractRoutesFromSource(code) {
-  const routes = [];
-  const regex = /\bpath(?:\.[a-zA-Z_$][\w$]*)?\s*\(/g;
-  let match;
-  while ((match = regex.exec(code)) !== null) {
-    const result = parsePathCall(code, match.index + match[0].length);
-    if (result) routes.push(result);
-  }
-  return routes;
+import ts from "typescript";
+function getStringValue(node) {
+  if (ts.isStringLiteral(node)) return node.text;
+  if (ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  return null;
 }
-function generatePerModuleTypesSource(routes) {
-  const valid = routes.filter(({ name }) => {
-    if (!name || /["'\\`\n\r]/.test(name)) {
-      console.warn(`[rsc-router] Skipping route with invalid name: ${JSON.stringify(name)}`);
-      return false;
-    }
-    return true;
-  });
-  const deduped = /* @__PURE__ */ new Map();
-  for (const { name, pattern, search } of valid) {
-    deduped.set(name, { pattern, search });
+function extractObjectStringProperties(node) {
+  const result = {};
+  for (const prop of node.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    const key = ts.isIdentifier(prop.name) ? prop.name.text : ts.isStringLiteral(prop.name) ? prop.name.text : null;
+    if (!key) continue;
+    const val = getStringValue(prop.initializer);
+    if (val !== null) result[key] = val;
   }
-  const sorted = [...deduped.entries()].sort(([a], [b]) => a.localeCompare(b));
-  const body = sorted.map(([name, { pattern, search }]) => {
-    const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
-    if (search && Object.keys(search).length > 0) {
-      const searchBody = Object.entries(search).map(([k, v]) => `${k}: "${v}"`).join(", ");
-      return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
-    }
-    return `  ${key}: "${pattern}",`;
-  }).join("\n");
-  return `// Auto-generated by @rangojs/router - do not edit
-export const routes = {
-${body}
-} as const;
-export type routes = typeof routes;
-`;
+  return result;
 }
-function isWhitespace(ch) {
-  return ch === " " || ch === "	" || ch === "\n" || ch === "\r";
-}
-function readString(code, pos) {
-  const quote = code[pos];
-  if (quote !== '"' && quote !== "'") return null;
-  let value = "";
-  pos++;
-  while (pos < code.length) {
-    if (code[pos] === "\\") {
-      pos++;
-      if (pos < code.length) {
-        value += code[pos];
-        pos++;
-      }
-      continue;
-    }
-    if (code[pos] === quote) {
-      return { value, end: pos + 1 };
-    }
-    value += code[pos];
-    pos++;
+function extractParamsFromPattern(pattern) {
+  const params = {};
+  const regex = /:([a-zA-Z_$][\w$]*)(?:\([^)]+\))?(\?)?/g;
+  let match;
+  while ((match = regex.exec(pattern)) !== null) {
+    params[match[1]] = match[2] ? "string?" : "string";
   }
-  return null;
+  return Object.keys(params).length > 0 ? params : void 0;
 }
-function skipStringLiteral(code, pos) {
-  const quote = code[pos];
-  if (quote === "`") {
-    pos++;
-    while (pos < code.length) {
-      if (code[pos] === "\\") {
-        pos += 2;
-        continue;
-      }
-      if (code[pos] === "`") return pos + 1;
-      if (code[pos] === "$" && pos + 1 < code.length && code[pos + 1] === "{") {
-        pos += 2;
-        let braceDepth = 1;
-        while (pos < code.length && braceDepth > 0) {
-          if (code[pos] === "{") braceDepth++;
-          else if (code[pos] === "}") braceDepth--;
-          else if (code[pos] === "\\") pos++;
-          else if (code[pos] === '"' || code[pos] === "'" || code[pos] === "`") {
-            pos = skipStringLiteral(code, pos);
-            continue;
-          }
-          if (braceDepth > 0) pos++;
-        }
-        continue;
-      }
-      pos++;
-    }
-    return pos;
-  }
-  pos++;
-  while (pos < code.length) {
-    if (code[pos] === "\\") {
-      pos += 2;
-      continue;
-    }
-    if (code[pos] === quote) return pos + 1;
-    pos++;
+function formatRouteEntry(key, pattern, _params, search) {
+  const hasSearch = search && Object.keys(search).length > 0;
+  if (!hasSearch) {
+    return `  ${key}: "${pattern}",`;
   }
-  return pos;
+  const searchBody = Object.entries(search).map(([k, v]) => `${k}: "${v}"`).join(", ");
+  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
 }
-function matchesNameColon(code, pos) {
-  if (code.slice(pos, pos + 4) !== "name") return false;
-  if (pos > 0 && /\w/.test(code[pos - 1])) return false;
-  const afterName = pos + 4;
-  if (afterName < code.length && /\w/.test(code[afterName])) return false;
-  let checkPos = afterName;
-  while (checkPos < code.length && isWhitespace(code[checkPos])) checkPos++;
-  return code[checkPos] === ":";
-}
-function extractNameValue(code, pos) {
-  pos += 4;
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-  pos++;
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-  return readString(code, pos);
-}
-function matchesSearchColon(code, pos) {
-  if (code.slice(pos, pos + 6) !== "search") return false;
-  if (pos > 0 && /\w/.test(code[pos - 1])) return false;
-  const afterSearch = pos + 6;
-  if (afterSearch < code.length && /\w/.test(code[afterSearch])) return false;
-  let checkPos = afterSearch;
-  while (checkPos < code.length && isWhitespace(code[checkPos])) checkPos++;
-  return code[checkPos] === ":";
-}
-function extractSearchValue(code, pos) {
-  pos += 6;
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-  pos++;
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-  if (code[pos] !== "{") return null;
-  pos++;
-  const schema = {};
-  while (pos < code.length) {
-    while (pos < code.length && isWhitespace(code[pos])) pos++;
-    if (code[pos] === "}") return { value: schema, end: pos + 1 };
-    if (code[pos] === ",") {
-      pos++;
-      continue;
+function extractRoutesFromSource(code) {
+  const sourceFile = ts.createSourceFile("input.tsx", code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const routes = [];
+  function visit(node) {
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      const isPath = ts.isIdentifier(callee) && callee.text === "path" || ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === "path";
+      if (isPath && node.arguments.length >= 1) {
+        const route = extractRouteFromCallExpression(node);
+        if (route) routes.push(route);
+      }
     }
-    let key;
-    if (code[pos] === '"' || code[pos] === "'") {
-      const keyStr = readString(code, pos);
-      if (!keyStr) return null;
-      key = keyStr.value;
-      pos = keyStr.end;
-    } else {
-      const keyStart = pos;
-      while (pos < code.length && /[\w$]/.test(code[pos])) pos++;
-      if (pos === keyStart) return null;
-      key = code.slice(keyStart, pos);
-    }
-    while (pos < code.length && isWhitespace(code[pos])) pos++;
-    if (code[pos] !== ":") return null;
-    pos++;
-    while (pos < code.length && isWhitespace(code[pos])) pos++;
-    const valStr = readString(code, pos);
-    if (!valStr) return null;
-    schema[key] = valStr.value;
-    pos = valStr.end;
+    ts.forEachChild(node, visit);
   }
-  return null;
+  visit(sourceFile);
+  return routes;
 }
-function parsePathCall(code, pos) {
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-  const patternStr = readString(code, pos);
-  if (!patternStr) return null;
-  const pattern = patternStr.value;
-  pos = patternStr.end;
-  let depth = 1;
+function extractRouteFromCallExpression(node) {
+  const patternNode = node.arguments[0];
+  const pattern = getStringValue(patternNode);
+  if (pattern === null) return null;
   let name = null;
   let search;
-  while (pos < code.length && depth > 0) {
-    const ch = code[pos];
-    if (isWhitespace(ch)) {
-      pos++;
-      continue;
-    }
-    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
-      pos += 2;
-      while (pos < code.length && code[pos] !== "\n") pos++;
-      continue;
-    }
-    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
-      pos += 2;
-      while (pos < code.length - 1 && !(code[pos] === "*" && code[pos + 1] === "/"))
-        pos++;
-      pos += 2;
-      continue;
-    }
-    if (depth === 2 && ch === "n" && matchesNameColon(code, pos)) {
-      const nameResult = extractNameValue(code, pos);
-      if (nameResult) {
-        name = nameResult.value;
-        pos = nameResult.end;
-        continue;
-      }
-    }
-    if (depth === 2 && ch === "s" && matchesSearchColon(code, pos)) {
-      const searchResult = extractSearchValue(code, pos);
-      if (searchResult) {
-        search = searchResult.value;
-        pos = searchResult.end;
-        continue;
+  for (let i = 1; i < node.arguments.length; i++) {
+    const arg = node.arguments[i];
+    if (ts.isObjectLiteralExpression(arg)) {
+      for (const prop of arg.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const propName = ts.isIdentifier(prop.name) ? prop.name.text : null;
+        if (propName === "name") {
+          name = getStringValue(prop.initializer);
+        } else if (propName === "search" && ts.isObjectLiteralExpression(prop.initializer)) {
+          search = extractObjectStringProperties(prop.initializer);
+        }
       }
     }
-    if (ch === '"' || ch === "`" || ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1]))) {
-      pos = skipStringLiteral(code, pos);
-      continue;
-    }
-    if (ch === "(" || ch === "{" || ch === "[") depth++;
-    else if (ch === ")" || ch === "}" || ch === "]") depth--;
-    pos++;
   }
-  if (name === null) return null;
-  return { name, pattern, ...search ? { search } : {} };
+  if (!name) return null;
+  const params = extractParamsFromPattern(pattern);
+  return {
+    name,
+    pattern,
+    ...params ? { params } : {},
+    ...search && Object.keys(search).length > 0 ? { search } : {}
+  };
 }
 function generateRouteTypesSource(routeManifest, searchSchemas) {
   const entries = Object.entries(routeManifest).sort(
@@ -236,12 +96,9 @@ function generateRouteTypesSource(routeManifest, searchSchemas) {
   );
   const objectBody = entries.map(([name, pattern]) => {
     const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
+    const params = extractParamsFromPattern(pattern);
     const search = searchSchemas?.[name];
-    if (search && Object.keys(search).length > 0) {
-      const searchBody = Object.entries(search).map(([k, v]) => `${k}: "${v}"`).join(", ");
-      return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
-    }
-    return `  ${key}: "${pattern}",`;
+    return formatRouteEntry(key, pattern, params, search);
   }).join("\n");
   return `// Auto-generated by @rangojs/router - do not edit
 export const NamedRoutes = {
@@ -299,88 +156,41 @@ function findTsFiles(dir, filter) {
   }
   return results;
 }
-function writePerModuleRouteTypes(root, filter) {
-  const files = findTsFiles(root, filter);
-  for (const filePath of files) {
-    writePerModuleRouteTypesForFile(filePath);
-  }
-}
-function writePerModuleRouteTypesForFile(filePath) {
-  try {
-    const source = readFileSync(filePath, "utf-8");
-    if (!source.includes("urls(")) return;
-    const routes = extractRoutesFromSource(source);
-    if (routes.length === 0) return;
-    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
-    const genSource = generatePerModuleTypesSource(routes);
-    const existing = existsSync(genPath) ? readFileSync(genPath, "utf-8") : null;
-    if (existing !== genSource) {
-      writeFileSync(genPath, genSource);
-      console.log(`[rsc-router] Generated route types -> ${genPath}`);
-    }
-  } catch (err) {
-    console.warn(`[rsc-router] Failed to generate route types for ${filePath}: ${err.message}`);
-  }
-}
 function extractIncludesFromSource(code) {
+  const sourceFile = ts.createSourceFile("input.tsx", code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
   const results = [];
-  const regex = /\binclude\s*\(/g;
-  let match;
-  while ((match = regex.exec(code)) !== null) {
-    const result = parseIncludeCall(code, match.index + match[0].length);
-    if (result) results.push(result);
+  function visit(node) {
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (ts.isIdentifier(callee) && callee.text === "include") {
+        const result = extractIncludeFromCallExpression(node);
+        if (result) results.push(result);
+      }
+    }
+    ts.forEachChild(node, visit);
   }
+  visit(sourceFile);
   return results;
 }
-function parseIncludeCall(code, pos) {
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-  const prefixStr = readString(code, pos);
-  if (!prefixStr) return null;
-  const pathPrefix = prefixStr.value;
-  pos = prefixStr.end;
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-  if (pos >= code.length || code[pos] !== ",") return null;
-  pos++;
-  while (pos < code.length && isWhitespace(code[pos])) pos++;
-  const varStart = pos;
-  while (pos < code.length && /[\w$]/.test(code[pos])) pos++;
-  if (pos === varStart) return null;
-  const variableName = code.slice(varStart, pos);
+function extractIncludeFromCallExpression(node) {
+  if (node.arguments.length < 2) return null;
+  const pathPrefix = getStringValue(node.arguments[0]);
+  if (pathPrefix === null) return null;
+  const secondArg = node.arguments[1];
+  if (!ts.isIdentifier(secondArg)) return null;
+  const variableName = secondArg.text;
   let namePrefix = null;
-  let depth = 1;
-  while (pos < code.length && depth > 0) {
-    const ch = code[pos];
-    if (isWhitespace(ch)) {
-      pos++;
-      continue;
-    }
-    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
-      pos += 2;
-      while (pos < code.length && code[pos] !== "\n") pos++;
-      continue;
-    }
-    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
-      pos += 2;
-      while (pos < code.length - 1 && !(code[pos] === "*" && code[pos + 1] === "/"))
-        pos++;
-      pos += 2;
-      continue;
-    }
-    if (depth === 2 && ch === "n" && matchesNameColon(code, pos)) {
-      const nameResult = extractNameValue(code, pos);
-      if (nameResult) {
-        namePrefix = nameResult.value;
-        pos = nameResult.end;
-        continue;
+  if (node.arguments.length >= 3) {
+    const thirdArg = node.arguments[2];
+    if (ts.isObjectLiteralExpression(thirdArg)) {
+      for (const prop of thirdArg.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const propName = ts.isIdentifier(prop.name) ? prop.name.text : null;
+        if (propName === "name") {
+          namePrefix = getStringValue(prop.initializer);
+        }
       }
     }
-    if (ch === '"' || ch === "`" || ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1]))) {
-      pos = skipStringLiteral(code, pos);
-      continue;
-    }
-    if (ch === "(" || ch === "{" || ch === "[") depth++;
-    else if (ch === ")" || ch === "}" || ch === "]") depth--;
-    pos++;
   }
   return { pathPrefix, variableName, namePrefix };
 }
@@ -417,41 +227,22 @@ function resolveImportPath(importSpec, fromFile) {
   }
   return null;
 }
-function escapeRegExp(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function extractUrlsBlockForVariable(code, varName) {
-  const pattern = new RegExp(
-    `(?:export\\s+)?(?:const|let|var)\\s+${escapeRegExp(varName)}\\s*=\\s*urls\\s*\\(`
-  );
-  const match = pattern.exec(code);
-  if (!match) return null;
-  const openParen = match.index + match[0].length - 1;
-  let depth = 1;
-  let pos = openParen + 1;
-  while (pos < code.length && depth > 0) {
-    const ch = code[pos];
-    if (ch === '"' || ch === "`" || ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1]))) {
-      pos = skipStringLiteral(code, pos);
-      continue;
-    }
-    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
-      pos += 2;
-      while (pos < code.length && code[pos] !== "\n") pos++;
-      continue;
-    }
-    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
-      pos += 2;
-      while (pos < code.length - 1 && !(code[pos] === "*" && code[pos + 1] === "/"))
-        pos++;
-      pos += 2;
-      continue;
+  const sourceFile = ts.createSourceFile("input.tsx", code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  let result = null;
+  function visit(node) {
+    if (result) return;
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === varName && node.initializer && ts.isCallExpression(node.initializer)) {
+      const callee = node.initializer.expression;
+      if (ts.isIdentifier(callee) && callee.text === "urls") {
+        result = node.initializer.getText(sourceFile);
+        return;
+      }
     }
-    if (ch === "(" || ch === "{" || ch === "[") depth++;
-    else if (ch === ")" || ch === "}" || ch === "]") depth--;
-    pos++;
+    ts.forEachChild(node, visit);
   }
-  return code.slice(openParen, pos);
+  visit(sourceFile);
+  return result;
 }
 function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSchemasOut) {
   const routeMap = {};
@@ -499,7 +290,10 @@ function buildCombinedRouteMapWithSearch(filePath, variableName, visited) {
   visited = visited ?? /* @__PURE__ */ new Set();
   const realPath = resolve(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
-  if (visited.has(key)) return { routes: {}, searchSchemas: {} };
+  if (visited.has(key)) {
+    console.warn(`[rsc-router] Circular include detected, skipping: ${key}`);
+    return { routes: {}, searchSchemas: {} };
+  }
   visited.add(key);
   let source;
   try {
@@ -609,7 +403,7 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
     );
     if (existing !== source) {
       if (opts?.preserveIfLarger && existing) {
-        const existingCount = (existing.match(/^\s+["a-zA-Z_$][^:]*:\s*"/gm) || []).length;
+        const existingCount = (existing.match(/^\s+["a-zA-Z_$][^:]*:\s*["{]/gm) || []).length;
         const newCount = Object.keys(result.routes).length;
         if (existingCount > newCount) {
           continue;
@@ -1167,7 +961,7 @@ var STRICT_CREATE_CONFIGS = [
   { fnName: "createHandle" },
   { fnName: "createLocationState" }
 ];
-function escapeRegExp2(input) {
+function escapeRegExp(input) {
   return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function isExportOnlyFile(code, bindings) {
@@ -1200,7 +994,7 @@ function isExportOnlyFile(code, bindings) {
 }
 function countCreateCallsForNames(code, fnNames) {
   const pattern = new RegExp(
-    `\\b(?:${fnNames.map(escapeRegExp2).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`,
+    `\\b(?:${fnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`,
     "g"
   );
   return (code.match(pattern) || []).length;
@@ -1233,7 +1027,7 @@ function getCalledIdentifierFromCall(callExpr) {
   return null;
 }
 function collectCreateExportBindingsFallback(code, fnNames) {
-  const alternation = fnNames.map(escapeRegExp2).join("|");
+  const alternation = fnNames.map(escapeRegExp).join("|");
   const exportConstPattern = new RegExp(
     `export\\s+const\\s+(\\w+)\\s*=\\s*(?:${alternation})\\s*(?:<[^>]*>)?\\s*\\(`,
     "g"
@@ -1484,7 +1278,7 @@ ${binding.localName}.$$id = "${handlerId}";`;
 }
 function transformRouter(code, filePath, routerFnNames) {
   const pat = new RegExp(
-    `\\b(?:${routerFnNames.map(escapeRegExp2).join("|")})\\s*(?:<[^>]*>)?\\s*\\(`,
+    `\\b(?:${routerFnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>)?\\s*\\(`,
     "g"
   );
   let match;
@@ -1984,7 +1778,7 @@ import { resolve as resolve2 } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.13",
+  version: "0.0.0-experimental.15",
   type: "module",
   description: "Django-inspired RSC router with composable URL patterns",
   author: "Ivo Todorov",
@@ -2717,7 +2511,6 @@ Set an explicit \`id\` on createRouter() or check the call site.`
         });
       }
       if (opts?.staticRouteTypesGeneration !== false) {
-        writePerModuleRouteTypes(projectRoot, scanFilter);
         cachedRouterFiles = findRouterFiles(projectRoot, scanFilter);
         writeCombinedRouteTypes(projectRoot, cachedRouterFiles, { preserveIfLarger: true });
       }
@@ -2870,9 +2663,6 @@ ${err.stack}`
             const hasUrls = source.includes("urls(");
             const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
             if (!hasUrls && !hasCreateRouter) return;
-            if (hasUrls) {
-              writePerModuleRouteTypesForFile(filePath);
-            }
             if (hasCreateRouter) {
               cachedRouterFiles = void 0;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.13",
+  "version": "0.0.0-experimental.15",
   "type": "module",
   "description": "Django-inspired RSC router with composable URL patterns",
   "author": "Ivo Todorov",

package/skills/rango/SKILL.md

@@ -30,6 +30,7 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 | `/response-routes` | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()` |
 | `/mime-routes` | Content negotiation — same URL, different response types via Accept header |
 | `/fonts` | Load web fonts with preload hints |
+| `/testing` | Unit test route trees with `buildRouteTree()` |
 
 ## Quick Start
 
@@ -52,3 +53,65 @@ export default createRouter({ document: Document }).urls(urlpatterns);
 ```
 
 Use `/typesafety` for type-safe href and environment setup.
+
+## CLI: `npx rango generate`
+
+Single command to generate `.gen.ts` route type files. Auto-detects file type and
+generates the appropriate output.
+
+```bash
+# Single file
+npx rango generate src/urls.tsx
+
+# Multiple files
+npx rango generate src/router.tsx src/urls.tsx
+
+# Directory (recursive scan)
+npx rango generate src/
+
+# Mix of files and directories
+npx rango generate src/urls.tsx src/api/
+```
+
+### Auto-detection
+
+Each file is classified by its contents:
+
+| Contains | Generated output |
+|----------|-----------------|
+| `urls(` | Per-module `*.gen.ts` with route names, patterns, params, search |
+| `createRouter` | Per-router `*.named-routes.gen.ts` with global route map |
+| Both | Both files |
+
+Directories are scanned recursively for `.ts`/`.tsx` files, skipping `node_modules`,
+dotfiles, and existing `.gen.` files.
+
+### Recursive includes
+
+The generator follows `include()` calls across files, resolving imports to build
+the full route tree. Circular includes are detected and warned about.
+
+### First-wins deduplication
+
+When a route name appears more than once, the first definition wins and duplicates
+are dropped with a warning. This applies only to the generated `.gen.ts` type files.
+Define the primary route before any fallback variant that reuses the same name.
+
+Content negotiation (see `/mime-routes`) is unaffected — negotiated routes use
+distinct names (e.g. `"product"` and `"productJson"`) and the Accept header
+dispatching happens at runtime in the trie, not in the type generator.
+
+### Limitations
+
+The CLI uses static source analysis (AST walking), not runtime execution. It cannot
+extract routes defined dynamically:
+
+- `Array.from()` or `.map()` generating path() calls
+- Conditional routes behind `import.meta.env` or feature flags
+- Routes computed from external data (databases, config files)
+- Template literal patterns with interpolated variables
+
+These routes are only discovered by the Vite plugin's runtime discovery during
+`pnpm dev` or `pnpm build`. The CLI-generated `.gen.ts` may have fewer routes
+than the runtime-generated version. During dev, the `preserveIfLarger` guard
+prevents the static parser from overwriting a larger runtime-discovered file.