blast-shield

💻 Blast Shield CLI

With Report Analysis

# Generate a detailed technical debt report
blast-shield --generate-report

When using --generate-report, Blast Shield will:

• Generate a detailed report of technical debt metrics
• Compare the debt score against your configured threshold
• Apply debt penalties based on your configuration
• Save the report for historical tracking

This is useful for projects that want to maintain consistent code quality standards and track technical debt over time.

Technical debt protection for your entire codebase. Track, measure, and manage your code's health across any language.

What is Blast Shield?

Blast Shield is a command-line tool that helps you protect your codebase from accumulating technical debt, regardless of programming language. It scans your code for special comments (TODO, FIXME, HACK, etc.) that indicate potential technical debt and generates reports to help you track and manage this debt over time.

Key Features

• 🔍 Debt Detection: Identifies technical debt markers in code comments across your entire codebase
• 📊 File-Based Analysis: Tracks debt at the file level for better granularity and actionable insights
• 📈 Debt-Free Metrics: Calculates both file-level and codebase-wide debt-free percentages
• 🚦 Threshold Enforcement: Enforces customizable debt thresholds per file and overall
• ⚙️ Multiple Profiles: Choose from different profiles based on your project requirements
• 🔧 Configurable Weights: Customize the impact of different debt types on your score

Installation

# Install globally
npm install -g blast-shield

# Or use with npx
npx blast-shield

Quick Start

# Initialize with a configuration file
blast-shield init

# Analyze your codebase
blast-shield

How It Works

Blast Shield scans your files for comments indicating technical debt:

• // TODO: - Something that needs to be done
• // FIXME: - Something that needs fixing
• // HACK: - A workaround or non-ideal solution
• // OPTIMIZE: - Something that needs performance improvement
• // REFACTOR: - Code that should be restructured
• // BUG: - A known bug that needs addressing
• // NOTE: - Informational comments

Each marker has a configurable weight, and Blast Shield calculates a total debt score for your codebase.

Usage

Basic Command

# Analyze current project with default settings
blast-shield

With Custom Config

# Use a specific config file
blast-shield --config ./my-debt-config.json

Different Source Path

# Analyze only specific files
blast-shield --src "libs/**/*.ts"

With Report Analysis

# Include report metrics in the analysis
blast-shield --generate-report

When using --generate-report, Blast Shield will:

• Generate a detailed report including report metrics
• Compare the report score against your configured minReportScore
• Apply debt penalties to your debt score if below the minimum
• Save the report for historical tracking

Report Structure

When using --generate-report, Blast Shield generates a comprehensive debt analysis:

File-Level Metrics

• Total files scanned
• Number of clean files (no debt)
• Number of files with debt
• Debt-free percentage
• Per-file debt counts and density

Code-Level Metrics

• Total lines of code
• Debt-free lines
• Lines containing debt
• Overall debt score
• Debt distribution by type (TODO, FIXME, etc.)

Historical Tracking

• Change in debt-free percentage over time
• Trend analysis for debt accumulation
• Files with increasing debt density

Example Output

$ blast-shield --generate-report
Loading config from blast-shield.config.json
[blast-shield] › ℹ  info      🎯 Technical Debt Detector - Starting our code checkup...
[blast-shield] › ℹ  info      🎯 Scanning 51 files for technical debt...
[blast-shield] › ℹ  info      Source files have changed, regenerating debt report...
[blast-shield] › ℹ  info      🎯 Analyzing technical debt...
[blast-shield] › ℹ  info      Generated debt report: 98% debt-free code
[blast-shield] › ℹ  info      📈 Debt summary saved to .blast-shield/debt-summary.json

   ╭─────────────── ✨ CODE CHECKUP REPORT ✨ ────────────────╮
   │                                                          │
   │   🎯 Important Quests                                    │
   │   ✅ Bugs to Fix (Bugs): 0                               │
   │   ✅ Quick Fixes (FIXME): 0                              │
   │                                                          │
   │   ✨ Code Powers                                         │
   │   ✅ Speed Boosts (OPTIMIZE): 0                          │
   │   ✅ Clean Up (REFACTOR): 0                              │
   │                                                          │
   │   📋 Future Plans                                        │
   │   ✅ Future Tasks (TODO): 0                              │
   │   ✅ Special Tasks (HACK): 0                             │
   │   📌 Notes (NOTE): 1 (reminders for later)               │
   │                                                          │
   │   🦸‍♂️ CODE HEALTH SCORE                                   │
   │   ██████████████████████████████ 100% (Super Amazing!)   │
   │   🎯 GOAL:: 80% (to get a power-up!)                     │
   │   📈 CLEAN FILES:: 98% (Great!)                          │
   │                                                          │
   ╰──────────────────────────────────────────────────────────╯

[blast-shield] › ℹ  info      🎯 CONCLUSION: Wow! Your code is super-powered and ready to go!

Commands

blast-shield init

Creates a new configuration file with your preferred settings. You will be prompted to enter the source file glob pattern (src) for your project. There is no default value for src, as it can vary depending on your project structure (e.g., monorepo or single repo).

blast-shield init [options]

Options:

• -o, --output <path> - Specify the output path for the config file (default: "blast-shield.config.json")

During initialization, you will be prompted for:

• The source file glob pattern (e.g., src/**/*.{js,ts} or packages/*/src/**/*.{js,ts})
• The debt profile (defensive, balanced, aggressive, extreme)

If you leave the src pattern blank, you will need to manually update your config file later.

blast-shield (default)

Analyzes your codebase for technical debt indicators.

blast-shield [options]

Options:

• -c, --config <path> - Path to config file (default: "blast-shield.config.json")
• -s, --src <pattern> - Source file glob pattern (e.g., "src/**/*.ts")
• -g, --generate-report - Generate a detailed report of technical debt metrics
• -h, --save-history - Save debt history over time
• -p, --profile <name> - Use a specific debt profile (defensive, balanced, aggressive, extreme)

Configuration

Create a blast-shield.config.json file in your project root. The src field is required and should match your project structure:

{
  "src": "src/**/*.{ts,tsx}",
  "profile": "balanced",
  "generateReport": true,
  "threshold": 20,
  "minReportScore": 80,
  "weights": {
    "todo": 1,
    "fixme": 2,
    "hack": 2,
    "optimize": 1,
    "refactor": 1,
    "bug": 3,
    "note": 0,
    "debtPenaltyPerPoint": 0.5
  }
}

For monorepos, you might use a pattern like "packages/*/src/**/*.{js,ts}" for the src field.

Debt Types

Blast Shield identifies the following debt indicators in code comments:

Type	Description	Default Weight
TODO	Task to be completed later	1
FIXME	Code that needs fixing	2
HACK	Workaround that should be improved	2
OPTIMIZE	Code that needs performance improvements	1
REFACTOR	Code that needs restructuring	1
BUG	Known bugs that need fixing	3
NOTE	Just an informational note (not counted in debt score)	0

Debt Profiles

Blast Shield supports different debt profiles to match your project's needs and quality standards:

Profile	Description	Best For
defensive	Lenient settings for new projects	New projects, early development, prototypes
balanced	Standard settings for most projects	General purpose, well-established projects
aggressive	Stricter settings for mature codebases	Mature projects with good quality standards
extreme	Very strict settings for mission-critical	Critical systems, high-reliability code
custom	Custom profile with user-defined weights	Projects with specific debt tracking needs

How to Use Profiles

Via CLI:

# Analyze your current project
blast-shield --src "src/**/*.ts"

# Use the defensive profile (more lenient)
blast-shield --profile defensive

# Use the aggressive profile (stricter)
blast-shield --profile aggressive

# Use the extreme profile (strictest)
blast-shield --profile extreme

# Generate a detailed technical debt report
blast-shield --generate-report

Via Configuration File

{
  "profile": "aggressive",
  "src": "src/**/*.ts",
  "generateReport": true
}

Custom Weights

{
  "weights": {
    "todo": 1.5,
    "fixme": 3,
    "hack": 4,
    "optimize": 1,
    "refactor": 2,
    "bug": 5,
    "note": 0,
    "debtPenaltyPerPoint": 0.7
  },
  "threshold": 15,
  "minReportScore": 85
}

Profile Details

Each profile configures different weight values for debt indicators and sets appropriate thresholds:

Defensive Profile

• Most forgiving with lower weights for common markers
• Higher threshold (30) to allow more debt
• Lower report score requirement (70%)
• Ideal for new projects or teams just starting with debt tracking

Balanced Profile (Default)

• Moderate weights for all debt types
• Medium threshold (20)
• Standard report score requirement (80%)
• Suitable for most projects with normal quality requirements

Aggressive Profile

• Higher weights for debt markers
• Lower threshold (15) for stricter enforcement
• Higher report score requirement (90%)
• Good for mature codebases with established practices

Extreme Profile

• Highest weights for all debt types
• Very low threshold (10) for minimal debt tolerance
• Stringent report score requirement (95%)
• For mission-critical code where quality is paramount

Custom Profile

• User-defined weights
• Applied whenever weights are explicitly defined in configuration
• Allows fine-tuning for specific project needs

CI/CD Integration

Add Blast Shield to your CI/CD pipeline to enforce debt limits:

# GitHub Actions example
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install -g blast-shield
      - run: blast-shield --profile balanced --src "**/*.{js,ts,py,java,go,rb,php,cs,cpp}"

Development

pnpm build       # Build the CLI
pnpm test        # Run tests
pnpm lint        # Run Biome linter

License

MIT © Arnaud Zheng