Monitor Tech Debt

Readme.md

@s4l/tech-debt

A CLI tool to track and monitor technical debt reduction progress in monorepo projects by analyzing ESLint violations and sending metrics to Datadog.

Motivation

Technical debt is inevitable in software projects. While ESLint helps identify code quality issues, it doesn't provide visibility into the progress of fixing them over time. This tool bridges that gap by:

• Tracking progress: Monitor how many files still violate specific ESLint rules
• Measuring impact: Calculate the percentage of affected files (affectation rate)
• Visualizing trends: Send metrics to Datadog for time-series visualization
• Prioritizing work: Identify which rules need more attention based on affectation rates

By defining a baseline of affected files and tracking current violations, teams can measure their technical debt reduction efforts and celebrate progress.

How It Works

1. Run ESLint on your packages/apps and generate JSON reports
2. Create .tech-debt folders with rule definitions listing initially affected files
3. Run tech-debt metrics to calculate current affectation vs baseline
4. Metrics are sent to Datadog for monitoring and visualization

Expected Monorepo Structure

The tool expects a monorepo structure with apps/ and packages/ directories:

your-monorepo/
├── apps/
│   └── your-app/
│       ├── .tech-debt/
│       │   ├── rule-name-1.json
│       │   └── rule-name-2.json
│       └── eslint-report.json
├── packages/
│   ├── package-a/
│   │   ├── .tech-debt/
│   │   │   └── rule-name.json
│   │   └── eslint-report.json
│   └── package-b/
│       ├── .tech-debt/
│       │   └── rule-name.json
│       └── eslint-report.json
└── tools/
    └── tech-debt-monitor/

Requirements

Each package or app that you want to monitor must have:

1. eslint-report.json: ESLint output in JSON format at the package/app root
2. .tech-debt/: A directory containing rule definition files
3. Rule files: JSON files (one per rule) defining the baseline

.tech-debt File Format

Each .tech-debt folder should contain one or more JSON files (one per ESLint rule to track). Each file defines:

• RULE_ID: The ESLint rule identifier
• AFFECTED_FILES: Array of file paths that initially violated this rule (baseline)

Example

packages/stayforlong/.tech-debt/s4l-no-empty-method.json

{
  "RULE_ID": "s4l/no-static-empty-method",
  "AFFECTED_FILES": [
    "src/_kernel/Count.ts",
    "src/_kernel/Country.ts",
    "src/_kernel/Currency.ts",
    "src/_kernel/Date.ts",
    "src/_kernel/Description.ts",
    "src/_kernel/Money.ts",
    "src/_kernel/Nationality.ts",
    "src/_kernel/PageNumber.ts",
    "src/_kernel/Rating.ts",
    "src/_kernel/Slug.ts",
    "src/_kernel/Title.ts",
    "src/booking/domain/SupportInfo.ts",
    "src/location/domain/BoxShape.ts",
    "src/marketing/domain/Banner.ts",
    "src/property/domain/Facility.ts",
    "src/shared/domain/Language.ts",
    "src/shared/domain/Market.ts"
  ]
}

The tool will:

1. Count how many of these files currently violate the rule (from eslint-report.json)
2. Calculate affectation: (current violations / baseline files) * 100
3. Track progress as you fix violations

CLI Commands

Installation

From your monorepo root:

npx tech-debt [command] [options]

Commands

metrics

Calculate technical debt metrics and optionally send them to Datadog.

npx tech-debt metrics [options]

Options:

• -d, --dry - Calculate and print metrics without sending to Datadog
• -j, --json - Output metrics as JSON instead of formatted text
• -h, --help - Display help for command

Examples

Dry run with formatted output:

npx tech-debt metrics -d

Output:

🚀 Tech Debt Metrics Calculator

📊 Analyzing 1 project(s)...

============================================================
📦 PACKAGES › stayforlong
============================================================

🔍 Found 1 tech debt rule(s)

  📋 Rule: s4l/no-static-empty-method
     📁 Affected files: 32
     ⚠️  Current affected files: 31
     🔴 Affectation: 96.88%

============================================================
✅ Analysis complete!
============================================================

Dry run with JSON output:

npx tech-debt metrics -d -j

Output:

{
  "packages/stayforlong": {
    "s4l/no-static-empty-method": {
      "affectedFiles": 32,
      "currentAffectedFiles": 31,
      "affectation": "96.88"
    }
  }
}

Send metrics to Datadog:

# Set Datadog StatsD address (optional, defaults to localhost:8125)
export STATSD_ADDR="datadog-agent:8125"

# Run without --dry flag
npx tech-debt metrics

Metrics are sent to Datadog with:

• Metric name: s4l.pwa.tech_debt.affectation
• Value: Affectation percentage (0-100)
• Tags: categoryName (apps/packages), rule (ESLint rule ID)

Affectation Status Indicators

The tool uses emojis to indicate progress at a glance:

• 🟢 Green (< 25%): Great progress!
• 🟡 Yellow (< 50%): Good progress
• 🟠 Orange (< 75%): Some progress
• 🔴 Red (≥ 75%): Needs attention

Generating ESLint Reports

Before running the tool, generate ESLint JSON reports for each package/app:

# In your package/app directory
npx eslint . --format json --output-file eslint-report.json

Or add to your package scripts:

{
  "scripts": {
    "lint:report": "eslint . --format json --output-file eslint-report.json"
  }
}

Configuration

Environment Variables

• STATSD_ADDR: StatsD/Datadog agent address (default: localhost:8125)

Search Depth

The tool searches for .tech-debt folders up to 2 levels deep:

• apps/**/.tech-debt (e.g., apps/my-app/.tech-debt)
• packages/**/.tech-debt (e.g., packages/my-package/.tech-debt)

Workflow Example

1. Initial setup: Run ESLint and identify files violating a rule

cd packages/my-package
npx eslint . --format json --output-file eslint-report.json

2. Create baseline: Create a .tech-debt file with current violations

mkdir .tech-debt
cat > .tech-debt/no-console.json << EOF
{
  "RULE_ID": "no-console",
  "AFFECTED_FILES": [
    "src/utils/logger.ts",
    "src/services/api.ts",
    "src/components/Debug.tsx"
  ]
}
EOF

3. Track progress: As you fix violations, run metrics to see progress

# After fixing logger.ts
npx tech-debt metrics -d

# Output shows:
#   📁 Affected files: 3
#   ⚠️  Current affected files: 2
#   🟡 Affectation: 66.67%

4. Monitor over time: Send to Datadog and create dashboards

npx tech-debt metrics

Contributing

This tool is part of the S4L monorepo tooling suite.

Requirements

• Node.js: 22.17.0
• A monorepo with apps/ and/or packages/ directories
• ESLint configured with JSON output capability