@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

pnpm add @fd-fastest/scorer

Usage

Basic Usage

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:

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:

{
  // 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

{
  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

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

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

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

ScoringThresholds

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:

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