invar-tools 1.0.0__py3-none-any.whl

invar/shell/guard_output.py

@@ -0,0 +1,235 @@
+"""
+Guard output formatters.
+
+Shell module: handles output formatting for guard command.
+Extracted from cli.py to reduce file size.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+from invar.core.formatter import format_guard_agent
+from invar.core.models import GuardReport, Severity
+
+console = Console()
+
+
+def show_file_context(file_path: str) -> None:
+    """
+    Show INSPECT section for a file (Phase 9.2 P14).
+
+    Displays file status and contract patterns to help agents understand context.
+    """
+    from pathlib import Path
+
+    from invar.core.inspect import analyze_file_context
+
+    try:
+        path = Path(file_path)
+        if not path.exists():
+            return
+
+        source = path.read_text()
+        ctx = analyze_file_context(source, file_path, max_lines=500)
+
+        # Show compact INSPECT section
+        console.print(
+            f"  [dim]INSPECT: {ctx.lines} lines ({ctx.percentage}% of limit), "
+            f"{ctx.functions_with_contracts}/{ctx.functions_total} functions with contracts[/dim]"
+        )
+        if ctx.contract_examples:
+            patterns = ", ".join(ctx.contract_examples[:2])
+            if len(patterns) > 60:
+                patterns = patterns[:57] + "..."
+            console.print(f"  [dim]Patterns: {patterns}[/dim]")
+    except Exception:
+        pass  # Silently ignore errors in context display
+
+
+def output_rich(
+    report: GuardReport,
+    strict_pure: bool = False,
+    changed_mode: bool = False,
+    pedantic_mode: bool = False,
+    explain_mode: bool = False,
+) -> None:
+    """Output report using Rich formatting."""
+    console.print("\n[bold]Invar Guard Report[/bold]")
+    console.print("=" * 40)
+    mode_info = [
+        m
+        for m, c in [
+            ("strict-pure", strict_pure),
+            ("changed-only", changed_mode),
+            ("pedantic", pedantic_mode),
+            ("explain", explain_mode),
+        ]
+        if c
+    ]
+    if mode_info:
+        console.print(f"[cyan]({', '.join(mode_info)} mode)[/cyan]")
+    console.print()
+
+    if not report.violations:
+        console.print("[green]No violations found.[/green]")
+    else:
+        from invar.core.rule_meta import get_rule_meta
+
+        by_file: dict[str, list] = {}
+        for v in report.violations:
+            by_file.setdefault(v.file, []).append(v)
+        for fp, vs in sorted(by_file.items()):
+            console.print(f"[bold]{fp}[/bold]")
+            # Phase 9.2 P14: Show INSPECT section in --changed mode
+            if changed_mode:
+                show_file_context(fp)
+            for v in vs:
+                if v.severity == Severity.ERROR:
+                    icon = "[red]ERROR[/red]"
+                elif v.severity == Severity.WARNING:
+                    icon = "[yellow]WARN[/yellow]"
+                else:
+                    icon = "[blue]INFO[/blue]"
+                ln = f":{v.line}" if v.line else ""
+                console.print(f"  {icon} {ln} {v.message}")
+                # Show violation's suggestion if present (includes P25 extraction hints)
+                if v.suggestion:
+                    # Handle multi-line suggestions (P25)
+                    for line in v.suggestion.split("\n"):
+                        console.print(f"    [dim cyan]→ {line}[/dim cyan]")
+                else:
+                    # Phase 9.2 P5: Fallback to hints from RULE_META
+                    meta = get_rule_meta(v.rule)
+                    if meta:
+                        console.print(f"    [dim cyan]→ {meta.hint}[/dim cyan]")
+                        # --explain: show detailed information
+                        if explain_mode:
+                            console.print(f"    [dim]Detects: {meta.detects}[/dim]")
+                            if meta.cannot_detect:
+                                console.print(
+                                    f"    [dim]Cannot detect: {', '.join(meta.cannot_detect)}[/dim]"
+                                )
+            console.print()
+
+    console.print("-" * 40)
+    summary = (
+        f"Files checked: {report.files_checked}\n"
+        f"Errors: {report.errors}\n"
+        f"Warnings: {report.warnings}"
+    )
+    if report.infos > 0:
+        summary += f"\nInfos: {report.infos}"
+    console.print(summary)
+
+    # P24: Contract coverage statistics (only show if core files exist)
+    if report.core_functions_total > 0:
+        pct = report.contract_coverage_pct
+        console.print(
+            f"\n[bold]Contract coverage:[/bold] {pct}% "
+            f"({report.core_functions_with_contracts}/{report.core_functions_total} functions)"
+        )
+        issues = report.contract_issue_counts
+        issue_parts = []
+        if issues["tautology"] > 0:
+            issue_parts.append(f"{issues['tautology']} tautology")
+        if issues["empty"] > 0:
+            issue_parts.append(f"{issues['empty']} empty")
+        if issues["partial"] > 0:
+            issue_parts.append(f"{issues['partial']} partial")
+        if issues["type_only"] > 0:
+            issue_parts.append(f"{issues['type_only']} type-check only")
+        if issue_parts:
+            console.print(f"[dim]Issues: {', '.join(issue_parts)}[/dim]")
+
+    # Code Health display (only when guard passes)
+    if report.passed and report.files_checked > 0:
+        # Calculate health: 100% for 0 warnings, decreases by 5% per warning, min 50%
+        health = max(50, 100 - report.warnings * 5)
+        bar_filled = health // 5  # 20 chars total
+        bar_empty = 20 - bar_filled
+        bar = "█" * bar_filled + "░" * bar_empty
+
+        if report.warnings == 0:
+            health_color = "green"
+            health_label = "Excellent"
+        elif report.warnings <= 2:
+            health_color = "green"
+            health_label = "Good"
+        elif report.warnings <= 5:
+            health_color = "yellow"
+            health_label = "Fair"
+        else:
+            health_color = "yellow"
+            health_label = "Needs attention"
+
+        console.print(
+            f"\n[bold]Code Health:[/bold] [{health_color}]{health}%[/{health_color}] "
+            f"{bar} ({health_label})"
+        )
+
+        # Tip for fixing warnings
+        if report.warnings > 0:
+            console.print(
+                "[dim]💡 Fix warnings in files you modified to improve code health.[/dim]"
+            )
+
+    console.print(
+        f"\n[{'green' if report.passed else 'red'}]Guard {'passed' if report.passed else 'failed'}.[/]"
+    )
+    console.print(
+        "\n[dim]Note: Guard performs static analysis only. "
+        "Dynamic imports and runtime behavior are not checked.[/dim]"
+    )
+
+
+def output_json(report: GuardReport) -> None:
+    """Output report as JSON."""
+    import json
+
+    output = {
+        "files_checked": report.files_checked,
+        "errors": report.errors,
+        "warnings": report.warnings,
+        "infos": report.infos,
+        "passed": report.passed,
+        "violations": [v.model_dump() for v in report.violations],
+    }
+    console.print(json.dumps(output, indent=2))
+
+
+def output_agent(
+    report: GuardReport,
+    doctest_passed: bool = True,
+    doctest_output: str = "",
+    crosshair_output: dict | None = None,
+    verification_level: str = "standard",
+    property_output: dict | None = None,  # DX-08
+) -> None:
+    """Output report in Agent-optimized JSON format (Phase 8.2 + DX-06 + DX-08 + DX-09).
+
+    Args:
+        report: Guard analysis report
+        doctest_passed: Whether doctests passed
+        doctest_output: Doctest stdout (only if failed)
+        crosshair_output: CrossHair results dict
+        verification_level: Current level (static/standard)
+        property_output: Property test results dict (DX-08)
+    """
+    import json
+
+    output = format_guard_agent(report)
+    # DX-09: Add verification level for Agent transparency
+    output["verification_level"] = verification_level
+    # DX-06: Add doctest results to agent output
+    output["doctest"] = {
+        "passed": doctest_passed,
+        "output": doctest_output if not doctest_passed else "",
+    }
+    # DX-06: Add CrossHair results if available
+    if crosshair_output:
+        output["crosshair"] = crosshair_output
+    # DX-08: Add property test results if available
+    if property_output:
+        output["property_tests"] = property_output
+    console.print(json.dumps(output, indent=2))

invar/shell/init_cmd.py

@@ -0,0 +1,289 @@
+"""
+Init command for Invar.
+
+Shell module: handles project initialization.
+DX-21B: Added --claude flag for Claude Code integration.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+from returns.result import Failure, Success
+from rich.console import Console
+
+from invar.shell.mcp_config import (
+    detect_available_methods,
+    generate_mcp_json,
+    get_method_by_name,
+    get_recommended_method,
+)
+from invar.shell.templates import (
+    add_config,
+    add_invar_reference,
+    copy_examples_directory,
+    copy_template,
+    create_agent_config,
+    create_directories,
+    detect_agent_configs,
+    install_hooks,
+)
+
+console = Console()
+
+
+def run_claude_init(path: Path) -> bool:
+    """
+    Run 'claude /init' to generate intelligent CLAUDE.md.
+
+    Returns True if successful, False otherwise.
+    """
+    if not shutil.which("claude"):
+        console.print(
+            "[yellow]Warning:[/yellow] 'claude' CLI not found. "
+            "Install Claude Code: https://claude.ai/code"
+        )
+        console.print("[dim]Skipping claude /init, will create basic CLAUDE.md[/dim]")
+        return False
+
+    console.print("\n[bold]Running claude /init...[/bold]")
+    try:
+        result = subprocess.run(
+            ["claude", "/init"],
+            cwd=path,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        if result.returncode == 0:
+            console.print("[green]claude /init completed successfully[/green]")
+            return True
+        else:
+            console.print(f"[yellow]Warning:[/yellow] claude /init failed: {result.stderr}")
+            return False
+    except subprocess.TimeoutExpired:
+        console.print("[yellow]Warning:[/yellow] claude /init timed out")
+        return False
+    except Exception as e:
+        console.print(f"[yellow]Warning:[/yellow] claude /init error: {e}")
+        return False
+
+
+def append_invar_reference_to_claude_md(path: Path) -> bool:
+    """
+    Append Invar reference to existing CLAUDE.md.
+
+    Preserves content generated by 'claude /init'.
+    Returns True if modified, False otherwise.
+    """
+    claude_md = path / "CLAUDE.md"
+    if not claude_md.exists():
+        return False
+
+    content = claude_md.read_text()
+    if "INVAR.md" in content:
+        console.print("[dim]CLAUDE.md already references INVAR.md[/dim]")
+        return False
+
+    # Append reference at the end
+    invar_reference = """
+
+---
+
+## Invar Protocol
+
+> **Protocol:** Follow [INVAR.md](./INVAR.md) for the Invar development methodology.
+
+Your **first message** for any implementation task MUST include actual output from:
+
+```bash
+invar guard --changed   # or: invar_guard(changed=true)
+invar map --top 10      # or: invar_map(top=10)
+```
+
+**Use MCP tools if available**, otherwise use CLI commands.
+"""
+
+    claude_md.write_text(content + invar_reference)
+    console.print("[green]Updated[/green] CLAUDE.md (added Invar reference)")
+    return True
+
+
+def configure_mcp_with_method(
+    path: Path, mcp_method: str | None
+) -> None:
+    """Configure MCP server with specified or detected method."""
+    import json
+
+    # Determine method to use
+    if mcp_method:
+        config = get_method_by_name(mcp_method)
+        if config is None:
+            console.print(f"[yellow]Warning:[/yellow] Method '{mcp_method}' not available")
+            config = get_recommended_method()
+            console.print(f"[dim]Using fallback: {config.description}[/dim]")
+    else:
+        config = get_recommended_method()
+
+    console.print("\n[bold]Configuring MCP server...[/bold]")
+    console.print(f"  Method: {config.description}")
+
+    # Generate and write .mcp.json
+    mcp_json_path = path / ".mcp.json"
+    mcp_content = generate_mcp_json(config)
+
+    if mcp_json_path.exists():
+        try:
+            existing = json.loads(mcp_json_path.read_text())
+            if "mcpServers" in existing and "invar" in existing.get("mcpServers", {}):
+                console.print("[dim]Skipped[/dim] .mcp.json (invar already configured)")
+                return
+            # Add invar to existing config
+            if "mcpServers" not in existing:
+                existing["mcpServers"] = {}
+            existing["mcpServers"]["invar"] = mcp_content["mcpServers"]["invar"]
+            mcp_json_path.write_text(json.dumps(existing, indent=2))
+            console.print("[green]Updated[/green] .mcp.json (added invar)")
+        except (json.JSONDecodeError, OSError):
+            console.print("[yellow]Warning:[/yellow] .mcp.json exists but couldn't update")
+    else:
+        mcp_json_path.write_text(json.dumps(mcp_content, indent=2))
+        console.print("[green]Created[/green] .mcp.json")
+
+
+def show_available_mcp_methods() -> None:
+    """Display available MCP execution methods."""
+    methods = detect_available_methods()
+    console.print("\n[bold]Available MCP methods:[/bold]")
+    for i, method in enumerate(methods):
+        marker = "[green]→[/green]" if i == 0 else " "
+        console.print(f"  {marker} {method.method.value}: {method.description}")
+
+
+def init(
+    path: Path = typer.Argument(Path(), help="Project root directory"),
+    claude: bool = typer.Option(
+        False, "--claude", help="Run 'claude /init' and integrate with Claude Code"
+    ),
+    mcp_method: str = typer.Option(
+        None,
+        "--mcp-method",
+        help="MCP execution method: uvx (recommended), command, or python",
+    ),
+    dirs: bool = typer.Option(
+        None, "--dirs/--no-dirs", help="Create src/core and src/shell directories"
+    ),
+    hooks: bool = typer.Option(
+        True, "--hooks/--no-hooks", help="Install pre-commit hooks (default: ON)"
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Accept defaults without prompting"
+    ),
+) -> None:
+    """
+    Initialize Invar configuration in a project.
+
+    Works with or without pyproject.toml:
+    - If pyproject.toml exists: adds [tool.invar.guard] section
+    - Otherwise: creates invar.toml
+
+    Use --claude to run 'claude /init' first (recommended for Claude Code users).
+    Use --mcp-method to specify MCP execution method (uvx, command, python).
+    Use --dirs to always create directories, --no-dirs to skip.
+    Use --no-hooks to skip pre-commit hooks installation.
+    Use --yes to accept defaults without prompting.
+    """
+    # DX-21B: Run claude /init if requested
+    if claude:
+        claude_success = run_claude_init(path)
+        if claude_success:
+            # Append Invar reference to generated CLAUDE.md
+            append_invar_reference_to_claude_md(path)
+
+    config_result = add_config(path, console)
+    if isinstance(config_result, Failure):
+        console.print(f"[red]Error:[/red] {config_result.failure()}")
+        raise typer.Exit(1)
+    config_added = config_result.unwrap()
+
+    # Create INVAR.md (protocol)
+    result = copy_template("INVAR.md", path)
+    if isinstance(result, Success) and result.unwrap():
+        console.print("[green]Created[/green] INVAR.md (Invar Protocol)")
+
+    # Copy examples directory
+    copy_examples_directory(path, console)
+
+    # Create .invar directory structure
+    invar_dir = path / ".invar"
+    if not invar_dir.exists():
+        invar_dir.mkdir()
+        result = copy_template("context.md.template", invar_dir, "context.md")
+        if isinstance(result, Success) and result.unwrap():
+            console.print("[green]Created[/green] .invar/context.md (context management)")
+
+    # Create proposals directory for protocol governance
+    proposals_dir = invar_dir / "proposals"
+    if not proposals_dir.exists():
+        proposals_dir.mkdir()
+        result = copy_template("proposal.md.template", proposals_dir, "TEMPLATE.md")
+        if isinstance(result, Success) and result.unwrap():
+            console.print("[green]Created[/green] .invar/proposals/TEMPLATE.md")
+
+    # Agent detection and configuration (DX-11)
+    console.print("\n[bold]Checking for agent configurations...[/bold]")
+    agent_result = detect_agent_configs(path)
+    if isinstance(agent_result, Failure):
+        console.print(f"[yellow]Warning:[/yellow] {agent_result.failure()}")
+        agent_status: dict[str, str] = {}
+    else:
+        agent_status = agent_result.unwrap()
+
+    # Handle agent configs (DX-11, DX-17)
+    for agent, status in agent_status.items():
+        if status == "configured":
+            console.print(f"  [green]✓[/green] {agent}: already configured")
+        elif status == "found":
+            # Existing file without Invar reference - ask before modifying
+            if yes or typer.confirm(f"  Add Invar reference to {agent} config?", default=True):
+                add_invar_reference(path, agent, console)
+            else:
+                console.print(f"  [yellow]○[/yellow] {agent}: skipped")
+        elif status == "not_found":
+            # Create full template with workflow enforcement (DX-17)
+            create_agent_config(path, agent, console)
+
+    # Configure MCP server (DX-16, DX-21B)
+    configure_mcp_with_method(path, mcp_method)
+
+    # Show available methods if user might want to change
+    if not mcp_method and not yes:
+        show_available_mcp_methods()
+
+    # Create MCP setup guide
+    mcp_setup = invar_dir / "mcp-setup.md"
+    if not mcp_setup.exists():
+        from invar.shell.templates import _MCP_SETUP_TEMPLATE
+        mcp_setup.write_text(_MCP_SETUP_TEMPLATE)
+        console.print("[green]Created[/green] .invar/mcp-setup.md (setup guide)")
+
+    # Handle directory creation based on --dirs flag
+    if dirs is not False:
+        create_directories(path, console)
+
+    # Install pre-commit hooks if requested
+    if hooks:
+        install_hooks(path, console)
+
+    if not config_added and not (path / "INVAR.md").exists():
+        console.print("[yellow]Invar already configured.[/yellow]")
+
+    # Summary
+    console.print("\n[bold green]Invar initialized successfully![/bold green]")
+    if claude:
+        console.print("[dim]Next: Review CLAUDE.md and start coding with Claude Code[/dim]")
+    else:
+        console.print("[dim]Tip: Use --claude for Claude Code integration[/dim]")

invar/shell/mcp_config.py

@@ -0,0 +1,171 @@
+"""
+MCP configuration detection and generation.
+
+Shell module: handles MCP server configuration for AI agents.
+DX-21B: Smart detection of available MCP execution methods.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class McpMethod(Enum):
+    """Available MCP execution methods."""
+
+    UVX = "uvx"
+    COMMAND = "command"
+    PYTHON = "python"
+
+
+@dataclass
+class McpExecConfig:
+    """Configuration for MCP server execution.
+
+    Examples:
+        >>> config = McpExecConfig(
+        ...     method=McpMethod.UVX,
+        ...     command="uvx",
+        ...     args=["invar-tools", "mcp"],
+        ...     description="uvx (recommended - isolated environment)",
+        ... )
+        >>> config.to_mcp_json()
+        {'command': 'uvx', 'args': ['invar-tools', 'mcp']}
+    """
+
+    method: McpMethod
+    command: str
+    args: list[str]
+    description: str
+
+    def to_mcp_json(self) -> dict[str, Any]:
+        """Convert to MCP JSON format for .mcp.json."""
+        return {
+            "command": self.command,
+            "args": self.args,
+        }
+
+
+def detect_available_methods() -> list[McpExecConfig]:
+    """
+    Detect available MCP execution methods, ordered by preference.
+
+    Returns a list of available methods, with the most preferred first.
+
+    Examples:
+        >>> methods = detect_available_methods()
+        >>> len(methods) >= 1  # At least Python fallback
+        True
+        >>> methods[-1].method == McpMethod.PYTHON  # Python is always last
+        True
+    """
+    methods: list[McpExecConfig] = []
+
+    # 1. uvx (recommended - isolated, auto-updates)
+    if shutil.which("uvx"):
+        methods.append(
+            McpExecConfig(
+                method=McpMethod.UVX,
+                command="uvx",
+                args=["invar-tools", "mcp"],
+                description="uvx (recommended - isolated environment)",
+            )
+        )
+
+    # 2. invar command in PATH
+    if shutil.which("invar"):
+        methods.append(
+            McpExecConfig(
+                method=McpMethod.COMMAND,
+                command="invar",
+                args=["mcp"],
+                description="invar command (from PATH)",
+            )
+        )
+
+    # 3. Current Python (always available as fallback)
+    methods.append(
+        McpExecConfig(
+            method=McpMethod.PYTHON,
+            command=sys.executable,
+            args=["-m", "invar.mcp"],
+            description=f"Python ({sys.executable})",
+        )
+    )
+
+    return methods
+
+
+def get_recommended_method() -> McpExecConfig:
+    """
+    Get the recommended MCP execution method.
+
+    Returns the first (most preferred) available method.
+
+    Examples:
+        >>> config = get_recommended_method()
+        >>> config.method in [McpMethod.UVX, McpMethod.COMMAND, McpMethod.PYTHON]
+        True
+    """
+    methods = detect_available_methods()
+    return methods[0]
+
+
+def get_method_by_name(name: str) -> McpExecConfig | None:
+    """
+    Get a specific MCP method by name.
+
+    Args:
+        name: Method name ('uvx', 'command', or 'python')
+
+    Returns:
+        McpExecConfig if the method is available, None otherwise.
+
+    Examples:
+        >>> config = get_method_by_name("python")
+        >>> config is not None
+        True
+        >>> config.method == McpMethod.PYTHON
+        True
+    """
+    methods = detect_available_methods()
+    for method in methods:
+        if method.method.value == name:
+            return method
+    return None
+
+
+def generate_mcp_json(config: McpExecConfig | None = None) -> dict[str, Any]:
+    """
+    Generate .mcp.json content for the given configuration.
+
+    Args:
+        config: MCP execution config, or None to use recommended.
+
+    Returns:
+        Dictionary suitable for writing to .mcp.json.
+
+    Examples:
+        >>> from invar.shell.mcp_config import generate_mcp_json, McpExecConfig, McpMethod
+        >>> config = McpExecConfig(
+        ...     method=McpMethod.UVX,
+        ...     command="uvx",
+        ...     args=["invar-tools", "mcp"],
+        ...     description="test",
+        ... )
+        >>> result = generate_mcp_json(config)
+        >>> result["mcpServers"]["invar"]["command"]
+        'uvx'
+    """
+    if config is None:
+        config = get_recommended_method()
+
+    return {
+        "mcpServers": {
+            "invar": config.to_mcp_json(),
+        }
+    }