🧠 Cognitive Guard

Gamify your code documentation. Block commits that hurt brains.

Cognitive Guard is a revolutionary CLI tool that analyzes the cognitive complexity of your code in real-time and enforces documentation where it matters most. Instead of nagging you about every missing docstring, it focuses on the code that's genuinely hard to understand.

🎯 The Problem

• Traditional linters check for missing docs everywhere (boring!)
• Complex code without documentation causes cognitive overload
• Developers skip documentation because it feels like busywork
• No feedback loop between code complexity and documentation requirements

✨ The Solution

Cognitive Guard:

• 🎮 Gamifies documentation with Brain Scores and achievements
• 🧮 Calculates cognitive complexity using AST traversal
• 🎯 Targets only complex code (Score > configurable threshold)
• 🚫 Blocks commits for undocumented complex functions
• 🖥️ Launches an interactive TUI to fix issues on the spot
• 📊 Tracks your documentation coverage over time

🚀 Quick Start

Installation

pip install cognitive-guard

Initialize in Your Project

cd your-project
cognitive-guard init

This installs the git pre-commit hook and creates a .cognitive-guard.yml config file.

Configuration

Edit .cognitive-guard.yml to customize:

# Complexity threshold (1-20, default: 10)
complexity_threshold: 10

# Target documentation coverage (0.0-1.0, default: 0.9)
target_coverage: 0.9

# Languages to analyze
languages:
  - python
  - javascript
  - typescript
  - java

# Patterns to ignore
ignore:
  - "**/test_*.py"
  - "**/*.test.js"
  - "**/migrations/**"

# Gamification settings
gamification:
  enabled: true
  show_achievements: true
  track_stats: true

💡 How It Works

1. Pre-Commit Hook: Cognitive Guard runs automatically before each commit
2. AST Analysis: Parses staged files and builds Abstract Syntax Trees
3. Brain Score Calculation: Computes cognitive complexity for each function
4. Documentation Check: Verifies complex functions (Score > threshold) have docs
5. Interactive TUI: If violations found, launches a beautiful terminal UI to fix them
6. Commit Decision: Allows commit only when documentation requirements are met

🎮 Brain Score Metrics

Cognitive complexity is calculated based on:

• Control Flow: if/else, switch, loops (+1 each)
• Nesting: Each level of nesting (+1)
• Boolean Operators: &&, ||, ?? in conditions (+1)
• Recursion: Recursive calls (+2)
• Exception Handling: try/catch blocks (+1)

Score Ranges

• 0-5: 🟢 Simple - No docs required
• 6-10: 🟡 Moderate - Docs recommended
• 11-15: 🟠 Complex - Docs required
• 16+: 🔴 Very Complex - Detailed docs required + consider refactoring

🖥️ CLI Commands

Check Staged Changes

cognitive-guard check

Analyzes staged changes and reports complexity scores.

Scan Entire Codebase

cognitive-guard scan

Full codebase analysis with coverage report.

Interactive TUI

cognitive-guard tui

Launch the interactive documentation assistant.

Stats & Achievements

cognitive-guard stats

View your documentation journey and achievements.

Update Hook

cognitive-guard update-hook

Update the git hook to the latest version.

🏆 Gamification Features

Achievements

• 📝 First Steps: Document your first complex function
• 🎯 Marksman: Achieve 90% documentation coverage
• 🧠 Mind Reader: Document 10 functions with Score > 15
• 🚀 Speed Demon: Document 5 functions in one session
• 💯 Perfectionist: Achieve 100% documentation coverage

Stats Tracking

• Total functions analyzed
• Documentation coverage %
• Average Brain Score
• Most complex function
• Documentation streak (consecutive days)

🛠️ Advanced Usage

Bypass Hook (Emergency)

git commit --no-verify

Custom Thresholds Per File

# cognitive-guard: threshold=15
def ultra_complex_function():
    """This function needs threshold 15 instead of default 10"""
    pass

CI/CD Integration

# .github/workflows/cognitive-guard.yml
name: Cognitive Guard

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install Cognitive Guard
        run: pip install cognitive-guard
      - name: Check Documentation
        run: cognitive-guard scan --fail-under 0.9

🧪 Development

Setup Development Environment

git clone https://github.com/yourusername/cognitive-guard.git
cd cognitive-guard
pip install -e ".[dev]"
pre-commit install

Run Tests

pytest

Code Quality

black cognitive_guard tests
ruff cognitive_guard tests
mypy cognitive_guard

📚 Architecture

cognitive_guard/
├── core/           # Core complexity calculation engine
├── parsers/        # Language-specific AST parsers
├── analyzers/      # Complexity analyzers per language
├── tui/            # Interactive terminal UI (Textual)
├── hooks/          # Git hook integration
└── utils/          # Shared utilities

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Inspired by cognitive complexity research
• Built with Textual for the TUI
• Uses Radon and Lizard for complexity analysis

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---

Remember: Complex code without documentation is like a puzzle missing the picture on the box. 🧩