@elench/testkit 0.1.56 → 0.1.57

package/README.md

@@ -14,6 +14,12 @@ cd my-product
 # Run every testkit-managed suite
 npx @elench/testkit
 
+# Inspect discovered tests without running them
+npx @elench/testkit discover
+npx @elench/testkit discover --output-mode verbose
+npx @elench/testkit discover --json > .testkit/discovery.json
+npx @elench/testkit discover --output .testkit/discovery.json
+
 # Filter by type
 npx @elench/testkit --type int
 npx @elench/testkit --type dal
@@ -70,6 +76,11 @@ captured runtime output, emitted artifacts, and user-visible LLM responses are
 persisted under `.testkit/results/` and inspected on demand with `show`,
 `artifacts`, `logs`, or `watch`.
 
+`testkit discover` also maintains a small durable per-test history index at
+`.testkit/history/tests.json`. The index tracks first/last seen timestamps,
+run counts, pass/fail/skip counts, average duration, and last observed status,
+and those summaries are exposed in compact, verbose, and JSON discovery output.
+
 ## Setup
 
 Create `testkit.setup.ts` at repo root:
@@ -411,6 +422,54 @@ Suite names are inferred from the colocated path:
 - `auth/__testkit__/*.int.testkit.ts` => `auth`
 - `routes/__testkit__/auth/*.int.testkit.ts` => `auth`
 
+Discovery is also a first-class CLI/API surface:
+
+- `testkit discover`
+  - human-first compact output with service -> type -> suite -> file hierarchy
+- `testkit discover --output-mode verbose`
+  - explicit paths, IDs, locks, dependencies, skip reasons, and history detail
+- `testkit discover --json`
+  - machine-readable output with stable enums, canonical paths, and summary data
+- `testkit discover --output .testkit/discovery.json`
+  - writes the same machine-readable JSON document to a file artifact
+
+Compact mode prefers derived human labels such as `Agent Configs Auth Gate`
+instead of printing long file paths as the primary row label. Exact paths remain
+available in verbose and JSON output.
+
+The public API is exported from `@elench/testkit/discovery`:
+
+```ts
+import { discoverTests } from "@elench/testkit/discovery";
+
+const result = await discoverTests({
+  dir: process.cwd(),
+  runnableOnly: true,
+  diagnostics: "report",
+});
+```
+
+JSON and file output are machine-first. Each discovered file carries a stable
+identifier plus canonical metadata such as:
+
+- `id`
+- `path`
+- `service`
+- `suiteName`
+- `selectionType`
+- `internalType`
+- `framework`
+- `skipped`
+- `skipReason`
+- `locks`
+- `dependsOn`
+- `displayName`
+- `history`
+
+Discovery history is generic and local to `testkit`. `firstSeenAt` is derived
+from the first time a file appears in the history index, not from filesystem or
+Git metadata.
+
 ## Local Databases
 
 `@elench/testkit` provisions Docker-managed local Postgres automatically for

package/lib/cli/commands/discover.mjs

@@ -0,0 +1,80 @@
+import fs from "fs";
+import path from "path";
+import { Command, Flags } from "@oclif/core";
+import { discoverTests } from "../../discovery/index.mjs";
+import { resolveProductDir } from "../../config/index.mjs";
+import { buildDiscoveryReportLines } from "../presentation/discovery-reporter.mjs";
+import { resolveRequestedFiles } from "../args.mjs";
+import { sharedFlags } from "../command-helpers.mjs";
+
+export default class DiscoverCommand extends Command {
+  static summary = "Discover managed tests and report their metadata";
+
+  static enableJsonFlag = true;
+
+  static flags = {
+    ...sharedFlags,
+    type: Flags.string({
+      char: "t",
+      multiple: true,
+      description: "Filter by suite type(s): int, e2e, scenario, dal, load, pw, all",
+    }),
+    suite: Flags.string({
+      char: "s",
+      multiple: true,
+      description: "Filter by suite selector(s)",
+    }),
+    file: Flags.string({
+      char: "f",
+      multiple: true,
+      description: "Filter by exact file path(s)",
+    }),
+    "runnable-only": Flags.boolean({
+      description: "Show only files not skipped by repo rules",
+      default: false,
+    }),
+    strict: Flags.boolean({
+      description: "Fail instead of reporting discovery/config diagnostics",
+      default: false,
+    }),
+    output: Flags.string({
+      description: "Write machine-readable discovery JSON to a file",
+    }),
+    "output-mode": Flags.string({
+      description: "Human-readable output mode",
+      options: ["compact", "verbose"],
+      default: "compact",
+    }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(DiscoverCommand);
+    const productDir = resolveProductDir(process.cwd(), flags.dir);
+    const fileNames = resolveRequestedFiles(flags.file || [], productDir, process.cwd());
+    const result = await discoverTests({
+      dir: productDir,
+      service: flags.service || null,
+      type: flags.type || [],
+      suite: flags.suite || [],
+      file: fileNames,
+      runnableOnly: flags["runnable-only"],
+      diagnostics: flags.strict ? "error" : "report",
+    });
+    let outputLabel = null;
+    if (flags.output) {
+      const outputPath = path.resolve(productDir, flags.output);
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+      fs.writeFileSync(outputPath, `${JSON.stringify(result, null, 2)}\n`);
+      outputLabel = path.relative(productDir, outputPath) || path.basename(outputPath);
+    }
+
+    if (!this.jsonEnabled()) {
+      for (const line of buildDiscoveryReportLines(result, { outputMode: flags["output-mode"] })) {
+        this.log(line);
+      }
+      if (outputLabel) this.log(`Wrote ${outputLabel}`);
+    }
+
+    return result;
+  }
+}

package/lib/cli/entrypoint.mjs

@@ -8,6 +8,7 @@ export function normalizeCliArgs(argv) {
     "logs",
     "artifacts",
     "watch",
+    "discover",
     "known-failures",
     "db",
     "help",

package/lib/cli/presentation/colors.mjs

@@ -14,6 +14,38 @@ export function dim(text) {
   return pc.dim(text);
 }
 
+export function bold(text) {
+  return pc.bold(text);
+}
+
+export function muted(text) {
+  return pc.dim(text);
+}
+
+export function colorHeading(text) {
+  return pc.bold(text);
+}
+
+export function colorService(text) {
+  return pc.cyan(pc.bold(text));
+}
+
+export function colorTypeBadge(type) {
+  if (type === "INT") return pc.blue(type);
+  if (type === "E2E") return pc.magenta(type);
+  if (type === "SCENARIO") return pc.yellow(type);
+  if (type === "DAL") return pc.green(type);
+  if (type === "LOAD") return pc.cyan(type);
+  if (type === "PW") return pc.blue(pc.bold(type));
+  return type;
+}
+
+export function colorDiagnosticSeverity(severity) {
+  if (severity === "error") return pc.red(pc.bold("ERR"));
+  if (severity === "warning") return pc.yellow(pc.bold("WARN"));
+  return pc.dim("INFO");
+}
+
 export function colorResultLine(line) {
   if (/^Result: PASSED\b/.test(line)) return line.replace("PASSED", pc.green("PASSED"));
   if (/^Result: FAILED\b/.test(line)) return line.replace("FAILED", pc.red("FAILED"));

package/lib/cli/presentation/discovery-reporter.mjs

@@ -0,0 +1,166 @@
+import { formatDuration } from "../../runner/formatting.mjs";
+import { formatSelectionTypeLabel } from "../../discovery/index.mjs";
+import {
+  bold,
+  colorDiagnosticSeverity,
+  colorHeading,
+  colorService,
+  colorStatus,
+  colorTypeBadge,
+  muted,
+} from "./colors.mjs";
+
+const TYPE_ORDER = ["int", "e2e", "scenario", "dal", "load", "pw"];
+
+export function buildDiscoveryReportLines(result, options = {}) {
+  const mode = options.outputMode || "compact";
+  return mode === "verbose" ? buildVerboseLines(result) : buildCompactLines(result);
+}
+
+function buildCompactLines(result) {
+  const lines = [];
+  lines.push(
+    `${colorHeading("Summary")} ${result.summary.files} files · ${result.summary.activeFiles} active · ${result.summary.skippedFiles} skipped · ${result.summary.suites} suites · ${result.summary.services} services`
+  );
+
+  if (result.history?.available) {
+    lines.push(muted(`history ${result.history.path || ".testkit/history/tests.json"}`));
+  }
+
+  appendDiagnostics(lines, result.diagnostics);
+
+  const suitesByService = groupSuitesByServiceAndType(result.suites);
+  const filesBySuite = groupFilesBySuite(result.files);
+
+  for (const service of result.services) {
+    lines.push("");
+    lines.push(
+      `${colorService(service.name)} ${muted(`(${service.fileCount} files${service.dependsOn.length > 0 ? ` · depends on ${service.dependsOn.join(", ")}` : ""})`)}`
+    );
+    const typeGroups = suitesByService.get(service.name) || new Map();
+    for (const type of orderedTypes([...typeGroups.keys()])) {
+      const suites = typeGroups.get(type) || [];
+      lines.push(`  ${colorTypeBadge(type.toUpperCase())} ${formatSelectionTypeLabel(type)}`);
+      for (const suite of suites) {
+        lines.push(`    ${bold(suite.groupLabel)} ${muted(`(${suite.fileCount} files)`)}`);
+        for (const file of filesBySuite.get(suite.id) || []) {
+          const status = file.skipped ? `${colorStatus("SKIP")} ${file.skipReason}` : muted(buildHistoryHint(file));
+          lines.push(`      ${file.displayName}${status ? `  ${status}` : ""}`);
+        }
+      }
+    }
+  }
+
+  return lines;
+}
+
+function buildVerboseLines(result) {
+  const lines = [];
+  lines.push(`${colorHeading("Summary")} ${JSON.stringify(result.summary)}`);
+  if (result.setupFile) {
+    lines.push(`setup ${result.setupFile}`);
+  }
+  if (result.history?.available) {
+    lines.push(`history ${result.history.path}`);
+  }
+
+  appendDiagnostics(lines, result.diagnostics);
+
+  for (const service of result.services) {
+    lines.push("");
+    lines.push(colorService(service.name));
+    lines.push(`  cwd ${service.localCwd}`);
+    if (service.dependsOn.length > 0) {
+      lines.push(`  dependsOn ${service.dependsOn.join(", ")}`);
+    }
+    lines.push(`  files ${service.fileCount} · active ${service.activeFileCount} · skipped ${service.skippedFileCount}`);
+
+    const suites = result.suites.filter((suite) => suite.service === service.name).sort(compareSuites);
+    for (const suite of suites) {
+      lines.push(
+        `  suite ${suite.selectionType}:${suite.name} ${muted(`[${suite.framework}]`)} ${muted(`${suite.fileCount} files`)}`
+      );
+      if (suite.locks.length > 0) {
+        lines.push(`    locks ${suite.locks.join(", ")}`);
+      }
+      for (const file of result.files.filter((entry) => entry.service === service.name && entry.suiteName === suite.name && entry.selectionType === suite.selectionType)) {
+        lines.push(`    ${file.displayName}`);
+        lines.push(`      path ${file.path}`);
+        lines.push(`      id ${file.id}`);
+        lines.push(`      status ${file.skipped ? "skipped" : "active"}`);
+        if (file.skipReason) lines.push(`      skipReason ${file.skipReason}`);
+        if (file.locks.length > 0) lines.push(`      locks ${file.locks.join(", ")}`);
+        if (file.history) {
+          lines.push(
+            `      history runs=${file.history.runCount} pass=${file.history.passCount} fail=${file.history.failCount} skip=${file.history.skipCount} avg=${file.history.avgDurationMs > 0 ? formatDuration(file.history.avgDurationMs) : "0s"} last=${file.history.lastStatus || "unknown"} firstSeen=${file.history.firstSeenAt || "unknown"}`
+          );
+        }
+      }
+    }
+  }
+
+  return lines;
+}
+
+function appendDiagnostics(lines, diagnostics = []) {
+  if (!diagnostics.length) return;
+  lines.push("");
+  lines.push(colorHeading("Diagnostics"));
+  for (const entry of diagnostics) {
+    const location = entry.path ? ` ${entry.path}` : "";
+    lines.push(`  ${colorDiagnosticSeverity(entry.severity)} ${entry.code}${location}`);
+    lines.push(`    ${entry.message}`);
+  }
+}
+
+function groupSuitesByServiceAndType(suites) {
+  const grouped = new Map();
+  for (const suite of suites) {
+    let byType = grouped.get(suite.service);
+    if (!byType) {
+      byType = new Map();
+      grouped.set(suite.service, byType);
+    }
+    const list = byType.get(suite.selectionType) || [];
+    list.push(suite);
+    byType.set(suite.selectionType, list.sort(compareSuites));
+  }
+  return grouped;
+}
+
+function groupFilesBySuite(files) {
+  const bySuite = new Map();
+  for (const file of files) {
+    const suiteId = [file.service, file.selectionType, file.framework, file.suiteName].join("|");
+    const list = bySuite.get(suiteId) || [];
+    list.push(file);
+    bySuite.set(
+      suiteId,
+      list.sort((left, right) => left.displayName.localeCompare(right.displayName) || left.path.localeCompare(right.path))
+    );
+  }
+  return bySuite;
+}
+
+function orderedTypes(types) {
+  return [...types].sort((left, right) => TYPE_ORDER.indexOf(left) - TYPE_ORDER.indexOf(right));
+}
+
+function compareSuites(left, right) {
+  return left.groupLabel.localeCompare(right.groupLabel) || left.name.localeCompare(right.name);
+}
+
+function buildHistoryHint(file) {
+  if (!file.history) return "";
+  const totalCompleted = file.history.passCount + file.history.failCount;
+  const passRate = totalCompleted > 0 ? `${Math.round((file.history.passCount / totalCompleted) * 100)}% pass` : "no result history";
+  const avg = file.history.avgDurationMs > 0 ? formatDuration(file.history.avgDurationMs) : null;
+  return [
+    `${file.history.runCount} ${file.history.runCount === 1 ? "run" : "runs"}`,
+    passRate,
+    avg ? `avg ${avg}` : null,
+    file.history.firstSeenAt ? `seen ${file.history.firstSeenAt.slice(0, 10)}` : null,
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}

package/lib/config/discovery.mjs

@@ -29,13 +29,13 @@ const IGNORED_DIRS = new Set([
   "test-results",
 ]);
 
-export function discoverProject(productDir, explicitServices = {}) {
+export function discoverProject(productDir, explicitServices = {}, options = {}) {
+  const strict = options.strict !== false;
   const { suiteFiles, legacyFiles } = discoverFiles(productDir);
   const groupedByService = {};
   const services = {};
-  const unowned = [];
-  const ambiguous = [];
-  const discoveredSuites = [];
+  const diagnostics = buildLegacyFileDiagnostics(legacyFiles);
+  const discoveredFiles = [];
 
   for (const filePath of suiteFiles) {
     const rule = inferRule(filePath);
@@ -43,12 +43,20 @@ export function discoverProject(productDir, explicitServices = {}) {
 
     const owners = inferOwners(filePath, explicitServices);
     if (owners.length === 0) {
-      unowned.push(filePath);
+      diagnostics.push({
+        code: "unowned_test",
+        severity: "error",
+        message: `Unowned test file: ${filePath}`,
+        path: filePath,
+      });
       continue;
     }
     if (owners.length > 1) {
-      ambiguous.push({
-        filePath,
+      diagnostics.push({
+        code: "ambiguous_test",
+        severity: "error",
+        message: `Ambiguous test file: ${filePath} -> ${owners.map((owner) => owner.name).sort((left, right) => left.localeCompare(right)).join(", ")}`,
+        path: filePath,
         serviceNames: owners.map((owner) => owner.name).sort((left, right) => left.localeCompare(right)),
       });
       continue;
@@ -58,7 +66,7 @@ export function discoverProject(productDir, explicitServices = {}) {
     services[owner.name] = mergeServiceDiscovery(services[owner.name], owner);
     const relativeToService = relativeToServiceRoot(owner, filePath);
     const suiteRef = deriveSuiteRef(relativeToService, rule.suffix);
-    discoveredSuites.push({
+    discoveredFiles.push({
       serviceName: owner.name,
       type: rule.type,
       framework: rule.framework,
@@ -67,11 +75,11 @@ export function discoverProject(productDir, explicitServices = {}) {
     });
   }
 
-  if (legacyFiles.length > 0 || unowned.length > 0 || ambiguous.length > 0) {
-    throw buildDiscoveryError(legacyFiles, unowned, ambiguous);
+  if (strict && hasDiscoveryErrors(diagnostics)) {
+    throw buildDiscoveryErrorFromDiagnostics(diagnostics);
   }
 
-  for (const entry of discoveredSuites) {
+  for (const entry of discoveredFiles) {
     const grouped = groupedByService[entry.serviceName] || {};
     const suitesForType = grouped[entry.type] || [];
     const suiteKey = entry.suitePath.join("/");
@@ -95,12 +103,23 @@ export function discoverProject(productDir, explicitServices = {}) {
     suite.files.push(entry.filePath);
   }
 
+  const fileEntries = [];
   for (const grouped of Object.values(groupedByService)) {
     for (const suites of Object.values(grouped)) {
       const suiteNames = disambiguateSuiteNames(suites);
       for (const suite of suites) {
         suite.name = suiteNames.get(suite._suiteKey);
         suite.files.sort((left, right) => left.localeCompare(right));
+        for (const filePath of suite.files) {
+          fileEntries.push({
+            serviceName: findSuiteServiceName(groupedByService, grouped, suite),
+            type: findSuiteType(grouped, suites),
+            framework: suite.framework,
+            suiteName: suite.name,
+            suitePath: [...suite._suitePath],
+            filePath,
+          });
+        }
         delete suite._suiteKey;
         delete suite._suitePath;
       }
@@ -111,11 +130,59 @@ export function discoverProject(productDir, explicitServices = {}) {
   return {
     services,
     suitesByService: groupedByService,
+    files: fileEntries.sort(
+      (left, right) =>
+        left.serviceName.localeCompare(right.serviceName) ||
+        left.type.localeCompare(right.type) ||
+        left.suiteName.localeCompare(right.suiteName) ||
+        left.filePath.localeCompare(right.filePath)
+    ),
+    diagnostics,
   };
 }
 
-export function discoverSuites(productDir, explicitServices = {}) {
-  return discoverProject(productDir, explicitServices).suitesByService;
+export function discoverSuites(productDir, explicitServices = {}, options = {}) {
+  return discoverProject(productDir, explicitServices, options).suitesByService;
+}
+
+export function hasDiscoveryErrors(diagnostics = []) {
+  return diagnostics.some((entry) => entry?.severity === "error");
+}
+
+export function buildDiscoveryErrorFromDiagnostics(diagnostics = []) {
+  const lines = ["Filesystem discovery failed for one or more .testkit.ts files."];
+
+  const legacyFiles = diagnostics.filter((entry) => entry.code === "legacy_path").map((entry) => entry.path);
+  const unownedFiles = diagnostics.filter((entry) => entry.code === "unowned_test").map((entry) => entry.path);
+  const ambiguousFiles = diagnostics.filter((entry) => entry.code === "ambiguous_test");
+
+  if (legacyFiles.length > 0) {
+    lines.push("");
+    lines.push("Legacy test files outside __testkit__:");
+    for (const filePath of legacyFiles) {
+      lines.push(`- ${filePath}`);
+    }
+  }
+
+  if (unownedFiles.length > 0) {
+    lines.push("");
+    lines.push("Unowned test files:");
+    for (const filePath of unownedFiles) {
+      lines.push(`- ${filePath}`);
+    }
+  }
+
+  if (ambiguousFiles.length > 0) {
+    lines.push("");
+    lines.push("Ambiguous test files:");
+    for (const entry of ambiguousFiles) {
+      lines.push(`- ${entry.path} -> ${entry.serviceNames.join(", ")}`);
+    }
+  }
+
+  lines.push("");
+  lines.push('Expected test files to live under a "__testkit__" directory within a service root.');
+  return new Error(lines.join("\n"));
 }
 
 function discoverFiles(productDir) {
@@ -306,38 +373,6 @@ function mergeServiceDiscovery(existing, owner) {
   };
 }
 
-function buildDiscoveryError(legacyFiles, unowned, ambiguous) {
-  const lines = ["Filesystem discovery failed for one or more .testkit.ts files."];
-
-  if (legacyFiles.length > 0) {
-    lines.push("");
-    lines.push("Legacy test files outside __testkit__:");
-    for (const filePath of legacyFiles) {
-      lines.push(`- ${filePath}`);
-    }
-  }
-
-  if (unowned.length > 0) {
-    lines.push("");
-    lines.push("Unowned test files:");
-    for (const filePath of unowned) {
-      lines.push(`- ${filePath}`);
-    }
-  }
-
-  if (ambiguous.length > 0) {
-    lines.push("");
-    lines.push("Ambiguous test files:");
-    for (const entry of ambiguous) {
-      lines.push(`- ${entry.filePath} -> ${entry.serviceNames.join(", ")}`);
-    }
-  }
-
-  lines.push("");
-  lines.push('Expected test files to live under a "__testkit__" directory within a service root.');
-  return new Error(lines.join("\n"));
-}
-
 function inferRule(filePath) {
   return DISCOVERY_RULES.find((rule) => filePath.endsWith(rule.suffix)) || null;
 }
@@ -351,3 +386,29 @@ function normalizePath(value) {
   if (normalized === "." || normalized === "./") return ".";
   return normalized.replace(/^\.\/+/, "").replace(/\/+$/, "") || ".";
 }
+
+function buildLegacyFileDiagnostics(legacyFiles) {
+  return legacyFiles.map((filePath) => ({
+    code: "legacy_path",
+    severity: "error",
+    message: `Legacy test file outside __testkit__: ${filePath}`,
+    path: filePath,
+  }));
+}
+
+function findSuiteServiceName(groupedByService, grouped, suite) {
+  for (const [serviceName, candidate] of Object.entries(groupedByService)) {
+    if (candidate !== grouped) continue;
+    for (const suites of Object.values(candidate)) {
+      if (suites.includes(suite)) return serviceName;
+    }
+  }
+  return "app";
+}
+
+function findSuiteType(grouped, targetSuites) {
+  for (const [type, suites] of Object.entries(grouped)) {
+    if (suites === targetSuites) return type;
+  }
+  return "integration";
+}

package/lib/config/discovery.test.mjs

@@ -22,7 +22,7 @@ describe("filesystem-discovery", () => {
     writeFile(productDir, "src/api/routes/__testkit__/journeys/smoke.scenario.testkit.ts");
     writeFile(productDir, "frontend/app/__testkit__/homepage/homepage.pw.testkit.ts");
 
-    const suites = discoverSuites(productDir, {
+    const project = discoverProject(productDir, {
       api: {
         local: {
           cwd: ".",
@@ -35,6 +35,7 @@ describe("filesystem-discovery", () => {
       },
     });
 
+    const suites = project.suitesByService;
     expect(suites.api.integration).toEqual([
       {
         name: "auth",
@@ -61,6 +62,41 @@ describe("filesystem-discovery", () => {
         framework: "playwright",
       },
     ]);
+    expect(project.files).toEqual([
+      {
+        serviceName: "api",
+        type: "integration",
+        framework: "k6",
+        suiteName: "auth",
+        suitePath: ["src", "api", "routes", "auth"],
+        filePath: "src/api/routes/__testkit__/auth/me.int.testkit.ts",
+      },
+      {
+        serviceName: "api",
+        type: "integration",
+        framework: "k6",
+        suiteName: "health",
+        suitePath: ["src", "api", "routes", "health"],
+        filePath: "src/api/routes/__testkit__/health/ready.int.testkit.ts",
+      },
+      {
+        serviceName: "api",
+        type: "scenario",
+        framework: "k6",
+        suiteName: "journeys",
+        suitePath: ["src", "api", "routes", "journeys"],
+        filePath: "src/api/routes/__testkit__/journeys/smoke.scenario.testkit.ts",
+      },
+      {
+        serviceName: "frontend",
+        type: "e2e",
+        framework: "playwright",
+        suiteName: "homepage",
+        suitePath: ["app", "homepage"],
+        filePath: "frontend/app/__testkit__/homepage/homepage.pw.testkit.ts",
+      },
+    ]);
+    expect(project.diagnostics).toEqual([]);
   });
 
   it("infers the suite from the directory that owns __testkit__", () => {
@@ -130,6 +166,44 @@ describe("filesystem-discovery", () => {
       })
     ).toThrow("Legacy test files outside __testkit__");
   });
+
+  it("reports legacy files in non-strict mode", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-discovery-"));
+    cleanups.push(() => fs.rmSync(productDir, { recursive: true, force: true }));
+
+    writeFile(productDir, "src/api/routes/__testkit__/health/ready.int.testkit.ts");
+    writeFile(productDir, "tests/api/integration/health.int.testkit.ts");
+
+    const project = discoverProject(
+      productDir,
+      {
+        api: {
+          local: {
+            cwd: ".",
+          },
+        },
+      },
+      {
+        strict: false,
+      }
+    );
+
+    expect(project.suitesByService.api.integration).toEqual([
+      {
+        name: "health",
+        files: ["src/api/routes/__testkit__/health/ready.int.testkit.ts"],
+        framework: "k6",
+      },
+    ]);
+    expect(project.diagnostics).toEqual([
+      {
+        code: "legacy_path",
+        severity: "error",
+        message: "Legacy test file outside __testkit__: tests/api/integration/health.int.testkit.ts",
+        path: "tests/api/integration/health.int.testkit.ts",
+      },
+    ]);
+  });
 });
 
 function writeFile(productDir, relativePath) {