executable-stories-vitest 7.0.1 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-vitest",
-  "version": "7.0.1",
+  "version": "8.0.0",
   "description": "TS-first story/given/when/then helpers for Vitest with Markdown user-story doc generation.",
   "author": "Jag Reehal <jag@jagreehal.com>",
   "homepage": "https://github.com/jagreehal/executable-stories#readme",
@@ -32,21 +32,23 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "skills",
+    "README.md",
+    "bin"
   ],
   "peerDependencies": {
-    "vitest": ">=4.0.18",
-    "executable-stories-formatters": "^0.6.1"
+    "vitest": ">=4.1.0",
+    "executable-stories-formatters": "^0.7.0"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@types/node": "^25.3.2",
+    "@types/node": "^25.5.0",
     "@types/picomatch": "^4.0.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18",
     "eslint-config-executable-stories": "0.2.0",
-    "executable-stories-formatters": "0.6.1"
+    "executable-stories-formatters": "0.7.0"
   },
   "keywords": [
     "vitest",
@@ -64,6 +66,9 @@
     "fast-glob": "^3.3.3",
     "picomatch": "^4.0.3"
   },
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "scripts": {
     "build": "tsup",
     "type-check": "tsc --noEmit",

package/skills/vitest-converting-tests/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: vitest-converting-tests
+description: >
+  Incrementally adopt executable-stories in Vitest. Add story.init(task) and
+  step markers to existing it/test blocks. Use doc.story for framework-native
+  tests. File naming .story.test.ts. No rewrite needed — progressive
+  enhancement of existing tests.
+type: lifecycle
+library: executable-stories-vitest
+library_version: "7.0.1"
+requires:
+  - vitest-story-api
+sources:
+  - "jagreehal/executable-stories:apps/docs-site/src/content/docs/guides/converting-vitest.md"
+---
+
+This skill builds on vitest-story-api. Read vitest-story-api first.
+
+# Converting Existing Vitest Tests
+
+## Setup
+
+Install the package:
+
+```bash
+npm install -D executable-stories-vitest executable-stories-formatters
+```
+
+## Core Patterns
+
+### Step 1: Rename the file
+
+```
+# Before
+test/calculator.test.ts
+
+# After
+test/calculator.story.test.ts
+```
+
+The reporter filters for `.story.test.ts` files.
+
+### Step 2: Add story.init() and step markers
+
+```typescript
+// Before
+import { describe, expect, it } from "vitest";
+
+describe("Calculator", () => {
+  it("adds two numbers", () => {
+    const result = add(2, 3);
+    expect(result).toBe(5);
+  });
+});
+```
+
+```typescript
+// After
+import { describe, expect, it } from "vitest";
+import { story } from "executable-stories-vitest";
+
+describe("Calculator", () => {
+  it("adds two numbers", ({ task }) => {
+    story.init(task);
+
+    story.given("two numbers 2 and 3");
+    const a = 2, b = 3;
+
+    story.when("they are added");
+    const result = add(a, b);
+
+    story.then("the result is 5");
+    expect(result).toBe(5);
+  });
+});
+```
+
+Key change: add `({ task })` to the callback parameter.
+
+### Step 3: Minimal story (test name only)
+
+If you want a test to appear in docs without step markers:
+
+```typescript
+it("subtracts two numbers", ({ task }) => {
+  story.init(task);
+  // Test runs normally, appears in report with test name as scenario title
+  expect(subtract(10, 4)).toBe(6);
+});
+```
+
+### Step 4: Add doc entries for richer output
+
+```typescript
+it("handles division by zero", ({ task }) => {
+  story.init(task, { tags: ["edge-case"] });
+
+  story.given("a divisor of zero");
+  story.note("This tests the error handling path");
+
+  story.when("division is attempted");
+  const fn = () => divide(10, 0);
+
+  story.then("an error is thrown");
+  expect(fn).toThrow("Division by zero");
+});
+```
+
+### Progressive adoption
+
+Convert tests one file at a time. Non-story tests continue working normally. The reporter only processes files matching `*.story.test.ts` with `story.init()` calls.
+
+## Common Mistakes
+
+### HIGH Forgetting ({ task }) in callback
+
+Wrong:
+
+```typescript
+it("my test", () => {
+  story.init(task); // ReferenceError: task is not defined
+});
+```
+
+Correct:
+
+```typescript
+it("my test", ({ task }) => {
+  story.init(task);
+});
+```
+
+Vitest passes the test context as the first callback argument. You must destructure `task` from it.
+
+Source: packages/executable-stories-vitest/src/story-api.ts
+
+### MEDIUM Using wrong file extension
+
+Wrong: `calculator.story.spec.ts` (Playwright convention)
+Correct: `calculator.story.test.ts` (Vitest convention)
+
+Source: CLAUDE.md — file naming conventions

package/skills/vitest-reporter-setup/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: vitest-reporter-setup
+description: >
+  Configure StoryReporter in vitest.config.ts for executable-stories-vitest.
+  Import from executable-stories-vitest/reporter subpath. OutputConfig with
+  formats, outputDir, outputName. Output modes: aggregated, colocated
+  (mirrored/adjacent). Markdown, HTML, JUnit, Cucumber JSON options.
+  GitHub Actions summary. rawRunPath for CLI consumption.
+type: core
+library: executable-stories-vitest
+library_version: "7.0.1"
+sources:
+  - "jagreehal/executable-stories:packages/executable-stories-vitest/src/reporter.ts"
+  - "jagreehal/executable-stories:apps/docs-site/src/content/docs/vitest/vitest-config.md"
+---
+
+# executable-stories-vitest — Reporter Setup
+
+## Setup
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { StoryReporter } from "executable-stories-vitest/reporter";
+
+export default defineConfig({
+  test: {
+    reporters: [
+      "default",
+      new StoryReporter({
+        formats: ["markdown", "html"],
+        outputDir: "docs",
+        outputName: "user-stories",
+      }),
+    ],
+  },
+});
+```
+
+Peer dependency: `executable-stories-formatters` must be installed.
+
+## Core Patterns
+
+### Output modes
+
+```typescript
+// Aggregated (default) — one file per format
+new StoryReporter({
+  formats: ["markdown"],
+  outputDir: "docs",
+  outputName: "user-stories",
+  output: { mode: "aggregated" },
+})
+// → docs/user-stories.md
+
+// Colocated mirrored — one file per source, directory mirrored
+new StoryReporter({
+  formats: ["markdown"],
+  outputDir: "docs",
+  output: { mode: "colocated", colocatedStyle: "mirrored" },
+})
+// test/auth/login.story.test.ts → docs/test/auth/login.story.md
+
+// Colocated adjacent — written next to the test file
+new StoryReporter({
+  formats: ["markdown"],
+  output: { mode: "colocated", colocatedStyle: "adjacent" },
+})
+// test/auth/login.story.test.ts → test/auth/login.story.md
+```
+
+### Format-specific options
+
+```typescript
+new StoryReporter({
+  formats: ["markdown", "html", "junit", "cucumber-json"],
+  outputDir: "reports",
+  markdown: {
+    title: "User Stories",
+    includeStatusIcons: true,
+    includeErrors: true,
+    includeMetadata: true,
+    sortScenarios: "source",
+    ticketUrlTemplate: "https://jira.example.com/browse/{ticket}",
+  },
+  html: {
+    title: "Test Report",
+    darkMode: true,
+    searchable: true,
+    startCollapsed: false,
+    embedScreenshots: true,
+  },
+  junit: {
+    suiteName: "My Test Suite",
+    includeOutput: true,
+  },
+  cucumberJson: { pretty: true },
+})
+```
+
+### Pattern-based output rules
+
+```typescript
+new StoryReporter({
+  formats: ["markdown"],
+  output: {
+    mode: "aggregated",
+    rules: [
+      {
+        match: "test/api/**",
+        mode: "colocated",
+        colocatedStyle: "adjacent",
+        formats: ["markdown", "html"],
+      },
+      {
+        match: "test/e2e/**",
+        outputDir: "docs/e2e",
+        outputName: "e2e-stories",
+      },
+    ],
+  },
+})
+```
+
+### Raw run output for CLI
+
+```typescript
+new StoryReporter({
+  formats: ["markdown"],
+  rawRunPath: "reports/raw-run.json",
+  enableGithubActionsSummary: true,
+})
+```
+
+## Common Mistakes
+
+### HIGH Importing StoryReporter from main package entry
+
+Wrong:
+
+```typescript
+import { StoryReporter } from "executable-stories-vitest";
+```
+
+Correct:
+
+```typescript
+import { StoryReporter } from "executable-stories-vitest/reporter";
+```
+
+The main entry exports a guard class that throws at construction time. The real `StoryReporter` lives at the `/reporter` subpath to keep heavy formatter dependencies out of test code.
+
+Source: packages/executable-stories-vitest/src/index.ts
+
+### HIGH Passing a string instead of OutputConfig object
+
+Wrong:
+
+```typescript
+new StoryReporter({ output: "docs/user-stories.md" })
+```
+
+Correct:
+
+```typescript
+new StoryReporter({
+  formats: ["markdown"],
+  outputDir: "docs",
+  outputName: "user-stories",
+})
+```
+
+The `output` property expects an `OutputConfig` object with `mode`, `colocatedStyle`, and `rules`. A string is silently treated as an object with all `undefined` fields, falling back to defaults.
+
+Source: packages/executable-stories-vitest/src/reporter.ts
+
+### MEDIUM Default format is cucumber-json, not markdown
+
+Wrong assumption:
+
+```typescript
+// Expecting markdown output
+new StoryReporter({ outputDir: "docs" })
+// → docs/test-results.cucumber.json (not .md)
+```
+
+Correct:
+
+```typescript
+new StoryReporter({
+  formats: ["markdown"],
+  outputDir: "docs",
+})
+```
+
+The default format is `["cucumber-json"]`, not `["markdown"]`. Always specify `formats` explicitly.
+
+Source: packages/executable-stories-vitest/src/reporter.ts
+
+See also: vitest-story-api/SKILL.md — Stories need the reporter to produce output
+See also: formatters-cli/SKILL.md — Reporter produces RawRun that CLI consumes

package/skills/vitest-story-api/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: vitest-story-api
+description: >
+  Write BDD stories in Vitest using executable-stories-vitest. Callback-only
+  API: story.init(task) with ({ task }) destructuring. Steps: given, when,
+  then, and, but. Doc entries: json, kv, code, table, link, section, mermaid,
+  note, tag, screenshot, custom. Auto-And keyword conversion. No top-level
+  then export. Aliases: arrange, act, assert. Inline docs via second argument.
+type: core
+library: executable-stories-vitest
+library_version: "7.0.1"
+sources:
+  - "jagreehal/executable-stories:packages/executable-stories-vitest/src/story-api.ts"
+  - "jagreehal/executable-stories:apps/docs-site/src/content/docs/vitest/vitest-story-api.md"
+---
+
+# executable-stories-vitest — Story API
+
+## Setup
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { story } from "executable-stories-vitest";
+
+describe("Cart checkout", () => {
+  it("applies discount code", ({ task }) => {
+    story.init(task, { tags: ["checkout"], ticket: "CART-42" });
+
+    story.given("a cart with items totaling $100");
+    const cart = createCart([{ name: "Shirt", price: 100 }]);
+
+    story.when("a 20% discount code is applied");
+    applyDiscount(cart, "SAVE20");
+
+    story.then("the total is $80");
+    expect(cart.total).toBe(80);
+
+    story.and("the discount is shown in the summary");
+    expect(cart.discounts).toHaveLength(1);
+  });
+});
+```
+
+File naming: `*.story.test.ts` or `*.story.spec.ts`.
+
+## Core Patterns
+
+### Step markers with Auto-And conversion
+
+First call to `given()`, `when()`, or `then()` renders the keyword as-is. Subsequent calls to the same keyword in the same story auto-convert to "And". Explicit `and()` always renders "And". Explicit `but()` always renders "But" and never auto-converts.
+
+```typescript
+it("blocks suspended user login", ({ task }) => {
+  story.init(task);
+
+  story.given("the user account exists");        // renders "Given"
+  story.given("the account is suspended");        // renders "And" (auto-converted)
+  story.when("the user submits valid credentials");
+  story.then("the user sees an error message");
+  story.but("the user is not logged in");         // renders "But" (always)
+  story.but("no session is created");             // renders "But" (always)
+});
+```
+
+### Doc entries attached to steps
+
+```typescript
+it("processes payment", ({ task }) => {
+  story.init(task);
+
+  story.given("a valid payment request");
+  story.json({ label: "Request payload", value: { amount: 50, currency: "USD" } });
+  story.kv({ label: "Gateway", value: "stripe" });
+
+  story.when("the payment is submitted");
+  story.code({ label: "Response", content: '{ "status": "ok" }', lang: "json" });
+
+  story.then("the order is confirmed");
+  story.table({
+    label: "Order summary",
+    columns: ["Item", "Qty", "Price"],
+    rows: [["Widget", "2", "$25"]],
+  });
+  story.link({ label: "API docs", url: "https://docs.example.com/payments" });
+  story.note("Payment processed in sandbox mode");
+});
+```
+
+### Inline docs via second argument
+
+```typescript
+story.given("valid credentials", {
+  json: { label: "Credentials", value: { user: "alice", role: "admin" } },
+  note: "Password masked for security",
+});
+```
+
+### Step wrappers with timing
+
+```typescript
+it("fetches user profile", ({ task }) => {
+  story.init(task);
+
+  story.given("a registered user");
+  const userId = "user-123";
+
+  const profile = await story.fn("When", "the profile is fetched", async () => {
+    return fetchProfile(userId);
+  });
+
+  await story.expect("the profile contains the correct name", () => {
+    expect(profile.name).toBe("Alice");
+  });
+});
+```
+
+## Common Mistakes
+
+### CRITICAL Missing task argument in story.init()
+
+Wrong:
+
+```typescript
+it("my test", () => {
+  story.init();
+  story.given("something");
+});
+```
+
+Correct:
+
+```typescript
+it("my test", ({ task }) => {
+  story.init(task);
+  story.given("something");
+});
+```
+
+Without `task`, story metadata is not linked to the test and the reporter cannot capture it. The `task` object comes from Vitest's test callback destructuring.
+
+Source: packages/executable-stories-vitest/src/story-api.ts
+
+### CRITICAL Importing top-level then from the package
+
+Wrong:
+
+```typescript
+import { story, then } from "executable-stories-vitest";
+```
+
+Correct:
+
+```typescript
+import { story } from "executable-stories-vitest";
+
+it("my test", ({ task }) => {
+  story.init(task);
+  story.then("result is correct");
+});
+```
+
+A top-level `then` export would make the module namespace thenable. Tools using `await import("executable-stories-vitest")` would treat the module as a Promise and invoke `then` unexpectedly. All step functions exist only on the `story` object.
+
+Source: CLAUDE.md — "Vitest: do not export top-level then"
+
+### HIGH Expecting but() to auto-convert to And
+
+Wrong:
+
+```typescript
+story.then("the user sees a success message");
+story.but("no email is sent");  // Developer expects this to render "And"
+```
+
+Correct:
+
+```typescript
+// but() always renders "But" — this is intentional for negative/contrast intent
+story.then("the user sees a success message");
+story.but("no email is sent");  // Renders "But" (correct for contrast)
+
+// Use and() if you want "And"
+story.then("the user sees a success message");
+story.and("no email is sent");  // Renders "And"
+```
+
+`but()` expresses negative intent or contrast and never auto-converts. This matches Gherkin semantics.
+
+Source: packages/executable-stories-vitest/src/story-api.ts
+
+### HIGH Calling steps before story.init()
+
+Wrong:
+
+```typescript
+it("my test", ({ task }) => {
+  story.given("something");
+  story.init(task);
+});
+```
+
+Correct:
+
+```typescript
+it("my test", ({ task }) => {
+  story.init(task);
+  story.given("something");
+});
+```
+
+Steps called before `init()` are silently dropped because no story context exists yet.
+
+Source: packages/eslint-plugin-executable-stories-vitest/src/rules/require-init-before-steps.ts
+
+See also: vitest-reporter-setup/SKILL.md — Stories need a reporter to produce output
+See also: eslint-vitest-rules/SKILL.md — ESLint enforces correct story.init() usage
+
+## Parameterized Scenarios (Scenario Outline equivalent)
+
+Use Vitest's `it.each` with `story()` to produce one scenario per data row — the framework-native replacement for Cucumber's Scenario Outline + Examples.
+
+```ts
+import { story } from "executable-stories-vitest";
+
+const cases = [
+  { input: 1, expected: 2 },
+  { input: 2, expected: 4 },
+  { input: 3, expected: 6 },
+];
+
+describe("Doubling", () => {
+  it.each(cases)("doubles $input to $expected", ({ input, expected }) => {
+    story(`Doubles ${input} to ${expected}`, (s) => {
+      s.given(`the input is ${input}`);
+      s.when("the doubler runs");
+      s.then(`the result is ${expected}`);
+      expect(input * 2).toBe(expected);
+    });
+  });
+});
+```
+
+Each iteration produces a separate scenario in the generated report. Use interpolated titles so each scenario has a distinct, descriptive name.