invar-tools 1.0.0__py3-none-any.whl

invar/shell/cli.py

@@ -0,0 +1,358 @@
+"""
+CLI commands using Typer.
+
+Shell module: handles user interaction and file I/O.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+from returns.result import Failure, Result, Success
+from rich.console import Console
+from rich.table import Table
+
+
+def _detect_agent_mode() -> bool:
+    """Detect agent context: INVAR_MODE=agent OR non-TTY (pipe/redirect)."""
+    import sys
+    return os.getenv("INVAR_MODE") == "agent" or not sys.stdout.isatty()
+
+
+from invar import __version__
+from invar.core.models import GuardReport, RuleConfig
+from invar.core.rules import check_all_rules
+from invar.core.utils import get_exit_code
+from invar.shell.config import load_config
+from invar.shell.fs import scan_project
+from invar.shell.guard_output import output_agent, output_json, output_rich
+
+app = typer.Typer(
+    name="invar",
+    help="AI-native software engineering framework",
+    add_completion=False,
+)
+console = Console()
+
+
+def _count_core_functions(file_info) -> tuple[int, int]:
+    """Count functions and functions with contracts in a Core file (P24)."""
+    from invar.core.models import SymbolKind
+
+    if not file_info.is_core:
+        return (0, 0)
+
+    total = 0
+    with_contracts = 0
+    for sym in file_info.symbols:
+        if sym.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD):
+            total += 1
+            if sym.contracts:
+                with_contracts += 1
+    return (total, with_contracts)
+
+
+def _scan_and_check(
+    path: Path, config: RuleConfig, only_files: set[Path] | None = None
+) -> Result[GuardReport, str]:
+    """Scan project files and check against rules."""
+    report = GuardReport(files_checked=0)
+    for file_result in scan_project(path, only_files):
+        if isinstance(file_result, Failure):
+            console.print(f"[yellow]Warning:[/yellow] {file_result.failure()}")
+            continue
+        file_info = file_result.unwrap()
+        report.files_checked += 1
+        # P24: Track contract coverage for Core files
+        total, with_contracts = _count_core_functions(file_info)
+        report.update_coverage(total, with_contracts)
+        for violation in check_all_rules(file_info, config):
+            report.add_violation(violation)
+    return Success(report)
+
+
+@app.command()
+def guard(
+    path: Path = typer.Argument(
+        Path(), help="Project root directory", exists=True, file_okay=False, dir_okay=True
+    ),
+    strict: bool = typer.Option(False, "--strict", help="Treat warnings as errors"),
+    no_strict_pure: bool = typer.Option(
+        False, "--no-strict-pure", help="Disable purity checks (internal imports, impure calls)"
+    ),
+    pedantic: bool = typer.Option(
+        False, "--pedantic", help="Show all violations including off-by-default rules"
+    ),
+    explain: bool = typer.Option(
+        False, "--explain", help="Show detailed explanations and limitations"
+    ),
+    changed: bool = typer.Option(
+        False, "--changed", help="Only check git-modified files"
+    ),
+    agent: bool = typer.Option(
+        False, "--agent", help="Output JSON with fix instructions for agents"
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Output as JSON (simple format, no fix instructions)"
+    ),
+    static: bool = typer.Option(
+        False, "--static", help="Static analysis only, skip all runtime tests"
+    ),
+) -> None:
+    """Check project against Invar architecture rules.
+
+    Smart Guard: Runs static analysis + doctests + CrossHair + Hypothesis by default.
+    Use --static for quick static-only checks (~0.5s vs ~5s full).
+
+    DX-19: Simplified to 2 levels (Zero decisions).
+    """
+    from invar.shell.guard_helpers import (
+        collect_files_to_check,
+        handle_changed_mode,
+        output_verification_status,
+        run_crosshair_phase,
+        run_doctests_phase,
+        run_property_tests_phase,
+    )
+    from invar.shell.testing import VerificationLevel
+
+    # Load and configure
+    config_result = load_config(path)
+    if isinstance(config_result, Failure):
+        console.print(f"[red]Error:[/red] {config_result.failure()}")
+        raise typer.Exit(1)
+
+    config = config_result.unwrap()
+    if no_strict_pure:
+        config.strict_pure = False
+    if pedantic:
+        config.severity_overrides = {}
+
+    # Handle --changed mode
+    only_files: set[Path] | None = None
+    checked_files: list[Path] = []
+    if changed:
+        changed_result = handle_changed_mode(path)
+        if isinstance(changed_result, Failure):
+            if changed_result.failure() == "NO_CHANGES":
+                console.print("[green]No changed Python files.[/green]")
+                raise typer.Exit(0)
+            console.print(f"[red]Error:[/red] {changed_result.failure()}")
+            raise typer.Exit(1)
+        only_files, checked_files = changed_result.unwrap()
+
+    # Run static analysis
+    scan_result = _scan_and_check(path, config, only_files)
+    if isinstance(scan_result, Failure):
+        console.print(f"[red]Error:[/red] {scan_result.failure()}")
+        raise typer.Exit(1)
+    report = scan_result.unwrap()
+
+    # Determine output mode
+    use_agent_output, use_json_output = _determine_output_mode(
+        json_output, agent
+    )
+
+    # DX-19: Simplified to 2 levels (STATIC or STANDARD)
+    verification_level = VerificationLevel.STATIC if static else VerificationLevel.STANDARD
+    level_name = "STATIC" if static else "STANDARD"
+
+    # Show verification level (human mode)
+    if not use_agent_output and not use_json_output:
+        _show_verification_level(verification_level)
+
+    # 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, {}
+
+    # 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 2: CrossHair symbolic verification
+        crosshair_passed, crosshair_output = run_crosshair_phase(
+            path, checked_files, doctest_passed, static_exit_code,
+            changed_mode=changed,
+        )
+
+        # Phase 3: Hypothesis property tests
+        property_passed, property_output = run_property_tests_phase(
+            checked_files, doctest_passed, static_exit_code
+        )
+
+    # Output results
+    if use_agent_output:
+        output_agent(
+            report, doctest_passed, doctest_output, crosshair_output, level_name,
+            property_output=property_output,
+        )
+    elif use_json_output:
+        output_json(report)
+    else:
+        output_rich(report, config.strict_pure, changed, pedantic, explain)
+        output_verification_status(
+            verification_level, static_exit_code, doctest_passed,
+            doctest_output, crosshair_output, explain,
+            property_output=property_output,
+        )
+
+    # Exit with combined status
+    all_passed = doctest_passed and crosshair_passed and property_passed
+    final_exit = static_exit_code if all_passed else 1
+    raise typer.Exit(final_exit)
+
+
+def _determine_output_mode(json_output: bool, agent: bool) -> tuple[bool, bool]:
+    """Determine output mode based on flags and context."""
+    if json_output:
+        return False, True
+    if agent or _detect_agent_mode():
+        return True, False
+    return False, False
+
+
+def _show_verification_level(verification_level) -> None:
+    """Show verification level in human-readable format.
+
+    DX-19: Simplified to 2 levels.
+    """
+    from invar.shell.testing import VerificationLevel
+
+    labels = {
+        VerificationLevel.STATIC: "[yellow]--static[/yellow] (static only)",
+        VerificationLevel.STANDARD: "default (static + doctests + CrossHair + Hypothesis)",
+    }
+    console.print(f"[dim]Verification: {labels[verification_level]}[/dim]")
+
+
+@app.command()
+def version() -> None:
+    """Show Invar version."""
+    console.print(f"invar {__version__}")
+
+
+@app.command("map")
+def map_command(
+    path: Path = typer.Argument(Path(), help="Project root directory"),
+    top: int = typer.Option(0, "--top", help="Show top N most-referenced symbols"),
+    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
+
+    # Phase 9 P11: Auto-detect agent mode
+    use_json = json_output or _detect_agent_mode()
+    result = run_map(path, top, use_json)
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+
+@app.command("sig")
+def sig_command(
+    target: str = typer.Argument(..., help="File or file::symbol path"),
+    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
+
+    # Phase 9 P11: Auto-detect agent mode
+    use_json = json_output or _detect_agent_mode()
+    result = run_sig(target, use_json)
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+
+@app.command()
+def rules(
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    category: str = typer.Option(
+        None, "--category", "-c", help="Filter by category (size, contracts, purity, shell, docs)"
+    ),
+) -> None:
+    """
+    List all Guard rules with their metadata.
+
+    Shows what each rule detects and its limitations.
+    """
+    import json as json_lib
+
+    from invar.core.rule_meta import RULE_META, RuleCategory, get_rules_by_category
+
+    # Phase 9 P11: Auto-detect agent mode
+    use_json = json_output or _detect_agent_mode()
+
+    # Filter by category if specified
+    if category:
+        try:
+            cat = RuleCategory(category.lower())
+            rules_list = get_rules_by_category(cat)
+        except ValueError:
+            valid = ", ".join(c.value for c in RuleCategory)
+            console.print(f"[red]Error:[/red] Invalid category '{category}'. Valid: {valid}")
+            raise typer.Exit(1)
+    else:
+        rules_list = list(RULE_META.values())
+
+    if use_json:
+        # JSON output for agents
+        data = {
+            "rules": [
+                {
+                    "name": r.name,
+                    "severity": r.severity.value,
+                    "category": r.category.value,
+                    "detects": r.detects,
+                    "cannot_detect": list(r.cannot_detect),
+                    "hint": r.hint,
+                }
+                for r in rules_list
+            ]
+        }
+        console.print(json_lib.dumps(data, indent=2))
+    else:
+        # Rich table output for humans
+        table = Table(title="Invar Guard Rules")
+        table.add_column("Rule", style="cyan")
+        table.add_column("Severity", style="yellow")
+        table.add_column("Category")
+        table.add_column("Detects")
+        table.add_column("Hint", style="green")
+
+        for r in rules_list:
+            sev_style = {"error": "red", "warning": "yellow", "info": "blue"}.get(
+                r.severity.value, ""
+            )
+            table.add_row(
+                r.name,
+                f"[{sev_style}]{r.severity.value.upper()}[/{sev_style}]",
+                r.category.value,
+                r.detects[:50] + "..." if len(r.detects) > 50 else r.detects,
+                r.hint[:40] + "..." if len(r.hint) > 40 else r.hint,
+            )
+
+        console.print(table)
+        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.test_cmd import test, verify
+from invar.shell.update_cmd import update
+
+app.command()(init)
+app.command()(update)
+app.command()(test)
+app.command()(verify)
+
+
+if __name__ == "__main__":
+    app()

invar/shell/config.py

@@ -0,0 +1,248 @@
+"""
+Configuration loading from multiple sources.
+
+Shell module: performs file I/O to load configuration.
+
+Configuration sources (priority order):
+1. pyproject.toml [tool.invar.guard]
+2. invar.toml [guard]
+3. .invar/config.toml [guard]
+4. Built-in defaults
+"""
+
+from __future__ import annotations
+
+import tomllib
+from typing import TYPE_CHECKING, Any, Literal
+
+from returns.result import Failure, Result, Success
+
+from invar.core.models import RuleConfig
+from invar.core.utils import (
+    extract_guard_section,
+    matches_path_prefix,
+    matches_pattern,
+    parse_guard_config,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+ConfigSource = Literal["pyproject", "invar", "invar_dir", "default"]
+
+
+def _find_config_source(project_root: Path) -> Result[tuple[Path | None, ConfigSource], str]:
+    """
+    Find the first available config file.
+
+    Returns:
+        Result containing tuple of (config_path, source_type)
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.TemporaryDirectory() as tmpdir:
+        ...     root = Path(tmpdir)
+        ...     result = _find_config_source(root)
+        ...     result.unwrap()[1]
+        'default'
+    """
+    try:
+        pyproject = project_root / "pyproject.toml"
+        if pyproject.exists():
+            return Success((pyproject, "pyproject"))
+
+        invar_toml = project_root / "invar.toml"
+        if invar_toml.exists():
+            return Success((invar_toml, "invar"))
+
+        invar_config = project_root / ".invar" / "config.toml"
+        if invar_config.exists():
+            return Success((invar_config, "invar_dir"))
+
+        return Success((None, "default"))
+    except OSError as e:
+        return Failure(f"Failed to find config: {e}")
+
+
+def _read_toml(path: Path) -> Result[dict[str, Any], str]:
+    """Read and parse a TOML file."""
+    try:
+        content = path.read_text(encoding="utf-8")
+        return Success(tomllib.loads(content))
+    except tomllib.TOMLDecodeError as e:
+        return Failure(f"Invalid TOML in {path.name}: {e}")
+    except OSError as e:
+        return Failure(f"Failed to read {path.name}: {e}")
+
+
+def load_config(project_root: Path) -> Result[RuleConfig, str]:
+    """
+    Load Invar configuration from available sources.
+
+    Tries sources in priority order:
+    1. pyproject.toml [tool.invar.guard]
+    2. invar.toml [guard]
+    3. .invar/config.toml [guard]
+    4. Built-in defaults
+
+    Args:
+        project_root: Path to project root directory
+
+    Returns:
+        Result containing RuleConfig or error message
+    """
+    find_result = _find_config_source(project_root)
+    if isinstance(find_result, Failure):
+        return find_result
+    config_path, source = find_result.unwrap()
+
+    if source == "default":
+        return Success(RuleConfig())
+
+    assert config_path is not None  # source != "default" guarantees path exists
+    result = _read_toml(config_path)
+
+    if isinstance(result, Failure):
+        return result
+
+    data = result.unwrap()
+    guard_config = extract_guard_section(data, source)
+
+    # For pyproject.toml, if no [tool.invar.guard] section, use defaults
+    if source == "pyproject" and not guard_config:
+        return Success(RuleConfig())
+
+    return Success(parse_guard_config(guard_config))
+
+
+# Default paths for Core/Shell classification
+_DEFAULT_CORE_PATHS = ["src/core", "core"]
+_DEFAULT_SHELL_PATHS = ["src/shell", "shell"]
+
+# Default exclude paths
+_DEFAULT_EXCLUDE_PATHS = [
+    "tests",
+    "test",
+    "scripts",
+    ".venv",
+    "venv",
+    ".env",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    "dist",
+    "build",
+    ".tox",
+]
+
+
+def _get_classification_config(project_root: Path) -> Result[dict[str, Any], str]:
+    """Get classification-related config (paths and patterns)."""
+    find_result = _find_config_source(project_root)
+    if isinstance(find_result, Failure):
+        return Success({})  # Return empty on error
+    config_path, source = find_result.unwrap()
+
+    if source == "default":
+        return Success({})
+
+    assert config_path is not None
+    result = _read_toml(config_path)
+
+    if isinstance(result, Failure):
+        return Success({})  # Return empty on error
+
+    data = result.unwrap()
+    return Success(extract_guard_section(data, source))
+
+
+def get_path_classification(project_root: Path) -> Result[tuple[list[str], list[str]], str]:
+    """
+    Get Core and Shell path prefixes from configuration.
+
+    Returns:
+        Result containing tuple of (core_paths, shell_paths)
+    """
+    config_result = _get_classification_config(project_root)
+    guard_config = config_result.unwrap() if isinstance(config_result, Success) else {}
+
+    core_paths = guard_config.get("core_paths", _DEFAULT_CORE_PATHS)
+    shell_paths = guard_config.get("shell_paths", _DEFAULT_SHELL_PATHS)
+
+    return Success((core_paths, shell_paths))
+
+
+def get_pattern_classification(project_root: Path) -> Result[tuple[list[str], list[str]], str]:
+    """
+    Get Core and Shell glob patterns from configuration.
+
+    Returns:
+        Result containing tuple of (core_patterns, shell_patterns)
+    """
+    config_result = _get_classification_config(project_root)
+    guard_config = config_result.unwrap() if isinstance(config_result, Success) else {}
+
+    core_patterns = guard_config.get("core_patterns", [])
+    shell_patterns = guard_config.get("shell_patterns", [])
+
+    return Success((core_patterns, shell_patterns))
+
+
+def get_exclude_paths(project_root: Path) -> Result[list[str], str]:
+    """
+    Get paths to exclude from checking.
+
+    Returns:
+        Result containing list of path patterns to exclude
+    """
+    config_result = _get_classification_config(project_root)
+    guard_config = config_result.unwrap() if isinstance(config_result, Success) else {}
+    return Success(guard_config.get("exclude_paths", _DEFAULT_EXCLUDE_PATHS.copy()))
+
+
+def classify_file(file_path: str, project_root: Path) -> Result[tuple[bool, bool], str]:
+    """
+    Classify a file as Core, Shell, or neither.
+
+    Priority: patterns > paths > uncategorized.
+
+    Examples:
+        >>> import tempfile
+        >>> from pathlib import Path
+        >>> with tempfile.TemporaryDirectory() as tmpdir:
+        ...     root = Path(tmpdir)
+        ...     result = classify_file("src/core/logic.py", root)
+        ...     result.unwrap()[0]
+        True
+    """
+    pattern_result = get_pattern_classification(project_root)
+    core_patterns, shell_patterns = (
+        pattern_result.unwrap() if isinstance(pattern_result, Success) else ([], [])
+    )
+
+    path_result = get_path_classification(project_root)
+    core_paths, shell_paths = (
+        path_result.unwrap()
+        if isinstance(path_result, Success)
+        else (_DEFAULT_CORE_PATHS, _DEFAULT_SHELL_PATHS)
+    )
+
+    # Priority 1: Pattern-based classification
+    if core_patterns and matches_pattern(file_path, core_patterns):
+        return Success((True, False))
+    if shell_patterns and matches_pattern(file_path, shell_patterns):
+        return Success((False, True))
+
+    # Priority 2: Path-based classification
+    if matches_path_prefix(file_path, core_paths):
+        return Success((True, False))
+    if matches_path_prefix(file_path, shell_paths):
+        return Success((False, True))
+
+    return Success((False, False))