nat-engine 1__py3-none-any.whl

mannf/product/healing/schema_diff.py

@@ -0,0 +1,251 @@
+# 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.
+
+"""Schema differ for OpenAPI specs."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from mannf.product.healing.models import EndpointChange, FieldChange, SchemaDiff
+
+logger = logging.getLogger(__name__)
+
+_HTTP_METHODS = ("get", "post", "put", "patch", "delete", "head", "options")
+
+
+class SchemaDiffer:
+    """Compare two OpenAPI / Swagger specs and return a structured :class:`SchemaDiff`."""
+
+    def diff(self, old_spec: Dict[str, Any], new_spec: Dict[str, Any]) -> SchemaDiff:
+        """Compare *old_spec* and *new_spec* and return a :class:`SchemaDiff`."""
+        old_endpoints = self._extract_endpoints(old_spec)
+        new_endpoints = self._extract_endpoints(new_spec)
+
+        old_keys: Set[Tuple[str, str]] = set(old_endpoints.keys())
+        new_keys: Set[Tuple[str, str]] = set(new_endpoints.keys())
+
+        added_keys = new_keys - old_keys
+        removed_keys = old_keys - new_keys
+        common_keys = old_keys & new_keys
+
+        added_endpoints = [
+            EndpointChange(method=method, path=path, change_type="added")
+            for method, path in sorted(added_keys)
+        ]
+        removed_endpoints = [
+            EndpointChange(method=method, path=path, change_type="removed")
+            for method, path in sorted(removed_keys)
+        ]
+        modified_endpoints = []
+        for method, path in sorted(common_keys):
+            old_op = old_endpoints[(method, path)]
+            new_op = new_endpoints[(method, path)]
+            changes = self._diff_operation(method, path, old_op, new_op, old_spec, new_spec)
+            if changes:
+                modified_endpoints.append(
+                    EndpointChange(method=method, path=path, change_type="modified", details=changes)
+                )
+
+        result = SchemaDiff(
+            added_endpoints=added_endpoints,
+            removed_endpoints=removed_endpoints,
+            modified_endpoints=modified_endpoints,
+        )
+        result.summary = {
+            "added": len(added_endpoints),
+            "removed": len(removed_endpoints),
+            "modified": len(modified_endpoints),
+            "total_changes": len(added_endpoints) + len(removed_endpoints) + len(modified_endpoints),
+        }
+        return result
+
+    def _extract_endpoints(self, spec: Dict[str, Any]) -> Dict[Tuple[str, str], Dict[str, Any]]:
+        """Return mapping of (method, path) -> operation dict."""
+        endpoints: Dict[Tuple[str, str], Dict[str, Any]] = {}
+        for path, path_item in spec.get("paths", {}).items():
+            if not isinstance(path_item, dict):
+                continue
+            for method in _HTTP_METHODS:
+                op = path_item.get(method)
+                if isinstance(op, dict):
+                    endpoints[(method.upper(), path)] = op
+        return endpoints
+
+    def _diff_operation(
+        self,
+        method: str,
+        path: str,
+        old_op: Dict[str, Any],
+        new_op: Dict[str, Any],
+        old_spec: Dict[str, Any],
+        new_spec: Dict[str, Any],
+    ) -> List[FieldChange]:
+        """Return field-level changes between two operations."""
+        changes: List[FieldChange] = []
+
+        # Compare parameters
+        old_params = self._params_by_name(old_op.get("parameters", []), old_spec)
+        new_params = self._params_by_name(new_op.get("parameters", []), new_spec)
+
+        for name in set(old_params) - set(new_params):
+            changes.append(FieldChange(
+                field_path=f"parameters.{name}",
+                change_type="removed",
+                old_value=old_params[name],
+                new_value=None,
+            ))
+        for name in set(new_params) - set(old_params):
+            changes.append(FieldChange(
+                field_path=f"parameters.{name}",
+                change_type="added",
+                old_value=None,
+                new_value=new_params[name],
+            ))
+        for name in set(old_params) & set(new_params):
+            old_p = old_params[name]
+            new_p = new_params[name]
+            old_type = (old_p.get("schema") or {}).get("type")
+            new_type = (new_p.get("schema") or {}).get("type")
+            if old_type != new_type:
+                changes.append(FieldChange(
+                    field_path=f"parameters.{name}.type",
+                    change_type="type_changed",
+                    old_value=old_type,
+                    new_value=new_type,
+                ))
+
+        # Compare request body schema
+        old_body = self._get_body_schema(old_op, old_spec)
+        new_body = self._get_body_schema(new_op, new_spec)
+        if old_body or new_body:
+            body_changes = self._diff_schemas("requestBody", old_body or {}, new_body or {})
+            changes.extend(body_changes)
+
+        # Compare response schemas (200, 201, 2xx)
+        old_resp = self._get_response_schema(old_op, old_spec)
+        new_resp = self._get_response_schema(new_op, new_spec)
+        if old_resp or new_resp:
+            resp_changes = self._diff_schemas("response", old_resp or {}, new_resp or {})
+            changes.extend(resp_changes)
+
+        return changes
+
+    def _params_by_name(
+        self, params: List[Dict[str, Any]], spec: Dict[str, Any]
+    ) -> Dict[str, Dict[str, Any]]:
+        result: Dict[str, Dict[str, Any]] = {}
+        for p in params:
+            if "$ref" in p:
+                p = _resolve_ref(spec, p["$ref"])
+            name = p.get("name", "")
+            if name:
+                result[name] = p
+        return result
+
+    def _get_body_schema(
+        self, op: Dict[str, Any], spec: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        # OpenAPI 3
+        rb = op.get("requestBody", {})
+        if rb:
+            content = rb.get("content", {})
+            for mt in ("application/json", "application/x-www-form-urlencoded"):
+                if mt in content:
+                    s = content[mt].get("schema", {})
+                    return _resolve_ref(spec, s["$ref"]) if "$ref" in s else s
+        # Swagger 2
+        for p in op.get("parameters", []):
+            if "$ref" in p:
+                p = _resolve_ref(spec, p["$ref"])
+            if p.get("in") == "body":
+                s = p.get("schema", {})
+                return _resolve_ref(spec, s["$ref"]) if "$ref" in s else s
+        return None
+
+    def _get_response_schema(
+        self, op: Dict[str, Any], spec: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        responses = op.get("responses", {})
+        for code in ("200", "201", "2xx", "default"):
+            resp = responses.get(code, {})
+            if resp:
+                content = resp.get("content", {})
+                if content:
+                    for mt in ("application/json",):
+                        if mt in content:
+                            s = content[mt].get("schema", {})
+                            return _resolve_ref(spec, s["$ref"]) if "$ref" in s else s
+                schema = resp.get("schema", {})
+                if schema:
+                    return _resolve_ref(spec, schema["$ref"]) if "$ref" in schema else schema
+        return None
+
+    def _diff_schemas(
+        self, prefix: str, old_schema: Dict[str, Any], new_schema: Dict[str, Any]
+    ) -> List[FieldChange]:
+        changes: List[FieldChange] = []
+        old_props = old_schema.get("properties", {})
+        new_props = new_schema.get("properties", {})
+
+        for name in set(old_props) - set(new_props):
+            changes.append(FieldChange(
+                field_path=f"{prefix}.properties.{name}",
+                change_type="removed",
+                old_value=old_props[name],
+                new_value=None,
+            ))
+        for name in set(new_props) - set(old_props):
+            changes.append(FieldChange(
+                field_path=f"{prefix}.properties.{name}",
+                change_type="added",
+                old_value=None,
+                new_value=new_props[name],
+            ))
+        for name in set(old_props) & set(new_props):
+            old_t = old_props[name].get("type")
+            new_t = new_props[name].get("type")
+            if old_t != new_t:
+                changes.append(FieldChange(
+                    field_path=f"{prefix}.properties.{name}.type",
+                    change_type="type_changed",
+                    old_value=old_t,
+                    new_value=new_t,
+                ))
+
+        # Compare required fields
+        old_req = set(old_schema.get("required", []))
+        new_req = set(new_schema.get("required", []))
+        for name in old_req - new_req:
+            changes.append(FieldChange(
+                field_path=f"{prefix}.required.{name}",
+                change_type="constraint_changed",
+                old_value="required",
+                new_value="optional",
+            ))
+        for name in new_req - old_req:
+            changes.append(FieldChange(
+                field_path=f"{prefix}.required.{name}",
+                change_type="constraint_changed",
+                old_value="optional",
+                new_value="required",
+            ))
+
+        return changes
+
+
+def _resolve_ref(spec: Dict[str, Any], ref: str) -> Dict[str, Any]:
+    """Resolve a ``$ref`` pointer within *spec*."""
+    if not ref.startswith("#/"):
+        return {}
+    parts = ref.lstrip("#/").split("/")
+    node: Any = spec
+    for part in parts:
+        part = part.replace("~1", "/").replace("~0", "~")
+        if not isinstance(node, dict) or part not in node:
+            return {}
+        node = node[part]
+    return node if isinstance(node, dict) else {}

mannf/product/ingestors/__init__.py

@@ -0,0 +1,77 @@
+# 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.
+
+"""Ingestor plugins package — public API."""
+
+from __future__ import annotations
+
+from mannf.product.ingestors.base import IngestorPlugin
+from mannf.product.ingestors.models import (
+    IngestedEndpoint,
+    IngestedTestCase,
+    IngestorSource,
+    IngestResult,
+)
+from mannf.product.ingestors.loader import (
+    get_ingestor_by_name,
+    get_ingestor_for_source,
+    load_all_ingestors,
+    load_ingestors_from_directory,
+    load_ingestors_from_entry_points,
+)
+from mannf.product.ingestors.bgstm_ingestor import BGSTMIngestor
+from mannf.product.ingestors.curl_ingestor import CurlIngestor
+from mannf.product.ingestors.cypress_ingestor import CypressIngestor
+from mannf.product.ingestors.gherkin_ingestor import GherkinIngestor
+from mannf.product.ingestors.graphql_ingestor import GraphQLIngestor
+from mannf.product.ingestors.grpc_ingestor import GrpcIngestor
+from mannf.product.ingestors.har_ingestor import HARIngestor
+from mannf.product.ingestors.openapi_ingestor import OpenAPIIngestor
+from mannf.product.ingestors.playwright_ingestor import PlaywrightIngestor
+from mannf.product.ingestors.postman_ingestor import PostmanIngestor
+from mannf.product.ingestors.traffic_ingestor import TrafficIngestor
+from mannf.product.ingestors.websocket_ingestor import WebSocketIngestor
+
+# Built-in ingestors that are always available without entry-point registration.
+BUILTIN_INGESTORS: list[IngestorPlugin] = [
+    OpenAPIIngestor(),
+    PostmanIngestor(),
+    GraphQLIngestor(),
+    GrpcIngestor(),
+    BGSTMIngestor(),
+    HARIngestor(),
+    CurlIngestor(),
+    GherkinIngestor(),
+    PlaywrightIngestor(),
+    CypressIngestor(),
+    TrafficIngestor(),
+    WebSocketIngestor(),
+]
+
+__all__ = [
+    "IngestorPlugin",
+    "IngestorSource",
+    "IngestedEndpoint",
+    "IngestedTestCase",
+    "IngestResult",
+    "BGSTMIngestor",
+    "CurlIngestor",
+    "CypressIngestor",
+    "GherkinIngestor",
+    "GraphQLIngestor",
+    "GrpcIngestor",
+    "HARIngestor",
+    "OpenAPIIngestor",
+    "PlaywrightIngestor",
+    "PostmanIngestor",
+    "TrafficIngestor",
+    "WebSocketIngestor",
+    "BUILTIN_INGESTORS",
+    "load_all_ingestors",
+    "load_ingestors_from_directory",
+    "load_ingestors_from_entry_points",
+    "get_ingestor_by_name",
+    "get_ingestor_for_source",
+]

mannf/product/ingestors/base.py

@@ -0,0 +1,256 @@
+# 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.
+
+"""Abstract base class for ingestor plugins.
+
+All ingestor plugins must subclass :class:`IngestorPlugin` and implement the
+three abstract methods: :meth:`ingest`, :meth:`validate_config`, and
+:meth:`can_handle`.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from mannf.product.ingestors.models import (
+    IngestedEndpoint,
+    IngestedTestCase,
+    IngestorSource,
+    IngestResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class IngestorPlugin(ABC):
+    """Abstract base class for ingestor plugins.
+
+    Subclasses must define the class-level attributes ``name``,
+    ``display_name``, ``description``, ``supported_extensions``, and
+    ``supported_formats``, and implement the abstract methods :meth:`ingest`,
+    :meth:`validate_config`, and :meth:`can_handle`.
+
+    Example::
+
+        class MyIngestor(IngestorPlugin):
+            name = "myformat"
+            display_name = "My Format"
+            description = "Ingest MyFormat specs."
+            supported_extensions = [".myfmt"]
+            supported_formats = ["myformat"]
+
+            async def ingest(self, source, config):
+                content = self._read_source(source)
+                # ... parse content ...
+                return IngestResult(success=True, source=source)
+
+            def validate_config(self, config):
+                return []
+
+            def can_handle(self, source):
+                return source.format in self.supported_formats
+    """
+
+    name: str                        # e.g., "openapi"
+    display_name: str                # e.g., "OpenAPI/Swagger"
+    description: str                 # one-line description
+    supported_extensions: list[str]  # e.g., [".yaml", ".yml", ".json"]
+    supported_formats: list[str]     # e.g., ["openapi", "swagger"]
+
+    # ------------------------------------------------------------------
+    # Abstract methods
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def ingest(self, source: IngestorSource, config: dict) -> IngestResult:
+        """Ingest the given source and return a unified :class:`IngestResult`.
+
+        Parameters
+        ----------
+        source:
+            Metadata and content of the source to ingest.
+        config:
+            Plugin-specific configuration dict (keys validated by
+            :meth:`validate_config`).
+
+        Returns
+        -------
+        IngestResult
+            The result of the ingestion, including extracted endpoints and
+            test cases.
+        """
+        ...
+
+    @abstractmethod
+    def validate_config(self, config: dict) -> list[str]:
+        """Validate plugin-specific configuration.
+
+        Parameters
+        ----------
+        config:
+            Configuration dict to validate.
+
+        Returns
+        -------
+        list[str]
+            A list of human-readable error strings.  An empty list means the
+            config is valid.
+        """
+        ...
+
+    @abstractmethod
+    def can_handle(self, source: IngestorSource) -> bool:
+        """Return True if this plugin can handle the given source.
+
+        Parameters
+        ----------
+        source:
+            The source to evaluate.
+
+        Returns
+        -------
+        bool
+            True if this plugin is capable of ingesting the source.
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # Concrete helper methods
+    # ------------------------------------------------------------------
+
+    def _read_source(self, source: IngestorSource) -> str:
+        """Read and return the raw content from *source*.
+
+        Tries, in order:
+        1. ``source.raw_content`` — returned as-is if present.
+        2. ``source.path`` — read from the local filesystem.
+
+        Parameters
+        ----------
+        source:
+            The source to read.
+
+        Returns
+        -------
+        str
+            The raw content string.
+
+        Raises
+        ------
+        ValueError
+            If neither ``raw_content`` nor a valid ``path`` is available.
+        FileNotFoundError
+            If ``source.path`` points to a non-existent file.
+        """
+        if source.raw_content is not None:
+            return source.raw_content
+
+        if source.path is not None:
+            file_path = Path(source.path)
+            if not file_path.exists():
+                raise FileNotFoundError(
+                    f"Source file not found: {source.path!r}"
+                )
+            return file_path.read_text(encoding="utf-8")
+
+        raise ValueError(
+            "IngestorSource has no raw_content or path — cannot read content."
+        )
+
+    def _make_error_result(
+        self, source: IngestorSource, error: str
+    ) -> IngestResult:
+        """Create a failed :class:`IngestResult` for the given *source*.
+
+        Parameters
+        ----------
+        source:
+            The source that failed ingestion.
+        error:
+            Human-readable error message describing the failure.
+
+        Returns
+        -------
+        IngestResult
+            A result with ``success=False`` and the error in ``errors``.
+        """
+        return IngestResult(
+            success=False,
+            source=source,
+            errors=[error],
+        )
+
+    def _detect_format(
+        self, content: str, source: IngestorSource
+    ) -> str | None:
+        """Attempt to detect the format of *content*.
+
+        Performs simple heuristic detection based on well-known keywords and
+        file extensions.  Concrete plugins may override this for more
+        sophisticated detection.
+
+        Parameters
+        ----------
+        content:
+            The raw content string.
+        source:
+            The originating source (used to inspect file extension).
+
+        Returns
+        -------
+        str | None
+            A format identifier string (e.g., ``"openapi"``, ``"postman"``,
+            ``"har"``, ``"graphql"``, ``"gherkin"``), or ``None`` if the
+            format cannot be determined.
+        """
+        # Check file extension first
+        if source.path is not None:
+            name = Path(source.path).name.lower()
+            ext = Path(source.path).suffix.lower()
+            if name.endswith((".cy.js", ".cy.ts", ".cy.jsx", ".cy.tsx")):
+                return "cypress"
+            if ext == ".feature":
+                return "gherkin"
+            if ext == ".graphql" or ext == ".gql":
+                return "graphql"
+
+        # Content-based heuristics (check more specific patterns first)
+        stripped = content.strip()
+
+        # HAR — always JSON with "log" key containing "entries"
+        if '"log"' in content and '"entries"' in content and '"request"' in content:
+            return "har"
+
+        # Postman — JSON with "info" and "item" keys
+        if '"info"' in content and '"item"' in content and '"postman"' in stripped.lower():
+            return "postman"
+
+        # OpenAPI 3.x
+        if "openapi:" in content or '"openapi"' in content:
+            return "openapi"
+
+        # Swagger 2.x
+        if "swagger:" in content or '"swagger"' in content:
+            return "openapi"
+
+        # GraphQL SDL
+        if stripped.startswith("type ") or "type Query" in content or "schema {" in content:
+            return "graphql"
+
+        # Gherkin
+        if stripped.startswith("Feature:") or "Scenario:" in content:
+            return "gherkin"
+
+        # Cypress — cy.visit/cy.get/cy.contains usage
+        if "cy.visit(" in content or "cy.get(" in content or "cy.contains(" in content:
+            return "cypress"
+
+        # cURL
+        if stripped.startswith("curl ") or "\ncurl " in content:
+            return "curl"
+
+        return None