executable-stories-formatters 0.15.0 → 0.16.0

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
+```

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)}`;
+}