executable-stories-formatters 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-formatters",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Cucumber-compatible report formats (HTML, Markdown, JUnit XML, Cucumber JSON) for executable-stories test results.",
   "author": "Jag Reehal <jag@jagreehal.com>",
   "license": "Apache-2.0",
@@ -36,8 +36,7 @@
   "files": [
     "dist",
     "skills",
-    "schemas",
-    "templates"
+    "schemas"
   ],
   "engines": {
     "node": ">=22"

package/templates/astro-thin/astro.config.mjs

@@ -1,46 +0,0 @@
-// @ts-check
-import { defineConfig } from 'astro/config';
-import react from '@astrojs/react';
-import starlight from '@astrojs/starlight';
-import { executableStories, storiesSidebar } from 'executable-stories-astro';
-import esConfig from './executable-stories.config.mjs';
-
-// The story pages render the React report components from
-// executable-stories-react (the SAME components the standalone single-file HTML
-// report uses), so a React renderer must be registered. executable-stories-astro
-// can't auto-add it on Astro 7 — wire `react()` here, before the integration.
-
-// Run your tests in watch mode in one terminal and `astro dev` in another —
-// editing tests hot-reloads the Stories pages here. Nothing is written to disk;
-// tests stay the source of truth.
-export default defineConfig({
-  // Set this to your deployed URL to enable canonical links + the sitemap
-  // Starlight ships (otherwise `astro build` prints a harmless sitemap notice).
-  // site: 'https://docs.example.com',
-
-  // No vite tuning needed here: the integration pre-bundles React + the report
-  // components (optimizeDeps) and dedupes React itself, so fixes ship with
-  // `pnpm update executable-stories-astro`. If you add your OWN React islands,
-  // list their heavy deps in a `vite.optimizeDeps.include` of your own — it
-  // merges with the integration's list.
-  integrations: [
-    // React renderer for the report islands — must come before executableStories.
-    react(),
-    // Mermaid diagrams are rendered by a small inline loader on
-    // `pre[data-mermaid]`. Don't add astro-mermaid — both would process the same
-    // element and double-render.
-    executableStories(esConfig),
-    starlight({
-      title: 'Story Docs',
-      description: 'Living documentation generated from executable stories.',
-      customCss: ['./src/styles/stories.css'],
-      // Nav is built straight from the config (Stories + Explorer, plus a group
-      // per `docs` source). Edit the array to taste.
-      sidebar: [
-        { label: 'Home', slug: 'index' },
-        ...storiesSidebar(esConfig),
-        { label: 'Guides', items: [{ autogenerate: { directory: 'guides' } }] },
-      ],
-    }),
-  ],
-});

package/templates/astro-thin/executable-stories.config.mjs

@@ -1,76 +0,0 @@
-import { defineExecutableStories } from 'executable-stories-astro';
-
-/**
- * One config object drives the whole docs site. It is imported by BOTH
- * astro.config.mjs (route injection, nav, theme) and src/content.config.ts
- * (the loaders) — so everything lives in one place.
- *
- * `source` points at the directory of per-file reports your test run writes,
- * one per test source file. Pointing at the directory rather than a single run
- * JSON is what keeps the site showing your whole suite when you have only run
- * part of it. Run your tests in watch mode + `astro dev` to hot-reload these
- * pages; new test files appear without a restart.
- *
- * A single run JSON still works if you want only the last run:
- * `source: '../reports/raw-run.json'`.
- */
-export default defineExecutableStories({
-  source: process.env.ES_RUN_JSON ?? '../reports/by-file',
-
-  // Shown only until your tests emit the run JSON above, so `astro dev` is
-  // populated on first run instead of empty. Replaced automatically the moment
-  // real results land; the Stories page labels these as sample data. Delete the
-  // file (and this line) once you're wired up.
-  sampleSource: './reports/sample-run.json',
-
-  // How scenarios are categorised in the index/explorer/nav:
-  //   'feature' (default) | 'tag' | 'source' | 'status' | 'none'
-  groupBy: 'feature',
-
-  // Only show some scenarios (optional):
-  // include: { tags: ['security', 'observability'] },
-  // exclude: { status: ['skipped'] },
-
-  // Combine several test suites in one site (optional):
-  // sources: [
-  //   { name: 'web', label: 'Web app', source: '../apps/web/reports/by-file' },
-  //   { name: 'api', label: 'API',     source: '../apps/api/reports/by-file' },
-  // ],
-
-  // Audience lenses (optional): each view mounts a filtered, re-grouped index
-  // at its own URL — same tests, a different lens per audience. Tag scenarios
-  // in your tests (e.g. tags: ['audience:stakeholder']) and filter on them:
-  // views: [
-  //   { base: '/for/product', include: { tags: ['audience:stakeholder'] }, groupBy: 'tag' },
-  //   { base: '/for/design',  include: { tags: ['storyboard'] } },
-  //   { base: '/for/support', include: { tags: ['support'] } },
-  // ],
-
-  // Journeys are on by default at /journeys: tag scenarios with
-  // `journey:<id>:<order>` (e.g. tags: ['journey:guest-checkout:1']) and each
-  // id becomes an ordered multi-scenario walkthrough page.
-  // journeysBase: '/journeys',
-
-  // The UI-state catalog is on by default at /states: tag scenarios with
-  // `state:<name>` (plus optional `viewport:mobile` / `viewport:desktop`) and
-  // they appear as a thumbnail grid, viewport variants side by side.
-  // statesBase: '/states',
-
-  // Theme the story pages (optional). `preset` picks a built-in palette
-  // ('default' | 'terminal' | 'minimal' | 'vibrant'); `accent` is a shorthand;
-  // `tokens` overrides any individual token (accent, pass, fail, warn, fg,
-  // muted, border, surface). These restyle the story content only — the
-  // Starlight shell keeps its own light/dark theme.
-  // theme: { preset: 'terminal', accent: '#3245ff', tokens: { pass: '#16a34a' } },
-
-  // Where the Stories/Explorer pages render (optional). 'auto' (default) uses
-  // the Starlight shell — sidebar, search, theme toggle — when this site has
-  // Starlight, and falls back to standalone pages otherwise. Force it with
-  // 'starlight' or 'standalone' if you embed the integration in your own site.
-  // shell: 'auto',
-
-  // Agent-readable endpoints (on by default): /llms.txt indexes every scenario
-  // and each story page gets a plain-Markdown twin at /stories/<slug>.md, so
-  // the deployed site is consumable by agents/curl, not just browsers.
-  // agentEndpoints: true,
-});

package/templates/astro-thin/gitignore

@@ -1,3 +0,0 @@
-dist/
-.astro/
-node_modules/

package/templates/astro-thin/package.json

@@ -1,20 +0,0 @@
-{
-  "name": "story-docs",
-  "type": "module",
-  "version": "0.0.1",
-  "private": true,
-  "scripts": {
-    "dev": "astro dev",
-    "build": "astro build",
-    "preview": "astro preview"
-  },
-  "dependencies": {
-    "@astrojs/react": "^4.4.2",
-    "@astrojs/starlight": "^0.41.0",
-    "astro": "^7.0.0",
-    "executable-stories-astro": "^0.1.0",
-    "executable-stories-react": "^0.1.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
-  }
-}

package/templates/astro-thin/reports/sample-run.json

@@ -1,214 +0,0 @@
-{
-  "$schema": "https://executable-stories.dev/schemas/raw-run.schema.json",
-  "schemaVersion": 1,
-  "projectRoot": "/sample",
-  "startedAtMs": 0,
-  "finishedAtMs": 1234,
-  "packageVersion": "sample",
-  "testCases": [
-    {
-      "title": "A returning customer checks out with a saved card",
-      "sourceFile": "src/checkout.story.test.ts",
-      "sourceLine": 12,
-      "status": "pass",
-      "durationMs": 41,
-      "story": {
-        "scenario": "A returning customer checks out with a saved card",
-        "tags": [
-          "checkout",
-          "payments"
-        ],
-        "covers": [
-          "src/checkout/**"
-        ],
-        "steps": [
-          {
-            "keyword": "Given",
-            "text": "a signed-in customer with a saved card"
-          },
-          {
-            "keyword": "And",
-            "text": "a basket worth \u00a342.00"
-          },
-          {
-            "keyword": "When",
-            "text": "they confirm the order"
-          },
-          {
-            "keyword": "Then",
-            "text": "the payment is captured and an order id is returned",
-            "docs": [
-              {
-                "kind": "table",
-                "phase": "runtime",
-                "label": "Captured payment",
-                "columns": [
-                  "Field",
-                  "Value"
-                ],
-                "rows": [
-                  [
-                    "amount",
-                    "\u00a342.00"
-                  ],
-                  [
-                    "status",
-                    "captured"
-                  ],
-                  [
-                    "order",
-                    "ord_1A2B"
-                  ]
-                ]
-              }
-            ]
-          }
-        ],
-        "docs": [
-          {
-            "kind": "mermaid",
-            "phase": "static",
-            "code": "flowchart LR\n  Basket --> Confirm --> Capture --> Order"
-          }
-        ]
-      }
-    },
-    {
-      "title": "Checkout is blocked when the card is declined",
-      "sourceFile": "src/checkout.story.test.ts",
-      "sourceLine": 34,
-      "status": "fail",
-      "durationMs": 28,
-      "error": {
-        "message": "Expected order to be created, but payment was declined (card_declined)"
-      },
-      "story": {
-        "scenario": "Checkout is blocked when the card is declined",
-        "tags": [
-          "checkout",
-          "payments"
-        ],
-        "covers": [
-          "src/checkout/**"
-        ],
-        "steps": [
-          {
-            "keyword": "Given",
-            "text": "a customer whose card will be declined"
-          },
-          {
-            "keyword": "When",
-            "text": "they confirm the order"
-          },
-          {
-            "keyword": "Then",
-            "text": "they see a clear decline message"
-          },
-          {
-            "keyword": "But",
-            "text": "no order is created"
-          }
-        ]
-      }
-    },
-    {
-      "title": "Gift wrapping is offered above the free-wrap threshold",
-      "sourceFile": "src/checkout.story.test.ts",
-      "sourceLine": 58,
-      "status": "skip",
-      "durationMs": 0,
-      "story": {
-        "scenario": "Gift wrapping is offered above the free-wrap threshold",
-        "tags": [
-          "checkout"
-        ],
-        "steps": [
-          {
-            "keyword": "Given",
-            "text": "a basket above the free-wrap threshold"
-          },
-          {
-            "keyword": "Then",
-            "text": "free gift wrapping is offered"
-          }
-        ]
-      }
-    },
-    {
-      "title": "Search ranks exact title matches first",
-      "sourceFile": "src/search.story.test.ts",
-      "sourceLine": 9,
-      "status": "pass",
-      "durationMs": 17,
-      "story": {
-        "scenario": "Search ranks exact title matches first",
-        "tags": [
-          "search"
-        ],
-        "covers": [
-          "src/search/**"
-        ],
-        "steps": [
-          {
-            "keyword": "Given",
-            "text": "products titled 'Wireless Mouse' and 'Mouse Pad'"
-          },
-          {
-            "keyword": "When",
-            "text": "the shopper searches for 'mouse'"
-          },
-          {
-            "keyword": "Then",
-            "text": "the exact title match is ranked first",
-            "docs": [
-              {
-                "kind": "code",
-                "phase": "runtime",
-                "label": "Ranked results",
-                "lang": "json",
-                "content": "[\n  { \"title\": \"Wireless Mouse\", \"score\": 0.98 },\n  { \"title\": \"Mouse Pad\", \"score\": 0.61 }\n]"
-              }
-            ]
-          }
-        ],
-        "docs": [
-          {
-            "kind": "note",
-            "phase": "static",
-            "text": "This is **sample data** shipped with the scaffold so the site is populated on first run. It is replaced automatically the moment your tests emit their run JSON."
-          }
-        ]
-      }
-    },
-    {
-      "title": "Search tolerates a single typo",
-      "sourceFile": "src/search.story.test.ts",
-      "sourceLine": 31,
-      "status": "pass",
-      "durationMs": 23,
-      "story": {
-        "scenario": "Search tolerates a single typo",
-        "tags": [
-          "search"
-        ],
-        "covers": [
-          "src/search/**"
-        ],
-        "steps": [
-          {
-            "keyword": "Given",
-            "text": "a product titled 'Keyboard'"
-          },
-          {
-            "keyword": "When",
-            "text": "the shopper searches for 'keybord'"
-          },
-          {
-            "keyword": "Then",
-            "text": "the product is still found"
-          }
-        ]
-      }
-    }
-  ]
-}

package/templates/astro-thin/src/content/docs/404.md

@@ -1,20 +0,0 @@
----
-title: Page not found
-template: splash
-editUrl: false
-# Keep this out of the routable `[...slug]` paths so it doesn't collide with
-# Starlight's dedicated 404 route; Starlight still reads it via getEntry to
-# populate that route. (Without this, the build warns about a /404 conflict.)
-draft: true
-hero:
-  title: "404"
-  tagline: That page isn't here. The Stories are generated live from your test runs, so a link can go stale if a scenario is renamed or removed.
-  actions:
-    - text: Browse the Stories
-      link: /stories/
-      icon: right-arrow
-      variant: primary
-    - text: Back to docs home
-      link: /
-      variant: minimal
----

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

@@ -1,58 +0,0 @@
----
-title: Writing docs
----
-
-Add your own `.mdx` files under `src/content/docs/` — they appear in the sidebar
-alongside the generated Stories. The generated pages are derived from tests and
-are never written to disk, so you can't accidentally edit them into a lie.
-
-## Embed live scenarios in your own pages
-
-Your hand-written pages can pull scenarios in as live evidence — rendered from
-the latest test run, so the embedded card can never drift from reality:
-
-```mdx
----
-title: Discount policy
----
-import StoryScenario from 'executable-stories-astro/components/StoryScenario.astro';
-import StoryStatus from 'executable-stories-astro/components/StoryStatus.astro';
-
-We cap discounts at 30% — enforced end-to-end
-(currently <StoryStatus id="checkout--caps-the-discount-at-30-percent" />):
-
-<StoryScenario id="checkout--caps-the-discount-at-30-percent" />
-```
-
-- `<StoryScenario id="…" />` embeds the full scenario card — steps, status,
-  failure output, and any docs the test attached.
-- `<StoryStatus id="…" />` is an inline status pill linked to the story page,
-  for referencing evidence mid-sentence.
-- `id` accepts the stable scenario id (copy it from the **Explorer** page), the
-  URL slug, or the exact title. An id that no longer matches renders a visible
-  callout — embedded evidence never silently disappears.
-
-## Prove a page is still true
-
-Declare which stories verify a page in its frontmatter and render a live badge:
-
-```mdx
----
-title: ADR 0007 — cap discount at 30%
-verifiedBy: [checkout--caps-the-discount-at-30-percent]
----
-import VerifiedBy from 'executable-stories-astro/components/VerifiedBy.astro';
-
-<VerifiedBy refs={frontmatter.verifiedBy} />
-```
-
-## For agents and tooling
-
-The site also publishes machine-readable twins (on by default):
-
-- `/llms.txt` — an index of every scenario with links to its Markdown form.
-- `/stories/<slug>.md` — a plain-Markdown twin of each story page.
-
-Point an agent at your deployed site's `/llms.txt` and it can read every
-scenario without an HTML parser. Disable with `agentEndpoints: false` in
-`executable-stories.config.mjs`.

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

@@ -1,51 +0,0 @@
----
-title: Story Docs
-description: Living documentation generated from executable stories.
----
-
-The **Stories** section is generated live from your test-run JSON by the
-`executable-stories-astro` integration — there is no build/generate step and the
-pages are never written to disk, so they can't drift into a lie. Everything under
-**Guides** is hand-authored by your team.
-
-## The loop
-
-Run two things side by side and leave them running:
-
-```bash
-# Terminal 1 — your tests in watch mode (rewrites reports/by-file/ on every run)
-pnpm test --watch        # or: vitest, jest --watch, playwright --ui, …
-
-# Terminal 2 — this docs site
-npm run dev              # Astro dev server
-```
-
-Each time your tests re-run, they rewrite the run JSON; the integration reloads
-it and these pages hot-update in place. Edit a `*.story.test.ts`, save, and watch
-the matching page change.
-
-## Where to look
-
-- **[Stories](/stories)** — one page per scenario, grouped by feature (change the
-  grouping with `groupBy` in `executable-stories.config.mjs`). Add a story and it
-  appears; delete it and its page is pruned. On a fresh scaffold this shows a few
-  **sample scenarios** (labelled as such) so the site isn't empty — they vanish
-  the moment your tests emit their run JSON.
-- **[Explorer](/explorer)** — a searchable index of every scenario with its status.
-- **Trajectory** — pins a baseline when the dev server starts and shows what
-  changed *since you started this session* (e.g. "+2 passing, 1 regressed") — the
-  signal to watch while iterating in an agent loop.
-- **[/llms.txt](/llms.txt)** — a machine-readable index of every scenario; each
-  story page also has a plain-Markdown twin at `/stories/<slug>.md`, so agents
-  can read the published site without an HTML parser.
-
-Your own pages can embed scenarios as live evidence too — see
-**[Writing docs](/guides/writing-docs/)** for `<StoryScenario/>` and
-`<StoryStatus/>`.
-
-## Wiring (one-time)
-
-The site reads the run JSON your test adapter writes. Point `source` in
-`executable-stories.config.mjs` at it (default `../reports/by-file`), and set
-the matching `rawRunPath` in your StoryReporter config. That's the only wiring —
-no per-test setup.

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

@@ -1,33 +0,0 @@
-import { defineCollection, z } from 'astro:content';
-import { docsSchema } from '@astrojs/starlight/schema';
-import {
-  storiesLoader,
-  trajectoryLoader,
-  authoredDocsLoader,
-} from 'executable-stories-astro';
-import esConfig from '../executable-stories.config.mjs';
-
-export const collections = {
-  // Hand-authored docs. `authoredDocsLoader` is a drop-in for Starlight's
-  // docsLoader that ALSO: auto-titles frontmatter-free markdown from its first
-  // H1, rewrites relative `*.md` cross-links to their routes, and (because the
-  // shared config is passed as `explainers`) injects a fresh/stale banner into
-  // any doc carrying an `explainer` provenance block (explain-change skill) —
-  // with deep links to the cited scenarios' story pages.
-  docs: defineCollection({
-    loader: authoredDocsLoader({ path: 'src/content/docs', explainers: esConfig }),
-    schema: docsSchema({
-      extend: z.object({
-        verifiedBy: z.union([z.string(), z.array(z.string())]).optional(),
-        // Explainer provenance block — kept loose here (zod would otherwise
-        // strip it); `executable-stories check-explainers` validates strictly.
-        explainer: z.record(z.unknown()).optional(),
-      }),
-    }),
-  }),
-  // Generated scenarios (executable-stories) — in-memory, never written to disk.
-  stories: defineCollection({ loader: storiesLoader(esConfig) }),
-  // Session trajectory ("passed N → M since you started"). Render with the
-  // shipped <Trajectory /> component (executable-stories-astro/components/Trajectory.astro).
-  trajectory: defineCollection({ loader: trajectoryLoader(esConfig) }),
-};

package/templates/astro-thin/src/styles/stories.css

@@ -1,32 +0,0 @@
-/**
- * Site theme for the executable-stories docs site. Loaded as Starlight
- * `customCss`, so unlike the package's `es.css` (which styles only the
- * /stories + /explorer content), this reaches the WHOLE shell — home page,
- * sidebar, header, search — and gives the site the look & feel of the HTML
- * report the formatters produce: IBM Plex type + a green primary accent.
- *
- * Edit freely (or delete) to match your own brand. To re-theme just the story
- * content, prefer the `theme` field in executable-stories.config.mjs.
- */
-@import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap");
-
-:root {
-  --sl-font: "IBM Plex Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-  --sl-font-mono: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
-
-  /* Dark theme (Starlight's default :root) — green primary to match the report. */
-  --sl-color-accent-low: #11341f;
-  --sl-color-accent: #1f9d4d;
-  --sl-color-accent-high: #b8f0cb;
-  --sl-color-text-accent: #4ade80;
-}
-
-:root[data-theme="light"] {
-  --sl-color-accent-low: #d6f3e0;
-  --sl-color-accent: #1a7f37;
-  --sl-color-accent-high: #0c4a23;
-  --sl-color-text-accent: #15803d;
-}
-
-/* Tighten the brand wordmark + nav to feel a touch more product/Storybook-like. */
-.site-title { font-weight: 700; letter-spacing: -0.01em; }

package/templates/astro-thin/tsconfig.json

@@ -1,5 +0,0 @@
-{
-  "extends": "astro/tsconfigs/strict",
-  "include": [".astro/types.d.ts", "**/*"],
-  "exclude": ["dist"]
-}