@step-forge/step-forge 0.0.19 → 0.0.20

package/dist/runtime.d.ts

@@ -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.js";
+
+//#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.ts.map

package/dist/runtime.js

@@ -0,0 +1,159 @@
+import { a as StepRegistry, i as runHooks, n as ensureGlobalHooks, o as globalRegistry, r as globalHookRegistry, t as HookRegistry } from "./hooks-CywugMQQ.js";
+import { CucumberExpression, ParameterType, ParameterTypeRegistry } from "@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 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 ParameterType(parser.name, regexps, null, (value) => parser.parse(value)));
+		}
+		return {
+			step,
+			expression: new 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 = 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
+export { AmbiguousStepError, HookRegistry, StepRegistry, UndefinedStepError, ensureGlobalHooks, globalHookRegistry, globalRegistry, runHooks, runScenario };
+
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","names":[],"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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"}