@tokenoftrust/storefront-runner 1.3.4-rc.3 → 1.4.0

package/apps/storefront/src/lib/analytics/perfBudgets.ts

@@ -0,0 +1,452 @@
+/**
+ * F14 — Performance budgets (framework-enforceable, not prose).
+ *
+ * This module is the typed lens over the checked-in manifest (`budgets.json`,
+ * the source of truth). It provides three things the go-live framework needs:
+ *
+ *  1. `parsePerfBudgets` — a runtime validator so a malformed manifest fails
+ *     loudly (in a test / at harness start) instead of silently under-enforcing.
+ *  2. `evaluateManifest` / `evaluateRoute` — the PURE budget-assertion logic the
+ *     lab harness (`perf/assert-budgets.ts`) runs against a measurement report
+ *     (Lighthouse or any collector that emits the `RouteMeasurement` shape).
+ *  3. `toLighthouseBudgets` — a derived, Lighthouse-native `budget.json` array so
+ *     a Lighthouse/LHCI run can enforce the same numbers directly.
+ *
+ * Keeping the comparison pure (no fs / no network) is what makes the gate
+ * unit-testable here (perfBudgets.test.ts) without a live preview — the live
+ * Lighthouse run only has to PRODUCE the report; this decides pass/fail.
+ *
+ * `classifyPath` is shared with the field RUM collector (webVitals.ts) so a
+ * field sample and a lab measurement bucket into the SAME route id.
+ */
+import manifestJson from "./budgets.json";
+
+export type RouteId = "home" | "plp" | "pdp" | "search" | "account" | "checkout";
+export const ROUTE_IDS: readonly RouteId[] = [
+  "home",
+  "plp",
+  "pdp",
+  "search",
+  "account",
+  "checkout",
+];
+
+/** A path that matched no budgeted route — collected by RUM, never gated. */
+export type RouteClass = RouteId | "other";
+
+export interface WebVitalsBudget {
+  /** Largest Contentful Paint, p75, milliseconds. */
+  lcpMs: number;
+  /** Interaction to Next Paint, p75, milliseconds. */
+  inpMs: number;
+  /** Cumulative Layout Shift, p75, unitless. */
+  cls: number;
+}
+
+export interface ResourceBudget {
+  /** Script transfer budget, KiB compressed. */
+  jsKib: number;
+  /** Stylesheet transfer budget, KiB compressed. */
+  cssKib: number;
+  /** Image transfer budget, KiB compressed. */
+  imageKib: number;
+  /** Total page transfer budget, KiB compressed. */
+  totalKib: number;
+}
+
+export interface RouteBudgetDef {
+  id: RouteId;
+  label: string;
+  /** A representative path a lab run can navigate to. */
+  samplePath: string;
+  /**
+   * Path-prefix matchers used by `classifyPath`. The sentinel `"="` means the
+   * exact site root (`/`) only — a bare prefix would match every path.
+   */
+  match: readonly string[];
+  /** Optional per-route resource-budget overrides (merged over the defaults). */
+  resourceBudgets?: Partial<ResourceBudget>;
+  /** Optional per-route Web Vitals overrides (merged over the defaults). */
+  webVitals?: Partial<WebVitalsBudget>;
+}
+
+export interface PerfBudgetManifest {
+  version: number;
+  webVitals: WebVitalsBudget;
+  resourceBudgets: ResourceBudget;
+  thirdPartyScriptAllowlist: readonly string[];
+  routes: readonly RouteBudgetDef[];
+}
+
+/** The fully-resolved budget for one route (defaults + overrides applied). */
+export interface ResolvedRouteBudget {
+  id: RouteId;
+  label: string;
+  samplePath: string;
+  webVitals: WebVitalsBudget;
+  resourceBudgets: ResourceBudget;
+}
+
+/**
+ * What a lab run (Lighthouse or an equivalent collector) reports for one route.
+ * All fields optional except `routeId` so a partial run (e.g. resource-only, no
+ * lab vitals) still evaluates the dimensions it did measure.
+ */
+export interface RouteMeasurement {
+  routeId: RouteId;
+  url?: string;
+  resources?: Partial<{
+    jsKib: number;
+    cssKib: number;
+    imageKib: number;
+    totalKib: number;
+  }>;
+  webVitals?: Partial<WebVitalsBudget>;
+  /** Distinct third-party origins that loaded scripts on the page. */
+  thirdPartyOrigins?: readonly string[];
+}
+
+export interface BudgetViolation {
+  routeId: RouteId;
+  /** Which budget line failed. */
+  metric:
+    | "lcpMs"
+    | "inpMs"
+    | "cls"
+    | "jsKib"
+    | "cssKib"
+    | "imageKib"
+    | "totalKib"
+    | "thirdParty";
+  budget: number;
+  actual: number;
+  /** For `thirdParty`: the offending origin(s). */
+  detail?: string;
+}
+
+export interface RouteBudgetResult {
+  routeId: RouteId;
+  passed: boolean;
+  violations: BudgetViolation[];
+}
+
+export interface BudgetReport {
+  passed: boolean;
+  results: RouteBudgetResult[];
+  violations: BudgetViolation[];
+  /** Budgeted route ids that had no measurement in the report. */
+  missingRoutes: RouteId[];
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function num(obj: Record<string, unknown>, key: string, where: string): number {
+  const v = obj[key];
+  if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+    throw new Error(`perf budgets: ${where}.${key} must be a non-negative number`);
+  }
+  return v;
+}
+
+function partialWebVitals(v: unknown, where: string): Partial<WebVitalsBudget> {
+  if (!isRecord(v)) throw new Error(`perf budgets: ${where}.webVitals must be an object`);
+  const out: Partial<WebVitalsBudget> = {};
+  for (const k of ["lcpMs", "inpMs", "cls"] as const) {
+    if (v[k] !== undefined) out[k] = num(v, k, `${where}.webVitals`);
+  }
+  return out;
+}
+
+function partialResources(v: unknown, where: string): Partial<ResourceBudget> {
+  if (!isRecord(v)) throw new Error(`perf budgets: ${where}.resourceBudgets must be an object`);
+  const out: Partial<ResourceBudget> = {};
+  for (const k of ["jsKib", "cssKib", "imageKib", "totalKib"] as const) {
+    if (v[k] !== undefined) out[k] = num(v, k, `${where}.resourceBudgets`);
+  }
+  return out;
+}
+
+/**
+ * Validate + narrow a raw manifest. Throws with a precise path on the first
+ * problem — so `budgets.json` cannot silently drift into a shape that
+ * under-enforces (a test calls this on the checked-in file).
+ */
+export function parsePerfBudgets(raw: unknown): PerfBudgetManifest {
+  if (!isRecord(raw)) throw new Error("perf budgets: manifest must be an object");
+  const version = num(raw, "version", "manifest");
+
+  if (!isRecord(raw.webVitals)) throw new Error("perf budgets: manifest.webVitals missing");
+  const webVitals: WebVitalsBudget = {
+    lcpMs: num(raw.webVitals, "lcpMs", "webVitals"),
+    inpMs: num(raw.webVitals, "inpMs", "webVitals"),
+    cls: num(raw.webVitals, "cls", "webVitals"),
+  };
+
+  if (!isRecord(raw.resourceBudgets)) {
+    throw new Error("perf budgets: manifest.resourceBudgets missing");
+  }
+  const resourceBudgets: ResourceBudget = {
+    jsKib: num(raw.resourceBudgets, "jsKib", "resourceBudgets"),
+    cssKib: num(raw.resourceBudgets, "cssKib", "resourceBudgets"),
+    imageKib: num(raw.resourceBudgets, "imageKib", "resourceBudgets"),
+    totalKib: num(raw.resourceBudgets, "totalKib", "resourceBudgets"),
+  };
+
+  const allowlistRaw = raw.thirdPartyScriptAllowlist;
+  if (!Array.isArray(allowlistRaw) || !allowlistRaw.every((h) => typeof h === "string")) {
+    throw new Error("perf budgets: thirdPartyScriptAllowlist must be a string[]");
+  }
+  const thirdPartyScriptAllowlist = allowlistRaw.map((h) => h.toLowerCase());
+
+  if (!Array.isArray(raw.routes) || raw.routes.length === 0) {
+    throw new Error("perf budgets: manifest.routes must be a non-empty array");
+  }
+  const routes: RouteBudgetDef[] = raw.routes.map((r, i) => {
+    if (!isRecord(r)) throw new Error(`perf budgets: routes[${i}] must be an object`);
+    const id = r.id;
+    if (typeof id !== "string" || !(ROUTE_IDS as readonly string[]).includes(id)) {
+      throw new Error(`perf budgets: routes[${i}].id "${String(id)}" is not a known RouteId`);
+    }
+    if (typeof r.label !== "string" || typeof r.samplePath !== "string") {
+      throw new Error(`perf budgets: routes[${i}] needs string label + samplePath`);
+    }
+    if (!Array.isArray(r.match) || !r.match.every((m) => typeof m === "string") || r.match.length === 0) {
+      throw new Error(`perf budgets: routes[${i}].match must be a non-empty string[]`);
+    }
+    return {
+      id: id as RouteId,
+      label: r.label,
+      samplePath: r.samplePath,
+      match: r.match as string[],
+      ...(r.resourceBudgets !== undefined
+        ? { resourceBudgets: partialResources(r.resourceBudgets, `routes[${i}]`) }
+        : {}),
+      ...(r.webVitals !== undefined
+        ? { webVitals: partialWebVitals(r.webVitals, `routes[${i}]`) }
+        : {}),
+    };
+  });
+
+  const seen = new Set<string>();
+  for (const r of routes) {
+    if (seen.has(r.id)) throw new Error(`perf budgets: duplicate route id "${r.id}"`);
+    seen.add(r.id);
+  }
+
+  return { version, webVitals, resourceBudgets, thirdPartyScriptAllowlist, routes };
+}
+
+/** The validated, checked-in manifest. */
+export const PERF_BUDGETS: PerfBudgetManifest = parsePerfBudgets(manifestJson);
+
+// ---------------------------------------------------------------------------
+// Route classification (shared lab + field)
+// ---------------------------------------------------------------------------
+
+/**
+ * Bucket a URL pathname into a budgeted route id (or "other"). Matching is by
+ * the manifest's `match` prefixes; the `"="` sentinel matches only the exact
+ * root. Order follows the manifest, but the root sentinel and longer prefixes
+ * are unambiguous so order rarely matters.
+ */
+export function classifyPath(
+  pathname: string,
+  manifest: PerfBudgetManifest = PERF_BUDGETS,
+): RouteClass {
+  // Normalize: strip a trailing slash (except root) and lowercase.
+  let p = pathname.toLowerCase();
+  if (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
+  for (const route of manifest.routes) {
+    for (const m of route.match) {
+      if (m === "=") {
+        if (p === "" || p === "/") return route.id;
+      } else if (p === m || p.startsWith(m.endsWith("/") ? m : `${m}/`) || p === m.replace(/\/$/, "")) {
+        return route.id;
+      }
+    }
+  }
+  return "other";
+}
+
+// ---------------------------------------------------------------------------
+// Budget resolution + evaluation
+// ---------------------------------------------------------------------------
+
+/** Resolve a route's effective budget (manifest defaults + per-route overrides). */
+export function resolveRouteBudget(
+  routeId: RouteId,
+  manifest: PerfBudgetManifest = PERF_BUDGETS,
+): ResolvedRouteBudget {
+  const def = manifest.routes.find((r) => r.id === routeId);
+  if (!def) throw new Error(`perf budgets: no route "${routeId}" in manifest`);
+  return {
+    id: def.id,
+    label: def.label,
+    samplePath: def.samplePath,
+    webVitals: { ...manifest.webVitals, ...def.webVitals },
+    resourceBudgets: { ...manifest.resourceBudgets, ...def.resourceBudgets },
+  };
+}
+
+const RESOURCE_METRICS: readonly (keyof ResourceBudget)[] = [
+  "jsKib",
+  "cssKib",
+  "imageKib",
+  "totalKib",
+];
+
+/** Evaluate ONE route's measurement against its resolved budget. Pure. */
+export function evaluateRoute(
+  measurement: RouteMeasurement,
+  manifest: PerfBudgetManifest = PERF_BUDGETS,
+): BudgetViolation[] {
+  const budget = resolveRouteBudget(measurement.routeId, manifest);
+  const violations: BudgetViolation[] = [];
+
+  const res = measurement.resources ?? {};
+  for (const metric of RESOURCE_METRICS) {
+    const actual = res[metric];
+    if (typeof actual === "number" && actual > budget.resourceBudgets[metric]) {
+      violations.push({
+        routeId: measurement.routeId,
+        metric,
+        budget: budget.resourceBudgets[metric],
+        actual,
+      });
+    }
+  }
+
+  const wv = measurement.webVitals ?? {};
+  for (const metric of ["lcpMs", "inpMs", "cls"] as const) {
+    const actual = wv[metric];
+    if (typeof actual === "number" && actual > budget.webVitals[metric]) {
+      violations.push({
+        routeId: measurement.routeId,
+        metric,
+        budget: budget.webVitals[metric],
+        actual,
+      });
+    }
+  }
+
+  if (measurement.thirdPartyOrigins?.length) {
+    const allow = new Set(manifest.thirdPartyScriptAllowlist);
+    const offenders = measurement.thirdPartyOrigins
+      .map((o) => o.toLowerCase())
+      .filter((o) => !allow.has(o));
+    if (offenders.length) {
+      violations.push({
+        routeId: measurement.routeId,
+        metric: "thirdParty",
+        budget: 0,
+        actual: offenders.length,
+        detail: offenders.join(", "),
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Evaluate a full report (measurements for some/all budgeted routes). `passed`
+ * is true only when there are ZERO violations. Missing routes are reported but
+ * do NOT fail the gate on their own — a partial lab run (e.g. account/checkout
+ * need auth) still enforces the routes it did measure. The harness decides
+ * whether missing routes are fatal for a given run (`--require-all`).
+ */
+export function evaluateManifest(
+  measurements: readonly RouteMeasurement[],
+  manifest: PerfBudgetManifest = PERF_BUDGETS,
+): BudgetReport {
+  const byRoute = new Map<RouteId, RouteMeasurement>();
+  for (const m of measurements) byRoute.set(m.routeId, m);
+
+  const results: RouteBudgetResult[] = [];
+  const allViolations: BudgetViolation[] = [];
+  for (const m of measurements) {
+    const violations = evaluateRoute(m, manifest);
+    results.push({ routeId: m.routeId, passed: violations.length === 0, violations });
+    allViolations.push(...violations);
+  }
+
+  const missingRoutes = manifest.routes.map((r) => r.id).filter((id) => !byRoute.has(id));
+
+  return {
+    passed: allViolations.length === 0,
+    results,
+    violations: allViolations,
+    missingRoutes,
+  };
+}
+
+/** Human-readable summary for CLI / CI logs. */
+export function formatBudgetReport(report: BudgetReport): string {
+  const lines: string[] = [];
+  lines.push(report.passed ? "✓ performance budgets: PASS" : "✗ performance budgets: FAIL");
+  for (const r of report.results) {
+    if (r.passed) {
+      lines.push(`  ✓ ${r.routeId}`);
+    } else {
+      lines.push(`  ✗ ${r.routeId}`);
+      for (const v of r.violations) {
+        const detail = v.detail ? ` (${v.detail})` : "";
+        lines.push(
+          `      ${v.metric}: ${v.actual} > budget ${v.budget}${detail}`,
+        );
+      }
+    }
+  }
+  if (report.missingRoutes.length) {
+    lines.push(`  · no measurement for: ${report.missingRoutes.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Lighthouse budgets exporter (documented lab seam)
+// ---------------------------------------------------------------------------
+
+/** One entry of a Lighthouse `budget.json` (the format `--budget-path` reads). */
+export interface LighthouseBudgetEntry {
+  path: string;
+  timings: { metric: string; budget: number }[];
+  resourceSizes: { resourceType: string; budget: number }[];
+}
+
+/**
+ * Derive a Lighthouse-native budgets array from the manifest, one entry per
+ * budgeted route. Feed it to Lighthouse (`--budget-path`) / LHCI so a lab run
+ * enforces the SAME numbers this module does. Lighthouse resource budgets are
+ * in KiB and its timing budgets in ms — matching our manifest units.
+ *
+ * Note: Lighthouse's LCP/CLS assertions are LAB metrics; INP has no lab
+ * equivalent (it needs real interaction), so INP is enforced via field RUM
+ * (rumAlert.ts), not here. We emit `interactive` as the closest lab proxy.
+ */
+export function toLighthouseBudgets(
+  manifest: PerfBudgetManifest = PERF_BUDGETS,
+): LighthouseBudgetEntry[] {
+  return manifest.routes.map((r) => {
+    const b = resolveRouteBudget(r.id, manifest);
+    return {
+      path: b.samplePath.split("?")[0] ?? "/",
+      timings: [
+        { metric: "largest-contentful-paint", budget: b.webVitals.lcpMs },
+        { metric: "cumulative-layout-shift", budget: b.webVitals.cls },
+      ],
+      resourceSizes: [
+        { resourceType: "script", budget: b.resourceBudgets.jsKib },
+        { resourceType: "stylesheet", budget: b.resourceBudgets.cssKib },
+        { resourceType: "image", budget: b.resourceBudgets.imageKib },
+        { resourceType: "total", budget: b.resourceBudgets.totalKib },
+      ],
+    };
+  });
+}

package/apps/storefront/src/lib/analytics/rumAlert.ts

@@ -0,0 +1,179 @@
+/**
+ * F14 — RUM regression-alert contract.
+ *
+ * The field beacon (`webVitals.ts`) emits per-route CWV samples; this module is
+ * the PURE sink-side logic that turns a window of those samples into regression
+ * alerts. It is the code half of F16's `core-web-vitals` monitor: F16's manifest
+ * declares WHAT is watched (p75 per metric per key template, threshold "past
+ * 'good'", runbook), and names F14's beacon as the source; this decides, from
+ * the samples, WHETHER the threshold tripped.
+ *
+ * Deliberately pure + transport-agnostic: it takes an array of `WebVitalsSample`
+ * and returns `RegressionAlert[]`. WHERE the samples come from (a Workers
+ * Analytics Engine query, a KV rollup, a Logpush aggregation) and WHERE the
+ * alerts go (PagerDuty, Slack, a Logpush alert rule) are the sink's job — this
+ * is the contract both sides agree on, and the only part worth unit-testing.
+ *
+ * The p75 percentile + the 1-hour sustain window match F16's threshold text and
+ * Google/CrUX convention. The window itself (which hour of samples) is chosen by
+ * the caller; a low-traffic bucket is suppressed by `minSamples` so a single
+ * bad sample never pages anyone.
+ */
+import {
+  PERF_BUDGETS,
+  type PerfBudgetManifest,
+  type RouteId,
+} from "./perfBudgets.js";
+import {
+  rateMetric,
+  type WebVitalName,
+  type WebVitalRating,
+  type WebVitalsSample,
+} from "./webVitals.js";
+
+/**
+ * The F16 monitor this contract feeds. Referenced by id, NOT imported from
+ * `monitoring/manifest.ts` — F14 owns the signal, F16 owns the monitor; keeping
+ * the coupling to a string means neither unit imports the other's files.
+ */
+export const CWV_MONITOR_ID = "core-web-vitals";
+
+/** Alert severity, mirroring F16's `Severity` (kept local to avoid the import). */
+export type AlertSeverity = "page" | "critical" | "warning" | "info";
+
+/** The p75 rollup for one route bucket over the caller's window. */
+export interface RouteVitalsP75 {
+  route: RouteId;
+  /** Number of samples that fed this bucket (across all three metrics). */
+  sampleCount: number;
+  /** p75 per metric, or undefined when the window had no sample for it. */
+  p75: Partial<Record<WebVitalName, number>>;
+}
+
+/** One regression: a route's p75 for a metric crossed out of `good`. */
+export interface RegressionAlert {
+  /** Always `core-web-vitals` — the F16 monitor an operator opens. */
+  monitorId: typeof CWV_MONITOR_ID;
+  route: RouteId;
+  metric: WebVitalName;
+  /** The observed p75 that tripped the alert. */
+  p75: number;
+  /** The `good` budget line it crossed. */
+  budget: number;
+  /** `needs-improvement` (warning) or `poor` (critical). */
+  rating: Exclude<WebVitalRating, "good">;
+  severity: AlertSeverity;
+  sampleCount: number;
+}
+
+export interface DetectOptions {
+  /**
+   * Minimum samples in a route bucket before it can alert — guards low-traffic
+   * routes from paging on noise. Default 50 (a stable-ish p75).
+   */
+  minSamples?: number;
+}
+
+/**
+ * Exact-rank percentile (nearest-rank, p in [0,1]) over a numeric series.
+ * Small windows are fine — this is O(n log n) and the series is one route-hour.
+ */
+export function percentile(values: readonly number[], p: number): number | undefined {
+  if (values.length === 0) return undefined;
+  const sorted = [...values].sort((a, b) => a - b);
+  const rank = Math.ceil(p * sorted.length);
+  const idx = Math.min(Math.max(rank, 1), sorted.length) - 1;
+  return sorted[idx];
+}
+
+const METRICS: readonly WebVitalName[] = ["lcp", "inp", "cls"];
+
+/**
+ * Roll a flat sample list up into per-route p75s. Samples whose route is
+ * `"other"` (unbudgeted) are dropped — we only alert on budgeted templates.
+ */
+export function aggregateP75(samples: readonly WebVitalsSample[]): RouteVitalsP75[] {
+  const byRoute = new Map<RouteId, Map<WebVitalName, number[]>>();
+  for (const s of samples) {
+    if (s.route === "other") continue;
+    let metrics = byRoute.get(s.route);
+    if (!metrics) {
+      metrics = new Map();
+      byRoute.set(s.route, metrics);
+    }
+    const series = metrics.get(s.metric) ?? [];
+    series.push(s.value);
+    metrics.set(s.metric, series);
+  }
+
+  const out: RouteVitalsP75[] = [];
+  for (const [route, metrics] of byRoute) {
+    const p75: Partial<Record<WebVitalName, number>> = {};
+    let sampleCount = 0;
+    for (const metric of METRICS) {
+      const series = metrics.get(metric);
+      if (!series?.length) continue;
+      sampleCount += series.length;
+      const v = percentile(series, 0.75);
+      if (v !== undefined) p75[metric] = v;
+    }
+    out.push({ route, sampleCount, p75 });
+  }
+  return out;
+}
+
+function severityFor(rating: Exclude<WebVitalRating, "good">): AlertSeverity {
+  // A `poor` p75 is customer-visible degradation → same-hours critical; a
+  // `needs-improvement` p75 is the leading-indicator warning F16 describes.
+  return rating === "poor" ? "critical" : "warning";
+}
+
+/**
+ * The contract: given a window of field samples, return the regressions. A
+ * regression is a budgeted route whose p75 for some metric rates worse than
+ * `good`, in a bucket with enough samples to trust. Zero regressions ⇒ the
+ * `core-web-vitals` monitor stays green.
+ */
+export function detectRegressions(
+  samples: readonly WebVitalsSample[],
+  manifest: PerfBudgetManifest = PERF_BUDGETS,
+  opts: DetectOptions = {},
+): RegressionAlert[] {
+  const minSamples = opts.minSamples ?? 50;
+  const budgets: Record<WebVitalName, number> = {
+    lcp: manifest.webVitals.lcpMs,
+    inp: manifest.webVitals.inpMs,
+    cls: manifest.webVitals.cls,
+  };
+
+  const alerts: RegressionAlert[] = [];
+  for (const bucket of aggregateP75(samples)) {
+    if (bucket.sampleCount < minSamples) continue;
+    for (const metric of METRICS) {
+      const p75 = bucket.p75[metric];
+      if (p75 === undefined) continue;
+      const rating = rateMetric(metric, p75, manifest);
+      if (rating === "good") continue;
+      alerts.push({
+        monitorId: CWV_MONITOR_ID,
+        route: bucket.route,
+        metric,
+        p75,
+        budget: budgets[metric],
+        rating,
+        severity: severityFor(rating),
+        sampleCount: bucket.sampleCount,
+      });
+    }
+  }
+  return alerts;
+}
+
+/** One-line alert summary for a log line / notification body. */
+export function formatRegressionAlert(a: RegressionAlert): string {
+  const unit = a.metric === "cls" ? "" : "ms";
+  return (
+    `[${a.severity}] ${a.monitorId}: ${a.route} ${a.metric.toUpperCase()} ` +
+    `p75 ${a.p75}${unit} > budget ${a.budget}${unit} (${a.rating}, n=${a.sampleCount})`
+  );
+}