executable-stories-formatters 0.15.0 → 0.15.1

package/templates/astro-starlight/src/lib/render-doc-entry.ts

@@ -0,0 +1,154 @@
+/**
+ * Pure doc-entry → HTML renderer for the Scenario Explorer.
+ *
+ * The Explorer builds its detail pane from the story report at runtime; this is
+ * the string-building logic behind it, kept DOM-free so it can be unit-tested
+ * and so the page file stays a thin shell. Markdown/diagrams/code are emitted as
+ * placeholder markup (`data-md`, `.mermaid`, `language-*`) that the Explorer
+ * hydrates with the bundled marked/mermaid/highlight.js libraries.
+ *
+ * Mirrors the doc kinds in the formatter's HTML renderer
+ * (src/formatters/html/renderers/doc-entries.ts) but emits the Explorer's own
+ * card markup. `tag` is intentionally skipped — tags render as header pills.
+ */
+
+/** Loose structural shape of a story-report doc entry (template is decoupled from the package types). */
+export interface DocEntry {
+  kind: string;
+  text?: string;
+  label?: string;
+  value?: unknown;
+  lang?: string;
+  content?: string;
+  columns?: string[];
+  rows?: string[][];
+  url?: string;
+  title?: string;
+  markdown?: string;
+  code?: string;
+  path?: string;
+  alt?: string;
+  poster?: string;
+  caption?: string;
+  type?: string;
+  data?: unknown;
+  children?: DocEntry[];
+}
+
+export function escapeHtml(value: unknown): string {
+  return String(value ?? "")
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+const isRemote = (p: string): boolean => /^(?:https?:|data:)/i.test(p);
+const isWindowsFsPath = (p: string): boolean => /^(?:[A-Za-z]:[\\/]|\\\\)/.test(p);
+
+const mediaCaption = (text: string | undefined): string =>
+  text ? `<div class="doc-media__caption">${escapeHtml(text)}</div>` : "";
+
+const broken = (kind: string, p: string): string =>
+  `<div class="doc-media doc-media--broken">${kind} unavailable<code>${escapeHtml(p)}</code></div>`;
+
+const renderScreenshot = (entry: DocEntry): string => {
+  const path = entry.path ?? "";
+  if (isWindowsFsPath(path)) return broken("Screenshot", path);
+  return `<div class="doc-media"><img src="${escapeHtml(path)}" alt="${escapeHtml(
+    entry.alt ?? "Screenshot",
+  )}" loading="lazy" />${mediaCaption(entry.alt)}</div>`;
+};
+
+const renderVideo = (entry: DocEntry): string => {
+  const path = entry.path ?? "";
+  if (!isRemote(path) && isWindowsFsPath(path)) return broken("Video", path);
+  const poster = entry.poster ? ` poster="${escapeHtml(entry.poster)}"` : "";
+  return `<div class="doc-media"><video controls preload="metadata"${poster} src="${escapeHtml(
+    path,
+  )}">Your browser cannot play this video.</video>${mediaCaption(entry.caption)}</div>`;
+};
+
+/** A labelled card wrapper used by most doc kinds. */
+const labelled = (label: string, bodyHtml: string): string =>
+  `<div class="doc-entry"><div class="doc-entry__label">${escapeHtml(
+    label,
+  )}</div><div class="doc-entry__body">${bodyHtml}</div></div>`;
+
+const renderVisualCustom = (data: Record<string, unknown>): string => {
+  const img = (src: unknown, label: string): string =>
+    typeof src === "string"
+      ? `<div class="doc-visual-item"><div class="doc-visual-label">${escapeHtml(
+          label,
+        )}</div><img src="${escapeHtml(src)}" alt="${escapeHtml(label)}" /></div>`
+      : "";
+  return labelled(
+    `Visual check · ${escapeHtml(typeof data.status === "string" ? data.status : "unknown")}`,
+    `<div class="doc-visual-grid">${img(data.baseline, "Baseline")}${img(data.actual, "Actual")}${img(
+      data.diff,
+      "Diff",
+    )}</div>`,
+  );
+};
+
+const RENDERERS: Record<string, (doc: DocEntry) => string> = {
+  // Tags already render as pills in the header — skip the noise.
+  tag: () => "",
+  note: (doc) => `<div class="doc-entry"><div class="doc-note">${escapeHtml(doc.text)}</div></div>`,
+  kv: (doc) => {
+    const value = typeof doc.value === "string" ? doc.value : JSON.stringify(doc.value, null, 2);
+    return `<div class="doc-entry"><div class="doc-kv"><span class="doc-kv__label">${escapeHtml(
+      doc.label,
+    )}</span><span class="doc-kv__value">${escapeHtml(value)}</span></div></div>`;
+  },
+  code: (doc) => {
+    const langClass = doc.lang ? ` class="language-${escapeHtml(doc.lang)}"` : "";
+    return labelled(
+      doc.label || doc.lang || "code",
+      `<pre><code${langClass}>${escapeHtml(doc.content)}</code></pre>`,
+    );
+  },
+  table: (doc) => {
+    const head = (doc.columns ?? []).map((c) => `<th>${escapeHtml(c)}</th>`).join("");
+    const body = (doc.rows ?? [])
+      .map((r) => `<tr>${r.map((c) => `<td>${escapeHtml(c)}</td>`).join("")}</tr>`)
+      .join("");
+    return labelled(
+      doc.label || "table",
+      `<table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`,
+    );
+  },
+  link: (doc) =>
+    `<div class="doc-entry"><a class="doc-link-a" href="${escapeHtml(
+      doc.url,
+    )}" target="_blank" rel="noopener noreferrer">${escapeHtml(doc.label || doc.url)}</a></div>`,
+  section: (doc) =>
+    labelled(
+      doc.title || "section",
+      `<div class="doc-section-content" data-md="${escapeHtml(
+        encodeURIComponent(doc.markdown ?? ""),
+      )}"><pre>${escapeHtml(doc.markdown ?? "")}</pre></div>`,
+    ),
+  mermaid: (doc) =>
+    labelled(doc.title || "diagram", `<pre class="mermaid">${escapeHtml(doc.code ?? "")}</pre>`),
+  screenshot: (doc) => `<div class="doc-entry"><div class="doc-entry__body">${renderScreenshot(doc)}</div></div>`,
+  video: (doc) => `<div class="doc-entry"><div class="doc-entry__body">${renderVideo(doc)}</div></div>`,
+  custom: (doc) =>
+    doc.type === "visual" && doc.data && typeof doc.data === "object"
+      ? renderVisualCustom(doc.data as Record<string, unknown>)
+      : labelled(doc.type || "custom", `<pre><code>${escapeHtml(JSON.stringify(doc.data, null, 2))}</code></pre>`),
+};
+
+export function renderDocEntry(doc: DocEntry): string {
+  let html = RENDERERS[doc.kind]?.(doc) ?? "";
+  if (html && doc.children && doc.children.length > 0) {
+    const childHtml = doc.children.map(renderDocEntry).join("");
+    if (childHtml) html += `<div class="doc-children">${childHtml}</div>`;
+  }
+  return html;
+}
+
+export function renderDocs(docs: DocEntry[] | undefined): string {
+  if (!docs?.length) return '<p class="meta">No docs attached.</p>';
+  return docs.map(renderDocEntry).join("") || '<p class="meta">No docs attached.</p>';
+}

package/templates/astro-starlight/src/lib/report-health.ts

@@ -0,0 +1,61 @@
+/**
+ * Health summary for the dashboard landing page.
+ *
+ * Confluence dashboards are the first thing a team sees and they are static.
+ * This one is computed from the latest test run, so the home page always
+ * reflects whether the documented system is actually green right now.
+ *
+ * Pure (no Astro imports) so it can be unit-tested.
+ */
+
+import { flattenReport, type StoryReportLike, type ScenarioLike } from "./verification";
+
+export interface FailingScenario {
+  id: string;
+  title: string;
+  feature?: string;
+  sourceFile?: string;
+}
+
+export interface HealthSummary {
+  total: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  pending: number;
+  /** Passed / total, 0..1 (0 when there are no scenarios). */
+  passRate: number;
+  lastRunMs?: number;
+  runId?: string;
+  failing: FailingScenario[];
+  /** True when no run has populated the report yet. */
+  empty: boolean;
+}
+
+export function summarizeHealth(report: StoryReportLike): HealthSummary {
+  const scenarios: ScenarioLike[] = flattenReport(report);
+  const count = (status: string) => scenarios.filter((s) => s.status === status).length;
+
+  const passed = count("passed");
+  const failed = count("failed");
+  const skipped = count("skipped");
+  const pending = count("pending");
+  const total = scenarios.length;
+
+  const failing: FailingScenario[] = scenarios
+    .filter((s) => s.status === "failed")
+    .map((s) => ({ id: s.id, title: s.title, feature: s.feature, sourceFile: s.sourceFile }));
+
+  return {
+    total,
+    passed,
+    failed,
+    skipped,
+    pending,
+    passRate: total > 0 ? passed / total : 0,
+    lastRunMs: report.finishedAtMs && report.finishedAtMs > 0 ? report.finishedAtMs : undefined,
+    runId: report.runId && report.runId.length > 0 ? report.runId : undefined,
+    failing,
+    empty: total === 0,
+  };
+}

package/templates/astro-starlight/src/lib/verification.ts

@@ -0,0 +1,247 @@
+/**
+ * verified-by resolver — the core of living documentation.
+ *
+ * A docs page declares which stories prove it is still true:
+ *
+ *   ---
+ *   title: ADR 0007 — Cap combined discount at 30%
+ *   verifiedBy: [checkout--caps-the-discount-at-30-percent, pricing]
+ *   ---
+ *
+ * At build time each reference is resolved against the latest test run
+ * (story-report.json) so the page renders a live status badge. If the
+ * referenced story is missing or failing, the page says so loudly — that is
+ * the mechanism that stops documentation from rotting.
+ *
+ * This module is intentionally free of any Astro/runtime imports so it can be
+ * unit-tested in isolation and reused anywhere.
+ */
+
+export type ScenarioStatus = "passed" | "failed" | "skipped" | "pending";
+
+/** Overall verification verdict for a set of references. */
+export type VerificationStatus =
+  /** Every matched story passed in the last run. */
+  | "verified"
+  /** At least one matched story failed. */
+  | "failing"
+  /** Stories matched but some were skipped/pending — not actually exercised. */
+  | "not-run"
+  /** No story matched — the page references something that doesn't exist. */
+  | "unverified";
+
+export interface ScenarioLike {
+  id: string;
+  title: string;
+  status: ScenarioStatus;
+  tags?: string[];
+  tickets?: Array<{ id: string; url?: string }>;
+  /** Feature title (filled in when flattening a report). */
+  feature?: string;
+  sourceFile?: string;
+  sourceLine?: number;
+}
+
+export interface StoryReportLike {
+  runId?: string;
+  finishedAtMs?: number;
+  features?: Array<{
+    title?: string;
+    sourceFile?: string;
+    scenarios?: ScenarioLike[];
+  }>;
+}
+
+/** Per-reference resolution: which scenarios a single `verifiedBy` entry matched. */
+export interface RefResolution {
+  ref: string;
+  matched: ScenarioLike[];
+}
+
+export interface VerificationResult {
+  status: VerificationStatus;
+  /** Run finish time, used as the "last verified" timestamp. */
+  lastVerifiedMs?: number;
+  runId?: string;
+  /** Number of distinct scenarios matched across all references. */
+  total: number;
+  passed: number;
+  failed: number;
+  /** skipped + pending. */
+  notRun: number;
+  refs: RefResolution[];
+  /** References that matched no scenario at all. */
+  missingRefs: string[];
+}
+
+/** Flatten a story report into a single list of scenarios with feature context. */
+export function flattenReport(report: StoryReportLike): ScenarioLike[] {
+  const features = report.features ?? [];
+  return features.flatMap((feature) =>
+    (feature.scenarios ?? []).map((scenario) => ({
+      ...scenario,
+      feature: scenario.feature ?? feature.title,
+      sourceFile: scenario.sourceFile ?? feature.sourceFile,
+    })),
+  );
+}
+
+/** Resolve a single scenario id against the latest report. */
+export function findScenarioById(
+  report: StoryReportLike,
+  scenarioId: string,
+): ScenarioLike | undefined {
+  return flattenReport(report).find((scenario) => scenario.id === scenarioId);
+}
+
+/** Convenience check for human-authored pages that point at one scenario id. */
+export function hasScenarioId(report: StoryReportLike, scenarioId: string): boolean {
+  return findScenarioById(report, scenarioId) !== undefined;
+}
+
+/** Does a single reference identify this scenario? id, tag, ticket id, or exact title. */
+function scenarioMatchesRef(scenario: ScenarioLike, ref: string): boolean {
+  if (scenario.id === ref) return true;
+  if (scenario.title === ref) return true;
+  if ((scenario.tags ?? []).includes(ref)) return true;
+  if ((scenario.tickets ?? []).some((ticket) => ticket.id === ref)) return true;
+  return false;
+}
+
+function toRefArray(refs: string | string[]): string[] {
+  const list = Array.isArray(refs) ? refs : [refs];
+  // Trim, drop empties, de-duplicate while preserving order.
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const raw of list) {
+    const ref = raw.trim();
+    if (ref && !seen.has(ref)) {
+      seen.add(ref);
+      out.push(ref);
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve `verifiedBy` references against a story report.
+ *
+ * Status semantics (deliberately strict — a doc is only "verified" when the
+ * evidence actually passed):
+ *   - any matched scenario failed            → "failing"
+ *   - every matched scenario passed          → "verified"
+ *   - matched but some skipped/pending       → "not-run"
+ *   - nothing matched                        → "unverified"
+ */
+export function resolveVerification(
+  refs: string | string[],
+  report: StoryReportLike,
+): VerificationResult {
+  const refList = toRefArray(refs);
+  const scenarios = flattenReport(report);
+
+  const refResolutions: RefResolution[] = refList.map((ref) => ({
+    ref,
+    matched: scenarios.filter((scenario) => scenarioMatchesRef(scenario, ref)),
+  }));
+
+  // De-duplicate matched scenarios across references (a tag + id can overlap).
+  const matchedById = new Map<string, ScenarioLike>();
+  for (const resolution of refResolutions) {
+    for (const scenario of resolution.matched) {
+      matchedById.set(scenario.id, scenario);
+    }
+  }
+  const matched = [...matchedById.values()];
+
+  const passed = matched.filter((s) => s.status === "passed").length;
+  const failed = matched.filter((s) => s.status === "failed").length;
+  const notRun = matched.filter(
+    (s) => s.status === "skipped" || s.status === "pending",
+  ).length;
+
+  let status: VerificationStatus;
+  if (matched.length === 0) {
+    status = "unverified";
+  } else if (failed > 0) {
+    status = "failing";
+  } else if (notRun > 0) {
+    status = "not-run";
+  } else {
+    status = "verified";
+  }
+
+  return {
+    status,
+    lastVerifiedMs: report.finishedAtMs && report.finishedAtMs > 0 ? report.finishedAtMs : undefined,
+    runId: report.runId && report.runId.length > 0 ? report.runId : undefined,
+    total: matched.length,
+    passed,
+    failed,
+    notRun,
+    refs: refResolutions,
+    missingRefs: refResolutions.filter((r) => r.matched.length === 0).map((r) => r.ref),
+  };
+}
+
+export interface StatusPresentation {
+  label: string;
+  icon: string;
+  /** Short human sentence describing the verdict. */
+  summary: string;
+}
+
+/** Whole days since the verification run completed, if known. */
+export function verificationAgeDays(
+  result: VerificationResult,
+  nowMs = Date.now(),
+): number | undefined {
+  if (!result.lastVerifiedMs) return undefined;
+  return Math.floor(Math.max(0, nowMs - result.lastVerifiedMs) / 86_400_000);
+}
+
+/** Simple freshness heuristic for portal UI warnings. */
+export function isVerificationStale(
+  result: VerificationResult,
+  staleAfterDays: number,
+  nowMs = Date.now(),
+): boolean {
+  const ageDays = verificationAgeDays(result, nowMs);
+  return ageDays !== undefined && ageDays >= staleAfterDays;
+}
+
+/** Presentation metadata for each status — kept here so badge + tests agree. */
+export function presentStatus(result: VerificationResult): StatusPresentation {
+  switch (result.status) {
+    case "verified":
+      return {
+        label: "Verified",
+        icon: "✓",
+        summary:
+          result.total === 1
+            ? "Verified by a passing story"
+            : `Verified by ${result.total} passing stories`,
+      };
+    case "failing":
+      return {
+        label: "Failing",
+        icon: "✕",
+        summary: `${result.failed} of ${result.total} verifying stories are failing`,
+      };
+    case "not-run":
+      return {
+        label: "Not run",
+        icon: "⏳",
+        summary: "Verifying stories exist but were not exercised in the last run",
+      };
+    case "unverified":
+      return {
+        label: "Unverified",
+        icon: "⚠",
+        summary:
+          result.missingRefs.length > 0
+            ? `No story matches: ${result.missingRefs.join(", ")}`
+            : "No verifying story is linked",
+      };
+  }
+}