@elench/testkit 0.1.60 → 0.1.62

package/lib/coverage/routing.mjs

@@ -0,0 +1,86 @@
+import path from "path";
+import { normalizePath, normalizeRoute } from "./shared.mjs";
+
+export function inferPageRouteFromTestFile(filePath, nextAppRoot, serviceRoot) {
+  const appRelativeSegments = extractRouteOwnerSegments(filePath, nextAppRoot, serviceRoot);
+  if (!appRelativeSegments) return null;
+  return normalizeRouteSegments(appRelativeSegments);
+}
+
+export function inferApiRoutesFromTestFile(filePath, nextAppRoot, serviceRoot) {
+  const normalized = normalizePath(filePath);
+  const appRootRelative = normalizePath(path.relative(serviceRoot, nextAppRoot));
+  const appPrefix = appRootRelative === "." ? "" : `${appRootRelative}/`;
+  const apiMarker = `${appPrefix}api/`;
+  const markerIndex = normalized.indexOf(apiMarker);
+  if (markerIndex === -1) return [];
+  const rest = normalized.slice(markerIndex + apiMarker.length);
+  const segments = rest.split("/");
+  const testkitIndex = segments.indexOf("__testkit__");
+  if (testkitIndex === -1) return [];
+  return [normalizeRouteSegments(segments.slice(0, testkitIndex))];
+}
+
+export function inferOwnerDirectoryFromTestFile(filePath) {
+  const normalized = normalizePath(filePath);
+  const segments = normalized.split("/");
+  const testkitIndex = segments.indexOf("__testkit__");
+  if (testkitIndex <= 0) return null;
+  return segments.slice(0, testkitIndex).join("/");
+}
+
+export function pathMatchesOwner(candidatePath, ownerDirectory) {
+  const normalizedCandidate = normalizePath(candidatePath);
+  const normalizedOwner = normalizePath(ownerDirectory);
+  return normalizedCandidate === normalizedOwner || normalizedCandidate.startsWith(`${normalizedOwner}/`);
+}
+
+export function extractRouteOwnerSegments(filePath, nextAppRoot, serviceRoot) {
+  const normalized = normalizePath(filePath);
+  const appRootRelative = normalizePath(path.relative(serviceRoot, nextAppRoot));
+  const appPrefix = appRootRelative === "." ? "" : `${appRootRelative}/`;
+  if (!normalized.startsWith(appPrefix)) return null;
+  const rest = normalized.slice(appPrefix.length);
+  const segments = rest.split("/");
+  const testkitIndex = segments.indexOf("__testkit__");
+  if (testkitIndex === -1) return null;
+  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";
+  return type;
+}

package/lib/coverage/routing.test.mjs

@@ -0,0 +1,52 @@
+import path from "path";
+import { describe, expect, it } from "vitest";
+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");
+
+    expect(
+      inferPageRouteFromTestFile("src/app/campaigns/[campaignId]/__testkit__/details.pw.testkit.ts", nextAppRoot, serviceRoot)
+    ).toBe("/campaigns/[campaignId]");
+  });
+
+  it("infers API routes from colocated __testkit__ files", () => {
+    const serviceRoot = "/repo";
+    const nextAppRoot = path.join(serviceRoot, "src", "app");
+
+    expect(
+      inferApiRoutesFromTestFile("src/app/api/campaigns/__testkit__/create.int.testkit.ts", nextAppRoot, serviceRoot)
+    ).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"
+    );
+    expect(pathMatchesOwner("src/backend/data/campaigns/index.ts", "src/backend/data/campaigns")).toBe(true);
+    expect(pathMatchesOwner("src/backend/data/other/index.ts", "src/backend/data/campaigns")).toBe(false);
+  });
+});

package/lib/coverage/shared.mjs

@@ -0,0 +1,198 @@
+import path from "path";
+import { TESTKIT_COVERAGE_GRAPH_VERSION } from "@elench/testkit-protocol";
+
+export const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+export const HTTP_WRAPPER_METHODS = {
+  getJson: "GET",
+  postJson: "POST",
+  putJson: "PUT",
+  patchJson: "PATCH",
+  deleteJson: "DELETE",
+};
+
+export function createEmptyGraph() {
+  return {
+    schemaVersion: TESTKIT_COVERAGE_GRAPH_VERSION,
+    nodes: [],
+    edges: [],
+    evidence: [],
+    diagnostics: [],
+  };
+}
+
+export function appendGraph(graph, fragment) {
+  const nodeIds = new Set(graph.nodes.map((node) => node.id));
+  for (const node of fragment.nodes) {
+    if (nodeIds.has(node.id)) continue;
+    nodeIds.add(node.id);
+    graph.nodes.push(node);
+  }
+  const edgeIds = new Set(graph.edges.map((edge) => edge.id));
+  for (const edge of fragment.edges) {
+    if (edgeIds.has(edge.id)) continue;
+    edgeIds.add(edge.id);
+    graph.edges.push(edge);
+  }
+}
+
+export function createTestFileNode(graph, entry) {
+  const nodeId = `test_file:${entry.serviceName}:${entry.filePath}`;
+  if (!graph.nodes.some((node) => node.id === nodeId)) {
+    graph.nodes.push({
+      id: nodeId,
+      kind: "test_file",
+      service: entry.serviceName,
+      label: path.basename(entry.filePath),
+      filePath: entry.filePath,
+      metadata: {
+        suiteName: entry.suiteName,
+        framework: entry.framework,
+        type: toSelectionType(entry.type, entry.framework),
+      },
+    });
+  }
+  return nodeId;
+}
+
+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, "\\$&");
+}
+
+export function isServerActionFile(content) {
+  const trimmed = content.trimStart();
+  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);
+}
+
+export function dedupeRequests(requests) {
+  const seen = new Set();
+  return requests.filter((entry) => {
+    const key = `${entry.method}:${entry.path}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function dedupeNodes(nodes) {
+  const seen = new Set();
+  return nodes.filter((node) => {
+    if (seen.has(node.id)) return false;
+    seen.add(node.id);
+    return true;
+  });
+}
+
+export function dedupeEdges(edges) {
+  const seen = new Set();
+  return edges.filter((edge) => {
+    if (seen.has(edge.id)) return false;
+    seen.add(edge.id);
+    return true;
+  });
+}
+
+export function dedupeTargets(targets) {
+  const seen = new Set();
+  return targets.filter((target) => {
+    const key = `${target.kind}:${target.value}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+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;
+  });
+}

package/lib/coverage/shared.test.mjs

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import {
+  dedupeTargets,
+  modulePathKey,
+  pageLabelFromRoute,
+  toApiRequestPath,
+  toSelectionType,
+} from "./shared.mjs";
+
+describe("coverage shared helpers", () => {
+  it("builds readable page labels from routes", () => {
+    expect(pageLabelFromRoute("/")).toBe("Home");
+    expect(pageLabelFromRoute("/campaigns/[campaignId]")).toBe("Campaigns CampaignId");
+  });
+
+  it("collapses index modules into stable module path keys", () => {
+    expect(modulePathKey("src/backend/server/campaigns/index.ts")).toBe("src/backend/server/campaigns");
+    expect(modulePathKey("src/backend/server/campaigns.ts")).toBe("src/backend/server/campaigns");
+  });
+
+  it("dedupes overlay targets by kind and value", () => {
+    expect(
+      dedupeTargets([
+        { kind: "testId", value: "save-button", confidence: "high" },
+        { kind: "testId", value: "save-button", confidence: "medium" },
+        { kind: "text", value: "Save", confidence: "medium" },
+      ])
+    ).toEqual([
+      { kind: "testId", value: "save-button", confidence: "high" },
+      { kind: "text", value: "Save", confidence: "medium" },
+    ]);
+  });
+
+  it("normalizes request paths and selection types", () => {
+    expect(toApiRequestPath("/campaigns")).toBe("/api/campaigns");
+    expect(toSelectionType("integration", "http")).toBe("int");
+    expect(toSelectionType("ui", "playwright")).toBe("pw");
+  });
+});

package/node_modules/@elench/testkit-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.60",
+  "version": "0.1.62",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./src/index.mjs",
@@ -11,7 +11,7 @@
     "src/"
   ],
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.60"
+    "@elench/testkit-protocol": "0.1.62"
   },
   "private": false
 }

package/node_modules/@elench/testkit-bridge/src/index.mjs

@@ -143,6 +143,7 @@ export function buildPageOverlayResponse(context, pageUrl) {
   const projection = buildGraphProjection(context, page, match.service?.name || null);
   const relatedCoverageCount = projection.coverage.length;
   const relatedFailureCount = projection.failures.length;
+  const coverageBreakdown = buildCoverageBreakdown(projection.coverage);
 
   return {
     protocolVersion: TESTKIT_BROWSER_PROTOCOL_VERSION,
@@ -162,6 +163,7 @@ export function buildPageOverlayResponse(context, pageUrl) {
       coverageState: relatedCoverageCount > 0 ? "covered" : "missing",
       relatedFailureCount,
       relatedCoverageCount,
+      coverageBreakdown,
     },
     failures: projection.failures,
     coverage: projection.coverage,
@@ -260,15 +262,94 @@ function buildGraphProjection(context, page, matchedServiceName) {
     return { coverage: [], failures: [] };
   }
 
-  const reachableNodeIds = collectReachableNodeIds(pageNode.id, outgoing);
-  const relevantEvidence = evidence.filter((entry) =>
-    intersects(entry.coveredNodeIds || [], reachableNodeIds)
-  );
+  const failedFiles = collectFailedFiles(context.runArtifact);
+  const failureByFile = new Map(failedFiles.map((entry) => [entry.filePath, entry]));
+  const surfaceNodes = (outgoing.get(pageNode.id) || [])
+    .map((nodeId) => nodeById.get(nodeId))
+    .filter((node) => node?.kind === "ui_surface");
+  const pageReachableNodeIds = collectReachableNodeIds(pageNode.id, outgoing);
+
+  if (surfaceNodes.length === 0) {
+    const relevantEvidence = evidence.filter((entry) => intersects(entry.coveredNodeIds || [], pageReachableNodeIds));
+    return buildPageLevelProjection({
+      pageNode,
+      nodeById,
+      relevantEvidence,
+      pageReachableNodeIds,
+      discoveryByFile,
+      failureByFile,
+      runArtifact: context.runArtifact,
+    });
+  }
+
+  const coverage = [];
+  const failures = [];
+
+  for (const surfaceNode of surfaceNodes.sort((left, right) => left.id.localeCompare(right.id))) {
+    const surfaceReachableNodeIds = collectReachableNodeIds(surfaceNode.id, outgoing);
+    const relevantEvidence = evidence.filter((entry) => intersects(entry.coveredNodeIds || [], surfaceReachableNodeIds));
+    const supportingTests = relevantEvidence
+      .map((entry) => buildSupportingTestRef(entry, discoveryByFile, context.runArtifact))
+      .filter(Boolean);
+
+    if (supportingTests.length > 0) {
+      const supportKind = inferCoverageSupportKind(supportingTests);
+      coverage.push({
+        id: surfaceNode.id,
+        kind: surfaceNode.kind,
+        label: surfaceNode.label,
+        service: surfaceNode.service,
+        route: pageNode.route || null,
+        targets: collectTargetsForEvidence(relevantEvidence, surfaceNode.target),
+        supportingTests,
+        viaNodes: collectViaNodes(relevantEvidence, surfaceReachableNodeIds, nodeById, new Set([pageNode.id, surfaceNode.id])),
+        confidence: supportingTests.some((entry) => entry.type === "pw") ? "high" : "medium",
+        importance: inferSurfaceImportance(surfaceNode),
+        surfaceKind: surfaceNode.metadata?.surfaceKind ? String(surfaceNode.metadata.surfaceKind) : null,
+        supportKind,
+        reason: buildCoverageReason(surfaceNode, supportKind, supportingTests, relevantEvidence),
+      });
+    }
+
+    const failedEvidence = relevantEvidence.filter((entry) => failureByFile.has(entry.testFilePath));
+    if (failedEvidence.length === 0) continue;
+
+    const failedTests = failedEvidence
+      .map((entry) => {
+        const supporting = buildSupportingTestRef(entry, discoveryByFile, context.runArtifact);
+        const failed = failureByFile.get(entry.testFilePath);
+        if (!supporting) return null;
+        return {
+          ...supporting,
+          error: failed?.error || supporting.error || null,
+          status: "failed",
+        };
+      })
+      .filter(Boolean);
+
+    failures.push({
+      id: `failure:${surfaceNode.id}`,
+      kind: surfaceNode.kind,
+      label: surfaceNode.label,
+      service: surfaceNode.service,
+      route: pageNode.route || null,
+      targets: collectTargetsForEvidence(failedEvidence, surfaceNode.target),
+      failedTests,
+      viaNodes: collectViaNodes(failedEvidence, surfaceReachableNodeIds, nodeById, new Set([pageNode.id, surfaceNode.id])),
+      importance: inferSurfaceImportance(surfaceNode),
+      surfaceKind: surfaceNode.metadata?.surfaceKind ? String(surfaceNode.metadata.surfaceKind) : null,
+      reason: buildFailureReason(surfaceNode, failedTests),
+    });
+  }
+
+  return { coverage, failures };
+}
+
+function buildPageLevelProjection({ pageNode, nodeById, relevantEvidence, pageReachableNodeIds, discoveryByFile, failureByFile, runArtifact }) {
   const supportingTests = relevantEvidence
-    .map((entry) => buildSupportingTestRef(entry, discoveryByFile, context.runArtifact))
+    .map((entry) => buildSupportingTestRef(entry, discoveryByFile, runArtifact))
     .filter(Boolean);
 
-  const viaNodes = collectViaNodes(relevantEvidence, reachableNodeIds, nodeById, pageNode.id);
   const coverage = supportingTests.length > 0
     ? [
         {
@@ -279,19 +360,21 @@ function buildGraphProjection(context, page, matchedServiceName) {
           route: pageNode.route || null,
           targets: collectTargetsForEvidence(relevantEvidence, pageNode.target),
           supportingTests,
-          viaNodes,
+          viaNodes: collectViaNodes(relevantEvidence, pageReachableNodeIds, nodeById, new Set([pageNode.id])),
           confidence: supportingTests.some((entry) => entry.type === "pw") ? "high" : "medium",
+          importance: inferSurfaceImportance(pageNode),
+          surfaceKind: pageNode.kind,
+          supportKind: inferCoverageSupportKind(supportingTests),
+          reason: buildCoverageReason(pageNode, inferCoverageSupportKind(supportingTests), supportingTests, relevantEvidence),
         },
       ]
     : [];
 
-  const failedFiles = collectFailedFiles(context.runArtifact);
-  const failureByFile = new Map(failedFiles.map((entry) => [entry.filePath, entry]));
   const failures = relevantEvidence
     .filter((entry) => failureByFile.has(entry.testFilePath))
     .map((entry) => {
       const failed = failureByFile.get(entry.testFilePath);
-      const supporting = buildSupportingTestRef(entry, discoveryByFile, context.runArtifact);
+      const supporting = buildSupportingTestRef(entry, discoveryByFile, runArtifact);
       return {
         id: `failure:${entry.testFilePath}`,
         kind: pageNode.kind,
@@ -300,7 +383,10 @@ function buildGraphProjection(context, page, matchedServiceName) {
         route: pageNode.route || null,
         targets: collectTargetsForEvidence([entry], pageNode.target),
         failedTests: supporting ? [{ ...supporting, error: failed?.error || supporting.error || null, status: "failed" }] : [],
-        viaNodes: collectViaNodes([entry], reachableNodeIds, nodeById, pageNode.id),
+        viaNodes: collectViaNodes([entry], pageReachableNodeIds, nodeById, new Set([pageNode.id])),
+        importance: inferSurfaceImportance(pageNode),
+        surfaceKind: pageNode.kind,
+        reason: buildFailureReason(pageNode, supporting ? [{ ...supporting, error: failed?.error || supporting.error || null, status: "failed" }] : []),
       };
     });
 
@@ -331,11 +417,11 @@ function collectReachableNodeIds(startNodeId, outgoing) {
   return visited;
 }
 
-function collectViaNodes(evidenceEntries, reachableNodeIds, nodeById, pageNodeId) {
+function collectViaNodes(evidenceEntries, reachableNodeIds, nodeById, excludedNodeIds = new Set()) {
   const nodes = new Map();
   for (const entry of evidenceEntries) {
     for (const nodeId of entry.coveredNodeIds || []) {
-      if (!reachableNodeIds.has(nodeId) || nodeId === pageNodeId) continue;
+      if (!reachableNodeIds.has(nodeId) || excludedNodeIds.has(nodeId)) continue;
       const node = nodeById.get(nodeId);
       if (!node) continue;
       nodes.set(nodeId, {
@@ -406,3 +492,60 @@ function pathBaseName(filePath) {
   const parts = String(filePath || "").split("/");
   return parts[parts.length - 1] || filePath;
 }
+
+function buildCoverageBreakdown(entries) {
+  const breakdown = { direct: 0, indirect: 0, mixed: 0 };
+  for (const entry of entries || []) {
+    if (entry.supportKind === "direct") breakdown.direct += 1;
+    else if (entry.supportKind === "indirect") breakdown.indirect += 1;
+    else breakdown.mixed += 1;
+  }
+  return breakdown;
+}
+
+function inferCoverageSupportKind(supportingTests) {
+  const hasPw = (supportingTests || []).some((entry) => entry.type === "pw");
+  const hasBackend = (supportingTests || []).some((entry) => entry.type !== "pw");
+  if (hasPw && hasBackend) return "mixed";
+  if (hasPw) return "direct";
+  return "indirect";
+}
+
+function inferSurfaceImportance(node) {
+  const label = String(node?.label || "").toLowerCase();
+  const surfaceKind = String(node?.metadata?.surfaceKind || node?.kind || "").toLowerCase();
+
+  if (/\b(pay|purchase|checkout|publish|send|submit|confirm|delete|remove)\b/u.test(label)) {
+    return "critical";
+  }
+  if (/\b(save|create|update|refresh|retry|login|sign in|continue)\b/u.test(label)) {
+    return "high";
+  }
+  if (surfaceKind === "form" || surfaceKind === "button" || surfaceKind === "input") {
+    return "medium";
+  }
+  return "low";
+}
+
+function buildCoverageReason(node, supportKind, supportingTests, evidenceEntries) {
+  const directCount = supportingTests.filter((entry) => entry.type === "pw").length;
+  const backendCount = supportingTests.filter((entry) => entry.type !== "pw").length;
+  const requestPaths = new Set();
+  for (const entry of evidenceEntries || []) {
+    for (const path of entry?.details?.requestPaths || []) requestPaths.add(path);
+  }
+  const requestSummary = requestPaths.size > 0 ? ` via ${[...requestPaths].join(", ")}` : "";
+  if (supportKind === "mixed") {
+    return `${node.label} is covered directly by ${directCount} UI test${directCount === 1 ? "" : "s"} and indirectly by ${backendCount} backend test${backendCount === 1 ? "" : "s"}${requestSummary}.`;
+  }
+  if (supportKind === "direct") {
+    return `${node.label} is covered directly by ${directCount} UI test${directCount === 1 ? "" : "s"}${requestSummary}.`;
+  }
+  return `${node.label} is covered indirectly by ${backendCount} backend test${backendCount === 1 ? "" : "s"}${requestSummary}.`;
+}
+
+function buildFailureReason(node, failedTests) {
+  const count = (failedTests || []).length;
+  if (count === 0) return `${node.label} has a related failing test.`;
+  return `${node.label} is implicated by ${count} failing test${count === 1 ? "" : "s"}.`;
+}