Add CI performance budgets and observability checks

frontend/package.json

@@ -42,6 +42,7 @@
     "@types/node": "^20",
     "@types/react": "^18",
     "@types/react-dom": "^18",
+    "@types/js-yaml": "^4.0.9",
     "autoprefixer": "^10.0.1",
     "eslint": "^8",
     "eslint-config-next": "14.2.0",

frontend/tests/e2e/perf/perf-budget.spec.ts

@@ -0,0 +1,277 @@
+import { expect, test } from '@playwright/test';
+import type { Browser } from '@playwright/test';
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+type WaitConfig = {
+  type: 'selector' | 'networkidle';
+  selector?: string;
+  timeout_ms?: number;
+  idle_ms?: number;
+};
+
+type MetricConfig = {
+  id: string;
+  aggregation: string;
+  threshold: number;
+  unit: string;
+};
+
+type JourneyConfig = {
+  id: string;
+  description?: string;
+  from_url: string;
+  to_url: string;
+  waits?: WaitConfig[];
+  metrics?: MetricConfig[];
+};
+
+type PerfBudgetConfig = {
+  run_count?: number;
+  journeys?: JourneyConfig[];
+};
+
+type JourneyMetricSummary = {
+  quantile: string;
+  value_ms: number;
+  threshold_ms?: number;
+  passed: boolean;
+};
+
+type JourneyResult = {
+  id: string;
+  description?: string;
+  runs: Array<{
+    navigation_duration_ms: number;
+    largest_contentful_paint_ms: number;
+  }>;
+  aggregated: {
+    navigation_duration?: JourneyMetricSummary;
+    largest_contentful_paint?: JourneyMetricSummary;
+  };
+};
+
+const percentile = (values: number[], percentileValue: number): number => {
+  if (!values.length) {
+    return 0;
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  const rank = (sorted.length - 1) * percentileValue;
+  const lowerIndex = Math.floor(rank);
+  const upperIndex = Math.ceil(rank);
+  if (lowerIndex === upperIndex) {
+    return sorted[lowerIndex];
+  }
+  const weight = rank - lowerIndex;
+  return sorted[lowerIndex] + (sorted[upperIndex] - sorted[lowerIndex]) * weight;
+};
+
+const loadPerfBudget = (): PerfBudgetConfig => {
+  const configPath = process.env.PERF_BUDGET_FILE
+    ? path.resolve(process.cwd(), process.env.PERF_BUDGET_FILE)
+    : path.resolve(__dirname, '../../../../perf-budget.yml');
+
+  const raw = fs.readFileSync(configPath, 'utf8');
+  return yaml.load(raw) as PerfBudgetConfig;
+};
+
+const toQuantile = (aggregation: string): number | undefined => {
+  const match = /^p(\d{1,2})$/i.exec(aggregation.trim());
+  if (!match) {
+    return undefined;
+  }
+  const percentileNumber = Number(match[1]);
+  return percentileNumber / 100;
+};
+
+const ensureResultsDir = (): string => {
+  const dir = process.env.PERF_RESULTS_DIR
+    ? path.resolve(process.cwd(), process.env.PERF_RESULTS_DIR)
+    : path.resolve(__dirname, '../../../../perf-results');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+};
+
+const writeJourneyResult = (dir: string, result: JourneyResult): void => {
+  const filePath = path.join(dir, `${result.id}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(result, null, 2), 'utf8');
+};
+
+const attachJourneyResult = async (result: JourneyResult): Promise<void> => {
+  await test.info().attach(`${result.id}-metrics.json`, {
+    body: Buffer.from(JSON.stringify(result, null, 2)),
+    contentType: 'application/json',
+  });
+};
+
+const collectNavigationMetrics = async (
+  browser: Browser,
+  fromUrl: string,
+  toUrl: string,
+  waits: WaitConfig[] | undefined,
+): Promise<{ navigation: number; lcp: number }> => {
+  const context = await browser.newContext();
+
+  await context.addInitScript(() => {
+    (window as typeof window & {
+      __lcpEntries?: PerformanceEntry[];
+      __lcpObserver?: PerformanceObserver;
+    }).__lcpEntries = [];
+  });
+
+  const page = await context.newPage();
+  await page.goto(fromUrl, { waitUntil: 'networkidle' });
+
+  await page.evaluate(() => {
+    const globalWindow = window as typeof window & {
+      __lcpEntries?: PerformanceEntry[];
+      __lcpObserver?: PerformanceObserver;
+    };
+
+    globalWindow.__lcpEntries = [];
+    if (globalWindow.__lcpObserver) {
+      globalWindow.__lcpObserver.disconnect();
+    }
+    globalWindow.__lcpObserver = new PerformanceObserver((entryList) => {
+      const entries = entryList.getEntries();
+      globalWindow.__lcpEntries = [
+        ...(globalWindow.__lcpEntries ?? []),
+        ...entries,
+      ];
+    });
+    globalWindow.__lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true });
+
+    performance.clearResourceTimings();
+    performance.clearMeasures();
+    performance.clearMarks();
+  });
+
+  await page.goto(toUrl, { waitUntil: 'networkidle' });
+
+  if (waits) {
+    for (const wait of waits) {
+      if (wait.type === 'selector' && wait.selector) {
+        await page.waitForSelector(wait.selector, {
+          state: 'attached',
+          timeout: wait.timeout_ms ?? 30_000,
+        });
+      }
+      if (wait.type === 'networkidle') {
+        await page.waitForLoadState('networkidle', { timeout: wait.timeout_ms ?? 30_000 });
+        if (wait.idle_ms) {
+          await page.waitForTimeout(wait.idle_ms);
+        }
+      }
+    }
+  }
+
+  await page.waitForTimeout(500);
+
+  const navigationDuration = await page.evaluate(() => {
+    const entries = performance.getEntriesByType('navigation');
+    const last = entries[entries.length - 1] as PerformanceNavigationTiming | undefined;
+    return last ? last.duration : Number.NaN;
+  });
+
+  const lcp = await page.evaluate(() => {
+    const globalWindow = window as typeof window & {
+      __lcpEntries?: PerformanceEntry[];
+    };
+    const entries = (globalWindow.__lcpEntries ?? []) as Array<PerformanceEntry & { renderTime?: number; loadTime?: number; startTime: number }>;
+    if (!entries.length) {
+      return Number.NaN;
+    }
+    return entries.reduce((acc, entry) => {
+      const candidate = entry.startTime ?? entry.renderTime ?? entry.loadTime ?? 0;
+      return Math.max(acc, candidate);
+    }, 0);
+  });
+
+  await context.close();
+
+  return { navigation: navigationDuration, lcp };
+};
+
+const perfConfig = loadPerfBudget();
+const runCount = perfConfig.run_count ?? 3;
+const resultsDir = ensureResultsDir();
+
+test.describe('performance budget journeys', () => {
+  if (!perfConfig.journeys || perfConfig.journeys.length === 0) {
+    test('no journeys defined', async () => {
+      test.skip(true, 'No journeys defined in perf budget');
+    });
+    return;
+  }
+
+  for (const journey of perfConfig.journeys) {
+    test(journey.id, async ({ browser }) => {
+      const runs: Array<{ navigation_duration_ms: number; largest_contentful_paint_ms: number }> = [];
+
+      for (let iteration = 0; iteration < runCount; iteration += 1) {
+        const metrics = await collectNavigationMetrics(browser, journey.from_url, journey.to_url, journey.waits);
+        runs.push({
+          navigation_duration_ms: metrics.navigation,
+          largest_contentful_paint_ms: metrics.lcp,
+        });
+      }
+
+      const navigationValues = runs.map((run) => run.navigation_duration_ms).filter((value) => Number.isFinite(value));
+      const lcpValues = runs.map((run) => run.largest_contentful_paint_ms).filter((value) => Number.isFinite(value));
+
+      const aggregated: JourneyResult['aggregated'] = {};
+
+      const metricConfigById = new Map<string, MetricConfig>();
+      for (const metric of journey.metrics ?? []) {
+        metricConfigById.set(metric.id, metric);
+      }
+
+      if (navigationValues.length) {
+        const metricConfig = metricConfigById.get('navigation-duration');
+        const quantile = metricConfig ? toQuantile(metricConfig.aggregation) : 0.9;
+        const value = percentile(navigationValues, quantile ?? 0.9);
+        aggregated.navigation_duration = {
+          quantile: metricConfig ? metricConfig.aggregation.toLowerCase() : 'p90',
+          value_ms: value,
+          threshold_ms: metricConfig?.threshold,
+          passed: metricConfig ? value <= metricConfig.threshold : true,
+        };
+      }
+
+      if (lcpValues.length) {
+        const metricConfig = metricConfigById.get('largest-contentful-paint');
+        const quantile = metricConfig ? toQuantile(metricConfig.aggregation) : 0.95;
+        const value = percentile(lcpValues, quantile ?? 0.95);
+        aggregated.largest_contentful_paint = {
+          quantile: metricConfig ? metricConfig.aggregation.toLowerCase() : 'p95',
+          value_ms: value,
+          threshold_ms: metricConfig?.threshold,
+          passed: metricConfig ? value <= metricConfig.threshold : true,
+        };
+      }
+
+      const result: JourneyResult = {
+        id: journey.id,
+        description: journey.description,
+        runs,
+        aggregated,
+      };
+
+      writeJourneyResult(resultsDir, result);
+      await attachJourneyResult(result);
+
+      if (aggregated.navigation_duration && aggregated.navigation_duration.threshold_ms !== undefined) {
+        expect(aggregated.navigation_duration.value_ms, 'homepage to configurator navigation P90 should remain under budget').toBeLessThanOrEqual(
+          aggregated.navigation_duration.threshold_ms,
+        );
+      }
+
+      if (aggregated.largest_contentful_paint && aggregated.largest_contentful_paint.threshold_ms !== undefined) {
+        expect(aggregated.largest_contentful_paint.value_ms, 'homepage to configurator LCP P95 should remain under budget').toBeLessThanOrEqual(
+          aggregated.largest_contentful_paint.threshold_ms,
+        );
+      }
+    });
+  }
+});

mkdocs.yml

@@ -33,6 +33,7 @@ nav:
   - Getting Started: getting-started.md
   - Backend Development: backend-development.md
   - Frontend Development: frontend-development.md
+  - Release Checklist: release-checklist.md
   - Docker and Deployment: docker-deployment.md
   - Architecture: ARCHITECTURE.md
   - API Spec: API_SPEC.md

scripts/ci/__init__.py

@@ -0,0 +1 @@
+"""CI helper scripts for observability automation."""