@elench/testkit 0.1.59 → 0.1.61

package/lib/config/validation.mjs

@@ -0,0 +1,124 @@
+import { ensureExistingPath, resolveServiceCwd } from "./paths.mjs";
+import { parseModuleSpecifier } from "./runtime.mjs";
+
+export function validateConfigCoverage(configs) {
+  const names = new Set(configs.map((config) => config.name));
+  for (const config of configs) {
+    for (const depName of config.testkit.dependsOn || []) {
+      if (!names.has(depName)) {
+        throw new Error(`Service "${config.name}" depends on "${depName}", but ${depName} is not defined`);
+      }
+    }
+    const databaseFrom = config.testkit.databaseFrom;
+    if (databaseFrom && !names.has(databaseFrom)) {
+      throw new Error(`Service "${config.name}" databaseFrom "${databaseFrom}" is not defined`);
+    }
+  }
+}
+
+export function validateServiceConfig({
+  name,
+  local,
+  database,
+  databaseFrom,
+  runtime,
+  dependsOn,
+  suites,
+  productDir,
+}) {
+  const usesLocalExecution = Object.entries(suites).some(([suiteType, discoveredSuites]) =>
+    discoveredSuites.some((suite) => (suite.framework && suite.framework !== "k6") || suiteType !== "dal")
+  );
+
+  if (usesLocalExecution && !local) {
+    throw new Error(
+      `Service "${name}" defines non-DAL suites but no local runtime could be resolved. Add it in testkit.setup.ts.`
+    );
+  }
+
+  if (database && databaseFrom) {
+    throw new Error(`Service "${name}" cannot define both database and databaseFrom`);
+  }
+  if (runtime.instances < 1) {
+    throw new Error(`Service "${name}" runtime.instances must be a positive integer`);
+  }
+  if (runtime.maxConcurrentTasks <= 0) {
+    throw new Error(`Service "${name}" runtime.maxConcurrentTasks must be a positive integer when provided`);
+  }
+
+  for (const depName of dependsOn || []) {
+    if (depName === name) {
+      throw new Error(`Service "${name}" cannot depend on itself`);
+    }
+  }
+
+  if (local?.cwd) {
+    ensureExistingPath(productDir, local.cwd, `Service "${name}" local.cwd`);
+  }
+  if (runtime.toolchain?.cwd) {
+    ensureExistingPath(productDir, runtime.toolchain.cwd, `Service "${name}" runtime.toolchain.cwd`);
+  }
+  for (const [stageName, steps] of Object.entries(database?.template || {})) {
+    if (stageName === "inputs") continue;
+    for (const step of steps || []) {
+      if (step.cwd) {
+        ensureExistingPath(productDir, step.cwd, `Service "${name}" database.template.${stageName} step cwd`);
+      }
+      if (step.kind === "sql-file") {
+        ensureExistingPath(
+          resolveServiceCwd(productDir, step.cwd || "."),
+          step.path,
+          `Service "${name}" database.template.${stageName} sql file`
+        );
+      }
+      if (step.kind === "module") {
+        const { modulePath } = parseModuleSpecifier(step.specifier);
+        ensureExistingPath(
+          resolveServiceCwd(productDir, step.cwd || "."),
+          modulePath,
+          `Service "${name}" database.template.${stageName} module`
+        );
+      }
+      for (const input of step.inputs || []) {
+        ensureExistingPath(
+          resolveServiceCwd(productDir, step.cwd || "."),
+          input,
+          `Service "${name}" database.template.${stageName} step input`
+        );
+      }
+    }
+  }
+  for (const input of database?.template?.inputs || []) {
+    ensureExistingPath(productDir, input, `Service "${name}" database.template input`);
+  }
+  for (const step of runtime.prepare?.steps || []) {
+    if (step.cwd) {
+      ensureExistingPath(productDir, step.cwd, `Service "${name}" runtime.prepare step cwd`);
+    }
+    if (step.kind === "sql-file") {
+      ensureExistingPath(
+        resolveServiceCwd(productDir, step.cwd || "."),
+        step.path,
+        `Service "${name}" runtime.prepare sql file`
+      );
+    }
+    if (step.kind === "module") {
+      const { modulePath } = parseModuleSpecifier(step.specifier);
+      ensureExistingPath(
+        resolveServiceCwd(productDir, step.cwd || "."),
+        modulePath,
+        `Service "${name}" runtime.prepare module`
+      );
+    }
+    for (const input of step.inputs || []) {
+      ensureExistingPath(
+        resolveServiceCwd(productDir, step.cwd || "."),
+        input,
+        `Service "${name}" runtime.prepare step input`
+      );
+    }
+  }
+  for (const input of runtime.prepare?.inputs || []) {
+    ensureExistingPath(productDir, input, `Service "${name}" runtime.prepare input`);
+  }
+}

package/lib/coverage/backend-discovery.mjs

@@ -0,0 +1,183 @@
+import fs from "fs";
+import path from "path";
+import {
+  dedupeBackendImports,
+  dedupeDataImports,
+  dedupeEdges,
+  dedupeNodes,
+  escapeRegExp,
+  hasWord,
+  isBackendSpecifier,
+  isDataSpecifier,
+  modulePathKey,
+} from "./shared.mjs";
+import { resolveImportToSourceFile } from "./fs-walk.mjs";
+
+export function extractBackendImports({
+  serviceName,
+  serviceRoot,
+  filePath,
+  content,
+  resolveImport = resolveImportToSourceFile,
+  resolveImportToSourceFile: resolveImportAlias,
+}) {
+  const resolveImportFn = resolveImportAlias || resolveImport;
+  const imports = [];
+  const importRegex = /import\s+\{([^}]+)\}\s+from\s+["'`]([^"'`]+)["'`]/gu;
+  for (const match of content.matchAll(importRegex)) {
+    const rawNames = match[1]
+      .split(",")
+      .map((entry) => entry.trim())
+      .map((entry) => entry.split(/\s+as\s+/u)[0]?.trim())
+      .filter(Boolean);
+    const specifier = match[2].trim();
+    if (!isBackendSpecifier(specifier)) continue;
+    const resolvedFilePath = resolveImportFn(serviceRoot, filePath, specifier);
+    for (const importName of rawNames) {
+      imports.push({
+        importName,
+        node: {
+          id: `server_capability:${modulePathKey(resolvedFilePath || filePath)}#${importName}`,
+          kind: "server_capability",
+          service: serviceName,
+          label: importName,
+          filePath: resolvedFilePath || null,
+          metadata: {
+            specifier,
+          },
+        },
+      });
+    }
+  }
+  return dedupeBackendImports(imports);
+}
+
+export function discoverDataCapabilities({ serviceName, serviceRoot, nodes, readFile = defaultReadFile }) {
+  const dataNodes = [];
+  const dataEdges = [];
+  const serverCapabilities = nodes.filter((node) => node.kind === "server_capability" && node.filePath);
+
+  for (const capability of serverCapabilities) {
+    const absolutePath = path.join(serviceRoot, capability.filePath);
+    const content = readFile(absolutePath);
+    if (!content) continue;
+    const dataImports = extractDataImports({ serviceName, serviceRoot, filePath: capability.filePath, content });
+    const exportedBody = extractExportedFunctionBody(content, capability.label);
+    if (!exportedBody) continue;
+
+    const matchedDataImports = dataImports.filter((entry) => hasWord(exportedBody, entry.importName));
+    for (const dataImport of matchedDataImports) {
+      dataNodes.push(dataImport.node);
+      dataEdges.push({
+        id: `delegates_to:${capability.id}:${dataImport.node.id}`,
+        kind: "delegates_to",
+        from: capability.id,
+        to: dataImport.node.id,
+        confidence: "high",
+      });
+    }
+  }
+
+  return {
+    nodes: dedupeNodes(dataNodes),
+    edges: dedupeEdges(dataEdges),
+  };
+}
+
+export function extractDataImports({
+  serviceName,
+  serviceRoot,
+  filePath,
+  content,
+  resolveImport = resolveImportToSourceFile,
+  resolveImportToSourceFile: resolveImportAlias,
+}) {
+  const resolveImportFn = resolveImportAlias || resolveImport;
+  const imports = [];
+  const importRegex = /import\s+\{([^}]+)\}\s+from\s+["'`]([^"'`]+)["'`]/gu;
+  for (const match of content.matchAll(importRegex)) {
+    const rawNames = match[1]
+      .split(",")
+      .map((entry) => entry.trim())
+      .map((entry) => entry.split(/\s+as\s+/u)[0]?.trim())
+      .filter(Boolean);
+    const specifier = match[2].trim();
+    if (!isDataSpecifier(specifier)) continue;
+    const resolvedFilePath = resolveImportFn(serviceRoot, filePath, specifier);
+    for (const importName of rawNames) {
+      imports.push({
+        importName,
+        node: {
+          id: `data_capability:${modulePathKey(resolvedFilePath || filePath)}#${importName}`,
+          kind: "data_capability",
+          service: serviceName,
+          label: importName,
+          filePath: resolvedFilePath || null,
+          metadata: {
+            specifier,
+          },
+        },
+      });
+    }
+  }
+  return dedupeDataImports(imports);
+}
+
+export function extractExportedMethodBodies(content, methods) {
+  const bodies = [];
+  for (const method of methods) {
+    const body = extractExportedFunctionBody(content, method);
+    if (body) bodies.push([method, body]);
+  }
+  return bodies;
+}
+
+export function extractExportedFunctions(content) {
+  const exported = [];
+  const functionRegex = /export\s+(?:async\s+)?function\s+([A-Za-z0-9_]+)\s*\(/gu;
+  for (const match of content.matchAll(functionRegex)) {
+    const name = match[1];
+    const body = extractExportedFunctionBody(content, name);
+    if (!body) continue;
+    exported.push({ name, body });
+  }
+  return exported;
+}
+
+export function extractExportedFunctionBody(content, exportName) {
+  const functionStart = new RegExp(`export\\s+(?:async\\s+)?function\\s+${escapeRegExp(exportName)}\\s*\\(`, "u");
+  const startMatch = functionStart.exec(content);
+  if (!startMatch) return null;
+  const afterSignatureIndex = content.indexOf("{", startMatch.index);
+  if (afterSignatureIndex === -1) return null;
+  return readBalancedBlock(content, afterSignatureIndex);
+}
+
+export function readBalancedBlock(content, startIndex) {
+  let depth = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let inTemplate = false;
+
+  for (let index = startIndex; index < content.length; index += 1) {
+    const char = content[index];
+    const previous = content[index - 1];
+    if (char === "'" && !inDouble && !inTemplate && previous !== "\\") inSingle = !inSingle;
+    if (char === '"' && !inSingle && !inTemplate && previous !== "\\") inDouble = !inDouble;
+    if (char === "`" && !inSingle && !inDouble && previous !== "\\") inTemplate = !inTemplate;
+    if (inSingle || inDouble || inTemplate) continue;
+    if (char === "{") depth += 1;
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return content.slice(startIndex, index + 1);
+      }
+    }
+  }
+  return null;
+}
+
+function defaultReadFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, "utf8");
+}

package/lib/coverage/backend-discovery.test.mjs

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import {
+  extractExportedFunctionBody,
+  extractExportedFunctions,
+  extractExportedMethodBodies,
+  readBalancedBlock,
+} from "./backend-discovery.mjs";
+
+describe("coverage backend discovery helpers", () => {
+  it("extracts exported HTTP method bodies without being confused by braces in strings", () => {
+    const content = `
+      export async function GET() {
+        const template = "{not a block}";
+        return template;
+      }
+
+      export async function POST() {
+        return { ok: true };
+      }
+    `;
+
+    expect(extractExportedMethodBodies(content, ["GET", "POST"])).toEqual([
+      ["GET", expect.stringContaining('"{not a block}"')],
+      ["POST", expect.stringContaining("{ ok: true }")],
+    ]);
+  });
+
+  it("extracts named exported functions and their bodies", () => {
+    const content = `
+      export async function saveSettings() {
+        return updateSettings();
+      }
+
+      export function listSettings() {
+        return [];
+      }
+    `;
+
+    expect(extractExportedFunctions(content)).toEqual([
+      { name: "saveSettings", body: expect.stringContaining("updateSettings") },
+      { name: "listSettings", body: expect.stringContaining("return [];") },
+    ]);
+    expect(extractExportedFunctionBody(content, "saveSettings")).toContain("updateSettings");
+  });
+
+  it("reads a balanced block from a brace offset", () => {
+    const content = `before { const tpl = \`{nested}\`; return tpl; } after`;
+    const startIndex = content.indexOf("{");
+
+    expect(readBalancedBlock(content, startIndex)).toBe("{ const tpl = `{nested}`; return tpl; }");
+  });
+});

package/lib/coverage/evidence.mjs

@@ -0,0 +1,146 @@
+import fs from "fs";
+import path from "path";
+import { extractHttpSuiteRequests } from "./next-static-analysis.mjs";
+import {
+  apiRouteLookupKey,
+  HTTP_METHODS,
+  dedupeTargets,
+  toApiRequestPath,
+  toSelectionType,
+} from "./shared.mjs";
+import {
+  inferApiRoutesFromTestFile,
+  inferOwnerDirectoryFromTestFile,
+  inferPageRouteFromTestFile,
+  pathMatchesOwner,
+} from "./routing.mjs";
+
+export function inferCoveredNodeIdsForTest(entry, context) {
+  const coveredNodeIds = new Set();
+  const selectionType = toSelectionType(entry.type, entry.framework);
+
+  if (entry.framework === "playwright") {
+    const route = inferPageRouteFromTestFile(entry.filePath, context.nextAppRoot, context.serviceRoot);
+    if (route && context.pageByRoute.has(route)) {
+      const pageEntry = context.pageByRoute.get(route);
+      coveredNodeIds.add(pageEntry.node.id);
+      for (const target of extractPlaywrightTargets(entry, context)) {
+        const surfaceNode = pageEntry.surfacesByTargetValue?.get(target.value);
+        if (surfaceNode) coveredNodeIds.add(surfaceNode.id);
+      }
+    }
+  }
+
+  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));
+        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);
+    }
+  }
+
+  return [...coveredNodeIds].sort();
+}
+
+export function buildEvidenceDetails(coveredNodeIds, graph, entry, context) {
+  const routes = new Set();
+  const requestPaths = new Set();
+  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+  for (const nodeId of coveredNodeIds) {
+    const node = nodeById.get(nodeId);
+    if (!node) continue;
+    if (node.route) routes.add(node.route);
+    if (node.path) requestPaths.add(node.path);
+  }
+  return buildEvidenceDetailsFromTargets({
+    routes: [...routes].sort(),
+    requestPaths: [...requestPaths].sort(),
+    targets: extractPlaywrightTargets(entry, context),
+  });
+}
+
+export function buildEvidenceDetailsFromTargets({ routes = [], requestPaths = [], targets = [] }) {
+  const details = {};
+  if (routes.length === 1) {
+    details.route = routes[0];
+  }
+  if (requestPaths.length > 0) {
+    details.requestPaths = [...requestPaths].sort();
+  }
+  if (targets.length > 0) {
+    details.targets = dedupeTargets(targets);
+  }
+  return Object.keys(details).length > 0 ? details : undefined;
+}
+
+export function extractPlaywrightTargets(entry, context) {
+  if (!entry || entry.framework !== "playwright" || !context?.serviceRoot) return [];
+  const absolutePath = path.join(context.serviceRoot, entry.filePath);
+  if (!fs.existsSync(absolutePath)) return [];
+  return extractPlaywrightTargetsFromContent(fs.readFileSync(absolutePath, "utf8"));
+}
+
+export function extractPlaywrightTargetsFromContent(content) {
+  const targets = [];
+
+  for (const match of content.matchAll(/\bgetByTestId\(\s*["'`]([^"'`]+)["'`]\s*\)/gu)) {
+    targets.push({
+      kind: "testId",
+      value: match[1],
+      confidence: "high",
+    });
+  }
+
+  for (const match of content.matchAll(/\blocator\(\s*["'`]\[data-testid=(?:"|')([^"'`\]]+)(?:"|')\]["'`]\s*\)/gu)) {
+    targets.push({
+      kind: "testId",
+      value: match[1],
+      confidence: "medium",
+    });
+  }
+
+  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 [];
+  const ownerDirectory = inferOwnerDirectoryFromTestFile(entry.filePath);
+  if (!ownerDirectory) return [];
+  return inferDataCapabilitiesFromOwner(ownerDirectory, context.dataCapabilities);
+}
+
+export function inferDataCapabilitiesFromOwner(ownerDirectory, dataCapabilities = []) {
+  return dataCapabilities
+    .filter((node) => node.filePath && pathMatchesOwner(node.filePath, ownerDirectory))
+    .map((node) => node.id)
+    .sort();
+}

package/lib/coverage/evidence.test.mjs

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildEvidenceDetailsFromTargets,
+  extractHttpSuiteRequestsFromContent,
+  extractPlaywrightTargetsFromContent,
+  inferDataCapabilitiesFromOwner,
+} from "./evidence.mjs";
+
+describe("coverage evidence helpers", () => {
+  it("extracts and dedupes Playwright targets from source content", () => {
+    const content = `
+      await page.getByTestId("save-button").click();
+      await page.locator('[data-testid="save-button"]').click();
+      await page.getByTestId("drawer").click();
+    `;
+
+    expect(extractPlaywrightTargetsFromContent(content)).toEqual([
+      { kind: "testId", value: "save-button", confidence: "high" },
+      { kind: "testId", value: "drawer", confidence: "high" },
+    ]);
+  });
+
+  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({
+        routes: ["/campaigns"],
+        requestPaths: ["/api/campaigns"],
+        targets: [{ kind: "testId", value: "save-button", confidence: "high" }],
+      })
+    ).toEqual({
+      route: "/campaigns",
+      requestPaths: ["/api/campaigns"],
+      targets: [{ kind: "testId", value: "save-button", confidence: "high" }],
+    });
+
+    expect(buildEvidenceDetailsFromTargets({ routes: [], requestPaths: [], targets: [] })).toBeUndefined();
+  });
+
+  it("infers DAL coverage from owner directories", () => {
+    const dataCapabilities = [
+      { id: "data_capability:src/backend/data/campaigns#saveCampaignRow", filePath: "src/backend/data/campaigns/index.ts" },
+      { id: "data_capability:src/backend/data/users#saveUserRow", filePath: "src/backend/data/users/index.ts" },
+    ];
+
+    expect(inferDataCapabilitiesFromOwner("src/backend/data/campaigns", dataCapabilities)).toEqual([
+      "data_capability:src/backend/data/campaigns#saveCampaignRow",
+    ]);
+  });
+});

package/lib/coverage/fs-walk.mjs

@@ -0,0 +1,64 @@
+import fs from "fs";
+import path from "path";
+import {
+  normalizeDiscoveryPath,
+  shouldExcludeDiscoveryPath,
+} from "../discovery/path-policy.mjs";
+import { normalizePath } from "./shared.mjs";
+import { resolveImportToSourceFile as resolveImportToSourceFileFromAst } from "./next-static-analysis.mjs";
+
+export function findNextAppRoot(serviceRoot) {
+  const candidates = [path.join(serviceRoot, "app"), path.join(serviceRoot, "src", "app")];
+  return candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) || null;
+}
+
+export function resolveServiceRoot(productDir, config) {
+  const cwd = config?.local?.cwd || ".";
+  return path.resolve(productDir, cwd);
+}
+
+export 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) {
+    const current = queue.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        const relativeDirPath = normalizeDiscoveryPath(path.relative(baseDir, absolutePath));
+        if (shouldExcludeDiscoveryPath(relativeDirPath, exclude)) continue;
+        queue.push(absolutePath);
+        continue;
+      }
+      if (entry.isFile()) {
+        results.push(absolutePath);
+      }
+    }
+  }
+  return results.sort((left, right) => left.localeCompare(right));
+}
+
+export function resolveImportToSourceFile(serviceRoot, fromFilePath, specifier) {
+  return resolveImportToSourceFileFromAst(serviceRoot, fromFilePath, specifier);
+}
+
+export function resolveSourceCandidate(basePath) {
+  const direct = [basePath, `${basePath}.ts`, `${basePath}.tsx`, `${basePath}.js`, `${basePath}.mjs`];
+  for (const candidate of direct) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+  }
+  const indexed = [
+    path.join(basePath, "index.ts"),
+    path.join(basePath, "index.tsx"),
+    path.join(basePath, "index.js"),
+    path.join(basePath, "index.mjs"),
+  ];
+  for (const candidate of indexed) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+  }
+  return null;
+}