executable-stories-formatters 0.16.0 → 1.0.0

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

@@ -1,281 +0,0 @@
----
-/**
- * <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

@@ -1,91 +0,0 @@
----
-/**
- * <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

@@ -1,45 +0,0 @@
----
-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

@@ -1,41 +0,0 @@
----
-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

@@ -1,49 +0,0 @@
----
-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

@@ -1,49 +0,0 @@
----
-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

@@ -1,18 +0,0 @@
-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

@@ -1,50 +0,0 @@
-/**
- * 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)}`;
-}