executable-stories-formatters 0.14.0 → 0.15.1

package/templates/astro-starlight/src/content/docs/guides/writing-docs.mdx

@@ -0,0 +1,49 @@
+---
+title: Writing hand-written docs
+description: How prose pages live alongside generated story docs.
+---
+
+This page is hand-written — proof that any author can add prose to the same site
+as the generated story docs, with the same navigation, search, and theming.
+
+## Where pages live
+
+- **Generated** story pages are written to `src/content/docs/stories/` by
+  `executable-stories build-docs reports/raw-run.json --site-dir .`. Don't edit
+  these by hand — they are regenerated from tests.
+- **Hand-written** pages (guides, ADRs, runbooks, incidents, API docs) live in
+  their own folders under `src/content/docs/`. They are never overwritten by a
+  regenerate.
+- **Scenario notes** live in `src/content/docs/notes/` and add stakeholder
+  context next to a specific scenario without editing the generated page. After
+  `build-docs`, the matching story page, the Explorer, and the `/stories/`
+  overview each link to the note automatically — no manual cross-linking.
+
+Both kinds share one sidebar, one search index, and one set of themes.
+
+If you scaffolded the site with `init-astro`, the template `.gitignore` already
+ignores the generated machine zone (`stories/` and `public/stories/*`) so git
+tracks your hand-written content by default, not the latest test run output.
+
+## Keep prose honest, too
+
+Hand-written pages can link to the tests that back them. Add `verifiedBy` to the
+frontmatter and a live badge appears under the title:
+
+```yaml
+---
+title: How transfers are priced
+verifiedBy: [pricing, transfer-fee]
+---
+```
+
+If a linked story starts failing, the badge turns red — so even your prose
+can't quietly drift away from the code.
+
+## Start from a template
+
+```bash
+executable-stories new adr "Cap combined discount at 30%"
+executable-stories new runbook "Restart the payments service"
+executable-stories new scenario-note "Checkout happy path" --scenario-id feature-checkout--happy-path
+```

package/templates/astro-starlight/src/content/docs/index.mdx

@@ -0,0 +1,49 @@
+---
+title: Story Docs
+description: Living documentation generated from your executable stories.
+---
+
+import HealthDashboard from '../../components/HealthDashboard.astro';
+
+<HealthDashboard />
+
+Living documentation for your whole team — product owners, testers, and
+engineers — generated from your executable stories and kept honest by the tests
+themselves. Works the same whether your stories are written in TypeScript,
+Python, Go, Ruby, Java/Kotlin, Rust, or C#: it all flows through one report.
+
+## Trust model
+
+- **Proven** — generated story pages and Explorer data come from the latest test run.
+- **Commentary** — guides, ADRs, runbooks, incidents, and notes are hand-written context.
+- **Linked** — add `verifiedBy` to commentary pages to show which stories still prove them.
+- **Stale** — failing or missing proof shows up as a badge; it is surfaced, not hidden.
+
+## What you can do here
+
+- **Browse stories** — the [Scenario Explorer](/explorer/) is a searchable, filterable
+  view of every executable story.
+- **Verify any page** — add `verifiedBy: [story-id]` to a page's frontmatter and a
+  live badge shows whether the tests that prove it currently pass.
+- **Start from a template** — `executable-stories new adr "…"` (also `runbook`,
+  `decision-log`, `incident`, `scenario-note`), each pre-wired to verifying stories.
+- **Document your API** — `executable-stories import-openapi spec.json --run story-report.json`
+  generates endpoint pages with a coverage badge per route.
+- **Keep links honest** — `executable-stories check-links src/content/docs` fails CI
+  on broken links.
+
+## Getting started
+
+Generate the behavior portal from any test run:
+
+```bash
+# run your tests first (StoryReporter writes reports/raw-run.json), then:
+executable-stories build-docs reports/raw-run.json --site-dir .
+# add --audience-split to split pages into business vs technical URLs
+```
+
+Then start the dev server:
+
+```bash
+npm run dev
+```

package/templates/astro-starlight/src/content.config.ts

@@ -0,0 +1,18 @@
+import { defineCollection } from 'astro:content';
+import { z } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({
+    loader: docsLoader(),
+    // `verifiedBy` links a page to the stories that prove it is still true.
+    // The PageTitle override renders a live verification badge from it.
+    schema: docsSchema({
+      extend: z.object({
+        verifiedBy: z.union([z.string(), z.array(z.string())]).optional(),
+        scenarioId: z.string().optional(),
+      }),
+    }),
+  }),
+};

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

@@ -0,0 +1,50 @@
+/**
+ * Site configuration — the one place to point at your test-run data.
+ *
+ * The verification badges, runbook checklists, and health dashboard read the
+ * latest run at build time (`report`); the Scenario Explorer fetches the same
+ * file in the browser (`REPORT_URL`). If you move the report, change it here —
+ * nowhere else references the path.
+ *
+ * Generate the report with (writes public/stories/story-report.json for you):
+ *   executable-stories build-docs reports/raw-run.json --site-dir .
+ *
+ * `report` (build-time import) and `REPORT_URL` (runtime fetch) must point at
+ * the same file — one is a filesystem path, the other the URL it's served at.
+ */
+import reportData from "../../public/stories/story-report.json";
+import type { StoryReportLike } from "./verification";
+
+/** The latest test run, imported at build time (badges, checklist, dashboard). */
+export const report = reportData as StoryReportLike;
+
+/**
+ * Public URL the Scenario Explorer fetches the run from at runtime.
+ * Override per-environment with `PUBLIC_STORY_REPORT_URL` in a `.env` file.
+ */
+export const REPORT_URL: string =
+  import.meta.env.PUBLIC_STORY_REPORT_URL ?? "/stories/story-report.json";
+
+/** Public URL the Explorer fetches the scenario-note index from at runtime. */
+export const NOTES_INDEX_URL: string =
+  import.meta.env.PUBLIC_NOTES_INDEX_URL ?? "/stories/notes-index.json";
+
+/**
+ * Base URL of the source repository (e.g. https://github.com/acme/app/blob/main).
+ * When set, the Scenario Explorer turns each scenario's file path into a link to
+ * the test on your git host. Leave unset to fall back to an in-page anchor.
+ * Override with `PUBLIC_SOURCE_BASE_URL` in a `.env` file.
+ */
+export const SOURCE_BASE_URL: string =
+  import.meta.env.PUBLIC_SOURCE_BASE_URL ?? "";
+
+/**
+ * Deep-link to a single story inside the Scenario Explorer. Used by the
+ * verification badge and the API coverage table so "verified by X" always
+ * takes you to X. Respects Astro's configured `base`.
+ */
+export function explorerUrl(storyId: string): string {
+  const base = import.meta.env.BASE_URL ?? "/";
+  const prefix = base.endsWith("/") ? base : `${base}/`;
+  return `${prefix}explorer/#${encodeURIComponent(storyId)}`;
+}

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",
+      };
+  }
+}