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

invar/shell/coverage.py

@@ -0,0 +1,351 @@
+"""
+Coverage integration for Guard verification phases.
+
+DX-37: Collect branch coverage from doctest + hypothesis phases.
+Coverage.py is used for accurate tracking via sys.settrace().
+
+Note: CrossHair uses symbolic execution (Z3 solver) in subprocess,
+so coverage.py cannot track it. This is a fundamental limitation.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from deal import post, pre
+from returns.result import Failure, Result, Success
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from coverage import Coverage
+
+
+@dataclass
+class UncoveredBranch:
+    """A branch that was never taken during testing.
+
+    Examples:
+        >>> branch = UncoveredBranch(line=127, branch_type="else", context="if x > 0:")
+        >>> branch.line
+        127
+        >>> branch.branch_type
+        'else'
+    """
+
+    line: int
+    branch_type: str  # "if", "else", "elif", "except", "for", "while"
+    context: str  # Source line for context
+
+
+@dataclass
+class FileCoverage:
+    """Coverage data for a single file.
+
+    Examples:
+        >>> fc = FileCoverage(path="src/foo.py", branch_coverage=94.5)
+        >>> fc.branch_coverage
+        94.5
+        >>> len(fc.uncovered_branches)
+        0
+    """
+
+    path: str
+    branch_coverage: float  # 0.0 to 100.0
+    uncovered_branches: list[UncoveredBranch] = field(default_factory=list)
+
+
+@dataclass
+class CoverageReport:
+    """Coverage data from doctest + hypothesis phases.
+
+    Examples:
+        >>> report = CoverageReport(overall_branch_coverage=91.2)
+        >>> report.phases_tracked
+        []
+        >>> report.phases_excluded
+        ['crosshair']
+    """
+
+    overall_branch_coverage: float  # 0.0 to 100.0
+    files: dict[str, FileCoverage] = field(default_factory=dict)
+    phases_tracked: list[str] = field(default_factory=list)
+    phases_excluded: list[str] = field(default_factory=lambda: ["crosshair"])
+
+
+# @shell_orchestration: Import check utility for coverage.py dependency
+def _is_coverage_available() -> bool:
+    """Check if coverage.py is installed.
+
+    Examples:
+        >>> result = _is_coverage_available()
+        >>> isinstance(result, bool)
+        True
+    """
+    try:
+        import coverage  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+@pre(lambda source_dirs: len(source_dirs) >= 0)
+@contextmanager
+def collect_coverage(source_dirs: list[Path]) -> Iterator[Coverage]:
+    """Context manager for coverage collection.
+
+    Args:
+        source_dirs: Directories to track coverage for
+
+    Yields:
+        Coverage object for data extraction
+
+    Examples:
+        >>> from pathlib import Path
+        >>> # When coverage is available, yields a Coverage object
+        >>> # with collect_coverage([Path("src")]) as cov:
+        >>> #     pass  # Execute code to track
+    """
+    import coverage
+
+    cov = coverage.Coverage(
+        branch=True,
+        source=[str(d) for d in source_dirs] if source_dirs else None,
+        omit=["**/test_*", "**/*_test.py", "**/conftest.py"],
+    )
+
+    cov.start()
+    try:
+        yield cov
+    finally:
+        cov.stop()
+        cov.save()
+
+
+# @shell_complexity: Coverage API interaction with multiple analysis branches
+@pre(lambda cov, files: files is not None)
+@post(lambda result: isinstance(result, CoverageReport))
+def extract_coverage_report(cov: Coverage, files: list[Path], phase: str) -> CoverageReport:
+    """Extract coverage report from Coverage object.
+
+    Args:
+        cov: Coverage object after data collection
+        files: Files to extract coverage for
+        phase: Name of the phase ("doctest" or "hypothesis")
+
+    Returns:
+        CoverageReport with branch coverage data
+
+    Examples:
+        >>> # After running with collect_coverage:
+        >>> # report = extract_coverage_report(cov, [Path("src/foo.py")], "doctest")
+        >>> # report.phases_tracked == ["doctest"]
+    """
+    file_coverages: dict[str, FileCoverage] = {}
+    total_branches = 0
+    covered_branches = 0
+
+    # Get analysis data
+    for file_path in files:
+        str_path = str(file_path)
+        try:
+            # Trigger coverage analysis for this file
+            _ = cov.analysis2(str_path)
+
+            # Get branch data
+            branch_stats = cov._analyze(str_path)
+            if hasattr(branch_stats, "numbers"):
+                nums = branch_stats.numbers
+                file_total = nums.n_branches
+                file_covered = nums.n_branches - nums.n_missing_branches
+
+                if file_total > 0:
+                    total_branches += file_total
+                    covered_branches += file_covered
+                    branch_pct = (file_covered / file_total) * 100
+
+                    # Extract uncovered branches
+                    uncovered = []
+                    if hasattr(branch_stats, "missing_branch_arcs"):
+                        for arc in branch_stats.missing_branch_arcs():
+                            from_line, to_line = arc
+                            uncovered.append(
+                                UncoveredBranch(
+                                    line=from_line,
+                                    branch_type="branch",
+                                    context=f"line {from_line} -> {to_line}",
+                                )
+                            )
+
+                    file_coverages[str_path] = FileCoverage(
+                        path=str_path,
+                        branch_coverage=round(branch_pct, 1),
+                        uncovered_branches=uncovered[:5],  # Limit to 5 per file
+                    )
+        except Exception:
+            # File not covered or analysis failed
+            continue
+
+    overall = (covered_branches / total_branches * 100) if total_branches > 0 else 0.0
+
+    return CoverageReport(
+        overall_branch_coverage=round(overall, 1),
+        files=file_coverages,
+        phases_tracked=[phase],
+    )
+
+
+# @shell_orchestration: Report merging coordinates data from multiple phases
+# @shell_complexity: Report merging with multiple iteration paths
+@pre(lambda reports: all(isinstance(r, CoverageReport) for r in reports if r is not None))
+@post(lambda result: isinstance(result, CoverageReport))
+def merge_coverage_reports(reports: list[CoverageReport | None]) -> CoverageReport:
+    """Merge coverage from multiple phases.
+
+    Union of covered lines/branches across all phases.
+    Only branches uncovered in ALL phases are reported as uncovered.
+
+    Args:
+        reports: List of CoverageReport objects (None entries are skipped)
+
+    Returns:
+        Merged CoverageReport
+
+    Examples:
+        >>> r1 = CoverageReport(overall_branch_coverage=80.0, phases_tracked=["doctest"])
+        >>> r2 = CoverageReport(overall_branch_coverage=70.0, phases_tracked=["hypothesis"])
+        >>> merged = merge_coverage_reports([r1, r2])
+        >>> "doctest" in merged.phases_tracked
+        True
+        >>> "hypothesis" in merged.phases_tracked
+        True
+    """
+    valid_reports = [r for r in reports if r is not None]
+
+    if not valid_reports:
+        return CoverageReport(overall_branch_coverage=0.0)
+
+    if len(valid_reports) == 1:
+        return valid_reports[0]
+
+    # Merge phases tracked
+    all_phases: list[str] = []
+    for r in valid_reports:
+        all_phases.extend(r.phases_tracked)
+
+    # Merge file coverages - take the max coverage for each file
+    merged_files: dict[str, FileCoverage] = {}
+    for r in valid_reports:
+        for path, fc in r.files.items():
+            if path not in merged_files or fc.branch_coverage > merged_files[path].branch_coverage:
+                merged_files[path] = fc
+
+    # Calculate overall as average of file coverages (weighted would be better but needs LOC)
+    if merged_files:
+        overall = sum(fc.branch_coverage for fc in merged_files.values()) / len(merged_files)
+    else:
+        overall = 0.0
+
+    return CoverageReport(
+        overall_branch_coverage=round(overall, 1),
+        files=merged_files,
+        phases_tracked=all_phases,
+    )
+
+
+# @shell_orchestration: Format report for Rich console output
+@pre(lambda report: isinstance(report, CoverageReport))
+@post(lambda result: isinstance(result, str))
+def format_coverage_output(report: CoverageReport) -> str:
+    """Format coverage report for CLI output.
+
+    Args:
+        report: CoverageReport to format
+
+    Returns:
+        Formatted string for terminal output
+
+    Examples:
+        >>> report = CoverageReport(overall_branch_coverage=91.2, phases_tracked=["doctest"])
+        >>> output = format_coverage_output(report)
+        >>> "91.2%" in output
+        True
+        >>> "doctest" in output
+        True
+    """
+    lines = [
+        f"Coverage Analysis ({' + '.join(report.phases_tracked)}):",
+    ]
+
+    # Sort files by coverage (lowest first to highlight issues)
+    sorted_files = sorted(report.files.items(), key=lambda x: x[1].branch_coverage)
+
+    for path, fc in sorted_files[:10]:  # Limit to 10 files
+        uncovered_count = len(fc.uncovered_branches)
+        lines.append(f"  {path}: {fc.branch_coverage}% branch ({uncovered_count} uncovered)")
+        for branch in fc.uncovered_branches[:3]:  # Limit to 3 branches per file
+            lines.append(f"    Line {branch.line}: {branch.context}")
+
+    lines.append("")
+    lines.append(f"Overall: {report.overall_branch_coverage}% branch coverage ({' + '.join(report.phases_tracked)})")
+    lines.append("")
+    lines.append("Note: CrossHair uses symbolic execution; coverage not applicable.")
+
+    return "\n".join(lines)
+
+
+# @shell_orchestration: Format report for JSON agent output
+@post(lambda result: isinstance(result, dict))
+def format_coverage_json(report: CoverageReport) -> dict:
+    """Format coverage report for JSON output.
+
+    Args:
+        report: CoverageReport to format
+
+    Returns:
+        Dictionary for JSON serialization
+
+    Examples:
+        >>> report = CoverageReport(overall_branch_coverage=91.2, phases_tracked=["doctest"])
+        >>> data = format_coverage_json(report)
+        >>> data["enabled"]
+        True
+        >>> data["overall_branch_coverage"]
+        91.2
+    """
+    return {
+        "enabled": True,
+        "phases_tracked": report.phases_tracked,
+        "phases_excluded": report.phases_excluded,
+        "overall_branch_coverage": report.overall_branch_coverage,
+        "files": [
+            {
+                "path": fc.path,
+                "branch_coverage": fc.branch_coverage,
+                "uncovered_branches": [
+                    {"line": b.line, "type": b.branch_type, "context": b.context}
+                    for b in fc.uncovered_branches
+                ],
+            }
+            for fc in report.files.values()
+        ],
+    }
+
+
+def check_coverage_available() -> Result[bool, str]:
+    """Check if coverage.py is installed and return helpful error if not.
+
+    Returns:
+        Success(True) if available, Failure with install instructions if not
+
+    Examples:
+        >>> result = check_coverage_available()
+        >>> # Either Success(True) or Failure("Install coverage...")
+    """
+    if _is_coverage_available():
+        return Success(True)
+    return Failure("Install coverage for --coverage support: pip install coverage[toml]>=7.0")

invar/shell/guard_helpers.py

@@ -82,25 +82,38 @@ def collect_files_to_check(
 
 # @shell_orchestration: Coordinates doctest execution via testing module
 def run_doctests_phase(
-    checked_files: list[Path], explain: bool
-) -> tuple[bool, str]:
+    checked_files: list[Path],
+    explain: bool,
+    timeout: int = 60,
+    collect_coverage: bool = False,
+) -> tuple[bool, str, dict | None]:
     """Run doctests on collected files.
 
-    Returns (passed, output).
+    Args:
+        checked_files: Files to run doctests on
+        explain: Show verbose output
+        timeout: Maximum time in seconds (default: 60, from RuleConfig.timeout_doctest)
+        collect_coverage: DX-37: If True, collect branch coverage data
+
+    Returns (passed, output, coverage_data).
     """
     from invar.shell.testing import run_doctests_on_files
 
     if not checked_files:
-        return True, ""
+        return True, "", None
 
-    doctest_result = run_doctests_on_files(checked_files, verbose=explain)
+    doctest_result = run_doctests_on_files(
+        checked_files, verbose=explain, timeout=timeout, collect_coverage=collect_coverage
+    )
     if isinstance(doctest_result, Success):
         result_data = doctest_result.unwrap()
         passed = result_data.get("status") in ("passed", "skipped")
         output = result_data.get("stdout", "")
-        return passed, output
+        # DX-37: Return coverage data if collected
+        coverage_data = {"collected": result_data.get("coverage_collected", False)}
+        return passed, output, coverage_data if collect_coverage else None
 
-    return False, doctest_result.failure()
+    return False, doctest_result.failure(), None
 
 
 # @shell_orchestration: Coordinates CrossHair verification via prove module
@@ -111,6 +124,8 @@ def run_crosshair_phase(
     doctest_passed: bool,
     static_exit_code: int,
     changed_mode: bool = False,
+    timeout: int = 300,
+    per_condition_timeout: int = 30,
 ) -> tuple[bool, dict]:
     """Run CrossHair verification phase.
 
@@ -120,10 +135,12 @@ def run_crosshair_phase(
         doctest_passed: Whether doctests passed
         static_exit_code: Exit code from static analysis
         changed_mode: If True, only verify git-changed files (--changed flag)
+        timeout: Max time per file in seconds (default: 300)
+        per_condition_timeout: Max time per contract in seconds (default: 30)
 
     Returns (passed, output_dict).
     """
-    from invar.shell.prove_cache import ProveCache
+    from invar.shell.prove.cache import ProveCache
     from invar.shell.testing import get_files_to_prove, run_crosshair_parallel
 
     # Skip if prior failures
@@ -157,6 +174,8 @@ def run_crosshair_phase(
         max_iterations=5,
         max_workers=None,
         cache=cache,
+        timeout=timeout,
+        per_condition_timeout=per_condition_timeout,
     )
 
     if isinstance(crosshair_result, Success):
@@ -244,7 +263,8 @@ def run_property_tests_phase(
     doctest_passed: bool,
     static_exit_code: int,
     max_examples: int = 100,
-) -> tuple[bool, dict]:
+    collect_coverage: bool = False,
+) -> tuple[bool, dict, dict | None]:
     """Run property tests phase (DX-08).
 
     Args:
@@ -252,27 +272,28 @@ def run_property_tests_phase(
         doctest_passed: Whether doctests passed
         static_exit_code: Exit code from static analysis
         max_examples: Maximum Hypothesis examples per function
+        collect_coverage: DX-37: If True, collect branch coverage data
 
-    Returns (passed, output_dict).
+    Returns (passed, output_dict, coverage_data).
     """
     from invar.shell.property_tests import run_property_tests_on_files
 
     # Skip if prior failures
     if not doctest_passed or static_exit_code != 0:
-        return True, {"status": "skipped", "reason": "prior failures"}
+        return True, {"status": "skipped", "reason": "prior failures"}, None
 
     if not checked_files:
-        return True, {"status": "skipped", "reason": "no files"}
+        return True, {"status": "skipped", "reason": "no files"}, None
 
     # Only test Core files (with contracts)
     core_files = [f for f in checked_files if "core" in str(f)]
     if not core_files:
-        return True, {"status": "skipped", "reason": "no core files"}
+        return True, {"status": "skipped", "reason": "no core files"}, None
 
-    result = run_property_tests_on_files(core_files, max_examples)
+    result = run_property_tests_on_files(core_files, max_examples, collect_coverage=collect_coverage)
 
     if isinstance(result, Success):
-        report = result.unwrap()
+        report, coverage_data = result.unwrap()
         # DX-26: Build structured failures array for actionable output
         failures = [
             {
@@ -292,9 +313,9 @@ def run_property_tests_phase(
             "total_examples": report.total_examples,
             "failures": failures,  # DX-26: Structured failure info
             "errors": report.errors,
-        }
+        }, coverage_data
 
-    return False, {"status": "error", "error": result.failure()}
+    return False, {"status": "error", "error": result.failure()}, None
 
 
 # @shell_complexity: Property test status formatting

invar/shell/guard_output.py

@@ -257,8 +257,9 @@ def output_agent(
     verification_level: str = "standard",
     property_output: dict | None = None,  # DX-08
     routing_stats: dict | None = None,  # DX-22
+    coverage_data: dict | None = None,  # DX-37
 ) -> None:
-    """Output report in Agent-optimized JSON format (Phase 8.2 + DX-06 + DX-08 + DX-09 + DX-22 + DX-26).
+    """Output report in Agent-optimized JSON format (Phase 8.2 + DX-06 + DX-08 + DX-09 + DX-22 + DX-26 + DX-37).
 
     Args:
         report: Guard analysis report
@@ -269,9 +270,11 @@ def output_agent(
         verification_level: Current level (static/standard)
         property_output: Property test results dict (DX-08)
         routing_stats: Smart routing statistics (DX-22)
+        coverage_data: DX-37: Branch coverage data from doctest + hypothesis
 
     DX-22: Adds routing stats showing CrossHair vs Hypothesis distribution.
     DX-26: status now reflects ALL test phases, not just static analysis.
+    DX-37: Adds optional coverage data from doctest + hypothesis phases.
     """
     import json
 
@@ -308,4 +311,7 @@ def output_agent(
     # DX-22: Add smart routing statistics if available
     if routing_stats:
         output["routing"] = routing_stats
+    # DX-37: Add coverage data if collected
+    if coverage_data:
+        output["coverage"] = coverage_data
     console.print(json.dumps(output, indent=2))

invar/shell/property_tests.py

@@ -99,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.
 
@@ -111,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:

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
+"""