@elench/testkit 0.1.61 → 0.1.62

package/lib/coverage/evidence.mjs

@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { extractHttpSuiteRequests } from "./next-static-analysis.mjs";
+import { extractHttpSuiteRequests, extractPlaywrightVisitedRoutes } from "./next-static-analysis.mjs";
 import {
   apiRouteLookupKey,
   HTTP_METHODS,
@@ -15,14 +15,26 @@ import {
   pathMatchesOwner,
 } from "./routing.mjs";
 
+function readTestFileContent(entry, context) {
+  if (!context?.serviceRoot) return null;
+  const absolutePath = path.join(context.serviceRoot, entry.filePath);
+  if (!fs.existsSync(absolutePath)) return null;
+  return fs.readFileSync(absolutePath, "utf8");
+}
+
 export function inferCoveredNodeIdsForTest(entry, context) {
   const coveredNodeIds = new Set();
-  const selectionType = toSelectionType(entry.type, entry.framework);
+  const content = readTestFileContent(entry, context);
 
+  // Capability: Playwright page routes (content-first, path-fallback)
   if (entry.framework === "playwright") {
-    const route = inferPageRouteFromTestFile(entry.filePath, context.nextAppRoot, context.serviceRoot);
-    if (route && context.pageByRoute.has(route)) {
+    const gotoRoutes = content ? extractPlaywrightVisitedRoutes(content, entry.filePath) : [];
+    const routes = gotoRoutes.length > 0
+      ? gotoRoutes
+      : (() => { const r = inferPageRouteFromTestFile(entry.filePath, context.nextAppRoot, context.serviceRoot); return r ? [r] : []; })();
+    for (const route of routes) {
       const pageEntry = context.pageByRoute.get(route);
+      if (!pageEntry) continue;
       coveredNodeIds.add(pageEntry.node.id);
       for (const target of extractPlaywrightTargets(entry, context)) {
         const surfaceNode = pageEntry.surfacesByTargetValue?.get(target.value);
@@ -31,28 +43,30 @@ export function inferCoveredNodeIdsForTest(entry, context) {
     }
   }
 
-  if (selectionType === "int") {
-    const explicitRequests = extractHttpSuiteRequestsFromTestFile(entry, context);
-    if (explicitRequests.length > 0) {
-      for (const request of explicitRequests) {
-        const routeEntry = context.apiRouteByKey.get(apiRouteLookupKey(request.method, request.path));
+  // Capability: HTTP request extraction (any test type with rawReq/fetch/wrapper calls)
+  if (content) {
+    const requests = extractHttpSuiteRequests(content, entry.filePath);
+    for (const request of requests) {
+      if (!request.path.startsWith("/api/")) continue;
+      const routeEntry = context.apiRouteByKey.get(apiRouteLookupKey(request.method, request.path));
+      if (routeEntry) coveredNodeIds.add(routeEntry.node.id);
+    }
+  }
+
+  // Capability: path-based API route inference (fallback when no content matches)
+  if (coveredNodeIds.size === 0) {
+    const apiRoutes = inferApiRoutesFromTestFile(entry.filePath, context.nextAppRoot, context.serviceRoot);
+    for (const route of apiRoutes) {
+      for (const method of HTTP_METHODS) {
+        const routeEntry = context.apiRouteByKey.get(apiRouteLookupKey(method, toApiRequestPath(route)));
         if (routeEntry) coveredNodeIds.add(routeEntry.node.id);
       }
-    } else {
-      const apiRoutes = inferApiRoutesFromTestFile(entry.filePath, context.nextAppRoot, context.serviceRoot);
-      for (const route of apiRoutes) {
-        for (const method of HTTP_METHODS) {
-          const routeEntry = context.apiRouteByKey.get(apiRouteLookupKey(method, toApiRequestPath(route)));
-          if (routeEntry) coveredNodeIds.add(routeEntry.node.id);
-        }
-      }
     }
   }
 
-  if (selectionType === "dal") {
-    for (const nodeId of inferDataCapabilitiesFromTestFile(entry, context)) {
-      coveredNodeIds.add(nodeId);
-    }
+  // Capability: DAL owner directory matching
+  for (const nodeId of inferDataCapabilitiesFromTestFile(entry, context)) {
+    coveredNodeIds.add(nodeId);
   }
 
   return [...coveredNodeIds].sort();
@@ -118,21 +132,8 @@ export function extractPlaywrightTargetsFromContent(content) {
   return dedupeTargets(targets);
 }
 
-export function extractHttpSuiteRequestsFromTestFile(entry, context) {
-  if (!entry || toSelectionType(entry.type, entry.framework) !== "int" || !context?.serviceRoot) return [];
-  const absolutePath = path.join(context.serviceRoot, entry.filePath);
-  if (!fs.existsSync(absolutePath)) return [];
-  return extractHttpSuiteRequestsFromContent(fs.readFileSync(absolutePath, "utf8"), entry.filePath);
-}
-
-export function extractHttpSuiteRequestsFromContent(content, filePath = "unknown") {
-  return extractHttpSuiteRequests(content, filePath)
-    .filter((request) => request.path.startsWith("/api/"))
-    .sort((left, right) => `${left.method}:${left.path}`.localeCompare(`${right.method}:${right.path}`));
-}
-
 export function inferDataCapabilitiesFromTestFile(entry, context) {
-  if (!entry || toSelectionType(entry.type, entry.framework) !== "dal") return [];
+  if (!entry) return [];
   const ownerDirectory = inferOwnerDirectoryFromTestFile(entry.filePath);
   if (!ownerDirectory) return [];
   return inferDataCapabilitiesFromOwner(ownerDirectory, context.dataCapabilities);

package/lib/coverage/evidence.test.mjs

@@ -1,10 +1,10 @@
 import { describe, expect, it } from "vitest";
 import {
   buildEvidenceDetailsFromTargets,
-  extractHttpSuiteRequestsFromContent,
   extractPlaywrightTargetsFromContent,
   inferDataCapabilitiesFromOwner,
 } from "./evidence.mjs";
+import { extractPlaywrightVisitedRoutes } from "./next-static-analysis.mjs";
 
 describe("coverage evidence helpers", () => {
   it("extracts and dedupes Playwright targets from source content", () => {
@@ -20,21 +20,6 @@ describe("coverage evidence helpers", () => {
     ]);
   });
 
-  it("extracts API requests from integration suite source content", () => {
-    const content = `
-      export default defineHttpSuite(({ rawReq }) => {
-        rawReq("GET", "/api/campaigns");
-        rawReq("POST", "/api/campaigns");
-        rawReq("GET", "/health");
-      });
-    `;
-
-    expect(extractHttpSuiteRequestsFromContent(content, "campaigns.int.testkit.ts")).toEqual([
-      { method: "GET", path: "/api/campaigns", confidence: "high" },
-      { method: "POST", path: "/api/campaigns", confidence: "high" },
-    ]);
-  });
-
   it("builds compact evidence details only when meaningful signals exist", () => {
     expect(
       buildEvidenceDetailsFromTargets({
@@ -62,3 +47,31 @@ describe("coverage evidence helpers", () => {
     ]);
   });
 });
+
+describe("extractPlaywrightVisitedRoutes", () => {
+  it("extracts routes from page.goto() via AST", () => {
+    expect(extractPlaywrightVisitedRoutes(`
+      import { test } from "@playwright/test";
+      test("nav", async ({ page }) => {
+        await page.goto("/dashboard");
+        await page.goto("/settings/profile?tab=general");
+        await page.goto("/dashboard"); // duplicate
+        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"]);
+  });
+
+  it("handles property chain: foo.page.goto()", () => {
+    expect(extractPlaywrightVisitedRoutes(`
+      await this.page.goto("/projects");
+    `, "test.pw.testkit.ts")).toEqual(["/projects"]);
+  });
+
+  it("ignores dynamic goto expressions", () => {
+    expect(extractPlaywrightVisitedRoutes(`
+      await page.goto(\`/projects/\${id}\`);
+      await page.goto(someVar);
+    `, "test.pw.testkit.ts")).toEqual([]);
+  });
+});

package/lib/coverage/graph-builder.mjs

@@ -29,12 +29,26 @@ export function buildCoverageGraph({ productDir, repoDiscovery = {}, services =
     const context = serviceContexts.get(entry.serviceName);
     const testNodeId = createTestFileNode(graph, entry);
     if (!context) {
+      graph.diagnostics.push({
+        level: "warn",
+        code: "no-service-context",
+        filePath: entry.filePath,
+        service: entry.serviceName,
+        message: `No coverage context available for service "${entry.serviceName}".`,
+      });
       evidence.push(createFallbackEvidence(entry, testNodeId));
       continue;
     }
 
     const coveredNodeIds = inferCoveredNodeIdsForTest(entry, context);
     if (coveredNodeIds.length === 0) {
+      graph.diagnostics.push({
+        level: "info",
+        code: "zero-coverage-inferred",
+        filePath: entry.filePath,
+        service: entry.serviceName,
+        message: `No routes, API endpoints, or data capabilities matched for "${entry.filePath}".`,
+      });
       evidence.push(createFallbackEvidence(entry, testNodeId));
       continue;
     }

package/lib/coverage/index.test.mjs

@@ -375,6 +375,174 @@ describe("coverage graph builder", () => {
     expect(context.apiRouteByKey.get("GET:/api/projects/[projectId]").node).toBeTruthy();
   });
 
+  it("resolves root-level PW test via page.goto() content extraction", () => {
+    const productDir = createProduct();
+    writeFile(
+      productDir,
+      "src/app/dashboard/page.tsx",
+      `export default function DashboardPage() { return <button data-testid="dash-header">Dashboard</button>; }`
+    );
+    writeFile(
+      productDir,
+      "__testkit__/dashboard.pw.testkit.ts",
+      `
+        import { test, expect } from "@playwright/test";
+        test("dashboard loads", async ({ page }) => {
+          await page.goto("/dashboard");
+          await expect(page.getByTestId("dash-header")).toBeVisible();
+        });
+      `
+    );
+
+    const graph = buildCoverageGraph({
+      productDir,
+      services: {
+        web: {
+          local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
+        },
+      },
+      discoveryFiles: [
+        {
+          serviceName: "web",
+          type: "e2e",
+          framework: "playwright",
+          suiteName: "dashboard",
+          filePath: "__testkit__/dashboard.pw.testkit.ts",
+        },
+      ],
+    });
+
+    const evidence = graph.evidence.find((e) => e.testFilePath === "__testkit__/dashboard.pw.testkit.ts");
+    expect(evidence.coveredNodeIds).toEqual(
+      expect.arrayContaining([
+        "page_view:web:/dashboard",
+        "ui_surface:web:/dashboard:dash-header",
+      ])
+    );
+  });
+
+  it("resolves root-level e2e test via rawReq content extraction", () => {
+    const productDir = createProduct();
+    writeFile(
+      productDir,
+      "src/app/api/projects/route.ts",
+      `export async function GET() { return Response.json({ ok: true }); }`
+    );
+    writeFile(
+      productDir,
+      "__testkit__/projects.e2e.testkit.ts",
+      `
+        import { defineHttpSuite } from "@elench/testkit";
+        export default defineHttpSuite(({ rawReq }) => {
+          rawReq("GET", "/api/projects");
+        });
+      `
+    );
+
+    const graph = buildCoverageGraph({
+      productDir,
+      services: {
+        web: {
+          local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
+        },
+      },
+      discoveryFiles: [
+        {
+          serviceName: "web",
+          type: "e2e",
+          framework: "k6",
+          suiteName: "projects",
+          filePath: "__testkit__/projects.e2e.testkit.ts",
+        },
+      ],
+    });
+
+    const evidence = graph.evidence.find((e) => e.testFilePath === "__testkit__/projects.e2e.testkit.ts");
+    expect(evidence.coveredNodeIds).toEqual(["api_route:web:GET:/api/projects"]);
+  });
+
+  it("resolves scenario test via rawReq content extraction", () => {
+    const productDir = createProduct();
+    writeFile(
+      productDir,
+      "src/app/api/campaigns/route.ts",
+      `export async function POST() { return Response.json({ ok: true }); }`
+    );
+    writeFile(
+      productDir,
+      "__testkit__/campaign-flow.scenario.testkit.ts",
+      `
+        import { defineHttpSuite } from "@elench/testkit";
+        export default defineHttpSuite(({ rawReq }) => {
+          rawReq("POST", "/api/campaigns");
+        });
+      `
+    );
+
+    const graph = buildCoverageGraph({
+      productDir,
+      services: {
+        web: {
+          local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
+        },
+      },
+      discoveryFiles: [
+        {
+          serviceName: "web",
+          type: "scenario",
+          framework: "k6",
+          suiteName: "campaign-flow",
+          filePath: "__testkit__/campaign-flow.scenario.testkit.ts",
+        },
+      ],
+    });
+
+    const evidence = graph.evidence.find((e) => e.testFilePath === "__testkit__/campaign-flow.scenario.testkit.ts");
+    expect(evidence.coveredNodeIds).toEqual(["api_route:web:POST:/api/campaigns"]);
+  });
+
+  it("emits zero-coverage-inferred diagnostic when no patterns match", () => {
+    const productDir = createProduct();
+    writeFile(productDir, "src/app/page.tsx", `export default function HomePage() { return null; }`);
+    writeFile(
+      productDir,
+      "__testkit__/misc.e2e.testkit.ts",
+      `// no recognizable patterns here\nconsole.log("hello");`
+    );
+
+    const graph = buildCoverageGraph({
+      productDir,
+      services: {
+        web: {
+          local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
+        },
+      },
+      discoveryFiles: [
+        {
+          serviceName: "web",
+          type: "e2e",
+          framework: "k6",
+          suiteName: "misc",
+          filePath: "__testkit__/misc.e2e.testkit.ts",
+        },
+      ],
+    });
+
+    expect(graph.diagnostics).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          level: "info",
+          code: "zero-coverage-inferred",
+          filePath: "__testkit__/misc.e2e.testkit.ts",
+          service: "web",
+        }),
+      ])
+    );
+
+    const evidence = graph.evidence.find((e) => e.testFilePath === "__testkit__/misc.e2e.testkit.ts");
+    expect(evidence.coveredNodeIds).toEqual([expect.stringContaining("test_file:web:")]);
+  });
+
   it("does not exclude app/coverage source routes while still allowing top-level coverage output to be ignored", () => {
     const productDir = createProduct();
     writeFile(productDir, "app/coverage/page.tsx", `export default function CoveragePage() { return null; }`);

package/lib/coverage/next-static-analysis.mjs

@@ -196,6 +196,41 @@ export function extractHttpSuiteRequests(content, filePath = "suite.int.testkit.
   return dedupeRequests(requests);
 }
 
+export function extractPlaywrightVisitedRoutes(content, filePath = "suite.pw.testkit.ts") {
+  const sourceFile = createSourceFile(filePath, content);
+  const routes = [];
+
+  const visit = (node) => {
+    if (ts.isCallExpression(node)) {
+      const route = resolveGotoRoute(node);
+      if (route) routes.push(route);
+    }
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return [...new Set(routes)];
+}
+
+function resolveGotoRoute(callExpression) {
+  const callee = callExpression.expression;
+  if (!ts.isPropertyAccessExpression(callee)) return null;
+  if (callee.name.text !== "goto") return null;
+  const pathArg = callExpression.arguments[0];
+  const literal = extractStringLiteral(pathArg);
+  if (!literal) return null;
+  if (/^https?:\/\//u.test(literal)) {
+    try {
+      const parsed = new URL(literal);
+      if (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1") {
+        return defaultNormalizeRoute(parsed.pathname.split("?")[0]);
+      }
+    } catch { /* ignore malformed */ }
+    return null;
+  }
+  return defaultNormalizeRoute(literal.split("?")[0]);
+}
+
 function walkJsx(sourceFile, visitor) {
   const visit = (node, formContext = null) => {
     let nextFormContext = formContext;

package/lib/coverage/shared.mjs

@@ -16,6 +16,7 @@ export function createEmptyGraph() {
     nodes: [],
     edges: [],
     evidence: [],
+    diagnostics: [],
   };
 }
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.61",
+  "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.61"
+    "@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,
@@ -291,6 +293,7 @@ function buildGraphProjection(context, page, matchedServiceName) {
       .filter(Boolean);
 
     if (supportingTests.length > 0) {
+      const supportKind = inferCoverageSupportKind(supportingTests);
       coverage.push({
         id: surfaceNode.id,
         kind: surfaceNode.kind,
@@ -301,6 +304,10 @@ function buildGraphProjection(context, page, matchedServiceName) {
         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),
       });
     }
 
@@ -329,6 +336,9 @@ function buildGraphProjection(context, page, matchedServiceName) {
       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),
     });
   }
 
@@ -352,6 +362,10 @@ function buildPageLevelProjection({ pageNode, nodeById, relevantEvidence, pageRe
           supportingTests,
           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),
         },
       ]
     : [];
@@ -370,6 +384,9 @@ function buildPageLevelProjection({ pageNode, nodeById, relevantEvidence, pageRe
         targets: collectTargetsForEvidence([entry], pageNode.target),
         failedTests: supporting ? [{ ...supporting, error: failed?.error || supporting.error || null, status: "failed" }] : [],
         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" }] : []),
       };
     });
 
@@ -475,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"}.`;
+}

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

@@ -179,11 +179,18 @@ describe("testkit bridge", () => {
         coverageState: "covered",
         relatedFailureCount: 1,
         relatedCoverageCount: 1,
+        coverageBreakdown: {
+          direct: 0,
+          indirect: 0,
+          mixed: 1,
+        },
       },
       failures: [
         {
           kind: "ui_surface",
           label: "Refresh overlay",
+          importance: "high",
+          reason: "Refresh overlay is implicated by 1 failing test.",
           targets: [{ kind: "testId", value: "coverage-refresh-button", confidence: "high" }],
           failedTests: [
             {
@@ -197,6 +204,8 @@ describe("testkit bridge", () => {
         {
           kind: "ui_surface",
           label: "Refresh overlay",
+          importance: "high",
+          supportKind: "mixed",
           targets: [{ kind: "testId", value: "coverage-refresh-button", confidence: "high" }],
           supportingTests: [
             {

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.61",
+  "version": "0.1.62",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./src/index.mjs",

package/node_modules/@elench/testkit-protocol/src/index.d.ts

@@ -5,6 +5,8 @@ export type BrowserTargetKind = "testId" | "role" | "text" | "css" | "xpath" | "
 export type BrowserConfidence = "low" | "medium" | "high";
 export type BrowserFailureState = "failing" | "healthy" | "unavailable";
 export type BrowserCoverageState = "covered" | "missing" | "unavailable";
+export type BridgeSurfaceImportance = "critical" | "high" | "medium" | "low";
+export type BridgeCoverageSupportKind = "direct" | "indirect" | "mixed";
 
 export type CoverageNodeKind =
   | "page_view"
@@ -86,11 +88,22 @@ export interface CoverageEvidence {
   };
 }
 
+export type CoverageGraphDiagnosticLevel = "info" | "warn";
+
+export interface CoverageGraphDiagnostic {
+  level: CoverageGraphDiagnosticLevel;
+  code: string;
+  filePath: string;
+  service: string;
+  message: string;
+}
+
 export interface CoverageGraph {
   schemaVersion: number;
   nodes: CoverageGraphNode[];
   edges: CoverageGraphEdge[];
   evidence: CoverageEvidence[];
+  diagnostics: CoverageGraphDiagnostic[];
 }
 
 export interface BridgeProductRef {
@@ -149,6 +162,9 @@ export interface FailureOverlayEntry {
   targets: BrowserTarget[];
   failedTests: BridgeSupportingTestRef[];
   viaNodes: BridgeCoverageViaNodeRef[];
+  importance?: BridgeSurfaceImportance;
+  surfaceKind?: string | null;
+  reason?: string | null;
 }
 
 export interface CoverageOverlayEntry {
@@ -161,6 +177,10 @@ export interface CoverageOverlayEntry {
   supportingTests: BridgeSupportingTestRef[];
   viaNodes: BridgeCoverageViaNodeRef[];
   confidence: BrowserConfidence;
+  importance?: BridgeSurfaceImportance;
+  surfaceKind?: string | null;
+  supportKind?: BridgeCoverageSupportKind;
+  reason?: string | null;
 }
 
 export interface PageOverlayResponse {
@@ -177,6 +197,11 @@ export interface PageOverlayResponse {
     coverageState: BrowserCoverageState;
     relatedFailureCount: number;
     relatedCoverageCount: number;
+    coverageBreakdown?: {
+      direct: number;
+      indirect: number;
+      mixed: number;
+    };
   };
   failures: FailureOverlayEntry[];
   coverage: CoverageOverlayEntry[];
@@ -196,6 +221,7 @@ export declare function normalizeBrowserMetadataDocument(value: unknown): Browse
 export declare function normalizeCoverageGraphNode(value: unknown): CoverageGraphNode | null;
 export declare function normalizeCoverageGraphEdge(value: unknown): CoverageGraphEdge | null;
 export declare function normalizeCoverageEvidence(value: unknown): CoverageEvidence | null;
+export declare function normalizeCoverageGraphDiagnostic(value: unknown): CoverageGraphDiagnostic | null;
 export declare function normalizeCoverageGraph(value: unknown): CoverageGraph | null;
 export declare function normalizePageOverlayResponse(value: unknown): PageOverlayResponse | null;
 export declare function isPageOverlayResponse(value: unknown): value is PageOverlayResponse;

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

@@ -158,6 +158,20 @@ export function normalizeCoverageEvidence(value) {
   };
 }
 
+const DIAGNOSTIC_LEVELS = new Set(["info", "warn"]);
+
+export function normalizeCoverageGraphDiagnostic(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const level = normalizeOptionalString(value.level);
+  const code = normalizeOptionalString(value.code);
+  const filePath = normalizeOptionalString(value.filePath);
+  const service = normalizeOptionalString(value.service);
+  const message = normalizeOptionalString(value.message);
+  if (!level || !code || !filePath || !service || !message) return null;
+  if (!DIAGNOSTIC_LEVELS.has(level)) return null;
+  return { level, code, filePath, service, message };
+}
+
 export function normalizeCoverageGraph(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const schemaVersion =
@@ -169,12 +183,16 @@ export function normalizeCoverageGraph(value) {
   const evidence = Array.isArray(value.evidence)
     ? value.evidence.map(normalizeCoverageEvidence).filter(Boolean)
     : [];
+  const diagnostics = Array.isArray(value.diagnostics)
+    ? value.diagnostics.map(normalizeCoverageGraphDiagnostic).filter(Boolean)
+    : [];
   if (nodes.length === 0) return null;
   return {
     schemaVersion,
     nodes,
     edges,
     evidence,
+    diagnostics,
   };
 }
 

package/node_modules/@elench/testkit-protocol/src/index.test.mjs

@@ -6,6 +6,7 @@ import {
   normalizeBrowserTarget,
   normalizeCoverageEvidence,
   normalizeCoverageGraph,
+  normalizeCoverageGraphDiagnostic,
   normalizeCoverageGraphEdge,
   normalizeCoverageGraphNode,
 } from "./index.mjs";
@@ -107,7 +108,79 @@ describe("testkit browser protocol", () => {
     });
   });
 
-  it("normalizes graph payloads", () => {
+  it("normalizes coverage graph diagnostics", () => {
+    expect(
+      normalizeCoverageGraphDiagnostic({
+        level: "warn",
+        code: "no-service-context",
+        filePath: "tests/example.int.testkit.ts",
+        service: "web",
+        message: 'No coverage context available for service "web".',
+      })
+    ).toEqual({
+      level: "warn",
+      code: "no-service-context",
+      filePath: "tests/example.int.testkit.ts",
+      service: "web",
+      message: 'No coverage context available for service "web".',
+    });
+
+    expect(normalizeCoverageGraphDiagnostic({ level: "error", code: "x", filePath: "f", service: "s", message: "m" })).toBeNull();
+    expect(normalizeCoverageGraphDiagnostic({ level: "warn", code: "", filePath: "f", service: "s", message: "m" })).toBeNull();
+    expect(normalizeCoverageGraphDiagnostic(null)).toBeNull();
+  });
+
+  it("normalizes graph payloads with diagnostics", () => {
+    expect(
+      normalizeCoverageGraph({
+        schemaVersion: TESTKIT_COVERAGE_GRAPH_VERSION,
+        nodes: [
+          {
+            id: "page_view:web:/coverage",
+            kind: "page_view",
+            service: "web",
+            label: "Coverage",
+            route: "/coverage",
+          },
+        ],
+        edges: [],
+        evidence: [],
+        diagnostics: [
+          {
+            level: "info",
+            code: "zero-coverage-inferred",
+            filePath: "tests/example.pw.testkit.ts",
+            service: "web",
+            message: "No routes matched.",
+          },
+        ],
+      })
+    ).toEqual({
+      schemaVersion: TESTKIT_COVERAGE_GRAPH_VERSION,
+      nodes: [
+        {
+          id: "page_view:web:/coverage",
+          kind: "page_view",
+          service: "web",
+          label: "Coverage",
+          route: "/coverage",
+        },
+      ],
+      edges: [],
+      evidence: [],
+      diagnostics: [
+        {
+          level: "info",
+          code: "zero-coverage-inferred",
+          filePath: "tests/example.pw.testkit.ts",
+          service: "web",
+          message: "No routes matched.",
+        },
+      ],
+    });
+  });
+
+  it("normalizes graph payloads without diagnostics field", () => {
     expect(
       normalizeCoverageGraph({
         schemaVersion: TESTKIT_COVERAGE_GRAPH_VERSION,
@@ -136,6 +209,7 @@ describe("testkit browser protocol", () => {
       ],
       edges: [],
       evidence: [],
+      diagnostics: [],
     });
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.61",
+  "version": "0.1.62",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "workspaces": [
@@ -59,8 +59,8 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@elench/testkit-bridge": "0.1.61",
-    "@elench/testkit-protocol": "0.1.61",
+    "@elench/testkit-bridge": "0.1.62",
+    "@elench/testkit-protocol": "0.1.62",
     "@babel/code-frame": "^7.29.0",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",