invar-tools 1.0.0__py3-none-any.whl

invar/templates/INVAR.md

@@ -0,0 +1,134 @@
+<!--
+  ┌─────────────────────────────────────────────────────────────┐
+  │ 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/templates/__init__.py

@@ -0,0 +1 @@
+"""Template files for invar init command."""

invar/templates/aider.conf.yml.template

@@ -0,0 +1,29 @@
+# Invar Protocol Configuration for Aider
+# Follow the Invar Protocol in INVAR.md
+
+# Auto-read protocol files at session start
+read:
+  - INVAR.md
+  - .invar/examples/core_example.py
+  - .invar/examples/shell_example.py
+  - .invar/context.md
+
+# System prompt addition
+system-prompt: |
+  Follow the Invar Protocol in INVAR.md.
+
+  Before writing code, execute:
+  1. invar_guard (changed=true) - or: invar guard --changed
+  2. invar_map (top=10) - or: invar map --top 10
+
+  Use MCP tools if available, otherwise use CLI commands.
+
+  Workflow (ICIDIV):
+  - Intent: What? Core or Shell?
+  - Contract: @pre/@post + doctests BEFORE code
+  - Inspect: invar_sig (or: invar sig <file>)
+  - Design: Decompose first
+  - Implement: Pass your doctests
+  - Verify: invar_guard (or: invar guard)
+
+  Task complete only when final invar_guard passes.

invar/templates/context.md.template

@@ -0,0 +1,51 @@
+# Project Context
+
+*Last updated: [DATE]*
+
+## Current State
+
+- Phase: [current development phase]
+- Working on: [current task or feature]
+- Blockers: None
+
+## Recent Decisions
+
+1. [Decision summary] - [Brief rationale]
+
+## Lessons Learned
+
+1. [Pitfall or issue] → [Solution or workaround]
+
+## Documentation Structure
+
+| File | Owner | Edit? |
+|------|-------|-------|
+| INVAR.md | Invar | No — use `invar update` |
+| CLAUDE.md | User | Yes |
+| .invar/context.md | User | Yes (this file) |
+| .invar/examples/ | Invar | No |
+
+**Decision rule:** Is this Invar protocol or project-specific?
+- Protocol content → Already in INVAR.md, don't duplicate
+- Project-specific → Add to CLAUDE.md or here
+
+## Technical Debt
+
+*Run `invar guard` to check current status.*
+
+| File | Warning | Priority |
+|------|---------|----------|
+| (none) | — | — |
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| INVAR.md | Protocol reference (Invar-managed) |
+| CLAUDE.md | Project guide (customize freely) |
+| src/core/ | Pure business logic |
+| src/shell/ | I/O adapters |
+
+---
+
+*Update this file when: completing major tasks, making design decisions, discovering pitfalls.*

invar/templates/cursorrules.template

@@ -0,0 +1,28 @@
+# Invar Protocol
+
+Follow the Invar Protocol in INVAR.md — includes Session Start, ICIDIV workflow, and Task Completion requirements.
+
+## Cursor-Specific: Entry Verification
+
+Before writing any code, execute and show output from:
+
+```
+invar_guard (changed=true)   # Check existing violations
+invar_map (top=10)           # Understand code structure
+```
+
+Use MCP tools if available, otherwise use CLI commands:
+- `invar guard --changed`
+- `invar map --top 10`
+
+Then read .invar/examples/ and .invar/context.md.
+
+Skipping these steps leads to non-compliant code.
+
+## Quick Reference
+
+- Core (`**/core/**`): @pre/@post contracts, doctests, pure (no I/O)
+- Shell (`**/shell/**`): Result[T, E] return type
+- Workflow: Intent → Contract → Inspect → Design → Implement → Verify
+- Contract before Implement. No exceptions.
+- Task complete only when final invar_guard passes.

invar/templates/examples/README.md

@@ -0,0 +1,21 @@
+# Invar Examples
+
+Reference examples for the Invar Protocol. These are managed by Invar.
+
+## Files
+
+| File | Content |
+|------|---------|
+| [contracts.py](contracts.py) | @pre/@post patterns, doctest best practices |
+| [core_shell.py](core_shell.py) | Core/Shell separation patterns |
+
+## Usage
+
+Read these when you need:
+- Contract pattern reference
+- Core vs Shell decision guidance
+- Doctest formatting examples
+
+---
+
+*Managed by Invar. Do not edit — use `invar update` to sync.*

invar/templates/examples/contracts.py

@@ -0,0 +1,111 @@
+"""
+Invar Contract Examples
+
+Reference patterns for @pre/@post contracts and doctests.
+Managed by Invar - do not edit directly.
+"""
+
+from deal import post, pre
+
+# =============================================================================
+# GOOD: Complete Contract
+# =============================================================================
+
+
+@pre(lambda price, discount: price > 0 and 0 <= discount <= 1)
+@post(lambda result: result >= 0)
+def discounted_price(price: float, discount: float) -> float:
+    """
+    Apply discount to price.
+
+    >>> discounted_price(100.0, 0.2)
+    80.0
+    >>> discounted_price(100.0, 0)      # Edge: no discount
+    100.0
+    >>> discounted_price(100.0, 1)      # Edge: full discount
+    0.0
+    """
+    return price * (1 - discount)
+
+
+# =============================================================================
+# GOOD: List Processing with Length Constraint
+# =============================================================================
+
+
+@pre(lambda items: len(items) > 0)
+@post(lambda result: result >= 0)
+def average(items: list[float]) -> float:
+    """
+    Calculate average of non-empty list.
+
+    >>> average([1, 2, 3])
+    2.0
+    >>> average([5])        # Edge: single element
+    5.0
+    >>> average([0, 0, 0])  # Edge: all zeros
+    0.0
+    """
+    return sum(items) / len(items)
+
+
+# =============================================================================
+# GOOD: Dict Comparison in Doctests
+# =============================================================================
+
+
+@pre(lambda data: isinstance(data, dict))
+@post(lambda result: isinstance(result, dict))
+def normalize_keys(data: dict[str, int]) -> dict[str, int]:
+    """
+    Lowercase all keys.
+
+    # GOOD: Use sorted() for deterministic output
+    >>> sorted(normalize_keys({'A': 1, 'B': 2}).items())
+    [('a', 1), ('b', 2)]
+
+    # GOOD: Or use equality comparison
+    >>> normalize_keys({'X': 10}) == {'x': 10}
+    True
+    """
+    return {k.lower(): v for k, v in data.items()}
+
+
+# =============================================================================
+# BAD: Incomplete Contract (anti-pattern)
+# =============================================================================
+
+# DON'T: Empty contract tells nothing
+# @pre(lambda: True)
+# @post(lambda result: True)
+# def process(x): ...  # noqa: ERA001
+
+# DON'T: Missing edge cases in doctests
+# def divide(a, b):
+#     """
+#     >>> divide(10, 2)
+#     5.0
+#     # Missing: what about b=0?
+#     """
+
+
+# =============================================================================
+# GOOD: Multiple @pre for Clarity
+# =============================================================================
+
+
+@pre(lambda start, end: start >= 0)
+@pre(lambda start, end: end >= start)
+@post(lambda result: result >= 0)
+def range_size(start: int, end: int) -> int:
+    """
+    Calculate size of range [start, end).
+
+    >>> range_size(0, 10)
+    10
+    >>> range_size(5, 5)    # Edge: empty range
+    0
+    >>> range_size(0, 1)    # Edge: single element
+    1
+    """
+    return end - start

invar/templates/examples/core_shell.py

@@ -0,0 +1,121 @@
+"""
+Invar Core/Shell Separation Examples
+
+Reference patterns for Core vs Shell architecture.
+Managed by Invar - do not edit directly.
+"""
+
+from pathlib import Path
+
+from deal import post, pre
+from returns.result import Failure, Result, Success
+
+# =============================================================================
+# CORE: Pure Logic (no I/O)
+# =============================================================================
+# Location: src/*/core/
+# Requirements: @pre/@post, doctests, no I/O imports
+# =============================================================================
+
+
+@pre(lambda content: isinstance(content, str))
+@post(lambda result: isinstance(result, list))
+def parse_lines(content: str) -> list[str]:
+    """
+    Parse content into non-empty lines.
+
+    >>> parse_lines("a\\nb\\nc")
+    ['a', 'b', 'c']
+    >>> parse_lines("")
+    []
+    >>> parse_lines("  \\n  ")  # Edge: whitespace only
+    []
+    """
+    return [line.strip() for line in content.split("\n") if line.strip()]
+
+
+@pre(lambda items: isinstance(items, list))
+@post(lambda result: isinstance(result, dict))
+def count_items(items: list[str]) -> dict[str, int]:
+    """
+    Count occurrences of each item.
+
+    >>> sorted(count_items(['a', 'b', 'a']).items())
+    [('a', 2), ('b', 1)]
+    >>> count_items([])
+    {}
+    """
+    counts: dict[str, int] = {}
+    for item in items:
+        counts[item] = counts.get(item, 0) + 1
+    return counts
+
+
+# =============================================================================
+# SHELL: I/O Operations
+# =============================================================================
+# Location: src/*/shell/
+# Requirements: Result[T, E] return type, calls Core for logic
+# =============================================================================
+
+
+def read_file(path: Path) -> Result[str, str]:
+    """
+    Read file content.
+
+    Shell handles I/O, returns Result for error handling.
+    """
+    try:
+        return Success(path.read_text())
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+
+
+def count_lines_in_file(path: Path) -> Result[dict[str, int], str]:
+    """
+    Count lines in file - demonstrates Core/Shell integration.
+
+    Shell reads file → Core parses content → Shell returns result.
+    """
+    # Shell: I/O operation
+    content_result = read_file(path)
+
+    if isinstance(content_result, Failure):
+        return content_result
+
+    content = content_result.unwrap()
+
+    # Core: Pure logic (no I/O)
+    lines = parse_lines(content)
+    counts = count_items(lines)
+
+    # Shell: Return result
+    return Success(counts)
+
+
+# =============================================================================
+# ANTI-PATTERNS
+# =============================================================================
+
+# DON'T: I/O in Core
+# def parse_file(path: Path):  # BAD: Path in Core
+#     content = path.read_text()  # BAD: I/O in Core  # noqa: ERA001
+#     return parse_lines(content)  # noqa: ERA001
+
+# DO: Core receives content, not paths
+# def parse_content(content: str):  # GOOD: receives data
+#     return parse_lines(content)  # noqa: ERA001
+
+
+# DON'T: Missing Result in Shell
+# def load_config(path: Path) -> dict:  # BAD: no Result type
+#     return json.loads(path.read_text())  # Exceptions not handled  # noqa: ERA001
+
+# DO: Return Result[T, E]
+# def load_config(path: Path) -> Result[dict, str]:  # GOOD
+#     try:  # noqa: ERA001
+#         return Success(json.loads(path.read_text()))  # noqa: ERA001
+#     except Exception as e:  # noqa: ERA001
+#         return Failure(str(e))  # noqa: ERA001

invar/templates/pre-commit-config.yaml.template

@@ -0,0 +1,44 @@
+# Invar Pre-commit Hooks
+# Install: pre-commit install
+#
+# Default runs full verification (static + doctests + CrossHair + Hypothesis).
+# Incremental mode makes this fast: ~5s first commit, ~2s subsequent (cached).
+#
+# Smart Guard: Detects rule-affecting file changes and runs full guard when needed.
+# Structure Protection: Warns if INVAR.md is modified directly.
+
+repos:
+  - repo: local
+    hooks:
+      # Warn if INVAR.md is modified directly (use --no-verify if intentional)
+      - id: invar-md-protected
+        name: INVAR.md Protection
+        entry: bash -c 'if git diff --cached --name-only | grep -q "^INVAR.md$"; then echo "Warning - INVAR.md was modified directly. Use git commit --no-verify if intentional."; exit 1; fi'
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
+      # Invar Guard (full verification by default)
+      # Uses incremental mode: only verifies changed files, caches results
+      # Smart mode: runs full guard when rule files change, --changed otherwise
+      - id: invar-guard
+        name: Invar Guard
+        entry: bash -c '
+          RULE_FILES="rule_meta.py rules.py contracts.py purity.py pyproject.toml"
+          STAGED=$(git diff --cached --name-only)
+          FULL=false
+          for f in $RULE_FILES; do
+            if echo "$STAGED" | grep -q "$f"; then FULL=true; break; fi
+          done
+          if [ "$FULL" = true ]; then
+            echo "⚠️  Rule change detected - running FULL guard"
+            invar guard
+          else
+            invar guard --changed
+          fi
+        '
+        language: python
+        additional_dependencies: ['invar-tools']
+        pass_filenames: false
+        stages: [pre-commit]
+        types: [python]

invar/templates/proposal.md.template

@@ -0,0 +1,93 @@
+# Protocol Change Proposal
+
+> Copy this template to `YYYY-MM-DD-title.md` when proposing changes.
+
+---
+
+## Metadata
+
+- **Date:** YYYY-MM-DD
+- **Author:** [Agent/Human]
+- **Status:** Draft | Pending Approval | Approved | Rejected
+- **Layer:** L1 (Protocol) | L2 (Project)
+
+---
+
+## Trigger
+
+What problem or friction caused this proposal?
+
+```
+Describe the specific situation that revealed a gap in the protocol.
+Include concrete examples if possible.
+```
+
+---
+
+## Proposed Change
+
+What specific change is proposed?
+
+```
+Be precise. Show before/after if applicable.
+```
+
+---
+
+## Evidence
+
+What experience supports this change?
+
+```
+- What happened that demonstrates the need?
+- How many times did this issue occur?
+- What was the impact (time lost, bugs introduced, etc.)?
+```
+
+---
+
+## Impact Analysis
+
+What else needs to change if this is approved?
+
+- [ ] INVAR.md sections affected
+- [ ] CLAUDE.md updates needed
+- [ ] Template files to update
+- [ ] Code changes required
+- [ ] Other documentation
+
+---
+
+## Alternatives Considered
+
+What other approaches were considered and why were they rejected?
+
+```
+1. Alternative A: ...
+   Rejected because: ...
+
+2. Alternative B: ...
+   Rejected because: ...
+```
+
+---
+
+## Approval
+
+**For Layer 1 changes only:**
+
+- [ ] Human has reviewed this proposal
+- [ ] Human explicitly approves: _____________ (signature/date)
+
+---
+
+## Implementation Checklist
+
+After approval:
+
+- [ ] Update INVAR.md
+- [ ] Update version number
+- [ ] Sync templates
+- [ ] Update related documentation
+- [ ] Add to version history
+- [ ] Commit with clear message