benchforge 0.1.9 → 0.1.11

package/src/export/JsonExport.ts

@@ -47,6 +47,16 @@ function prepareJsonData(
   };
 }
 
+/** Clean CLI args for JSON export (remove undefined values) */
+function cleanCliArgs(args: DefaultCliArgs): Record<string, any> {
+  const toCamel = (k: string) =>
+    k.replace(/-([a-z])/g, (_, l) => l.toUpperCase());
+  const entries = Object.entries(args)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => [toCamel(k), v]);
+  return Object.fromEntries(entries);
+}
+
 /** Convert a report group, mapping each report to the JSON result format */
 function convertGroup(group: ReportGroup): BenchmarkGroup {
   return {
@@ -91,13 +101,3 @@ function convertReport(report: any): BenchmarkResult {
     },
   };
 }
-
-/** Clean CLI args for JSON export (remove undefined values) */
-function cleanCliArgs(args: DefaultCliArgs): Record<string, any> {
-  const toCamel = (k: string) =>
-    k.replace(/-([a-z])/g, (_, l) => l.toUpperCase());
-  const entries = Object.entries(args)
-    .filter(([, v]) => v !== undefined && v !== null)
-    .map(([k, v]) => [toCamel(k), v]);
-  return Object.fromEntries(entries);
-}

package/src/export/PerfettoExport.ts

@@ -73,54 +73,6 @@ function buildTraceEvents(
   return events;
 }
 
-function instant(
-  ts: number,
-  name: string,
-  args: Record<string, unknown>,
-): TraceEvent {
-  return { ph: "i", ts, pid, tid, cat: "bench", name, s: "t", args };
-}
-
-function counter(
-  ts: number,
-  name: string,
-  args: Record<string, unknown>,
-): TraceEvent {
-  return { ph: "C", ts, pid, tid, cat: "bench", name, args };
-}
-
-/** Build events for a single benchmark run */
-function buildBenchmarkEvents(results: MeasuredResults): TraceEvent[] {
-  const { samples, heapSamples, timestamps, pausePoints } = results;
-  if (!timestamps?.length) return [];
-
-  const events: TraceEvent[] = [];
-  for (let i = 0; i < samples.length; i++) {
-    const ts = timestamps[i];
-    const ms = Math.round(samples[i] * 100) / 100;
-    events.push(instant(ts, results.name, { n: i, ms }));
-    events.push(counter(ts, "duration", { ms }));
-    if (heapSamples?.[i] !== undefined) {
-      const MB = Math.round((heapSamples[i] / 1024 / 1024) * 10) / 10;
-      events.push(counter(ts, "heap", { MB }));
-    }
-  }
-
-  for (const pause of pausePoints ?? []) {
-    const ts = timestamps[pause.sampleIndex];
-    if (ts) events.push(instant(ts, "pause", { ms: pause.durationMs }));
-  }
-  return events;
-}
-
-/** Normalize timestamps so events start at 0 */
-function normalizeTimestamps(events: TraceEvent[]): void {
-  const times = events.filter(e => e.ts > 0).map(e => e.ts);
-  if (times.length === 0) return;
-  const minTs = Math.min(...times);
-  for (const e of events) if (e.ts > 0) e.ts -= minTs;
-}
-
 /** Merge V8 trace events from a previous run, aligning timestamps */
 function mergeV8Trace(customEvents: TraceEvent[]): TraceEvent[] {
   const traceFiles = readdirSync(".").filter(
@@ -135,38 +87,12 @@ function mergeV8Trace(customEvents: TraceEvent[]): TraceEvent[] {
   return [...v8Events, ...customEvents];
 }
 
-/** Load V8 trace events from file, or undefined if unavailable */
-function loadV8Events(
-  v8TracePath: string | undefined,
-): TraceEvent[] | undefined {
-  if (!v8TracePath) return undefined;
-  try {
-    const v8Data = JSON.parse(readFileSync(v8TracePath, "utf-8")) as TraceFile;
-    console.log(
-      `Merged ${v8Data.traceEvents.length} V8 events from ${v8TracePath}`,
-    );
-    return v8Data.traceEvents;
-  } catch {
-    console.warn(`Could not parse V8 trace file: ${v8TracePath}`);
-    return undefined;
-  }
-}
-
 /** Write trace events to JSON file */
 function writeTraceFile(outputPath: string, events: TraceEvent[]): void {
   const traceFile: TraceFile = { traceEvents: events };
   writeFileSync(outputPath, JSON.stringify(traceFile));
 }
 
-/** Clean CLI args for metadata */
-function cleanArgs(args: DefaultCliArgs): Record<string, unknown> {
-  const skip = new Set(["_", "$0"]);
-  const entries = Object.entries(args).filter(
-    ([k, v]) => v !== undefined && !skip.has(k),
-  );
-  return Object.fromEntries(entries);
-}
-
 /** Spawn a detached child to merge V8 trace after process exit */
 function scheduleDeferredMerge(outputPath: string): void {
   const cwd = process.cwd();
@@ -201,3 +127,77 @@ function scheduleDeferredMerge(outputPath: string): void {
     child.unref();
   });
 }
+
+/** Clean CLI args for metadata */
+function cleanArgs(args: DefaultCliArgs): Record<string, unknown> {
+  const skip = new Set(["_", "$0"]);
+  const entries = Object.entries(args).filter(
+    ([k, v]) => v !== undefined && !skip.has(k),
+  );
+  return Object.fromEntries(entries);
+}
+
+/** Build events for a single benchmark run */
+function buildBenchmarkEvents(results: MeasuredResults): TraceEvent[] {
+  const { samples, heapSamples, timestamps, pausePoints } = results;
+  if (!timestamps?.length) return [];
+
+  const events: TraceEvent[] = [];
+  for (let i = 0; i < samples.length; i++) {
+    const ts = timestamps[i];
+    const ms = Math.round(samples[i] * 100) / 100;
+    events.push(instant(ts, results.name, { n: i, ms }));
+    events.push(counter(ts, "duration", { ms }));
+    if (heapSamples?.[i] !== undefined) {
+      const MB = Math.round((heapSamples[i] / 1024 / 1024) * 10) / 10;
+      events.push(counter(ts, "heap", { MB }));
+    }
+  }
+
+  for (const pause of pausePoints ?? []) {
+    const ts = timestamps[pause.sampleIndex];
+    if (ts) events.push(instant(ts, "pause", { ms: pause.durationMs }));
+  }
+  return events;
+}
+
+/** Load V8 trace events from file, or undefined if unavailable */
+function loadV8Events(
+  v8TracePath: string | undefined,
+): TraceEvent[] | undefined {
+  if (!v8TracePath) return undefined;
+  try {
+    const v8Data = JSON.parse(readFileSync(v8TracePath, "utf-8")) as TraceFile;
+    console.log(
+      `Merged ${v8Data.traceEvents.length} V8 events from ${v8TracePath}`,
+    );
+    return v8Data.traceEvents;
+  } catch {
+    console.warn(`Could not parse V8 trace file: ${v8TracePath}`);
+    return undefined;
+  }
+}
+
+/** Normalize timestamps so events start at 0 */
+function normalizeTimestamps(events: TraceEvent[]): void {
+  const times = events.filter(e => e.ts > 0).map(e => e.ts);
+  if (times.length === 0) return;
+  const minTs = Math.min(...times);
+  for (const e of events) if (e.ts > 0) e.ts -= minTs;
+}
+
+function instant(
+  ts: number,
+  name: string,
+  args: Record<string, unknown>,
+): TraceEvent {
+  return { ph: "i", ts, pid, tid, cat: "bench", name, s: "t", args };
+}
+
+function counter(
+  ts: number,
+  name: string,
+  args: Record<string, unknown>,
+): TraceEvent {
+  return { ph: "C", ts, pid, tid, cat: "bench", name, args };
+}

package/src/export/SpeedscopeExport.ts

@@ -0,0 +1,202 @@
+import { spawn } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { groupReports, type ReportGroup } from "../BenchmarkReport.ts";
+import type { HeapProfile } from "../heap-sample/HeapSampler.ts";
+import {
+  type ResolvedFrame,
+  type ResolvedProfile,
+  resolveProfile,
+} from "../heap-sample/ResolvedProfile.ts";
+
+/** speedscope file format (https://www.speedscope.app/file-format-schema.json) */
+interface SpeedscopeFile {
+  $schema: "https://www.speedscope.app/file-format-schema.json";
+  shared: { frames: SpeedscopeFrame[] };
+  profiles: SpeedscopeProfile[];
+  name?: string;
+  exporter?: string;
+}
+
+interface SpeedscopeFrame {
+  name: string;
+  file?: string;
+  line?: number;
+  col?: number;
+}
+
+interface SpeedscopeProfile {
+  type: "sampled";
+  name: string;
+  unit: "bytes";
+  startValue: number;
+  endValue: number;
+  samples: number[][]; // each sample is stack of frame indices
+  weights: number[]; // bytes per sample
+}
+
+/** Export heap profiles from benchmark results to speedscope JSON format.
+ *  Creates one speedscope profile per benchmark that has a heapProfile.
+ *  @returns resolved output path, or undefined if no profiles were found */
+export function exportSpeedscope(
+  groups: ReportGroup[],
+  outputPath: string,
+): string | undefined {
+  const frames: SpeedscopeFrame[] = [];
+  const frameIndex = new Map<string, number>();
+  const profiles: SpeedscopeProfile[] = [];
+
+  for (const group of groups) {
+    for (const report of groupReports(group)) {
+      const { heapProfile } = report.measuredResults;
+      if (!heapProfile) continue;
+      const resolved = resolveProfile(heapProfile);
+      profiles.push(buildProfile(report.name, resolved, frames, frameIndex));
+    }
+  }
+
+  if (profiles.length === 0) {
+    console.log("No heap profiles to export.");
+    return undefined;
+  }
+
+  const file: SpeedscopeFile = {
+    $schema: "https://www.speedscope.app/file-format-schema.json",
+    shared: { frames },
+    profiles,
+    exporter: "benchforge",
+  };
+
+  const absPath = resolve(outputPath);
+  writeFileSync(absPath, JSON.stringify(file));
+  console.log(`Speedscope profile exported to: ${outputPath}`);
+  return absPath;
+}
+
+/** Export to a temp file and open in speedscope via npx */
+export function exportAndLaunchSpeedscope(groups: ReportGroup[]): void {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const outputPath = join(tmpdir(), `benchforge-${timestamp}.speedscope.json`);
+  const absPath = exportSpeedscope(groups, outputPath);
+  if (absPath) {
+    launchSpeedscope(absPath);
+  }
+}
+
+/** Launch speedscope viewer on a file via npx */
+export function launchSpeedscope(filePath: string): void {
+  console.log("Opening speedscope...");
+  const child = spawn("npx", ["speedscope", filePath], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  child.on("error", () => {
+    console.error(
+      `Failed to launch speedscope. Run manually:\n  npx speedscope ${filePath}`,
+    );
+  });
+}
+
+/** Convert a single HeapProfile to speedscope format (for standalone use) */
+export function heapProfileToSpeedscope(
+  name: string,
+  profile: HeapProfile,
+): SpeedscopeFile {
+  const frames: SpeedscopeFrame[] = [];
+  const frameIndex = new Map<string, number>();
+  const resolved = resolveProfile(profile);
+  const p = buildProfile(name, resolved, frames, frameIndex);
+
+  return {
+    $schema: "https://www.speedscope.app/file-format-schema.json",
+    shared: { frames },
+    profiles: [p],
+    exporter: "benchforge",
+  };
+}
+
+/** Build a single speedscope profile from a resolved heap profile */
+function buildProfile(
+  name: string,
+  resolved: ResolvedProfile,
+  sharedFrames: SpeedscopeFrame[],
+  frameIndex: Map<string, number>,
+): SpeedscopeProfile {
+  // Build nodeId -> stack of frame indices
+  const nodeStacks = new Map<number, number[]>();
+  for (const node of resolved.nodes) {
+    const stack = node.stack.map(f => internFrame(f, sharedFrames, frameIndex));
+    nodeStacks.set(node.nodeId, stack);
+  }
+
+  const samples: number[][] = [];
+  const weights: number[] = [];
+
+  if (!resolved.sortedSamples || resolved.sortedSamples.length === 0) {
+    console.error(
+      `Speedscope export: no samples in heap profile for "${name}", skipping`,
+    );
+    return {
+      type: "sampled",
+      name,
+      unit: "bytes",
+      startValue: 0,
+      endValue: 0,
+      samples,
+      weights,
+    };
+  }
+
+  for (const sample of resolved.sortedSamples) {
+    const stack = nodeStacks.get(sample.nodeId);
+    if (stack) {
+      samples.push(stack);
+      weights.push(sample.size);
+    }
+  }
+
+  const totalBytes = weights.reduce((sum, w) => sum + w, 0);
+
+  return {
+    type: "sampled",
+    name,
+    unit: "bytes",
+    startValue: 0,
+    endValue: totalBytes,
+    samples,
+    weights,
+  };
+}
+
+/** Intern a call frame, returning its index in the shared frames array */
+function internFrame(
+  frame: ResolvedFrame,
+  sharedFrames: SpeedscopeFrame[],
+  frameIndex: Map<string, number>,
+): number {
+  const { name, url, line, col } = frame;
+  const key = `${name}\0${url}\0${line}\0${col}`;
+
+  let idx = frameIndex.get(key);
+  if (idx === undefined) {
+    idx = sharedFrames.length;
+    // Match speedscope's convention: anonymous functions include location in name
+    const shortFile = url ? url.split("/").pop() : undefined;
+    const displayName =
+      name !== "(anonymous)"
+        ? name
+        : shortFile
+          ? `(anonymous ${shortFile}:${line})`
+          : "(anonymous)";
+    const entry: SpeedscopeFrame = { name: displayName };
+    if (url) entry.file = url;
+    if (line > 0) entry.line = line;
+    if (col != null) entry.col = col;
+    sharedFrames.push(entry);
+    frameIndex.set(key, idx);
+  }
+  return idx;
+}