Tech Debt Estimator

Quantify technical debt in developer-hours. Analyzes code duplication, complexity hotspots, stale code, missing tests, and documentation gaps to produce an actionable debt inventory.

Features

• Complexity Debt Detection: Identifies large files (>500 LOC) and deeply nested code
• Duplication Analysis: Finds repeated code blocks across your codebase
• Test Coverage Gaps: Locates source files without corresponding tests
• Documentation Gaps: Detects missing JSDoc comments and inline documentation
• Stale Code Detection: Identifies files untouched for 12+ months via git history
• Dependency Health: Analyzes package.json and lock file freshness
• Multiple Output Formats: JSON, table, and Markdown reporting
• Developer-Hour Estimation: Converts debt into actionable time estimates

Installation

npm install -g @glue-tools-ai/tech-debt-estimator

Or use directly with npx:

npx @glue-tools-ai/tech-debt-estimator scan ./src

Quick Start

Full Debt Scan

Analyze your entire project:

tech-debt scan ./src

Find Hotspots

Identify the worst technical debt files:

tech-debt hotspots ./src --top 15

Export Results

Save analysis to a file:

tech-debt scan ./src --format json --output debt-report.json
tech-debt scan ./src --format markdown --output debt-report.md

Commands

tech-debt scan [path]

Performs a complete technical debt analysis across 6 debt categories.

Options:

• --format <type> - Output format: json, table, or markdown (default: table)
• --output <file> - Save output to a file

Example:

tech-debt scan ./src --format markdown --output report.md

tech-debt hotspots [path]

Identifies files with the highest accumulated technical debt.

Options:

• --top <number> - Number of hotspots to display (default: 10)
• --format <type> - Output format: json, table, or markdown (default: table)
• --output <file> - Save output to a file

Example:

tech-debt hotspots ./src --top 20 --format json

Debt Categories

Complexity Debt

Files larger than 500 lines or with nesting depth > 5. Estimated at 10 hours per file.

Duplication Debt

Repeated code blocks detected via hashing. Estimated at 3 hours per duplicate block.

Test Debt

Source files without corresponding test coverage. Estimated at 4 hours per file.

Documentation Debt

Functions, classes, and variables without JSDoc comments. Estimated at 0.5 hours per item.

Stale Code Debt

Files untouched for 12+ months. Estimated at 6 hours per file.

Dependency Debt

Outdated package.json or lock files. Base estimate 5 hours plus adjustments.

Output Formats

Table (Default)

Color-coded terminal output with severity indicators:

Technical Debt Analysis

Severity Summary
  Critical: 2 items
  High:     5 items
  Medium:   8 items
  Low:      1 item

  Total Debt Hours: 142.5 hrs

Complexity Debt - 80.0 hrs
Complex code structures requiring refactoring
Affected files: 8
  - src/app.js (1200 lines, nesting: 7)
  - src/api/handler.js (850 lines, nesting: 6)
...

JSON

Machine-readable format for integration with other tools:

{
  "scannedPath": "/path/to/project",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "totalDebtHours": 142.5,
  "categories": [...]
}

Markdown

Professional report format for sharing:

# Technical Debt Analysis Report

- **Scanned Path**: /path/to/project
- **Timestamp**: 2024-01-15T10:30:00.000Z
- **Total Debt Hours**: 142.5

## Severity Summary

- **Critical**: 2 items
- **High**: 5 items
...

Integration

With Git

For accurate stale code detection, ensure your project is a git repository:

git init
git add .
git commit -m "Initial commit"
tech-debt scan .

CI/CD Pipeline

Use JSON output for automated threshold checks:

DEBT=$(npx @glue-tools-ai/tech-debt-estimator scan ./src --format json | jq '.totalDebtHours')
if (( $(echo "$DEBT > 200" | bc -l) )); then
  echo "Warning: Technical debt exceeds 200 hours"
  exit 1
fi

Performance

• Scans typical projects (1000+ files) in 5-30 seconds
• Git history queries are optimized for performance
• Results are calculated locally - no external services required

Requirements

• Node.js >= 14.0.0
• Git (for stale code detection)

Dependencies

• commander: CLI argument parsing
• chalk: Terminal styling and colors
• simple-git: Git repository analysis
• ora: Spinner animations

Author

Made by Glue - The AI tool for developers

Email: [email protected] Website: https://getglueapp.com Repository: https://github.com/glue-tools-ai/tech-debt-estimator

License

MIT © 2026 Glue

Contributing

Found a bug or have a feature request? Open an issue on GitHub.

Support

For questions or support, reach out to [email protected]