invar-tools 1.0.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

invar_tools-1.3.0.dist-info/licenses/NOTICE

@@ -0,0 +1,63 @@
+Invar
+Copyright 2025 Invar Contributors
+
+This product includes software developed by the Invar project
+(https://github.com/Tefx/Invar).
+
+================================================================================
+
+This project uses the following third-party libraries:
+
+--------------------------------------------------------------------------------
+deal - Design by Contract library
+License: LGPL-3.0-or-later
+https://github.com/life4/deal
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+hypothesis - Property-based testing library
+License: MPL-2.0
+https://github.com/HypothesisWorks/hypothesis
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+crosshair-tool - Symbolic execution analysis
+License: MIT
+https://github.com/pschanely/CrossHair
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+typer - CLI framework
+License: MIT
+https://github.com/tiangolo/typer
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+rich - Terminal formatting library
+License: MIT
+https://github.com/Textualize/rich
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+pydantic - Data validation library
+License: MIT
+https://github.com/pydantic/pydantic
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+returns - Functional programming primitives
+License: BSD-2-Clause
+https://github.com/dry-python/returns
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+mcp - Model Context Protocol SDK
+License: MIT
+https://github.com/modelcontextprotocol/python-sdk
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+pre-commit - Git hooks framework
+License: MIT
+https://github.com/pre-commit/pre-commit
+--------------------------------------------------------------------------------

invar/contracts.py

@@ -1,152 +0,0 @@
-"""
-Composable contracts for Invar.
-
-Provides Contract class with &, |, ~ operators for combining conditions,
-and a standard library of common predicates. Works with deal decorators.
-
-Inspired by Idris' dependent types.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
-
-import deal
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-
-@dataclass
-class Contract:
-    """
-    Composable contract with &, |, ~ operators.
-
-    Contracts encapsulate predicates that can be combined and reused.
-    Works with deal.pre for runtime checking.
-
-    Examples:
-        >>> NonEmpty = Contract(lambda x: len(x) > 0, "non-empty")
-        >>> Sorted = Contract(lambda x: list(x) == sorted(x), "sorted")
-        >>> combined = NonEmpty & Sorted
-        >>> combined.check([1, 2, 3])
-        True
-        >>> combined.check([])
-        False
-        >>> combined.check([3, 1, 2])
-        False
-        >>> (NonEmpty | Sorted).check([])  # Empty but sorted
-        True
-        >>> (~NonEmpty).check([])  # NOT non-empty
-        True
-    """
-
-    predicate: Callable[[Any], bool]
-    description: str
-
-    def check(self, value: Any) -> bool:
-        """Check if value satisfies the contract."""
-        return self.predicate(value)
-
-    def __and__(self, other: Contract) -> Contract:
-        """Combine contracts with AND."""
-        return Contract(
-            predicate=lambda x: self.check(x) and other.check(x),
-            description=f"({self.description} AND {other.description})",
-        )
-
-    def __or__(self, other: Contract) -> Contract:
-        """Combine contracts with OR."""
-        return Contract(
-            predicate=lambda x: self.check(x) or other.check(x),
-            description=f"({self.description} OR {other.description})",
-        )
-
-    def __invert__(self) -> Contract:
-        """Negate the contract."""
-        return Contract(
-            predicate=lambda x: not self.check(x),
-            description=f"NOT({self.description})",
-        )
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        """Allow using as deal.pre predicate directly."""
-        value = args[0] if args else next(iter(kwargs.values()))
-        return self.check(value)
-
-    def __repr__(self) -> str:
-        return f"Contract({self.description!r})"
-
-
-def pre(*contracts: Contract) -> Callable[[Callable], Callable]:
-    """
-    Decorator accepting Contract objects for preconditions.
-
-    Works with deal.pre under the hood.
-
-    Examples:
-        >>> from invar.contracts import pre, NonEmpty
-        >>> @pre(NonEmpty)
-        ... def first(xs): return xs[0]
-        >>> first([1, 2, 3])
-        1
-    """
-
-    def combined(*args: Any, **kwargs: Any) -> bool:
-        value = args[0] if args else next(iter(kwargs.values()))
-        return all(c.check(value) for c in contracts)
-
-    return deal.pre(combined)
-
-
-def post(*contracts: Contract) -> Callable[[Callable], Callable]:
-    """
-    Decorator accepting Contract objects for postconditions.
-
-    Works with deal.post under the hood.
-
-    Examples:
-        >>> from invar.contracts import post, NonEmpty
-        >>> @post(NonEmpty)
-        ... def get_list(): return [1]
-        >>> get_list()
-        [1]
-    """
-
-    def combined(result: Any) -> bool:
-        return all(c.check(result) for c in contracts)
-
-    return deal.post(combined)
-
-
-# =============================================================================
-# Standard Library of Contracts
-# =============================================================================
-
-# --- Collections ---
-NonEmpty: Contract = Contract(lambda x: len(x) > 0, "non-empty")
-Sorted: Contract = Contract(lambda x: list(x) == sorted(x), "sorted")
-Unique: Contract = Contract(lambda x: len(x) == len(set(x)), "unique")
-SortedNonEmpty: Contract = NonEmpty & Sorted
-
-# --- Numbers ---
-Positive: Contract = Contract(lambda x: x > 0, "positive")
-NonNegative: Contract = Contract(lambda x: x >= 0, "non-negative")
-Negative: Contract = Contract(lambda x: x < 0, "negative")
-
-
-def InRange(lo: float, hi: float) -> Contract:
-    """Create a contract checking value is in [lo, hi]."""
-    return Contract(lambda x: lo <= x <= hi, f"[{lo},{hi}]")
-
-
-Percentage: Contract = InRange(0, 100)
-
-# --- Strings ---
-NonBlank: Contract = Contract(lambda s: bool(s and s.strip()), "non-blank")
-
-# --- Lists with elements ---
-AllPositive: Contract = Contract(lambda xs: all(x > 0 for x in xs), "all positive")
-AllNonNegative: Contract = Contract(lambda xs: all(x >= 0 for x in xs), "all non-negative")
-NoNone: Contract = Contract(lambda xs: None not in xs, "no None")

invar/decorators.py

@@ -1,94 +0,0 @@
-"""
-Invar contract decorators.
-
-Provides decorators that extend deal's contract system for additional
-static analysis by Guard.
-
-DX-12-B: Added @strategy for custom Hypothesis strategies.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import Any, TypeVar
-
-F = TypeVar("F", bound=Callable)
-
-
-def must_use(reason: str | None = None) -> Callable[[F], F]:
-    """
-    Mark a function's return value as must-use.
-
-    Guard will warn if calls to this function discard the return value.
-    Inspired by Move's lack of drop ability and Rust's #[must_use].
-
-    Args:
-        reason: Explanation of why the return value must be used.
-
-    Returns:
-        A decorator that marks the function.
-
-    >>> @must_use("Error must be handled")
-    ... def may_fail() -> int:
-    ...     return 42
-    >>> may_fail.__invar_must_use__
-    'Error must be handled'
-
-    >>> @must_use()
-    ... def important() -> str:
-    ...     return "result"
-    >>> important.__invar_must_use__
-    'Return value must be used'
-    """
-
-    def decorator(func: F) -> F:
-        func.__invar_must_use__ = reason or "Return value must be used"  # type: ignore[attr-defined]
-        return func
-
-    return decorator
-
-
-def strategy(**param_strategies: Any) -> Callable[[F], F]:
-    """
-    Specify custom Hypothesis strategies for function parameters.
-
-    DX-12-B: Escape hatch when automatic strategy inference fails or
-    when you need precise control over generated values.
-
-    Args:
-        **param_strategies: Mapping of parameter names to Hypothesis strategies.
-
-    Returns:
-        A decorator that attaches strategies to the function.
-
-    Examples:
-        >>> from hypothesis import strategies as st
-        >>> @strategy(x=st.floats(min_value=1e-10, max_value=1e10))
-        ... def sqrt(x: float) -> float:
-        ...     return x ** 0.5
-        >>> hasattr(sqrt, '__invar_strategies__')
-        True
-        >>> 'x' in sqrt.__invar_strategies__
-        True
-
-        >>> # NumPy array with specific shape
-        >>> @strategy(arr="arrays(dtype=float64, shape=(10,))")
-        ... def normalize(arr):
-        ...     return arr / arr.sum()
-        >>> 'arr' in normalize.__invar_strategies__
-        True
-
-    Note:
-        Strategies can be either:
-        - Hypothesis strategy objects (e.g., st.floats())
-        - String representations (e.g., "floats(min_value=0)")
-
-        String representations are useful when you don't want to import
-        Hypothesis at module load time.
-    """
-
-    def decorator(func: F) -> F:
-        func.__invar_strategies__ = param_strategies  # type: ignore[attr-defined]
-        return func
-
-    return decorator

invar/invariant.py

@@ -1,57 +0,0 @@
-"""
-Loop invariant support for Invar.
-
-Provides runtime-checked loop invariants inspired by Dafny.
-Checking controlled by INVAR_CHECK environment variable (default: ON).
-"""
-
-from __future__ import annotations
-
-import os
-
-
-class InvariantViolation(Exception):
-    """Raised when a loop invariant is violated."""
-
-    pass
-
-
-# Read once at module load time - effectively a constant
-_INVAR_CHECK = os.environ.get("INVAR_CHECK", "1") == "1"
-
-
-def invariant(condition: bool, message: str = "") -> None:
-    """
-    Assert loop invariant. Checked at runtime when INVAR_CHECK=1.
-
-    Place at the START of loop body to check condition each iteration.
-    Invariants document what must remain true throughout loop execution.
-
-    Args:
-        condition: Boolean condition that must hold
-        message: Optional message describing the invariant
-
-    Raises:
-        InvariantViolation: When condition is False and INVAR_CHECK=1
-
-    Examples:
-        >>> invariant(True)  # OK
-
-        >>> invariant(True, "x is positive")  # OK with message
-
-        >>> try:
-        ...     invariant(False, "x must be positive")
-        ... except InvariantViolation as e:
-        ...     print(str(e))
-        Loop invariant violated: x must be positive
-
-    Typical usage in a binary search:
-
-        while lo < hi:
-            invariant(0 <= lo <= hi <= len(arr))
-            invariant(target not in arr[:lo])  # Already searched
-            ...
-    """
-    if _INVAR_CHECK and not condition:
-        msg = f"Loop invariant violated: {message}" if message else "Loop invariant violated"
-        raise InvariantViolation(msg)

invar/resource.py

@@ -1,99 +0,0 @@
-"""
-Resource management decorators for Invar.
-
-Provides @must_close for marking classes that require explicit cleanup.
-Inspired by Move language's resource semantics.
-"""
-
-from __future__ import annotations
-
-from typing import Any, TypeVar
-
-T = TypeVar("T")
-
-
-class ResourceWarning(UserWarning):
-    """Warning raised when a resource may not be properly closed."""
-
-    pass
-
-
-class MustCloseViolation(Exception):
-    """Raised when a @must_close resource is not properly managed."""
-
-    pass
-
-
-def must_close(cls: type[T]) -> type[T]:
-    """
-    Mark a class as a resource that must be explicitly closed.
-
-    The decorated class should have a `close()` method. The decorator:
-    1. Adds __invar_must_close__ marker for Guard detection
-    2. Adds context manager protocol if not present
-
-    Examples:
-        >>> @must_close
-        ... class TempFile:
-        ...     def __init__(self, path: str):
-        ...         self.path = path
-        ...         self.closed = False
-        ...     def write(self, data: str) -> None:
-        ...         if self.closed:
-        ...             raise ValueError("File is closed")
-        ...     def close(self) -> None:
-        ...         self.closed = True
-
-        >>> # Preferred: use as context manager
-        >>> with TempFile("test.txt") as f:
-        ...     f.write("hello")
-        >>> f.closed
-        True
-
-        >>> # Also works: explicit close
-        >>> f2 = TempFile("test2.txt")
-        >>> f2.write("world")
-        >>> f2.close()
-        >>> f2.closed
-        True
-    """
-    # Mark for Guard detection
-    cls.__invar_must_close__ = True  # type: ignore[attr-defined]
-
-    # Add context manager protocol if not present
-    if not hasattr(cls, "__enter__"):
-
-        def __enter__(self: Any) -> Any:
-            return self
-
-        cls.__enter__ = __enter__  # type: ignore[attr-defined]
-
-    if not hasattr(cls, "__exit__"):
-
-        def __exit__(self: Any, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
-            if hasattr(self, "close") and callable(self.close):
-                self.close()
-
-        cls.__exit__ = __exit__  # type: ignore[attr-defined]
-
-    return cls
-
-
-def is_must_close(cls_or_obj: Any) -> bool:
-    """
-    Check if a class or instance is marked with @must_close.
-
-    >>> @must_close
-    ... class Resource:
-    ...     def close(self): pass
-    >>> is_must_close(Resource)
-    True
-    >>> is_must_close(Resource())
-    True
-    >>> class Plain: pass
-    >>> is_must_close(Plain)
-    False
-    """
-    if isinstance(cls_or_obj, type):
-        return getattr(cls_or_obj, "__invar_must_close__", False)
-    return getattr(type(cls_or_obj), "__invar_must_close__", False)

invar/shell/prove_fallback.py

@@ -1,183 +0,0 @@
-"""
-Hypothesis fallback for proof verification.
-
-DX-12: Provides Hypothesis as automatic fallback when CrossHair
-is unavailable, times out, or skips files.
-"""
-
-from __future__ import annotations
-
-import subprocess
-import sys
-from pathlib import Path
-
-from returns.result import Failure, Result, Success
-
-
-def run_hypothesis_fallback(
-    files: list[Path],
-    max_examples: int = 100,
-) -> Result[dict, str]:
-    """
-    Run Hypothesis property tests as fallback when CrossHair skips/times out.
-
-    DX-12: Uses inferred strategies from type hints and @pre contracts.
-
-    Args:
-        files: List of Python file paths to test
-        max_examples: Maximum examples per test
-
-    Returns:
-        Success with test results or Failure with error message
-    """
-    # Import CrossHairStatus here to avoid circular import
-    from invar.shell.prove import CrossHairStatus
-
-    # Check if hypothesis is available
-    try:
-        import hypothesis  # noqa: F401
-    except ImportError:
-        return Success(
-            {
-                "status": CrossHairStatus.SKIPPED,
-                "reason": "Hypothesis not installed (pip install hypothesis)",
-                "files": [],
-                "tool": "hypothesis",
-            }
-        )
-
-    if not files:
-        return Success(
-            {
-                "status": CrossHairStatus.SKIPPED,
-                "reason": "no files",
-                "files": [],
-                "tool": "hypothesis",
-            }
-        )
-
-    # Filter to Python files only
-    py_files = [f for f in files if f.suffix == ".py" and f.exists()]
-    if not py_files:
-        return Success(
-            {
-                "status": CrossHairStatus.SKIPPED,
-                "reason": "no Python files",
-                "files": [],
-                "tool": "hypothesis",
-            }
-        )
-
-    # Use pytest with hypothesis
-    cmd = [
-        sys.executable,
-        "-m",
-        "pytest",
-        "--hypothesis-show-statistics",
-        "--hypothesis-seed=0",  # Reproducible
-        "-x",  # Stop on first failure
-        "--tb=short",
-    ]
-    cmd.extend(str(f) for f in py_files)
-
-    try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
-        # Pytest exit codes: 0=passed, 5=no tests collected
-        is_passed = result.returncode in (0, 5)
-        return Success(
-            {
-                "status": "passed" if is_passed else "failed",
-                "files": [str(f) for f in py_files],
-                "exit_code": result.returncode,
-                "stdout": result.stdout,
-                "stderr": result.stderr,
-                "tool": "hypothesis",
-                "note": "Fallback from CrossHair",
-            }
-        )
-    except subprocess.TimeoutExpired:
-        return Failure("Hypothesis timeout (300s)")
-    except Exception as e:
-        return Failure(f"Hypothesis error: {e}")
-
-
-def run_prove_with_fallback(
-    files: list[Path],
-    crosshair_timeout: int = 10,
-    hypothesis_max_examples: int = 100,
-    use_cache: bool = True,
-    cache_dir: Path | None = None,
-) -> Result[dict, str]:
-    """
-    Run proof verification with automatic Hypothesis fallback.
-
-    DX-12 + DX-13: Tries CrossHair first with optimizations, falls back to Hypothesis.
-
-    Args:
-        files: List of Python file paths to verify
-        crosshair_timeout: Ignored (kept for backwards compatibility)
-        hypothesis_max_examples: Maximum Hypothesis examples
-        use_cache: Whether to use verification cache (DX-13)
-        cache_dir: Cache directory (default: .invar/cache/prove)
-
-    Returns:
-        Success with verification results or Failure with error message
-    """
-    # Import here to avoid circular import
-    from invar.shell.prove import CrossHairStatus, run_crosshair_parallel
-    from invar.shell.prove_cache import ProveCache
-
-    # DX-13: Initialize cache
-    cache = None
-    if use_cache:
-        if cache_dir is None:
-            cache_dir = Path(".invar/cache/prove")
-        cache = ProveCache(cache_dir=cache_dir)
-
-    # DX-13: Use parallel CrossHair with caching
-    crosshair_result = run_crosshair_parallel(
-        files,
-        max_iterations=5,  # Fast mode
-        max_workers=None,  # Auto-detect
-        cache=cache,
-    )
-
-    if isinstance(crosshair_result, Failure):
-        # CrossHair failed, try Hypothesis
-        return run_hypothesis_fallback(files, max_examples=hypothesis_max_examples)
-
-    result_data = crosshair_result.unwrap()
-    status = result_data.get("status", "")
-
-    # Check if we need fallback
-    needs_fallback = (
-        status == CrossHairStatus.SKIPPED
-        or status == CrossHairStatus.TIMEOUT
-        or "not installed" in result_data.get("reason", "")
-    )
-
-    if needs_fallback:
-        # Run Hypothesis as fallback
-        hypothesis_result = run_hypothesis_fallback(
-            files, max_examples=hypothesis_max_examples
-        )
-
-        if isinstance(hypothesis_result, Success):
-            hyp_data = hypothesis_result.unwrap()
-            # Merge results
-            return Success(
-                {
-                    "status": hyp_data.get("status", "unknown"),
-                    "primary_tool": "hypothesis",
-                    "crosshair_status": status,
-                    "crosshair_reason": result_data.get("reason", ""),
-                    "hypothesis_result": hyp_data,
-                    "files": [str(f) for f in files],
-                    "note": "CrossHair skipped/unavailable, used Hypothesis fallback",
-                }
-            )
-        return hypothesis_result
-
-    # CrossHair succeeded (verified or found counterexample)
-    result_data["primary_tool"] = "crosshair"
-    return Success(result_data)