@step-forge/step-forge 0.0.7-beta.6 → 0.0.7

package/dts-bundle-generator.config.cjs

@@ -0,0 +1,19 @@
+const config = {
+  compilationOptions: {
+    preferredConfigPath: "./tsconfig.json",
+  },
+  entries: [
+    {
+      filePath: "./src/index.ts",
+      outFile: "./build/dist/index.d.ts",
+      noCheck: false,
+    },
+    {
+      filePath: "./src/analyzer/index.ts",
+      outFile: "./build/dist/analyzer.d.ts",
+      noCheck: false,
+    },
+  ],
+};
+
+module.exports = config;

package/features/TESTING.md

@@ -0,0 +1,100 @@
+# Testing
+
+All tests use Cucumber.js in a self-testing pattern: feature files in `features/` with step definitions in `features/steps/` exercise the library.
+
+## Test Scripts
+
+| Script                  | Profile   | Description                                                                                                         |
+| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------- |
+| `npm test`              | `all`     | Run all tests. Suppresses stderr for clean output. Use for normal development.                                      |
+| `npm run test:debug`    | `all`     | Run all tests with full output (stderr included). Use when a test fails and you need stack traces or error details. |
+| `npm run test:cucumber` | `default` | 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.
+
+There is no way to run a single test file. To run a subset, use Cucumber tags or modify the feature files temporarily.
+
+## Directory Structure
+
+```
+features/
+  basic.feature                   ← Builder pattern tests (variables, deps, state)
+  exported.feature                ← Re-exported builder tests
+  steps/
+    commonSteps.ts                ← Step defs for basic.feature
+    exportedSteps.ts              ← Step defs for exported.feature
+    analyzerSteps.ts              ← Step defs for analyzer tests
+    world.ts                      ← World state types
+  analyzer/
+    analyzer.feature              ← Analyzer test scenarios (run by Cucumber)
+    fixtures/
+      steps.ts                    ← Fixture step definitions (data, NOT run by Cucumber)
+      valid-no-deps.feature       ← Fixture feature files (data, NOT run by Cucumber)
+      valid-deps.feature
+      ...
+```
+
+## Builder Tests
+
+`basic.feature` and `exported.feature` test the core builder pattern — step registration, variable extraction, dependency resolution, and state merging. Their step definitions in `features/steps/` use the builders directly and assert on the resulting world state.
+
+Type-safety tests in `test/` use `@ts-expect-error` annotations and validate at `tsc` compile time, not at runtime.
+
+## Analyzer Tests
+
+The analyzer test suite under `features/analyzer/` tests the `analyze()` API against fixture files. The key distinction: **fixture files are data, not tests**. The analyzer's extractor reads `fixtures/steps.ts` as a TypeScript AST, and the parser reads `fixtures/*.feature` as Gherkin data. Cucumber never executes them.
+
+The `cucumber.mjs` config uses non-recursive path globs (`./features/*.feature`, `./features/analyzer/*.feature`) so fixture files in `features/analyzer/fixtures/` are excluded from Cucumber's test discovery.
+
+### Available Steps
+
+Step definitions in `features/steps/analyzerSteps.ts` provide:
+
+| Step                                      | Purpose                                                |
+| ----------------------------------------- | ------------------------------------------------------ |
+| `Given step definitions from {string}`    | Set the fixture step file (relative to `fixtures/`)    |
+| `Given a feature file {string}`           | Set the fixture feature file (relative to `fixtures/`) |
+| `When I analyze the files`                | Call `analyze()` with the configured files             |
+| `Then there should be no errors`          | Assert zero errors in diagnostics                      |
+| `Then there should be {int} error/errors` | Assert exact error count                               |
+| `Then an error should mention {string}`   | Assert an error message contains the substring         |
+
+### Adding New Analyzer Tests
+
+1. **Add step definition patterns** (if needed) to `features/analyzer/fixtures/steps.ts`. This file must be valid TypeScript that compiles, but it is never executed — only parsed by the AST extractor.
+
+2. **Create a fixture feature file** in `features/analyzer/fixtures/` using the step expressions from `steps.ts`. This file is parsed by the Gherkin parser as data.
+
+3. **Add a scenario** to `features/analyzer/analyzer.feature`:
+
+   ```gherkin
+   Scenario: Description of what you're testing
+     Given a feature file "your-new-fixture.feature"
+     When I analyze the files
+     Then there should be no errors
+   ```
+
+   The Background already provides `Given 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.
+
+### Fixture Step Definitions
+
+`features/analyzer/fixtures/steps.ts` contains builder calls covering these patterns:
+
+| Expression                    | Type  | Dependencies              | Produces  |
+| ----------------------------- | ----- | ------------------------- | --------- |
+| `a user`                      | given | none                      | `user`    |
+| `a user named {string}`       | given | none                      | `user`    |
+| `an account`                  | given | none                      | `account` |
+| `I started`                   | given | none                      | (nothing) |
+| `I save the user`             | when  | `given.user: required`    | `user`    |
+| `I delete the account`        | when  | `given.account: required` | `result`  |
+| `I got here`                  | when  | none                      | (nothing) |
+| `everything was good`         | then  | none                      | (nothing) |
+| `there is a user`             | then  | `when.user: required`     | (nothing) |
+| `the user's name is {string}` | then  | `when.user: required`     | (nothing) |
+| `the account might exist`     | then  | `given.account: optional` | (nothing) |
+
+When adding new patterns, add them to this file and they'll be available to all fixture feature files.

package/features/analyzer/analyzer.feature

@@ -0,0 +1,83 @@
+Feature: Analyzer dependency verification
+
+  Background:
+    Given step definitions from "steps.ts"
+
+  # --- Passing scenarios ---
+
+  Scenario: No dependencies produces no errors
+    Given a feature file "valid-no-deps.feature"
+    When I analyze the files
+    Then there should be no errors
+
+  Scenario: Satisfied required dependencies produce no errors
+    Given a feature file "valid-deps.feature"
+    When I analyze the files
+    Then there should be no errors
+
+  Scenario: Variables with satisfied dependencies produce no errors
+    Given a feature file "valid-variables.feature"
+    When I analyze the files
+    Then there should be no errors
+
+  Scenario: Optional dependencies not produced produce no errors
+    Given a feature file "valid-optional-deps.feature"
+    When I analyze the files
+    Then there should be no errors
+
+  Scenario: And/But keywords resolve correctly with satisfied deps
+    Given a feature file "valid-and-but-keywords.feature"
+    When I analyze the files
+    Then there should be no errors
+
+  # --- Undefined step scenarios ---
+
+  Scenario: Undefined step reports an error
+    Given a feature file "undefined-step.feature"
+    When I analyze the files
+    Then there should be 1 error
+    And there is 1 error for rule "undefined-step"
+    And an error should mention "I do something that does not exist"
+    And an error should mention "does not match any step definition"
+
+  Scenario: Undefined step combined with missing dependency
+    Given a feature file "undefined-with-missing-dep.feature"
+    When I analyze the files
+    Then there should be 2 errors
+    And there is 1 error for rule "undefined-step"
+    And an error should mention "I do something that does not exist"
+    And there is 1 error for rule "dependency-check"
+    And an error should mention "given.user"
+
+  # --- Ambiguous step scenarios ---
+
+  Scenario: Ambiguous step reports an error
+    Given a feature file "ambiguous-step.feature"
+    When I analyze the files
+    Then there should be 1 error
+    And there is 1 error for rule "ambiguous-step"
+    And an error should mention "matches multiple step definitions"
+
+  # --- Failing scenarios ---
+
+  Scenario: Missing required given dependency reports an error
+    Given a feature file "missing-given-dep.feature"
+    When I analyze the files
+    Then there should be 1 error
+    And there is 1 error for rule "dependency-check"
+    And an error should mention "given.user"
+
+  Scenario: Missing required when dependency reports an error
+    Given a feature file "missing-when-dep.feature"
+    When I analyze the files
+    Then there should be 1 error
+    And there is 1 error for rule "dependency-check"
+    And an error should mention "when.user"
+
+  Scenario: Multiple missing dependencies reports multiple errors
+    Given a feature file "missing-multiple-deps.feature"
+    When I analyze the files
+    Then there should be 2 errors
+    And there are 2 errors for rule "dependency-check"
+    And an error should mention "given.user"
+    And an error should mention "given.account"

package/features/analyzer/fixtures/ambiguous-step.feature

@@ -0,0 +1,5 @@
+Feature: Ambiguous step
+  Scenario: Uses an ambiguous step
+    Given the system is ready
+    When I got here
+    Then everything was good

package/features/analyzer/fixtures/missing-given-dep.feature

@@ -0,0 +1,5 @@
+Feature: Missing given dependency
+
+  Scenario: When step needs given.user but nothing produces it
+    When I save the user
+    Then everything was good

package/features/analyzer/fixtures/missing-multiple-deps.feature

@@ -0,0 +1,6 @@
+Feature: Multiple missing dependencies
+
+  Scenario: Multiple steps with missing deps
+    When I save the user
+    When I delete the account
+    Then there is a user

package/features/analyzer/fixtures/missing-when-dep.feature

@@ -0,0 +1,5 @@
+Feature: Missing when dependency
+
+  Scenario: Then step needs when.user but nothing produces it
+    Given a user
+    Then there is a user

package/features/analyzer/fixtures/steps.ts

@@ -0,0 +1,113 @@
+import { givenBuilder } from "../../../src/given";
+import { whenBuilder } from "../../../src/when";
+import { thenBuilder } from "../../../src/then";
+
+type GivenState = {
+  user: { type: string; token: string };
+  account: { id: string };
+};
+type WhenState = {
+  user: { type: string; token: string; saved: boolean };
+  result: { success: boolean };
+};
+type ThenState = Record<string, never>;
+
+// --- No dependency steps --- //
+
+givenBuilder<GivenState>()
+  .statement("I started")
+  .step(() => ({}))
+  .register();
+
+whenBuilder<GivenState, WhenState>()
+  .statement("I got here")
+  .step(() => ({}))
+  .register();
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement("everything was good")
+  .step(() => {})
+  .register();
+
+// --- Steps that produce state --- //
+
+givenBuilder<GivenState>()
+  .statement("a user")
+  .step(() => {
+    return {
+      user: { type: "person", token: "abc" },
+    };
+  })
+  .register();
+
+givenBuilder<GivenState>()
+  .statement((name: string) => `a user named ${name}`)
+  .step(({ variables: [name] }) => {
+    return {
+      user: { type: "person", token: name },
+    };
+  })
+  .register();
+
+givenBuilder<GivenState>()
+  .statement("an account")
+  .step(() => {
+    return {
+      account: { id: "acct-1" },
+    };
+  })
+  .register();
+
+// --- Ambiguous steps (same expression, two definitions) --- //
+
+givenBuilder<GivenState>()
+  .statement("the system is ready")
+  .step(() => ({}))
+  .register();
+
+givenBuilder<GivenState>()
+  .statement("the system is ready")
+  .step(() => ({}))
+  .register();
+
+// --- When steps with dependencies --- //
+
+whenBuilder<GivenState, WhenState>()
+  .statement("I save the user")
+  .dependencies({ given: { user: "required" } })
+  .step(({ given: { user } }) => {
+    return {
+      user: { ...user, saved: true },
+    };
+  })
+  .register();
+
+whenBuilder<GivenState, WhenState>()
+  .statement("I delete the account")
+  .dependencies({ given: { account: "required" } })
+  .step(() => {
+    return {
+      result: { success: true },
+    };
+  })
+  .register();
+
+// --- Then steps with dependencies --- //
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement("there is a user")
+  .dependencies({ when: { user: "required" } })
+  .step(() => {})
+  .register();
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement((name: string) => `the user's name is ${name}`)
+  .dependencies({ when: { user: "required" } })
+  .step(() => {})
+  .register();
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement("the account might exist")
+  .dependencies({ given: { account: "optional" } })
+  .step(() => {})
+  .register();

package/features/analyzer/fixtures/undefined-step.feature

@@ -0,0 +1,5 @@
+Feature: Undefined step
+  Scenario: Uses an undefined step
+    Given a user
+    When I do something that does not exist
+    Then everything was good

package/features/analyzer/fixtures/undefined-with-missing-dep.feature

@@ -0,0 +1,5 @@
+Feature: Undefined step with missing dependency
+  Scenario: Has both undefined and missing dependency
+    When I save the user
+    When I do something that does not exist
+    Then everything was good

package/features/analyzer/fixtures/valid-and-but-keywords.feature

@@ -0,0 +1,8 @@
+Feature: And/But keyword resolution
+
+  Scenario: And and But resolve correctly
+    Given a user
+    And an account
+    When I save the user
+    But I delete the account
+    Then there is a user

package/features/analyzer/fixtures/valid-deps.feature

@@ -0,0 +1,6 @@
+Feature: Satisfied dependencies
+
+  Scenario: Full chain with required deps
+    Given a user
+    When I save the user
+    Then there is a user

package/features/analyzer/fixtures/valid-no-deps.feature

@@ -0,0 +1,6 @@
+Feature: No dependencies
+
+  Scenario: Steps with no dependencies
+    Given I started
+    When I got here
+    Then everything was good

package/features/analyzer/fixtures/valid-optional-deps.feature

@@ -0,0 +1,6 @@
+Feature: Optional dependencies
+
+  Scenario: Optional dep not produced is fine
+    Given I started
+    When I got here
+    Then the account might exist

package/features/analyzer/fixtures/valid-variables.feature

@@ -0,0 +1,6 @@
+Feature: Variables with dependencies
+
+  Scenario: Variables and satisfied deps
+    Given a user named "John"
+    When I save the user
+    Then the user's name is "John"

package/features/basic.feature

@@ -0,0 +1,21 @@
+Feature: Steps written in gherkin can be matched to Step Forge steps
+
+    Scenario: Basic feature steps with no dependencies or variables can be run as a cucumber scenario
+        Given I started
+        When I got here
+        Then everything was good
+
+    Scenario: Basic feature steps with dependencies can be run as a cucumber scenario
+        Given a user
+        When I save the user
+        Then there is a user
+
+    Scenario: Basic feature steps with variables can be run as a cucumber scenario
+        Given a user named "John"
+        When I save the user
+        Then there is a user
+
+    Scenario: Basic feature steps with dependencies and variables can be run as a cucumber scenario
+        Given a user
+        When I name the user "John"
+        Then the user's name is "John"

package/features/exported.feature

@@ -0,0 +1,6 @@
+Feature: Builders can be re-exported for ease of use
+
+    Scenario: Exported steps can be used in cucumber scenarios
+        Given a bank user
+        When I deposit "1000" "USD"
+        Then the balance is "1000"

package/features/steps/analyzerSteps.ts

@@ -0,0 +1,53 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Given, When, Then } from "@cucumber/cucumber";
+import { expect } from "earl";
+import { analyze, Diagnostic } from "../../src/analyzer/index";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fixturesDir = path.resolve(__dirname, "../analyzer/fixtures");
+
+let fixtureStepFile: string;
+let fixtureFeatureFile: string;
+let diagnostics: Diagnostic[];
+
+Given("step definitions from {string}", function (fileName: string) {
+  fixtureStepFile = path.join(fixturesDir, fileName);
+});
+
+Given("a feature file {string}", function (fileName: string) {
+  fixtureFeatureFile = path.join(fixturesDir, fileName);
+});
+
+When("I analyze the files", async function () {
+  diagnostics = await analyze({
+    stepFiles: [fixtureStepFile],
+    featureFiles: [fixtureFeatureFile],
+  });
+});
+
+Then("there should be no errors", function () {
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  expect(errors).toHaveLength(0);
+});
+
+Then("there should be {int} error/errors", function (count: number) {
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  expect(errors).toHaveLength(count);
+});
+
+Then("an error should mention {string}", function (substring: string) {
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  const found = errors.some((e) => e.message.includes(substring));
+  expect(found).toEqual(true);
+});
+
+Then(
+  "there is/are {int} error/errors for rule {string}",
+  function (count: number, rule: string) {
+    const errors = diagnostics.filter(
+      (d) => d.severity === "error" && d.rule === rule
+    );
+    expect(errors).toHaveLength(count);
+  }
+);

package/features/steps/commonSteps.ts

@@ -0,0 +1,93 @@
+import { givenBuilder } from "../../src/given";
+import { whenBuilder } from "../../src/when";
+import { thenBuilder } from "../../src/then";
+import { GivenState, ThenState, WhenState } from "./world";
+import { expect } from "earl";
+
+// --- No dependency no variable steps --- //
+givenBuilder<GivenState>()
+  .statement("I started")
+  .step(() => ({}))
+  .register();
+
+whenBuilder<GivenState, WhenState>()
+  .statement("I got here")
+  .step(() => ({}))
+  .register();
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement("everything was good")
+  .step(() => ({}))
+  .register();
+
+// --- Dependency only steps --- //
+givenBuilder<GivenState>()
+  .statement("a user")
+  .step(() => {
+    return {
+      user: {
+        type: "person",
+        token: "random",
+      },
+    };
+  })
+  .register();
+
+whenBuilder<GivenState, WhenState>()
+  .statement("I save the user")
+  .dependencies({ given: { user: "required" } })
+  .step(({ given: { user } }) => {
+    return {
+      user: {
+        ...user,
+        saved: true,
+      },
+    };
+  })
+  .register();
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement("there is a user")
+  .dependencies({ when: { user: "required" } })
+  .step(({ when: { user } }) => {
+    expect(user.saved).toBeTruthy();
+  })
+  .register();
+
+// --- Variable only steps --- //
+givenBuilder<GivenState>()
+  .statement((userName: string) => `a user named ${userName}`)
+  .step(({ variables: [userName] }) => {
+    return {
+      user: {
+        type: "person",
+        token: userName,
+      },
+    };
+  })
+  .register();
+
+// --- More complex steps --- //
+
+whenBuilder<GivenState, WhenState>()
+  .statement((userName: string) => `I name the user ${userName}`)
+  .dependencies({ given: { user: "required" } })
+  .step(({ given: { user }, variables: [userName] }) => {
+    return {
+      user: {
+        ...user,
+        token: userName,
+        saved: true,
+      },
+    };
+  })
+  .register();
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement((userName: string) => `the user's name is ${userName}`)
+  .dependencies({ when: { user: "required" } })
+  .step(({ when: { user }, variables: [userName] }) => {
+    const token = user.token;
+    expect(token).toEqual(userName);
+  })
+  .register();

package/features/steps/exportedSteps.ts

@@ -0,0 +1,42 @@
+import { expect } from "earl";
+import { givenBuilder } from "../../src/given";
+import { thenBuilder } from "../../src/then";
+import { whenBuilder } from "../../src/when";
+import { GivenState, ThenState, WhenState } from "./world";
+
+const Given = givenBuilder<GivenState>().statement;
+const When = whenBuilder<GivenState, WhenState>().statement;
+const Then = thenBuilder<GivenState, WhenState, ThenState>().statement;
+
+Given("a bank user")
+  .step(() => {
+    return {
+      user: {
+        type: "customer",
+        token: "random",
+      },
+    };
+  })
+  .register();
+
+When((amount: string, currency: string) => `I deposit ${amount} ${currency}`)
+  .dependencies({ given: { user: "required" } })
+  .step(({ variables: [rawAmount, currency], given: { user } }) => {
+    const amount = parseFloat(rawAmount);
+    return {
+      deposit: {
+        amount,
+        currency,
+        user,
+      },
+    };
+  })
+  .register();
+
+Then((amount: string) => `the balance is ${amount}`)
+  .dependencies({ when: { deposit: "required" } })
+  .step(({ when: { deposit }, variables: [rawAmount] }) => {
+    const amount = parseFloat(rawAmount);
+    expect(deposit.amount).toEqual(amount);
+  })
+  .register();

package/features/steps/world.ts

@@ -0,0 +1,29 @@
+import { setWorldConstructor } from "@cucumber/cucumber";
+import { BasicWorld } from "../../src/world";
+
+export interface GivenState {
+  user: {
+    type: string;
+    token: string;
+  };
+}
+
+export interface WhenState {
+  user: {
+    type: string;
+    token: string;
+    saved: boolean;
+  };
+  deposit: {
+    amount: number;
+    currency: string;
+    user: {
+      type: string;
+      token: string;
+    };
+  };
+}
+
+export interface ThenState {}
+
+setWorldConstructor(BasicWorld<GivenState, WhenState, ThenState>);