tech-debt-score

Quantify technical debt you can actually control.
Built by developers, for developers.

tech-debt-score is an open-source CLI and engine that analyzes your codebase and produces a single, actionable Technical Debt Score, along with a breakdown of the factors that impact it.

The goal is not to find everything that could be wrong, but to measure what your team can realistically improve.

Why tech-debt-score?

Most tools focus on:

• Lint errors
• Code smells
• Best practices

But engineering teams need answers to questions like:

• How bad is our technical debt, really?
• Is it getting better or worse over time?
• Where should we focus first?

tech-debt-score provides:

• A normalized 0–100 score
• Clear ownership (team-controllable factors)
• CI-friendly output
• A foundation for long-term debt tracking
• Designed with developers in mind: fast, minimal friction, and easy to integrate

⚡ We made it by devs, for devs. Focus on your code, not the tooling.

What it measures (v1 scope)

The first version focuses only on signals fully controlled by the engineering team:

• Code complexity (cyclomatic, nesting)
• File and function size
• Code duplication
• Type safety indicators
• Project structure consistency, including circular dependencies

⚠️ External factors such as deprecated dependencies, security vulnerabilities, or runtime risks are intentionally out of scope for v1.

How it works (high level)

1. Scan the codebase
2. Collect raw metrics using AST parsing
3. Normalize metrics into signals
4. Apply weighted scoring
5. Generate:
   • Global score
   • Category breakdown
   • Human-readable report
   • Optional JSON output

Installation

Install as a dev dependency:

npm install --save-dev tech-debt-score

Usage

Analyze current directory

npx tech-debt-score

Analyze specific directory

npx tech-debt-score ./src

Output Options

Generate a JSON report for CI/CD integration:

npx tech-debt-score . --json report.json

Development

# Build the project
npm run build

# Run analysis on current project
npm run analyze

# Run self-scan verification
npm run scan

Publishing a new version

Before publishing, make sure the working tree is clean and that you are authenticated with npm:

npm login --auth-type=web --registry=https://registry.npmjs.org/
npm whoami

The web login supports passkeys and security keys. Then run the validation and release commands:

# Run the same checks used by CI
npm test
npm run build
npm run scan

# Bump the patch version, for example 0.1.15 → 0.1.16
npm version patch

# Preview the files that will be included
npm pack --dry-run

# Publish the package with the latest tag
npm publish

npm version patch updates package.json and package-lock.json, and creates a Git commit and tag. Push the commit and tag after publishing:

git push origin main --follow-tags

Never publish credentials, tokens, or security-key information in the repository. If a release fails, check the package version and authentication status before retrying; a published name/version combination cannot be reused.

Project Structure

This project follows Hexagonal Architecture (Ports & Adapters):

src/
├── domain/              # Pure business logic (no dependencies)
│   ├── entities/        # Core entities: Score, Metric, Rule, Finding
│   └── rules/           # Scoring rules: ComplexityRule, SizeRule, etc.
│
├── application/         # Use cases & orchestration
│   ├── services/        # AnalysisService
│   ├── ports/           # Interface definitions (IFileReader, IParser, IReporter)
│   └── config/          # Configuration
│
├── adapters/            # External integrations
│   ├── input/           # FileSystemReader, TypeScriptParser
│   └── output/          # TerminalReporter, JsonExporter
│
├── cli/                 # Command-line interface (entry point)
│   └── commands/        # CLI commands
│
└── shared/              # Shared types and utilities

Architecture Principles

• Clean Architecture: Domain layer has zero dependencies
• Dependency Inversion: Dependencies point inward
• Testability: Pure business logic, easy to unit test
• Extensibility: Easy to add new parsers, rules, or output formats

For detailed architecture information, see TECHNICAL_DESIGN.md

Development Status

Current Version: 0.1.15 (Beta)

✅ Completed

• [x] Hexagonal architecture setup
• [x] Domain layer (entities and rules)
• [x] Application layer (services and ports)
• [x] Full AST parsing implementation
• [x] File scanning with fast-glob
• [x] Code duplication detection
• [x] Circular dependency detection
• [x] CLI entry point with JSON export
• [x] Density-based scoring by analyzed file count

🚧 Roadmap to v1.0

v0.2 — Stabilization

• [x] Real test runner with initial domain, application, and integration coverage
• [x] Keep documentation and version metadata synchronized
• [x] Add continuous integration for build, tests, and self-scan
• [x] Document the package publishing workflow

v0.3 — Configuration and CI

• [ ] Configuration file support (.tech-debt-score.json)
• [ ] Custom ignore patterns
• [ ] Custom file patterns
• [ ] --fail-under threshold for CI pipelines
• [ ] Clearer CLI errors and exit codes

v0.4 — Analysis Quality

• [ ] Improve duplication detection beyond exact normalized matches
• [ ] Improve circular dependency resolution across extensions and index files
• [ ] Improve AST metric accuracy
• [ ] Add performance benchmarks

v1.0 — Stable Release

• [ ] Define and document a stable scoring contract
• [ ] Document the JSON report schema
• [ ] Establish a backward-compatibility policy
• [ ] Version the configuration format
• [ ] Validate the published npm package in a clean project

Future Ideas

• [ ] Git integration and historical trend tracking
• [ ] HTML and Markdown reports
• [ ] Additional language support
• [ ] VS Code extension

Contributing

Contributions are welcome! Please read our contributing guidelines (coming soon).

License

MIT © @panduken

Links

• GitHub: github.com/panduken/tech-debt-score
• Issues: Report a bug
• Technical Design: TECHNICAL_DESIGN.md