executable-stories-formatters 0.16.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-formatters",
-  "version": "0.16.0",
+  "version": "1.0.0",
   "description": "Cucumber-compatible report formats (HTML, Markdown, JUnit XML, Cucumber JSON) for executable-stories test results.",
   "author": "Jag Reehal <jag@jagreehal.com>",
   "license": "MIT",
@@ -59,14 +59,18 @@
     "@cucumber/messages": "^32.3.1",
     "ajv": "^8.20.0",
     "github-slugger": "^2.0.0",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "executable-stories-core": "0.18.0",
+    "executable-stories-react": "0.2.0"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@storybook/html": "^10.4.2",
-    "@storybook/html-vite": "^10.4.2",
+    "@storybook/html": "^10.4.6",
+    "@storybook/html-vite": "^10.4.6",
     "@types/node": "^25.9.2",
-    "storybook": "^10.4.2",
+    "storybook": "^10.4.6",
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "typescript": "~6.0.3",
@@ -74,12 +78,12 @@
     "vitest-mock-extended": "^4.0.0"
   },
   "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "type-check": "tsc --noEmit",
-    "generate:design-library": "tsx scripts/generate-design-library.ts",
-    "compile": "bun build src/cli.ts --compile --outfile executable-stories",
+    "embed-assets": "node scripts/embed-react-assets.mjs",
+    "build": "node scripts/embed-react-assets.mjs && tsup",
+    "test": "node scripts/embed-react-assets.mjs && vitest run",
+    "test:watch": "node scripts/embed-react-assets.mjs && vitest",
+    "type-check": "node scripts/embed-react-assets.mjs && tsc --noEmit",
+    "compile": "node scripts/embed-react-assets.mjs && bun build src/cli.ts --compile --outfile executable-stories",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build"
   }

package/schemas/README.md

@@ -178,7 +178,6 @@ SUBCOMMANDS
 | `--html-title <title>`           | `Test Results` | HTML report title                                             |
 | `--html-no-syntax-highlighting`  |                | Disable syntax highlighting in HTML (enabled by default)     |
 | `--html-no-mermaid`              |                | Disable Mermaid diagrams in HTML (enabled by default)         |
-| `--html-no-markdown`             |                | Disable markdown parsing in HTML (enabled by default)          |
 | `--stdin`                        |                | Read JSON from stdin instead of file                          |
 | `--json-summary`             | off            | Print machine-parsable JSON summary                           |
 | `--emit-canonical <path>`    |                | Write canonical JSON to given path                            |

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

@@ -0,0 +1,62 @@
+// @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',
+  vite: {
+    // The Stories page is a `client:load` React island. Pre-bundle React and the
+    // report component subtree in ONE optimize pass at startup so Astro's dev
+    // server never re-optimizes them mid-render when the island first hydrates.
+    // That mid-render re-optimize otherwise drops `react-dom/client`'s
+    // `createRoot` export and 504s the page ("Outdated Optimize Dep"), leaving
+    // the island unhydrated and the page rendered as unstyled SSR fallback.
+    // If you add your OWN React islands, add their heavy deps to `include` too.
+    optimizeDeps: {
+      include: [
+        'react',
+        'react-dom',
+        'react-dom/client',
+        'react/jsx-runtime',
+        'executable-stories-react',
+        'executable-stories-react/interactive',
+      ],
+      noDiscovery: true,
+    },
+    // Keep a single React copy so hooks/context work across the island boundary.
+    resolve: { dedupe: ['react', 'react-dom'] },
+  },
+  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

@@ -0,0 +1,47 @@
+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 run JSON your test adapter writes. Emit it by setting
+ * `rawRunPath: "reports/raw-run.json"` in your StoryReporter config, then run
+ * your tests in watch mode + `astro dev` to hot-reload these pages.
+ */
+export default defineExecutableStories({
+  source: process.env.ES_RUN_JSON ?? '../reports/raw-run.json',
+
+  // 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/raw-run.json' },
+  //   { name: 'api', label: 'API',     source: '../apps/api/reports/raw-run.json' },
+  // ],
+
+  // 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',
+});

package/templates/astro-thin/gitignore

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

package/templates/astro-thin/package.json

@@ -0,0 +1,20 @@
+{
+  "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

@@ -0,0 +1,133 @@
+{
+  "schemaVersion": "1.0",
+  "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 £42.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", "£42.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

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

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

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

@@ -0,0 +1,44 @@
+---
+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/raw-run.json 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.
+
+## Wiring (one-time)
+
+The site reads the run JSON your test adapter writes. Point `source` in
+`executable-stories.config.mjs` at it (default `../reports/raw-run.json`), 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

@@ -0,0 +1,26 @@
+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, and rewrites relative `*.md` cross-links to their routes — so you can
+  // drop in plain GitHub-style docs without edits.
+  docs: defineCollection({
+    loader: authoredDocsLoader({ path: 'src/content/docs' }),
+    schema: docsSchema({
+      extend: z.object({ verifiedBy: z.union([z.string(), z.array(z.string())]).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

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

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