@step-forge/step-forge 0.0.19 → 0.0.21

package/dist/hooks-Dar49TtT.d.cts

@@ -0,0 +1,189 @@
+//#region src/parsers.d.ts
+/**
+ * A Parser is a typed cucumber-expression *parameter type*: it declares how a
+ * value is recognised in a Gherkin step (`regexp`) and how the matched text is
+ * turned into a TypeScript value (`parse`). The step expression uses `{name}`
+ * as the placeholder.
+ *
+ * The engine folds each parser straight into the cucumber-expression matcher —
+ * `parse` is the parameter type's transform, so coercion happens exactly once,
+ * during matching (no second pass). This is also what lets a parser introduce a
+ * brand-new placeholder like `{color}`: it is registered as a real parameter
+ * type, so text that doesn't match `regexp` simply doesn't match the step.
+ *
+ * The four built-ins below reuse cucumber-expressions' own built-in parameter
+ * types (`{int}`, `{float}`, `{string}`) — those names are already registered,
+ * so the library performs the match + coercion and each parser's `regexp`/
+ * `parse` serve to document intent and to drive TypeScript inference of the
+ * variable type. `booleanParser` has no built-in equivalent, so it is a genuine
+ * custom parameter type whose `parse` runs at match time.
+ */
+type Parser<T> = {
+  /** Parameter-type name; the step expression uses `{name}` as the placeholder. */name: string; /** How cucumber-expressions recognises the value in the step text. */
+  regexp: RegExp | RegExp[]; /** Transform the matched text into the typed value. */
+  parse: (value: string) => T;
+};
+/** Matches a quoted string (`{string}`) and strips the surrounding quotes. */
+declare const stringParser: Parser<string>;
+/** Matches an unquoted integer (`{int}`). */
+declare const intParser: Parser<number>;
+/** Matches an unquoted floating point number (`{float}`). */
+declare const numberParser: Parser<number>;
+/**
+ * Matches an unquoted `true`/`false` word (`{boolean}`) and parses it to a
+ * boolean. Unlike the others this is a genuine custom parameter type — cucumber
+ * has no built-in `boolean` — so its `regexp`/`parse` are what the matcher uses.
+ */
+declare const booleanParser: Parser<boolean>;
+//#endregion
+//#region src/world.d.ts
+type WorldState<State> = { readonly [K in keyof State]?: State[K] };
+type MergeableWorldState<T> = WorldState<T> & {
+  merge: (newState: Partial<T>) => void;
+};
+type MergeableWorld<Given, When, Then> = {
+  given: MergeableWorldState<Given>;
+  when: MergeableWorldState<When>;
+  then: MergeableWorldState<Then>;
+};
+declare class BasicWorld<Given, When, Then> {
+  private givenState;
+  private whenState;
+  private thenState;
+  get given(): MergeableWorldState<Given>;
+  get when(): MergeableWorldState<When>;
+  get then(): MergeableWorldState<Then>;
+}
+//#endregion
+//#region src/analyzer/types.d.ts
+interface StepDefinitionMeta {
+  stepType: "given" | "when" | "then";
+  expression: string;
+  dependencies: {
+    given: Record<string, "required" | "optional">;
+    when: Record<string, "required" | "optional">;
+    then: Record<string, "required" | "optional">;
+  };
+  produces: string[];
+  sourceFile: string;
+  line: number;
+}
+interface ParsedScenario {
+  name: string;
+  file: string;
+  steps: ParsedStep[];
+  /**
+   * Gherkin tags in effect for this scenario, each including the leading `@`
+   * (feature + scenario tags, plus the Examples-block tags for outline rows).
+   * The Vitest plugin maps `@skip`/`@only` onto `test.skip`/`test.only`.
+   */
+  tags: string[];
+  /**
+   * Present only for rows expanded from a `Scenario Outline`. Carries the base
+   * outline name so the plugin can group its rows under one `describe`, with
+   * each row a separate `test` labelled by its example values.
+   */
+  outline?: {
+    name: string;
+  };
+}
+interface ParsedStep {
+  keyword: "Given" | "When" | "Then" | "And" | "But";
+  effectiveKeyword: "Given" | "When" | "Then";
+  text: string;
+  line: number;
+  column: number;
+}
+interface MatchedStep extends ParsedStep {
+  definitions: StepDefinitionMeta[];
+}
+interface Diagnostic {
+  file: string;
+  range: {
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+  };
+  severity: "error" | "warning" | "info";
+  message: string;
+  rule: string;
+  source: "step-forge";
+}
+interface AnalysisRule {
+  name: string;
+  check(scenario: ParsedScenario, matchedSteps: MatchedStep[]): Diagnostic[];
+}
+interface AnalyzerConfig {
+  stepFiles: string[];
+  featureFiles: string[];
+  tsConfigPath?: string;
+}
+//#endregion
+//#region src/runtime/hooks.d.ts
+/**
+ * Hooks are side-effect callbacks that run around scenarios, feature files, or
+ * the whole run. Unlike steps they never seed state: state is owned end to end
+ * by the typed dependency graph (given/when/then), and hooks exist for setup and
+ * teardown (opening a DB, starting a server, resetting mocks). A scenario hook
+ * may *read* the world, but its return value is ignored.
+ */
+type HookScope = "scenario" | "feature" | "global";
+type HookTiming = "before" | "after";
+/** Lightweight scenario identity handed to per-scenario hooks. */
+interface ScenarioInfo {
+  name: string;
+  file: string;
+}
+/** A per-scenario hook: gets the scenario's world (read-only in spirit). */
+type ScenarioHookFn = (context: {
+  world: MergeableWorld<any, any, any>;
+  scenario: ScenarioInfo;
+}) => void | Promise<void>;
+/** A per-feature-file or global hook: no world exists at these boundaries. */
+type PlainHookFn = () => void | Promise<void>;
+interface RegisteredHook {
+  scope: HookScope;
+  timing: HookTiming;
+  fn: ScenarioHookFn | PlainHookFn;
+}
+/**
+ * Collection of registered hooks. Like {@link StepRegistry}, a plain instance
+ * (not a hidden global) so tests can isolate; `globalHookRegistry` is the
+ * default sink the public `beforeScenario`/`afterAll`/etc helpers write to.
+ */
+declare class HookRegistry {
+  private hooks;
+  add(hook: RegisteredHook): void;
+  /**
+   * Hooks for a scope+timing. `before` hooks run in registration order;
+   * `after` hooks run in reverse (LIFO), so teardown unwinds setup.
+   */
+  for(scope: HookScope, timing: HookTiming): RegisteredHook[];
+  clear(): void;
+}
+declare const globalHookRegistry: HookRegistry;
+/**
+ * Run every registered feature/global hook of a scope+timing in order. Used by
+ * the generated test modules (feature hooks). Throws if a hook throws, so the
+ * runner reports it against the enclosing boundary.
+ */
+declare function runHooks(scope: "feature" | "global", timing: HookTiming, registry?: HookRegistry): Promise<void>;
+/**
+ * Run global before-hooks once per worker, ahead of that worker's first
+ * scenario, and schedule global after-hooks for worker exit. Idempotent: every
+ * feature module calls this in a `beforeAll`, but only the first call in a given
+ * worker does anything.
+ *
+ * Semantics & caveats (the once-per-worker model):
+ * - Runs in the *same* realm as steps, so global setup may touch in-process
+ *   state that steps later read.
+ * - "Once per worker", not strictly once per run — with multiple workers it runs
+ *   in each. Size global setup to be worker-safe (e.g. a server per worker).
+ * - Teardown is best-effort: after-hooks start on the worker's `beforeExit` and
+ *   are not awaited by the runner, so keep them fast/synchronous.
+ */
+declare function ensureGlobalHooks(registry?: HookRegistry): Promise<void>;
+//#endregion
+export { numberParser as C, intParser as S, StepDefinitionMeta as _, RegisteredHook as a, Parser as b, ensureGlobalHooks as c, AnalysisRule as d, AnalyzerConfig as f, ParsedStep as g, ParsedScenario as h, PlainHookFn as i, globalHookRegistry as l, MatchedStep as m, HookScope as n, ScenarioHookFn as o, Diagnostic as p, HookTiming as r, ScenarioInfo as s, HookRegistry as t, runHooks as u, BasicWorld as v, stringParser as w, booleanParser as x, MergeableWorld as y };
+//# sourceMappingURL=hooks-Dar49TtT.d.cts.map

package/dist/hooks-Dar49TtT.d.ts

@@ -0,0 +1,189 @@
+//#region src/parsers.d.ts
+/**
+ * A Parser is a typed cucumber-expression *parameter type*: it declares how a
+ * value is recognised in a Gherkin step (`regexp`) and how the matched text is
+ * turned into a TypeScript value (`parse`). The step expression uses `{name}`
+ * as the placeholder.
+ *
+ * The engine folds each parser straight into the cucumber-expression matcher —
+ * `parse` is the parameter type's transform, so coercion happens exactly once,
+ * during matching (no second pass). This is also what lets a parser introduce a
+ * brand-new placeholder like `{color}`: it is registered as a real parameter
+ * type, so text that doesn't match `regexp` simply doesn't match the step.
+ *
+ * The four built-ins below reuse cucumber-expressions' own built-in parameter
+ * types (`{int}`, `{float}`, `{string}`) — those names are already registered,
+ * so the library performs the match + coercion and each parser's `regexp`/
+ * `parse` serve to document intent and to drive TypeScript inference of the
+ * variable type. `booleanParser` has no built-in equivalent, so it is a genuine
+ * custom parameter type whose `parse` runs at match time.
+ */
+type Parser<T> = {
+  /** Parameter-type name; the step expression uses `{name}` as the placeholder. */name: string; /** How cucumber-expressions recognises the value in the step text. */
+  regexp: RegExp | RegExp[]; /** Transform the matched text into the typed value. */
+  parse: (value: string) => T;
+};
+/** Matches a quoted string (`{string}`) and strips the surrounding quotes. */
+declare const stringParser: Parser<string>;
+/** Matches an unquoted integer (`{int}`). */
+declare const intParser: Parser<number>;
+/** Matches an unquoted floating point number (`{float}`). */
+declare const numberParser: Parser<number>;
+/**
+ * Matches an unquoted `true`/`false` word (`{boolean}`) and parses it to a
+ * boolean. Unlike the others this is a genuine custom parameter type — cucumber
+ * has no built-in `boolean` — so its `regexp`/`parse` are what the matcher uses.
+ */
+declare const booleanParser: Parser<boolean>;
+//#endregion
+//#region src/world.d.ts
+type WorldState<State> = { readonly [K in keyof State]?: State[K] };
+type MergeableWorldState<T> = WorldState<T> & {
+  merge: (newState: Partial<T>) => void;
+};
+type MergeableWorld<Given, When, Then> = {
+  given: MergeableWorldState<Given>;
+  when: MergeableWorldState<When>;
+  then: MergeableWorldState<Then>;
+};
+declare class BasicWorld<Given, When, Then> {
+  private givenState;
+  private whenState;
+  private thenState;
+  get given(): MergeableWorldState<Given>;
+  get when(): MergeableWorldState<When>;
+  get then(): MergeableWorldState<Then>;
+}
+//#endregion
+//#region src/analyzer/types.d.ts
+interface StepDefinitionMeta {
+  stepType: "given" | "when" | "then";
+  expression: string;
+  dependencies: {
+    given: Record<string, "required" | "optional">;
+    when: Record<string, "required" | "optional">;
+    then: Record<string, "required" | "optional">;
+  };
+  produces: string[];
+  sourceFile: string;
+  line: number;
+}
+interface ParsedScenario {
+  name: string;
+  file: string;
+  steps: ParsedStep[];
+  /**
+   * Gherkin tags in effect for this scenario, each including the leading `@`
+   * (feature + scenario tags, plus the Examples-block tags for outline rows).
+   * The Vitest plugin maps `@skip`/`@only` onto `test.skip`/`test.only`.
+   */
+  tags: string[];
+  /**
+   * Present only for rows expanded from a `Scenario Outline`. Carries the base
+   * outline name so the plugin can group its rows under one `describe`, with
+   * each row a separate `test` labelled by its example values.
+   */
+  outline?: {
+    name: string;
+  };
+}
+interface ParsedStep {
+  keyword: "Given" | "When" | "Then" | "And" | "But";
+  effectiveKeyword: "Given" | "When" | "Then";
+  text: string;
+  line: number;
+  column: number;
+}
+interface MatchedStep extends ParsedStep {
+  definitions: StepDefinitionMeta[];
+}
+interface Diagnostic {
+  file: string;
+  range: {
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+  };
+  severity: "error" | "warning" | "info";
+  message: string;
+  rule: string;
+  source: "step-forge";
+}
+interface AnalysisRule {
+  name: string;
+  check(scenario: ParsedScenario, matchedSteps: MatchedStep[]): Diagnostic[];
+}
+interface AnalyzerConfig {
+  stepFiles: string[];
+  featureFiles: string[];
+  tsConfigPath?: string;
+}
+//#endregion
+//#region src/runtime/hooks.d.ts
+/**
+ * Hooks are side-effect callbacks that run around scenarios, feature files, or
+ * the whole run. Unlike steps they never seed state: state is owned end to end
+ * by the typed dependency graph (given/when/then), and hooks exist for setup and
+ * teardown (opening a DB, starting a server, resetting mocks). A scenario hook
+ * may *read* the world, but its return value is ignored.
+ */
+type HookScope = "scenario" | "feature" | "global";
+type HookTiming = "before" | "after";
+/** Lightweight scenario identity handed to per-scenario hooks. */
+interface ScenarioInfo {
+  name: string;
+  file: string;
+}
+/** A per-scenario hook: gets the scenario's world (read-only in spirit). */
+type ScenarioHookFn = (context: {
+  world: MergeableWorld<any, any, any>;
+  scenario: ScenarioInfo;
+}) => void | Promise<void>;
+/** A per-feature-file or global hook: no world exists at these boundaries. */
+type PlainHookFn = () => void | Promise<void>;
+interface RegisteredHook {
+  scope: HookScope;
+  timing: HookTiming;
+  fn: ScenarioHookFn | PlainHookFn;
+}
+/**
+ * Collection of registered hooks. Like {@link StepRegistry}, a plain instance
+ * (not a hidden global) so tests can isolate; `globalHookRegistry` is the
+ * default sink the public `beforeScenario`/`afterAll`/etc helpers write to.
+ */
+declare class HookRegistry {
+  private hooks;
+  add(hook: RegisteredHook): void;
+  /**
+   * Hooks for a scope+timing. `before` hooks run in registration order;
+   * `after` hooks run in reverse (LIFO), so teardown unwinds setup.
+   */
+  for(scope: HookScope, timing: HookTiming): RegisteredHook[];
+  clear(): void;
+}
+declare const globalHookRegistry: HookRegistry;
+/**
+ * Run every registered feature/global hook of a scope+timing in order. Used by
+ * the generated test modules (feature hooks). Throws if a hook throws, so the
+ * runner reports it against the enclosing boundary.
+ */
+declare function runHooks(scope: "feature" | "global", timing: HookTiming, registry?: HookRegistry): Promise<void>;
+/**
+ * Run global before-hooks once per worker, ahead of that worker's first
+ * scenario, and schedule global after-hooks for worker exit. Idempotent: every
+ * feature module calls this in a `beforeAll`, but only the first call in a given
+ * worker does anything.
+ *
+ * Semantics & caveats (the once-per-worker model):
+ * - Runs in the *same* realm as steps, so global setup may touch in-process
+ *   state that steps later read.
+ * - "Once per worker", not strictly once per run — with multiple workers it runs
+ *   in each. Size global setup to be worker-safe (e.g. a server per worker).
+ * - Teardown is best-effort: after-hooks start on the worker's `beforeExit` and
+ *   are not awaited by the runner, so keep them fast/synchronous.
+ */
+declare function ensureGlobalHooks(registry?: HookRegistry): Promise<void>;
+//#endregion
+export { numberParser as C, intParser as S, StepDefinitionMeta as _, RegisteredHook as a, Parser as b, ensureGlobalHooks as c, AnalysisRule as d, AnalyzerConfig as f, ParsedStep as g, ParsedScenario as h, PlainHookFn as i, globalHookRegistry as l, MatchedStep as m, HookScope as n, ScenarioHookFn as o, Diagnostic as p, HookTiming as r, ScenarioInfo as s, HookRegistry as t, runHooks as u, BasicWorld as v, stringParser as w, booleanParser as x, MergeableWorld as y };
+//# sourceMappingURL=hooks-Dar49TtT.d.ts.map

package/dist/runtime.cjs

@@ -0,0 +1,13 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_hooks = require("./hooks-CGYzwDOv.cjs");
+const require_engine = require("./engine-DWAIlwWp.cjs");
+exports.AmbiguousStepError = require_engine.AmbiguousStepError;
+exports.HookRegistry = require_hooks.HookRegistry;
+exports.StepRegistry = require_hooks.StepRegistry;
+exports.UndefinedStepError = require_engine.UndefinedStepError;
+exports.compileRegistry = require_engine.compileRegistry;
+exports.ensureGlobalHooks = require_hooks.ensureGlobalHooks;
+exports.globalHookRegistry = require_hooks.globalHookRegistry;
+exports.globalRegistry = require_hooks.globalRegistry;
+exports.runHooks = require_hooks.runHooks;
+exports.runScenario = require_engine.runScenario;

package/dist/runtime.d.cts

@@ -0,0 +1,142 @@
+import { a as RegisteredHook, b as Parser, c as ensureGlobalHooks, g as ParsedStep, h as ParsedScenario, i as PlainHookFn, l as globalHookRegistry, n as HookScope, o as ScenarioHookFn, r as HookTiming, s as ScenarioInfo, t as HookRegistry, u as runHooks, y as MergeableWorld } from "./hooks-Dar49TtT.cjs";
+import { CucumberExpression } from "@cucumber/cucumber-expressions";
+
+//#region src/runtime/registry.d.ts
+type StepType = "given" | "when" | "then";
+/**
+ * A step definition as it exists at *runtime*, independent of any test runner.
+ *
+ * `execute` is the fully-wired step body: given a world and the raw values
+ * captured from a Gherkin step, it applies parsers, validates + narrows
+ * dependencies, runs the user's step function, and merges the result back into
+ * the world. The engine never needs to know how any of that works — it just
+ * matches text to a step and calls `execute`.
+ */
+interface RegisteredStep {
+  stepType: StepType;
+  /** The Cucumber-expression source, e.g. `a user named {string}`. */
+  expression: string;
+  /** Parsers, one per captured variable, applied after expression capture. */
+  parsers: Parser<any>[];
+  execute: (world: MergeableWorld<any, any, any>, capturedArgs: unknown[]) => Promise<void>;
+  /** Where the step was defined, for ambiguous-match diagnostics. */
+  source?: string;
+}
+/**
+ * A collection of registered steps. Deliberately a plain instance (not a hidden
+ * module global) so tests and the Vitest plugin can create isolated registries.
+ * `globalRegistry` is the default sink that `.step()` writes to.
+ */
+declare class StepRegistry {
+  private steps;
+  add(step: RegisteredStep): void;
+  all(): readonly RegisteredStep[];
+  clear(): void;
+}
+declare const globalRegistry: StepRegistry;
+//#endregion
+//#region src/runtime/engine.d.ts
+/** A registered step paired with its compiled Cucumber expression. */
+interface CompiledStep {
+  step: RegisteredStep;
+  expression: CucumberExpression;
+}
+declare class UndefinedStepError extends Error {
+  readonly step: ParsedStep;
+  constructor(step: ParsedStep);
+}
+declare class AmbiguousStepError extends Error {
+  readonly step: ParsedStep;
+  readonly matches: RegisteredStep[];
+  constructor(step: ParsedStep, matches: RegisteredStep[]);
+}
+/**
+ * Compile a registry's steps into matchable Cucumber expressions **once** per
+ * run. The result is reused for every scenario — compilation is pure and depends
+ * only on the registry, so recompiling per scenario (as an earlier version did)
+ * was wasted work proportional to scenarios × steps.
+ */
+declare function compileRegistry(registry: StepRegistry): CompiledStep[];
+interface StepResult {
+  step: ParsedStep;
+  status: "passed" | "failed" | "skipped";
+  error?: Error;
+  durationMs?: number;
+}
+interface ScenarioResult {
+  scenario: ParsedScenario;
+  status: "passed" | "failed";
+  steps: StepResult[];
+  /**
+   * The scenario's first error, if it failed. Usually the same object as the
+   * failing step's `error` (with a synthetic `.feature` stack frame attached),
+   * but for a hook failure there's no step to point at, so this is the only
+   * place it surfaces. Reporters read this; the runner never throws it.
+   */
+  error?: Error;
+  /** Wall-clock duration of the whole scenario, in milliseconds. */
+  durationMs?: number;
+}
+/**
+ * Run one scenario against a pre-compiled step table. A fresh world is created
+ * per scenario (state never leaks between scenarios). On the first failing step
+ * the remaining steps are marked skipped, matching Cucumber's execution
+ * semantics.
+ *
+ * Never throws for step or hook failures: it always resolves to a
+ * `ScenarioResult` carrying the per-step breakdown and (on failure) the first
+ * `error` with a synthetic `.feature` stack frame attached. Callers decide what
+ * to do with a failure — the CLI runner reports it, a test-runner adapter can
+ * re-throw `result.error`. It still rejects for truly exceptional conditions
+ * (e.g. a bug in the engine itself), never for a normal test failure.
+ *
+ * Pass the compiled table from {@link compileRegistry} once and reuse it across
+ * every scenario in the run.
+ */
+declare function runScenario(scenario: ParsedScenario, compiled: CompiledStep[], makeWorld: () => MergeableWorld<any, any, any>, hooks?: HookRegistry): Promise<ScenarioResult>;
+//#endregion
+//#region src/runtime/config.d.ts
+/**
+ * User-facing runner configuration. The same shape is accepted from a
+ * `step-forge.config.ts` file (default export) and from CLI flags, with flags
+ * taking precedence. Everything is optional; {@link resolveConfig} fills in
+ * defaults.
+ */
+interface RunnerOptions {
+  /** Feature-file glob(s), relative to `cwd`. Defaults to every `.feature` file. */
+  features?: string | string[];
+  /** Step-module glob(s), relative to `cwd`. Defaults to every `.steps.ts` file. */
+  steps?: string | string[];
+  /**
+   * Module that default-exports a world factory `() => world`, relative to
+   * `cwd`. When omitted each scenario gets a fresh `BasicWorld`.
+   */
+  world?: string;
+  /**
+   * Max scenarios in flight at once. Defaults to `1` (serial), matching
+   * Cucumber's default execution model — scenarios often share module-level
+   * state via hooks, which only holds under serial execution. Raise it to opt
+   * into parallelism for isolated, I/O-bound suites.
+   */
+  concurrency?: number;
+  /** Reporter name. Default `pretty`. */
+  reporter?: "pretty" | "progress";
+  /** Only run scenarios whose name matches this (string → substring/regex). */
+  name?: string;
+  /** Cucumber tag expression, e.g. `@smoke and not @wip`. */
+  tags?: string;
+}
+/** Fully-resolved config: no optionals, globs kept as arrays, paths absolute. */
+interface ResolvedConfig {
+  cwd: string;
+  features: string[];
+  steps: string[];
+  world?: string;
+  concurrency: number;
+  reporter: "pretty" | "progress";
+  name?: string;
+  tags?: string;
+}
+//#endregion
+export { AmbiguousStepError, type CompiledStep, HookRegistry, type HookScope, type HookTiming, type PlainHookFn, type RegisteredHook, type RegisteredStep, type ResolvedConfig, type RunnerOptions, type ScenarioHookFn, type ScenarioInfo, type ScenarioResult, StepRegistry, type StepResult, type StepType, UndefinedStepError, compileRegistry, ensureGlobalHooks, globalHookRegistry, globalRegistry, runHooks, runScenario };
+//# sourceMappingURL=runtime.d.cts.map

package/dist/runtime.d.ts

@@ -0,0 +1,142 @@
+import { a as RegisteredHook, b as Parser, c as ensureGlobalHooks, g as ParsedStep, h as ParsedScenario, i as PlainHookFn, l as globalHookRegistry, n as HookScope, o as ScenarioHookFn, r as HookTiming, s as ScenarioInfo, t as HookRegistry, u as runHooks, y as MergeableWorld } from "./hooks-Dar49TtT.js";
+import { CucumberExpression } from "@cucumber/cucumber-expressions";
+
+//#region src/runtime/registry.d.ts
+type StepType = "given" | "when" | "then";
+/**
+ * A step definition as it exists at *runtime*, independent of any test runner.
+ *
+ * `execute` is the fully-wired step body: given a world and the raw values
+ * captured from a Gherkin step, it applies parsers, validates + narrows
+ * dependencies, runs the user's step function, and merges the result back into
+ * the world. The engine never needs to know how any of that works — it just
+ * matches text to a step and calls `execute`.
+ */
+interface RegisteredStep {
+  stepType: StepType;
+  /** The Cucumber-expression source, e.g. `a user named {string}`. */
+  expression: string;
+  /** Parsers, one per captured variable, applied after expression capture. */
+  parsers: Parser<any>[];
+  execute: (world: MergeableWorld<any, any, any>, capturedArgs: unknown[]) => Promise<void>;
+  /** Where the step was defined, for ambiguous-match diagnostics. */
+  source?: string;
+}
+/**
+ * A collection of registered steps. Deliberately a plain instance (not a hidden
+ * module global) so tests and the Vitest plugin can create isolated registries.
+ * `globalRegistry` is the default sink that `.step()` writes to.
+ */
+declare class StepRegistry {
+  private steps;
+  add(step: RegisteredStep): void;
+  all(): readonly RegisteredStep[];
+  clear(): void;
+}
+declare const globalRegistry: StepRegistry;
+//#endregion
+//#region src/runtime/engine.d.ts
+/** A registered step paired with its compiled Cucumber expression. */
+interface CompiledStep {
+  step: RegisteredStep;
+  expression: CucumberExpression;
+}
+declare class UndefinedStepError extends Error {
+  readonly step: ParsedStep;
+  constructor(step: ParsedStep);
+}
+declare class AmbiguousStepError extends Error {
+  readonly step: ParsedStep;
+  readonly matches: RegisteredStep[];
+  constructor(step: ParsedStep, matches: RegisteredStep[]);
+}
+/**
+ * Compile a registry's steps into matchable Cucumber expressions **once** per
+ * run. The result is reused for every scenario — compilation is pure and depends
+ * only on the registry, so recompiling per scenario (as an earlier version did)
+ * was wasted work proportional to scenarios × steps.
+ */
+declare function compileRegistry(registry: StepRegistry): CompiledStep[];
+interface StepResult {
+  step: ParsedStep;
+  status: "passed" | "failed" | "skipped";
+  error?: Error;
+  durationMs?: number;
+}
+interface ScenarioResult {
+  scenario: ParsedScenario;
+  status: "passed" | "failed";
+  steps: StepResult[];
+  /**
+   * The scenario's first error, if it failed. Usually the same object as the
+   * failing step's `error` (with a synthetic `.feature` stack frame attached),
+   * but for a hook failure there's no step to point at, so this is the only
+   * place it surfaces. Reporters read this; the runner never throws it.
+   */
+  error?: Error;
+  /** Wall-clock duration of the whole scenario, in milliseconds. */
+  durationMs?: number;
+}
+/**
+ * Run one scenario against a pre-compiled step table. A fresh world is created
+ * per scenario (state never leaks between scenarios). On the first failing step
+ * the remaining steps are marked skipped, matching Cucumber's execution
+ * semantics.
+ *
+ * Never throws for step or hook failures: it always resolves to a
+ * `ScenarioResult` carrying the per-step breakdown and (on failure) the first
+ * `error` with a synthetic `.feature` stack frame attached. Callers decide what
+ * to do with a failure — the CLI runner reports it, a test-runner adapter can
+ * re-throw `result.error`. It still rejects for truly exceptional conditions
+ * (e.g. a bug in the engine itself), never for a normal test failure.
+ *
+ * Pass the compiled table from {@link compileRegistry} once and reuse it across
+ * every scenario in the run.
+ */
+declare function runScenario(scenario: ParsedScenario, compiled: CompiledStep[], makeWorld: () => MergeableWorld<any, any, any>, hooks?: HookRegistry): Promise<ScenarioResult>;
+//#endregion
+//#region src/runtime/config.d.ts
+/**
+ * User-facing runner configuration. The same shape is accepted from a
+ * `step-forge.config.ts` file (default export) and from CLI flags, with flags
+ * taking precedence. Everything is optional; {@link resolveConfig} fills in
+ * defaults.
+ */
+interface RunnerOptions {
+  /** Feature-file glob(s), relative to `cwd`. Defaults to every `.feature` file. */
+  features?: string | string[];
+  /** Step-module glob(s), relative to `cwd`. Defaults to every `.steps.ts` file. */
+  steps?: string | string[];
+  /**
+   * Module that default-exports a world factory `() => world`, relative to
+   * `cwd`. When omitted each scenario gets a fresh `BasicWorld`.
+   */
+  world?: string;
+  /**
+   * Max scenarios in flight at once. Defaults to `1` (serial), matching
+   * Cucumber's default execution model — scenarios often share module-level
+   * state via hooks, which only holds under serial execution. Raise it to opt
+   * into parallelism for isolated, I/O-bound suites.
+   */
+  concurrency?: number;
+  /** Reporter name. Default `pretty`. */
+  reporter?: "pretty" | "progress";
+  /** Only run scenarios whose name matches this (string → substring/regex). */
+  name?: string;
+  /** Cucumber tag expression, e.g. `@smoke and not @wip`. */
+  tags?: string;
+}
+/** Fully-resolved config: no optionals, globs kept as arrays, paths absolute. */
+interface ResolvedConfig {
+  cwd: string;
+  features: string[];
+  steps: string[];
+  world?: string;
+  concurrency: number;
+  reporter: "pretty" | "progress";
+  name?: string;
+  tags?: string;
+}
+//#endregion
+export { AmbiguousStepError, type CompiledStep, HookRegistry, type HookScope, type HookTiming, type PlainHookFn, type RegisteredHook, type RegisteredStep, type ResolvedConfig, type RunnerOptions, type ScenarioHookFn, type ScenarioInfo, type ScenarioResult, StepRegistry, type StepResult, type StepType, UndefinedStepError, compileRegistry, ensureGlobalHooks, globalHookRegistry, globalRegistry, runHooks, runScenario };
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.js

@@ -0,0 +1,3 @@
+import { a as StepRegistry, i as runHooks, n as ensureGlobalHooks, o as globalRegistry, r as globalHookRegistry, t as HookRegistry } from "./hooks-CywugMQQ.js";
+import { i as runScenario, n as UndefinedStepError, r as compileRegistry, t as AmbiguousStepError } from "./engine-DPRxs6eC.js";
+export { AmbiguousStepError, HookRegistry, StepRegistry, UndefinedStepError, compileRegistry, ensureGlobalHooks, globalHookRegistry, globalRegistry, runHooks, runScenario };