nat-engine 1__py3-none-any.whl

mannf/product/ingestors/graphql_ingestor.py

@@ -0,0 +1,845 @@
+# 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.
+
+"""GraphQL Schema ingestor plugin.
+
+Parses GraphQL schemas from introspection JSON or SDL (Schema Definition
+Language) files and produces normalised
+:class:`~mannf.product.ingestors.models.IngestedEndpoint` and
+:class:`~mannf.product.ingestors.models.IngestedTestCase` objects.
+
+Two input formats are supported:
+
+* **Introspection JSON** — the ``{"data": {"__schema": {...}}}`` or plain
+  ``{"__schema": {...}}`` payload returned by a GraphQL introspection query.
+* **SDL** — ``.graphql`` / ``.gql`` source text with ``type Query``,
+  ``type Mutation``, and/or ``type Subscription`` root-type definitions.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from mannf.product.ingestors.base import IngestorPlugin
+from mannf.product.ingestors.models import (
+    IngestedEndpoint,
+    IngestedTestCase,
+    IngestorSource,
+    IngestResult,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Priority mapping by GraphQL operation type
+_OPERATION_PRIORITY: dict[str, str] = {
+    "QUERY": "medium",
+    "MUTATION": "high",
+    "SUBSCRIPTION": "low",
+}
+
+# Tags added to every endpoint by operation type
+_OPERATION_TAGS: dict[str, list[str]] = {
+    "QUERY": ["graphql", "query"],
+    "MUTATION": ["graphql", "mutation"],
+    "SUBSCRIPTION": ["graphql", "subscription"],
+}
+
+# Regex patterns for the lightweight SDL parser
+_RE_BLOCK_COMMENT = re.compile(r'"""(.*?)"""', re.DOTALL)
+_RE_LINE_COMMENT = re.compile(r'#[^\n]*')
+_RE_TYPE_BLOCK = re.compile(
+    r'type\s+(\w+)\s*(?:implements[^{]*)?\{([^}]*)\}',
+    re.DOTALL,
+)
+_RE_FIELD = re.compile(
+    r'(\w+)\s*(\([^)]*\))?\s*:\s*([\w!\[\]]+)',
+)
+_RE_ARG = re.compile(
+    r'(\w+)\s*:\s*([\w!\[\]]+)(?:\s*=\s*[^\s,)]+)?',
+)
+
+
+# ---------------------------------------------------------------------------
+# Introspection JSON helpers
+# ---------------------------------------------------------------------------
+
+
+def _unwrap_introspection(data: dict[str, Any]) -> dict[str, Any] | None:
+    """Return the ``__schema`` dict from an introspection payload, or ``None``.
+
+    Handles both the raw ``{"__schema": {...}}`` shape and the wrapped
+    ``{"data": {"__schema": {...}}}`` shape returned by some clients.
+    """
+    if "__schema" in data:
+        return data["__schema"]  # type: ignore[return-value]
+    nested = data.get("data") or {}
+    if isinstance(nested, dict) and "__schema" in nested:
+        return nested["__schema"]  # type: ignore[return-value]
+    return None
+
+
+def _is_introspection_json(data: dict[str, Any]) -> bool:
+    """Return ``True`` if *data* looks like a GraphQL introspection result."""
+    return _unwrap_introspection(data) is not None
+
+
+def _type_name(type_ref: dict[str, Any] | None) -> str:
+    """Unwrap a nested ``{"kind": ..., "name": ..., "ofType": ...}`` type ref."""
+    if not type_ref:
+        return ""
+    if type_ref.get("name"):
+        return type_ref["name"]
+    return _type_name(type_ref.get("ofType"))
+
+
+def _is_non_null(type_ref: dict[str, Any] | None) -> bool:
+    """Return ``True`` if the type ref represents a non-null (required) type."""
+    if not type_ref:
+        return False
+    return type_ref.get("kind") == "NON_NULL"
+
+
+def _args_from_introspection(
+    args: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Convert an introspection ``args`` array to ingestor parameter dicts."""
+    params: list[dict[str, Any]] = []
+    for arg in args:
+        if not isinstance(arg, dict):
+            continue
+        params.append(
+            {
+                "name": arg.get("name", ""),
+                "description": arg.get("description") or "",
+                "required": _is_non_null(arg.get("type")),
+                "schema": {"type": _type_name(arg.get("type"))},
+                "defaultValue": arg.get("defaultValue"),
+            }
+        )
+    return params
+
+
+def _endpoints_from_introspection(
+    schema: dict[str, Any],
+    base_url: str,
+    include_deprecated: bool,
+    include_subscriptions: bool,
+) -> list[IngestedEndpoint]:
+    """Extract endpoints from a parsed ``__schema`` dict."""
+    # Build a lookup of all types by name
+    types_by_name: dict[str, dict[str, Any]] = {
+        t["name"]: t
+        for t in schema.get("types", [])
+        if isinstance(t, dict) and t.get("name")
+    }
+
+    root_type_map: dict[str, str] = {}
+    for role in ("queryType", "mutationType", "subscriptionType"):
+        ref = schema.get(role)
+        if isinstance(ref, dict) and ref.get("name"):
+            root_type_map[role] = ref["name"]
+
+    operation_kind: dict[str, str] = {
+        "queryType": "QUERY",
+        "mutationType": "MUTATION",
+        "subscriptionType": "SUBSCRIPTION",
+    }
+
+    endpoints: list[IngestedEndpoint] = []
+
+    for role, type_name in root_type_map.items():
+        if role == "subscriptionType" and not include_subscriptions:
+            continue
+        kind = operation_kind[role]
+        root_type = types_by_name.get(type_name)
+        if not root_type:
+            continue
+
+        for field in root_type.get("fields") or []:
+            if not isinstance(field, dict):
+                continue
+            if field.get("isDeprecated") and not include_deprecated:
+                continue
+
+            field_name: str = field.get("name", "")
+            description: str = field.get("description") or ""
+            return_type: str = _type_name(field.get("type"))
+            args: list[dict[str, Any]] = field.get("args") or []
+
+            # Collect directives for auth hints
+            auth_requirements: list[str] = _auth_from_directives(
+                field.get("directives") or []
+            )
+
+            path = f"/graphql#{kind.lower()}.{field_name}"
+
+            endpoint = IngestedEndpoint(
+                method=kind,
+                path=path,
+                summary=description,
+                description=description,
+                parameters=_args_from_introspection(args),
+                request_body=_build_request_body(args),
+                responses={
+                    "200": {
+                        "description": "Successful response",
+                        "type": return_type,
+                    }
+                },
+                auth_requirements=auth_requirements,
+                tags=list(_OPERATION_TAGS[kind]),
+                metadata={
+                    "operationName": field_name,
+                    "returnType": return_type,
+                    "typeName": type_name,
+                    "deprecated": bool(field.get("isDeprecated", False)),
+                    "base_url": base_url,
+                    "source": "introspection",
+                },
+            )
+            endpoints.append(endpoint)
+
+    return endpoints
+
+
+def _auth_from_directives(directives: list[dict[str, Any]]) -> list[str]:
+    """Return auth scheme names hinted by directive names."""
+    auth_hints: list[str] = []
+    auth_directive_names = {"auth", "authenticated", "requiresAuth", "authorize", "jwt"}
+    for d in directives:
+        if not isinstance(d, dict):
+            continue
+        name = d.get("name", "")
+        if name in auth_directive_names:
+            auth_hints.append(name)
+    return auth_hints
+
+
+def _build_request_body(
+    args: list[dict[str, Any]],
+) -> dict[str, Any] | None:
+    """Build a minimal request body descriptor from introspection args."""
+    if not args:
+        return None
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for arg in args:
+        if not isinstance(arg, dict):
+            continue
+        name = arg.get("name", "")
+        type_name_str = _type_name(arg.get("type"))
+        properties[name] = {"type": type_name_str}
+        if _is_non_null(arg.get("type")):
+            required.append(name)
+
+    body: dict[str, Any] = {
+        "content": {
+            "application/json": {
+                "schema": {
+                    "type": "object",
+                    "properties": properties,
+                }
+            }
+        }
+    }
+    if required:
+        body["content"]["application/json"]["schema"]["required"] = required
+    return body
+
+
+# ---------------------------------------------------------------------------
+# SDL parser helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_sdl(content: str) -> bool:
+    """Return ``True`` if *content* appears to be GraphQL SDL source text."""
+    stripped = content.strip()
+    # SDL files often start with comments, schema/type keywords, or triple-quoted docs
+    return bool(
+        re.search(r'\btype\s+\w+', stripped)
+        or re.search(r'\bschema\s*\{', stripped)
+        or stripped.startswith('"""')
+        or stripped.startswith('#')
+    )
+
+
+def _strip_comments(content: str) -> str:
+    """Strip ``#`` line comments from SDL content (preserving triple-quoted strings)."""
+    return _RE_LINE_COMMENT.sub('', content)
+
+
+class _SDLField:
+    """Lightweight representation of a parsed SDL field/operation."""
+
+    __slots__ = ("name", "description", "args", "return_type")
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        args: list[dict[str, Any]],
+        return_type: str,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.args = args
+        self.return_type = return_type
+
+
+def _parse_sdl_args(args_str: str) -> list[dict[str, Any]]:
+    """Parse a parenthesised argument list string into parameter dicts."""
+    if not args_str:
+        return []
+    params: list[dict[str, Any]] = []
+    # Strip outer parentheses if present
+    args_str = args_str.strip().lstrip('(').rstrip(')')
+    for m in _RE_ARG.finditer(args_str):
+        arg_name = m.group(1)
+        arg_type = m.group(2)
+        required = arg_type.endswith('!')
+        params.append(
+            {
+                "name": arg_name,
+                "description": "",
+                "required": required,
+                "schema": {"type": arg_type.rstrip('!')},
+                "defaultValue": None,
+            }
+        )
+    return params
+
+
+def _parse_sdl_type_block(block_body: str) -> list[_SDLField]:
+    """Parse the body of a GraphQL type block into :class:`_SDLField` objects.
+
+    Handles triple-quoted description strings attached to fields.
+    """
+    fields: list[_SDLField] = []
+    # Extract triple-quoted descriptions alongside fields
+    # Replace triple-quoted docs with placeholder to assist field parsing
+    descriptions: dict[int, str] = {}
+    idx = 0
+    cleaned_parts: list[str] = []
+    last = 0
+    for m in _RE_BLOCK_COMMENT.finditer(block_body):
+        cleaned_parts.append(block_body[last:m.start()])
+        desc_text = m.group(1).strip()
+        placeholder = f"__DOC_{idx}__"
+        cleaned_parts.append(placeholder)
+        descriptions[idx] = desc_text
+        idx += 1
+        last = m.end()
+    cleaned_parts.append(block_body[last:])
+    cleaned = ''.join(cleaned_parts)
+    cleaned = _strip_comments(cleaned)
+
+    # Split lines for field detection
+    lines = [ln.strip() for ln in cleaned.splitlines() if ln.strip()]
+    pending_desc = ""
+    for line in lines:
+        # Check if this line is a doc placeholder
+        doc_match = re.match(r'^__DOC_(\d+)__$', line)
+        if doc_match:
+            pending_desc = descriptions[int(doc_match.group(1))]
+            continue
+
+        field_match = _RE_FIELD.match(line)
+        if field_match:
+            f_name = field_match.group(1)
+            args_str = field_match.group(2) or ""
+            f_return_type = field_match.group(3)
+            args = _parse_sdl_args(args_str)
+            fields.append(
+                _SDLField(
+                    name=f_name,
+                    description=pending_desc,
+                    args=args,
+                    return_type=f_return_type,
+                )
+            )
+            pending_desc = ""
+
+    return fields
+
+
+def _endpoints_from_sdl(
+    content: str,
+    base_url: str,
+    include_deprecated: bool,
+    include_subscriptions: bool,
+) -> tuple[list[IngestedEndpoint], list[str]]:
+    """Parse SDL text and return ``(endpoints, warnings)``."""
+    endpoints: list[IngestedEndpoint] = []
+    warnings: list[str] = []
+
+    root_type_names: dict[str, str] = {
+        "Query": "QUERY",
+        "Mutation": "MUTATION",
+        "Subscription": "SUBSCRIPTION",
+    }
+
+    for type_block_match in _RE_TYPE_BLOCK.finditer(content):
+        type_name = type_block_match.group(1)
+        if type_name not in root_type_names:
+            continue
+        kind = root_type_names[type_name]
+        if kind == "SUBSCRIPTION" and not include_subscriptions:
+            continue
+
+        block_body = type_block_match.group(2)
+        sdl_fields = _parse_sdl_type_block(block_body)
+
+        for sdl_field in sdl_fields:
+            # SDL has no built-in deprecated marker in a simple regex parser;
+            # skip fields only if include_deprecated is explicitly handled
+            path = f"/graphql#{kind.lower()}.{sdl_field.name}"
+
+            # Build parameter list from args
+            parameters = [
+                {
+                    "name": a["name"],
+                    "description": a["description"],
+                    "required": a["required"],
+                    "schema": a["schema"],
+                    "defaultValue": a["defaultValue"],
+                }
+                for a in sdl_field.args
+            ]
+
+            request_body: dict[str, Any] | None = None
+            if sdl_field.args:
+                props = {
+                    a["name"]: {"type": a["schema"].get("type", "")}
+                    for a in sdl_field.args
+                }
+                required_args = [a["name"] for a in sdl_field.args if a["required"]]
+                schema_obj: dict[str, Any] = {
+                    "type": "object",
+                    "properties": props,
+                }
+                if required_args:
+                    schema_obj["required"] = required_args
+                request_body = {
+                    "content": {
+                        "application/json": {"schema": schema_obj}
+                    }
+                }
+
+            endpoint = IngestedEndpoint(
+                method=kind,
+                path=path,
+                summary=sdl_field.description,
+                description=sdl_field.description,
+                parameters=parameters,
+                request_body=request_body,
+                responses={
+                    "200": {
+                        "description": "Successful response",
+                        "type": sdl_field.return_type,
+                    }
+                },
+                auth_requirements=[],
+                tags=list(_OPERATION_TAGS[kind]),
+                metadata={
+                    "operationName": sdl_field.name,
+                    "returnType": sdl_field.return_type,
+                    "typeName": type_name,
+                    "deprecated": False,
+                    "base_url": base_url,
+                    "source": "sdl",
+                },
+            )
+            endpoints.append(endpoint)
+
+    return endpoints, warnings
+
+
+# ---------------------------------------------------------------------------
+# Test case generation
+# ---------------------------------------------------------------------------
+
+
+def _generate_test_cases(endpoint: IngestedEndpoint) -> list[IngestedTestCase]:
+    """Generate synthetic test cases for a GraphQL *endpoint*.
+
+    Produces:
+
+    * **Happy-path** — valid operation, expect a 200 response.
+    * **Missing required args** — omit a required argument, expect an error.
+    * **Security** — if auth is required, omit credentials (expect 401/403).
+    * **Invalid input type** — for MUTATION operations with typed args.
+    """
+    cases: list[IngestedTestCase] = []
+    kind = endpoint.method  # "QUERY", "MUTATION", or "SUBSCRIPTION"
+    op_name = endpoint.metadata.get("operationName", endpoint.path)
+    priority = _OPERATION_PRIORITY.get(kind, "medium")
+    source_ref = f"{kind} {op_name}"
+
+    # --- Happy-path ---
+    cases.append(
+        IngestedTestCase(
+            name=f"[happy path] {kind} {op_name}",
+            description=(
+                f"Execute a valid {kind.lower()} '{op_name}' and expect a "
+                f"successful response."
+            ),
+            steps=[
+                {
+                    "action": f"{kind} {op_name}",
+                    "description": "Send valid GraphQL operation",
+                }
+            ],
+            expected_result="200 response with data field",
+            priority=priority,
+            tags=["happy-path", "functional"],
+            source_ref=source_ref,
+            metadata={
+                "intent": "functional",
+                "test_type": "positive",
+                "operationName": op_name,
+            },
+        )
+    )
+
+    # --- Missing required args ---
+    required_params = [
+        p for p in endpoint.parameters
+        if isinstance(p, dict) and p.get("required")
+    ]
+    if required_params:
+        first_required = required_params[0]
+        param_name = first_required.get("name", "arg")
+        cases.append(
+            IngestedTestCase(
+                name=f"[missing required arg] {kind} {op_name} — omit '{param_name}'",
+                description=(
+                    f"Execute '{op_name}' without required argument "
+                    f"'{param_name}' and expect an error response."
+                ),
+                steps=[
+                    {
+                        "action": f"{kind} {op_name}",
+                        "description": f"Omit required argument '{param_name}'",
+                    }
+                ],
+                expected_result="GraphQL error or 400 response",
+                priority=priority,
+                tags=["negative", "functional"],
+                source_ref=source_ref,
+                metadata={
+                    "intent": "functional",
+                    "test_type": "negative",
+                    "neg_type": "missing_required_arg",
+                    "missing_arg": param_name,
+                },
+            )
+        )
+
+    # --- Security test case ---
+    if endpoint.auth_requirements:
+        cases.append(
+            IngestedTestCase(
+                name=f"[security] {kind} {op_name} — missing auth",
+                description=(
+                    f"Execute '{op_name}' without authentication and expect "
+                    f"a 401 or 403 response."
+                ),
+                steps=[
+                    {
+                        "action": f"{kind} {op_name}",
+                        "description": "Send request without auth credentials",
+                    }
+                ],
+                expected_result="401 or 403 response",
+                priority="high",
+                tags=["security", "auth"],
+                source_ref=source_ref,
+                metadata={
+                    "intent": "security",
+                    "test_type": "negative",
+                    "neg_type": "missing_auth",
+                    "auth_schemes": endpoint.auth_requirements,
+                },
+            )
+        )
+
+    # --- Invalid input type (mutations only) ---
+    if kind == "MUTATION" and endpoint.parameters:
+        typed_params = [
+            p for p in endpoint.parameters
+            if isinstance(p, dict) and p.get("schema", {}).get("type")
+        ]
+        if typed_params:
+            param = typed_params[0]
+            param_name = param.get("name", "input")
+            cases.append(
+                IngestedTestCase(
+                    name=f"[invalid input type] MUTATION {op_name} — wrong type for '{param_name}'",
+                    description=(
+                        f"Execute mutation '{op_name}' with an invalid type "
+                        f"for '{param_name}' and expect an error response."
+                    ),
+                    steps=[
+                        {
+                            "action": f"MUTATION {op_name}",
+                            "description": f"Use wrong type for '{param_name}'",
+                        }
+                    ],
+                    expected_result="GraphQL error or 400 response",
+                    priority=priority,
+                    tags=["negative", "functional"],
+                    source_ref=source_ref,
+                    metadata={
+                        "intent": "functional",
+                        "test_type": "negative",
+                        "neg_type": "invalid_input_type",
+                        "param": param_name,
+                    },
+                )
+            )
+
+    return cases
+
+
+# ---------------------------------------------------------------------------
+# GraphQLIngestor
+# ---------------------------------------------------------------------------
+
+
+class GraphQLIngestor(IngestorPlugin):
+    """Ingest GraphQL schemas from introspection JSON or SDL files.
+
+    Produces normalised
+    :class:`~mannf.product.ingestors.models.IngestedEndpoint` and
+    :class:`~mannf.product.ingestors.models.IngestedTestCase` objects from
+    GraphQL introspection results (JSON) or SDL schema files (``.graphql``,
+    ``.gql``).
+
+    Configuration keys
+    ------------------
+    base_url : str, optional
+        The GraphQL endpoint URL to associate with extracted endpoints.
+    include_deprecated : bool, optional
+        When ``True``, deprecated fields/operations are included in the
+        output.  Defaults to ``False``.
+    include_subscriptions : bool, optional
+        When ``False``, subscription operations are omitted.  Defaults to
+        ``True``.
+    """
+
+    name = "graphql"
+    display_name = "GraphQL Schema"
+    description = "Ingest GraphQL schemas from introspection JSON or SDL files."
+    supported_extensions = [".graphql", ".gql", ".json"]
+    supported_formats = ["graphql"]
+
+    # ------------------------------------------------------------------
+    # validate_config
+    # ------------------------------------------------------------------
+
+    def validate_config(self, config: dict) -> list[str]:
+        """Validate the plugin configuration.
+
+        Parameters
+        ----------
+        config:
+            Supported keys: ``base_url`` (str), ``include_deprecated`` (bool),
+            ``include_subscriptions`` (bool).
+
+        Returns
+        -------
+        list[str]
+            Empty list when the config is valid; error strings otherwise.
+        """
+        errors: list[str] = []
+        if "base_url" in config and not isinstance(config["base_url"], str):
+            errors.append("'base_url' must be a string.")
+        if "include_deprecated" in config and not isinstance(
+            config["include_deprecated"], bool
+        ):
+            errors.append("'include_deprecated' must be a boolean.")
+        if "include_subscriptions" in config and not isinstance(
+            config["include_subscriptions"], bool
+        ):
+            errors.append("'include_subscriptions' must be a boolean.")
+        return errors
+
+    # ------------------------------------------------------------------
+    # can_handle
+    # ------------------------------------------------------------------
+
+    def can_handle(self, source: IngestorSource) -> bool:
+        """Return ``True`` for graphql format, supported extensions, or SDL/introspection content.
+
+        Parameters
+        ----------
+        source:
+            The source to evaluate.
+
+        Returns
+        -------
+        bool
+            ``True`` if this plugin can ingest the source.
+        """
+        if source.format and source.format in self.supported_formats:
+            return True
+
+        if source.path is not None:
+            ext = Path(source.path).suffix.lower()
+            if ext in {".graphql", ".gql"}:
+                return True
+            # .json could be introspection — peek at content
+            if ext == ".json" and source.raw_content:
+                try:
+                    data = json.loads(source.raw_content)
+                    return _is_introspection_json(data)
+                except (json.JSONDecodeError, ValueError):
+                    return False
+
+        # No path — check raw content
+        if source.raw_content:
+            stripped = source.raw_content.strip()
+            if stripped.startswith("{"):
+                try:
+                    data = json.loads(stripped)
+                    return _is_introspection_json(data)
+                except (json.JSONDecodeError, ValueError):
+                    pass
+            return _is_sdl(stripped)
+
+        return False
+
+    # ------------------------------------------------------------------
+    # ingest
+    # ------------------------------------------------------------------
+
+    async def ingest(self, source: IngestorSource, config: dict) -> IngestResult:
+        """Parse a GraphQL schema and return a normalised :class:`IngestResult`.
+
+        Parameters
+        ----------
+        source:
+            The source to ingest.  Must provide either ``raw_content`` or a
+            valid ``path``.
+        config:
+            Plugin-specific configuration.  See :meth:`validate_config` for
+            supported keys.
+
+        Returns
+        -------
+        IngestResult
+            Populated result on success; ``success=False`` with ``errors`` on
+            failure.
+        """
+        # --- Read content ---
+        try:
+            content = self._read_source(source)
+        except (FileNotFoundError, ValueError) as exc:
+            return self._make_error_result(source, str(exc))
+
+        if not content or not content.strip():
+            return self._make_error_result(source, "Empty content — nothing to ingest.")
+
+        base_url: str = config.get("base_url", "") or ""
+        include_deprecated: bool = bool(config.get("include_deprecated", False))
+        include_subscriptions: bool = bool(config.get("include_subscriptions", True))
+
+        warnings: list[str] = []
+        endpoints: list[IngestedEndpoint] = []
+
+        # --- Detect and parse format ---
+        stripped = content.strip()
+        is_json = stripped.startswith("{") or stripped.startswith("[")
+
+        if is_json:
+            try:
+                data: dict[str, Any] = json.loads(content)
+            except json.JSONDecodeError as exc:
+                return self._make_error_result(
+                    source, f"Failed to parse JSON: {exc}"
+                )
+
+            schema = _unwrap_introspection(data)
+            if schema is None:
+                return self._make_error_result(
+                    source,
+                    "JSON content does not contain a GraphQL introspection "
+                    "result (__schema key not found).",
+                )
+
+            try:
+                endpoints = _endpoints_from_introspection(
+                    schema,
+                    base_url=base_url,
+                    include_deprecated=include_deprecated,
+                    include_subscriptions=include_subscriptions,
+                )
+            except Exception as exc:  # noqa: BLE001
+                return self._make_error_result(
+                    source, f"Failed to process introspection JSON: {exc}"
+                )
+        else:
+            # Treat as SDL
+            if not _is_sdl(content):
+                warnings.append(
+                    "Content does not appear to be valid GraphQL SDL; "
+                    "attempting to parse anyway."
+                )
+            try:
+                endpoints, sdl_warnings = _endpoints_from_sdl(
+                    content,
+                    base_url=base_url,
+                    include_deprecated=include_deprecated,
+                    include_subscriptions=include_subscriptions,
+                )
+                warnings.extend(sdl_warnings)
+            except Exception as exc:  # noqa: BLE001
+                return self._make_error_result(
+                    source, f"Failed to parse SDL schema: {exc}"
+                )
+
+        if not endpoints:
+            warnings.append(
+                "No operations found. Ensure the schema defines at least one "
+                "of: type Query, type Mutation, type Subscription."
+            )
+
+        # --- Generate test cases ---
+        test_cases: list[IngestedTestCase] = []
+        for ep in endpoints:
+            test_cases.extend(_generate_test_cases(ep))
+
+        # --- Stats ---
+        query_count = sum(1 for e in endpoints if e.method == "QUERY")
+        mutation_count = sum(1 for e in endpoints if e.method == "MUTATION")
+        subscription_count = sum(1 for e in endpoints if e.method == "SUBSCRIPTION")
+
+        stats: dict[str, Any] = {
+            "endpoints_count": len(endpoints),
+            "test_cases_count": len(test_cases),
+            "queries_count": query_count,
+            "mutations_count": mutation_count,
+            "subscriptions_count": subscription_count,
+            "base_url": base_url,
+        }
+
+        return IngestResult(
+            success=True,
+            source=source,
+            endpoints=endpoints,
+            test_cases=test_cases,
+            errors=[],
+            warnings=warnings,
+            stats=stats,
+        )