rolldown-perf-kit 0.0.0-stage → 0.1.0

package/lib/build.mjs

@@ -0,0 +1,57 @@
+// Builds the demo app with the repo's rolldown (packages/rolldown/dist), devtools
+// report mode on, so every build also refreshes the build-side metrics report
+// (entry bytes, initial-load bytes, delta/baselineDelta) next to the runtime numbers.
+// The report lands in the app's node_modules/.rolldown/report/dist.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { reportDirFor } from './module-graph.mjs';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const ROLLDOWN_DIST =
+  process.env.ROLLDOWN_DIST ?? path.join(REPO_ROOT, 'packages', 'rolldown', 'dist', 'index.mjs');
+
+export async function buildApp({ appDir }) {
+  if (!fs.existsSync(ROLLDOWN_DIST)) {
+    throw new Error(
+      `rolldown dist not found at ${ROLLDOWN_DIST} - run \`just build-rolldown\` first (or set ROLLDOWN_DIST).`,
+    );
+  }
+  const { build } = await import(pathToFileURL(ROLLDOWN_DIST).href);
+  const distDir = path.join(appDir, 'dist');
+  fs.rmSync(distDir, { recursive: true, force: true });
+  const started = Date.now();
+  await build({
+    cwd: appDir,
+    input: { main: './src/main.ts' },
+    devtools: { mode: 'report' },
+    output: {
+      dir: 'dist',
+      format: 'esm',
+      sourcemap: true,
+      minify: false, // keep offsets readable; relative deltas match minified builds
+      entryFileNames: '[name].js',
+      chunkFileNames: 'chunks/[name]-[hash].js',
+    },
+  });
+  fs.copyFileSync(path.join(appDir, 'index.html'), path.join(distDir, 'index.html'));
+
+  const entryBytes = fs.statSync(path.join(distDir, 'main.js')).size;
+  const chunksDir = path.join(distDir, 'chunks');
+  const chunks = fs.existsSync(chunksDir)
+    ? fs
+        .readdirSync(chunksDir)
+        .filter((f) => f.endsWith('.js'))
+        .map((f) => ({ file: `chunks/${f}`, bytes: fs.statSync(path.join(chunksDir, f)).size }))
+    : [];
+  let buildMetrics = null;
+  try {
+    const reportDir = reportDirFor(appDir, 'dist');
+    buildMetrics = JSON.parse(fs.readFileSync(path.join(reportDir, 'metrics.json'), 'utf8'));
+  } catch {
+    // metrics report is best-effort; the harness still works without it
+  }
+  return { distDir, entryBytes, chunks, buildMetrics, wallMs: Date.now() - started };
+}

package/lib/cdp.mjs

@@ -0,0 +1,217 @@
+// Minimal Chrome DevTools Protocol client over Node's built-in WebSocket (Node >= 22).
+// No dependencies: launches headless Chrome/Edge with a throwaway profile, parses the
+// "DevTools listening on ws://..." line, and exposes flat-protocol page sessions.
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CHROME_CANDIDATES = [
+  process.env.CHROME_PATH,
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+  process.env.LOCALAPPDATA &&
+    path.join(process.env.LOCALAPPDATA, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+  'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+  '/usr/bin/google-chrome',
+  '/usr/bin/chromium',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+].filter(Boolean);
+
+export function findChrome() {
+  for (const candidate of CHROME_CANDIDATES) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error('No Chrome/Edge executable found. Set CHROME_PATH to a Chromium binary.');
+}
+
+/** `extraArgs`: more Chrome switches (the replay maps every host to its server). */
+export async function launchBrowser({ profileDir, extraArgs = [] }) {
+  if (typeof WebSocket === 'undefined') {
+    throw new Error(
+      `This harness needs Node >= 22 (global WebSocket); running ${process.version}.`,
+    );
+  }
+  const exe = findChrome();
+  fs.rmSync(profileDir, { recursive: true, force: true });
+  fs.mkdirSync(profileDir, { recursive: true });
+  const child = spawn(
+    exe,
+    [
+      '--headless=new',
+      '--remote-debugging-port=0',
+      `--user-data-dir=${profileDir}`,
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--disable-background-networking',
+      '--disable-component-update',
+      '--disable-sync',
+      '--disable-default-apps',
+      '--mute-audio',
+      '--window-size=1280,900',
+      ...extraArgs,
+      'about:blank',
+    ],
+    { stdio: ['ignore', 'ignore', 'pipe'] },
+  );
+  // Registered before anything else can run, so close() never waits for an exit
+  // that already happened.
+  const exited = new Promise((resolve) => child.once('exit', resolve));
+
+  const wsUrl = await new Promise((resolve, reject) => {
+    let stderr = '';
+    const timer = setTimeout(() => {
+      cleanup();
+      child.kill();
+      reject(new Error(`Chrome did not announce a DevTools endpoint within 20s.\n${stderr}`));
+    }, 20_000);
+    const onData = (chunk) => {
+      stderr += chunk;
+      const match = stderr.match(/DevTools listening on (ws:\/\/\S+)/);
+      if (match) {
+        cleanup();
+        resolve(match[1]);
+      }
+    };
+    const onExit = (code) => {
+      cleanup();
+      reject(
+        new Error(`Chrome exited before announcing DevTools endpoint (code ${code}).\n${stderr}`),
+      );
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      child.stderr.off('data', onData);
+      child.off('exit', onExit);
+    };
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', onData);
+    child.on('exit', onExit);
+  });
+
+  const cdp = await connect(wsUrl);
+  return {
+    cdp,
+    pid: child.pid,
+    /**
+     * Resolves only after the Chrome process has exited. Chrome keeps writing its
+     * profile directory while it shuts down; removing that directory before the exit
+     * fails with ENOTEMPTY. SIGTERM lets it flush; a browser that is still alive
+     * after 5 s gets SIGKILL, and close() still waits for the exit.
+     */
+    async close() {
+      try {
+        cdp.close();
+      } catch {
+        /* already closed */
+      }
+      if (child.exitCode === null && child.signalCode === null) child.kill();
+      const forceKill = setTimeout(() => child.kill('SIGKILL'), 5_000);
+      await exited;
+      clearTimeout(forceKill);
+    },
+  };
+}
+
+/**
+ * Flat JSON-RPC client for a DevTools endpoint. Exported because Node's inspector
+ * speaks the same protocol on the same transport — `lib/node/launch.mjs` attaches
+ * to `Debugger listening on ws://…` with this exact client, minus the page domains.
+ */
+export function connect(wsUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(wsUrl);
+    let nextId = 1;
+    const pending = new Map();
+    const listeners = new Map(); // `${sessionId}:${method}` -> handlers
+    ws.addEventListener('open', () => resolve(api));
+    ws.addEventListener('error', () => reject(new Error(`WebSocket connection failed: ${wsUrl}`)));
+    ws.addEventListener('message', (event) => {
+      const msg = JSON.parse(event.data);
+      if (msg.id === undefined) {
+        const key = `${msg.sessionId ?? ''}:${msg.method}`;
+        for (const handler of listeners.get(key) ?? []) handler(msg.params);
+        return;
+      }
+      const entry = pending.get(msg.id);
+      if (!entry) return;
+      pending.delete(msg.id);
+      if (msg.error) entry.reject(new Error(`${entry.method}: ${msg.error.message}`));
+      else entry.resolve(msg.result);
+    });
+    const api = {
+      send(method, params = {}, sessionId) {
+        return new Promise((res, rej) => {
+          const id = nextId++;
+          pending.set(id, { resolve: res, reject: rej, method });
+          ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+        });
+      },
+      on(method, handler, sessionId = '') {
+        const key = `${sessionId}:${method}`;
+        if (!listeners.has(key)) listeners.set(key, []);
+        const handlers = listeners.get(key);
+        handlers.push(handler);
+        return () => {
+          const index = handlers.indexOf(handler);
+          if (index === -1) return;
+          handlers.splice(index, 1);
+          if (!handlers.length) listeners.delete(key);
+        };
+      },
+      close() {
+        ws.close();
+      },
+    };
+  });
+}
+
+/** Fresh tab configured for a measurement: cache off, optional throttle, optional init script. */
+export async function openPage(cdp, { throttle, injectScript } = {}) {
+  const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' });
+  const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
+  const send = (method, params) => cdp.send(method, params, sessionId);
+  await send('Page.enable');
+  await send('Runtime.enable');
+  await send('Network.enable');
+  await send('Network.setCacheDisabled', { cacheDisabled: true });
+  // PWAs install a service worker on the first run; without this, later runs are
+  // served from SW cache (setCacheDisabled does not cover it) and measure faster
+  // than a cold visitor ever would.
+  await send('Network.setBypassServiceWorker', { bypass: true }).catch(() => {});
+  if (throttle) {
+    await send('Network.emulateNetworkConditions', {
+      offline: false,
+      latency: throttle.latencyMs,
+      downloadThroughput: throttle.downloadBps,
+      uploadThroughput: throttle.uploadBps,
+    });
+    await send('Emulation.setCPUThrottlingRate', { rate: throttle.cpuRate });
+  }
+  if (injectScript) {
+    await send('Page.addScriptToEvaluateOnNewDocument', { source: injectScript });
+  }
+  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) {
+        const detail =
+          result.exceptionDetails.exception?.description ??
+          result.exceptionDetails.text ??
+          'unknown error';
+        throw new Error(`page evaluate threw: ${detail}`);
+      }
+      return result.result.value;
+    },
+    close: () => cdp.send('Target.closeTarget', { targetId }),
+  };
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/lib/chunk-discovery.mjs

@@ -0,0 +1,226 @@
+// Join emitted static chunk imports to the runtime waterfall. A discovery delay
+// is a lead to test, not a predicted LCP gain or proof that paint awaits a chunk.
+// The waterfall is a lab scan's Resource Timing list, or the CDP requests of field
+// and replay runs (requestSamples).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { median } from './measure.mjs';
+
+/** Prefer a current emitted graph; Vite's manifest supplies the same static edges. */
+export function loadChunkGraph(dist, candidates = []) {
+  const manifestFile = path.join(dist, '.vite', 'manifest.json');
+  const manifestMtime = fs.existsSync(manifestFile) ? fs.statSync(manifestFile).mtimeMs : 0;
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    const graphMtime = fs.statSync(file).mtimeMs;
+    if (graphMtime < manifestMtime) continue;
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (data.schemaVersion !== 1 || !Array.isArray(data.chunks) || !data.chunks.length) continue;
+    const files = new Map();
+    for (const chunk of data.chunks) {
+      // Metrics filenames may include the build's relative output directory.
+      // Match a path suffix only when it names a real file inside this dist.
+      const parts = chunk.fileName.replaceAll('\\', '/').split('/');
+      for (let i = 0; i < parts.length; i++) {
+        const name = parts.slice(i).join('/');
+        const resolved = path.resolve(dist, name);
+        if (!resolved.startsWith(`${path.resolve(dist)}${path.sep}`)) continue;
+        const stat = fs.existsSync(resolved) ? fs.statSync(resolved) : null;
+        if (stat?.isFile() && stat.mtimeMs <= graphMtime) {
+          files.set(chunk.fileName, name);
+          break;
+        }
+      }
+    }
+    // Rebuilds can reuse filenames. The graph must also follow the emitted files
+    // and the manifest so old imports cannot produce a false all-clear.
+    if (files.size !== data.chunks.length) continue;
+    return {
+      file,
+      chunks: new Map(
+        data.chunks.map((chunk) => [
+          files.get(chunk.fileName),
+          {
+            facadeModuleId: chunk.facadeModuleId ?? null,
+            imports: (chunk.imports ?? []).map((name) => files.get(name)).filter(Boolean),
+          },
+        ]),
+      ),
+    };
+  }
+  const file = manifestFile;
+  if (!fs.existsSync(file)) return null;
+  const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const rows = Object.values(manifest).filter((chunk) => /\.[cm]?js$/.test(chunk.file ?? ''));
+  if (
+    !rows.length ||
+    rows.some((chunk) => {
+      const file = path.join(dist, chunk.file);
+      const stat = fs.existsSync(file) ? fs.statSync(file) : null;
+      return !stat?.isFile() || stat.mtimeMs > manifestMtime;
+    })
+  )
+    return null;
+  return {
+    file,
+    chunks: new Map(
+      rows.map((chunk) => [
+        chunk.file,
+        {
+          facadeModuleId: chunk.src ?? null,
+          imports: (chunk.imports ?? []).map((key) => manifest[key]?.file).filter(Boolean),
+        },
+      ]),
+    ),
+  };
+}
+
+/** Keep one shortest static import chain per descendant, excluding cycles. */
+function staticDescendants(graph, root) {
+  const paths = new Map([[root, [root]]]);
+  const queue = [root];
+  for (let i = 0; i < queue.length; i++) {
+    const parent = queue[i];
+    for (const file of graph.chunks.get(parent)?.imports ?? []) {
+      if (paths.has(file)) continue;
+      paths.set(file, [...paths.get(parent), file]);
+      queue.push(file);
+    }
+  }
+  paths.delete(root);
+  return paths;
+}
+
+/**
+ * Field and replay runs as discovery samples. Their CDP request rows (page time,
+ * every request of the page) stand in for the Resource Timing list, which field
+ * runs do not keep. `redact` cleans initiator URLs: a document URL can name an account.
+ */
+export function requestSamples(runs, origin, redact = (value) => value) {
+  const local = (url) => (url?.startsWith(`${origin}/`) ? url.slice(origin.length) : url);
+  return runs.map((run) => ({
+    fcp: run.fcp ?? null,
+    lcp: run.lcp ?? null,
+    resourceDetailsComplete: true,
+    resources: (run.requests ?? []).map((r) => ({
+      name: local(r.url),
+      type: String(r.type ?? 'other').toLowerCase(),
+      start: r.startMs ?? 0,
+      // end 0 = unfinished or failed, as in the Resource Timing list.
+      end: r.failed || typeof r.endMs !== 'number' ? 0 : r.endMs,
+      bytes: r.encodedBytes ?? 0,
+      initiator: { type: r.initiator?.type ?? null, url: redact(local(r.initiator?.url ?? null)) },
+      requestPriority: { initial: r.priority ?? null, last: r.lastPriority ?? r.priority ?? null },
+    })),
+  }));
+}
+
+export function analyzeChunkDiscovery(graph, samples, latencyMs) {
+  return Object.fromEntries(
+    ['fcp', 'lcp'].map((paint) => [paint, analyzePaintDiscovery(graph, samples, latencyMs, paint)]),
+  );
+}
+
+function analyzePaintDiscovery(graph, samples, latencyMs, paint) {
+  const complete = samples.length > 0 && samples.every((s) => s.resourceDetailsComplete === true);
+  if (!graph) return { state: 'unknown', reason: 'no chunk graph or Vite manifest', groups: [] };
+  if (typeof latencyMs !== 'number' || latencyMs <= 0) {
+    return {
+      state: 'unknown',
+      reason: 'no throttled RTT reference',
+      graphFile: graph.file,
+      groups: [],
+    };
+  }
+  const groups = new Map();
+  const matchedCounts = [];
+  let paintedRuns = 0;
+  for (const sample of samples) {
+    if (typeof sample[paint] !== 'number') continue;
+    paintedRuns++;
+    const requests = new Map();
+    for (const resource of sample.resources ?? []) {
+      // Same-origin names are relative. Cross-origin scripts can have identical
+      // basenames but do not belong to this build's graph.
+      if (resource.type !== 'script' || !resource.name.startsWith('/') || resource.end <= 0)
+        continue;
+      let file;
+      try {
+        file = decodeURIComponent(resource.name.split(/[?#]/)[0].slice(1));
+      } catch {
+        continue;
+      }
+      if (!graph.chunks.has(file)) continue;
+      const previous = requests.get(file);
+      if (!previous || resource.start < previous.start) requests.set(file, resource);
+    }
+    matchedCounts.push(requests.size);
+    for (const [parent, request] of requests) {
+      if (request.end > sample[paint]) continue;
+      const late = [];
+      for (const [file, importChain] of staticDescendants(graph, parent)) {
+        const child = requests.get(file);
+        if (!child || child.end > sample[paint] || child.start - request.end <= latencyMs) continue;
+        late.push({
+          file,
+          facadeModuleId: graph.chunks.get(file)?.facadeModuleId ?? null,
+          importChain,
+          startMs: child.start,
+          endMs: child.end,
+          delayMs: child.start - request.end,
+          bytes: child.bytes,
+          initiator: child.initiator ?? null,
+          requestPriority: child.requestPriority ?? null,
+        });
+      }
+      if (!late.length) continue;
+      late.sort((a, b) => b.bytes - a.bytes || a.file.localeCompare(b.file));
+      if (!groups.has(parent)) groups.set(parent, []);
+      groups.get(parent).push({
+        paintMs: sample[paint],
+        parentEndMs: request.end,
+        bytes: late.reduce((sum, r) => sum + r.bytes, 0),
+        count: late.length,
+        maxDelayMs: Math.max(...late.map((r) => r.delayMs)),
+        chunks: late,
+      });
+    }
+  }
+  const rows = [...groups]
+    .map(([parent, runs]) => {
+      const sorted = runs.slice().sort((a, b) => a.bytes - b.bytes);
+      return {
+        parent,
+        facadeModuleId: graph.chunks.get(parent)?.facadeModuleId ?? null,
+        paintDependency: 'unverified',
+        runsAffected: runs.length,
+        measuredRuns: paintedRuns,
+        bytes: median(runs.map((r) => r.bytes)),
+        count: median(runs.map((r) => r.count)),
+        maxDelayMs: median(runs.map((r) => r.maxDelayMs)),
+        // Keep an actual run's edges and timings; do not invent a median waterfall.
+        example: sorted[Math.floor(sorted.length / 2)],
+      };
+    })
+    .sort(
+      (a, b) =>
+        b.bytes - a.bytes || b.maxDelayMs - a.maxDelayMs || a.parent.localeCompare(b.parent),
+    );
+  const matchedScripts = median(matchedCounts) ?? 0;
+  const reason = !complete
+    ? 'resource details missing or browser timing buffer overflow'
+    : paintedRuns !== samples.length
+      ? `${paint.toUpperCase()} missing in one or more runs`
+      : matchedCounts.some((count) => count === 0)
+        ? 'no runtime scripts matched the chunk graph in one or more runs'
+        : null;
+  return {
+    state: reason ? 'unknown' : rows.length ? 'open' : 'clear',
+    reason,
+    graphFile: graph.file,
+    latencyMs,
+    matchedScripts,
+    groups: rows,
+  };
+}