rolldown-perf-kit 0.0.0-stage → 0.1.0

package/lib/rolldown-support.mjs

@@ -0,0 +1,161 @@
+// The app's rolldown must carry the devtools report mode, or no build writes the report
+// and graph / what-if / cut / why / graph-diff have nothing to read. The npm release does
+// not carry it yet; this checkout's packages/rolldown does. Two things live here: the probe
+// that names the app's rolldown and whether it has the mode, and the install that copies
+// the checkout's build over the copy the app's vite resolves, whatever the package manager
+// laid out (bun and npm hoist a real directory, pnpm symlinks into its store).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const LAB_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+// The sibling package is this checkout's packages/rolldown only when the lab runs from the
+// repo. An installed copy sits under node_modules, where the sibling is the app's own release.
+export const CHECKOUT_ROLLDOWN = /[\\/]node_modules[\\/]/.test(LAB_DIR)
+  ? null
+  : path.resolve(LAB_DIR, '..', 'rolldown');
+// What a built package carries (the npm tarball leaves dist/*.node out; the install keeps it,
+// because the loader tries dist/rolldown-binding.<platform>.node before the binding package).
+const PACKAGE_PARTS = ['dist', 'bin', 'cli', 'package.json', 'LICENSE'];
+
+const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+const REPORT_MODE = /mode\?:\s*['"]full['"]\s*\|\s*['"]report['"]/;
+
+/** True when a package's type declarations offer `mode: 'report'` for devtools. */
+export function hasReportMode(pkgDir) {
+  const dist = path.join(pkgDir, 'dist');
+  if (!fs.existsSync(dist)) return false;
+  const stack = [dist];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) stack.push(file);
+      else if (/\.d\.[cm]?ts$/.test(entry.name) && REPORT_MODE.test(fs.readFileSync(file, 'utf8')))
+        return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * The rolldown package the app's vite resolves (the app's own when vite is absent):
+ * `{ dir, version, viteVersion, reportMode }`; `dir` is null when none resolves.
+ */
+export function appRolldown(appDir) {
+  const fromApp = createRequire(path.join(appDir, 'package.json'));
+  let viteDir = null;
+  let viteVersion = null;
+  try {
+    const vitePkg = fromApp.resolve('vite/package.json');
+    viteDir = path.dirname(fs.realpathSync(vitePkg));
+    viteVersion = readJson(vitePkg).version;
+  } catch {
+    /* no vite: resolve from the app itself */
+  }
+  let pkgFile = null;
+  for (const from of [viteDir, appDir]) {
+    if (!from) continue;
+    try {
+      pkgFile = createRequire(path.join(from, 'package.json')).resolve('rolldown/package.json');
+      break;
+    } catch {
+      /* try the next base */
+    }
+  }
+  if (!pkgFile) return { dir: null, version: null, viteVersion, reportMode: false };
+  const dir = path.dirname(fs.realpathSync(pkgFile));
+  return { dir, version: readJson(pkgFile).version, viteVersion, reportMode: hasReportMode(dir) };
+}
+
+/** This checkout's packages/rolldown: `{ dir, version, built, binding, reportMode }`, or null when none (or `dir` is null). */
+export function checkoutRolldown(dir = CHECKOUT_ROLLDOWN) {
+  if (!dir) return null;
+  const pkgFile = path.join(dir, 'package.json');
+  if (!fs.existsSync(pkgFile)) return null;
+  const dist = path.join(dir, 'dist');
+  const built = fs.existsSync(path.join(dist, 'index.mjs'));
+  const binding = built
+    ? (fs.readdirSync(dist).find((f) => /^rolldown-binding\..+\.node$/.test(f)) ?? null)
+    : null;
+  return {
+    dir,
+    version: readJson(pkgFile).version,
+    built,
+    binding,
+    reportMode: built && hasReportMode(dir),
+  };
+}
+
+/**
+ * Why no build of this app writes the report, with the fix, or null when its rolldown has
+ * the report mode. `cli` is how to spell the harness in the hint.
+ */
+export function reportSupportNote(appDir, cli, { checkout = CHECKOUT_ROLLDOWN } = {}) {
+  const app = appRolldown(appDir);
+  if (app.reportMode) return null;
+  const rel = path.relative(process.cwd(), appDir);
+  const appRel = !rel ? '.' : rel.startsWith('..') ? appDir : rel;
+  if (!app.dir) {
+    return `no rolldown package resolves from ${appDir} - install the app's dependencies first (vite >= 8 brings rolldown).`;
+  }
+  const src = checkoutRolldown(checkout);
+  const lines = [
+    `rolldown ${app.version} at ${app.dir} has no devtools report mode, so no build of this app writes the report`,
+    '(the npm release does not carry it yet; graph / what-if / cut / why / graph-diff need it).',
+  ];
+  if (src?.built && src.binding) {
+    lines.push(
+      `Install the build next to the lab (rolldown ${src.version}) over it, then rebuild:`,
+      `  ${cli} rolldown-install --app ${appRel}`,
+      '(`<package manager> install --force` in the app restores the release later.)',
+    );
+  } else if (src) {
+    lines.push(
+      `The rolldown package next to the lab, ${src.dir}, is not built: run \`just build-rolldown-release\` there,`,
+      `then \`${cli} rolldown-install --app ${appRel}\` copies it over the app's copy.`,
+    );
+  } else {
+    lines.push(
+      'No rolldown package sits next to the lab. Build one in a rolldown checkout (`just build-rolldown-release`',
+      `writes packages/rolldown), then \`${cli} rolldown-install --app ${appRel} --from <that packages/rolldown>\`.`,
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Copy the checkout's built package over the copy the app's vite resolves. Each part is
+ * removed before the copy: pnpm hard-links its store, and a write in place would change
+ * every project that shares the file. Returns `{ from, dir, before, after }`.
+ */
+export function installCheckoutRolldown(appDir, { checkout = CHECKOUT_ROLLDOWN } = {}) {
+  const app = appRolldown(appDir);
+  if (!app.dir)
+    throw new Error(
+      `no rolldown package resolves from ${appDir} - install the app's dependencies first.`,
+    );
+  const src = checkoutRolldown(checkout);
+  if (!src) {
+    throw new Error(
+      checkout
+        ? `no rolldown package at ${checkout}`
+        : 'no rolldown package sits next to the lab: pass --from <a built packages/rolldown>.',
+    );
+  }
+  if (!src.built || !src.binding) {
+    throw new Error(
+      `${src.dir} is not built (dist/index.mjs and dist/rolldown-binding.*.node): run \`just build-rolldown-release\` in the checkout first.`,
+    );
+  }
+  for (const part of PACKAGE_PARTS) {
+    const from = path.join(src.dir, part);
+    if (!fs.existsSync(from)) continue;
+    const to = path.join(app.dir, part);
+    fs.rmSync(to, { recursive: true, force: true });
+    fs.cpSync(from, to, { recursive: true, dereference: true });
+  }
+  return { from: src, dir: app.dir, before: app.version, after: appRolldown(appDir) };
+}

package/lib/serve.mjs

@@ -0,0 +1,142 @@
+// Static file server for the built app. Port 0 = ephemeral (measure/coverage runs);
+// `/blank.html` is synthesized so coverage can arm the profiler on a same-origin page
+// before index.html loads (keeps the renderer process, and thus V8 coverage, alive).
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+};
+
+// Cross-origin isolation: wasm-threaded apps (SQLite wasm, ffmpeg.wasm) need
+// SharedArrayBuffer, which browsers only enable under COOP+COEP — without these
+// headers such apps show a fatal error instead of a first paint (found via
+// Actual Budget). COEP 'credentialless' (not 'require-corp') keeps cross-origin
+// subresources like third-party fonts loading, so non-wasm apps measure
+// identically to before.
+const ISOLATION_HEADERS = {
+  'cross-origin-opener-policy': 'same-origin',
+  'cross-origin-embedder-policy': 'credentialless',
+  'cross-origin-resource-policy': 'cross-origin',
+};
+
+// Real deployments compress text assets; serving a 16MB bundle raw would
+// overcharge the throttled lab by 3-4x versus what any user's wire sees
+// (found via drawDB). transfer_bytes reads encodedBodySize, so metrics report
+// compressed bytes - same as production.
+const COMPRESSIBLE = new Set([
+  '.html',
+  '.js',
+  '.mjs',
+  '.css',
+  '.json',
+  '.map',
+  '.svg',
+  '.txt',
+  '.webmanifest',
+  '.wasm',
+]);
+
+function wantsGzip(req, ext) {
+  return COMPRESSIBLE.has(ext) && /\bgzip\b/.test(req.headers['accept-encoding'] ?? '');
+}
+
+// Deliberately contentless: the warm-up page must never fire FCP/LCP, or a
+// coverage/measure poll racing the next navigation could read the blank page's
+// paint entries as the app's.
+const BLANK_HTML = '<!doctype html><title>blank</title>';
+
+// Navigations get what a real static host gives them: a directory's index.html, a
+// sibling .html for an extensionless path (multi-page entries), and finally the
+// root index.html (SPA history routes, which parity loads by path). Subresource
+// misses stay 404 - an API fetch must never start receiving HTML it didn't get
+// before, or a measurement would change under the app.
+function resolveFile(rootDir, pathname, navigation) {
+  const inRoot = (file) =>
+    (file === rootDir || file.startsWith(rootDir + path.sep)) &&
+    fs.existsSync(file) &&
+    fs.statSync(file).isFile();
+  const direct = path.normalize(path.join(rootDir, pathname === '/' ? '/index.html' : pathname));
+  if (inRoot(direct)) return direct;
+  if (!navigation) return null;
+  const fallbacks = [path.join(direct, 'index.html')];
+  if (!path.extname(pathname)) fallbacks.push(`${direct}.html`, path.join(rootDir, 'index.html'));
+  return fallbacks.map((file) => path.normalize(file)).find(inRoot) ?? null;
+}
+
+/**
+ * `root` may be a function: parity serves the original build and the candidate
+ * from ONE origin (neither may render a different `location`), swapping the root
+ * between captures.
+ */
+export function startServer(root, port = 0) {
+  const rootOf = typeof root === 'function' ? root : () => root;
+  const server = http.createServer((req, res) => {
+    let pathname;
+    try {
+      pathname = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
+    } catch {
+      res.writeHead(400).end('bad request');
+      return;
+    }
+    if (pathname === '/blank.html') {
+      res.writeHead(200, {
+        'content-type': MIME['.html'],
+        'cache-control': 'no-store',
+        ...ISOLATION_HEADERS,
+      });
+      res.end(BLANK_HTML);
+      return;
+    }
+    const file = resolveFile(
+      path.normalize(rootOf()),
+      pathname,
+      req.headers['sec-fetch-mode'] === 'navigate',
+    );
+    if (!file) {
+      res.writeHead(404).end('not found');
+      return;
+    }
+    const ext = path.extname(file).toLowerCase();
+    const headers = {
+      'content-type': MIME[ext] ?? 'application/octet-stream',
+      'cache-control': 'no-store',
+      ...ISOLATION_HEADERS,
+    };
+    if (wantsGzip(req, ext)) {
+      res.writeHead(200, { ...headers, 'content-encoding': 'gzip' });
+      fs.createReadStream(file)
+        .pipe(zlib.createGzip({ level: 6 }))
+        .pipe(res);
+    } else {
+      res.writeHead(200, headers);
+      fs.createReadStream(file).pipe(res);
+    }
+  });
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      const actualPort = server.address().port;
+      resolve({
+        port: actualPort,
+        origin: `http://127.0.0.1:${actualPort}`,
+        // Chrome can keep a socket open with no finished request; server.close()
+        // alone waits for it until requestTimeout (300 s).
+        close: () =>
+          new Promise((r) => {
+            server.close(r);
+            server.closeAllConnections();
+          }),
+      });
+    });
+  });
+}

package/lib/worker/attrib.mjs

@@ -0,0 +1,125 @@
+// Startup CPU by EVALUATING module, from a profile taken on an attribution build (the
+// same environment built with `preserveModules`, every module its own file).
+//
+// Two things make this build necessary. V8 attaches line ticks to a frame only when
+// source positions exist, which in practice means optimized code; the top-level frame
+// of a bundled chunk usually has none, so its self time cannot be split by module. And
+// ESM evaluation is not a call stack: a library's top-level work has no importer frame
+// above it. With one file per module, the root-most frame under the output dir IS the
+// module whose evaluation is running, and the build report's importer chain says where
+// the import to cut lives.
+
+import path from 'node:path';
+
+import { localFile } from './measure.mjs';
+
+const isLab = (rel) => !rel || rel.startsWith('__lab') || rel.startsWith('_virtual/');
+
+/**
+ * `graph` (optional) is the loaded module graph of the attribution build; with it every
+ * row carries the chain from the entry. Returns rows sorted by time: `{ module, ms, chain }`,
+ * `pairs` (evaluating module -> library file the time is spent in) and `self` by file.
+ */
+export function evaluatingModules(profile, { outDir, graph = null, top = 20 }) {
+  const nodes = new Map(profile.nodes.map((n) => [n.id, n]));
+  const parent = new Map();
+  for (const n of profile.nodes) for (const c of n.children ?? []) parent.set(c, n.id);
+  const rel = (url) => {
+    const file = localFile(url, outDir);
+    return file ? path.relative(outDir, file).replaceAll('\\', '/') : null;
+  };
+  const evaluating = new Map();
+  const pairs = new Map();
+  const self = new Map();
+  const add = (m, k, v) => m.set(k, (m.get(k) ?? 0) + v);
+  profile.samples.forEach((id, i) => {
+    const delta = profile.timeDeltas[i] ?? 0;
+    if (delta <= 0) return;
+    const leaf = nodes.get(id);
+    const fn = leaf?.callFrame.functionName;
+    if (fn === '(idle)' || fn === '(program)') return;
+    const leafFile = rel(leaf?.callFrame.url);
+    add(
+      self,
+      leafFile ?? (fn === '(garbage collector)' ? '(gc)' : leaf?.callFrame.url || '(engine)'),
+      delta,
+    );
+    let cur = id;
+    let root = null;
+    while (cur != null) {
+      const f = rel(nodes.get(cur)?.callFrame.url);
+      if (f && !isLab(f)) root = f;
+      cur = parent.get(cur);
+    }
+    add(evaluating, root ?? (fn === '(garbage collector)' ? '(gc)' : '(no module frame)'), delta);
+    if (root && leafFile && leafFile !== root && !isLab(leafFile)) {
+      add(pairs, `${root} -> ${leafFile.replace(/^node_modules\//, '')}`, delta);
+    }
+  });
+  const ms = (v) => Math.round(v / 100) / 10;
+  const sorted = (m) => [...m.entries()].sort((a, b) => b[1] - a[1]);
+  const chainOf = graph ? graphChainResolver(graph) : () => null;
+  return {
+    rows: sorted(evaluating)
+      .slice(0, top)
+      .map(([module, us]) => ({ module, ms: ms(us), chain: chainOf(module) })),
+    pairs: sorted(pairs)
+      .slice(0, top)
+      .map(([pair, us]) => ({ pair, ms: ms(us) })),
+    self: sorted(self)
+      .slice(0, top)
+      .map(([file, us]) => ({ file, ms: ms(us) })),
+  };
+}
+
+/** Match an output file of the attribution build to a graph id and walk up to the entry. */
+export function graphChainResolver(graph) {
+  const norm = (id) =>
+    String(id)
+      .replace(/^(\.\.\/)+/, '')
+      .replace(/^node_modules\//, '')
+      .replace(/\.[cm]?[jt]sx?$/, '');
+  const byKey = new Map(graph.modules.map((m, i) => [norm(m.id), i]));
+  return (file) => {
+    const i = byKey.get(norm(file));
+    if (i == null) return null;
+    const chain = [];
+    let cur = i;
+    const seen = new Set();
+    while (cur != null && !seen.has(cur)) {
+      seen.add(cur);
+      const m = graph.modules[cur];
+      const up = m.idom != null && m.idom >= 0 ? m.idom : (graph.staticPreds[cur] ?? [])[0];
+      if (up == null || up === cur) break;
+      chain.push(up);
+      cur = up;
+    }
+    return chain
+      .reverse()
+      .map((j) => graph.modules[j].id)
+      .filter((id) => !/^(\\0|\0)/.test(id));
+  };
+}
+
+/** Direct static importers of a module and one chain from the entry: the "why" view. */
+export function whyModule(graph, index) {
+  const name = (i) => graph.modules[i].id;
+  const preds = graph.staticPreds[index] ?? [];
+  const chain = [];
+  let cur = index;
+  const seen = new Set();
+  while (cur != null && !seen.has(cur)) {
+    seen.add(cur);
+    const m = graph.modules[cur];
+    const up = m.idom != null && m.idom >= 0 ? m.idom : (graph.staticPreds[cur] ?? [])[0];
+    if (up == null || up === cur) break;
+    chain.push(up);
+    cur = up;
+  }
+  return {
+    module: name(index),
+    bytes: graph.modules[index].bytes ?? 0,
+    importers: preds.map((p) => ({ module: name(p), bytes: graph.modules[p].bytes ?? 0 })),
+    chain: chain.reverse().map(name),
+  };
+}

package/lib/worker/config.mjs

@@ -0,0 +1,116 @@
+// The Vite config shim: builds the app with the rolldown metrics report on EVERY
+// environment (one directory per output dir), sourcemaps on the worker environment, and two
+// variants behind environment variables - a worker-only rebuild for the loop and the
+// preserveModules attribution build. It wraps the app's own config without editing it.
+//
+// Every environment must carry the report: the devtools tracer is process-global, and an
+// environment built without it in the same process writes a full JSON-lines log under
+// node_modules/.rolldown/unknown-session (hundreds of MB on a real app).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SHIM_FILE = 'perf-kit.vite.config.ts';
+export const ATTRIB_DIR = 'dist-attrib';
+
+export function viteConfigShim(baseConfigFile) {
+  return `// Written by perf-kit (worker-config). Wraps ${baseConfigFile} without editing it.
+//   npx vite build --config ${SHIM_FILE}                         full build, report per environment
+//   ROLLDOWN_PERF_KIT_WORKER_ONLY=1 npx vite build --config ${SHIM_FILE}  rebuild only the worker environment
+//   ROLLDOWN_PERF_KIT_ATTRIB=1 npx vite build --config ${SHIM_FILE}       attribution build into ${ATTRIB_DIR}/ (preserveModules)
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { mergeConfig } from 'vite';
+import base from './${baseConfigFile.replace(/\.[cm]?[jt]s$/, '')}';
+
+// A rolldown without the report mode takes \`devtools\` as the plain tracer and writes the
+// full event log (hundreds of MB per build) instead of the report. Refuse to build on one.
+function assertReportMode() {
+  const here = createRequire(import.meta.url);
+  let from = here;
+  try { from = createRequire(path.dirname(fs.realpathSync(here.resolve('vite/package.json')))); } catch {}
+  const pkg = JSON.parse(fs.readFileSync(from.resolve('rolldown/package.json'), 'utf8'));
+  const dist = path.join(path.dirname(fs.realpathSync(from.resolve('rolldown/package.json'))), 'dist');
+  const stack = [dist];
+  while (stack.length) {
+    const dir = stack.pop()!;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const f = path.join(dir, e.name);
+      if (e.isDirectory()) stack.push(f);
+      else if (/\\.d\\.[cm]?ts$/.test(e.name) && /mode\\?:\\s*['"]full['"]\\s*\\|\\s*['"]report['"]/.test(fs.readFileSync(f, 'utf8'))) return;
+    }
+  }
+  throw new Error(
+    \`perf-kit: rolldown \${pkg.version} at \${dist} has no devtools report mode; a build with this config would write the full event log instead of the report. Run \\\`rolldown-install --app <appDir>\\\` first (\\\`--from <built packages/rolldown>\\\` when no checkout sits next to the lab).\`,
+  );
+}
+
+export default async (env: any) => {
+  assertReportMode();
+  const resolved = typeof base === 'function' ? await (base as any)(env) : await base;
+  const attrib = process.env.ROLLDOWN_PERF_KIT_ATTRIB === '1';
+  const workerOnly = attrib || process.env.ROLLDOWN_PERF_KIT_WORKER_ONLY === '1';
+  return mergeConfig(resolved, {
+    ...(workerOnly
+      ? {
+          builder: {
+            buildApp: async (builder: any) => {
+              for (const name of Object.keys(builder.environments)) {
+                if (name !== 'client') await builder.build(builder.environments[name]);
+              }
+            },
+          },
+        }
+      : {}),
+    plugins: [
+      {
+        name: 'perf-kit',
+        generateBundle(_options: any, bundle: Record<string, any>) {
+          // rolldown's preserveModules output ends every CommonJS file with an eager
+          // \`export default require_x();\`. In a require cycle that call reaches a wrapper whose
+          // file has not run yet ("require_x is not a function"), and the attribution build
+          // throws at import (rolldown#11348). Its importers use the named wrapper, so this build drops the eager
+          // line; the cycle then resolves at the require site, as in node. The line is the last
+          // one of the file, so the sourcemap of the lines above stays right. The entry keeps
+          // its default export: that is the Worker's interface, and the lab imports it.
+          if (!attrib) return;
+          for (const chunk of Object.values(bundle)) {
+            if (chunk.type !== 'chunk' || chunk.isEntry) continue;
+            const code = chunk.code.replace(/^export default require_[\\w$]+\\(\\);\\n?/m, '');
+            if (code !== chunk.code) chunk.code = code;
+          }
+        },
+        configEnvironment(name: string) {
+          const worker = name !== 'client';
+          return {
+            build: {
+              ...(attrib && worker ? { outDir: \`${ATTRIB_DIR}/\${name}\`, minify: false } : {}),
+              sourcemap: worker,
+              rolldownOptions: {
+                ...(attrib && worker
+                  ? { output: { preserveModules: true, preserveModulesRoot: '.', entryFileNames: '[name].js', chunkFileNames: '[name].js' } }
+                  : {}),
+                devtools: { mode: 'report' },
+              },
+            },
+          };
+        },
+      },
+    ],
+  });
+};
+`;
+}
+
+/** Write the shim next to the app's vite config. Returns `{ file, baseConfigFile, existed }`. */
+export function writeViteConfigShim(appDir, { force = false } = {}) {
+  const base = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'].find(
+    (f) => fs.existsSync(path.join(appDir, f)),
+  );
+  if (!base) throw new Error(`no vite.config.{ts,mts,js,mjs} in ${appDir}`);
+  const file = path.join(appDir, SHIM_FILE);
+  const existed = fs.existsSync(file);
+  if (!existed || force) fs.writeFileSync(file, viteConfigShim(base));
+  return { file, baseConfigFile: base, existed };
+}