invar-tools 1.0.0__tar.gz → 1.2.0__tar.gz

{invar_tools-1.0.0 → invar_tools-1.2.0}/.aider.conf.yml

@@ -15,13 +15,11 @@ system-prompt: |
   1. invar guard --changed
   2. invar map --top 10
 
-  Workflow (ICIDIV):
-  - Intent: What? Core or Shell?
-  - Contract: @pre/@post + doctests BEFORE code
-  - Inspect: invar sig <file>
-  - Design: Decompose first
-  - Implement: Pass your doctests
-  - Verify: invar guard
+  Workflow (USBV):
+  - Understand: Intent, Inspect (invar sig), Constraints
+  - Specify: @pre/@post + doctests, Design decomposition
+  - Build: Implement leaves first, Compose
+  - Validate: invar guard, Integrate, Reflect
 
   Project-specific:
   - INVAR.md here is the SOURCE, templates are in src/invar/templates/

invar_tools-1.2.0/.claude/commands/review.md

@@ -0,0 +1,200 @@
+# Code Review (Reviewer Role)
+
+## Mode Detection (Required First Step)
+
+Before reviewing, determine the appropriate mode:
+
+### Check for `review_suggested`
+
+Look at your conversation history for recent `invar guard` output, or run:
+```bash
+invar guard --changed
+```
+
+Check if `review_suggested` warning is present:
+```
+WARNING: review_suggested - High escape hatch count: N @invar:allow markers
+WARNING: review_suggested - Security-sensitive path detected
+WARNING: review_suggested - Low contract coverage
+```
+
+### Select Mode
+
+| Condition | Mode | Why |
+|-----------|------|-----|
+| `review_suggested` present | **Isolated** | Eliminates confirmation bias |
+| No trigger | **Quick** | Faster, context preserved |
+| User requests `--isolated` | **Isolated** | Explicit override |
+| User requests `--quick` | **Quick** | Explicit override |
+
+---
+
+## Isolated Mode
+
+**Use when:** `review_suggested` triggered, or user explicitly requests isolation.
+
+Spawn an independent reviewer with fresh context using Task tool:
+
+```
+I'll spawn an independent reviewer to eliminate confirmation bias...
+
+[Task tool call]
+prompt: |
+  You are an adversarial code reviewer. Your job is to FIND PROBLEMS.
+
+  Review these files: {files_to_review}
+
+  Read .claude/commands/review.md for the full checklist, then:
+  1. Check contract semantic value (not just syntax)
+  2. Audit all escape hatches (@invar:allow)
+  3. Look for logic errors and edge cases
+  4. Check security if applicable
+
+  Report issues as CRITICAL/MAJOR/MINOR with file:line locations.
+
+  Your success is measured by problems found, not code approved.
+
+subagent_type: "general-purpose"
+```
+
+After receiving the sub-agent's report, summarize findings for the user.
+
+**Key:** The sub-agent has NO conversation history. It only sees the code.
+
+---
+
+## Quick Mode
+
+**Use when:** No `review_suggested` trigger, routine review needed.
+
+Proceed with same-context review below.
+
+---
+
+## Adversarial Reviewer Persona
+
+You are an **adversarial code reviewer**. Your job is to FIND PROBLEMS.
+
+### Your Mindset
+
+Assume:
+- The code has bugs until proven otherwise
+- The contracts may be meaningless ceremony
+- The implementer may have rationalized poor decisions
+- Escape hatches may be abused
+
+You are NOT here to:
+- Validate that code works
+- Confirm the implementer did a good job
+- Be nice or diplomatic
+
+You ARE here to:
+- Find bugs, logic errors, edge cases
+- Challenge whether contracts have semantic value
+- Identify code smells and duplication
+- Question every escape hatch
+- Check if code matches contracts (not if code "seems right")
+
+**Your success is measured by problems found, not code approved.**
+
+---
+
+## Review Checklist
+
+> **Principle:** Only items requiring semantic judgment. Mechanical checks are excluded (see bottom).
+
+### A. Contract Semantic Value
+- [ ] Does @pre constrain inputs beyond type checking?
+  - Bad: `@pre(lambda x: isinstance(x, int))`
+  - Good: `@pre(lambda x: x > 0 and x < MAX_VALUE)`
+- [ ] Does @post verify meaningful output properties?
+  - Bad: `@post(lambda result: result is not None)`
+  - Good: `@post(lambda result: len(result) == len(input))`
+- [ ] Could someone implement correctly from contracts alone?
+- [ ] Are boundary conditions explicit in contracts?
+
+### B. Doctest Coverage
+- [ ] Do doctests cover normal cases?
+- [ ] Do doctests cover boundary cases?
+- [ ] Do doctests cover error cases?
+- [ ] Are doctests testing behavior, not just syntax?
+
+### C. Code Quality
+- [ ] Is duplicated code worth extracting?
+- [ ] Is naming consistent and clear?
+- [ ] Is complexity justified?
+
+### D. Escape Hatch Audit
+- [ ] Is each @invar:allow justification valid?
+- [ ] Could refactoring eliminate the need?
+- [ ] Is there a pattern suggesting systematic issues?
+
+### E. Logic Verification
+- [ ] Do contracts correctly capture intended behavior?
+- [ ] Are there paths that bypass contract checks?
+- [ ] Are there implicit assumptions not in contracts?
+- [ ] What happens with unexpected inputs?
+
+### F. Security
+- [ ] Are inputs validated against security threats (injection, XSS)?
+- [ ] No hardcoded secrets (API keys, passwords, tokens)?
+- [ ] Are authentication/authorization checks correct?
+- [ ] Is sensitive data properly protected?
+
+### G. Error Handling & Observability
+- [ ] Are exceptions caught at appropriate level?
+- [ ] Are error messages clear without leaking sensitive info?
+- [ ] Are critical operations logged for debugging?
+- [ ] Is there graceful degradation on failure?
+
+---
+
+## Excluded (Covered by Tools)
+
+These are checked by Guard or linters - don't duplicate:
+- Core/Shell separation → Guard (forbidden_import, impure_call)
+- Shell returns Result[T,E] → Guard (shell_result)
+- Missing contracts → Guard (missing_contract)
+- File/function size limits → Guard (file_size, function_size)
+- Entry point thickness → Guard (entry_point_too_thick)
+- Magic numbers → Linters (ruff)
+- Escape hatch count → Guard (review_suggested)
+
+---
+
+## Report Format
+
+For each issue found, use severity levels:
+
+| Severity | Meaning | Enforcement |
+|----------|---------|-------------|
+| **CRITICAL** | Must fix before completion | Blocking |
+| **MAJOR** | Fix or provide written justification | Strong |
+| **MINOR** | Optional, can defer | Advisory |
+
+```markdown
+### [CRITICAL/MAJOR/MINOR] Issue Title
+
+**Location:** file.py:line_number
+**Category:** contract_quality | logic_error | security | escape_hatch | code_smell
+**Problem:** What's wrong
+**Suggestion:** How to fix (if applicable)
+```
+
+---
+
+## Instructions Summary
+
+1. **Mode Detection:** Check for `review_suggested` in guard output
+2. **If Isolated Mode:** Spawn Task sub-agent (fresh context)
+3. **If Quick Mode:** Proceed with same-context adversarial review
+4. Go through each checklist category
+5. For each issue, determine severity (CRITICAL/MAJOR/MINOR)
+6. Report with structured format above
+7. Be thorough and adversarial
+
+**Remember:** You are READ-ONLY. Report issues, don't fix them directly.
+
+---
+
+Now review the recent changes or the files specified by the user.

{invar_tools-1.0.0 → invar_tools-1.2.0}/.cursorrules

@@ -17,7 +17,7 @@ Use MCP tools if available, otherwise use CLI commands.
 
 - Core (`src/invar/core/`): @pre/@post contracts, doctests, pure (no I/O)
 - Shell (`src/invar/shell/`): Result[T, E] return type
-- Workflow: Intent -> Contract -> Inspect -> Design -> Implement -> Verify
+- Workflow: Understand -> Specify -> Build -> Validate (USBV)
 - Task complete only when final invar_guard passes.
 
 ## Project-Specific

{invar_tools-1.0.0 → invar_tools-1.2.0}/.github/workflows/publish.yml

@@ -29,6 +29,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages-dir: runtime/dist/
+          skip-existing: true
         # Uses trusted publishing - configure at pypi.org/manage/project/invar-runtime/settings/publishing/
 
   publish-tools:
@@ -54,4 +55,34 @@ jobs:
 
       - name: Publish invar-tools to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
         # Uses trusted publishing - configure at pypi.org/manage/project/invar-tools/settings/publishing/
+
+  publish-deprecated:
+    name: Publish python-invar (deprecated)
+    runs-on: ubuntu-latest
+    needs: publish-tools  # Deprecated package depends on invar-tools
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build python-invar package
+        run: python -m build deprecated/python-invar/
+
+      - name: Publish python-invar to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: deprecated/python-invar/dist/
+          skip-existing: true
+        # Uses trusted publishing - configure at pypi.org/manage/project/python-invar/settings/publishing/

{invar_tools-1.0.0 → invar_tools-1.2.0}/.invar/context.md

@@ -1,13 +1,229 @@
 # Invar Project Context
 
-*Last updated: 2025-12-23*
+*Last updated: 2025-12-25*
+
+## Coverage Guarantee Matrix
+
+Smart Guard (`invar guard`) runs multiple verification layers. Here's what covers what:
+
+### Layer Coverage
+
+| Layer | Runs On | Catches | Limitations |
+|-------|---------|---------|-------------|
+| **Static Analysis** | All Python files | Architecture violations, missing contracts, file/function size | No runtime behavior |
+| **Doctests** | Functions with `>>>` examples | Logic errors, edge cases | Requires manual examples |
+| **CrossHair** | Functions with @pre/@post | Contract violations via symbolic execution | Skips C extensions (ast.parse, compile) |
+| **Hypothesis** | Functions with @pre/@post | Contract violations via random testing | Skips untestable types (Any, Pydantic, AST) |
+
+### Function Coverage Guarantee
+
+| Function Has | Static | Doctests | CrossHair | Hypothesis |
+|--------------|--------|----------|-----------|------------|
+| No contracts | ✅ | ❌ | ❌ | ❌ |
+| @pre/@post only | ✅ | ❌ | ✅ | ✅ |
+| Doctests only | ✅ | ✅ | ❌ | ❌ |
+| @pre/@post + doctests | ✅ | ✅ | ✅ | ✅ |
+| Uses ast.parse/compile | ✅ | ✅ | ⚠️ Skipped | ✅ |
+| Uses typing.Any | ✅ | ✅ | ✅ | ⚠️ Skipped |
+| Uses Pydantic models | ✅ | ✅ | ✅ | ⚠️ Skipped |
+
+**Key Insight:** Doctests are the universal fallback. Every function should have at least one doctest example.
+
+### deal.has Functions
+
+Functions decorated with `@has("import")` or similar are:
+- ✅ Tested by Hypothesis (deal.cases respects @pre conditions)
+- ⚠️ Skipped by CrossHair (correctly - C extensions unsupported)
+
+The `@has` decorator marks side effects for documentation, not verification bypass.
+
+### Verification Results (2025-12-24)
+
+```
+Functions tested: 151
+Functions passed: 151
+Functions failed: 0
+Total examples: 7000
+```
+
+All contracted functions pass property testing after switching to `deal.cases()`.
+
+---
+
+## Session 2025-12-25: DX-32 USBV Implementation & Review Gate Integration
+
+### DX-32: USBV Workflow Implementation
+
+Replaced ICIDIV with USBV (Understand → Specify → Build → Validate):
+- **Key insight:** Inspect before Contract. Depth varies naturally.
+- **Iteration:** VALIDATE failure returns to appropriate phase
+
+### Review Gate Integration (DX-31 Phase 2)
+
+Integrated independent reviewer subagent into USBV's VALIDATE phase:
+
+```
+VALIDATE Phase
+├─ invar guard              # Smart Guard
+├─ Review Gate (条件)       # If review_suggested triggered
+│  └─ /review               # Invoke independent reviewer
+└─ Reflect & Iterate
+```
+
+**Trigger conditions:**
+- Escape hatches >= 3 (`@invar:allow` markers)
+- Contract coverage < 50% in Core files
+- Security-sensitive paths detected
+
+**Documentation Updated:**
+- `docs/mechanisms/workflow/usbv.md` - Added Review Gate section
+- `INVAR.md` - Updated VALIDATE phase, added iteration path
+- `src/invar/templates/INVAR.md` - Synced changes
+- `.invar/examples/workflow.md` - Added Review Gate principle
+- `docs/AGENTS.md` - Added USBV Integration section
+
+### Lesson #28: Review Gate as Conditional Step
+
+**发现:** Review should be automatic trigger, not manual decision.
+**机制:** Guard detects conditions → suggests review → Agent invokes /review → addresses findings.
+**类别:** Integration at workflow phase boundary (VALIDATE) is more effective than separate tool.
+
+---
+
+## Session 2025-12-25: DX-31 Review Trigger
+
+### DX-31 Phase 1: Guard Trigger Rule
+
+Implemented `review_suggested` rule that triggers independent review suggestion when:
+- **Security-sensitive path**: Files containing auth, crypt, secret, password, token, etc.
+- **High escape hatch count**: >= 3 `@invar:allow` markers
+- **Low contract coverage**: < 50% of public functions have contracts
+
+**Files Created:**
+- `src/invar/core/review_trigger.py` (252 lines) - Central module for DX-30/31 triggers
+
+**Files Modified:**
+- `src/invar/core/entry_points.py` - Added `count_escape_hatches()` helper
+- `src/invar/core/rules.py` - Registered `check_review_suggested`
+- `src/invar/core/rule_meta.py` - Added `review_suggested` metadata
+
+**Refactoring:**
+- Moved `calculate_contract_ratio` and `check_contract_quality_ratio` from `contracts.py` to `review_trigger.py` to keep file sizes under 500 lines
+
+### DX-32 Proposal: Workflow Iteration
+
+Created `docs/proposals/DX-32-workflow-iteration.md` analyzing ICIDIV workflow order.
+
+**Key Insight:** Contract-before-Inspect is problematic for brownfield development. Proposed USBV (Understand → Specify → Build → Validate) as alternative with iteration loops.
+
+### Lesson #26: Contract Before Inspect Problem
+
+**发现:** ICIDIV的Contract-before-Inspect顺序在修改现有代码时造成摩擦 - 无法为未检查的代码写合约。
+**机制:** Brownfield需要先理解再规范；Greenfield可以先规范。
+**类别:** Workflow order should be context-sensitive (greenfield vs brownfield).
+
+### Lesson #27: Process Visibility vs Task Completion
+
+**发现:** 在实现DX-31时违反了DX-30 Visible Workflow原则 - 优先完成任务而非展示过程。
+**机制:** Agent倾向于"直接做完"而非"展示正在做什么"。需要显式检查点。
+**类别:** Agent-Native workflows need explicit visibility checkpoints, not just documentation.
+
+---
+
+## Session 2025-12-24: DX-22 AST Detection & Tech Debt Resolution
+
+### The Problem
+
+Full `invar guard` scan revealed 36 errors that previous `--changed` checks missed:
+- Content-based detection used string matching (`"@pre(" in source`)
+- This matched patterns in docstrings, causing false positives
+- Example: `>>> @pre(NonEmpty)` in a docstring was detected as a Core module
+
+### The Solution
+
+1. **AST-Based Detection** (`src/invar/shell/config.py`):
+   - Replaced string matching with AST parsing
+   - `_has_contract_decorators()` - walks AST to find real decorators
+   - `_has_io_imports()` - checks actual import nodes
+   - `_has_result_types()` - detects Result/Success/Failure usage
+   - Errors reduced: 36 → 14 (-61%)
+
+2. **Tech Debt Resolution** (14 → 0 errors):
+   - `invariant.py`: Added `@invar:allow` for false positive (`.get()` matched `router.get`)
+   - `mcp/server.py`: Added `@shell_orchestration` and `@invar:allow` for MCP framework API
+   - `pyproject.toml`: Added `templates` and `.invar/examples` to exclude paths
+
+3. **DX-29 Proposal Created**:
+   - Pure content detection with explicit `@invar:module` markers
+   - Pending review - may need splitting into separate proposals
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `src/invar/shell/config.py` | AST-based detection functions |
+| `src/invar/invariant.py` | False positive escape marker |
+| `runtime/src/invar_runtime/invariant.py` | Same |
+| `src/invar/mcp/server.py` | MCP framework escape markers |
+| `pyproject.toml` | Exclude templates from checking |
+| `docs/proposals/DX-29-pure-content-detection.md` | New proposal |
+| `docs/proposals/README.md` | Updated status for all proposals |
+
+### Lesson #26: String Matching vs AST
+
+**发现:** 字符串匹配检测代码特征会产生误报（docstring中的示例代码）。
+**机制:** AST解析只匹配真正的语法结构，不会被注释或字符串内容误导。
+**类别:** Detection logic should use AST for code patterns, string matching for comments/markers.
+
+---
+
+## Session 2025-12-24: DX-28 Skip Abuse Prevention
+
+### The Problem
+
+During DX-28 implementation, I batch-added `@skip_property_test` to 4 functions in `format_strategies.py` without proper justification. Only 1 (zero-parameter function) truly needed skip; the other 3 had `@pre` conditions that property testing could verify.
+
+**Root cause:** Convenience over discipline. Adding skip was easier than thinking about whether it was needed.
+
+### The Solution
+
+1. **Decorator enhanced** (`decorators.py`):
+   - `@skip_property_test` now requires a reason string
+   - Bare usage sets `"(no reason provided)"` enabling Guard detection
+
+2. **Guard rule added** (`contracts.py`):
+   - `check_skip_without_reason` detects bare/empty skip usage
+   - Uses regex with `^` anchor to avoid matching examples in docstrings
+
+3. **Rule metadata** (`rule_meta.py`):
+   - `skip_without_reason` rule registered with WARNING severity
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `runtime/src/invar_runtime/decorators.py` | Enhanced skip_property_test decorator |
+| `src/invar/core/contracts.py` | Added check_skip_without_reason rule |
+| `src/invar/core/rules.py` | Registered new rule |
+| `src/invar/core/rule_meta.py` | Added rule metadata |
+| `src/invar/core/format_strategies.py` | Removed 3 unnecessary skips |
+
+### Lesson #25: Skip Requires Justification
+
+**发现:** 批量添加`@skip_property_test`是"懒惰的快捷方式"。每个skip都应该有明确理由。
+**机制:** Guard检测缺失理由，强制开发者思考为什么跳过。
+**类别:** 有效的跳过理由包括: `no_params`, `strategy_factory`, `external_io`, `non_deterministic`。
+
+---
 
 ## Current State
 
-- **PyPI:** `invar-tools` + `invar-runtime` v1.0.0 (DX-21 package split)
-- **Protocol:** v3.26 (DX-19: 2 verification levels, DX-21: package split + Claude init)
+- **PyPI:** `invar-tools` + `invar-runtime` v1.0.2 (DX-21 package split + dual licensing)
+- **Protocol:** v4.0 (DX-32: USBV workflow, DX-31: review triggers)
 - **GitHub Pages:** https://tefx.github.io/Invar/
+- **Licenses:** Apache-2.0 (runtime) + GPL-3.0 (tools) + CC-BY-4.0 (docs)
 - **Status:** Feature complete, zero technical debt
+- **Recent:** DX-31 Phase 1 (review_suggested rule), DX-32 proposal (workflow iteration)
 - **Blockers:** None
 
 ## Documentation Structure (DX-11)
@@ -710,6 +926,8 @@ Human (Commander) ──directs──→ Agent (Executor) ──uses──→ In
 | 0.8.1 | 2025-12 | Fix --top limit for JSON output |
 | 0.8.2 | 2025-12 | Handle empty files gracefully |
 | 1.0.0 | 2025-12 | DX-21: Package split (invar-runtime + invar-tools), Claude init integration |
+| 1.0.1 | 2025-12 | Deprecated python-invar package with migration warning |
+| 1.0.2 | 2025-12 | Dual licensing: Apache-2.0 (runtime) + GPL-3.0 (tools) + CC-BY-4.0 (docs) |
 
 ## Tool Priority
 
@@ -726,7 +944,7 @@ Human (Commander) ──directs──→ Agent (Executor) ──uses──→ In
 
 | File | Purpose |
 |------|---------|
-| INVAR.md | Protocol v3.26 |
+| INVAR.md | Protocol v4.0 |
 | docs/INVAR-GUIDE.md | Why & How |
 | docs/VISION.md | Design philosophy |
 | CLAUDE.md | Development guide |
@@ -758,6 +976,10 @@ Human (Commander) ──directs──→ Agent (Executor) ──uses──→ In
 22. **Session Context > Async Feedback** - Problems caught during Agent session (pre-commit) beat CI feedback (context lost)
 23. **Example-Driven Learning** - Abstract rules don't teach; concrete code examples do. New agents learn fastest by seeing working code
 24. **deal Lambda Boolean Trap** - `and`/`or` in contracts may return strings; deal interprets non-bool as error messages. Always use `bool()`
+25. **Skip Requires Justification** - Batch-adding @skip_property_test is lazy shortcut. Each skip needs explicit reason. Guard enforces categories: no_params, strategy_factory, external_io, non_deterministic
+26. **Contract Before Inspect Problem** - ICIDIV's Contract-before-Inspect order causes friction in brownfield development. USBV (Understand → Specify → Build → Validate) with Inspect-before-Contract is more natural
+27. **Process Visibility vs Task Completion** - Agents tend to "just do it" rather than "show what they're doing". Need explicit visibility checkpoints
+28. **Review Gate as Conditional Step** - Review should be automatic trigger at workflow phase boundary (VALIDATE), not separate manual step
 
 ## Release Process
 

{invar_tools-1.0.0/src/invar/templates → invar_tools-1.2.0/.invar}/examples/contracts.py

@@ -5,7 +5,9 @@ Reference patterns for @pre/@post contracts and doctests.
 Managed by Invar - do not edit directly.
 """
 
-from deal import post, pre
+# Use invar_runtime for lightweight runtime contracts
+# (or 'from deal import pre, post' works too - deal is the underlying library)
+from invar_runtime import post, pre
 
 # =============================================================================
 # GOOD: Complete Contract

{invar_tools-1.0.0/src/invar/templates → invar_tools-1.2.0/.invar}/examples/core_shell.py

@@ -7,7 +7,9 @@ Managed by Invar - do not edit directly.
 
 from pathlib import Path
 
-from deal import post, pre
+# Use invar_runtime for lightweight runtime contracts
+# (or 'from deal import pre, post' works too - deal is the underlying library)
+from invar_runtime import post, pre
 from returns.result import Failure, Result, Success
 
 # =============================================================================