benchforge 0.1.9 → 0.2.4

package/src/viewer/Providers.ts

@@ -0,0 +1,191 @@
+import {
+  type BenchforgeArchive,
+  migrateArchive,
+} from "../export/ArchiveFormat.ts";
+import type { LineCoverage } from "../export/CoverageExport.ts";
+import type { SpeedscopeFrame } from "../export/SpeedscopeTypes.ts";
+
+/** Discriminant for heap allocation vs CPU time profiles. */
+export type ProfileType = "alloc" | "time";
+
+/** Feature flags and settings received from the server or inferred from an archive. */
+export interface ViewerConfig {
+  editorUri: string | null;
+  hasReport: boolean;
+  hasProfile: boolean;
+  hasTimeProfile: boolean;
+  hasCoverage: boolean;
+}
+
+/** Coverage data keyed by source URL. */
+export type ViewerCoverageData = Record<string, LineCoverage[]>;
+
+/** A single sampled profile with weights per sample stack. */
+export interface ViewerSpeedscopeProfile {
+  type: "sampled";
+  unit: "bytes" | "microseconds";
+  samples: number[][];
+  weights: number[];
+}
+
+/** Container for shared frames and one or more sampled profiles. */
+export interface ViewerSpeedscopeFile {
+  shared: { frames: SpeedscopeFrame[] };
+  profiles: ViewerSpeedscopeProfile[];
+}
+
+/** Parsed archive data, with optional fields for forward compatibility. */
+export type ArchiveData = Partial<BenchforgeArchive>;
+
+/** Abstraction over data sources (live server or static archive). */
+export interface DataProvider {
+  readonly config: ViewerConfig;
+  fetchReportData(): Promise<unknown>;
+  fetchSource(url: string): Promise<string>;
+  fetchProfileData(type: ProfileType): Promise<ViewerSpeedscopeFile | null>;
+  fetchCoverageData(): Promise<ViewerCoverageData | null>;
+  // LATER once we replace the speedscope iframe with an integrated viewer,
+  // we can pass profile data directly instead of returning URLs.
+  profileUrl(type: ProfileType): string | null;
+  createArchive(): Promise<{ blob: Blob; filename: string }>;
+}
+
+/** Fetches data from the live CLI viewer HTTP server. */
+export class ServerProvider implements DataProvider {
+  private profileCache = new Map<
+    string,
+    Promise<ViewerSpeedscopeFile | null>
+  >();
+
+  readonly config: ViewerConfig;
+  constructor(config: ViewerConfig) {
+    this.config = config;
+  }
+
+  /** Fetch the server config and return a ready-to-use provider. */
+  static async create(): Promise<ServerProvider> {
+    const resp = await fetch("/api/config");
+    return new ServerProvider((await resp.json()) as ViewerConfig);
+  }
+
+  async fetchReportData(): Promise<unknown> {
+    const resp = await fetch("/api/report-data");
+    if (!resp.ok) throw new Error("No report data: " + resp.status);
+    return resp.json();
+  }
+
+  async fetchSource(url: string): Promise<string> {
+    const resp = await fetch("/api/source?url=" + encodeURIComponent(url));
+    if (!resp.ok) throw new Error("Source unavailable");
+    return resp.text();
+  }
+
+  /** Fetch a speedscope profile, caching the result by type. */
+  fetchProfileData(type: ProfileType): Promise<ViewerSpeedscopeFile | null> {
+    const url = this.profileUrl(type);
+    if (!url) return Promise.resolve(null);
+    let cached = this.profileCache.get(type);
+    if (!cached) {
+      cached = fetch(url).then(r =>
+        r.ok ? (r.json() as Promise<ViewerSpeedscopeFile>) : null,
+      );
+      this.profileCache.set(type, cached);
+    }
+    return cached;
+  }
+
+  private coverageCache?: Promise<ViewerCoverageData | null>;
+
+  fetchCoverageData(): Promise<ViewerCoverageData | null> {
+    if (!this.config.hasCoverage) return Promise.resolve(null);
+    this.coverageCache ??= fetch("/api/coverage").then(r =>
+      r.ok ? (r.json() as Promise<ViewerCoverageData>) : null,
+    );
+    return this.coverageCache;
+  }
+
+  profileUrl(type: ProfileType): string | null {
+    if (type === "alloc") return this.config.hasProfile ? "/api/profile" : null;
+    return this.config.hasTimeProfile ? "/api/profile/time" : null;
+  }
+
+  /** Request a `.benchforge` archive, extracting filename from Content-Disposition. */
+  async createArchive(): Promise<{ blob: Blob; filename: string }> {
+    const resp = await fetch("/api/archive", { method: "POST" });
+    if (!resp.ok) throw new Error("Archive failed");
+    const header = resp.headers.get("Content-Disposition") || "";
+    const filename =
+      header.match(/filename="?(.+?)"?$/)?.[1] ||
+      "benchforge-archive.benchforge";
+    return { blob: await resp.blob(), filename };
+  }
+}
+
+/** Serves data from an in-memory `.benchforge` archive (drag-drop or URL). */
+export class ArchiveProvider implements DataProvider {
+  readonly config: ViewerConfig;
+  private blobUrls = new Map<string, string>();
+  private archive: ArchiveData;
+
+  constructor(archive: ArchiveData | Record<string, unknown>) {
+    this.archive = migrateArchive(archive as Record<string, unknown>);
+    this.config = {
+      editorUri: null,
+      hasReport: !!archive.report,
+      hasProfile: !!archive.allocProfile,
+      hasTimeProfile: !!archive.timeProfile,
+      hasCoverage: !!archive.coverage,
+    };
+  }
+
+  private rawProfile(type: ProfileType): unknown {
+    return type === "alloc"
+      ? this.archive.allocProfile
+      : this.archive.timeProfile;
+  }
+
+  async fetchReportData(): Promise<unknown> {
+    if (!this.archive.report) throw new Error("No report data");
+    return this.archive.report;
+  }
+
+  async fetchSource(url: string): Promise<string> {
+    const source = this.archive.sources?.[url];
+    if (source === undefined) throw new Error("Source unavailable");
+    return source;
+  }
+
+  async fetchProfileData(
+    type: ProfileType,
+  ): Promise<ViewerSpeedscopeFile | null> {
+    return (this.rawProfile(type) as ViewerSpeedscopeFile) ?? null;
+  }
+
+  async fetchCoverageData(): Promise<ViewerCoverageData | null> {
+    return (this.archive.coverage as ViewerCoverageData) ?? null;
+  }
+
+  /** Return a blob URL for the profile, lazily created and cached. */
+  profileUrl(type: ProfileType): string | null {
+    const data = this.rawProfile(type);
+    if (!data) return null;
+    let url = this.blobUrls.get(type);
+    if (!url) {
+      const blob = new Blob([JSON.stringify(data)], {
+        type: "application/json",
+      });
+      url = URL.createObjectURL(blob);
+      this.blobUrls.set(type, url);
+    }
+    return url;
+  }
+
+  async createArchive(): Promise<{ blob: Blob; filename: string }> {
+    const blob = new Blob([JSON.stringify(this.archive)], {
+      type: "application/json",
+    });
+    const fallback = new Date().toISOString().replace(/[:.]/g, "-");
+    const timestamp = this.archive.metadata?.timestamp || fallback;
+    return { blob, filename: `benchforge-${timestamp}.benchforge` };
+  }
+}

package/src/viewer/ReportData.ts

@@ -0,0 +1,123 @@
+import type { GitVersion } from "../report/GitUtils.ts";
+import type { PausePoint } from "../runners/MeasuredResults.ts";
+import type {
+  CILevel,
+  DifferenceCI,
+  HistogramBin,
+} from "../stats/StatisticalUtils.ts";
+
+/** Top-level data structure for the HTML benchmark report. */
+export interface ReportData {
+  groups: BenchmarkGroup[];
+  metadata: {
+    timestamp: string;
+    bencherVersion: string;
+    cliArgs?: Record<string, unknown>;
+    cliDefaults?: Record<string, unknown>;
+    gcTrackingEnabled?: boolean;
+    currentVersion?: GitVersion;
+    baselineVersion?: GitVersion;
+    environment?: {
+      node: string;
+      platform: string;
+      arch: string;
+    };
+  };
+}
+
+/** A named group of benchmarks, optionally compared against a baseline. */
+export interface BenchmarkGroup {
+  name: string;
+  baseline?: BenchmarkEntry;
+  benchmarks: BenchmarkEntry[];
+  warnings?: string[];
+}
+
+/** One benchmark's raw data, statistics, and optional comparison results. */
+export interface BenchmarkEntry {
+  name: string;
+  samples: number[];
+  warmupSamples?: number[];
+  allocationSamples?: number[];
+  heapSamples?: number[];
+  gcEvents?: GcEvent[];
+  optSamples?: number[];
+  pausePoints?: PausePoint[];
+  batchOffsets?: number[];
+  stats: BenchmarkStats;
+  heapSize?: { min: number; max: number; avg: number };
+  totalTime?: number;
+  sections?: ViewerSection[];
+  coverageSummary?: CoverageSummary;
+  heapSummary?: HeapSummary;
+  comparisonCI?: DifferenceCI;
+}
+
+/** Summary percentile statistics for a benchmark's samples. */
+export interface BenchmarkStats {
+  min: number;
+  max: number;
+  avg: number;
+  p50: number;
+  p75: number;
+  p99: number;
+  p999: number;
+  cv?: number;
+  mad?: number;
+  outlierRate?: number;
+}
+
+/** A section of related stats for the viewer (e.g., "Lines / Sec", "GC"). */
+export interface ViewerSection {
+  title: string;
+  tabLink?: string;
+  rows: ViewerRow[];
+}
+
+/** A stat row with per-run values and optional comparison CI. */
+export interface ViewerRow {
+  label: string;
+  entries: ViewerEntry[];
+  comparisonCI?: DifferenceCI;
+  shared?: boolean;
+  /** First comparable row with a statKind in the section. */
+  primary?: boolean;
+}
+
+/** A single run's value for a stat. */
+export interface ViewerEntry {
+  runName: string;
+  value: string;
+  bootstrapCI?: BootstrapCIData;
+}
+
+/** Bootstrap CI data for inline visualization. */
+export interface BootstrapCIData {
+  estimate: number;
+  ci: [number, number];
+  histogram: HistogramBin[];
+  /** Formatted CI bounds for display (e.g., ["0.12ms", "0.15ms"]) */
+  ciLabels?: [string, string];
+  /** Block-level (between-run) or sample-level (within-run) resampling */
+  ciLevel?: CILevel;
+  /** false when batch count is too low for reliable CI */
+  ciReliable?: boolean;
+}
+
+/** Summary of coverage/call-count data. */
+export interface CoverageSummary {
+  functionCount: number;
+  totalCalls: number;
+}
+
+/** Summary of heap allocation profile. */
+export interface HeapSummary {
+  totalBytes: number;
+  userBytes: number;
+}
+
+/** A garbage collection event with timing relative to the benchmark start. */
+export interface GcEvent {
+  offset: number;
+  duration: number;
+}

package/src/viewer/State.ts

@@ -0,0 +1,49 @@
+import { signal } from "@preact/signals";
+import type { DataProvider } from "./Providers.ts";
+import type { ReportData } from "./ReportData.ts";
+
+/** Tracked state for an open source-code tab in the viewer. */
+export interface SourceTabState {
+  id: string;
+  file: string;
+  line: number;
+  col: number;
+  generation: number;
+}
+
+/** User color-scheme preference: follow OS, or force light/dark. */
+export type ThemePreference = "system" | "light" | "dark";
+
+/** Active data source (server or archive). */
+export const provider = signal<DataProvider | null>(null);
+
+/** Parsed report data from the provider. */
+export const reportData = signal<ReportData | null>(null);
+
+/** Currently visible tab id. */
+export const activeTabId = signal("summary");
+
+/** Whether sample data has been loaded for the samples tab. */
+export const samplesLoaded = signal(false);
+
+/** Error info when a `?url=` archive fetch fails. */
+export const urlError = signal<{ url: string; detail: string } | null>(null);
+
+/** Open source-code tabs. */
+export const sourceTabs = signal<SourceTabState[]>([]);
+
+const cookieTheme = document.cookie.match(/(?:^|; )theme=(light|dark)/);
+
+/** User's light/dark theme preference, initialized from cookie. */
+export const themePreference = signal<ThemePreference>(
+  (cookieTheme?.[1] as ThemePreference) ?? "system",
+);
+
+/** Pick the best default tab based on available data. */
+export function defaultTabId(): string {
+  const config = provider.value?.config;
+  if (config?.hasReport) return "summary";
+  if (config?.hasProfile) return "flamechart";
+  if (config?.hasTimeProfile) return "time-flamechart";
+  return "summary";
+}

package/src/viewer/Theme.ts

@@ -0,0 +1,15 @@
+import { type ThemePreference, themePreference } from "./State.ts";
+
+/** Apply a theme preference, persisting to a cookie and updating the document. */
+export function setTheme(pref: ThemePreference): void {
+  themePreference.value = pref;
+  if (pref === "system") {
+    delete document.documentElement.dataset.theme;
+    // biome-ignore lint/suspicious/noDocumentCookie: no alternative API for setting cookies
+    document.cookie = "theme=; max-age=0; path=/; SameSite=Lax";
+  } else {
+    document.documentElement.dataset.theme = pref;
+    // biome-ignore lint/suspicious/noDocumentCookie: no alternative API for setting cookies
+    document.cookie = `theme=${pref}; max-age=31536000; path=/; SameSite=Lax`;
+  }
+}

package/src/viewer/components/App.tsx

@@ -0,0 +1,73 @@
+import { useEffect, useState } from "preact/hooks";
+import type { DataProvider } from "../Providers.ts";
+import {
+  type ArchiveData,
+  ArchiveProvider,
+  ServerProvider,
+} from "../Providers.ts";
+import {
+  activeTabId,
+  defaultTabId,
+  provider,
+  reportData,
+  samplesLoaded,
+  sourceTabs,
+  urlError,
+} from "../State.ts";
+import { DropZone } from "./DropZone.tsx";
+import { Shell } from "./Shell.tsx";
+
+/** Reset viewer state and activate the appropriate default tab for the provider. */
+export function initViewer(p: DataProvider): void {
+  provider.value = p;
+  reportData.value = null;
+  samplesLoaded.value = false;
+  urlError.value = null;
+  sourceTabs.value = [];
+  activeTabId.value = defaultTabId();
+}
+
+export function App() {
+  const [resolved, setResolved] = useState(false);
+
+  useEffect(() => {
+    resolve().then(() => setResolved(true));
+  }, []);
+
+  if (provider.value) return <Shell />;
+  if (resolved) return <DropZone />;
+  return null;
+}
+
+/** Try archive URL param, preloaded data, then dev server -- first match wins. */
+async function resolve(): Promise<void> {
+  const archiveUrl = new URLSearchParams(window.location.search).get("url");
+  if (archiveUrl) {
+    try {
+      const resp = await fetch(archiveUrl);
+      if (resp.ok) {
+        initViewer(new ArchiveProvider((await resp.json()) as ArchiveData));
+        return;
+      }
+      urlError.value = { url: archiveUrl, detail: `(${resp.status})` };
+    } catch {
+      urlError.value = {
+        url: archiveUrl,
+        detail: "(Perhaps CORS or network error?)",
+      };
+    }
+  }
+
+  const preloaded = (window as unknown as Record<string, unknown>)
+    .__benchforgeArchive as ArchiveData | undefined;
+  if (preloaded) {
+    initViewer(new ArchiveProvider(preloaded));
+    return;
+  }
+
+  try {
+    initViewer(await ServerProvider.create());
+  } catch {
+    // No server available
+  }
+}

package/src/viewer/components/DropZone.tsx

@@ -0,0 +1,71 @@
+import { useRef, useState } from "preact/hooks";
+import { type ArchiveData, ArchiveProvider } from "../Providers.ts";
+import { urlError } from "../State.ts";
+import { initViewer } from "./App.tsx";
+
+/** Landing page for loading `.benchforge` archive files via drag-drop or file picker. */
+export function DropZone() {
+  const [dragOver, setDragOver] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  /** Parse an archive JSON file and initialize the viewer with its data. */
+  async function loadFile(file: File): Promise<void> {
+    try {
+      const text = await file.text();
+      const archive = JSON.parse(text) as ArchiveData;
+      initViewer(new ArchiveProvider(archive));
+    } catch (err) {
+      console.error("Failed to load archive:", err);
+      setError(String(err));
+    }
+  }
+
+  return (
+    <div
+      class={`drop-zone${dragOver ? " drag-over" : ""}`}
+      onDragOver={e => {
+        e.preventDefault();
+        setDragOver(true);
+      }}
+      onDragLeave={() => setDragOver(false)}
+      onDrop={async e => {
+        e.preventDefault();
+        setDragOver(false);
+        const file = e.dataTransfer?.files[0];
+        if (file) loadFile(file);
+      }}
+    >
+      <div class="drop-zone-content">
+        <h2>Benchforge Viewer</h2>
+        <p>
+          Drop a <code>.benchforge</code> file here to view results
+        </p>
+        <div class="drop-zone-divider">or</div>
+        <label class="drop-zone-browse">
+          Browse files
+          <input
+            ref={inputRef}
+            type="file"
+            accept=".benchforge"
+            hidden
+            onChange={() => {
+              const file = inputRef.current?.files?.[0];
+              if (file) loadFile(file);
+            }}
+          />
+        </label>
+        {urlError.value && (
+          <p class="drop-zone-error">
+            Failed to load archive from <b>{urlError.value.url}</b>.{" "}
+            {urlError.value.detail}
+            <p>Download the file and drop it here instead.</p>
+          </p>
+        )}
+        {error && (
+          <p class="drop-zone-error">Failed to load file: {error}</p>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/viewer/components/LazyPlot.ts

@@ -0,0 +1,33 @@
+import type { RefObject } from "preact";
+import { useEffect, useRef } from "preact/hooks";
+
+/**
+ * Lazy-import a plot module and mount the resulting element into a div ref.
+ * Defers the ~hundreds-of-KB `@observablehq/plot` + `d3` bundle until the
+ * Samples tab is actually opened, keeping the initial viewer load small.
+ */
+export function useLazyPlot(
+  render: () => Promise<Element | null | undefined>,
+  deps: unknown[],
+  errorLabel?: string,
+): RefObject<HTMLDivElement> {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    render()
+      .then(el => {
+        if (!ref.current || !el) return;
+        ref.current.innerHTML = "";
+        ref.current.appendChild(el);
+      })
+      .catch(err => {
+        console.error(`${errorLabel ?? "Plot"} failed:`, err);
+        if (ref.current) {
+          const div = document.createElement("div");
+          div.className = "loading";
+          div.textContent = String(err.message ?? err);
+          ref.current.replaceChildren(div);
+        }
+      });
+  }, deps);
+  return ref;
+}