@letsrunit/executor 0.20.0 → 0.21.1

package/README.md

@@ -42,6 +42,14 @@ Executes a given Gherkin feature on a target URL with full reporting.
 
 Uses AI to refine and improve a user-provided test suggestion.
 
+### `explain(options)`
+
+Imported from the dedicated subpath so runtime consumers that do not need local sqlite storage do not pull it into their main bundle.
+
+```ts
+import explain from '@letsrunit/executor/explain';
+```
+
 ## Testing
 
 Run tests for this package:

package/dist/chunk-PMQZSUZG.js

@@ -0,0 +1,38 @@
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url); const __filename = new URL(import.meta.url).pathname; __filename.substring(0, __filename.lastIndexOf('/'));
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+export { __commonJS, __require, __toESM };
+//# sourceMappingURL=chunk-PMQZSUZG.js.map
+//# sourceMappingURL=chunk-PMQZSUZG.js.map

package/dist/chunk-PMQZSUZG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-PMQZSUZG.js"}

package/dist/explain.d.ts

@@ -0,0 +1,30 @@
+interface ExplainOptions {
+    dbPath?: string;
+    artifactsDir?: string;
+}
+interface ExplainScenario {
+    scenarioId: string;
+    scenarioName: string;
+    featurePath: string;
+    steps: string;
+    failureMessage: string;
+    update: 'test' | 'code';
+    updateMessage: string;
+    reason: string;
+    advice: string;
+}
+interface ExplainScenarioError {
+    scenarioId: string;
+    scenarioName: string;
+    featurePath: string;
+    error: string;
+}
+interface ExplainResult {
+    hasRun: boolean;
+    totalFailed: number;
+    explanations: ExplainScenario[];
+    errors: ExplainScenarioError[];
+}
+declare function explain(options?: ExplainOptions): Promise<ExplainResult>;
+
+export { type ExplainOptions, type ExplainResult, type ExplainScenario, type ExplainScenarioError, explain as default };

package/dist/explain.js

@@ -0,0 +1,181 @@
+import { createRequire } from 'module';
+import './chunk-PMQZSUZG.js';
+import { executableScenarioIds } from '@letsrunit/gherkin';
+import { unifiedHtmlDiff } from '@letsrunit/playwright';
+import { openStore, findLastRun, findLastTest, findArtifacts } from '@letsrunit/store';
+import { statusSymbol } from '@letsrunit/utils';
+import { readFileSync } from 'fs';
+import { join, dirname, isAbsolute } from 'path';
+import { generate } from '@letsrunit/ai';
+import { z } from 'zod';
+
+createRequire(import.meta.url); const __filename = new URL(import.meta.url).pathname; __filename.substring(0, __filename.lastIndexOf('/'));
+var PROMPT = `You are analyzing a failed browser test to provide useful information to the user
+
+Classify the failure as:
+- "test" when the failed step is caused by an intentional user-visible change in the application, and the product still appears to work as expected.
+- "code" when the failed step is caused by broken or missing functionality, or when the user can no longer complete the expected flow.
+
+The advise should match the classification. If the classification is to update the test, don't advise to update the code and visa-versa.
+The advise must be a single concrete action to solve the failure without examples or alternatives.
+`;
+var ResponseSchema = z.object({
+  update: z.enum(["test", "code"]).describe('Classification: "test" if the test is outdated OR "code" if it is likely a regression'),
+  reason: z.string().describe("One short sentence describing only the observed user-visible change"),
+  advice: z.string().describe("One short imperative sentence with a single action")
+});
+async function explainFailure(input) {
+  return await generate(PROMPT, input, { model: "medium", schema: ResponseSchema });
+}
+
+// src/explain.ts
+function defaultDbPath() {
+  return join(process.cwd(), ".letsrunit", "letsrunit.db");
+}
+function resolveArtifactsDir(dbPath, artifactsDir) {
+  if (artifactsDir) return artifactsDir;
+  return join(dirname(dbPath), "artifacts");
+}
+function resolveFeaturePath(path) {
+  return isAbsolute(path) ? path : join(process.cwd(), path);
+}
+function isFailed(test) {
+  return test.failedStepIndex !== null || test.status === "failed";
+}
+function colorize(status, text) {
+  switch (status) {
+    case "success":
+    case "skipped":
+      return `\x1B[90m${text}\x1B[0m`;
+    case "failure":
+      return `\x1B[31m${text}\x1B[0m`;
+    default:
+      return text;
+  }
+}
+function renderScenarioSteps(test, failedStepIndex) {
+  return test.steps.map((step) => {
+    const status = step.index < failedStepIndex ? "success" : step.index === failedStepIndex ? "failure" : "skipped";
+    const symbol = statusSymbol(status);
+    return colorize(status, `${symbol} ${step.text}`);
+  }).join("\n");
+}
+function pickLatestHtmlFilename(filenames) {
+  const html = filenames.filter((artifact) => artifact.filename.endsWith(".html"));
+  if (html.length === 0) return null;
+  return html.at(-1)?.filename ?? null;
+}
+function asHeading(update) {
+  return update === "test" ? "Test outdated" : "Possible regression";
+}
+function buildPrompt(test, renderedSteps, failureMessage, diff) {
+  return [
+    `Feature: ${test.featureName}`,
+    `Scenario: ${test.scenarioName}`,
+    "",
+    renderedSteps,
+    "",
+    "Failure message:",
+    failureMessage,
+    "",
+    "HTML diff (baseline -> failed):",
+    diff
+  ].join("\n");
+}
+function parseFeatureIds(featureCache, featurePath) {
+  const cached = featureCache.get(featurePath);
+  if (cached) return cached;
+  const source = readFileSync(resolveFeaturePath(featurePath), "utf-8");
+  const ids = executableScenarioIds(source, featurePath);
+  featureCache.set(featurePath, ids);
+  return ids;
+}
+function createError(test, error) {
+  return {
+    scenarioId: test.scenarioId,
+    scenarioName: test.scenarioName,
+    featurePath: test.featurePath,
+    error
+  };
+}
+async function explain(options = {}) {
+  const dbPath = options.dbPath ?? defaultDbPath();
+  const artifactsDir = resolveArtifactsDir(dbPath, options.artifactsDir);
+  const db = openStore(dbPath);
+  try {
+    const run = findLastRun(db);
+    if (!run) {
+      return { hasRun: false, totalFailed: 0, explanations: [], errors: [] };
+    }
+    const featureCache = /* @__PURE__ */ new Map();
+    const failedTests = run.tests.filter((test) => isFailed(test));
+    const explanations = [];
+    const errors = [];
+    for (const test of failedTests) {
+      try {
+        if (test.failedStepIndex === null) {
+          errors.push(createError(test, "Missing failed step index for failed scenario"));
+          continue;
+        }
+        const knownScenarioIds = parseFeatureIds(featureCache, test.featurePath);
+        if (!knownScenarioIds.has(test.scenarioId)) {
+          errors.push(createError(test, "Scenario has changed in feature file since the last run"));
+          continue;
+        }
+        const failedStep = test.steps.find((step) => step.index === test.failedStepIndex);
+        if (!failedStep) {
+          errors.push(createError(test, `Failed step at index ${test.failedStepIndex} was not found`));
+          continue;
+        }
+        const baseline = findLastTest(db, test.scenarioId, "passed");
+        if (!baseline) {
+          errors.push(createError(test, "No prior successful baseline found for this scenario"));
+          continue;
+        }
+        const failedArtifacts = findArtifacts(db, test.id, failedStep.id);
+        const baselineArtifacts = findArtifacts(db, baseline.id, failedStep.id);
+        const failedHtmlFile = pickLatestHtmlFilename(failedArtifacts);
+        const baselineHtmlFile = pickLatestHtmlFilename(baselineArtifacts);
+        if (!failedHtmlFile || !baselineHtmlFile) {
+          errors.push(createError(test, "Missing HTML snapshot artifact for failed step"));
+          continue;
+        }
+        const failedHtml = readFileSync(join(artifactsDir, failedHtmlFile), "utf-8");
+        const baselineHtml = readFileSync(join(artifactsDir, baselineHtmlFile), "utf-8");
+        const diff = await unifiedHtmlDiff(
+          { html: baselineHtml, url: "about:blank" },
+          { html: failedHtml, url: "about:blank" }
+        );
+        const renderedSteps = renderScenarioSteps(test, test.failedStepIndex);
+        const failureMessage = test.error ?? "Step failed";
+        const prompt = buildPrompt(test, renderedSteps, failureMessage, diff);
+        const ai = await explainFailure(prompt);
+        explanations.push({
+          scenarioId: test.scenarioId,
+          scenarioName: test.scenarioName,
+          featurePath: test.featurePath,
+          steps: renderedSteps,
+          failureMessage,
+          update: ai.update,
+          updateMessage: asHeading(ai.update),
+          reason: ai.reason,
+          advice: ai.advice
+        });
+      } catch (error) {
+        errors.push(createError(test, error.message));
+      }
+    }
+    return {
+      hasRun: true,
+      totalFailed: failedTests.length,
+      explanations,
+      errors
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export { explain as default };
+//# sourceMappingURL=explain.js.map
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ai/explain-failure.ts","../src/explain.ts"],"names":[],"mappings":"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","file":"explain.js","sourcesContent":["import { generate } from '@letsrunit/ai';\nimport { z } from 'zod';\n\nconst PROMPT = `You are analyzing a failed browser test to provide useful information to the user\n\nClassify the failure as:\n- \"test\" when the failed step is caused by an intentional user-visible change in the application, and the product still appears to work as expected.\n- \"code\" when the failed step is caused by broken or missing functionality, or when the user can no longer complete the expected flow.\n\nThe advise should match the classification. If the classification is to update the test, don't advise to update the code and visa-versa.\nThe advise must be a single concrete action to solve the failure without examples or alternatives.\n`;\n\nconst ResponseSchema = z.object({\n  update: z\n    .enum(['test', 'code'])\n    .describe('Classification: \"test\" if the test is outdated OR \"code\" if it is likely a regression'),\n  reason: z\n    .string()\n    .describe('One short sentence describing only the observed user-visible change'),\n  advice: z.string().describe('One short imperative sentence with a single action'),\n});\n\nexport type ExplainFailureResponse = z.infer<typeof ResponseSchema>;\n\nexport async function explainFailure(input: string): Promise<ExplainFailureResponse> {\n  return await generate(PROMPT, input, { model: 'medium', schema: ResponseSchema });\n}\n","import { executableScenarioIds } from '@letsrunit/gherkin';\nimport { unifiedHtmlDiff } from '@letsrunit/playwright';\nimport { findArtifacts, findLastRun, findLastTest, type LastRunTest, openStore } from '@letsrunit/store';\nimport { statusSymbol } from '@letsrunit/utils';\nimport { readFileSync } from 'node:fs';\nimport { dirname, isAbsolute, join } from 'node:path';\nimport { explainFailure, type ExplainFailureResponse } from './ai/explain-failure';\n\nexport interface ExplainOptions {\n  dbPath?: string;\n  artifactsDir?: string;\n}\n\nexport interface ExplainScenario {\n  scenarioId: string;\n  scenarioName: string;\n  featurePath: string;\n  steps: string;\n  failureMessage: string;\n  update: 'test' | 'code';\n  updateMessage: string;\n  reason: string;\n  advice: string;\n}\n\nexport interface ExplainScenarioError {\n  scenarioId: string;\n  scenarioName: string;\n  featurePath: string;\n  error: string;\n}\n\nexport interface ExplainResult {\n  hasRun: boolean;\n  totalFailed: number;\n  explanations: ExplainScenario[];\n  errors: ExplainScenarioError[];\n}\n\nfunction defaultDbPath(): string {\n  return join(process.cwd(), '.letsrunit', 'letsrunit.db');\n}\n\nfunction resolveArtifactsDir(dbPath: string, artifactsDir?: string): string {\n  if (artifactsDir) return artifactsDir;\n  return join(dirname(dbPath), 'artifacts');\n}\n\nfunction resolveFeaturePath(path: string): string {\n  return isAbsolute(path) ? path : join(process.cwd(), path);\n}\n\nfunction isFailed(test: LastRunTest): boolean {\n  return test.failedStepIndex !== null || test.status === 'failed';\n}\n\nfunction colorize(status: string, text: string): string {\n  switch (status) {\n    case 'success':\n    case 'skipped':\n      return `\\x1b[90m${text}\\x1b[0m`;\n    case 'failure':\n      return `\\x1b[31m${text}\\x1b[0m`;\n    default:\n      return text;\n  }\n}\n\nfunction renderScenarioSteps(test: LastRunTest, failedStepIndex: number): string {\n  return test.steps\n    .map((step) => {\n      const status = step.index < failedStepIndex ? 'success' : step.index === failedStepIndex ? 'failure' : 'skipped';\n      const symbol = statusSymbol(status);\n      return colorize(status, `${symbol} ${step.text}`);\n    })\n    .join('\\n');\n}\n\nfunction pickLatestHtmlFilename(filenames: Array<{ filename: string }>): string | null {\n  const html = filenames.filter((artifact) => artifact.filename.endsWith('.html'));\n  if (html.length === 0) return null;\n  return html.at(-1)?.filename ?? null;\n}\n\nfunction asHeading(update: ExplainFailureResponse['update']): string {\n  return update === 'test' ? 'Test outdated' : 'Possible regression';\n}\n\nfunction buildPrompt(test: LastRunTest, renderedSteps: string, failureMessage: string, diff: string): string {\n  return [\n    `Feature: ${test.featureName}`,\n    `Scenario: ${test.scenarioName}`,\n    '',\n    renderedSteps,\n    '',\n    'Failure message:',\n    failureMessage,\n    '',\n    'HTML diff (baseline -> failed):',\n    diff,\n  ].join('\\n');\n}\n\nfunction parseFeatureIds(featureCache: Map<string, Set<string>>, featurePath: string): Set<string> {\n  const cached = featureCache.get(featurePath);\n  if (cached) return cached;\n\n  const source = readFileSync(resolveFeaturePath(featurePath), 'utf-8');\n  const ids = executableScenarioIds(source, featurePath);\n  featureCache.set(featurePath, ids);\n  return ids;\n}\n\nfunction createError(test: LastRunTest, error: string): ExplainScenarioError {\n  return {\n    scenarioId: test.scenarioId,\n    scenarioName: test.scenarioName,\n    featurePath: test.featurePath,\n    error,\n  };\n}\n\nexport default async function explain(options: ExplainOptions = {}): Promise<ExplainResult> {\n  const dbPath = options.dbPath ?? defaultDbPath();\n  const artifactsDir = resolveArtifactsDir(dbPath, options.artifactsDir);\n  const db = openStore(dbPath);\n\n  try {\n    const run = findLastRun(db);\n    if (!run) {\n      return { hasRun: false, totalFailed: 0, explanations: [], errors: [] };\n    }\n\n    const featureCache = new Map<string, Set<string>>();\n    const failedTests = run.tests.filter((test) => isFailed(test));\n    const explanations: ExplainScenario[] = [];\n    const errors: ExplainScenarioError[] = [];\n\n    for (const test of failedTests) {\n      try {\n        if (test.failedStepIndex === null) {\n          errors.push(createError(test, 'Missing failed step index for failed scenario'));\n          continue;\n        }\n\n        const knownScenarioIds = parseFeatureIds(featureCache, test.featurePath);\n        if (!knownScenarioIds.has(test.scenarioId)) {\n          errors.push(createError(test, 'Scenario has changed in feature file since the last run'));\n          continue;\n        }\n\n        const failedStep = test.steps.find((step) => step.index === test.failedStepIndex);\n        if (!failedStep) {\n          errors.push(createError(test, `Failed step at index ${test.failedStepIndex} was not found`));\n          continue;\n        }\n\n        const baseline = findLastTest(db, test.scenarioId, 'passed');\n        if (!baseline) {\n          errors.push(createError(test, 'No prior successful baseline found for this scenario'));\n          continue;\n        }\n\n        const failedArtifacts = findArtifacts(db, test.id, failedStep.id);\n        const baselineArtifacts = findArtifacts(db, baseline.id, failedStep.id);\n\n        const failedHtmlFile = pickLatestHtmlFilename(failedArtifacts);\n        const baselineHtmlFile = pickLatestHtmlFilename(baselineArtifacts);\n\n        if (!failedHtmlFile || !baselineHtmlFile) {\n          errors.push(createError(test, 'Missing HTML snapshot artifact for failed step'));\n          continue;\n        }\n\n        const failedHtml = readFileSync(join(artifactsDir, failedHtmlFile), 'utf-8');\n        const baselineHtml = readFileSync(join(artifactsDir, baselineHtmlFile), 'utf-8');\n\n        const diff = await unifiedHtmlDiff(\n          { html: baselineHtml, url: 'about:blank' },\n          { html: failedHtml, url: 'about:blank' },\n        );\n\n        const renderedSteps = renderScenarioSteps(test, test.failedStepIndex);\n        const failureMessage = test.error ?? 'Step failed';\n        const prompt = buildPrompt(test, renderedSteps, failureMessage, diff);\n        const ai = await explainFailure(prompt);\n\n        explanations.push({\n          scenarioId: test.scenarioId,\n          scenarioName: test.scenarioName,\n          featurePath: test.featurePath,\n          steps: renderedSteps,\n          failureMessage,\n          update: ai.update,\n          updateMessage: asHeading(ai.update),\n          reason: ai.reason,\n          advice: ai.advice,\n        });\n      } catch (error) {\n        errors.push(createError(test, (error as Error).message));\n      }\n    }\n\n    return {\n      hasRun: true,\n      totalFailed: failedTests.length,\n      explanations,\n      errors,\n    };\n  } finally {\n    db.close();\n  }\n}\n"]}

package/dist/index.d.ts

@@ -6,35 +6,6 @@ import { RequiredAndOptional } from '@letsrunit/utils';
 
 declare function refineSuggestion(suggestion: string | Pick<Feature, 'name' | 'description' | 'comments'>): Promise<Required<Pick<Feature, 'name' | 'description' | 'comments'>>>;
 
-interface ExplainOptions {
-    dbPath?: string;
-    artifactsDir?: string;
-}
-interface ExplainScenario {
-    scenarioId: string;
-    scenarioName: string;
-    featurePath: string;
-    steps: string;
-    failureMessage: string;
-    update: 'test' | 'code';
-    updateMessage: string;
-    reason: string;
-    advice: string;
-}
-interface ExplainScenarioError {
-    scenarioId: string;
-    scenarioName: string;
-    featurePath: string;
-    error: string;
-}
-interface ExplainResult {
-    hasRun: boolean;
-    totalFailed: number;
-    explanations: ExplainScenario[];
-    errors: ExplainScenarioError[];
-}
-declare function explain(options?: ExplainOptions): Promise<ExplainResult>;
-
 declare const ActionSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodString;
@@ -92,4 +63,4 @@ interface GenerateOptions {
 }
 declare function run(target: string, feature: Feature | string, opts?: GenerateOptions): Promise<Result>;
 
-export { type PreparedAction as Action, ActionSchema, type AppInfo, type Assessment, AssessmentSchema, type ExplainResult, type Result, explain, explore, generate, refineSuggestion, run };
+export { type PreparedAction as Action, ActionSchema, type AppInfo, type Assessment, AssessmentSchema, type Result, explore, generate, refineSuggestion, run };