💻 Blast Shield CLI

$3

``bash


Generate a detailed technical debt report


blast-shield --generate-report
`

When using --generate-report, Blast Shield will:
1. Generate a detailed report of technical debt metrics
2. Compare the debt score against your configured threshold
3. Apply debt penalties based on your configuration
4. 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.


![npm version](https://www.npmjs.com/package/blast-shield)
![npm downloads](https://www.npmjs.com/package/blast-shield)
![npm unpacked size](https://www.npmjs.com/package/blast-shield)
![License: MIT](https://opensource.org/licenses/MIT)


![TypeScript](https://www.typescriptlang.org/)
![ESM Ready]()
![Language Agnostic](https://github.com/arnaud-zg/blast-shield)

> 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

`bash


Install globally

npm install -g blast-shield

Or use with npx

npx blast-shield
`

Quick Start

`bash


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

$3

`bash


Analyze current project with default settings


blast-shield
`

$3

`bash


Use a specific config file


blast-shield --config ./my-debt-config.json
`

$3

`bash


Analyze only specific files


blast-shield --src "libs/*/.ts"
`

$3

`bash


Include report metrics in the analysis


blast-shield --generate-report
`

When using --generate-report, Blast Shield will:
1. Generate a detailed report including report metrics
2. Compare the report score against your configured minReportScore
3. Apply debt penalties to your debt score if below the minimum
4. Save the report for historical tracking

Report Structure

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

$3

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

$3

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

$3

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

$3

`
$ 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

$3

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).

`bash
blast-shield init [options]
`

Options:
- -o, --output - 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.

$3

Analyzes your codebase for technical debt indicators.

`bash
blast-shield [options]
`

Options:
- -c, --config - Path to config file (default: "blast-shield.config.json")
- -s, --src - 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 - 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:

`json
{
"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 |

$3

#### Via CLI:

`bash


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

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

#### Custom Weights

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

$3

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:

`yaml


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}"
``

License

MIT © Arnaud Zheng