# 💻 Blast Shield CLI

<p align="center">
  <img src="https://raw.githubusercontent.com/arnaud-zg/blast-shield/main/assets/logo.png" width="128" height="128" alt="Blast Shield Logo" />
</p>

### With Report Analysis

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

<!-- Package Info -->
[![npm version](https://img.shields.io/npm/v/blast-shield.svg)](https://www.npmjs.com/package/blast-shield)
[![npm downloads](https://img.shields.io/npm/dm/blast-shield)](https://www.npmjs.com/package/blast-shield)
[![npm unpacked size](https://img.shields.io/npm/unpacked-size/blast-shield)](https://www.npmjs.com/package/blast-shield)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<!-- Tech Stack -->
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![ESM Ready](https://img.shields.io/badge/ESM-Ready-green)]()
[![Language Agnostic](https://img.shields.io/badge/🌐_Language-Agnostic-orange)](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

### Basic Command

```bash
# Analyze current project with default settings
blast-shield
```

### With Custom Config

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

### Different Source Path

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

### With Report Analysis

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

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

```bash
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.

```bash
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:

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

### How to Use Profiles

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

### 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:

```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](https://github.com/arnaud-zg)