invar-tools 1.8.0__py3-none-any.whl → 1.11.0__py3-none-any.whl

invar/templates/protocol/python/contracts-syntax.md

@@ -0,0 +1,56 @@
+## Contract Syntax (Python)
+
+### Lambda Signature (Critical)
+
+```python
+# WRONG: Lambda only takes first parameter
+@pre(lambda x: x >= 0)
+def calculate(x: int, y: int = 0): ...
+
+# CORRECT: Lambda must include ALL parameters (even defaults)
+@pre(lambda x, y=0: x >= 0)
+def calculate(x: int, y: int = 0): ...
+```
+
+Guard's `param_mismatch` rule catches this as ERROR.
+
+### Meaningful Contracts
+
+```python
+# Redundant - type hints already check this
+@pre(lambda x: isinstance(x, int))
+def calc(x: int): ...
+
+# Meaningful - checks business logic
+@pre(lambda x: x > 0)
+def calc(x: int): ...
+
+# Meaningful - checks relationship between params
+@pre(lambda start, end: start < end)
+def process_range(start: int, end: int): ...
+```
+
+### @post Scope
+
+```python
+# WRONG: @post cannot access function parameters
+@post(lambda result: result > x)  # 'x' not available!
+def calc(x: int) -> int: ...
+
+# CORRECT: @post can only use 'result'
+@post(lambda result: result >= 0)
+def calc(x: int) -> int: ...
+```
+
+### Doctest Examples
+
+```python
+def calculate(x: int) -> int:
+    """
+    >>> calculate(5)
+    10
+    >>> calculate(0)      # Edge case
+    0
+    """
+    return x * 2
+```

invar/templates/protocol/python/markers.md

@@ -0,0 +1,44 @@
+## Markers (Python)
+
+### Entry Points
+
+Entry points are framework callbacks (`@app.route`, `@app.command`) at Shell boundary.
+- **Exempt** from `Result[T, E]` — must match framework signature
+- **Keep thin** (max 15 lines) — delegate to Shell functions that return Result
+
+Auto-detected by decorators. For custom callbacks:
+
+```python
+# @shell:entry
+def on_custom_event(data: dict) -> dict:
+    result = handle_event(data)
+    return result.unwrap_or({"error": "failed"})
+```
+
+### Shell Complexity
+
+When shell function complexity is justified:
+
+```python
+# @shell_complexity: Subprocess with error classification
+def run_external_tool(...): ...
+
+# @shell_orchestration: Multi-step pipeline coordination
+def process_batch(...): ...
+```
+
+### Architecture Escape Hatch
+
+When rule violation has valid architectural justification:
+
+```python
+# @invar:allow shell_result: Framework callback signature fixed
+def flask_handler(): ...
+```
+
+**Valid rule names for @invar:allow:**
+- `shell_result` — Shell function without Result return type
+- `entry_point_too_thick` — Entry point exceeds 15 lines
+- `forbidden_import` — I/O import in Core (rare, justify carefully)
+
+Run `invar rules` for complete rule catalog with hints.

invar/templates/protocol/python/tools.md

@@ -0,0 +1,24 @@
+## Commands (Python)
+
+```bash
+invar guard              # Full: static + doctests + CrossHair + Hypothesis
+invar guard --static     # Static only (quick debug, ~0.5s)
+invar guard --changed    # Modified files only
+invar guard --coverage   # Collect branch coverage
+invar guard -c           # Contract coverage only (DX-63)
+invar sig <file>         # Show contracts + signatures
+invar map --top 10       # Most-referenced symbols
+invar rules              # List all rules with detection/hints (JSON)
+```
+
+## Configuration (Python)
+
+```toml
+# pyproject.toml or invar.toml
+[tool.invar.guard]
+core_paths = ["src/myapp/core"]    # Default: ["src/core", "core"]
+shell_paths = ["src/myapp/shell"]  # Default: ["src/shell", "shell"]
+max_file_lines = 500               # Default: 500 (warning at 80%)
+max_function_lines = 50            # Default: 50
+# Doctest lines are excluded from size calculations
+```

invar/templates/protocol/python/troubleshooting.md

@@ -0,0 +1,38 @@
+## Troubleshooting (Python)
+
+### Size Limits (Agent Quick Reference)
+
+| Rule | Limit | Fix |
+|------|-------|-----|
+| `function_too_long` | **50 lines** | Extract helper: `_impl()` + main with docstring |
+| `file_too_long` | **500 lines** | Split by responsibility |
+| `entry_point_too_thick` | **15 lines** | Delegate to Shell functions |
+
+*Doctest lines excluded from counts. Limits configurable in `pyproject.toml`.*
+
+### Common Errors
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `param_mismatch` error | Lambda missing params | Include ALL params (even defaults) |
+| `shell_result` error | Shell func no Result | Add Result[T,E] or @invar:allow |
+| `is_failure()` not found | Wrong Result check | Use `isinstance(result, Failure)` |
+
+### Result Type Usage
+
+```python
+from returns.result import Result, Success, Failure
+
+# Creating results
+return Success(value)
+return Failure(error)
+
+# Checking results
+if isinstance(result, Failure):
+    handle_error(result.failure())
+else:
+    use_value(result.unwrap())
+
+# Chaining
+result.map(transform).bind(next_operation)
+```

invar/templates/protocol/typescript/architecture-examples.md

@@ -0,0 +1,52 @@
+## Core Example (TypeScript)
+
+```typescript
+import { z } from 'zod';
+
+// Contracts as Zod schemas
+const DiscountInput = z.object({
+  price: z.number().positive(),
+  discount: z.number().min(0).max(1),
+});
+
+const DiscountOutput = z.number().nonnegative();
+
+/**
+ * @example discountedPrice({ price: 100, discount: 0.2 }) // => 80
+ * @example discountedPrice({ price: 100, discount: 0 })   // => 100 (edge: no discount)
+ */
+export function discountedPrice(input: z.infer<typeof DiscountInput>): number {
+  const { price, discount } = DiscountInput.parse(input);
+  const result = price * (1 - discount);
+  return DiscountOutput.parse(result);
+}
+```
+
+**Self-test:** Can someone else write the exact same function from just Zod schemas + @example?
+
+**Forbidden in Core:** `fs`, `path`, `http`, `fetch`, `process.env`, `Date.now()`
+
+## Shell Example (TypeScript)
+
+```typescript
+import { Result, ok, err } from 'neverthrow';
+import { readFileSync } from 'fs';
+
+interface Config { [key: string]: unknown }
+
+export function readConfig(path: string): Result<Config, string> {
+  try {
+    const content = readFileSync(path, 'utf-8');
+    return ok(JSON.parse(content));
+  } catch (e) {
+    if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
+      return err(`File not found: ${path}`);
+    }
+    return err(`Invalid JSON: ${e}`);
+  }
+}
+```
+
+**Pattern:** Shell reads file → passes content to Core → returns Result.
+
+More examples: `.invar/examples/`

invar/templates/protocol/typescript/contracts-syntax.md

@@ -0,0 +1,73 @@
+## Contract Syntax (TypeScript)
+
+### Zod Schema Patterns
+
+```typescript
+import { z } from 'zod';
+
+// Input validation (precondition)
+const CalcInput = z.object({
+  x: z.number().int().nonnegative(),
+  y: z.number().int().default(0),
+});
+
+// Output validation (postcondition)
+const CalcOutput = z.number().int().nonnegative();
+
+function calculate(input: z.infer<typeof CalcInput>): number {
+  const { x, y } = CalcInput.parse(input);
+  const result = x + y;
+  return CalcOutput.parse(result);
+}
+```
+
+### Meaningful Contracts
+
+```typescript
+// Redundant - TypeScript already checks this
+const BadSchema = z.object({
+  x: z.number(),  // Just type checking
+});
+
+// Meaningful - checks business logic
+const GoodSchema = z.object({
+  x: z.number().positive(),  // Domain constraint
+});
+
+// Meaningful - checks relationship
+const RangeInput = z.object({
+  start: z.number(),
+  end: z.number(),
+}).refine(data => data.start < data.end, {
+  message: "start must be less than end",
+});
+```
+
+### Postcondition Scope
+
+```typescript
+// Output schema can only validate the result
+const OutputSchema = z.object({
+  total: z.number().nonnegative(),
+  items: z.array(z.string()).min(1),
+});
+
+// For input-dependent validation, use refinement in function
+function process(items: string[]): z.infer<typeof OutputSchema> {
+  const result = { total: items.length, items };
+  return OutputSchema.parse(result);
+}
+```
+
+### JSDoc Examples
+
+```typescript
+/**
+ * Calculate doubled value.
+ * @example calculate(5)  // => 10
+ * @example calculate(0)  // => 0 (edge case)
+ */
+function calculate(x: number): number {
+  return x * 2;
+}
+```

invar/templates/protocol/typescript/markers.md

@@ -0,0 +1,48 @@
+## Markers (TypeScript)
+
+### Entry Points
+
+Entry points are framework callbacks (Express routes, Next.js handlers) at Shell boundary.
+- **Exempt** from `Result<T, E>` — must match framework signature
+- **Keep thin** (max 15 lines) — delegate to Shell functions that return Result
+
+For custom callbacks:
+
+```typescript
+// @shell:entry
+export function onCustomEvent(data: Record<string, unknown>): Response {
+  const result = handleEvent(data);
+  if (result.isErr()) {
+    return new Response(JSON.stringify({ error: result.error }), { status: 500 });
+  }
+  return new Response(JSON.stringify(result.value));
+}
+```
+
+### Shell Complexity
+
+When shell function complexity is justified:
+
+```typescript
+// @shell_complexity: External process with error classification
+async function runExternalTool(...): Promise<Result<Output, Error>> { ... }
+
+// @shell_orchestration: Multi-step pipeline coordination
+async function processBatch(...): Promise<Result<BatchResult, Error>> { ... }
+```
+
+### Architecture Escape Hatch
+
+When rule violation has valid architectural justification:
+
+```typescript
+// @invar:allow shell_result: Express middleware signature fixed
+function expressMiddleware(req: Request, res: Response, next: NextFunction): void { ... }
+```
+
+**Valid rule names for @invar:allow:**
+- `shell_result` — Shell function without Result return type
+- `entry_point_too_thick` — Entry point exceeds 15 lines
+- `forbidden_import` — I/O import in Core (rare, justify carefully)
+
+Run `invar rules` for complete rule catalog with hints.

invar/templates/protocol/typescript/tools.md

@@ -0,0 +1,65 @@
+## Commands (TypeScript)
+
+```bash
+# Verification (Python CLI - works for TypeScript)
+invar guard                  # Full: tsc + eslint + vitest + ts-analyzer
+invar guard --json           # Agent-friendly v2.0 JSON output
+invar guard --changed        # Modified files only
+
+# Analysis
+invar sig <file>             # Show function signatures
+invar map --top 10           # Most-referenced symbols
+```
+
+## Guard Output (v2.0 JSON)
+
+```json
+{
+  "version": "2.0",
+  "language": "typescript",
+  "status": "passed",
+  "contracts": {
+    "coverage": {"total": 10, "withContracts": 7, "percent": 70},
+    "quality": {"strong": 3, "medium": 2, "weak": 1, "useless": 0},
+    "blind_spots": [
+      {"function": "deleteUser", "risk": "high", "suggested_schema": "z.object({...})"}
+    ]
+  }
+}
+```
+
+## Configuration (TypeScript)
+
+```json
+// package.json
+{
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/"
+  }
+}
+```
+
+```javascript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts', 'src/**/*.property.ts'],
+  },
+});
+```
+
+## Embedded Node Tools
+
+Invar includes bundled TypeScript analysis tools (no npm install required):
+
+| Tool | Purpose |
+|------|---------|
+| **ts-analyzer** | Contract coverage, blind spot detection |
+| **fc-runner** | Property-based testing with fast-check |
+| **quick-check** | Fast pre-commit verification (<1s) |
+
+These are called automatically by `invar guard` when analyzing TypeScript projects.

invar/templates/protocol/typescript/troubleshooting.md

@@ -0,0 +1,104 @@
+## Troubleshooting (TypeScript)
+
+### Guard Output Interpretation
+
+```json
+{
+  "status": "failed",
+  "contracts": {
+    "coverage": {"total": 10, "withContracts": 5, "percent": 50},
+    "blind_spots": [
+      {"function": "deleteUser", "risk": "high", "suggested_schema": "z.object({userId: z.string()})"}
+    ]
+  }
+}
+```
+
+| Field | Meaning | Action |
+|-------|---------|--------|
+| `status: failed` | Verification errors | Fix tsc/eslint/test errors first |
+| `coverage.percent < 70` | Low contract coverage | Add Zod schemas to uncovered functions |
+| `blind_spots` (high risk) | Critical functions without contracts | Priority: add schemas before next commit |
+| `blind_spots` (medium risk) | Functions that should have contracts | Add schemas when modifying |
+
+### Fixing Blind Spots
+
+```typescript
+// Before: blind spot (no validation)
+function deleteUser(userId: string): void {
+  db.delete(userId);
+}
+
+// After: contract added
+const DeleteUserInput = z.object({
+  userId: z.string().uuid(),
+});
+
+function deleteUser(input: z.infer<typeof DeleteUserInput>): void {
+  const { userId } = DeleteUserInput.parse(input);
+  db.delete(userId);
+}
+```
+
+### Size Limits (Agent Quick Reference)
+
+| Rule | Limit | Fix |
+|------|-------|-----|
+| `function_too_long` | **50 lines** | Extract helper: `_impl()` + main with JSDoc |
+| `file_too_long` | **500 lines** | Split by responsibility |
+| `entry_point_too_thick` | **15 lines** | Delegate to Shell functions |
+
+*JSDoc/comment lines excluded from counts.*
+
+### Common Errors
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `ZodError` at runtime | Schema mismatch | Check input against Zod schema |
+| `shell_result` error | Shell func no Result | Add Result<T,E> or @invar:allow |
+| `isErr()` not found | Wrong Result import | Use `neverthrow` Result type |
+
+### Result Type Usage
+
+```typescript
+import { Result, ok, err } from 'neverthrow';
+
+// Creating results
+return ok(value);
+return err(error);
+
+// Checking results
+if (result.isErr()) {
+  handleError(result.error);
+} else {
+  useValue(result.value);
+}
+
+// Chaining
+result
+  .map(transform)
+  .andThen(nextOperation);
+
+// Async operations
+import { ResultAsync } from 'neverthrow';
+
+const asyncResult = ResultAsync.fromPromise(
+  fetch(url),
+  (e) => new Error(`Fetch failed: ${e}`)
+);
+```
+
+### Zod Validation Patterns
+
+```typescript
+import { z } from 'zod';
+
+// Safe parse (returns Result-like object)
+const parsed = Schema.safeParse(data);
+if (!parsed.success) {
+  console.error(parsed.error.issues);
+}
+
+// Strict parse (throws on error)
+const validated = Schema.parse(data);
+```

invar/templates/protocol/universal/architecture.md

@@ -0,0 +1,36 @@
+## Core/Shell Architecture
+
+| Zone | Location | Requirements |
+|------|----------|--------------|
+| Core | `**/core/**` | Contracts + Examples, pure (no I/O) |
+| Shell | `**/shell/**` | Error-handling return type |
+
+### Decision Tree: Core vs Shell
+
+```
+Does this function...
+│
+├─ Read or write files? ──────────────────→ Shell
+├─ Make network requests? ─────────────────→ Shell
+├─ Access current time? ──────────────────→ Shell OR inject as parameter
+├─ Generate random values? ────────────────→ Shell OR inject as parameter
+├─ Print to console? ──────────────────────→ Shell (return data, Shell logs)
+├─ Access environment variables? ──────────→ Shell
+│
+└─ None of the above? ─────────────────────→ Core
+```
+
+### Injection Pattern (Universal)
+
+Instead of accessing impure values directly, inject them as parameters:
+
+```
+# Core: receives 'current_time' as parameter (pure)
+FUNCTION is_expired(expiry, current_time):
+    RETURN current_time > expiry
+
+# Shell: calls with actual time
+expired = is_expired(token.expiry, get_current_time())
+```
+
+This keeps Core functions pure and testable.

invar/templates/protocol/universal/completion.md

@@ -0,0 +1,14 @@
+## Task Completion
+
+A task is complete only when ALL conditions are met:
+- Check-In displayed: `✓ Check-In: [project] | [branch] | [clean/dirty]`
+- Intent explicitly stated
+- Contract written before implementation
+- Final displayed: `✓ Final: verification PASS | <errors>, <warnings>`
+- User requirement satisfied
+
+**Missing any = Task incomplete.**
+
+---
+
+*Protocol v5.0 — USBV workflow | [Examples](.invar/examples/)*

invar/templates/protocol/universal/contracts-concept.md

@@ -0,0 +1,37 @@
+## Contract Concepts
+
+### Precondition
+Constraints on inputs that must be true before function executes.
+
+```
+PRECONDITION: input_value > 0 AND input_value < 100
+```
+
+### Postcondition
+Guarantees about outputs that must be true after function executes.
+
+```
+POSTCONDITION: result >= 0
+```
+
+### Self-Test Rule
+
+> "Can someone else write the exact same function from just the contracts + examples?"
+
+If yes → Contracts are complete.
+If no → Add more constraints or examples.
+
+### Meaningful Contracts
+
+Contracts should check **business logic**, not just types:
+
+```
+# Redundant - type system already checks this
+PRECONDITION: x is integer
+
+# Meaningful - checks business logic
+PRECONDITION: x > 0
+
+# Meaningful - checks relationship between params
+PRECONDITION: start < end
+```

invar/templates/protocol/universal/header.md

@@ -0,0 +1,17 @@
+<!--
+  ┌─────────────────────────────────────────────────────────────┐
+  │ 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.   │
+  └─────────────────────────────────────────────────────────────┘
+
+  License: CC-BY-4.0 (Creative Commons Attribution 4.0 International)
+  https://creativecommons.org/licenses/by/4.0/
+
+  You are free to share and adapt this document, provided you give
+  appropriate credit to the Invar project.
+-->
+# The Invar Protocol v5.0
+
+> **"Trade structure for safety."**

invar/templates/protocol/universal/session.md

@@ -0,0 +1,17 @@
+## Check-In (Required)
+
+Your first message MUST display:
+
+```
+✓ Check-In: [project] | [branch] | [clean/dirty]
+```
+
+Actions:
+1. Read `.invar/context.md` (Key Rules + Current State + Lessons Learned)
+2. Show one-line status
+
+**Do NOT execute verification at Check-In.**
+Verification is for VALIDATE phase and Final only.
+
+This is your sign-in. The user sees it immediately.
+No visible check-in = Session not started.

invar/templates/protocol/universal/six-laws.md

@@ -0,0 +1,10 @@
+## Six Laws
+
+| Law | Principle |
+|-----|-----------|
+| 1. Separation | Core (pure logic) / Shell (I/O) physically separate |
+| 2. Contract Complete | Preconditions + Postconditions + Examples uniquely determine implementation |
+| 3. Context Economy | Overview → Signatures → 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 |

invar/templates/protocol/universal/usbv.md

@@ -0,0 +1,14 @@
+## USBV Workflow
+
+**U**nderstand → **S**pecify → **B**uild → **V**alidate
+
+| Phase | Purpose | Activities |
+|-------|---------|------------|
+| UNDERSTAND | Know what and why | Intent, Inspect existing code, Constraints |
+| SPECIFY | Define boundaries | Preconditions, Postconditions, Examples |
+| BUILD | Write code | Implement leaves, Compose |
+| VALIDATE | Confirm correctness | Run verification, Review if needed |
+
+**Key:** Inspect before Contract. Contracts before Code. Depth varies naturally.
+
+**Review Gate:** When verification triggers `review_suggested` (escape hatches ≥3, security paths, low coverage), invoke `/review` before completion.

invar/templates/protocol/universal/visible-workflow.md

@@ -0,0 +1,25 @@
+## Visible Workflow
+
+For complex tasks (3+ functions), show 3 checkpoints in TodoList:
+
+```
+□ [UNDERSTAND] Task description, codebase context, constraints
+□ [SPECIFY] Contracts and design decomposition
+□ [VALIDATE] Verification results, Review Gate if triggered, integration status
+```
+
+**BUILD is internal work** — not shown in TodoList.
+
+**Show contracts before code.** Example:
+
+```
+[SPECIFY] calculate_discount:
+PRECONDITION: price > 0 AND 0 <= rate <= 1
+POSTCONDITION: result >= 0
+FUNCTION calculate_discount(price, rate): ...
+
+[BUILD] Now coding...
+```
+
+**When to use:** New features (3+ functions), architectural changes, Core modifications.
+**Skip for:** Single-line fixes, documentation, trivial refactoring.