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

invar/mcp/server.py

@@ -3,18 +3,54 @@ Invar MCP Server implementation.
 
 Exposes invar guard, sig, and map as first-class MCP tools.
 Part of DX-16: Agent Tool Enforcement.
+DX-52: Added Phase 2 smart re-spawn for project Python compatibility.
 """
 
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 import sys
+from pathlib import Path
 from typing import Any
 
 from mcp.server import Server
 from mcp.types import TextContent, Tool
 
+from invar.shell.subprocess_env import should_respawn
+
+
+# @invar:allow shell_result: Pure validation helper, no I/O, returns tuple not Result
+# @shell_complexity: Security validation requires multiple checks
+def _validate_path(path: str) -> tuple[bool, str]:
+    """Validate path argument for safety.
+
+    Returns (is_valid, error_message).
+    Rejects paths that could be interpreted as shell commands or flags.
+    """
+    if not path:
+        return True, ""  # Empty path defaults to "." in handlers
+
+    # Reject if looks like a flag (starts with -)
+    if path.startswith("-"):
+        return False, f"Invalid path: cannot start with '-': {path}"
+
+    # Reject shell metacharacters that could cause issues
+    dangerous_chars = [";", "&", "|", "$", "`", "\n", "\r"]
+    for char in dangerous_chars:
+        if char in path:
+            return False, f"Invalid path: contains forbidden character: {char!r}"
+
+    # Try to resolve path - this catches malformed paths
+    try:
+        Path(path).resolve()
+    except (OSError, ValueError) as e:
+        return False, f"Invalid path: {e}"
+
+    return True, ""
+
+
 # Strong instructions for agent behavior (DX-16 + DX-17 + DX-26)
 INVAR_INSTRUCTIONS = """
 ## Invar Tool Usage (MANDATORY)
@@ -84,7 +120,7 @@ the MCP tools and may not follow the correct workflow.
 
 
 # @shell_orchestration: MCP tool factory - creates Tool objects
-# @invar:allow shell_result: MCP framework API returns Tool
+# @invar:allow shell_result: MCP tool factory for guard command
 def _get_guard_tool() -> Tool:
     """Define the invar_guard tool."""
     return Tool(
@@ -100,13 +136,14 @@ def _get_guard_tool() -> Tool:
                 "path": {"type": "string", "description": "Project path (default: .)", "default": "."},
                 "changed": {"type": "boolean", "description": "Only verify git-changed files", "default": True},
                 "strict": {"type": "boolean", "description": "Treat warnings as errors", "default": False},
+                "coverage": {"type": "boolean", "description": "DX-37: Collect branch coverage from doctest + hypothesis", "default": False},
             },
         },
     )
 
 
 # @shell_orchestration: MCP tool factory - creates Tool objects
-# @invar:allow shell_result: MCP framework API returns Tool
+# @invar:allow shell_result: MCP tool factory for sig command
 def _get_sig_tool() -> Tool:
     """Define the invar_sig tool."""
     return Tool(
@@ -126,7 +163,7 @@ def _get_sig_tool() -> Tool:
 
 
 # @shell_orchestration: MCP tool factory - creates Tool objects
-# @invar:allow shell_result: MCP framework API returns Tool
+# @invar:allow shell_result: MCP tool factory for map command
 def _get_map_tool() -> Tool:
     """Define the invar_map tool."""
     return Tool(
@@ -167,18 +204,25 @@ def create_server() -> Server:
 
 
 # @shell_orchestration: MCP handler - subprocess is called inside
-# @invar:allow shell_result: MCP framework API returns list[TextContent]
+# @shell_complexity: Guard command with multiple optional flags
+# @invar:allow shell_result: MCP handler for guard tool
 async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
     """Run invar guard command."""
-    cmd = [sys.executable, "-m", "invar.shell.cli", "guard"]
-
     path = args.get("path", ".")
+    is_valid, error = _validate_path(path)
+    if not is_valid:
+        return [TextContent(type="text", text=f"Error: {error}")]
+
+    cmd = [sys.executable, "-m", "invar.shell.commands.guard", "guard"]
     cmd.append(path)
 
     if args.get("changed", True):
         cmd.append("--changed")
     if args.get("strict", False):
         cmd.append("--strict")
+    # DX-37: Optional coverage collection
+    if args.get("coverage", False):
+        cmd.append("--coverage")
 
     # DX-26: TTY auto-detection - MCP runs in non-TTY, so agent JSON output is automatic
     # No explicit flag needed
@@ -187,24 +231,33 @@ async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
 
 
 # @shell_orchestration: MCP handler - subprocess is called inside
-# @invar:allow shell_result: MCP framework API returns list[TextContent]
+# @invar:allow shell_result: MCP handler for sig tool
 async def _run_sig(args: dict[str, Any]) -> list[TextContent]:
     """Run invar sig command."""
     target = args.get("target", "")
     if not target:
         return [TextContent(type="text", text="Error: target is required")]
 
-    cmd = [sys.executable, "-m", "invar.shell.cli", "sig", target, "--json"]
+    # Validate target (can be file path or file::symbol)
+    target_path = target.split("::")[0] if "::" in target else target
+    is_valid, error = _validate_path(target_path)
+    if not is_valid:
+        return [TextContent(type="text", text=f"Error: {error}")]
+
+    cmd = [sys.executable, "-m", "invar.shell.commands.guard", "sig", target, "--json"]
     return await _execute_command(cmd)
 
 
 # @shell_orchestration: MCP handler - subprocess is called inside
-# @invar:allow shell_result: MCP framework API returns list[TextContent]
+# @invar:allow shell_result: MCP handler for map tool
 async def _run_map(args: dict[str, Any]) -> list[TextContent]:
     """Run invar map command."""
-    cmd = [sys.executable, "-m", "invar.shell.cli", "map"]
-
     path = args.get("path", ".")
+    is_valid, error = _validate_path(path)
+    if not is_valid:
+        return [TextContent(type="text", text=f"Error: {error}")]
+
+    cmd = [sys.executable, "-m", "invar.shell.commands.guard", "map"]
     cmd.append(path)
 
     top = args.get("top", 10)
@@ -215,15 +268,20 @@ async def _run_map(args: dict[str, Any]) -> list[TextContent]:
 
 
 # @shell_complexity: Command execution with error handling branches
-# @invar:allow shell_result: MCP framework API returns list[TextContent]
-async def _execute_command(cmd: list[str]) -> list[TextContent]:
-    """Execute a command and return the result."""
+# @invar:allow shell_result: MCP subprocess wrapper utility
+async def _execute_command(cmd: list[str], timeout: int = 600) -> list[TextContent]:
+    """Execute a command and return the result.
+
+    Args:
+        cmd: Command to execute
+        timeout: Maximum time in seconds (default: 600, accommodates full Guard cycle)
+    """
     try:
         result = subprocess.run(
             cmd,
             capture_output=True,
             text=True,
-            timeout=120,
+            timeout=timeout,
         )
 
         output = result.stdout
@@ -240,18 +298,43 @@ async def _execute_command(cmd: list[str]) -> list[TextContent]:
         return [TextContent(type="text", text=output)]
 
     except subprocess.TimeoutExpired:
-        return [TextContent(type="text", text="Error: Command timed out (120s)")]
+        return [TextContent(type="text", text=f"Error: Command timed out ({timeout}s)")]
     except Exception as e:
         return [TextContent(type="text", text=f"Error: {e}")]
 
 
 # @shell_orchestration: MCP server entry point - runs async server
 def run_server() -> None:
-    """Run the Invar MCP server."""
+    """Run the Invar MCP server.
+
+    DX-52 Phase 2: If project has invar installed, re-spawn with project Python
+    to ensure C extensions are compatible with project's Python version.
+    """
     import asyncio
 
     from mcp.server.stdio import stdio_server
 
+    # DX-52 Phase 2: Smart re-spawn with project Python
+    cwd = Path.cwd()
+    do_respawn, project_python = should_respawn(cwd)
+
+    if do_respawn and project_python is not None:
+        # Re-spawn with project Python (has both invar AND project deps)
+        import subprocess
+        import sys
+
+        if os.name == "nt":
+            # Windows: execv doesn't replace process, use subprocess + exit
+            result = subprocess.call([str(project_python), "-m", "invar.mcp"])
+            sys.exit(result)
+        else:
+            # Unix: execv replaces current process, does not return
+            os.execv(
+                str(project_python),
+                [str(project_python), "-m", "invar.mcp"],
+            )
+
+    # Phase 1 fallback: Continue with uvx + PYTHONPATH injection
     async def main():
         server = create_server()
         async with stdio_server() as (read_stream, write_stream):

invar/shell/commands/__init__.py

@@ -0,0 +1,11 @@
+"""
+CLI commands for Invar.
+
+This module contains Typer command implementations:
+- guard: Main verification command
+- init: Project initialization
+- update: Update INVAR.md from template
+- test: Run property tests
+- mutate: Run mutation testing
+- perception: Map and sig commands
+"""

invar/shell/{cli.py → commands/guard.py}

@@ -56,14 +56,19 @@ def _count_core_functions(file_info) -> tuple[int, int]:
     return (total, with_contracts)
 
 
+# @shell_complexity: Core orchestration - iterates files, handles failures, aggregates results
 # @shell_complexity: Core orchestration - iterates files, handles failures, aggregates results
 def _scan_and_check(
     path: Path, config: RuleConfig, only_files: set[Path] | None = None
 ) -> Result[GuardReport, str]:
     """Scan project files and check against rules."""
+    from invar.core.entry_points import extract_escape_hatches
+    from invar.core.review_trigger import check_duplicate_escape_reasons
     from invar.core.shell_architecture import check_complexity_debt
 
     report = GuardReport(files_checked=0)
+    all_escapes: list[tuple[str, str, str]] = []  # DX-33: (file, rule, reason)
+
     for file_result in scan_project(path, only_files):
         if isinstance(file_result, Failure):
             console.print(f"[yellow]Warning:[/yellow] {file_result.failure()}")
@@ -75,6 +80,10 @@ def _scan_and_check(
         report.update_coverage(total, with_contracts)
         for violation in check_all_rules(file_info, config):
             report.add_violation(violation)
+        # DX-33: Collect escape hatches for cross-file analysis
+        if file_info.source:
+            for rule, reason in extract_escape_hatches(file_info.source):
+                all_escapes.append((file_info.path, rule, reason))
 
     # DX-22: Check project-level complexity debt (Fix-or-Explain enforcement)
     for debt_violation in check_complexity_debt(
@@ -82,6 +91,10 @@ def _scan_and_check(
     ):
         report.add_violation(debt_violation)
 
+    # DX-33: Check for duplicate escape reasons across files
+    for escape_violation in check_duplicate_escape_reasons(all_escapes):
+        report.add_violation(escape_violation)
+
     return Success(report)
 
 
@@ -117,6 +130,9 @@ def guard(
     json_output: bool = typer.Option(
         False, "--json", hidden=True, help="[Deprecated] Use TTY auto-detection instead"
     ),
+    coverage: bool = typer.Option(
+        False, "--coverage", help="DX-37: Collect branch coverage from doctest + hypothesis"
+    ),
 ) -> None:
     """Check project against Invar architecture rules.
 
@@ -179,32 +195,76 @@ def guard(
     # Run verification phases
     static_exit_code = get_exit_code(report, strict)
     doctest_passed, doctest_output = True, ""
-    crosshair_passed, crosshair_output = True, {}
-    property_passed, property_output = True, {}
+    crosshair_passed: bool = True
+    crosshair_output: dict = {}
+    property_passed: bool = True
+    property_output: dict = {}
+    # DX-37: Coverage data from doctest + hypothesis phases
+    doctest_coverage: dict | None = None
+    property_coverage: dict | None = None
+
+    # DX-37: Check coverage availability if requested
+    if coverage:
+        from invar.shell.coverage import check_coverage_available
+        cov_check = check_coverage_available()
+        if isinstance(cov_check, Failure):
+            console.print(f"[yellow]Warning:[/yellow] {cov_check.failure()}")
+            coverage = False  # Disable coverage if not available
 
     # DX-19: STANDARD runs all verification phases
     if verification_level == VerificationLevel.STANDARD and static_exit_code == 0:
         checked_files = collect_files_to_check(path, checked_files)
 
-        # Phase 1: Doctests
-        doctest_passed, doctest_output = run_doctests_phase(checked_files, explain)
+        # Phase 1: Doctests (DX-37: with optional coverage)
+        doctest_passed, doctest_output, doctest_coverage = run_doctests_phase(
+            checked_files, explain, timeout=config.timeout_doctest,
+            collect_coverage=coverage,
+        )
 
         # Phase 2: CrossHair symbolic verification
+        # Note: CrossHair uses subprocess + symbolic execution, coverage not applicable
         crosshair_passed, crosshair_output = run_crosshair_phase(
             path, checked_files, doctest_passed, static_exit_code,
             changed_mode=changed,
+            timeout=config.timeout_crosshair,
+            per_condition_timeout=config.timeout_crosshair_per_condition,
         )
 
-        # Phase 3: Hypothesis property tests
-        property_passed, property_output = run_property_tests_phase(
-            checked_files, doctest_passed, static_exit_code
+        # Phase 3: Hypothesis property tests (DX-37: with optional coverage)
+        property_passed, property_output, property_coverage = run_property_tests_phase(
+            checked_files, doctest_passed, static_exit_code,
+            collect_coverage=coverage,
         )
+    elif verification_level == VerificationLevel.STATIC:
+        # Static-only mode: explicitly mark verification as skipped
+        crosshair_output = {"status": "skipped", "reason": "static mode"}
+        property_output = {"status": "skipped", "reason": "static mode"}
+    elif static_exit_code != 0:
+        # Static failures: explicitly mark verification as skipped
+        crosshair_output = {"status": "skipped", "reason": "prior failures"}
+        property_output = {"status": "skipped", "reason": "prior failures"}
+
+    # DX-37: Merge coverage data from doctest + hypothesis
+    coverage_output: dict | None = None
+    if coverage and (doctest_coverage or property_coverage):
+        coverage_output = {
+            "enabled": True,
+            "phases_tracked": [],
+            "phases_excluded": ["crosshair"],  # CrossHair uses symbolic execution
+        }
+        if doctest_coverage and doctest_coverage.get("collected"):
+            coverage_output["phases_tracked"].append("doctest")
+        if property_coverage and property_coverage.get("collected"):
+            coverage_output["phases_tracked"].append("hypothesis")
+            if "overall_branch_coverage" in property_coverage:
+                coverage_output["overall_branch_coverage"] = property_coverage["overall_branch_coverage"]
 
     # DX-26: Unified output (agent JSON or human Rich)
     if use_agent_output:
         output_agent(
             report, strict, doctest_passed, doctest_output, crosshair_output, level_name,
             property_output=property_output,
+            coverage_data=coverage_output,  # DX-37
         )
     else:
         output_rich(report, config.strict_pure, changed, pedantic, explain, static)
@@ -214,6 +274,13 @@ def guard(
             property_output=property_output,
             strict=strict,
         )
+        # DX-37: Show coverage info in human output
+        if coverage_output and coverage_output.get("phases_tracked"):
+            phases = coverage_output.get("phases_tracked", [])
+            overall = coverage_output.get("overall_branch_coverage", 0.0)
+            console.print(f"\n[bold]Coverage Analysis[/bold] ({' + '.join(phases)})")
+            console.print(f"  Overall branch coverage: {overall}%")
+            console.print("  [dim]Note: CrossHair uses symbolic execution; coverage not applicable.[/dim]")
 
     # Exit with combined status
     all_passed = doctest_passed and crosshair_passed and property_passed
@@ -270,7 +337,7 @@ def map_command(
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
     """Generate symbol map with reference counts."""
-    from invar.shell.perception import run_map
+    from invar.shell.commands.perception import run_map
 
     # Phase 9 P11: Auto-detect agent mode
     use_json = json_output or _detect_agent_mode()
@@ -286,7 +353,7 @@ def sig_command(
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
     """Extract signatures from a file or symbol."""
-    from invar.shell.perception import run_sig
+    from invar.shell.commands.perception import run_sig
 
     # Phase 9 P11: Auto-detect agent mode
     use_json = json_output or _detect_agent_mode()
@@ -369,11 +436,12 @@ def rules(
         console.print(f"\n[dim]{len(rules_list)} rules total. Use --json for full details.[/dim]")
 
 
-# Import commands from separate modules to reduce file size
-from invar.shell.init_cmd import init
-from invar.shell.mutate_cmd import mutate  # DX-28
-from invar.shell.test_cmd import test, verify
-from invar.shell.update_cmd import update
+# DX-48b: Import commands from shell/commands/
+from invar.shell.commands.init import init
+from invar.shell.commands.mutate import mutate  # DX-28
+from invar.shell.commands.sync_self import sync_self  # DX-49
+from invar.shell.commands.test import test, verify
+from invar.shell.commands.update import update
 
 app.command()(init)
 app.command()(update)
@@ -381,6 +449,18 @@ app.command()(test)
 app.command()(verify)
 app.command()(mutate)  # DX-28: Mutation testing
 
+# DX-56: Create dev subcommand group for developer commands
+dev_app = typer.Typer(
+    name="dev",
+    help="Developer commands for Invar project development",
+    add_completion=False,
+)
+dev_app.command("sync")(sync_self)  # DX-56: renamed from sync-self
+app.add_typer(dev_app)
+
+# DX-56: Keep sync-self as alias for backward compatibility (deprecated)
+app.command("sync-self", hidden=True)(sync_self)
+
 
 if __name__ == "__main__":
     app()