@g_package/jest-cucumber-fusion 2.0.0 → 3.0.0

package/src/keywords.js

@@ -0,0 +1,56 @@
+// A Gherkin step keyword, in whatever dialect the feature file declared, resolved onto the
+// one registry bucket that owns it.
+//
+// WHY THIS MODULE EXISTS. Compiled pickles throw the keyword away: a PickleStep carries only
+// `type: "Context" | "Action" | "Outcome"`, and an `And` step arrives as Context. The registry
+// is keyed by keyword, so an `And` definition must bind only `And` steps, which means the
+// keyword has to come back from the parsed AST and then be mapped through the dialect that
+// spelled it. This module owns that map and nothing else; it is pure, and it never sees a
+// pickle, a file or a parser.
+
+// The bucket order IS the resolution order. A dialect that spells one word in two lists
+// (several do) therefore still yields exactly one bucket, deterministically.
+const BUCKETS = ["given", "when", "then", "and", "but"];
+
+// Legal in every dialect and in none of the five buckets. It is listed in all five dialect
+// arrays, so a plain lookup would silently answer "given"; refusing by name is the only
+// honest answer, and it is a refusal rather than a guess.
+const UNBUCKETED_KEYWORD = "*";
+
+const asComparable = (keyword) => String(keyword).trim();
+
+const refuseUnsupportedKeyword = (keyword, language) => {
+  throw new Error(
+    `Unsupported step keyword: "${asComparable(keyword)}"` +
+      (language ? ` in the "${language}" Gherkin dialect` : "") +
+      `. Fusion binds step definitions by keyword, and only ${BUCKETS.join(
+        ", ",
+      )} have a registry to bind in. Rewrite the step with one of those keywords.`,
+  );
+};
+
+// Returns one of the five buckets, or throws. There is no third answer, which is what keeps
+// an invalid keyword from ever reaching the registry lookup: the bare TypeError an asterisk
+// step used to raise there came from exactly that gap.
+const bucketForKeyword = (keyword, dialect, language) => {
+  const comparable = asComparable(keyword);
+
+  if (comparable === UNBUCKETED_KEYWORD || comparable === "")
+    refuseUnsupportedKeyword(keyword, language);
+
+  const bucket = BUCKETS.find((candidate) =>
+    (dialect[candidate] || [])
+      .map(asComparable)
+      .some(
+        (dialectKeyword) =>
+          dialectKeyword !== UNBUCKETED_KEYWORD &&
+          dialectKeyword === comparable,
+      ),
+  );
+
+  if (!bucket) refuseUnsupportedKeyword(keyword, language);
+
+  return bucket;
+};
+
+export { bucketForKeyword };

package/src/scenario-name.js

@@ -0,0 +1,128 @@
+// What one test is called.
+//
+// With no scenarioNameTemplate the answer is the scenario's own title and nothing here is
+// entered. With a template, this module assembles the four variables the template is declared
+// to receive, calls it, and checks that what came back can actually name a test.
+//
+// The consumer's template is UNTRUSTED: it may throw, and it may answer with anything at all.
+// Both are refusals rather than something to paper over, because there is no honest name to
+// fall back on: naming one test from the template and the next from the raw title would leave
+// a report that looks complete and cannot be compared with the next run.
+//
+// Pure: no filesystem, no parser, no Jest global. The port calls it; it calls the template.
+
+import { describeValue } from "./value-description.js";
+
+// Kept as the first line of the refusal because the previous engine used it, so anything a
+// consumer greps for still matches.
+const TEMPLATE_FAILED =
+  "An error occurred while executing a scenario name template";
+
+// Tags reach a template lowercased and with their leading at sign, which is what the previous
+// engine passed: it built its lists from AST tag names, and a Gherkin AST tag name carries the
+// at sign. The value 3 carrier deliberately keeps the original case, so the lowercasing
+// happens here, where the variables are assembled.
+const asTemplateTags = (tagNames) =>
+  (tagNames || []).map((tagName) => String(tagName).toLowerCase());
+
+// The four variables, and only those four: a consumer's existing template was written against
+// this shape.
+//
+// scenarioTitle is the title of THIS test. For an Examples row that is the row's own
+// substituted title, which is the whole point of this value: the previous engine called the
+// template with the outline's un-substituted title and then registered the row under its own
+// name anyway, so the option was silently inert on every row.
+//
+// scenarioTags is the tag set that reached this scenario with the feature's declared tags
+// removed, which reproduces both of the previous engine's lists from the one source this
+// package has. Named residue: a tag written on BOTH the feature and a scenario appears only in
+// featureTags, where the previous engine would have had it in both.
+const templateVariablesFor = (loadedFeature, scenario) => {
+  const featureTags = asTemplateTags(loadedFeature.featureTags);
+  const tagsThatReachedTheScenario = asTemplateTags(scenario.tags);
+
+  return {
+    featureTitle: loadedFeature.title,
+    featureTags,
+    scenarioTitle: scenario.title,
+    scenarioTags: tagsThatReachedTheScenario.filter(
+      (tagName) => !featureTags.includes(tagName),
+    ),
+  };
+};
+
+const describeWhatCameBack = (answer) =>
+  typeof answer === "string" ? `the empty string` : describeValue(answer);
+
+const refuseUnusableName = (scenarioTitle, what, how) =>
+  new Error(
+    `${TEMPLATE_FAILED}.\n\n` +
+      `WHAT: ${what}\n` +
+      `      It was naming the scenario "${scenarioTitle}".\n` +
+      `WHY:  every test needs a name before it can be registered, and a template that cannot\n` +
+      `      produce one leaves no honest name to fall back on. Naming this test from its raw\n` +
+      `      title while its siblings keep their templated names would give a report that\n` +
+      `      looks complete and cannot be compared with the next run.\n` +
+      `HOW:  ${how}`,
+  );
+
+// Calling the untrusted template, and nothing else. Whatever it answers comes back as it is;
+// only a throw is turned into the refusal here, because that is the one outcome this function
+// cannot hand on.
+const answerFromTemplate = (loadedFeature, scenario, scenarioNameTemplate) => {
+  try {
+    return scenarioNameTemplate(templateVariablesFor(loadedFeature, scenario));
+  } catch (templateFailure) {
+    throw refuseUnusableName(
+      scenario.title,
+      `the scenarioNameTemplate threw: ${
+        templateFailure && templateFailure.message
+          ? templateFailure.message
+          : templateFailure
+      }`,
+      "make the template total over the four variables it is handed: featureTitle, " +
+        "featureTags, scenarioTitle and scenarioTags. A tag list may be empty, and a title " +
+        "may hold any character a feature file allows.",
+    );
+  }
+};
+
+const nameForScenario = (loadedFeature, scenario, scenarioNameTemplate) => {
+  if (!scenarioNameTemplate) return scenario.title;
+
+  // Named for what it is. Called anyway, a non-function was reported as a template that threw
+  // "scenarioNameTemplate is not a function" (fresh fuzz of PR #16, 2026-10-10).
+  if (typeof scenarioNameTemplate !== "function")
+    throw refuseUnusableName(
+      scenario.title,
+      `the scenarioNameTemplate is ${describeValue(scenarioNameTemplate)}, not a function.`,
+      "pass a function that takes the template variables and returns the test's name.",
+    );
+
+  const answer = answerFromTemplate(
+    loadedFeature,
+    scenario,
+    scenarioNameTemplate,
+  );
+
+  // An async template's Promise was described as "object {}", its JSON (fresh fuzz of PR #16).
+  if (answer && typeof answer.then === "function")
+    throw refuseUnusableName(
+      scenario.title,
+      "the scenarioNameTemplate returned a Promise.",
+      "return the name directly. The template runs while Fusion registers the tests, before " +
+        "any of them runs, so it cannot wait for anything.",
+    );
+
+  if (typeof answer !== "string" || answer.length === 0)
+    throw refuseUnusableName(
+      scenario.title,
+      `the scenarioNameTemplate returned ${describeWhatCameBack(answer)}.`,
+      "return a non-empty string. A missing return answers undefined, which produces a test " +
+        "that cannot be reported or selected by name.",
+    );
+
+  return answer;
+};
+
+export { nameForScenario };

package/src/shared-state.js

@@ -0,0 +1,36 @@
+// The state every copy of Fusion in one test file must share: the step and hook registry, and
+// the global configuration.
+//
+// The package is dual. A file that require()s it loads dist/index.cjs; a file that imports it
+// loads src/. Those are two copies, each with its own module variables, so state kept in a
+// module variable splits between them: a shared step library written as CommonJS registered
+// steps an ES module step file's Fusion() call could not see, and a global set by a require()ing
+// setup script never reached importing steps (both measured with packed builds, and held by
+// test/specs/baseline/assert-packaged-consumer.js).
+//
+// So the state lives on globalThis, under one key. Jest gives each test file its own global, so
+// it stays per file exactly as a module variable did. The key names the major version: every
+// 3.x copy shares it, and a future major whose state has another shape cannot read this one.
+//
+// A value is created only when absent. A copy that loads second must not reset what the first
+// copy has already registered.
+const STORE = Symbol.for("@g_package/jest-cucumber-fusion@3");
+
+const store = () => {
+  if (!globalThis[STORE]) globalThis[STORE] = {};
+  return globalThis[STORE];
+};
+
+// The shared value under `name`, created by `initialValue()` the first time it is asked for.
+const shared = (name, initialValue) => {
+  const state = store();
+  if (!Object.prototype.hasOwnProperty.call(state, name))
+    state[name] = initialValue();
+  return state[name];
+};
+
+const replaceShared = (name, value) => {
+  store()[name] = value;
+};
+
+export { shared, replaceShared };

package/src/step-argument.js

@@ -0,0 +1,56 @@
+// A pickle step's Gherkin argument, turned into the shape a consumer's step function receives.
+//
+// A pickle hands back a dataTable of rows of cells, or a docString with content. A step
+// function receives an array of header-keyed row objects, or a plain string. That transform
+// belonged to the removed intermediary (parsed-feature-loading.js:33-63) and is owned here.
+//
+// Two values have to survive, because a consumer wrote them down on purpose: the EMPTY string
+// from an empty docstring, and the EMPTY array from a header-only table. Both are falsy, so
+// every test here is for PRESENCE, never truthiness, never `.length`.
+
+// `null` means "this step carries no argument", which is a different fact from an empty one.
+const NO_STEP_ARGUMENT = null;
+
+const cellValues = (row) => (row.cells || []).map((cell) => cell.value);
+
+// Header row names the keys; every later row becomes one object under those keys. A
+// header-only table is an empty array of rows, not an absent argument.
+const asRowObjects = (dataTable) => {
+  const [header, ...bodyRows] = dataTable.rows || [];
+  if (!header) return [];
+
+  const columnNames = cellValues(header);
+
+  // defineProperty, not assignment: a column headed `__proto__` would otherwise call the
+  // prototype setter and vanish from the row (fresh fuzz of PR #16, 2026-10-10, B1). The row
+  // stays a plain object, so a consumer's toStrictEqual against a literal still holds.
+  return bodyRows.map((row) =>
+    cellValues(row).reduce(
+      (rowObject, value, columnIndex) =>
+        Object.defineProperty(rowObject, columnNames[columnIndex], {
+          value,
+          enumerable: true,
+          writable: true,
+          configurable: true,
+        }),
+      {},
+    ),
+  );
+};
+
+const stepArgumentFrom = (pickleStepArgument) => {
+  if (pickleStepArgument == null) return NO_STEP_ARGUMENT;
+
+  if (pickleStepArgument.dataTable)
+    return asRowObjects(pickleStepArgument.dataTable);
+
+  // `content` is read by presence: an empty docstring is "" and must reach the step.
+  if (pickleStepArgument.docString)
+    return pickleStepArgument.docString.content == null
+      ? NO_STEP_ARGUMENT
+      : pickleStepArgument.docString.content;
+
+  return NO_STEP_ARGUMENT;
+};
+
+export { stepArgumentFrom };

package/src/step-matching.js

@@ -0,0 +1,89 @@
+// Which registered definition owns a step, and what that definition is called with.
+//
+// The step text arriving here is CONCRETE: a Scenario Outline row reaches this module with
+// its Examples values already substituted, so an outline step is bound by ordinary matching.
+// The heuristic that used to guess whether a definition could own a step whose text still
+// held `<placeholders>` is gone with the need for it, and with it went the two defects that
+// lived in it.
+//
+// Every answer is a bound step, an UNBOUND step, or a refusal.
+//
+// Unbound is a returned result rather than a throw, and that carrier is the whole of what this
+// module decides. A throw cannot express "unbound, and tolerated", which is precisely what a
+// consumer asks for by switching the step check off, and a throw on the first unbound step
+// can never reach the caller that holds the option, nor let it see the other unbound steps.
+// So the lookup reports, and the caller holding the options decides.
+//
+// Ambiguity stays a refusal from here: it is not switchable, because there is no reading of
+// two matching definitions under which Fusion could pick one.
+const UNBOUND = Object.freeze({ isBound: false });
+
+const findMatchingStep = (featureRegistry, currentStep) => {
+  const bucket = currentStep.keyword;
+  const stepText = currentStep.stepText;
+  const matchingSteps = Object.keys(featureRegistry[bucket]).filter(
+    (matcherKey) => {
+      return isFunctionForScenario(
+        stepText,
+        featureRegistry[bucket][matcherKey],
+      );
+    },
+  );
+  if (matchingSteps.length === 0) return UNBOUND;
+
+  if (matchingSteps.length > 1) {
+    const competingMatchers = matchingSteps
+      .map((matcherSource) => `"${matcherSource}"`)
+      .join(", ");
+    throw new Error(
+      `Ambiguous step definition: "${stepText}" matches ${matchingSteps.length} step definitions: ${competingMatchers}`,
+    );
+  }
+
+  // The winning definition is resolved here, where its key was just filtered, and handed over
+  // resolved. Passing the registry, the bucket and the key instead would be asking the next
+  // function to repeat a lookup this one has already done.
+  return boundStepFor(
+    featureRegistry[bucket][matchingSteps[0]],
+    stepText,
+    currentStep.stepArgument,
+  );
+};
+
+// A matcher with the global (g) or sticky (y) flag carries a `lastIndex` from one use to the
+// next, and a sticky one starts matching there. Testing a step and then reading its captures
+// each moved it, so a sticky matcher bound its step with no captures (finding F5 of the PR #16
+// review). Every use starts from the beginning of the step text instead, and leaves lastIndex
+// at 0 again: the consumer owns the RegExp and may use it elsewhere.
+const execFromStart = (stepRegExp, stepText) => {
+  stepRegExp.lastIndex = 0;
+  const match = stepRegExp.exec(stepText);
+  stepRegExp.lastIndex = 0;
+  return match;
+};
+
+const isFunctionForScenario = (stepText, stepDefinition) => {
+  if (stepDefinition.stepRegExp)
+    return execFromStart(stepDefinition.stepRegExp, stepText) !== null;
+
+  return stepText === stepDefinition.stepExpression;
+};
+
+const boundStepFor = (stepDefinition, stepText, stepArgs) => {
+  // A string matcher captures nothing; a regex matcher captures its groups out of the
+  // concrete step text. Both may still carry a Gherkin argument.
+  const captures = stepDefinition.stepRegExp
+    ? (execFromStart(stepDefinition.stepRegExp, stepText) || []).slice(1)
+    : [];
+
+  // Forward the step's Gherkin argument on PRESENCE, never on its type. A type test drops
+  // half the shapes: Gherkin parses a data table to an array but a docstring to a string,
+  // and an empty docstring to "", which a `.length` test would drop too. Absent, the
+  // argument is null, so this is the whole distinction that matters.
+  const stepArguments =
+    stepArgs == null ? captures : captures.concat([stepArgs]);
+
+  return { isBound: true, stepArguments, stepFn: stepDefinition.stepFn };
+};
+
+export { findMatchingStep };

package/src/tag-filter.js

@@ -0,0 +1,90 @@
+// Whether a scenario's tags satisfy a tagFilter expression.
+//
+// This module owns the NORMALISATION and the predicate. It does not own the expression
+// language: the parse function arrives as an argument from src/feature-source.js, which is the
+// one module the architectural law lets reach the cucumber scope
+// (test/specs/arch/dependency-direction.steps.js). That injection is why this module requires
+// nothing at all, and so can be read and reasoned about without a parser, a file or a runner.
+
+// Both sides are lowercased before they meet, which is the whole of the normalisation and the
+// reason matching ignores case. Lowercasing the expression lowercases its OPERATORS too, so an
+// expression written `@a AND @b` parses here where the previous engine's case-sensitive
+// rewriter rejected it. That widening is strict: every expression that worked before still
+// works.
+const lowercased = (text) => String(text).toLowerCase();
+
+const refusal = (expression, why) =>
+  new Error(
+    `Could not parse tag filter "${expression}".\n\n` +
+      `WHY:  ${why}\n` +
+      `HOW:  write a tag name as @name, and combine names with the operators "and", "or" and\n` +
+      `      "not", grouping with parentheses "(" and ")". For example:\n` +
+      `        @smoke and not @slow\n` +
+      `        @shop and (@included or @draft)`,
+  );
+
+const refuseUnparseableExpression = (expression, parseFailure) =>
+  refusal(
+    expression,
+    `the tag expression parser could not read it: ${
+      parseFailure && parseFailure.message ? parseFailure.message : parseFailure
+    }\n` +
+      `      The expression is lowercased before it is parsed, because tag matching ignores\n` +
+      `      case, so the text quoted above may differ in case from what you wrote.`,
+  );
+
+const refuseUntaggedOperand = (expression, operand) =>
+  refusal(
+    expression,
+    `"${operand}" is not a tag. Every tag Fusion reads from a feature file starts with "@",\n` +
+      `      so "${operand}" could never match, and the filter would quietly select no\n` +
+      `      scenario. Did you mean "@${operand}"?`,
+  );
+
+// Every operand of a parsed expression, read off its tree: an operand node carries its text as
+// `value`, and every other node holds its operands in its own properties.
+const operandsOf = (node) =>
+  typeof node.value === "string"
+    ? [node.value]
+    : Object.values(node)
+        .filter((child) => child !== null && typeof child === "object")
+        .flatMap(operandsOf);
+
+// The parser saw the lowercased expression; name the operand as the consumer wrote it, matched
+// as a WHOLE token of their text, and as parsed when no token matches (an escaped character,
+// for one). A substring search would find `smoke` inside `@Smoke`, and an offset taken from the
+// lowercased text drifts wherever lowercasing changes a length ("İ" becomes two code units).
+const asWritten = (expression, operand) =>
+  String(expression)
+    .split(/[\s()]+/)
+    .find((token) => lowercased(token) === operand) || operand;
+
+// Returns a predicate over a list of tag names, or raises the refusal if the expression cannot
+// be read. Raising rather than answering false for everything is deliberate: an unparseable
+// expression that quietly selected no scenario would exit 0 having run nothing, which is
+// exactly what a correct filter selecting no scenario looks like.
+//
+// The parser accepts a bare word such as `smoke` as an operand, but no tag Gherkin hands Fusion
+// lacks its "@", so such an operand can never match and leads to the same silent outcome. It is
+// refused with the same first line (finding F1 of the PR #16 review). 2.0.0 refused a lone bare
+// word the same way, but let a bare operand inside a longer expression through, or failed on it
+// with a ReferenceError.
+const tagFilterFor = (expression, parseExpression) => {
+  let parsed;
+
+  try {
+    parsed = parseExpression(lowercased(expression));
+  } catch (parseFailure) {
+    throw refuseUnparseableExpression(expression, parseFailure);
+  }
+
+  const untagged = operandsOf(parsed).find(
+    (operand) => !operand.startsWith("@"),
+  );
+  if (untagged !== undefined)
+    throw refuseUntaggedOperand(expression, asWritten(expression, untagged));
+
+  return (tagNames) => parsed.evaluate((tagNames || []).map(lowercased));
+};
+
+export { tagFilterFor };

package/src/test-registration.js

@@ -0,0 +1,178 @@
+// Driven port: the Jest runner.
+//
+// This is the ONLY module under src/ allowed to name describe, test, beforeEach or afterEach,
+// and that is an architectural law rather than a convention (see
+// test/specs/arch/dependency-direction.steps.js). It takes a LoadedFeature and the registry
+// that feature's definitions were registered in, and from them it owns four things the
+// removed intermediary used to own: one describe per feature, the hook wiring, one test per
+// scenario, and running the steps of a test in order.
+
+import { findMatchingStep } from "./step-matching.js";
+import { unmatchedStepRefusal } from "./code-suggestion.js";
+import { nameForScenario } from "./scenario-name.js";
+
+// BIND BEFORE REGISTERING. Every step of every scenario is matched up front, so a refusal
+// (an unmatched step, an ambiguous one, an unsupported keyword) leaves Fusion() on the way
+// out, synchronously, at collection time. Inside a describe body it would be reported as a
+// broken suite instead, and a consumer who wrapped Fusion() in a try/catch would never see
+// it (test/specs/features/step-definitions/undefined-step.steps.js drives exactly that).
+//
+// Binding up front is also what lets ONE refusal name every unbound step of the feature: the
+// lookup reports an unbound step rather than throwing on it, so this pass sees all of them.
+const boundScenarios = (loadedFeature, featureRegistry) =>
+  loadedFeature.scenarios.map((scenario) => {
+    const steps = scenario.steps.map((step) => ({
+      step,
+      bound: findMatchingStep(featureRegistry, step),
+    }));
+
+    return {
+      scenario,
+      // Read by truthiness and carried through untouched: a LoadedFeature staged without it,
+      // as a test double's fabricated one is, reads as "not excluded".
+      excludedByTagFilter: !!scenario.excludedByTagFilter,
+      steps,
+      unboundSteps: steps
+        .filter((each) => !each.bound.isBound)
+        .map((each) => each.step),
+    };
+  });
+
+// NAME BEFORE REGISTERING, for the same reason as binding. A template may throw on the third
+// scenario after naming the first two, and a refusal that arrived mid-describe would leave
+// those two registered: a report that looks complete and cannot be compared with the next run.
+// Asking for every name first makes it one refusal with nothing registered.
+//
+// One call per test, and the name is kept. Both registration routes below take it from here,
+// so a scenario's name never depends on whether it ran, and nothing re-derives it in a test
+// body: an expensive template is paid for once, and an impure one cannot disagree with the
+// name its test was registered under.
+const namedScenarios = (loadedFeature, scenarios, scenarioNameTemplate) =>
+  scenarios.map((scenario) =>
+    Object.assign({}, scenario, {
+      name: nameForScenario(
+        loadedFeature,
+        scenario.scenario,
+        scenarioNameTemplate,
+      ),
+    }),
+  );
+
+// The failing-step decoration, byte for byte as it has always read: the step's text in double
+// quotes, the JSON of the arguments it was called with, then the original message, each on
+// its own line with a blank line between. Every consumer failure output, and anything that
+// greps it, is this shape.
+//
+// An Error is decorated IN PLACE and rethrown, as jest-cucumber did: its class, its stack
+// frames in the consumer's steps file (Jest's code frame) and properties such as expect's
+// matcherResult all survive. A new Error lost every one of them (fresh review of PR #16,
+// 2026-10-10, finding B1). The stack's first line repeats the message, so it is rewritten to
+// match. Recognised by its tag rather than instanceof, which fails for an error made in another
+// realm (Node's own, from inside Jest's test context). Anything that cannot be rewritten (a
+// frozen error) is wrapped with the original as its cause; anything else thrown is wrapped.
+const isError = (value) =>
+  Object.prototype.toString.call(value) === "[object Error]";
+
+const decorationOf = (stepText, stepArguments, originalMessage) =>
+  `Failing step: "${stepText}"\n\n` +
+  `Step arguments: ${JSON.stringify(stepArguments)}\n\n` +
+  `Error: ${originalMessage}`;
+
+const decorateInPlace = (failure, decorated) => {
+  const oldHeader = `${failure.name}: ${failure.message}`;
+  const { stack } = failure;
+  failure.message = decorated;
+  if (typeof stack === "string" && stack.startsWith(oldHeader))
+    failure.stack = `${failure.name}: ${decorated}${stack.slice(oldHeader.length)}`;
+  return failure;
+};
+
+const decorate = (stepText, stepArguments, failure) => {
+  if (!isError(failure))
+    return new Error(
+      decorationOf(
+        stepText,
+        stepArguments,
+        failure && failure.message ? failure.message : failure,
+      ),
+    );
+  const decorated = decorationOf(stepText, stepArguments, failure.message);
+  try {
+    return decorateInPlace(failure, decorated);
+  } catch {
+    return new Error(decorated, { cause: failure });
+  }
+};
+
+// One test body: the scenario's steps, in order, each awaited before the next begins. A step
+// that throws or whose promise rejects ends the scenario there: running on would report a
+// second, invented failure and hide the first.
+const runScenario = (scenario) => async () => {
+  for (const step of scenario.steps) {
+    try {
+      await step.bound.stepFn(...step.bound.stepArguments);
+    } catch (failure) {
+      throw decorate(step.step.stepText, step.bound.stepArguments, failure);
+    }
+  }
+};
+
+// Each hook registered exactly ONCE per feature. The describe below already wraps every test
+// of the feature, so one registration runs the hook around each of them; N registrations
+// would run every hook N times per test.
+const registerHooks = (featureRegistry, beforeEachFn, afterEachFn) => {
+  featureRegistry.before.forEach((beforeHook) => beforeEachFn(beforeHook));
+  featureRegistry.after.forEach((afterHook) => afterEachFn(afterHook));
+};
+
+const registerFeature = (loadedFeature, featureRegistry, options) => {
+  const scenarios = boundScenarios(loadedFeature, featureRegistry);
+
+  // THE errors DECISION, taken here because this is the only module from which either outcome
+  // is reachable. With the step check on, one refusal names every unbound step of the feature
+  // and nothing is registered. With it off, the scenarios holding them become skipped tests,
+  // never passing ones, and never absent ones. Validation can be switched off; it is never
+  // switched into silence.
+  //
+  // Only the scenarios the tag filter KEPT are counted. A consumer who excluded a scenario is
+  // not asking for its steps to be bound, and excluding a half-written scenario is one of the
+  // main reasons to reach for a filter at all.
+  const unboundSteps = scenarios
+    .filter((scenario) => !scenario.excludedByTagFilter)
+    .flatMap((scenario) => scenario.unboundSteps);
+
+  if (unboundSteps.length > 0 && options.errors.stepsMustMatchFeatureFile)
+    throw unmatchedStepRefusal(loadedFeature.title, unboundSteps);
+
+  // Every name, before anything is registered. With no template this is each scenario's own
+  // title; with one it is what the template answered, and a template that cannot answer
+  // refuses here.
+  const named = namedScenarios(
+    loadedFeature,
+    scenarios,
+    options.scenarioNameTemplate,
+  );
+
+  // A feature with no scenarios registers no describe at all, and therefore no hooks: an
+  // empty describe is a reported suite that observes nothing, and hooks inside it would wrap
+  // nothing.
+  if (named.length === 0) return;
+
+  describe(loadedFeature.title, () => {
+    registerHooks(featureRegistry, beforeEach, afterEach);
+
+    named.forEach((scenario) => {
+      // ONE skip route, for either reason, and ONE name whichever route is taken. A scenario
+      // the filter excluded and a scenario left unwired are both registered as a skipped test
+      // under the name they would have carried had they run, and a scenario that is both is
+      // registered ONCE: two registrations would put two tests of one name in the report.
+      // Everything else runs: switching a check off, or filtering, costs the consumer only the
+      // scenarios it actually names.
+      if (scenario.excludedByTagFilter || scenario.unboundSteps.length > 0)
+        test.skip(scenario.name, () => {});
+      else test(scenario.name, runScenario(scenario));
+    });
+  });
+};
+
+export { registerFeature };

package/src/value-description.js

@@ -0,0 +1,26 @@
+// How a refusal names a value the consumer handed Fusion: `<type> <value>`.
+//
+// JSON first, because that is the form the refusals have always printed (`string "x"`,
+// `object ["@smoke"]`). JSON.stringify throws on a BigInt and on a circular object, and answers
+// undefined for a function or a symbol, so those fall back to util.inspect: a refusal must never
+// crash while naming what it refuses (finding F8 of the PR #16 review).
+import { inspect } from "util";
+
+const asText = (value) => {
+  try {
+    const json = JSON.stringify(value);
+    if (json !== undefined) return json;
+  } catch {
+    // Not serialisable as JSON; described below.
+  }
+  try {
+    return inspect(value);
+  } catch {
+    // A custom inspect hook that throws: say so rather than let the refusal crash.
+    return "(a value that cannot be printed)";
+  }
+};
+
+const describeValue = (value) => `${typeof value} ${asText(value)}`;
+
+export { describeValue };