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

invar/shell/git.py

@@ -28,6 +28,7 @@ def _run_git(args: list[str], cwd: Path) -> Result[str, str]:
         return Failure(f"Git error: {e}")
 
 
+# @shell_orchestration: Helper for git output parsing, tightly coupled to Shell
 def _parse_py_files(output: str, project_root: Path) -> set[Path]:
     """Parse git output and return Python file paths."""
     files: set[Path] = set()
@@ -37,6 +38,7 @@ def _parse_py_files(output: str, project_root: Path) -> set[Path]:
     return files
 
 
+# @shell_complexity: Git operations require multiple subprocess calls with error handling
 def get_changed_files(project_root: Path) -> Result[set[Path], str]:
     """
     Get Python files modified according to git (staged, unstaged, untracked).

invar/shell/guard_helpers.py

@@ -19,6 +19,7 @@ if TYPE_CHECKING:
 console = Console()
 
 
+# @shell_complexity: Git changed mode with file collection
 def handle_changed_mode(
     path: Path,
 ) -> Result[tuple[set[Path], list[Path]], str]:
@@ -42,6 +43,8 @@ def handle_changed_mode(
     return Success((only_files, list(only_files)))
 
 
+# @shell_orchestration: Coordinates path classification and file collection
+# @shell_complexity: File collection with path normalization
 def collect_files_to_check(
     path: Path, checked_files: list[Path]
 ) -> list[Path]:
@@ -77,34 +80,52 @@ def collect_files_to_check(
     return result_files
 
 
+# @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
+# @shell_complexity: CrossHair phase with conditional execution
 def run_crosshair_phase(
     path: Path,
     checked_files: list[Path],
     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.
 
@@ -114,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
@@ -151,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):
@@ -161,6 +186,7 @@ def run_crosshair_phase(
     return False, {"status": "error", "error": crosshair_result.failure()}
 
 
+# @shell_complexity: Status output with multiple phases
 def output_verification_status(
     verification_level: VerificationLevel,
     static_exit_code: int,
@@ -169,17 +195,30 @@ def output_verification_status(
     crosshair_output: dict,
     explain: bool,
     property_output: dict | None = None,
+    strict: bool = False,
 ) -> None:
     """Output verification status for human-readable mode.
 
     DX-19: Simplified - STANDARD runs all phases (doctests + CrossHair + Hypothesis).
+    DX-26: Shows combined conclusion after all phase results.
     """
     from invar.shell.testing import VerificationLevel
 
-    # STATIC mode: no runtime tests to report
+    # STATIC mode: no runtime tests to report (conclusion shown by output_rich)
     if verification_level == VerificationLevel.STATIC:
         return
 
+    # DX-26: Extract passed status from phase outputs
+    crosshair_passed = True
+    if crosshair_output:
+        crosshair_status = crosshair_output.get("status", "verified")
+        crosshair_passed = crosshair_status in ("verified", "skipped")
+
+    property_passed = True
+    if property_output:
+        property_status = property_output.get("status", "passed")
+        property_passed = property_status in ("passed", "skipped")
+
     # STANDARD mode: report all test results
     if static_exit_code == 0:
         # Doctest results
@@ -203,13 +242,29 @@ def output_verification_status(
     else:
         console.print("[dim]⊘ Runtime tests skipped (static errors)[/dim]")
 
+    # DX-26: Combined conclusion after all phases
+    console.print("-" * 40)
+    all_passed = (
+        static_exit_code == 0
+        and doctest_passed
+        and crosshair_passed
+        and property_passed
+    )
+    # In strict mode, warnings also cause failure (but exit code already reflects this)
+    status = "passed" if all_passed else "failed"
+    color = "green" if all_passed else "red"
+    console.print(f"[{color}]Guard {status}.[/{color}]")
+
 
+# @shell_orchestration: Coordinates shell module calls for property testing
+# @shell_complexity: Property tests with result aggregation
 def run_property_tests_phase(
     checked_files: list[Path],
     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:
@@ -217,45 +272,62 @@ 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 = [
+            {
+                "function": r.function_name,
+                "file_path": r.file_path,
+                "error": r.error,
+                "seed": r.seed,
+            }
+            for r in report.results
+            if not r.passed
+        ]
         return report.all_passed(), {
             "status": "passed" if report.all_passed() else "failed",
             "functions_tested": report.functions_tested,
             "functions_passed": report.functions_passed,
             "functions_failed": report.functions_failed,
             "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
 def _output_property_tests_status(
     static_exit_code: int,
     doctest_passed: bool,
     property_output: dict,
 ) -> None:
-    """Output property tests status (DX-08)."""
+    """Output property tests status (DX-08, DX-26).
+
+    DX-26: Show file::function format and reproduction command for failures.
+    """
     if static_exit_code != 0 or not doctest_passed:
         console.print("[dim]⊘ Property tests skipped (prior failures)[/dim]")
         return
@@ -275,12 +347,36 @@ def _output_property_tests_status(
     elif status == "failed":
         failed = property_output.get("functions_failed", 0)
         console.print(f"[red]✗ Property tests failed ({failed} functions)[/red]")
+        # DX-26: Show actionable failure info
+        for failure in property_output.get("failures", [])[:5]:
+            file_path = failure.get("file_path", "")
+            func_name = failure.get("function", "unknown")
+            seed = failure.get("seed")
+            error = failure.get("error", "")
+
+            # Show file::function format
+            location = f"{file_path}::{func_name}" if file_path else func_name
+            console.print(f"  [red]✗[/red] {location}")
+
+            # Show truncated error
+            if error:
+                short_error = error[:100] + "..." if len(error) > 100 else error
+                console.print(f"    {short_error}")
+
+            # Show reproduction command with seed
+            if seed:
+                console.print(
+                    f"    [dim]Reproduce: python -c \"from hypothesis import reproduce_failure; "
+                    f"import {func_name}\" --seed={seed}[/dim]"
+                )
+        # Fallback for errors without structured failures
         for error in property_output.get("errors", [])[:5]:
-            console.print(f"  {error}")
+            console.print(f"  [yellow]![/yellow] {error}")
     else:
         console.print(f"[yellow]! Property tests: {status}[/yellow]")
 
 
+# @shell_complexity: CrossHair status formatting
 def _output_crosshair_status(
     static_exit_code: int,
     doctest_passed: bool,

invar/shell/guard_output.py

@@ -3,18 +3,77 @@ Guard output formatters.
 
 Shell module: handles output formatting for guard command.
 Extracted from cli.py to reduce file size.
+
+DX-22: Added verification routing statistics for de-duplication.
 """
 
 from __future__ import annotations
 
+from dataclasses import dataclass
+
 from rich.console import Console
 
 from invar.core.formatter import format_guard_agent
 from invar.core.models import GuardReport, Severity
+from invar.core.utils import get_combined_status
 
 console = Console()
 
 
+@dataclass
+class VerificationStats:
+    """
+    DX-22: De-duplicated verification statistics.
+
+    Tracks separate counts for CrossHair (proof) vs Hypothesis (testing)
+    to avoid misleading double-counting.
+    """
+
+    crosshair_proven: int = 0
+    hypothesis_tested: int = 0
+    doctests_passed: int = 0
+    routed_to_hypothesis: int = 0  # Files routed due to C extensions
+
+    @property
+    def total_verified(self) -> int:
+        """Total unique functions verified (no double-counting)."""
+        return self.crosshair_proven + self.hypothesis_tested
+
+    @property
+    def proof_coverage_pct(self) -> float:
+        """Percentage of verifiable code proven by CrossHair."""
+        total = self.crosshair_proven + self.hypothesis_tested
+        if total == 0:
+            return 0.0
+        return (self.crosshair_proven / total) * 100
+
+
+# @shell_orchestration: Rich markup formatting tightly coupled to shell output
+# @shell_complexity: Conditional formatting for each stat category
+def format_verification_stats(stats: VerificationStats) -> str:
+    """
+    Format verification statistics for display.
+
+    DX-22: Shows de-duplicated counts distinguishing proof from testing.
+    """
+    lines = []
+    lines.append("Verification breakdown:")
+    if stats.crosshair_proven > 0:
+        lines.append(f"  ✓ Proven (CrossHair): {stats.crosshair_proven} functions")
+    if stats.hypothesis_tested > 0:
+        lines.append(f"  ✓ Tested (Hypothesis): {stats.hypothesis_tested} functions")
+    if stats.routed_to_hypothesis > 0:
+        lines.append(
+            f"    [dim](C-extension routing: {stats.routed_to_hypothesis} files)[/dim]"
+        )
+    if stats.doctests_passed > 0:
+        lines.append(f"  ✓ Doctests: {stats.doctests_passed} passed")
+    if stats.total_verified > 0:
+        lines.append(f"  Proof coverage: {stats.proof_coverage_pct:.0f}%")
+    return "\n".join(lines)
+
+
+# @shell_complexity: Context display with line range extraction
 def show_file_context(file_path: str) -> None:
     """
     Show INSPECT section for a file (Phase 9.2 P14).
@@ -47,12 +106,14 @@ def show_file_context(file_path: str) -> None:
         pass  # Silently ignore errors in context display
 
 
+# @shell_complexity: Rich formatting with conditional sections
 def output_rich(
     report: GuardReport,
     strict_pure: bool = False,
     changed_mode: bool = False,
     pedantic_mode: bool = False,
     explain_mode: bool = False,
+    static_mode: bool = False,
 ) -> None:
     """Output report using Rich formatting."""
     console.print("\n[bold]Invar Guard Report[/bold]")
@@ -60,6 +121,7 @@ def output_rich(
     mode_info = [
         m
         for m, c in [
+            ("static", static_mode),
             ("strict-pure", strict_pure),
             ("changed-only", changed_mode),
             ("pedantic", pedantic_mode),
@@ -174,51 +236,65 @@ def output_rich(
                 "[dim]💡 Fix warnings in files you modified to improve code health.[/dim]"
             )
 
-    console.print(
-        f"\n[{'green' if report.passed else 'red'}]Guard {'passed' if report.passed else 'failed'}.[/]"
-    )
-    console.print(
-        "\n[dim]Note: Guard performs static analysis only. "
-        "Dynamic imports and runtime behavior are not checked.[/dim]"
-    )
-
-
-def output_json(report: GuardReport) -> None:
-    """Output report as JSON."""
-    import json
-
-    output = {
-        "files_checked": report.files_checked,
-        "errors": report.errors,
-        "warnings": report.warnings,
-        "infos": report.infos,
-        "passed": report.passed,
-        "violations": [v.model_dump() for v in report.violations],
-    }
-    console.print(json.dumps(output, indent=2))
+    # DX-26: Show static-only conclusion for --static mode
+    # Full mode shows conclusion after all phases in output_verification_status()
+    if static_mode:
+        console.print(
+            f"\n[{'green' if report.passed else 'red'}]Guard {'passed' if report.passed else 'failed'}.[/]"
+        )
+        console.print(
+            "\n[dim]Note: --static mode skips runtime tests (doctests, CrossHair, Hypothesis).[/dim]"
+        )
 
 
+# @shell_complexity: JSON output assembly with multiple sections
 def output_agent(
     report: GuardReport,
+    strict: bool = False,
     doctest_passed: bool = True,
     doctest_output: str = "",
     crosshair_output: dict | None = None,
     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).
+    """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
+        strict: Whether warnings are treated as errors
         doctest_passed: Whether doctests passed
         doctest_output: Doctest stdout (only if failed)
         crosshair_output: CrossHair results dict
         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
 
-    output = format_guard_agent(report)
+    # DX-26: Extract passed status from phase outputs
+    crosshair_passed = True
+    if crosshair_output:
+        crosshair_status = crosshair_output.get("status", "verified")
+        crosshair_passed = crosshair_status in ("verified", "skipped")
+
+    property_passed = True
+    if property_output:
+        property_status = property_output.get("status", "passed")
+        property_passed = property_status in ("passed", "skipped")
+
+    # DX-26: Calculate combined status including all test phases
+    combined_status = get_combined_status(
+        report, strict, doctest_passed, crosshair_passed, property_passed
+    )
+
+    output = format_guard_agent(report, combined_status=combined_status)
     # DX-09: Add verification level for Agent transparency
     output["verification_level"] = verification_level
     # DX-06: Add doctest results to agent output
@@ -232,4 +308,10 @@ def output_agent(
     # DX-08: Add property test results if available
     if property_output:
         output["property_tests"] = property_output
+    # 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/mcp_config.py

@@ -100,6 +100,7 @@ def detect_available_methods() -> list[McpExecConfig]:
     return methods
 
 
+# @shell_orchestration: MCP method selection helper
 def get_recommended_method() -> McpExecConfig:
     """
     Get the recommended MCP execution method.
@@ -115,6 +116,7 @@ def get_recommended_method() -> McpExecConfig:
     return methods[0]
 
 
+# @shell_orchestration: MCP method lookup helper
 def get_method_by_name(name: str) -> McpExecConfig | None:
     """
     Get a specific MCP method by name.
@@ -139,6 +141,7 @@ def get_method_by_name(name: str) -> McpExecConfig | None:
     return None
 
 
+# @shell_orchestration: MCP configuration generator
 def generate_mcp_json(config: McpExecConfig | None = None) -> dict[str, Any]:
     """
     Generate .mcp.json content for the given configuration.