invar-tools 1.0.0__py3-none-any.whl

invar/shell/test_cmd.py

@@ -0,0 +1,117 @@
+"""
+Test and verify CLI commands.
+
+Extracted from cli.py to manage file size.
+DX-08: Updated to use contract-driven property testing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from returns.result import Failure
+from rich.console import Console
+
+from invar.shell.git import get_changed_files, is_git_repo
+
+console = Console()
+
+
+def _detect_agent_mode() -> bool:
+    """Detect agent context: INVAR_MODE=agent OR non-TTY (pipe/redirect)."""
+    import os
+    import sys
+
+    return os.getenv("INVAR_MODE") == "agent" or not sys.stdout.isatty()
+
+
+def test(
+    target: str = typer.Argument(None, help="File to test (optional with --changed)"),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help="Verbose output"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    changed: bool = typer.Option(False, "--changed", help="Test git-modified files only"),
+    max_examples: int = typer.Option(100, "--max-examples", help="Maximum Hypothesis examples per function"),
+) -> None:
+    """Run property-based tests using Hypothesis on contracted functions (DX-08)."""
+    from invar.shell.property_tests import (
+        format_property_test_report,
+        run_property_tests_on_files,
+    )
+
+    use_json = json_output or _detect_agent_mode()
+
+    # Get files to test
+    if changed:
+        if not is_git_repo(Path()):
+            console.print("[red]Error:[/red] --changed requires a git repository")
+            raise typer.Exit(1)
+        changed_result = get_changed_files(Path())
+        if isinstance(changed_result, Failure):
+            console.print(f"[red]Error:[/red] {changed_result.failure()}")
+            raise typer.Exit(1)
+        files = list(changed_result.unwrap())
+        if not files:
+            console.print("[green]No changed Python files.[/green]")
+            raise typer.Exit(0)
+    elif target:
+        files = [Path(target)]
+    else:
+        console.print("[red]Error:[/red] Either provide a file or use --changed")
+        raise typer.Exit(1)
+
+    # DX-08: Run property tests on files
+    result = run_property_tests_on_files(files, max_examples, verbose)
+
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+    report = result.unwrap()
+    output = format_property_test_report(report, use_json)
+    console.print(output)
+
+    if not report.all_passed():
+        raise typer.Exit(1)
+
+
+def verify(
+    target: str = typer.Argument(None, help="File to verify (optional with --changed)"),
+    timeout: int = typer.Option(30, "--timeout", help="Timeout per function (seconds)"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    changed: bool = typer.Option(False, "--changed", help="Verify git-modified files only"),
+) -> None:
+    """Run symbolic verification using CrossHair."""
+    from invar.shell.testing import run_verify
+
+    use_json = json_output or _detect_agent_mode()
+
+    # Get files to verify
+    if changed:
+        if not is_git_repo(Path()):
+            console.print("[red]Error:[/red] --changed requires a git repository")
+            raise typer.Exit(1)
+        changed_result = get_changed_files(Path())
+        if isinstance(changed_result, Failure):
+            console.print(f"[red]Error:[/red] {changed_result.failure()}")
+            raise typer.Exit(1)
+        files = list(changed_result.unwrap())
+        if not files:
+            console.print("[green]No changed Python files.[/green]")
+            raise typer.Exit(0)
+    elif target:
+        files = [Path(target)]
+    else:
+        console.print("[red]Error:[/red] Either provide a file or use --changed")
+        raise typer.Exit(1)
+
+    # Run verification on all files
+    all_passed = True
+    for file_path in files:
+        result = run_verify(str(file_path), use_json, timeout)
+        if isinstance(result, Failure):
+            console.print(f"[red]Error:[/red] {result.failure()}")
+            all_passed = False
+
+    if not all_passed:
+        raise typer.Exit(1)

invar/shell/testing.py

@@ -0,0 +1,297 @@
+"""
+Testing commands for Invar.
+
+Shell module: handles I/O for testing operations.
+Includes Smart Guard verification (DX-06).
+DX-12: Hypothesis as CrossHair fallback (see prove.py).
+"""
+
+from __future__ import annotations
+
+import json as json_lib
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from enum import IntEnum
+from pathlib import Path
+
+from returns.result import Failure, Result, Success
+from rich.console import Console
+
+# DX-12: Import from prove module
+# DX-13: Added get_files_to_prove, run_crosshair_parallel
+# DX-13: ProveCache extracted to prove_cache.py
+from invar.shell.prove import (
+    CrossHairStatus,
+    get_files_to_prove,
+    run_crosshair_on_files,
+    run_crosshair_parallel,
+    run_hypothesis_fallback,
+    run_prove_with_fallback,
+)
+from invar.shell.prove_cache import ProveCache
+
+console = Console()
+
+# Re-export for backwards compatibility
+# DX-13: Added get_files_to_prove, run_crosshair_parallel, ProveCache
+__all__ = [
+    "CrossHairStatus",
+    "ProveCache",
+    "VerificationLevel",
+    "VerificationResult",
+    "detect_verification_context",
+    "get_available_verifiers",
+    "get_files_to_prove",
+    "run_crosshair_on_files",
+    "run_crosshair_parallel",
+    "run_doctests_on_files",
+    "run_hypothesis_fallback",
+    "run_prove_with_fallback",
+    "run_test",
+    "run_verify",
+]
+
+
+class VerificationLevel(IntEnum):
+    """Verification depth levels for Smart Guard.
+
+    DX-19: Simplified to 2 levels (Agent-Native: Zero decisions).
+    - STATIC: Quick debug mode (~0.5s)
+    - STANDARD: Full verification including CrossHair + Hypothesis (~5s)
+    """
+
+    STATIC = 0  # Static analysis only (--static, quick debug)
+    STANDARD = 1  # Full: static + doctests + CrossHair + Hypothesis (default)  # Static + doctests + property tests (--thorough, DX-08)
+
+
+@dataclass
+class VerificationResult:
+    """Results from Smart Guard verification."""
+
+    static_passed: bool = True
+    doctest_passed: bool | None = None
+    hypothesis_passed: bool | None = None
+    crosshair_passed: bool | None = None
+    doctest_output: str = ""
+    hypothesis_output: str = ""
+    crosshair_output: str = ""
+    files_tested: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+def get_available_verifiers() -> list[str]:
+    """
+    Detect installed verification tools.
+
+    Returns:
+        List of available verifier names.
+
+    >>> "static" in get_available_verifiers()
+    True
+    >>> "doctest" in get_available_verifiers()
+    True
+    """
+    available = ["static", "doctest"]  # Always available
+
+    try:
+        import hypothesis  # noqa: F401
+
+        available.append("hypothesis")
+    except ImportError:
+        pass
+
+    try:
+        import crosshair  # noqa: F401
+
+        available.append("crosshair")
+    except ImportError:
+        pass
+
+    return available
+
+
+def detect_verification_context() -> VerificationLevel:
+    """
+    Auto-detect appropriate verification depth based on context.
+
+    DX-19: Simplified to 2 levels. Always returns STANDARD (full verification).
+    STATIC is only used when explicitly requested via --static flag.
+
+    >>> detect_verification_context() == VerificationLevel.STANDARD
+    True
+    """
+    # DX-19: Always use STANDARD (full verification) by default
+    # STATIC is only for explicit --static flag
+    return VerificationLevel.STANDARD
+
+
+def run_doctests_on_files(
+    files: list[Path], verbose: bool = False
+) -> Result[dict, str]:
+    """
+    Run doctests on a list of Python files.
+
+    Args:
+        files: List of Python file paths to test
+        verbose: Show verbose output
+
+    Returns:
+        Success with test results or Failure with error message
+    """
+    if not files:
+        return Success({"status": "skipped", "reason": "no files", "files": []})
+
+    # Filter to Python files only
+    py_files = [f for f in files if f.suffix == ".py" and f.exists()]
+    if not py_files:
+        return Success({"status": "skipped", "reason": "no Python files", "files": []})
+
+    # Build pytest command
+    cmd = [
+        sys.executable, "-m", "pytest",
+        "--doctest-modules", "-x", "--tb=short",
+    ]
+    cmd.extend(str(f) for f in py_files)
+    if verbose:
+        cmd.append("-v")
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+        # Pytest exit codes: 0=passed, 5=no tests collected (also OK)
+        is_passed = result.returncode in (0, 5)
+        return Success({
+            "status": "passed" if is_passed else "failed",
+            "files": [str(f) for f in py_files],
+            "exit_code": result.returncode,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+        })
+    except subprocess.TimeoutExpired:
+        return Failure("Doctest timeout (120s)")
+    except Exception as e:
+        return Failure(f"Doctest error: {e}")
+
+
+def run_test(
+    target: str, json_output: bool = False, verbose: bool = False
+) -> Result[dict, str]:
+    """
+    Run property-based tests using Hypothesis via deal.cases.
+
+    Args:
+        target: File path or module to test
+        json_output: Output as JSON
+        verbose: Show verbose output
+
+    Returns:
+        Success with test results or Failure with error message
+    """
+    target_path = Path(target)
+    if not target_path.exists():
+        return Failure(f"Target not found: {target}")
+    if target_path.suffix != ".py":
+        return Failure(f"Target must be a Python file: {target}")
+
+    cmd = [
+        sys.executable, "-m", "pytest",
+        str(target_path), "--doctest-modules", "-x", "--tb=short",
+    ]
+    if verbose:
+        cmd.append("-v")
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+        test_result = {
+            "status": "passed" if result.returncode == 0 else "failed",
+            "target": str(target_path),
+            "exit_code": result.returncode,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+        }
+
+        if json_output:
+            console.print(json_lib.dumps(test_result, indent=2))
+        else:
+            if result.returncode == 0:
+                console.print(f"[green]✓[/green] Tests passed: {target}")
+                if verbose:
+                    console.print(result.stdout)
+            else:
+                console.print(f"[red]✗[/red] Tests failed: {target}")
+                console.print(result.stdout)
+                if result.stderr:
+                    console.print(f"[red]{result.stderr}[/red]")
+
+        return Success(test_result)
+    except subprocess.TimeoutExpired:
+        return Failure(f"Test timeout (300s): {target}")
+    except Exception as e:
+        return Failure(f"Test error: {e}")
+
+
+def run_verify(
+    target: str, json_output: bool = False, timeout: int = 30
+) -> Result[dict, str]:
+    """
+    Run symbolic verification using CrossHair.
+
+    Args:
+        target: File path or module to verify
+        json_output: Output as JSON
+        timeout: Timeout per function in seconds
+
+    Returns:
+        Success with verification results or Failure with error message
+    """
+    try:
+        import crosshair  # noqa: F401
+    except ImportError:
+        return Failure(
+            "CrossHair not installed. Run: pip install crosshair-tool\n"
+            "Note: CrossHair requires Python 3.8-3.12 (not 3.14)"
+        )
+
+    target_path = Path(target)
+    if not target_path.exists():
+        return Failure(f"Target not found: {target}")
+    if target_path.suffix != ".py":
+        return Failure(f"Target must be a Python file: {target}")
+
+    cmd = [
+        sys.executable, "-m", "crosshair", "check",
+        str(target_path), f"--per_condition_timeout={timeout}",
+    ]
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout * 10)
+
+        counterexamples = [
+            line.strip() for line in result.stdout.split("\n")
+            if "error" in line.lower() or "counterexample" in line.lower()
+        ]
+
+        verify_result = {
+            "status": "verified" if result.returncode == 0 else "counterexample_found",
+            "target": str(target_path),
+            "exit_code": result.returncode,
+            "counterexamples": counterexamples,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+        }
+
+        if json_output:
+            console.print(json_lib.dumps(verify_result, indent=2))
+        else:
+            if result.returncode == 0:
+                console.print(f"[green]✓[/green] Verified: {target}")
+            else:
+                console.print(f"[yellow]![/yellow] Counterexamples found: {target}")
+                for ce in counterexamples:
+                    console.print(f"  {ce}")
+
+        return Success(verify_result)
+    except subprocess.TimeoutExpired:
+        return Failure(f"Verification timeout ({timeout * 10}s): {target}")
+    except Exception as e:
+        return Failure(f"Verification error: {e}")

invar/shell/update_cmd.py

@@ -0,0 +1,191 @@
+"""
+Update command for Invar.
+
+Shell module: handles updating Invar-managed files to latest version.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import typer
+from returns.result import Failure, Result, Success
+from rich.console import Console
+
+from invar.shell.templates import copy_examples_directory, get_template_path
+
+console = Console()
+
+# Version pattern: matches "v3.23" or "v3.23.1"
+VERSION_PATTERN = re.compile(r"v(\d+)\.(\d+)(?:\.(\d+))?")
+
+
+def parse_version(text: str) -> tuple[int, int, int] | None:
+    """
+    Parse version string from text.
+
+    >>> parse_version("Protocol v3.23")
+    (3, 23, 0)
+    >>> parse_version("v3.23.1")
+    (3, 23, 1)
+    >>> parse_version("no version here")
+    """
+    match = VERSION_PATTERN.search(text)
+    if match:
+        major = int(match.group(1))
+        minor = int(match.group(2))
+        patch = int(match.group(3)) if match.group(3) else 0
+        return (major, minor, patch)
+    return None
+
+
+def get_current_version(path: Path) -> Result[tuple[int, int, int], str]:
+    """Get version from current INVAR.md file."""
+    invar_md = path / "INVAR.md"
+    if not invar_md.exists():
+        return Failure("INVAR.md not found. Run 'invar init' first.")
+
+    try:
+        content = invar_md.read_text()
+        version = parse_version(content)
+        if version is None:
+            return Failure("Could not parse version from INVAR.md")
+        return Success(version)
+    except OSError as e:
+        return Failure(f"Failed to read INVAR.md: {e}")
+
+
+def get_template_version() -> Result[tuple[int, int, int], str]:
+    """Get version from template INVAR.md."""
+    template_result = get_template_path("INVAR.md")
+    if isinstance(template_result, Failure):
+        return template_result
+
+    template_path = template_result.unwrap()
+    try:
+        content = template_path.read_text()
+        version = parse_version(content)
+        if version is None:
+            return Failure("Could not parse version from template")
+        return Success(version)
+    except OSError as e:
+        return Failure(f"Failed to read template: {e}")
+
+
+def format_version(version: tuple[int, int, int]) -> str:
+    """Format version tuple as string."""
+    if version[2] == 0:
+        return f"v{version[0]}.{version[1]}"
+    return f"v{version[0]}.{version[1]}.{version[2]}"
+
+
+def update_invar_md(path: Path, console: Console) -> Result[bool, str]:
+    """Update INVAR.md by overwriting with template."""
+    template_result = get_template_path("INVAR.md")
+    if isinstance(template_result, Failure):
+        return template_result
+
+    template_path = template_result.unwrap()
+    dest_file = path / "INVAR.md"
+
+    try:
+        dest_file.write_text(template_path.read_text())
+        return Success(True)
+    except OSError as e:
+        return Failure(f"Failed to update INVAR.md: {e}")
+
+
+def update_examples(path: Path, console: Console) -> Result[bool, str]:
+    """Update .invar/examples/ directory."""
+    import shutil
+
+    examples_dest = path / ".invar" / "examples"
+
+    # Remove existing examples
+    if examples_dest.exists():
+        try:
+            shutil.rmtree(examples_dest)
+        except OSError as e:
+            return Failure(f"Failed to remove old examples: {e}")
+
+    # Copy new examples
+    return copy_examples_directory(path, console)
+
+
+def update(
+    path: Path = typer.Argument(Path(), help="Project root directory"),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Update even if already at latest version"
+    ),
+    check: bool = typer.Option(
+        False, "--check", help="Check for updates without applying"
+    ),
+) -> None:
+    """
+    Update Invar-managed files to latest version.
+
+    Updates INVAR.md and .invar/examples/ from the installed python-invar package.
+    User-managed files (CLAUDE.md, .invar/context.md) are never modified.
+
+    Use --check to see if updates are available without applying them.
+    Use --force to update even if already at latest version.
+    """
+    # Get current version
+    current_result = get_current_version(path)
+    if isinstance(current_result, Failure):
+        console.print(f"[red]Error:[/red] {current_result.failure()}")
+        raise typer.Exit(1)
+    current_version = current_result.unwrap()
+
+    # Get template version
+    template_result = get_template_version()
+    if isinstance(template_result, Failure):
+        console.print(f"[red]Error:[/red] {template_result.failure()}")
+        raise typer.Exit(1)
+    template_version = template_result.unwrap()
+
+    current_str = format_version(current_version)
+    template_str = format_version(template_version)
+
+    # Compare versions
+    needs_update = template_version > current_version
+
+    if check:
+        # Check mode: just report status
+        if needs_update:
+            console.print(f"[yellow]Update available:[/yellow] {current_str} → {template_str}")
+        else:
+            console.print(f"[green]Up to date:[/green] {current_str}")
+        return
+
+    if not needs_update and not force:
+        console.print(f"[green]Already at latest version:[/green] {current_str}")
+        console.print("[dim]Use --force to update anyway[/dim]")
+        return
+
+    # Perform update
+    console.print("\n[bold]Updating Invar files...[/bold]")
+    console.print(f"  Version: {current_str} → {template_str}")
+    console.print()
+
+    # Update INVAR.md
+    result = update_invar_md(path, console)
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+    console.print(f"[green]Updated[/green] INVAR.md ({template_str})")
+
+    # Update examples
+    result = update_examples(path, console)
+    if isinstance(result, Failure):
+        console.print(f"[yellow]Warning:[/yellow] {result.failure()}")
+    else:
+        console.print("[green]Updated[/green] .invar/examples/")
+
+    # Remind about user-managed files
+    console.print()
+    console.print("[dim]User-managed files unchanged:[/dim]")
+    console.print("[dim]  ○ CLAUDE.md[/dim]")
+    console.print("[dim]  ○ .invar/context.md[/dim]")
+    console.print("[dim]  ○ pyproject.toml [tool.invar][/dim]")

invar/templates/CLAUDE.md.template

@@ -0,0 +1,58 @@
+# Project Development Guide
+
+> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Session Start, ICIDIV workflow, and Task Completion requirements.
+
+## Claude-Specific: Entry Verification
+
+Your **first message** for any implementation task MUST include actual output from:
+
+```
+invar_guard(changed=true)   # or: invar guard --changed
+invar_map(top=10)           # or: invar map --top 10
+```
+
+**Use MCP tools if available**, otherwise use CLI commands.
+
+No output = Session not started correctly. Stop, execute tools, restart.
+
+This ensures you've followed the Session Start requirements in INVAR.md.
+
+---
+
+## Project Structure
+
+```
+src/{project}/
+├── core/    # Pure logic (@pre/@post, doctests, no I/O)
+└── shell/   # I/O operations (Result[T, E] return type)
+```
+
+**Key insight:** Core receives data (strings), Shell handles I/O (paths, files).
+
+## Quick Reference
+
+| Zone | Requirements |
+|------|-------------|
+| Core | `@pre`/`@post` + doctests, pure (no I/O) |
+| Shell | Returns `Result[T, E]` from `returns` library |
+
+## Documentation Structure
+
+| File | Owner | Edit? | Purpose |
+|------|-------|-------|---------|
+| INVAR.md | Invar | No | Protocol (`invar update` to sync) |
+| CLAUDE.md | User | Yes | Project customization (this file) |
+| .invar/context.md | User | Yes | Project state, lessons learned |
+| .invar/examples/ | Invar | No | **Must read:** Core/Shell patterns |
+
+## Project-Specific Rules
+
+<!-- Add your team conventions below -->
+
+## Overrides
+
+<!-- Document any exceptions to INVAR.md rules -->
+
+---
+
+*Generated by `invar init`. Customize freely.*