@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/utils/sourceRouteExtractor.js

@@ -32,7 +32,7 @@ import * as path from "path";
 import * as ts from "typescript";
 import { collectFiles } from "./fileWalk.js";
 function makeParseCache() {
-    return { files: new Map(), tsconfigBaseUrl: new Map() };
+    return { files: new Map(), tsconfig: new Map() };
 }
 /** Recursion cap for cross-file constant resolution. */
 const MAX_RESOLVE_DEPTH = 4;
@@ -155,9 +155,7 @@ function extractRoutesFromFile(filePath, cache) {
     visit(sf, (node) => {
         // 1. JSX route elements: <Route path="…" element={<X/>} />
         if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
-            const r = jsxRouteFromNode(node, filePath, imports, localConsts, cache);
-            if (r)
-                routes.push(r);
+            routes.push(...jsxRoutesFromNode(node, filePath, imports, localConsts, cache));
             return;
         }
         // 2. defineModule({ id, routes: [...] }) — Directus per-module aggregation.
@@ -179,37 +177,66 @@ function extractRoutesFromFile(filePath, cache) {
     routes.push(...vueRouterRoutesFromFile(sf, filePath, imports, localConsts, cache));
     return routes;
 }
-function jsxRouteFromNode(node, filePath, imports, localConsts, cache) {
+function jsxRoutesFromNode(node, filePath, imports, localConsts, cache) {
     const tag = jsxTagOf(node);
     if (!tag || !ROUTE_TAG_NAMES.has(tag))
-        return null;
+        return [];
     const attrs = jsxAttributesOf(node);
+    const componentAttr = attrs.find((a) => a.name === "element" || a.name === "component");
+    if (!componentAttr || componentAttr.kind !== "identifier")
+        return [];
+    const mountedAt = (routePath) => ({
+        path: routePath,
+        componentName: componentAttr.value,
+        componentFile: imports.get(componentAttr.value)?.filePath,
+        declaredIn: filePath,
+    });
+    // React Router child paths are relative to the enclosing <Route>; compose
+    // with the ancestor chain so nested routes yield full navigable URLs.
+    const parentPrefix = enclosingJsxRoutePath(node, filePath, imports, localConsts, cache);
     const pathAttr = attrs.find((a) => a.name === "path");
-    let ownPath;
     if (pathAttr) {
-        ownPath = resolveAttrToString(pathAttr, filePath, imports, localConsts, cache);
+        const ownPath = resolveAttrToString(pathAttr, filePath, imports, localConsts, cache);
         if (ownPath === null)
-            return null;
+            return [];
+        return [mountedAt(composeRoutePath(parentPrefix, ownPath))];
     }
-    else if (attrs.some((a) => a.name === "index")) {
+    if (attrs.some((a) => a.name === "index")) {
         // <Route index> has no path — it renders at the parent route's path.
-        ownPath = "";
-    }
-    else {
-        return null;
+        return [mountedAt(composeRoutePath(parentPrefix, ""))];
     }
-    const componentAttr = attrs.find((a) => a.name === "element" || a.name === "component");
-    if (!componentAttr || componentAttr.kind !== "identifier")
-        return null;
-    // React Router child paths are relative to the enclosing <Route>; compose
-    // with the ancestor chain so nested routes yield full navigable URLs.
-    const parentPrefix = enclosingJsxRoutePath(node, filePath, imports, localConsts, cache);
-    return {
-        path: composeRoutePath(parentPrefix, ownPath),
-        componentName: componentAttr.value,
-        componentFile: imports.get(componentAttr.value)?.filePath,
-        declaredIn: filePath,
-    };
+    // A pathless layout route has no URL of its own: it renders on every route
+    // nested under it. Reporting nothing would read as "no route renders this
+    // file", the one answer that is definitely wrong for a layout, and the parent
+    // path on its own would be a URL the app may not serve. Report the pages it
+    // appears on, the way readTanStackRouteTree reports a pathless TanStack layout.
+    return nestedJsxRoutePaths(node, filePath, imports, localConsts, cache).map(mountedAt);
+}
+/** The composed paths of the routes written inside a JSX route element. */
+function nestedJsxRoutePaths(node, filePath, imports, localConsts, cache) {
+    const element = node.parent;
+    if (!ts.isJsxElement(element) || element.openingElement !== node)
+        return [];
+    const paths = [];
+    visit(element, (inner) => {
+        if (inner === node)
+            return;
+        if (!ts.isJsxOpeningElement(inner) && !ts.isJsxSelfClosingElement(inner))
+            return;
+        const tag = jsxTagOf(inner);
+        if (!tag || !ROUTE_TAG_NAMES.has(tag))
+            return;
+        const pathAttr = jsxAttributesOf(inner).find((a) => a.name === "path");
+        if (!pathAttr)
+            return;
+        const ownPath = resolveAttrToString(pathAttr, filePath, imports, localConsts, cache);
+        if (ownPath === null)
+            return;
+        const composed = composeRoutePath(enclosingJsxRoutePath(inner, filePath, imports, localConsts, cache), ownPath);
+        if (!paths.includes(composed))
+            paths.push(composed);
+    });
+    return paths;
 }
 /**
  * Walk a JSX route node's ancestor chain and compose the paths of the enclosing
@@ -323,36 +350,19 @@ function parseExpressionAttr(name, expr) {
  *   import { WORKSPACE_URL } from "constants/routes" // baseUrl-resolved
  *
  * Bare imports (`react-router-dom`) are skipped — those aren't local files.
- * `paths` aliases (e.g. `@/*`, `ee/*`) aren't currently honored; the only
- * consequence in target repos is missing some constants in deep-aliased
- * subtrees, which downgrades to "couldn't resolve, skip the route" — safe.
+ * Aliased imports (`@/components/X`) go through tsconfig `paths`; an alias with
+ * no matching pattern downgrades to "couldn't resolve, skip the route" — safe.
  */
 function collectImports(sf, filePath, cache) {
     const result = new Map();
     const fileDir = path.dirname(filePath);
-    const baseUrl = findTsconfigBaseUrl(fileDir, cache);
     for (const stmt of sf.statements) {
         if (!ts.isImportDeclaration(stmt))
             continue;
         const moduleSpec = stmt.moduleSpecifier;
         if (!ts.isStringLiteral(moduleSpec))
             continue;
-        const spec = moduleSpec.text;
-        let resolved;
-        if (spec.startsWith("/")) {
-            // Absolute import specs would let a hostile repo point the analyzer
-            // at arbitrary host paths during route extraction (e.g. /etc/passwd).
-            // Real codebases don't use literal absolute imports — they use
-            // relative paths or tsconfig path aliases.
-            continue;
-        }
-        if (spec.startsWith(".")) {
-            resolved = resolveImportPath(fileDir, spec);
-        }
-        else if (baseUrl) {
-            // Try baseUrl resolution for non-relative imports.
-            resolved = resolveImportPath(baseUrl, spec);
-        }
+        const resolved = resolveModuleSpecifier(moduleSpec.text, fileDir, cache);
         if (!resolved)
             continue;
         const clause = stmt.importClause;
@@ -494,7 +504,6 @@ function resolveExportedSymbolToString(filePath, exportedName, cache, depth) {
     const imports = collectImports(sf, filePath, cache);
     const localConsts = collectLocalConsts(sf);
     const fileDir = path.dirname(filePath);
-    const baseUrl = findTsconfigBaseUrl(fileDir, cache);
     // 1. Look for `export const X = …` directly in this file.
     for (const stmt of sf.statements) {
         if (!ts.isVariableStatement(stmt))
@@ -547,17 +556,7 @@ function resolveExportedSymbolToString(filePath, exportedName, cache, depth) {
         if (!stmt.moduleSpecifier || !ts.isStringLiteral(stmt.moduleSpecifier))
             continue;
         const targetSpec = stmt.moduleSpecifier.text;
-        let targetFile;
-        if (targetSpec.startsWith("/")) {
-            // Absolute paths rejected for the same reason as collectImports.
-            continue;
-        }
-        if (targetSpec.startsWith(".")) {
-            targetFile = resolveImportPath(fileDir, targetSpec);
-        }
-        else if (baseUrl) {
-            targetFile = resolveImportPath(baseUrl, targetSpec);
-        }
+        const targetFile = resolveModuleSpecifier(targetSpec, fileDir, cache);
         if (!targetFile)
             continue;
         if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
@@ -581,18 +580,43 @@ function resolveExportedSymbolToString(filePath, exportedName, cache, depth) {
     return null;
 }
 const IMPORT_EXTENSIONS = [".tsx", ".jsx", ".ts", ".js", ".vue"];
+/**
+ * TypeScript's `moduleResolution: node16/nodenext` requires an ESM import to
+ * name the file the compiler EMITS, so a `.tsx` component is imported as
+ * `./Page.js`. Appending extensions to that specifier only ever tries
+ * `Page.js.tsx`, so the TS source has to be looked up under its own extension.
+ */
+const TS_SOURCE_EXTENSIONS = {
+    ".js": [".ts", ".tsx"],
+    ".jsx": [".tsx"],
+    ".mjs": [".mts"],
+    ".cjs": [".cts"],
+};
 function resolveImportPath(fromDir, spec) {
-    const base = path.resolve(fromDir, spec);
+    return resolveFilePath(path.resolve(fromDir, spec));
+}
+/** The file an already-joined absolute module path names, if any. */
+function resolveFilePath(base) {
     // 1. Exact file (with the extension already in spec).
     if (fileExistsSync(base))
         return base;
-    // 2. Try each known extension.
+    // 2. A JavaScript extension standing in for the TypeScript source.
+    const jsExt = /\.(?:js|jsx|mjs|cjs)$/i.exec(base);
+    if (jsExt) {
+        const stem = base.slice(0, base.length - jsExt[0].length);
+        for (const ext of TS_SOURCE_EXTENSIONS[jsExt[0].toLowerCase()] ?? []) {
+            const candidate = stem + ext;
+            if (fileExistsSync(candidate))
+                return candidate;
+        }
+    }
+    // 3. Try each known extension.
     for (const ext of IMPORT_EXTENSIONS) {
         const candidate = base + ext;
         if (fileExistsSync(candidate))
             return candidate;
     }
-    // 3. Treat as directory with index.{tsx,jsx,ts,js,vue}.
+    // 4. Treat as directory with index.{tsx,jsx,ts,js,vue}.
     for (const ext of IMPORT_EXTENSIONS) {
         const candidate = path.join(base, "index" + ext);
         if (fileExistsSync(candidate))
@@ -600,6 +624,51 @@ function resolveImportPath(fromDir, spec) {
     }
     return undefined;
 }
+/**
+ * The repository file a module specifier written in `fromDir` names, or
+ * undefined when nothing in the project answers it.
+ *
+ * An absolute specifier is refused: it would let a scanned repository point the
+ * analyzer at any file on the host (`import x from "/etc/passwd"`). Real
+ * projects write relative paths or tsconfig aliases.
+ */
+function resolveModuleSpecifier(spec, fromDir, cache) {
+    if (spec.startsWith("/") || path.isAbsolute(spec))
+        return undefined;
+    if (spec.startsWith("."))
+        return resolveImportPath(fromDir, spec);
+    const tsconfig = findTsconfig(fromDir, cache);
+    if (!tsconfig)
+        return undefined;
+    const viaPaths = resolveViaTsconfigPaths(spec, tsconfig);
+    if (viaPaths)
+        return viaPaths;
+    return tsconfig.baseUrl ? resolveImportPath(tsconfig.baseUrl, spec) : undefined;
+}
+/** The file a `paths` alias names, trying the most specific pattern first and,
+ *  within one pattern, the first target that exists. */
+function resolveViaTsconfigPaths(spec, tsconfig) {
+    for (const alias of tsconfig.paths) {
+        let substitution;
+        if (alias.wildcard) {
+            if (spec.length < alias.prefix.length + alias.suffix.length)
+                continue;
+            if (!spec.startsWith(alias.prefix) || !spec.endsWith(alias.suffix))
+                continue;
+            substitution = spec.slice(alias.prefix.length, spec.length - alias.suffix.length);
+        }
+        else if (spec !== alias.prefix) {
+            continue;
+        }
+        for (const target of alias.targets) {
+            const candidate = substitution === undefined ? target : target.replace("*", substitution);
+            const resolved = resolveFilePath(candidate);
+            if (resolved)
+                return resolved;
+        }
+    }
+    return undefined;
+}
 function fileExistsSync(p) {
     try {
         const stat = fs.statSync(p);
@@ -610,40 +679,37 @@ function fileExistsSync(p) {
     }
 }
 /**
- * Walk parent directories until a `tsconfig.json` is found, then resolve its
- * `baseUrl` (following one level of `extends` for the common case where
+ * Walk parent directories until a `tsconfig.json` is found, then read its
+ * `baseUrl` and `paths` (following `extends` for the common case where
  * tsconfig.json extends a tsconfig.path.json sibling). Returns null when no
- * tsconfig is found or no `baseUrl` is configured.
+ * tsconfig is found, or when the one found configures neither.
  *
  * Memoized in the parse cache: cache hits AND misses, both keyed by the
  * directory we started searching from. Prevents re-stat'ing the same parent
  * chain on every import in a deeply nested tree.
  */
-function findTsconfigBaseUrl(fromDir, cache) {
-    const cached = cache.tsconfigBaseUrl.get(fromDir);
+function findTsconfig(fromDir, cache) {
+    const cached = cache.tsconfig.get(fromDir);
     if (cached !== undefined)
         return cached;
     let cur = fromDir;
     for (let i = 0; i < 12; i++) {
         const tsconfigPath = path.join(cur, "tsconfig.json");
         if (fileExistsSync(tsconfigPath)) {
-            const baseUrl = readTsconfigBaseUrl(tsconfigPath);
-            cache.tsconfigBaseUrl.set(fromDir, baseUrl);
-            return baseUrl;
+            // Cap recursion through `extends` to avoid pathological loops.
+            const resolution = readTsconfig(tsconfigPath, 0);
+            cache.tsconfig.set(fromDir, resolution);
+            return resolution;
         }
         const parent = path.dirname(cur);
         if (parent === cur)
             break;
         cur = parent;
     }
-    cache.tsconfigBaseUrl.set(fromDir, null);
+    cache.tsconfig.set(fromDir, null);
     return null;
 }
-function readTsconfigBaseUrl(tsconfigPath) {
-    // Cap recursion through `extends` to avoid pathological loops.
-    return readTsconfigBaseUrlInner(tsconfigPath, 0);
-}
-function readTsconfigBaseUrlInner(tsconfigPath, depth) {
+function readTsconfig(tsconfigPath, depth) {
     if (depth > 4)
         return null;
     let parsed;
@@ -655,26 +721,86 @@ function readTsconfigBaseUrlInner(tsconfigPath, depth) {
     catch {
         return null;
     }
-    const baseUrl = parsed?.compilerOptions?.baseUrl;
-    if (typeof baseUrl === "string") {
-        return path.resolve(path.dirname(tsconfigPath), baseUrl);
-    }
-    const extendsPath = parsed?.extends;
-    if (typeof extendsPath === "string") {
-        const tsconfigDir = path.dirname(tsconfigPath);
-        let extendedPath;
-        if (extendsPath.startsWith(".") || extendsPath.startsWith("/")) {
-            extendedPath = path.resolve(tsconfigDir, extendsPath);
-        }
-        else {
-            // Bare-extend (e.g. "@tsconfig/node20/tsconfig.json") — skip.
+    const tsconfigDir = path.dirname(tsconfigPath);
+    const rawBaseUrl = parsed?.compilerOptions?.baseUrl;
+    let baseUrl = null;
+    if (typeof rawBaseUrl === "string") {
+        // An absolute baseUrl makes every non-relative import in the repo resolve
+        // against a directory of the tsconfig's choosing, anywhere on the host. The
+        // same reason absolute import specifiers are skipped applies here, and a
+        // real project writes baseUrl relative to its own tsconfig.
+        if (path.isAbsolute(rawBaseUrl))
             return null;
+        baseUrl = path.resolve(tsconfigDir, rawBaseUrl);
+    }
+    // TypeScript resolves `paths` targets against baseUrl when the project sets
+    // one, and against the tsconfig's own directory otherwise.
+    const paths = readPathAliases(parsed?.compilerOptions?.paths, baseUrl ?? tsconfigDir);
+    if (baseUrl !== null && paths.length > 0)
+        return { baseUrl, paths };
+    const inherited = readExtendedTsconfig(parsed?.extends, tsconfigDir, depth);
+    const merged = {
+        baseUrl: baseUrl ?? inherited?.baseUrl ?? null,
+        paths: paths.length > 0 ? paths : (inherited?.paths ?? []),
+    };
+    if (merged.baseUrl === null && merged.paths.length === 0)
+        return null;
+    return merged;
+}
+/** Follow `extends`, refusing anything that is not a config file named relative
+ *  to this one. */
+function readExtendedTsconfig(extendsPath, tsconfigDir, depth) {
+    if (typeof extendsPath !== "string")
+        return null;
+    if (path.isAbsolute(extendsPath)) {
+        // `extends: "/etc/passwd"` would have this function read that file during
+        // a scan. Only a sibling config, named relative to this one, is followed.
+        return null;
+    }
+    // Bare-extend (e.g. "@tsconfig/node20/tsconfig.json") — skip.
+    if (!extendsPath.startsWith("."))
+        return null;
+    let extended = path.resolve(tsconfigDir, extendsPath);
+    if (!extended.endsWith(".json"))
+        extended += ".json";
+    return readTsconfig(extended, depth + 1);
+}
+/** Parse `compilerOptions.paths` into match-ready aliases. */
+function readPathAliases(raw, resolveAgainst) {
+    if (!raw || typeof raw !== "object")
+        return [];
+    const aliases = [];
+    for (const [pattern, value] of Object.entries(raw)) {
+        if (!Array.isArray(value))
+            continue;
+        const star = pattern.indexOf("*");
+        // TypeScript accepts at most one `*` per pattern and per target.
+        if (star !== pattern.lastIndexOf("*"))
+            continue;
+        const targets = [];
+        for (const target of value) {
+            if (typeof target !== "string")
+                continue;
+            // An absolute target reaches outside the project, the same way an
+            // absolute baseUrl would.
+            if (path.isAbsolute(target))
+                continue;
+            if (target.indexOf("*") !== target.lastIndexOf("*"))
+                continue;
+            targets.push(path.resolve(resolveAgainst, target));
         }
-        if (!extendedPath.endsWith(".json"))
-            extendedPath += ".json";
-        return readTsconfigBaseUrlInner(extendedPath, depth + 1);
+        if (targets.length === 0)
+            continue;
+        aliases.push({
+            prefix: star >= 0 ? pattern.slice(0, star) : pattern,
+            suffix: star >= 0 ? pattern.slice(star + 1) : "",
+            wildcard: star >= 0,
+            targets,
+        });
     }
-    return null;
+    // Longest prefix first, so `@/components/*` is tried before `@/*`.
+    aliases.sort((a, b) => b.prefix.length - a.prefix.length);
+    return aliases;
 }
 /**
  * Strip line/block comments from JSON before parsing. tsconfig.json files
@@ -713,12 +839,55 @@ function vueRouterRoutesFromFile(sf, filePath, imports, localConsts, cache) {
         // heuristic anyway, so this guard only bites the rarer `component:` form.
         if (isInsideCreateRouter(node))
             return;
-        const r = routeFromObjectLiteral(node, "", filePath, imports, localConsts, cache);
+        const prefix = enclosingObjectRoutePath(node, filePath, imports, localConsts, cache);
+        if (prefix === null)
+            return;
+        const r = routeFromObjectLiteral(node, prefix, filePath, imports, localConsts, cache);
         if (r)
             out.push(r);
     });
     return out;
 }
+/**
+ * The path prefix a route object literal inherits from the route objects that
+ * hold it in a `children:` array, composed root-to-leaf. `""` for a top-level
+ * route. `null` when an ancestor states a path this scan cannot resolve: the
+ * descendant's URL would then be wrong, and a wrong URL sends the browser to
+ * the wrong page with the server's authority behind it.
+ */
+function enclosingObjectRoutePath(node, filePath, imports, localConsts, cache) {
+    const segments = [];
+    for (let cur = node.parent; cur; cur = cur.parent) {
+        if (!ts.isPropertyAssignment(cur))
+            continue;
+        if (!ts.isIdentifier(cur.name) || cur.name.text !== "children")
+            continue;
+        if (!ts.isObjectLiteralExpression(cur.parent))
+            continue;
+        const value = objectLiteralPath(cur.parent, filePath, imports, localConsts, cache);
+        if (value === null)
+            return null;
+        // Nearest ancestor is seen first, so prepend for root→leaf order.
+        if (value !== undefined)
+            segments.unshift(value);
+    }
+    let prefix = "";
+    for (const segment of segments)
+        prefix = composeRoutePath(prefix, segment);
+    return prefix;
+}
+/** A route object's `path`: the string it states, `undefined` when it states
+ *  none (a pathless layout), `null` when it states one that cannot be resolved. */
+function objectLiteralPath(obj, filePath, imports, localConsts, cache) {
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+            continue;
+        if (prop.name.text !== "path")
+            continue;
+        return resolveExpressionToString(prop.initializer, filePath, imports, localConsts, cache, 0);
+    }
+    return undefined;
+}
 function isInsideDefineModule(node) {
     let cur = node.parent;
     while (cur) {
@@ -826,7 +995,38 @@ function createRouterRoutesFromCall(call, filePath, imports, localConsts, cache)
     const arg = call.arguments[0];
     if (!arg || !ts.isArrayLiteralExpression(arg))
         return null;
-    return dataRouterRoutesFromArray(arg, "", filePath, imports, localConsts, cache);
+    const routes = dataRouterRoutesFromArray(arg, "", filePath, imports, localConsts, cache);
+    // A route path inside the array is written absolute, so the basename cannot be
+    // threaded through as a prefix — composeRoutePath drops a prefix for an
+    // absolute child. Apply it to the finished paths instead.
+    const basename = basenameOfRouterCall(call);
+    if (!basename)
+        return routes;
+    return routes.map((route) => ({
+        ...route,
+        path: composeRoutePath(basename, route.path.replace(/^\//, "")),
+    }));
+}
+/** The `basename` a data-router factory mounts its tree under, from its options
+ *  argument: `createBrowserRouter(routes, { basename: "/app" })`. Every URL the
+ *  app serves carries it. */
+function basenameOfRouterCall(call) {
+    const options = call.arguments[1];
+    if (!options || !ts.isObjectLiteralExpression(options))
+        return undefined;
+    for (const prop of options.properties) {
+        if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+            continue;
+        if (prop.name.text !== "basename")
+            continue;
+        if (!ts.isStringLiteral(prop.initializer))
+            return undefined;
+        const value = prop.initializer.text.replace(/\/+$/, "");
+        if (value === "")
+            return undefined;
+        return value.startsWith("/") ? value : "/" + value;
+    }
+    return undefined;
 }
 function dataRouterRoutesFromArray(arr, prefix, filePath, imports, localConsts, cache) {
     const out = [];
@@ -861,30 +1061,38 @@ function dataRouterRoutesFromArray(arr, prefix, filePath, imports, localConsts,
         if (hasPath && pathValue === null)
             continue;
         let childPrefix = prefix;
+        let ownPath;
         if (hasPath) {
             childPrefix = composeRoutePath(prefix, pathValue);
-            if (componentName) {
-                out.push({
-                    path: childPrefix,
-                    componentName,
-                    componentFile: imports.get(componentName)?.filePath,
-                    declaredIn: filePath,
-                });
-            }
+            ownPath = childPrefix;
+        }
+        else if (isIndex) {
+            ownPath = composeRoutePath(prefix, "");
         }
-        else if (isIndex && componentName) {
-            out.push({
-                path: composeRoutePath(prefix, ""),
-                componentName,
-                componentFile: imports.get(componentName)?.filePath,
+        const childRoutes = childrenArray
+            ? dataRouterRoutesFromArray(childrenArray, childPrefix, filePath, imports, localConsts, cache)
+            : [];
+        if (componentName) {
+            const component = componentName;
+            const mountedAt = (routePath) => ({
+                path: routePath,
+                componentName: component,
+                componentFile: imports.get(component)?.filePath,
                 declaredIn: filePath,
             });
+            if (ownPath !== undefined) {
+                out.push(mountedAt(ownPath));
+            }
+            else {
+                // Pathless layout route: it contributes no URL segment and has none of
+                // its own, so it renders on every route nested under it — reported the
+                // same way a pathless TanStack layout is.
+                for (const routePath of new Set(childRoutes.map((route) => route.path))) {
+                    out.push(mountedAt(routePath));
+                }
+            }
         }
-        // Pathless layout route (no path, not index): contributes no URL segment;
-        // its children inherit the current prefix unchanged.
-        if (childrenArray) {
-            out.push(...dataRouterRoutesFromArray(childrenArray, childPrefix, filePath, imports, localConsts, cache));
-        }
+        out.push(...childRoutes);
     }
     return out;
 }

package/build/utils/testFileClassification.d.ts

@@ -2,10 +2,19 @@
  * The single definition of "discovery treats this path as a test file", shared by
  * discovery itself and by callers that must agree with what discovery classified as
  * external coverage. A narrower predicate silently disagrees: `tests/test_orders.py`
- * is external coverage here but is not a test file to `isTestFile` in
- * scopeAssessment.ts, which only knows the Skyramp and JS/TS spec spellings.
+ * is external coverage here but is not a test file to `isTestFile` below, which
+ * only knows the Skyramp and JS/TS spec spellings.
  *
  * Accepts absolute or repo-relative paths. The directory patterns need a leading
  * separator, which a repo-relative path has not got, so one is prepended.
  */
 export declare function isDiscoveredTestFile(filePath: string): boolean;
+/** The NARROW predicate: a Skyramp-generated test or scenario file, a
+ *  Vitest/Jest/Playwright spec, or anything under `__tests__/`. Deliberately not
+ *  `isDiscoveredTestFile`'s rule, which also counts `tests/`, a page-object
+ *  directory and `test_orders.py`. The maintenance tool wants this narrow one. */
+export declare function isTestFile(filePath: string): boolean;
+/** Whether a path is a test file, by directory or by name. Read by the route
+ *  checks: a route declared in a mock server or a spec fixture is not a surface
+ *  anyone serves. */
+export declare function isTestPath(file: string): boolean;

package/build/utils/testFileClassification.js

@@ -1,4 +1,11 @@
 import * as path from "path";
+// Four questions about a path, four predicates, one file. Each is answered by its
+// own rule on purpose, and merging them has broken a caller before:
+//   isDiscoveredTestFile — does test DISCOVERY own this file?
+//   isTestFile           — is it a Skyramp test or a JS/TS spec? (maintenance)
+//   isTestPath           — can this file DECLARE a route? (route citations)
+// Two more patterns still live elsewhere and are out of scope here:
+// `pr-comment-parser.ts:45` and `test-recommendation-prompt.ts:45`.
 // Test file naming patterns — match against basename.
 // Includes Skyramp-generated suffixes so that files like orders_smoke.py placed
 // outside a recognized test directory are still discovered.
@@ -34,8 +41,8 @@ const TEST_DIR_PATTERNS = [
  * The single definition of "discovery treats this path as a test file", shared by
  * discovery itself and by callers that must agree with what discovery classified as
  * external coverage. A narrower predicate silently disagrees: `tests/test_orders.py`
- * is external coverage here but is not a test file to `isTestFile` in
- * scopeAssessment.ts, which only knows the Skyramp and JS/TS spec spellings.
+ * is external coverage here but is not a test file to `isTestFile` below, which
+ * only knows the Skyramp and JS/TS spec spellings.
  *
  * Accepts absolute or repo-relative paths. The directory patterns need a leading
  * separator, which a repo-relative path has not got, so one is prepended.
@@ -45,3 +52,38 @@ export function isDiscoveredTestFile(filePath) {
         return true;
     return TEST_DIR_PATTERNS.some((p) => p.test(`/${filePath}`));
 }
+/** The NARROW predicate: a Skyramp-generated test or scenario file, a
+ *  Vitest/Jest/Playwright spec, or anything under `__tests__/`. Deliberately not
+ *  `isDiscoveredTestFile`'s rule, which also counts `tests/`, a page-object
+ *  directory and `test_orders.py`. The maintenance tool wants this narrow one. */
+export function isTestFile(filePath) {
+    return (/(?:_test|_smoke|_contract|_fuzz|_integration|_load|_e2e|_ui)\.[^/]+$/.test(filePath) ||
+        /scenario_[^/]+\.json$/.test(filePath) ||
+        // Include the `.e2e.` dot form so Playwright/Cypress specs discovery treats
+        // as UI tests are recognized here too — e.g. `login.e2e.ts`.
+        /\.(spec|test|e2e)\.(tsx?|jsx?)$/.test(filePath) ||
+        /(?:^|\/)__tests__\//.test(filePath));
+}
+// ── The route-citation rule ──────────────────────────────────────────────────
+// Its three regexes stay separate from the discovery patterns above. Each one
+// differs deliberately, and the differences are the point — see each comment.
+/** A directory that is a test root whatever the file inside is called. `spec/`
+ *  and `specs/` are deliberately absent, unlike `TEST_DIR_PATTERNS`: a spec-first
+ *  service keeps its OpenAPI document there, and that document IS its route
+ *  definition. */
+const TEST_ROOT_DIR = /(^|[\\/])(tests?|__tests__|__mocks__|e2e|cypress|testing)([\\/]|$)/i;
+/** A file whose own NAME says it is a test, wherever it sits. Wider than the
+ *  `TEST_FILE_PATTERNS` rows it resembles — any extension, and `.`, `_` or `-`
+ *  before `test` — so no row above can stand in for it. */
+const TEST_FILE_NAME = /[._-](test|spec)\.[a-z]+$|(^|[\\/])test_[^\\/]*$/i;
+/** The CamelCase spellings, which carry no separator before `Test`.
+ *  Case-SENSITIVE and must stay so: with `i` it also matches `Latest.java` and
+ *  `Manifest.cs`, ordinary source files. That is why the case-insensitive
+ *  `*Test.java` / `*Tests.cs` rows above cannot serve here. */
+const CAMEL_TEST_FILE_NAME = /[a-z0-9](Tests?|IT)\.[A-Za-z0-9]+$/;
+/** Whether a path is a test file, by directory or by name. Read by the route
+ *  checks: a route declared in a mock server or a spec fixture is not a surface
+ *  anyone serves. */
+export function isTestPath(file) {
+    return TEST_ROOT_DIR.test(file) || TEST_FILE_NAME.test(file) || CAMEL_TEST_FILE_NAME.test(file);
+}