npm package: @glue-tools-ai/tech-debt-estimator
Description: Quantify technical debt in developer-hours. Analyzes code duplication, complexity hotspots, stale code, missing tests, and documentation gaps.
Author: Glue
Latest version: 1.0.0

[![npm version](https://badge.fury.io/js/%40glue-tools-ai%2Ftech-debt-estimator.svg)](https://badge.fury.io/js/%40glue-tools-ai%2Ftech-debt-estimator)
[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

# 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

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

Or use directly with npx:

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

## Quick Start

### Full Debt Scan

Analyze your entire project:

```bash
tech-debt scan ./src
```

### Find Hotspots

Identify the worst technical debt files:

```bash
tech-debt hotspots ./src --top 15
```

### Export Results

Save analysis to a file:

```bash
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:**
```bash
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:**
```bash
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:

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

### Markdown

Professional report format for sharing:

```markdown
# 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:

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

### CI/CD Pipeline

Use JSON output for automated threshold checks:

```bash
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](https://getglueapp.com) - The AI tool for developers

**Email**: hello@getglueapp.com
**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](https://github.com/glue-tools-ai/tech-debt-estimator/issues).

## Support

For questions or support, reach out to hello@getglueapp.com