@g_package/jest-cucumber-fusion 2.0.0 → 3.0.0

package/dist/index.d.cts

@@ -0,0 +1,145 @@
+// Type definitions for @g_package/jest-cucumber-fusion
+// Project: https://github.com/gotreasa/jest-cucumber-fusion#readme
+// Originally written by Pelle Johnsen <https://github.com/pjoe> for DefinitelyTyped.
+
+/** What Fusion passes a step: a capture or a docstring as a string, a data table as its rows. */
+export type StepArgument = string | Array<Record<string, string>>;
+
+// Declared through a method so its parameters are checked bivariantly: a step may declare
+// the narrower type it receives, such as `(count: string) => ...`, which a plain function type
+// refuses under strictFunctionTypes. A type Fusion never passes, such as `number`, is still
+// refused, and an undeclared parameter is still a StepArgument.
+export type CallBack = {
+  step(...args: ReadonlyArray<StepArgument>): void | Promise<void>;
+}["step"];
+
+export interface StepChain {
+  stepSentence: string | RegExp;
+  stepFnDefinition: CallBack;
+}
+
+export function Given(name: string | RegExp, callback: CallBack): StepChain;
+export function Given(chain: StepChain): StepChain;
+export function When(name: string | RegExp, callback: CallBack): StepChain;
+export function When(chain: StepChain): StepChain;
+export function Then(name: string | RegExp, callback: CallBack): StepChain;
+export function Then(chain: StepChain): StepChain;
+export function And(name: string | RegExp, callback: CallBack): StepChain;
+export function And(chain: StepChain): StepChain;
+export function But(name: string | RegExp, callback: CallBack): StepChain;
+export function But(chain: StepChain): StepChain;
+
+export function Before(callback: () => void | Promise<void>): void;
+export function After(callback: () => void | Promise<void>): void;
+
+/**
+ * Which of Fusion's validations are on.
+ *
+ * - `stepsMustMatchFeatureFile` (default on): a feature step that no registered definition
+ *   matches is refused at collection, in one message naming every unbound step of the feature
+ *   with starter code for each. Off, the scenarios holding those steps are registered through
+ *   `test.skip`, so Jest reports them as skipped and never as passed.
+ * - `scenariosMustMatchFeatureFile` (default on): two scenarios of one feature file declared
+ *   with the same title, ignoring case and counting a scenario inside a Rule, are refused at
+ *   collection. A Scenario Outline counts once however many Examples rows it has, so repeated
+ *   row names are never a duplicate. Off, the file is accepted as written.
+ * - `allowScenariosNotInFeatureFile`: accepted and vestigial. Fusion generates the scenario
+ *   definitions from the feature file itself, so there is no scenario outside it to allow.
+ *
+ * As a boolean, `errors` is shorthand: `true` turns every key on, `false` turns every key off.
+ * As an object it merges KEY-WISE over the defaults, so naming one key says nothing about the
+ * others. Switching the step check off leaves the duplicate check exactly as it was.
+ */
+export interface FusionErrorOptions {
+  stepsMustMatchFeatureFile?: boolean;
+  scenariosMustMatchFeatureFile?: boolean;
+  allowScenariosNotInFeatureFile?: boolean;
+}
+
+/**
+ * What a scenarioNameTemplate is handed, once per test. Unchanged from the shape consumers
+ * already write: these four variables and no others.
+ *
+ * `scenarioTitle` is the title of the individual test being named. For a Scenario Outline row
+ * that is the row's OWN substituted title, so each row gets its own name.
+ *
+ * `featureTags` are the feature's declared tags. `scenarioTags` are the rest of the tags that
+ * reached the scenario, which for an Examples row includes that Examples set's tags. The two
+ * lists are disjoint, and every tag carries its leading `@` and is lowercased. A tag declared
+ * on both the feature and the scenario appears in `featureTags` only.
+ */
+export interface ScenarioNameTemplateVars {
+  featureTitle: string;
+  scenarioTitle: string;
+  scenarioTags: string[];
+  featureTags: string[];
+}
+
+export interface FusionOptions {
+  /**
+   * Accepted and ignored. Fusion always resolves a relative feature path against the
+   * directory of the file that called it, and hands an absolute path on from there, so there
+   * is nothing left for this to switch.
+   */
+  loadRelativePath?: boolean;
+  errors?: boolean | FusionErrorOptions;
+  /**
+   * Which scenarios to run, as a tag expression: a tag name written `@name`, combined with
+   * the operators `and`, `or` and `not` and grouped with parentheses. For example
+   * `@smoke and not @slow`, or `@shop and (@included or @draft)`.
+   *
+   * Matching ignores case on both sides: the expression and every tag are lowercased before
+   * they are compared, so the operators may be written in any case too.
+   *
+   * A scenario is selected on the tags its compiled pickle carries, which is the union of the
+   * scenario's own tags, its feature's tags and, for a Scenario Outline row, that Examples
+   * set's tags. A scenario the expression excludes is registered through `test.skip` under its
+   * own unannotated name, so Jest reports it as skipped: never run, and never absent from the
+   * report. Its steps are also exempt from the unmatched-step check, because a scenario you
+   * excluded is not one you are asking to have wired. They are still read, so a step with an
+   * unsupported keyword (`*`) or one that matches two definitions is refused all the same.
+   *
+   * An expression that cannot be parsed is refused at collection, before anything is
+   * registered, and the refusal names the expression you wrote. So is one with an operand
+   * that is not a tag, such as `smoke` written for `@smoke`: it could never match.
+   */
+  tagFilter?: string;
+  /**
+   * Renames every test Fusion registers, Scenario Outline rows included. It is called once per
+   * test while Fusion registers, never again while the tests run, and it names a test whatever
+   * its status: a scenario skipped because a tag filter excluded it, or because its steps do
+   * not bind, carries the same templated name it would have carried had it run.
+   *
+   * It must return a non-empty string. A template that throws, or that answers with anything
+   * else, is refused at collection rather than naming a test something Jest cannot report.
+   */
+  scenarioNameTemplate?: (vars: ScenarioNameTemplateVars) => string;
+}
+
+export function Fusion(feature: string, options?: FusionOptions): void;
+
+/**
+ * Sets options for every `Fusion()` call in the current test file, so they need not be repeated
+ * in each one. Meant for a script listed in Jest's `setupFiles`:
+ *
+ * ```js
+ * // jest.config.js      ->  setupFiles: ["<rootDir>/jest.setup.js"]
+ * // jest.setup.js
+ * const { setFusionConfiguration } = require("@g_package/jest-cucumber-fusion");
+ * setFusionConfiguration({ tagFilter: "@smoke and not @slow" });
+ * ```
+ *
+ * Options are merged lowest to highest: the defaults, then whatever this setter holds, then the
+ * options passed to one `Fusion()` call. A per-call option therefore still wins for its own
+ * file, and `errors` merges key-wise at every layer, so naming one validation never switches
+ * off another. An option set to `undefined`, such as an unset environment variable forwarded
+ * as `{ tagFilter: process.env.TAGS }`, counts as not set and leaves the layer below in place.
+ *
+ * A second call REPLACES what the first set rather than merging into it, which is what lets a
+ * global be cleared or redefined. Jest gives each test file its own module registry and runs
+ * `setupFiles` inside it, so what is set here cannot reach another file.
+ *
+ * An argument that is not an options object is refused where it is called, before any step
+ * definition file has loaded. An unknown key is accepted and ignored, exactly as it is per call.
+ */
+export function setFusionConfiguration(options: FusionOptions): void;

package/package.json

@@ -1,16 +1,32 @@
 {
   "name": "@g_package/jest-cucumber-fusion",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Write cucumber test as part of a jest run (including coverage)",
-  "main": "src/index.js",
+  "type": "module",
+  "main": "dist/index.cjs",
   "types": "src/index.d.ts",
+  "files": [
+    "src/",
+    "dist/",
+    "scripts/prepare-hooks.js"
+  ],
+  "engines": {
+    "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+  },
   "scripts": {
-    "test": "jest --color",
+    "pretest": "npm run build",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --color",
     "test-d": "tsd",
-    "coverage": "jest --coverage",
+    "test:baseline": "node test/specs/baseline/run-all.js",
+    "coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "lint": "eslint . --max-warnings 0",
+    "lint:secrets": "secretlint \"**/*\"",
     "commit": "git-cz",
     "semantic-release": "semantic-release",
-    "fmt": "npx prettier --write ."
+    "fmt": "npx prettier --write .",
+    "prepare": "node scripts/prepare-hooks.js",
+    "build": "node scripts/build-cjs.js",
+    "prepack": "npm run build"
   },
   "repository": {
     "type": "git",
@@ -23,14 +39,28 @@
     "gherkin"
   ],
   "dependencies": {
-    "callsites": "~3.1.0",
-    "jest": "^30.4.2",
-    "jest-cucumber": "^4.5.0"
+    "@cucumber/gherkin": "42.0.1",
+    "@cucumber/messages": "34.2.1",
+    "@cucumber/tag-expressions": "11.0.1",
+    "callsites": "4.2.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.2.3",
+    "@commitlint/config-conventional": "^21.2.3",
+    "@eslint/js": "^9.39.5",
+    "@secretlint/secretlint-rule-pattern": "^13.0.7",
+    "@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
     "cz-conventional-changelog": "^3.3.0",
+    "esbuild": "0.28.2",
+    "eslint": "^9.39.5",
+    "eslint-plugin-jest": "^29.16.6",
     "fast-check": "^4.10.2",
-    "prettier": "2.3.2",
+    "globals": "^17.13.0",
+    "husky": "^9.1.7",
+    "jest": "^30.4.2",
+    "lint-staged": "^16.4.0",
+    "prettier": "3.9.9",
+    "secretlint": "^13.0.7",
     "semantic-release": "^25.0.5",
     "tsd": "^0.33.0"
   },
@@ -56,7 +86,8 @@
       [
         "@semantic-release/npm",
         {
-          "npmPublish": true
+          "npmPublish": false,
+          "tarballDir": "release"
         }
       ]
     ],
@@ -78,11 +109,30 @@
       "/node_modules/",
       "<rootDir>/.claude/"
     ],
+    "collectCoverageFrom": [
+      "src/**/*.js"
+    ],
     "coveragePathIgnorePatterns": [
       "/node_modules/",
       "/test/"
     ],
     "coverageDirectory": "./coverage/",
     "collectCoverage": true
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./src/index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "jest": ">=27"
   }
 }

package/scripts/prepare-hooks.js

@@ -0,0 +1,23 @@
+// The prepare script: installs the git hooks, exactly as `husky` does, but writes husky's
+// message to stderr instead of stdout.
+//
+// npm runs `prepare` during `npm pack`, and `npm pack --json` prints its JSON on stdout. husky's
+// own command writes its message to stdout, so outside a git checkout (a source archive, for
+// one) ".git can't be found" broke that JSON (finding F6 of PR #16 review round 4;
+// test/specs/packaging/prepare-script.steps.js). husky returns the message from its function,
+// so it is still shown, on stderr, and the exit code stays 0 as husky's own command keeps it.
+//
+// npm also runs `prepare` when a consumer installs this package from a directory or a `file:`
+// dependency. That install has none of this package's devDependencies, husky included, and no
+// hooks to install, so a missing husky is skipped quietly. Any other failure still fails. This
+// file ships in the package for that reason (fresh fuzz of PR #16, 2026-10-10, finding B4).
+let husky;
+try {
+  ({ default: husky } = await import("husky"));
+} catch (failure) {
+  if (failure && failure.code === "ERR_MODULE_NOT_FOUND") process.exit(0);
+  throw failure;
+}
+
+const message = husky();
+if (message) console.error(`husky: ${message}`);

package/src/code-suggestion.js

@@ -0,0 +1,240 @@
+// What to tell a consumer whose step binds nothing: the starter code for one step, and the
+// one numbered refusal for every unbound step of a feature.
+//
+// The refusal is the whole value here. "No step definition matches" on its own is the message
+// the consumer already had; code they can paste is the message they wanted. So each entry
+// carries a verb call in FUSION's own idiom, keyed on that step's recovered keyword, with a
+// matcher built from the step's own text and one parameter for every argument the step
+// implies.
+//
+// Pure: no filesystem, no parser, no Jest global. The argument detection, the escaping and the
+// parameter naming are carried over from the removed intermediary's code generator
+// (code-generation/step-generation.js:19-61); only its output form is not, because it emitted
+// a test-callback idiom Fusion has no verb for.
+
+// A number, or a double-quoted substring. The intermediary's pattern had a third alternative
+// for an angle-bracket placeholder; it is dead for Fusion, because the step text reaching a
+// suggestion is already substituted for its Examples row and no angle brackets survive.
+const ARGUMENT_IN_STEP_TEXT = /([-+]?[0-9]*\.?[0-9]+)|"([^"<]+)"/g;
+
+// A plain unsigned integer keeps the familiar (\d+). Any other number the detection above
+// accepts (a sign, a decimal point, a leading dot) gets a capture that matches that same shape,
+// because (\d+) cannot match "3.14", "-5" or ".5" and the suggested matcher would then fail to
+// bind the very step it was suggested for. Inherited from jest-cucumber's generator; found by
+// fuzzing on 2026-10-08.
+const INTEGER_CAPTURE = "(\\d+)";
+const NUMBER_CAPTURE = "([-+]?\\d*\\.?\\d+)";
+// A quoted value never holds a double quote (the detection above stops at one), so the capture
+// stops at one too. jest-cucumber's "(.*)" is greedy: it spans several quoted arguments and the
+// text between them, so the matcher for `"a" "b"` also matched `"a" "b" 3 "c"` and two pasted
+// definitions were refused as ambiguous. And "." matches no line terminator, which a quoted
+// value may hold (a lone \r, U+2028 and U+2029 survive Gherkin's \r?\n line split); a negated
+// class matches every character but the quote. Found by the review of the PR #16 fixes.
+const QUOTED_CAPTURE = '"([^"]*)"';
+
+// One capture for every value an argument position takes across the steps it must bind, so
+// one definition binds them all: the integer capture only if every value is an unsigned
+// integer.
+const captureForNumbers = (numberTexts) =>
+  numberTexts.every((numberText) => /^\d+$/.test(numberText))
+    ? INTEGER_CAPTURE
+    : NUMBER_CAPTURE;
+
+const captureFor = (kind, valueTexts) =>
+  kind === "number" ? captureForNumbers(valueTexts) : QUOTED_CAPTURE;
+
+const VERB_FOR_BUCKET = {
+  given: "Given",
+  when: "When",
+  then: "Then",
+  and: "And",
+  but: "But",
+};
+
+// The matcher is emitted as a regex LITERAL, so "/" must be escaped too: unescaped it ends the
+// literal early and the suggested code is not valid JavaScript. The same holds for the two
+// Unicode line terminators, U+2028 and U+2029: Gherkin splits lines on \r?\n only, so they can
+// reach step text, and JavaScript forbids a line terminator inside a regex literal. They are
+// written as \u escapes, which match the same character. A lone \r reaches step text the same
+// way and ends a regex or a string literal just as early, so it is written \r in both.
+const escapedLineTerminators = (text) =>
+  text
+    .replace(/\r/g, "\\r")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+
+const escapedForRegex = (text) =>
+  escapedLineTerminators(text.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&"));
+
+const escapedForDoubleQuotes = (text) =>
+  escapedLineTerminators(text.replace(/[\\"]/g, "\\$&"));
+
+// Every argument the step text carries, as {start, end, kind, value} in text order. One pass
+// with indices rather than a sequence of string replacements: a replacement would rewrite the
+// first occurrence of the matched text wherever it sat, which is the wrong one as soon as a
+// step says the same number twice.
+//
+// matchAll clones the pattern internally, so a shared lastIndex cannot leak between calls and
+// the module-level regex needs no defensive copy of its own.
+const argumentsInStepText = (stepText) =>
+  [...stepText.matchAll(ARGUMENT_IN_STEP_TEXT)].map((match) => ({
+    start: match.index,
+    end: match.index + match[0].length,
+    kind: match[1] === undefined ? "quoted" : "number",
+    value: match[1] === undefined ? match[2] : match[1],
+  }));
+
+// A step's SHAPE: its verb and its literal text, with each argument reduced to its kind. Steps
+// of one shape are bound by one definition, whatever their values.
+const shapeOf = (step) => {
+  const argumentsFound = argumentsInStepText(step.stepText);
+  const shape = argumentsFound.reduce(
+    (built, argument) => ({
+      text:
+        built.text +
+        step.stepText.slice(built.consumedTo, argument.start) +
+        `\u0000${argument.kind}\u0000`,
+      consumedTo: argument.end,
+    }),
+    { text: "", consumedTo: 0 },
+  );
+
+  return `${step.keyword}\u0000${
+    shape.text + step.stepText.slice(shape.consumedTo)
+  }`;
+};
+
+// An ANCHORED regex literal over the step's own text, with each detected argument replaced by
+// a capture group and everything around it escaped so it matches literally.
+const matcherRegexFor = (stepText, argumentsFound) => {
+  const pattern = argumentsFound.reduce(
+    (built, argument) => ({
+      source:
+        built.source +
+        escapedForRegex(stepText.slice(built.consumedTo, argument.start)) +
+        argument.capture,
+      consumedTo: argument.end,
+    }),
+    { source: "", consumedTo: 0 },
+  );
+
+  return `/^${
+    pattern.source + escapedForRegex(stepText.slice(pattern.consumedTo))
+  }$/`;
+};
+
+// One parameter per detected argument, then the Gherkin argument LAST if the step carries one,
+// named for the shape it actually is. Fusion hands a step its captures and then its Gherkin
+// argument, so this order is the order the values arrive in.
+//
+// The Gherkin argument is read by PRESENCE: an empty docstring is "" and still earns a
+// parameter, because the step really does receive it.
+const parametersFor = (argumentsFound, stepArgument) => {
+  const captures = argumentsFound.map((each, index) => `arg${index}`);
+
+  if (stepArgument == null) return captures;
+
+  return captures.concat([
+    typeof stepArgument === "string" ? "docString" : "table",
+  ]);
+};
+
+const matcherFor = (stepText, argumentsFound) =>
+  argumentsFound.length > 0
+    ? matcherRegexFor(stepText, argumentsFound)
+    : `"${escapedForDoubleQuotes(stepText)}"`;
+
+// The starter code for steps of ONE shape: the verb for their keyword, a matcher built from the
+// first step's text with each capture wide enough for every step's value at that position, and
+// a step function with the parameters they imply and an empty body to fill in. The Gherkin
+// argument parameter is named for the first step that carries one.
+const starterCodeForShape = (steps) => {
+  const valuesByStep = steps.map((step) => argumentsInStepText(step.stepText));
+  const argumentsFound = valuesByStep[0].map((argument, position) => ({
+    start: argument.start,
+    end: argument.end,
+    capture: captureFor(
+      argument.kind,
+      valuesByStep.map((values) => values[position].value),
+    ),
+  }));
+  const stepWithArgument = steps.find((step) => step.stepArgument != null);
+  const parameters = parametersFor(
+    argumentsFound,
+    stepWithArgument ? stepWithArgument.stepArgument : null,
+  );
+
+  return `${VERB_FOR_BUCKET[steps[0].keyword]}(${matcherFor(
+    steps[0].stepText,
+    argumentsFound,
+  )}, (${parameters.join(", ")}) => {});`;
+};
+
+// The unbound steps of one feature, each named once (a Background step is unbound in every
+// scenario), grouped by shape in order of first appearance. Every row of an outline, and any
+// two steps that differ only in their values, share a shape. The consumer writes ONE definition
+// for them: two definitions would be refused when pasted, as a duplicate when their matchers
+// are equal, and as ambiguous when one is wider ("(\d+)" beside a decimal capture both match
+// "1"). A step with a table and the same step without one share a shape too; parameters do not
+// make two definitions distinct.
+const stepsByShape = (unboundSteps) => {
+  const groups = new Map();
+  const named = new Set();
+  unboundSteps.forEach((step) => {
+    const identity = `${step.keyword}\u0000${step.stepText}`;
+    if (named.has(identity)) return;
+    named.add(identity);
+    const shape = shapeOf(step);
+    if (!groups.has(shape)) groups.set(shape, []);
+    groups.get(shape).push(step);
+  });
+  return [...groups.values()];
+};
+
+// The refusal for every unbound step of one feature, numbered, in feature order.
+//
+// Refusing on the first unbound step instead bills the consumer one full re-run per missing
+// definition, and the message would be telling the truth about a fraction of the state.
+//
+// The phrase "No step definition matches:" followed by the step text in double quotes opens
+// every entry and appears nowhere else in the message. That is a designed constraint, not a
+// turn of phrase: it is what the existing undefined-step guard and two seam regressions match
+// on, and what lets a reader count the entries. One entry is one definition to write; the
+// other steps it binds follow on lines of their own, so every unbound step is still named, and
+// the header counts steps, not entries.
+const unmatchedStepRefusal = (featureTitle, unboundSteps) => {
+  const shapes = stepsByShape(unboundSteps);
+  const stepCount = shapes.reduce((count, steps) => count + steps.length, 0);
+  const entries = shapes.map(
+    (steps, index) =>
+      `  ${index + 1}. No step definition matches: "${steps[0].stepText}"\n` +
+      steps
+        .slice(1)
+        .map((step) => `     nor: "${step.stepText}"\n`)
+        .join("") +
+      `     ${starterCodeForShape(steps)}`,
+  );
+
+  return new Error(
+    `Fusion found ${stepCount} step${
+      stepCount === 1 ? "" : "s"
+    } in the feature "${featureTitle}" that no registered step definition matches.\n\n` +
+      `WHY:  Fusion runs each step through the definition registered for that step's own\n` +
+      `      Gherkin keyword, so a step with no definition has nothing to run and the\n` +
+      `      scenario holding it cannot be reported honestly.\n` +
+      `HOW:  register a definition for each entry below. The starter code under each one is\n` +
+      `      the verb, the matcher and the parameters its steps need, and one definition\n` +
+      `      binds every step its entry names. Or pass\n` +
+      `      errors: { stepsMustMatchFeatureFile: false } to have the scenarios holding them\n` +
+      `      reported as skipped tests instead.\n\n` +
+      `${entries.join("\n\n")}\n`,
+  );
+};
+
+// The starter code for ONE step, as the refusal would suggest it on its own. Kept as an export
+// for probes that drive the generator directly (plan, 2026-10-08 refactor: "keep the
+// starterCodeFor export").
+const starterCodeFor = (step) => starterCodeForShape([step]);
+
+export { starterCodeFor };
+export { unmatchedStepRefusal };

package/src/configuration.js

@@ -0,0 +1,147 @@
+// The option defaults, the global layer and the merge, owned here rather than by the removed
+// intermediary, whose configuration module did exactly this (configuration.js:26-36: the
+// defaults, the global object, then the per-call options, with `errors: true` expanded).
+//
+// Three layers, lowest first: the defaults, the global a consumer sets once through
+// setFusionConfiguration, and the options passed to one Fusion() call. The per-call layer wins,
+// which is the precedence the documentation has always stated.
+//
+// WHERE THE GLOBAL LAYER LIVES, AND WHY IT IS PER FILE. In src/shared-state.js, on globalThis,
+// so that every copy of the dual package in a test file sees it: a setup script may require()
+// the package while the steps import it. Jest gives each test file its own global and runs
+// setupFiles inside it, so the global a setup script sets is visible to that file's Fusion
+// calls and cannot reach another file. It is per-file configuration, which is the whole reason
+// this option can be set in one place.
+
+import { describeValue } from "./value-description.js";
+import { shared, replaceShared } from "./shared-state.js";
+
+// Fusion's three validation keys. stepsMustMatchFeatureFile decides between the
+// unmatched-step refusal and a visible skipped test; scenariosMustMatchFeatureFile gates the
+// duplicate declared-title check; allowScenariosNotInFeatureFile is accepted and vestigial,
+// because Fusion generates the scenario definitions from the feature file itself and so has
+// no scenario outside it to allow.
+const everyValidation = (on) => ({
+  stepsMustMatchFeatureFile: on,
+  scenariosMustMatchFeatureFile: on,
+  allowScenariosNotInFeatureFile: on,
+});
+
+// Validation is ON by default: an unmatched step fails loudly, and a duplicated declared
+// title is refused, unless the consumer asks otherwise.
+const defaultOptions = () => ({
+  errors: everyValidation(true),
+  tagFilter: undefined,
+  scenarioNameTemplate: undefined,
+});
+
+// An option whose value is `undefined` is NOT SET, at every layer and inside `errors`, so it
+// never overrides the layer below. Forwarding an unset environment variable,
+// `{ tagFilter: process.env.TAGS }`, is the ordinary way to write one, and a key-wise
+// Object.assign would otherwise copy that `undefined` over a global the consumer set on purpose
+// (finding F4 of the PR #16 review). `errors: undefined` already meant "no change"; this makes
+// every key agree with it.
+const keysThatAreSet = (options) =>
+  Object.fromEntries(
+    Object.entries(options).filter(([, value]) => value !== undefined),
+  );
+
+// What ONE layer's `errors` contributes, in the three forms a consumer may write it:
+//
+//   true        -> every key on. An explicit reset of all three.
+//   false       -> every key off. The same shorthand in the other direction.
+//   { one key } -> ONLY that key. Naming one validation says nothing about the others, so the
+//                  keys it did not mention keep whatever the layer below set.
+//
+// Returning only the named keys is what makes the layers compose. Expanding a partial object
+// over all-true here instead would let a per-call object naming one key silently switch a
+// DIFFERENT key back on, undoing a global the consumer set deliberately.
+const errorsNamedBy = (errors) => {
+  if (errors === true) return everyValidation(true);
+  if (errors === false) return everyValidation(false);
+  // Anything else but an object, null or undefined is refused: `errors: 0` was read as "no
+  // change", leaving every validation on while the consumer meant off (fresh fuzz of PR #16).
+  if (errors !== undefined && errors !== null && !isAnOptionObject(errors))
+    throw new Error(
+      `The errors option must be true, false or an object, but was given ${describeValue(
+        errors,
+      )}.\n\n` +
+        `HOW:  pass errors: false to switch every validation off, or an object naming the ones\n` +
+        `      to change, for example errors: { stepsMustMatchFeatureFile: false }.`,
+    );
+
+  return keysThatAreSet(errors || {});
+};
+
+// The middle layer. Replaced wholesale by each setFusionConfiguration call, never merged into:
+// replace is what the previous setter did, and it is the only semantics under which a consumer
+// can CLEAR a global they set earlier.
+//
+// Kept in the shared store (src/shared-state.js), not in a module variable: a global set
+// through one copy of the dual package was otherwise lost to the other (measured: the mixed
+// consumer in test/specs/baseline/assert-packaged-consumer.js).
+const globalOptions = () => shared("globalOptions", () => ({}));
+
+const isAnOptionObject = (candidate) =>
+  typeof candidate === "object" &&
+  candidate !== null &&
+  !Array.isArray(candidate);
+
+const refuseNonOptionObject = (whatItWasGiven) =>
+  new Error(
+    `setFusionConfiguration needs an options object.\n\n` +
+      `WHAT: it was given ${describeValue(whatItWasGiven)}.\n` +
+      `WHY:  the argument is merged under every Fusion() call of this test file, so anything\n` +
+      `      that is not an options object leaves the whole file silently unconfigured, and\n` +
+      `      the mistake then looks like a bug in the feature files.\n` +
+      `HOW:  pass the same object a Fusion() call accepts, for example\n` +
+      `      setFusionConfiguration({ tagFilter: "@smoke and not @slow" }). The accepted keys\n` +
+      `      are errors, tagFilter, scenarioNameTemplate and loadRelativePath; an unknown key\n` +
+      `      is ignored, exactly as it is per call.`,
+  );
+
+// Refused here, at the call, because that is the one place and time the consumer can act: a
+// setup script runs before any step definition file loads.
+const setFusionConfiguration = (optionsForEveryFusionCall) => {
+  if (!isAnOptionObject(optionsForEveryFusionCall))
+    throw refuseNonOptionObject(optionsForEveryFusionCall);
+
+  // Copied, so the stored global is ours: a consumer who later mutates the object they passed
+  // does not silently reconfigure the rest of their file.
+  replaceShared("globalOptions", Object.assign({}, optionsForEveryFusionCall));
+};
+
+// `errors` is merged key-wise ACROSS the layers, not layer-over-layer as a whole value, which
+// is the same promise value 2 made within one layer: naming one validation says nothing about
+// the others, whichever layer named it. A top-level Object.assign would instead replace a
+// global errors object wholesale with a per-call one, losing a key the consumer only mentioned
+// once.
+//
+// The result always carries all three keys, because the fold starts from them. So no reader
+// downstream has to know that `errors` has three spellings or three layers.
+const errorsAcross = (layers) =>
+  layers.reduce(
+    (merged, layer) =>
+      Object.prototype.hasOwnProperty.call(layer, "errors")
+        ? Object.assign(merged, errorsNamedBy(layer.errors))
+        : merged,
+    everyValidation(true),
+  );
+
+const mergeFusionOptions = (perCallOptions) => {
+  const perCall = perCallOptions || {};
+  // Lowest to highest, and a fresh object every call: the per-call options are never written
+  // into the global, so one file's option cannot configure another file of the same run.
+  const merged = Object.assign(
+    defaultOptions(),
+    keysThatAreSet(globalOptions()),
+    keysThatAreSet(perCall),
+  );
+
+  return Object.assign(merged, {
+    errors: errorsAcross([globalOptions(), perCall]),
+  });
+};
+
+export { setFusionConfiguration };
+export { mergeFusionOptions };