benchforge 0.1.11 → 0.2.4

package/src/test/ViewerStatic.static.e2e.test.ts

@@ -0,0 +1,137 @@
+import { createServer, type Server } from "node:http";
+import path from "node:path";
+import type { Browser } from "playwright";
+import { chromium } from "playwright";
+import sirv from "sirv";
+import { afterAll, beforeAll, expect, test } from "vitest";
+
+const viewerDir = path.resolve(import.meta.dirname!, "../../dist/viewer");
+const archivePath = path.resolve(
+  import.meta.dirname!,
+  "../../examples/simple-cli.benchforge",
+);
+
+let server: Server;
+let port: number;
+let browser: Browser;
+
+test("static viewer: drop zone appears on load", {
+  timeout: 30_000,
+}, async () => {
+  const page = await browser.newPage();
+  try {
+    await page.goto(`http://localhost:${port}`, { waitUntil: "networkidle" });
+    await page.locator(".drop-zone").waitFor({ state: "visible" });
+  } finally {
+    await page.close();
+  }
+});
+
+test("static viewer: archive upload shows summary with stats", {
+  timeout: 30_000,
+}, async () => {
+  const consoleErrors: string[] = [];
+  const page = await browser.newPage();
+  try {
+    page.on("console", msg => {
+      if (msg.type() === "error" && !msg.text().includes("WebGL"))
+        consoleErrors.push(msg.text());
+    });
+    await page.goto(`http://localhost:${port}`, { waitUntil: "networkidle" });
+
+    const fileInput = page.locator('.drop-zone input[type="file"]');
+    await fileInput.setInputFiles(archivePath);
+
+    await page
+      .locator(".drop-zone")
+      .waitFor({ state: "detached", timeout: 15_000 });
+
+    const summaryPanel = page.locator("#summary-panel");
+    const stats = summaryPanel.locator(".section-panel").first();
+    await stats.waitFor({ state: "visible", timeout: 15_000 });
+    const statRows = await summaryPanel.locator(".stat-row").count();
+    expect(statRows).toBeGreaterThan(0);
+  } finally {
+    await page.close();
+  }
+  expect(consoleErrors).toEqual([]);
+});
+
+test("static viewer: tab navigation after archive upload", {
+  timeout: 30_000,
+}, async () => {
+  const consoleErrors: string[] = [];
+  const page = await browser.newPage();
+  try {
+    page.on("console", msg => {
+      if (msg.type() === "error" && !msg.text().includes("WebGL"))
+        consoleErrors.push(msg.text());
+    });
+    await page.goto(`http://localhost:${port}`, { waitUntil: "networkidle" });
+
+    const fileInput = page.locator('.drop-zone input[type="file"]');
+    await fileInput.setInputFiles(archivePath);
+    await page
+      .locator(".drop-zone")
+      .waitFor({ state: "detached", timeout: 15_000 });
+
+    // Wait for summary to load
+    const summaryPanel = page.locator("#summary-panel");
+    await summaryPanel
+      .locator(".section-panel")
+      .first()
+      .waitFor({ state: "visible", timeout: 15_000 });
+
+    // Samples tab
+    await page.locator("#tab-samples").click();
+    const samplesPanel = page.locator("#samples-panel");
+    await samplesPanel
+      .locator("svg")
+      .first()
+      .waitFor({ state: "visible", timeout: 15_000 });
+
+    // Allocation tab
+    await page.locator("#tab-flamechart").click();
+    const allocFrame = page.frameLocator("#speedscope-iframe");
+    await allocFrame
+      .locator("body *")
+      .first()
+      .waitFor({ state: "visible", timeout: 15_000 });
+
+    // Back to Summary
+    await page.locator("#tab-summary").click();
+    await summaryPanel
+      .locator(".section-panel")
+      .first()
+      .waitFor({ state: "visible" });
+  } finally {
+    await page.close();
+  }
+  expect(consoleErrors).toEqual([]);
+});
+
+beforeAll(async () => {
+  const assets = sirv(viewerDir, { single: true });
+  server = createServer((req, res) => {
+    assets(req, res, () => {
+      res.statusCode = 404;
+      res.end("Not found");
+    });
+  });
+  const portP = new Promise<number>((resolve, reject) => {
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (typeof addr === "object" && addr) resolve(addr.port);
+      else reject(new Error("Failed to get server address"));
+    });
+  });
+  [port, browser] = await Promise.all([
+    portP,
+    chromium.launch({ headless: true }),
+  ]);
+});
+
+afterAll(async () => {
+  await browser?.close();
+  server?.close();
+});

package/src/{tests → test}/fixtures/baseline/impl.ts

@@ -1,4 +1,4 @@
-export const run = () => {
+export const run = (): void => {
   let _x = 0;
   for (let i = 0; i < 100; i++) _x++;
 };

package/src/{tests → test}/fixtures/bevy30-samples.ts

@@ -155,4 +155,6 @@ export const bevy30SamplesMs = [
 ] as number[];
 
 /** Get samples in nanoseconds */
-export const bevy30SamplesNs = bevy30SamplesMs.map(s => s * 1_000_000);
+export const bevy30SamplesNs: number[] = bevy30SamplesMs.map(
+  s => s * 1_000_000,
+);

package/src/test/fixtures/cases/asyncCases.ts

@@ -0,0 +1,9 @@
+/** Test cases module with async loadCase */
+export const cases: string[] = ["alpha", "beta"];
+
+export async function loadCase(
+  id: string,
+): Promise<{ data: string; metadata: { original: string } }> {
+  await Promise.resolve(); // simulate async
+  return { data: id.toUpperCase(), metadata: { original: id } };
+}

package/src/{tests → test}/fixtures/cases/cases.ts

@@ -1,7 +1,10 @@
 /** Test cases module for Phase 3 testing */
-export const cases = ["small", "large"];
+export const cases: string[] = ["small", "large"];
 
-export function loadCase(id: string) {
+export function loadCase(id: string): {
+  data: number[];
+  metadata: { size: number };
+} {
   const data =
     id === "small" ? [1, 2, 3] : Array.from({ length: 100 }, (_, i) => i);
   return { data, metadata: { size: data.length } };

package/src/test/fixtures/cases/variants/product.ts

@@ -0,0 +1,2 @@
+/** Variant that multiplies array elements */
+export const run = (arr: number[]): number => arr.reduce((a, b) => a * b, 1);

package/src/test/fixtures/cases/variants/sum.ts

@@ -0,0 +1,2 @@
+/** Variant that sums array elements */
+export const run = (arr: number[]): number => arr.reduce((a, b) => a + b, 0);

package/src/test/fixtures/discover/fast.ts

@@ -0,0 +1 @@
+export const run = (): void => {};

package/src/{tests → test}/fixtures/discover/slow.ts

@@ -1,4 +1,4 @@
-export const run = () => {
+export const run = (): void => {
   let _x = 0;
   for (let i = 0; i < 100; i++) _x++;
 };

package/src/test/fixtures/invalid/bad.ts

@@ -0,0 +1 @@
+export const notRun = (): void => {};

package/src/test/fixtures/loader/fast.ts

@@ -0,0 +1 @@
+export const run = (): void => {};

package/src/{tests → test}/fixtures/loader/slow.ts

@@ -1,4 +1,4 @@
-export const run = () => {
+export const run = (): void => {
   let _x = 0;
   for (let i = 0; i < 100; i++) _x++;
 };

package/src/test/fixtures/loader/stateful.ts

@@ -0,0 +1,2 @@
+export const setup = (data: unknown): { value: unknown } => ({ value: data });
+export const run = (state: { value: unknown }): unknown => state.value;

package/src/test/fixtures/stateful/stateful.ts

@@ -0,0 +1,2 @@
+export const setup = (data: unknown): { value: unknown } => ({ value: data });
+export const run = (state: { value: unknown }): unknown => state.value;

package/src/test/fixtures/variants/extra.ts

@@ -0,0 +1 @@
+export const run = (): void => {};

package/src/test/fixtures/variants/impl.ts

@@ -0,0 +1 @@
+export const run = (): void => {};

package/src/test/fixtures/worker/fast.ts

@@ -0,0 +1 @@
+export const run = (): void => {};

package/src/{tests → test}/fixtures/worker/slow.ts

@@ -1,4 +1,4 @@
-export const run = () => {
+export const run = (): void => {
   let _x = 0;
   for (let i = 0; i < 100; i++) _x++;
 };

package/src/viewer/DateFormat.ts

@@ -0,0 +1,30 @@
+/** Format ISO date as local time with UTC: "Jan 9, 2026, 3:45 PM (2026-01-09T23:45:00Z)" */
+export function formatDateWithTimezone(isoDate: string): string {
+  const date = new Date(isoDate);
+  const local = date.toLocaleString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+  const utc = date.toISOString().replace(".000Z", "Z");
+  return `${local} (${utc})`;
+}
+
+/** Format relative time: "5m ago", "2h ago", "yesterday", "3 days ago" */
+export function formatRelativeTime(isoDate: string): string {
+  const date = new Date(isoDate);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
+
+  if (diffMins < 1) return "just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays === 1) return "yesterday";
+  if (diffDays < 30) return `${diffDays} days ago`;
+  return date.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+}

package/src/viewer/Helpers.ts

@@ -0,0 +1,23 @@
+/** Escape a string for safe insertion into HTML. */
+export function escapeHtml(s: string): string {
+  const el = document.createElement("div");
+  el.textContent = s;
+  return el.innerHTML;
+}
+
+/** Infer a Shiki language id from a file extension. */
+export function guessLang(file: string): string {
+  if (file.endsWith(".ts") || file.endsWith(".tsx")) return "typescript";
+  if (file.endsWith(".css")) return "css";
+  if (file.endsWith(".html")) return "html";
+  return "javascript";
+}
+
+/** Extract the pathname from a URL, returning the input unchanged if it isn't a valid URL. */
+export function filePathFromUrl(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}

package/src/viewer/LineData.ts

@@ -0,0 +1,120 @@
+import type { ViewerCoverageData, ViewerSpeedscopeFile } from "./Providers.ts";
+
+/** Per-line profiling metrics for source gutter display. */
+export interface LineGutterData {
+  allocBytes: Map<number, number>;
+  selfTimeUs: Map<number, number>;
+  callCounts: Map<number, number>;
+}
+
+/** Aggregate per-line profiling data for a source file from speedscope profiles. */
+export function computeLineData(
+  file: string,
+  allocProfile: ViewerSpeedscopeFile | null,
+  timeProfile: ViewerSpeedscopeFile | null,
+  coverage: ViewerCoverageData | null,
+): LineGutterData {
+  return {
+    allocBytes: aggregateSelf(file, allocProfile),
+    selfTimeUs: aggregateSelf(file, timeProfile),
+    callCounts: extractCallCounts(file, coverage),
+  };
+}
+
+/** Format byte count for gutter display, scaling to KB/MB as appropriate. */
+export function formatGutterBytes(bytes: number | undefined): string {
+  if (!bytes) return "";
+  return formatDecimalBytes(bytes);
+}
+
+/** Format bytes using decimal (SI) units: KB = 1000, MB = 1e6, GB = 1e9. */
+export function formatDecimalBytes(bytes: number): string {
+  if (bytes >= 1e9) return (bytes / 1e9).toFixed(1) + " GB";
+  if (bytes >= 1e6) return (bytes / 1e6).toFixed(1) + " MB";
+  if (bytes >= 1e3) return (bytes / 1e3).toFixed(1) + " KB";
+  return bytes + " B";
+}
+
+/** Format microsecond duration for gutter display, scaling to ms/s as appropriate. */
+export function formatGutterTime(us: number | undefined): string {
+  if (!us) return "";
+  if (us >= 1_000_000) return (us / 1_000_000).toFixed(1) + " s";
+  if (us >= 1_000) return (us / 1_000).toFixed(1) + " ms";
+  return us.toFixed(0) + " us";
+}
+
+/** Format large counts with K/M suffixes (e.g. 1234567 ==> "1.2M"). */
+export function formatCount(n: number): string {
+  if (n >= 1e6) return (n / 1e6).toFixed(1) + "M";
+  if (n >= 1e3) return (n / 1e3).toFixed(1) + "K";
+  return n.toLocaleString();
+}
+
+/** Format a call count for gutter display, scaling to K/M as appropriate. */
+export function formatGutterCount(count: number | undefined): string {
+  if (!count) return "";
+  return formatCount(count);
+}
+
+/** Accumulate weight for the deepest (self) frame matching `file` in each sample. */
+function aggregateSelf(
+  file: string,
+  profile: ViewerSpeedscopeFile | null,
+): Map<number, number> {
+  const result = new Map<number, number>();
+  if (!profile) return result;
+
+  const { frames } = profile.shared;
+
+  const fileFrames = new Map<number, number>(); // frameIndex -> line
+  frames.forEach((frame, i) => {
+    if (frame.line && frame.file && fileMatches(frame.file, file))
+      fileFrames.set(i, frame.line);
+  });
+  if (fileFrames.size === 0) return result;
+
+  for (const p of profile.profiles) {
+    for (let i = 0; i < p.samples.length; i++) {
+      const leaf = p.samples[i].at(-1)!;
+      const line = fileFrames.get(leaf);
+      if (line !== undefined)
+        result.set(line, (result.get(line) || 0) + p.weights[i]);
+    }
+  }
+  return result;
+}
+
+/** Extract per-function call counts from coverage data for a file. */
+function extractCallCounts(
+  file: string,
+  coverage: ViewerCoverageData | null,
+): Map<number, number> {
+  const result = new Map<number, number>();
+  if (!coverage) return result;
+
+  const entries = coverage[file] ?? findCoverageEntries(file, coverage);
+  if (!entries) return result;
+
+  for (const entry of entries) {
+    if (entry.count <= 0) continue;
+    const prev = result.get(entry.startLine) || 0;
+    if (entry.count > prev) result.set(entry.startLine, entry.count);
+  }
+  return result;
+}
+
+/** Check if a frame's file URL matches the target file path. */
+function fileMatches(frameFile: string, target: string): boolean {
+  if (frameFile === target) return true;
+  // Frame files may be full URLs while target is a bare path, or vice versa
+  try {
+    if (new URL(frameFile).pathname === target) return true;
+  } catch {}
+  return frameFile.endsWith(target) || target.endsWith(frameFile);
+}
+
+/** Find coverage entries by URL matching when exact key lookup fails. */
+function findCoverageEntries(file: string, coverage: ViewerCoverageData) {
+  const matchingUrl = Object.keys(coverage).find(url => fileMatches(url, file));
+  return matchingUrl ? coverage[matchingUrl] : undefined;
+}

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` };
+  }
+}