npm package: @flightdev/bundle-analyzer
Description: Bundle analysis and optimization recommendations for Flight Framework
Author: Flight Framework Team
Latest version: 0.1.1

# @flight-framework/bundle-analyzer

Bundle analysis and optimization recommendations for Flight Framework.

## Installation

```bash
npm install -D @flight-framework/bundle-analyzer
```

## Quick Start

### CLI Usage

```bash
# Analyze default ./dist directory
npx @flight-framework/bundle-analyzer

# Specify build directory
npx @flight-framework/bundle-analyzer -d ./build

# Generate HTML report
npx @flight-framework/bundle-analyzer -f html --open

# Output JSON for CI/CD
npx @flight-framework/bundle-analyzer -f json -o report.json
```

### Programmatic Usage

```typescript
import { analyzeBundle, generateReport } from '@flight-framework/bundle-analyzer';

const result = await analyzeBundle({
    buildDir: './dist',
});

console.log(`Total size: ${result.totalSize} bytes`);
console.log(`Recommendations: ${result.recommendations.length}`);

// Generate text report
const report = generateReport(result, 'text');
console.log(report);
```

## CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `-d, --dir <path>` | Build directory to analyze | `./dist` |
| `-f, --format <type>` | Output format: json, html, text | `text` |
| `-o, --output <path>` | Output file path | stdout |
| `--open` | Open HTML report in browser | false |
| `-h, --help` | Show help | - |

## Output

### Text Report

```
============================================================
  FLIGHT BUNDLE ANALYSIS
============================================================

SUMMARY
----------------------------------------
  Total Size:     245.3 KB
  Gzip Size:      78.2 KB
  Brotli Size:    66.5 KB
  Chunks:         12
  Analysis Time:  234ms

CHUNKS
----------------------------------------

Chunk                               Size       Gzip
---------------------------------------------------------
index-abc123.js                   85.2 KB   28.1 KB [!]
vendor-def456.js                  62.1 KB   21.3 KB [~]
...

RECOMMENDATIONS
----------------------------------------
  [!] Large chunk: index-abc123.js
      This chunk exceeds the recommended size limit.
      Action: Consider code splitting.
```

### HTML Report

Generates a dark-themed, responsive HTML report with:
- Summary statistics
- Chunk breakdown with size bars
- Recommendations with severity indicators

### JSON Report

Full analysis data for CI/CD integration:

```json
{
  "chunks": [...],
  "modules": [...],
  "duplicates": [...],
  "recommendations": [...],
  "totalSize": 251234,
  "totalGzipSize": 80123,
  "timestamp": 1705056000000
}
```

## Recommendations

The analyzer detects common issues:

| ID | Type | Description |
|----|------|-------------|
| `large-chunk` | Critical | Chunk exceeds size threshold |
| `duplicate-dependency` | Warning | Same package bundled multiple times |
| `heavy-dependency` | Suggestion | Large package with lighter alternative |
| `no-code-splitting` | Suggestion | Single bundle without dynamic imports |

## API Reference

### analyzeBundle(options)

```typescript
interface AnalyzerOptions {
    buildDir: string;
    includeSourceMaps?: boolean;
    sizeThreshold?: number;      // Default: 50000
}

const result: AnalysisResult = await analyzeBundle(options);
```

### generateReport(result, format)

```typescript
type ReportFormat = 'json' | 'html' | 'text';

const report: string = generateReport(result, format);
```

## License

MIT