pi-dev-team 0.2.0

package/scripts/gherkin_stub_gate.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""gherkin_stub_gate.py — fail closed while bdd-runner step definitions are
+still pending (issue #1391).
+
+`bdd-runner` mode wires a real native Gherkin parser (cucumber-js, Reqnroll,
+cucumber-jvm, godog) and `gherkin-derive/SKILL.md` Step 4 generates **pending**
+step-definition stubs so the suite compiles and fails intentionally (red
+before green) — that scaffolding step is correct on its own. Choosing
+`bdd-runner` mode is a decision to end up with fully executing, Gherkin-bound
+tests, not a decision to scaffold placeholders that may or may not get
+finished. This script is the completion gate: it greps the step-definition
+files for the per-language pending marker and fails, listing every remaining
+file:line, when any stub was never filled in.
+
+Per-language pending markers (`gherkin-derive/SKILL.md` Step 4's table,
+reused here — not re-derived). The extension -> (language label, markers)
+table itself lives in `lib/_bdd_markers.py` (issue #1421 bug 5) — shared with
+`lib/stub_extractors/__init__.py`, which needs the same mapping and used to
+reach up into this module's `_MARKERS_BY_EXT` via a `sys.path` layer
+inversion to get it. C# carries two markers: `PendingStepException`
+is Reqnroll's current auto-suggested stub, and `StepIsPending()` is its
+deprecated-since-3.3.4 predecessor — still recognized so an older or
+not-yet-regenerated stub isn't a false negative
+(`knowledge/test-stack-profiles/bdd-frameworks.md`):
+
+| Language | Framework                          | Pending marker(s)                          |
+|----------|-------------------------------------|----------------------------------------------|
+| JS/TS    | Cucumber.js                         | `this.pending()`                             |
+| Java     | Cucumber-JVM                        | `PendingException`                           |
+| C#       | Reqnroll (xUnit/NUnit/MSTest)       | `PendingStepException`, `StepIsPending()`    |
+| Go       | Godog                                | `godog.ErrPending`                           |
+
+The language for a given step-definition file is resolved from its
+extension, matched **case-insensitively** — `.js`/`.ts`/`.mjs`/`.cjs` →
+JS/TS, `.java` → Java, `.cs` → C#, `.go` → Go. Files with an unrecognized
+extension are skipped (not every file under a step-definitions directory is
+necessarily a step-definition file). Vendored/generated trees
+(`.git`, `node_modules`, `vendor`, `dist`, `build`, and virtualenv
+directories) are pruned during the scan — the same exclusion set
+`detect_bdd_convention.py` uses — so a stray dependency tree under a scanned
+directory is never walked or grepped — via the shared `_vendored_tree.py`
+helper (issue #1420), also used by `detect_bdd_convention.py` and
+`gherkin_failure_path_gate.py`.
+
+Stdlib-only. (ADR 0014/0015).
+
+Usage:
+    python3 gherkin_stub_gate.py --dir <step-definitions-dir> [--dir <dir> ...]
+    python3 gherkin_stub_gate.py --dir features/test-improve/my-slug --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE / "lib"))
+
+from _bdd_markers import MARKERS_BY_EXT as _MARKERS_BY_EXT
+from _gherkin_text import safe_for_terminal as _safe_for_terminal
+from _vendored_tree import find_files as _find_files
+
+
+def find_step_definition_files(directories: list[Path]) -> list[Path]:
+    """Return every file under `directories` whose extension is a known
+    step-definition language (matched case-insensitively), pruning vendored
+    trees, sorted for deterministic output."""
+    return _find_files(directories, lambda path: path.suffix.lower() in _MARKERS_BY_EXT)
+
+
+def _matching_marker(line: str, markers: tuple) -> str | None:
+    """Return the first marker in `markers` that occurs in `line`, or
+    `None` — the innermost scan of `find_pending_stubs`, extracted so that
+    function stays at 2 levels of nesting instead of 4."""
+    return next((marker for marker in markers if marker in line), None)
+
+
+def find_pending_stubs(files: list[Path]) -> list[dict]:
+    """Return one entry per pending-marker occurrence: {file, line, language, text}."""
+    pending: list[dict] = []
+    for path in files:
+        language, markers = _MARKERS_BY_EXT[path.suffix.lower()]
+        text = path.read_text(encoding="utf-8", errors="replace")
+        for line_no, line in enumerate(text.splitlines(), start=1):
+            marker = _matching_marker(line, markers)
+            if marker is not None:
+                pending.append(
+                    {
+                        "file": str(path),
+                        "line": line_no,
+                        "language": language,
+                        "marker": marker,
+                        "text": line.strip(),
+                    }
+                )
+    return pending
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="gherkin_stub_gate.py",
+        description=(
+            "Fail closed when any bdd-runner step-definition file still "
+            "carries a pending-stub marker."
+        ),
+    )
+    parser.add_argument(
+        "--dir",
+        dest="dirs",
+        action="append",
+        type=Path,
+        required=True,
+        help="Step-definitions directory to scan (repeatable).",
+    )
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args(argv)
+
+    files = find_step_definition_files(args.dirs)
+
+    if not files:
+        # Mirrors gherkin_failure_path_gate.py's identical fix: a --dir that
+        # doesn't exist (or resolves to zero step-definition files) used to
+        # silently report "OK: 0 ... scanned, no pending stubs remain" — an
+        # affirmative all-clear for zero evidence. --dir is composed by
+        # gherkin-derive from a probe of the target repo, not always typed
+        # by a human, so a gate that scanned nothing must say so distinctly.
+        dirs_display = ", ".join(str(d) for d in args.dirs)
+        message = f"no step-definition files found under {dirs_display} — gate did not run"
+        if args.json:
+            print(json.dumps({"scanned": [], "pending": [], "warning": message}, indent=2))
+        else:
+            # --dir is composed by gherkin-derive from a probe of the target
+            # repo, not always typed by a human — the same untrusted-path
+            # class as a scanned file's path, sanitized the same way.
+            print(
+                f"WARN: no step-definition files found under "
+                f"{_safe_for_terminal(dirs_display)} — gate did not run"
+            )
+        return 2
+
+    pending = find_pending_stubs(files)
+
+    if args.json:
+        print(json.dumps({"scanned": [str(f) for f in files], "pending": pending}, indent=2))
+        return 1 if pending else 0
+
+    if pending:
+        print(f"FAIL: {len(pending)} pending step definition(s) — bdd-runner mode is not done:")
+        for entry in pending:
+            path = _safe_for_terminal(entry["file"])
+            text = _safe_for_terminal(entry["text"])
+            print(f"  - {path}:{entry['line']} ({entry['language']}) — {text}")
+        return 1
+
+    print(f"OK: {len(files)} step-definition file(s) scanned, no pending stubs remain.")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/gherkin_stub_merge.py

@@ -0,0 +1,479 @@
+#!/usr/bin/env python3
+"""gherkin_stub_merge.py — merge newly-derived step-definition stubs into an
+existing step-definition file without clobbering an already-implemented step
+(issue #1421).
+
+`gherkin-derive`'s `bdd-runner` mode used to regenerate step-definition stubs
+unconditionally on every run, silently discarding any step a human (or
+`/build`) had already implemented. This module gives it a safe alternative,
+mirroring `gherkin_feature_merge.py`'s read-before-write/merge discipline:
+parse the existing file via `scripts/lib/stub_extractors` (one
+lexically-aware, brace-balance-bounded extractor per language), skip any
+candidate whose step-pattern text already exists there — regardless of
+whether that existing binding is pending or already implemented — and append
+only genuinely-new candidates as pending stubs after the last existing
+binding. An existing binding's body is never rewritten or reordered.
+
+`stub_extractors.parse_existing_steps` refuses to guess a span when a file's
+brackets don't lexically balance, or a marker has no attached, boundable
+body — reported as one of two structural-error sentinels
+(`unbalanced-braces`, `dangling-annotation`, re-exported here), plus
+`unsafe-path` at this script's own level for a `--existing` path containing a
+`..` component, `malformed-candidates` when the `--candidates` scratch
+file itself can't be bounded, `unreadable-candidates` when that file is
+missing or can't be read at all, and `unsupported-extension` for an `--ext`
+naming no known step-definition language. Every error leaves the existing
+file completely untouched.
+
+Stdlib-only. (ADR 0014/0015).
+
+Usage:
+    python3 gherkin_stub_merge.py merge --existing <path> --candidates <path> \
+        --ext <.js|.ts|.mjs|.cjs|.java|.cs|.go> [--dry-run] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE / "lib"))
+
+from _gherkin_text import safe_for_terminal as _safe_for_terminal
+from stub_extractors import (
+    ERROR_DANGLING_ANNOTATION,  # noqa: F401
+    ERROR_UNBALANCED_BRACES,  # noqa: F401
+    parse_existing_steps,
+)
+from stub_extractors import go as _go_extractor
+
+# This script's own error sentinels — distinct from the two structural
+# sentinels stub_extractors returns (re-exported above), the same split
+# gherkin_feature_merge.py makes between its own ERROR_UNSAFE_PATH/
+# ERROR_MALFORMED_CANDIDATES and the parser's ERROR_FEATURE_NOT_FOUND/
+# ERROR_MALFORMED_FEATURE_BLOCK.
+ERROR_UNSAFE_PATH = "unsafe-path"
+ERROR_MALFORMED_CANDIDATES = "malformed-candidates"
+# issue #1421 bug 6: a missing/unreadable --candidates path and an
+# unrecognized --ext (argparse has no `choices=` for it) used to escape
+# _cmd_merge as raw, uncaught Python exceptions instead of one of these
+# sentinels through the same exit-2 --json contract every other structural
+# problem uses.
+ERROR_UNREADABLE_CANDIDATES = "unreadable-candidates"
+ERROR_UNSUPPORTED_EXTENSION = "unsupported-extension"
+
+
+@dataclass
+class StepCandidate:
+    """One newly-derived step-definition stub to merge in — pre-composed,
+    language-appropriate source text (the caller, `gherkin-derive/SKILL.md`
+    Step 4, is responsible for its exact shape), plus the step-pattern text
+    used to detect whether it already exists.
+
+    `decl_text` is Go-only (`None` for JS/TS, Java, C#): Go's registration
+    call and the top-level function it references are non-adjacent source
+    regions, so `text` (the registration call alone) is insufficient on its
+    own — `decl_text` carries the function declaration that must be spliced
+    in at a different, top-level-safe position (see `merge_steps`).
+    `parse_candidate_steps` populates it automatically from a `--candidates`
+    scratch file; a caller building `StepCandidate` by hand for Go must
+    supply it explicitly or the merged file will fail to compile."""
+
+    pattern: str
+    text: str
+    decl_text: str | None = None
+
+
+@dataclass
+class MergeResult:
+    text: str
+    added_patterns: list
+    skipped_duplicate_patterns: list
+    error: str | None
+
+
+def _dedupe_candidates(candidates: list) -> tuple:
+    """Return `(deduped_candidates, self_duplicate_patterns)`. Two candidates
+    sharing a trimmed pattern would otherwise both be appended, mirroring the
+    identical fix `gherkin_feature_merge._dedupe_candidate_units` applies to
+    scenario titles."""
+    seen = set()
+    deduped = []
+    duplicates = []
+    for candidate in candidates:
+        key = candidate.pattern.strip()
+        if key in seen:
+            duplicates.append(candidate.pattern)
+            continue
+        seen.add(key)
+        deduped.append(candidate)
+    return deduped, duplicates
+
+
+def _insert_at(text: str, idx: int, insertion: str) -> str:
+    """Splice `insertion` into `text` at char offset `idx`, restoring a
+    missing line terminator right at the splice point (matching
+    `gherkin_feature_merge.merge_scenarios`'s identical guard) so neither
+    side's content is ever rewritten — only the separator whose absence
+    would otherwise fuse two lines together. No-op when `insertion` is empty."""
+    if not insertion:
+        return text
+    prefix = text[:idx]
+    suffix = text[idx:]
+    if prefix and not prefix.endswith("\n"):
+        prefix += "\n"
+    if not insertion.endswith("\n"):
+        insertion += "\n"
+    return prefix + insertion + suffix
+
+
+def _existing_bindings_use_blank_line_separator(existing_text: str, bindings: list) -> bool:
+    """Infer whether this file's existing step bindings are separated by a
+    blank line, from the joins between consecutive existing bindings —
+    excluding the boundary after the very last binding, which sits at the
+    file's end and may have nothing after it to separate from for reasons
+    unrelated to the file's own convention. A binding's `.end` (from
+    `extend_to_line_end`) stops at its own closing line, so the gap between
+    one binding's end and the next binding's start is exactly whatever sits
+    between them — empty when the file has no blank line there, the blank
+    line's own line terminator when it does, or just the next binding's
+    leading indentation when the language wraps bindings in an indented
+    block (Java, C#, a class-wrapped JS/TS style) and there is no blank
+    line. That last case is whitespace-only but has no newline in it —
+    `gap.strip() == ""` alone can't tell it apart from a genuine blank
+    line, so a join is only counted as separated when the gap is BOTH
+    whitespace-only AND actually contains a newline (a blank line always
+    has one; bare indentation never does). Defaults to `True` when there
+    are fewer than two bindings to compare, matching the
+    blank-line-between-methods style most existing step-definition files
+    already use."""
+    comparable = bindings[:-1]
+    if not comparable:
+        return True
+    separated = sum(
+        1
+        for i, binding in enumerate(comparable)
+        if (gap := existing_text[binding.end : bindings[i + 1].start])
+        and gap.strip() == ""
+        and "\n" in gap
+    )
+    return separated * 2 >= len(comparable)
+
+
+def _splice_single_point(existing_text: str, bindings: list, new_candidates: list) -> str:
+    """The default splice: append every new candidate's text as one block
+    right after the last existing binding (or at file end with no existing
+    bindings) — correct whenever a binding's `text` already contains
+    everything the language needs (JS/TS, Java, C#).
+
+    The last existing binding sits at the splice point with nothing after
+    it, so its own text alone can't say whether this file puts a blank
+    line between step definitions — infer that from the *other* existing
+    joins instead (`_existing_bindings_use_blank_line_separator`) and
+    reproduce it here, so a splice landing flush against the last existing
+    method's closing brace doesn't silently drop the blank line every
+    other method boundary in the file already has."""
+    insertion_point = bindings[-1].end if bindings else len(existing_text)
+    insertion = "".join(candidate.text for candidate in new_candidates)
+    if bindings and insertion and _existing_bindings_use_blank_line_separator(existing_text, bindings):
+        insertion = "\n" + insertion
+    return _insert_at(existing_text, insertion_point, insertion)
+
+
+def _splice_go_two_part(existing_text: str, bindings: list, new_candidates: list) -> str:
+    """Go-only splice: a new step needs its function declaration inserted
+    at the top level (safe anywhere alongside the other existing step
+    functions — Go has no forward-declaration ordering requirement) and its
+    `sc.Step(...)` registration inserted separately, inside the existing
+    registration function (right after the last existing registration,
+    `bindings[-1].end` — unchanged from the single-point case). Applying
+    the two splices from the higher offset down means neither invalidates
+    the other's not-yet-applied position.
+
+    When `bindings` is empty — an existing, non-empty `.go` file whose
+    `InitializeScenario` has no `sc.Step(...)` calls yet (issue #1421 bug 1)
+    — there is no existing binding to anchor against. Anchor the call just
+    before `InitializeScenario`'s own closing brace (so it lands inside a
+    function body, not as an invalid top-level statement) and the
+    declaration at that function's own top-level start. Falls back to
+    appending both at file end (declaration first) only if
+    `InitializeScenario` itself can't be found or bounded — a shape this
+    module's own tests never produce, but still handled rather than raising."""
+    decl_text = "".join(c.decl_text or "" for c in new_candidates)
+    call_text = "".join(c.text for c in new_candidates)
+
+    if bindings:
+        decl_starts = [b.decl_start for b in bindings if b.decl_start is not None]
+        call_anchor = bindings[-1].end
+        decl_anchor = min(decl_starts) if decl_starts else call_anchor
+    else:
+        registration_body = _go_extractor.find_scenario_initializer_body(existing_text)
+        if registration_body is not None and registration_body.error is None:
+            call_anchor = registration_body.end - 1  # just before the closing '}'
+            decl_anchor = registration_body.decl_start
+        else:
+            call_anchor = decl_anchor = len(existing_text)
+
+    if call_anchor >= decl_anchor:
+        text = _insert_at(existing_text, call_anchor, call_text)
+        text = _insert_at(text, decl_anchor, decl_text)
+    else:
+        text = _insert_at(existing_text, decl_anchor, decl_text)
+        text = _insert_at(text, call_anchor, call_text)
+    return text
+
+
+def merge_steps(existing_text: str, ext: str, candidate_steps: list) -> MergeResult:
+    """Append-only merge of `candidate_steps` into `existing_text`.
+
+    Relays `parse_existing_steps`'s structural-error sentinel unchanged when
+    the existing file can't be bounded — this function never re-derives or
+    guesses the cause. When `existing_text` is empty, the candidates' own
+    text is the entire file (no skeleton is synthesized — that is the
+    caller's concern, mirroring `merge_scenarios`'s identical empty-file
+    branch; for Go specifically this means a caller composing a genuinely
+    new file must supply a complete registration-function wrapper in one
+    candidate's `text`/`decl_text` — this function only concatenates, it
+    never synthesizes one)."""
+    candidate_steps, self_duplicate_patterns = _dedupe_candidates(candidate_steps)
+
+    if not existing_text:
+        decl_body = "".join(candidate.decl_text or "" for candidate in candidate_steps)
+        call_body = "".join(candidate.text for candidate in candidate_steps)
+        return MergeResult(
+            text=decl_body + call_body,
+            added_patterns=[candidate.pattern for candidate in candidate_steps],
+            skipped_duplicate_patterns=self_duplicate_patterns,
+            error=None,
+        )
+
+    result = parse_existing_steps(existing_text, ext)
+    if result.error is not None:
+        return MergeResult(
+            text=existing_text,
+            added_patterns=[],
+            skipped_duplicate_patterns=[],
+            error=result.error,
+        )
+
+    existing_patterns = {binding.pattern.strip() for binding in result.bindings}
+    new_candidates = [c for c in candidate_steps if c.pattern.strip() not in existing_patterns]
+    skipped = self_duplicate_patterns + [
+        c.pattern for c in candidate_steps if c.pattern.strip() in existing_patterns
+    ]
+
+    if not new_candidates:
+        return MergeResult(
+            text=existing_text, added_patterns=[], skipped_duplicate_patterns=skipped, error=None
+        )
+
+    is_go = ext.lower() == ".go"
+    if is_go:
+        merged_text = _splice_go_two_part(existing_text, result.bindings, new_candidates)
+    else:
+        merged_text = _splice_single_point(existing_text, result.bindings, new_candidates)
+
+    return MergeResult(
+        text=merged_text,
+        added_patterns=[c.pattern for c in new_candidates],
+        skipped_duplicate_patterns=skipped,
+        error=None,
+    )
+
+
+def parse_candidate_steps(text: str, ext: str) -> tuple:
+    """Parse a `--candidates` scratch file's step-definition text (the same
+    syntax as an existing file's bindings — a candidates file is just
+    syntactically-valid step-definition fragments, no separate schema)
+    into `(candidates, error)`. Mirrors
+    `gherkin_feature_merge.parse_candidate_units`'s reuse of the same parser
+    used for existing content."""
+    result = parse_existing_steps(text, ext)
+    if result.error is not None:
+        return [], result.error
+    candidates = [
+        StepCandidate(pattern=b.pattern, text=b.text, decl_text=b.decl_text) for b in result.bindings
+    ]
+    return candidates, None
+
+
+def _write_error(message: str) -> None:
+    sys.stderr.write(message + "\n")
+
+
+def _reject_path_traversal(raw: str) -> str | None:
+    """Return an error message if `raw` contains a `..` path component, else
+    `None`. `--existing` is composed by `gherkin-derive/SKILL.md` Step 4 from
+    a surface name derived from the target repository's own content, not
+    always typed by a human — mirrors
+    `gherkin_feature_merge._reject_path_traversal` exactly."""
+    if ".." in Path(raw).parts:
+        return f"--existing {raw!r} must not contain a '..' path component"
+    return None
+
+
+def _merge_payload(written: bool, added=(), skipped=(), error=None) -> dict:
+    """The one JSON shape every `merge` response uses, named once so a future
+    field addition touches this single place rather than every call site
+    rebuilding the dict by hand — mirrors `gherkin_feature_merge._merge_payload`."""
+    return {
+        "written": written,
+        "added_patterns": list(added),
+        "skipped_duplicate_patterns": list(skipped),
+        "error": error,
+    }
+
+
+def _write_atomic(path: Path, text: str) -> None:
+    """Write `text` to `path` via a same-directory temp file + os.replace, so
+    a crash or kill mid-write can never leave a truncated/corrupted
+    step-definition file — identical pattern to
+    `gherkin_feature_merge._write_atomic`."""
+    fd, tmp_name = tempfile.mkstemp(dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as tmp_file:
+            tmp_file.write(text)
+        os.replace(tmp_name, path)
+    except BaseException:
+        Path(tmp_name).unlink(missing_ok=True)
+        raise
+
+
+def _cmd_merge(args: argparse.Namespace) -> int:
+    # Known limitation (concurrency-review, issue #1421 consistency with
+    # gherkin_feature_merge.py): read-then-write here is still a TOCTOU race
+    # if two `merge` invocations ever target the same --existing path
+    # concurrently — whichever writes last silently wins (the atomic write
+    # below only rules out a truncated file, not a lost update between two
+    # racing invocations). Not fixed: gherkin-derive's own design invokes
+    # this once per surface, sequentially, never in parallel against the
+    # same file (see gherkin-derive/SKILL.md Step 4), so there is no known
+    # live trigger; a cross-platform lock (fcntl vs. msvcrt) would close
+    # this remaining gap but is a design call for a human to make, not a
+    # mechanical fix — deliberately left to a human decision rather than
+    # guessed at here.
+    path_error = _reject_path_traversal(args.existing)
+    if path_error is not None:
+        if args.json:
+            print(json.dumps(_merge_payload(written=False, error=ERROR_UNSAFE_PATH)))
+        else:
+            _write_error(f"gherkin_stub_merge: {path_error} — no steps merged")
+        return 2
+
+    existing_path = Path(args.existing)
+    existing_text = existing_path.read_text(encoding="utf-8") if existing_path.is_file() else ""
+
+    try:
+        candidates_text = Path(args.candidates).read_text(encoding="utf-8")
+    except OSError as exc:
+        # Missing/unreadable --candidates (not found, a directory, denied
+        # permission, bad encoding, ...) used to escape as a raw traceback —
+        # issue #1421 bug 6.
+        if args.json:
+            print(json.dumps(_merge_payload(written=False, error=ERROR_UNREADABLE_CANDIDATES)))
+        else:
+            _write_error(
+                f"gherkin_stub_merge: --candidates {_safe_for_terminal(args.candidates)} "
+                f"could not be read ({exc}) — no steps merged"
+            )
+        return 2
+
+    try:
+        candidate_steps, candidates_error = parse_candidate_steps(candidates_text, args.ext)
+    except ValueError:
+        # An --ext with no known step-definition language (argparse has no
+        # `choices=` for it) used to escape parse_existing_steps's
+        # ValueError as a raw traceback — issue #1421 bug 6.
+        if args.json:
+            print(json.dumps(_merge_payload(written=False, error=ERROR_UNSUPPORTED_EXTENSION)))
+        else:
+            _write_error(
+                f"gherkin_stub_merge: --ext {args.ext!r} is not a supported "
+                "step-definition extension — no steps merged"
+            )
+        return 2
+
+    if candidates_error is not None:
+        if args.json:
+            print(json.dumps(_merge_payload(written=False, error=ERROR_MALFORMED_CANDIDATES)))
+        else:
+            _write_error(
+                f"gherkin_stub_merge: candidates file {_safe_for_terminal(args.candidates)} "
+                f"is malformed (error={candidates_error}) — no steps merged, existing file "
+                f"left untouched"
+            )
+        return 2
+
+    result = merge_steps(existing_text, args.ext, candidate_steps)
+
+    if result.error is not None:
+        if args.json:
+            print(json.dumps(_merge_payload(written=False, error=result.error)))
+        else:
+            _write_error(
+                f"gherkin_stub_merge: {_safe_for_terminal(args.existing)} structure could not "
+                f"be parsed (error={result.error}) — no steps merged, existing file left "
+                f"untouched"
+            )
+        return 2
+
+    if args.dry_run:
+        if args.json:
+            print(
+                json.dumps(
+                    _merge_payload(
+                        written=False,
+                        added=result.added_patterns,
+                        skipped=result.skipped_duplicate_patterns,
+                    )
+                )
+            )
+        else:
+            sys.stdout.write(result.text)
+        return 0
+
+    existing_path.parent.mkdir(parents=True, exist_ok=True)
+    _write_atomic(existing_path, result.text)
+
+    if args.json:
+        print(
+            json.dumps(
+                _merge_payload(
+                    written=True,
+                    added=result.added_patterns,
+                    skipped=result.skipped_duplicate_patterns,
+                )
+            )
+        )
+    else:
+        print(
+            f"OK: merged {len(result.added_patterns)} new step(s) into "
+            f"{_safe_for_terminal(args.existing)}"
+        )
+    return 0
+
+
+def main(argv: list | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="gherkin_stub_merge.py")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    merge_parser = sub.add_parser("merge")
+    merge_parser.add_argument("--existing", required=True)
+    merge_parser.add_argument("--candidates", required=True)
+    merge_parser.add_argument("--ext", required=True)
+    merge_parser.add_argument("--dry-run", action="store_true")
+    merge_parser.add_argument("--json", action="store_true")
+    merge_parser.set_defaults(func=_cmd_merge)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())