# Repotoire 🎼
**The code analyzer that understands your architecture — not just your syntax.**
[](https://crates.io/crates/repotoire)
[](https://opensource.org/licenses/MIT)
[](https://www.rust-lang.org/)
## The Problem
Your linter catches syntax errors. Your tests catch bugs. But who catches the **architecture rot**?
- Why does every PR touch 15 files?
- Why is this "simple" change breaking production?
- Why is the codebase slower to work in every month?
**Traditional tools can't answer these questions** because they analyze files in isolation.
## The Solution
Repotoire builds a **knowledge graph** of your entire codebase and finds the structural problems that cause real pain:
```
┌─────────────────────────────────────────────────────────────────┐
│ 🔄 Circular Dependencies │ Why: Change A breaks B and C │
│ 🎯 God Classes │ Why: 47 things depend on this │
│ 💀 Dead Code │ Why: Nothing calls this │
│ 🔗 Coupling Hotspots │ Why: This file is a bottleneck│
│ 🔒 Security Vulnerabilities │ Why: User input → SQL query │
└─────────────────────────────────────────────────────────────────┘
```
## Quick Start
```bash
# Install (pick one)
cargo install repotoire
cargo binstall repotoire # Faster, no cmake needed
brew install zachhammad/tap/repotoire # macOS
# Run
cd your-project
repotoire analyze .
```
**That's it.** No config files. No API keys. No Docker. No cloud account.
## What You Get
```
🎼 Repotoire Analysis
──────────────────────────────────────
Score: 85.2/100 Grade: B Files: 342 Functions: 1,847
SCORES
Structure: 88 Quality: 82 Architecture: 86
FINDINGS (47 total)
🔴 2 critical 🟠 12 high 🟡 28 medium 🔵 5 low
# SEV DETECTOR FILE LINE
─────────────────────────────────────────────────────────────────────
1 [C] sql-injection src/api/users.rs 142
2 [C] hardcoded-secret src/config/keys.rs 23
3 [H] circular-dependency src/auth ↔ src/users -
4 [H] god-class src/services/OrderManager 89
...
```
## Why Switch From Your Current Linter?
| "This function is too long" | "This function is called by 47 other functions — changes here will cascade" |
| "Unused import" | "This entire module is dead code — nothing in your codebase calls it" |
| "Security warning on line 142" | "User input flows from `get_user()` → `validate()` → `query()` (taint traced)" |
| File-by-file rules | Whole-codebase graph analysis |
**Repotoire finds problems that exist *between* files, not *within* files.**
## 108 Detectors
### 🏗️ Architecture (Graph-Powered)
- **Circular dependencies** — Tarjan's algorithm finds cycles
- **Architectural bottlenecks** — Betweenness centrality finds fragile hubs
- **Module cohesion** — Detects modules that should be split
- **Shotgun surgery** — Changes that ripple across the codebase
### 🔒 Security (Taint Analysis)
- **SQL injection** — Traces user input to queries
- **Command injection** — `exec()` with untrusted data
- **Hardcoded secrets** — API keys, passwords, tokens
- **Unsafe deserialization** — Pickle, YAML, eval
### 🧠 AI Code Watchdog
- **AI complexity spikes** — Sudden cyclomatic complexity jumps
- **AI churn patterns** — Files modified 3+ times in 48h
- **AI boilerplate explosion** — Copy-paste patterns
- **torch.load()** — Pickle RCE in ML code
### 📊 Quality
- **God classes** — Too many responsibilities
- **Dead code** — Unreachable functions
- **Feature envy** — Methods using wrong class's data
- **Duplicate code** — AST-level similarity detection
## Performance
| React | 4,443 | 2m 5s | **0.9s** |
| Django | 3,000 | 55s | 0.8s |
| Your project | 500 | ~8s | ~0.5s |
Warm runs use **smart caching** — only re-analyzes changed files.
### Need Faster Cold Runs?
```bash
repotoire analyze . --fast # Skip expensive graph detectors
repotoire analyze . --relaxed # Only HIGH+ findings
```
## Supported Languages
Full parsing for: **Rust, Python, TypeScript, JavaScript, Go, Java, C/C++, C#, Kotlin**
All use tree-sitter compiled to native Rust — no external dependencies.
## AI-Powered Fixes (Optional)
```bash
# Fix issue #1 with AI
repotoire fix 1
# Uses your API key (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
# Or use Ollama for free local AI:
ollama pull deepseek-coder:6.7b
repotoire fix 1 # Auto-detects Ollama
```
No API key? No Ollama? **All analysis still works.** AI is optional.
## CI/CD Integration
### GitHub Actions
```yaml
name: Code Health
on: [push, pull_request]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: zachhammad/repotoire-action@v1
with:
fail-on: high # Fail if any HIGH+ findings
```
### Pre-commit
```yaml
repos:
- repo: local
hooks:
- id: repotoire
name: repotoire
entry: repotoire analyze . --fast --relaxed
language: system
pass_filenames: false
```
## Configuration
```toml
# repotoire.toml
[detectors.god-class]
thresholds = { method_count = 30 }
[detectors.magic-numbers]
enabled = false
[exclude]
paths = ["vendor/", "generated/"]
```
### Inline Suppression
```python
# repotoire: ignore
def legacy_function(): # This line won't trigger findings
pass
```
## How It Works
```
Source Files → Tree-sitter Parser → Kuzu Graph DB → 108 Detectors → Report
│ │
Native Rust Graph algorithms:
~400 files/sec • Tarjan's SCC
• Betweenness centrality
• Taint propagation
```
## Comparison
| **Graph analysis** | ✅ | Partial | ❌ | ❌ |
| **Circular deps** | ✅ | ✅ | ❌ | ❌ |
| **Taint tracking** | ✅ | ✅ | ✅ | ❌ |
| **Local-first** | ✅ | ❌ | ✅ | ✅ |
| **No Docker** | ✅ | ❌ | ✅ | ✅ |
| **AI fixes** | ✅ | ❌ | ❌ | ❌ |
| **Multi-language** | 9 | Many | Many | JS only |
| **Free** | ✅ | Limited | ✅ | ✅ |
| **Setup time** | 30 sec | Hours | Minutes | Minutes |
## Troubleshooting
**Stale database error?**
```bash
rm -rf .repotoire && repotoire analyze .
```
**cmake not found during install?**
```bash
cargo binstall repotoire # No cmake needed
```
## Documentation
- [Getting Started](docs/GETTING_STARTED.md)
- [All Detectors](docs/DETECTORS.md)
- [Configuration](docs/CONFIGURATION.md)
- [CI/CD Guide](docs/CI_CD.md)
## License
MIT
---
```bash
cargo install repotoire && repotoire analyze .
```