💸 Debt Collector

A CLI tool to track and manage technical debt in your codebase by scanning for TODO and FIXME comments.

✨ Features

• 🔍 Fast scanning - Quickly scan entire projects for TODO and FIXME comments
• 🎯 Flexible filtering - Support for multiple file extensions and ignore patterns
• 📊 Multiple output formats - Terminal-friendly or JSON for CI/CD integration
• 🚨 CI/CD ready - Fail builds when technical debt is detected
• 🎨 Beautiful output - Color-coded results for better readability
• ⚡ High performance - Powered by fast-glob for efficient file scanning

📦 Installation

Global Installation (Recommended)

npm install -g debt-collector

Local Installation

npm install debt-collector --save-dev

🚀 Usage

Basic Usage

Scan a directory for technical debt:

debt debt ./src

Advanced Options

debt debt <directory> [options]

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --ext <extensions> | -e | File extensions to scan (comma-separated) | js,ts,jsx,tsx | | --ignore <patterns> | -i | Glob patterns to ignore (comma-separated) | | | --json | | Output results in JSON format | false | | --fail-on-debt | | Exit with non-zero code if debts found | false |

Examples

Scan TypeScript files only

debt debt ./src --ext ts,tsx

Ignore node_modules and test files

debt debt ./src --ignore "**/node_modules/**,**/*.test.js"

Generate JSON report

debt debt ./src --json

This creates a debt-report.json file with detailed results.

Fail CI/CD pipeline on debt

debt debt ./src --fail-on-debt

Scan Python files

debt debt ./src --ext py

Combine multiple options

debt debt ./src --ext js,ts,jsx,tsx --ignore "**/dist/**,**/build/**" --fail-on-debt

📋 Detected Patterns

The tool detects technical debt comments in the following formats:

• // TODO: description
• // FIXME: description
• /* TODO: description */
• # TODO: description (for Python, Ruby, etc.)

Pattern matching is case-insensitive.

📊 Output Format

Terminal Output

Debts found in file: src/components/Header.js
  12: // TODO: Add proper error handling
  45: // FIXME: Memory leak in event listener

Scan complete. Total files scanned: 24. Total debts found: 2.

JSON Output (--json)

{
  "totalFilesScanned": 24,
  "totalDebtsFound": 2,
  "debts": [
    {
      "file": "src/components/Header.js",
      "debts": [
        {
          "line": "// TODO: Add proper error handling",
          "lineNo": 12
        },
        {
          "line": "// FIXME: Memory leak in event listener",
          "lineNo": 45
        }
      ]
    }
  ]
}

🔧 Use Cases

1. Pre-commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash
debt debt ./src --fail-on-debt

2. CI/CD Pipeline

GitHub Actions:

- name: Check Technical Debt
  run: |
    npm install -g debt-collector
    debt debt ./src --fail-on-debt

GitLab CI:

debt-check:
  script:
    - npm install -g debt-collector
    - debt debt ./src --fail-on-debt

3. NPM Script

Add to package.json:

{
  "scripts": {
    "check-debt": "debt debt ./src",
    "check-debt:strict": "debt debt ./src --fail-on-debt"
  }
}

Then run:

npm run check-debt

4. Generate Reports

# Generate weekly debt report
debt debt ./src --json
mv debt-report.json reports/debt-$(date +%Y-%m-%d).json

🛠️ Development

Project Structure

debt-collector/
├── bin/
│   └── index.js        # CLI entry point
├── package.json
├── package-lock.json
└── README.md

Local Development

# Clone the repository
git clone <your-repo-url>
cd debt-collector

# Install dependencies
npm install

# Link for local testing
npm link

# Test the CLI
debt debt ./test-project

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

ISC License - see the LICENSE file for details.

🙏 Acknowledgments

Built with:

• Commander.js - CLI framework
• fast-glob - Fast file pattern matching
• Chalk - Terminal string styling

📧 Support

If you have any questions or run into issues, please open an issue on GitHub.

Happy debt hunting! 💸🔍