@step-forge/step-forge 0.0.7-beta.7 → 0.0.8

package/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(NODE_ENV=test NODE_OPTIONS=\"--experimental-specifier-resolution=node --loader ts-node/esm\" TS_NODE_PROJECT=./tsconfig.cucumber.json cucumber-js:*)",
+      "Bash(NODE_ENV=test NODE_OPTIONS=\"--experimental-specifier-resolution=node --loader ts-node/esm\" TS_NODE_PROJECT=./tsconfig.cucumber.json npx cucumber-js:*)",
+      "Bash(npm run test:cucumber:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm run build:*)",
+      "Bash(git stash:*)",
+      "Bash(npm install:*)",
+      "Bash(npm run test:debug:*)",
+      "Bash(npm test:*)",
+      "Bash(git -C /Users/ellisande/dev/step-forge log --oneline -10)",
+      "Bash(git -C /Users/ellisande/dev/step-forge branch:*)"
+    ]
+  }
+}

package/.eslintignore

@@ -0,0 +1,6 @@
+.history
+.husky
+.vscode
+coverage
+dist
+node_modules

package/.eslintrc

@@ -0,0 +1,18 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint", "prettier"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "env": {
+    "browser": true,
+    "node": true
+  },
+  "rules": {
+    "prettier/prettier": "error"
+  }
+}

package/.prettierignore

@@ -0,0 +1,6 @@
+.history
+.husky
+.vscode
+coverage
+dist
+node_modules

package/.prettierrc

@@ -0,0 +1,15 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "useTabs": false,
+  "endOfLine": "auto",
+  "singleAttributePerLine": false,
+  "bracketSameLine": false,
+  "jsxSingleQuote": false,
+  "quoteProps": "as-needed",
+  "semi": true
+}

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Change Log
+
+All notable changes to the "@step-forge/step-forge" project will be documented in this file.
+
+## [0.0.5] - 2024-12-31
+
+- Add support for exporting steps
+
+## [0.0.4] - 2024-07-30
+
+- Update all packages to the latest versions
+- Remove support for CommonJS modules
+
+## [0.0.3] - 2024-01-23
+
+- Update all packages to the latest versions (update to vite 5.x)
+
+## [0.0.2] - 2023-01-18
+
+- Update all packages to the latest versions (update to vite 4.x)
+
+## [0.0.1] - 2022-09-08
+
+- Update all packages to the latest versions (update to vite 3.x)
+
+## [0.0.0] - 2022-03-28
+
+- Initial release

package/CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm test                # Run all tests (Cucumber.js, suppresses stderr)
+npm run test:debug      # Run all tests with full output (use when debugging failures)
+npm run test:cucumber   # Run with default Cucumber profile
+npm run test:ci         # Run with CI profile
+npm run build           # Full build: clean → tsc → rolldown → dts-bundle-generator → copy
+npm run lint            # ESLint
+npm run format          # Prettier
+```
+
+## Architecture
+
+Step Forge is a TypeScript library that wraps Cucumber.js with a type-safe builder pattern for step definitions.
+
+### Builder Chain
+
+Each Gherkin phase (given/when/then) has a builder that follows this chain:
+
+```
+builder<State>().statement(str | fn) → .dependencies?(deps) → .step(fn) → .register()
+```
+
+- **Statement**: A string or function. Functions define variables via parameters: `(name: string) => \`a user named ${name}\`` — each parameter becomes a `{string}` placeholder in the Gherkin expression.
+- **Dependencies**: Declare which keys from other phases' state this step needs. Keys are marked `"required"` or `"optional"`. Required deps are validated at runtime; optional ones may be `undefined`.
+- **Step function**: Receives `{ variables, given, when, then }` — only the phases allowed by the builder type are accessible (given steps can't access when/then state).
+- **Register**: Calls the corresponding Cucumber.js `Given`/`When`/`Then` to wire everything up.
+
+### Phase Restrictions
+
+- `givenBuilder` — dependencies on `given` only, returns `Partial<GivenState>`
+- `whenBuilder` — dependencies on `given` and `when`, returns `Partial<WhenState>`
+- `thenBuilder` — dependencies on all three phases, returns `Partial<ThenState> | void`
+
+### Key Source Files
+
+- `src/common.ts` — `addStep()`: core registration that wires parsers, dependency validation, and state merging into Cucumber
+- `src/given.ts`, `src/when.ts`, `src/then.ts` — Builder implementations with phase-specific type constraints
+- `src/world.ts` — `BasicWorld<Given, When, Then>` with `MergeableWorldState` (lodash deep merge, arrays concatenate)
+- `src/builderTypeUtils.ts` — TypeScript utility types driving the builder's type safety
+- `src/utils.ts` — `typeCoercer()` for string→typed conversion, `requireFrom{Given,When,Then}()` for runtime dep validation
+
+### Testing
+
+Tests use Cucumber.js itself (self-testing). Feature files in `features/` with step definitions in `features/steps/` exercise the library. Type-safety tests in `test/` use `@ts-expect-error` annotations — they validate at `tsc` compile time, not at runtime.
+
+#### Test Scripts
+
+| Script | Profile | Description |
+|---|---|---|
+| `npm test` | `all` | Run all tests. Suppresses stderr (`2> /dev/null`) for clean output. Use this for normal development. |
+| `npm run test:debug` | `all` | Run all tests with full output (stderr included). Use this when a test fails and you need stack traces or error details. |
+| `npm run test:cucumber` | `default` | Run tests using the `default` Cucumber profile. Same paths as `all`, but does not set `PORT` or `LOG_LEVEL`. |
+| `npm run test:ci` | `ci` | CI-oriented profile. Does not import `src/**/*.ts` (only step defs). Enables `publish`. |
+
+All profiles run with `parallel: 1` and use `tsx` as the TypeScript loader via `NODE_OPTIONS='--import tsx'`.
+
+There is no way to run a single test file. To run a subset, use Cucumber tags or modify the feature files temporarily.
+
+#### Analyzer Tests
+
+The analyzer has its own test suite under `features/analyzer/` that tests the `analyze()` API against fixture files. The fixtures are **data** — they are read by the analyzer's extractor and parser, not executed by Cucumber.
+
+```
+features/analyzer/
+  analyzer.feature                ← Test scenarios (run by Cucumber)
+  fixtures/
+    steps.ts                      ← Fixture step definitions (read by extractor as data)
+    valid-no-deps.feature         ← Fixture feature files (read by parser as data)
+    valid-deps.feature
+    missing-given-dep.feature
+    ...
+```
+
+The `cucumber.mjs` config uses non-recursive path globs (`./features/*.feature`, `./features/analyzer/*.feature`) to ensure fixture files in `features/analyzer/fixtures/` are never executed as tests.
+
+Step definitions in `features/steps/analyzerSteps.ts` provide these steps:
+
+- `Given step definitions from {string}` — sets the fixture step file (relative to `fixtures/`)
+- `Given a feature file {string}` — sets the fixture feature file (relative to `fixtures/`)
+- `When I analyze the files` — calls `analyze()` with the configured files
+- `Then there should be no errors` — asserts zero errors
+- `Then there should be {int} error/errors` — asserts exact error count
+- `Then an error should mention {string}` — asserts an error message contains the substring
+
+#### Adding New Analyzer Tests
+
+1. **If you need new step definition patterns**, add builder calls to `features/analyzer/fixtures/steps.ts`. This file is only parsed by the TypeScript AST extractor — it is never executed, but it must be valid TypeScript that compiles.
+
+2. **Create a fixture feature file** in `features/analyzer/fixtures/` that uses the step expressions defined in `steps.ts`. This file is parsed by the Gherkin parser as data — Cucumber never runs it.
+
+3. **Add a scenario** to `features/analyzer/analyzer.feature`:
+   ```gherkin
+   Scenario: Description of what you're testing
+     Given step definitions from "steps.ts"
+     Given a feature file "your-new-fixture.feature"
+     When I analyze the files
+     Then there should be no errors
+   ```
+   The Background already provides `step definitions from "steps.ts"`, so you only need the `Given a feature file` line in each scenario.
+
+4. **Run `npm run test:debug`** to verify. Use `test:debug` instead of `npm test` so you can see error details if something fails.
+
+### Build Output
+
+Vite produces ESM (`dist/step-forge.js`) and `dts-bundle-generator` creates a single `dist/index.d.ts`. The `build/` directory contains the publishable package.
+
+## Exports
+
+`givenBuilder`, `whenBuilder`, `thenBuilder`, `BasicWorld` — all from `src/index.ts`.

package/README.md

@@ -2,14 +2,16 @@
 
 Step Forge is a typed wrapper around the Cucumber library. It provides an opinionated way to define steps, work with scenario state, and enforce dependencies between steps.
 
+This is just a primer, see the [official documentation site](https://step-forge.com) for more information.
+
 ## Installation
 
 ```bash
 npm install @step-forge/step-forge
 ```
 
-
 ## Getting Started
+
 ### Setting Up World State
 
 ```ts
@@ -53,6 +55,7 @@ givenBuilder<GivenState>()
 ```
 
 This creates a cucumber step that conceptually looks like this:
+
 ```ts
 Given("a user", function (this: World) {
   this.given.merge({
@@ -77,7 +80,7 @@ type GivenState = {
 
 givenBuilder<GivenState>()
   .statement((userName: string) => `a user named ${userName}`)
-  .step(({ variables: [ userName ] }) => {
+  .step(({ variables: [userName] }) => {
     return {
       user: userName,
     };
@@ -90,6 +93,7 @@ Here you can see that you can pass a template function to the statement that wil
 > Note: Right now only `string` variables are supported, but we're working to improve this.
 
 This creates a cucumber step that conceptually looks like this:
+
 ```ts
 Given("a user named {name}", function (this: World, name: string) {
   this.given.merge({
@@ -111,15 +115,15 @@ type GivenState = {
   user: {
     name: string;
     realName: string;
-  }
+  };
 };
 
 givenBuilder<GivenState>()
   .statement((userName: string) => `a user named ${userName}`)
   // Since this is a given step, only allow dependencies on given state
   // Strongly typed to ensure you can't depend on something not in given state
-  .dependencies({ given: { realName: "required"}})
-  .step(({ variables: [ userName ], given: { realName } }) => {
+  .dependencies({ given: { realName: "required" } })
+  .step(({ variables: [userName], given: { realName } }) => {
     return {
       user: {
         name: userName,
@@ -134,6 +138,7 @@ givenBuilder<GivenState>()
 Now this is getting more interesting. We've added a dependency on the `realName` part of given state. Step Forge strongly types dependencies based on your world state, and properly restricts access based on the step type. Additionally, since `realName` is required Step Forge will fail the scenario if it doesn't exist when the step is run.
 
 This creates a cucumber step that conceptually looks like this:
+
 ```ts
 Given("a user named {name}", function (this: World, name: string) {
   if (!this.given.realName) {
@@ -174,34 +179,38 @@ type GivenState = {
   user: {
     name: string;
     realName: string;
-  }
-}
+  };
+};
 
 type WhenState = {
   user: {
     name: string;
     realName: string;
-  }
-}
+  };
+};
 
-type ThenState = {}
+type ThenState = {};
 
 thenBuilder<GivenState, WhenState, ThenState>()
   .statement("the user's real name should not change")
   .dependencies({
     given: { realName: "required" },
-    when: { user: "required" }
-  })
-  .step(({ given: { realName: expectedRealName }, when: { user: updatedUser } }) => {
-    expect(updatedUser.realName).toEqual(expectedRealName);
-    // Then steps can return void if they are not adding anything to `then` state
+    when: { user: "required" },
   })
+  .step(
+    ({
+      given: { realName: expectedRealName },
+      when: { user: updatedUser },
+    }) => {
+      expect(updatedUser.realName).toEqual(expectedRealName);
+      // Then steps can return void if they are not adding anything to `then` state
+    }
+  )
   .register();
 ```
 
 Even though we have complex dependencies across multiple parts of state, Step Forge ensures that the dependencies are properly enforced. It also provides type safety ensuring that the step can't depend on something from state that isn't explicitly declared.
 
-
 ### Simpler Step Definitions
 
 > Note: Defining steps this way currently doesn't work with the vs code extension. We're working to improve this.
@@ -224,15 +233,15 @@ import { Given } from "./common";
 
 // You can now start your definition with the statement directly, without having to provide GivenState or chain through the builder.
 Given("a user")
-.dependencies({ given: { realName: "required" } })
-.step(({ given: { realName } }) => {
-  return {
-    user: {
-      realName,
-    },
-  };
-})
-.register();
+  .dependencies({ given: { realName: "required" } })
+  .step(({ given: { realName } }) => {
+    return {
+      user: {
+        realName,
+      },
+    };
+  })
+  .register();
 ```
 
 ### Compile Time Gherkin Analysis
@@ -251,21 +260,21 @@ type GivenState = {
   name: string;
   user: {
     name: string;
-  }
-}
+  };
+};
 
 Given((name: string) => `a user named ${name}`)
-.step(({ variables: [ name ] }) => {
-  return { name }
-})
-.register();
+  .step(({ variables: [name] }) => {
+    return { name };
+  })
+  .register();
 
 When("I save the user")
-.dependencies({ given: { user: "required" } })
-.step(({ given: { user } }) => {
-  // save the user
-})
-.register();
+  .dependencies({ given: { user: "required" } })
+  .step(({ given: { user } }) => {
+    // save the user
+  })
+  .register();
 ```
 
 ```gherkin
@@ -284,6 +293,3 @@ Feature: Updating a user's username
 Additionally when adding a step to a feature file, if the step has unfulfilled dependencies, the extension will show a list of steps that can be used to fulfill the dependencies.
 
 ![Step Forge Autocomplete Demo](./docs/assets/state_deps.gif)
-
-
-

package/cucumber.mjs

@@ -0,0 +1,39 @@
+const defaultProfile = {
+  format: [
+    process.env.CI || !process.stdout.isTTY ? "progress" : "progress-bar",
+    "json:./reports/cucumber-json-reports/report.json",
+    "rerun:./reports/cucumber/@rerun.txt",
+    "usage:./reports/cucumber/usage.txt",
+  ],
+  parallel: 1,
+  paths: [
+    "./features/*.feature",
+    "./features/analyzer/*.feature",
+  ],
+  import: [
+    "./features/steps/**/*.ts",
+    "./features/steps/*.ts",
+    "./src/**/*.ts",
+  ],
+  strict: false,
+};
+
+const ciProfile = {
+  format: [
+    process.env.CI || !process.stdout.isTTY ? "progress" : "progress-bar",
+    "json:./reports/cucumber-json-reports/report.json",
+    "rerun:./reports/cucumber/@rerun.txt",
+    "usage:./reports/cucumber/usage.txt",
+  ],
+  parallel: 1,
+  import: ["./features/steps/**/*.ts", "./features/steps/*.ts"],
+  strict: false,
+  publish: true,
+};
+
+const all = {
+  ...defaultProfile,
+};
+
+export { ciProfile as ci, all };
+export default defaultProfile;

package/dist/step-forge.cjs

@@ -1 +1 @@
-"use strict";var M=Object.defineProperty;var $=(e,n,t)=>n in e?M(e,n,{enumerable:!0,configurable:!0,writable:!0,value:t}):e[n]=t;var h=(e,n,t)=>$(e,typeof n!="symbol"?n+"":n,t);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("@cucumber/cucumber"),z=require("lodash"),j=e=>e&&e.__esModule?e:{default:e},c=j(z),d=e=>typeof e=="string",A=(e,n)=>(e.forEach(t=>{if(!n.given[t])throw new Error(`Key ${String(t)} is required in given state`)}),e.reduce((t,r)=>({...t,[r]:n.given[r]}),{})),C=(e,n)=>(e.forEach(t=>{if(!n.when[t])throw new Error(`Key ${String(t)} is required in when state`)}),e.reduce((t,r)=>({...t,[r]:n.when[r]}),{})),P=(e,n)=>(e.forEach(t=>{if(!n.then[t])throw new Error(`Key ${String(t)} is required in then state`)}),e.reduce((t,r)=>({...t,[r]:n.then[r]}),{})),N=e=>{const n=parseInt(e,10);return isNaN(n)?e==="true"?!0:e==="false"?!1:e:n},I={given:o.Given,when:o.When,then:o.Then},u=(e,n,t={given:{},when:{},then:{}})=>r=>{const s=e,{given:g,when:l,then:f}=t;return{statement:e,dependencies:t,stepType:n,stepFunction:r,register:()=>{const w=s.length,v=Array.from({length:w},()=>"{string}"),m=s(...v),S=Object.defineProperty(async function(...q){const D=q.map(N),F=Object.entries(g??{}).filter(([,i])=>i==="required").map(([i])=>i),O=A(F,this),b={...c.default.pick(this.given,Object.keys(g??{})),...O},B=Object.entries(l??{}).filter(([,i])=>i==="required").map(([i])=>i),E=C(B,this),W={...c.default.pick(this.when,Object.keys(l??{})),...E},_=Object.entries(f??{}).filter(([,i])=>i==="required").map(([i])=>i),y=P(_,this),K={...c.default.pick(this.then,Object.keys(f??{})),...y},G=await r({variables:D,given:b,when:W,then:K});this[n].merge({...G})},"length",{value:w,configurable:!0}),p=I[n];return p(m,S),{stepType:n,dependencies:t,statement:s,stepFunction:r}}}},x=(e,n)=>t=>{const r={...t,when:{},then:{}};return{step:u(e,n,r)}},H=e=>n=>{let t;d(n)?t=()=>n:t=n;const r=x(t,e),s=u(t,e);return{dependencies:r,step:s}},J=()=>({statement:H("given")}),L=(e,n)=>t=>{const r={given:t.given??{},when:t.when??{},then:{}};return{step:u(e,n,r)}},Q=e=>n=>{let t;d(n)?t=()=>n:t=n;const r=L(t,e),s=u(t,e);return{dependencies:r,step:s}},R=()=>({statement:Q("when")}),T=(e,n)=>t=>{const r={given:t.given??{},when:t.when??{},then:t.then??{}};return{step:u(e,n,r)}},U=e=>n=>{let t;d(n)?t=()=>n:t=n;const r=T(t,e),s=u(t,e);return{dependencies:r,step:s}},X=()=>({statement:U("then")});function a(e,n){if(c.default.isArray(e))return e.concat(n);if(e&&!c.default.isPlainObject(e)&&e!==n)throw new Error(`Merge would have destroyed previous value ${e} with ${n}`);return e}class Y{constructor(){h(this,"givenState",{});h(this,"whenState",{});h(this,"thenState",{})}get given(){return{...this.givenState,merge:n=>{this.givenState=c.default.merge({...this.givenState},n,a)}}}get when(){return{...this.whenState,merge:n=>{this.whenState=c.default.merge({...this.whenState},n,a)}}}get then(){return{...this.thenState,merge:n=>{this.thenState=c.default.merge({...this.thenState},n,a)}}}}exports.BasicWorld=Y;exports.givenBuilder=J;exports.thenBuilder=X;exports.whenBuilder=R;
+"use strict";var C=Object.defineProperty;var I=(e,n,t)=>n in e?C(e,n,{enumerable:!0,configurable:!0,writable:!0,value:t}):e[n]=t;var u=(e,n,t)=>I(e,typeof n!="symbol"?n+"":n,t);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=require("@cucumber/cucumber"),x=require("lodash"),H=e=>e&&e.__esModule?e:{default:e},o=H(x),f=e=>typeof e=="string",J=(e,n)=>(e.forEach(t=>{if(!n.given[t])throw new Error(`Key ${String(t)} is required in given state`)}),e.reduce((t,r)=>({...t,[r]:n.given[r]}),{})),L=(e,n)=>(e.forEach(t=>{if(!n.when[t])throw new Error(`Key ${String(t)} is required in when state`)}),e.reduce((t,r)=>({...t,[r]:n.when[r]}),{})),N=(e,n)=>(e.forEach(t=>{if(!n.then[t])throw new Error(`Key ${String(t)} is required in then state`)}),e.reduce((t,r)=>({...t,[r]:n.then[r]}),{})),q={parse:e=>e,gherkin:"{string}"},Q={parse:e=>parseInt(e,10),gherkin:"{int}"},R={parse:e=>parseFloat(e),gherkin:"{double}"},U={parse:e=>e==="true",gherkin:"{string}"},X={given:g.Given,when:g.When,then:g.Then},c=(e,n,t={given:{},when:{},then:{}},r)=>i=>{const h=e,{given:v,when:w,then:m}=t;return{statement:e,dependencies:t,stepType:n,stepFunction:i,register:()=>{const a=h.length,S=r??Array.from({length:a},()=>q),D=Array.from({length:a},(p,d)=>S[d].gherkin),O=h(...D),B=Object.defineProperty(async function(...p){const d=p.filter(s=>typeof s!="function").map((s,y)=>S[y].parse(s)),E=Object.entries(v??{}).filter(([,s])=>s==="required").map(([s])=>s),W=J(E,this),K={...o.default.pick(this.given,Object.keys(v??{})),...W},G=Object.entries(w??{}).filter(([,s])=>s==="required").map(([s])=>s),M=L(G,this),$={...o.default.pick(this.when,Object.keys(w??{})),...M},z=Object.entries(m??{}).filter(([,s])=>s==="required").map(([s])=>s),A=N(z,this),j={...o.default.pick(this.then,Object.keys(m??{})),...A},k=await i({variables:d,given:K,when:$,then:j});this[n].merge({...k})},"length",{value:a,configurable:!0}),_=X[n];return _(O,B),{stepType:n,dependencies:t,statement:h,stepFunction:i}}}},P=(e,n,t)=>r=>{const i={...r,when:{},then:{}};return{step:c(e,n,i,t)}},Y=(e,n)=>t=>({dependencies:P(e,n,t),step:c(e,n,void 0,t)}),Z=e=>n=>{let t;return f(n)?t=()=>n:t=n,{dependencies:P(t,e),parsers:Y(t,e),step:c(t,e)}},V=()=>({statement:Z("given")}),F=(e,n,t)=>r=>{const i={given:r.given??{},when:r.when??{},then:{}};return{step:c(e,n,i,t)}},T=(e,n)=>t=>({dependencies:F(e,n,t),step:c(e,n,void 0,t)}),ee=e=>n=>{let t;f(n)?t=()=>n:t=n;const r=F(t,e),i=T(t,e),h=c(t,e);return{dependencies:r,parsers:i,step:h}},ne=()=>({statement:ee("when")}),b=(e,n,t)=>r=>{const i={given:r.given??{},when:r.when??{},then:r.then??{}};return{step:c(e,n,i,t)}},te=(e,n)=>t=>({dependencies:b(e,n,t),step:c(e,n,void 0,t)}),re=e=>n=>{let t;f(n)?t=()=>n:t=n;const r=b(t,e),i=c(t,e),h=te(t,e);return{dependencies:r,parsers:h,step:i}},se=()=>({statement:re("then")});function l(e,n){if(o.default.isArray(e))return e.concat(n);if(e&&!o.default.isPlainObject(e)&&e!==n)throw new Error(`Merge would have destroyed previous value ${e} with ${n}`);return e}class ie{constructor(){u(this,"givenState",{});u(this,"whenState",{});u(this,"thenState",{})}get given(){return{...this.givenState,merge:n=>{this.givenState=o.default.merge({...this.givenState},n,l)}}}get when(){return{...this.whenState,merge:n=>{this.whenState=o.default.merge({...this.whenState},n,l)}}}get then(){return{...this.thenState,merge:n=>{this.thenState=o.default.merge({...this.thenState},n,l)}}}}exports.BasicWorld=ie;exports.booleanParser=U;exports.givenBuilder=V;exports.intParser=Q;exports.numberParser=R;exports.stringParser=q;exports.thenBuilder=se;exports.whenBuilder=ne;