invar-tools 1.17.1__tar.gz

invar_tools-1.17.1/.aider.conf.yml

@@ -0,0 +1,27 @@
+# Invar Project Configuration for Aider
+# This is the Invar project itself
+
+# Auto-read protocol files at session start
+read:
+  - INVAR.md
+  - CLAUDE.md
+  - .invar/context.md
+
+# System prompt addition
+system-prompt: |
+  This is the Invar project itself. Follow INVAR.md and CLAUDE.md.
+
+  Before writing code, execute:
+  1. invar guard --changed
+  2. invar map --top 10
+
+  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/
+  - Do NOT run invar update on this project
+  - Task complete only when final invar guard passes.

invar_tools-1.17.1/.claude/commands/audit.md

@@ -0,0 +1,144 @@
+---
+_invar:
+  version: "5.0"
+  type: command
+---
+
+# Audit
+
+Read-only code review. Reports issues without fixing them.
+
+---
+
+## Behavior
+
+1. Analyze code for issues (style, bugs, security, architecture)
+2. Report findings with file:line references
+3. **Do NOT make any changes** - report only
+
+---
+
+## 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 Guard)
+
+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)
+- Escape hatch count → Guard (review_suggested)
+
+---
+
+## Report Format
+
+For each issue found, use severity levels:
+
+| Severity | Meaning |
+|----------|---------|
+| **CRITICAL** | Must fix before completion |
+| **MAJOR** | Fix or provide written justification |
+| **MINOR** | Optional, can defer |
+
+```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 (but don't implement)
+```
+
+---
+
+## Instructions
+
+1. Run `invar guard --changed` to see current state
+2. Go through each checklist category
+3. For each issue, determine severity (CRITICAL/MAJOR/MINOR)
+4. Report with structured format above
+5. Be thorough and adversarial
+
+**Remember:** You are READ-ONLY. Report issues, don't fix them.
+
+---
+
+Now review the recent changes or the files specified by the user.

invar_tools-1.17.1/.claude/commands/guard.md

@@ -0,0 +1,83 @@
+---
+_invar:
+  version: "5.0"
+  type: command
+---
+
+# Guard
+
+Run Invar verification on the project and report results.
+
+---
+
+## Behavior
+
+Execute `invar_guard()` and report:
+- Pass/fail status
+- Error count with details
+- Warning count with details
+
+**Do NOT fix issues** - just report verification results.
+
+---
+
+## When to Use
+
+- Quick verification check
+- Before committing changes
+- After pulling changes
+- To see current project health
+
+---
+
+## Execution
+
+Run verification:
+
+```
+invar_guard(changed=true)
+```
+
+Or for full project verification:
+
+```
+invar_guard()
+```
+
+---
+
+## Report Format
+
+```
+## Guard Results
+
+**Status:** PASS / FAIL
+**Errors:** N
+**Warnings:** N
+
+### Errors (if any)
+
+| Rule | File | Line | Message |
+|------|------|------|---------|
+| missing_contract | src/foo.py | 42 | Function 'bar' has no @pre/@post |
+
+### Warnings (if any)
+
+| Rule | File | Line | Message |
+|------|------|------|---------|
+| function_size | src/baz.py | 15 | Function exceeds 50 lines |
+```
+
+---
+
+## Next Steps
+
+After reporting results:
+- If PASS: No action needed
+- If FAIL: User decides whether to fix issues
+
+**Remember:** You are READ-ONLY. Report results, don't fix them.
+
+---
+
+Now run verification on the current project.

invar_tools-1.17.1/.claude/hooks/PostToolUse.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Invar hook wrapper (DX-57)
+# Ensure correct working directory regardless of where Claude Code invokes from
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+if ! cd "$PROJECT_ROOT" 2>/dev/null; then
+  echo "[invar] Warning: Could not cd to $PROJECT_ROOT" >&2
+  exit 0  # Don't block Claude Code
+fi
+source "$SCRIPT_DIR/invar.PostToolUse.sh" "$@"

invar_tools-1.17.1/.claude/hooks/PreToolUse.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Invar hook wrapper (DX-57)
+# Ensure correct working directory regardless of where Claude Code invokes from
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+if ! cd "$PROJECT_ROOT" 2>/dev/null; then
+  echo "[invar] Warning: Could not cd to $PROJECT_ROOT" >&2
+  exit 0  # Don't block Claude Code
+fi
+source "$SCRIPT_DIR/invar.PreToolUse.sh" "$@"

invar_tools-1.17.1/.claude/hooks/Stop.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Invar hook wrapper (DX-57)
+# Ensure correct working directory regardless of where Claude Code invokes from
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+if ! cd "$PROJECT_ROOT" 2>/dev/null; then
+  echo "[invar] Warning: Could not cd to $PROJECT_ROOT" >&2
+  exit 0  # Don't block Claude Code
+fi
+source "$SCRIPT_DIR/invar.Stop.sh" "$@"

invar_tools-1.17.1/.claude/hooks/UserPromptSubmit.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Invar hook wrapper (DX-57)
+# Ensure correct working directory regardless of where Claude Code invokes from
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+if ! cd "$PROJECT_ROOT" 2>/dev/null; then
+  echo "[invar] Warning: Could not cd to $PROJECT_ROOT" >&2
+  exit 0  # Don't block Claude Code
+fi
+source "$SCRIPT_DIR/invar.UserPromptSubmit.sh" "$@"

invar_tools-1.17.1/.claude/hooks/invar.PostToolUse.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Invar PostToolUse Hook
+# Protocol: v5.0 | Generated: 2025-12-30
+# DX-57: Git-based change detection with fallback
+
+TOOL_NAME="$1"
+
+# Check if hooks are disabled
+[[ -f ".claude/hooks/.invar_disabled" ]] && exit 0
+
+# Use session-specific state directory
+STATE_DIR="${CLAUDE_STATE_DIR:-/tmp/invar_hooks_$(id -u)}"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+CHANGES_FILE="$STATE_DIR/changes"
+LAST_GUARD="$STATE_DIR/last_guard"
+LAST_CHECK_MARKER="$STATE_DIR/last_check"
+
+# ============================================
+# Reset state on guard run (MCP or CLI)
+# ============================================
+# MCP: invar_guard tool call
+if [[ "$TOOL_NAME" == "mcp__invar__invar_guard" ]]; then
+  date +%s > "$LAST_GUARD"
+  rm -f "$CHANGES_FILE"
+  touch "$LAST_CHECK_MARKER"
+  exit 0
+fi
+
+# CLI: Bash command containing "invar guard"
+if [[ "$TOOL_NAME" == "Bash" ]]; then
+  TOOL_INPUT="$2"
+  if echo "$TOOL_INPUT" | grep -qE '"command"[^}]*invar\s+guard'; then
+    date +%s > "$LAST_GUARD"
+    rm -f "$CHANGES_FILE"
+    touch "$LAST_CHECK_MARKER"
+    exit 0
+  fi
+fi
+
+# ============================================
+# Detect changes (git with fallback)
+# ============================================
+is_git_repo() {
+  git rev-parse --git-dir >/dev/null 2>&1
+}
+
+detect_changes() {
+  if is_git_repo; then
+    # Primary: Git-based detection (includes staged + unstaged)
+    { git diff --name-only -- '*.py' 2>/dev/null; git diff --cached --name-only -- '*.py' 2>/dev/null; } | sort -u
+  elif [[ -f "$LAST_CHECK_MARKER" ]]; then
+    # Fallback: Timestamp-based detection (approximate)
+    find . -name "*.py" -newer "$LAST_CHECK_MARKER" -type f 2>/dev/null | \
+      grep -v __pycache__ | grep -v '.venv' | head -20
+  fi
+  # Update marker for next check
+  touch "$LAST_CHECK_MARKER" 2>/dev/null
+}
+
+# Track changes
+CHANGED=$(detect_changes)
+if [[ -n "$CHANGED" ]]; then
+  echo "$CHANGED" >> "$CHANGES_FILE"
+  sort -u "$CHANGES_FILE" -o "$CHANGES_FILE" 2>/dev/null
+fi
+
+# ============================================
+# Smart trigger evaluation
+# ============================================
+CHANGE_COUNT=$(wc -l < "$CHANGES_FILE" 2>/dev/null | tr -d ' ' || echo 0)
+LAST_TIME=$(cat "$LAST_GUARD" 2>/dev/null || echo 0)
+NOW=$(date +%s)
+ELAPSED=$((NOW - LAST_TIME))
+
+SHOULD_REMIND=false
+REASON=""
+
+# Trigger 1: Accumulated changes (3+ files)
+if [[ $CHANGE_COUNT -ge 3 ]]; then
+  SHOULD_REMIND=true
+  REASON="$CHANGE_COUNT files changed"
+fi
+
+# Trigger 2: Core file changed (high priority)
+if grep -qE "/core/|/contracts/" "$CHANGES_FILE" 2>/dev/null; then
+  SHOULD_REMIND=true
+  REASON="core/ files modified"
+fi
+
+# Trigger 3: Time threshold (>5 min with changes)
+if [[ $ELAPSED -gt 300 && $CHANGE_COUNT -gt 0 ]]; then
+  SHOULD_REMIND=true
+  REASON=">5 min since last guard"
+fi
+
+# Output reminder if triggered
+if [[ "$SHOULD_REMIND" == "true" ]]; then
+  echo ""
+  echo "⚠️ Verification suggested: $REASON"
+  echo "   Run: invar_guard --changed"
+fi

invar_tools-1.17.1/.claude/hooks/invar.PreToolUse.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# Invar PreToolUse Hook
+# Protocol: v5.0 | Generated: 2025-12-30
+# DX-57: Smart blocking with auto-escape for pytest/crosshair
+
+TOOL_NAME="$1"
+TOOL_INPUT="$2"
+
+# Check if hooks are disabled
+[[ -f ".claude/hooks/.invar_disabled" ]] && exit 0
+
+# Only process Bash commands
+[[ "$TOOL_NAME" != "Bash" ]] && exit 0
+
+# Parse command from JSON input
+# Primary: jq (accurate), Fallback: grep/sed (basic)
+if command -v jq &>/dev/null; then
+  CMD=$(echo "$TOOL_INPUT" | jq -r '.command // empty' 2>/dev/null)
+else
+  # Fallback: Extract command field using grep/sed (handles simple cases)
+  CMD=$(echo "$TOOL_INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"\(.*\)"/\1/')
+fi
+[[ -z "$CMD" ]] && exit 0
+
+# ============================================
+# pytest blocking with smart escape
+# ============================================
+if echo "$CMD" | grep -qE '\bpytest\b|python.*-m\s+pytest\b'; then
+
+  # Auto-escape 1: Debugging mode (--pdb, --debug, --tb=long)
+  if echo "$CMD" | grep -qE '\-\-pdb|\-\-debug|\-\-tb='; then
+    echo "⚠️ pytest debugging allowed. Run invar_guard after."
+    exit 0
+  fi
+
+  # Auto-escape 2: External/vendor tests
+  if echo "$CMD" | grep -qE 'vendor/|third_party/|external/|node_modules/'; then
+    exit 0
+  fi
+
+  # Auto-escape 3: Explicit coverage collection
+  if echo "$CMD" | grep -qE '\-\-cov'; then
+    echo "⚠️ pytest coverage allowed. Run invar_guard for contract verification."
+    exit 0
+  fi
+
+  # Auto-escape 4: Environment variable override
+  if [[ "$INVAR_ALLOW_PYTEST" == "1" ]]; then
+    exit 0
+  fi
+
+  # Default: Block with helpful message
+  echo "❌ Use invar_guard instead of pytest"
+  echo "   invar_guard = static + doctests + CrossHair + Hypothesis"
+  echo ""
+  echo "   Auto-allowed: pytest --pdb (debug), pytest --cov (coverage)"
+  echo "   Manual escape: INVAR_ALLOW_PYTEST=1 pytest ..."
+  exit 1
+fi
+
+# ============================================
+# crosshair blocking (always redirect)
+# ============================================
+if echo "$CMD" | grep -qE '\bcrosshair\b'; then
+  if [[ "$INVAR_ALLOW_CROSSHAIR" == "1" ]]; then
+    exit 0
+  fi
+
+  echo "❌ Use invar_guard (includes CrossHair by default)"
+  echo "   Manual escape: INVAR_ALLOW_CROSSHAIR=1 crosshair ..."
+  exit 1
+fi
+
+exit 0

invar_tools-1.17.1/.claude/hooks/invar.Stop.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Invar Stop Hook
+# Protocol: v5.0 | Generated: 2025-12-30
+# DX-57: Session cleanup and unverified changes warning
+
+# Use session-specific state
+STATE_DIR="${CLAUDE_STATE_DIR:-/tmp/invar_hooks_$(id -u)}"
+CHANGES_FILE="$STATE_DIR/changes"
+
+# Check for unverified changes
+if [[ -f "$CHANGES_FILE" ]]; then
+  CHANGE_COUNT=$(wc -l < "$CHANGES_FILE" 2>/dev/null | tr -d ' ' || echo 0)
+  if [[ $CHANGE_COUNT -gt 0 ]]; then
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "⚠️  Invar: $CHANGE_COUNT Python files not verified"
+    echo "   Run before commit: invar_guard --changed"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  fi
+fi
+
+# Cleanup session state
+rm -rf "$STATE_DIR" 2>/dev/null