nat-engine 1__py3-none-any.whl

mannf/product/ingestors/gherkin_ingestor.py

@@ -0,0 +1,967 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Gherkin/BDD Feature File ingestor plugin.
+
+Parses Gherkin ``.feature`` files (used by Cucumber, Behave, SpecFlow,
+pytest-bdd, etc.) and extracts functional test intents, mapping BDD scenarios
+to API endpoints where possible.
+
+Supported Gherkin elements
+--------------------------
+* **Feature** — Top-level container with name and optional description.
+* **Background** — Steps that run before each scenario (setup context).
+* **Scenario** — Individual test case with Given/When/Then steps.
+* **Scenario Outline** — Parameterised scenario with Examples table.
+* **Tags** — ``@tag`` annotations on Feature or Scenario.
+* **Doc Strings** — Multi-line strings delimited by ``\"\"\"``.
+* **Data Tables** — Pipe-delimited tabular data within steps.
+* **And / But** — Step continuation keywords.
+
+HTTP endpoint extraction
+------------------------
+The ingestor looks for HTTP request patterns in step text:
+
+* ``I send a (GET|POST|…) request to "/path"``
+* ``the endpoint "/path"``
+* Full URL patterns in step text or doc strings.
+
+No external dependencies are required — only stdlib (``json``, ``re``,
+``urllib.parse``).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from mannf.product.ingestors.base import IngestorPlugin
+from mannf.product.ingestors.models import (
+    IngestedEndpoint,
+    IngestedTestCase,
+    IngestorSource,
+    IngestResult,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Step keywords recognised as step starters
+_STEP_KEYWORDS: tuple[str, ...] = (
+    "Given ", "When ", "Then ", "And ", "But ",
+)
+
+# Gherkin structural keywords
+_BLOCK_KEYWORDS: tuple[str, ...] = (
+    "Feature:",
+    "Background:",
+    "Scenario Outline:",
+    "Scenario:",
+    "Examples:",
+    "Rule:",
+)
+
+# Regex: extract HTTP method + path from common BDD step phrases
+# e.g. "I send a POST request to "/users"" or "I make a GET request to '/api/v1/items'"
+_RE_HTTP_STEP = re.compile(
+    r"(?:send|make|submit)\s+(?:a\s+)?"
+    r"(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)"
+    r"\s+(?:request\s+)?(?:to\s+)?[\"']([^\"']+)[\"']",
+    re.IGNORECASE,
+)
+
+# Regex: "the endpoint "/path"" or "endpoint '/path'"
+_RE_ENDPOINT_STEP = re.compile(
+    r"\bendpoint\s+[\"']([^\"']+)[\"']",
+    re.IGNORECASE,
+)
+
+# Regex: full URL (used as a fallback)
+_RE_FULL_URL = re.compile(
+    r"https?://[^\s\"'<>]+",
+    re.IGNORECASE,
+)
+
+# Regex: status code in Then step (e.g. "the response status should be 201")
+_RE_STATUS_CODE = re.compile(
+    r"\b(1\d{2}|2\d{2}|3\d{2}|4\d{2}|5\d{2})\b",
+)
+
+# Tag priority mapping
+_TAG_PRIORITY: dict[str, float] = {
+    "critical": 1.0,
+    "security": 0.9,
+    "smoke": 0.8,
+    "regression": 0.7,
+    "sanity": 0.7,
+    "high": 0.8,
+    "medium": 0.5,
+    "low": 0.2,
+}
+
+_DEFAULT_PRIORITY: float = 0.5
+_DEFAULT_PRIORITY_LABEL: str = "medium"
+
+# ---------------------------------------------------------------------------
+# Internal parser data structures
+# ---------------------------------------------------------------------------
+
+
+class _Step:
+    """A single Gherkin step."""
+
+    __slots__ = ("keyword", "text", "doc_string", "data_table")
+
+    def __init__(
+        self,
+        keyword: str,
+        text: str,
+        doc_string: str | None = None,
+        data_table: list[list[str]] | None = None,
+    ) -> None:
+        self.keyword = keyword
+        self.text = text
+        self.doc_string = doc_string
+        self.data_table = data_table
+
+
+class _Scenario:
+    """A parsed Gherkin Scenario or Scenario Outline."""
+
+    __slots__ = ("name", "tags", "steps", "examples", "is_outline", "line_no")
+
+    def __init__(
+        self,
+        name: str,
+        tags: list[str],
+        steps: list[_Step],
+        examples: list[dict[str, str]],
+        is_outline: bool,
+        line_no: int,
+    ) -> None:
+        self.name = name
+        self.tags = tags
+        self.steps = steps
+        self.examples = examples
+        self.is_outline = is_outline
+        self.line_no = line_no
+
+
+class _Feature:
+    """A parsed Gherkin Feature."""
+
+    __slots__ = ("name", "description", "tags", "background", "scenarios")
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        tags: list[str],
+        background: list[_Step],
+        scenarios: list[_Scenario],
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.tags = tags
+        self.background = background
+        self.scenarios = scenarios
+
+
+# ---------------------------------------------------------------------------
+# Lightweight Gherkin parser
+# ---------------------------------------------------------------------------
+
+
+def _parse_gherkin(text: str) -> _Feature:
+    """Parse *text* as a Gherkin feature file.
+
+    Returns a :class:`_Feature` containing all parsed scenarios.  Raises
+    ``ValueError`` if the text does not look like a Gherkin feature.
+
+    Parameters
+    ----------
+    text:
+        Raw Gherkin content.
+
+    Returns
+    -------
+    _Feature
+        The parsed feature.
+    """
+    lines = text.splitlines()
+    idx = 0
+    n = len(lines)
+
+    def _strip(line: str) -> str:
+        return line.strip()
+
+    def _is_tag_line(line: str) -> bool:
+        s = line.strip()
+        return bool(s) and s.startswith("@")
+
+    def _collect_tags(line: str) -> list[str]:
+        """Extract tag names (without @) from a tag line."""
+        return [tok.lstrip("@") for tok in line.split() if tok.startswith("@")]
+
+    def _read_doc_string() -> str:
+        """Consume lines until the closing \"\"\", return the content."""
+        nonlocal idx
+        # idx currently points to the opening \"\"\" line
+        idx += 1
+        doc_lines: list[str] = []
+        while idx < n:
+            stripped = _strip(lines[idx])
+            if stripped == '"""' or stripped == "'''":
+                idx += 1
+                break
+            doc_lines.append(lines[idx])
+            idx += 1
+        return "\n".join(doc_lines)
+
+    def _read_data_table() -> list[list[str]]:
+        """Consume pipe-delimited table lines; return list of rows."""
+        nonlocal idx
+        rows: list[list[str]] = []
+        while idx < n:
+            stripped = _strip(lines[idx])
+            if not stripped.startswith("|"):
+                break
+            cells = [c.strip() for c in stripped.strip("|").split("|")]
+            rows.append(cells)
+            idx += 1
+        return rows
+
+    def _read_steps() -> list[_Step]:
+        """Consume step lines until a block keyword or end of section."""
+        nonlocal idx
+        steps: list[_Step] = []
+        while idx < n:
+            stripped = _strip(lines[idx])
+
+            # A block keyword ends the step list
+            if any(stripped.startswith(kw) for kw in _BLOCK_KEYWORDS):
+                break
+
+            # Tag line also ends the step list (next scenario)
+            if _is_tag_line(lines[idx]):
+                break
+
+            # Blank line — skip
+            if not stripped:
+                idx += 1
+                continue
+
+            # Step line?
+            step_keyword: str | None = None
+            step_text: str = ""
+            for kw in _STEP_KEYWORDS:
+                if stripped.startswith(kw):
+                    step_keyword = kw.rstrip()
+                    step_text = stripped[len(kw):].strip()
+                    break
+
+            if step_keyword is None:
+                # Not a step line; skip (could be continuation description)
+                idx += 1
+                continue
+
+            idx += 1
+            doc_string: str | None = None
+            data_table: list[list[str]] | None = None
+
+            # Check for doc string or data table immediately following
+            if idx < n:
+                next_stripped = _strip(lines[idx])
+                if next_stripped.startswith('"""') or next_stripped.startswith("'''"):
+                    doc_string = _read_doc_string()
+                elif next_stripped.startswith("|"):
+                    data_table = _read_data_table()
+
+            steps.append(_Step(step_keyword, step_text, doc_string, data_table))
+
+        return steps
+
+    def _read_examples() -> list[dict[str, str]]:
+        """Read an Examples table and return list of row dicts."""
+        nonlocal idx
+        # idx currently at Examples: line
+        idx += 1
+
+        # Skip optional description lines until first table line
+        while idx < n and not _strip(lines[idx]).startswith("|"):
+            idx += 1
+
+        rows = _read_data_table()
+        if not rows:
+            return []
+
+        headers = rows[0]
+        result: list[dict[str, str]] = []
+        for row in rows[1:]:
+            result.append(dict(zip(headers, row)))
+        return result
+
+    # ---------------------------------------------------------------
+    # Main parsing loop
+    # ---------------------------------------------------------------
+    feature_tags: list[str] = []
+    feature_name: str = ""
+    feature_description_lines: list[str] = []
+    background_steps: list[_Step] = []
+    scenarios: list[_Scenario] = []
+
+    # Pending tags for the next Feature/Scenario
+    pending_tags: list[str] = []
+
+    while idx < n:
+        stripped = _strip(lines[idx])
+
+        if not stripped:
+            idx += 1
+            continue
+
+        # Tag line
+        if _is_tag_line(lines[idx]):
+            pending_tags.extend(_collect_tags(stripped))
+            idx += 1
+            continue
+
+        # Feature:
+        if stripped.startswith("Feature:"):
+            feature_name = stripped[len("Feature:"):].strip()
+            feature_tags = pending_tags[:]
+            pending_tags = []
+            idx += 1
+            # Collect optional description lines until next keyword
+            while idx < n:
+                s = _strip(lines[idx])
+                if any(s.startswith(kw) for kw in _BLOCK_KEYWORDS) or _is_tag_line(lines[idx]):
+                    break
+                if s:
+                    feature_description_lines.append(s)
+                idx += 1
+            continue
+
+        # Background:
+        if stripped.startswith("Background:"):
+            idx += 1
+            background_steps = _read_steps()
+            continue
+
+        # Scenario Outline:
+        if stripped.startswith("Scenario Outline:"):
+            scenario_name = stripped[len("Scenario Outline:"):].strip()
+            scenario_tags = feature_tags + pending_tags[:]
+            pending_tags = []
+            line_no = idx + 1
+            idx += 1
+            steps = _read_steps()
+            # Check for Examples:
+            examples: list[dict[str, str]] = []
+            while idx < n:
+                s = _strip(lines[idx])
+                if s.startswith("Examples:"):
+                    examples = _read_examples()
+                elif s.startswith("Scenario") or s.startswith("Feature") or _is_tag_line(lines[idx]):
+                    break
+                elif s:
+                    idx += 1
+                else:
+                    idx += 1
+            scenarios.append(
+                _Scenario(scenario_name, scenario_tags, steps, examples, True, line_no)
+            )
+            continue
+
+        # Scenario:
+        if stripped.startswith("Scenario:"):
+            scenario_name = stripped[len("Scenario:"):].strip()
+            scenario_tags = feature_tags + pending_tags[:]
+            pending_tags = []
+            line_no = idx + 1
+            idx += 1
+            steps = _read_steps()
+            scenarios.append(
+                _Scenario(scenario_name, scenario_tags, steps, [], False, line_no)
+            )
+            continue
+
+        # Rule: (GWT 6 — treat like a comment, skip)
+        if stripped.startswith("Rule:"):
+            idx += 1
+            continue
+
+        # Anything else (orphan lines) — skip
+        idx += 1
+
+    return _Feature(
+        name=feature_name,
+        description=" ".join(feature_description_lines),
+        tags=feature_tags,
+        background=background_steps,
+        scenarios=scenarios,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Endpoint & test-case extraction helpers
+# ---------------------------------------------------------------------------
+
+
+def _extract_http_from_step(step: _Step) -> tuple[str, str] | None:
+    """Return ``(method, path)`` from a step if an HTTP pattern is found.
+
+    Checks both the step text and any embedded doc string.
+
+    Parameters
+    ----------
+    step:
+        The step to analyse.
+
+    Returns
+    -------
+    tuple[str, str] | None
+        ``(HTTP_METHOD, path_or_url)`` or ``None``.
+    """
+    search_text = step.text
+    if step.doc_string:
+        search_text += "\n" + step.doc_string
+
+    m = _RE_HTTP_STEP.search(search_text)
+    if m:
+        return m.group(1).upper(), m.group(2)
+
+    # "the endpoint '/path'" pattern — assume GET unless method found
+    m2 = _RE_ENDPOINT_STEP.search(search_text)
+    if m2:
+        return "GET", m2.group(1)
+
+    return None
+
+
+def _extract_full_url_from_step(step: _Step) -> str | None:
+    """Return the first full URL found in a step's text or doc string."""
+    search_text = step.text
+    if step.doc_string:
+        search_text += "\n" + step.doc_string
+    m = _RE_FULL_URL.search(search_text)
+    return m.group(0) if m else None
+
+
+def _extract_base_url_from_background(
+    background: list[_Step],
+) -> str | None:
+    """Scan Background steps for a base URL."""
+    for step in background:
+        url = _extract_full_url_from_step(step)
+        if url:
+            return url
+    return None
+
+
+def _extract_status_code_from_steps(steps: list[_Step]) -> int | None:
+    """Return the first HTTP status code found in Then/And steps."""
+    for step in steps:
+        kw_lower = step.keyword.lower()
+        if kw_lower in ("then", "and", "but"):
+            m = _RE_STATUS_CODE.search(step.text)
+            if m:
+                code = int(m.group(1))
+                if 100 <= code <= 599:
+                    return code
+    return None
+
+
+def _extract_request_body_from_steps(
+    steps: list[_Step],
+) -> dict | str | None:
+    """Return a parsed JSON body (or raw string) from Given/When steps with doc strings."""
+    for step in steps:
+        kw_lower = step.keyword.lower()
+        if kw_lower in ("given", "when", "and", "but") and step.doc_string:
+            raw = step.doc_string.strip()
+            try:
+                return json.loads(raw)
+            except (json.JSONDecodeError, ValueError):
+                return raw
+    return None
+
+
+def _priority_from_tags(tags: list[str]) -> tuple[float, str]:
+    """Return ``(priority_float, priority_label)`` based on scenario tags.
+
+    The highest-priority tag found wins.  Falls back to default (0.5 / medium)
+    when no recognised priority tags are present.
+
+    Parameters
+    ----------
+    tags:
+        List of tag strings (without ``@``).
+
+    Returns
+    -------
+    tuple[float, str]
+        Priority value and label.
+    """
+    best_value: float | None = None
+    best_label: str = _DEFAULT_PRIORITY_LABEL
+
+    for tag in tags:
+        tag_lower = tag.lower()
+        if tag_lower in _TAG_PRIORITY:
+            value = _TAG_PRIORITY[tag_lower]
+            if best_value is None or value > best_value:
+                best_value = value
+                best_label = tag_lower
+
+    return (best_value if best_value is not None else _DEFAULT_PRIORITY), best_label
+
+
+def _expand_outline(
+    scenario: _Scenario,
+) -> list[tuple[str, list[_Step]]]:
+    """Expand a Scenario Outline into concrete (name, steps) variants.
+
+    Each row in the Examples table produces one variant.  Placeholder tokens
+    ``<column>`` in step text and doc strings are substituted with the
+    corresponding value from the row.
+
+    Parameters
+    ----------
+    scenario:
+        The Scenario Outline to expand.
+
+    Returns
+    -------
+    list[tuple[str, list[_Step]]]
+        A list of ``(variant_name, steps)`` tuples.
+    """
+    if not scenario.examples:
+        # Outline with no examples — return the template as-is
+        return [(scenario.name, scenario.steps)]
+
+    variants: list[tuple[str, list[_Step]]] = []
+    for row in scenario.examples:
+        # Substitute placeholders in the scenario name
+        variant_name = scenario.name
+        for col, val in row.items():
+            variant_name = variant_name.replace(f"<{col}>", val)
+
+        # Deep-copy and substitute step text / doc strings
+        new_steps: list[_Step] = []
+        for step in scenario.steps:
+            new_text = step.text
+            new_doc = step.doc_string
+            new_table = deepcopy(step.data_table) if step.data_table else None
+            for col, val in row.items():
+                placeholder = f"<{col}>"
+                new_text = new_text.replace(placeholder, val)
+                if new_doc:
+                    new_doc = new_doc.replace(placeholder, val)
+                if new_table:
+                    new_table = [
+                        [cell.replace(placeholder, val) for cell in r]
+                        for r in new_table
+                    ]
+            new_steps.append(_Step(step.keyword, new_text, new_doc, new_table))
+
+        variants.append((variant_name, new_steps))
+
+    return variants
+
+
+def _normalise_path(path: str) -> str:
+    """Return just the path component of *path*, stripping any host/scheme."""
+    if path.startswith("http://") or path.startswith("https://"):
+        parsed = urlparse(path)
+        return parsed.path or "/"
+    return path if path.startswith("/") else f"/{path}"
+
+
+def _endpoint_key(method: str, path: str) -> str:
+    """Return a deduplication key for an endpoint."""
+    return f"{method.upper()}:{_normalise_path(path)}"
+
+
+# ---------------------------------------------------------------------------
+# GherkinIngestor
+# ---------------------------------------------------------------------------
+
+
+class GherkinIngestor(IngestorPlugin):
+    """Ingestor plugin for Gherkin/BDD ``.feature`` files.
+
+    Parses Gherkin feature files used by Cucumber, Behave, SpecFlow, and
+    pytest-bdd, and converts BDD scenarios into :class:`IngestedTestCase`
+    objects (and :class:`IngestedEndpoint` objects where HTTP patterns are
+    detectable in step text).
+
+    Configuration keys
+    ------------------
+    ``base_url`` : str, optional
+        Default base URL to prepend when steps contain only a path
+        (e.g. ``"/users"``).
+    ``tag_filter`` : list[str] | str, optional
+        Only ingest scenarios that carry at least one of these tags (without
+        the ``@`` prefix).  When omitted or empty, all scenarios are ingested.
+    ``extract_endpoints`` : bool, optional (default ``True``)
+        If ``False``, skip HTTP endpoint extraction entirely and only produce
+        test case objects.
+    """
+
+    name = "gherkin"
+    display_name = "Gherkin/BDD Feature"
+    description = "Parses Gherkin .feature files (Cucumber, Behave, SpecFlow, pytest-bdd)."
+    supported_extensions = [".feature"]
+    supported_formats = ["gherkin", "bdd", "cucumber", "behave"]
+
+    # ------------------------------------------------------------------
+    # can_handle
+    # ------------------------------------------------------------------
+
+    def can_handle(self, source: IngestorSource) -> bool:
+        """Return ``True`` for Gherkin feature files.
+
+        Detection is based on:
+
+        1. ``source.format`` being ``"gherkin"`` (or ``"bdd"`` / ``"cucumber"``
+           / ``"behave"``).
+        2. The file extension being ``.feature``.
+        3. The raw content containing both ``Feature:`` and ``Scenario:``
+           keywords.
+
+        Parameters
+        ----------
+        source:
+            The source to evaluate.
+
+        Returns
+        -------
+        bool
+        """
+        if source.format in self.supported_formats:
+            return True
+
+        if source.path is not None:
+            ext = Path(source.path).suffix.lower()
+            if ext == ".feature":
+                return True
+
+        if source.raw_content is not None:
+            content = source.raw_content
+            return "Feature:" in content and "Scenario:" in content
+
+        return False
+
+    # ------------------------------------------------------------------
+    # validate_config
+    # ------------------------------------------------------------------
+
+    def validate_config(self, config: dict) -> list[str]:
+        """Validate Gherkin ingestor configuration.
+
+        Parameters
+        ----------
+        config:
+            Configuration dict.
+
+        Returns
+        -------
+        list[str]
+            Human-readable error strings.  Empty if valid.
+        """
+        errors: list[str] = []
+
+        if "base_url" in config:
+            base_url = config["base_url"]
+            if not isinstance(base_url, str):
+                errors.append("'base_url' must be a string.")
+            elif base_url and not (
+                base_url.startswith("http://") or base_url.startswith("https://")
+            ):
+                errors.append(
+                    "'base_url' must start with 'http://' or 'https://'."
+                )
+
+        if "tag_filter" in config:
+            tf = config["tag_filter"]
+            if not isinstance(tf, (str, list)):
+                errors.append("'tag_filter' must be a string or list of strings.")
+            elif isinstance(tf, list):
+                for item in tf:
+                    if not isinstance(item, str):
+                        errors.append(
+                            "'tag_filter' list items must all be strings."
+                        )
+                        break
+
+        if "extract_endpoints" in config:
+            if not isinstance(config["extract_endpoints"], bool):
+                errors.append("'extract_endpoints' must be a boolean.")
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # ingest
+    # ------------------------------------------------------------------
+
+    async def ingest(self, source: IngestorSource, config: dict) -> IngestResult:
+        """Parse a Gherkin feature file and return endpoints + test cases.
+
+        Parameters
+        ----------
+        source:
+            Source to ingest.
+        config:
+            Plugin configuration (see class docstring).
+
+        Returns
+        -------
+        IngestResult
+        """
+        warnings: list[str] = []
+
+        # ------ read raw content ------
+        try:
+            content = self._read_source(source)
+        except (FileNotFoundError, ValueError) as exc:
+            return self._make_error_result(source, str(exc))
+
+        if not content.strip():
+            return self._make_error_result(source, "Source content is empty.")
+
+        # ------ parse ------
+        try:
+            feature = _parse_gherkin(content)
+        except Exception as exc:  # pragma: no cover — safety net
+            return self._make_error_result(
+                source, f"Gherkin parsing failed: {exc}"
+            )
+
+        if not feature.name:
+            warnings.append("No Feature: keyword found — file may not be valid Gherkin.")
+
+        # ------ config ------
+        base_url: str = config.get("base_url", "")
+        extract_endpoints: bool = bool(config.get("extract_endpoints", True))
+
+        raw_tag_filter = config.get("tag_filter", [])
+        if isinstance(raw_tag_filter, str):
+            tag_filter: set[str] = {raw_tag_filter} if raw_tag_filter else set()
+        else:
+            tag_filter = set(raw_tag_filter)
+
+        # ------ background context ------
+        bg_base_url = _extract_base_url_from_background(feature.background)
+        effective_base_url = base_url or bg_base_url or ""
+
+        # ------ process scenarios ------
+        endpoints: dict[str, IngestedEndpoint] = {}
+        test_cases: list[IngestedTestCase] = []
+        skipped_by_filter = 0
+
+        for scenario in feature.scenarios:
+            # ---- tag filtering ----
+            if tag_filter:
+                scenario_tag_set = {t.lower() for t in scenario.tags}
+                if not tag_filter.intersection(scenario_tag_set):
+                    skipped_by_filter += 1
+                    continue
+
+            # ---- expand Scenario Outline ----
+            if scenario.is_outline:
+                variants = _expand_outline(scenario)
+            else:
+                variants = [(scenario.name, scenario.steps)]
+
+            for variant_name, vsteps in variants:
+                all_steps = feature.background + vsteps
+                tc = self._build_test_case(
+                    scenario=scenario,
+                    variant_name=variant_name,
+                    steps=vsteps,
+                    all_steps=all_steps,
+                    feature=feature,
+                    source=source,
+                )
+                test_cases.append(tc)
+
+                if extract_endpoints:
+                    # Look for HTTP pattern in all steps (background + variant)
+                    for step in all_steps:
+                        pair = _extract_http_from_step(step)
+                        if pair is not None:
+                            method, raw_path = pair
+                            path = _normalise_path(raw_path)
+                            key = _endpoint_key(method, path)
+                            if key not in endpoints:
+                                endpoints[key] = self._build_endpoint(
+                                    method=method,
+                                    path=path,
+                                    scenario=scenario,
+                                    steps=all_steps,
+                                    feature=feature,
+                                    base_url=effective_base_url,
+                                )
+
+        if skipped_by_filter:
+            warnings.append(
+                f"{skipped_by_filter} scenario(s) skipped by tag_filter."
+            )
+
+        if not feature.scenarios:
+            warnings.append("No scenarios found in the feature file.")
+
+        endpoint_list = list(endpoints.values())
+
+        stats: dict[str, Any] = {
+            "feature_name": feature.name,
+            "scenarios_count": len(feature.scenarios),
+            "test_cases_count": len(test_cases),
+            "endpoints_count": len(endpoint_list),
+            "skipped_by_filter": skipped_by_filter,
+            "has_background": bool(feature.background),
+            "outline_count": sum(1 for s in feature.scenarios if s.is_outline),
+        }
+
+        return IngestResult(
+            success=True,
+            source=source,
+            endpoints=endpoint_list,
+            test_cases=test_cases,
+            errors=[],
+            warnings=warnings,
+            stats=stats,
+        )
+
+    # ------------------------------------------------------------------
+    # Private builders
+    # ------------------------------------------------------------------
+
+    def _build_endpoint(
+        self,
+        method: str,
+        path: str,
+        scenario: _Scenario,
+        steps: list[_Step],
+        feature: _Feature,
+        base_url: str,
+    ) -> IngestedEndpoint:
+        """Build an :class:`IngestedEndpoint` from extracted HTTP data."""
+        # Auth requirements: detect keywords in step text
+        auth_requirements: list[str] = []
+        for step in steps:
+            text_lower = step.text.lower()
+            if "without auth" in text_lower or "unauthenticated" in text_lower:
+                auth_requirements.append("none")
+                break
+            if "auth" in text_lower or "token" in text_lower or "bearer" in text_lower:
+                if "bearer" not in auth_requirements:
+                    auth_requirements.append("bearer")
+
+        request_body = _extract_request_body_from_steps(steps)
+
+        # Build responses dict from status code
+        responses: dict[str, Any] = {}
+        status_code = _extract_status_code_from_steps(steps)
+        if status_code is not None:
+            responses[str(status_code)] = {"description": "Expected status"}
+
+        # Tags: strip @ and combine feature + scenario tags
+        tags = list({t for t in scenario.tags})
+
+        return IngestedEndpoint(
+            method=method,
+            path=path if not base_url else path,  # path stays relative
+            summary=scenario.name,
+            description=f"Extracted from Gherkin scenario: {scenario.name}",
+            request_body={"body": request_body} if request_body is not None else None,
+            responses=responses,
+            auth_requirements=auth_requirements,
+            tags=tags,
+            metadata={
+                "feature": feature.name,
+                "base_url": base_url,
+                "source_line": scenario.line_no,
+            },
+        )
+
+    def _build_test_case(
+        self,
+        scenario: _Scenario,
+        variant_name: str,
+        steps: list[_Step],
+        all_steps: list[_Step],
+        feature: _Feature,
+        source: IngestorSource,
+    ) -> IngestedTestCase:
+        """Build an :class:`IngestedTestCase` from a scenario variant."""
+        priority_value, priority_label = _priority_from_tags(scenario.tags)
+
+        # Build step dicts for the test case
+        step_dicts: list[dict] = []
+        for step in steps:
+            sd: dict[str, Any] = {
+                "keyword": step.keyword,
+                "text": step.text,
+            }
+            if step.doc_string is not None:
+                sd["doc_string"] = step.doc_string
+            if step.data_table is not None:
+                sd["data_table"] = step.data_table
+            step_dicts.append(sd)
+
+        # Description: concatenate Given/When/Then step text
+        desc_parts = [
+            f"{s.keyword} {s.text}" for s in steps
+        ]
+        description = " | ".join(desc_parts)
+
+        # Expected result from Then steps
+        then_parts = [
+            s.text for s in steps if s.keyword.lower() in ("then", "and", "but")
+        ]
+        expected_result = "; ".join(then_parts) if then_parts else ""
+
+        # Tags: strip @
+        tags = [t.lstrip("@") for t in scenario.tags]
+
+        # Source reference
+        source_file = source.path or "<inline>"
+        source_ref = f"{source_file}:{scenario.line_no} — {variant_name}"
+
+        # Expected status code
+        status_code = _extract_status_code_from_steps(all_steps)
+
+        # Request body
+        request_body = _extract_request_body_from_steps(all_steps)
+
+        metadata: dict[str, Any] = {
+            "feature": feature.name,
+            "priority_value": priority_value,
+        }
+        if status_code is not None:
+            metadata["expected_status_code"] = status_code
+        if request_body is not None:
+            metadata["request_body"] = request_body
+
+        return IngestedTestCase(
+            name=variant_name,
+            description=description,
+            steps=step_dicts,
+            expected_result=expected_result,
+            priority=priority_label,
+            tags=tags,
+            source_ref=source_ref,
+            metadata=metadata,
+        )