invar-tools 1.0.0__py3-none-any.whl

invar/mcp/server.py

@@ -0,0 +1,251 @@
+"""
+Invar MCP Server implementation.
+
+Exposes invar guard, sig, and map as first-class MCP tools.
+Part of DX-16: Agent Tool Enforcement.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from typing import Any
+
+from mcp.server import Server
+from mcp.types import TextContent, Tool
+
+# Strong instructions for agent behavior (DX-16 + DX-17)
+INVAR_INSTRUCTIONS = """
+## Invar Tool Usage (MANDATORY)
+
+This project uses Invar for all code verification and analysis.
+The following rules are MANDATORY, not suggestions.
+
+### Session Start (REQUIRED)
+
+Before writing ANY code, you MUST execute:
+
+1. `invar_guard(changed=true)` — Check existing violations
+2. `invar_map(top=10)` — Understand code structure
+
+Then read `.invar/examples/` and `.invar/context.md` for project context.
+
+**Skipping Session Start → Non-compliant code → Task failure.**
+
+### Tool Substitution Rules (ENFORCED)
+
+| Task | ❌ NEVER Use | ✅ ALWAYS Use |
+|------|-------------|---------------|
+| Verify code quality | `Bash("pytest ...")` | `invar_guard` |
+| Symbolic verification | `Bash("crosshair ...")` | `invar_guard` (included by default) |
+| Understand file structure | `Read` entire .py file | `invar_sig` |
+| Find entry points | `Grep` for "def " | `invar_map` |
+
+### Common Mistakes to AVOID
+
+❌ `Bash("python -m pytest file.py")` - Use invar_guard instead
+❌ `Bash("pytest --doctest-modules ...")` - invar_guard includes doctests
+❌ `Bash("crosshair check ...")` - invar_guard includes CrossHair by default
+❌ `Read("src/foo.py")` just to see signatures - Use invar_sig instead
+❌ `Grep` for function definitions - Use invar_map instead
+❌ `Bash("invar guard ...")` - Use invar_guard MCP tool instead
+
+### Task Completion
+
+A task is complete ONLY when:
+- Session Start executed (invar_guard + invar_map)
+- Final `invar_guard` passed
+- User requirement satisfied
+
+### Why This Matters
+
+1. **invar_guard** = Smart Guard (static + doctests + CrossHair + Hypothesis)
+2. **invar_sig** shows @pre/@post contracts that Read misses
+3. **invar_map** includes reference counts for importance ranking
+
+### Correct Usage Examples
+
+```
+# Session Start (REQUIRED before any code)
+invar_guard(changed=true)
+invar_map(top=10)
+
+# Verify code after changes (full verification by default)
+invar_guard(changed=true)
+
+# Understand a file's structure
+invar_sig(target="src/invar/core/parser.py")
+```
+
+IMPORTANT: Using Bash commands for Invar operations bypasses
+the MCP tools and may not follow the correct workflow.
+"""
+
+
+def _get_guard_tool() -> Tool:
+    """Define the invar_guard tool."""
+    return Tool(
+        name="invar_guard",
+        description=(
+            "Smart Guard: Verify code quality with static analysis + doctests. "
+            "Use this INSTEAD of Bash('pytest ...') or Bash('crosshair ...'). "
+            "Default runs static + doctests + CrossHair + Hypothesis."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Project path (default: .)", "default": "."},
+                "changed": {"type": "boolean", "description": "Only verify git-changed files", "default": True},
+                "strict": {"type": "boolean", "description": "Treat warnings as errors", "default": False},
+            },
+        },
+    )
+
+
+def _get_sig_tool() -> Tool:
+    """Define the invar_sig tool."""
+    return Tool(
+        name="invar_sig",
+        description=(
+            "Show function signatures and contracts (@pre/@post). "
+            "Use this INSTEAD of Read('file.py') when you want to understand structure."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "target": {"type": "string", "description": "File or file::symbol path"},
+            },
+            "required": ["target"],
+        },
+    )
+
+
+def _get_map_tool() -> Tool:
+    """Define the invar_map tool."""
+    return Tool(
+        name="invar_map",
+        description=(
+            "Symbol map with reference counts. "
+            "Use this INSTEAD of Grep for 'def ' to find functions."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Project path", "default": "."},
+                "top": {"type": "integer", "description": "Show top N symbols", "default": 10},
+            },
+        },
+    )
+
+
+def create_server() -> Server:
+    """Create and configure the Invar MCP server."""
+    server = Server(name="invar", version="0.1.0", instructions=INVAR_INSTRUCTIONS)
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return [_get_guard_tool(), _get_sig_tool(), _get_map_tool()]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+        handlers = {"invar_guard": _run_guard, "invar_sig": _run_sig, "invar_map": _run_map}
+        handler = handlers.get(name)
+        if handler:
+            return await handler(arguments)
+        return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+    return server
+
+
+async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
+    """Run invar guard command."""
+    cmd = [sys.executable, "-m", "invar.shell.cli", "guard"]
+
+    path = args.get("path", ".")
+    cmd.append(path)
+
+    if args.get("changed", True):
+        cmd.append("--changed")
+    if args.get("strict", False):
+        cmd.append("--strict")
+
+    # Always use JSON output for agent consumption
+    cmd.append("--json")
+
+    return await _execute_command(cmd)
+
+
+async def _run_sig(args: dict[str, Any]) -> list[TextContent]:
+    """Run invar sig command."""
+    target = args.get("target", "")
+    if not target:
+        return [TextContent(type="text", text="Error: target is required")]
+
+    cmd = [sys.executable, "-m", "invar.shell.cli", "sig", target, "--json"]
+    return await _execute_command(cmd)
+
+
+async def _run_map(args: dict[str, Any]) -> list[TextContent]:
+    """Run invar map command."""
+    cmd = [sys.executable, "-m", "invar.shell.cli", "map"]
+
+    path = args.get("path", ".")
+    cmd.append(path)
+
+    top = args.get("top", 10)
+    cmd.extend(["--top", str(top)])
+
+    cmd.append("--json")
+    return await _execute_command(cmd)
+
+
+async def _execute_command(cmd: list[str]) -> list[TextContent]:
+    """Execute a command and return the result."""
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+
+        output = result.stdout
+        if result.stderr:
+            output += f"\n\nStderr:\n{result.stderr}"
+
+        # Try to parse as JSON for better formatting
+        try:
+            parsed = json.loads(result.stdout)
+            output = json.dumps(parsed, indent=2)
+        except json.JSONDecodeError:
+            pass
+
+        return [TextContent(type="text", text=output)]
+
+    except subprocess.TimeoutExpired:
+        return [TextContent(type="text", text="Error: Command timed out (120s)")]
+    except Exception as e:
+        return [TextContent(type="text", text=f"Error: {e}")]
+
+
+def run_server() -> None:
+    """Run the Invar MCP server."""
+    import asyncio
+
+    from mcp.server.stdio import stdio_server
+
+    async def main():
+        server = create_server()
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                server.create_initialization_options(),
+            )
+
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run_server()

invar/resource.py

@@ -0,0 +1,99 @@
+"""
+Resource management decorators for Invar.
+
+Provides @must_close for marking classes that require explicit cleanup.
+Inspired by Move language's resource semantics.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+class ResourceWarning(UserWarning):
+    """Warning raised when a resource may not be properly closed."""
+
+    pass
+
+
+class MustCloseViolation(Exception):
+    """Raised when a @must_close resource is not properly managed."""
+
+    pass
+
+
+def must_close(cls: type[T]) -> type[T]:
+    """
+    Mark a class as a resource that must be explicitly closed.
+
+    The decorated class should have a `close()` method. The decorator:
+    1. Adds __invar_must_close__ marker for Guard detection
+    2. Adds context manager protocol if not present
+
+    Examples:
+        >>> @must_close
+        ... class TempFile:
+        ...     def __init__(self, path: str):
+        ...         self.path = path
+        ...         self.closed = False
+        ...     def write(self, data: str) -> None:
+        ...         if self.closed:
+        ...             raise ValueError("File is closed")
+        ...     def close(self) -> None:
+        ...         self.closed = True
+
+        >>> # Preferred: use as context manager
+        >>> with TempFile("test.txt") as f:
+        ...     f.write("hello")
+        >>> f.closed
+        True
+
+        >>> # Also works: explicit close
+        >>> f2 = TempFile("test2.txt")
+        >>> f2.write("world")
+        >>> f2.close()
+        >>> f2.closed
+        True
+    """
+    # Mark for Guard detection
+    cls.__invar_must_close__ = True  # type: ignore[attr-defined]
+
+    # Add context manager protocol if not present
+    if not hasattr(cls, "__enter__"):
+
+        def __enter__(self: Any) -> Any:
+            return self
+
+        cls.__enter__ = __enter__  # type: ignore[attr-defined]
+
+    if not hasattr(cls, "__exit__"):
+
+        def __exit__(self: Any, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+            if hasattr(self, "close") and callable(self.close):
+                self.close()
+
+        cls.__exit__ = __exit__  # type: ignore[attr-defined]
+
+    return cls
+
+
+def is_must_close(cls_or_obj: Any) -> bool:
+    """
+    Check if a class or instance is marked with @must_close.
+
+    >>> @must_close
+    ... class Resource:
+    ...     def close(self): pass
+    >>> is_must_close(Resource)
+    True
+    >>> is_must_close(Resource())
+    True
+    >>> class Plain: pass
+    >>> is_must_close(Plain)
+    False
+    """
+    if isinstance(cls_or_obj, type):
+        return getattr(cls_or_obj, "__invar_must_close__", False)
+    return getattr(type(cls_or_obj), "__invar_must_close__", False)

invar/shell/__init__.py

@@ -0,0 +1,8 @@
+"""
+Shell module: I/O operations.
+
+This module contains:
+- cli.py: Typer commands (invar guard, invar map, etc.)
+- fs.py: File system operations
+- config.py: Configuration loading from pyproject.toml
+"""