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

invar/core/verification_routing.py

@@ -0,0 +1,155 @@
+"""
+Verification routing logic for smart tool selection.
+
+DX-22: Automatically routes code to CrossHair or Hypothesis based on imports.
+Core module: Pure logic, no I/O.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+from deal import post
+
+
+class VerificationTool(Enum):
+    """Verification tool selection."""
+
+    CROSSHAIR = "crosshair"
+    HYPOTHESIS = "hypothesis"
+    SKIP = "skip"
+
+
+# C extensions that CrossHair cannot symbolically execute
+# These libraries use native code that breaks symbolic execution
+CROSSHAIR_INCOMPATIBLE_LIBS = frozenset(
+    [
+        # Scientific computing (C/Fortran extensions)
+        "numpy",
+        "pandas",
+        "scipy",
+        "sklearn",
+        "scikit-learn",
+        # Deep learning (CUDA/C++ backends)
+        "torch",
+        "tensorflow",
+        "keras",
+        "jax",
+        # Image processing (C extensions)
+        "cv2",
+        "PIL",
+        "pillow",
+        "skimage",
+        # Network I/O (non-deterministic)
+        "requests",
+        "aiohttp",
+        "httpx",
+        "urllib3",
+        # System calls (side effects)
+        "subprocess",
+        "multiprocessing",
+        # Database I/O
+        "sqlalchemy",
+        "psycopg2",
+        "pymongo",
+    ]
+)
+
+# Regex pattern to detect imports
+# Matches: import numpy, from numpy import, import numpy as np
+_IMPORT_PATTERN = re.compile(
+    r"^\s*(?:import\s+(\w+)|from\s+(\w+)(?:\.\w+)*\s+import)",
+    re.MULTILINE,
+)
+
+
+# @invar:allow missing_contract: Boolean predicate, empty string returns False
+def has_incompatible_imports(source: str) -> bool:
+    """
+    Check if source contains imports incompatible with CrossHair.
+
+    DX-22: Detects C extension libraries that cannot be symbolically executed.
+    Used to route code directly to Hypothesis instead of wasting time on CrossHair.
+
+    Examples:
+        >>> has_incompatible_imports("import numpy as np")
+        True
+        >>> has_incompatible_imports("from pandas import DataFrame")
+        True
+        >>> has_incompatible_imports("from pathlib import Path")
+        False
+        >>> has_incompatible_imports("import json")
+        False
+        >>> has_incompatible_imports("from sklearn.model_selection import train_test_split")
+        True
+        >>> has_incompatible_imports("import torch.nn as nn")
+        True
+        >>> has_incompatible_imports("")
+        False
+    """
+    # Early return for empty/whitespace-only strings (avoids regex edge cases)
+    if not source or not source.strip():
+        return False
+    for match in _IMPORT_PATTERN.finditer(source):
+        lib = match.group(1) or match.group(2)
+        if lib and lib.lower() in CROSSHAIR_INCOMPATIBLE_LIBS:
+            return True
+    return False
+
+
+@post(lambda result: all(lib in CROSSHAIR_INCOMPATIBLE_LIBS for lib in result))
+def get_incompatible_imports(source: str) -> set[str]:
+    """
+    Get the set of incompatible libraries imported in source.
+
+    Examples:
+        >>> sorted(get_incompatible_imports("import numpy\\nfrom pandas import DataFrame"))
+        ['numpy', 'pandas']
+        >>> get_incompatible_imports("import json")
+        set()
+        >>> sorted(get_incompatible_imports("import torch\\nimport tensorflow"))
+        ['tensorflow', 'torch']
+        >>> get_incompatible_imports("")
+        set()
+    """
+    # Early return for empty/whitespace-only strings (avoids regex edge cases)
+    if not source or not source.strip():
+        return set()
+    incompatible: set[str] = set()
+    for match in _IMPORT_PATTERN.finditer(source):
+        lib = match.group(1) or match.group(2)
+        if lib and lib.lower() in CROSSHAIR_INCOMPATIBLE_LIBS:
+            incompatible.add(lib.lower())
+    return incompatible
+
+
+@post(lambda result: result in VerificationTool)  # Returns valid enum member
+def select_verification_tool(source: str, has_contracts: bool) -> VerificationTool:
+    """
+    Select the appropriate verification tool for a source file.
+
+    DX-22 Smart Routing:
+    - No contracts -> SKIP (nothing to verify)
+    - Has C extensions -> HYPOTHESIS (CrossHair will fail)
+    - Pure Python with contracts -> CROSSHAIR (can prove correctness)
+
+    Examples:
+        >>> select_verification_tool("def foo(): pass", has_contracts=False)
+        <VerificationTool.SKIP: 'skip'>
+        >>> select_verification_tool("import numpy\\n@pre(lambda x: x > 0)\\ndef foo(x): pass", has_contracts=True)
+        <VerificationTool.HYPOTHESIS: 'hypothesis'>
+        >>> select_verification_tool("@pre(lambda x: x > 0)\\ndef foo(x): pass", has_contracts=True)
+        <VerificationTool.CROSSHAIR: 'crosshair'>
+        >>> select_verification_tool("", has_contracts=False)
+        <VerificationTool.SKIP: 'skip'>
+        >>> select_verification_tool("", has_contracts=True)
+        <VerificationTool.CROSSHAIR: 'crosshair'>
+    """
+    if not has_contracts:
+        return VerificationTool.SKIP
+
+    if has_incompatible_imports(source):
+        return VerificationTool.HYPOTHESIS
+
+    return VerificationTool.CROSSHAIR

invar/mcp/server.py

@@ -3,19 +3,55 @@ 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
 
-# Strong instructions for agent behavior (DX-16 + DX-17)
+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)
 
@@ -83,6 +119,8 @@ the MCP tools and may not follow the correct workflow.
 """
 
 
+# @shell_orchestration: MCP tool factory - creates Tool objects
+# @invar:allow shell_result: MCP tool factory for guard command
 def _get_guard_tool() -> Tool:
     """Define the invar_guard tool."""
     return Tool(
@@ -98,11 +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 tool factory for sig command
 def _get_sig_tool() -> Tool:
     """Define the invar_sig tool."""
     return Tool(
@@ -121,6 +162,8 @@ def _get_sig_tool() -> Tool:
     )
 
 
+# @shell_orchestration: MCP tool factory - creates Tool objects
+# @invar:allow shell_result: MCP tool factory for map command
 def _get_map_tool() -> Tool:
     """Define the invar_map tool."""
     return Tool(
@@ -139,6 +182,8 @@ def _get_map_tool() -> Tool:
     )
 
 
+# @shell_orchestration: MCP server setup - registers handlers with framework
+# @invar:allow shell_result: MCP framework API returns Server
 def create_server() -> Server:
     """Create and configure the Invar MCP server."""
     server = Server(name="invar", version="0.1.0", instructions=INVAR_INSTRUCTIONS)
@@ -158,39 +203,61 @@ def create_server() -> Server:
     return server
 
 
+# @shell_orchestration: MCP handler - subprocess is called inside
+# @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")
 
-    # Always use JSON output for agent consumption
-    cmd.append("--json")
+    # DX-26: TTY auto-detection - MCP runs in non-TTY, so agent JSON output is automatic
+    # No explicit flag needed
 
     return await _execute_command(cmd)
 
 
+# @shell_orchestration: MCP handler - subprocess is called inside
+# @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 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)
@@ -200,14 +267,21 @@ async def _run_map(args: dict[str, Any]) -> list[TextContent]:
     return await _execute_command(cmd)
 
 
-async def _execute_command(cmd: list[str]) -> list[TextContent]:
-    """Execute a command and return the result."""
+# @shell_complexity: Command execution with error handling branches
+# @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
@@ -224,17 +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
+"""