@elench/testkit 0.1.64 → 0.1.65

package/lib/coverage/evidence.mjs

@@ -1,12 +1,14 @@
 import fs from "fs";
 import path from "path";
-import { extractHttpSuiteRequests, extractPlaywrightVisitedRoutes } from "./next-static-analysis.mjs";
+import { extractHttpRequests, extractPlaywrightVisitedRoutes } from "@elench/ts-analysis";
 import {
   apiRouteLookupKey,
+  DYNAMIC_SEGMENT_TOKEN,
   HTTP_METHODS,
   dedupeTargets,
   findMatchingApiRouteEntry,
   findMatchingRouteValue,
+  normalizeRoute,
   toApiRequestPath,
   toSelectionType,
 } from "./shared.mjs";
@@ -36,7 +38,13 @@ export function inferCoveredNodeIdsForTest(entry, context) {
 
   // Capability: Playwright page routes (content-first, path-fallback)
   if (entry.framework === "playwright") {
-    const gotoRoutes = content ? extractPlaywrightVisitedRoutes(content, entry.filePath) : [];
+    const gotoRoutes = content
+      ? extractPlaywrightVisitedRoutes(content, {
+          filePath: entry.filePath,
+          normalizeRoute,
+          dynamicSegmentToken: DYNAMIC_SEGMENT_TOKEN,
+        })
+      : [];
     const routes = gotoRoutes.length > 0
       ? gotoRoutes
       : (() => { const r = inferPageRouteFromTestFile(entry.filePath, context.nextAppRoot, context.serviceRoot); return r ? [r] : []; })();
@@ -56,7 +64,11 @@ export function inferCoveredNodeIdsForTest(entry, context) {
 
   // Capability: HTTP request extraction (any test type with rawReq/fetch/wrapper calls)
   if (content) {
-    const requests = extractHttpSuiteRequests(content, entry.filePath);
+    const requests = extractHttpRequests(content, {
+      filePath: entry.filePath,
+      normalizeRoute,
+      dynamicSegmentToken: DYNAMIC_SEGMENT_TOKEN,
+    });
     for (const request of requests) {
       if (!request.path.startsWith("/api/")) continue;
       const routeEntry = resolveApiRouteEntry(context, request.method, request.path);

package/lib/coverage/evidence.test.mjs

@@ -4,7 +4,7 @@ import {
   extractPlaywrightTargetsFromContent,
   inferDataCapabilitiesFromOwner,
 } from "./evidence.mjs";
-import { extractPlaywrightVisitedRoutes } from "./next-static-analysis.mjs";
+import { extractPlaywrightVisitedRoutes } from "@elench/ts-analysis";
 import { DYNAMIC_SEGMENT_TOKEN } from "./shared.mjs";
 
 describe("coverage evidence helpers", () => {
@@ -60,19 +60,28 @@ describe("extractPlaywrightVisitedRoutes", () => {
         await page.goto("https://external.com/path"); // external
         await page.goto("http://localhost:3000/events"); // same-origin absolute
       });
-    `, "nav.pw.testkit.ts")).toEqual(["/dashboard", "/settings/profile", "/events"]);
+    `, {
+      filePath: "nav.pw.testkit.ts",
+      dynamicSegmentToken: DYNAMIC_SEGMENT_TOKEN,
+    })).toEqual(["/dashboard", "/settings/profile", "/events"]);
   });
 
   it("handles property chain: foo.page.goto()", () => {
     expect(extractPlaywrightVisitedRoutes(`
       await this.page.goto("/projects");
-    `, "test.pw.testkit.ts")).toEqual(["/projects"]);
+    `, {
+      filePath: "test.pw.testkit.ts",
+      dynamicSegmentToken: DYNAMIC_SEGMENT_TOKEN,
+    })).toEqual(["/projects"]);
   });
 
   it("normalizes dynamic goto expressions into route patterns", () => {
     expect(extractPlaywrightVisitedRoutes(`
       await page.goto(\`/projects/\${id}\`);
       await page.goto(someVar);
-    `, "test.pw.testkit.ts")).toEqual([`/projects/${DYNAMIC_SEGMENT_TOKEN}`]);
+    `, {
+      filePath: "test.pw.testkit.ts",
+      dynamicSegmentToken: DYNAMIC_SEGMENT_TOKEN,
+    })).toEqual([`/projects/${DYNAMIC_SEGMENT_TOKEN}`]);
   });
 });

package/lib/coverage/graph-builder.mjs

@@ -1,7 +1,7 @@
 import { discoverDataCapabilities } from "./backend-discovery.mjs";
 import { buildEvidenceDetails, inferCoveredNodeIdsForTest } from "./evidence.mjs";
-import { findNextAppRoot, resolveImportToSourceFile, resolveServiceRoot } from "./fs-walk.mjs";
-import { discoverApiRoutes, discoverPageViews, discoverServerActions } from "./next-discovery.mjs";
+import { resolveServiceRoot } from "./fs-walk.mjs";
+import { convertNextAnalysisToGraph } from "./next-ir-to-graph.mjs";
 import {
   appendGraph,
   createEmptyGraph,
@@ -11,6 +11,7 @@ import {
   toSelectionType,
 } from "./shared.mjs";
 import { DEFAULT_DISCOVERY_EXCLUDES, normalizeDiscoveryConfig } from "../discovery/path-policy.mjs";
+import { createNextAnalysisProject } from "@elench/next-analysis";
 
 export function buildCoverageGraph({ productDir, repoDiscovery = {}, services = {}, discoveryFiles = [] }) {
   const graph = createEmptyGraph();
@@ -85,7 +86,8 @@ export function buildCoverageGraph({ productDir, repoDiscovery = {}, services =
 
 export function buildServiceCoverageContext(productDir, serviceName, config, repoDiscovery = {}) {
   const serviceRoot = resolveServiceRoot(productDir, config);
-  const nextAppRoot = findNextAppRoot(serviceRoot);
+  const nextProject = createNextAnalysisProject({ rootDir: serviceRoot });
+  const nextAppRoot = nextProject.findAppRoot();
   if (!nextAppRoot) return null;
   const serviceDiscovery = normalizeDiscoveryConfig(config?.discovery, { allowRoots: true });
   const exclude = [
@@ -97,40 +99,37 @@ export function buildServiceCoverageContext(productDir, serviceName, config, rep
   ];
 
   const graph = createEmptyGraph();
-  const discoveryOptions = {
+  const pages = nextProject.discoverPages();
+  const apiRoutes = nextProject.discoverApiRoutes();
+  const serverActions = nextProject.discoverServerActions();
+  const routeTrees = pages.map((page) => nextProject.analyzeRouteTree(page.route)).filter(Boolean);
+  const converted = convertNextAnalysisToGraph({
     serviceName,
-    serviceRoot,
-    nextAppRoot,
-    exclude,
-    resolveImportToSourceFile,
-  };
-  const pages = discoverPageViews(discoveryOptions);
-  const apiRoutes = discoverApiRoutes(discoveryOptions);
-  const serverActions = discoverServerActions({
-    serviceName,
-    serviceRoot,
-    exclude,
-    resolveImportToSourceFile,
+    pages,
+    apiRoutes,
+    serverActions,
+    routeTrees,
   });
 
-  for (const node of [...pages.nodes, ...apiRoutes.nodes, ...serverActions.nodes]) graph.nodes.push(node);
-  for (const edge of [...pages.edges, ...apiRoutes.edges, ...serverActions.edges]) graph.edges.push(edge);
+  for (const node of converted.nodes) graph.nodes.push(node);
+  for (const edge of converted.edges) graph.edges.push(edge);
 
   const dataAugmentation = discoverDataCapabilities({ serviceName, serviceRoot, nodes: graph.nodes });
   for (const node of dataAugmentation.nodes) graph.nodes.push(node);
   for (const edge of dataAugmentation.edges) graph.edges.push(edge);
+  for (const diagnostic of nextProject.getDiagnostics()) graph.diagnostics.push(diagnostic);
 
-  const pageByRoute = new Map(pages.pageEntries.map((entry) => [entry.route, entry]));
+  const pageByRoute = new Map(converted.pageEntries.map((entry) => [entry.route, entry]));
   const apiRouteByKey = new Map(
-    apiRoutes.routeEntries.map((entry) => [`${entry.method}:${entry.requestPath}`, entry])
+    converted.routeEntries.map((entry) => [`${entry.method}:${entry.requestPath}`, entry])
   );
   const serverActionByExportKey = new Map(
-    serverActions.actionEntries.map((entry) => [`${entry.sourceFile}#${entry.exportName}`, entry])
+    converted.actionEntries.map((entry) => [`${entry.sourceFile}#${entry.exportName}`, entry])
   );
 
-  for (const pageEntry of pages.pageEntries) {
+  for (const pageEntry of converted.pageEntries) {
     for (const request of pageEntry.requests) {
-      const apiRoute = findMatchingApiRouteEntry(request.method, request.path, apiRoutes.routeEntries);
+      const apiRoute = findMatchingApiRouteEntry(request.method, request.path, converted.routeEntries);
       if (!apiRoute) continue;
       graph.edges.push({
         id: `handles:${request.node.id}:${apiRoute.node.id}`,
@@ -161,7 +160,7 @@ export function buildServiceCoverageContext(productDir, serviceName, config, rep
     graph,
     pageByRoute,
     apiRouteByKey,
-    apiRouteEntries: apiRoutes.routeEntries,
+    apiRouteEntries: converted.routeEntries,
     serverActionByExportKey,
     dataCapabilities: dataAugmentation.nodes,
   };

package/lib/coverage/next-ir-to-graph.mjs

@@ -0,0 +1,240 @@
+import {
+  normalizePath,
+  pageLabelFromRoute,
+} from "@elench/next-analysis";
+import {
+  dedupeEdges,
+  dedupeNodes,
+  findMatchingApiRouteEntry,
+  hasWord,
+  modulePathKey,
+} from "./shared.mjs";
+
+export function convertNextAnalysisToGraph({ serviceName, pages = [], apiRoutes = [], serverActions = [], routeTrees = [] }) {
+  const nodes = [];
+  const edges = [];
+  const pageEntries = [];
+  const routeEntries = [];
+  const actionEntries = [];
+
+  const routeTreeByRoute = new Map(routeTrees.filter(Boolean).map((entry) => [entry.route, entry]));
+
+  for (const page of pages) {
+    const pageNode = {
+      id: `page_view:${serviceName}:${page.route}`,
+      kind: "page_view",
+      service: serviceName,
+      label: pageLabelFromRoute(page.route),
+      route: page.route,
+      filePath: page.filePath,
+    };
+    nodes.push(pageNode);
+
+    const routeTree = routeTreeByRoute.get(page.route);
+    const surfacesByTargetValue = new Map();
+    if (routeTree) {
+      for (const surface of routeTree.surfaces) {
+        const surfaceNode = {
+          id: `ui_surface:${serviceName}:${page.route}:${surface.targetHint?.value || `${surface.filePath}:${surface.tagName}:${surface.line}`}`,
+          kind: "ui_surface",
+          service: serviceName,
+          label: surface.label,
+          route: page.route,
+          filePath: surface.filePath,
+          ...(surface.targetHint ? { target: surface.targetHint } : {}),
+          metadata: {
+            surfaceKind: surface.surfaceKind,
+            tagName: surface.tagName,
+          },
+        };
+        nodes.push(surfaceNode);
+        edges.push({
+          id: `contains:${pageNode.id}:${surfaceNode.id}`,
+          kind: "contains",
+          from: pageNode.id,
+          to: surfaceNode.id,
+          confidence: "high",
+        });
+        if (surface.targetHint?.kind === "testId") {
+          surfacesByTargetValue.set(surface.targetHint.value, surfaceNode);
+        }
+        if (surface.actionId) {
+          const actionKey = stripActionPrefix(surface.actionId, page.route);
+          edges.push({
+            id: `triggers:${surfaceNode.id}:ui_action:${serviceName}:${page.route}:${actionKey}`,
+            kind: "triggers",
+            from: surfaceNode.id,
+            to: `ui_action:${serviceName}:${page.route}:${actionKey}`,
+            confidence: "high",
+          });
+        }
+      }
+
+      for (const action of routeTree.actions) {
+        const actionKey = stripActionPrefix(action.id, page.route);
+        nodes.push({
+          id: `ui_action:${serviceName}:${page.route}:${actionKey}`,
+          kind: "ui_action",
+          service: serviceName,
+          label: action.label,
+          route: page.route,
+          filePath: action.filePath,
+          metadata: {
+            bindingKind: action.bindingKind,
+            actionProp: action.actionProp,
+          },
+        });
+      }
+
+      for (const request of routeTree.requests) {
+        const ownerId = mapRouteTreeOwnerToGraphId(serviceName, page.route, request.ownerId);
+        const requestNode = {
+          id: `client_request:${serviceName}:${request.filePath}:${request.ownerId}:${request.method}:${request.path}`,
+          kind: "client_request",
+          service: serviceName,
+          label: `${request.method} ${request.path}`,
+          method: request.method,
+          path: request.path,
+          filePath: request.filePath,
+        };
+        nodes.push(requestNode);
+        edges.push({
+          id: `requests:${ownerId}:${requestNode.id}`,
+          kind: "requests",
+          from: ownerId,
+          to: requestNode.id,
+          confidence: request.confidence,
+        });
+      }
+
+      pageEntries.push({
+        node: pageNode,
+        route: page.route,
+        filePath: page.filePath,
+        requests: routeTree.requests.map((request) => ({
+          originNodeId: mapRouteTreeOwnerToGraphId(serviceName, page.route, request.ownerId),
+          node: {
+            id: `client_request:${serviceName}:${request.filePath}:${request.ownerId}:${request.method}:${request.path}`,
+            kind: "client_request",
+            service: serviceName,
+            label: `${request.method} ${request.path}`,
+            method: request.method,
+            path: request.path,
+            filePath: request.filePath,
+          },
+          method: request.method,
+          path: request.path,
+        })),
+        serverActionRefs: routeTree.serverActionRefs.map((ref) => ({
+          originNodeId: mapRouteTreeOwnerToGraphId(serviceName, page.route, ref.ownerId),
+          exportKey: ref.exportKey,
+          confidence: ref.confidence,
+        })),
+        surfacesByTargetValue,
+      });
+    } else {
+      pageEntries.push({
+        node: pageNode,
+        route: page.route,
+        filePath: page.filePath,
+        requests: [],
+        serverActionRefs: [],
+        surfacesByTargetValue,
+      });
+    }
+  }
+
+  for (const apiRoute of apiRoutes) {
+    const node = {
+      id: `api_route:${serviceName}:${apiRoute.method}:${apiRoute.requestPath}`,
+      kind: "api_route",
+      service: serviceName,
+      label: `${apiRoute.method} ${apiRoute.requestPath}`,
+      route: apiRoute.route,
+      method: apiRoute.method,
+      path: apiRoute.requestPath,
+      filePath: apiRoute.filePath,
+    };
+    nodes.push(node);
+    routeEntries.push({
+      node,
+      method: apiRoute.method,
+      route: apiRoute.route,
+      requestPath: apiRoute.requestPath,
+      filePath: apiRoute.filePath,
+    });
+
+    for (const backendRef of apiRoute.backendRefs || []) {
+      const capabilityNode = createServerCapabilityNode(serviceName, backendRef);
+      nodes.push(capabilityNode);
+      edges.push({
+        id: `delegates_to:${node.id}:${capabilityNode.id}`,
+        kind: "delegates_to",
+        from: node.id,
+        to: capabilityNode.id,
+        confidence: "high",
+      });
+    }
+  }
+
+  for (const serverAction of serverActions) {
+    const node = {
+      id: `server_action:${serviceName}:${serverAction.filePath}#${serverAction.exportName}`,
+      kind: "server_action",
+      service: serviceName,
+      label: serverAction.exportName,
+      filePath: serverAction.filePath,
+    };
+    nodes.push(node);
+    actionEntries.push({
+      node,
+      exportName: serverAction.exportName,
+      sourceFile: serverAction.filePath,
+    });
+    for (const backendRef of serverAction.backendRefs || []) {
+      const capabilityNode = createServerCapabilityNode(serviceName, backendRef);
+      nodes.push(capabilityNode);
+      edges.push({
+        id: `delegates_to:${node.id}:${capabilityNode.id}`,
+        kind: "delegates_to",
+        from: node.id,
+        to: capabilityNode.id,
+        confidence: "high",
+      });
+    }
+  }
+
+  return {
+    nodes: dedupeNodes(nodes),
+    edges: dedupeEdges(edges),
+    pageEntries,
+    routeEntries,
+    actionEntries,
+  };
+}
+
+function mapRouteTreeOwnerToGraphId(serviceName, route, ownerId) {
+  if (ownerId === `page:${route}`) return `page_view:${serviceName}:${route}`;
+  if (ownerId.startsWith("action:")) {
+    return `ui_action:${serviceName}:${route}:${stripActionPrefix(ownerId, route)}`;
+  }
+  return ownerId;
+}
+
+function stripActionPrefix(actionId, route) {
+  const prefix = `action:${route}:`;
+  return actionId.startsWith(prefix) ? actionId.slice(prefix.length) : actionId;
+}
+
+function createServerCapabilityNode(serviceName, backendRef) {
+  return {
+    id: `server_capability:${modulePathKey(backendRef.modulePath)}#${backendRef.exportName}`,
+    kind: "server_capability",
+    service: serviceName,
+    label: backendRef.exportName,
+    filePath: backendRef.modulePath || null,
+    metadata: {
+      specifier: backendRef.specifier,
+    },
+  };
+}

package/node_modules/@elench/next-analysis/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@elench/next-analysis",
+  "version": "0.1.65",
+  "description": "SWC-backed Next.js source analysis primitives for Erench tools",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@next/routing": "^16.2.4",
+    "@swc/core": "^1.15.32"
+  }
+}

package/node_modules/@elench/next-analysis/src/api-routes.mjs

@@ -0,0 +1,81 @@
+import fs from "fs";
+import path from "path";
+import { extractBackendRefs } from "./backend-links.mjs";
+import { routeFromApiFile } from "./routes.mjs";
+import { HTTP_METHODS, isRouteHandlerFile, normalizePath, toApiRequestPath } from "./shared.mjs";
+import { parseModule } from "./swc.mjs";
+
+export function discoverApiRoutes({ rootDir, appRoot }) {
+  const apiRoot = path.join(appRoot, "api");
+  if (!fs.existsSync(apiRoot)) return [];
+  const routeFiles = walkFiles(apiRoot).filter(isRouteHandlerFile);
+  const entries = [];
+
+  for (const absolutePath of routeFiles) {
+    const filePath = normalizePath(path.relative(rootDir, absolutePath));
+    const route = routeFromApiFile(appRoot, absolutePath);
+    const requestPath = toApiRequestPath(route);
+    const content = fs.readFileSync(absolutePath, "utf8");
+    const ast = parseModule(content, filePath);
+    const backendRefs = extractBackendRefs({
+      ast,
+      rootDir,
+      filePath,
+      readSourceFile: (targetPath) => fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : null,
+    });
+    const exportedMethods = extractExportedMethods(ast);
+
+    for (const method of exportedMethods) {
+      entries.push({
+        id: `api:${method}:${requestPath}`,
+        kind: "api_route",
+        route,
+        requestPath,
+        method,
+        filePath,
+        backendRefs,
+      });
+    }
+  }
+
+  return entries.sort((left, right) => {
+    return left.requestPath.localeCompare(right.requestPath) || left.method.localeCompare(right.method);
+  });
+}
+
+function extractExportedMethods(ast) {
+  const methods = [];
+  for (const statement of ast.body || []) {
+    if (statement.type !== "ExportDeclaration") continue;
+    const declaration = statement.declaration;
+    if (declaration?.type === "FunctionDeclaration" && declaration.identifier) {
+      const name = declaration.identifier.value.toUpperCase();
+      if (HTTP_METHODS.includes(name)) methods.push(name);
+    } else if (declaration?.type === "VariableDeclaration") {
+      for (const declarator of declaration.declarations || []) {
+        if (declarator.id?.type !== "Identifier") continue;
+        const name = declarator.id.value.toUpperCase();
+        if (HTTP_METHODS.includes(name)) methods.push(name);
+      }
+    }
+  }
+  return [...new Set(methods)];
+}
+
+function walkFiles(rootDir) {
+  const results = [];
+  const queue = [rootDir];
+  while (queue.length > 0) {
+    const current = queue.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(absolutePath);
+      } else if (entry.isFile()) {
+        results.push(absolutePath);
+      }
+    }
+  }
+  return results.sort((left, right) => left.localeCompare(right));
+}

package/node_modules/@elench/next-analysis/src/api-routes.test.mjs

@@ -0,0 +1,22 @@
+import path from "path";
+import { describe, expect, it } from "vitest";
+import { createNextAnalysisProject } from "./index.mjs";
+
+const fixtureRoot = path.resolve(
+  "/home/georgedlr/workspace/elench/testkit/test/fixtures/integration/next-dynamic-routes-product"
+);
+
+describe("@elench/next-analysis api routes", () => {
+  it("discovers dynamic API routes with normalized request paths", () => {
+    const project = createNextAnalysisProject({ rootDir: fixtureRoot });
+    expect(project.discoverApiRoutes()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          method: "GET",
+          route: "/projects/[projectId]",
+          requestPath: "/api/projects/[projectId]",
+        }),
+      ])
+    );
+  });
+});

package/node_modules/@elench/next-analysis/src/app-root.mjs

@@ -0,0 +1,7 @@
+import path from "path";
+import { directoryExists } from "./shared.mjs";
+
+export function findNextAppRoot(rootDir) {
+  const candidates = [path.join(rootDir, "app"), path.join(rootDir, "src", "app")];
+  return candidates.find((candidate) => directoryExists(candidate)) || null;
+}

package/node_modules/@elench/next-analysis/src/backend-links.mjs

@@ -0,0 +1,31 @@
+import { isBackendSpecifier, modulePathKey, normalizePath } from "./shared.mjs";
+import { collectImports } from "./swc.mjs";
+
+export function extractBackendRefs({ ast, rootDir, filePath, readSourceFile }) {
+  const imports = collectImports(ast, { rootDir, filePath, readSourceFile });
+  const refs = [];
+
+  for (const [localName, imported] of imports.entries()) {
+    if (!isBackendSpecifier(imported.specifier)) continue;
+    refs.push({
+      id: `server_ref:${modulePathKey(imported.resolvedFilePath || filePath)}#${imported.importedName}`,
+      kind: "server_capability",
+      importName: localName,
+      exportName: imported.importedName,
+      modulePath: normalizePath(imported.resolvedFilePath || filePath),
+      specifier: imported.specifier,
+    });
+  }
+
+  return dedupeBackendRefs(refs);
+}
+
+function dedupeBackendRefs(entries) {
+  const seen = new Set();
+  return entries.filter((entry) => {
+    const key = `${entry.modulePath}#${entry.exportName}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/node_modules/@elench/next-analysis/src/index.mjs

@@ -0,0 +1,21 @@
+export { createNextAnalysisProject } from "./project.mjs";
+export { findNextAppRoot } from "./app-root.mjs";
+export { discoverPages } from "./pages.mjs";
+export { discoverApiRoutes } from "./api-routes.mjs";
+export { discoverServerActions } from "./server-actions.mjs";
+export { analyzeRouteTree } from "./route-tree.mjs";
+export {
+  normalizePath,
+  normalizeRoute,
+  normalizeRouteSegments,
+  pageLabelFromRoute,
+  toApiRequestPath,
+  HTTP_METHODS,
+} from "./shared.mjs";
+export {
+  routeFromAppFile,
+  routeFromApiFile,
+  routePatternMatches,
+  requestPathPatternFromLiteral,
+} from "./routes.mjs";
+export { parseModule, extractHttpRequests, extractPlaywrightVisitedRoutes } from "./swc.mjs";

package/node_modules/@elench/next-analysis/src/pages.mjs

@@ -0,0 +1,68 @@
+import fs from "fs";
+import path from "path";
+import { routeFromAppFile } from "./routes.mjs";
+import { compareByRoute, isPageFile, normalizePath, pageLabelFromRoute } from "./shared.mjs";
+
+export function discoverPages({ rootDir, appRoot }) {
+  const pageFiles = walkFiles(appRoot).filter(isPageFile);
+  return pageFiles
+    .map((absolutePath) => {
+      const filePath = normalizePath(path.relative(rootDir, absolutePath));
+      const route = routeFromAppFile(appRoot, absolutePath);
+      const layoutFiles = collectLayoutFiles(rootDir, appRoot, absolutePath);
+      const rootFiles = [...layoutFiles, filePath];
+      return {
+        id: `page:${route}`,
+        kind: "page",
+        route,
+        label: pageLabelFromRoute(route),
+        filePath,
+        layoutFiles,
+        rootFiles,
+      };
+    })
+    .sort(compareByRoute);
+}
+
+function collectLayoutFiles(rootDir, appRoot, pageAbsolutePath) {
+  const rootFiles = [];
+  let currentDir = path.dirname(pageAbsolutePath);
+  const absoluteAppRoot = path.resolve(appRoot);
+
+  while (currentDir.startsWith(absoluteAppRoot)) {
+    const layoutFile = resolveRouteCompanion(currentDir, "layout");
+    if (layoutFile) rootFiles.push(normalizePath(path.relative(rootDir, layoutFile)));
+    if (currentDir === absoluteAppRoot) break;
+    currentDir = path.dirname(currentDir);
+  }
+
+  return [...new Set(rootFiles.reverse())];
+}
+
+function resolveRouteCompanion(directoryPath, baseName) {
+  const candidates = [
+    path.join(directoryPath, `${baseName}.tsx`),
+    path.join(directoryPath, `${baseName}.ts`),
+    path.join(directoryPath, `${baseName}.jsx`),
+    path.join(directoryPath, `${baseName}.js`),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
+}
+
+function walkFiles(rootDir) {
+  const results = [];
+  const queue = [rootDir];
+  while (queue.length > 0) {
+    const current = queue.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(absolutePath);
+      } else if (entry.isFile()) {
+        results.push(absolutePath);
+      }
+    }
+  }
+  return results.sort((left, right) => left.localeCompare(right));
+}