invar-tools 1.0.0__py3-none-any.whl

invar_tools-1.0.0.dist-info/METADATA

@@ -0,0 +1,321 @@
+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

invar_tools-1.0.0.dist-info/RECORD

@@ -0,0 +1,64 @@
+invar/__init__.py,sha256=gvCf_VzCH3gMfq6dvsvncxicAEv7_FhgBoQTBdbqcFM,1256
+invar/contracts.py,sha256=xAqk901hd3ep7ItxCln7Q0fID3rm47OROgEugmFnRY4,4631
+invar/decorators.py,sha256=EaZUgt4JzlhSgRTeRmKIEb-KgU8L5Npn8-oJuMuygRU,2677
+invar/invariant.py,sha256=PJ4vBET0uSxZmjr7flgrfPACyefXTCw3EM6_aREcnys,1609
+invar/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+invar/resource.py,sha256=uX3V8R8_e5uFRO6ksOt_RN62g6nmf_wzpjyr9JXNhoc,2680
+invar/core/__init__.py,sha256=01TgQ2bqTFV4VFdksfqXYPa2WUqo-DpUWUkEcIUXFb4,218
+invar/core/contracts.py,sha256=9v2fD1EoNbWDTUHLXdv3WvYFwk0FQwAu1jTlptnq93w,16008
+invar/core/extraction.py,sha256=NEGtpmPLIg0O_EnXGEDQcTRXudwJneysYCM3rpy0a2g,6058
+invar/core/formatter.py,sha256=M4Y6BlZuxRNFkGzng6ysPcCsB5cKHpuSVEZlUJIs4OY,9542
+invar/core/hypothesis_strategies.py,sha256=eOQAUjm5JCjzdMhPSfFtNytols5iQKTh6O7i4PhaqLY,15139
+invar/core/inspect.py,sha256=5OX-c3BJ7GEiJWqIY77GYoP0Ox15cTcrmlNfjh9Hvfg,4380
+invar/core/lambda_helpers.py,sha256=c4kX5ATsAiNu9nMayLWWWOD68ft0iN0Z6Lkfj4JuuPo,6326
+invar/core/models.py,sha256=2pws44NN4eaihbTPy6k-P9oZfFQABf_PSwGvXH18TzE,8902
+invar/core/must_use.py,sha256=R8VsIIWqLXtVov1kf5RqiKfkvqI1o2Bn4rKKNo5KFSw,5376
+invar/core/parser.py,sha256=I_FE2Rum1NxdqIr_qajxc8lp0vaBYTWkn3EEP480iUE,8862
+invar/core/property_gen.py,sha256=VBxEyfJmAqqteNpP8DM_kmZd0F3bf5oiYXpIE-WNFQY,11866
+invar/core/purity.py,sha256=gqhS3ZvJFPSol17CEwYarK7XPEl9eL6sz2B_b-dzKIo,11582
+invar/core/purity_heuristics.py,sha256=dcdYqJJh-RLZHZR_G1j1gViH3Cqe37RfE3leaA2MU34,4748
+invar/core/references.py,sha256=iOIivmQ3Qcp38XiFpzaa7EZa01Ab75Q-G7KR2PRn-tI,6107
+invar/core/rule_meta.py,sha256=nhicVNhbw_Tw5dxd9SEQBZLuuBtiEEsFlm0zq3QInb0,6702
+invar/core/rules.py,sha256=7WY_NJF0PM-w1Adkm2EL9ysgZsbxeVcRlhwzg2E4PWc,17174
+invar/core/strategies.py,sha256=AhiEJl-5SxXKSmprpeT4OdCmEk7dS3Di7Eb90I7QENQ,8797
+invar/core/suggestions.py,sha256=H5_cupuWHu2nFiTVS91iFxW8U-E4i6cIWdD9ggoQLB8,11167
+invar/core/tautology.py,sha256=btrcFMQElLPr-BM5LZO0YzUqQwvkLUYLFtAhho4K9_s,5564
+invar/core/timeout_inference.py,sha256=NOLwNuadLAKvGTtAnd3qppZikVfKlo2ZPxHFVg4Vupk,3544
+invar/core/utils.py,sha256=xMynNQPRsjtslg0SEzabYJ05hutDCzDOR5v9nzLwiis,12986
+invar/mcp/__init__.py,sha256=n3S7QwMjSMqOMT8cI2jf9E0yZPjKmBOJyIYhq4WZ8TQ,226
+invar/mcp/__main__.py,sha256=ZcIT2U6xUyGOWucl4jq422BDE3lRLjqyxb9pFylRBdk,219
+invar/mcp/server.py,sha256=bfCqLpfQxYQAP2Z3Ig2be8ZJnSKTQXGVBSfzV-5NwWE,7645
+invar/shell/__init__.py,sha256=FFw1mNbh_97PeKPcHIqQpQ7mw-JoIvyLM1yOdxLw5uk,204
+invar/shell/cli.py,sha256=Amg08r_vVY4nKCjDzABrA_VSm_e19va7VV-reb2JlKE,12154
+invar/shell/config.py,sha256=yutQPCOw9YfN-m9v3IDV80m3RttJlXS70UDA1ceS_8M,7396
+invar/shell/fs.py,sha256=HQaZmOWkfWvqjkDTwt8kyxP9xvDMudG-4rFy9DWVc4s,3437
+invar/shell/git.py,sha256=DOQhG6pfyxmZRrMLuqf4oVGpOlVLlnX5EUfU354JHVA,2614
+invar/shell/guard_helpers.py,sha256=kZmfmc1e2pimzPcHfbJpWm_P3nhR8Cg1da8FxVNmHpw,10749
+invar/shell/guard_output.py,sha256=nE-yncGuMwUxbak_nd59bMGQBnDHi2O3fn23w9TJ-eY,8347
+invar/shell/init_cmd.py,sha256=EGZNngBH_04WXJYsBzJHB478sajnNHNluEqYMul1KNE,10165
+invar/shell/mcp_config.py,sha256=Gxpmw3UN-xLas_8qU0miIBrVRSOscCt7Wb5LobJO8tw,4427
+invar/shell/perception.py,sha256=HwH2MSQC8IkeWqFm4Bcm0iylaqX6H2ZbqG5xdIlQXO0,3700
+invar/shell/property_tests.py,sha256=NKDWH7iRC6Vpdl9kkzzxSkTKPa8mb8VBqot339zAmUc,6493
+invar/shell/prove.py,sha256=Eb-dhSrDN6b1Pv9F6nnpCz35kevXrPgdvMIPl0uvjHY,13978
+invar/shell/prove_cache.py,sha256=jbNdrvfLjvK7S0iqugErqeabb4YIbQuwIlcSRyCKbcg,4105
+invar/shell/prove_fallback.py,sha256=PmJqhV0aYLYZ5qW4nnOGZOKVgWjpCpsvZrCNvilcuJE,5719
+invar/shell/templates.py,sha256=PYlkjowvJonZljwXlYD-K2Q6i6Km4xMP60AlGRhyNFQ,13642
+invar/shell/test_cmd.py,sha256=I651IJN_bxnxXk2W47RQhUpT5F6UtgfS1YDoJ5-f9WY,4068
+invar/shell/testing.py,sha256=qQKaG6i2pdO8SlT7ymRD6B7vDkQ_sSLqN5oHrEaIGgE,8991
+invar/shell/update_cmd.py,sha256=dzuF_Fu4m32lvGYCLdHfQEQpZzGRL3hJSzwpqytMwmw,6190
+invar/templates/__init__.py,sha256=cb3ht8KPK5oBn5oG6HsTznujmo9WriJ_P--fVxJwycc,45
+invar/templates/aider.conf.yml.template,sha256=MKtBZT-Mz6YkoF46vlA85Nr8OuYQVlsAPzhaQp6Xhko,831
+invar/templates/cursorrules.template,sha256=J663VycDV0MsM04hDK9aIRejgVbA8OrRM-kn9rN3w4I,878
+invar/templates/examples/README.md,sha256=dkS5QI1mzDsQp23dJGCoTZzM_1SQg1vos37sZAS-Wsc,485
+invar/templates/examples/contracts.py,sha256=46KpdotDgaospIO1cy1B9AQ-G8Oqu3b8uYcFYRAG8_4,3062
+invar/templates/examples/core_shell.py,sha256=mA1luz4aeurYIb_Uy0Fte-0qb2n5dYqdSU70Ga9MneM,3678
+invar/templates/CLAUDE.md.template,sha256=WGPNMjV2C7Lp68snYWYFpXONSqGAPmmudobNb0KoNyI,1594
+invar/templates/INVAR.md,sha256=c1ezOVuGF8uhLGWjrdHtcPgWpgOuIzXQoPqGme916xU,4533
+invar/templates/context.md.template,sha256=D4mIAbj33io5_xe0uTcZh5JuSfpzXpv_t5h6k0B6UIA,1168
+invar/templates/pre-commit-config.yaml.template,sha256=2qWY3E8iDUqi85jE_X7y0atE88YOlL5IZ93wkjCgQGo,1737
+invar/templates/proposal.md.template,sha256=UP7SpQ7gk8jVlHGLQCSQ5c-kCj1DBQEz8M-vEStK77I,1573
+invar_tools-1.0.0.dist-info/METADATA,sha256=GiNpK5taOqOuIPRyPP5hDnmI0Zyw_DWDlg27CTx0iYg,8123
+invar_tools-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+invar_tools-1.0.0.dist-info/entry_points.txt,sha256=C7R-M4tvNd6UHDOcG98RQVS9plLyJ-c939z8qLLzTj8,46
+invar_tools-1.0.0.dist-info/licenses/LICENSE,sha256=c9ClTzwDoKiyVo3hGAtPa7F9QpMagpluUWAnbD5BP0w,1075
+invar_tools-1.0.0.dist-info/RECORD,,

invar_tools-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

invar_tools-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+invar = invar.shell.cli:app

invar_tools-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Invar Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.