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

invar/shell/update_cmd.py

@@ -1,191 +0,0 @@
-"""
-Update command for Invar.
-
-Shell module: handles updating Invar-managed files to latest version.
-"""
-
-from __future__ import annotations
-
-import re
-from pathlib import Path
-
-import typer
-from returns.result import Failure, Result, Success
-from rich.console import Console
-
-from invar.shell.templates import copy_examples_directory, get_template_path
-
-console = Console()
-
-# Version pattern: matches "v3.23" or "v3.23.1"
-VERSION_PATTERN = re.compile(r"v(\d+)\.(\d+)(?:\.(\d+))?")
-
-
-def parse_version(text: str) -> tuple[int, int, int] | None:
-    """
-    Parse version string from text.
-
-    >>> parse_version("Protocol v3.23")
-    (3, 23, 0)
-    >>> parse_version("v3.23.1")
-    (3, 23, 1)
-    >>> parse_version("no version here")
-    """
-    match = VERSION_PATTERN.search(text)
-    if match:
-        major = int(match.group(1))
-        minor = int(match.group(2))
-        patch = int(match.group(3)) if match.group(3) else 0
-        return (major, minor, patch)
-    return None
-
-
-def get_current_version(path: Path) -> Result[tuple[int, int, int], str]:
-    """Get version from current INVAR.md file."""
-    invar_md = path / "INVAR.md"
-    if not invar_md.exists():
-        return Failure("INVAR.md not found. Run 'invar init' first.")
-
-    try:
-        content = invar_md.read_text()
-        version = parse_version(content)
-        if version is None:
-            return Failure("Could not parse version from INVAR.md")
-        return Success(version)
-    except OSError as e:
-        return Failure(f"Failed to read INVAR.md: {e}")
-
-
-def get_template_version() -> Result[tuple[int, int, int], str]:
-    """Get version from template INVAR.md."""
-    template_result = get_template_path("INVAR.md")
-    if isinstance(template_result, Failure):
-        return template_result
-
-    template_path = template_result.unwrap()
-    try:
-        content = template_path.read_text()
-        version = parse_version(content)
-        if version is None:
-            return Failure("Could not parse version from template")
-        return Success(version)
-    except OSError as e:
-        return Failure(f"Failed to read template: {e}")
-
-
-def format_version(version: tuple[int, int, int]) -> str:
-    """Format version tuple as string."""
-    if version[2] == 0:
-        return f"v{version[0]}.{version[1]}"
-    return f"v{version[0]}.{version[1]}.{version[2]}"
-
-
-def update_invar_md(path: Path, console: Console) -> Result[bool, str]:
-    """Update INVAR.md by overwriting with template."""
-    template_result = get_template_path("INVAR.md")
-    if isinstance(template_result, Failure):
-        return template_result
-
-    template_path = template_result.unwrap()
-    dest_file = path / "INVAR.md"
-
-    try:
-        dest_file.write_text(template_path.read_text())
-        return Success(True)
-    except OSError as e:
-        return Failure(f"Failed to update INVAR.md: {e}")
-
-
-def update_examples(path: Path, console: Console) -> Result[bool, str]:
-    """Update .invar/examples/ directory."""
-    import shutil
-
-    examples_dest = path / ".invar" / "examples"
-
-    # Remove existing examples
-    if examples_dest.exists():
-        try:
-            shutil.rmtree(examples_dest)
-        except OSError as e:
-            return Failure(f"Failed to remove old examples: {e}")
-
-    # Copy new examples
-    return copy_examples_directory(path, console)
-
-
-def update(
-    path: Path = typer.Argument(Path(), help="Project root directory"),
-    force: bool = typer.Option(
-        False, "--force", "-f", help="Update even if already at latest version"
-    ),
-    check: bool = typer.Option(
-        False, "--check", help="Check for updates without applying"
-    ),
-) -> None:
-    """
-    Update Invar-managed files to latest version.
-
-    Updates INVAR.md and .invar/examples/ from the installed python-invar package.
-    User-managed files (CLAUDE.md, .invar/context.md) are never modified.
-
-    Use --check to see if updates are available without applying them.
-    Use --force to update even if already at latest version.
-    """
-    # Get current version
-    current_result = get_current_version(path)
-    if isinstance(current_result, Failure):
-        console.print(f"[red]Error:[/red] {current_result.failure()}")
-        raise typer.Exit(1)
-    current_version = current_result.unwrap()
-
-    # Get template version
-    template_result = get_template_version()
-    if isinstance(template_result, Failure):
-        console.print(f"[red]Error:[/red] {template_result.failure()}")
-        raise typer.Exit(1)
-    template_version = template_result.unwrap()
-
-    current_str = format_version(current_version)
-    template_str = format_version(template_version)
-
-    # Compare versions
-    needs_update = template_version > current_version
-
-    if check:
-        # Check mode: just report status
-        if needs_update:
-            console.print(f"[yellow]Update available:[/yellow] {current_str} → {template_str}")
-        else:
-            console.print(f"[green]Up to date:[/green] {current_str}")
-        return
-
-    if not needs_update and not force:
-        console.print(f"[green]Already at latest version:[/green] {current_str}")
-        console.print("[dim]Use --force to update anyway[/dim]")
-        return
-
-    # Perform update
-    console.print("\n[bold]Updating Invar files...[/bold]")
-    console.print(f"  Version: {current_str} → {template_str}")
-    console.print()
-
-    # Update INVAR.md
-    result = update_invar_md(path, console)
-    if isinstance(result, Failure):
-        console.print(f"[red]Error:[/red] {result.failure()}")
-        raise typer.Exit(1)
-    console.print(f"[green]Updated[/green] INVAR.md ({template_str})")
-
-    # Update examples
-    result = update_examples(path, console)
-    if isinstance(result, Failure):
-        console.print(f"[yellow]Warning:[/yellow] {result.failure()}")
-    else:
-        console.print("[green]Updated[/green] .invar/examples/")
-
-    # Remind about user-managed files
-    console.print()
-    console.print("[dim]User-managed files unchanged:[/dim]")
-    console.print("[dim]  ○ CLAUDE.md[/dim]")
-    console.print("[dim]  ○ .invar/context.md[/dim]")
-    console.print("[dim]  ○ pyproject.toml [tool.invar][/dim]")

invar/templates/INVAR.md

@@ -1,134 +0,0 @@
-<!--
-  ┌─────────────────────────────────────────────────────────────┐
-  │ INVAR-MANAGED FILE - DO NOT EDIT DIRECTLY                   │
-  │                                                             │
-  │ This file is managed by Invar. Changes may be lost on       │
-  │ `invar update`. Add project content to CLAUDE.md instead.   │
-  └─────────────────────────────────────────────────────────────┘
--->
-# The Invar Protocol v3.26
-
-> **"Trade structure for safety."**
-
-## Six Laws
-
-| Law | Principle |
-|-----|-----------|
-| 1. Separation | Core (pure logic) / Shell (I/O) physically separate |
-| 2. Contract Complete | @pre/@post + doctests uniquely determine implementation |
-| 3. Context Economy | map → sig → code (only read what's needed) |
-| 4. Decompose First | Break into sub-functions before implementing |
-| 5. Verify Reflectively | Fail → Reflect (why?) → Fix → Verify |
-| 6. Integrate Fully | Local correct ≠ Global correct; verify all paths |
-
-## Core/Shell Architecture
-
-| Zone | Location | Requirements |
-|------|----------|--------------|
-| Core | `**/core/**` | @pre/@post, pure (no I/O), doctests |
-| Shell | `**/shell/**` | `Result[T, E]` return type |
-
-**Forbidden in Core:** `os`, `sys`, `subprocess`, `pathlib`, `open`, `requests`, `datetime.now`
-
-## Core Example (Pure Logic)
-
-```python
-from deal import pre, post
-
-@pre(lambda price, discount: price > 0 and 0 <= discount <= 1)
-@post(lambda result: result >= 0)
-def discounted_price(price: float, discount: float) -> float:
-    """
-    >>> discounted_price(100, 0.2)
-    80.0
-    >>> discounted_price(100, 0)      # Edge: no discount
-    100.0
-    """
-    return price * (1 - discount)
-```
-
-**Self-test:** Can someone else write the exact same function from just @pre/@post + doctests?
-
-## Shell Example (I/O Operations)
-
-```python
-from pathlib import Path
-from returns.result import Result, Success, Failure
-
-def read_config(path: Path) -> Result[dict, str]:
-    """Shell: handles I/O, returns Result for error handling."""
-    try:
-        import json
-        return Success(json.loads(path.read_text()))
-    except FileNotFoundError:
-        return Failure(f"File not found: {path}")
-    except json.JSONDecodeError as e:
-        return Failure(f"Invalid JSON: {e}")
-```
-
-**Pattern:** Shell reads file → passes content to Core → returns Result.
-
-More examples: `.invar/examples/`
-
-## Session Start (Required)
-
-Before writing any code, execute:
-
-1. **invar_guard** (changed=true) — Check existing violations
-2. **invar_map** (top=10) — Understand code structure
-
-Then read:
-- `.invar/examples/` — Core/Shell patterns
-- `.invar/context.md` — Project state, lessons learned
-
-**Skipping these steps → Non-compliant code → Rework required.**
-
-Use MCP tools if available (`invar_guard`, `invar_map`), otherwise use CLI commands.
-For agent-specific entry format, see your configuration file (CLAUDE.md, .cursorrules, etc).
-
-## ICIDIV Workflow (Required Order)
-
-```
-1. Intent    — What? Core or Shell? Edge cases?
-2. Contract  — @pre/@post + doctests BEFORE code
-3. Inspect   — invar sig <file>, invar map --top 10
-4. Design    — Decompose: leaves first, then compose
-5. Implement — Write code to pass your doctests
-6. Verify    — invar guard. If fail: reflect → fix → verify
-```
-
-**Contract before Implement. Verify after every change. No exceptions.**
-
-## Task Completion
-
-A task is complete only when ALL conditions are met:
-- Session Start executed (invar_guard + invar_map, context read)
-- Intent explicitly stated
-- Contract written before implementation
-- Final **invar_guard** passed
-- User requirement satisfied
-
-**Missing any = Task incomplete.**
-
-## Commands
-
-```bash
-invar guard              # Full: static + doctests + CrossHair + Hypothesis (default)
-invar guard --static     # Static only (quick debug, ~0.5s)
-invar guard --changed    # Modified files only
-invar sig <file>         # Show contracts + signatures
-invar map --top 10       # Most-referenced symbols
-```
-
-## Configuration
-
-```toml
-[tool.invar.guard]
-core_paths = ["src/myapp/core"]
-shell_paths = ["src/myapp/shell"]
-exclude_doctest_lines = true  # Don't count doctests in function size
-```
-
----
-
-*Protocol v3.26 | [Guide](docs/INVAR-GUIDE.md) | [Examples](.invar/examples/)*

invar_tools-1.0.0.dist-info/METADATA

@@ -1,321 +0,0 @@
-Metadata-Version: 2.4
-Name: invar-tools
-Version: 1.0.0
-Summary: AI-native software engineering tools with design-by-contract verification
-Project-URL: Homepage, https://github.com/tefx/invar
-Project-URL: Documentation, https://github.com/tefx/invar#readme
-Project-URL: Repository, https://github.com/tefx/invar
-Project-URL: Issues, https://github.com/tefx/invar/issues
-Author: Invar Team
-License-Expression: MIT
-License-File: LICENSE
-Keywords: ai,code-quality,contracts,design-by-contract,static-analysis
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development :: Quality Assurance
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Requires-Dist: crosshair-tool>=0.0.60
-Requires-Dist: hypothesis>=6.0
-Requires-Dist: invar-runtime>=1.0
-Requires-Dist: mcp>=1.0
-Requires-Dist: pre-commit>=3.0
-Requires-Dist: pydantic>=2.0
-Requires-Dist: returns>=0.20
-Requires-Dist: rich>=13.0
-Requires-Dist: typer>=0.9
-Provides-Extra: dev
-Requires-Dist: mypy>=1.0; extra == 'dev'
-Requires-Dist: pytest-cov>=4.0; extra == 'dev'
-Requires-Dist: pytest>=7.0; extra == 'dev'
-Requires-Dist: ruff>=0.1; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# Invar
-
-[![PyPI version](https://badge.fury.io/py/invar-tools.svg)](https://badge.fury.io/py/invar-tools)
-[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-**Don't hope AI code is correct. Know it.**
-
-Invar is a framework that helps developers ensure AI-generated code is reliable through contracts, verification, and mechanical checks.
-
-```python
-from invar_runtime import pre, post
-
-@pre(lambda items: len(items) > 0)
-@post(lambda result: result >= 0)
-def average(items: list[float]) -> float:
-    """
-    >>> average([1, 2, 3])
-    2.0
-    """
-    return sum(items) / len(items)
-```
-
----
-
-## Installation
-
-### Development Tools
-
-```bash
-# Recommended: use without installing
-uvx invar-tools guard
-
-# Or install globally
-pip install invar-tools
-```
-
-### Runtime Contracts (for your project)
-
-```bash
-pip install invar-runtime
-```
-
-**Packages:**
-
-| Package | Size | Purpose |
-|---------|------|---------|
-| `invar-runtime` | ~3MB | Runtime contracts (`@pre`, `@post`, etc.) |
-| `invar-tools` | ~100MB | Development tools (`guard`, `map`, `sig`, MCP) |
-
----
-
-## Quick Start
-
-```bash
-cd your-project
-invar init          # Creates INVAR.md, CLAUDE.md, .invar/
-invar guard         # Verify code quality
-```
-
-**Multi-Agent Support:** `invar init` auto-detects and configures:
-
-| AI Tool | Configuration |
-|---------|---------------|
-| Claude Code | Creates CLAUDE.md + MCP server |
-| Cursor | Adds to .cursorrules |
-| Aider | Adds to .aider.conf.yml |
-| Others | Add "Follow INVAR.md" to system prompt |
-
----
-
-## Core/Shell Architecture
-
-Invar enforces separation between pure logic and I/O:
-
-| Zone | Requirements | Forbidden |
-|------|--------------|-----------|
-| **Core** | `@pre`/`@post` contracts, doctests | I/O imports (os, pathlib, requests...) |
-| **Shell** | `Result[T, E]` returns | - |
-
-```python
-# Core: Pure logic, receives data
-def parse_config(content: str) -> Config:
-    return Config.parse(content)
-
-# Shell: Handles I/O, returns Result
-def load_config(path: Path) -> Result[Config, str]:
-    content = path.read_text()
-    return Success(parse_config(content))
-```
-
----
-
-## Commands
-
-### Guard (Primary)
-
-```bash
-invar guard              # Full verification (default)
-invar guard --changed    # Only git-modified files
-invar guard --static     # Static only (~0.5s)
-```
-
-**Flags:**
-
-| Flag | Purpose |
-|------|---------|
-| `--strict` | Treat warnings as errors |
-| `--explain` | Show rule limitations |
-| `--agent` | JSON output for AI tools |
-| `--pedantic` | Show all rules including off-by-default |
-
-### Other Commands
-
-```bash
-invar sig <file>         # Show signatures + contracts
-invar map --top 10       # Most-referenced symbols
-invar rules              # List all rules
-invar update             # Update managed files
-```
-
----
-
-## Verification Levels (DX-19)
-
-| Level | Command | Checks | When to Use |
-|-------|---------|--------|-------------|
-| STATIC | `--static` | Rules only (~0.5s) | Debugging static analysis |
-| STANDARD | (default) | Rules + doctests + CrossHair + Hypothesis (~5s) | Everything else |
-
-**Zero decisions:** Default runs full verification. Incremental mode makes it fast (~5s first, ~2s cached).
-
----
-
-## Configuration
-
-### pyproject.toml
-
-```toml
-[tool.invar.guard]
-# Directory classification
-core_paths = ["src/myapp/core"]
-shell_paths = ["src/myapp/shell"]
-
-# Or use patterns for existing projects
-core_patterns = ["**/domain/**", "**/models/**"]
-shell_patterns = ["**/api/**", "**/cli/**"]
-
-# Size limits
-max_file_lines = 500
-max_function_lines = 50
-
-# Contract requirements
-require_contracts = true
-require_doctests = true
-
-# Doctest-heavy code
-exclude_doctest_lines = true
-
-# Purity overrides
-purity_pure = ["pandas.DataFrame.groupby"]
-purity_impure = ["my_module.cached_lookup"]
-
-# Rule exclusions
-[[tool.invar.guard.rule_exclusions]]
-pattern = "**/generated/**"
-rules = ["*"]
-
-# Severity overrides
-[tool.invar.guard.severity_overrides]
-redundant_type_contract = "off"
-```
-
----
-
-## Rules Reference
-
-| Rule | Severity | What It Checks |
-|------|----------|----------------|
-| `file_size` | ERROR | File > max lines |
-| `function_size` | WARN | Function > max lines |
-| `missing_contract` | ERROR | Core function lacks @pre/@post |
-| `missing_doctest` | WARN | Contracted function lacks doctest |
-| `forbidden_import` | ERROR | I/O import in Core |
-| `shell_result` | WARN | Shell function not returning Result |
-| `empty_contract` | ERROR | Contract is `lambda: True` |
-| `param_mismatch` | ERROR | Lambda params ≠ function params |
-
-Full list: `invar rules --explain`
-
----
-
-## MCP Integration (Claude Code)
-
-`invar init` automatically creates `.mcp.json` with smart detection of available methods:
-
-```json
-{
-  "mcpServers": {
-    "invar": {
-      "command": "uvx",
-      "args": ["invar-tools", "mcp"]
-    }
-  }
-}
-```
-
-**Claude Code Integration:**
-
-```bash
-# Full integration (recommended)
-invar init --claude
-
-# Specify MCP method
-invar init --claude --mcp-method uvx      # Recommended
-invar init --claude --mcp-method command  # Use PATH invar
-invar init --claude --mcp-method python   # Use current Python
-```
-
-**MCP Tools:**
-
-| Tool | Replaces | Purpose |
-|------|----------|---------|
-| `invar_guard` | `pytest`, `crosshair` | Smart Guard verification |
-| `invar_sig` | Reading entire file | Show contracts and signatures |
-| `invar_map` | `grep` for functions | Symbol map with reference counts |
-
-Manual setup: See `.invar/mcp-setup.md` after running `invar init`.
-
----
-
-## File Ownership
-
-| File | Owner | Edit? |
-|------|-------|-------|
-| `INVAR.md` | Invar | No (`invar update` manages) |
-| `CLAUDE.md` | You | Yes (project config) |
-| `.invar/examples/` | Invar | No (reference only) |
-
----
-
-## Runtime Behavior
-
-Contracts are checked at runtime via [deal](https://github.com/life4/deal).
-
-```bash
-# Disable in production
-DEAL_DISABLE=1 python app.py
-```
-
----
-
-## Troubleshooting
-
-**Guard is slow:**
-- Use `--changed` for incremental checks
-- Use `--static` to skip doctests during debugging
-
-**Too many warnings:**
-- Add exclusions for generated code
-- Override severity for noisy rules
-
-**CrossHair timeout:**
-- Some code patterns don't work well with symbolic execution
-- Hypothesis fallback runs automatically
-
----
-
-## Learn More
-
-**In your project** (created by `invar init`):
-- `INVAR.md` — Protocol for AI agents
-- `CLAUDE.md` — Project configuration
-- `.invar/examples/` — Reference patterns
-
-**Documentation:**
-- [docs/INVAR-GUIDE.md](./docs/INVAR-GUIDE.md) — Detailed guide
-- [docs/VISION.md](./docs/VISION.md) — Design philosophy
-
----
-
-## License
-
-MIT