invar-tools 1.0.0__py3-none-any.whl → 1.2.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/perception.py

@@ -30,6 +30,7 @@ if TYPE_CHECKING:
 console = Console()
 
 
+# @shell_complexity: Symbol map generation with sorting and output modes
 def run_map(path: Path, top_n: int, json_output: bool) -> Result[None, str]:
     """
     Run the map command.
@@ -75,6 +76,7 @@ def run_map(path: Path, top_n: int, json_output: bool) -> Result[None, str]:
     return Success(None)
 
 
+# @shell_complexity: Signature extraction with symbol filtering
 def run_sig(target: str, json_output: bool) -> Result[None, str]:
     """
     Run the sig command.

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
@@ -163,6 +167,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 +199,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 +223,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.py

@@ -56,6 +56,8 @@ class CrossHairStatus:
 # ============================================================
 
 
+# @shell_orchestration: Contract detection for CrossHair prove module
+# @shell_complexity: AST traversal for contract detection
 def has_verifiable_contracts(source: str) -> bool:
     """
     Check if source has verifiable contracts.
@@ -105,6 +107,7 @@ def has_verifiable_contracts(source: str) -> bool:
 # ============================================================
 
 
+# @shell_complexity: CrossHair subprocess with error classification
 def _verify_single_file(
     file_path: str,
     max_iterations: int = 5,
@@ -153,17 +156,41 @@ def _verify_single_file(
                 "stdout": result.stdout,
             }
         else:
+            # Check if this is an execution error vs actual counterexample
+            # CrossHair reports TypeError/AttributeError when it can't
+            # symbolically execute C extensions like ast.parse()
+            stdout = result.stdout
+            execution_errors = [
+                "TypeError:",
+                "AttributeError:",
+                "NotImplementedError:",
+                "compile() arg 1 must be",  # ast.parse limitation
+            ]
+            is_execution_error = any(err in stdout for err in execution_errors)
+
+            if is_execution_error:
+                # Treat as skipped - function uses unsupported operations
+                return {
+                    "file": file_path,
+                    "status": CrossHairStatus.SKIPPED,
+                    "time_ms": elapsed_ms,
+                    "reason": "uses unsupported operations (ast/compile)",
+                    "stdout": stdout,
+                }
+
+            # Extract counterexample lines - CrossHair format: "file:line: error: Err when calling func(...)"
+            # Include lines with "error:" as they contain the actual counterexamples
             counterexamples = [
                 line.strip()
-                for line in result.stdout.split("\n")
-                if line.strip() and "error" not in line.lower()
+                for line in stdout.split("\n")
+                if line.strip() and ": error:" in line.lower()
             ]
             return {
                 "file": file_path,
                 "status": CrossHairStatus.COUNTEREXAMPLE,
                 "time_ms": elapsed_ms,
                 "counterexamples": counterexamples,
-                "stdout": result.stdout,
+                "stdout": stdout,
             }
 
     except subprocess.TimeoutExpired:
@@ -185,6 +212,7 @@ def _verify_single_file(
 # ============================================================
 
 
+# @shell_complexity: Parallel verification with caching and filtering
 def run_crosshair_parallel(
     files: list[Path],
     max_iterations: int = 5,
@@ -354,6 +382,8 @@ def run_crosshair_parallel(
     )
 
 
+# @shell_orchestration: Result aggregation helper for parallel verification
+# @shell_complexity: Result classification with cache update
 def _process_verification_result(
     result: dict,
     file_path: Path,
@@ -417,6 +447,8 @@ def run_crosshair_on_files(
 # ============================================================
 
 
+# @shell_orchestration: File selection for incremental verification
+# @shell_complexity: Git integration for incremental verification
 def get_files_to_prove(
     path: Path,
     all_core_files: list[Path],

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