rolldown-perf-kit 0.0.0-stage → 0.1.0

package/lib/field/analysis.mjs

@@ -0,0 +1,225 @@
+// Pure analysis for field runs (a deployed site, a real login, a real network):
+// the request the LCP waited for, the script chain that started it, paired
+// statistics across alternating variants, chunk-level coverage that needs no
+// sourcemap, and URL redaction. No browser access here, so all of it is testable.
+
+import { coverageBounds, executedIntervals } from '../coverage.mjs';
+import { median, quantile } from '../measure.mjs';
+
+// --- redaction -------------------------------------------------------------------
+// Field output comes from a real account. Identifiers in URLs (account, zone and
+// user IDs, emails, long numbers) are replaced before anything is written.
+
+const DEFAULT_REDACTIONS = [
+  [/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '<uuid>'],
+  [/[0-9a-f]{16,}/gi, '<hex>'],
+  [/[^\s/?&=@:]+?(?:@|%40)[^\s/?&=]+\.[a-z]{2,}/gi, '<email>'],
+  [/(?<![\w.])\d{6,}(?![\w])/g, '<n>'],
+];
+
+export function makeRedactor(extraPatterns = []) {
+  const rules = [
+    ...DEFAULT_REDACTIONS,
+    ...extraPatterns.map((source) => [new RegExp(source, 'g'), '<redacted>']),
+  ];
+  return (value) => {
+    if (typeof value !== 'string') return value;
+    let out = value;
+    for (const [re, replacement] of rules) out = out.replace(re, replacement);
+    return out;
+  };
+}
+
+// --- critical path ---------------------------------------------------------------
+
+const isDataRequest = (r) => r.type === 'Fetch' || r.type === 'XHR';
+
+/**
+ * The data request the LCP most likely waited for: the fetch/XHR that finished
+ * last before LCP (within `windowMs`), or the last one matching `pattern` when the
+ * config pins it. The automatic choice is a heuristic - `candidates` lists the
+ * runners-up so a wrong pick is visible, and `gate` in the config fixes it.
+ */
+export function findGate(requests, lcpMs, { pattern = null, windowMs = 1500 } = {}) {
+  if (typeof lcpMs !== 'number') return { gate: null, reason: 'no LCP', candidates: [] };
+  let pool = requests.filter(
+    (r) => isDataRequest(r) && !r.failed && typeof r.endMs === 'number' && r.endMs <= lcpMs,
+  );
+  if (pattern) pool = pool.filter((r) => r.url.includes(pattern));
+  else pool = pool.filter((r) => lcpMs - r.endMs <= windowMs);
+  pool.sort((a, b) => b.endMs - a.endMs);
+  const candidates = pool.slice(0, 3).map((r) => ({ url: r.url, endMs: r.endMs }));
+  if (!pool.length) {
+    return {
+      gate: null,
+      reason: pattern
+        ? `no request matching "${pattern}" finished before LCP`
+        : `no fetch/XHR finished within ${windowMs}ms before LCP`,
+      candidates,
+    };
+  }
+  return { gate: pool[0], reason: pattern ? 'pinned by config' : 'auto', candidates };
+}
+
+/**
+ * The script a request had to wait for. A request cannot start before every
+ * script on its initiator stack has loaded, so of all the scripts on the stack
+ * (sync frames and async parents) the one whose download ended last is the
+ * bottleneck. A fetch wrapper on top of the stack is then skipped automatically
+ * when the real caller loaded later.
+ */
+export function criticalInitiatorUrl(req, requests) {
+  const urls = [
+    ...new Set([...(req.initiator?.frames ?? []).map((f) => f.url), req.initiator?.url]),
+  ].filter(Boolean);
+  let best = null;
+  for (const url of urls) {
+    const loaded = requests.find((r) => r.url === url && !r.failed);
+    if (loaded && (!best || (loaded.endMs ?? -1) > (best.endMs ?? -1))) best = loaded;
+  }
+  return best?.url ?? urls[0] ?? null;
+}
+
+/**
+ * Walk initiators back from a request: the script it waited for, the script that
+ * loaded that script, and so on to the document. Each step keeps its fetch
+ * window, which is what turns "the request started late" into the exact
+ * waterfall of chunk loads in front of it.
+ */
+export function initiatorChain(requests, startUrl, maxDepth = 12) {
+  const chain = [];
+  const seen = new Set();
+  let url = startUrl;
+  while (url && !seen.has(url) && chain.length < maxDepth) {
+    seen.add(url);
+    const req = requests.find((r) => r.url === url && !r.failed);
+    if (!req) {
+      chain.push({
+        url,
+        type: 'unknown',
+        note: 'no request recorded for this URL (inline or cached)',
+      });
+      break;
+    }
+    chain.push({
+      url: req.url,
+      type: req.type,
+      startMs: req.startMs,
+      endMs: req.endMs,
+      initiatorType: req.initiator?.type ?? null,
+    });
+    if (req.type === 'Document') break;
+    url = criticalInitiatorUrl(req, requests);
+  }
+  return chain;
+}
+
+/**
+ * Split one run's LCP at its gate: the client time before the gate request
+ * started (also measured from the end of the document, which removes a slower
+ * HTML response of one variant's server), the time to first byte, the
+ * download, and the client time after it. Only the client parts can move with
+ * a front-end change.
+ */
+export function criticalPath(requests, lcpMs, options = {}) {
+  const found = findGate(requests, lcpMs, options);
+  if (!found.gate) return { ...found, breakdown: null, chain: [] };
+  const g = found.gate;
+  const sendStart = g.sendStartMs ?? g.startMs;
+  const headersEnd = g.headersEndMs ?? null;
+  const doc =
+    requests.find((r) => r.navigation && !r.failed) ??
+    requests.find((r) => r.type === 'Document' && !r.failed);
+  return {
+    gate: { url: g.url, method: g.method, startMs: g.startMs, endMs: g.endMs },
+    reason: found.reason,
+    candidates: found.candidates,
+    breakdown: {
+      documentEndMs: round(doc?.endMs ?? null),
+      beforeGateMs: round(g.startMs),
+      gateAfterDocumentMs: doc?.endMs == null ? null : round(g.startMs - doc.endMs),
+      ttfbMs: headersEnd == null ? null : round(headersEnd - sendStart),
+      downloadMs: headersEnd == null ? null : round(g.endMs - headersEnd),
+      afterGateMs: round(lcpMs - g.endMs),
+    },
+    chain: initiatorChain(requests, criticalInitiatorUrl(g, requests)),
+  };
+}
+
+// --- statistics ------------------------------------------------------------------
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Paired comparison of alternating runs: pair i holds one run of each variant,
+ * measured back to back, so slow minutes of the network hit both sides. Reports
+ * the median paired delta (candidate - base; negative = candidate faster), a
+ * seeded bootstrap 90% interval of that median, and the win count.
+ */
+export function pairedDelta(pairs, { resamples = 2000, seed = 1 } = {}) {
+  const deltas = pairs
+    .filter(([a, b]) => typeof a === 'number' && typeof b === 'number')
+    .map(([a, b]) => b - a);
+  if (!deltas.length) return null;
+  const rand = mulberry32(seed);
+  const medians = [];
+  for (let i = 0; i < resamples; i++) {
+    const draw = deltas.map(() => deltas[Math.floor(rand() * deltas.length)]);
+    medians.push(median(draw));
+  }
+  return {
+    pairs: deltas.length,
+    medianDeltaMs: round(median(deltas)),
+    ci90Ms: [round(quantile(medians, 0.05)), round(quantile(medians, 0.95))],
+    candidateFaster: deltas.filter((d) => d < 0).length,
+  };
+}
+
+/** Values above `factor` x the median, for n >= 3. A slow server minute, not the build. */
+export function outlierIndexes(values, factor = 3) {
+  const nums = values.filter((v) => typeof v === 'number');
+  if (nums.length < 3) return [];
+  const mid = median(nums);
+  return values.flatMap((v, i) => (typeof v === 'number' && v > factor * mid ? [i] : []));
+}
+
+// --- chunk-level coverage ----------------------------------------------------------
+
+function unionLength(a, b) {
+  const all = [...a, ...b].sort((x, y) => x.start - y.start);
+  let total = 0;
+  let current = null;
+  for (const interval of all) {
+    if (current && interval.start <= current.end) current.end = Math.max(current.end, interval.end);
+    else {
+      if (current) total += current.end - current.start;
+      current = { ...interval };
+    }
+  }
+  if (current) total += current.end - current.start;
+  return total;
+}
+
+/**
+ * Executed bytes of one served script at the cut and by settle, from V8 ranges
+ * and the response body alone. Works for every chunk, with or without a matching
+ * local build - module attribution is what needs the build.
+ */
+export function chunkCoverage({ bytes, atCut, atSettle }) {
+  const cut = atCut ? executedIntervals(coverageBounds(atCut)) : [];
+  const settle = atSettle ? executedIntervals(coverageBounds(atSettle)) : [];
+  const cutBytes = Math.min(bytes, unionLength(cut, []));
+  const settleBytes = Math.min(bytes, unionLength(cut, settle));
+  return { bytes, cutBytes, settleBytes, cutRatio: bytes ? cutBytes / bytes : 0 };
+}
+
+export const round = (v) => (typeof v === 'number' ? Math.round(v) : null);

package/lib/field/browser.mjs

@@ -0,0 +1,232 @@
+// Browser access for field runs. The lab launches a throwaway headless Chrome;
+// a deployed site behind a login needs the user's own browser instead, because
+// copied cookies rarely survive device-bound sessions and bot checks. So field
+// mode ATTACHES to a running Chrome over CDP and works in the browser context
+// (profile) of a tab that already shows the site.
+//
+// Endpoint, in order: --cdp-url ws://..., --cdp-port N, or the DevToolsActivePort
+// file that Chrome writes when remote debugging is on (chrome://inspect/#remote-debugging).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { connect } from '../cdp.mjs';
+
+function activePortFiles() {
+  const home = os.homedir();
+  const dirs = [
+    process.env.CHROME_USER_DATA_DIR,
+    path.join(home, 'Library', 'Application Support', 'Google', 'Chrome'),
+    path.join(home, 'Library', 'Application Support', 'Google', 'Chrome Canary'),
+    path.join(home, '.config', 'google-chrome'),
+    path.join(home, '.config', 'chromium'),
+    process.env.LOCALAPPDATA &&
+      path.join(process.env.LOCALAPPDATA, 'Google', 'Chrome', 'User Data'),
+  ].filter(Boolean);
+  return dirs.map((dir) => path.join(dir, 'DevToolsActivePort'));
+}
+
+export async function resolveEndpoint({ cdpUrl, cdpPort } = {}) {
+  if (cdpUrl) return cdpUrl;
+  if (cdpPort) {
+    const res = await fetch(`http://127.0.0.1:${cdpPort}/json/version`);
+    return (await res.json()).webSocketDebuggerUrl;
+  }
+  for (const file of activePortFiles()) {
+    if (!fs.existsSync(file)) continue;
+    const [port, wsPath] = fs.readFileSync(file, 'utf8').trim().split('\n');
+    if (port && wsPath) return `ws://127.0.0.1:${port}${wsPath}`;
+  }
+  throw new Error(
+    'no running Chrome with remote debugging found. Turn it on at chrome://inspect/#remote-debugging,\n' +
+      'or start Chrome with --remote-debugging-port=<n> and pass --cdp-port <n>.',
+  );
+}
+
+export async function attachBrowser(options) {
+  const wsUrl = await resolveEndpoint(options);
+  const cdp = await connect(wsUrl);
+  return { cdp, close: async () => cdp.close() };
+}
+
+/** The browser context of an open tab on `origin`: that profile holds the login. */
+export async function contextForOrigin(cdp, origin) {
+  const { targetInfos } = await cdp.send('Target.getTargets');
+  const tab = targetInfos.find((t) => t.type === 'page' && t.url.startsWith(origin));
+  return tab ? { browserContextId: tab.browserContextId, found: true } : { found: false };
+}
+
+// --- cookies -------------------------------------------------------------------------
+// Variant cookies change the whole profile, not only the measuring tab, so the
+// original values are saved first and restored at the end (also on Ctrl-C).
+// Values stay in memory only; nothing here is printed.
+
+const domainMatches = (cookieDomain, host) => {
+  const d = cookieDomain.replace(/^\./, '');
+  return host === d || host.endsWith(`.${d}`);
+};
+
+export async function snapshotCookies(cdp, { browserContextId, origin, names }) {
+  const host = new URL(origin).hostname;
+  const { cookies } = await cdp.send(
+    'Storage.getCookies',
+    browserContextId ? { browserContextId } : {},
+  );
+  const saved = new Map();
+  for (const name of names) {
+    saved.set(name, cookies.find((c) => c.name === name && domainMatches(c.domain, host)) ?? null);
+  }
+  return saved;
+}
+
+const cookieParam = (c) => ({
+  name: c.name,
+  value: c.value,
+  domain: c.domain,
+  path: c.path,
+  secure: c.secure,
+  httpOnly: c.httpOnly,
+  ...(c.sameSite ? { sameSite: c.sameSite } : {}),
+  ...(c.session ? {} : { expires: c.expires }),
+});
+
+/**
+ * Where a variant cookie lands: the config's domain/path, else those of the
+ * user's cookie of the same name. A null domain is a host-only cookie on the
+ * origin. CDP treats a domain without a leading dot as host-only too.
+ */
+const variantScope = (cookie, existing) => ({
+  domain: cookie.domain ?? existing?.domain ?? null,
+  path: cookie.path ?? existing?.path ?? '/',
+});
+
+/**
+ * Put back each saved cookie. A variant cookie in another scope than the saved
+ * one (or a name the user did not have) is deleted with an expired cookie in the
+ * scope the variant used: `url` for host-only cookies, `domain` otherwise.
+ */
+export async function restoreCookies(cdp, { browserContextId, origin, saved, configured = [] }) {
+  const host = new URL(origin).hostname;
+  const cookies = [];
+  for (const [name, original] of saved) {
+    if (original) cookies.push(cookieParam(original));
+    const scopes = new Map();
+    for (const c of configured.filter((x) => x.name === name)) {
+      const scope = variantScope(c, original);
+      scopes.set(`${scope.domain ?? host} ${scope.path}`, scope);
+    }
+    for (const [key, scope] of scopes) {
+      if (original && key === `${original.domain} ${original.path}`) continue;
+      cookies.push({
+        name,
+        value: '',
+        path: scope.path,
+        ...(scope.domain ? { domain: scope.domain } : { url: origin }),
+        expires: 1,
+      });
+    }
+  }
+  if (cookies.length) {
+    await cdp.send('Storage.setCookies', {
+      cookies,
+      ...(browserContextId ? { browserContextId } : {}),
+    });
+  }
+}
+
+// --- measuring tab ---------------------------------------------------------------------
+
+/**
+ * A new window in the chosen profile, configured like the lab tab: cache off,
+ * service worker bypassed, blocked URLs, the variant's cookies, init scripts.
+ * A variant cookie reuses the domain/path of the user's existing cookie of the
+ * same name, so the profile never ends up with two cookies of that name.
+ * `configured` holds the cookies of all variants, for the reset to the saved state.
+ * `bodies` raises the response buffers so script bodies stay readable for
+ * build matching (diagnostic runs only).
+ */
+export async function openFieldPage(
+  cdp,
+  {
+    browserContextId,
+    origin,
+    cookies = [],
+    saved = new Map(),
+    configured = [],
+    block = [],
+    scripts = [],
+    bodies = false,
+    throttle = null,
+  },
+) {
+  const { targetId } = await cdp.send('Target.createTarget', {
+    url: 'about:blank',
+    newWindow: true,
+    ...(browserContextId ? { browserContextId } : {}),
+  });
+  const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
+  // A covered or background window is "hidden", and Chrome stops reporting LCP
+  // for hidden pages. Bring the window to the front; runs still check visibility.
+  await cdp.send('Target.activateTarget', { targetId }).catch(() => {});
+  const send = (method, params) => cdp.send(method, params, sessionId);
+  await send('Page.enable');
+  await send('Runtime.enable');
+  await send(
+    'Network.enable',
+    bodies ? { maxTotalBufferSize: 400_000_000, maxResourceBufferSize: 64_000_000 } : {},
+  );
+  await send('Network.setCacheDisabled', { cacheDisabled: true });
+  await send('Network.setBypassServiceWorker', { bypass: true }).catch(() => {});
+  if (block.length) {
+    await send('Network.setBlockedURLs', {
+      urls: block.map((p) => (p.includes('*') ? p : `*${p}*`)),
+    });
+  }
+  if (throttle) {
+    await send('Network.emulateNetworkConditions', {
+      offline: false,
+      latency: throttle.latencyMs,
+      downloadThroughput: throttle.downloadBps,
+      uploadThroughput: throttle.uploadBps,
+    });
+    await send('Emulation.setCPUThrottlingRate', { rate: throttle.cpuRate });
+  }
+  // Each run starts from the user's own cookies: a cookie that an earlier variant
+  // set must not stay for a variant that does not set it.
+  if (saved.size) await restoreCookies(cdp, { browserContextId, origin, saved, configured });
+  const secure = origin.startsWith('https:');
+  for (const cookie of cookies) {
+    const existing = saved.get(cookie.name);
+    const scope = variantScope(cookie, existing);
+    await send('Network.setCookie', {
+      url: origin,
+      secure: existing?.secure ?? secure,
+      ...cookie,
+      path: scope.path,
+      ...(scope.domain ? { domain: scope.domain } : {}),
+    });
+  }
+  for (const source of scripts) {
+    await send('Page.addScriptToEvaluateOnNewDocument', { source });
+  }
+  return {
+    send,
+    on: (method, handler) => cdp.on(method, handler, sessionId),
+    navigate: (url) => send('Page.navigate', { url }),
+    async evaluate(expression) {
+      const result = await send('Runtime.evaluate', {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+      });
+      if (result.exceptionDetails) {
+        throw new Error(
+          `page evaluate threw: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`,
+        );
+      }
+      return result.result.value;
+    },
+    close: () => cdp.send('Target.closeTarget', { targetId }),
+  };
+}

package/lib/field/build-match.mjs

@@ -0,0 +1,86 @@
+// Match the scripts a deployed site served to the files of a local build, so a
+// field run can use that build's sourcemaps and module graph. Production rarely
+// serves its maps; a local build of the same commit with the same settings often
+// emits byte-identical chunks. Identity is decided by content, never by name:
+// - exact:          same path, same SHA-256
+// - renamed:        another path in the build has the same SHA-256
+// - debug-id:       the served file names a //# debugId that a local map carries
+// - different-build: the path exists locally with other content (wrong commit,
+//                   settings or bundler version - the usual cause)
+// - not-in-build:   no local file has this path or content
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const sha256 = (text) => crypto.createHash('sha256').update(text).digest('hex');
+// A line of its own, often followed by the //# sourceMappingURL line.
+const DEBUG_ID_RE = /^\/\/# debugId=([0-9a-fA-F-]{36})[ \t]*$/m;
+
+function walk(dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, out);
+    else if (/\.[mc]?js$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+/** Hash every emitted script of a build once. Maps are read lazily, on a match. */
+export function indexBuild(dir) {
+  const byPath = new Map();
+  const bySha = new Map();
+  const byDebugId = new Map();
+  for (const file of walk(dir)) {
+    const rel = path.relative(dir, file).replaceAll('\\', '/');
+    const code = fs.readFileSync(file, 'utf8');
+    const sha = sha256(code);
+    byPath.set(rel, sha);
+    if (!bySha.has(sha)) bySha.set(sha, rel);
+    const debugId = code.match(DEBUG_ID_RE)?.[1]?.toLowerCase();
+    if (debugId) byDebugId.set(debugId, rel);
+  }
+  return { dir, byPath, bySha, byDebugId };
+}
+
+/** Decide which local file (if any) a served script is. `file` has no leading slash. */
+export function matchScript(index, { file, body }) {
+  if (!index) return { status: 'no-build' };
+  const sha = sha256(body);
+  if (index.byPath.get(file) === sha) return { status: 'exact', local: file };
+  const renamed = index.bySha.get(sha);
+  if (renamed) return { status: 'renamed', local: renamed };
+  const debugId = body.match(DEBUG_ID_RE)?.[1]?.toLowerCase();
+  if (debugId && index.byDebugId.has(debugId)) {
+    return { status: 'debug-id', local: index.byDebugId.get(debugId) };
+  }
+  return { status: index.byPath.has(file) ? 'different-build' : 'not-in-build' };
+}
+
+/** Code + sourcemap of a matched local file, in the shape attributeChunks expects. */
+export function readMatched(index, match) {
+  if (!match?.local) return null;
+  const file = path.join(index.dir, match.local);
+  const mapFile = `${file}.map`;
+  if (!fs.existsSync(mapFile)) return null;
+  return {
+    code: fs.readFileSync(file, 'utf8'),
+    map: JSON.parse(fs.readFileSync(mapFile, 'utf8')),
+  };
+}
+
+/** Counts and bytes per match status - how much of the page the build explains. */
+export function matchSummary(matches) {
+  const summary = { scripts: 0, bytes: 0, matchedScripts: 0, matchedBytes: 0, byStatus: {} };
+  for (const { status, bytes } of matches) {
+    summary.scripts += 1;
+    summary.bytes += bytes;
+    summary.byStatus[status] = (summary.byStatus[status] ?? 0) + 1;
+    if (status === 'exact' || status === 'renamed' || status === 'debug-id') {
+      summary.matchedScripts += 1;
+      summary.matchedBytes += bytes;
+    }
+  }
+  return summary;
+}