@step-forge/step-forge 0.0.19 → 0.0.20

package/dist/hooks-CywugMQQ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-CywugMQQ.js","names":[],"sources":["../../src/runtime/registry.ts","../../src/runtime/hooks.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { Parser } from \"../parsers\";\nimport { MergeableWorld } from \"../world\";\n\nexport type StepType = \"given\" | \"when\" | \"then\";\n\n/**\n * A step definition as it exists at *runtime*, independent of any test runner.\n *\n * `execute` is the fully-wired step body: given a world and the raw values\n * captured from a Gherkin step, it applies parsers, validates + narrows\n * dependencies, runs the user's step function, and merges the result back into\n * the world. The engine never needs to know how any of that works — it just\n * matches text to a step and calls `execute`.\n */\nexport interface RegisteredStep {\n  stepType: StepType;\n  /** The Cucumber-expression source, e.g. `a user named {string}`. */\n  expression: string;\n  /** Parsers, one per captured variable, applied after expression capture. */\n  parsers: Parser<any>[];\n  execute: (\n    world: MergeableWorld<any, any, any>,\n    capturedArgs: unknown[]\n  ) => Promise<void>;\n  /** Where the step was defined, for ambiguous-match diagnostics. */\n  source?: string;\n}\n\n/**\n * A collection of registered steps. Deliberately a plain instance (not a hidden\n * module global) so tests and the Vitest plugin can create isolated registries.\n * `globalRegistry` is the default sink that `.step()` writes to.\n */\nexport class StepRegistry {\n  private steps: RegisteredStep[] = [];\n\n  add(step: RegisteredStep): void {\n    this.steps.push(step);\n  }\n\n  all(): readonly RegisteredStep[] {\n    return this.steps;\n  }\n\n  clear(): void {\n    this.steps = [];\n  }\n}\n\nexport const globalRegistry = new StepRegistry();\n","/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { MergeableWorld } from \"../world\";\n\n/**\n * Hooks are side-effect callbacks that run around scenarios, feature files, or\n * the whole run. Unlike steps they never seed state: state is owned end to end\n * by the typed dependency graph (given/when/then), and hooks exist for setup and\n * teardown (opening a DB, starting a server, resetting mocks). A scenario hook\n * may *read* the world, but its return value is ignored.\n */\nexport type HookScope = \"scenario\" | \"feature\" | \"global\";\nexport type HookTiming = \"before\" | \"after\";\n\n/** Lightweight scenario identity handed to per-scenario hooks. */\nexport interface ScenarioInfo {\n  name: string;\n  file: string;\n}\n\n/** A per-scenario hook: gets the scenario's world (read-only in spirit). */\nexport type ScenarioHookFn = (context: {\n  world: MergeableWorld<any, any, any>;\n  scenario: ScenarioInfo;\n}) => void | Promise<void>;\n\n/** A per-feature-file or global hook: no world exists at these boundaries. */\nexport type PlainHookFn = () => void | Promise<void>;\n\nexport interface RegisteredHook {\n  scope: HookScope;\n  timing: HookTiming;\n  fn: ScenarioHookFn | PlainHookFn;\n}\n\n/**\n * Collection of registered hooks. Like {@link StepRegistry}, a plain instance\n * (not a hidden global) so tests can isolate; `globalHookRegistry` is the\n * default sink the public `beforeScenario`/`afterAll`/etc helpers write to.\n */\nexport class HookRegistry {\n  private hooks: RegisteredHook[] = [];\n\n  add(hook: RegisteredHook): void {\n    this.hooks.push(hook);\n  }\n\n  /**\n   * Hooks for a scope+timing. `before` hooks run in registration order;\n   * `after` hooks run in reverse (LIFO), so teardown unwinds setup.\n   */\n  for(scope: HookScope, timing: HookTiming): RegisteredHook[] {\n    const matching = this.hooks.filter(\n      h => h.scope === scope && h.timing === timing\n    );\n    return timing === \"after\" ? matching.reverse() : matching;\n  }\n\n  clear(): void {\n    this.hooks = [];\n  }\n}\n\nexport const globalHookRegistry = new HookRegistry();\n\n/**\n * Run every registered feature/global hook of a scope+timing in order. Used by\n * the generated test modules (feature hooks). Throws if a hook throws, so the\n * runner reports it against the enclosing boundary.\n */\nexport async function runHooks(\n  scope: \"feature\" | \"global\",\n  timing: HookTiming,\n  registry: HookRegistry = globalHookRegistry\n): Promise<void> {\n  for (const hook of registry.for(scope, timing)) {\n    await (hook.fn as PlainHookFn)();\n  }\n}\n\n// Process-global (via Symbol.for so it survives module duplication) guard so\n// global hooks fire exactly once per worker, no matter how many feature modules\n// call in.\nconst GLOBAL_GUARD = Symbol.for(\"step-forge.globalHooksStarted\");\n\n/**\n * Run global before-hooks once per worker, ahead of that worker's first\n * scenario, and schedule global after-hooks for worker exit. Idempotent: every\n * feature module calls this in a `beforeAll`, but only the first call in a given\n * worker does anything.\n *\n * Semantics & caveats (the once-per-worker model):\n * - Runs in the *same* realm as steps, so global setup may touch in-process\n *   state that steps later read.\n * - \"Once per worker\", not strictly once per run — with multiple workers it runs\n *   in each. Size global setup to be worker-safe (e.g. a server per worker).\n * - Teardown is best-effort: after-hooks start on the worker's `beforeExit` and\n *   are not awaited by the runner, so keep them fast/synchronous.\n */\nexport async function ensureGlobalHooks(\n  registry: HookRegistry = globalHookRegistry\n): Promise<void> {\n  const store = globalThis as Record<symbol, boolean>;\n  if (store[GLOBAL_GUARD]) return;\n  store[GLOBAL_GUARD] = true;\n\n  for (const hook of registry.for(\"global\", \"before\")) {\n    await (hook.fn as PlainHookFn)();\n  }\n\n  process.once(\"beforeExit\", () => {\n    void (async () => {\n      for (const hook of registry.for(\"global\", \"after\")) {\n        await (hook.fn as PlainHookFn)();\n      }\n    })();\n  });\n}\n"],"mappings":";;;;;;AAkCA,IAAa,eAAb,MAA0B;CACxB,QAAkC,CAAC;CAEnC,IAAI,MAA4B;EAC9B,KAAK,MAAM,KAAK,IAAI;CACtB;CAEA,MAAiC;EAC/B,OAAO,KAAK;CACd;CAEA,QAAc;EACZ,KAAK,QAAQ,CAAC;CAChB;AACF;AAEA,MAAa,iBAAiB,IAAI,aAAa;;;;;;;;ACX/C,IAAa,eAAb,MAA0B;CACxB,QAAkC,CAAC;CAEnC,IAAI,MAA4B;EAC9B,KAAK,MAAM,KAAK,IAAI;CACtB;;;;;CAMA,IAAI,OAAkB,QAAsC;EAC1D,MAAM,WAAW,KAAK,MAAM,QAC1B,MAAK,EAAE,UAAU,SAAS,EAAE,WAAW,MACzC;EACA,OAAO,WAAW,UAAU,SAAS,QAAQ,IAAI;CACnD;CAEA,QAAc;EACZ,KAAK,QAAQ,CAAC;CAChB;AACF;AAEA,MAAa,qBAAqB,IAAI,aAAa;;;;;;AAOnD,eAAsB,SACpB,OACA,QACA,WAAyB,oBACV;CACf,KAAK,MAAM,QAAQ,SAAS,IAAI,OAAO,MAAM,GAC3C,MAAO,KAAK,GAAmB;AAEnC;AAKA,MAAM,eAAe,OAAO,IAAI,+BAA+B;;;;;;;;;;;;;;;AAgB/D,eAAsB,kBACpB,WAAyB,oBACV;CACf,MAAM,QAAQ;CACd,IAAI,MAAM,eAAe;CACzB,MAAM,gBAAgB;CAEtB,KAAK,MAAM,QAAQ,SAAS,IAAI,UAAU,QAAQ,GAChD,MAAO,KAAK,GAAmB;CAGjC,QAAQ,KAAK,oBAAoB;EAC/B,CAAM,YAAY;GAChB,KAAK,MAAM,QAAQ,SAAS,IAAI,UAAU,OAAO,GAC/C,MAAO,KAAK,GAAmB;EAEnC,EAAA,CAAG;CACL,CAAC;AACH"}

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,168 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_hooks = require("./hooks-CGYzwDOv.cjs");
+let _cucumber_cucumber_expressions = require("@cucumber/cucumber-expressions");
+//#region src/runtime/engine.ts
+const keywordToStepType = {
+	Given: "given",
+	When: "when",
+	Then: "then"
+};
+var UndefinedStepError = class extends Error {
+	step;
+	constructor(step) {
+		super(`Undefined step: ${step.effectiveKeyword} ${step.text}`);
+		this.step = step;
+		this.name = "UndefinedStepError";
+	}
+};
+var AmbiguousStepError = class extends Error {
+	step;
+	matches;
+	constructor(step, matches) {
+		super(`Ambiguous step: "${step.text}" matched ${matches.length} definitions:\n` + matches.map((m) => `  - ${m.expression}`).join("\n"));
+		this.step = step;
+		this.matches = matches;
+		this.name = "AmbiguousStepError";
+	}
+};
+function compile(registry) {
+	return registry.all().map((step) => {
+		const paramRegistry = new _cucumber_cucumber_expressions.ParameterTypeRegistry();
+		for (const parser of step.parsers) {
+			if (paramRegistry.lookupByTypeName(parser.name)) continue;
+			const regexps = Array.isArray(parser.regexp) ? parser.regexp : [parser.regexp];
+			paramRegistry.defineParameterType(new _cucumber_cucumber_expressions.ParameterType(parser.name, regexps, null, (value) => parser.parse(value)));
+		}
+		return {
+			step,
+			expression: new _cucumber_cucumber_expressions.CucumberExpression(step.expression, paramRegistry)
+		};
+	});
+}
+/**
+* Find the single step definition matching a Gherkin step. Matching is
+* opinionated and strict: the keyword must line up with the step type, exactly
+* one definition must match, and undefined/ambiguous both throw rather than
+* silently skipping (unlike Cucumber's pending/undefined dance).
+*/
+function matchStep(step, compiled) {
+	const expectedType = keywordToStepType[step.effectiveKeyword];
+	const matches = [];
+	for (const { step: def, expression } of compiled) {
+		if (def.stepType !== expectedType) continue;
+		const result = expression.match(step.text);
+		if (result) matches.push({
+			step: def,
+			args: result.map((a) => a.getValue(null))
+		});
+	}
+	if (matches.length === 0) throw new UndefinedStepError(step);
+	if (matches.length > 1) throw new AmbiguousStepError(step, matches.map((m) => m.step));
+	return matches[0];
+}
+/**
+* Run one scenario against a registry. 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.
+*
+* Throws on failure so it maps cleanly onto a test runner's `test()` body, but
+* the returned/attached `ScenarioResult` carries the per-step breakdown.
+*/
+async function runScenario(scenario, registry, makeWorld, hooks = require_hooks.globalHookRegistry) {
+	const compiled = compile(registry);
+	const world = makeWorld();
+	const scenarioInfo = {
+		name: scenario.name,
+		file: scenario.file
+	};
+	const steps = [];
+	let failed = false;
+	let firstError;
+	const fail = (err) => {
+		if (failed) return;
+		failed = true;
+		firstError = err instanceof Error ? err : new Error(String(err));
+	};
+	try {
+		for (const hook of hooks.for("scenario", "before")) await hook.fn({
+			world,
+			scenario: scenarioInfo
+		});
+	} catch (err) {
+		fail(err);
+	}
+	for (const step of scenario.steps) {
+		if (failed) {
+			steps.push({
+				step,
+				status: "skipped"
+			});
+			continue;
+		}
+		try {
+			const { step: def, args } = matchStep(step, compiled);
+			await def.execute(world, args);
+			steps.push({
+				step,
+				status: "passed"
+			});
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			steps.push({
+				step,
+				status: "failed",
+				error
+			});
+			fail(error);
+		}
+	}
+	for (const hook of hooks.for("scenario", "after")) try {
+		await hook.fn({
+			world,
+			scenario: scenarioInfo
+		});
+	} catch (err) {
+		fail(err);
+	}
+	const result = {
+		scenario,
+		status: failed ? "failed" : "passed",
+		steps
+	};
+	if (failed && firstError) {
+		const failing = steps.find((s) => s.status === "failed");
+		if (failing) attachFeatureFrame(firstError, scenario.file, failing.step);
+		throw firstError;
+	}
+	return result;
+}
+/**
+* Prepend a synthetic stack frame pointing at the failing Gherkin step. Because
+* the frame's file is the real `.feature` on disk, the test runner treats it as
+* a source location and shows a code frame at the step — instead of us jamming
+* `file:line` into the error message. The frame goes *above* the real stack, so
+* the step-definition frames (the actual throw site) are preserved below it.
+*/
+function attachFeatureFrame(error, file, step) {
+	const frame = `    at ${`${step.effectiveKeyword} ${step.text}`} (${file}:${step.line}:${step.column})`;
+	const stack = error.stack;
+	if (!stack) {
+		error.stack = `${error.name}: ${error.message}\n${frame}`;
+		return;
+	}
+	const firstFrame = stack.indexOf("\n    at ");
+	if (firstFrame === -1) error.stack = `${stack}\n${frame}`;
+	else error.stack = stack.slice(0, firstFrame) + `\n${frame}` + stack.slice(firstFrame);
+}
+//#endregion
+exports.AmbiguousStepError = AmbiguousStepError;
+exports.HookRegistry = require_hooks.HookRegistry;
+exports.StepRegistry = require_hooks.StepRegistry;
+exports.UndefinedStepError = UndefinedStepError;
+exports.ensureGlobalHooks = require_hooks.ensureGlobalHooks;
+exports.globalHookRegistry = require_hooks.globalHookRegistry;
+exports.globalRegistry = require_hooks.globalRegistry;
+exports.runHooks = require_hooks.runHooks;
+exports.runScenario = runScenario;
+
+//# sourceMappingURL=runtime.cjs.map

package/dist/runtime.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.cjs","names":["ParameterTypeRegistry","ParameterType","CucumberExpression","globalHookRegistry"],"sources":["../../src/runtime/engine.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport {\n  CucumberExpression,\n  ParameterType,\n  ParameterTypeRegistry,\n} from \"@cucumber/cucumber-expressions\";\nimport { ParsedScenario, ParsedStep } from \"../analyzer/types\";\nimport { MergeableWorld } from \"../world\";\nimport { globalHookRegistry, HookRegistry, ScenarioHookFn } from \"./hooks\";\nimport { RegisteredStep, StepRegistry, StepType } from \"./registry\";\n\nconst keywordToStepType: Record<ParsedStep[\"effectiveKeyword\"], StepType> = {\n  Given: \"given\",\n  When: \"when\",\n  Then: \"then\",\n};\n\n/** A registered step paired with its compiled Cucumber expression. */\ninterface CompiledStep {\n  step: RegisteredStep;\n  expression: CucumberExpression;\n}\n\nexport class UndefinedStepError extends Error {\n  constructor(public readonly step: ParsedStep) {\n    super(`Undefined step: ${step.effectiveKeyword} ${step.text}`);\n    this.name = \"UndefinedStepError\";\n  }\n}\n\nexport class AmbiguousStepError extends Error {\n  constructor(\n    public readonly step: ParsedStep,\n    public readonly matches: RegisteredStep[]\n  ) {\n    super(\n      `Ambiguous step: \"${step.text}\" matched ${matches.length} definitions:\\n` +\n        matches.map(m => `  - ${m.expression}`).join(\"\\n\")\n    );\n    this.name = \"AmbiguousStepError\";\n  }\n}\n\nfunction compile(registry: StepRegistry): CompiledStep[] {\n  return registry.all().map(step => {\n    // Each step gets its own parameter-type registry (seeded with the\n    // built-ins). A parser whose name is already registered — the built-in\n    // `{int}`/`{float}`/`{string}`, or a repeat within the same step — reuses\n    // that type; a novel name (e.g. `{boolean}`, `{color}`) is registered from\n    // the parser's regexp + parse, so matching and coercion happen in one pass.\n    const paramRegistry = new ParameterTypeRegistry();\n    for (const parser of step.parsers) {\n      if (paramRegistry.lookupByTypeName(parser.name)) continue;\n      const regexps = Array.isArray(parser.regexp)\n        ? parser.regexp\n        : [parser.regexp];\n      paramRegistry.defineParameterType(\n        new ParameterType(parser.name, regexps, null, (value: string) =>\n          parser.parse(value)\n        )\n      );\n    }\n    return {\n      step,\n      expression: new CucumberExpression(step.expression, paramRegistry),\n    };\n  });\n}\n\n/**\n * Find the single step definition matching a Gherkin step. Matching is\n * opinionated and strict: the keyword must line up with the step type, exactly\n * one definition must match, and undefined/ambiguous both throw rather than\n * silently skipping (unlike Cucumber's pending/undefined dance).\n */\nfunction matchStep(\n  step: ParsedStep,\n  compiled: CompiledStep[]\n): { step: RegisteredStep; args: unknown[] } {\n  const expectedType = keywordToStepType[step.effectiveKeyword];\n  const matches: { step: RegisteredStep; args: unknown[] }[] = [];\n\n  for (const { step: def, expression } of compiled) {\n    if (def.stepType !== expectedType) continue;\n    const result = expression.match(step.text);\n    if (result) {\n      // The parsers are registered as the expression's parameter types, so the\n      // captured values are already coerced (`{int}` → number, `{color}` → the\n      // parser's T). `execute` consumes them as-is.\n      matches.push({ step: def, args: result.map(a => a.getValue(null)) });\n    }\n  }\n\n  if (matches.length === 0) throw new UndefinedStepError(step);\n  if (matches.length > 1) {\n    throw new AmbiguousStepError(\n      step,\n      matches.map(m => m.step)\n    );\n  }\n  return matches[0];\n}\n\nexport interface StepResult {\n  step: ParsedStep;\n  status: \"passed\" | \"failed\" | \"skipped\";\n  error?: Error;\n  durationMs?: number;\n}\n\nexport interface ScenarioResult {\n  scenario: ParsedScenario;\n  status: \"passed\" | \"failed\";\n  steps: StepResult[];\n}\n\n/**\n * Run one scenario against a registry. A fresh world is created per scenario\n * (state never leaks between scenarios). On the first failing step the\n * remaining steps are marked skipped, matching Cucumber's execution semantics.\n *\n * Throws on failure so it maps cleanly onto a test runner's `test()` body, but\n * the returned/attached `ScenarioResult` carries the per-step breakdown.\n */\nexport async function runScenario(\n  scenario: ParsedScenario,\n  registry: StepRegistry,\n  makeWorld: () => MergeableWorld<any, any, any>,\n  hooks: HookRegistry = globalHookRegistry\n): Promise<ScenarioResult> {\n  const compiled = compile(registry);\n  const world = makeWorld();\n  const scenarioInfo = { name: scenario.name, file: scenario.file };\n  const steps: StepResult[] = [];\n  let failed = false;\n  let firstError: Error | undefined;\n\n  const fail = (err: unknown) => {\n    if (failed) return;\n    failed = true;\n    firstError = err instanceof Error ? err : new Error(String(err));\n  };\n\n  // before-scenario hooks: a throw here aborts the scenario before any step.\n  try {\n    for (const hook of hooks.for(\"scenario\", \"before\")) {\n      await (hook.fn as ScenarioHookFn)({ world, scenario: scenarioInfo });\n    }\n  } catch (err) {\n    fail(err);\n  }\n\n  for (const step of scenario.steps) {\n    if (failed) {\n      steps.push({ step, status: \"skipped\" });\n      continue;\n    }\n    try {\n      const { step: def, args } = matchStep(step, compiled);\n      await def.execute(world, args);\n      steps.push({ step, status: \"passed\" });\n    } catch (err) {\n      const error = err instanceof Error ? err : new Error(String(err));\n      steps.push({ step, status: \"failed\", error });\n      fail(error);\n    }\n  }\n\n  // after-scenario hooks always run (teardown), even on failure. A hook failure\n  // only becomes the scenario's error if nothing else failed first.\n  for (const hook of hooks.for(\"scenario\", \"after\")) {\n    try {\n      await (hook.fn as ScenarioHookFn)({ world, scenario: scenarioInfo });\n    } catch (err) {\n      fail(err);\n    }\n  }\n\n  const result: ScenarioResult = {\n    scenario,\n    status: failed ? \"failed\" : \"passed\",\n    steps,\n  };\n\n  if (failed && firstError) {\n    // Surface the failing Gherkin line as a real stack frame so the runner\n    // renders a code frame from the `.feature` file itself. Hook failures have\n    // no step to point at, so they surface with their own stack unchanged.\n    const failing = steps.find(s => s.status === \"failed\");\n    if (failing) attachFeatureFrame(firstError, scenario.file, failing.step);\n    throw firstError;\n  }\n\n  return result;\n}\n\n/**\n * Prepend a synthetic stack frame pointing at the failing Gherkin step. Because\n * the frame's file is the real `.feature` on disk, the test runner treats it as\n * a source location and shows a code frame at the step — instead of us jamming\n * `file:line` into the error message. The frame goes *above* the real stack, so\n * the step-definition frames (the actual throw site) are preserved below it.\n */\nfunction attachFeatureFrame(\n  error: Error,\n  file: string,\n  step: ParsedStep\n): void {\n  const label = `${step.effectiveKeyword} ${step.text}`;\n  const frame = `    at ${label} (${file}:${step.line}:${step.column})`;\n  const stack = error.stack;\n  if (!stack) {\n    error.stack = `${error.name}: ${error.message}\\n${frame}`;\n    return;\n  }\n  // A message can span multiple lines, so split on the first frame marker\n  // rather than the first newline to find where the header ends.\n  const firstFrame = stack.indexOf(\"\\n    at \");\n  if (firstFrame === -1) {\n    error.stack = `${stack}\\n${frame}`;\n  } else {\n    error.stack =\n      stack.slice(0, firstFrame) + `\\n${frame}` + stack.slice(firstFrame);\n  }\n}\n"],"mappings":"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"}

package/dist/runtime.d.cts

@@ -0,0 +1,69 @@
+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";
+
+//#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
+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[]);
+}
+interface StepResult {
+  step: ParsedStep;
+  status: "passed" | "failed" | "skipped";
+  error?: Error;
+  durationMs?: number;
+}
+interface ScenarioResult {
+  scenario: ParsedScenario;
+  status: "passed" | "failed";
+  steps: StepResult[];
+}
+/**
+ * Run one scenario against a registry. 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.
+ *
+ * Throws on failure so it maps cleanly onto a test runner's `test()` body, but
+ * the returned/attached `ScenarioResult` carries the per-step breakdown.
+ */
+declare function runScenario(scenario: ParsedScenario, registry: StepRegistry, makeWorld: () => MergeableWorld<any, any, any>, hooks?: HookRegistry): Promise<ScenarioResult>;
+//#endregion
+export { AmbiguousStepError, HookRegistry, type HookScope, type HookTiming, type PlainHookFn, type RegisteredHook, type RegisteredStep, type ScenarioHookFn, type ScenarioInfo, type ScenarioResult, StepRegistry, type StepResult, type StepType, UndefinedStepError, ensureGlobalHooks, globalHookRegistry, globalRegistry, runHooks, runScenario };
+//# sourceMappingURL=runtime.d.cts.map