CodeDebt 🚀

Ultra-fast code debt detection library and CLI tool written in Rust.

Features

• Blazingly Fast: Parallel file scanning with Rust performance
• Smart Patterns: Detects TODO, FIXME, HACK, XXX, and more
• Severity Levels: Critical, High, Medium, Low classification
• Multiple Formats: Pretty, JSON, CSV output
• Library + CLI: Use as library or standalone tool
• Git-aware: Respects .gitignore automatically
• Enhanced Intelligence: Git blame integration, duplicate detection, file type analysis
• Advanced Filtering: Filter by age, duplicates, severity, and file types

Installation

cargo install codedebt

Or build from source:

git clone https://github.com/haasonsaas/codedebt
cd codedebt
cargo build --release

CLI Usage

Basic Usage

# Scan current directory
codedebt

# Scan specific directory
codedebt /path/to/project

# Show only critical and high severity
codedebt --severity high

# Output as JSON
codedebt --format json

# Show summary only
codedebt --summary

# Custom file extensions
codedebt --extensions "rs,py,js"

# Ignore additional directories
codedebt --ignore "vendor,tmp"

Enhanced Intelligence Features

# Enable git blame integration (shows author, age, commit info)
codedebt --git-blame

# Detect duplicate patterns across files
codedebt --detect-duplicates

# Show file type distribution
codedebt --file-types

# Show age distribution of code debt
codedebt --git-blame --age-distribution

# Filter by maximum age (requires git blame)
codedebt --git-blame --max-age 30

# Show only duplicates with minimum count
codedebt --detect-duplicates --min-duplicates 3

# Combine multiple intelligence features
codedebt --git-blame --detect-duplicates --file-types --age-distribution

Getting Help

# Get help
codedebt --help

Library Usage

use codedebt::{CodeDebtScanner, Severity, Pattern};
use regex::Regex;

// Basic usage
let scanner = CodeDebtScanner::new();
let items = scanner.scan("./src")?;

// Enhanced intelligence features
let scanner = CodeDebtScanner::new()
    .with_git_blame(true)                    // Enable git blame integration
    .with_duplicate_detection(true)          // Enable duplicate detection
    .with_file_extensions(vec!["rs".to_string(), "py".to_string()]);

let all_items = scanner.scan(".")?;

// Use enhanced methods
let summary = scanner.get_summary(&all_items);
let file_types = scanner.get_file_type_summary(&all_items);
let age_distribution = scanner.get_age_distribution(&all_items);

// Apply filters
let recent_items = scanner.filter_by_age(&all_items, 30);  // Last 30 days
let duplicates = scanner.find_duplicates(&all_items, 2);   // 2+ occurrences

// Custom patterns
let custom_patterns = vec![
    Pattern {
        name: "URGENT".to_string(),
        regex: Regex::new(r"(?i)\bURGENT\b").unwrap(),
        severity: Severity::Critical,
    },
];

let scanner = CodeDebtScanner::new().with_patterns(custom_patterns);

Performance

• Lightning fast - scans large codebases in milliseconds
• Parallel processing of files using Rayon
• Memory efficient streaming with ignore crate
• Optimized regex compilation and matching

Example performance on codedebt project (57 items found in 3.6ms):

⚡ Scanned in 3.57ms

Patterns Detected

Example Output

Basic Output

🔍 18 code debt items found:

🚨 CRITICAL PRODUCTION_DEBT ./src/config.rs:42:15 placeholder="Production API Key"
⚠️  HIGH TEMPORARY ./src/auth.rs:123:8 // Temporary workaround for OAuth
📝 MEDIUM TODO ./src/utils.rs:67:4 // TODO: Add proper error handling
💡 LOW MOCK_STUB ./tests/setup.rs:12:8 Mock database connection

⚡ Scanned in 5.17ms

Enhanced Intelligence Output

🔍 12 code debt items found:

🚨 CRITICAL HACK ./src/auth.rs:45:8 // HACK: bypass validation for demo
    👤 john.doe@company.com • 📅 3 days ago • 🔄 2 duplicates

⚠️  HIGH FIXME ./src/utils.rs:123:4 // FIXME: memory leak in parser
    👤 jane.smith@company.com • 📅 2 weeks ago

📝 MEDIUM TODO ./src/config.rs:67:4 // TODO: add environment validation
    👤 bob.wilson@company.com • 📅 1 month ago • 🔄 5 duplicates

📊 File Type Distribution:
════════════════════════════════════════
rs                 8
js                 3
py                 1

📅 Age Distribution:
════════════════════════════════════════
This week           2
This month          7
Last 3 months       3

⚡ Scanned in 8.42ms

Enhanced Intelligence Features

Git Blame Integration

• Author tracking: See who created each piece of code debt
• Age analysis: Understand how old technical debt is
• Commit context: Link debt to specific commits for deeper investigation
• Age filtering: Focus on recent or old debt with --max-age

Duplicate Detection

• Pattern matching: Find repeated code debt across your codebase
• Count tracking: See how many times each pattern appears
• Duplicate filtering: Focus on the most common issues with --min-duplicates
• Team awareness: Identify systemic problems affecting multiple files

File Type Analysis

• Language breakdown: See which programming languages have the most debt
• Technology debt: Understand debt distribution across your tech stack
• Targeting improvements: Focus refactoring efforts on the most problematic file types

Age Distribution

• Time-based insights: Understand debt accumulation patterns over time
• Project timeline: See how debt relates to project milestones
• Priority guidance: Focus on recent debt that's easier to fix or old debt that's become critical

Supported Languages

Rust, Python, JavaScript, TypeScript, Go, Java, C/C++, Ruby, PHP, C#, Swift, Kotlin, Scala, and more.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development

# Clone the repository
git clone https://github.com/haasonsaas/codedebt
cd codedebt

# Build and test
cargo build
cargo test

# Run on a sample project
cargo run -- /path/to/test/project

License

MIT - see LICENSE file for details