invar-tools 1.0.0__py3-none-any.whl

invar/shell/fs.py

@@ -0,0 +1,112 @@
+"""
+File system operations.
+
+Shell module: performs file I/O operations.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from returns.result import Failure, Result, Success
+
+from invar.core.models import FileInfo
+from invar.core.parser import parse_source
+from invar.shell.config import classify_file, get_exclude_paths
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+
+def discover_python_files(
+    project_root: Path,
+    exclude_patterns: list[str] | None = None,
+) -> Iterator[Path]:
+    """
+    Discover all Python files in a project.
+
+    Args:
+        project_root: Root directory to search
+        exclude_patterns: Patterns to exclude (uses config defaults if None)
+
+    Yields:
+        Path objects for each Python file found
+    """
+    if exclude_patterns is None:
+        exclude_result = get_exclude_paths(project_root)
+        exclude_patterns = exclude_result.unwrap() if isinstance(exclude_result, Success) else []
+
+    for py_file in project_root.rglob("*.py"):
+        # Check exclusions
+        relative = py_file.relative_to(project_root)
+        relative_str = str(relative)
+
+        excluded = False
+        for pattern in exclude_patterns:
+            if relative_str.startswith(pattern) or f"/{pattern}/" in f"/{relative_str}":
+                excluded = True
+                break
+
+        if not excluded:
+            yield py_file
+
+
+def read_and_parse_file(file_path: Path, project_root: Path) -> Result[FileInfo, str]:
+    """
+    Read a Python file and parse it into FileInfo.
+
+    Args:
+        file_path: Path to the Python file
+        project_root: Project root for relative path calculation
+
+    Returns:
+        Result containing FileInfo or error message
+    """
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        return Failure(f"Failed to read {file_path}: {e}")
+
+    relative_path = str(file_path.relative_to(project_root))
+
+    # Skip empty files (e.g., __init__.py) - return empty FileInfo
+    if not content.strip():
+        return Success(FileInfo(path=relative_path, lines=0, symbols=[], imports=[], source=""))
+
+    file_info = parse_source(content, relative_path)
+
+    if file_info is None:
+        return Failure(f"Syntax error in {file_path}")
+
+    # Classify as Core or Shell based on patterns and paths
+    classify_result = classify_file(relative_path, project_root)
+    file_info.is_core, file_info.is_shell = (
+        classify_result.unwrap() if isinstance(classify_result, Success) else (False, False)
+    )
+
+    return Success(file_info)
+
+
+def scan_project(
+    project_root: Path,
+    only_files: set[Path] | None = None,
+) -> Iterator[Result[FileInfo, str]]:
+    """
+    Scan a project and yield FileInfo for each Python file.
+
+    Args:
+        project_root: Root directory of the project
+        only_files: If provided, only scan these files (for --changed mode)
+
+    Yields:
+        Result containing FileInfo or error message for each file
+    """
+    if only_files is not None:
+        # Phase 8.1: --changed mode - only scan specified files
+        for py_file in only_files:
+            if py_file.exists() and py_file.suffix == ".py":
+                yield read_and_parse_file(py_file, project_root)
+    else:
+        for py_file in discover_python_files(project_root):
+            yield read_and_parse_file(py_file, project_root)

invar/shell/git.py

@@ -0,0 +1,85 @@
+"""
+Git operations for Guard (Phase 8).
+
+Shell module: handles git I/O for changed file detection.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import TYPE_CHECKING
+
+from returns.result import Failure, Result, Success
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _run_git(args: list[str], cwd: Path) -> Result[str, str]:
+    """Run a git command and return stdout."""
+    try:
+        result = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True)
+        if result.returncode != 0:
+            return Failure(result.stderr.strip() or f"git {args[0]} failed")
+        return Success(result.stdout)
+    except FileNotFoundError:
+        return Failure("git command not found")
+    except Exception as e:
+        return Failure(f"Git error: {e}")
+
+
+def _parse_py_files(output: str, project_root: Path) -> set[Path]:
+    """Parse git output and return Python file paths."""
+    files: set[Path] = set()
+    for line in output.strip().split("\n"):
+        if line and line.endswith(".py"):
+            files.add(project_root / line)
+    return files
+
+
+def get_changed_files(project_root: Path) -> Result[set[Path], str]:
+    """
+    Get Python files modified according to git (staged, unstaged, untracked).
+
+    Examples:
+        >>> from pathlib import Path
+        >>> result = get_changed_files(Path("."))
+        >>> isinstance(result, (Success, Failure))
+        True
+    """
+    # Verify git repo
+    check = _run_git(["rev-parse", "--git-dir"], project_root)
+    if isinstance(check, Failure):
+        return Failure(f"Not a git repository: {project_root}")
+
+    changed: set[Path] = set()
+
+    # Staged changes
+    staged = _run_git(["diff", "--cached", "--name-only"], project_root)
+    if isinstance(staged, Success):
+        changed.update(_parse_py_files(staged.unwrap(), project_root))
+
+    # Unstaged changes
+    unstaged = _run_git(["diff", "--name-only"], project_root)
+    if isinstance(unstaged, Success):
+        changed.update(_parse_py_files(unstaged.unwrap(), project_root))
+
+    # Untracked files
+    untracked = _run_git(["ls-files", "--others", "--exclude-standard"], project_root)
+    if isinstance(untracked, Success):
+        changed.update(_parse_py_files(untracked.unwrap(), project_root))
+
+    return Success(changed)
+
+
+def is_git_repo(path: Path) -> bool:
+    """
+    Check if a path is inside a git repository.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> isinstance(is_git_repo(Path(".")), bool)
+        True
+    """
+    result = _run_git(["rev-parse", "--git-dir"], path)
+    return isinstance(result, Success)

invar/shell/guard_helpers.py

@@ -0,0 +1,324 @@
+"""
+Guard command helper functions.
+
+Extracted from cli.py to reduce function sizes and improve maintainability.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003 - Path used at runtime for path operations
+from typing import TYPE_CHECKING
+
+from returns.result import Failure, Result, Success
+from rich.console import Console
+
+if TYPE_CHECKING:
+    from invar.shell.testing import VerificationLevel
+
+
+console = Console()
+
+
+def handle_changed_mode(
+    path: Path,
+) -> Result[tuple[set[Path], list[Path]], str]:
+    """Handle --changed flag: get modified files from git.
+
+    Returns (only_files set, checked_files list) on success.
+    """
+    from invar.shell.git import get_changed_files, is_git_repo
+
+    if not is_git_repo(path):
+        return Failure("--changed requires a git repository")
+
+    changed_result = get_changed_files(path)
+    if isinstance(changed_result, Failure):
+        return Failure(changed_result.failure())
+
+    only_files = changed_result.unwrap()
+    if not only_files:
+        return Failure("NO_CHANGES")  # Special marker for "no changes"
+
+    return Success((only_files, list(only_files)))
+
+
+def collect_files_to_check(
+    path: Path, checked_files: list[Path]
+) -> list[Path]:
+    """Collect Python files to check when not in --changed mode."""
+    from invar.shell.config import get_path_classification
+
+    if checked_files:
+        return checked_files
+
+    result_files: list[Path] = []
+
+    path_result = get_path_classification(path)
+    if isinstance(path_result, Success):
+        core_paths, shell_paths = path_result.unwrap()
+    else:
+        core_paths, shell_paths = ["src/core"], ["src/shell"]
+
+    # Scan core/shell paths
+    for core_path in core_paths:
+        full_path = path / core_path
+        if full_path.exists():
+            result_files.extend(full_path.rglob("*.py"))
+
+    for shell_path in shell_paths:
+        full_path = path / shell_path
+        if full_path.exists():
+            result_files.extend(full_path.rglob("*.py"))
+
+    # Fallback: scan path directly
+    if not result_files and path.exists():
+        result_files.extend(path.rglob("*.py"))
+
+    return result_files
+
+
+def run_doctests_phase(
+    checked_files: list[Path], explain: bool
+) -> tuple[bool, str]:
+    """Run doctests on collected files.
+
+    Returns (passed, output).
+    """
+    from invar.shell.testing import run_doctests_on_files
+
+    if not checked_files:
+        return True, ""
+
+    doctest_result = run_doctests_on_files(checked_files, verbose=explain)
+    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
+
+    return False, doctest_result.failure()
+
+
+def run_crosshair_phase(
+    path: Path,
+    checked_files: list[Path],
+    doctest_passed: bool,
+    static_exit_code: int,
+    changed_mode: bool = False,
+) -> tuple[bool, dict]:
+    """Run CrossHair verification phase.
+
+    Args:
+        path: Project root path
+        checked_files: Files to potentially verify
+        doctest_passed: Whether doctests passed
+        static_exit_code: Exit code from static analysis
+        changed_mode: If True, only verify git-changed files (--changed flag)
+
+    Returns (passed, output_dict).
+    """
+    from invar.shell.prove_cache import ProveCache
+    from invar.shell.testing import get_files_to_prove, run_crosshair_parallel
+
+    # Skip if prior failures
+    if not doctest_passed or static_exit_code != 0:
+        return True, {"status": "skipped", "reason": "prior failures"}
+
+    if not checked_files:
+        return True, {"status": "skipped", "reason": "no files to verify"}
+
+    # Only verify Core files (pure logic)
+    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 found"}
+
+    # DX-13 fix: Only use git-based incremental when --changed is specified
+    # Cache-based incremental still applies in run_crosshair_parallel
+    files_to_prove = get_files_to_prove(path, core_files, changed_only=changed_mode)
+
+    if not files_to_prove:
+        return True, {
+            "status": "verified",
+            "reason": "no changes to verify",
+            "files_verified": 0,
+            "files_cached": len(core_files),
+        }
+
+    # Create cache and run parallel verification
+    cache = ProveCache(path / ".invar" / "cache" / "prove")
+    crosshair_result = run_crosshair_parallel(
+        files_to_prove,
+        max_iterations=5,
+        max_workers=None,
+        cache=cache,
+    )
+
+    if isinstance(crosshair_result, Success):
+        output = crosshair_result.unwrap()
+        passed = output.get("status") in ("verified", "skipped")
+        return passed, output
+
+    return False, {"status": "error", "error": crosshair_result.failure()}
+
+
+def output_verification_status(
+    verification_level: VerificationLevel,
+    static_exit_code: int,
+    doctest_passed: bool,
+    doctest_output: str,
+    crosshair_output: dict,
+    explain: bool,
+    property_output: dict | None = None,
+) -> None:
+    """Output verification status for human-readable mode.
+
+    DX-19: Simplified - STANDARD runs all phases (doctests + CrossHair + Hypothesis).
+    """
+    from invar.shell.testing import VerificationLevel
+
+    # STATIC mode: no runtime tests to report
+    if verification_level == VerificationLevel.STATIC:
+        return
+
+    # STANDARD mode: report all test results
+    if static_exit_code == 0:
+        # Doctest results
+        if doctest_passed:
+            console.print("[green]✓ Doctests passed[/green]")
+        else:
+            console.print("[red]✗ Doctests failed[/red]")
+            if doctest_output and explain:
+                console.print(doctest_output)
+
+        # CrossHair results
+        _output_crosshair_status(
+            static_exit_code, doctest_passed, crosshair_output
+        )
+
+        # Property tests results
+        if property_output:
+            _output_property_tests_status(
+                static_exit_code, doctest_passed, property_output
+            )
+    else:
+        console.print("[dim]⊘ Runtime tests skipped (static errors)[/dim]")
+
+
+def run_property_tests_phase(
+    checked_files: list[Path],
+    doctest_passed: bool,
+    static_exit_code: int,
+    max_examples: int = 100,
+) -> tuple[bool, dict]:
+    """Run property tests phase (DX-08).
+
+    Args:
+        checked_files: Files to test
+        doctest_passed: Whether doctests passed
+        static_exit_code: Exit code from static analysis
+        max_examples: Maximum Hypothesis examples per function
+
+    Returns (passed, output_dict).
+    """
+    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"}
+
+    if not checked_files:
+        return True, {"status": "skipped", "reason": "no files"}
+
+    # 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"}
+
+    result = run_property_tests_on_files(core_files, max_examples)
+
+    if isinstance(result, Success):
+        report = result.unwrap()
+        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,
+            "errors": report.errors,
+        }
+
+    return False, {"status": "error", "error": result.failure()}
+
+
+def _output_property_tests_status(
+    static_exit_code: int,
+    doctest_passed: bool,
+    property_output: dict,
+) -> None:
+    """Output property tests status (DX-08)."""
+    if static_exit_code != 0 or not doctest_passed:
+        console.print("[dim]⊘ Property tests skipped (prior failures)[/dim]")
+        return
+
+    status = property_output.get("status", "unknown")
+
+    if status == "passed":
+        tested = property_output.get("functions_tested", 0)
+        examples = property_output.get("total_examples", 0)
+        console.print(
+            f"[green]✓ Property tests passed[/green] "
+            f"[dim]({tested} functions, {examples} examples)[/dim]"
+        )
+    elif status == "skipped":
+        reason = property_output.get("reason", "no contracted functions")
+        console.print(f"[dim]⊘ Property tests skipped ({reason})[/dim]")
+    elif status == "failed":
+        failed = property_output.get("functions_failed", 0)
+        console.print(f"[red]✗ Property tests failed ({failed} functions)[/red]")
+        for error in property_output.get("errors", [])[:5]:
+            console.print(f"  {error}")
+    else:
+        console.print(f"[yellow]! Property tests: {status}[/yellow]")
+
+
+def _output_crosshair_status(
+    static_exit_code: int,
+    doctest_passed: bool,
+    crosshair_output: dict,
+) -> None:
+    """Output CrossHair verification status."""
+    if static_exit_code != 0 or not doctest_passed:
+        console.print("[dim]⊘ CrossHair skipped (prior failures)[/dim]")
+        return
+
+    status = crosshair_output.get("status", "unknown")
+
+    if status == "verified":
+        verified_count = crosshair_output.get("files_verified", 0)
+        cached_count = crosshair_output.get("files_cached", 0)
+        time_ms = crosshair_output.get("total_time_ms", 0)
+        workers = crosshair_output.get("workers", 1)
+
+        if verified_count == 0 and cached_count > 0:
+            reason = crosshair_output.get("reason", "cached")
+            console.print(f"[green]✓ CrossHair verified ({reason})[/green]")
+        elif time_ms > 0:
+            time_sec = time_ms / 1000
+            stats = f"{verified_count} verified"
+            if cached_count > 0:
+                stats += f", {cached_count} cached"
+            if workers > 1:
+                stats += f", {workers} workers"
+            console.print(
+                f"[green]✓ CrossHair verified[/green] "
+                f"[dim]({stats}, {time_sec:.1f}s)[/dim]"
+            )
+        else:
+            console.print("[green]✓ CrossHair verified[/green]")
+    elif status == "skipped":
+        reason = crosshair_output.get("reason", "no files")
+        console.print(f"[dim]⊘ CrossHair skipped ({reason})[/dim]")
+    else:
+        console.print("[yellow]! CrossHair found counterexamples[/yellow]")
+        for ce in crosshair_output.get("counterexamples", [])[:5]:
+            console.print(f"  {ce}")