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

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,6 +80,7 @@ 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]:
@@ -99,6 +103,8 @@ def run_doctests_phase(
     return False, doctest_result.failure()
 
 
+# @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],
@@ -161,6 +167,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 +176,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,7 +223,22 @@ 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,
@@ -238,24 +273,40 @@ def run_property_tests_phase(
 
     if isinstance(result, Success):
         report = 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,
         }
 
     return False, {"status": "error", "error": result.failure()}
 
 
+# @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 +326,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,62 @@ 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
 ) -> 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).
 
     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)
+
+    DX-22: Adds routing stats showing CrossHair vs Hypothesis distribution.
+    DX-26: status now reflects ALL test phases, not just static analysis.
     """
     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 +305,7 @@ 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
     console.print(json.dumps(output, indent=2))

invar/shell/init_cmd.py

@@ -24,6 +24,7 @@ from invar.shell.mcp_config import (
 from invar.shell.templates import (
     add_config,
     add_invar_reference,
+    copy_commands_directory,
     copy_examples_directory,
     copy_template,
     create_agent_config,
@@ -35,6 +36,7 @@ from invar.shell.templates import (
 console = Console()
 
 
+# @shell_complexity: Claude init with config file detection
 def run_claude_init(path: Path) -> bool:
     """
     Run 'claude /init' to generate intelligent CLAUDE.md.
@@ -95,16 +97,27 @@ def append_invar_reference_to_claude_md(path: Path) -> bool:
 
 ## Invar Protocol
 
-> **Protocol:** Follow [INVAR.md](./INVAR.md) for the Invar development methodology.
+> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion.
 
-Your **first message** for any implementation task MUST include actual output from:
+### Check-In
 
-```bash
-invar guard --changed   # or: invar_guard(changed=true)
-invar map --top 10      # or: invar_map(top=10)
+Your first message MUST display:
+
+```
+✓ Check-In: guard PASS | top: <entry1>, <entry2>
+```
+
+Execute `invar guard --changed` and `invar map --top 10`, then show this one-line summary.
+
+### Final
+
+Your last message MUST display:
+
+```
+✓ Final: guard PASS | 0 errors, 2 warnings
 ```
 
-**Use MCP tools if available**, otherwise use CLI commands.
+Execute `invar guard` and show this one-line summary.
 """
 
     claude_md.write_text(content + invar_reference)
@@ -112,6 +125,7 @@ invar map --top 10      # or: invar_map(top=10)
     return True
 
 
+# @shell_complexity: MCP config with method selection and validation
 def configure_mcp_with_method(
     path: Path, mcp_method: str | None
 ) -> None:
@@ -163,6 +177,7 @@ def show_available_mcp_methods() -> None:
         console.print(f"  {marker} {method.method.value}: {method.description}")
 
 
+# @shell_complexity: Project init with config detection and template setup
 def init(
     path: Path = typer.Argument(Path(), help="Project root directory"),
     claude: bool = typer.Option(
@@ -187,7 +202,9 @@ def init(
     Initialize Invar configuration in a project.
 
     Works with or without pyproject.toml:
-    - If pyproject.toml exists: adds [tool.invar.guard] section
+
+    \b
+    - If pyproject.toml exists: adds tool.invar section
     - Otherwise: creates invar.toml
 
     Use --claude to run 'claude /init' first (recommended for Claude Code users).
@@ -256,6 +273,9 @@ def init(
             # Create full template with workflow enforcement (DX-17)
             create_agent_config(path, agent, console)
 
+    # Copy Claude commands (DX-32: /review skill with Mode Detection)
+    copy_commands_directory(path, console)
+
     # Configure MCP server (DX-16, DX-21B)
     configure_mcp_with_method(path, mcp_method)
 

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.

invar/shell/mutate_cmd.py

@@ -0,0 +1,184 @@
+"""
+Mutation testing command for Invar CLI.
+
+DX-28: `invar mutate` wraps mutmut to detect undertested code.
+"""
+
+from __future__ import annotations
+
+import json as json_lib
+from pathlib import Path
+
+import typer
+from returns.result import Failure
+from rich.console import Console
+
+from invar.shell.mutation import (
+    MutationResult,
+    check_mutmut_installed,
+    get_surviving_mutants,
+    run_mutation_test,
+    show_mutant,
+)
+
+console = Console()
+
+
+# @shell:entry - CLI command entry point
+# @invar:allow entry_point_too_thick: CLI orchestration with multiple output modes
+def mutate(
+    target: Path = typer.Argument(
+        Path(),
+        help="File or directory to mutate",
+        exists=True,
+    ),
+    tests: Path = typer.Option(
+        None,
+        "--tests",
+        "-t",
+        help="Test directory (auto-detected if not specified)",
+    ),
+    timeout: int = typer.Option(
+        300,
+        "--timeout",
+        help="Maximum time in seconds",
+    ),
+    show_survivors: bool = typer.Option(
+        False,
+        "--survivors",
+        "-s",
+        help="Show surviving mutants",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output as JSON",
+    ),
+) -> None:
+    """
+    Run mutation testing to find undertested code.
+
+    DX-28: Uses mutmut to automatically mutate code (e.g., `in` → `not in`)
+    and check if tests catch the mutations. Surviving mutants indicate
+    weak test coverage.
+
+    Examples:
+
+        invar mutate src/myapp/core/parser.py
+
+        invar mutate src/myapp --tests tests/ --timeout 600
+
+        invar mutate --survivors  # Show surviving mutants from last run
+    """
+    # Check if mutmut is installed
+    install_check = check_mutmut_installed()
+    if isinstance(install_check, Failure):
+        if json_output:
+            console.print(json_lib.dumps({"error": install_check.failure()}))
+        else:
+            console.print(f"[red]Error:[/red] {install_check.failure()}")
+            console.print("\n[dim]Install with: pip install mutmut[/dim]")
+        raise typer.Exit(1)
+
+    # If just showing survivors from last run
+    if show_survivors:
+        result = get_surviving_mutants(target)
+        if isinstance(result, Failure):
+            if json_output:
+                console.print(json_lib.dumps({"error": result.failure()}))
+            else:
+                console.print(f"[red]Error:[/red] {result.failure()}")
+            raise typer.Exit(1)
+
+        survivors = result.unwrap()
+        if json_output:
+            console.print(json_lib.dumps({"survivors": survivors}))
+        else:
+            if survivors:
+                console.print(f"[yellow]Surviving mutants ({len(survivors)}):[/yellow]")
+                for s in survivors:
+                    console.print(f"  {s}")
+            else:
+                console.print("[green]No surviving mutants![/green]")
+        return
+
+    # Run mutation testing
+    if not json_output:
+        console.print(f"[bold]Running mutation testing on {target}...[/bold]")
+        console.print("[dim]This may take a while.[/dim]\n")
+
+    result = run_mutation_test(target, tests, timeout)
+
+    if isinstance(result, Failure):
+        if json_output:
+            console.print(json_lib.dumps({"error": result.failure()}))
+        else:
+            console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+    mutation_result = result.unwrap()
+    _display_mutation_result(mutation_result, json_output)
+
+    # Exit with error if mutation score is too low
+    if not mutation_result.passed:
+        raise typer.Exit(1)
+
+
+# @shell_complexity: Result display with dual output modes (JSON/human)
+def _display_mutation_result(result: MutationResult, json_output: bool) -> None:
+    """Display mutation testing results."""
+    if json_output:
+        data = {
+            "total": result.total,
+            "killed": result.killed,
+            "survived": result.survived,
+            "timeout": result.timeout,
+            "score": round(result.score, 1),
+            "passed": result.passed,
+            "errors": result.errors,
+            "survivors": result.survivors,
+        }
+        console.print(json_lib.dumps(data, indent=2))
+    else:
+        # Human-readable output
+        score_color = "green" if result.passed else "red"
+
+        console.print("\n[bold]Mutation Testing Results[/bold]")
+        console.print(f"  Total mutants: {result.total}")
+        console.print(f"  [green]Killed:[/green] {result.killed}")
+        console.print(f"  [red]Survived:[/red] {result.survived}")
+        if result.timeout > 0:
+            console.print(f"  [yellow]Timeout:[/yellow] {result.timeout}")
+
+        console.print(
+            f"\n  [{score_color}]Mutation Score: {result.score:.1f}%[/{score_color}]"
+        )
+
+        if result.passed:
+            console.print("\n[green]✓ Mutation testing passed (≥80% killed)[/green]")
+        else:
+            console.print("\n[red]✗ Mutation testing failed (<80% killed)[/red]")
+            console.print("[dim]Run with --survivors to see surviving mutants[/dim]")
+
+        if result.errors:
+            console.print("\n[yellow]Errors:[/yellow]")
+            for err in result.errors:
+                console.print(f"  {err}")
+
+
+# @shell:entry - CLI command for showing mutant details
+def mutant_show(
+    mutant_id: int = typer.Argument(..., help="Mutant ID to show"),
+) -> None:
+    """
+    Show the diff for a specific mutant.
+
+    Use after `invar mutate --survivors` to investigate surviving mutants.
+    """
+    result = show_mutant(mutant_id)
+
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+    console.print(result.unwrap())