pytest-httpchain-jsonref 0.1.0__tar.gz

pytest_httpchain_jsonref-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: pytest-httpchain-jsonref
+Version: 0.1.0
+Summary: JSON reference ($ref) support for pytest-httpchain
+Author: Alexander Eresov
+Author-email: Alexander Eresov <aeresov@gmail.com>
+Requires-Dist: deepmerge>=2.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+

pytest_httpchain_jsonref-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "pytest-httpchain-jsonref"
+version = "0.1.0"
+description = "JSON reference ($ref) support for pytest-httpchain"
+readme = "README.md"
+requires-python = ">=3.13"
+authors = [{ name = "Alexander Eresov", email = "aeresov@gmail.com" }]
+dependencies = ["deepmerge>=2.0"]
+
+[build-system]
+requires = ["uv_build>=0.7.21,<0.8.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest-datadir>=1.7.2"]

pytest_httpchain_jsonref-0.1.0/src/pytest_httpchain_jsonref/exceptions.py

@@ -0,0 +1,2 @@
+class ReferenceResolverError(Exception):
+    """Base exception for reference resolution errors."""

pytest_httpchain_jsonref-0.1.0/src/pytest_httpchain_jsonref/loader.py

@@ -0,0 +1,23 @@
+"""JSON file loading with reference resolution."""
+
+from pathlib import Path
+from typing import Any
+
+from pytest_httpchain_jsonref.plumbing.reference import ReferenceResolver
+
+
+def load_json(path: Path, max_parent_traversal_depth: int = 3) -> dict[str, Any]:
+    """Load JSON from file and resolve all $ref statements with circular reference protection.
+
+    Args:
+        path: Path to the JSON file to load
+        max_parent_traversal_depth: Maximum number of parent directory traversals allowed in $ref paths
+
+    Returns:
+        Dictionary with all $ref statements resolved
+
+    Raises:
+        ReferenceResolverError: If the file cannot be loaded or parsed, if merge conflicts occur, or if circular references are detected
+    """
+    resolver = ReferenceResolver(max_parent_traversal_depth)
+    return resolver.resolve_file(path)

pytest_httpchain_jsonref-0.1.0/src/pytest_httpchain_jsonref/plumbing/circular.py

@@ -0,0 +1,69 @@
+"""Circular dependency tracking for reference resolution."""
+
+from pathlib import Path
+from typing import Self
+
+
+class CircularDependencyTracker:
+    """Tracks references to detect circular dependencies."""
+
+    def __init__(self):
+        self.external_refs: set[tuple[Path, str]] = set()
+        self.internal_refs: set[str] = set()
+
+    def check_external_ref(self, file_path: Path, pointer: str) -> None:
+        """Check if an external reference would create a circular dependency.
+
+        Args:
+            file_path: The file being referenced
+            pointer: The JSON pointer within the file
+
+        Raises:
+            RuntimeError: If a circular reference is detected
+        """
+        ref_key = (file_path, pointer)
+        if ref_key in self.external_refs:
+            raise RuntimeError(f"Circular reference detected: {file_path}#{pointer}")
+        self.external_refs.add(ref_key)
+
+    def check_internal_ref(self, pointer: str) -> None:
+        """Check if an internal reference would create a circular dependency.
+
+        Args:
+            pointer: The JSON pointer being referenced
+
+        Raises:
+            RuntimeError: If a circular reference is detected
+        """
+        if pointer in self.internal_refs:
+            raise RuntimeError(f"Circular reference detected: #{pointer}")
+        self.internal_refs.add(pointer)
+
+    def clear_external_ref(self, file_path: Path, pointer: str) -> None:
+        """Clear an external reference after processing.
+
+        Args:
+            file_path: The file that was referenced
+            pointer: The JSON pointer that was referenced
+        """
+        ref_key = (file_path, pointer)
+        self.external_refs.discard(ref_key)
+
+    def clear_internal_ref(self, pointer: str) -> None:
+        """Clear an internal reference after processing.
+
+        Args:
+            pointer: The JSON pointer that was referenced
+        """
+        self.internal_refs.discard(pointer)
+
+    def create_child_tracker(self) -> Self:
+        """Create a child tracker that inherits current state.
+
+        Returns:
+            A new tracker with copies of the current reference sets
+        """
+        child = CircularDependencyTracker()
+        child.external_refs = self.external_refs.copy()
+        child.internal_refs = self.internal_refs.copy()
+        return child

pytest_httpchain_jsonref-0.1.0/src/pytest_httpchain_jsonref/plumbing/path.py

@@ -0,0 +1,70 @@
+"""Path validation utilities for reference resolution."""
+
+from pathlib import Path
+
+from pytest_httpchain_jsonref.exceptions import ReferenceResolverError
+
+
+class PathValidator:
+    """Validates paths for security and correctness."""
+
+    @staticmethod
+    def validate_ref_path(ref_path: str, base_path: Path, root_path: Path, max_parent_traversal_depth: int) -> Path:
+        """Validate and resolve a reference path.
+
+        Args:
+            ref_path: The reference path to validate
+            base_path: The base path to resolve relative references from
+            root_path: The root path that references should not escape
+            max_parent_traversal_depth: Maximum allowed parent directory traversals
+
+        Returns:
+            The resolved absolute path
+
+        Raises:
+            ReferenceResolverError: If the path is invalid or violates security constraints
+        """
+        # Count parent traversals before resolution
+        parent_traversals = sum(1 for part in Path(ref_path).parts if part == "..")
+
+        if parent_traversals > max_parent_traversal_depth:
+            raise ReferenceResolverError(f"Reference path '{ref_path}' exceeds maximum parent traversal depth of {max_parent_traversal_depth}")
+
+        # Resolve and validate path containment
+        resolved_path = (base_path / ref_path).resolve()
+        root_path_resolved = root_path.resolve()
+
+        try:
+            resolved_path.relative_to(root_path_resolved)
+        except ValueError:
+            raise ReferenceResolverError(f"Reference path '{ref_path}' points outside allowed directory tree") from None
+
+        return resolved_path
+
+    @staticmethod
+    def parse_json_pointer(pointer: str) -> list[str]:
+        """Parse a JSON pointer into path components.
+
+        Args:
+            pointer: JSON pointer string (e.g., "/path/to/node")
+
+        Returns:
+            List of path components
+
+        Raises:
+            ReferenceResolverError: If the pointer is invalid
+        """
+        if not pointer:
+            return []
+
+        if not pointer.startswith("/"):
+            raise ReferenceResolverError(f"Invalid JSON pointer: {pointer} (must start with '/')")
+
+        # Split by / and handle escaped characters
+        parts = []
+        for part in pointer[1:].split("/"):
+            # Unescape JSON pointer escape sequences
+            part = part.replace("~1", "/").replace("~0", "~")
+            parts.append(part)
+
+        return parts

pytest_httpchain_jsonref-0.1.0/src/pytest_httpchain_jsonref/plumbing/reference.py

@@ -0,0 +1,212 @@
+"""Reference resolution for JSON files."""
+
+import json
+import re
+from functools import reduce
+from pathlib import Path
+from typing import Any, Self
+
+from deepmerge import always_merger
+
+from pytest_httpchain_jsonref.exceptions import ReferenceResolverError
+from pytest_httpchain_jsonref.plumbing.circular import CircularDependencyTracker
+from pytest_httpchain_jsonref.plumbing.path import PathValidator
+
+REF_PATTERN = re.compile(r"^(?P<file>[^#]+)?(?:#(?P<pointer>/.*))?$")
+
+
+class ReferenceResolver:
+    """Resolves JSON references ($ref) in documents."""
+
+    def __init__(self, max_parent_traversal_depth: int = 3):
+        self.max_parent_traversal_depth = max_parent_traversal_depth
+        self.path_validator = PathValidator()
+        self.tracker = CircularDependencyTracker()
+        self.base_path: Path | None = None
+        self.root_path: Path | None = None
+        self._cache: dict[tuple[Path, str], Any] = {}
+
+    def resolve_document(self, data: dict[str, Any], base_path: Path) -> dict[str, Any]:
+        """Resolve all references in a document.
+
+        Args:
+            data: The document data to resolve references in
+            base_path: The base path for resolving relative references
+
+        Returns:
+            The document with all references resolved
+
+        Raises:
+            ReferenceResolverError: If resolution fails
+        """
+        self.base_path = base_path
+        return self._resolve_refs(data, base_path, root_data=data)
+
+    def resolve_file(self, path: Path) -> dict[str, Any]:
+        """Load a JSON file and resolve all references.
+
+        Args:
+            path: Path to the JSON file to load
+
+        Returns:
+            The loaded document with all references resolved
+
+        Raises:
+            ReferenceResolverError: If the file cannot be loaded or references cannot be resolved
+        """
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+
+            self.root_path = path.parent
+            return self.resolve_document(data, path.parent)
+
+        except (OSError, json.JSONDecodeError) as e:
+            raise ReferenceResolverError(f"Failed to load JSON from {path}: {e}") from e
+
+    def _resolve_refs(
+        self,
+        data: Any,
+        current_path: Path,
+        root_data: Any,
+    ) -> Any:
+        match data:
+            case dict() if "$ref" in data:
+                return self._resolve_single_ref(data, current_path, root_data)
+            case dict():
+                return {key: self._resolve_refs(value, current_path, root_data) for key, value in data.items()}
+            case list():
+                return [self._resolve_refs(item, current_path, root_data) for item in data]
+            case _:
+                return data
+
+    def _resolve_single_ref(
+        self,
+        data: dict[str, Any],
+        current_path: Path,
+        root_data: Any,
+    ) -> Any:
+        ref_value = data["$ref"]
+        match = REF_PATTERN.match(ref_value)
+
+        if not match:
+            raise ReferenceResolverError(f"Invalid $ref format: {ref_value}")
+
+        file_path = match.group("file")
+        pointer = match.group("pointer") or ""
+
+        if file_path:
+            referenced_data = self._resolve_external_ref(file_path, pointer, current_path)
+        else:
+            referenced_data = self._resolve_internal_ref(pointer, root_data)
+
+        return self._merge_with_siblings(data, referenced_data, current_path, root_data)
+
+    def _resolve_external_ref(
+        self,
+        file_path: str,
+        pointer: str,
+        current_path: Path,
+    ) -> Any:
+        resolved_path = self.path_validator.validate_ref_path(file_path, current_path, self.root_path or current_path, self.max_parent_traversal_depth)
+
+        cache_key = (resolved_path, pointer)
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        self.tracker.check_external_ref(resolved_path, pointer)
+
+        try:
+            full_external_data = self._load_json_file(resolved_path)
+            external_data = self._navigate_pointer(full_external_data, pointer) if pointer else full_external_data
+
+            child_resolver = self._create_child_resolver()
+            result = child_resolver._resolve_refs(external_data, resolved_path.parent, root_data=full_external_data)
+            self._cache[cache_key] = result
+            return result
+
+        except (OSError, json.JSONDecodeError) as e:
+            raise ReferenceResolverError(f"Failed to load external reference {file_path}: {e}") from e
+        finally:
+            self.tracker.clear_external_ref(resolved_path, pointer)
+
+    def _resolve_internal_ref(
+        self,
+        pointer: str,
+        root_data: Any,
+    ) -> Any:
+        self.tracker.check_internal_ref(pointer)
+
+        try:
+            referenced_data = self._navigate_pointer(root_data, pointer)
+            return self._resolve_refs(referenced_data, self.base_path, root_data)
+        finally:
+            self.tracker.clear_internal_ref(pointer)
+
+    def _navigate_pointer(self, data: Any, pointer: str) -> Any:
+        if not pointer:
+            return data
+
+        parts = self.path_validator.parse_json_pointer(pointer)
+
+        try:
+            return reduce(lambda obj, key: obj[int(key)] if isinstance(obj, list) else obj[key], parts, data)
+        except (KeyError, IndexError, ValueError, TypeError) as e:
+            raise ReferenceResolverError(f"Invalid JSON pointer {pointer}: {e}") from e
+
+    def _merge_with_siblings(
+        self,
+        ref_dict: dict[str, Any],
+        referenced_data: Any,
+        current_path: Path,
+        root_data: Any,
+    ) -> Any:
+        siblings = {k: v for k, v in ref_dict.items() if k != "$ref"}
+
+        if not siblings:
+            return referenced_data
+
+        if not isinstance(referenced_data, dict):
+            if len(siblings) > 0:
+                raise ReferenceResolverError("Cannot merge non-dict reference with sibling properties")
+            return referenced_data
+
+        resolved_siblings = self._resolve_refs(siblings, current_path, root_data)
+
+        self._detect_merge_conflicts(referenced_data, resolved_siblings)
+
+        return always_merger.merge(referenced_data, resolved_siblings)
+
+    def _load_json_file(self, path: Path) -> dict[str, Any]:
+        """Load and cache JSON file content."""
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+
+    def _create_child_resolver(self) -> Self:
+        """Create a child resolver with inherited state."""
+        child_resolver = type(self)(self.max_parent_traversal_depth)
+        child_resolver.tracker = self.tracker.create_child_tracker()
+        child_resolver.root_path = self.root_path
+        child_resolver._cache = self._cache.copy()
+        return child_resolver
+
+    def _detect_merge_conflicts(
+        self,
+        base: Any,
+        overlay: Any,
+        path: str = "",
+    ) -> None:
+        if base is None or overlay is None or base == overlay:
+            return
+
+        if isinstance(base, dict) and isinstance(overlay, dict):
+            for key, value in overlay.items():
+                if key in base:
+                    new_path = f"{path}.{key}" if path else key
+                    self._detect_merge_conflicts(base[key], value, new_path)
+            return
+
+        if isinstance(base, list) and isinstance(overlay, list):
+            return
+
+        raise ReferenceResolverError(f"Merge conflict at {path if path else 'root'}")