performance-budget-enforcer

What this skill does

# Performance Budget Enforcer

Implement automated performance monitoring and budget enforcement to prevent performance regressions in worldbuilding applications.

## Overview

To enforce performance budgets:

1. Define performance budgets for key metrics (bundle size, Lighthouse scores, Web Vitals)
2. Set up automated monitoring in CI/CD pipeline
3. Configure alerts for threshold violations
4. Generate performance reports and trends
5. Block deployments that exceed budgets

## Performance Metrics

### JavaScript Bundle Size

To monitor bundle sizes:

- **Initial Bundle**: First-load JS (target: <200KB)
- **Route Bundles**: Per-page JS (target: <50KB per route)
- **Total Bundle**: All JS combined (target: <500KB)
- **Vendor Bundle**: Third-party libraries (target: <150KB)

### Lighthouse Scores

To track Lighthouse metrics:

- **Performance**: Overall performance score (target: >90)
- **Accessibility**: A11y compliance (target: >90)
- **Best Practices**: Web standards compliance (target: >90)
- **SEO**: Search engine optimization (target: >90)

### Core Web Vitals

To measure user experience:

- **LCP** (Largest Contentful Paint): <2.5s
- **FID** (First Input Delay): <100ms
- **CLS** (Cumulative Layout Shift): <0.1
- **TTFB** (Time to First Byte): <600ms
- **FCP** (First Contentful Paint): <1.8s

Consult `references/performance-targets.md` for detailed target definitions and industry benchmarks.

## Budget Configuration

### Define Budgets

Create `performance-budget.json`:

```json
{
  "bundles": {
    "maxInitialBundle": 204800,
    "maxRouteBundle": 51200,
    "maxTotalBundle": 512000,
    "maxVendorBundle": 153600
  },
  "lighthouse": {
    "performance": 90,
    "accessibility": 90,
    "bestPractices": 90,
    "seo": 90
  },
  "webVitals": {
    "lcp": 2500,
    "fid": 100,
    "cls": 0.1,
    "ttfb": 600,
    "fcp": 1800
  },
  "assets": {
    "maxImageSize": 102400,
    "maxFontSize": 51200,
    "maxCssSize": 51200
  }
}
```

Use `scripts/generate_budget.py` to create initial budget configuration based on current metrics.

### Budget Levels

Define severity levels:

- **Error**: Block deployment (>20% over budget)
- **Warning**: Alert but allow (10-20% over budget)
- **Info**: Track but continue (<10% over budget)

## CI/CD Integration

### GitHub Actions Setup

To add performance checks to CI:

```yaml
name: Performance Budget

on:
  pull_request:
    branches: [main, master]

jobs:
  performance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Analyze bundle size
        run: npx @next/bundle-analyzer

      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun

      - name: Check performance budgets
        run: python scripts/check_budgets.py

      - name: Comment results on PR
        uses: actions/github-script@v7
        with:
          script: |
            const results = require('./performance-results.json');
            // Comment logic here
```

Use `assets/github-workflow.yml` for complete workflow template.

### Lighthouse CI Configuration

Create `lighthouserc.json`:

```json
{
  "ci": {
    "collect": {
      "startServerCommand": "npm run start",
      "url": ["http://localhost:3000", "http://localhost:3000/entities"],
      "numberOfRuns": 3
    },
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.9 }],
        "categories:accessibility": ["error", { "minScore": 0.9 }],
        "first-contentful-paint": ["error", { "maxNumericValue": 1800 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}
```

Reference `assets/lighthouserc.json` for complete configuration.

## Bundle Analysis

### Next.js Bundle Analyzer

To analyze bundle composition:

```bash
# Install analyzer
npm install --save-dev @next/bundle-analyzer

# Add to next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({
  // Next.js config
});

# Run analysis
ANALYZE=true npm run build
```

### Size Tracking

Use `scripts/track_bundle_size.py` to track bundle size over time:

```bash
python scripts/track_bundle_size.py --record
```

Store results in `performance-history/bundle-sizes.json` for trend analysis.

## Automated Alerts

### Threshold Violations

To configure alerts:

```typescript
// scripts/check_budgets.ts
interface BudgetCheck {
  metric: string;
  current: number;
  budget: number;
  status: 'pass' | 'warning' | 'error';
  percentOver: number;
}

function checkBudget(current: number, budget: number): BudgetCheck['status'] {
  const percentOver = ((current - budget) / budget) * 100;

  if (percentOver > 20) return 'error';
  if (percentOver > 10) return 'warning';
  return 'pass';
}
```

### Notification Channels

To send alerts:

- **GitHub PR Comments**: Automated comments with performance report
- **Slack**: Webhook notifications for violations
- **Email**: Digest of performance trends
- **Build Status**: Fail builds on error-level violations

Use `scripts/send_alerts.py` to integrate notification channels.

## Performance Monitoring

### Real User Monitoring (RUM)

To track real user metrics:

```typescript
// lib/web-vitals.ts
import { onCLS, onFID, onLCP, onFCP, onTTFB } from 'web-vitals';

export function reportWebVitals() {
  onCLS((metric) => sendToAnalytics(metric));
  onFID((metric) => sendToAnalytics(metric));
  onLCP((metric) => sendToAnalytics(metric));
  onFCP((metric) => sendToAnalytics(metric));
  onTTFB((metric) => sendToAnalytics(metric));
}

function sendToAnalytics(metric: Metric) {
  // Send to analytics service
  fetch('/api/analytics', {
    method: 'POST',
    body: JSON.stringify(metric),
  });
}
```

Enable in `app/layout.tsx`:

```typescript
import { reportWebVitals } from '@/lib/web-vitals';

export default function RootLayout({ children }: { children: ReactNode }) {
  useEffect(() => {
    reportWebVitals();
  }, []);

  return <html>{children}</html>;
}
```

### Synthetic Monitoring

To run scheduled Lighthouse audits:

```yaml
# .github/workflows/scheduled-performance.yml
name: Scheduled Performance Audit

on:
  schedule:
    - cron: '0 0 * * *' # Daily at midnight

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - name: Run Lighthouse
        run: lhci autorun --config=lighthouserc.json

      - name: Store results
        run: python scripts/store_performance_data.py
```

## Performance Reports

### PR Comments

To generate PR comments with results:

```markdown
## Performance Report

### Bundle Size

- Initial Bundle: 185KB ([OK] under 200KB budget)
- Total Bundle: 480KB ([OK] under 500KB budget)

### Lighthouse Scores

- Performance: 92/100 ([OK] meets 90 target)
- Accessibility: 95/100 ([OK] meets 90 target)
- Best Practices: 88/100 ([WARN] below 90 target)

### Core Web Vitals

- LCP: 2.1s ([OK] under 2.5s)
- FID: 85ms ([OK] under 100ms)
- CLS: 0.05 ([OK] under 0.1)

### Bundle Comparison

| Route            | Current | Previous | Change  |
| ---------------- | ------- | -------- | ------- |
| /                | 185KB   | 180KB    | +5KB    |
| /entities        | 45KB    | 45KB     | No change |
| /entities/[id]   | 38KB    | 40KB     | -2KB [OK] |

[View detailed report](https://lighthouse-report-url)
```

Use `scripts/generate_pr_comment.py` to create formatted reports.

### Trend Analysis

To visualize performance trends:

```bash
python scripts/generate_trends.py --days 30 --output performance-trends.html
```

Generate cha