executable-stories-formatters 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-formatters",
-  "version": "0.15.0",
+  "version": "0.16.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",
@@ -36,7 +36,8 @@
   "files": [
     "dist",
     "skills",
-    "schemas"
+    "schemas",
+    "templates"
   ],
   "engines": {
     "node": ">=22"

package/schemas/README.md

@@ -172,7 +172,7 @@ SUBCOMMANDS
 | `--format <formats>`         | `html`         | Comma-separated: `html`, `markdown`, `junit`, `cucumber-json`, `cucumber-html`, `cucumber-messages` |
 | `--input-type <type>`        | `raw`          | Input type: `raw`, `canonical`, or `ndjson`                   |
 | `--output-dir <dir>`         | `reports`      | Output directory                                              |
-| `--output-name <name>`       | `test-results` | Base filename                                                 |
+| `--output-name <name>`       | `index` | Base filename                                                 |
 | `--synthesize-stories`       | on             | Synthesize story metadata for plain test results              |
 | `--no-synthesize-stories`    |                | Disable story synthesis (strict mode)                         |
 | `--html-title <title>`           | `Test Results` | HTML report title                                             |

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

@@ -0,0 +1,57 @@
+// @ts-check
+import starlight from '@astrojs/starlight';
+import astroMermaid from 'astro-mermaid';
+import remarkGfm from 'remark-gfm';
+import { defineConfig } from 'astro/config';
+
+/*
+ * Available themes (match HTML formatter themes):
+ *   default    — cucumber green, IBM Plex typography
+ *   corporate  — navy, Playfair Display serif headings
+ *   terminal   — green-on-dark, JetBrains Mono, flat
+ *   minimal    — teal, Noto Serif Display headings, warm neutrals
+ *   dashboard  — blue, DM Sans + JetBrains Mono
+ *   playful    — coral, rounded corners, Source Sans 3
+ *
+ * To switch themes, replace `themes/default.css` below with the filename
+ * of the theme you want (e.g. `./src/styles/themes/corporate.css`).
+ */
+
+export default defineConfig({
+  // GFM tables don't render in .mdx by default — enable them so hand-written
+  // and generated .mdx pages (ADRs, API coverage, decision logs) show tables.
+  markdown: {
+    remarkPlugins: [remarkGfm],
+  },
+  integrations: [
+    astroMermaid(),
+    starlight({
+      title: 'Story Docs',
+      description: 'Living documentation generated from executable stories.',
+      // Renders a live verification badge under the title of any page that
+      // declares `verifiedBy` in its frontmatter.
+      components: {
+        PageTitle: './src/components/PageTitle.astro',
+      },
+      sidebar: [
+        { label: 'Home', slug: 'index' },
+        { label: 'Explorer', link: '/explorer/' },
+        // Hand-written content — edited by the team, never overwritten by a regenerate.
+        { label: 'Guides', autogenerate: { directory: 'guides' } },
+        { label: 'Notes', autogenerate: { directory: 'notes' } },
+        // Autogenerated, not a hard-coded slug — clearing the sample ADR (or the
+        // whole directory) leaves the build green instead of 404ing on a missing slug.
+        { label: 'Examples', autogenerate: { directory: 'examples' } },
+        // Generated from tests by `format --format astro`.
+        {
+          label: 'Stories',
+          autogenerate: { directory: 'stories' },
+        },
+      ],
+      customCss: [
+        './src/styles/global.css',
+        './src/styles/themes/default.css',
+      ],
+    }),
+  ],
+});

package/templates/astro-starlight/gitignore

@@ -0,0 +1,14 @@
+node_modules/
+.astro/
+dist/
+
+# Machine-owned portal output. Regenerated by build-docs / CI.
+src/content/docs/stories/*
+!src/content/docs/stories/.gitkeep
+public/stories/assets/*
+!public/stories/assets/.gitkeep
+public/stories/story-report.json
+public/stories/scenario-links.json
+public/stories/notes-index.json
+!public/stories/notes-index.json
+public/stories/changes.json

package/templates/astro-starlight/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/starlight": "^0.38.3",
+    "astro": "^6.1.8",
+    "astro-mermaid": "^2.0.1",
+    "highlight.js": "^11.10.0",
+    "marked": "^12.0.0",
+    "mermaid": "^11.14.0",
+    "remark-gfm": "^4.0.0"
+  }
+}

package/templates/astro-starlight/public/stories/notes-index.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": "1.0",
+  "notes": []
+}

package/templates/astro-starlight/public/stories/story-report.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "1.0",
+  "runId": "empty",
+  "startedAtMs": 0,
+  "finishedAtMs": 0,
+  "durationMs": 0,
+  "projectRoot": "",
+  "summary": {
+    "total": 0,
+    "passed": 0,
+    "failed": 0,
+    "skipped": 0,
+    "pending": 0,
+    "durationMs": 0
+  },
+  "features": []
+}

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

@@ -0,0 +1,366 @@
+---
+/**
+ * <ApiOperations tag="Transfers" hasRun endpoints={[...]} summary={{...}} />
+ *
+ * Renders the API coverage table for one OpenAPI tag. Generated by
+ * `executable-stories import-openapi`, which writes an MDX page that imports
+ * this component and passes the endpoints + their test coverage.
+ *
+ * Each endpoint shows an HTTP-method pill, its path, a coverage badge, and the
+ * stories that exercise it — linked straight into the Scenario Explorer, so the
+ * API docs can never drift from the tests that prove them.
+ */
+import { explorerUrl } from "../lib/config";
+
+type CoverageStatus = "covered" | "failing" | "uncovered";
+
+export interface ApiStoryRef {
+  id: string;
+  title: string;
+  status: string;
+}
+
+export interface ApiEndpoint {
+  method: string;
+  path: string;
+  summary: string;
+  status: CoverageStatus;
+  stories: ApiStoryRef[];
+}
+
+interface Props {
+  tag: string;
+  hasRun: boolean;
+  endpoints: ApiEndpoint[];
+  summary: { total: number; covered: number; failing: number; uncovered: number };
+}
+
+const { hasRun, endpoints, summary } = Astro.props;
+
+const coverageLabel: Record<CoverageStatus, string> = {
+  covered: "Covered",
+  failing: "Failing",
+  uncovered: "Uncovered",
+};
+
+const methodClass = (method: string) => `m-${method.toLowerCase()}`;
+---
+
+<section class="api-ops">
+  <header class="api-ops__bar">
+    <p class="api-ops__lede">
+      Generated from the OpenAPI spec.{" "}
+      {hasRun
+        ? "Coverage reflects the last test run."
+        : "Re-run with --run <story-report.json> to show per-endpoint coverage."}
+    </p>
+    {
+      hasRun && (
+        <div class="api-ops__stats" role="group" aria-label="Coverage summary">
+          <span class="stat stat--covered">
+            <strong>{summary.covered}</strong> covered
+          </span>
+          {summary.failing > 0 && (
+            <span class="stat stat--failing">
+              <strong>{summary.failing}</strong> failing
+            </span>
+          )}
+          <span class="stat stat--uncovered">
+            <strong>{summary.uncovered}</strong> no test
+          </span>
+          <span class="stat stat--total">of {summary.total}</span>
+        </div>
+      )
+    }
+  </header>
+
+  <div class="api-ops__rows" role="table" aria-label="API endpoints">
+    <div class="api-ops__row api-ops__row--head" role="row">
+      <span role="columnheader">Endpoint</span>
+      <span role="columnheader">Summary</span>
+      {hasRun && <span role="columnheader">Coverage</span>}
+      {hasRun && <span role="columnheader">Verified by</span>}
+    </div>
+    {
+      endpoints.map((ep) => (
+        <div class="api-ops__row" role="row">
+          <span class="cell-endpoint" role="cell">
+            <span class:list={["method", methodClass(ep.method)]}>{ep.method}</span>
+            <code class="path">{ep.path}</code>
+          </span>
+          <span class="cell-summary" role="cell">{ep.summary || "—"}</span>
+          {hasRun && (
+            <span role="cell">
+              <span class:list={["coverage", `coverage--${ep.status}`]}>
+                <span class="coverage__dot" aria-hidden="true" />
+                {coverageLabel[ep.status]}
+              </span>
+            </span>
+          )}
+          {hasRun && (
+            <span class="cell-stories" role="cell">
+              {ep.stories.length === 0 ? (
+                <span class="no-stories">—</span>
+              ) : (
+                ep.stories.map((s) => (
+                  <a class:list={["story-chip", `story-chip--${s.status}`]} href={explorerUrl(s.id)}>
+                    <span class="story-chip__dot" aria-hidden="true" />
+                    {s.title}
+                  </a>
+                ))
+              )}
+            </span>
+          )}
+        </div>
+      ))
+    }
+  </div>
+</section>
+
+<style>
+  .api-ops {
+    margin: 1.25rem 0 2rem;
+  }
+
+  .api-ops__bar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem 1.25rem;
+    margin-bottom: 1rem;
+  }
+
+  .api-ops__lede {
+    margin: 0;
+    color: var(--es-text-muted);
+    font-size: var(--sl-text-sm);
+    max-width: 52ch;
+  }
+
+  .api-ops__stats {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    flex-wrap: wrap;
+  }
+
+  .stat {
+    display: inline-flex;
+    align-items: baseline;
+    gap: 0.3rem;
+    font-size: var(--sl-text-xs);
+    color: var(--es-text-muted);
+    padding: 0.25rem 0.6rem;
+    border: 1px solid var(--es-line);
+    border-radius: var(--es-radius-pill);
+    background: var(--es-surface);
+  }
+  .stat strong {
+    font-size: var(--sl-text-sm);
+    color: var(--es-text);
+  }
+  .stat--covered {
+    color: var(--es-passed);
+    border-color: color-mix(in oklab, var(--es-passed) 40%, var(--es-line));
+    background: var(--es-passed-soft);
+  }
+  .stat--covered strong {
+    color: var(--es-passed);
+  }
+  .stat--failing {
+    color: var(--es-failed);
+    border-color: color-mix(in oklab, var(--es-failed) 40%, var(--es-line));
+    background: var(--es-failed-soft);
+  }
+  .stat--failing strong {
+    color: var(--es-failed);
+  }
+  .stat--uncovered {
+    color: var(--es-skipped);
+    border-color: color-mix(in oklab, var(--es-skipped) 40%, var(--es-line));
+    background: var(--es-skipped-soft);
+  }
+  .stat--uncovered strong {
+    color: var(--es-skipped);
+  }
+  .stat--total {
+    border: none;
+    background: none;
+  }
+
+  .api-ops__rows {
+    border: 1px solid var(--es-line);
+    border-radius: var(--es-radius);
+    overflow: hidden;
+    background: var(--es-bg);
+  }
+
+  .api-ops__row {
+    display: grid;
+    grid-template-columns: minmax(220px, 1.2fr) minmax(140px, 1.4fr) auto minmax(160px, 1.3fr);
+    gap: 1rem;
+    align-items: center;
+    padding: 0.7rem 1rem;
+    border-top: 1px solid var(--es-line);
+  }
+  .api-ops__row:first-child {
+    border-top: none;
+  }
+  .api-ops__row:not(.api-ops__row--head):hover {
+    background: var(--es-surface);
+  }
+
+  .api-ops__row--head {
+    background: var(--es-surface-2);
+    font-size: var(--sl-text-xs);
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--es-text-muted);
+  }
+
+  .cell-endpoint {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.6rem;
+    min-width: 0;
+  }
+
+  .method {
+    flex: none;
+    font-family: var(--es-mono);
+    font-size: 0.7rem;
+    font-weight: 700;
+    letter-spacing: 0.04em;
+    padding: 0.2rem 0.45rem;
+    border-radius: var(--es-radius-sm);
+    color: #fff;
+    background: var(--es-method-default);
+  }
+  .m-get {
+    background: var(--es-method-get);
+  }
+  .m-post {
+    background: var(--es-method-post);
+  }
+  .m-put {
+    background: var(--es-method-put);
+  }
+  .m-patch {
+    background: var(--es-method-patch);
+  }
+  .m-delete {
+    background: var(--es-method-delete);
+  }
+
+  .path {
+    font-family: var(--es-mono);
+    font-size: var(--sl-text-sm);
+    color: var(--es-text);
+    background: none;
+    border: none;
+    padding: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .cell-summary {
+    color: var(--es-text-soft);
+    font-size: var(--sl-text-sm);
+  }
+
+  .coverage {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-size: var(--sl-text-xs);
+    font-weight: 600;
+    padding: 0.2rem 0.6rem;
+    border-radius: var(--es-radius-pill);
+    border: 1px solid currentcolor;
+    white-space: nowrap;
+  }
+  .coverage__dot {
+    width: 0.5rem;
+    height: 0.5rem;
+    border-radius: 50%;
+    background: currentcolor;
+  }
+  .coverage--covered {
+    color: var(--es-passed);
+    background: var(--es-passed-soft);
+  }
+  .coverage--failing {
+    color: var(--es-failed);
+    background: var(--es-failed-soft);
+  }
+  .coverage--uncovered {
+    color: var(--es-skipped);
+    background: var(--es-skipped-soft);
+  }
+
+  .cell-stories {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.35rem;
+  }
+
+  .story-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.35rem;
+    font-size: var(--sl-text-xs);
+    text-decoration: none;
+    color: var(--es-text-soft);
+    padding: 0.2rem 0.5rem;
+    border: 1px solid var(--es-line);
+    border-radius: var(--es-radius-pill);
+    background: var(--es-surface);
+    transition: border-color 120ms ease, color 120ms ease;
+  }
+  .story-chip:hover {
+    border-color: var(--es-accent);
+    color: var(--es-text);
+  }
+  .story-chip:focus-visible {
+    outline: 2px solid var(--es-accent);
+    outline-offset: 2px;
+  }
+  .story-chip__dot {
+    width: 0.45rem;
+    height: 0.45rem;
+    border-radius: 50%;
+    background: var(--chip-dot, var(--es-text-muted));
+  }
+  .story-chip--passed {
+    --chip-dot: var(--es-passed);
+  }
+  .story-chip--failed {
+    --chip-dot: var(--es-failed);
+  }
+  .story-chip--skipped {
+    --chip-dot: var(--es-skipped);
+  }
+  .story-chip--pending {
+    --chip-dot: var(--es-pending);
+  }
+
+  .no-stories {
+    color: var(--es-text-muted);
+  }
+
+  @media (max-width: 720px) {
+    .api-ops__row {
+      grid-template-columns: 1fr;
+      gap: 0.5rem;
+    }
+    .api-ops__row--head {
+      display: none;
+    }
+    .cell-summary {
+      color: var(--es-text-muted);
+    }
+  }
+</style>

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

@@ -0,0 +1,15 @@
+---
+/**
+ * <Checklist> wraps a set of <VerifiedStep> items into a clean runbook list.
+ */
+---
+
+<ul class="checklist"><slot /></ul>
+
+<style>
+  .checklist {
+    margin: 1rem 0;
+    padding: 0;
+    border-top: 1px solid var(--sl-color-gray-6);
+  }
+</style>

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>