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

invar/shell/template_engine.py

@@ -0,0 +1,345 @@
+"""DX-49: Template engine with I/O operations and Jinja2 support.
+
+This module provides:
+- File update with region preservation
+- Jinja2 template rendering
+- Manifest loading
+
+Pure parsing logic is in core/template_parser.py.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from deal import pre
+from returns.result import Failure, Result, Success
+
+# Import pure logic from Core
+from invar.core.template_parser import (
+    ParsedFile,
+    Region,
+    get_syntax_for_command,
+    parse_invar_regions,
+    reconstruct_file,
+)
+
+# Re-export for convenience
+__all__ = [
+    "ParsedFile",
+    "Region",
+    "generate_from_manifest",
+    "get_syntax_for_command",
+    "get_templates_dir",
+    "is_invar_project",
+    "load_manifest",
+    "parse_invar_regions",
+    "reconstruct_file",
+    "render_template",
+    "render_template_file",
+    "update_file_with_regions",
+]
+
+
+# =============================================================================
+# File Update Logic
+# =============================================================================
+
+
+# @shell_complexity: File handling requires branching for exists/has_regions/new_project cases
+@pre(lambda path, new_managed: isinstance(path, Path) and isinstance(new_managed, str))
+def update_file_with_regions(
+    path: Path,
+    new_managed: str,
+    new_project: str | None = None,
+) -> Result[str, str]:
+    """Update file preserving user regions and unmarked content.
+
+    Args:
+        path: File path to update
+        new_managed: New content for managed region
+        new_project: New content for project region (sync-self only)
+
+    Returns:
+        Success with updated content, or Failure with error message
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     _ = f.write('''<!--invar:managed-->
+        ... old
+        ... <!--/invar:managed-->
+        ... <!--invar:user-->
+        ... keep this
+        ... <!--/invar:user-->''')
+        ...     path = Path(f.name)
+        >>> result = update_file_with_regions(path, "NEW")
+        >>> isinstance(result, Success)
+        True
+        >>> "NEW" in result.unwrap()
+        True
+        >>> "keep this" in result.unwrap()
+        True
+        >>> path.unlink()  # cleanup
+    """
+    if not path.exists():
+        # New file - just wrap in managed region
+        content = f"<!--invar:managed-->\n{new_managed}\n<!--/invar:managed-->\n"
+        if new_project:
+            content += f"\n<!--invar:project-->\n{new_project}\n<!--/invar:project-->\n"
+        content += "\n<!--invar:user-->\n\n<!--/invar:user-->\n"
+        return Success(content)
+
+    try:
+        current = path.read_text()
+    except OSError as e:
+        return Failure(f"Failed to read {path}: {e}")
+
+    parsed = parse_invar_regions(current)
+
+    if not parsed.has_regions:
+        # No markers - insert at top, preserve rest
+        content = f"<!--invar:managed-->\n{new_managed}\n<!--/invar:managed-->\n\n"
+        content += current
+        return Success(content)
+
+    # Build updates dict
+    updates: dict[str, str] = {"managed": new_managed}
+    if new_project is not None and "project" in parsed.regions:
+        updates["project"] = new_project
+
+    result = reconstruct_file(parsed, updates)
+    return Success(result)
+
+
+# =============================================================================
+# Jinja2 Template Rendering
+# =============================================================================
+
+
+def render_template(
+    template_content: str,
+    variables: dict[str, str],
+) -> Result[str, str]:
+    """Render a Jinja2 template with given variables.
+
+    Args:
+        template_content: Jinja2 template string
+        variables: Variables to inject (syntax, version, project_name, etc.)
+
+    Returns:
+        Success with rendered content, or Failure with error
+
+    Examples:
+        >>> result = render_template("Hello {{ name }}", {"name": "World"})
+        >>> result.unwrap()
+        'Hello World'
+
+        >>> result = render_template("{% if x %}yes{% endif %}", {"x": True})
+        >>> result.unwrap()
+        'yes'
+    """
+    try:
+        from jinja2 import BaseLoader, Environment, StrictUndefined
+
+        env = Environment(
+            loader=BaseLoader(),
+            undefined=StrictUndefined,
+            keep_trailing_newline=True,
+        )
+        template = env.from_string(template_content)
+        rendered = template.render(**variables)
+        return Success(rendered)
+    except ImportError:
+        return Failure("Jinja2 not installed. Run: pip install jinja2")
+    except Exception as e:
+        return Failure(f"Template rendering failed: {e}")
+
+
+def render_template_file(
+    template_path: Path,
+    variables: dict[str, str],
+) -> Result[str, str]:
+    """Render a Jinja2 template file.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.jinja', delete=False) as f:
+        ...     _ = f.write("Version: {{ version }}")
+        ...     path = Path(f.name)
+        >>> result = render_template_file(path, {"version": "5.0"})
+        >>> result.unwrap()
+        'Version: 5.0'
+        >>> path.unlink()
+    """
+    try:
+        content = template_path.read_text()
+    except OSError as e:
+        return Failure(f"Failed to read template {template_path}: {e}")
+
+    return render_template(content, variables)
+
+
+# =============================================================================
+# Manifest Loading
+# =============================================================================
+
+
+# @shell_complexity: TOML loading with Python version fallback (tomllib vs tomli)
+def load_manifest(templates_dir: Path) -> Result[dict, str]:
+    """Load manifest.toml from templates directory.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> # Will fail if manifest doesn't exist
+        >>> result = load_manifest(Path("/nonexistent"))
+        >>> isinstance(result, Failure)
+        True
+    """
+    manifest_path = templates_dir / "manifest.toml"
+
+    if not manifest_path.exists():
+        return Failure(f"Manifest not found: {manifest_path}")
+
+    try:
+        import tomllib
+
+        content = manifest_path.read_text()
+        data = tomllib.loads(content)
+        return Success(data)
+    except ImportError:
+        # Python < 3.11
+        try:
+            import tomli as tomllib  # type: ignore
+
+            content = manifest_path.read_text()
+            data = tomllib.loads(content)
+            return Success(data)
+        except ImportError:
+            return Failure("tomllib/tomli not available")
+    except Exception as e:
+        return Failure(f"Failed to parse manifest: {e}")
+
+
+# =============================================================================
+# Template Generation
+# =============================================================================
+
+
+def get_templates_dir() -> Path:
+    """Get the templates directory path."""
+    return Path(__file__).parent.parent / "templates"
+
+
+# @shell_complexity: Template generation has multiple paths for copy/jinja/copy_dir types
+def generate_from_manifest(
+    dest_root: Path,
+    syntax: str = "cli",
+    files_to_generate: list[str] | None = None,
+) -> Result[list[str], str]:
+    """Generate files from manifest.toml templates.
+
+    Args:
+        dest_root: Destination project root
+        syntax: "cli" or "mcp" for command syntax
+        files_to_generate: Optional list of files to generate (None = all from manifest)
+
+    Returns:
+        Success with list of generated files, or Failure with error
+    """
+    templates_dir = get_templates_dir()
+    manifest_result = load_manifest(templates_dir)
+    if isinstance(manifest_result, Failure):
+        return manifest_result
+
+    manifest = manifest_result.unwrap()
+    templates = manifest.get("templates", {})
+    # Copy to avoid mutating cached manifest
+    variables = {**manifest.get("variables", {}), "syntax": syntax}
+
+    generated: list[str] = []
+
+    for dest_path, config in templates.items():
+        # Skip if not in files_to_generate list
+        if files_to_generate is not None and dest_path not in files_to_generate:
+            continue
+
+        src = config.get("src", "")
+        template_type = config.get("type", "copy")
+        src_path = templates_dir / src
+
+        # Resolve destination
+        full_dest = dest_root / dest_path
+
+        # Ensure parent directories exist
+        full_dest.parent.mkdir(parents=True, exist_ok=True)
+
+        if template_type == "copy":
+            # Direct file copy
+            if not src_path.exists():
+                continue
+            if full_dest.exists():
+                continue  # Don't overwrite existing
+            try:
+                full_dest.write_text(src_path.read_text())
+                generated.append(dest_path)
+            except OSError as e:
+                print(f"Warning: Failed to copy {dest_path}: {e}", file=sys.stderr)
+                continue
+
+        elif template_type == "jinja":
+            # Jinja2 template rendering
+            if not src_path.exists():
+                continue
+            if full_dest.exists():
+                continue  # Don't overwrite existing
+            result = render_template_file(src_path, variables)
+            if isinstance(result, Success):
+                try:
+                    full_dest.write_text(result.unwrap())
+                    generated.append(dest_path)
+                except OSError as e:
+                    print(f"Warning: Failed to write {dest_path}: {e}", file=sys.stderr)
+                    continue
+
+        elif template_type == "copy_dir":
+            # Directory copy
+            if not src_path.exists() or not src_path.is_dir():
+                continue
+            if full_dest.exists():
+                continue  # Don't overwrite existing directory
+            try:
+                import shutil
+                shutil.copytree(src_path, full_dest)
+                generated.append(dest_path)
+            except OSError as e:
+                print(f"Warning: Failed to copy directory {dest_path}: {e}", file=sys.stderr)
+                continue
+
+    return Success(generated)
+
+
+# =============================================================================
+# Utility Functions
+# =============================================================================
+
+
+def is_invar_project(project_root: Path) -> bool:
+    """Check if this is the Invar project itself.
+
+    The Invar project has special handling via sync-self.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> is_invar_project(Path("/some/random/project"))
+        False
+    """
+    # Check for Invar-specific markers
+    invar_markers = [
+        project_root / "src" / "invar" / "__init__.py",
+        project_root / "runtime" / "src" / "invar_runtime" / "__init__.py",
+    ]
+    return all(marker.exists() for marker in invar_markers)

invar/shell/templates.py

@@ -53,6 +53,7 @@ def get_template_path(name: str) -> Result[Path, str]:
         return Failure(f"Failed to get template path: {e}")
 
 
+# @shell_complexity: Template copy with path resolution
 def copy_template(
     template_name: str, dest: Path, dest_name: str | None = None
 ) -> Result[bool, str]:
@@ -73,6 +74,7 @@ def copy_template(
         return Failure(f"Failed to copy template: {e}")
 
 
+# @shell_complexity: Config addition with existing file detection
 def add_config(path: Path, console) -> Result[bool, str]:
     """Add configuration to project. Returns Success(True) if added, Success(False) if skipped."""
     pyproject = path / "pyproject.toml"
@@ -114,6 +116,7 @@ def create_directories(path: Path, console) -> None:
         console.print("[green]Created[/green] src/shell/")
 
 
+# @shell_complexity: Directory copy with file filtering
 def copy_examples_directory(dest: Path, console) -> Result[bool, str]:
     """Copy examples directory to .invar/examples/. Returns Success(True) if copied."""
     import shutil
@@ -139,6 +142,51 @@ def copy_examples_directory(dest: Path, console) -> Result[bool, str]:
         return Failure(f"Failed to copy examples: {e}")
 
 
+# @shell_complexity: Directory copy for Claude commands (DX-32)
+def copy_commands_directory(dest: Path, console) -> Result[bool, str]:
+    """Copy commands directory to .claude/commands/. Returns Success(True) if copied."""
+    import shutil
+
+    commands_dest = dest / ".claude" / "commands"
+    if commands_dest.exists():
+        return Success(False)
+
+    try:
+        commands_src = Path(str(resources.files("invar.templates").joinpath("commands")))
+        if not commands_src.exists():
+            return Failure("Commands template directory not found")
+
+        # Create .claude if needed
+        claude_dir = dest / ".claude"
+        if not claude_dir.exists():
+            claude_dir.mkdir()
+
+        shutil.copytree(commands_src, commands_dest)
+        console.print("[green]Created[/green] .claude/commands/ (Claude Code skills)")
+        return Success(True)
+    except OSError as e:
+        return Failure(f"Failed to copy commands: {e}")
+
+
+# @shell_complexity: Directory copy for Claude skills (DX-36)
+def copy_skills_directory(dest: Path, console) -> Result[bool, str]:
+    """Copy skills directory to .claude/skills/. Returns Success(True) if copied."""
+    import shutil
+    skills_dest = dest / ".claude" / "skills"
+    if skills_dest.exists():
+        return Success(False)
+    try:
+        skills_src = Path(str(resources.files("invar.templates").joinpath("skills")))
+        if not skills_src.exists():
+            return Failure("Skills template directory not found")
+        (dest / ".claude").mkdir(exist_ok=True)
+        shutil.copytree(skills_src, skills_dest)
+        console.print("[green]Created[/green] .claude/skills/ (workflow skills)")
+        return Success(True)
+    except OSError as e:
+        return Failure(f"Failed to copy skills: {e}")
+
+
 # Agent configuration for multi-agent support (DX-11, DX-17)
 AGENT_CONFIGS = {
     "claude": {
@@ -162,6 +210,7 @@ AGENT_CONFIGS = {
 }
 
 
+# @shell_complexity: Agent config detection across multiple locations
 def detect_agent_configs(path: Path) -> Result[dict[str, str], str]:
     """
     Detect existing agent configuration files.
@@ -195,6 +244,7 @@ def detect_agent_configs(path: Path) -> Result[dict[str, str], str]:
         return Failure(f"Failed to detect agent configs: {e}")
 
 
+# @shell_complexity: Reference addition with existing check
 def add_invar_reference(path: Path, agent: str, console) -> Result[bool, str]:
     """Add Invar reference to an existing agent config file."""
     if agent not in AGENT_CONFIGS:
@@ -220,6 +270,7 @@ def add_invar_reference(path: Path, agent: str, console) -> Result[bool, str]:
         return Failure(f"Failed to update {config['file']}: {e}")
 
 
+# @shell_complexity: Config creation with template selection
 def create_agent_config(path: Path, agent: str, console) -> Result[bool, str]:
     """
     Create agent config from template (DX-17).
@@ -248,6 +299,7 @@ def create_agent_config(path: Path, agent: str, console) -> Result[bool, str]:
     return Success(False)
 
 
+# @shell_complexity: MCP server config with JSON manipulation
 def configure_mcp_server(path: Path, console) -> Result[list[str], str]:
     """
     Configure MCP server for AI agents (DX-16).
@@ -407,6 +459,7 @@ The server communicates via stdio and should be managed by your AI agent.
 """
 
 
+# @shell_complexity: Git hooks installation with backup
 def install_hooks(path: Path, console) -> Result[bool, str]:
     """Install pre-commit hooks configuration and activate them."""
     import subprocess

invar/shell/testing.py

@@ -18,10 +18,12 @@ from pathlib import Path
 from returns.result import Failure, Result, Success
 from rich.console import Console
 
+from invar.shell.prove.cache import ProveCache
+
 # 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 (
+# DX-48b: Relocated to shell/prove/
+from invar.shell.prove.crosshair import (
     CrossHairStatus,
     get_files_to_prove,
     run_crosshair_on_files,
@@ -29,7 +31,7 @@ from invar.shell.prove import (
     run_hypothesis_fallback,
     run_prove_with_fallback,
 )
-from invar.shell.prove_cache import ProveCache
+from invar.shell.subprocess_env import build_subprocess_env
 
 console = Console()
 
@@ -40,7 +42,6 @@ __all__ = [
     "ProveCache",
     "VerificationLevel",
     "VerificationResult",
-    "detect_verification_context",
     "get_available_verifiers",
     "get_files_to_prove",
     "run_crosshair_on_files",
@@ -80,6 +81,7 @@ class VerificationResult:
     errors: list[str] = field(default_factory=list)
 
 
+# @shell_orchestration: Verifier discovery helper
 def get_available_verifiers() -> list[str]:
     """
     Detect installed verification tools.
@@ -111,23 +113,12 @@ def get_available_verifiers() -> list[str]:
     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
-
-
+# @shell_complexity: Doctest execution with subprocess and result parsing
 def run_doctests_on_files(
-    files: list[Path], verbose: bool = False
+    files: list[Path],
+    verbose: bool = False,
+    timeout: int = 60,
+    collect_coverage: bool = False,
 ) -> Result[dict, str]:
     """
     Run doctests on a list of Python files.
@@ -135,6 +126,8 @@ def run_doctests_on_files(
     Args:
         files: List of Python file paths to test
         verbose: Show verbose output
+        timeout: Maximum time in seconds (default: 60, from RuleConfig.timeout_doctest)
+        collect_coverage: DX-37: If True, run with coverage.py and return coverage data
 
     Returns:
         Success with test results or Failure with error message
@@ -143,21 +136,45 @@ def run_doctests_on_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()]
+    # Exclude: conftest.py (pytest config), templates/examples/ (source templates, not user examples)
+    py_files = [
+        f for f in files
+        if f.suffix == ".py"
+        and f.exists()
+        and f.name != "conftest.py"
+        and "templates/examples" not in str(f)
+    ]
     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",
-    ]
+    # DX-37: Build command with optional coverage
+    if collect_coverage:
+        # Use coverage run to wrap pytest
+        cmd = [
+            sys.executable, "-m", "coverage", "run",
+            "--branch",  # Enable branch coverage
+            "--parallel-mode",  # For merging with hypothesis later
+            "-m", "pytest",
+            "--doctest-modules", "-x", "--tb=short",
+        ]
+    else:
+        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)
+        # DX-52: Inject project venv site-packages for uvx compatibility
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=build_subprocess_env(),
+        )
         # Pytest exit codes: 0=passed, 5=no tests collected (also OK)
         is_passed = result.returncode in (0, 5)
         return Success({
@@ -166,15 +183,17 @@ def run_doctests_on_files(
             "exit_code": result.returncode,
             "stdout": result.stdout,
             "stderr": result.stderr,
+            "coverage_collected": collect_coverage,  # DX-37: Flag for caller
         })
     except subprocess.TimeoutExpired:
-        return Failure("Doctest timeout (120s)")
+        return Failure(f"Doctest timeout ({timeout}s)")
     except Exception as e:
         return Failure(f"Doctest error: {e}")
 
 
+# @shell_complexity: Property test orchestration with subprocess
 def run_test(
-    target: str, json_output: bool = False, verbose: bool = False
+    target: str, json_output: bool = False, verbose: bool = False, timeout: int = 300
 ) -> Result[dict, str]:
     """
     Run property-based tests using Hypothesis via deal.cases.
@@ -183,6 +202,7 @@ def run_test(
         target: File path or module to test
         json_output: Output as JSON
         verbose: Show verbose output
+        timeout: Maximum time in seconds (default: 300, from RuleConfig.timeout_hypothesis)
 
     Returns:
         Success with test results or Failure with error message
@@ -201,7 +221,14 @@ def run_test(
         cmd.append("-v")
 
     try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+        # DX-52: Inject project venv site-packages for uvx compatibility
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=build_subprocess_env(),
+        )
         test_result = {
             "status": "passed" if result.returncode == 0 else "failed",
             "target": str(target_path),
@@ -225,13 +252,17 @@ def run_test(
 
         return Success(test_result)
     except subprocess.TimeoutExpired:
-        return Failure(f"Test timeout (300s): {target}")
+        return Failure(f"Test timeout ({timeout}s): {target}")
     except Exception as e:
         return Failure(f"Test error: {e}")
 
 
+# @shell_complexity: CrossHair verification with subprocess
 def run_verify(
-    target: str, json_output: bool = False, timeout: int = 30
+    target: str,
+    json_output: bool = False,
+    total_timeout: int = 300,
+    per_condition_timeout: int = 30,
 ) -> Result[dict, str]:
     """
     Run symbolic verification using CrossHair.
@@ -239,7 +270,8 @@ def run_verify(
     Args:
         target: File path or module to verify
         json_output: Output as JSON
-        timeout: Timeout per function in seconds
+        total_timeout: Total timeout in seconds (default: 300, from RuleConfig.timeout_crosshair)
+        per_condition_timeout: Per-contract timeout (default: 30, from RuleConfig.timeout_crosshair_per_condition)
 
     Returns:
         Success with verification results or Failure with error message
@@ -260,15 +292,23 @@ def run_verify(
 
     cmd = [
         sys.executable, "-m", "crosshair", "check",
-        str(target_path), f"--per_condition_timeout={timeout}",
+        str(target_path), f"--per_condition_timeout={per_condition_timeout}",
     ]
 
     try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout * 10)
+        # DX-52: Inject project venv site-packages for uvx compatibility
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=total_timeout,
+            env=build_subprocess_env(),
+        )
 
+        # CrossHair format: "file:line: error: Err when calling func(...)"
         counterexamples = [
             line.strip() for line in result.stdout.split("\n")
-            if "error" in line.lower() or "counterexample" in line.lower()
+            if ": error:" in line.lower() or "counterexample" in line.lower()
         ]
 
         verify_result = {
@@ -292,6 +332,6 @@ def run_verify(
 
         return Success(verify_result)
     except subprocess.TimeoutExpired:
-        return Failure(f"Verification timeout ({timeout * 10}s): {target}")
+        return Failure(f"Verification timeout ({total_timeout}s): {target}")
     except Exception as e:
         return Failure(f"Verification error: {e}")