analysis

Debt Categories

Overview of the six technical debt categories that Technical Debt Radar detects, scores, and enforces on every pull request.

Debt Categories

Technical Debt Radar classifies every violation into one of six categories. Each category has its own detection strategy, severity model, and gate behavior -- determining whether a pull request is blocked, warned, or passed.

Category Summary

Category	Patterns	Detection	Severity Model	Blocking Behavior
Architecture	4 rules	Import graph + AST	Always critical	Blocks on any violation
Runtime Risk	11 patterns	Scope-aware AST	Handler-context dependent	Critical blocks merge
Performance	9 patterns	ORM-aware AST	Volume-aware scaling	XL/XXL blocks merge
Reliability	8 patterns	AST + framework detection	Policy-configurable	Critical blocks merge
Maintainability	7 patterns	AST + token hashing + coverage	Warning/info only	Warns only, never blocks
AI Cross-File	6 indirect rules	Reverse import graph BFS	Medium confidence	Warns only

How Scoring Works

Every violation carries a debtPoints value based on its category and severity. Points are summed into a total debt score per PR. The default scoring weights are:

scoring:
  architecture_violation: 5
  circular_dependency: 10
  runtime_risk_critical: 8
  runtime_risk_warning: 3
  performance_risk_critical: 8
  performance_risk_warning: 3
  reliability_critical: 5
  reliability_warning: 3
  complexity_point: 1
  missing_tests: 3
  coverage_drop_per_pct: 2
  ai_concern: 2

Fixing violations earns negative points (credits), rewarding teams that reduce debt:

  violation_fixed: -5
  runtime_risk_fixed: -8
  complexity_reduced: -1
  reliability_fixed: -3

Gate Actions

Each violation produces one of three gate actions:

block -- The PR cannot be merged. Used for architecture violations, critical runtime risks, and XL/XXL performance issues.
warn -- The PR can merge, but the violation appears in the PR comment with a warning badge.
none -- The violation is tracked internally but not surfaced in the PR comment. Used for info-level findings on small tables.

The final gate result is fail if any violation has gateAction: 'block', otherwise pass.

Analysis Pipeline

Detection runs in a three-phase pipeline to handle dependencies between analyzers:

Phase 1 -- runs all independent analyzers in parallel:

Import graph builder
Complexity calculator
Runtime risk detector
Performance pattern detector
Reliability detector
Duplication detector
Missing tests detector
Dead code detector
Coverage delta detector

Phase 2 -- depends on the import graph from Phase 1:

Boundary checker (layer + module violations)
Circular dependency detector (Tarjan's algorithm)

Phase 3 -- depends on Phase 1 + Phase 2:

Cross-file analyzer (reverse import graph BFS, optional AI enhancement)

The entire pipeline typically completes in under 30 seconds for PRs with up to 100 changed files.

Category Details

Architecture

Enforces structural boundaries defined in your radar.yml. Detects layer violations (e.g., domain importing from infrastructure), circular dependencies, cross-module bypasses, and forbidden framework usage in the wrong layer. Every architecture violation blocks merge.

Runtime Risk

Detects 11 patterns that block the Node.js event loop or cause unsafe operations inside request handlers. The detector is scope-aware -- it only flags patterns inside HTTP handlers (NestJS decorators, Express callbacks, Fastify, Koa, Hapi) and reports patterns outside handlers as cross-file candidates for Phase 3 analysis.

Performance

Detects 9 ORM anti-patterns across Prisma, TypeORM, Sequelize, Mongoose, Drizzle, Knex, and MikroORM. Severity scales with declared data volumes -- the same unbounded query on a 1K-row table is info-level, but on a 10M-row table it blocks merge.

Reliability

Detects 8 error-handling and resilience anti-patterns. Includes fire-and-forget promises, missing try/catch, HTTP calls without timeouts, retry loops without backoff, empty catch blocks, missing error logging, database transactions without timeouts, and missing null guards after nullable queries.

Maintainability

Tracks 7 code quality metrics that warn but never block. Includes cyclomatic complexity (threshold 10), large files/functions, token-based duplication detection, dead code and unused exports, missing test files, and coverage delta tracking.

AI Cross-File Analysis

Traces risky patterns through the import graph using reverse BFS. When a pattern like readFileSync exists in a utility function outside a handler, the cross-file analyzer walks the import graph backwards to find if any request handler calls it directly or indirectly. Optionally enhanced by Claude API for contextual risk assessment.