@elench/testkit 0.1.58 → 0.1.59

package/lib/config/discovery.mjs

@@ -1,5 +1,12 @@
 import fs from "fs";
 import path from "path";
+import {
+  DEFAULT_DISCOVERY_EXCLUDES,
+  normalizeDiscoveryConfig,
+  normalizeDiscoveryPath,
+  resolveDiscoveryRoots,
+  shouldExcludeDiscoveryPath,
+} from "../discovery/path-policy.mjs";
 
 const TESTKIT_DIRNAME = "__testkit__";
 const DISCOVERY_RULES = [
@@ -11,27 +18,10 @@ const DISCOVERY_RULES = [
   { suffix: ".pw.testkit.ts", type: "e2e", framework: "playwright" },
 ];
 
-const IGNORED_DIRS = new Set([
-  ".cache",
-  ".git",
-  ".hg",
-  ".next",
-  ".nuxt",
-  ".playwright-browsers",
-  ".svn",
-  ".testkit",
-  ".turbo",
-  "build",
-  "coverage",
-  "dist",
-  "node_modules",
-  "playwright-report",
-  "test-results",
-]);
-
 export function discoverProject(productDir, explicitServices = {}, options = {}) {
   const strict = options.strict !== false;
-  const { suiteFiles, legacyFiles } = discoverFiles(productDir);
+  const repoDiscovery = normalizeDiscoveryConfig(options.discovery, { allowRoots: true });
+  const { suiteFiles, legacyFiles } = discoverFiles(productDir, repoDiscovery);
   const groupedByService = {};
   const services = {};
   const diagnostics = buildLegacyFileDiagnostics(legacyFiles);
@@ -41,7 +31,8 @@ export function discoverProject(productDir, explicitServices = {}, options = {})
     const rule = inferRule(filePath);
     if (!rule) continue;
 
-    const owners = inferOwners(filePath, explicitServices);
+    const owners = inferOwners(filePath, explicitServices, repoDiscovery);
+    if (owners === null) continue;
     if (owners.length === 0) {
       diagnostics.push({
         code: "unowned_test",
@@ -185,10 +176,16 @@ export function buildDiscoveryErrorFromDiagnostics(diagnostics = []) {
   return new Error(lines.join("\n"));
 }
 
-function discoverFiles(productDir) {
+function discoverFiles(productDir, repoDiscovery = {}) {
   const suiteFiles = [];
   const legacyFiles = [];
-  const queue = [productDir];
+  const exclude = [
+    ...new Set([
+      ...DEFAULT_DISCOVERY_EXCLUDES,
+      ...((repoDiscovery.exclude || []).map(normalizePath)),
+    ]),
+  ];
+  const queue = resolveDiscoveryRoots(productDir, repoDiscovery.roots, ".");
 
   while (queue.length > 0) {
     const current = queue.pop();
@@ -198,7 +195,8 @@ function discoverFiles(productDir) {
       if (entry.isSymbolicLink()) continue;
 
       if (entry.isDirectory()) {
-        if (IGNORED_DIRS.has(entry.name)) continue;
+        const relativeDirPath = normalizeDiscoveryPath(path.relative(productDir, absolutePath));
+        if (shouldExcludeDiscoveryPath(relativeDirPath, exclude)) continue;
         queue.push(absolutePath);
         continue;
       }
@@ -221,9 +219,9 @@ function discoverFiles(productDir) {
   };
 }
 
-function inferOwners(filePath, explicitServices) {
+function inferOwners(filePath, explicitServices, repoDiscovery = {}) {
   const serviceRules = Object.entries(explicitServices).flatMap(([name, config]) =>
-    buildServiceRules(name, config)
+    buildServiceRules(name, config, repoDiscovery)
   );
   if (serviceRules.length === 0) {
     return [
@@ -235,8 +233,14 @@ function inferOwners(filePath, explicitServices) {
     ];
   }
 
-  const owningRules = serviceRules.filter((rule) => ownsFile(rule, filePath));
+  const relevantRules = serviceRules.filter(
+    (rule) => rule.depth === 0 || (rule.matchPrefix && hasPrefix(filePath, rule.matchPrefix))
+  );
+  const owningRules = relevantRules.filter((rule) => ownsFile(rule, filePath));
   if (owningRules.length === 0) {
+    if (relevantRules.length > 0 && relevantRules.every((rule) => isExcludedForServiceRule(rule, filePath))) {
+      return null;
+    }
     return [];
   }
 
@@ -291,37 +295,62 @@ function disambiguateSuiteNames(suites) {
   return resolved;
 }
 
-function buildServiceRules(serviceName, serviceConfig) {
+function buildServiceRules(serviceName, serviceConfig, repoDiscovery = {}) {
   const cwd = normalizePath(serviceConfig?.local?.cwd || ".");
-  const discoveryRoots = Array.isArray(serviceConfig?.discovery?.roots)
-    ? serviceConfig.discovery.roots
-    : [cwd];
+  const serviceDiscovery = normalizeDiscoveryConfig(serviceConfig?.discovery, { allowRoots: true });
+  const discoveryRoots =
+    Array.isArray(serviceDiscovery.roots) && serviceDiscovery.roots.length > 0 ? serviceDiscovery.roots : ["."];
+  const serviceRootRelativeExcludes = (serviceDiscovery.exclude || []).map((entry) =>
+    cwd === "." ? normalizePath(entry) : normalizePath(path.posix.join(cwd, entry))
+  );
+  const exclude = [
+    ...new Set([
+      ...DEFAULT_DISCOVERY_EXCLUDES,
+      ...((repoDiscovery.exclude || []).map(normalizePath)),
+      ...serviceRootRelativeExcludes,
+    ]),
+  ];
 
   return discoveryRoots.map((root) => {
     const normalizedRoot = normalizePath(root || ".");
+    const matchPrefix =
+      cwd === "."
+        ? normalizedRoot
+        : normalizedRoot === "."
+          ? cwd
+          : normalizePath(path.posix.join(cwd, normalizedRoot));
     return {
       name: serviceName,
       source: "cwd",
       cwdPrefix: cwd === "." ? null : cwd,
-      matchPrefix: normalizedRoot === "." ? null : normalizedRoot,
-      depth: normalizedRoot === "." ? 0 : normalizedRoot.split("/").filter(Boolean).length,
+      matchPrefix: matchPrefix === "." ? null : matchPrefix,
+      depth: matchPrefix === "." ? 0 : matchPrefix.split("/").filter(Boolean).length,
+      exclude,
     };
   });
 }
 
 function ownsFile(serviceRule, filePath) {
+  if (isExcludedForServiceRule(serviceRule, filePath)) return false;
   if (serviceRule.depth === 0) return true;
   if (serviceRule.matchPrefix && hasPrefix(filePath, serviceRule.matchPrefix)) return true;
   return false;
 }
 
 function relativeToServiceRoot(serviceRule, filePath) {
+  if (serviceRule.matchPrefix && hasPrefix(filePath, serviceRule.matchPrefix)) {
+    return path.posix.relative(serviceRule.matchPrefix, filePath);
+  }
   if (serviceRule.cwdPrefix && hasPrefix(filePath, serviceRule.cwdPrefix)) {
     return path.posix.relative(serviceRule.cwdPrefix, filePath);
   }
   return filePath;
 }
 
+function isExcludedForServiceRule(serviceRule, filePath) {
+  return shouldExcludeDiscoveryPath(normalizePath(filePath), serviceRule.exclude || []);
+}
+
 function deriveSuiteRef(relativePath, suffix) {
   const parts = relativePath.split("/").filter(Boolean);
   const testkitIndex = parts.indexOf(TESTKIT_DIRNAME);

package/lib/config/discovery.test.mjs

@@ -205,6 +205,68 @@ describe("filesystem-discovery", () => {
     ]);
   });
 
+  it("does not treat nested coverage source directories as generated output", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-discovery-"));
+    cleanups.push(() => fs.rmSync(productDir, { recursive: true, force: true }));
+
+    writeFile(productDir, "app/coverage/__testkit__/coverage-map.pw.testkit.ts");
+
+    const project = discoverProject(productDir, {
+      web: {
+        local: {
+          cwd: ".",
+        },
+        discovery: {
+          roots: ["app"],
+        },
+      },
+    });
+
+    expect(project.files).toEqual([
+      {
+        serviceName: "web",
+        type: "e2e",
+        framework: "playwright",
+        suiteName: "coverage",
+        suitePath: ["coverage"],
+        filePath: "app/coverage/__testkit__/coverage-map.pw.testkit.ts",
+      },
+    ]);
+  });
+
+  it("supports repo-level and service-level discovery excludes", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-discovery-"));
+    cleanups.push(() => fs.rmSync(productDir, { recursive: true, force: true }));
+
+    writeFile(productDir, "coverage/__testkit__/noise/noise.pw.testkit.ts");
+    writeFile(productDir, "app/generated/__testkit__/noise/noise.pw.testkit.ts");
+    writeFile(productDir, "app/coverage/__testkit__/coverage-map.pw.testkit.ts");
+
+    const project = discoverProject(
+      productDir,
+      {
+        web: {
+          local: {
+            cwd: ".",
+          },
+          discovery: {
+            roots: ["app"],
+            exclude: ["app/generated"],
+          },
+        },
+      },
+      {
+        discovery: {
+          exclude: ["coverage"],
+        },
+      }
+    );
+
+    expect(project.files.map((entry) => entry.filePath)).toEqual([
+      "app/coverage/__testkit__/coverage-map.pw.testkit.ts",
+    ]);
+  });
+
 });
 
 function writeFile(productDir, relativePath, content = "export {};\n") {

package/lib/config/index.mjs

@@ -20,6 +20,10 @@ import {
   normalizeRuntimeToolchain,
   normalizeToolchainRegistry,
 } from "../toolchains/index.mjs";
+import {
+  mergeDiscoveryConfigs,
+  normalizeDiscoveryConfig,
+} from "../discovery/path-policy.mjs";
 
 const TESTKIT_K6_BIN = "TESTKIT_K6_BIN";
 const DEFAULT_LOCAL_IMAGE = "pgvector/pgvector:pg16";
@@ -38,8 +42,12 @@ export async function loadConfigContext(opts = {}) {
   const execution = normalizeRepoExecution(setup.execution);
   const reporting = normalizeReportingConfig(setup.reporting);
   const toolchains = normalizeToolchainRegistry(setup.toolchains);
+  const discoveryConfig = normalizeRepoDiscoveryConfig(setup.discovery);
   const explicitServices = setup.services || {};
-  const discovery = discoverProject(productDir, explicitServices, opts.discoveryOptions || {});
+  const discovery = discoverProject(productDir, explicitServices, {
+    ...(opts.discoveryOptions || {}),
+    discovery: discoveryConfig,
+  });
   const serviceNames = new Set([
     ...Object.keys(explicitServices),
     ...Object.keys(discovery.suitesByService),
@@ -54,6 +62,7 @@ export async function loadConfigContext(opts = {}) {
         setup,
         setupFile,
         execution,
+        discovery: discoveryConfig,
         reporting,
         toolchains,
         explicitService: explicitServices[name] || {},
@@ -69,6 +78,7 @@ export async function loadConfigContext(opts = {}) {
     setup,
     setupFile,
     execution,
+    discovery: discoveryConfig,
     reporting,
     toolchains,
     explicitServices,
@@ -132,6 +142,7 @@ function normalizeServiceConfig({
   setup,
   setupFile,
   execution,
+  discovery,
   reporting,
   toolchains,
   explicitService,
@@ -145,6 +156,10 @@ function normalizeServiceConfig({
     ...(explicitService.env || {}),
   };
   const browser = normalizeBrowserServiceConfig(explicitService.browser, name);
+  const normalizedDiscovery = mergeDiscoveryConfigs(
+    discovery,
+    normalizeServiceDiscoveryConfig(explicitService.discovery, name)
+  );
   if (explicitService.migrate || explicitService.seed) {
     throw new Error(
       `Service "${name}" uses removed migrate/seed hooks. Move template lifecycle to database.template.{migrate,seed,verify}.`
@@ -184,6 +199,7 @@ function normalizeServiceConfig({
       execution,
       reporting,
       dependsOn: explicitService.dependsOn || [],
+      discovery: normalizedDiscovery,
       database,
       databaseFrom: explicitService.databaseFrom,
       envFiles,
@@ -197,6 +213,18 @@ function normalizeServiceConfig({
   };
 }
 
+function normalizeRepoDiscoveryConfig(value) {
+  return normalizeDiscoveryConfig(value, { allowRoots: true });
+}
+
+function normalizeServiceDiscoveryConfig(value, serviceName) {
+  try {
+    return normalizeDiscoveryConfig(value, { allowRoots: true });
+  } catch (error) {
+    throw new Error(`Service "${serviceName}" has invalid discovery config: ${error.message}`);
+  }
+}
+
 function normalizeReportingConfig(value) {
   if (!value) return null;
 

package/lib/coverage/index.mjs

@@ -1,24 +1,12 @@
 import fs from "fs";
 import path from "path";
 import { TESTKIT_COVERAGE_GRAPH_VERSION } from "@elench/testkit-protocol";
-
-const IGNORED_DIRS = new Set([
-  ".cache",
-  ".git",
-  ".hg",
-  ".next",
-  ".nuxt",
-  ".playwright-browsers",
-  ".svn",
-  ".testkit",
-  ".turbo",
-  "build",
-  "coverage",
-  "dist",
-  "node_modules",
-  "playwright-report",
-  "test-results",
-]);
+import {
+  DEFAULT_DISCOVERY_EXCLUDES,
+  normalizeDiscoveryConfig,
+  normalizeDiscoveryPath,
+  shouldExcludeDiscoveryPath,
+} from "../discovery/path-policy.mjs";
 
 const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 const HTTP_WRAPPER_METHODS = {
@@ -29,12 +17,13 @@ const HTTP_WRAPPER_METHODS = {
   deleteJson: "DELETE",
 };
 
-export function buildCoverageGraph({ productDir, services = {}, discoveryFiles = [] }) {
+export function buildCoverageGraph({ productDir, repoDiscovery = {}, services = {}, discoveryFiles = [] }) {
   const graph = createEmptyGraph();
   const serviceContexts = new Map();
+  const normalizedRepoDiscovery = normalizeDiscoveryConfig(repoDiscovery, { allowRoots: true });
 
   for (const [serviceName, config] of Object.entries(services)) {
-    const context = buildServiceCoverageContext(productDir, serviceName, config);
+    const context = buildServiceCoverageContext(productDir, serviceName, config, normalizedRepoDiscovery);
     if (!context) continue;
     serviceContexts.set(serviceName, context);
     appendGraph(graph, context.graph);
@@ -105,15 +94,23 @@ export function buildCoverageGraph({ productDir, services = {}, discoveryFiles =
   return graph;
 }
 
-export function buildServiceCoverageContext(productDir, serviceName, config) {
+export function buildServiceCoverageContext(productDir, serviceName, config, repoDiscovery = {}) {
   const serviceRoot = resolveServiceRoot(productDir, config);
   const nextAppRoot = findNextAppRoot(serviceRoot);
   if (!nextAppRoot) return null;
+  const serviceDiscovery = normalizeDiscoveryConfig(config?.discovery, { allowRoots: true });
+  const exclude = [
+    ...new Set([
+      ...DEFAULT_DISCOVERY_EXCLUDES,
+      ...((repoDiscovery.exclude || []).map(normalizePath)),
+      ...((serviceDiscovery.exclude || []).map(normalizePath)),
+    ]),
+  ];
 
   const graph = createEmptyGraph();
-  const pages = discoverPageViews(serviceName, serviceRoot, nextAppRoot);
-  const apiRoutes = discoverApiRoutes(serviceName, serviceRoot, nextAppRoot);
-  const serverActions = discoverServerActions(serviceName, serviceRoot);
+  const pages = discoverPageViews(serviceName, serviceRoot, nextAppRoot, exclude);
+  const apiRoutes = discoverApiRoutes(serviceName, serviceRoot, nextAppRoot, exclude);
+  const serverActions = discoverServerActions(serviceName, serviceRoot, exclude);
 
   for (const node of [...pages.nodes, ...apiRoutes.nodes, ...serverActions.nodes]) {
     graph.nodes.push(node);
@@ -261,8 +258,10 @@ function buildEvidenceDetails(coveredNodeIds, graph) {
   return Object.keys(details).length > 0 ? details : undefined;
 }
 
-function discoverPageViews(serviceName, serviceRoot, nextAppRoot) {
-  const pageFiles = walkFiles(nextAppRoot).filter((filePath) => filePath.endsWith("/page.tsx") || filePath.endsWith("/page.ts"));
+function discoverPageViews(serviceName, serviceRoot, nextAppRoot, exclude = []) {
+  const pageFiles = walkFiles(nextAppRoot, { baseDir: serviceRoot, exclude }).filter(
+    (filePath) => filePath.endsWith("/page.tsx") || filePath.endsWith("/page.ts")
+  );
   const nodes = [];
   const edges = [];
   const pageEntries = [];
@@ -300,8 +299,8 @@ function discoverPageViews(serviceName, serviceRoot, nextAppRoot) {
   return { nodes, edges, pageEntries };
 }
 
-function discoverApiRoutes(serviceName, serviceRoot, nextAppRoot) {
-  const routeFiles = walkFiles(path.join(nextAppRoot, "api")).filter(
+function discoverApiRoutes(serviceName, serviceRoot, nextAppRoot, exclude = []) {
+  const routeFiles = walkFiles(path.join(nextAppRoot, "api"), { baseDir: serviceRoot, exclude }).filter(
     (filePath) => filePath.endsWith("/route.ts") || filePath.endsWith("/route.tsx") || filePath.endsWith("/route.js")
   );
   const nodes = [];
@@ -348,7 +347,7 @@ function discoverApiRoutes(serviceName, serviceRoot, nextAppRoot) {
   return { nodes: dedupeNodes(nodes), edges, routeEntries };
 }
 
-function discoverServerActions(serviceName, serviceRoot) {
+function discoverServerActions(serviceName, serviceRoot, exclude = []) {
   const appRoots = [path.join(serviceRoot, "app"), path.join(serviceRoot, "src", "app")].filter((candidate) =>
     fs.existsSync(candidate)
   );
@@ -357,7 +356,7 @@ function discoverServerActions(serviceName, serviceRoot) {
   const actionEntries = [];
 
   for (const appRoot of appRoots) {
-    for (const absolutePath of walkFiles(appRoot)) {
+    for (const absolutePath of walkFiles(appRoot, { baseDir: serviceRoot, exclude })) {
       if (!absolutePath.endsWith(".ts") && !absolutePath.endsWith(".tsx")) continue;
       const content = fs.readFileSync(absolutePath, "utf8");
       if (!isServerActionFile(content)) continue;
@@ -630,8 +629,10 @@ function resolveServiceRoot(productDir, config) {
   return path.resolve(productDir, cwd);
 }
 
-function walkFiles(rootDir) {
+function walkFiles(rootDir, options = {}) {
   if (!fs.existsSync(rootDir)) return [];
+  const baseDir = options.baseDir || rootDir;
+  const exclude = options.exclude || [];
   const results = [];
   const queue = [rootDir];
   while (queue.length > 0) {
@@ -640,7 +641,8 @@ function walkFiles(rootDir) {
       if (entry.isSymbolicLink()) continue;
       const absolutePath = path.join(current, entry.name);
       if (entry.isDirectory()) {
-        if (IGNORED_DIRS.has(entry.name)) continue;
+        const relativeDirPath = normalizeDiscoveryPath(path.relative(baseDir, absolutePath));
+        if (shouldExcludeDiscoveryPath(relativeDirPath, exclude)) continue;
         queue.push(absolutePath);
         continue;
       }

package/lib/coverage/index.test.mjs

@@ -205,6 +205,27 @@ describe("coverage graph builder", () => {
     expect(context.pageByRoute.get("/projects/[projectId]").node).toBeTruthy();
     expect(context.apiRouteByKey.get("GET:/api/projects/[projectId]").node).toBeTruthy();
   });
+
+  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; }`);
+    writeFile(productDir, "coverage/page.tsx", `export default function OutputPage() { return null; }`);
+
+    const context = buildServiceCoverageContext(
+      productDir,
+      "web",
+      {
+        local: { cwd: ".", start: "node server.js", baseUrl: "http://127.0.0.1:3000", readyUrl: "http://127.0.0.1:3000" },
+        discovery: { roots: ["app"] },
+      },
+      { exclude: ["coverage"] }
+    );
+
+    expect(context.pageByRoute.get("/coverage").node).toMatchObject({
+      filePath: "app/coverage/page.tsx",
+    });
+    expect(context.graph.nodes.some((node) => node.filePath === "coverage/page.tsx")).toBe(false);
+  });
 });
 
 function createProduct() {

package/lib/discovery/index.mjs

@@ -52,6 +52,7 @@ export async function discoverTests(options = {}) {
 
   const rawDiscovery = discoverProject(productDir, setupContext.setup.services || {}, {
     strict: filters.diagnosticsMode === "error",
+    discovery: setupContext.setup.discovery || {},
   });
   baseResult.diagnostics.push(...rawDiscovery.diagnostics);
   validateRequestedService(filters.serviceFilter, setupContext.setup.services || {}, rawDiscovery);
@@ -90,6 +91,7 @@ export async function discoverTests(options = {}) {
       files: resolved.files,
       coverageGraph: buildCoverageGraph({
         productDir,
+        repoDiscovery: setupContext.setup.discovery || {},
         services: setupContext.setup.services || {},
         discoveryFiles: rawDiscovery.files || [],
       }),
@@ -111,6 +113,7 @@ export async function discoverTests(options = {}) {
     files: rawOnly.files,
     coverageGraph: buildCoverageGraph({
       productDir,
+      repoDiscovery: setupContext.setup.discovery || {},
       services: setupContext.setup.services || {},
       discoveryFiles: rawDiscovery.files || [],
     }),

package/lib/discovery/path-policy.mjs

@@ -0,0 +1,106 @@
+import fs from "fs";
+import path from "path";
+
+export const DEFAULT_DISCOVERY_EXCLUDES = Object.freeze([
+  ".cache",
+  ".git",
+  ".hg",
+  ".next",
+  ".nuxt",
+  ".playwright-browsers",
+  ".svn",
+  ".testkit",
+  ".turbo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "playwright-report",
+  "test-results",
+]);
+
+export function normalizeDiscoveryConfig(value, { allowRoots = true } = {}) {
+  if (value == null) return {};
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("testkit discovery config must be an object");
+  }
+
+  const normalized = {};
+  if (allowRoots && Object.prototype.hasOwnProperty.call(value, "roots")) {
+    normalized.roots = normalizeDiscoveryPathList(value.roots, "testkit discovery roots");
+  }
+  if (Object.prototype.hasOwnProperty.call(value, "exclude")) {
+    normalized.exclude = normalizeDiscoveryPathList(value.exclude, "testkit discovery exclude");
+  }
+  return normalized;
+}
+
+export function mergeDiscoveryConfigs(...configs) {
+  const merged = {};
+  for (const config of configs.filter(Boolean)) {
+    if (Array.isArray(config.roots)) {
+      merged.roots = [...config.roots];
+    }
+    if (Array.isArray(config.exclude) && config.exclude.length > 0) {
+      merged.exclude = [...new Set([...(merged.exclude || []), ...config.exclude])];
+    }
+  }
+  return merged;
+}
+
+export function resolveDiscoveryRoots(baseDir, roots, defaultRoot = ".") {
+  const normalizedRoots = Array.isArray(roots) && roots.length > 0 ? roots : [defaultRoot];
+  const seen = new Set();
+  const resolved = [];
+
+  for (const root of normalizedRoots) {
+    const normalizedRoot = normalizeDiscoveryPath(root);
+    if (!normalizedRoot) continue;
+    const absolutePath = path.resolve(baseDir, normalizedRoot === "." ? "." : normalizedRoot);
+    if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isDirectory()) continue;
+    if (seen.has(absolutePath)) continue;
+    seen.add(absolutePath);
+    resolved.push(absolutePath);
+  }
+
+  return resolved.sort((left, right) => left.localeCompare(right));
+}
+
+export function shouldExcludeDiscoveryPath(relativePath, exclude = []) {
+  const normalizedPath = normalizeDiscoveryPath(relativePath);
+  if (!normalizedPath || normalizedPath === ".") return false;
+  return exclude.some((pattern) => matchesDiscoveryPathPattern(normalizedPath, pattern));
+}
+
+export function normalizeDiscoveryPath(value) {
+  const normalized = String(value || "")
+    .trim()
+    .split(path.sep)
+    .join("/")
+    .replace(/^\.\/+/u, "")
+    .replace(/\/+/gu, "/")
+    .replace(/\/+$/u, "");
+  return normalized || ".";
+}
+
+function normalizeDiscoveryPathList(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array of relative paths`);
+  }
+  const normalized = value
+    .map((entry) => {
+      if (typeof entry !== "string" || entry.trim().length === 0) {
+        throw new Error(`${label} entries must be non-empty strings`);
+      }
+      if (path.isAbsolute(entry)) {
+        throw new Error(`${label} entries must be relative paths`);
+      }
+      return normalizeDiscoveryPath(entry);
+    })
+    .filter(Boolean);
+  return [...new Set(normalized)];
+}
+
+function matchesDiscoveryPathPattern(relativePath, pattern) {
+  return relativePath === pattern || relativePath.startsWith(`${pattern}/`);
+}

package/lib/discovery/path-policy.test.mjs

@@ -0,0 +1,65 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  mergeDiscoveryConfigs,
+  normalizeDiscoveryConfig,
+  resolveDiscoveryRoots,
+  shouldExcludeDiscoveryPath,
+} from "./path-policy.mjs";
+
+const cleanups = [];
+
+afterEach(() => {
+  while (cleanups.length > 0) {
+    cleanups.pop()();
+  }
+});
+
+describe("discovery path policy", () => {
+  it("normalizes roots and excludes as relative paths", () => {
+    expect(
+      normalizeDiscoveryConfig({
+        roots: ["./app/", "src/app"],
+        exclude: ["./coverage/", "dist"],
+      })
+    ).toEqual({
+      roots: ["app", "src/app"],
+      exclude: ["coverage", "dist"],
+    });
+  });
+
+  it("merges excludes without losing later roots", () => {
+    expect(
+      mergeDiscoveryConfigs(
+        { roots: ["src"], exclude: ["coverage"] },
+        { exclude: ["dist"] },
+        { roots: ["app"], exclude: ["test-results"] }
+      )
+    ).toEqual({
+      roots: ["app"],
+      exclude: ["coverage", "dist", "test-results"],
+    });
+  });
+
+  it("treats exclude paths as path prefixes rather than bare directory names", () => {
+    expect(shouldExcludeDiscoveryPath("coverage", ["coverage"])).toBe(true);
+    expect(shouldExcludeDiscoveryPath("coverage/report/index.html", ["coverage"])).toBe(true);
+    expect(shouldExcludeDiscoveryPath("app/coverage", ["coverage"])).toBe(false);
+    expect(shouldExcludeDiscoveryPath("src/app/coverage", ["coverage"])).toBe(false);
+  });
+
+  it("resolves only existing discovery roots", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-discovery-roots-"));
+    cleanups.push(() => fs.rmSync(productDir, { recursive: true, force: true }));
+    fs.mkdirSync(path.join(productDir, "app"), { recursive: true });
+    fs.mkdirSync(path.join(productDir, "src", "app"), { recursive: true });
+
+    const roots = resolveDiscoveryRoots(productDir, ["app", "missing", "src/app"]);
+    expect(roots).toEqual([
+      path.join(productDir, "app"),
+      path.join(productDir, "src", "app"),
+    ]);
+  });
+});

package/lib/setup/index.d.ts

@@ -116,13 +116,16 @@ export interface KnownFailureIssueValidationConfig {
   cacheTtlSeconds?: number;
 }
 
+export interface DiscoveryConfig {
+  roots?: string[];
+  exclude?: string[];
+}
+
 export interface ServiceConfig {
   database?: LocalDatabaseConfig;
   databaseFrom?: string;
   dependsOn?: string[];
-  discovery?: {
-    roots?: string[];
-  };
+  discovery?: DiscoveryConfig;
   env?: Record<string, string>;
   envFile?: string;
   envFiles?: string[];
@@ -142,6 +145,7 @@ export interface ServiceConfig {
 }
 
 export interface TestkitSetup {
+  discovery?: DiscoveryConfig;
   execution?: TestkitExecutionConfig;
   profiles?: {
     http?: Record<string, HttpSuiteConfig>;

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.58",
+  "version": "0.1.59",
   "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.58",
-    "@elench/testkit-protocol": "0.1.58",
+    "@elench/testkit-bridge": "0.1.59",
+    "@elench/testkit-protocol": "0.1.59",
     "@babel/code-frame": "^7.29.0",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",