@elench/testkit 0.1.64 → 0.1.66

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

@@ -0,0 +1,239 @@
+import {
+  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/lib/coverage/routing.mjs

@@ -1,5 +1,6 @@
 import path from "path";
-import { normalizePath, normalizeRoute } from "./shared.mjs";
+import { normalizeRouteSegments, toApiRequestPath } from "@elench/next-analysis";
+import { normalizePath } from "./shared.mjs";
 
 export function inferPageRouteFromTestFile(filePath, nextAppRoot, serviceRoot) {
   const appRelativeSegments = extractRouteOwnerSegments(filePath, nextAppRoot, serviceRoot);
@@ -47,38 +48,10 @@ export function extractRouteOwnerSegments(filePath, nextAppRoot, serviceRoot) {
   return segments.slice(0, testkitIndex);
 }
 
-export function routeFromAppFile(nextAppRoot, filePath) {
-  const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(nextAppRoot, filePath);
-  const relative = normalizePath(path.relative(nextAppRoot, absolutePath));
-  const segments = relative.split("/");
-  segments.pop();
-  return normalizeRouteSegments(segments);
-}
-
-export function routeFromApiFile(nextAppRoot, filePath) {
-  const appRelative = normalizePath(path.relative(nextAppRoot, path.dirname(filePath)));
-  const segments = appRelative.split("/").filter(Boolean);
-  if (segments[0] === "api") segments.shift();
-  return normalizeRouteSegments(segments);
-}
-
-export function normalizeRouteSegments(segments) {
-  const normalizedSegments = segments
-    .filter(Boolean)
-    .filter((segment) => !segment.startsWith("(") || !segment.endsWith(")"))
-    .filter((segment) => !segment.startsWith("@"))
-    .filter((segment) => segment !== "page" && segment !== "route");
-  return normalizeRoute(`/${normalizedSegments.join("/")}`);
-}
-
 export function apiRouteLookupKey(method, route) {
   return `${method}:${route}`;
 }
 
-export function toApiRequestPath(route) {
-  return normalizeRoute(`/api${route === "/" ? "" : route}`);
-}
-
 export function toSelectionType(type, framework) {
   if (framework === "playwright") return "pw";
   if (type === "integration") return "int";

package/lib/coverage/routing.test.mjs

@@ -4,19 +4,10 @@ import {
   inferApiRoutesFromTestFile,
   inferOwnerDirectoryFromTestFile,
   inferPageRouteFromTestFile,
-  normalizeRouteSegments,
   pathMatchesOwner,
-  routeFromApiFile,
-  routeFromAppFile,
 } from "./routing.mjs";
 
 describe("coverage routing helpers", () => {
-  it("normalizes route segments by stripping route groups and slots", () => {
-    expect(normalizeRouteSegments(["(marketing)", "@modal", "campaigns", "[campaignId]", "page"])).toBe(
-      "/campaigns/[campaignId]"
-    );
-  });
-
   it("infers page ownership routes from colocated __testkit__ files", () => {
     const serviceRoot = "/repo";
     const nextAppRoot = path.join(serviceRoot, "src", "app");
@@ -35,13 +26,6 @@ describe("coverage routing helpers", () => {
     ).toEqual(["/campaigns"]);
   });
 
-  it("derives page and API routes from Next app file paths", () => {
-    const nextAppRoot = "/repo/src/app";
-
-    expect(routeFromAppFile(nextAppRoot, "/repo/src/app/settings/page.tsx")).toBe("/settings");
-    expect(routeFromApiFile(nextAppRoot, "/repo/src/app/api/campaigns/route.ts")).toBe("/campaigns");
-  });
-
   it("matches nested ownership directories for DAL evidence", () => {
     expect(inferOwnerDirectoryFromTestFile("src/backend/data/campaigns/__testkit__/save.dal.testkit.ts")).toBe(
       "src/backend/data/campaigns"

package/lib/coverage/shared.mjs

@@ -1,7 +1,28 @@
 import path from "path";
 import { TESTKIT_COVERAGE_GRAPH_VERSION } from "@elench/testkit-protocol";
+import {
+  DYNAMIC_SEGMENT_TOKEN,
+  HTTP_METHODS,
+  isBackendSpecifier,
+  isDataSpecifier,
+  modulePathKey,
+  normalizePath,
+  normalizeRoute,
+  pageLabelFromRoute,
+  toApiRequestPath,
+} from "@elench/next-analysis";
+export {
+  DYNAMIC_SEGMENT_TOKEN,
+  HTTP_METHODS,
+  isBackendSpecifier,
+  isDataSpecifier,
+  modulePathKey,
+  normalizePath,
+  normalizeRoute,
+  pageLabelFromRoute,
+  toApiRequestPath,
+};
 
-export const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 export const HTTP_WRAPPER_METHODS = {
   getJson: "GET",
   postJson: "POST",
@@ -9,7 +30,6 @@ export const HTTP_WRAPPER_METHODS = {
   patchJson: "PATCH",
   deleteJson: "DELETE",
 };
-export const DYNAMIC_SEGMENT_TOKEN = "__TESTKIT_DYNAMIC_SEGMENT__";
 
 export function createEmptyGraph() {
   return {
@@ -59,51 +79,12 @@ export function apiRouteLookupKey(method, route) {
   return `${method}:${route}`;
 }
 
-export function toApiRequestPath(route) {
-  return normalizeRoute(`/api${route === "/" ? "" : route}`);
-}
-
 export function toSelectionType(type, framework) {
   if (framework === "playwright") return "pw";
   if (type === "integration") return "int";
   return type;
 }
 
-export function pageLabelFromRoute(route) {
-  if (route === "/") return "Home";
-  return route
-    .split("/")
-    .filter(Boolean)
-    .map((segment) => {
-      if (segment.startsWith("[") && segment.endsWith("]")) {
-        return segment.slice(1, -1);
-      }
-      return segment;
-    })
-    .map((segment) => segment.replace(/[-_]+/gu, " "))
-    .map((segment) => segment.replace(/^\w/u, (char) => char.toUpperCase()))
-    .join(" ");
-}
-
-export function normalizeRoute(value) {
-  const trimmed = String(value || "/").trim();
-  if (!trimmed || trimmed === "/") return "/";
-  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  return withLeadingSlash.length > 1 ? withLeadingSlash.replace(/\/+$/u, "") : withLeadingSlash;
-}
-
-export function normalizePath(filePath) {
-  return filePath.split(path.sep).join("/");
-}
-
-export function modulePathKey(filePath) {
-  const normalized = normalizePath(filePath);
-  const ext = path.extname(normalized);
-  if (path.basename(normalized, ext) === "index") {
-    return normalizePath(path.dirname(normalized));
-  }
-  return normalized.slice(0, normalized.length - ext.length);
-}
 
 export function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
@@ -114,27 +95,6 @@ export function isServerActionFile(content) {
   return trimmed.startsWith('"use server"') || trimmed.startsWith("'use server'");
 }
 
-export function isBackendSpecifier(specifier) {
-  return (
-    specifier.startsWith("@/backend/server/") ||
-    specifier.includes("/backend/server/") ||
-    specifier.startsWith("./backend/server/") ||
-    specifier.startsWith("../backend/server/")
-  );
-}
-
-export function isDataSpecifier(specifier) {
-  return (
-    specifier.startsWith("@/backend/data/") ||
-    specifier.startsWith("@/backend/dal/") ||
-    specifier.includes("/backend/data/") ||
-    specifier.includes("/backend/dal/") ||
-    specifier.includes("/db/") ||
-    specifier.includes("/repository/") ||
-    specifier.includes("/repositories/")
-  );
-}
-
 export function hasWord(content, word) {
   if (!content || !word) return false;
   return new RegExp(`\\b${escapeRegExp(word)}\\b`, "u").test(content);
@@ -178,26 +138,6 @@ export function dedupeTargets(targets) {
   });
 }
 
-export function dedupeBackendImports(entries) {
-  const seen = new Set();
-  return entries.filter((entry) => {
-    const key = `${entry.importName}:${entry.node.filePath || ""}:${entry.node.label}`;
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-
-export function dedupeDataImports(entries) {
-  const seen = new Set();
-  return entries.filter((entry) => {
-    const key = `${entry.importName}:${entry.node.filePath || ""}:${entry.node.label}`;
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-
 export function findMatchingApiRouteEntry(method, candidatePath, routeEntries = []) {
   const normalizedMethod = String(method || "").trim().toUpperCase();
   const normalizedCandidate = normalizeRequestPathCandidate(candidatePath);

package/lib/database/fingerprint.mjs

@@ -1,7 +1,7 @@
 import crypto from "crypto";
 import fs from "fs";
 import path from "path";
-import { resolveServiceCwd } from "../config/index.mjs";
+import { resolveServiceCwd } from "../config/paths.mjs";
 import { collectTemplateInputs } from "./template-steps.mjs";
 
 const LOCAL_IMAGE = "pgvector/pgvector:pg16";

package/lib/known-failures/github-cache.mjs

@@ -0,0 +1,159 @@
+import fs from "fs";
+import path from "path";
+
+export function loadIssueCache(productDir, cachePath, schemaVersion) {
+  const filePath = path.join(productDir, ...cachePath);
+  if (!fs.existsSync(filePath)) {
+    return {
+      schemaVersion,
+      entries: {},
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (parsed?.schemaVersion !== schemaVersion || typeof parsed.entries !== "object") {
+      return {
+        schemaVersion,
+        entries: {},
+      };
+    }
+    return parsed;
+  } catch {
+    return {
+      schemaVersion,
+      entries: {},
+    };
+  }
+}
+
+export function resolveIssueCache(cache, issueNumbersByRepo, config, now) {
+  const issuesByRepo = new Map();
+  const missingByRepo = new Map();
+  const staleByRepo = new Map();
+  const ttlMs = config.cacheTtlSeconds * 1000;
+
+  for (const [repo, numbers] of issueNumbersByRepo.entries()) {
+    const cachedIssues = new Map();
+    const missing = [];
+    const stale = [];
+
+    for (const number of numbers) {
+      const key = buildIssueCacheKey(repo, number);
+      const cached = cache.entries[key];
+      if (!cached) {
+        missing.push(number);
+        continue;
+      }
+
+      const checkedAt = Date.parse(cached.checkedAt);
+      const normalized = {
+        repo,
+        number,
+        exists: Boolean(cached.exists),
+        title: normalizeOptionalString(cached.title),
+        state: normalizeOptionalString(cached.state),
+        url: normalizeOptionalString(cached.url),
+        checkedAt: cached.checkedAt || null,
+        source: "cache",
+      };
+
+      if (!Number.isFinite(checkedAt) || now - checkedAt > ttlMs) {
+        stale.push(number);
+        cachedIssues.set(number, normalized);
+        continue;
+      }
+
+      cachedIssues.set(number, normalized);
+    }
+
+    issuesByRepo.set(repo, cachedIssues);
+    if (missing.length > 0 || stale.length > 0) {
+      missingByRepo.set(repo, [...new Set([...missing, ...stale])].sort((a, b) => a - b));
+    }
+    if (stale.length > 0) {
+      staleByRepo.set(repo, stale.sort((a, b) => a - b));
+    }
+  }
+
+  return {
+    issuesByRepo,
+    missingByRepo,
+    staleByRepo,
+  };
+}
+
+export function updateIssueCache(cache, issuesByRepo, now, schemaVersion) {
+  cache.schemaVersion = schemaVersion;
+  cache.entries = cache.entries || {};
+  const checkedAt = new Date(now).toISOString();
+
+  for (const [repo, issues] of issuesByRepo.entries()) {
+    for (const [number, issue] of issues.entries()) {
+      issue.checkedAt = checkedAt;
+      cache.entries[buildIssueCacheKey(repo, number)] = {
+        exists: issue.exists,
+        title: issue.title,
+        state: issue.state,
+        url: issue.url,
+        checkedAt,
+      };
+    }
+  }
+}
+
+export function writeIssueCache(productDir, cachePath, cache) {
+  const filePath = path.join(productDir, ...cachePath);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(cache, null, 2)}\n`);
+}
+
+export function applyStaleCacheFallback(issuesByRepo, staleByRepo, findings) {
+  let usedStale = false;
+  for (const [repo, numbers] of staleByRepo.entries()) {
+    const issues = issuesByRepo.get(repo);
+    if (!issues) continue;
+    for (const number of numbers) {
+      if (issues.has(number)) {
+        usedStale = true;
+      }
+    }
+  }
+  if (usedStale) {
+    findings.push({
+      code: "used_stale_cache",
+      severity: "warning",
+      message: "Used stale cached GitHub issue metadata because fresh validation failed",
+    });
+  }
+  return issuesByRepo;
+}
+
+export function mergeIssuesByRepo(left, right) {
+  const merged = new Map();
+  for (const [repo, issues] of left.entries()) {
+    merged.set(repo, new Map(issues.entries()));
+  }
+
+  for (const [repo, issues] of right.entries()) {
+    if (!merged.has(repo)) {
+      merged.set(repo, new Map());
+    }
+    const mergedIssues = merged.get(repo);
+    for (const [number, issue] of issues.entries()) {
+      mergedIssues.set(number, issue);
+    }
+  }
+
+  return merged;
+}
+
+function buildIssueCacheKey(repo, number) {
+  return `${repo}#${number}`;
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}