executable-stories-formatters 0.15.0 → 0.16.0

package/dist/cli.js

@@ -702,6 +702,41 @@ function generateFeatureId(uri) {
 function generateScenarioId(featureId, scenarioName) {
   return `${featureId};${slugify(scenarioName)}`;
 }
+function normalizeText(text2) {
+  return text2.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/g, " ").trim();
+}
+function tokenize(text2) {
+  const normalized = normalizeText(text2);
+  return normalized.length === 0 ? [] : normalized.split(" ");
+}
+function behaviourFingerprint(input) {
+  const steps = input.steps.map((step) => `${step.keyword.toLowerCase()}:${normalizeText(step.text)}`).join("\n");
+  const covers = [...input.covers ?? []].map((path18) => path18.trim()).filter(Boolean).sort().join(",");
+  if (steps.length === 0 && covers.length === 0) return "";
+  return createHash("sha1").update(`${steps}\0${covers}`).digest("hex").slice(0, 16);
+}
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 1;
+  if (a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const value of a) if (b.has(value)) intersection += 1;
+  return intersection / (a.size + b.size - intersection);
+}
+function stepTokens(steps) {
+  const tokens = /* @__PURE__ */ new Set();
+  for (const step of steps) {
+    for (const token of tokenize(step.text)) tokens.add(token);
+  }
+  return tokens;
+}
+function behaviourSimilarity(a, b) {
+  const aSteps = stepTokens(a.steps);
+  const bSteps = stepTokens(b.steps);
+  if (aSteps.size === 0 || bSteps.size === 0) return 0;
+  const stepScore = jaccard(aSteps, bSteps);
+  const titleScore = jaccard(new Set(tokenize(a.scenario)), new Set(tokenize(b.scenario)));
+  return stepScore * 0.7 + titleScore * 0.3;
+}
 
 // src/converters/acl/steps.ts
 function deriveStepResults(steps, scenarioStatus, error) {
@@ -17401,6 +17436,10 @@ function titleFor(kind) {
       return "Added";
     case "removed":
       return "Removed";
+    case "renamed":
+      return "Renamed";
+    case "moved":
+      return "Moved";
     case "changed":
       return "Changed";
     default:
@@ -17449,6 +17488,8 @@ function createPrCommentSummary(diff, maxScenarios = 10) {
   addSection(lines, diff, "fixed", maxScenarios);
   addSection(lines, diff, "added", maxScenarios);
   addSection(lines, diff, "removed", maxScenarios);
+  addSection(lines, diff, "renamed", maxScenarios);
+  addSection(lines, diff, "moved", maxScenarios);
   addSection(lines, diff, "changed", maxScenarios);
   return lines.join("\n").trimEnd();
 }
@@ -17525,8 +17566,10 @@ function sortDiffs(scenarios) {
     fixed: 1,
     added: 2,
     removed: 3,
-    changed: 4,
-    unchanged: 5
+    renamed: 4,
+    moved: 5,
+    changed: 6,
+    unchanged: 7
   };
   return [...scenarios].sort((a, b) => {
     if (rank[a.kind] !== rank[b.kind]) {
@@ -17541,69 +17584,108 @@ function sortDiffs(scenarios) {
     return a.scenario.localeCompare(b.scenario);
   });
 }
+var SIMILARITY_THRESHOLD = 0.75;
+function identityInput(tc) {
+  return {
+    scenario: tc.story.scenario,
+    sourceFile: tc.sourceFile,
+    steps: tc.story.steps,
+    covers: tc.story.covers
+  };
+}
+function changedFieldsOf(flags) {
+  return Object.entries(flags).filter(([, changed]) => changed).map(([field]) => field);
+}
+function allChangedFlags(errorMessage) {
+  return {
+    status: true,
+    steps: true,
+    docs: true,
+    tags: true,
+    tickets: true,
+    source: true,
+    duration: true,
+    attachments: true,
+    error: Boolean(errorMessage),
+    titlePath: true
+  };
+}
+function matchIdentities(removed, added) {
+  const pairs = [];
+  const remainingRemoved = new Set(removed);
+  const remainingAdded = new Set(added);
+  const removedByFp = /* @__PURE__ */ new Map();
+  const addedByFp = /* @__PURE__ */ new Map();
+  for (const tc of remainingRemoved) {
+    const fp = behaviourFingerprint(identityInput(tc));
+    if (fp === "") continue;
+    (removedByFp.get(fp) ?? removedByFp.set(fp, []).get(fp)).push(tc);
+  }
+  for (const tc of remainingAdded) {
+    const fp = behaviourFingerprint(identityInput(tc));
+    if (fp === "") continue;
+    (addedByFp.get(fp) ?? addedByFp.set(fp, []).get(fp)).push(tc);
+  }
+  for (const [fp, removedGroup] of removedByFp) {
+    const addedGroup = addedByFp.get(fp);
+    if (removedGroup.length === 1 && addedGroup && addedGroup.length === 1) {
+      pairs.push({ before: removedGroup[0], after: addedGroup[0], confidence: 1, matchedBy: "fingerprint" });
+      remainingRemoved.delete(removedGroup[0]);
+      remainingAdded.delete(addedGroup[0]);
+    }
+  }
+  for (const before of [...remainingRemoved]) {
+    let best;
+    let bestScore = 0;
+    let tied = false;
+    for (const after of remainingAdded) {
+      const score = behaviourSimilarity(identityInput(before), identityInput(after));
+      if (score > bestScore) {
+        bestScore = score;
+        best = after;
+        tied = false;
+      } else if (score === bestScore) {
+        tied = true;
+      }
+    }
+    if (best && !tied && bestScore >= SIMILARITY_THRESHOLD) {
+      pairs.push({ before, after: best, confidence: Math.round(bestScore * 100) / 100, matchedBy: "similarity" });
+      remainingRemoved.delete(before);
+      remainingAdded.delete(best);
+    }
+  }
+  return {
+    pairs,
+    unmatchedRemoved: [...remainingRemoved],
+    unmatchedAdded: [...remainingAdded]
+  };
+}
+function identityKind(before, after) {
+  const titleChanged = before.story.scenario !== after.story.scenario;
+  const fileChanged = before.sourceFile !== after.sourceFile;
+  return fileChanged && !titleChanged ? "moved" : "renamed";
+}
 function diffRuns(baseline, current) {
   const baselineById = new Map(baseline.testCases.map((tc) => [tc.id, tc]));
   const currentById = new Map(current.testCases.map((tc) => [tc.id, tc]));
   const ids = /* @__PURE__ */ new Set([...baselineById.keys(), ...currentById.keys()]);
   const scenarios = [];
+  const removedCases = [];
+  const addedCases = [];
   for (const id of ids) {
     const before = baselineById.get(id);
     const after = currentById.get(id);
     if (!before && after) {
-      const flags2 = {
-        status: true,
-        steps: true,
-        docs: true,
-        tags: true,
-        tickets: true,
-        source: true,
-        duration: true,
-        attachments: true,
-        error: Boolean(after.errorMessage),
-        titlePath: true
-      };
-      scenarios.push({
-        kind: "added",
-        id,
-        scenario: after.story.scenario,
-        sourceFile: after.sourceFile,
-        sourceLine: after.sourceLine,
-        current: toScenarioSnapshot(after),
-        flags: flags2,
-        changedFields: Object.entries(flags2).filter(([, changed]) => changed).map(([field]) => field)
-      });
+      addedCases.push(after);
       continue;
     }
     if (before && !after) {
-      const flags2 = {
-        status: true,
-        steps: true,
-        docs: true,
-        tags: true,
-        tickets: true,
-        source: true,
-        duration: true,
-        attachments: true,
-        error: Boolean(before.errorMessage),
-        titlePath: true
-      };
-      scenarios.push({
-        kind: "removed",
-        id,
-        scenario: before.story.scenario,
-        sourceFile: before.sourceFile,
-        sourceLine: before.sourceLine,
-        baseline: toScenarioSnapshot(before),
-        flags: flags2,
-        changedFields: Object.entries(flags2).filter(([, changed]) => changed).map(([field]) => field)
-      });
-      continue;
-    }
-    if (!before || !after) {
+      removedCases.push(before);
       continue;
     }
+    if (!before || !after) continue;
     const flags = buildFlags(before, after);
-    const changedFields = Object.entries(flags).filter(([, changed]) => changed).map(([field]) => field);
+    const changedFields = changedFieldsOf(flags);
     const kind = getPrimaryKind(before, after, changedFields.length > 0);
     scenarios.push({
       kind,
@@ -17618,12 +17700,59 @@ function diffRuns(baseline, current) {
       durationDeltaMs: after.durationMs - before.durationMs
     });
   }
+  const { pairs, unmatchedRemoved, unmatchedAdded } = matchIdentities(removedCases, addedCases);
+  for (const { before, after, confidence, matchedBy } of pairs) {
+    const flags = buildFlags(before, after);
+    scenarios.push({
+      kind: identityKind(before, after),
+      id: after.id,
+      previousId: before.id,
+      scenario: after.story.scenario,
+      sourceFile: after.sourceFile,
+      sourceLine: after.sourceLine,
+      baseline: toScenarioSnapshot(before),
+      current: toScenarioSnapshot(after),
+      flags,
+      changedFields: changedFieldsOf(flags),
+      durationDeltaMs: after.durationMs - before.durationMs,
+      matchConfidence: confidence,
+      matchedBy
+    });
+  }
+  for (const after of unmatchedAdded) {
+    const flags = allChangedFlags(after.errorMessage);
+    scenarios.push({
+      kind: "added",
+      id: after.id,
+      scenario: after.story.scenario,
+      sourceFile: after.sourceFile,
+      sourceLine: after.sourceLine,
+      current: toScenarioSnapshot(after),
+      flags,
+      changedFields: changedFieldsOf(flags)
+    });
+  }
+  for (const before of unmatchedRemoved) {
+    const flags = allChangedFlags(before.errorMessage);
+    scenarios.push({
+      kind: "removed",
+      id: before.id,
+      scenario: before.story.scenario,
+      sourceFile: before.sourceFile,
+      sourceLine: before.sourceLine,
+      baseline: toScenarioSnapshot(before),
+      flags,
+      changedFields: changedFieldsOf(flags)
+    });
+  }
   const sorted = sortDiffs(scenarios);
   const summary = {
     totalBaseline: baseline.testCases.length,
     totalCurrent: current.testCases.length,
     added: sorted.filter((s) => s.kind === "added").length,
     removed: sorted.filter((s) => s.kind === "removed").length,
+    renamed: sorted.filter((s) => s.kind === "renamed").length,
+    moved: sorted.filter((s) => s.kind === "moved").length,
     changed: sorted.filter((s) => s.kind === "changed").length,
     regressed: sorted.filter((s) => s.kind === "regressed").length,
     fixed: sorted.filter((s) => s.kind === "fixed").length,
@@ -17651,6 +17780,10 @@ function statusLabel(kind) {
       return "Added";
     case "removed":
       return "Removed";
+    case "renamed":
+      return "Renamed";
+    case "moved":
+      return "Moved";
     case "changed":
       return "Changed";
     default:
@@ -17976,6 +18109,8 @@ window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', fun
         <div class="summary-card"><strong>${diff.summary.fixed}</strong><span>Fixed</span></div>
         <div class="summary-card"><strong>${diff.summary.added}</strong><span>Added</span></div>
         <div class="summary-card"><strong>${diff.summary.removed}</strong><span>Removed</span></div>
+        <div class="summary-card"><strong>${diff.summary.renamed}</strong><span>Renamed</span></div>
+        <div class="summary-card"><strong>${diff.summary.moved}</strong><span>Moved</span></div>
         <div class="summary-card"><strong>${diff.summary.changed}</strong><span>Changed</span></div>
         <div class="summary-card"><strong>${diff.summary.unchanged}</strong><span>Unchanged</span></div>
       </section>
@@ -18036,6 +18171,10 @@ function formatStatus(kind) {
       return "Added";
     case "removed":
       return "Removed";
+    case "renamed":
+      return "Renamed";
+    case "moved":
+      return "Moved";
     case "changed":
       return "Changed";
     default:
@@ -18188,13 +18327,13 @@ var RunDiffMarkdownFormatter = class {
       lines.push("No regressions or fixes detected. Remaining changes are neutral.");
     }
     lines.push("");
-    lines.push("| Added | Removed | Regressed | Fixed | Changed | Unchanged |");
-    lines.push("| ---: | ---: | ---: | ---: | ---: | ---: |");
+    lines.push("| Added | Removed | Renamed | Moved | Regressed | Fixed | Changed | Unchanged |");
+    lines.push("| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |");
     lines.push(
-      `| ${diff.summary.added} | ${diff.summary.removed} | ${diff.summary.regressed} | ${diff.summary.fixed} | ${diff.summary.changed} | ${diff.summary.unchanged} |`
+      `| ${diff.summary.added} | ${diff.summary.removed} | ${diff.summary.renamed} | ${diff.summary.moved} | ${diff.summary.regressed} | ${diff.summary.fixed} | ${diff.summary.changed} | ${diff.summary.unchanged} |`
     );
     lines.push("");
-    for (const kind of ["regressed", "fixed", "added", "removed", "changed"]) {
+    for (const kind of ["regressed", "fixed", "added", "removed", "renamed", "moved", "changed"]) {
       const scenarios = diff.scenarios.filter((scenario) => scenario.kind === kind);
       if (scenarios.length === 0) continue;
       lines.push(`## ${formatStatus(kind)} (${scenarios.length})`);
@@ -19143,7 +19282,10 @@ function diffStoryReports(baseline, current) {
     };
   });
   const summary = { added: 0, removed: 0, regressed: 0, fixed: 0, changed: 0, unchanged: 0 };
-  for (const s of scenarios) summary[s.kind] += 1;
+  for (const s of scenarios) {
+    if (s.kind === "renamed" || s.kind === "moved") continue;
+    summary[s.kind] += 1;
+  }
   return { schemaVersion: "1.0", summary, scenarios };
 }
 
@@ -21987,6 +22129,9 @@ import { fileURLToPath } from "url";
 var __dirname = path10.dirname(fileURLToPath(import.meta.url));
 var FRAMEWORK_DIRS = ["src/components", "src/lib", "src/styles", "src/pages"];
 var FRAMEWORK_FILES = ["tsconfig.json"];
+function isScaffoldedAstroSite(dir) {
+  return fs9.existsSync(path10.join(dir, "astro.config.mjs"));
+}
 function initAstro(options = {}) {
   const targetDir = options.targetDir ?? "./story-docs";
   const force = options.force ?? false;
@@ -22012,7 +22157,7 @@ function initAstro(options = {}) {
   return { targetDir };
 }
 function updateFrameworkFiles(templateDir, targetDir) {
-  if (!fs9.existsSync(targetDir) || !fs9.existsSync(path10.join(targetDir, "astro.config.mjs"))) {
+  if (!isScaffoldedAstroSite(targetDir)) {
     throw new Error(
       `"${targetDir}" does not look like a scaffolded docs site. Run init-astro (without --update) first.`
     );
@@ -22057,7 +22202,8 @@ function copyDirRecursive(src, dest, onFile, baseSrc = src) {
   const entries = fs9.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = path10.join(src, entry.name);
-    const destPath = path10.join(dest, entry.name);
+    const destName = entry.name === "gitignore" ? ".gitignore" : entry.name;
+    const destPath = path10.join(dest, destName);
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath, onFile, baseSrc);
     } else {
@@ -23019,6 +23165,12 @@ ${schemaResult.errors.map((e) => `  ${e}`).join("\n")}`,
 }
 async function buildDocs(options) {
   const siteDir = path16.resolve(options.siteDir);
+  if (!isScaffoldedAstroSite(siteDir)) {
+    throw new BuildDocsError(
+      `"${siteDir}" is not a scaffolded Astro docs site (no astro.config.mjs). Run "executable-stories init-astro <dir>" first, then pass it with --site-dir <dir>.`,
+      "usage"
+    );
+  }
   const storiesPublicDir = path16.join(siteDir, "public", "stories");
   const assetsDir = path16.join(storiesPublicDir, "assets");
   const storyPagesDir = path16.join(siteDir, "src", "content", "docs", "stories");
@@ -23152,6 +23304,7 @@ executable-stories \u2014 Generate reports from test results JSON.
 USAGE
   executable-stories format <file> [options]
   executable-stories format --stdin [options]
+  executable-stories watch <raw-run.json> [options]
   executable-stories compare <baseline-file> <current-file> [options]
   executable-stories gate-release <dev-run.json> <rc-run.json> [options]
   executable-stories review <file> --changed-files <path> [options]
@@ -23162,6 +23315,7 @@ USAGE
   executable-stories validate <file>
   executable-stories validate --stdin
   executable-stories init-astro [directory]
+  executable-stories build-docs <raw-run.json> [--site-dir <dir>] [options]
   executable-stories new <template> "<name>" [options]
   executable-stories check-links <dir> [options]
   executable-stories import-openapi <spec> [options]
@@ -23183,6 +23337,7 @@ SUBCOMMANDS
   triage             Discovery worklist for agent loops: failing scenarios, regressions first, each with the code it covers
   validate           Validate a JSON file against the schema (no output generated)
   init-astro         Scaffold an Astro docs site for story output (Starlight with themed CSS)
+  build-docs         Build the living-docs site: one page per story file + Explorer data (auto-pickup, prunes deleted stories)
   new                Scaffold a docs page from a template (adr, runbook, decision-log, incident, scenario-note)
   check-links        Scan docs for broken internal/external links (CI-friendly exit code)
   import-openapi     Generate API doc pages from an OpenAPI spec, linked to verifying stories
@@ -23192,7 +23347,7 @@ SUBCOMMANDS
 
 OPTIONS
   --format <formats>            Comma-separated formats: html, markdown, release-manifest, traceability-matrix, junit, cucumber-json, cucumber-messages, cucumber-html, astro, confluence, story-report-json, scenario-index-json, behavior-manifest-json, or custom names from config (default: html)
-                                  astro             Themed Markdown (for Astro docs sites with matching CSS)
+                                  astro             Themed Markdown primitive (single aggregated page; for a full site use "build-docs")
                                   confluence        Atlassian Document Format (ADF) JSON for Confluence / Jira
                                   behavior-manifest-json Agent-readable behavior manifest and debugger warnings
                                   html              Custom HTML report (accessible, dark mode, mermaid)
@@ -23313,6 +23468,20 @@ DEPLOY
 INIT-ASTRO
   executable-stories init-astro [directory]   Scaffold into directory (default: ./story-docs)
   --force                                      Overwrite existing directory
+  --update                                     Refresh framework files only (keeps your content + config)
+
+BUILD-DOCS
+  Build the multi-page living-docs site from a raw run: one Astro page per story
+  file plus Explorer data (scenario-links.json, story-report.json). Auto-pickup \u2014
+  a new *.story.test.ts becomes a new page on the next run; deleting a story
+  prunes its page. This is the headline living-docs flow; "format --format astro"
+  is a low-level primitive that emits a single aggregated page, not a site.
+
+  executable-stories build-docs <raw-run.json> [--site-dir <dir>]
+  --site-dir <dir>             Target site dir (default: a scaffolded init-astro site)
+  --openapi <spec>             Link generated API pages to verifying stories
+  --baseline <prev-report>     Diff against a prior story-report.json for change markers
+  --audience-split             Split pages by audience (business vs technical)
 
 PUBLISH-CONFLUENCE
   executable-stories publish-confluence <file.adf.json> [options]
@@ -23419,12 +23588,17 @@ async function parseCliArgs(argv) {
       console.log("To change theme, edit astro.config.mjs customCss array.");
       console.log("");
       console.log("Next steps:");
-      console.log(`  cd ${result.targetDir}`);
-      console.log("  pnpm install    # or npm install");
-      console.log("  pnpm dev        # start the dev server");
-      console.log("");
-      console.log("Generate everything (story pages, explorer data, API pages) in one step:");
-      console.log(`  executable-stories build-docs run.json --site-dir ${result.targetDir} [--openapi spec.json]`);
+      console.log(`  1. cd ${result.targetDir} && pnpm install      # or npm install`);
+      console.log("  2. In your TEST project, add the StoryReporter with a rawRunPath, e.g.");
+      console.log("       StoryReporter({ rawRunPath: 'reports/raw-run.json' })");
+      console.log("     (this is what writes the raw run that build-docs reads)");
+      console.log("  3. Run your tests to produce reports/raw-run.json:");
+      console.log("       pnpm test");
+      console.log("  4. Build the living-docs site (story pages, explorer data, API pages):");
+      console.log(
+        `       executable-stories build-docs reports/raw-run.json --site-dir ${result.targetDir} [--openapi spec.json]`
+      );
+      console.log(`  5. Preview it:  cd ${result.targetDir} && pnpm dev`);
       console.log("");
       console.log("Later, pull template/design improvements without losing your content:");
       console.log(`  executable-stories init-astro ${result.targetDir} --update`);