chore: compare unlighthouse reports preview vs production

Author: jorgemoya

.github/scripts/compare-unlighthouse.mts

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/* eslint-disable no-console, no-restricted-syntax, no-plusplus, no-continue */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+
+interface CiResult {
+  summary: {
+    score: number;
+    categories: Record<string, { score: number }>;
+    metrics: Record<string, { displayValue: string }>;
+  };
+}
+
+function loadCiResult(filePath: string): CiResult {
+  if (!existsSync(filePath)) {
+    console.error(`Error: file not found: ${filePath}`);
+    process.exit(1);
+  }
+
+  return JSON.parse(readFileSync(filePath, "utf-8")) as CiResult;
+}
+
+function dec(value: number): string {
+  return value.toFixed(2);
+}
+
+function row(
+  label: string,
+  prodDesktop: string,
+  prodMobile: string,
+  prevDesktop: string,
+  prevMobile: string,
+): string {
+  return `| ${label} | ${prodDesktop} | ${prodMobile} | ${prevDesktop} | ${prevMobile} |`;
+}
+
+const CATEGORY_ORDER = ["performance", "accessibility", "best-practices", "seo"];
+
+const CATEGORY_LABELS: Record<string, string> = {
+  performance: "Performance",
+  accessibility: "Accessibility",
+  "best-practices": "Best Practices",
+  seo: "SEO",
+};
+
+const METRIC_ORDER = [
+  "largest-contentful-paint",
+  "cumulative-layout-shift",
+  "first-contentful-paint",
+  "total-blocking-time",
+  "max-potential-fid",
+  "interactive",
+];
+
+const METRIC_LABELS: Record<string, string> = {
+  "largest-contentful-paint": "LCP",
+  "cumulative-layout-shift": "CLS",
+  "first-contentful-paint": "FCP",
+  "total-blocking-time": "TBT",
+  "max-potential-fid": "Max Potential FID",
+  interactive: "Time to Interactive",
+};
+
+const COL_HEADER =
+  "| | Prod Desktop | Prod Mobile | Preview Desktop | Preview Mobile |";
+const COL_SEP =
+  "|:-|:------------|:------------|:----------------|:---------------|";
+
+function compareResults(
+  productionDesktop: CiResult,
+  productionMobile: CiResult,
+  previewDesktop: CiResult,
+  previewMobile: CiResult,
+  threshold: number,
+  provider?: string,
+): { markdown: string; hasChanges: boolean } {
+  const thresholdDecimal = threshold / 100;
+
+  // hasChanges: any summary or category score pair differs by >= threshold
+  let hasChanges =
+    Math.abs(previewDesktop.summary.score - productionDesktop.summary.score) >=
+      thresholdDecimal ||
+    Math.abs(previewMobile.summary.score - productionMobile.summary.score) >=
+      thresholdDecimal;
+
+  if (!hasChanges) {
+    for (const id of CATEGORY_ORDER) {
+      const deltaDesktop = Math.abs(
+        (previewDesktop.summary.categories[id]?.score ?? 0) -
+          (productionDesktop.summary.categories[id]?.score ?? 0),
+      );
+      const deltaMobile = Math.abs(
+        (previewMobile.summary.categories[id]?.score ?? 0) -
+          (productionMobile.summary.categories[id]?.score ?? 0),
+      );
+
+      if (deltaDesktop >= thresholdDecimal || deltaMobile >= thresholdDecimal) {
+        hasChanges = true;
+        break;
+      }
+    }
+  }
+
+  const lines: string[] = [];
+
+  const providerLabel = provider
+    ? ` — ${provider.charAt(0).toUpperCase()}${provider.slice(1)}`
+    : "";
+
+  lines.push(`## Unlighthouse Performance Comparison${providerLabel}`);
+  lines.push("Comparing PR preview against production.");
+  lines.push("");
+
+  lines.push("### Summary Score");
+  lines.push("");
+  lines.push(COL_HEADER);
+  lines.push(COL_SEP);
+  lines.push(
+    row(
+      "Score",
+      dec(productionDesktop.summary.score),
+      dec(productionMobile.summary.score),
+      dec(previewDesktop.summary.score),
+      dec(previewMobile.summary.score),
+    ),
+  );
+  lines.push("");
+
+  lines.push("### Category Scores");
+  lines.push("");
+  lines.push(
+    "| Category | Prod Desktop | Prod Mobile | Preview Desktop | Preview Mobile |",
+  );
+  lines.push(
+    "|:---------|:------------|:------------|:----------------|:---------------|",
+  );
+
+  for (const id of CATEGORY_ORDER) {
+    lines.push(
+      row(
+        CATEGORY_LABELS[id] ?? id,
+        dec(productionDesktop.summary.categories[id]?.score ?? 0),
+        dec(productionMobile.summary.categories[id]?.score ?? 0),
+        dec(previewDesktop.summary.categories[id]?.score ?? 0),
+        dec(previewMobile.summary.categories[id]?.score ?? 0),
+      ),
+    );
+  }
+
+  lines.push("");
+
+  lines.push("### Core Web Vitals");
+  lines.push("");
+  lines.push(
+    "| Metric | Prod Desktop | Prod Mobile | Preview Desktop | Preview Mobile |",
+  );
+  lines.push(
+    "|:-------|:------------|:------------|:----------------|:---------------|",
+  );
+
+  for (const id of METRIC_ORDER) {
+    lines.push(
+      row(
+        METRIC_LABELS[id] ?? id,
+        productionDesktop.summary.metrics[id]?.displayValue ?? "—",
+        productionMobile.summary.metrics[id]?.displayValue ?? "—",
+        previewDesktop.summary.metrics[id]?.displayValue ?? "—",
+        previewMobile.summary.metrics[id]?.displayValue ?? "—",
+      ),
+    );
+  }
+
+  lines.push("");
+
+  return { markdown: lines.join("\n"), hasChanges };
+}
+
+export { compareResults };
+export type { CiResult };
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  const { values } = parseArgs({
+    options: {
+      "preview-desktop": { type: "string" },
+      "preview-mobile": { type: "string" },
+      "production-desktop": { type: "string" },
+      "production-mobile": { type: "string" },
+      output: { type: "string" },
+      "meta-output": { type: "string" },
+      threshold: { type: "string" },
+      provider: { type: "string" },
+    },
+  });
+
+  const previewDesktopPath = values["preview-desktop"] ?? "";
+  const previewMobilePath = values["preview-mobile"] ?? "";
+  const productionDesktopPath = values["production-desktop"] ?? "";
+  const productionMobilePath = values["production-mobile"] ?? "";
+
+  if (
+    !previewDesktopPath ||
+    !previewMobilePath ||
+    !productionDesktopPath ||
+    !productionMobilePath
+  ) {
+    console.error(
+      "Usage: compare-unlighthouse.mts --preview-desktop <path> --preview-mobile <path> --production-desktop <path> --production-mobile <path> [--output <path>] [--meta-output <path>] [--threshold <n>] [--provider <name>]",
+    );
+    process.exit(1);
+  }
+
+  const threshold = Number(values.threshold ?? "1");
+
+  const previewDesktop = loadCiResult(resolve(previewDesktopPath));
+  const previewMobile = loadCiResult(resolve(previewMobilePath));
+  const productionDesktop = loadCiResult(resolve(productionDesktopPath));
+  const productionMobile = loadCiResult(resolve(productionMobilePath));
+
+  const { markdown, hasChanges } = compareResults(
+    productionDesktop,
+    productionMobile,
+    previewDesktop,
+    previewMobile,
+    threshold,
+    values.provider,
+  );
+
+  const outputPath = values.output ? resolve(values.output) : null;
+  const metaOutputPath = values["meta-output"]
+    ? resolve(values["meta-output"])
+    : null;
+
+  if (outputPath) {
+    writeFileSync(outputPath, markdown);
+    console.error(`Unlighthouse comparison report written to ${outputPath}`);
+  } else {
+    process.stdout.write(markdown);
+  }
+
+  if (metaOutputPath) {
+    writeFileSync(
+      metaOutputPath,
+      `${JSON.stringify({ hasChanges }, null, 2)}\n`,
+    );
+    console.error(`Meta output written to ${metaOutputPath}`);
+  }
+}

.github/scripts/post-unlighthouse-comment.js

@@ -0,0 +1,52 @@
+const fs = require('fs');
+
+module.exports = async ({ github, context, provider = 'unknown', reportPath = '/tmp/unlighthouse-report.md', metaPath = '/tmp/unlighthouse-meta.json' }) => {
+  // Exit early if no changes
+  const { hasChanges } = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+
+  if (!hasChanges) return;
+
+  // Find PR from commit SHA (context.issue.number is 0 in deployment_status events;
+  // deployment.ref is also the SHA in Vercel deployments, not the branch name)
+  const sha = context.payload.deployment?.sha;
+
+  if (!sha) return;
+
+  const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    commit_sha: sha,
+  });
+
+  const prNumber = prs[0]?.number;
+
+  if (!prNumber) return;
+
+  const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+  const marker = `<!-- unlighthouse-${provider}-report -->`;
+  const body = marker + '\n' + fs.readFileSync(reportPath, 'utf-8') + `[Full Unlighthouse report →](${runUrl})\n`;
+
+  const { data: comments } = await github.rest.issues.listComments({
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    issue_number: prNumber,
+  });
+
+  const existing = comments.find(c => c.body.includes(marker));
+
+  if (existing) {
+    await github.rest.issues.updateComment({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      comment_id: existing.id,
+      body,
+    });
+  } else {
+    await github.rest.issues.createComment({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      issue_number: prNumber,
+      body,
+    });
+  }
+};