@rangojs/router 0.0.0-experimental.debug-cache-fix → 0.0.0-experimental.df410dd5

package/src/build/route-types/per-module-writer.ts

@@ -97,7 +97,10 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       routes = extractRoutesFromSource(source);
     }
 
-    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    // Match .ts/.tsx/.js/.jsx (same as router-processing.ts / router-transform.ts).
+    // Without the jsx? branch a .jsx/.js source produced genPath === filePath,
+    // overwriting the source file instead of writing a sibling .gen.ts.
+    const genPath = filePath.replace(/\.(tsx?|jsx?)$/, ".gen.ts");
 
     // When a urls() variable was found but static resolution yields zero
     // routes, write an empty placeholder so generated imports stay
@@ -106,7 +109,7 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       if (varNames.length > 0 && !existsSync(genPath)) {
         writeFileSync(genPath, generatePerModuleTypesSource([]));
         console.log(
-          `[rsc-router] Generated route types (placeholder) -> ${genPath}`,
+          `[rango] Generated route types (placeholder) -> ${genPath}`,
         );
       }
       return;
@@ -118,11 +121,11 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       : null;
     if (existing !== genSource) {
       writeFileSync(genPath, genSource);
-      console.log(`[rsc-router] Generated route types -> ${genPath}`);
+      console.log(`[rango] Generated route types -> ${genPath}`);
     }
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to generate route types for ${filePath}: ${(err as Error).message}`,
+      `[rango] Failed to generate route types for ${filePath}: ${(err as Error).message}`,
     );
   }
 }

package/src/build/route-types/router-processing.ts

@@ -15,6 +15,7 @@ import {
 import ts from "typescript";
 import { generateRouteTypesSource } from "./codegen.js";
 import type { ScanFilter } from "./scan-filter.js";
+import { firstCodeMatchIndex } from "./source-scan.js";
 import {
   resolveImportedVariable,
   resolveImportPath,
@@ -38,6 +39,8 @@ function countPublicRouteEntries(source: string): number {
 }
 
 const ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+// Global variant for the code-region scan (firstCodeMatchIndex sets lastIndex).
+const ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
 
 function isRoutableSourceFile(name: string): boolean {
   return (
@@ -61,7 +64,7 @@ function findRouterFilesRecursive(
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return;
   }
@@ -90,7 +93,17 @@ function findRouterFilesRecursive(
 
     try {
       const source = readFileSync(fullPath, "utf-8");
-      if (ROUTER_CALL_PATTERN.test(source)) {
+      // Fast path: most files contain no `createRouter(` at all, so the cheap
+      // raw regex short-circuits before the code-region scan. Only a file that
+      // mentions the token (real call OR a comment/string mention) is rescanned
+      // over code regions — allocation-free, never building a stripped copy —
+      // so a mention inside a comment or string is not mistaken for a real
+      // router file (which previously triggered a spurious "Multiple routers
+      // found" error).
+      if (
+        ROUTER_CALL_PATTERN.test(source) &&
+        firstCodeMatchIndex(source, ROUTER_CALL_PATTERN_G) >= 0
+      ) {
         routerFilesInDir.push(fullPath);
       }
     } catch {
@@ -142,7 +155,7 @@ export function findNestedRouterConflict(
 
 export function formatNestedRouterConflictError(
   conflict: { ancestor: string; nested: string },
-  prefix = "[rsc-router]",
+  prefix = "[rango]",
 ): string {
   return (
     `${prefix} Nested router roots are not supported.\n` +
@@ -157,13 +170,26 @@ export function formatNestedRouterConflictError(
 // ---------------------------------------------------------------------------
 
 /**
- * Extract the url patterns variable from a router file using AST.
- * Detects two patterns:
+ * Result of extracting URL patterns from a router file.
+ * - "variable": a named variable reference (e.g., `.routes(patterns)` or `urls: patterns`)
+ * - "inline": an inline builder function (e.g., `.routes(({ path }) => [...])` or `urls: ({ path }) => [...]`)
+ */
+export type UrlsExtractionResult =
+  | { kind: "variable"; name: string }
+  | { kind: "inline"; block: string };
+
+/**
+ * Extract the url patterns from a router file using AST.
+ * Detects four patterns:
  *   1. createRouter(...).routes(variableName)
  *   2. createRouter({ urls: variableName, ... })
- * Returns the local variable name.
+ *   3. createRouter(...).routes(({ path, ... }) => [...])
+ *   4. createRouter({ urls: ({ path, ... }) => [...], ... })
+ * Returns either a variable name or an inline code block.
  */
-export function extractUrlsVariableFromRouter(code: string): string | null {
+export function extractUrlsFromRouter(
+  code: string,
+): UrlsExtractionResult | null {
   const sourceFile = ts.createSourceFile(
     "router.tsx",
     code,
@@ -171,7 +197,7 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
     true,
     ts.ScriptKind.TSX,
   );
-  let result: string | null = null;
+  let result: UrlsExtractionResult | null = null;
 
   function isCreateRouterCall(node: ts.Node): boolean {
     if (!ts.isCallExpression(node)) return false;
@@ -179,44 +205,108 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
     return ts.isIdentifier(callee) && callee.text === "createRouter";
   }
 
+  /** Check if a node is an arrow/function expression (inline builder). */
+  function isInlineBuilder(node: ts.Node): boolean {
+    return ts.isArrowFunction(node) || ts.isFunctionExpression(node);
+  }
+
+  /** Check if a .routes() call chains from createRouter(). */
+  function isRoutesOnCreateRouter(node: ts.CallExpression): boolean {
+    if (
+      !ts.isPropertyAccessExpression(node.expression) ||
+      node.expression.name.text !== "routes"
+    )
+      return false;
+    let inner: ts.Expression = node.expression.expression;
+    while (
+      ts.isCallExpression(inner) &&
+      ts.isPropertyAccessExpression(inner.expression)
+    ) {
+      inner = inner.expression.expression;
+    }
+    return isCreateRouterCall(inner);
+  }
+
   function visit(node: ts.Node) {
     if (result) return;
 
-    // Pattern 1: createRouter(...).routes(variableName)
-    // The AST shape is CallExpression(.routes) -> PropertyAccessExpression -> CallExpression(createRouter)
+    // Pattern 1 & 3: createRouter(...).routes(variableName | builder)
     if (
       ts.isCallExpression(node) &&
-      ts.isPropertyAccessExpression(node.expression) &&
-      node.expression.name.text === "routes" &&
       node.arguments.length >= 1 &&
-      ts.isIdentifier(node.arguments[0])
+      isRoutesOnCreateRouter(node)
     ) {
-      // Walk up the chain: createRouter().middleware(...).routes(x) etc.
-      // The innermost call should be createRouter(...)
-      let inner: ts.Expression = node.expression.expression;
-      while (
-        ts.isCallExpression(inner) &&
-        ts.isPropertyAccessExpression(inner.expression)
-      ) {
-        inner = inner.expression.expression;
-      }
-      if (isCreateRouterCall(inner)) {
-        result = (node.arguments[0] as ts.Identifier).text;
-        return;
+      const arg = node.arguments[0];
+      if (ts.isIdentifier(arg)) {
+        result = { kind: "variable", name: arg.text };
+      } else if (isInlineBuilder(arg)) {
+        result = { kind: "inline", block: arg.getText(sourceFile) };
       }
+      return;
     }
 
-    // Pattern 2: createRouter({ urls: variableName, ... })
+    // Pattern 2 & 4: createRouter({ urls: variableName | builder, ... })
     if (isCreateRouterCall(node)) {
       const callExpr = node as ts.CallExpression;
-      for (const arg of callExpr.arguments) {
+      for (const callArg of callExpr.arguments) {
+        if (ts.isObjectLiteralExpression(callArg)) {
+          for (const prop of callArg.properties) {
+            if (
+              ts.isPropertyAssignment(prop) &&
+              ts.isIdentifier(prop.name) &&
+              prop.name.text === "urls"
+            ) {
+              if (ts.isIdentifier(prop.initializer)) {
+                result = { kind: "variable", name: prop.initializer.text };
+              } else if (isInlineBuilder(prop.initializer)) {
+                result = {
+                  kind: "inline",
+                  block: prop.initializer.getText(sourceFile),
+                };
+              }
+              return;
+            }
+          }
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return result;
+}
+
+/**
+ * Extract the `basename` string literal from createRouter({ basename: "..." }).
+ * Returns the basename value or undefined if not present.
+ */
+export function extractBasenameFromRouter(code: string): string | undefined {
+  const sourceFile = ts.createSourceFile(
+    "router.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  let result: string | undefined;
+
+  function visit(node: ts.Node) {
+    if (result !== undefined) return;
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === "createRouter"
+    ) {
+      for (const arg of node.arguments) {
         if (ts.isObjectLiteralExpression(arg)) {
           for (const prop of arg.properties) {
             if (
               ts.isPropertyAssignment(prop) &&
               ts.isIdentifier(prop.name) &&
-              prop.name.text === "urls" &&
-              ts.isIdentifier(prop.initializer)
+              prop.name.text === "basename" &&
+              ts.isStringLiteral(prop.initializer)
             ) {
               result = prop.initializer.text;
               return;
@@ -225,7 +315,6 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
         }
       }
     }
-
     ts.forEachChild(node, visit);
   }
 
@@ -233,9 +322,70 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
   return result;
 }
 
+/** @deprecated Use extractUrlsFromRouter instead */
+export function extractUrlsVariableFromRouter(code: string): string | null {
+  const result = extractUrlsFromRouter(code);
+  return result?.kind === "variable" ? result.name : null;
+}
+
+/** Apply a basename prefix to all route patterns in a result set. */
+function applyBasenameToRoutes(
+  result: {
+    routes: Record<string, string>;
+    searchSchemas: Record<string, Record<string, string>>;
+  },
+  basename: string,
+): {
+  routes: Record<string, string>;
+  searchSchemas: Record<string, Record<string, string>>;
+} {
+  const prefixed: Record<string, string> = {};
+  for (const [name, pattern] of Object.entries(result.routes)) {
+    if (pattern === "/") {
+      prefixed[name] = basename;
+    } else if (basename.endsWith("/") && pattern.startsWith("/")) {
+      prefixed[name] = basename + pattern.slice(1);
+    } else {
+      prefixed[name] = basename + pattern;
+    }
+  }
+  return { routes: prefixed, searchSchemas: result.searchSchemas };
+}
+
+// Filesystem path of the generated route-types file for a router source file.
+// Native separators — matches the self-gen-tracking Map key the watcher compares.
+export function genFileTsPath(sourceFile: string): string {
+  const base = pathBasename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+  return join(dirname(sourceFile), `${base}.named-routes.gen.ts`);
+}
+
+// Search schemas for the gen file: prefer the runtime manifest's; when it omits
+// them (some module-runner flows) fall back to static parsing filtered to the
+// public route-name set. Returns the runtime value unchanged otherwise.
+export function resolveSearchSchemas(
+  publicRouteNames: string[],
+  runtimeSchemas: Record<string, Record<string, string>> | undefined,
+  sourceFile: string,
+): Record<string, Record<string, string>> | undefined {
+  if (runtimeSchemas && Object.keys(runtimeSchemas).length > 0) {
+    return runtimeSchemas;
+  }
+  const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
+  if (Object.keys(staticParsed.searchSchemas).length === 0) {
+    return runtimeSchemas;
+  }
+  const filtered: Record<string, Record<string, string>> = {};
+  for (const name of publicRouteNames) {
+    const schema = staticParsed.searchSchemas[name];
+    if (schema) filtered[name] = schema;
+  }
+  return Object.keys(filtered).length > 0 ? filtered : runtimeSchemas;
+}
+
 /**
  * Resolve routes and search schemas from a router source file by following the
- * variable passed to `.routes(...)` or `urls: ...` in createRouter options.
+ * variable passed to `.routes(...)` or `urls: ...` in createRouter options,
+ * or by parsing an inline builder function directly.
  */
 export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
   routes: Record<string, string>;
@@ -248,21 +398,54 @@ export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
     return { routes: {}, searchSchemas: {} };
   }
 
-  const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-  if (!urlsVarName) {
+  const extraction = extractUrlsFromRouter(routerSource);
+  if (!extraction) {
     return { routes: {}, searchSchemas: {} };
   }
 
-  const imported = resolveImportedVariable(routerSource, urlsVarName);
-  if (imported) {
-    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-    if (!targetFile) {
-      return { routes: {}, searchSchemas: {} };
+  // Detect basename from createRouter({ basename: "..." })
+  const rawBasename = extractBasenameFromRouter(routerSource);
+  const basename = rawBasename
+    ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "")
+    : undefined;
+
+  let result: {
+    routes: Record<string, string>;
+    searchSchemas: Record<string, Record<string, string>>;
+  };
+
+  // Inline builder: extract routes directly from the function body
+  if (extraction.kind === "inline") {
+    result = buildCombinedRouteMapWithSearch(
+      routerFilePath,
+      undefined,
+      undefined,
+      undefined,
+      extraction.block,
+    );
+  } else {
+    // Variable reference: follow imports or same-file declaration
+    const imported = resolveImportedVariable(routerSource, extraction.name);
+    if (imported) {
+      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+      if (!targetFile) {
+        return { routes: {}, searchSchemas: {} };
+      }
+      result = buildCombinedRouteMapWithSearch(
+        targetFile,
+        imported.exportedName,
+      );
+    } else {
+      result = buildCombinedRouteMapWithSearch(routerFilePath, extraction.name);
     }
-    return buildCombinedRouteMapWithSearch(targetFile, imported.exportedName);
   }
 
-  return buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+  // Apply basename prefix to all extracted route patterns
+  if (basename) {
+    result = applyBasenameToRoutes(result, basename);
+  }
+
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -285,12 +468,26 @@ export function detectUnresolvableIncludes(
     return [];
   }
 
-  // Extract the urls variable from the router file
-  const urlsVarName = extractUrlsVariableFromRouter(source);
-  if (!urlsVarName) return [];
+  // Extract the urls source from the router file
+  const extraction = extractUrlsFromRouter(source);
+  if (!extraction) return [];
+
+  const diagnostics: UnresolvableInclude[] = [];
 
-  // Resolve where the urls variable comes from
-  const imported = resolveImportedVariable(source, urlsVarName);
+  if (extraction.kind === "inline") {
+    // Inline builder: parse directly
+    buildCombinedRouteMapWithSearch(
+      realPath,
+      undefined,
+      new Set(),
+      diagnostics,
+      extraction.block,
+    );
+    return diagnostics;
+  }
+
+  // Variable reference: resolve where it comes from
+  const imported = resolveImportedVariable(source, extraction.name);
   let targetFile: string;
   let exportedName: string | undefined;
 
@@ -312,10 +509,9 @@ export function detectUnresolvableIncludes(
   } else {
     // Same-file urls() definition
     targetFile = realPath;
-    exportedName = urlsVarName;
+    exportedName = extraction.name;
   }
 
-  const diagnostics: UnresolvableInclude[] = [];
   buildCombinedRouteMapWithSearch(
     targetFile,
     exportedName,
@@ -375,7 +571,10 @@ export function findRouterFiles(root: string, filter?: ScanFilter): string[] {
 export function writeCombinedRouteTypes(
   root: string,
   knownRouterFiles?: string[],
-  opts?: { preserveIfLarger?: boolean },
+  opts?: {
+    preserveIfLarger?: boolean;
+    onWrite?: (outPath: string, content: string) => void;
+  },
 ): void {
   // Delete old combined named-routes.gen.ts if it exists (stale from older versions)
   try {
@@ -383,7 +582,7 @@ export function writeCombinedRouteTypes(
     if (existsSync(oldCombinedPath)) {
       unlinkSync(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`,
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`,
       );
     }
   } catch {}
@@ -397,44 +596,23 @@ export function writeCombinedRouteTypes(
   }
 
   for (const routerFilePath of routerFilePaths) {
-    let routerSource: string;
-    try {
-      routerSource = readFileSync(routerFilePath, "utf-8");
-    } catch {
-      continue;
-    }
-    // Extract the urls variable name from .routes(varName) or urls: varName
-    const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-    if (!urlsVarName) continue;
-
-    // Resolve the variable to its source module
-    let result: {
-      routes: Record<string, string>;
-      searchSchemas: Record<string, Record<string, string>>;
-    };
-
-    const imported = resolveImportedVariable(routerSource, urlsVarName);
-    if (imported) {
-      // Variable is imported from another module
-      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-      if (!targetFile) continue;
-      result = buildCombinedRouteMapWithSearch(
-        targetFile,
-        imported.exportedName,
-      );
-    } else {
-      // Variable is defined in the same file
-      result = buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+    const result = buildCombinedRouteMapForRouterFile(routerFilePath);
+    if (
+      Object.keys(result.routes).length === 0 &&
+      Object.keys(result.searchSchemas).length === 0
+    ) {
+      // Check if the file even has a createRouter call — if not, skip entirely.
+      // If it does, fall through to write an empty placeholder below.
+      let routerSource: string;
+      try {
+        routerSource = readFileSync(routerFilePath, "utf-8");
+      } catch {
+        continue;
+      }
+      if (!extractUrlsFromRouter(routerSource)) continue;
     }
 
-    const routerBasename = pathBasename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      "",
-    );
-    const outPath = join(
-      dirname(routerFilePath),
-      `${routerBasename}.named-routes.gen.ts`,
-    );
+    const outPath = genFileTsPath(routerFilePath);
     const existing = existsSync(outPath)
       ? readFileSync(outPath, "utf-8")
       : null;
@@ -445,6 +623,7 @@ export function writeCombinedRouteTypes(
     if (Object.keys(result.routes).length === 0) {
       if (!existing) {
         const emptySource = generateRouteTypesSource({});
+        opts?.onWrite?.(outPath, emptySource);
         writeFileSync(outPath, emptySource);
       }
       continue;
@@ -470,9 +649,10 @@ export function writeCombinedRouteTypes(
           continue;
         }
       }
+      opts?.onWrite?.(outPath, source);
       writeFileSync(outPath, source);
       console.log(
-        `[rsc-router] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
+        `[rango] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
       );
     }
   }

package/src/build/route-types/scan-filter.ts

@@ -54,14 +54,21 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return results;
   }
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      if (
+        entry.name === "node_modules" ||
+        entry.name.startsWith(".") ||
+        entry.name === "dist" ||
+        entry.name === "build" ||
+        entry.name === "coverage"
+      )
+        continue;
       results.push(...findTsFiles(fullPath, filter));
     } else if (
       (entry.name.endsWith(".ts") ||

package/src/build/route-types/source-scan.ts

@@ -0,0 +1,118 @@
+// Allocation-light, linear-time source scanning for the build-time scanners.
+//
+// The router-file scanner, the HMR relevance check, and the unsupported-shape
+// warning all need to know whether a token like `createRouter(` / `createLoader(`
+// appears in REAL code versus inside a comment or string literal. Rather than
+// build a full comment/string-stripped copy of the source (which on a large
+// file allocates an O(n) string plus, naively, a per-char array), these helpers
+// run the regex over the whole source ONCE (the engine sweeps left-to-right,
+// O(n)) and classify each match's offset with a forward, O(1)-memory cursor that
+// advances monotonically across the source.
+//
+// Time: O(n) — one native regex sweep plus one forward classification pass.
+// Memory: O(1) for the boolean check; O(#matches) for the index list. No
+// stripped copy and no per-char array are ever materialized.
+//
+// Pragmatic scanner, not a full tokenizer: regex literals are not special-cased
+// (a target token inside one is implausible) and template interpolations are
+// treated as opaque string content. One intentional consequence: a token whose
+// match would only complete by treating an interleaved comment as whitespace
+// (e.g. `createRouter /* x */ (`) is not detected — real calls never interleave
+// a comment between the callee and its arguments.
+
+// JS line terminators end a `//` comment: LF, CR, LS (U+2028), PS (U+2029).
+function isLineTerminator(ch: string): boolean {
+  const c = ch.charCodeAt(0);
+  // LF, CR, LS (U+2028), PS (U+2029)
+  return c === 10 || c === 13 || c === 0x2028 || c === 0x2029;
+}
+
+/**
+ * Build a classifier that answers "is offset `q` in code (not a comment or
+ * string)?" for STRICTLY INCREASING `q`. The internal cursor only moves forward,
+ * so a full left-to-right sequence of queries costs O(n) total with O(1) memory.
+ */
+function makeCodeClassifier(code: string): (q: number) => boolean {
+  const n = code.length;
+  let i = 0; // forward cursor: everything before `i` is already classified
+  let skipStart = -1; // last detected comment/string region (cache)
+  let skipEnd = -1;
+
+  return (q: number): boolean => {
+    if (q >= skipStart && q < skipEnd) return false; // q in the cached region
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      }
+      if (end >= 0) {
+        // Comment/string region [i, end). `q >= i` here (loop condition).
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+      } else {
+        i++;
+      }
+    }
+    return true; // reached q in code mode
+  };
+}
+
+/**
+ * Index of the first match of `pattern` that occurs in code (not in a comment
+ * or string), or -1. `pattern` MUST be a global (`/g`) regex. Single native
+ * regex sweep with early-exit; O(1) extra memory.
+ */
+export function firstCodeMatchIndex(code: string, pattern: RegExp): number {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+
+/**
+ * Byte offsets of every match of `pattern` that occurs in code (not in a
+ * comment or string). `pattern` MUST be a global (`/g`) regex. Each offset is
+ * the match start — the same byte offset a raw `pattern.exec` reports. O(n)
+ * time, O(#matches) memory.
+ */
+export function codeMatchIndices(code: string, pattern: RegExp): number[] {
+  const inCode = makeCodeClassifier(code);
+  const indices: number[] = [];
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) indices.push(m.index);
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return indices;
+}