benchforge 0.1.9 → 0.2.4

package/src/export/ArchiveFormat.ts

@@ -0,0 +1,50 @@
+/** Serialized `.benchforge` archive format. */
+
+import type { ReportData } from "../viewer/ReportData.ts";
+import type { LineCoverage } from "./CoverageExport.ts";
+import type { SpeedscopeFile } from "./SpeedscopeTypes.ts";
+
+export interface BenchforgeArchive {
+  /** Archive format version. */
+  schema: number;
+
+  /** Heap allocation profile in Speedscope format. */
+  allocProfile?: SpeedscopeFile;
+
+  /** CPU time profile in Speedscope format. */
+  timeProfile?: SpeedscopeFile;
+
+  /** Per-line coverage data keyed by source URL. */
+  coverage?: Record<string, LineCoverage[]>;
+
+  /** Benchmark report with suite results and statistics. */
+  report?: ReportData;
+
+  /** Source file contents keyed by file URL. */
+  sources: Record<string, string>;
+
+  /** Archive creation metadata. */
+  metadata: ArchiveMetadata;
+}
+
+export interface ArchiveMetadata {
+  /** ISO timestamp (colons/periods replaced with dashes for filename safety). */
+  timestamp: string;
+
+  /** Benchforge package version. */
+  benchforgeVersion: string;
+}
+
+export const archiveSchemaVersion = 2;
+
+/** Migrate a parsed archive from older schema versions to current. */
+export function migrateArchive(
+  raw: Record<string, unknown>,
+): Partial<BenchforgeArchive> {
+  const schema = (raw.schema as number) ?? 0;
+  if (schema <= 1 && "profile" in raw && !("allocProfile" in raw)) {
+    raw.allocProfile = raw.profile;
+    delete raw.profile;
+  }
+  return raw as Partial<BenchforgeArchive>;
+}

package/src/export/CoverageExport.ts

@@ -0,0 +1,148 @@
+/** Line-level coverage maps from V8/CDP coverage data and frame annotation with execution counts. */
+
+import type { CoverageData } from "../profiling/node/CoverageTypes.ts";
+
+/** Per-function execution count at a specific source line. */
+export interface LineCoverage {
+  /** 1-indexed line number of the function start */
+  startLine: number;
+  /** Function name (empty string for anonymous top-level) */
+  functionName: string;
+  /** Number of times the function was invoked */
+  count: number;
+}
+
+/** Map from source URL to per-function execution counts. */
+export type CoverageMap = Map<string, LineCoverage[]>;
+
+/** Coverage data: per-URL entries and a name-only fallback lookup. */
+export interface CoverageResult {
+  /** Per-URL coverage entries (for frames with matching file URLs) */
+  map: CoverageMap;
+  /** Name ==> count lookup across all scripts (for frames without file URLs) */
+  byName: Map<string, number>;
+}
+
+/** Build coverage data from raw CDP/inspector coverage and source texts. */
+export function buildCoverageMap(
+  coverage: CoverageData,
+  sources: Record<string, string>,
+): CoverageResult {
+  const map: CoverageMap = new Map();
+  const byName = new Map<string, number>();
+
+  for (const script of coverage.scripts) {
+    processScript(script, sources, map, byName);
+  }
+
+  return { map, byName };
+}
+
+/** Annotate speedscope frame names with execution counts (e.g. "fn [1.2K]"). */
+export function annotateFramesWithCounts(
+  frames: { name: string; file?: string; line?: number }[],
+  coverage: CoverageResult,
+): void {
+  for (const frame of frames) {
+    const entries = frame.file ? coverage.map.get(frame.file) : undefined;
+    const count = entries && findCount(frame.name, frame.line, entries);
+    const isAnon = frame.name.startsWith("(anonymous");
+    const resolved =
+      count ?? (isAnon ? undefined : coverage.byName.get(frame.name));
+    if (resolved !== undefined && resolved > 0)
+      frame.name = `${frame.name} [${formatCount(resolved)}]`;
+  }
+}
+
+/** Extract per-function coverage entries from a single script. */
+function processScript(
+  script: CoverageData["scripts"][number],
+  sources: Record<string, string>,
+  map: CoverageMap,
+  byName: Map<string, number>,
+): void {
+  const { url, functions } = script;
+  const source = url ? sources[url] : undefined;
+  const lineOffsets = source ? buildLineOffsets(source) : undefined;
+  const entries: LineCoverage[] = [];
+
+  for (const fn of functions) {
+    const range = fn.ranges[0];
+    if (!range) continue;
+
+    if (lineOffsets && url) {
+      entries.push({
+        startLine: offsetToLine(range.startOffset, lineOffsets),
+        functionName: fn.functionName,
+        count: range.count,
+      });
+    }
+
+    if (fn.functionName && range.count > 0) {
+      const prev = byName.get(fn.functionName) ?? 0;
+      byName.set(fn.functionName, prev + range.count);
+    }
+  }
+
+  if (entries.length > 0 && url) map.set(url, entries);
+}
+
+/** Match a frame to a coverage entry by function name (or closest line for anonymous). */
+function findCount(
+  frameName: string,
+  frameLine: number | undefined,
+  entries: LineCoverage[],
+): number | undefined {
+  const isAnon =
+    frameName === "(anonymous)" || frameName.startsWith("(anonymous ");
+
+  if (isAnon) {
+    if (!frameLine) return undefined;
+    const anonymous = entries.filter(e => e.functionName === "");
+    return closestByLine(anonymous, frameLine)?.count;
+  }
+
+  const nameMatches = entries.filter(e => e.functionName === frameName);
+  if (nameMatches.length === 0) return undefined;
+  if (nameMatches.length === 1) return nameMatches[0].count;
+  if (frameLine) return closestByLine(nameMatches, frameLine)?.count;
+  return nameMatches[0].count;
+}
+
+/** Format a count for display (e.g. 1234567 ==> "1.2M"). */
+function formatCount(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 10_000) return `${(n / 1_000).toFixed(1)}K`;
+  return String(n);
+}
+
+/** Build array where index i is the character offset where line (i+1) starts. */
+function buildLineOffsets(source: string): number[] {
+  const offsets = [0]; // line 1 starts at offset 0
+  for (let i = 0; i < source.length; i++) {
+    if (source[i] === "\n") offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+/** Convert character offset to 1-indexed line number via binary search. */
+function offsetToLine(offset: number, lineOffsets: number[]): number {
+  let lo = 0;
+  let hi = lineOffsets.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (lineOffsets[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo + 1; // 1-indexed
+}
+
+/** Find the entry whose startLine is closest to the given line. */
+function closestByLine(
+  entries: LineCoverage[],
+  line: number,
+): LineCoverage | undefined {
+  if (!entries.length) return undefined;
+  const dist = (e: LineCoverage) => Math.abs(e.startLine - line);
+  return entries.reduce((best, e) => (dist(e) < dist(best) ? e : best));
+}

package/src/export/EditorUri.ts

@@ -0,0 +1,10 @@
+const presets: Record<string, string> = {
+  vscode: "vscode://file",
+  cursor: "cursor://file",
+};
+
+/** Resolve editor name or custom URI to a prefix.
+ *  Links are formatted as `{prefix}{absolutePath}:{line}:{col}` */
+export function resolveEditorUri(editor: string): string {
+  return presets[editor] ?? editor;
+}

package/src/export/PerfettoExport.ts

@@ -1,28 +1,19 @@
+/** Export benchmark samples to Chrome Trace Event format for viewing in Perfetto. */
+
 import { spawn } from "node:child_process";
 import { readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import type { ReportGroup } from "../BenchmarkReport.ts";
-import type { DefaultCliArgs } from "../cli/CliArgs.ts";
-import type { MeasuredResults } from "../MeasuredResults.ts";
-
-/** Chrome Trace Event format event */
-interface TraceEvent {
-  ph: string; // event type: M=metadata, C=counter, i=instant, B/E=begin/end
-  ts: number; // timestamp in microseconds
-  pid?: number;
-  tid?: number;
-  cat?: string;
-  name: string;
-  args?: Record<string, unknown>;
-  s?: string; // scope for instant events: "t"=thread, "p"=process, "g"=global
-  dur?: number; // duration for complete events
-}
+import { cleanCliArgs, type DefaultCliArgs } from "../cli/CliArgs.ts";
+import type { TraceEvent } from "../profiling/browser/ChromeTraceEvent.ts";
+import type { ReportGroup } from "../report/BenchmarkReport.ts";
+import type { MeasuredResults } from "../runners/MeasuredResults.ts";
 
-/** Chrome Trace Event format file structure */
 interface TraceFile {
   traceEvents: TraceEvent[];
 }
 
+type Args = Record<string, unknown>;
+
 const pid = 1;
 const tid = 1;
 
@@ -35,65 +26,84 @@ export function exportPerfettoTrace(
   const absPath = resolve(outputPath);
   const events = buildTraceEvents(groups, args);
 
-  // Try to merge any existing V8 trace from a previous run
   const merged = mergeV8Trace(events);
-  writeTraceFile(absPath, merged);
+  const traceFile: TraceFile = { traceEvents: merged };
+  writeFileSync(absPath, JSON.stringify(traceFile));
   console.log(`Perfetto trace exported to: ${outputPath}`);
 
-  // V8 writes trace files after process exit, so spawn a child to merge later
   scheduleDeferredMerge(absPath);
 }
 
-/** Build trace events from benchmark results */
 function buildTraceEvents(
   groups: ReportGroup[],
-  args: DefaultCliArgs,
+  cliArgs: DefaultCliArgs,
 ): TraceEvent[] {
-  const meta = (name: string, a: Record<string, unknown>): TraceEvent => ({
-    ph: "M",
-    ts: 0,
-    pid,
-    tid,
-    name,
-    args: a,
-  });
-  const events: TraceEvent[] = [
+  const metadata: TraceEvent[] = [
     meta("process_name", { name: "wesl-bench" }),
     meta("thread_name", { name: "MainThread" }),
-    meta("bench_settings", cleanArgs(args)),
+    meta("bench_settings", cleanCliArgs(cliArgs)),
   ];
 
-  for (const group of groups) {
-    for (const report of group.reports) {
-      const results = report.measuredResults as MeasuredResults;
-      events.push(...buildBenchmarkEvents(results));
-    }
-  }
+  const benchEvents = groups.flatMap(group =>
+    group.reports.flatMap(report =>
+      buildBenchmarkEvents(report.measuredResults as MeasuredResults),
+    ),
+  );
 
-  return events;
+  return [...metadata, ...benchEvents];
 }
 
-function instant(
-  ts: number,
-  name: string,
-  args: Record<string, unknown>,
-): TraceEvent {
-  return { ph: "i", ts, pid, tid, cat: "bench", name, s: "t", args };
+function mergeV8Trace(events: TraceEvent[]): TraceEvent[] {
+  const v8TracePath = readdirSync(".").find(
+    f => f.startsWith("node_trace.") && f.endsWith(".log"),
+  );
+  const v8Events = loadV8Events(v8TracePath);
+  const merged = v8Events ? [...v8Events, ...events] : events;
+  normalizeTimestamps(merged);
+  return merged;
 }
 
-function counter(
-  ts: number,
-  name: string,
-  args: Record<string, unknown>,
-): TraceEvent {
-  return { ph: "C", ts, pid, tid, cat: "bench", name, args };
+/** V8 writes trace files after process exit, so we spawn a deferred merge. */
+function scheduleDeferredMerge(outputPath: string): void {
+  const cwd = process.cwd();
+  const mergeScript = `
+    const { readdirSync, readFileSync, writeFileSync } = require('fs');
+    function normalize(events) {
+      let min = Infinity;
+      for (const e of events) if (e.ts > 0 && e.ts < min) min = e.ts;
+      if (min === Infinity) return;
+      for (const e of events) if (e.ts > 0) e.ts -= min;
+    }
+    setTimeout(() => {
+      const traceFiles = readdirSync('.').filter(f => f.startsWith('node_trace.') && f.endsWith('.log'));
+      if (traceFiles.length === 0) process.exit(0);
+      try {
+        const v8Data = JSON.parse(readFileSync(traceFiles[0], 'utf-8'));
+        const ourData = JSON.parse(readFileSync('${outputPath}', 'utf-8'));
+        const allEvents = [...v8Data.traceEvents, ...ourData.traceEvents];
+        normalize(allEvents);
+        writeFileSync('${outputPath}', JSON.stringify({ traceEvents: allEvents }));
+        console.log('Merged ' + v8Data.traceEvents.length + ' V8 events into ' + '${outputPath}');
+      } catch (e) { console.error('Merge failed:', e.message); }
+    }, 100);
+  `;
+
+  process.on("exit", () => {
+    const opts = { detached: true, stdio: "inherit" as const, cwd };
+    spawn("node", ["-e", mergeScript], opts).unref();
+  });
+}
+
+function meta(name: string, args: Args): TraceEvent {
+  return { ph: "M", ts: 0, pid, tid, name, args };
 }
 
-/** Build events for a single benchmark run */
+/** Build events for a single benchmark run, deriving timestamps from cumulative sample durations. */
 function buildBenchmarkEvents(results: MeasuredResults): TraceEvent[] {
-  const { samples, heapSamples, timestamps, pausePoints } = results;
-  if (!timestamps?.length) return [];
+  const { samples, heapSamples, pausePoints, startTime = 0 } = results;
+  if (!samples?.length) return [];
 
+  const timestamps = cumulativeTimestamps(samples, startTime);
   const events: TraceEvent[] = [];
   for (let i = 0; i < samples.length; i++) {
     const ts = timestamps[i];
@@ -101,8 +111,8 @@ function buildBenchmarkEvents(results: MeasuredResults): TraceEvent[] {
     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 }));
+      const mb = Math.round((heapSamples[i] / 1024 / 1024) * 10) / 10;
+      events.push(counter(ts, "heap", { MB: mb }));
     }
   }
 
@@ -113,91 +123,46 @@ function buildBenchmarkEvents(results: MeasuredResults): TraceEvent[] {
   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(
-    f => f.startsWith("node_trace.") && f.endsWith(".log"),
-  );
-
-  const v8Events = loadV8Events(traceFiles[0]);
-  normalizeTimestamps(customEvents);
-  if (!v8Events) return customEvents;
-
-  normalizeTimestamps(v8Events);
-  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;
+    const { traceEvents } = v8Data;
+    console.log(`Merged ${traceEvents.length} V8 events from ${v8TracePath}`);
+    return 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));
+/** Normalize timestamps so events start at 0 */
+function normalizeTimestamps(events: TraceEvent[]): void {
+  let min = Number.POSITIVE_INFINITY;
+  for (const e of events) if (e.ts > 0 && e.ts < min) min = e.ts;
+  if (min === Number.POSITIVE_INFINITY) return;
+  for (const e of events) if (e.ts > 0) e.ts -= min;
 }
 
-/** 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);
+/** Derive μs timestamps from cumulative sample durations (ms), offset by startTime. */
+function cumulativeTimestamps(samples: number[], offset = 0): number[] {
+  const timestamps = new Array<number>(samples.length);
+  let cumulative = 0;
+  for (let i = 0; i < samples.length; i++) {
+    cumulative += samples[i];
+    timestamps[i] = offset + Math.round(cumulative * 1000); // ms ==> μs
+  }
+  return timestamps;
 }
 
-/** Spawn a detached child to merge V8 trace after process exit */
-function scheduleDeferredMerge(outputPath: string): void {
-  const cwd = process.cwd();
-  const mergeScript = `
-    const { readdirSync, readFileSync, writeFileSync } = require('fs');
-    function normalize(events) {
-      const times = events.filter(e => e.ts > 0).map(e => e.ts);
-      if (!times.length) return;
-      const min = Math.min(...times);
-      for (const e of events) if (e.ts > 0) e.ts -= min;
-    }
-    setTimeout(() => {
-      const traceFiles = readdirSync('.').filter(f => f.startsWith('node_trace.') && f.endsWith('.log'));
-      if (traceFiles.length === 0) process.exit(0);
-      try {
-        const v8Data = JSON.parse(readFileSync(traceFiles[0], 'utf-8'));
-        const ourData = JSON.parse(readFileSync('${outputPath}', 'utf-8'));
-        normalize(v8Data.traceEvents);
-        const merged = { traceEvents: [...v8Data.traceEvents, ...ourData.traceEvents] };
-        writeFileSync('${outputPath}', JSON.stringify(merged));
-        console.log('Merged ' + v8Data.traceEvents.length + ' V8 events into ' + '${outputPath}');
-      } catch (e) { console.error('Merge failed:', e.message); }
-    }, 100);
-  `;
+/** Create a thread-scoped instant event */
+function instant(ts: number, name: string, args: Args): TraceEvent {
+  return { ph: "i", ts, pid, tid, cat: "bench", name, s: "t", args };
+}
 
-  process.on("exit", () => {
-    const child = spawn("node", ["-e", mergeScript], {
-      detached: true,
-      stdio: "inherit",
-      cwd,
-    });
-    child.unref();
-  });
+/** Create a counter event (shown as a time-series chart in Perfetto) */
+function counter(ts: number, name: string, args: Args): TraceEvent {
+  return { ph: "C", ts, pid, tid, cat: "bench", name, args };
 }

package/src/export/SpeedscopeTypes.ts

@@ -0,0 +1,98 @@
+/** Shared speedscope file format types and frame interning utilities. */
+
+/** speedscope file format (https://www.speedscope.app/file-format-schema.json) */
+export interface SpeedscopeFile {
+  $schema: "https://www.speedscope.app/file-format-schema.json";
+  shared: { frames: SpeedscopeFrame[] };
+  profiles: SpeedscopeProfile[];
+  name?: string;
+  exporter?: string;
+}
+
+/** A single call frame with optional source location */
+export interface SpeedscopeFrame {
+  name: string;
+  file?: string;
+  line?: number;
+  col?: number;
+}
+
+/** Union of heap and time profile shapes (unit differs) */
+export type SpeedscopeProfile = SpeedscopeHeapProfile | SpeedscopeTimeProfile;
+
+/** Heap allocation profile weighted by bytes */
+export interface SpeedscopeHeapProfile {
+  type: "sampled";
+  name: string;
+  unit: "bytes";
+  startValue: number;
+  endValue: number;
+  samples: number[][];
+  weights: number[];
+}
+
+/** CPU time profile weighted by microseconds */
+export interface SpeedscopeTimeProfile {
+  type: "sampled";
+  name: string;
+  unit: "microseconds";
+  startValue: number;
+  endValue: number;
+  samples: number[][];
+  weights: number[];
+}
+
+/** Shared mutable state for frame interning across profiles. */
+export interface FrameContext {
+  frames: SpeedscopeFrame[];
+  index: Map<string, number>;
+}
+
+/** Create an empty FrameContext for building speedscope profiles. */
+export function frameContext(): FrameContext {
+  return { frames: [], index: new Map() };
+}
+
+/** Wrap profiles in a SpeedscopeFile envelope */
+export function speedscopeFile(
+  ctx: FrameContext,
+  profiles: SpeedscopeProfile[],
+): SpeedscopeFile {
+  return {
+    $schema: "https://www.speedscope.app/file-format-schema.json",
+    shared: { frames: ctx.frames },
+    profiles,
+    exporter: "benchforge",
+  };
+}
+
+/** Intern a call frame, returning its index in the shared frames array.
+ *  All values should be 1-indexed (caller converts from V8's 0-indexed if needed). */
+export function internFrame(
+  name: string,
+  url: string,
+  line: number,
+  col: number | undefined | null,
+  ctx: FrameContext,
+): number {
+  const key = `${name}\0${url}\0${line}\0${col}`;
+
+  const existing = ctx.index.get(key);
+  if (existing !== undefined) return existing;
+
+  const idx = ctx.frames.length;
+  const entry: SpeedscopeFrame = { name: displayName(name, url, line) };
+  if (url) entry.file = url;
+  if (line > 0) entry.line = line;
+  if (col != null) entry.col = col;
+  ctx.frames.push(entry);
+  ctx.index.set(key, idx);
+  return idx;
+}
+
+/** Display name for a frame: named functions use their name, anonymous get a location hint */
+function displayName(name: string, url: string, line: number): string {
+  if (name !== "(anonymous)") return name;
+  const file = url?.split("/").pop();
+  return file ? `(anonymous ${file}:${line})` : "(anonymous)";
+}