executable-stories-formatters 0.8.0 → 0.9.0

package/dist/index.js

@@ -281,7 +281,8 @@ function canonicalizeTestCase(raw, options, projectRoot) {
     projectName: raw.projectName,
     retry: raw.retry ?? 0,
     retries: raw.retries ?? 0,
-    tags
+    tags,
+    ...raw.evidence ? { evidence: raw.evidence } : {}
   };
 }
 function normalizeTags(story) {
@@ -13814,7 +13815,7 @@ function renderDocEntry(entry, deps) {
 // src/formatters/html/renderers/steps.ts
 var CONTINUATION_KEYWORDS = ["And", "But", "*"];
 function renderStep(step, stepResult, index, deps) {
-  const statusIcon2 = stepResult ? deps.getStatusIcon(stepResult.status) : "\u25CB";
+  const statusIcon4 = stepResult ? deps.getStatusIcon(stepResult.status) : "\u25CB";
   const statusClass = stepResult ? `status-${stepResult.status}` : "";
   const duration = stepResult && stepResult.durationMs > 0 ? `${stepResult.durationMs}ms` : "";
   const keywordTrimmed = step.keyword.trim();
@@ -13823,7 +13824,7 @@ function renderStep(step, stepResult, index, deps) {
   const stepDocs = deps.renderDocs(step.docs, "step-docs");
   const textHtml = deps.highlightStepParams ? deps.highlightStepParams(step.text) : deps.escapeHtml(step.text);
   return `<div class="${stepClass}" data-keyword="${deps.escapeHtml(keywordTrimmed)}" data-text="${deps.escapeHtml(step.text)}">
-  <span class="step-status ${statusClass}">${statusIcon2}</span>
+  <span class="step-status ${statusClass}">${statusIcon4}</span>
   <span class="step-keyword">${deps.escapeHtml(step.keyword)}</span>
   <span class="step-text">${textHtml}</span>
   <span class="step-duration">${duration}</span>
@@ -13873,16 +13874,16 @@ function hasSufficientHistory(entries, min) {
 }
 
 // src/formatters/html/renderers/scenario.ts
-function renderTicket(ticket, template, escapeHtml3) {
+function renderTicket(ticket, template, escapeHtml4) {
   const url = ticket.url ?? (template ? template.replace("{ticket}", ticket.id) : void 0);
   if (url) {
-    return `<a class="tag ticket-tag" href="${escapeHtml3(url)}" target="_blank" rel="noopener noreferrer">${escapeHtml3(ticket.id)}</a>`;
+    return `<a class="tag ticket-tag" href="${escapeHtml4(url)}" target="_blank" rel="noopener noreferrer">${escapeHtml4(ticket.id)}</a>`;
   }
-  return `<span class="tag ticket-tag">${escapeHtml3(ticket.id)}</span>`;
+  return `<span class="tag ticket-tag">${escapeHtml4(ticket.id)}</span>`;
 }
 function renderScenario(args, deps) {
   const { tc } = args;
-  const statusIcon2 = deps.getStatusIcon(tc.status);
+  const statusIcon4 = deps.getStatusIcon(tc.status);
   const statusClass = `status-${tc.status}`;
   const duration = tc.durationMs > 0 ? `${(tc.durationMs / 1e3).toFixed(2)}s` : "";
   const tags = tc.tags.map((t) => `<span class="tag">${deps.escapeHtml(t)}</span>`).join("");
@@ -13952,7 +13953,7 @@ function renderScenario(args, deps) {
   <div class="scenario-header" role="button" tabindex="0" aria-expanded="${ariaExpanded}">
     <div class="scenario-info">
       <div class="scenario-title">
-        <span class="status-icon ${statusClass}">${statusIcon2}</span>
+        <span class="status-icon ${statusClass}">${statusIcon4}</span>
         <span class="scenario-name">${deps.escapeHtml(tc.story.scenario)}</span>
       </div>
       <div class="scenario-meta">${tags}${tickets}${outcomeBadge}${sourceLink}${traceBadge}${metricBadges}</div>
@@ -14078,7 +14079,7 @@ function flattenTree(roots) {
   }
   return result;
 }
-function buildTooltip(span, escapeHtml3) {
+function buildTooltip(span, escapeHtml4) {
   const parts = [];
   parts.push(`${span.name} (${formatDuration(span.durationMs)})`);
   if (span.statusMessage) {
@@ -14096,7 +14097,7 @@ function buildTooltip(span, escapeHtml3) {
   if (text2.length > TOOLTIP_MAX_LENGTH) {
     text2 = text2.slice(0, TOOLTIP_MAX_LENGTH - 3) + "...";
   }
-  return escapeHtml3(text2);
+  return escapeHtml4(text2);
 }
 function renderTraceView(args, deps) {
   if (!args.spans || args.spans.length === 0) return "";
@@ -14319,11 +14320,11 @@ function renderToc(args, deps) {
     const featureName = suitePaths.length > 0 && suitePaths[0].length > 0 ? suitePaths[0][0] : file.split("/").pop()?.replace(/\.[^.]+$/, "") ?? file;
     const featureSlug = `feature-${slugify(file)}`;
     const scenarios = testCases.map((tc) => {
-      const statusIcon2 = deps.getStatusIcon(tc.status);
+      const statusIcon4 = deps.getStatusIcon(tc.status);
       const statusClass = `status-${tc.status}`;
       const failedClass = tc.status === "failed" ? " toc-failed" : "";
       return `<a class="toc-scenario${failedClass}" href="#scenario-${tc.id}">
-          <span class="toc-status ${statusClass}">${statusIcon2}</span>
+          <span class="toc-status ${statusClass}">${statusIcon4}</span>
           ${deps.escapeHtml(tc.story.scenario)}
         </a>`;
     }).join("\n");
@@ -19634,6 +19635,697 @@ function listScenarios(args, _deps) {
   return lines.join("\n");
 }
 
+// src/review/conventions.ts
+var CHANGE_TAG_PREFIX = "change:";
+var AUDIENCE_TAG_PREFIX = "audience:";
+var VALID_CHANGE_TYPES = /* @__PURE__ */ new Set([
+  "feature",
+  "bugfix",
+  "refactor",
+  "perf",
+  "deps"
+]);
+var STAKEHOLDER_FILE = /(?:\.e2e\.)|(?:^|\/)e2e\/|(?:\.spec\.)/i;
+var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "ts",
+  "tsx",
+  "js",
+  "jsx",
+  "mjs",
+  "cjs",
+  "py",
+  "go",
+  "rs",
+  "kt",
+  "kts",
+  "java",
+  "cs",
+  "rb"
+]);
+var TEST_INFIX = /\.(?:story\.)?(?:int\.|e2e\.|unit\.)?(?:test|spec|cy)\.[a-z]+$/i;
+function deriveAudience(sourceFile, tags) {
+  const override = tags.map((t) => t.toLowerCase()).find((t) => t.startsWith(AUDIENCE_TAG_PREFIX));
+  if (override) {
+    const value = override.slice(AUDIENCE_TAG_PREFIX.length);
+    if (value === "stakeholder" || value === "engineer") return value;
+  }
+  return STAKEHOLDER_FILE.test(sourceFile) ? "stakeholder" : "engineer";
+}
+function deriveChangeType(tags) {
+  for (const tag of tags) {
+    const lower = tag.toLowerCase();
+    if (lower.startsWith(CHANGE_TAG_PREFIX)) {
+      const value = lower.slice(CHANGE_TAG_PREFIX.length);
+      if (VALID_CHANGE_TYPES.has(value)) return value;
+    }
+  }
+  return "unknown";
+}
+function extensionOf(path10) {
+  const base = path10.split("/").pop() ?? path10;
+  const dot = base.lastIndexOf(".");
+  return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
+}
+function isTestFile(path10) {
+  return TEST_INFIX.test(path10);
+}
+function isReviewableSource(path10) {
+  if (isTestFile(path10)) return false;
+  if (path10.endsWith(".d.ts")) return false;
+  return CODE_EXTENSIONS.has(extensionOf(path10));
+}
+function testBaseKey(testFile) {
+  return testFile.replace(TEST_INFIX, "");
+}
+function sourceBaseKey(sourceFile) {
+  const dot = sourceFile.lastIndexOf(".");
+  const slash = sourceFile.lastIndexOf("/");
+  return dot > slash ? sourceFile.slice(0, dot) : sourceFile;
+}
+
+// src/review/build-review.ts
+var STRENGTH_RANK = {
+  none: 0,
+  weak: 1,
+  moderate: 2,
+  strong: 3
+};
+var INTENT_SECTION_TITLE = /\b(why|intent|approach|rationale|reasoning)\b/i;
+function findDoc(docs, predicate) {
+  if (!docs) return void 0;
+  for (const doc of docs) {
+    if (predicate(doc)) return doc;
+    const nested = findDoc(doc.children, predicate);
+    if (nested) return nested;
+  }
+  return void 0;
+}
+function anyDoc(docs, predicate) {
+  return findDoc(docs, predicate) !== void 0;
+}
+function extractIntent(testCase) {
+  const docs = testCase.story.docs;
+  const section = findDoc(
+    docs,
+    (d) => d.kind === "section" && INTENT_SECTION_TITLE.test(d.title)
+  );
+  if (section && section.kind === "section") return section.markdown;
+  const note = findDoc(docs, (d) => d.kind === "note");
+  if (note && note.kind === "note") return note.text;
+  return void 0;
+}
+function hasScreenshot(testCase) {
+  if (testCase.attachments.some((a) => a.mediaType.startsWith("image/"))) {
+    return true;
+  }
+  if (anyDoc(testCase.story.docs, (d) => d.kind === "screenshot")) return true;
+  return testCase.story.steps.some(
+    (step) => anyDoc(step.docs, (d) => d.kind === "screenshot")
+  );
+}
+function hasOtelTrace(testCase) {
+  return (testCase.story.otelSpans?.length ?? 0) > 0;
+}
+function gradeEvidence(testCase, audience) {
+  if (testCase.status !== "passed") {
+    return {
+      strength: "none",
+      reasons: [`test is ${testCase.status} \u2014 the proof does not hold`]
+    };
+  }
+  const ev = testCase.evidence;
+  const screenshot = hasScreenshot(testCase);
+  const otel = hasOtelTrace(testCase);
+  const isIntegration = /\.int\.test\./i.test(testCase.sourceFile);
+  const mutation = ev?.mutationScorePct;
+  const changedCov = ev?.changedLineCoveragePct;
+  const strong2 = [];
+  if (ev?.failingFirstVerified) {
+    strong2.push("failing-first verified (red on base ref, green on head)");
+  }
+  if (typeof mutation === "number" && mutation >= 80) {
+    strong2.push(`mutation score ${mutation}% (\u226580%)`);
+  }
+  if (screenshot && otel) {
+    strong2.push("backed by screenshot + OTEL trace");
+  } else if (audience === "stakeholder" && (screenshot || otel)) {
+    strong2.push(`stakeholder proof: ${screenshot ? "screenshot" : "OTEL trace"}`);
+  }
+  if (strong2.length > 0) return { strength: "strong", reasons: strong2 };
+  const moderate = [];
+  if (screenshot) moderate.push("screenshot attached");
+  if (otel) moderate.push("OTEL trace attached");
+  if (typeof mutation === "number" && mutation >= 50) {
+    moderate.push(`mutation score ${mutation}%`);
+  }
+  if (typeof changedCov === "number" && changedCov >= 80) {
+    moderate.push(`changed-line coverage ${changedCov}%`);
+  }
+  if (isIntegration) moderate.push("integration-level test");
+  if (moderate.length > 0) return { strength: "moderate", reasons: moderate };
+  return {
+    strength: "weak",
+    reasons: [
+      "passing test only \u2014 no corroborating evidence (add e2e proof, mutation score, or failing-first)"
+    ]
+  };
+}
+function toClaim(testCase, changedSourcePaths) {
+  const audience = deriveAudience(testCase.sourceFile, testCase.tags);
+  const changeType = deriveChangeType(testCase.tags);
+  const { strength, reasons } = gradeEvidence(testCase, audience);
+  const key = testBaseKey(testCase.sourceFile);
+  const coversFiles = changedSourcePaths.filter(
+    (path10) => sourceBaseKey(path10) === key
+  );
+  return {
+    id: testCase.id,
+    scenario: testCase.story.scenario,
+    sourceFile: testCase.sourceFile,
+    sourceLine: testCase.sourceLine,
+    status: testCase.status,
+    audience,
+    changeType,
+    strength,
+    strengthReasons: reasons,
+    intent: extractIntent(testCase),
+    coversFiles,
+    testCase
+  };
+}
+function bandFor(claims) {
+  if (claims.length === 0) return "uncovered";
+  const maxRank = Math.max(...claims.map((c) => STRENGTH_RANK[c.strength]));
+  return maxRank >= STRENGTH_RANK.moderate ? "covered" : "weak";
+}
+var AUDIENCE_ORDER = {
+  stakeholder: 0,
+  engineer: 1
+};
+function buildReview(run, context = { changedFiles: [] }) {
+  const changedSource = context.changedFiles.filter(
+    (f) => isReviewableSource(f.path)
+  );
+  const changedSourcePaths = changedSource.map((f) => f.path);
+  const claims = run.testCases.map((tc) => toClaim(tc, changedSourcePaths));
+  const changedFiles = changedSource.map((file) => {
+    const covering = claims.filter((c) => c.coversFiles.includes(file.path));
+    return {
+      path: file.path,
+      changeKind: file.changeKind,
+      band: bandFor(covering),
+      claims: covering.map((c) => ({
+        id: c.id,
+        scenario: c.scenario,
+        strength: c.strength
+      }))
+    };
+  });
+  const sortedClaims = [...claims].sort((a, b) => {
+    if (AUDIENCE_ORDER[a.audience] !== AUDIENCE_ORDER[b.audience]) {
+      return AUDIENCE_ORDER[a.audience] - AUDIENCE_ORDER[b.audience];
+    }
+    if (STRENGTH_RANK[a.strength] !== STRENGTH_RANK[b.strength]) {
+      return STRENGTH_RANK[a.strength] - STRENGTH_RANK[b.strength];
+    }
+    if (a.sourceFile !== b.sourceFile) {
+      return a.sourceFile.localeCompare(b.sourceFile);
+    }
+    return a.scenario.localeCompare(b.scenario);
+  });
+  const bandRank = { uncovered: 0, weak: 1, covered: 2 };
+  const sortedFiles = [...changedFiles].sort((a, b) => {
+    if (bandRank[a.band] !== bandRank[b.band]) {
+      return bandRank[a.band] - bandRank[b.band];
+    }
+    return a.path.localeCompare(b.path);
+  });
+  const summary = buildSummary2(sortedClaims, sortedFiles);
+  return {
+    run,
+    context,
+    summary,
+    claims: sortedClaims,
+    changedFiles: sortedFiles
+  };
+}
+function buildSummary2(claims, changedFiles) {
+  const byAudience = {
+    stakeholder: 0,
+    engineer: 0
+  };
+  const byStrength = {
+    none: 0,
+    weak: 0,
+    moderate: 0,
+    strong: 0
+  };
+  for (const claim of claims) {
+    byAudience[claim.audience] += 1;
+    byStrength[claim.strength] += 1;
+  }
+  return {
+    totalClaims: claims.length,
+    byAudience,
+    byStrength,
+    changedSourceFiles: changedFiles.length,
+    uncovered: changedFiles.filter((f) => f.band === "uncovered").length,
+    weaklyCovered: changedFiles.filter((f) => f.band === "weak").length,
+    covered: changedFiles.filter((f) => f.band === "covered").length
+  };
+}
+
+// src/formatters/review-markdown.ts
+var STRENGTH_BADGE = {
+  strong: "\u{1F7E2} strong",
+  moderate: "\u{1F7E1} moderate",
+  weak: "\u{1F7E0} weak",
+  none: "\u{1F534} none"
+};
+function statusIcon2(status) {
+  switch (status) {
+    case "passed":
+      return "\u2705";
+    case "failed":
+      return "\u274C";
+    case "skipped":
+      return "\u2298";
+    default:
+      return "\u2022";
+  }
+}
+function escapeCell2(value) {
+  return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function intentSummary(intent) {
+  const firstLine = intent.split("\n").find((l) => l.trim().length > 0) ?? "";
+  const trimmed = firstLine.trim();
+  return trimmed.length > 200 ? `${trimmed.slice(0, 197)}\u2026` : trimmed;
+}
+function renderTicket2(ticket) {
+  return ticket.url ? `[${ticket.id}](${ticket.url})` : `\`${ticket.id}\``;
+}
+function renderUncoveredBand(lines, files) {
+  const uncovered = files.filter((f) => f.band === "uncovered");
+  if (uncovered.length === 0) return;
+  lines.push(`## \u{1F534} Changed code with no evidence (${uncovered.length})`);
+  lines.push("");
+  lines.push("Start here \u2014 these changed source files have no claim or test behind them.");
+  lines.push("");
+  for (const file of uncovered) {
+    lines.push(`- \`${file.path}\` _(${file.changeKind})_`);
+  }
+  lines.push("");
+}
+function renderWeakBand(lines, files) {
+  const weak = files.filter((f) => f.band === "weak");
+  if (weak.length === 0) return;
+  lines.push(`## \u{1F7E1} Changed code with weak evidence (${weak.length})`);
+  lines.push("");
+  for (const file of weak) {
+    const covered = file.claims.map((c) => `${escapeCell2(c.scenario)} (${c.strength})`).join(", ");
+    lines.push(`- \`${file.path}\` _(${file.changeKind})_ \u2014 only: ${covered}`);
+  }
+  lines.push("");
+}
+function renderClaim(lines, claim) {
+  lines.push(`### ${statusIcon2(claim.status)} ${claim.scenario}`);
+  lines.push("");
+  lines.push(`- File: \`${claim.sourceFile}:${claim.sourceLine}\``);
+  if (claim.changeType !== "unknown") {
+    lines.push(`- Change: \`${claim.changeType}\``);
+  }
+  const tickets = claim.testCase.story.tickets ?? [];
+  if (tickets.length > 0) {
+    lines.push(`- Tickets: ${tickets.map(renderTicket2).join(", ")}`);
+  }
+  lines.push(
+    `- Evidence: ${STRENGTH_BADGE[claim.strength]} \u2014 ${claim.strengthReasons.join("; ")}`
+  );
+  if (claim.coversFiles.length > 0) {
+    lines.push(
+      `- Covers: ${claim.coversFiles.map((f) => `\`${f}\``).join(", ")}`
+    );
+  }
+  if (claim.intent) {
+    lines.push(`- Why: ${escapeCell2(intentSummary(claim.intent))}`);
+  }
+  lines.push("");
+}
+function renderAudienceSection(lines, title, claims) {
+  if (claims.length === 0) return;
+  lines.push(`## ${title} (${claims.length})`);
+  lines.push("");
+  for (const claim of claims) {
+    renderClaim(lines, claim);
+  }
+}
+var ReviewMarkdownFormatter = class {
+  title;
+  constructor(options = {}) {
+    this.title = options.title ?? "Evidence Review";
+  }
+  format(review) {
+    const lines = [];
+    const { summary, context } = review;
+    lines.push(`# ${this.title}`);
+    lines.push("");
+    if (context.baseRef || context.headRef) {
+      lines.push(
+        `Comparing \`${context.baseRef ?? "base"}\` \u2192 \`${context.headRef ?? "head"}\`.`
+      );
+      lines.push("");
+    }
+    lines.push("## Review priority");
+    lines.push("");
+    if (summary.changedSourceFiles === 0) {
+      lines.push(
+        "No changed source files supplied \u2014 showing claims and evidence only."
+      );
+    } else if (summary.uncovered > 0) {
+      lines.push(
+        `Review the ${summary.uncovered} unaccounted-for file(s) first: changed code with no evidence behind it.`
+      );
+    } else if (summary.weaklyCovered > 0) {
+      lines.push(
+        `No unaccounted-for changes. Review ${summary.weaklyCovered} weakly-covered file(s) next.`
+      );
+    } else {
+      lines.push("Every changed source file is backed by at least moderate evidence.");
+    }
+    lines.push("");
+    if (summary.changedSourceFiles > 0) {
+      lines.push("| \u{1F534} Uncovered | \u{1F7E1} Weak | \u{1F7E2} Covered | Changed files |");
+      lines.push("| ---: | ---: | ---: | ---: |");
+      lines.push(
+        `| ${summary.uncovered} | ${summary.weaklyCovered} | ${summary.covered} | ${summary.changedSourceFiles} |`
+      );
+      lines.push("");
+    }
+    lines.push("| Claims | Stakeholder | Engineer | Strong | Moderate | Weak | None |");
+    lines.push("| ---: | ---: | ---: | ---: | ---: | ---: | ---: |");
+    lines.push(
+      `| ${summary.totalClaims} | ${summary.byAudience.stakeholder} | ${summary.byAudience.engineer} | ${summary.byStrength.strong} | ${summary.byStrength.moderate} | ${summary.byStrength.weak} | ${summary.byStrength.none} |`
+    );
+    lines.push("");
+    renderUncoveredBand(lines, review.changedFiles);
+    renderWeakBand(lines, review.changedFiles);
+    renderAudienceSection(
+      lines,
+      "Stakeholder behaviour",
+      review.claims.filter((c) => c.audience === "stakeholder")
+    );
+    renderAudienceSection(
+      lines,
+      "Engineer changes",
+      review.claims.filter((c) => c.audience === "engineer")
+    );
+    return lines.join("\n").trimEnd();
+  }
+};
+
+// src/formatters/review-html.ts
+function escapeHtml3(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+var STRENGTH_LABEL = {
+  strong: "Strong",
+  moderate: "Moderate",
+  weak: "Weak",
+  none: "None"
+};
+function statusIcon3(status) {
+  switch (status) {
+    case "passed":
+      return "\u2705";
+    case "failed":
+      return "\u274C";
+    case "skipped":
+      return "\u2298";
+    default:
+      return "\u2022";
+  }
+}
+function formatStep3(step) {
+  return `<li><strong>${escapeHtml3(step.keyword)}</strong> ${escapeHtml3(step.text)}</li>`;
+}
+function inlineDoc(doc) {
+  switch (doc.kind) {
+    case "note":
+      return escapeHtml3(doc.text);
+    case "section":
+      return `<strong>${escapeHtml3(doc.title)}</strong>: ${escapeHtml3(doc.markdown)}`;
+    case "kv":
+      return `${escapeHtml3(doc.label)}: ${escapeHtml3(String(doc.value))}`;
+    case "code":
+      return `${escapeHtml3(doc.label)}: <code>${escapeHtml3(doc.content)}</code>`;
+    case "link":
+      return `${escapeHtml3(doc.label)}: ${escapeHtml3(doc.url)}`;
+    default:
+      return escapeHtml3(doc.kind);
+  }
+}
+function renderEvidenceArtifacts(testCase) {
+  const parts = [];
+  for (const att of testCase.attachments) {
+    if (att.mediaType.startsWith("image/") && att.contentEncoding === "BASE64") {
+      parts.push(
+        `<img class="shot" alt="${escapeHtml3(att.name)}" src="data:${escapeHtml3(att.mediaType)};base64,${att.body}" />`
+      );
+    }
+  }
+  if ((testCase.story.otelSpans?.length ?? 0) > 0) {
+    parts.push(
+      `<p class="trace-note">\u{1F4E1} ${testCase.story.otelSpans.length} OTEL span(s) captured</p>`
+    );
+  }
+  return parts.length > 0 ? `<div class="artifacts">${parts.join("")}</div>` : "";
+}
+function renderTicketPills(claim) {
+  const tickets = claim.testCase.story.tickets ?? [];
+  if (tickets.length === 0) return "";
+  return `<div class="ticket-row">${tickets.map((ticket) => {
+    const label = escapeHtml3(ticket.id);
+    if (ticket.url) {
+      return `<a class="ticket-pill" href="${escapeHtml3(ticket.url)}" target="_blank" rel="noopener noreferrer">${label}</a>`;
+    }
+    return `<span class="ticket-pill">${label}</span>`;
+  }).join("")}</div>`;
+}
+function renderClaimCard(claim) {
+  const ticketSearch = (claim.testCase.story.tickets ?? []).map((ticket) => ticket.id).join(" ");
+  const search = escapeHtml3(
+    `${claim.scenario} ${claim.sourceFile} ${claim.changeType} ${claim.audience} ${claim.strength} ${ticketSearch}`
+  ).toLowerCase();
+  const steps = claim.testCase.story.steps.length > 0 ? `<ul class="step-list">${claim.testCase.story.steps.map(formatStep3).join("")}</ul>` : "";
+  const reasons = `<ul class="reasons">${claim.strengthReasons.map((r) => `<li>${escapeHtml3(r)}</li>`).join("")}</ul>`;
+  const intent = claim.intent !== void 0 ? `<div class="intent"><span class="intent-label">Why</span> ${escapeHtml3(claim.intent)}</div>` : "";
+  const covers = claim.coversFiles.length > 0 ? `<p class="covers">Covers ${claim.coversFiles.map((f) => `<code>${escapeHtml3(f)}</code>`).join(", ")}</p>` : "";
+  const docs = (claim.testCase.story.docs ?? []).filter(
+    (d) => d.kind === "section" || d.kind === "note"
+  );
+  const extraDocs = docs.length > 0 && claim.intent === void 0 ? `<div class="intent">${docs.map(inlineDoc).join("<br>")}</div>` : "";
+  return `
+    <article class="claim-card" data-audience="${claim.audience}" data-strength="${claim.strength}" data-search="${search}">
+      <header class="claim-header">
+        <div>
+          <span class="strength-badge strength-${claim.strength}">${STRENGTH_LABEL[claim.strength]}</span>
+          ${claim.changeType !== "unknown" ? `<span class="change-pill">${escapeHtml3(claim.changeType)}</span>` : ""}
+          <h3>${statusIcon3(claim.status)} ${escapeHtml3(claim.scenario)}</h3>
+          <p class="source">${escapeHtml3(`${claim.sourceFile}:${claim.sourceLine}`)}</p>
+          ${renderTicketPills(claim)}
+        </div>
+      </header>
+      ${intent}${extraDocs}
+      <div class="evidence-block">
+        <span class="evidence-label">Evidence</span>
+        ${reasons}
+      </div>
+      ${covers}
+      ${renderEvidenceArtifacts(claim.testCase)}
+      ${steps}
+    </article>`;
+}
+function renderChangedFileRow(file) {
+  const claims = file.claims.length > 0 ? file.claims.map((c) => `${escapeHtml3(c.scenario)} <em>(${c.strength})</em>`).join(", ") : "\u2014";
+  return `<tr data-band="${file.band}">
+    <td><span class="band-dot band-${file.band}"></span></td>
+    <td><code>${escapeHtml3(file.path)}</code></td>
+    <td>${escapeHtml3(file.changeKind)}</td>
+    <td>${claims}</td>
+  </tr>`;
+}
+function renderAudienceSection2(title, claims) {
+  if (claims.length === 0) return "";
+  return `<section class="audience-section">
+    <h2>${escapeHtml3(title)} <span class="count">${claims.length}</span></h2>
+    <div class="claim-list">${claims.map(renderClaimCard).join("\n")}</div>
+  </section>`;
+}
+var REVIEW_CSS = `
+  * { box-sizing: border-box; }
+  body { margin: 0; font-family: var(--font-sans, system-ui, sans-serif); background: var(--background); color: var(--foreground); }
+  main { max-width: 1100px; margin: 0 auto; padding: 32px 20px 80px; }
+  h1, h2, h3, p { margin: 0; }
+  .review-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
+  .subtle { color: var(--muted-foreground); margin-top: 6px; }
+  .theme-toggle { background: var(--secondary); border: 1px solid var(--border); border-radius: 8px; padding: 8px 12px; cursor: pointer; font-size: 1.1rem; color: var(--foreground); }
+  .card, .claim-card, .summary-card, .panel { background: var(--card); border: 1px solid var(--border); border-radius: var(--radius, 16px); }
+  .hero-card { padding: 24px; margin-bottom: 20px; }
+  .summary-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 12px; margin-bottom: 20px; }
+  .summary-card { padding: 14px 16px; }
+  .summary-card strong { display: block; font-size: 1.8rem; }
+  .priority-banner { padding: 18px 20px; margin-bottom: 20px; background: linear-gradient(135deg, color-mix(in srgb, var(--destructive) 10%, transparent), var(--card)); }
+  .panel { padding: 18px; margin-bottom: 24px; }
+  table { width: 100%; border-collapse: collapse; }
+  th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid var(--border); vertical-align: top; }
+  th { color: var(--muted-foreground); font-weight: 600; }
+  .band-dot { display: inline-block; width: 12px; height: 12px; border-radius: 50%; }
+  .band-uncovered { background: var(--destructive); }
+  .band-weak { background: var(--warning, #b58900); }
+  .band-covered { background: var(--success, #2e7d32); }
+  .toolbar { position: sticky; top: 12px; z-index: 2; display: flex; flex-wrap: wrap; gap: 10px; padding: 14px; margin-bottom: 20px; }
+  .toolbar input { flex: 1 1 240px; border: 1px solid var(--border); border-radius: 999px; padding: 10px 14px; font: inherit; background: var(--background); color: var(--foreground); }
+  .toolbar button { border: 1px solid var(--border); background: var(--secondary); border-radius: 999px; padding: 10px 14px; font: inherit; cursor: pointer; color: var(--foreground); }
+  .toolbar button.active { background: var(--foreground); color: var(--background); }
+  .audience-section { margin-bottom: 28px; }
+  .audience-section h2 { margin-bottom: 12px; }
+  .count { color: var(--muted-foreground); font-weight: 400; }
+  .claim-list { display: grid; gap: 14px; }
+  .claim-card { padding: 18px; }
+  .claim-header h3 { margin-top: 8px; }
+  .source { color: var(--muted-foreground); font-family: var(--font-mono, ui-monospace, monospace); font-size: 0.85rem; margin-top: 4px; }
+  .ticket-row { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
+  .ticket-pill { display: inline-flex; align-items: center; border: 1px solid var(--border); border-radius: 999px; padding: 3px 9px; color: var(--muted-foreground); background: var(--background); font-size: 0.78rem; text-decoration: none; }
+  .ticket-pill:hover { color: var(--foreground); border-color: var(--muted-foreground); }
+  .strength-badge, .change-pill { display: inline-flex; align-items: center; padding: 3px 10px; border-radius: 999px; font-size: 0.8rem; margin-right: 6px; }
+  .change-pill { background: var(--secondary); }
+  .strength-strong { background: color-mix(in srgb, var(--success, #2e7d32) 18%, transparent); color: var(--success, #2e7d32); }
+  .strength-moderate { background: color-mix(in srgb, var(--warning, #b58900) 20%, transparent); color: var(--warning, #b58900); }
+  .strength-weak { background: color-mix(in srgb, #d2691e 20%, transparent); color: #b5530a; }
+  .strength-none { background: color-mix(in srgb, var(--destructive) 16%, transparent); color: var(--destructive); }
+  .intent { margin: 12px 0; padding: 10px 12px; border-left: 3px solid var(--border); background: color-mix(in srgb, var(--card) 60%, var(--background)); border-radius: 6px; }
+  .intent-label { font-weight: 700; margin-right: 6px; }
+  .evidence-block { margin-top: 10px; }
+  .evidence-label { font-weight: 600; color: var(--muted-foreground); }
+  .reasons { margin: 6px 0 0; padding-left: 18px; }
+  .covers { color: var(--muted-foreground); margin-top: 8px; font-size: 0.9rem; }
+  .artifacts { margin-top: 12px; display: flex; flex-wrap: wrap; gap: 10px; align-items: flex-start; }
+  .shot { max-width: 280px; max-height: 200px; border: 1px solid var(--border); border-radius: 8px; }
+  .trace-note { color: var(--muted-foreground); }
+  .step-list { margin: 12px 0 0; padding-left: 18px; color: var(--muted-foreground); }
+`;
+var JS_THEME_TOGGLE2 = `
+function getSystemTheme() { return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; }
+function getEffectiveTheme() { var s = localStorage.getItem('review-theme'); return (s === 'dark' || s === 'light') ? s : getSystemTheme(); }
+function toggleTheme() { var n = getEffectiveTheme() === 'dark' ? 'light' : 'dark'; localStorage.setItem('review-theme', n); applyTheme(n); }
+function applyTheme(t) {
+  document.documentElement.setAttribute('data-theme', t);
+  var b = document.querySelector('.theme-toggle');
+  if (b) { b.textContent = t === 'dark' ? '\\u2600\\ufe0f' : '\\ud83c\\udf19'; }
+}
+`;
+var ReviewHtmlFormatter = class {
+  title;
+  theme;
+  darkMode;
+  constructor(options = {}) {
+    this.title = options.title ?? "Evidence Review";
+    this.theme = resolveTheme(options.theme ?? "default");
+    this.darkMode = options.darkMode ?? true;
+  }
+  format(review) {
+    const { summary, context } = review;
+    const priority = summary.changedSourceFiles === 0 ? "No changed source files supplied \u2014 showing claims and evidence only." : summary.uncovered > 0 ? `${summary.uncovered} changed file(s) have no evidence. Review them first.` : summary.weaklyCovered > 0 ? `No unaccounted-for changes. ${summary.weaklyCovered} file(s) are weakly covered.` : "Every changed source file is backed by at least moderate evidence.";
+    const changedFilesPanel = summary.changedSourceFiles > 0 ? `<section class="panel">
+            <h2>Changed files</h2>
+            <table>
+              <thead><tr><th></th><th>File</th><th>Change</th><th>Evidence</th></tr></thead>
+              <tbody>${review.changedFiles.map(renderChangedFileRow).join("")}</tbody>
+            </table>
+          </section>` : "";
+    const themeToggleHtml = this.darkMode ? `<button type="button" class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme"></button>` : "";
+    const themeInitJs = this.darkMode ? `${JS_THEME_TOGGLE2}
+applyTheme(getEffectiveTheme());` : "";
+    const themeAttr = this.darkMode ? ' data-theme="light"' : "";
+    const refsLine = context.baseRef || context.headRef ? `<p class="subtle">Comparing ${escapeHtml3(context.baseRef ?? "base")} \u2192 ${escapeHtml3(context.headRef ?? "head")}</p>` : "";
+    return `<!doctype html>
+<html lang="en"${themeAttr}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml3(this.title)}</title>
+    <style>
+      ${this.theme.css}
+      ${REVIEW_CSS}
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="hero-card card">
+        <div class="review-header">
+          <h1>${escapeHtml3(this.title)}</h1>
+          ${themeToggleHtml}
+        </div>
+        ${refsLine}
+      </div>
+      <section class="summary-grid">
+        <div class="summary-card"><strong>${summary.uncovered}</strong><span>\u{1F534} Uncovered</span></div>
+        <div class="summary-card"><strong>${summary.weaklyCovered}</strong><span>\u{1F7E1} Weak</span></div>
+        <div class="summary-card"><strong>${summary.covered}</strong><span>\u{1F7E2} Covered</span></div>
+        <div class="summary-card"><strong>${summary.totalClaims}</strong><span>Claims</span></div>
+        <div class="summary-card"><strong>${summary.byStrength.strong}</strong><span>Strong</span></div>
+        <div class="summary-card"><strong>${summary.byStrength.weak + summary.byStrength.none}</strong><span>Weak/None</span></div>
+      </section>
+      <section class="card priority-banner">
+        <h2>Review priority</h2>
+        <p class="subtle">${escapeHtml3(priority)}</p>
+      </section>
+      ${changedFilesPanel}
+      <section class="toolbar">
+        <input type="search" placeholder="Filter claims by scenario, file, change-type" aria-label="Filter claims" />
+        <button type="button" class="active" data-filter="all">All</button>
+        <button type="button" data-filter="stakeholder">Stakeholder</button>
+        <button type="button" data-filter="engineer">Engineer</button>
+        <button type="button" data-filter="weak">Weak/None</button>
+      </section>
+      ${renderAudienceSection2("Stakeholder behaviour", review.claims.filter((c) => c.audience === "stakeholder"))}
+      ${renderAudienceSection2("Engineer changes", review.claims.filter((c) => c.audience === "engineer"))}
+    </main>
+    <script>
+      ${themeInitJs}
+      const input = document.querySelector('input[type="search"]');
+      const buttons = Array.from(document.querySelectorAll('[data-filter]'));
+      const cards = Array.from(document.querySelectorAll('.claim-card'));
+      let activeFilter = 'all';
+      function applyFilters() {
+        const query = (input.value || '').trim().toLowerCase();
+        cards.forEach((card) => {
+          const audience = card.getAttribute('data-audience');
+          const strength = card.getAttribute('data-strength');
+          const haystack = card.getAttribute('data-search') || '';
+          let matchesFilter = activeFilter === 'all'
+            || audience === activeFilter
+            || (activeFilter === 'weak' && (strength === 'weak' || strength === 'none'));
+          const matchesSearch = !query || haystack.includes(query);
+          card.style.display = matchesFilter && matchesSearch ? '' : 'none';
+        });
+      }
+      input.addEventListener('input', applyFilters);
+      buttons.forEach((button) => {
+        button.addEventListener('click', () => {
+          activeFilter = button.getAttribute('data-filter');
+          buttons.forEach((b) => b.classList.toggle('active', b === button));
+          applyFilters();
+        });
+      });
+      applyFilters();
+    </script>
+  </body>
+</html>`;
+  }
+};
+
 // src/index.ts
 var FORMAT_EXTENSIONS = {
   astro: ".md",
@@ -20096,6 +20788,8 @@ export {
   MIN_PERF_SAMPLES,
   MarkdownFormatter,
   ReportGenerator,
+  ReviewHtmlFormatter,
+  ReviewMarkdownFormatter,
   RunDiffHtmlFormatter,
   RunDiffMarkdownFormatter,
   STORY_META_KEY,
@@ -20106,6 +20800,7 @@ export {
   adaptPlaywrightRun,
   adaptVitestRun,
   assertValidRun,
+  buildReview,
   bundleAssets,
   calculateFlakiness,
   calculateStability,
@@ -20115,6 +20810,8 @@ export {
   copyMarkdownAssets,
   createPrCommentSummary,
   createReportGenerator,
+  deriveAudience,
+  deriveChangeType,
   deriveStepResults,
   detectCI4 as detectCI,
   detectPerformanceTrend,
@@ -20126,7 +20823,10 @@ export {
   generateTestCaseId,
   getAvailableThemes,
   getCssOnlyThemes,
+  gradeEvidence,
   hasSufficientHistory,
+  isReviewableSource,
+  isTestFile,
   listScenarios,
   loadHistory,
   mergeStepResults,