executable-stories-formatters 0.14.0 → 0.15.1

package/templates/astro-starlight/src/components/HealthDashboard.astro

@@ -0,0 +1,171 @@
+---
+/**
+ * <HealthDashboard /> — a living landing widget.
+ *
+ * Reads the latest run at build time and shows pass rate, counts, freshness,
+ * and any failing stories. Drop it at the top of the home page so the first
+ * thing a stakeholder sees is whether the documented system is green.
+ */
+import { report } from "../lib/config";
+import { summarizeHealth, type FailingScenario } from "../lib/report-health";
+
+const health = summarizeHealth(report);
+const passPct = Math.round(health.passRate * 100);
+const lastRun = health.lastRunMs
+  ? new Date(health.lastRunMs).toLocaleString(undefined, {
+      dateStyle: "medium",
+      timeStyle: "short",
+    })
+  : null;
+
+const overall = health.empty
+  ? "empty"
+  : health.failed > 0
+    ? "failing"
+    : "healthy";
+
+const metrics: Array<{ label: string; value: string | number }> = [
+  { label: "Pass rate", value: health.empty ? "—" : `${passPct}%` },
+  { label: "Scenarios", value: health.total },
+  { label: "Passed", value: health.passed },
+  { label: "Failed", value: health.failed },
+];
+
+const failing: FailingScenario[] = health.failing;
+---
+
+<section class:list={["health", `health--${overall}`]} aria-label="Test health dashboard">
+  <header class="health__head">
+    <span class="health__dot" aria-hidden="true"></span>
+    <strong class="health__title">
+      {health.empty ? "No test run yet" : health.failed > 0 ? "Attention needed" : "All systems documented & passing"}
+    </strong>
+    {lastRun && <span class="health__meta">last run {lastRun}</span>}
+  </header>
+
+  <div class="health__metrics">
+    {
+      metrics.map((m) => (
+        <div class="health__metric">
+          <span class="health__metric-value">{m.value}</span>
+          <span class="health__metric-label">{m.label}</span>
+        </div>
+      ))
+    }
+  </div>
+
+  {
+    health.empty && (
+      <p class="health__hint">
+        Generate a run with <code>executable-stories build-docs reports/raw-run.json --site-dir .</code> to light up this dashboard.
+      </p>
+    )
+  }
+
+  {
+    failing.length > 0 && (
+      <details class="health__failing" open>
+        <summary>{failing.length} failing {failing.length === 1 ? "story" : "stories"}</summary>
+        <ul>
+          {failing.map((f) => (
+            <li>
+              <span class="health__failing-title">{f.title}</span>
+              {f.feature && <span class="health__failing-feature"> · {f.feature}</span>}
+            </li>
+          ))}
+        </ul>
+      </details>
+    )
+  }
+</section>
+
+<style>
+  .health {
+    --health-accent: var(--sl-color-gray-3);
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.75rem;
+    padding: 1.25rem 1.5rem;
+    margin: 0 0 2rem;
+    background: var(--sl-color-gray-7, var(--sl-color-gray-6));
+  }
+  .health--healthy {
+    --health-accent: #16a34a;
+  }
+  .health--failing {
+    --health-accent: #dc2626;
+  }
+  .health--empty {
+    --health-accent: #d97706;
+  }
+  .health__head {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    margin-bottom: 1rem;
+  }
+  .health__dot {
+    width: 0.7rem;
+    height: 0.7rem;
+    border-radius: 999px;
+    background: var(--health-accent);
+    flex: none;
+  }
+  .health__title {
+    font-size: var(--sl-text-lg);
+  }
+  .health__meta {
+    margin-left: auto;
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-xs);
+  }
+  .health__metrics {
+    display: grid;
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+    gap: 0.75rem;
+  }
+  .health__metric {
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.5rem;
+    padding: 0.75rem;
+    text-align: center;
+    background: var(--sl-color-black, transparent);
+  }
+  .health__metric-value {
+    display: block;
+    font-size: var(--sl-text-2xl);
+    font-weight: 700;
+    line-height: 1;
+  }
+  .health__metric-label {
+    display: block;
+    margin-top: 0.35rem;
+    font-size: var(--sl-text-xs);
+    color: var(--sl-color-gray-3);
+  }
+  .health__hint {
+    margin: 1rem 0 0;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-2);
+  }
+  .health__failing {
+    margin-top: 1rem;
+  }
+  .health__failing > summary {
+    cursor: pointer;
+    color: #dc2626;
+    font-weight: 600;
+  }
+  .health__failing ul {
+    margin: 0.5rem 0 0;
+    padding-left: 1.1rem;
+  }
+  .health__failing-feature {
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-sm);
+  }
+  @media (max-width: 640px) {
+    .health__metrics {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+  }
+</style>

package/templates/astro-starlight/src/components/PageTitle.astro

@@ -0,0 +1,53 @@
+---
+/**
+ * Starlight PageTitle override.
+ *
+ * Renders the default page title, then — if the page declares `verifiedBy` in
+ * its frontmatter — a live verification badge underneath it. Any page (ADR,
+ * runbook, hand-written prose) gets the badge for free, no component import.
+ */
+import Default from '@astrojs/starlight/components/PageTitle.astro';
+import { report } from '../lib/config';
+import { hasScenarioId } from '../lib/verification';
+import VerifiedBy from './VerifiedBy.astro';
+
+const verifiedBy = Astro.locals.starlightRoute?.entry?.data?.verifiedBy;
+const scenarioId = Astro.locals.starlightRoute?.entry?.data?.scenarioId;
+const hasVerifiedBy = Object.prototype.hasOwnProperty.call(
+  Astro.locals.starlightRoute?.entry?.data ?? {},
+  "verifiedBy",
+);
+const staleScenarioNote =
+  typeof scenarioId === "string" && scenarioId.length > 0 && !hasScenarioId(report, scenarioId);
+---
+
+<Default><slot /></Default>
+{hasVerifiedBy && <VerifiedBy refs={verifiedBy ?? []} />}
+{
+  staleScenarioNote && (
+    <p class="scenario-note-stale">
+      Stale note: scenario <code>{scenarioId}</code> is not present in the latest test run.
+    </p>
+  )
+}
+
+<style>
+  .scenario-note-stale {
+    margin: -0.75rem 0 1.75rem;
+    padding: 0.65rem 0.9rem;
+    border: 1px solid var(--es-line);
+    border-left: 3px solid var(--es-unverified);
+    border-radius: var(--es-radius);
+    background: var(--es-skipped-soft);
+    color: var(--es-text);
+    font-size: var(--sl-text-xs);
+    font-weight: 600;
+  }
+
+  .scenario-note-stale code {
+    background: var(--es-bg);
+    border: 1px solid var(--es-line);
+    border-radius: 0.25rem;
+    padding: 0.05rem 0.35rem;
+  }
+</style>

package/templates/astro-starlight/src/components/VerifiedBy.astro

@@ -0,0 +1,281 @@
+---
+/**
+ * <VerifiedBy refs={["story-id", "tag", "TICKET-1"]} />
+ *
+ * Renders a live verification badge for a docs page. Each reference is resolved
+ * at build time against the latest test run (see src/lib/config.ts):
+ * a passing story shows "Verified", a failing one shows "Failing", and a
+ * reference that matches nothing shows "Unverified" — so a page can never
+ * quietly claim something the tests no longer prove.
+ *
+ * Every matched story is a link straight into the Scenario Explorer, so a
+ * reader can go from "verified by X" to X — its steps, docs and video — in one
+ * click. Unresolved references are called out by name so they get fixed.
+ *
+ * Use it directly in MDX, or set `verifiedBy:` in page frontmatter and let the
+ * PageTitle override render it automatically.
+ */
+import { report, explorerUrl } from "../lib/config";
+import {
+  resolveVerification,
+  presentStatus,
+  verificationAgeDays,
+  isVerificationStale,
+} from "../lib/verification";
+import type { ScenarioLike } from "../lib/verification";
+
+interface Props {
+  refs: string | string[];
+}
+
+const { refs } = Astro.props;
+const result = resolveVerification(refs, report);
+const present = presentStatus(result);
+const staleAfterDays = Number(import.meta.env.PUBLIC_VERIFICATION_STALE_DAYS ?? 14);
+const ageDays = verificationAgeDays(result);
+const ageWarning = Number.isFinite(staleAfterDays)
+  ? isVerificationStale(result, staleAfterDays)
+  : false;
+
+// Flatten the per-reference matches into a single de-duplicated story list so
+// the badge lists stories (the thing a reader cares about), not raw refs.
+const matched: ScenarioLike[] = [];
+const seen = new Set<string>();
+for (const resolution of result.refs) {
+  for (const scenario of resolution.matched) {
+    if (seen.has(scenario.id)) continue;
+    seen.add(scenario.id);
+    matched.push(scenario);
+  }
+}
+
+const statusVerb: Record<string, string> = {
+  passed: "passed",
+  failed: "failed",
+  skipped: "skipped",
+  pending: "pending",
+};
+
+const lastVerified = result.lastVerifiedMs
+  ? new Date(result.lastVerifiedMs).toLocaleDateString(undefined, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+    })
+  : null;
+---
+
+<aside
+  class:list={["verified-by", `verified-by--${result.status}`]}
+  aria-label={`Verification status: ${present.label}`}
+>
+  <div class="verified-by__head">
+    <span class="verified-by__icon" aria-hidden="true">{present.icon}</span>
+    <span class="verified-by__label">{present.label}</span>
+    <span class="verified-by__summary">{present.summary}</span>
+    {lastVerified && (
+      <span class="verified-by__meta">
+        verified {lastVerified}
+        {typeof ageDays === "number" ? ` · ${ageDays}d ago` : ""}
+      </span>
+    )}
+  </div>
+
+  {
+    ageWarning && (
+      <p class="verified-by__age-warning">
+        Verification is {ageDays} days old. Rerun the stories if freshness matters.
+      </p>
+    )
+  }
+
+  {
+    matched.length > 0 && (
+      <ul class="verified-by__stories">
+        {matched.map((scenario) => (
+          <li>
+            <a class:list={["vb-story", `vb-story--${scenario.status}`]} href={explorerUrl(scenario.id)}>
+              <span class="vb-story__dot" aria-hidden="true" />
+              <span class="vb-story__title">{scenario.title}</span>
+              <span class="vb-story__status">{statusVerb[scenario.status] ?? scenario.status}</span>
+              <span class="vb-story__go" aria-hidden="true">→</span>
+            </a>
+          </li>
+        ))}
+      </ul>
+    )
+  }
+
+  {
+    result.missingRefs.length > 0 && (
+      <p class="verified-by__missing">
+        No story matches{" "}
+        {result.missingRefs.map((ref, i) => (
+          <>
+            {i > 0 && ", "}
+            <code>{ref}</code>
+          </>
+        ))}
+        {" "}— check the reference or add a verifying story.
+      </p>
+    )
+  }
+</aside>
+
+<style>
+  .verified-by {
+    --vb-accent: var(--es-text-muted);
+    --vb-soft: var(--es-surface);
+    border: 1px solid var(--es-line);
+    border-left: 3px solid var(--vb-accent);
+    border-radius: var(--es-radius);
+    background: var(--vb-soft);
+    padding: 0.85rem 1.1rem;
+    margin: 1rem 0 1.75rem;
+    font-size: var(--sl-text-sm);
+  }
+
+  .verified-by--verified {
+    --vb-accent: var(--es-passed);
+    --vb-soft: var(--es-passed-soft);
+  }
+  .verified-by--failing {
+    --vb-accent: var(--es-failed);
+    --vb-soft: var(--es-failed-soft);
+  }
+  .verified-by--not-run {
+    --vb-accent: var(--es-skipped);
+    --vb-soft: var(--es-skipped-soft);
+  }
+  .verified-by--unverified {
+    --vb-accent: var(--es-unverified);
+    --vb-soft: var(--es-skipped-soft);
+  }
+
+  .verified-by__head {
+    display: flex;
+    align-items: baseline;
+    flex-wrap: wrap;
+    gap: 0.55rem;
+  }
+
+  .verified-by__icon {
+    color: var(--vb-accent);
+    font-weight: 700;
+  }
+
+  .verified-by__label {
+    font-weight: 700;
+    color: var(--vb-accent);
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    font-size: var(--sl-text-xs);
+  }
+
+  .verified-by__summary {
+    color: var(--es-text);
+  }
+
+  .verified-by__meta {
+    margin-left: auto;
+    color: var(--es-text-muted);
+    font-size: var(--sl-text-xs);
+    white-space: nowrap;
+  }
+
+  .verified-by__stories {
+    list-style: none;
+    margin: 0.85rem 0 0;
+    padding: 0;
+    display: grid;
+    gap: 0.4rem;
+  }
+
+  .vb-story {
+    display: grid;
+    grid-template-columns: auto 1fr auto auto;
+    align-items: center;
+    gap: 0.6rem;
+    padding: 0.5rem 0.7rem;
+    border: 1px solid var(--es-line);
+    border-radius: var(--es-radius-sm);
+    background: var(--es-bg);
+    color: var(--es-text);
+    text-decoration: none;
+    transition: border-color 120ms ease, background-color 120ms ease, transform 120ms ease;
+  }
+
+  .vb-story:hover {
+    border-color: var(--vb-accent);
+    background: var(--vb-soft);
+  }
+
+  .vb-story:focus-visible {
+    outline: 2px solid var(--vb-accent);
+    outline-offset: 2px;
+  }
+
+  .vb-story:hover .vb-story__go {
+    transform: translateX(2px);
+    opacity: 1;
+  }
+
+  .vb-story__dot {
+    width: 0.5rem;
+    height: 0.5rem;
+    border-radius: 50%;
+    background: var(--vb-dot, var(--es-text-muted));
+  }
+  .vb-story--passed {
+    --vb-dot: var(--es-passed);
+  }
+  .vb-story--failed {
+    --vb-dot: var(--es-failed);
+  }
+  .vb-story--skipped {
+    --vb-dot: var(--es-skipped);
+  }
+  .vb-story--pending {
+    --vb-dot: var(--es-pending);
+  }
+
+  .vb-story__title {
+    font-weight: 550;
+    line-height: 1.3;
+    color: var(--es-text);
+  }
+
+  .vb-story__status {
+    font-family: var(--es-mono);
+    font-size: var(--sl-text-xs);
+    color: var(--vb-dot, var(--es-text-muted));
+    text-transform: lowercase;
+  }
+
+  .vb-story__go {
+    color: var(--es-text-muted);
+    opacity: 0.6;
+    transition: transform 120ms ease, opacity 120ms ease;
+  }
+
+  .verified-by__missing {
+    margin: 0.75rem 0 0;
+    color: var(--es-text);
+    font-size: var(--sl-text-xs);
+  }
+
+  .verified-by__age-warning {
+    margin: 0.75rem 0 0;
+    color: var(--es-text);
+    font-size: var(--sl-text-xs);
+    font-weight: 600;
+  }
+
+  .verified-by__missing code {
+    font-size: var(--sl-text-xs);
+    background: var(--es-bg);
+    border: 1px solid var(--es-line);
+    border-radius: 0.25rem;
+    padding: 0.05rem 0.35rem;
+  }
+</style>

package/templates/astro-starlight/src/components/VerifiedStep.astro

@@ -0,0 +1,91 @@
+---
+/**
+ * <VerifiedStep story="health-check">Verify the /health endpoint returns 200</VerifiedStep>
+ *
+ * A runbook/checklist item whose trustworthiness is backed by a test. The `story`
+ * prop links the step to one or more story references; the box shows a live
+ * green check when the linked story passed in the last run, a red cross when it
+ * failed, and an empty box when there is no linked story (a manual step) or no
+ * matching story was found. Wrap a set of these in <Checklist>.
+ */
+import { report } from "../lib/config";
+import { resolveVerification } from "../lib/verification";
+
+interface Props {
+  /** Story id, tag, ticket, or title that verifies this step. Omit for a manual step. */
+  story?: string | string[];
+}
+
+const { story } = Astro.props;
+const result = story ? resolveVerification(story, report) : null;
+
+const ICON: Record<string, string> = {
+  verified: "✓",
+  failing: "✕",
+  "not-run": "⏳",
+  unverified: "⚠",
+};
+
+const icon = result ? ICON[result.status] : "○";
+const stateClass = result ? `verified-step--${result.status}` : "verified-step--manual";
+
+const note = result
+  ? result.status === "verified"
+    ? "verified by a passing story"
+    : result.status === "failing"
+      ? "linked story is failing"
+      : result.status === "not-run"
+        ? "linked story did not run"
+        : "no matching story"
+  : "manual step";
+---
+
+<li class:list={["verified-step", stateClass]}>
+  <span class="verified-step__box" aria-hidden="true">{icon}</span>
+  <span class="verified-step__body"><slot /></span>
+  <span class="verified-step__note" title={note}>{note}</span>
+</li>
+
+<style>
+  .verified-step {
+    list-style: none;
+    display: flex;
+    align-items: baseline;
+    gap: 0.6rem;
+    padding: 0.4rem 0;
+    border-bottom: 1px solid var(--sl-color-gray-6);
+  }
+  .verified-step__box {
+    flex: none;
+    width: 1.3rem;
+    height: 1.3rem;
+    display: inline-grid;
+    place-items: center;
+    border: 1px solid currentColor;
+    border-radius: 0.3rem;
+    font-size: 0.8rem;
+    font-weight: 700;
+  }
+  .verified-step__body {
+    flex: 1;
+  }
+  .verified-step__note {
+    flex: none;
+    font-size: var(--sl-text-xs);
+    color: var(--sl-color-gray-3);
+    white-space: nowrap;
+  }
+  .verified-step--verified .verified-step__box {
+    color: #16a34a;
+  }
+  .verified-step--failing .verified-step__box {
+    color: #dc2626;
+  }
+  .verified-step--not-run .verified-step__box,
+  .verified-step--unverified .verified-step__box {
+    color: #d97706;
+  }
+  .verified-step--manual .verified-step__box {
+    color: var(--sl-color-gray-3);
+  }
+</style>

package/templates/astro-starlight/src/content/docs/examples/example-adr.mdx

@@ -0,0 +1,45 @@
+---
+title: 'ADR 0001 — Charge a 35 bps transfer fee'
+description: 'Example decision record kept honest by executable stories.'
+verifiedBy:
+  - transfer-fee
+  - send-money--charges-a-35-bps-fee
+---
+
+import VerifiedBy from '../../../components/VerifiedBy.astro';
+
+The badge directly under the title is rendered automatically from the
+`verifiedBy` field in this page's frontmatter — it links this decision to the
+stories that prove it still holds.
+
+:::note
+On a fresh scaffold the badge reads **Unverified**, because no test run has
+populated `public/stories/story-report.json` yet. That is the point: the page
+tells you it is unproven until a real run backs it up. Generate the report with
+`executable-stories build-docs reports/raw-run.json --site-dir .`
+and the badge turns green when the linked stories pass.
+:::
+
+## Status
+
+Accepted
+
+## Context
+
+Cross-border transfers must cover FX spread and settlement cost. We need a fee
+that is predictable for customers and simple to reason about.
+
+## Decision
+
+Charge a flat **35 basis points** (0.35%) on the source amount of every
+transfer.
+
+## Verification
+
+This decision is only "true" while the stories that exercise it pass. You can
+also drop a badge inline anywhere in the page:
+
+<VerifiedBy refs={["transfer-fee"]} />
+
+When the fee logic changes and a linked story fails, this badge turns red — the
+decision record can no longer silently drift away from the code.

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

@@ -0,0 +1,41 @@
+---
+title: Behavior portal
+description: How proven behavior, commentary, and verification work together.
+---
+
+The portal has one job: make behavior trustworthy for both engineers and stakeholders.
+
+## Three content tiers
+
+- **Proven** lives in generated story pages and the Scenario Explorer. It comes from the latest run and is safe to regenerate at any time.
+- **Commentary** lives in hand-written guides, ADRs, runbooks, incidents, and scenario notes. It explains why behavior matters.
+- **Stale** is visible on purpose. If a commentary page links to failing or missing proof, the badge shows it.
+
+## Where to add context
+
+Use a scenario note when the commentary belongs to one scenario:
+
+```bash
+executable-stories new scenario-note "Checkout happy path" \
+  --scenario-id feature-checkout--happy-path
+```
+
+Use ADRs, runbooks, and guides when the context spans multiple scenarios.
+
+Once a scenario note exists, `build-docs` links to it automatically from every
+surface that shows the scenario — the generated story page, the Scenario
+Explorer, and the `/stories/` overview. You never add those links by hand, and
+they appear or disappear as notes are added or removed.
+
+## What not to edit
+
+Do not hand-edit `src/content/docs/stories/`. Those files are machine-owned and are replaced on each `build-docs` run.
+
+## Recommended CI flow
+
+```bash
+executable-stories build-docs raw-run.json \
+  --site-dir ./story-docs \
+  --audience-split \
+  --baseline ./story-docs/public/stories/story-report.json
+```