npm package: @forgedock/fd-fastest-scorer
Description: Performance scoring and grading for FD-Fastest reports
Author: ForgeDock
Latest version: 1.0.0

# @fd-fastest/scorer

Performance scoring and grading for FD-Fastest reports.

## Overview

The `@fd-fastest/scorer` package provides a comprehensive performance scoring system that analyzes test reports and generates:

- **Overall Score (0-100)**: A weighted average of multiple performance categories
- **Letter Grade (A-F)**: Easy-to-understand performance rating
- **Category Scores**: Individual scores for vitals, assets, hydration, and server performance
- **Actionable Insights**: Specific recommendations for improving performance
- **Pass/Fail Metrics**: Clear indication of which Core Web Vitals are passing or failing

## Installation

```bash
pnpm add @fd-fastest/scorer
```

## Usage

### Basic Usage

```typescript
import { PerformanceScorer } from '@fd-fastest/scorer';
import type { Report } from '@fd-fastest/reporter-json';

// Get your performance report
const report: Report = {
  /* ... */
};

// Create scorer instance
const scorer = new PerformanceScorer();

// Calculate score
const score = scorer.calculate(report);

console.log(`Score: ${score.overall}/100 (${score.grade})`);
console.log(`Passing: ${score.passing.join(', ')}`);
console.log(`Failing: ${score.failing.join(', ')}`);

// Display insights
score.insights.forEach((insight) => {
  console.log(`${insight.severity}: ${insight.message}`);
  console.log(`Recommendation: ${insight.recommendation}`);
});
```

### Custom Thresholds

You can customize the performance thresholds:

```typescript
import { PerformanceScorer, DEFAULT_THRESHOLDS } from '@fd-fastest/scorer';

const customThresholds = {
  ...DEFAULT_THRESHOLDS,
  lcp: { good: 2000, poor: 3500 }, // Stricter LCP requirements
  cls: { good: 0.05, poor: 0.15 }, // Stricter CLS requirements
};

const scorer = new PerformanceScorer(customThresholds);
const score = scorer.calculate(report);
```

## Scoring System

### Overall Score

The overall score (0-100) is a weighted average of four categories:

- **Web Vitals (40%)**: LCP, CLS, INP
- **Assets (30%)**: JavaScript and CSS bundle sizes
- **Hydration (20%)**: React hydration timing
- **Server (10%)**: Server-side performance

### Letter Grades

| Score  | Grade |
| ------ | ----- |
| 90-100 | A     |
| 80-89  | B     |
| 70-79  | C     |
| 60-69  | D     |
| 0-59   | F     |

### Default Thresholds

Based on Google's Core Web Vitals and Lighthouse standards:

```typescript
{
  // Core Web Vitals
  lcp: { good: 2500, poor: 4000 },     // milliseconds
  cls: { good: 0.1, poor: 0.25 },       // score
  inp: { good: 200, poor: 500 },        // milliseconds

  // Additional metrics
  fcp: { good: 1800, poor: 3000 },      // milliseconds
  tbt: { good: 200, poor: 600 },        // milliseconds
  tti: { good: 3800, poor: 7300 },      // milliseconds

  // Asset sizes
  jsKb: { good: 300, poor: 600 },       // kilobytes
  cssKb: { good: 100, poor: 200 },      // kilobytes

  // Framework-specific
  hydration: { good: 500, poor: 1500 }, // milliseconds
}
```

## Insights

The scorer generates actionable insights with:

- **Severity**: `info`, `warning`, or `critical`
- **Category**: The performance area affected
- **Message**: Description of the issue
- **Recommendation**: Specific steps to improve
- **Impact**: Expected impact of fixing the issue (`low`, `medium`, `high`)

### Example Insights

```typescript
{
  severity: 'critical',
  category: 'Core Web Vitals',
  message: 'LCP is 5000ms (target: <2500ms)',
  recommendation: 'Optimize images, reduce render-blocking resources, improve server response time',
  impact: 'high'
}
```

## API

### `PerformanceScorer`

#### Constructor

```typescript
new PerformanceScorer(thresholds?: ScoringThresholds)
```

Creates a new scorer instance with optional custom thresholds.

#### Methods

##### `calculate(report: Report): PerformanceScore`

Calculates the performance score for a given report.

**Parameters:**

- `report`: A validated performance report from `@fd-fastest/reporter-json`

**Returns:**

- `PerformanceScore`: Complete scoring results including overall score, grade, category scores, insights, and pass/fail metrics

## Types

### `PerformanceScore`

```typescript
interface PerformanceScore {
  overall: number; // 0-100
  grade: 'A' | 'B' | 'C' | 'D' | 'F';
  categories: {
    vitals: number; // 0-100
    assets: number; // 0-100
    hydration: number; // 0-100
    server: number; // 0-100
  };
  insights: Insight[];
  passing: string[];
  failing: string[];
}
```

### `Insight`

```typescript
interface Insight {
  severity: 'info' | 'warning' | 'critical';
  category: string;
  message: string;
  recommendation: string;
  impact: 'low' | 'medium' | 'high';
}
```

### `ScoringThresholds`

```typescript
interface ScoringThresholds {
  lcp: { good: number; poor: number };
  cls: { good: number; poor: number };
  inp: { good: number; poor: number };
  fcp: { good: number; poor: number };
  tbt: { good: number; poor: number };
  tti: { good: number; poor: number };
  jsKb: { good: number; poor: number };
  cssKb: { good: number; poor: number };
  hydration: { good: number; poor: number };
}
```

## Integration

The scorer is automatically integrated into the FD-Fastest CLI. When you run performance tests, scores are calculated and displayed in the output:

```bash
pnpm fd-fastest lab
```

Output includes:

```
📊 Performance Score: 85/100 (B)

  Categories:
    Vitals:    78/100
    Assets:    90/100
    Hydration: 92/100
    Server:    100/100

  ✅ Passing: CLS, INP
  ❌ Failing: LCP

💡 Insights:

  🟡 LCP is 3200ms (target: <2500ms)
     → Consider image optimization and reducing render-blocking resources
```

## License

MIT