benchforge 0.1.9 → 0.2.4

package/src/profiling/browser/BrowserProfiler.ts

@@ -0,0 +1,160 @@
+import type { GcStats } from "../../runners/GcStats.ts";
+import type { CoverageData } from "../node/CoverageTypes.ts";
+import type { HeapProfile, HeapSampleOptions } from "../node/HeapSampler.ts";
+import type { TimeProfile } from "../node/TimeSampler.ts";
+import { runBenchLoop } from "./BenchLoop.ts";
+import { collectTracing, startGcTracing } from "./BrowserCDP.ts";
+import { type CdpClient, connectCdp } from "./CdpClient.ts";
+import { type CdpPage, createCdpPage } from "./CdpPage.ts";
+import {
+  type ChromeInstance,
+  closeTab,
+  createTab,
+  launchChrome,
+} from "./ChromeLauncher.ts";
+import { runPageLoad } from "./PageLoadMode.ts";
+
+/** Options for a browser benchmark run. */
+export interface BrowserProfileParams {
+  /** URL to benchmark */
+  url: string;
+  /** Enable heap allocation profiling */
+  alloc?: boolean;
+  /** Heap sampling options (interval, depth) */
+  allocOptions?: HeapSampleOptions;
+  /** Enable CPU time profiling */
+  profile?: boolean;
+  /** CPU profiling sample interval in microseconds (default 1000) */
+  profileInterval?: number;
+  /** Track function call counts via V8 coverage */
+  callCounts?: boolean;
+  /** Collect GC statistics via CDP tracing */
+  gcStats?: boolean;
+  /** Run Chrome in headless mode */
+  headless?: boolean;
+  /** Path to Chrome executable */
+  chromePath?: string;
+  /** Chrome user data directory for persistent profile */
+  chromeProfile?: string;
+  /** Extra Chrome launch arguments */
+  chromeArgs?: string[];
+  /** Page timeout in seconds */
+  timeout?: number;
+  /** Bench function iteration time limit in ms */
+  maxTime?: number;
+  /** Exact iteration count for bench function mode */
+  maxIterations?: number;
+  /** Passive page-load profiling mode */
+  pageLoad?: boolean;
+  /** Completion signal: CSS selector, JS expression, "load", or "domcontentloaded" */
+  waitFor?: string;
+  /** Reuse an existing Chrome instance (caller manages lifecycle) */
+  chrome?: ChromeInstance;
+}
+
+/** Navigation timing metrics from the Performance API. */
+export interface NavTiming {
+  /** DOMContentLoaded time in ms */
+  domContentLoaded: number;
+  /** Load event time in ms */
+  loadEvent: number;
+  /** Largest Contentful Paint time in ms */
+  lcp?: number;
+}
+
+/** Collected profiles, timing samples, and GC stats from a browser benchmark. */
+export interface BrowserProfileResult {
+  /** Heap allocation profile */
+  heapProfile?: HeapProfile;
+  /** CPU time profile */
+  timeProfile?: TimeProfile;
+  /** V8 code coverage data */
+  coverage?: CoverageData;
+  /** Garbage collection statistics */
+  gcStats?: GcStats;
+  /** Wall-clock ms for the entire bench loop or page load */
+  wallTimeMs?: number;
+  /** Per-iteration timing samples (ms) from bench function mode */
+  samples?: number[];
+  /** Navigation timing from page-load mode */
+  navTiming?: NavTiming;
+}
+
+/** Shared context passed to bench/page-load mode runners. */
+export interface ProfileCtx {
+  page: CdpPage;
+  cdp: CdpClient;
+  params: BrowserProfileParams;
+  samplingInterval: number;
+}
+
+/**
+ * Run browser benchmark, auto-detecting mode:
+ * - Bench function (window.__bench): CLI controls iteration and timing.
+ * - Page load (no __bench, or --page-load): measures navigation timing.
+ */
+export async function profileBrowser(
+  params: BrowserProfileParams,
+): Promise<BrowserProfileResult> {
+  const {
+    headless = false,
+    chromePath,
+    chromeProfile,
+    chromeArgs: args,
+  } = params;
+  const owned = !params.chrome;
+  const launch = { headless, chromePath, chromeProfile, args };
+  const chrome = params.chrome ?? (await launchChrome(launch));
+  try {
+    const { wsUrl, targetId } = await createTab(chrome.port);
+    const cdp = await connectCdp(wsUrl);
+    try {
+      const timeout = (params.timeout ?? 60) * 1000;
+      const page = await createCdpPage(cdp, { timeout });
+      return await runProfile(page, cdp, params);
+    } finally {
+      cdp.close();
+      await closeTab(chrome.port, targetId);
+    }
+  } finally {
+    if (owned) await chrome.close();
+  }
+}
+
+/**
+ * Run profiling on an open CDP page, auto-detecting mode:
+ * - **bench**: page exports `window.__bench` ==> CLI iterates and times it
+ * - **page-load**: no `__bench` found (or `--page-load` flag) ==> profile navigation
+ *
+ * When auto-detecting, navigates once to check for `__bench`. If not found,
+ * reloads via `runPageLoad` which starts instruments before navigation.
+ */
+async function runProfile(
+  page: CdpPage,
+  cdp: CdpClient,
+  params: BrowserProfileParams,
+): Promise<BrowserProfileResult> {
+  const samplingInterval = params.allocOptions?.samplingInterval ?? 32768;
+  const traceEvents = params.gcStats ? await startGcTracing(cdp) : [];
+  const ctx = { page, cdp, params, samplingInterval };
+
+  let result: BrowserProfileResult;
+  if (params.pageLoad) {
+    result = await runPageLoad(ctx);
+  } else {
+    await page.navigate(params.url, { waitUntil: "load" });
+    const hasBench = await page.evaluate(
+      () => typeof (globalThis as any).__bench === "function",
+    );
+    if (hasBench) {
+      result = await runBenchLoop(ctx);
+    } else {
+      console.warn("No __bench found. Reloading in --page-load mode.");
+      result = await runPageLoad(ctx);
+    }
+  }
+
+  if (params.gcStats)
+    return { ...result, gcStats: await collectTracing(cdp, traceEvents) };
+  return result;
+}

package/src/profiling/browser/CdpClient.ts

@@ -0,0 +1,82 @@
+/** Minimal CDP WebSocket client. */
+export interface CdpClient {
+  send(method: string, params?: Record<string, unknown>): Promise<any>;
+  on(event: string, handler: (params: any) => void): void;
+  once(event: string, handler: (params: any) => void): void;
+  close(): void;
+}
+
+/** Connect to a CDP WebSocket endpoint and return a client. */
+export async function connectCdp(wsUrl: string): Promise<CdpClient> {
+  const ws = await openWebSocket(wsUrl);
+  let nextId = 1;
+  type Pending = { resolve: (v: any) => void; reject: (e: Error) => void };
+  const pending = new Map<number, Pending>();
+  const listeners = new Map<string, Set<(params: any) => void>>();
+
+  ws.addEventListener("message", event => {
+    const msg = JSON.parse(String(event.data));
+    if ("id" in msg) {
+      const p = pending.get(msg.id);
+      if (!p) return;
+      pending.delete(msg.id);
+      if (msg.error) p.reject(new Error(`CDP: ${msg.error.message}`));
+      else p.resolve(msg.result ?? {});
+    } else if ("method" in msg) {
+      for (const h of listeners.get(msg.method) ?? []) h(msg.params ?? {});
+    }
+  });
+
+  const client: CdpClient = {
+    send(method, params) {
+      return new Promise((resolve, reject) => {
+        const id = nextId++;
+        const timer = setTimeout(() => {
+          if (pending.delete(id))
+            reject(new Error(`CDP timeout after 60s: ${method}`));
+        }, 60_000);
+        const clear = () => clearTimeout(timer);
+        pending.set(id, {
+          resolve(v) {
+            clear();
+            resolve(v);
+          },
+          reject(e) {
+            clear();
+            reject(e);
+          },
+        });
+        ws.send(JSON.stringify({ id, method, params }));
+      });
+    },
+    on(event, handler) {
+      const set = listeners.get(event) ?? new Set();
+      listeners.set(event, set);
+      set.add(handler);
+    },
+    once(event, handler) {
+      const wrap = (params: any) => {
+        listeners.get(event)?.delete(wrap);
+        handler(params);
+      };
+      client.on(event, wrap);
+    },
+    close() {
+      for (const [, p] of pending) p.reject(new Error("CDP connection closed"));
+      pending.clear();
+      ws.close();
+    },
+  };
+  return client;
+}
+
+/** Open a WebSocket connection, rejecting if the handshake fails. */
+async function openWebSocket(wsUrl: string): Promise<WebSocket> {
+  const ws = new WebSocket(wsUrl);
+  const err = new Error(`CDP connect failed: ${wsUrl}`);
+  await new Promise<void>((resolve, reject) => {
+    ws.addEventListener("open", () => resolve());
+    ws.addEventListener("error", () => reject(err));
+  });
+  return ws;
+}

package/src/profiling/browser/CdpPage.ts

@@ -0,0 +1,138 @@
+import type { CdpClient } from "./CdpClient.ts";
+
+/** Page-level CDP abstraction for navigation, evaluation, and event handling. */
+export interface CdpPage {
+  navigate(
+    url: string,
+    opts?: { waitUntil?: "load" | "domcontentloaded" },
+  ): Promise<void>;
+  evaluate<R>(
+    fn: (...args: any[]) => R | Promise<R>,
+    arg?: unknown,
+  ): Promise<Awaited<R>>;
+  exposeFunction(name: string, fn: (...args: any[]) => any): Promise<void>;
+  addInitScript(fn: () => void): Promise<void>;
+  waitForSelector(selector: string): Promise<void>;
+  waitForFunction(expression: string): Promise<void>;
+  onPageError(handler: (message: string) => void): void;
+}
+
+/** Create a page abstraction over a CDP client connected to a page target. */
+export async function createCdpPage(
+  cdp: CdpClient,
+  opts?: { timeout?: number },
+): Promise<CdpPage> {
+  const timeout = opts?.timeout ?? 30_000;
+
+  await cdp.send("Page.enable");
+  await cdp.send("Runtime.enable");
+
+  return {
+    navigate: (url, navOpts) => cdpNavigate(cdp, url, navOpts),
+    evaluate: (fn, arg) => cdpEvaluate(cdp, fn, arg),
+    exposeFunction: (name, fn) => cdpExpose(cdp, name, fn),
+    async addInitScript(fn) {
+      await cdp.send("Page.addScriptToEvaluateOnNewDocument", {
+        source: `(${fn.toString()})()`,
+      });
+    },
+    waitForSelector(sel) {
+      const expr = `!!document.querySelector(${JSON.stringify(sel)})`;
+      return pollEval(cdp, expr, timeout);
+    },
+    waitForFunction: expr => pollEval(cdp, expr, timeout),
+    onPageError(handler) {
+      cdp.on("Runtime.exceptionThrown", ({ exceptionDetails: d }) => {
+        handler(d.exception?.description || d.text);
+      });
+    },
+  };
+}
+
+/** Navigate to a URL and wait for the specified load condition. */
+async function cdpNavigate(
+  cdp: CdpClient,
+  url: string,
+  navOpts?: { waitUntil?: "load" | "domcontentloaded" },
+): Promise<void> {
+  const waitUntil = navOpts?.waitUntil ?? "load";
+  const event =
+    waitUntil === "domcontentloaded"
+      ? "Page.domContentEventFired"
+      : "Page.loadEventFired";
+  const loaded = new Promise<void>(r => cdp.once(event, () => r()));
+  await cdp.send("Page.navigate", { url });
+  await loaded;
+}
+
+/** Evaluate a function in the page and return the result. */
+async function cdpEvaluate(
+  cdp: CdpClient,
+  fn: (...args: any[]) => any,
+  arg?: unknown,
+): Promise<any> {
+  const argStr = arg !== undefined ? JSON.stringify(arg) : "";
+  const expression = `(${fn.toString()})(${argStr})`;
+  const opts = { expression, awaitPromise: true, returnByValue: true };
+  const { result, exceptionDetails: err } = await cdp.send(
+    "Runtime.evaluate",
+    opts,
+  );
+  if (err) throw new Error(err.exception?.description || err.text);
+  return result.value;
+}
+
+/** Expose a Node function to the page via Runtime.addBinding. */
+async function cdpExpose(
+  cdp: CdpClient,
+  name: string,
+  fn: (...args: any[]) => any,
+): Promise<void> {
+  const binding = `__cdp_${name}`;
+  await cdp.send("Runtime.addBinding", { name: binding });
+
+  // Wrapper: page calls window[name](...) ==> binding fires ==> Node runs fn ==> resolve
+  const wrapper = `(() => {
+    const g = globalThis;
+    if (!g.__cdpSeq) { g.__cdpSeq = 0; g.__cdpCbs = {}; }
+    g[${JSON.stringify(name)}] = (...args) => new Promise((resolve, reject) => {
+      const seq = ++g.__cdpSeq;
+      g.__cdpCbs[seq] = { resolve, reject };
+      g[${JSON.stringify(binding)}](JSON.stringify({ seq, args }));
+    });
+  })()`;
+
+  await cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: wrapper });
+  await cdp.send("Runtime.evaluate", { expression: wrapper });
+
+  const pageEval = (expr: string) =>
+    cdp.send("Runtime.evaluate", { expression: expr });
+  cdp.on("Runtime.bindingCalled", async params => {
+    if (params.name !== binding) return;
+    const { seq, args } = JSON.parse(params.payload);
+    const cb = `globalThis.__cdpCbs[${seq}]`;
+    try {
+      const val = await fn(...args);
+      await pageEval(`${cb}?.resolve(${JSON.stringify(val ?? null)})`);
+    } catch (err: any) {
+      const msg = JSON.stringify(String(err.message));
+      await pageEval(`${cb}?.reject(new Error(${msg}))`);
+    }
+  });
+}
+
+/** Poll a JS expression until truthy, with timeout. */
+async function pollEval(
+  cdp: CdpClient,
+  expression: string,
+  timeout: number,
+): Promise<void> {
+  const deadline = Date.now() + timeout;
+  const evalOpts = { expression, returnByValue: true };
+  while (Date.now() < deadline) {
+    const { result } = await cdp.send("Runtime.evaluate", evalOpts);
+    if (result.value) return;
+    await new Promise(r => setTimeout(r, 100));
+  }
+  throw new Error(`Timed out waiting for: ${expression}`);
+}

package/src/profiling/browser/ChromeLauncher.ts

@@ -0,0 +1,158 @@
+import { type ChildProcess, execFileSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Handle for a running Chrome instance. */
+export interface ChromeInstance {
+  port: number;
+  process: ChildProcess;
+  close(): Promise<void>;
+}
+
+/** Flags to suppress background services irrelevant to benchmarking. */
+const quietFlags = [
+  "--disable-background-networking",
+  "--disable-client-side-phishing-detection",
+  "--disable-component-update",
+  "--disable-field-trial-config",
+  "--disable-sync",
+  "--disable-breakpad",
+  "--noerrdialogs",
+  "--disable-features=OptimizationHints,Translate,MediaRouter,DialMediaRouteProvider",
+  "--disable-extensions",
+  "--disable-component-extensions-with-background-pages",
+  "--disable-default-apps",
+  "--metrics-recording-only",
+  "--no-service-autorun",
+  "--password-store=basic",
+  "--use-mock-keychain",
+];
+
+/** Stderr patterns to suppress (irrelevant to benchmarking). */
+const chromeNoise =
+  /SharedImageManager|skia_output_device_buffer_queue|task_policy_set/;
+
+/** Launch Chrome with remote debugging and return instance handle. */
+export async function launchChrome(opts: {
+  headless?: boolean;
+  chromePath?: string;
+  chromeProfile?: string;
+  args?: string[];
+}): Promise<ChromeInstance> {
+  const { headless = false, chromeProfile, chromePath, args = [] } = opts;
+  const chrome = chromePath || process.env.CHROME_PATH || findChrome();
+
+  const tmpDir = chromeProfile
+    ? undefined
+    : await mkdtemp(join(tmpdir(), "benchforge-"));
+  const userDataDir = chromeProfile ?? tmpDir!;
+
+  const flags = [
+    "--remote-debugging-port=0",
+    `--user-data-dir=${userDataDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    ...quietFlags,
+    ...(headless ? ["--headless=new"] : []),
+    ...args,
+  ];
+
+  const proc = spawn(chrome, flags, { stdio: ["pipe", "pipe", "pipe"] });
+  const wsUrlPromise = parseWsUrl(proc);
+  pipeChromeOutput(proc);
+  const wsUrl = await wsUrlPromise;
+  const port = Number(new URL(wsUrl).port);
+
+  return {
+    port,
+    process: proc,
+    async close() {
+      proc.kill();
+      await new Promise<void>(r => proc.on("exit", () => r()));
+      if (tmpDir)
+        await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    },
+  };
+}
+
+/** Create a new browser tab and return its CDP WebSocket URL and target ID. */
+export async function createTab(
+  port: number,
+): Promise<{ wsUrl: string; targetId: string }> {
+  const url = `http://127.0.0.1:${port}/json/new`;
+  const resp = await fetch(url, { method: "PUT" });
+  const text = await resp.text();
+  try {
+    const json = JSON.parse(text);
+    return { wsUrl: json.webSocketDebuggerUrl, targetId: json.id };
+  } catch {
+    const msg = `Chrome /json/new returned non-JSON: ${text.slice(0, 200)}`;
+    throw new Error(msg);
+  }
+}
+
+/** Close a browser tab by target ID. */
+export async function closeTab(port: number, targetId: string): Promise<void> {
+  const url = `http://127.0.0.1:${port}/json/close/${targetId}`;
+  await fetch(url).catch(() => {});
+}
+
+/** Find Chrome/Chromium on the system. */
+function findChrome(): string {
+  if (process.platform === "darwin") {
+    const path = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+    if (existsSync(path)) return path;
+  }
+  if (process.platform === "win32") {
+    for (const env of ["ProgramFiles", "ProgramFiles(x86)"] as const) {
+      const base = process.env[env];
+      if (!base) continue;
+      const p = join(base, "Google", "Chrome", "Application", "chrome.exe");
+      if (existsSync(p)) return p;
+    }
+  }
+  for (const name of ["google-chrome", "chromium-browser", "chromium"]) {
+    try {
+      return execFileSync("which", [name], { encoding: "utf8" }).trim();
+    } catch {}
+  }
+  throw new Error(
+    "Chrome not found. Install Chrome or set CHROME_PATH, or use --chrome <path>.",
+  );
+}
+
+/** Parse the DevTools WebSocket URL from Chrome's stderr. */
+function parseWsUrl(proc: ChildProcess): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const wsPattern = /DevTools listening on (ws:\/\/\S+)/;
+    const onData = (chunk: Buffer) => {
+      const match = chunk.toString().match(wsPattern);
+      if (match) {
+        proc.stderr?.off("data", onData);
+        resolve(match[1]);
+      }
+    };
+    proc.stderr?.on("data", onData);
+    proc.on("error", reject);
+    proc.on("exit", code =>
+      reject(new Error(`Chrome exited (code ${code}) before DevTools ready`)),
+    );
+  });
+}
+
+/** Forward Chrome stdout/stderr to terminal, filtering known noise. */
+function pipeChromeOutput(proc: ChildProcess): void {
+  const forward = (stream: NodeJS.ReadableStream | null) =>
+    stream?.on("data", (chunk: Buffer) => {
+      const lines = chunk
+        .toString()
+        .split("\n")
+        .map(l => l.trim())
+        .filter(l => l && !chromeNoise.test(l));
+      for (const line of lines) process.stderr.write(`[chrome] ${line}\n`);
+    });
+  forward(proc.stdout);
+  forward(proc.stderr);
+}

package/src/profiling/browser/ChromeTraceEvent.ts

@@ -0,0 +1,28 @@
+/** Chrome Trace Event format (used by Perfetto and CDP tracing). */
+export interface TraceEvent {
+  /** Event type: M=metadata, C=counter, i=instant, B/E=begin/end, X=complete */
+  ph: string;
+
+  /** Timestamp in microseconds */
+  ts: number;
+
+  /** Process ID */
+  pid?: number;
+
+  /** Thread ID */
+  tid?: number;
+
+  /** Event category */
+  cat?: string;
+
+  name: string;
+
+  /** Arbitrary event arguments */
+  args?: Record<string, unknown>;
+
+  /** Scope for instant events: "t"=thread, "p"=process, "g"=global */
+  s?: string;
+
+  /** Duration for complete events (microseconds) */
+  dur?: number;
+}

package/src/profiling/browser/PageLoadMode.ts

@@ -0,0 +1,61 @@
+import {
+  instrumentOpts,
+  startInstruments,
+  stopInstruments,
+} from "./BrowserCDP.ts";
+import type {
+  BrowserProfileResult,
+  NavTiming,
+  ProfileCtx,
+} from "./BrowserProfiler.ts";
+import type { CdpPage } from "./CdpPage.ts";
+
+/** Run passive page-load profiling: instrument ==> navigate ==> wait ==> collect. */
+export async function runPageLoad(
+  ctx: ProfileCtx,
+): Promise<BrowserProfileResult> {
+  const { page, cdp, params, samplingInterval } = ctx;
+  const opts = instrumentOpts(params, samplingInterval);
+  await startInstruments(cdp, opts);
+
+  // Observe LCP via PerformanceObserver (avoids deprecated getEntriesByType warning)
+  await page.addInitScript(() => {
+    const g = globalThis as any;
+    g.__lcpTime = undefined;
+    new PerformanceObserver(list => {
+      const entries = list.getEntries();
+      if (entries.length) g.__lcpTime = entries.at(-1)!.startTime;
+    }).observe({ type: "largest-contentful-paint" as any, buffered: true });
+  });
+
+  const { url, waitFor } = params;
+
+  const isBuiltinWait = waitFor === "load" || waitFor === "domcontentloaded";
+  const waitUntil = isBuiltinWait ? waitFor : "load";
+  await page.navigate(url, { waitUntil });
+
+  if (waitFor && !isBuiltinWait) {
+    if (/^[#.[]/.test(waitFor)) {
+      await page.waitForSelector(waitFor);
+    } else {
+      await page.waitForFunction(waitFor);
+    }
+  }
+
+  const navTiming = await readNavTiming(page);
+  const collected = await stopInstruments(cdp, opts);
+  return { ...collected, navTiming, wallTimeMs: navTiming.loadEvent };
+}
+
+/** Read navigation timing from the page via Performance API. */
+export async function readNavTiming(page: CdpPage): Promise<NavTiming> {
+  return page.evaluate(() => {
+    const perf = performance as any;
+    const nav = perf.getEntriesByType("navigation")[0] ?? {};
+    return {
+      domContentLoaded: (nav.domContentLoadedEventEnd as number) ?? 0,
+      loadEvent: (nav.loadEventEnd as number) ?? 0,
+      lcp: (globalThis as any).__lcpTime as number | undefined,
+    };
+  });
+}

package/src/profiling/node/CoverageSampler.ts

@@ -0,0 +1,27 @@
+import { Session } from "node:inspector/promises";
+import type { CoverageData, ScriptCoverage } from "./CoverageTypes.ts";
+
+/** Run a function while collecting precise V8 coverage, return execution counts.
+ *  The session passed to `fn` can be shared with TimeSampler to avoid resetting counters. */
+export async function withCoverageProfiling<T>(
+  fn: (session: Session) => Promise<T> | T,
+): Promise<{ result: T; coverage: CoverageData }> {
+  const session = new Session();
+  session.connect();
+
+  try {
+    await session.post("Profiler.enable");
+    await session.post("Profiler.startPreciseCoverage", {
+      callCount: true,
+      detailed: true,
+    });
+    const result = await fn(session);
+    const raw = await session.post("Profiler.takePreciseCoverage");
+    const scripts = raw.result as unknown as ScriptCoverage[];
+    return { result, coverage: { scripts } };
+  } finally {
+    await session.post("Profiler.stopPreciseCoverage");
+    await session.post("Profiler.disable");
+    session.disconnect();
+  }
+}

package/src/profiling/node/CoverageTypes.ts

@@ -0,0 +1,23 @@
+/** Per-function execution counts from V8 Profiler.takePreciseCoverage (Node and CDP). */
+export interface CoverageData {
+  scripts: ScriptCoverage[];
+}
+
+/** Coverage data for a single script (file) */
+export interface ScriptCoverage {
+  url: string;
+  functions: FunctionCoverage[];
+}
+
+/** Coverage data for a single function within a script */
+export interface FunctionCoverage {
+  functionName: string;
+  ranges: CoverageRange[];
+}
+
+/** A byte-offset range within a function with its execution count */
+export interface CoverageRange {
+  startOffset: number;
+  endOffset: number;
+  count: number;
+}