benchforge 0.1.8 → 0.1.11

package/src/heap-sample/HeapSampleReport.ts

@@ -1,60 +1,79 @@
 import pc from "picocolors";
-import type { HeapProfile, ProfileNode } from "./HeapSampler.ts";
 
-/** Sum selfSize across all nodes in profile (before any filtering) */
-export function totalProfileBytes(profile: HeapProfile): number {
-  let total = 0;
-  function walk(node: ProfileNode): void {
-    total += node.selfSize;
-    for (const child of node.children || []) walk(child);
-  }
-  walk(profile.head);
-  return total;
-}
+import { formatBytes } from "../table-util/Formatters.ts";
+import type { HeapProfile, HeapSample } from "./HeapSampler.ts";
+import {
+  type ResolvedFrame,
+  type ResolvedProfile,
+  resolveProfile,
+} from "./ResolvedProfile.ts";
 
 export interface CallFrame {
   fn: string;
   url: string;
   line: number; // 1-indexed for display
-  col: number;
+  col?: number; // 1-indexed for display
 }
 
 export interface HeapSite {
   fn: string;
   url: string;
   line: number; // 1-indexed for display
-  col: number;
+  col?: number;
   bytes: number;
   stack?: CallFrame[]; // call stack from root to this frame
+  samples?: HeapSample[]; // individual allocation samples at this site
+  callers?: { stack: CallFrame[]; bytes: number }[]; // distinct caller paths
+}
+
+export type UserCodeFilter = (site: CallFrame) => boolean;
+
+export interface HeapReportOptions {
+  topN: number;
+  stackDepth?: number;
+  verbose?: boolean;
+  raw?: boolean; // dump every raw sample
+  userOnly?: boolean; // filter to user code only (hide node internals)
+  isUserCode?: UserCodeFilter; // predicate for user vs internal code
+  totalAll?: number; // total across all nodes (before filtering)
+  totalUserCode?: number; // total for user code only
+  sampleCount?: number; // number of samples taken
+}
+
+/** Sum selfSize across all nodes in profile (before any filtering) */
+export function totalProfileBytes(profile: HeapProfile): number {
+  return resolveProfile(profile).totalBytes;
 }
 
-/** Flatten profile tree into sorted list of allocation sites with call stacks */
-export function flattenProfile(profile: HeapProfile): HeapSite[] {
+/** Flatten resolved profile into sorted list of allocation sites with call stacks.
+ *  When raw samples are available, attaches them to corresponding sites. */
+export function flattenProfile(resolved: ResolvedProfile): HeapSite[] {
   const sites: HeapSite[] = [];
+  const nodeIdToSites = new Map<number, HeapSite[]>();
 
-  function walk(node: ProfileNode, stack: CallFrame[]): void {
-    const { functionName, url, lineNumber, columnNumber } = node.callFrame;
-    const fn = functionName || "(anonymous)";
-    const col = columnNumber ?? 0;
-    const frame: CallFrame = { fn, url: url || "", line: lineNumber + 1, col };
-    const newStack = [...stack, frame];
-
-    if (node.selfSize > 0) {
-      sites.push({
-        ...frame,
-        bytes: node.selfSize,
-        stack: newStack,
-      });
+  for (const node of resolved.allocationNodes) {
+    const frame = toCallFrame(node.frame);
+    const stack = node.stack.map(toCallFrame);
+    const site: HeapSite = { ...frame, bytes: node.selfSize, stack };
+    sites.push(site);
+    const existing = nodeIdToSites.get(node.nodeId);
+    if (existing) existing.push(site);
+    else nodeIdToSites.set(node.nodeId, [site]);
+  }
+
+  // Attach raw samples to their corresponding sites
+  for (const sample of resolved.sortedSamples ?? []) {
+    const matchingSites = nodeIdToSites.get(sample.nodeId);
+    if (!matchingSites) continue;
+    for (const site of matchingSites) {
+      if (!site.samples) site.samples = [];
+      site.samples.push(sample);
     }
-    for (const child of node.children || []) walk(child, newStack);
   }
 
-  walk(profile.head, []);
   return sites.sort((a, b) => b.bytes - a.bytes);
 }
 
-export type UserCodeFilter = (site: CallFrame) => boolean;
-
 /** Check if site is user code (not node internals) */
 export function isNodeUserCode(site: CallFrame): boolean {
   if (!site.url) return false;
@@ -81,38 +100,39 @@ export function filterSites(
   return sites.filter(isUser);
 }
 
-/** Aggregate sites by location (combine same file:line:col) */
+/** Aggregate sites by location (combine same file:line:col).
+ *  Tracks distinct caller stacks with byte weights when merging. */
 export function aggregateSites(sites: HeapSite[]): HeapSite[] {
   const byLocation = new Map<string, HeapSite>();
 
   for (const site of sites) {
-    const key = `${site.url}:${site.line}:${site.col}`;
+    // When column is unknown, include fn name to avoid merging distinct sites
+    const key =
+      site.col != null
+        ? `${site.url}:${site.line}:${site.col}`
+        : `${site.url}:${site.line}:?:${site.fn}`;
     const existing = byLocation.get(key);
     if (existing) {
       existing.bytes += site.bytes;
+      addCaller(existing, site);
     } else {
-      byLocation.set(key, { ...site });
+      const entry = { ...site };
+      if (site.stack) {
+        entry.callers = [{ stack: site.stack, bytes: site.bytes }];
+      }
+      byLocation.set(key, entry);
     }
   }
 
-  return [...byLocation.values()].sort((a, b) => b.bytes - a.bytes);
-}
-
-function fmtBytes(bytes: number): string {
-  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
-  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${bytes} B`;
-}
+  // Sort callers by bytes descending, use top caller as primary stack
+  for (const site of byLocation.values()) {
+    if (site.callers && site.callers.length > 1) {
+      site.callers.sort((a, b) => b.bytes - a.bytes);
+      site.stack = site.callers[0].stack;
+    }
+  }
 
-export interface HeapReportOptions {
-  topN: number;
-  stackDepth?: number;
-  verbose?: boolean;
-  userOnly?: boolean; // filter to user code only (hide node internals)
-  isUserCode?: UserCodeFilter; // predicate for user vs internal code
-  totalAll?: number; // total across all nodes (before filtering)
-  totalUserCode?: number; // total for user code only
-  sampleCount?: number; // number of samples taken
+  return [...byLocation.values()].sort((a, b) => b.bytes - a.bytes);
 }
 
 /** Format heap report for console output */
@@ -145,52 +165,105 @@ export function formatHeapReport(
   return lines.join("\n");
 }
 
-/** Compact single-line format: `49 MB  fn1 <- fn2 <- fn3` */
-function formatCompactSite(
+/** Get total bytes from sites */
+export function totalBytes(sites: HeapSite[]): number {
+  return sites.reduce((sum, s) => sum + s.bytes, 0);
+}
+
+/** Format every raw sample as one line, ordered by ordinal (time).
+ *  Output is tab-separated for easy piping/grep/diff. */
+export function formatRawSamples(resolved: ResolvedProfile): string {
+  if (!resolved.sortedSamples || resolved.sortedSamples.length === 0) {
+    return "No raw samples available.";
+  }
+
+  const lines: string[] = ["ordinal\tsize\tfunction\tlocation"];
+  for (const s of resolved.sortedSamples) {
+    const node = resolved.nodeMap.get(s.nodeId);
+    const fn = node?.frame.name || "(unknown)";
+    const url = node?.frame.url || "";
+    const loc = url
+      ? fmtLoc(url, node!.frame.line, node!.frame.col)
+      : "(unknown)";
+    lines.push(`${s.ordinal}\t${s.size}\t${fn}\t${loc}`);
+  }
+  return lines.join("\n");
+}
+
+function toCallFrame(f: ResolvedFrame): CallFrame {
+  return { fn: f.name, url: f.url, line: f.line, col: f.col };
+}
+
+/** Add a caller stack to an aggregated site, merging if the same path exists */
+function addCaller(existing: HeapSite, site: HeapSite): void {
+  if (!site.stack) return;
+  if (!existing.callers) {
+    existing.callers = [];
+  }
+  const key = callerKey(site.stack);
+  const match = existing.callers.find(c => callerKey(c.stack) === key);
+  if (match) {
+    match.bytes += site.bytes;
+  } else {
+    existing.callers.push({ stack: site.stack, bytes: site.bytes });
+  }
+}
+
+/** Verbose multi-line format with file:// paths and line numbers */
+function formatVerboseSite(
   lines: string[],
   site: HeapSite,
   stackDepth: number,
   isUser: UserCodeFilter,
 ): void {
   const bytes = fmtBytes(site.bytes).padStart(10);
-  const fns = [site.fn];
+  const loc = site.url ? fmtLoc(site.url, site.line, site.col) : "(unknown)";
+  const dimFn = isUser(site) ? (s: string) => s : pc.dim;
+
+  lines.push(dimFn(`${bytes}  ${site.fn}  ${loc}`));
 
   if (site.stack && site.stack.length > 1) {
     const callers = site.stack.slice(0, -1).reverse().slice(0, stackDepth);
     for (const frame of callers) {
       if (!frame.url || !isUser(frame)) continue;
-      fns.push(frame.fn);
+      const callerLoc = fmtLoc(frame.url, frame.line, frame.col);
+      lines.push(dimFn(`            <- ${frame.fn}  ${callerLoc}`));
     }
   }
-
-  const line = `${bytes}  ${fns.join(" <- ")}`;
-  lines.push(isUser(site) ? line : pc.dim(line));
 }
 
-/** Verbose multi-line format with file:// paths and line numbers */
-function formatVerboseSite(
+/** Compact single-line format: `49 MB  fn1 <- fn2 <- fn3` */
+function formatCompactSite(
   lines: string[],
   site: HeapSite,
   stackDepth: number,
   isUser: UserCodeFilter,
 ): void {
   const bytes = fmtBytes(site.bytes).padStart(10);
-  const loc = site.url ? `${site.url}:${site.line}:${site.col}` : "(unknown)";
-  const dimFn = isUser(site) ? (s: string) => s : pc.dim;
-
-  lines.push(dimFn(`${bytes}  ${site.fn}  ${loc}`));
+  const fns = [site.fn];
 
   if (site.stack && site.stack.length > 1) {
     const callers = site.stack.slice(0, -1).reverse().slice(0, stackDepth);
     for (const frame of callers) {
       if (!frame.url || !isUser(frame)) continue;
-      const callerLoc = `${frame.url}:${frame.line}:${frame.col}`;
-      lines.push(dimFn(`            <- ${frame.fn}  ${callerLoc}`));
+      fns.push(frame.fn);
     }
   }
+
+  const line = `${bytes}  ${fns.join(" <- ")}`;
+  lines.push(isUser(site) ? line : pc.dim(line));
 }
 
-/** Get total bytes from sites */
-export function totalBytes(sites: HeapSite[]): number {
-  return sites.reduce((sum, s) => sum + s.bytes, 0);
+function fmtBytes(bytes: number): string {
+  return formatBytes(bytes, { space: true }) ?? `${bytes} B`;
+}
+
+/** Format location, omitting column when unknown */
+function fmtLoc(url: string, line: number, col?: number): string {
+  return col != null ? `${url}:${line}:${col}` : `${url}:${line}`;
+}
+
+/** Serialize a call stack for dedup comparison */
+function callerKey(stack: CallFrame[]): string {
+  return stack.map(f => `${f.url}:${f.line}:${f.col}`).join("|");
 }

package/src/heap-sample/HeapSampler.ts

@@ -1,26 +1,68 @@
 import { Session } from "node:inspector/promises";
 
 export interface HeapSampleOptions {
-  samplingInterval?: number; // bytes between samples, default 32768
-  stackDepth?: number; // max stack frames, default 64
-  includeMinorGC?: boolean; // keep objects collected by minor GC, default true
-  includeMajorGC?: boolean; // keep objects collected by major GC, default true
+  /** Bytes between samples (default 32768) */
+  samplingInterval?: number;
+
+  /** Max stack frames (default 64) */
+  stackDepth?: number;
+
+  /** Keep objects collected by minor GC (default true) */
+  includeMinorGC?: boolean;
+
+  /** Keep objects collected by major GC (default true) */
+  includeMajorGC?: boolean;
 }
 
+/** V8 call frame location within a profiled script */
+export interface CallFrame {
+  /** Function name (empty string for anonymous) */
+  functionName: string;
+
+  /** Script URL or file path */
+  url: string;
+
+  /** Zero-based line number */
+  lineNumber: number;
+
+  /** Zero-based column number */
+  columnNumber?: number;
+}
+
+/** Node in the V8 sampling heap profile tree */
 export interface ProfileNode {
-  callFrame: {
-    functionName: string;
-    url: string;
-    lineNumber: number;
-    columnNumber?: number;
-  };
+  /** Call site for this allocation node */
+  callFrame: CallFrame;
+
+  /** Bytes allocated directly at this node (not children) */
   selfSize: number;
+
+  /** Unique node ID, links to {@link HeapSample.nodeId} */
+  id: number;
+
+  /** Child nodes in the call tree */
   children?: ProfileNode[];
 }
 
+/** Individual heap allocation sample from V8's SamplingHeapProfiler */
+export interface HeapSample {
+  /** Links to {@link ProfileNode.id} for stack lookup */
+  nodeId: number;
+
+  /** Allocation size in bytes */
+  size: number;
+
+  /** Monotonically increasing, gives temporal ordering */
+  ordinal: number;
+}
+
+/** V8 sampling heap profile tree with optional per-allocation samples */
 export interface HeapProfile {
+  /** Root of the profile call tree */
   head: ProfileNode;
-  samples?: number[]; // sample IDs (length = number of samples taken)
+
+  /** Per-allocation samples, if collected */
+  samples?: HeapSample[];
 }
 
 const defaultOptions: Required<HeapSampleOptions> = {
@@ -74,5 +116,6 @@ async function startSampling(
 
 async function stopSampling(session: Session): Promise<HeapProfile> {
   const { profile } = await session.post("HeapProfiler.stopSampling");
-  return profile as HeapProfile;
+  // V8 returns id/samples fields not in @types/node's incomplete SamplingHeapProfile
+  return profile as unknown as HeapProfile;
 }

package/src/heap-sample/ResolvedProfile.ts

@@ -0,0 +1,89 @@
+import type { HeapProfile, HeapSample, ProfileNode } from "./HeapSampler.ts";
+
+/** A call frame with display-ready 1-indexed source positions */
+export interface ResolvedFrame {
+  /** Function name, "(anonymous)" when empty */
+  name: string;
+
+  /** Script URL or file path, "" when unknown */
+  url: string;
+
+  /** 1-indexed line number */
+  line: number;
+
+  /** 1-indexed column number (undefined when unknown) */
+  col?: number;
+}
+
+/** A profile node with its resolved call stack from root to this node */
+export interface ResolvedNode {
+  /** The call frame at this node */
+  frame: ResolvedFrame;
+
+  /** Call stack from root to this node (inclusive) */
+  stack: ResolvedFrame[];
+
+  /** Bytes allocated directly at this node */
+  selfSize: number;
+
+  /** V8 node ID, used to match {@link HeapSample.nodeId} */
+  nodeId: number;
+}
+
+/** Pre-resolved heap profile: single tree walk produces all derived data */
+export interface ResolvedProfile {
+  /** All nodes from the profile tree, flattened */
+  nodes: ResolvedNode[];
+
+  /** nodeId -> ResolvedNode lookup */
+  nodeMap: Map<number, ResolvedNode>;
+
+  /** Nodes with selfSize > 0, sorted by selfSize descending */
+  allocationNodes: ResolvedNode[];
+
+  /** Samples sorted by ordinal (temporal order), if available */
+  sortedSamples: HeapSample[] | undefined;
+
+  /** Total bytes across all nodes (sum of selfSize) */
+  totalBytes: number;
+}
+
+/** Walk a HeapProfile tree once, producing a fully resolved intermediate form */
+export function resolveProfile(profile: HeapProfile): ResolvedProfile {
+  const nodes: ResolvedNode[] = [];
+  const nodeMap = new Map<number, ResolvedNode>();
+  let totalBytes = 0;
+
+  function walk(node: ProfileNode, parentStack: ResolvedFrame[]): void {
+    const { functionName, url, lineNumber, columnNumber } = node.callFrame;
+    const frame: ResolvedFrame = {
+      name: functionName || "(anonymous)",
+      url: url || "",
+      line: lineNumber + 1,
+      col: columnNumber != null ? columnNumber + 1 : undefined,
+    };
+    const stack = [...parentStack, frame];
+    const resolved: ResolvedNode = {
+      frame,
+      stack,
+      selfSize: node.selfSize,
+      nodeId: node.id,
+    };
+    nodes.push(resolved);
+    nodeMap.set(node.id, resolved);
+    totalBytes += node.selfSize;
+    for (const child of node.children || []) walk(child, stack);
+  }
+
+  walk(profile.head, []);
+
+  const allocationNodes = nodes
+    .filter(n => n.selfSize > 0)
+    .sort((a, b) => b.selfSize - a.selfSize);
+
+  const sortedSamples = profile.samples
+    ? [...profile.samples].sort((a, b) => a.ordinal - b.ordinal)
+    : undefined;
+
+  return { nodes, nodeMap, allocationNodes, sortedSamples, totalBytes };
+}

package/src/html/HtmlReport.ts

@@ -44,6 +44,39 @@ export async function generateHtmlReport(
   return { reportDir, server, closeServer };
 }
 
+/** Create a timestamped report directory under ./bench-report/ */
+async function createReportDir(): Promise<string> {
+  const base = "./bench-report";
+  await mkdir(base, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  return join(base, `report-${ts}`);
+}
+
+/** Read the pre-built browser plots bundle from dist/ */
+async function loadPlotsBundle(): Promise<string> {
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const builtPath = join(thisDir, "browser/index.js");
+  const devPath = join(thisDir, "../../dist/browser/index.js");
+  try {
+    return await readFile(builtPath, "utf-8");
+  } catch {}
+  return readFile(devPath, "utf-8");
+}
+
+/** Write an index.html in the parent dir that redirects to this report */
+async function writeLatestRedirect(reportDir: string): Promise<void> {
+  const baseDir = dirname(reportDir);
+  const reportName = reportDir.split("/").pop();
+  const html = `<!DOCTYPE html>
+<html><head>
+  <meta http-equiv="refresh" content="0; url=./${reportName}/">
+  <script>location.href = "./${reportName}/";</script>
+</head><body>
+  <a href="./${reportName}/">Latest report</a>
+</body></html>`;
+  await writeFile(join(baseDir, "index.html"), html, "utf-8");
+}
+
 /** Start HTTP server for report directory, trying fallback ports if needed */
 async function startReportServer(
   baseDir: string,
@@ -96,36 +129,3 @@ function tryListen(
     });
   });
 }
-
-/** Create a timestamped report directory under ./bench-report/ */
-async function createReportDir(): Promise<string> {
-  const base = "./bench-report";
-  await mkdir(base, { recursive: true });
-  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-  return join(base, `report-${ts}`);
-}
-
-/** Read the pre-built browser plots bundle from dist/ */
-async function loadPlotsBundle(): Promise<string> {
-  const thisDir = dirname(fileURLToPath(import.meta.url));
-  const builtPath = join(thisDir, "browser/index.js");
-  const devPath = join(thisDir, "../../dist/browser/index.js");
-  try {
-    return await readFile(builtPath, "utf-8");
-  } catch {}
-  return readFile(devPath, "utf-8");
-}
-
-/** Write an index.html in the parent dir that redirects to this report */
-async function writeLatestRedirect(reportDir: string): Promise<void> {
-  const baseDir = dirname(reportDir);
-  const reportName = reportDir.split("/").pop();
-  const html = `<!DOCTYPE html>
-<html><head>
-  <meta http-equiv="refresh" content="0; url=./${reportName}/">
-  <script>location.href = "./${reportName}/";</script>
-</head><body>
-  <a href="./${reportName}/">Latest report</a>
-</body></html>`;
-  await writeFile(join(baseDir, "index.html"), html, "utf-8");
-}