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

invar/shell/commands/merge.py

@@ -0,0 +1,256 @@
+"""
+DX-55: Smart merge logic for CLAUDE.md recovery.
+
+Shell module: handles merging and recovering CLAUDE.md content.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from typing import TYPE_CHECKING, Literal
+
+from returns.result import Failure, Result, Success
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from invar.core.template_parser import (
+    ClaudeMdState,
+    detect_claude_md_state,
+    format_preserved_content,
+    parse_invar_regions,
+    reconstruct_file,
+    strip_invar_markers,
+)
+from invar.shell.template_engine import generate_from_manifest
+
+# =============================================================================
+# DX-55: Project State Detection
+# =============================================================================
+
+
+@dataclass
+class ProjectState:
+    """Overall project initialization state.
+
+    DX-55: Captures full state for idempotent init decision.
+    """
+
+    initialized: bool
+    claude_md_state: ClaudeMdState
+    version: str
+    needs_update: bool
+
+    @property
+    def action(self) -> Literal["full_init", "update", "recover", "create", "none"]:
+        """Determine what action to take."""
+        if not self.initialized:
+            return "full_init"
+
+        match self.claude_md_state.state:
+            case "intact":
+                return "update" if self.needs_update else "none"
+            case "partial" | "missing":
+                return "recover"
+            case "absent":
+                return "create"
+            case _:
+                return "none"
+
+
+# @shell_complexity: State detection requires multiple file existence checks
+def detect_project_state(path: Path) -> ProjectState:
+    """Detect Invar initialization state.
+
+    DX-55: Core state detection for idempotent init.
+    """
+    from invar import __protocol_version__
+
+    invar_md = path / "INVAR.md"
+    invar_dir = path / ".invar"
+    claude_md = path / "CLAUDE.md"
+
+    initialized = invar_md.exists() and invar_dir.exists()
+
+    # Detect CLAUDE.md state
+    if claude_md.exists():
+        try:
+            content = claude_md.read_text()
+            claude_state = detect_claude_md_state(content)
+        except UnicodeDecodeError:
+            # Binary or non-UTF-8 content - treat as corrupt, will be replaced
+            claude_state = ClaudeMdState(state="partial")
+    else:
+        claude_state = ClaudeMdState(state="absent")
+
+    # Extract protocol version from existing INVAR.md
+    version = ""
+    if invar_md.exists():
+        content = invar_md.read_text()
+        import re
+
+        match = re.search(r"Invar (?:Protocol )?v([\d.]+)", content)
+        if match:
+            version = match.group(1)
+
+    # Check if update needed (compare protocol versions, not package versions)
+    needs_update = initialized and version != __protocol_version__
+
+    return ProjectState(
+        initialized=initialized,
+        claude_md_state=claude_state,
+        version=version,
+        needs_update=needs_update,
+    )
+
+
+# =============================================================================
+# DX-55: Smart Merge Functions
+# =============================================================================
+
+
+# @shell_complexity: Smart merge with multiple state handling paths
+def merge_claude_md(path: Path, state: ClaudeMdState) -> Result[str, str]:
+    """Smart merge CLAUDE.md based on detected state.
+
+    DX-55: Preserves user content while restoring Invar regions.
+    """
+    from pathlib import Path as PathLib  # Runtime import for Path operations
+
+    claude_md = PathLib(path) / "CLAUDE.md"
+
+    # Read existing content (handle binary/corrupt files)
+    existing_content = ""
+    if claude_md.exists():
+        try:
+            existing_content = claude_md.read_text()
+        except UnicodeDecodeError:
+            # Binary content - delete and recreate
+            claude_md.unlink()
+            state = ClaudeMdState(state="absent")
+
+    match state.state:
+        case "intact":
+            # Just update managed region, preserve user exactly
+            return _update_managed_only(path, existing_content)
+
+        case "partial":
+            # Corruption: try to salvage user content
+            return _recover_from_partial(path, existing_content, state)
+
+        case "missing":
+            # No Invar markers - treat entire file as user content
+            return _merge_with_preserved(path, existing_content)
+
+        case "absent":
+            # Just create new file
+            return Success("create_new")
+
+    return Success("no_action")
+
+
+# @shell_complexity: Template regeneration with region extraction
+def _update_managed_only(path: Path, existing_content: str) -> Result[str, str]:
+    """Update only the managed region, preserve user content."""
+    # Parse existing
+    parsed = parse_invar_regions(existing_content)
+
+    if "user" not in parsed.regions:
+        return Failure("No user region found")
+
+    # Generate fresh template
+    template_result = generate_from_manifest(
+        path, syntax="cli", files_to_generate=["CLAUDE.md"]
+    )
+    if isinstance(template_result, Failure):
+        return template_result
+
+    # Re-read and extract managed
+    new_content = (path / "CLAUDE.md").read_text()
+    new_parsed = parse_invar_regions(new_content)
+
+    if "managed" not in new_parsed.regions:
+        return Failure("Template missing managed region")
+
+    # Reconstruct with new managed but old user
+    updates = {"managed": new_parsed.regions["managed"].content}
+    final_content = reconstruct_file(parsed, updates)
+
+    (path / "CLAUDE.md").write_text(final_content)
+    return Success("updated_managed")
+
+
+# @shell_complexity: Recovery with content salvage logic
+def _recover_from_partial(
+    path: Path, existing_content: str, state: ClaudeMdState
+) -> Result[str, str]:
+    """Recover from partial corruption."""
+    from pathlib import Path as PathLib  # Runtime import for Path operations
+
+    # Try to salvage user content
+    if state.user_content:
+        user_content = state.user_content
+    else:
+        # Strip markers and treat rest as user content
+        user_content = strip_invar_markers(existing_content)
+        if user_content:
+            user_content = format_preserved_content(
+                user_content, date.today().isoformat()
+            )
+
+    # Remove existing CLAUDE.md so generate_from_manifest creates fresh template
+    claude_md = PathLib(path) / "CLAUDE.md"
+    if claude_md.exists():
+        claude_md.unlink()
+
+    # Generate fresh template
+    result = generate_from_manifest(
+        path, syntax="cli", files_to_generate=["CLAUDE.md"]
+    )
+    if isinstance(result, Failure):
+        return result
+
+    # Inject recovered user content
+    if user_content:
+        new_content = claude_md.read_text()
+        parsed = parse_invar_regions(new_content)
+        if "user" in parsed.regions:
+            updates = {"user": "\n" + user_content + "\n"}
+            final_content = reconstruct_file(parsed, updates)
+            claude_md.write_text(final_content)
+
+    return Success("recovered")
+
+
+def _merge_with_preserved(path: Path, existing_content: str) -> Result[str, str]:
+    """Merge overwritten content as preserved user content."""
+    from pathlib import Path as PathLib  # Runtime import for Path operations
+
+    # Format existing content as preserved
+    preserved = format_preserved_content(
+        existing_content, date.today().isoformat()
+    )
+
+    # Remove existing CLAUDE.md so generate_from_manifest creates fresh template
+    claude_md = PathLib(path) / "CLAUDE.md"
+    if claude_md.exists():
+        claude_md.unlink()
+
+    # Generate fresh template
+    result = generate_from_manifest(
+        path, syntax="cli", files_to_generate=["CLAUDE.md"]
+    )
+    if isinstance(result, Failure):
+        return result
+
+    # Inject preserved content into user region
+    new_content = claude_md.read_text()
+    parsed = parse_invar_regions(new_content)
+
+    if "user" in parsed.regions:
+        updates = {"user": "\n" + preserved + "\n"}
+        final_content = reconstruct_file(parsed, updates)
+        claude_md.write_text(final_content)
+
+    return Success("merged")

invar/shell/commands/mutate.py

@@ -0,0 +1,184 @@
+"""
+Mutation testing command for Invar CLI.
+
+DX-28: `invar mutate` wraps mutmut to detect undertested code.
+"""
+
+from __future__ import annotations
+
+import json as json_lib
+from pathlib import Path
+
+import typer
+from returns.result import Failure
+from rich.console import Console
+
+from invar.shell.mutation import (
+    MutationResult,
+    check_mutmut_installed,
+    get_surviving_mutants,
+    run_mutation_test,
+    show_mutant,
+)
+
+console = Console()
+
+
+# @shell:entry - CLI command entry point
+# @invar:allow entry_point_too_thick: CLI orchestration with multiple output modes
+def mutate(
+    target: Path = typer.Argument(
+        Path(),
+        help="File or directory to mutate",
+        exists=True,
+    ),
+    tests: Path = typer.Option(
+        None,
+        "--tests",
+        "-t",
+        help="Test directory (auto-detected if not specified)",
+    ),
+    timeout: int = typer.Option(
+        300,
+        "--timeout",
+        help="Maximum time in seconds",
+    ),
+    show_survivors: bool = typer.Option(
+        False,
+        "--survivors",
+        "-s",
+        help="Show surviving mutants",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output as JSON",
+    ),
+) -> None:
+    """
+    Run mutation testing to find undertested code.
+
+    DX-28: Uses mutmut to automatically mutate code (e.g., `in` → `not in`)
+    and check if tests catch the mutations. Surviving mutants indicate
+    weak test coverage.
+
+    Examples:
+
+        invar mutate src/myapp/core/parser.py
+
+        invar mutate src/myapp --tests tests/ --timeout 600
+
+        invar mutate --survivors  # Show surviving mutants from last run
+    """
+    # Check if mutmut is installed
+    install_check = check_mutmut_installed()
+    if isinstance(install_check, Failure):
+        if json_output:
+            console.print(json_lib.dumps({"error": install_check.failure()}))
+        else:
+            console.print(f"[red]Error:[/red] {install_check.failure()}")
+            console.print("\n[dim]Install with: pip install mutmut[/dim]")
+        raise typer.Exit(1)
+
+    # If just showing survivors from last run
+    if show_survivors:
+        result = get_surviving_mutants(target)
+        if isinstance(result, Failure):
+            if json_output:
+                console.print(json_lib.dumps({"error": result.failure()}))
+            else:
+                console.print(f"[red]Error:[/red] {result.failure()}")
+            raise typer.Exit(1)
+
+        survivors = result.unwrap()
+        if json_output:
+            console.print(json_lib.dumps({"survivors": survivors}))
+        else:
+            if survivors:
+                console.print(f"[yellow]Surviving mutants ({len(survivors)}):[/yellow]")
+                for s in survivors:
+                    console.print(f"  {s}")
+            else:
+                console.print("[green]No surviving mutants![/green]")
+        return
+
+    # Run mutation testing
+    if not json_output:
+        console.print(f"[bold]Running mutation testing on {target}...[/bold]")
+        console.print("[dim]This may take a while.[/dim]\n")
+
+    result = run_mutation_test(target, tests, timeout)
+
+    if isinstance(result, Failure):
+        if json_output:
+            console.print(json_lib.dumps({"error": result.failure()}))
+        else:
+            console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+    mutation_result = result.unwrap()
+    _display_mutation_result(mutation_result, json_output)
+
+    # Exit with error if mutation score is too low
+    if not mutation_result.passed:
+        raise typer.Exit(1)
+
+
+# @shell_complexity: Result display with dual output modes (JSON/human)
+def _display_mutation_result(result: MutationResult, json_output: bool) -> None:
+    """Display mutation testing results."""
+    if json_output:
+        data = {
+            "total": result.total,
+            "killed": result.killed,
+            "survived": result.survived,
+            "timeout": result.timeout,
+            "score": round(result.score, 1),
+            "passed": result.passed,
+            "errors": result.errors,
+            "survivors": result.survivors,
+        }
+        console.print(json_lib.dumps(data, indent=2))
+    else:
+        # Human-readable output
+        score_color = "green" if result.passed else "red"
+
+        console.print("\n[bold]Mutation Testing Results[/bold]")
+        console.print(f"  Total mutants: {result.total}")
+        console.print(f"  [green]Killed:[/green] {result.killed}")
+        console.print(f"  [red]Survived:[/red] {result.survived}")
+        if result.timeout > 0:
+            console.print(f"  [yellow]Timeout:[/yellow] {result.timeout}")
+
+        console.print(
+            f"\n  [{score_color}]Mutation Score: {result.score:.1f}%[/{score_color}]"
+        )
+
+        if result.passed:
+            console.print("\n[green]✓ Mutation testing passed (≥80% killed)[/green]")
+        else:
+            console.print("\n[red]✗ Mutation testing failed (<80% killed)[/red]")
+            console.print("[dim]Run with --survivors to see surviving mutants[/dim]")
+
+        if result.errors:
+            console.print("\n[yellow]Errors:[/yellow]")
+            for err in result.errors:
+                console.print(f"  {err}")
+
+
+# @shell:entry - CLI command for showing mutant details
+def mutant_show(
+    mutant_id: int = typer.Argument(..., help="Mutant ID to show"),
+) -> None:
+    """
+    Show the diff for a specific mutant.
+
+    Use after `invar mutate --survivors` to investigate surviving mutants.
+    """
+    result = show_mutant(mutant_id)
+
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+    console.print(result.unwrap())

invar/shell/{perception.py → commands/perception.py}

@@ -30,6 +30,7 @@ if TYPE_CHECKING:
 console = Console()
 
 
+# @shell_complexity: Symbol map generation with sorting and output modes
 def run_map(path: Path, top_n: int, json_output: bool) -> Result[None, str]:
     """
     Run the map command.
@@ -75,6 +76,7 @@ def run_map(path: Path, top_n: int, json_output: bool) -> Result[None, str]:
     return Success(None)
 
 
+# @shell_complexity: Signature extraction with symbol filtering
 def run_sig(target: str, json_output: bool) -> Result[None, str]:
     """
     Run the sig command.

invar/shell/commands/sync_self.py

@@ -0,0 +1,113 @@
+"""
+DX-56: Developer sync command for Invar (unified sync engine).
+
+Shell module: Special command for updating Invar's own project files.
+Uses MCP syntax and injects project-additions.md content.
+
+CLI: `invar dev sync` (formerly `invar sync-self`)
+
+This is a thin wrapper around the unified template_sync engine.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from returns.result import Failure
+from rich.console import Console
+
+from invar.core.sync_helpers import SyncConfig
+from invar.shell.commands.template_sync import sync_templates
+from invar.shell.template_engine import is_invar_project
+
+console = Console()
+
+
+# @shell_complexity: CLI command with result display and multiple output branches
+def sync_self(
+    path: Path = typer.Argument(Path(), help="Invar project root"),
+    check: bool = typer.Option(
+        False, "--check", help="Preview changes without applying"
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Update even if already current"
+    ),
+) -> None:
+    """
+    Synchronize Invar's own project files from templates.
+
+    DX-56: Now uses unified sync engine with manifest-driven file lists.
+
+    This command is for the Invar project only. It:
+    - Uses MCP syntax (invar_guard, invar_map, etc.)
+    - Injects .invar/project-additions.md into project region
+    - Updates managed regions while preserving user content
+    - Handles DX-55 state recovery (intact/partial/missing/absent)
+
+    Use --check to preview changes without applying them.
+    Use --force to update even if already current.
+    """
+    # Verify this is the Invar project
+    if not is_invar_project(path):
+        console.print("[red]Error:[/red] This command is only for the Invar project itself.")
+        console.print("[dim]Use 'invar init' for other projects.[/dim]")
+        raise typer.Exit(1)
+
+    console.print("[bold]Syncing Invar project files...[/bold]")
+    console.print("[dim]Using MCP syntax for templates[/dim]")
+    console.print()
+
+    # Configure for Invar project
+    config = SyncConfig(
+        syntax="mcp",
+        inject_project_additions=True,
+        force=force,
+        check=check,
+    )
+
+    # Run unified sync engine
+    result = sync_templates(path, config)
+
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+    report = result.unwrap()
+
+    # Display results
+    if check:
+        console.print("[bold]Preview mode - no changes applied[/bold]")
+        console.print()
+
+    for file in report.created:
+        action = "Would create" if check else "Created"
+        console.print(f"[green]{action}[/green] {file}")
+
+    for file in report.updated:
+        action = "Would update" if check else "Updated"
+        console.print(f"[cyan]{action}[/cyan] {file}")
+
+    for file in report.skipped:
+        console.print(f"[dim]Skipped[/dim] {file} (unchanged)")
+
+    for error in report.errors:
+        console.print(f"[yellow]Warning:[/yellow] {error}")
+
+    # Summary
+    console.print()
+    if check:
+        console.print("[bold]Dry run complete.[/bold]")
+        console.print(f"  Would create: {len(report.created)} files")
+        console.print(f"  Would update: {len(report.updated)} files")
+        console.print(f"  Would skip: {len(report.skipped)} files (unchanged)")
+    else:
+        console.print("[bold green]Sync complete![/bold green]")
+        console.print(f"  Created: {len(report.created)} files")
+        console.print(f"  Updated: {len(report.updated)} files")
+        console.print(f"  Skipped: {len(report.skipped)} files (unchanged)")
+
+    console.print()
+    console.print("[dim]MCP syntax applied:[/dim]")
+    console.print("[dim]  invar_guard(changed=true) instead of invar guard --changed[/dim]")
+    console.print("[dim]  invar_map(top=10) instead of invar map --top 10[/dim]")