benchforge 0.1.11 → 0.2.4

package/src/cli/CliArgs.ts

@@ -3,73 +3,186 @@ import yargs from "yargs";
 
 export type Configure<T> = (yargs: Argv) => Argv<T>;
 
-/** CLI args type inferred from cliOptions, plus optional file positional */
+/** CLI args type inferred from cliOptions, plus optional file positional. */
 export type DefaultCliArgs = InferredOptionTypes<typeof cliOptions> & {
   file?: string;
 };
 
-export const defaultAdaptiveMaxTime = 20;
-
 // biome-ignore format: compact option definitions
 const cliOptions = {
-  time:           { type: "number",  default: 0.642, requiresArg: true, describe: "test duration in seconds" },
-  cpu:            { type: "boolean", default: false, describe: "CPU counter measurements (requires root)" },
-  collect:        { type: "boolean", default: false, describe: "force GC after each iteration" },
-  "gc-stats":     { type: "boolean", default: false, describe: "collect GC statistics (Node: --trace-gc-nvp, browser: CDP tracing)" },
-  profile:        { type: "boolean", default: false, describe: "run once for profiling" },
-  filter:         { type: "string",  requiresArg: true, describe: "filter benchmarks by regex or substring" },
-  all:            { type: "boolean", default: false, describe: "run all cases (ignore defaultCases)" },
-  worker:         { type: "boolean", default: true, describe: "run in worker process for isolation (default: true)" },
-  adaptive:       { type: "boolean", default: false, describe: "adaptive sampling (experimental)" },
-  "min-time":     { type: "number",  default: 1, describe: "minimum time before adaptive convergence can stop" },
-  convergence:    { type: "number",  default: 95, describe: "adaptive confidence threshold (0-100)" },
-  warmup:         { type: "number",  default: 0, describe: "warmup iterations before measurement" },
-  html:           { type: "boolean", default: false, describe: "generate HTML report and open in browser" },
-  "export-html":  { type: "string",  requiresArg: true, describe: "export HTML report to specified file" },
-  json:           { type: "string",  requiresArg: true, describe: "export benchmark data to JSON file" },
-  "export-perfetto":    { type: "string",  requiresArg: true, describe: "export Perfetto trace file (view at ui.perfetto.dev)" },
-  speedscope:           { type: "boolean", default: false, describe: "open heap profile in speedscope (via npx)" },
-  "export-speedscope":  { type: "string",  requiresArg: true, describe: "export heap profile as speedscope JSON" },
-  "trace-opt":    { type: "boolean", default: false, describe: "trace V8 optimization tiers (requires --allow-natives-syntax)" },
-  "skip-settle":  { type: "boolean", default: false, describe: "skip post-warmup settle time (see V8 optimization cold start)" },
-  "pause-first":  { type: "number",  describe: "iterations before first pause (then pause-interval applies)" },
+  duration:         { type: "number",  requiresArg: true, describe: "duration per batch in seconds (default: 0.642)" },
+  iterations:       { type: "number",  requiresArg: true, describe: "iterations per batch (page loads for page-load mode, inner loop for bench)" },
+  warmup:           { type: "number",  default: 0, describe: "warmup iterations before measurement" },
+  filter:           { type: "string",  requiresArg: true, describe: "filter by name/regex. Matrix: case/variant, case/, /variant" },
+  all:              { type: "boolean", default: false, describe: "run all cases (ignore defaultCases)" },
+  list:             { type: "boolean", default: false, describe: "list available benchmarks (or matrix cases/variants)" },
+  worker:           { type: "boolean", default: true, describe: "run in worker process for isolation (default: true)" },
+  batches:          { type: "number",  default: 1, describe: "divide time into N batches, alternating baseline/current order" },
+  "warmup-batch":   { type: "boolean", default: false, describe: "include first batch in results (normally dropped to avoid OS cache warmup)" },
+  "equiv-margin":   { type: "number",  default: 2, describe: "equivalence margin % for baseline comparison (0 to disable)" },
+  "no-batch-trim":  { type: "boolean", default: false, describe: "disable Tukey trimming of outlier batches" },
+  "pause-first":    { type: "number",  describe: "iterations before first pause (then pause-interval applies)" },
   "pause-interval": { type: "number", default: 0, describe: "iterations between pauses for V8 optimization (0 to disable)" },
   "pause-duration": { type: "number", default: 100, describe: "pause duration in ms for V8 optimization" },
-  batches:          { type: "number",  default: 1, describe: "divide time into N batches, alternating baseline/current order" },
-  iterations:       { type: "number",  requiresArg: true, describe: "exact number of iterations (overrides --time)" },
-  "heap-sample":    { type: "boolean", default: false, describe: "heap sampling allocation attribution (includes garbage)" },
-  "heap-interval":  { type: "number",  default: 32768, describe: "heap sampling interval in bytes" },
-  "heap-depth":     { type: "number",  default: 64, describe: "heap sampling stack depth" },
-  "heap-rows":      { type: "number",  default: 20, describe: "top allocation sites to show" },
-  "heap-stack":     { type: "number",  default: 3, describe: "call stack depth to display" },
-  "heap-verbose":   { type: "boolean", default: false, describe: "verbose output with file:// paths and line numbers" },
-  "heap-raw":       { type: "boolean", default: false, describe: "dump every raw heap sample (ordinal, size, stack)" },
-  "heap-user-only": { type: "boolean", default: false, describe: "filter to user code only (hide node internals)" },
+  "gc-stats":       { type: "boolean", default: false, describe: "collect GC statistics (Node: --trace-gc-nvp, browser: CDP tracing)" },
+  "gc-force":       { type: "boolean", default: false, describe: "force GC after each iteration" },
+  adaptive:         { type: "boolean", default: false, describe: "adaptive sampling (experimental)" },
+  "min-time":       { type: "number",  default: 1, describe: "minimum time before adaptive convergence can stop" },
+  convergence:      { type: "number",  default: 95, describe: "adaptive confidence threshold (0-100)" },
+  alloc:            { type: "boolean", default: false, describe: "allocation sampling attribution (includes garbage)" },
+  "alloc-interval": { type: "number",  default: 32768, describe: "allocation sampling interval in bytes" },
+  "alloc-depth":    { type: "number",  default: 64, describe: "allocation sampling stack depth" },
+  "alloc-rows":     { type: "number",  default: 20, describe: "top allocation sites to show" },
+  "alloc-stack":    { type: "number",  default: 3, describe: "call stack depth to display" },
+  "alloc-verbose":  { type: "boolean", default: false, describe: "verbose output with file:// paths and line numbers" },
+  "alloc-raw":      { type: "boolean", default: false, describe: "dump every raw allocation sample (ordinal, size, stack)" },
+  "alloc-user-only":{ type: "boolean", default: false, describe: "filter to user code only (hide node internals)" },
+  profile:          { type: "boolean", default: false, alias: "time-sample", describe: "V8 CPU time sampling profiler" },
+  "profile-interval":{ type: "number", default: 1000, alias: "time-interval", describe: "CPU sampling interval in microseconds" },
+  "call-counts":    { type: "boolean", default: false, describe: "collect per-function execution counts via V8 precise coverage" },
+  stats:            { type: "string",  default: "mean,p50,p99", describe: "timing columns: mean|median|min|max|p<N> (e.g. mean,p70,p99)" },
+  view:             { type: "boolean", default: false, alias: "html", describe: "open viewer in browser" },
+  "view-serve":     { type: "boolean", default: false, describe: "start viewer server without opening browser (reload an existing tab)" },
+  "export-perfetto":{ type: "string",  requiresArg: true, describe: "export Perfetto trace file (view at ui.perfetto.dev)" },
+  "export-profile": { type: "string",  requiresArg: true, alias: "export-time", describe: "export CPU profile as .cpuprofile (V8/Chrome DevTools format)" },
+  archive:          { type: "string",  describe: "archive profile + sources to .benchforge file" },
+  editor:           { type: "string",  default: "vscode", describe: "editor for source links: vscode, cursor, or custom://scheme" },
+  inspect:          { type: "boolean", default: false, describe: "run once for external profiler attach" },
+  "trace-opt":      { type: "boolean", default: false, describe: "trace V8 optimization tiers (requires --allow-natives-syntax)" },
+  "pause-warmup":   { type: "number",  default: 0, requiresArg: true, describe: "post-warmup settle time in ms for V8 background compilation (0 to skip)" },
   url:              { type: "string",  requiresArg: true, describe: "page URL for browser profiling (enables browser mode)" },
-  headless:         { type: "boolean", default: true, describe: "run browser in headless mode" },
+  "page-load":      { type: "boolean", default: false, describe: "passive page-load profiling (no __bench needed)" },
+  "wait-for":       { type: "string",  requiresArg: true, describe: "page-load completion: CSS selector, JS expression, 'load', or 'domcontentloaded'" },
+  headless:         { type: "boolean", default: false, describe: "run browser in headless mode (default: headed)" },
   timeout:          { type: "number",  default: 60, describe: "browser page timeout in seconds" },
+  chrome:           { type: "string",  requiresArg: true, describe: "Chrome binary path (default: auto-detect or CHROME_PATH)" },
+  "chrome-profile": { type: "string",  requiresArg: true, describe: "Chrome user profile directory (default: temp profile)" },
+  "baseline-url":   { type: "string",  requiresArg: true, describe: "baseline URL for A/B comparison (fresh tab per batch)" },
   "chrome-args":    { type: "string",  array: true, requiresArg: true, describe: "extra Chromium flags" },
 } as const;
 
-/** @return yargs with standard benchmark options */
-export function defaultCliArgs(yargsInstance: Argv): Argv<DefaultCliArgs> {
-  return yargsInstance
-    .command("$0 [file]", "run benchmarks", y => {
-      y.positional("file", {
-        type: "string",
-        describe: "benchmark file to run",
-      });
-    })
-    .options(cliOptions)
-    .help()
-    .strict() as Argv<DefaultCliArgs>;
-}
+export const defaultDuration = 0.642;
+export const defaultAdaptiveMaxTime = 20;
+
+/** Default values for all CLI options, including alias keys for yargs filtering. */
+export const cliDefaults: Record<string, unknown> = Object.fromEntries(
+  Object.entries(cliOptions)
+    .filter(([, opt]) => "default" in opt)
+    .flatMap(([key, opt]) => {
+      const o = opt as Record<string, unknown>;
+      const entries: [string, unknown][] = [[key, o.default]];
+      if (o.alias) entries.push([o.alias as string, o.default]);
+      return entries;
+    }),
+);
+
+const optionGroups = {
+  "Run:": ["duration", "iterations"],
+  "Batching:": ["batches", "warmup-batch", "no-batch-trim"],
+  "Node:": ["worker", "inspect"],
+  "Browser:": [
+    "url",
+    "baseline-url",
+    "page-load",
+    "wait-for",
+    "headless",
+    "timeout",
+    "chrome",
+    "chrome-profile",
+    "chrome-args",
+  ],
+  "GC:": ["gc-stats", "gc-force"],
+  "Allocation Profiling:": [
+    "alloc",
+    "alloc-interval",
+    "alloc-depth",
+    "alloc-rows",
+    "alloc-stack",
+    "alloc-verbose",
+    "alloc-raw",
+    "alloc-user-only",
+  ],
+  "CPU Profiling:": ["profile", "profile-interval", "call-counts"],
+  "Output:": [
+    "stats",
+    "view",
+    "view-serve",
+    "equiv-margin",
+    "archive",
+    "export-perfetto",
+    "export-profile",
+    "editor",
+  ],
+  "Selecting Benchmarks:": ["filter", "all", "list"],
+  "V8 Tuning:": [
+    "warmup",
+    "trace-opt",
+    "pause-first",
+    "pause-interval",
+    "pause-duration",
+    "pause-warmup",
+  ],
+  "Adaptive:": ["adaptive", "min-time", "convergence"],
+} as const;
 
-/** @return parsed command line arguments */
+const { url: _url, ...browserOnlyOptions } = cliOptions;
+
+/** Parse command line arguments with optional custom yargs configuration. */
 export function parseCliArgs<T = DefaultCliArgs>(
   args: string[],
   configure: Configure<T> = defaultCliArgs as Configure<T>,
 ): T {
-  const yargsInstance = configure(yargs(args));
-  return yargsInstance.parseSync() as T;
+  return configure(yargs(args)).parseSync() as T;
+}
+
+/** Configure yargs for browser benchmarking with url as a required positional. */
+export function browserCliArgs(yargsInstance: Argv): Argv<DefaultCliArgs> {
+  return applyGroups(
+    yargsInstance
+      .command("$0 <url>", "run browser benchmarks", y => {
+        y.positional("url", {
+          type: "string",
+          describe: "page URL for browser profiling",
+        });
+      })
+      .options(browserOnlyOptions)
+      .help()
+      .strict(),
+  ) as Argv<DefaultCliArgs>;
+}
+
+/** Configure yargs with standard benchmark options and file positional. */
+export function defaultCliArgs(yargsInstance: Argv): Argv<DefaultCliArgs> {
+  return applyGroups(
+    yargsInstance
+      .command("$0 [file]", "run benchmarks", y => {
+        y.positional("file", {
+          type: "string",
+          describe: "benchmark file to run",
+        });
+      })
+      .options(cliOptions)
+      .help()
+      .strict(),
+  ) as Argv<DefaultCliArgs>;
+}
+
+/** Strip yargs internals (`_`, `$0`) and undefined values, converting kebab-case to camelCase. */
+export function cleanCliArgs(args: DefaultCliArgs): Record<string, unknown> {
+  const skip = new Set(["_", "$0"]);
+  const camel = (k: string) =>
+    k.replace(/-([a-z])/g, (_, l: string) => l.toUpperCase());
+  return Object.fromEntries(
+    Object.entries(args)
+      .filter(([k, v]) => v !== undefined && v !== null && !skip.has(k))
+      .map(([k, v]) => [camel(k), v]),
+  );
+}
+
+/** Assign options to their labeled groups in yargs help output. */
+function applyGroups(y: Argv): Argv {
+  return Object.entries(optionGroups).reduce(
+    (acc, [label, keys]) => acc.group(keys as unknown as string[], label),
+    y,
+  );
 }

package/src/cli/CliExport.ts

@@ -0,0 +1,179 @@
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { buildSpeedscopeFile } from "../export/AllocExport.ts";
+import { archiveBenchmark, collectSources } from "../export/ArchiveExport.ts";
+import {
+  annotateFramesWithCounts,
+  buildCoverageMap,
+} from "../export/CoverageExport.ts";
+import { resolveEditorUri } from "../export/EditorUri.ts";
+import { exportPerfettoTrace } from "../export/PerfettoExport.ts";
+import { buildTimeSpeedscopeFile } from "../export/TimeExport.ts";
+import type { CoverageData } from "../profiling/node/CoverageTypes.ts";
+import type { TimeProfile } from "../profiling/node/TimeSampler.ts";
+import type { ReportGroup, ReportSection } from "../report/BenchmarkReport.ts";
+import { groupReports } from "../report/BenchmarkReport.ts";
+import type { GitVersion } from "../report/GitUtils.ts";
+import { prepareHtmlData } from "../report/HtmlReport.ts";
+import type { ReportData } from "../viewer/ReportData.ts";
+import type { DefaultCliArgs } from "./CliArgs.ts";
+import {
+  cliComparisonOptions,
+  cliHeapReportOptions,
+  needsAlloc,
+} from "./CliOptions.ts";
+import { printHeapReports, withStatus } from "./CliReport.ts";
+import {
+  optionalJson,
+  startViewerServer,
+  waitForCtrlC,
+} from "./ViewerServer.ts";
+
+/** Options for exporting benchmark results to various formats */
+export interface ExportOptions {
+  results: ReportGroup[];
+  args: DefaultCliArgs;
+  sections?: ReportSection[];
+  currentVersion?: GitVersion;
+  baselineVersion?: GitVersion;
+}
+
+/** Export options for matrix benchmarks (results/args supplied by the matrix pipeline). */
+export interface MatrixExportOptions {
+  sections?: ReportSection[];
+  currentVersion?: GitVersion;
+  baselineVersion?: GitVersion;
+}
+
+type FrameContainer = {
+  shared: { frames: { name: string; file?: string; line?: number }[] };
+};
+
+/** Export reports (JSON, Perfetto, archive, viewer) based on CLI args. */
+export async function exportReports(options: ExportOptions): Promise<void> {
+  const { results, args, sections, currentVersion, baselineVersion } = options;
+
+  const wantViewer = args.view || args["view-serve"] || args.archive != null;
+  const comparison = cliComparisonOptions(args);
+  const htmlOpts = {
+    cliArgs: args,
+    sections,
+    currentVersion,
+    baselineVersion,
+    ...comparison,
+  };
+  const reportData = wantViewer
+    ? withStatus("computing viewer data", () =>
+        prepareHtmlData(results, htmlOpts),
+      )
+    : undefined;
+
+  exportFileFormats(results, args);
+
+  const profileFile = buildSpeedscopeFile(results);
+  const timeFile = buildAllTimeProfiles(results);
+  const coverageData = await annotateCoverage(results, profileFile, timeFile);
+  const timeData = timeFile ? JSON.stringify(timeFile) : undefined;
+
+  if (args.archive != null) {
+    const outputPath = args.archive || undefined;
+    await archiveBenchmark({
+      groups: results,
+      reportData,
+      timeProfileData: timeData,
+      coverageData,
+      outputPath,
+    });
+  }
+  if (args.view || args["view-serve"]) {
+    await openViewer(profileFile, timeData, coverageData, reportData, args);
+  }
+}
+
+/** Print heap reports (if enabled) and export results. */
+export async function finishReports(
+  results: ReportGroup[],
+  args: DefaultCliArgs,
+  exportOptions?: MatrixExportOptions,
+): Promise<void> {
+  if (needsAlloc(args)) {
+    printHeapReports(results, cliHeapReportOptions(args));
+  }
+  await exportReports({ results, args, ...exportOptions });
+}
+
+/** Write Perfetto and time profile files if requested by CLI args. */
+function exportFileFormats(results: ReportGroup[], args: DefaultCliArgs): void {
+  if (args["export-perfetto"])
+    exportPerfettoTrace(results, args["export-perfetto"], args);
+  if (args["export-profile"])
+    exportTimeProfile(results, args["export-profile"]);
+}
+
+/** Build combined Speedscope file from all time profiles in results. */
+function buildAllTimeProfiles(results: ReportGroup[]) {
+  const entries = results.flatMap(group =>
+    groupReports(group)
+      .filter(r => r.measuredResults.timeProfile)
+      .map(r => ({
+        name: r.name,
+        profile: r.measuredResults.timeProfile as TimeProfile,
+      })),
+  );
+  return buildTimeSpeedscopeFile(entries);
+}
+
+/** Annotate speedscope frame names with coverage counts. Returns serialized coverage map. */
+async function annotateCoverage(
+  results: ReportGroup[],
+  profileFile?: FrameContainer,
+  timeFile?: FrameContainer,
+): Promise<string | undefined> {
+  const coverage = mergeCoverage(results);
+  if (!coverage) return undefined;
+
+  const frames = coverage.scripts.map(s => ({ file: s.url }));
+  const sources = await collectSources(frames);
+  const covMap = buildCoverageMap(coverage, sources);
+  if (profileFile) annotateFramesWithCounts(profileFile.shared.frames, covMap);
+  if (timeFile) annotateFramesWithCounts(timeFile.shared.frames, covMap);
+  return JSON.stringify(Object.fromEntries(covMap.map));
+}
+
+/** Start viewer server with profile data and block until Ctrl+C. */
+async function openViewer(
+  profileFile: ReturnType<typeof buildSpeedscopeFile>,
+  timeData: string | undefined,
+  coverageData: string | undefined,
+  reportData: ReportData | undefined,
+  args: DefaultCliArgs,
+): Promise<void> {
+  const viewer = await startViewerServer({
+    profileData: optionalJson(profileFile),
+    timeProfileData: timeData,
+    coverageData,
+    reportData: optionalJson(reportData),
+    editorUri: resolveEditorUri(args.editor),
+    open: !args["view-serve"],
+  });
+  await waitForCtrlC();
+  viewer.close();
+}
+
+/** Export the first raw V8 TimeProfile to a JSON file. */
+function exportTimeProfile(results: ReportGroup[], path: string): void {
+  const profile = results
+    .flatMap(g => groupReports(g))
+    .find(r => r.measuredResults.timeProfile)?.measuredResults.timeProfile;
+  if (!profile) return void console.log("No time profiles to export.");
+  writeFileSync(resolve(path), JSON.stringify(profile));
+  console.log(`Time profile exported to: ${path}`);
+}
+
+/** Merge coverage data from all results into a single CoverageData. */
+function mergeCoverage(results: ReportGroup[]): CoverageData | undefined {
+  const scripts = results.flatMap(group =>
+    groupReports(group).flatMap(r => r.measuredResults.coverage?.scripts ?? []),
+  );
+  return scripts.length > 0 ? { scripts } : undefined;
+}

package/src/cli/CliOptions.ts

@@ -0,0 +1,147 @@
+import type { RunMatrixOptions } from "../matrix/BenchMatrix.ts";
+import type { HeapReportOptions } from "../profiling/node/HeapSampleReport.ts";
+import type { ComparisonOptions } from "../report/BenchmarkReport.ts";
+import { buildTimeSection } from "../report/StandardSections.ts";
+import type { RunnerOptions } from "../runners/BenchRunner.ts";
+import {
+  type DefaultCliArgs,
+  defaultAdaptiveMaxTime,
+  defaultDuration,
+} from "./CliArgs.ts";
+
+/**
+ * Resolve duration/iterations flags into runner limits.
+ *
+ * | Flags set         | maxTime            | maxIterations |
+ * |-------------------|--------------------|---------------|
+ * | neither           | defaultDuration*1000 | undefined   |
+ * | --iterations only | undefined          | N             |
+ * | --duration only   | duration*1000      | undefined     |
+ * | both              | duration*1000      | N             |
+ */
+type Limits = {
+  maxTime: number | undefined;
+  maxIterations: number | undefined;
+};
+
+/** Convert CLI args to matrix runner options. */
+export function cliToMatrixOptions(args: DefaultCliArgs): RunMatrixOptions {
+  const { iterations, worker, batches } = args;
+  const { maxTime } = resolveLimits(args);
+  return {
+    iterations,
+    maxTime,
+    useWorker: worker,
+    batches,
+    warmupBatch: args["warmup-batch"],
+    ...cliCommonOptions(args),
+  };
+}
+
+/** Validate CLI argument combinations. */
+export function validateArgs(args: DefaultCliArgs): void {
+  if (args["gc-stats"] && !args.worker && !args.url) {
+    throw new Error(
+      "--gc-stats requires worker mode (the default). Remove --no-worker flag.",
+    );
+  }
+  // Eagerly validate --stats tokens so users see the error before running benchmarks.
+  if (args.stats) buildTimeSection(args.stats);
+}
+
+/** Convert CLI args to benchmark runner options. */
+export function cliToRunnerOptions(args: DefaultCliArgs): RunnerOptions {
+  const { inspect, iterations, adaptive } = args;
+  const gcForce = args["gc-force"];
+  if (inspect)
+    return { maxIterations: iterations ?? 1, warmupTime: 0, gcForce };
+  if (adaptive) return createAdaptiveOptions(args);
+  return { ...resolveLimits(args), ...cliCommonOptions(args) };
+}
+
+/** Convert CLI args to heap report display options. */
+export function cliHeapReportOptions(args: DefaultCliArgs): HeapReportOptions {
+  return {
+    topN: args["alloc-rows"],
+    stackDepth: args["alloc-stack"],
+    verbose: args["alloc-verbose"],
+    raw: args["alloc-raw"],
+    userOnly: args["alloc-user-only"],
+  };
+}
+
+/** True if any alloc-related flag implies allocation sampling. */
+export function needsAlloc(args: DefaultCliArgs): boolean {
+  return (
+    args.alloc ||
+    args.archive != null ||
+    args["alloc-raw"] ||
+    args["alloc-verbose"] ||
+    args["alloc-user-only"]
+  );
+}
+
+/** True if any profiling flag implies CPU time sampling. */
+export function needsProfile(args: DefaultCliArgs): boolean {
+  return args.profile || !!args["export-profile"];
+}
+
+/** Extract baseline comparison options from CLI args. */
+export function cliComparisonOptions(args: DefaultCliArgs): ComparisonOptions {
+  return {
+    equivMargin: args["equiv-margin"],
+    noBatchTrim: args["no-batch-trim"],
+  };
+}
+
+export function resolveLimits(args: {
+  duration?: number;
+  iterations?: number;
+}): Limits {
+  const { duration, iterations } = args;
+  if (duration == null && iterations == null)
+    return { maxTime: defaultDuration * 1000, maxIterations: undefined };
+  return {
+    maxTime: duration != null ? duration * 1000 : undefined,
+    maxIterations: iterations,
+  };
+}
+
+/** Runner/matrix options shared across all CLI modes. */
+function cliCommonOptions(args: DefaultCliArgs) {
+  const { warmup } = args;
+  const { "gc-force": gcForce, "gc-stats": gcStats } = args;
+  const { "trace-opt": traceOpt, "call-counts": callCounts } = args;
+  const { "pause-warmup": pauseWarmup, "pause-first": pauseFirst } = args;
+  const { "pause-interval": pauseInterval, "pause-duration": pauseDuration } =
+    args;
+  const { "alloc-interval": allocInterval, "alloc-depth": allocDepth } = args;
+  const { "profile-interval": profileInterval } = args;
+  return {
+    gcForce,
+    warmup,
+    traceOpt,
+    gcStats,
+    callCounts,
+    pauseWarmup,
+    pauseFirst,
+    pauseInterval,
+    pauseDuration,
+    alloc: needsAlloc(args),
+    allocInterval,
+    allocDepth,
+    profile: needsProfile(args),
+    profileInterval,
+  };
+}
+
+/** Build runner options for adaptive sampling mode. */
+function createAdaptiveOptions(args: DefaultCliArgs): RunnerOptions {
+  return {
+    minTime: (args["min-time"] ?? 1) * 1000,
+    maxTime: defaultAdaptiveMaxTime * 1000,
+    targetConfidence: args.convergence,
+    adaptive: true,
+    ...cliCommonOptions(args),
+  } as any;
+}