@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/utils/screenRoutes.js

@@ -0,0 +1,727 @@
+/**
+ * Which route patterns render a given frontend file — SKYR-4341.
+ *
+ * A UI test names the file it is about and the page it opens. Nothing used to
+ * compare the two, so a run could name `SecretDetailSidebar.tsx`, open
+ * `/overview`, and spend its budget hunting an element that page never renders.
+ * This module answers the missing question: what URL does that file actually
+ * appear on?
+ *
+ * THREE ANSWERS, and the difference between them is the whole design:
+ *   - a non-empty list — these route patterns mount the file, spelled the way the
+ *     framework spells them (`/secrets/$envSlug`, `/orders/:id`);
+ *   - an empty list — this scan understands this repository and nothing mounts it;
+ *   - `undefined` — this scan cannot speak for this repository or this file.
+ * It NEVER guesses. There is no root-URL fallback, because both the plan check and
+ * the agent treat the answer as fact, and a wrong route is worse than no route:
+ * it sends the browser to a page with the server's authority behind it.
+ *
+ * The walk is TRANSITIVE, and that is the new part. The route entry file rarely
+ * renders the changed file directly — the motivating case is four hops
+ * (`route.tsx` -> `SecretDashboardPage.tsx` -> a barrel -> `SecretListView.tsx` ->
+ * `SecretDetailSidebar.tsx`). A per-file `git grep` per hop does not scale to that,
+ * so the reverse import index is built ONCE per repository and then walked
+ * breadth-first from the changed file up to the route entry files.
+ *
+ * Route tables come from two readers: TanStack Router's generated
+ * `routeTree.gen.ts`, which holds both halves of the mapping and needs no parser,
+ * and `sourceRouteExtractor` for React Router / Vue Router. A repository neither
+ * reader recognizes yields `undefined`, not an empty list — and so does any file
+ * that answers nothing in a repository whose table is knowably missing an entry,
+ * see {@link collectRouteEntries}.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { extractDartRoutes } from "./dartRouteExtractor.js";
+import { collectFiles } from "./fileWalk.js";
+import { buildPathSignatures, isIndexModule } from "./pathSignatures.js";
+import { extractSourceRoutes } from "./sourceRouteExtractor.js";
+/** Files that can import, and therefore render, a frontend module. */
+const FRONTEND_SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte|dart)$/i;
+const SKIP_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".svelte-kit", "coverage", "vendor",
+]);
+/** Walk cap. Hitting it means the index is incomplete, and an incomplete index
+ *  cannot honestly say "nothing mounts this" — the whole repository answers
+ *  `undefined` instead. Sized well above the largest frontend we scan. */
+const MAX_FILES = 20000;
+/** A file larger than this is a bundle or a generated blob, not a component that
+ *  imports one. `routeTree.gen.ts` is exempt: it IS the generated route table. */
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_ROUTE_TREE_BYTES = 8 * 1024 * 1024;
+/** Import hops walked upward from the changed file. Beyond this a component is
+ *  shared infrastructure rather than part of one screen. */
+const MAX_DEPTH = 8;
+/** Files visited by one BFS. Truncation, like a truncated walk, forces `undefined`. */
+const MAX_VISITED = 4000;
+/** Above this a file is a shell, a layout or a design-system primitive: it renders
+ *  on so many screens that "the test opened the wrong one" is not a claim this
+ *  check can make. Saying `undefined` keeps it silent instead of wrong. */
+const MAX_ROUTES = 25;
+/** Import specifiers, in the four forms a frontend module writes them. */
+const SPECIFIER_RE = /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|\bimport\s+)(['"`])([^'"`]+)\1/g;
+// ── Path helpers ────────────────────────────────────────────────────────────
+function toPosix(value) {
+    return value.replace(/\\/g, "/");
+}
+function stripExtension(file) {
+    return /\.d\.ts$/i.test(file) ? file.slice(0, -5) : file.slice(0, file.length - path.posix.extname(file).length);
+}
+/** The strings an import specifier can use to name this file: the file itself, the
+ *  file without its extension, and for an `index.*` module its directory. */
+function modulePaths(file) {
+    const paths = [file, stripExtension(file)];
+    if (isIndexModule(file))
+        paths.push(path.posix.dirname(file));
+    return paths;
+}
+/** Repository-relative posix path, or undefined when the input escapes the
+ *  repository. The caller hands us agent-written and scanner-written paths alike. */
+function normalizeRelative(relativePath) {
+    if (typeof relativePath !== "string")
+        return undefined;
+    const raw = toPosix(relativePath.trim()).replace(/^\.\//, "");
+    if (!raw || path.posix.isAbsolute(raw))
+        return undefined;
+    const normalized = path.posix.normalize(raw);
+    if (normalized.startsWith(".."))
+        return undefined;
+    return normalized;
+}
+// ── Import-edge resolution ──────────────────────────────────────────────────
+/** The lookup key `buildPathSignatures` produces, minus the quote character. A
+ *  signature is `<stem><quote>`; the quote is what makes it precise inside a grep,
+ *  and this index is keyed by the stem instead because the specifier is already
+ *  isolated by the time we get here. */
+function stemKeys(file) {
+    return [...new Set(buildPathSignatures(file).map((signature) => signature.slice(0, -1)))];
+}
+/**
+ * The candidate repository paths an import specifier could name.
+ *
+ * A relative specifier resolves against the importer's directory and is exact. A
+ * prefixed one (`@app/x`, `~/x`, `src/x`) is a tsconfig/bundler alias whose target
+ * root this module deliberately does not read: instead the alias is stripped and
+ * the remainder is matched as a path SUFFIX, with the importer required to live
+ * under the same root — so `packages/admin/...` importing `@app/components/Row`
+ * cannot bind to `packages/store/components/Row.tsx`.
+ *
+ * `@scope/name` is also the shape of a scoped npm package, and stripping the scope
+ * off one leaves a single bare segment (`themes` from `@radix-ui/themes`) that the
+ * suffix match will happily bind to a top-level source file of that name. So the
+ * scope is only stripped when what remains is itself a path — two segments or more.
+ * `@/x` is exempt: no package can be named that, so it is always an alias.
+ */
+function specifierCandidates(spec) {
+    const clean = spec.replace(/\/+$/, "");
+    if (!clean)
+        return { relative: false, paths: [] };
+    if (clean.startsWith("."))
+        return { relative: true, paths: [clean] };
+    const segments = clean.split("/");
+    // A single-segment specifier with no prefix is a package name (`react`), never a
+    // repository path. Multi-segment ones can be either, and the shared-root check
+    // below is what keeps `lodash/get` from binding to a source file.
+    if (segments.length === 1)
+        return { relative: false, paths: [] };
+    const paths = [clean];
+    const scopedPackageShape = segments[0].length > 1 && segments[0].startsWith("@") && segments.length < 3;
+    if (!scopedPackageShape && (/^[@~#]/.test(segments[0]) || segments[0] === "src")) {
+        paths.push(segments.slice(1).join("/"));
+    }
+    return { relative: false, paths };
+}
+/** Whether `importer`'s specifier names `candidate`. */
+function specifierNames(importer, spec, candidate) {
+    const { relative, paths } = specifierCandidates(spec);
+    if (paths.length === 0)
+        return false;
+    const targets = modulePaths(candidate);
+    if (relative) {
+        const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(importer), paths[0]));
+        return targets.includes(resolved);
+    }
+    for (const wanted of paths) {
+        for (const target of targets) {
+            if (target === wanted)
+                return true;
+            if (target.endsWith("/" + wanted)) {
+                const root = target.slice(0, target.length - wanted.length - 1);
+                if (importer.startsWith(root + "/"))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+// ── Index construction ──────────────────────────────────────────────────────
+function readFileSafely(absolute, maxBytes) {
+    try {
+        if (fs.statSync(absolute).size > maxBytes)
+            return undefined;
+        return fs.readFileSync(absolute, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function collectFrontendFiles(repositoryPath) {
+    const absolute = collectFiles(repositoryPath, {
+        match: (entry) => FRONTEND_SOURCE_EXT.test(entry.name),
+        limit: MAX_FILES,
+        shouldSkipDir: (entry) => SKIP_DIRS.has(entry.name) || entry.name.startsWith("."),
+    });
+    // Exactly `MAX_FILES` means the walk was cut short (`collectFiles` stops at the
+    // cap), so the index would be missing files that might be importers.
+    if (absolute.length === 0 || absolute.length >= MAX_FILES)
+        return undefined;
+    return absolute.map((file) => toPosix(path.relative(repositoryPath, file)));
+}
+/**
+ * TanStack Router's generated route tree, read rather than parsed.
+ *
+ * The generator writes both halves of the mapping into one file: an `import
+ * { Route as <ident> } from '<module>'` line per entry file, and one block per
+ * route carrying `fullPath` (already stripped of pathless `_layout` segments) and
+ * `preLoaderRoute: typeof <ident>`. Route pattern -> entry file is therefore two
+ * lookups, with no need to interpret `createFileRoute` calls. Absent the generated
+ * file there is no TanStack answer — hand-parsing the route files is a different
+ * job than reading a table that is already committed.
+ */
+function readTanStackRouteTree(repositoryPath, treeFile, filesByStem) {
+    const content = readFileSafely(path.join(repositoryPath, treeFile), MAX_ROUTE_TREE_BYTES);
+    if (!content)
+        return [];
+    const dir = path.posix.dirname(treeFile);
+    const entryFileByIdent = new Map();
+    const blocks = [];
+    let pendingId;
+    let pendingFullPath;
+    for (const line of content.split("\n")) {
+        const imported = /^\s*import\s*\{\s*Route as (\w+)\s*\}\s*from\s*['"]([^'"]+)['"]/.exec(line);
+        if (imported) {
+            const target = resolveWithin(dir, imported[2], filesByStem);
+            if (target)
+                entryFileByIdent.set(imported[1], target);
+            continue;
+        }
+        const id = /^\s*id:\s*'([^']*)'/.exec(line);
+        if (id) {
+            pendingId = id[1];
+            continue;
+        }
+        const fullPath = /^\s*fullPath:\s*'([^']*)'/.exec(line);
+        if (fullPath) {
+            pendingFullPath = fullPath[1];
+            continue;
+        }
+        const preLoader = /^\s*preLoaderRoute:\s*typeof\s+(\w+)/.exec(line);
+        if (preLoader && pendingId !== undefined && pendingFullPath !== undefined) {
+            blocks.push({ id: pendingId, fullPath: pendingFullPath, ident: preLoader[1] });
+            pendingId = undefined;
+            pendingFullPath = undefined;
+        }
+    }
+    const entries = [];
+    for (const block of blocks) {
+        const entryFile = entryFileByIdent.get(block.ident);
+        if (!entryFile)
+            continue;
+        if (block.fullPath) {
+            entries.push({ pattern: block.fullPath, entryFile });
+            continue;
+        }
+        // A pathless layout has no URL of its own; it renders on every route nested
+        // under it. Reporting nothing for it would read as "nothing mounts this file",
+        // which is the one answer that is definitely wrong for a layout.
+        for (const nested of blocks) {
+            if (nested.fullPath && nested.id.startsWith(block.id + "/"))
+                entries.push({ pattern: nested.fullPath, entryFile });
+        }
+    }
+    return entries;
+}
+/** The config file that proves a framework is configured, rather than that a
+ *  `pages/` directory happens to exist. A React app with a conventional `pages/`
+ *  folder routes in code, and reading it as Next.js invents every URL. */
+const FRAMEWORK_BY_CONFIG = new Map([
+    ["next.config.js", "next"],
+    ["next.config.mjs", "next"],
+    ["next.config.cjs", "next"],
+    ["next.config.ts", "next"],
+    ["nuxt.config.js", "nuxt"],
+    ["nuxt.config.mjs", "nuxt"],
+    ["nuxt.config.ts", "nuxt"],
+    ["svelte.config.js", "sveltekit"],
+    ["svelte.config.mjs", "sveltekit"],
+    ["svelte.config.ts", "sveltekit"],
+]);
+/** Page file extensions Next.js compiles. */
+const NEXT_PAGE_EXT = /\.(tsx|jsx|ts|js|mjs)$/;
+/**
+ * Which framework routes which part of the repository, as directory -> framework,
+ * the directory being repository-relative posix and `""` for the root.
+ *
+ * Reads the file list the index already walked, so it inherits that walk's skip
+ * list and caps and costs no I/O. Locating the config beats a list of likely
+ * directories: a frontend under `packages/` is as common as one under `apps/`,
+ * and the config's directory is also the only honest bound on which files the
+ * framework owns when a repository holds more than one app.
+ *
+ * Exported for the convention matrix in the tests; nothing else calls it.
+ */
+export function detectFrameworkRoots(files) {
+    const roots = new Map();
+    for (const file of files) {
+        const segments = file.split("/");
+        const framework = FRAMEWORK_BY_CONFIG.get(segments[segments.length - 1]);
+        if (!framework)
+            continue;
+        // Two frameworks in one directory cannot be read unambiguously; the first in
+        // the file list wins, and that list is stable.
+        const dir = segments.slice(0, -1).join("/");
+        if (!roots.has(dir))
+            roots.set(dir, framework);
+    }
+    return roots;
+}
+/** Directories a Flutter `pubspec.yaml` sits in, plus one level of fan-out under
+ *  `apps/` and `packages/` for a monorepo. */
+const PUBSPEC_DIRS = [".", "app", "mobile", "frontend", "web", "client"];
+const PUBSPEC_MONOREPO_PARENTS = ["apps", "packages"];
+/**
+ * The Flutter apps in the repository, as package name -> the directory holding
+ * their pubspec (repository-relative posix, `""` for the root). Empty means no
+ * Flutter app, which is what gates reading `.dart` files as routes at all: a
+ * pure-Dart project — a CLI tool, a server — has a pubspec with no Flutter SDK
+ * line and must not have its files read as screens.
+ *
+ * Ported from `hasFlutterSdkDep` in `scopeAssessment.ts`, which the v2 branch
+ * deleted, and widened to return the package name because `package:` imports
+ * cannot be resolved without it. Matching the `sdk: flutter` line beats parsing
+ * the YAML: it is the one line unique to a Flutter project.
+ */
+function flutterPackages(repositoryPath) {
+    const found = new Map();
+    const readPubspec = (dir) => {
+        const content = readFileSafely(path.join(repositoryPath, dir, "pubspec.yaml"), MAX_FILE_BYTES);
+        if (content === undefined || !/^\s+sdk:\s*flutter\s*$/m.test(content))
+            return;
+        const name = /^name:\s*(\S+)\s*$/m.exec(content);
+        if (name)
+            found.set(name[1], dir === "." ? "" : toPosix(dir));
+    };
+    for (const dir of PUBSPEC_DIRS)
+        readPubspec(dir);
+    for (const parent of PUBSPEC_MONOREPO_PARENTS) {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(repositoryPath, parent), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                readPubspec(path.join(parent, entry.name));
+        }
+    }
+    return found;
+}
+/** The repository path a `package:` import names — `package:myapp/x.dart` is
+ *  `<myapp's directory>/lib/x.dart`. Rewriting it lets the ordinary specifier
+ *  match find the file; without this a widget imported that way reads as
+ *  unmounted. Relative Dart imports need no help. */
+function dartPackagePath(spec, packages) {
+    if (!spec.startsWith("package:"))
+        return undefined;
+    const slash = spec.indexOf("/");
+    if (slash < 0)
+        return undefined;
+    const dir = packages.get(spec.slice("package:".length, slash));
+    if (dir === undefined)
+        return undefined;
+    return (dir === "" ? "" : dir + "/") + "lib/" + spec.slice(slash + 1);
+}
+/**
+ * The URL `relativePath` serves under `framework`, or undefined when the file is
+ * not a page in that framework's convention. `relativePath` is relative to the
+ * framework root, not to the repository.
+ *
+ * The conventions are kept PER FRAMEWORK because they disagree. Route groups
+ * `(shop)` vanish from the URL in the Next app router and in SvelteKit, and are a
+ * literal directory name in the Next pages router and in Nuxt. An underscore
+ * names a parameter in Nuxt 2 and marks a non-route file in Next. Pooling the
+ * rules produced URLs no framework serves.
+ *
+ * Exported for the convention matrix in the tests; `fileSystemRouteEntries` is
+ * the only caller in this module.
+ */
+export function frameworkRouteFor(relativePath, framework) {
+    // Next.js and Nuxt accept their routing directory at the root or under `src/`,
+    // and neither spelling appears in the URL.
+    const below = relativePath.startsWith("src/") ? relativePath.slice(4) : relativePath;
+    switch (framework) {
+        case "next":
+            return nextRoute(below);
+        case "nuxt":
+            return nuxtRoute(below);
+        case "sveltekit":
+            return svelteKitRoute(below);
+    }
+}
+/** `[id]`, `[...slug]` and `[[...slug]]` all name one parameter. The optional
+ *  catch-all has to be matched first, or its outer bracket survives as `:slug]`. */
+function bracketParam(segment) {
+    return segment
+        .replace(/\[\[\.\.\.(\w+)\]\]/g, ":$1")
+        .replace(/\[\.\.\.(\w+)\]/g, ":$1")
+        .replace(/\[(\w+)\]/g, ":$1");
+}
+/** Segments the Next app router organises the tree with and leaves out of the
+ *  URL: route groups `(shop)`, private folders `_internal`, slots `@modal`. */
+function isNextAppOrganisingSegment(segment) {
+    return /^\(.+\)$/.test(segment) || segment.startsWith("_") || segment.startsWith("@");
+}
+function nextRoute(below) {
+    const app = /^app\/(.*)$/.exec(below);
+    if (app) {
+        const ext = NEXT_PAGE_EXT.exec(app[1]);
+        if (!ext)
+            return undefined;
+        const segments = app[1].slice(0, app[1].length - ext[0].length).split("/");
+        // `page` alone renders a URL: `route` is an HTTP handler, and `layout`,
+        // `template`, `loading`, `error` and `not-found` wrap a page without being one.
+        if (segments.pop() !== "page")
+            return undefined;
+        return "/" + segments.filter((s) => !isNextAppOrganisingSegment(s)).map(bracketParam).join("/");
+    }
+    const pages = /^pages\/(.*)$/.exec(below);
+    if (!pages)
+        return undefined;
+    if (pages[1] === "api" || pages[1].startsWith("api/"))
+        return undefined;
+    const ext = NEXT_PAGE_EXT.exec(pages[1]);
+    if (!ext)
+        return undefined;
+    const stem = pages[1].slice(0, pages[1].length - ext[0].length);
+    // Next reserves a leading underscore for files that are not routes: `_app` and
+    // `_document` wrap every page, `_error` replaces one.
+    if ((stem.split("/").pop() ?? "").startsWith("_"))
+        return undefined;
+    // No route groups in this router — `(shop)` is a literal directory name.
+    const segments = stem.replace(/(?:^|\/)index$/, "").split("/");
+    return "/" + segments.filter((s) => s !== "").map(bracketParam).join("/");
+}
+function nuxtRoute(below) {
+    const pages = /^pages\/(.*)\.vue$/.exec(below);
+    if (!pages)
+        return undefined;
+    const segments = pages[1].replace(/(?:^|\/)index$/, "").split("/");
+    return "/" + segments.filter((s) => s !== "").map(nuxtParam).join("/");
+}
+/** Nuxt 3 spells a parameter `[id]`, Nuxt 2 spells it `_id`. The underscore names
+ *  one only as the WHOLE segment: a blanket rule made `order_total` `/order:total`. */
+function nuxtParam(segment) {
+    const bracketed = bracketParam(segment);
+    if (bracketed !== segment)
+        return bracketed;
+    return segment.replace(/^_(\w+)$/, ":$1");
+}
+function svelteKitRoute(below) {
+    const routes = /^routes\/(.*)$/.exec(below);
+    if (!routes)
+        return undefined;
+    const segments = routes[1].split("/");
+    // `+page.svelte` renders the URL; `+layout.svelte` wraps it, and `+page.ts` and
+    // `+server.ts` are load and endpoint modules.
+    if (segments.pop() !== "+page.svelte")
+        return undefined;
+    // The one non-Next framework with route groups, spelled the same way.
+    return "/" + segments.filter((s) => !/^\(.+\)$/.test(s)).map(svelteParam).join("/");
+}
+/** SvelteKit adds an optional parameter, `[[lang]]`, to the bracket spellings. */
+function svelteParam(segment) {
+    return bracketParam(segment.replace(/\[\[(?!\.\.\.)(\w+)\]\]/g, "[$1]"));
+}
+/**
+ * Routes a repository declares by where it puts its files rather than in code.
+ *
+ * The page file IS the route entry, so one path yields both halves of the
+ * mapping. Without this reader a Next.js, Nuxt or SvelteKit repository has no
+ * table at all, and every file in it answers `undefined` however well the import
+ * walk works — the routes are simply never written down for the extractor to find.
+ */
+function fileSystemRouteEntries(files) {
+    // Most specific root first: with a config at the repository root AND at
+    // `apps/web`, a file under `apps/web` belongs to the inner app.
+    const roots = [...detectFrameworkRoots(files)].sort((a, b) => b[0].length - a[0].length);
+    if (roots.length === 0)
+        return [];
+    const entries = [];
+    for (const file of files) {
+        for (const [root, framework] of roots) {
+            if (root !== "" && !file.startsWith(root + "/"))
+                continue;
+            const pattern = frameworkRouteFor(root === "" ? file : file.slice(root.length + 1), framework);
+            if (pattern !== undefined)
+                entries.push({ pattern, entryFile: file });
+            // The owning root is settled whether or not the file is a page in it.
+            break;
+        }
+    }
+    return entries;
+}
+/** The repository file a module specifier written in `dir` names, if any. Narrowed
+ *  through the stem index first: the route tree names hundreds of entry files, and
+ *  comparing each against every file in the repository is quadratic. */
+function resolveWithin(dir, spec, filesByStem) {
+    const base = spec.startsWith(".") ? path.posix.normalize(path.posix.join(dir, spec)) : spec;
+    const lastSegment = base.split("/").pop();
+    if (!lastSegment)
+        return undefined;
+    for (const file of filesByStem.get("/" + lastSegment) ?? []) {
+        if (modulePaths(file).includes(base))
+            return file;
+    }
+    return undefined;
+}
+/**
+ * The route table, and whether it is knowably missing an entry.
+ *
+ * A source route states a path and the component mounted at it; the extractor
+ * resolves that component to a file only when it was imported, so a route
+ * declared with a locally defined or library component leaves a path with no
+ * entry file. Dropping those quietly leaves a table that still looks like a
+ * table — and a file mounted only through a dropped route then answers `[]`,
+ * "nothing renders this", which is the one answer that shuts off UI recording.
+ *
+ * So a dropped route marks the table incomplete rather than discarding it. The
+ * routes that did resolve still answer, and it is only the EMPTY answer that
+ * the missing entry makes unsafe: a file with no route in an incomplete table
+ * answers `undefined` instead of `[]`, see {@link candidatesFor}.
+ *
+ * A generated `routeTree.gen.ts` is the exception: it carries the table for the
+ * whole router, so a source route the extractor could not follow adds nothing
+ * and takes nothing away.
+ */
+function collectRouteEntries(repositoryPath, files, fileSet, filesByStem, packages) {
+    const entries = [];
+    let dartIncomplete = false;
+    for (const file of files) {
+        if (path.posix.basename(file) === "routeTree.gen.ts") {
+            entries.push(...readTanStackRouteTree(repositoryPath, file, filesByStem));
+        }
+    }
+    if (packages.size > 0) {
+        for (const route of extractDartRoutes(repositoryPath)) {
+            const relative = route.componentFile ? toPosix(path.relative(repositoryPath, route.componentFile)) : undefined;
+            // A widget this reader could not trace to a file leaves the table short of
+            // a route, the same way an unresolved web component does.
+            if (relative && fileSet.has(relative))
+                entries.push({ pattern: route.path, entryFile: relative });
+            else
+                dartIncomplete = true;
+        }
+    }
+    const generated = entries.length > 0;
+    // Deliberately after `generated`: a page table proves what renders each URL, but
+    // it does not prove that no OTHER router also mounts a component, so a source
+    // route this scan could not follow still marks the table incomplete.
+    entries.push(...fileSystemRouteEntries(files));
+    let complete = true;
+    for (const route of extractSourceRoutes(repositoryPath)) {
+        if (!route.path)
+            continue;
+        const relative = route.componentFile ? toPosix(path.relative(repositoryPath, route.componentFile)) : undefined;
+        if (relative && fileSet.has(relative)) {
+            entries.push({ pattern: route.path, entryFile: relative });
+            continue;
+        }
+        if (!generated)
+            complete = false;
+    }
+    return { entries, complete: complete && !dartIncomplete };
+}
+function buildIndex(repositoryPath) {
+    const files = collectFrontendFiles(repositoryPath);
+    if (!files)
+        return undefined;
+    const fileSet = new Set(files);
+    // Stem index first, so each specifier costs one map lookup and a handful of
+    // path comparisons rather than a scan of every file in the repository.
+    const filesByStem = new Map();
+    for (const file of files) {
+        for (const stem of stemKeys(file)) {
+            const bucket = filesByStem.get(stem);
+            if (bucket)
+                bucket.push(file);
+            else
+                filesByStem.set(stem, [file]);
+        }
+    }
+    const packages = flutterPackages(repositoryPath);
+    const table = collectRouteEntries(repositoryPath, files, fileSet, filesByStem, packages);
+    // No route table found at all: this scan does not understand the repository,
+    // which is a different statement from "nothing mounts this file".
+    if (table.entries.length === 0)
+        return undefined;
+    const patternsByEntry = new Map();
+    for (const entry of table.entries) {
+        const patterns = patternsByEntry.get(entry.entryFile) ?? [];
+        if (!patterns.includes(entry.pattern))
+            patterns.push(entry.pattern);
+        patternsByEntry.set(entry.entryFile, patterns);
+    }
+    const importers = new Map();
+    let importsComplete = true;
+    for (const file of files) {
+        const content = readFileSafely(path.join(repositoryPath, file), MAX_FILE_BYTES);
+        if (!content) {
+            importsComplete = false;
+            continue;
+        }
+        const seen = new Set();
+        for (const match of content.matchAll(SPECIFIER_RE)) {
+            const spec = dartPackagePath(match[2], packages) ?? match[2];
+            const lastSegment = spec.replace(/\/+$/, "").split("/").pop();
+            if (!lastSegment)
+                continue;
+            for (const candidate of filesByStem.get("/" + lastSegment) ?? []) {
+                if (candidate === file || seen.has(candidate))
+                    continue;
+                if (!specifierNames(file, spec, candidate))
+                    continue;
+                seen.add(candidate);
+                const bucket = importers.get(candidate);
+                if (bucket)
+                    bucket.push(file);
+                else
+                    importers.set(candidate, [file]);
+            }
+        }
+    }
+    return { fileSet, importers, patternsByEntry, tableComplete: table.complete, importsComplete };
+}
+// ── Query ───────────────────────────────────────────────────────────────────
+function candidatesFor(index, file) {
+    // Where each visited file was reached FROM — the file it imports. Following the
+    // links from a route entry back down yields the mount chain.
+    const cameFrom = new Map();
+    const visited = new Set([file]);
+    let frontier = [file];
+    const candidates = [];
+    const collect = (reached) => {
+        for (const pattern of index.patternsByEntry.get(reached) ?? []) {
+            const chain = [reached];
+            for (let at = reached; cameFrom.has(at); at = cameFrom.get(at))
+                chain.push(cameFrom.get(at));
+            candidates.push({ routePattern: pattern, mountChain: chain });
+        }
+    };
+    collect(file);
+    for (let depth = 0; depth < MAX_DEPTH && frontier.length > 0; depth++) {
+        const next = [];
+        for (const current of frontier) {
+            for (const importer of index.importers.get(current) ?? []) {
+                if (visited.has(importer))
+                    continue;
+                if (visited.size >= MAX_VISITED)
+                    return undefined; // incomplete walk states nothing
+                visited.add(importer);
+                cameFrom.set(importer, current);
+                next.push(importer);
+                collect(importer);
+            }
+        }
+        frontier = next;
+    }
+    // Files were still queued when the depth ran out, so a route above MAX_DEPTH
+    // would be missed — the same truncation rule MAX_VISITED already applies.
+    if (frontier.length > 0)
+        return undefined;
+    // One route can be reached by several chains; the first one found is the
+    // shortest, because the walk is breadth-first.
+    const byPattern = new Map();
+    for (const candidate of candidates) {
+        if (!byPattern.has(candidate.routePattern))
+            byPattern.set(candidate.routePattern, candidate);
+    }
+    if (byPattern.size > MAX_ROUTES)
+        return undefined;
+    // Nothing mounts this file — but a route the table is missing, or an importer
+    // the index could not read, might, so that is not a claim an incomplete scan
+    // can make.
+    if (byPattern.size === 0 && !(index.tableComplete && index.importsComplete))
+        return undefined;
+    return [...byPattern.values()];
+}
+/**
+ * A lookup bound to one repository. The index is built on the first question and
+ * reused for the rest, so a plan with ten UI tests scans the repository once.
+ *
+ * Fails closed: any error anywhere becomes `undefined`. A scan is best-effort, and
+ * its failure is not evidence about the file it was asked about.
+ */
+export function createScreenRouteLookup(repositoryPath) {
+    let index;
+    let built = false;
+    const load = () => {
+        if (!built) {
+            built = true;
+            index = repositoryPath ? buildIndex(repositoryPath) : undefined;
+        }
+        return index;
+    };
+    return {
+        candidatesFor(relativePath) {
+            try {
+                const file = normalizeRelative(relativePath);
+                if (!file)
+                    return undefined;
+                const loaded = load();
+                if (!loaded)
+                    return undefined;
+                // A file the scan never saw is a file it cannot speak for: a backend path,
+                // a deleted file, or a misspelling. None of those means "no route mounts it".
+                if (!loaded.fileSet.has(file))
+                    return undefined;
+                return candidatesFor(loaded, file);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        routePatterns() {
+            try {
+                const loaded = load();
+                if (!loaded)
+                    return [];
+                return [...new Set([...loaded.patternsByEntry.values()].flat())];
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}
+/** The routes for a file, without the evidence. */
+export function createScreenRouteResolver(repositoryPath) {
+    const lookup = createScreenRouteLookup(repositoryPath);
+    return (relativePath) => lookup.candidatesFor(relativePath)?.map((candidate) => candidate.routePattern);
+}
+/** The same answer with its evidence: every route, and the import chain that
+ *  reaches the file from that route's entry file. */
+export function createScreenRouteCandidateResolver(repositoryPath) {
+    const lookup = createScreenRouteLookup(repositoryPath);
+    return (relativePath) => lookup.candidatesFor(relativePath);
+}
+/** One question, one scan. Convenience over {@link createScreenRouteResolver} for
+ *  callers that ask about a single file. */
+export function resolveScreenRoutes(repositoryPath, relativePath) {
+    return createScreenRouteResolver(repositoryPath)(relativePath);
+}
+/** One question, one scan, with the mount chains. */
+export function resolveScreenRouteCandidates(repositoryPath, relativePath) {
+    return createScreenRouteCandidateResolver(repositoryPath)(relativePath);
+}