benchforge 0.1.9 → 0.1.11

package/src/html/browser/SampleTimeSeries.ts

@@ -8,23 +8,6 @@ import type {
   TimeSeriesPoint,
 } from "./Types.ts";
 
-const OPT_STATUS_NAMES: Record<number, string> = {
-  1: "interpreted",
-  129: "sparkplug",
-  17: "turbofan",
-  33: "maglev",
-  49: "turbofan+maglev",
-  32769: "optimized",
-};
-const OPT_TIER_COLORS: Record<string, string> = {
-  turbofan: "#22c55e",
-  optimized: "#22c55e",
-  "turbofan+maglev": "#22c55e",
-  maglev: "#eab308",
-  sparkplug: "#f97316",
-  interpreted: "#dc3545",
-};
-
 interface SampleData {
   benchmark: string;
   sample: number;
@@ -49,6 +32,23 @@ interface PlotContext {
   benchmarks: string[];
 }
 
+const OPT_STATUS_NAMES: Record<number, string> = {
+  1: "interpreted",
+  129: "sparkplug",
+  17: "turbofan",
+  33: "maglev",
+  49: "turbofan+maglev",
+  32769: "optimized",
+};
+const OPT_TIER_COLORS: Record<string, string> = {
+  turbofan: "#22c55e",
+  optimized: "#22c55e",
+  "turbofan+maglev": "#22c55e",
+  maglev: "#eab308",
+  sparkplug: "#f97316",
+  interpreted: "#dc3545",
+};
+
 /** Create sample time series showing each sample in order */
 export function createSampleTimeSeries(
   timeSeries: TimeSeriesPoint[],
@@ -146,68 +146,6 @@ function buildPlotContext(timeSeries: TimeSeriesPoint[]): PlotContext {
   };
 }
 
-function buildSampleData(
-  timeSeries: TimeSeriesPoint[],
-  benchmarks: string[],
-): Omit<SampleData, "displayValue">[] {
-  const result: Omit<SampleData, "displayValue">[] = [];
-  for (const benchmark of benchmarks) {
-    const isBaseline = benchmark.includes("(baseline)");
-    for (const d of timeSeries.filter(t => t.benchmark === benchmark)) {
-      const optTier =
-        d.optStatus !== undefined
-          ? OPT_STATUS_NAMES[d.optStatus] || "unknown"
-          : null;
-      result.push({
-        benchmark,
-        sample: d.iteration,
-        value: d.value,
-        isBaseline,
-        isWarmup: d.isWarmup || false,
-        optTier,
-      });
-    }
-  }
-  return result;
-}
-
-/** Pick display unit (ns/us/ms) based on average value magnitude */
-function getTimeUnit(values: number[]) {
-  const avg = d3.mean(values)!;
-  const fmt0 = (d: number) => d3.format(",.0f")(d);
-  const fmt1 = (d: number) => d3.format(",.1f")(d);
-  if (avg < 0.001)
-    return {
-      unitSuffix: "ns",
-      convertValue: (ms: number) => ms * 1e6,
-      formatValue: fmt0,
-    };
-  if (avg < 1)
-    return {
-      unitSuffix: "μs",
-      convertValue: (ms: number) => ms * 1e3,
-      formatValue: fmt1,
-    };
-  return {
-    unitSuffix: "ms",
-    convertValue: (ms: number) => ms,
-    formatValue: fmt1,
-  };
-}
-
-/** Compute Y axis range with padding, snapping yMin to a round number */
-function computeYRange(values: number[]) {
-  const dataMin = d3.min(values)!;
-  const dataMax = d3.max(values)!;
-  const dataRange = dataMax - dataMin;
-  const padding = dataRange * 0.15;
-  let yMin = dataMin - padding;
-  const magnitude = 10 ** Math.floor(Math.log10(Math.abs(yMin)));
-  yMin = Math.floor(yMin / magnitude) * magnitude;
-  if (dataMin > 0 && yMin < 0) yMin = 0;
-  return { yMin, yMax: dataMax + dataRange * 0.05 };
-}
-
 /** Scale heap byte values into the plot's Y coordinate range */
 function prepareHeapData(heapSeries: HeapPoint[], yMin: number, yMax: number) {
   if (heapSeries.length === 0) return [];
@@ -387,3 +325,65 @@ function buildLegendItems(
   }
   return items;
 }
+
+function buildSampleData(
+  timeSeries: TimeSeriesPoint[],
+  benchmarks: string[],
+): Omit<SampleData, "displayValue">[] {
+  const result: Omit<SampleData, "displayValue">[] = [];
+  for (const benchmark of benchmarks) {
+    const isBaseline = benchmark.includes("(baseline)");
+    for (const d of timeSeries.filter(t => t.benchmark === benchmark)) {
+      const optTier =
+        d.optStatus !== undefined
+          ? OPT_STATUS_NAMES[d.optStatus] || "unknown"
+          : null;
+      result.push({
+        benchmark,
+        sample: d.iteration,
+        value: d.value,
+        isBaseline,
+        isWarmup: d.isWarmup || false,
+        optTier,
+      });
+    }
+  }
+  return result;
+}
+
+/** Pick display unit (ns/us/ms) based on average value magnitude */
+function getTimeUnit(values: number[]) {
+  const avg = d3.mean(values)!;
+  const fmt0 = (d: number) => d3.format(",.0f")(d);
+  const fmt1 = (d: number) => d3.format(",.1f")(d);
+  if (avg < 0.001)
+    return {
+      unitSuffix: "ns",
+      convertValue: (ms: number) => ms * 1e6,
+      formatValue: fmt0,
+    };
+  if (avg < 1)
+    return {
+      unitSuffix: "μs",
+      convertValue: (ms: number) => ms * 1e3,
+      formatValue: fmt1,
+    };
+  return {
+    unitSuffix: "ms",
+    convertValue: (ms: number) => ms,
+    formatValue: fmt1,
+  };
+}
+
+/** Compute Y axis range with padding, snapping yMin to a round number */
+function computeYRange(values: number[]) {
+  const dataMin = d3.min(values)!;
+  const dataMax = d3.max(values)!;
+  const dataRange = dataMax - dataMin;
+  const padding = dataRange * 0.15;
+  let yMin = dataMin - padding;
+  const magnitude = 10 ** Math.floor(Math.log10(Math.abs(yMin)));
+  yMin = Math.floor(yMin / magnitude) * magnitude;
+  if (dataMin > 0 && yMin < 0) yMin = 0;
+  return { yMin, yMax: dataMax + dataRange * 0.05 };
+}

package/src/index.ts

@@ -44,6 +44,12 @@ export {
 } from "./cli/RunBenchCLI.ts";
 export * from "./export/JsonFormat.ts";
 export { exportPerfettoTrace } from "./export/PerfettoExport.ts";
+export {
+  exportAndLaunchSpeedscope,
+  exportSpeedscope,
+  heapProfileToSpeedscope,
+  launchSpeedscope,
+} from "./export/SpeedscopeExport.ts";
 export type { GitVersion } from "./GitUtils.ts";
 export {
   formatDateWithTimezone,

package/src/matrix/MatrixFilter.ts

@@ -8,6 +8,12 @@ export interface MatrixFilter {
   variant?: string;
 }
 
+/** Filtered matrix with explicit case and variant lists */
+export interface FilteredMatrix<T = unknown> extends BenchMatrix<T> {
+  filteredCases?: string[];
+  filteredVariants?: string[];
+}
+
 /** Parse filter string: "case/variant", "case/", "/variant", or "case" */
 export function parseMatrixFilter(filter: string): MatrixFilter {
   if (filter.includes("/")) {
@@ -20,12 +26,6 @@ export function parseMatrixFilter(filter: string): MatrixFilter {
   return { case: filter };
 }
 
-/** Filtered matrix with explicit case and variant lists */
-export interface FilteredMatrix<T = unknown> extends BenchMatrix<T> {
-  filteredCases?: string[];
-  filteredVariants?: string[];
-}
-
 /** Apply filter to a matrix, merging with existing filters via intersection */
 export async function filterMatrix<T>(
   matrix: FilteredMatrix<T>,

package/src/matrix/MatrixReport.ts

@@ -43,6 +43,39 @@ interface MatrixReportRow extends Record<string, unknown> {
   diffCI?: DifferenceCI;
 }
 
+/** GC statistics columns - derived from gcStatsSection for consistency */
+export const gcStatsColumns: ExtraColumn[] = gcStatsSection
+  .columns()[0]
+  .columns.map(col => ({
+    key: col.key as string,
+    title: col.title,
+    groupTitle: "GC",
+    extract: (r: CaseResult) =>
+      gcStatsSection.extract(r.measured)[col.key as keyof GcStatsInfo],
+    formatter: (v: unknown) => col.formatter?.(v) ?? "-",
+  }));
+
+/** GC pause time column */
+export const gcPauseColumn: ExtraColumn = {
+  key: "gcPause",
+  title: "pause",
+  groupTitle: "GC",
+  extract: r => r.measured.gcStats?.gcPauseTime,
+  formatter: v => (v != null ? `${(v as number).toFixed(1)}ms` : "-"),
+};
+
+/** Heap sampling total bytes column */
+export const heapTotalColumn: ExtraColumn = {
+  key: "heapTotal",
+  title: "heap",
+  extract: r => {
+    const profile = r.measured.heapProfile;
+    if (!profile?.head) return undefined;
+    return totalProfileBytes(profile);
+  },
+  formatter: formatBytesOrDash,
+};
+
 /** Format matrix results as one table per case */
 export function reportMatrixResults(
   results: MatrixResults,
@@ -53,6 +86,11 @@ export function reportMatrixResults(
   return [header, ...tables].join("\n\n");
 }
 
+/** Format bytes with fallback to "-" for missing values */
+function formatBytesOrDash(value: unknown): string {
+  return formatBytes(value) ?? "-";
+}
+
 /** Build one table for each case showing all variants */
 function buildCaseTables(
   results: MatrixResults,
@@ -86,6 +124,20 @@ function buildCaseTable(
   return `${caseTitle}\n${table}`;
 }
 
+/** Format case title with metadata if available */
+function formatCaseTitle(results: MatrixResults, caseId: string): string {
+  const caseResult = results.variants[0]?.cases.find(c => c.caseId === caseId);
+  const metadata = caseResult?.metadata;
+
+  if (metadata && Object.keys(metadata).length > 0) {
+    const metaParts = Object.entries(metadata)
+      .map(([k, v]) => `${v} ${k}`)
+      .join(", ");
+    return `${caseId} (${metaParts})`;
+  }
+  return caseId;
+}
+
 /** Build table using ResultsMapper sections */
 function buildSectionTable(
   results: MatrixResults,
@@ -127,24 +179,6 @@ function buildSectionTable(
   return `${caseTitle}\n${table}`;
 }
 
-/** Build column groups from ResultsMapper sections */
-function buildSectionColumns(
-  sections: ResultsMapper[],
-  variantTitle: string,
-  hasBaseline: boolean,
-): ColumnGroup<Record<string, unknown>>[] {
-  const nameCol: ColumnGroup<Record<string, unknown>> = {
-    columns: [{ key: "name", title: variantTitle }],
-  };
-
-  const sectionColumns = sections.flatMap(s => s.columns());
-  const columnGroups = hasBaseline
-    ? injectDiffColumns(sectionColumns)
-    : (sectionColumns as ColumnGroup<Record<string, unknown>>[]);
-
-  return [nameCol, ...columnGroups];
-}
-
 /** Build rows for all variants for a given case */
 function buildCaseRows(
   results: MatrixResults,
@@ -157,35 +191,6 @@ function buildCaseRows(
   });
 }
 
-/** Build a single row from case result */
-function buildRow(
-  variantId: string,
-  caseResult: CaseResult,
-  extraColumns?: ExtraColumn[],
-): MatrixReportRow {
-  const { measured, baseline } = caseResult;
-  const samples = measured.samples;
-  const time = measured.time?.avg ?? average(samples);
-
-  const row: MatrixReportRow = {
-    name: truncate(variantId, 25),
-    time,
-    samples: samples.length,
-  };
-
-  if (baseline) {
-    row.diffCI = bootstrapDifferenceCI(baseline.samples, samples);
-  }
-
-  if (extraColumns) {
-    for (const col of extraColumns) {
-      row[col.key] = col.extract(caseResult);
-    }
-  }
-
-  return row;
-}
-
 /** Build column configuration */
 function buildColumns(
   hasBaseline: boolean,
@@ -231,60 +236,55 @@ function buildColumns(
   return groups;
 }
 
-/** Format diff with CI, or "baseline" marker */
-function formatDiff(value: unknown): string | null {
-  if (!value) return null;
-  return formatDiffWithCI(value as DifferenceCI);
+/** Build column groups from ResultsMapper sections */
+function buildSectionColumns(
+  sections: ResultsMapper[],
+  variantTitle: string,
+  hasBaseline: boolean,
+): ColumnGroup<Record<string, unknown>>[] {
+  const nameCol: ColumnGroup<Record<string, unknown>> = {
+    columns: [{ key: "name", title: variantTitle }],
+  };
+
+  const sectionColumns = sections.flatMap(s => s.columns());
+  const columnGroups = hasBaseline
+    ? injectDiffColumns(sectionColumns)
+    : (sectionColumns as ColumnGroup<Record<string, unknown>>[]);
+
+  return [nameCol, ...columnGroups];
 }
 
-/** Format case title with metadata if available */
-function formatCaseTitle(results: MatrixResults, caseId: string): string {
-  const caseResult = results.variants[0]?.cases.find(c => c.caseId === caseId);
-  const metadata = caseResult?.metadata;
+/** Build a single row from case result */
+function buildRow(
+  variantId: string,
+  caseResult: CaseResult,
+  extraColumns?: ExtraColumn[],
+): MatrixReportRow {
+  const { measured, baseline } = caseResult;
+  const samples = measured.samples;
+  const time = measured.time?.avg ?? average(samples);
 
-  if (metadata && Object.keys(metadata).length > 0) {
-    const metaParts = Object.entries(metadata)
-      .map(([k, v]) => `${v} ${k}`)
-      .join(", ");
-    return `${caseId} (${metaParts})`;
+  const row: MatrixReportRow = {
+    name: truncate(variantId, 25),
+    time,
+    samples: samples.length,
+  };
+
+  if (baseline) {
+    row.diffCI = bootstrapDifferenceCI(baseline.samples, samples);
   }
-  return caseId;
-}
 
-/** GC statistics columns - derived from gcStatsSection for consistency */
-export const gcStatsColumns: ExtraColumn[] = gcStatsSection
-  .columns()[0]
-  .columns.map(col => ({
-    key: col.key as string,
-    title: col.title,
-    groupTitle: "GC",
-    extract: (r: CaseResult) =>
-      gcStatsSection.extract(r.measured)[col.key as keyof GcStatsInfo],
-    formatter: (v: unknown) => col.formatter?.(v) ?? "-",
-  }));
+  if (extraColumns) {
+    for (const col of extraColumns) {
+      row[col.key] = col.extract(caseResult);
+    }
+  }
 
-/** Format bytes with fallback to "-" for missing values */
-function formatBytesOrDash(value: unknown): string {
-  return formatBytes(value) ?? "-";
+  return row;
 }
 
-/** GC pause time column */
-export const gcPauseColumn: ExtraColumn = {
-  key: "gcPause",
-  title: "pause",
-  groupTitle: "GC",
-  extract: r => r.measured.gcStats?.gcPauseTime,
-  formatter: v => (v != null ? `${(v as number).toFixed(1)}ms` : "-"),
-};
-
-/** Heap sampling total bytes column */
-export const heapTotalColumn: ExtraColumn = {
-  key: "heapTotal",
-  title: "heap",
-  extract: r => {
-    const profile = r.measured.heapProfile;
-    if (!profile?.head) return undefined;
-    return totalProfileBytes(profile);
-  },
-  formatter: formatBytesOrDash,
-};
+/** Format diff with CI, or "baseline" marker */
+function formatDiff(value: unknown): string | null {
+  if (!value) return null;
+  return formatDiffWithCI(value as DifferenceCI);
+}

package/src/matrix/VariantLoader.ts

@@ -22,6 +22,11 @@ export async function loadVariant<T = unknown>(
   return extractVariant(module, variantId, moduleUrl);
 }
 
+/** Get module URL for a variant in a directory */
+export function variantModuleUrl(dirUrl: string, variantId: string): string {
+  return new URL(`${variantId}.ts`, dirUrl).href;
+}
+
 /** Extract variant from module exports */
 function extractVariant<T>(
   module: Record<string, unknown>,
@@ -39,8 +44,3 @@ function extractVariant<T>(
   }
   return { setup: setup as (data: T) => unknown, run: run as () => void };
 }
-
-/** Get module URL for a variant in a directory */
-export function variantModuleUrl(dirUrl: string, variantId: string): string {
-  return new URL(`${variantId}.ts`, dirUrl).href;
-}