executable-stories-formatters 0.9.0 → 0.11.0

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   AstroFormatter: () => AstroFormatter,
+  BehaviorManifestJsonFormatter: () => BehaviorManifestJsonFormatter,
   ConfluenceFormatter: () => ConfluenceFormatter,
   CucumberHtmlFormatter: () => CucumberHtmlFormatter,
   CucumberJsonFormatter: () => CucumberJsonFormatter,
@@ -51,6 +52,7 @@ __export(src_exports, {
   STORY_META_KEY: () => STORY_META_KEY,
   STORY_REPORT_SCHEMA_MAJOR: () => STORY_REPORT_SCHEMA_MAJOR,
   STORY_REPORT_SCHEMA_VERSION: () => STORY_REPORT_SCHEMA_VERSION,
+  ScenarioIndexJsonFormatter: () => ScenarioIndexJsonFormatter,
   StoryReportJsonFormatter: () => StoryReportJsonFormatter,
   adaptJestRun: () => adaptJestRun,
   adaptPlaywrightRun: () => adaptPlaywrightRun,
@@ -61,6 +63,7 @@ __export(src_exports, {
   calculateFlakiness: () => calculateFlakiness,
   calculateStability: () => calculateStability,
   canonicalizeRun: () => canonicalizeRun,
+  classifyStatusChange: () => classifyStatusChange,
   clearVersionCache: () => clearVersionCache,
   computeTestMetrics: () => computeTestMetrics,
   copyMarkdownAssets: () => copyMarkdownAssets,
@@ -72,6 +75,7 @@ __export(src_exports, {
   detectCI: () => detectCI4,
   detectPerformanceTrend: () => detectPerformanceTrend,
   diffRuns: () => diffRuns,
+  diffStoryReports: () => diffStoryReports,
   findGitDir: () => findGitDir,
   formatDuration: () => formatDuration3,
   generateRunComparison: () => generateRunComparison,
@@ -83,6 +87,7 @@ __export(src_exports, {
   hasSufficientHistory: () => hasSufficientHistory,
   isReviewableSource: () => isReviewableSource,
   isTestFile: () => isTestFile,
+  joinNameAndExt: () => joinNameAndExt,
   listScenarios: () => listScenarios,
   loadHistory: () => loadHistory,
   mergeStepResults: () => mergeStepResults,
@@ -99,29 +104,34 @@ __export(src_exports, {
   readBranchName: () => readBranchName,
   readGitSha: () => readGitSha,
   readPackageVersion: () => readPackageVersion,
+  regenerateArtifacts: () => regenerateArtifacts,
   resolveAttachment: () => resolveAttachment,
   resolveAttachments: () => resolveAttachments,
   resolveTheme: () => resolveTheme,
   resolveTraceUrl: () => resolveTraceUrl,
   rewriteAssetPaths: () => rewriteAssetPaths,
   saveHistory: () => saveHistory,
+  scenariosCoveringPaths: () => scenariosCoveringPaths,
   sendNotifications: () => sendNotifications,
   sendSlackNotification: () => sendSlackNotification,
   sendTeamsNotification: () => sendTeamsNotification,
   sendWebhookNotification: () => sendWebhookNotification,
   signBody: () => signBody,
   slugify: () => slugify,
+  startWatch: () => startWatch,
   stripAnsi: () => stripAnsi,
+  toBehaviorManifest: () => toBehaviorManifest,
   toCIInfo: () => toCIInfo,
   toRawCIInfo: () => toRawCIInfo,
+  toScenarioIndex: () => toScenarioIndex,
   toStoryReport: () => toStoryReport,
   tryGetActiveOtelContext: () => tryGetActiveOtelContext,
   updateHistory: () => updateHistory,
   validateCanonicalRun: () => validateCanonicalRun
 });
 module.exports = __toCommonJS(src_exports);
-var fs8 = require("fs");
-var path9 = __toESM(require("path"), 1);
+var fs9 = require("fs");
+var path10 = __toESM(require("path"), 1);
 var fsPromises = __toESM(require("fs/promises"), 1);
 
 // src/converters/acl/status.ts
@@ -884,6 +894,15 @@ function copyDocEntry(entry) {
         phase: entry.phase,
         ...children
       };
+    case "video":
+      return {
+        kind: "video",
+        path: entry.path,
+        ...entry.caption ? { caption: entry.caption } : {},
+        ...entry.poster ? { poster: entry.poster } : {},
+        phase: entry.phase,
+        ...children
+      };
     case "custom":
       return {
         kind: "custom",
@@ -967,6 +986,9 @@ function buildScenario(tc, featureId) {
   if (tickets && tickets.length > 0) {
     scenario.tickets = tickets.map((t) => t.url ? { id: t.id, url: t.url } : { id: t.id });
   }
+  if (tc.story.covers && tc.story.covers.length > 0) {
+    scenario.covers = [...tc.story.covers];
+  }
   return scenario;
 }
 function deriveFeatureTitle(group, relSourceFile) {
@@ -1090,6 +1112,181 @@ var StoryReportJsonFormatter = class {
   }
 };
 
+// src/formatters/scenario-index-json.ts
+var ScenarioIndexJsonFormatter = class {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      pretty: options.pretty ?? true,
+      filters: options.filters
+    };
+  }
+  toIndex(run) {
+    return toScenarioIndex(toStoryReport(run), this.options.filters);
+  }
+  format(run) {
+    const index = this.toIndex(run);
+    return this.options.pretty ? JSON.stringify(index, null, 2) : JSON.stringify(index);
+  }
+};
+function toScenarioIndex(report, filters = {}) {
+  const scenarios = report.features.flatMap(
+    (feature) => feature.scenarios.map((scenario) => toScenarioIndexItem(feature, scenario))
+  ).filter((scenario) => matchesFilters(scenario, filters));
+  return {
+    schemaVersion: "1.0",
+    runId: report.runId,
+    generatedAtMs: report.finishedAtMs,
+    summary: summarize(scenarios),
+    scenarios
+  };
+}
+function toScenarioIndexItem(feature, scenario) {
+  return {
+    id: scenario.id,
+    title: scenario.title,
+    status: scenario.status,
+    feature: feature.title,
+    sourceFile: feature.sourceFile,
+    sourceLine: scenario.sourceLine,
+    tags: scenario.tags,
+    tickets: scenario.tickets ?? [],
+    covers: scenario.covers ?? [],
+    durationMs: scenario.durationMs,
+    steps: scenario.steps.map((step) => ({
+      id: step.id,
+      index: step.index,
+      keyword: step.keyword,
+      text: step.text,
+      status: step.status,
+      durationMs: step.durationMs,
+      errorMessage: step.errorMessage,
+      docKinds: step.docEntries.map((entry) => entry.kind)
+    })),
+    docKinds: scenario.docEntries.map((entry) => entry.kind),
+    error: scenario.errorMessage ? { message: scenario.errorMessage, stack: scenario.errorStack } : void 0
+  };
+}
+function matchesFilters(scenario, filters) {
+  if (filters.statuses?.length && !filters.statuses.includes(scenario.status)) {
+    return false;
+  }
+  if (filters.tags?.length && !filters.tags.some((tag) => scenario.tags.includes(tag))) {
+    return false;
+  }
+  if (filters.sourceFiles?.length && !filters.sourceFiles.some((sourceFile) => scenario.sourceFile.includes(sourceFile))) {
+    return false;
+  }
+  return true;
+}
+function summarize(scenarios) {
+  return {
+    total: scenarios.length,
+    passed: scenarios.filter((scenario) => scenario.status === "passed").length,
+    failed: scenarios.filter((scenario) => scenario.status === "failed").length,
+    skipped: scenarios.filter((scenario) => scenario.status === "skipped").length,
+    pending: scenarios.filter((scenario) => scenario.status === "pending").length,
+    durationMs: scenarios.reduce((total, scenario) => total + scenario.durationMs, 0)
+  };
+}
+
+// src/formatters/behavior-manifest-json.ts
+var BehaviorManifestJsonFormatter = class {
+  pretty;
+  constructor(options = {}) {
+    this.pretty = options.pretty ?? true;
+  }
+  toManifest(run) {
+    return toBehaviorManifest(toStoryReport(run));
+  }
+  format(run) {
+    const manifest = this.toManifest(run);
+    return this.pretty ? JSON.stringify(manifest, null, 2) : JSON.stringify(manifest);
+  }
+};
+function toBehaviorManifest(report) {
+  const index = toScenarioIndex(report);
+  const bySource = /* @__PURE__ */ new Map();
+  const byTag = /* @__PURE__ */ new Map();
+  const docKinds = /* @__PURE__ */ new Set();
+  const debuggerIssues = [];
+  for (const scenario of index.scenarios) {
+    const source = bySource.get(scenario.sourceFile) ?? {
+      path: scenario.sourceFile,
+      scenarioCount: 0,
+      failed: 0,
+      tags: []
+    };
+    source.scenarioCount += 1;
+    if (scenario.status === "failed") source.failed += 1;
+    source.tags = [.../* @__PURE__ */ new Set([...source.tags, ...scenario.tags])].sort();
+    bySource.set(scenario.sourceFile, source);
+    for (const tag of scenario.tags) {
+      const tagEntry = byTag.get(tag) ?? { name: tag, scenarioCount: 0 };
+      tagEntry.scenarioCount += 1;
+      byTag.set(tag, tagEntry);
+    }
+    for (const kind of scenario.docKinds) docKinds.add(kind);
+    for (const step of scenario.steps) {
+      for (const kind of step.docKinds) docKinds.add(kind);
+    }
+    if (!scenarioHasDocs(scenario)) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-docs",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario has no doc entries."
+      });
+    }
+    if (scenario.tags.length === 0) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-tags",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario has no tags."
+      });
+    }
+    if (scenario.covers.length === 0) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-covers",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario declares no covers (product-code paths), so code\u2192scenario lookup cannot find it."
+      });
+    }
+    if (scenario.sourceLine === void 0) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-source-line",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario has no source line."
+      });
+    }
+  }
+  const scenariosWithDocs = index.scenarios.filter(scenarioHasDocs).length;
+  return {
+    schemaVersion: "1.0",
+    runId: report.runId,
+    generatedAtMs: report.finishedAtMs,
+    summary: index.summary,
+    sourceFiles: [...bySource.values()].sort((a, b) => a.path.localeCompare(b.path)),
+    tags: [...byTag.values()].sort((a, b) => a.name.localeCompare(b.name)),
+    docCoverage: {
+      scenariosWithDocs,
+      scenariosWithoutDocs: index.scenarios.length - scenariosWithDocs,
+      docKinds: [...docKinds].sort()
+    },
+    debugger: debuggerIssues
+  };
+}
+function scenarioHasDocs(scenario) {
+  return scenario.docKinds.length > 0 || scenario.steps.some((step) => step.docKinds.length > 0);
+}
+
 // src/formatters/html/renderers/index.ts
 var fs2 = __toESM(require("fs"), 1);
 var path3 = __toESM(require("path"), 1);
@@ -13867,6 +14064,23 @@ function renderDocScreenshot(entry, deps) {
   ${entry.alt ? `<div class="doc-screenshot-caption">${deps.escapeHtml(entry.alt)}</div>` : ""}
 </div>`;
 }
+function renderDocVideo(entry, deps) {
+  const isRemote = /^(?:https?:|data:)/i.test(entry.path);
+  const isAbsoluteFsPath = !isRemote && /^(?:[/\\]|[A-Za-z]:[/\\])/.test(entry.path);
+  const captionHtml = entry.caption ? `<div class="doc-video-caption">${deps.escapeHtml(entry.caption)}</div>` : "";
+  if ((deps.embedScreenshots ?? true) && isAbsoluteFsPath) {
+    return `<div class="doc-video doc-video-missing">
+  <div class="doc-video-missing-label">Video unavailable</div>
+  <div class="doc-video-missing-path">${deps.escapeHtml(entry.path)}</div>
+  ${captionHtml}
+</div>`;
+  }
+  const poster = entry.poster ? ` poster="${deps.escapeHtml(entry.poster)}"` : "";
+  return `<div class="doc-video">
+  <video class="doc-video-player" controls preload="metadata"${poster} src="${deps.escapeHtml(entry.path)}"></video>
+  ${captionHtml}
+</div>`;
+}
 function renderDocCustom(entry, deps) {
   if (entry.type === "visual" && entry.data && typeof entry.data === "object") {
     const data = entry.data;
@@ -13920,6 +14134,9 @@ function renderDocEntry(entry, deps) {
     case "screenshot":
       html = renderDocScreenshot(entry, deps);
       break;
+    case "video":
+      html = renderDocVideo(entry, deps);
+      break;
     case "custom":
       html = renderDocCustom(entry, deps);
       break;
@@ -15246,6 +15463,19 @@ var MarkdownFormatter = class {
       case "screenshot":
         lines.push(`${indent}![${entry.alt ?? "Screenshot"}](${entry.path})`);
         break;
+      case "video": {
+        const poster = entry.poster ? ` poster="${entry.poster}"` : "";
+        lines.push(`${indent}`);
+        lines.push(`${indent}<video controls preload="metadata"${poster} class="doc-video">`);
+        lines.push(`${indent}  <source src="${entry.path}" />`);
+        lines.push(`${indent}</video>`);
+        if (entry.caption) {
+          lines.push(`${indent}`);
+          lines.push(`${indent}*${entry.caption}*`);
+        }
+        lines.push(`${indent}`);
+        break;
+      }
       case "custom":
         if (entry.type === "visual" && entry.data && typeof entry.data === "object") {
           const data = entry.data;
@@ -15958,8 +16188,8 @@ function extractDocAttachments(step) {
   }
   return attachments;
 }
-function guessMediaType(path10) {
-  const lower = path10.toLowerCase();
+function guessMediaType(path11) {
+  const lower = path11.toLowerCase();
   if (lower.endsWith(".png")) return "image/png";
   if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
   if (lower.endsWith(".gif")) return "image/gif";
@@ -16100,11 +16330,11 @@ var CucumberHtmlFormatter = class {
     for (const envelope of envelopes) {
       const accepted = htmlStream.write(envelope);
       if (!accepted) {
-        await new Promise((resolve7) => htmlStream.once("drain", resolve7));
+        await new Promise((resolve8) => htmlStream.once("drain", resolve8));
       }
     }
-    await new Promise((resolve7, reject) => {
-      collector.on("finish", resolve7);
+    await new Promise((resolve8, reject) => {
+      collector.on("finish", resolve8);
       collector.on("error", reject);
       htmlStream.end();
     });
@@ -16405,6 +16635,8 @@ function formatDocEntry(doc) {
       return `${escapeHtml2(doc.title ?? "mermaid diagram")}: <code>${escapeHtml2(doc.code)}</code>`;
     case "screenshot":
       return `${doc.alt ? `${escapeHtml2(doc.alt)}: ` : ""}${escapeHtml2(doc.path)}`;
+    case "video":
+      return `${doc.caption ? `${escapeHtml2(doc.caption)}: ` : ""}${escapeHtml2(doc.path)}`;
     case "custom":
       return `${escapeHtml2(doc.type)}: ${escapeHtml2(JSON.stringify(doc.data))}`;
   }
@@ -16861,6 +17093,8 @@ function formatDocEntry2(doc) {
       return `${doc.title ?? "mermaid diagram"}: \`${doc.code}\``;
     case "screenshot":
       return `${doc.alt ? `${doc.alt}: ` : ""}${doc.path}`;
+    case "video":
+      return `${doc.caption ? `${doc.caption}: ` : ""}${doc.path}`;
     case "custom":
       return `${doc.type}: ${JSON.stringify(doc.data)}`;
   }
@@ -17106,19 +17340,35 @@ function replaceAssetRef(html, original, replacement) {
   return html;
 }
 
+// src/utils/source-file.ts
+function cleanTestStem(fileName) {
+  const base = fileName.split(/[\\/]/).pop() ?? fileName;
+  const stripped = base.replace(/\.(story\.)?(test|spec|cy)\.[cm]?[jt]sx?$/i, "");
+  if (stripped !== base) return stripped;
+  return base.replace(/\.[^.]+$/, "");
+}
+function humanizeSourceFile(fileName) {
+  return cleanTestStem(fileName).split(/[-_.\s]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+
 // src/formatters/astro.ts
 var AstroFormatter = class _AstroFormatter {
   markdownFormatter;
   title;
+  perFileTitle;
   constructor(options = {}) {
     this.title = options.markdown?.title ?? "User Stories";
+    this.perFileTitle = options.perFileTitle ?? false;
     this.markdownFormatter = new MarkdownFormatter({
       ...options.markdown,
       title: this.title,
       stepStyle: "gherkin",
       includeFrontMatter: false,
       includeSummaryTable: false,
-      includeMetadata: false
+      includeMetadata: false,
+      // A per-file page is one file already — group by suite/describe so the
+      // body shows clean section headings, not the redundant source path.
+      groupBy: this.perFileTitle ? "suite" : options.markdown?.groupBy ?? "file"
     });
   }
   format(run) {
@@ -17128,13 +17378,31 @@ var AstroFormatter = class _AstroFormatter {
     return `${frontmatter}
 ${body}`;
   }
+  /**
+   * Title for the page. A per-file page (one source file — i.e. colocated mode)
+   * is titled by its suite/describe name, falling back to a humanized filename,
+   * so the docs nav reads "Convert Currency" not "User Stories" six times over.
+   * Multi-file (aggregated) pages keep the configured title.
+   */
+  deriveTitle(run) {
+    if (!this.perFileTitle) return this.title;
+    const sourceFiles = new Set(
+      run.testCases.map((tc) => tc.sourceFile).filter((f) => f && f !== "unknown")
+    );
+    if (sourceFiles.size !== 1) return this.title;
+    const suites = new Set(
+      run.testCases.map((tc) => tc.titlePath?.[0]).filter((s) => Boolean(s))
+    );
+    if (suites.size === 1) return [...suites][0];
+    return humanizeSourceFile([...sourceFiles][0]) || this.title;
+  }
   buildFrontmatter(run) {
     const badge = _AstroFormatter.computeBadge(run.testCases);
     const count = run.testCases.length;
     const description = `${count} scenario${count !== 1 ? "s" : ""} \u2014 ${badge.text.toLowerCase()}`;
     const lines = [
       "---",
-      `title: ${this.title}`,
+      `title: ${yamlScalar(this.deriveTitle(run))}`,
       `description: ${description}`,
       "sidebar:",
       "  badge:",
@@ -17152,6 +17420,12 @@ ${body}`;
     return { text: "Passed", variant: "success" };
   }
 };
+function yamlScalar(value) {
+  if (/[:#[\]{}&*!|>'"%@`]|^[\s-]|\s$/.test(value)) {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  return value;
+}
 
 // src/formatters/confluence.ts
 var ConfluenceFormatter = class {
@@ -17428,6 +17702,15 @@ ${tc.errorStack}` : "");
           ])
         );
         break;
+      case "video":
+        content.push(
+          paragraph([
+            text(entry.caption ?? "Video", strong()),
+            text(": "),
+            link(entry.path, entry.path)
+          ])
+        );
+        break;
       case "custom":
         content.push(paragraph([text(`[${entry.type}]`, strong())]));
         content.push(codeBlock(JSON.stringify(entry.data ?? null, null, 2), "json"));
@@ -17597,6 +17880,13 @@ function scanMarkdownAssets(markdown) {
       found.add(src);
     }
   }
+  const posterRe = /<video[^>]+\bposter=["']([^"']+)["'][^>]*>/gi;
+  while ((match = posterRe.exec(stripped)) !== null) {
+    const src = match[1].trim();
+    if (isLocalPath(src)) {
+      found.add(src);
+    }
+  }
   return Array.from(found);
 }
 function splitByCode(markdown) {
@@ -17647,6 +17937,19 @@ function rewriteProseSegment(prose, assetsBaseUrl, pathMap) {
       return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
     }
   );
+  result = result.replace(
+    /(<video[^>]+\bposter=["'])([^"']+)(["'][^>]*>)/gi,
+    (full, pre, src, post) => {
+      const trimmed = src.trim();
+      if (!isLocalPath(trimmed)) return full;
+      if (pathMap) {
+        const mapped = pathMap.get(trimmed);
+        if (mapped === void 0) return full;
+        return `${pre}${assetsBaseUrl}/${mapped}${post}`;
+      }
+      return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
+    }
+  );
   return result;
 }
 function rewriteAssetPaths(markdown, assetsBaseUrl, pathMap) {
@@ -18093,6 +18396,184 @@ ${result.errors.join("\n")}`);
   }
 }
 
+// src/coverage-index.ts
+function normalizePath(path11) {
+  return path11.replace(/^\.\//, "");
+}
+function scenariosCoveringPaths(index, paths) {
+  const queries = paths.map(normalizePath);
+  return index.scenarios.filter(
+    (scenario) => scenario.covers.some(
+      (glob) => queries.some((path11) => matchesPattern(normalizePath(glob), path11))
+    )
+  );
+}
+
+// src/watch.ts
+var fs6 = __toESM(require("fs"), 1);
+var path7 = __toESM(require("path"), 1);
+
+// src/converters/synthesize.ts
+var KEYWORD_MAP = {
+  given: "Given",
+  when: "When",
+  then: "Then",
+  and: "And",
+  but: "But"
+};
+function normalizeKeyword(keyword) {
+  return KEYWORD_MAP[keyword.toLowerCase()] ?? keyword;
+}
+function normalizeStepKeywords(steps) {
+  return steps.map((step) => ({
+    ...step,
+    keyword: normalizeKeyword(step.keyword)
+  }));
+}
+function deriveScenarioName(tc) {
+  if (tc.title) return tc.title;
+  if (tc.titlePath && tc.titlePath.length > 0) {
+    return tc.titlePath[tc.titlePath.length - 1];
+  }
+  return "Untitled";
+}
+function synthesizeStories(raw) {
+  return {
+    ...raw,
+    testCases: raw.testCases.map(synthesizeTestCase)
+  };
+}
+function synthesizeTestCase(tc) {
+  if (tc.story == null) {
+    const scenario = deriveScenarioName(tc);
+    return {
+      ...tc,
+      story: {
+        scenario,
+        steps: [{ keyword: "Then", text: scenario }]
+      }
+    };
+  }
+  const steps = tc.story.steps;
+  if (!steps || steps.length === 0) {
+    return {
+      ...tc,
+      story: {
+        ...tc.story,
+        steps: [{ keyword: "Then", text: tc.story.scenario }]
+      }
+    };
+  }
+  return {
+    ...tc,
+    story: {
+      ...tc.story,
+      steps: normalizeStepKeywords(steps)
+    }
+  };
+}
+
+// src/watch.ts
+function toRun(data, inputType, synthesize) {
+  if (inputType === "canonical") return data;
+  let raw = data;
+  if (synthesize) raw = synthesizeStories(raw);
+  return canonicalizeRun(raw);
+}
+async function regenerateArtifacts(options, deps = {}) {
+  const read = deps.readFile ?? ((filePath) => fs6.readFileSync(filePath, "utf8"));
+  const data = JSON.parse(read(path7.resolve(options.input)));
+  const run = toRun(data, options.inputType ?? "raw", options.synthesize !== false);
+  const generator = new ReportGenerator({
+    formats: options.formats,
+    outputDir: options.outputDir,
+    outputName: options.outputName
+  });
+  const result = await generator.generate(run);
+  return [...result.values()].flat();
+}
+function startWatch(options, deps = {}) {
+  const log = deps.log ?? ((message) => console.log(message));
+  const regenerate = deps.regenerate ?? ((input) => regenerateArtifacts({ ...options, input }, deps));
+  const watchFn = deps.watch ?? ((filePath, listener) => fs6.watch(filePath, listener));
+  const debounceMs = options.debounceMs ?? 150;
+  let timer;
+  let running = false;
+  let pending = false;
+  const run = async () => {
+    if (running) {
+      pending = true;
+      return;
+    }
+    running = true;
+    try {
+      const files = await regenerate(options.input);
+      log(`Regenerated ${files.length} artifact file(s) from ${options.input}`);
+    } catch (error) {
+      log(`Watch regeneration failed: ${error.message}`);
+    } finally {
+      running = false;
+      if (pending) {
+        pending = false;
+        trigger();
+      }
+    }
+  };
+  const trigger = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => void run(), debounceMs);
+  };
+  trigger();
+  const watcher = watchFn(path7.resolve(options.input), trigger);
+  return {
+    close: () => {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    }
+  };
+}
+
+// src/behavior-diff.ts
+function classifyStatusChange(baseline, current) {
+  if (baseline === void 0) return "added";
+  if (current === void 0) return "removed";
+  if (baseline === current) return "unchanged";
+  if (baseline === "passed" && current === "failed") return "regressed";
+  if (baseline === "failed" && current === "passed") return "fixed";
+  return "changed";
+}
+function scenarioMap(report) {
+  const map = /* @__PURE__ */ new Map();
+  for (const feature of report.features) {
+    for (const scenario of feature.scenarios) {
+      map.set(scenario.id, { scenario, sourceFile: feature.sourceFile });
+    }
+  }
+  return map;
+}
+function diffStoryReports(baseline, current) {
+  const base = scenarioMap(baseline);
+  const curr = scenarioMap(current);
+  const ids = [.../* @__PURE__ */ new Set([...base.keys(), ...curr.keys()])];
+  const scenarios = ids.map((id) => {
+    const b = base.get(id);
+    const c = curr.get(id);
+    const kind = classifyStatusChange(b?.scenario.status, c?.scenario.status);
+    const meta = c ?? b;
+    return {
+      id,
+      title: meta.scenario.title,
+      sourceFile: meta.sourceFile,
+      kind,
+      baselineStatus: b?.scenario.status,
+      currentStatus: c?.scenario.status
+    };
+  });
+  const summary = { added: 0, removed: 0, regressed: 0, fixed: 0, changed: 0, unchanged: 0 };
+  for (const s of scenarios) summary[s.kind] += 1;
+  return { schemaVersion: "1.0", summary, scenarios };
+}
+
 // src/publishers/confluence.ts
 function parseAdf(adf) {
   let parsed;
@@ -18688,27 +19169,27 @@ function pickleStepArgumentToDocs(ps) {
 }
 
 // src/utils/git-info.ts
-var fs6 = __toESM(require("fs"), 1);
-var path7 = __toESM(require("path"), 1);
+var fs7 = __toESM(require("fs"), 1);
+var path8 = __toESM(require("path"), 1);
 function readGitSha(cwd = process.cwd()) {
   const envSha = process.env.GITHUB_SHA || process.env.GIT_COMMIT || process.env.CI_COMMIT_SHA;
   if (envSha) return envSha;
   const gitDir = findGitDir(cwd);
   if (!gitDir) return void 0;
   try {
-    const headPath = path7.join(gitDir, "HEAD");
-    const head = fs6.readFileSync(headPath, "utf8").trim();
+    const headPath = path8.join(gitDir, "HEAD");
+    const head = fs7.readFileSync(headPath, "utf8").trim();
     if (!head.startsWith("ref:")) {
       return head;
     }
     const refPath = head.replace("ref:", "").trim();
-    const refFile = path7.join(gitDir, refPath);
-    if (fs6.existsSync(refFile)) {
-      return fs6.readFileSync(refFile, "utf8").trim();
+    const refFile = path8.join(gitDir, refPath);
+    if (fs7.existsSync(refFile)) {
+      return fs7.readFileSync(refFile, "utf8").trim();
     }
-    const packedRefs = path7.join(gitDir, "packed-refs");
-    if (fs6.existsSync(packedRefs)) {
-      const content = fs6.readFileSync(packedRefs, "utf8");
+    const packedRefs = path8.join(gitDir, "packed-refs");
+    if (fs7.existsSync(packedRefs)) {
+      const content = fs7.readFileSync(packedRefs, "utf8");
       for (const line of content.split("\n")) {
         if (!line || line.startsWith("#") || line.startsWith("^")) continue;
         const [sha, ref] = line.split(" ");
@@ -18723,19 +19204,19 @@ function readGitSha(cwd = process.cwd()) {
 function findGitDir(start) {
   let current = start;
   while (true) {
-    const candidate = path7.join(current, ".git");
-    if (fs6.existsSync(candidate)) {
-      const stat = fs6.statSync(candidate);
+    const candidate = path8.join(current, ".git");
+    if (fs7.existsSync(candidate)) {
+      const stat = fs7.statSync(candidate);
       if (stat.isFile()) {
-        const content = fs6.readFileSync(candidate, "utf8").trim();
+        const content = fs7.readFileSync(candidate, "utf8").trim();
         const match = content.match(/^gitdir: (.+)$/);
         if (match) {
-          return path7.resolve(current, match[1]);
+          return path8.resolve(current, match[1]);
         }
       }
       return candidate;
     }
-    const parent = path7.dirname(current);
+    const parent = path8.dirname(current);
     if (parent === current) return void 0;
     current = parent;
   }
@@ -18746,8 +19227,8 @@ function readBranchName(cwd = process.cwd()) {
   const gitDir = findGitDir(cwd);
   if (!gitDir) return void 0;
   try {
-    const headPath = path7.join(gitDir, "HEAD");
-    const head = fs6.readFileSync(headPath, "utf8").trim();
+    const headPath = path8.join(gitDir, "HEAD");
+    const head = fs7.readFileSync(headPath, "utf8").trim();
     if (head.startsWith("ref:")) {
       const refPath = head.replace("ref:", "").trim();
       const match = refPath.match(/^refs\/heads\/(.+)$/);
@@ -18784,8 +19265,8 @@ function nanosecondsToMs(ns) {
 }
 
 // src/utils/metadata.ts
-var fs7 = __toESM(require("fs"), 1);
-var path8 = __toESM(require("path"), 1);
+var fs8 = __toESM(require("fs"), 1);
+var path9 = __toESM(require("path"), 1);
 var versionCache = /* @__PURE__ */ new Map();
 function readPackageVersion(root) {
   if (versionCache.has(root)) {
@@ -18796,18 +19277,18 @@ function readPackageVersion(root) {
   return version;
 }
 function findPackageVersion(startDir) {
-  let current = path8.resolve(startDir);
+  let current = path9.resolve(startDir);
   while (true) {
-    const pkgPath = path8.join(current, "package.json");
+    const pkgPath = path9.join(current, "package.json");
     try {
-      if (fs7.existsSync(pkgPath)) {
-        const raw = fs7.readFileSync(pkgPath, "utf8");
+      if (fs8.existsSync(pkgPath)) {
+        const raw = fs8.readFileSync(pkgPath, "utf8");
         const parsed = JSON.parse(raw);
         return parsed.version;
       }
     } catch {
     }
-    const parent = path8.dirname(current);
+    const parent = path9.dirname(current);
     if (parent === current) {
       return void 0;
     }
@@ -19678,12 +20159,22 @@ function listScenarios(args, _deps) {
   const { testCases, format } = args;
   if (format === "json") {
     const items = testCases.map((tc) => ({
+      id: tc.id,
       scenario: tc.story.scenario,
       status: tc.status,
       sourceFile: tc.sourceFile,
       sourceLine: tc.sourceLine,
+      suitePath: tc.story.suitePath ?? tc.titlePath.slice(0, -1),
       tags: tc.tags,
-      id: tc.id
+      tickets: tc.story.tickets ?? [],
+      covers: tc.story.covers ?? [],
+      durationMs: tc.durationMs,
+      error: tc.errorMessage ? {
+        message: tc.errorMessage,
+        stack: tc.errorStack
+      } : void 0,
+      steps: tc.story.steps.map((step, index) => toScenarioStep(step, index, tc)),
+      docKinds: collectDocKinds(tc)
     }));
     return JSON.stringify(items, null, 2);
   }
@@ -19756,6 +20247,34 @@ function listScenarios(args, _deps) {
   ];
   return lines.join("\n");
 }
+function toScenarioStep(step, index, testCase) {
+  const result = testCase.stepResults.find(
+    (candidate) => candidate.index === index || candidate.stepId === step.id
+  );
+  return {
+    id: step.id,
+    index,
+    keyword: step.keyword,
+    text: step.text,
+    status: result?.status ?? testCase.status,
+    durationMs: result?.durationMs ?? step.durationMs ?? 0,
+    errorMessage: result?.errorMessage,
+    mode: step.mode,
+    docKinds: (step.docs ?? []).map((doc) => doc.kind)
+  };
+}
+function collectDocKinds(testCase) {
+  const kinds = /* @__PURE__ */ new Set();
+  for (const doc of testCase.story.docs ?? []) {
+    kinds.add(doc.kind);
+  }
+  for (const step of testCase.story.steps) {
+    for (const doc of step.docs ?? []) {
+      kinds.add(doc.kind);
+    }
+  }
+  return [...kinds].sort();
+}
 
 // src/review/conventions.ts
 var CHANGE_TAG_PREFIX = "change:";
@@ -19803,18 +20322,18 @@ function deriveChangeType(tags) {
   }
   return "unknown";
 }
-function extensionOf(path10) {
-  const base = path10.split("/").pop() ?? path10;
+function extensionOf(path11) {
+  const base = path11.split("/").pop() ?? path11;
   const dot = base.lastIndexOf(".");
   return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
 }
-function isTestFile(path10) {
-  return TEST_INFIX.test(path10);
+function isTestFile(path11) {
+  return TEST_INFIX.test(path11);
 }
-function isReviewableSource(path10) {
-  if (isTestFile(path10)) return false;
-  if (path10.endsWith(".d.ts")) return false;
-  return CODE_EXTENSIONS.has(extensionOf(path10));
+function isReviewableSource(path11) {
+  if (isTestFile(path11)) return false;
+  if (path11.endsWith(".d.ts")) return false;
+  return CODE_EXTENSIONS.has(extensionOf(path11));
 }
 function testBaseKey(testFile) {
   return testFile.replace(TEST_INFIX, "");
@@ -19918,7 +20437,7 @@ function toClaim(testCase, changedSourcePaths) {
   const { strength, reasons } = gradeEvidence(testCase, audience);
   const key = testBaseKey(testCase.sourceFile);
   const coversFiles = changedSourcePaths.filter(
-    (path10) => sourceBaseKey(path10) === key
+    (path11) => sourceBaseKey(path11) === key
   );
   return {
     id: testCase.id,
@@ -20451,6 +20970,7 @@ applyTheme(getEffectiveTheme());` : "";
 // src/index.ts
 var FORMAT_EXTENSIONS = {
   astro: ".md",
+  "behavior-manifest-json": ".behavior-manifest.json",
   markdown: ".md",
   html: ".html",
   "cucumber-html": ".cucumber.html",
@@ -20458,8 +20978,13 @@ var FORMAT_EXTENSIONS = {
   "cucumber-json": ".cucumber.json",
   "cucumber-messages": ".ndjson",
   confluence: ".adf.json",
+  "scenario-index-json": ".scenarios-index.json",
   "story-report-json": ".story-report.json"
 };
+function joinNameAndExt(name, ext) {
+  const stutter = `.${name}.`;
+  return ext.startsWith(stutter) ? `${name}.${ext.slice(stutter.length)}` : `${name}${ext}`;
+}
 var TEST_EXTENSIONS = [
   ".test.ts",
   ".test.tsx",
@@ -20485,11 +21010,11 @@ function computeOutputPath(sourceFile, format, mode, colocatedStyle, baseOutputD
   const ext = FORMAT_EXTENSIONS[format];
   const effectiveName = outputName + (outputNameSuffix ?? "");
   if (mode === "aggregated") {
-    return toPosix(path9.join(baseOutputDir, `${effectiveName}${ext}`));
+    return toPosix(path10.join(baseOutputDir, joinNameAndExt(effectiveName, ext)));
   }
   const normalizedSource = toPosix(sourceFile);
-  const dirOfSource = path9.posix.dirname(normalizedSource);
-  let baseName = path9.posix.basename(normalizedSource);
+  const dirOfSource = path10.posix.dirname(normalizedSource);
+  let baseName = path10.posix.basename(normalizedSource);
   for (const testExt of TEST_EXTENSIONS) {
     if (baseName.endsWith(testExt)) {
       baseName = baseName.slice(0, -testExt.length);
@@ -20498,9 +21023,12 @@ function computeOutputPath(sourceFile, format, mode, colocatedStyle, baseOutputD
   }
   const fileName = `${baseName}.${effectiveName}${ext}`;
   if (colocatedStyle === "adjacent") {
-    return toPosix(path9.posix.join(dirOfSource, fileName));
+    return toPosix(path10.posix.join(dirOfSource, fileName));
   }
-  return toPosix(path9.posix.join(baseOutputDir, dirOfSource, fileName));
+  if (colocatedStyle === "flat") {
+    return toPosix(path10.posix.join(baseOutputDir, `${cleanTestStem(normalizedSource)}${ext}`));
+  }
+  return toPosix(path10.posix.join(baseOutputDir, dirOfSource, fileName));
 }
 function groupTestCasesByOutput(testCases, format, options, logger, outputNameSuffix) {
   const groups = /* @__PURE__ */ new Map();
@@ -20586,6 +21114,12 @@ var ReportGenerator = class {
       storyReportJson: {
         pretty: options.storyReportJson?.pretty ?? true
       },
+      scenarioIndexJson: {
+        pretty: options.scenarioIndexJson?.pretty ?? true
+      },
+      behaviorManifestJson: {
+        pretty: options.behaviorManifestJson?.pretty ?? true
+      },
       cucumberMessages: {
         uriStrategy: options.cucumberMessages?.uriStrategy ?? "sourceFile",
         includeSynthetics: options.cucumberMessages?.includeSynthetics ?? true,
@@ -20701,8 +21235,8 @@ var ReportGenerator = class {
       if (astroPaths) {
         for (const mdPath of astroPaths) {
           const content = await fsPromises.readFile(mdPath, "utf8");
-          const mdDir = path9.dirname(mdPath);
-          const assetsDir = path9.resolve(this.options.astro.assetsDir);
+          const mdDir = path10.dirname(mdPath);
+          const assetsDir = path10.resolve(this.options.astro.assetsDir);
           const result = copyMarkdownAssets({
             markdown: content,
             markdownDir: mdDir,
@@ -20733,9 +21267,9 @@ var ReportGenerator = class {
     if (groups.size === 0 && this.options.output.mode === "aggregated") {
       const ext = FORMAT_EXTENSIONS[format];
       const effectiveName = this.options.outputName + (outputNameSuffix ?? "");
-      const outputPath = toPosix(path9.join(this.options.outputDir, `${effectiveName}${ext}`));
+      const outputPath = toPosix(path10.join(this.options.outputDir, joinNameAndExt(effectiveName, ext)));
       const content = await this.formatContent(run, format);
-      const dir = path9.dirname(outputPath);
+      const dir = path10.dirname(outputPath);
       await fsPromises.mkdir(dir, { recursive: true });
       await this.deps.writeFile(outputPath, content);
       return [outputPath];
@@ -20747,7 +21281,7 @@ var ReportGenerator = class {
         testCases
       };
       const content = await this.formatContent(groupRun, format);
-      const dir = path9.dirname(outputPath);
+      const dir = path10.dirname(outputPath);
       await fsPromises.mkdir(dir, { recursive: true });
       await this.deps.writeFile(outputPath, content);
       writtenPaths.push(outputPath);
@@ -20813,6 +21347,8 @@ var ReportGenerator = class {
       case "astro": {
         const formatter = new AstroFormatter({
           assetsBaseUrl: this.options.astro.assetsBaseUrl,
+          // Colocated = one page per file, so title each by its own suite/file.
+          perFileTitle: this.options.output.mode === "colocated",
           markdown: this.options.astro.markdown
         });
         return formatter.format(run);
@@ -20860,6 +21396,18 @@ var ReportGenerator = class {
         });
         return formatter.format(run);
       }
+      case "scenario-index-json": {
+        const formatter = new ScenarioIndexJsonFormatter({
+          pretty: this.options.scenarioIndexJson.pretty
+        });
+        return formatter.format(run);
+      }
+      case "behavior-manifest-json": {
+        const formatter = new BehaviorManifestJsonFormatter({
+          pretty: this.options.behaviorManifestJson.pretty
+        });
+        return formatter.format(run);
+      }
       default:
         throw new Error(`Unknown format: ${format}`);
     }
@@ -20876,7 +21424,7 @@ async function generateRunComparison(args) {
   await fsPromises.mkdir(outputDir, { recursive: true });
   for (const format of args.formats) {
     const ext = format === "html" ? ".html" : ".md";
-    const outputPath = toPosix(path9.join(outputDir, `${outputName}${ext}`));
+    const outputPath = toPosix(path10.join(outputDir, `${outputName}${ext}`));
     const content = format === "html" ? new RunDiffHtmlFormatter({ title: args.title }).format(diff) : new RunDiffMarkdownFormatter({ title: args.title }).format(diff);
     await fsPromises.writeFile(outputPath, content, "utf8");
     files.push(outputPath);
@@ -20898,6 +21446,7 @@ function normalizePlaywrightResults(testResults, adapterOptions, canonicalizeOpt
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AstroFormatter,
+  BehaviorManifestJsonFormatter,
   ConfluenceFormatter,
   CucumberHtmlFormatter,
   CucumberJsonFormatter,
@@ -20918,6 +21467,7 @@ function normalizePlaywrightResults(testResults, adapterOptions, canonicalizeOpt
   STORY_META_KEY,
   STORY_REPORT_SCHEMA_MAJOR,
   STORY_REPORT_SCHEMA_VERSION,
+  ScenarioIndexJsonFormatter,
   StoryReportJsonFormatter,
   adaptJestRun,
   adaptPlaywrightRun,
@@ -20928,6 +21478,7 @@ function normalizePlaywrightResults(testResults, adapterOptions, canonicalizeOpt
   calculateFlakiness,
   calculateStability,
   canonicalizeRun,
+  classifyStatusChange,
   clearVersionCache,
   computeTestMetrics,
   copyMarkdownAssets,
@@ -20939,6 +21490,7 @@ function normalizePlaywrightResults(testResults, adapterOptions, canonicalizeOpt
   detectCI,
   detectPerformanceTrend,
   diffRuns,
+  diffStoryReports,
   findGitDir,
   formatDuration,
   generateRunComparison,
@@ -20950,6 +21502,7 @@ function normalizePlaywrightResults(testResults, adapterOptions, canonicalizeOpt
   hasSufficientHistory,
   isReviewableSource,
   isTestFile,
+  joinNameAndExt,
   listScenarios,
   loadHistory,
   mergeStepResults,
@@ -20966,21 +21519,26 @@ function normalizePlaywrightResults(testResults, adapterOptions, canonicalizeOpt
   readBranchName,
   readGitSha,
   readPackageVersion,
+  regenerateArtifacts,
   resolveAttachment,
   resolveAttachments,
   resolveTheme,
   resolveTraceUrl,
   rewriteAssetPaths,
   saveHistory,
+  scenariosCoveringPaths,
   sendNotifications,
   sendSlackNotification,
   sendTeamsNotification,
   sendWebhookNotification,
   signBody,
   slugify,
+  startWatch,
   stripAnsi,
+  toBehaviorManifest,
   toCIInfo,
   toRawCIInfo,
+  toScenarioIndex,
   toStoryReport,
   tryGetActiveOtelContext,
   updateHistory,