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

invar/shell/mutation.py

@@ -0,0 +1,314 @@
+"""
+Mutation testing integration for Invar.
+
+DX-28: Wraps mutmut to detect undertested code by automatically
+mutating code (e.g., `in` → `not in`) and checking if tests catch it.
+
+Shell module: handles subprocess execution and result parsing.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from returns.result import Failure, Result, Success
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@dataclass
+class MutationResult:
+    """Results from mutation testing.
+
+    Examples:
+        >>> result = MutationResult(total=10, killed=8, survived=2)
+        >>> result.score
+        80.0
+        >>> result.passed
+        True
+    """
+
+    total: int = 0
+    killed: int = 0
+    survived: int = 0
+    timeout: int = 0
+    suspicious: int = 0
+    errors: list[str] = field(default_factory=list)
+    survivors: list[str] = field(default_factory=list)
+
+    @property
+    def score(self) -> float:
+        """Mutation score as percentage.
+
+        Examples:
+            >>> MutationResult(total=10, killed=10).score
+            100.0
+            >>> MutationResult(total=0).score
+            100.0
+        """
+        if self.total == 0:
+            return 100.0
+        return (self.killed / self.total) * 100
+
+    @property
+    def passed(self) -> bool:
+        """Check if mutation score meets threshold (80%).
+
+        Examples:
+            >>> MutationResult(total=10, killed=8).passed
+            True
+            >>> MutationResult(total=10, killed=7).passed
+            False
+        """
+        return self.score >= 80.0
+
+
+def check_mutmut_installed() -> Result[str, str]:
+    """
+    Check if mutmut is installed.
+
+    Returns:
+        Success with version or Failure with install instructions.
+
+    Examples:
+        >>> result = check_mutmut_installed()
+        >>> isinstance(result, (Success, Failure))
+        True
+    """
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "mutmut", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0:
+            version = result.stdout.strip() or "installed"
+            return Success(version)
+        return Failure("mutmut not installed. Run: pip install mutmut")
+    except subprocess.TimeoutExpired:
+        return Failure("mutmut check timed out")
+    except Exception as e:
+        return Failure(f"mutmut check failed: {e}")
+
+
+# @shell_complexity: Subprocess execution with result parsing
+def run_mutation_test(
+    target: Path,
+    tests: Path | None = None,
+    timeout: int = 300,
+) -> Result[MutationResult, str]:
+    """
+    Run mutation testing on a target file or directory.
+
+    Uses mutmut to generate mutations and run tests against them.
+
+    Args:
+        target: File or directory to mutate
+        tests: Test file or directory (auto-detected if None)
+        timeout: Maximum time in seconds
+
+    Returns:
+        Success with MutationResult or Failure with error message
+
+    Examples:
+        >>> # This is a shell function - actual behavior depends on mutmut
+        >>> from pathlib import Path
+        >>> result = run_mutation_test(Path("nonexistent.py"))
+        >>> isinstance(result, Failure)
+        True
+    """
+    # Check mutmut is installed
+    install_check = check_mutmut_installed()
+    if isinstance(install_check, Failure):
+        return install_check  # type: ignore[return-value]
+
+    # Validate target
+    if not target.exists():
+        return Failure(f"Target not found: {target}")
+
+    # Build command
+    cmd = [
+        sys.executable,
+        "-m",
+        "mutmut",
+        "run",
+        "--paths-to-mutate",
+        str(target),
+        "--no-progress",
+    ]
+
+    if tests:
+        cmd.extend(["--tests-dir", str(tests)])
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=target.parent if target.is_file() else target,
+        )
+
+        # Parse results
+        return parse_mutmut_output(result.stdout, result.stderr, result.returncode)
+
+    except subprocess.TimeoutExpired:
+        return Failure(f"Mutation testing timed out after {timeout}s")
+    except Exception as e:
+        return Failure(f"Mutation testing failed: {e}")
+
+
+# @shell_complexity: Output parsing with multiple formats
+def parse_mutmut_output(
+    stdout: str,
+    stderr: str,
+    returncode: int,
+) -> Result[MutationResult, str]:
+    """
+    Parse mutmut output into MutationResult.
+
+    Args:
+        stdout: Standard output from mutmut
+        stderr: Standard error from mutmut
+        returncode: Exit code from mutmut
+
+    Returns:
+        Success with parsed results or Failure with error
+
+    Examples:
+        >>> result = parse_mutmut_output("", "", 0)
+        >>> isinstance(result, Success)
+        True
+    """
+    result = MutationResult()
+
+    # Parse summary line: "X killed, Y survived, Z timeout"
+    for line in stdout.split("\n"):
+        line = line.strip().lower()
+
+        if "killed" in line:
+            # Try to extract numbers
+            parts = line.split()
+            for i, part in enumerate(parts):
+                if part.isdigit():
+                    next_word = parts[i + 1] if i + 1 < len(parts) else ""
+                    if "killed" in next_word:
+                        result.killed = int(part)
+                    elif "survived" in next_word:
+                        result.survived = int(part)
+                    elif "timeout" in next_word:
+                        result.timeout = int(part)
+
+        if "mutants" in line and "total" in line:
+            parts = line.split()
+            for _, part in enumerate(parts):
+                if part.isdigit():
+                    result.total = int(part)
+                    break
+
+    # If we couldn't parse, try alternative format
+    if result.total == 0:
+        # mutmut results show format: "Killed: X, Survived: Y"
+        for line in stdout.split("\n"):
+            if "Killed:" in line:
+                with contextlib.suppress(ValueError, IndexError):
+                    result.killed = int(line.split("Killed:")[1].split(",")[0].strip())
+            if "Survived:" in line:
+                with contextlib.suppress(ValueError, IndexError):
+                    result.survived = int(
+                        line.split("Survived:")[1].split(",")[0].strip()
+                    )
+
+        result.total = result.killed + result.survived + result.timeout
+
+    # Check for errors
+    if stderr and "error" in stderr.lower():
+        result.errors.append(stderr.strip())
+
+    return Success(result)
+
+
+# @shell_complexity: Multi-step command execution
+def get_surviving_mutants(target: Path) -> Result[list[str], str]:
+    """
+    Get list of surviving mutants from last run.
+
+    Args:
+        target: Target that was mutated
+
+    Returns:
+        Success with list of survivor descriptions or Failure
+
+    Examples:
+        >>> from pathlib import Path
+        >>> result = get_surviving_mutants(Path("."))
+        >>> isinstance(result, (Success, Failure))
+        True
+    """
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "mutmut", "results"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+
+        survivors = []
+        in_survivors = False
+
+        for line in result.stdout.split("\n"):
+            if "Survived" in line:
+                in_survivors = True
+                continue
+            if in_survivors and line.strip():
+                if line.startswith("  "):
+                    survivors.append(line.strip())
+                elif not line.startswith(" "):
+                    in_survivors = False
+
+        return Success(survivors)
+
+    except subprocess.TimeoutExpired:
+        return Failure("Results query timed out")
+    except Exception as e:
+        return Failure(f"Failed to get results: {e}")
+
+
+# @shell_orchestration: Show mutant diff for investigation
+def show_mutant(mutant_id: int) -> Result[str, str]:
+    """
+    Show the diff for a specific mutant.
+
+    Args:
+        mutant_id: The mutant ID to show
+
+    Returns:
+        Success with diff output or Failure
+
+    Examples:
+        >>> result = show_mutant(1)
+        >>> isinstance(result, (Success, Failure))
+        True
+    """
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "mutmut", "show", str(mutant_id)],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        if result.returncode == 0:
+            return Success(result.stdout)
+        return Failure(f"Mutant {mutant_id} not found")
+
+    except subprocess.TimeoutExpired:
+        return Failure("Show mutant timed out")
+    except Exception as e:
+        return Failure(f"Failed to show mutant: {e}")

invar/shell/property_tests.py

@@ -26,6 +26,7 @@ if TYPE_CHECKING:
 console = Console()
 
 
+# @shell_complexity: Property test orchestration with module import
 def run_property_tests_on_file(
     file_path: Path,
     max_examples: int = 100,
@@ -72,6 +73,7 @@ def run_property_tests_on_file(
 
     # Run tests on each contracted function
     report = PropertyTestReport()
+    file_path_str = str(file_path)  # DX-26: For actionable output
 
     for func_info in contracted:
         func_name = func_info["name"]
@@ -83,6 +85,8 @@ def run_property_tests_on_file(
 
         # Run property test
         result = run_property_test(func, max_examples)
+        # DX-26: Set file_path for actionable failure output
+        result.file_path = file_path_str
         report.results.append(result)
         report.functions_tested += 1
         report.total_examples += result.examples_run
@@ -95,11 +99,13 @@ def run_property_tests_on_file(
     return Success(report)
 
 
+# @shell_complexity: Property test orchestration with optional coverage collection
 def run_property_tests_on_files(
     files: list[Path],
     max_examples: int = 100,
     verbose: bool = False,
-) -> Result[PropertyTestReport, str]:
+    collect_coverage: bool = False,
+) -> Result[tuple[PropertyTestReport, dict | None], str]:
     """
     Run property tests on multiple files.
 
@@ -107,37 +113,71 @@ def run_property_tests_on_files(
         files: List of Python file paths
         max_examples: Maximum Hypothesis examples per function
         verbose: Show detailed output
+        collect_coverage: DX-37: If True, collect branch coverage data
 
     Returns:
-        Combined PropertyTestReport
+        Tuple of (PropertyTestReport, coverage_data) where coverage_data is dict or None
     """
     # Check hypothesis availability first
     try:
         import hypothesis  # noqa: F401
     except ImportError:
-        return Success(PropertyTestReport(
+        return Success((PropertyTestReport(
             errors=["Hypothesis not installed (pip install hypothesis)"]
-        ))
+        ), None))
 
     combined_report = PropertyTestReport()
-
-    for file_path in files:
-        result = run_property_tests_on_file(file_path, max_examples, verbose)
-
-        if isinstance(result, Failure):
-            combined_report.errors.append(result.failure())
-            continue
-
-        file_report = result.unwrap()
-        combined_report.functions_tested += file_report.functions_tested
-        combined_report.functions_passed += file_report.functions_passed
-        combined_report.functions_failed += file_report.functions_failed
-        combined_report.functions_skipped += file_report.functions_skipped
-        combined_report.total_examples += file_report.total_examples
-        combined_report.results.extend(file_report.results)
-        combined_report.errors.extend(file_report.errors)
-
-    return Success(combined_report)
+    coverage_data = None
+
+    # DX-37: Optional coverage collection for hypothesis tests
+    if collect_coverage:
+        try:
+            from invar.shell.coverage import collect_coverage as cov_ctx
+            from invar.shell.coverage import extract_coverage_report
+
+            source_dirs = list({f.parent for f in files})
+            with cov_ctx(source_dirs) as cov:
+                for file_path in files:
+                    result = run_property_tests_on_file(file_path, max_examples, verbose)
+                    _accumulate_report(combined_report, result)
+
+                # Extract coverage after all tests
+                coverage_report = extract_coverage_report(cov, files, "hypothesis")
+                coverage_data = {
+                    "collected": True,
+                    "overall_branch_coverage": coverage_report.overall_branch_coverage,
+                    "files": len(coverage_report.files),
+                }
+        except ImportError:
+            # coverage not installed, run without it
+            for file_path in files:
+                result = run_property_tests_on_file(file_path, max_examples, verbose)
+                _accumulate_report(combined_report, result)
+    else:
+        for file_path in files:
+            result = run_property_tests_on_file(file_path, max_examples, verbose)
+            _accumulate_report(combined_report, result)
+
+    return Success((combined_report, coverage_data))
+
+
+def _accumulate_report(
+    combined_report: PropertyTestReport,
+    result: Result[PropertyTestReport, str],
+) -> None:
+    """Accumulate a file result into the combined report."""
+    if isinstance(result, Failure):
+        combined_report.errors.append(result.failure())
+        return
+
+    file_report = result.unwrap()
+    combined_report.functions_tested += file_report.functions_tested
+    combined_report.functions_passed += file_report.functions_passed
+    combined_report.functions_failed += file_report.functions_failed
+    combined_report.functions_skipped += file_report.functions_skipped
+    combined_report.total_examples += file_report.total_examples
+    combined_report.results.extend(file_report.results)
+    combined_report.errors.extend(file_report.errors)
 
 
 def _import_module_from_path(file_path: Path) -> object | None:
@@ -163,6 +203,8 @@ def _import_module_from_path(file_path: Path) -> object | None:
         return None
 
 
+# @shell_orchestration: Formatting helper tightly coupled to CLI output
+# @shell_complexity: Report formatting with JSON/rich output modes
 def format_property_test_report(
     report: PropertyTestReport,
     json_output: bool = False,
@@ -193,6 +235,8 @@ def format_property_test_report(
                     "passed": r.passed,
                     "examples": r.examples_run,
                     "error": r.error,
+                    "file_path": r.file_path,  # DX-26
+                    "seed": r.seed,  # DX-26
                 }
                 for r in report.results
             ],
@@ -215,10 +259,17 @@ def format_property_test_report(
         f"{report.total_examples} examples"
     )
 
-    # Show failures
+    # Show failures (DX-26: actionable format)
     for result in report.results:
         if not result.passed:
-            lines.append(f"  [red]✗[/red] {result.function_name}: {result.error}")
+            # DX-26: file::function format
+            location = f"{result.file_path}::{result.function_name}" if result.file_path else result.function_name
+            lines.append(f"  [red]✗[/red] {location}")
+            if result.error:
+                short_error = result.error[:100] + "..." if len(result.error) > 100 else result.error
+                lines.append(f"      {short_error}")
+            if result.seed:
+                lines.append(f"      [dim]Seed: {result.seed}[/dim]")
 
     # Show errors
     for error in report.errors:

invar/shell/prove/__init__.py

@@ -0,0 +1,9 @@
+"""
+Verification execution module.
+
+This module contains:
+- crosshair: CrossHair symbolic execution
+- hypothesis: Hypothesis property testing fallback
+- cache: Verification result caching
+- accept: Accept mechanism for known violations
+"""

invar/shell/prove/accept.py

@@ -0,0 +1,113 @@
+"""
+CrossHair contract detection utilities.
+
+Shell module: Extracted for file size compliance.
+- DX-13: has_verifiable_contracts for contract detection
+- DX-19: @crosshair_accept acknowledgment handling
+"""
+
+from __future__ import annotations
+
+
+# @shell_orchestration: Contract analysis helper for CrossHair prove module
+# @shell_complexity: AST traversal for contract detection
+def has_verifiable_contracts(source: str) -> bool:
+    """
+    Check if source has verifiable contracts.
+
+    DX-13: Hybrid detection - fast string check + AST validation.
+
+    Args:
+        source: Python source code
+
+    Returns:
+        True if file has @pre/@post contracts worth verifying
+    """
+    # Fast path: no contract keywords at all
+    if "@pre" not in source and "@post" not in source:
+        return False
+
+    # AST validation to avoid false positives from comments/strings
+    try:
+        import ast
+
+        tree = ast.parse(source)
+    except SyntaxError:
+        return True  # Conservative: assume has contracts
+
+    contract_decorators = {"pre", "post"}
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for dec in node.decorator_list:
+                if isinstance(dec, ast.Call):
+                    func = dec.func
+                    # @pre(...) or @post(...)
+                    if isinstance(func, ast.Name) and func.id in contract_decorators:
+                        return True
+                    # @deal.pre(...) or @deal.post(...)
+                    if (
+                        isinstance(func, ast.Attribute)
+                        and func.attr in contract_decorators
+                    ):
+                        return True
+
+    return False
+
+
+# @shell_orchestration: Acceptance criteria analysis for CrossHair prove
+# @shell_complexity: AST traversal for decorator extraction
+def get_crosshair_accept_reasons(source: str) -> dict[str, str]:
+    """
+    Extract @crosshair_accept reasons from source.
+
+    DX-19: Returns a mapping of function_name -> reason for functions
+    that have @crosshair_accept decorator.
+
+    Args:
+        source: Python source code
+
+    Returns:
+        Dict mapping function names to their accept reasons
+    """
+    # Fast path: no decorator keyword
+    if "@crosshair_accept" not in source:
+        return {}
+
+    try:
+        import ast
+
+        tree = ast.parse(source)
+    except SyntaxError:
+        return {}
+
+    reasons: dict[str, str] = {}
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for dec in node.decorator_list:
+                if isinstance(dec, ast.Call):
+                    func = dec.func
+                    # @crosshair_accept("reason")
+                    if isinstance(func, ast.Name) and func.id == "crosshair_accept":
+                        if dec.args and isinstance(dec.args[0], ast.Constant):
+                            reasons[node.name] = str(dec.args[0].value)
+                    # @invar.crosshair_accept("reason")
+                    if isinstance(func, ast.Attribute) and func.attr == "crosshair_accept":
+                        if dec.args and isinstance(dec.args[0], ast.Constant):
+                            reasons[node.name] = str(dec.args[0].value)
+
+    return reasons
+
+
+# @shell_orchestration: Counterexample parsing helper for CrossHair output
+def extract_function_from_counterexample(ce: str) -> str | None:
+    """
+    Extract function name from CrossHair counterexample.
+
+    DX-19: Counterexamples look like "func_name(args) (error at ...)"
+    """
+    # Function name is everything before the first '('
+    if "(" in ce:
+        return ce.split("(")[0].strip()
+    return None