zbench-js 0.1.0

package/dist/config.js

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { isTimespan, unitScale } from './units.js';
+/** Config files are looked for at these paths, in order, relative to the working directory. */
+export const configPaths = ['tests/perf/config.json', 'tests/perf.json', 'tests/perf.config.json', 'zbench.json'];
+export const defaultBuild = 'npm install --no-audit --no-fund && npm run build';
+class ConfigError extends Error {
+    constructor(path, message) {
+        super(`${path}: ${message}`);
+        this.name = 'ConfigError';
+    }
+}
+function check(condition, path, message) {
+    if (!condition)
+        throw new ConfigError(path, message);
+}
+function isRecord(value) {
+    return typeof value == 'object' && value !== null && !Array.isArray(value);
+}
+/** Find the config file, starting from `from` and walking up to the filesystem root. */
+export function findConfig(from = process.cwd()) {
+    for (let dir = resolve(from);; dir = dirname(dir)) {
+        for (const candidate of configPaths) {
+            const path = join(dir, candidate);
+            if (existsSync(path))
+                return path;
+        }
+        if (dir == dirname(dir))
+            return null;
+    }
+}
+function parseMeasureValue(value, path) {
+    if (value === undefined || value === false)
+        return undefined;
+    if (value === true)
+        return null;
+    check(isTimespan(value), path, `expected true, false, or a timespan ("ns", "us", "ms", "s")`);
+    return value;
+}
+function parseMetrics(measure, path) {
+    if (measure === undefined)
+        return [];
+    check(isRecord(measure), path, 'expected an object');
+    const metrics = [];
+    for (const [key, raw] of Object.entries(measure)) {
+        const at = `${path}.${key}`;
+        check(isRecord(raw), at, 'expected an object');
+        const spec = raw;
+        const unit = spec.unit ?? key;
+        check(typeof unit == 'string', `${at}.unit`, 'expected a string');
+        check(spec.scale === undefined || typeof spec.scale == 'number', `${at}.scale`, 'expected a number');
+        const scale = spec.scale ?? unitScale(unit);
+        for (const kind of ['throughput', 'cost']) {
+            for (const aggregate of [false, true]) {
+                const field = aggregate ? `aggregate_${kind}` : kind;
+                const span = parseMeasureValue(spec[field], `${at}.${field}`);
+                if (span === undefined)
+                    continue;
+                metrics.push({ key, kind, aggregate, span, scale, unit, higherIsBetter: kind == 'throughput' });
+            }
+        }
+        check(metrics.some(m => m.key == key), at, 'declares no measurements; set at least one of throughput, cost, aggregate_throughput, aggregate_cost');
+    }
+    return metrics;
+}
+function defaultName(value) {
+    return Object.entries(value)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+}
+function parseFlags(flags, pool, path) {
+    if (flags === undefined)
+        return undefined;
+    if (Array.isArray(flags)) {
+        const selected = {};
+        for (const name of flags) {
+            check(typeof name == 'string', path, 'expected an array of flag names');
+            check(name in pool, path, `no flag named ${JSON.stringify(name)} is declared by the suite`);
+            selected[name] = pool[name];
+        }
+        return selected;
+    }
+    check(isRecord(flags), path, 'expected an array of flag names or an object of flag values');
+    const inline = {};
+    for (const [name, values] of Object.entries(flags)) {
+        check(Array.isArray(values) && values.length > 0, `${path}.${name}`, 'expected a non-empty array of values');
+        inline[name] = values;
+    }
+    return inline;
+}
+/** Parse and validate an already-loaded suite. `file` is used to resolve test paths. */
+export function parseSuite(data, file) {
+    const dir = dirname(resolve(file));
+    const spec = Array.isArray(data) ? { tests: data } : data;
+    check(isRecord(spec), 'config', 'expected an array of tests or an object with a `tests` array');
+    check(Array.isArray(spec.tests), 'config.tests', 'expected an array');
+    const pool = {};
+    if (spec.flags !== undefined) {
+        check(isRecord(spec.flags), 'config.flags', 'expected an object of flag values');
+        for (const [name, values] of Object.entries(spec.flags)) {
+            check(Array.isArray(values) && values.length > 0, `config.flags.${name}`, 'expected a non-empty array of values');
+            pool[name] = values;
+        }
+    }
+    const iterations = spec.iterations ?? 5;
+    const warmup = spec.warmup ?? 1;
+    const tests = spec.tests.map((test, i) => {
+        const at = `config.tests[${i}]`;
+        check(isRecord(test), at, 'expected an object');
+        check(typeof test.path == 'string', `${at}.path`, 'expected a string');
+        check(Array.isArray(test.configurations), `${at}.configurations`, 'expected an array');
+        const configurations = test.configurations.map((config, j) => {
+            const cat = `${at}.configurations[${j}]`;
+            check(isRecord(config), cat, 'expected an object');
+            check(isRecord(config.value), `${cat}.value`, 'expected an object');
+            for (const [k, v] of Object.entries(config.value))
+                check(typeof v == 'number', `${cat}.value.${k}`, 'expected a number');
+            return {
+                name: config.name ?? defaultName(config.value),
+                cpu: config.cpu ?? 0,
+                mem: config.mem ?? 0,
+                value: config.value,
+            };
+        });
+        check(configurations.length > 0, `${at}.configurations`, 'expected at least one configuration');
+        return {
+            // The name, so one file can back several tests that differ only in their matrix
+            id: test.name ?? test.path,
+            name: test.name ?? test.path,
+            file: isAbsolute(test.path) ? test.path : resolve(dir, test.path),
+            path: test.path,
+            metrics: parseMetrics(test.measure, `${at}.measure`),
+            configurations,
+            flags: parseFlags(test.flags, pool, `${at}.flags`) ?? {},
+            iterations: test.iterations ?? iterations,
+            warmup: test.warmup ?? warmup,
+        };
+    });
+    // Results are keyed by id, so a duplicate would silently merge two tests' numbers
+    const seen = new Set();
+    for (const test of tests) {
+        check(!seen.has(test.id), `config.tests`, `more than one test is named ${JSON.stringify(test.id)}`);
+        seen.add(test.id);
+    }
+    return {
+        file: resolve(file),
+        root: spec.root ? resolve(dir, spec.root) : dir,
+        build: spec.build ?? defaultBuild,
+        tests,
+    };
+}
+export function loadSuite(file) {
+    let data;
+    try {
+        data = JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch (e) {
+        throw new ConfigError(file, e.message);
+    }
+    return parseSuite(data, file);
+}
+/** Every combination of the given flags, in declaration order. Always at least one (possibly empty) combination. */
+export function flagCombinations(flags) {
+    let combinations = [{}];
+    for (const [name, values] of Object.entries(flags))
+        combinations = combinations.flatMap(base => values.map(value => ({ ...base, [name]: value })));
+    return combinations;
+}
+/** A stable, human-readable label for a flag combination. Empty when there are no flags. */
+export function flagLabel(flags) {
+    return Object.entries(flags)
+        .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+        .join(', ');
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './capabilities.js';
+export * from './compare.js';
+export * from './config.js';
+export * from './measure.js';
+export * from './refs.js';
+export * from './report.js';
+export * from './runner.js';
+export * from './stats.js';
+export * from './types.js';
+export * from './units.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+export * from './capabilities.js';
+export * from './compare.js';
+export * from './config.js';
+export * from './measure.js';
+export * from './refs.js';
+export * from './report.js';
+export * from './runner.js';
+export * from './stats.js';
+export * from './types.js';
+export * from './units.js';

package/dist/isolate.d.ts

@@ -0,0 +1,27 @@
+import { type CaseResult } from './runner.js';
+/** Everything a child process needs to run exactly one matrix. */
+export interface WorkerSpec {
+    /** Path to the config file, as seen from the child's working directory */
+    config: string;
+    /** The test's id */
+    test: string;
+    /** The single flag combination to run */
+    flags: Record<string, unknown>;
+    iterations?: number;
+    warmup?: number;
+    cpu?: number;
+    mem?: number;
+    all?: boolean;
+    /** Where the child writes its results */
+    out: string;
+}
+/** Run one matrix and write the results where the parent expects them. */
+export declare function runWorker(specPath: string): Promise<void>;
+/**
+ * Run one matrix in a fresh process.
+ * Every matrix gets its own heap and its own module graph, which is what keeps one configuration
+ * from warming up (or poisoning) the next, and what lets a git reference's own build be loaded.
+ */
+export declare function runIsolated(spec: Omit<WorkerSpec, 'out'>, cwd: string, cli: string, 
+/** Seconds before the worker is killed. 0 waits forever. */
+timeout?: number): Promise<CaseResult[]>;

package/dist/isolate.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadSuite } from './config.js';
+import { runTest } from './runner.js';
+/** Run one matrix and write the results where the parent expects them. */
+export async function runWorker(specPath) {
+    const spec = JSON.parse(await readFile(specPath, 'utf-8'));
+    const suite = loadSuite(spec.config);
+    const test = suite.tests.find(t => t.id == spec.test);
+    if (!test)
+        throw new Error(`no test with id ${JSON.stringify(spec.test)} in ${spec.config}`);
+    const results = await runTest(test, {
+        iterations: spec.iterations,
+        warmup: spec.warmup,
+        cpu: spec.cpu,
+        mem: spec.mem,
+        all: spec.all,
+        flags: Object.fromEntries(Object.entries(spec.flags).map(([k, v]) => [k, [v]])),
+    });
+    await writeFile(spec.out, JSON.stringify(results));
+}
+/**
+ * Run one matrix in a fresh process.
+ * Every matrix gets its own heap and its own module graph, which is what keeps one configuration
+ * from warming up (or poisoning) the next, and what lets a git reference's own build be loaded.
+ */
+export async function runIsolated(spec, cwd, cli, 
+/** Seconds before the worker is killed. 0 waits forever. */
+timeout = 0) {
+    const dir = await mkdtemp(join(tmpdir(), 'zbench-'));
+    const specPath = join(dir, 'spec.json');
+    const out = join(dir, 'results.json');
+    try {
+        await writeFile(specPath, JSON.stringify({ ...spec, out }));
+        // Output is buffered rather than inherited: with several workers running it would interleave,
+        // and it is only worth reading when one of them fails
+        let output = '';
+        let timedOut = false;
+        const code = await new Promise((resolve, reject) => {
+            const extra = [];
+            if (!process.features.typescript)
+                extra.push('--disable-warning=ExperimentalWarning');
+            const child = spawn(process.execPath, [...process.execArgv, ...extra, cli, '--worker', specPath], {
+                cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            const collect = (chunk) => (output += chunk.toString());
+            child.stdout.on('data', collect);
+            child.stderr.on('data', collect);
+            const timer = timeout
+                ? setTimeout(() => {
+                    timedOut = true;
+                    child.kill('SIGKILL');
+                }, timeout * 1000)
+                : undefined;
+            child.on('error', reject);
+            child.on('close', c => {
+                clearTimeout(timer);
+                resolve(c ?? 1);
+            });
+        });
+        if (timedOut)
+            throw new Error(`timed out after ${timeout}s`);
+        if (code != 0)
+            throw new Error(`worker exited with code ${code}\n${output.trim()}`);
+        return JSON.parse(await readFile(out, 'utf-8'));
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}

package/dist/measure.d.ts

@@ -0,0 +1,59 @@
+import { type Metric, type Test } from './config.js';
+import type { CaseResult } from './runner.js';
+import { type Stats } from './stats.js';
+import { type Timespan } from './units.js';
+/** One test's results for one flag combination: the unit a table is printed for. */
+export interface Matrix {
+    test: Test;
+    flags: Record<string, unknown>;
+    /** Empty when the test has no flags */
+    label: string;
+    cases: CaseResult[];
+}
+/** A metric with its timespan settled, so every row in a matrix shares one column heading. */
+export interface ResolvedMetric extends Metric {
+    span: Timespan;
+    /** Column heading, e.g. `MB/s` or `ms/entry` */
+    label: string;
+}
+/** Split a test's results into one matrix per flag combination, in the order they were run. */
+export declare function matrices(test: Test, cases: CaseResult[]): Matrix[];
+/** Cases that actually produced samples. */
+export declare function ran(matrix: Matrix): CaseResult[];
+/**
+ * Settle each metric's timespan against the matrix as a whole.
+ * Inferring per row would give each row a different heading, so the totals decide it once.
+ */
+export declare function resolveMetrics(matrix: Matrix): ResolvedMetric[];
+/** A metric's value for one configuration, or `null` when there is nothing to divide. */
+export declare function caseValue(metric: ResolvedMetric, result: CaseResult): number | null;
+/** A metric's value across the whole matrix. */
+export declare function aggregateValue(metric: ResolvedMetric, matrix: Matrix): number | null;
+/** Timing statistics for a case, in milliseconds. */
+export declare function timing(result: CaseResult): Stats;
+/** Iterations per second, the metric every test has whether or not it declares one. */
+export declare function opsPerSecond(result: CaseResult): number | null;
+/**
+ * A reported quantity, resolved against one matrix.
+ * Tables and comparisons both work in terms of these, so a column is defined once and reported the same way everywhere.
+ */
+export interface Column {
+    label: string;
+    higherIsBetter: boolean;
+    format(value: number): string;
+    /** `null` for a row the column does not apply to */
+    value(result: CaseResult): number | null;
+    /**
+     * The column's value across a set of cases, when it has one.
+     * The cases are a parameter rather than the matrix the column came from, so a comparison can
+     * evaluate one state's column against another state's results without re-inferring the timespan.
+     */
+    total?(cases: CaseResult[]): number | null;
+    /** Aggregate columns are reported once per matrix instead of once per row */
+    aggregate: boolean;
+}
+/**
+ * The columns a matrix reports: the built-in timings, then whatever the test declared.
+ * Aggregate metrics come last since they hold a single number rather than a column of them.
+ */
+export declare function columns(matrix: Matrix): Column[];

package/dist/measure.js

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { flagLabel } from './config.js';
+import { stats } from './stats.js';
+import { duration, inferCostSpan, inferThroughputSpan, sig, timespans } from './units.js';
+/** Split a test's results into one matrix per flag combination, in the order they were run. */
+export function matrices(test, cases) {
+    const byFlags = new Map();
+    for (const result of cases) {
+        if (result.test != test.id)
+            continue;
+        const key = JSON.stringify(result.flags);
+        let matrix = byFlags.get(key);
+        if (!matrix)
+            byFlags.set(key, (matrix = { test, flags: result.flags, label: flagLabel(result.flags), cases: [] }));
+        matrix.cases.push(result);
+    }
+    return [...byFlags.values()];
+}
+/** Cases that actually produced samples. */
+export function ran(matrix) {
+    return matrix.cases.filter(c => c.samples.length > 0);
+}
+/** The scaled amount and elapsed milliseconds a metric is computed from, for one case. */
+function terms(metric, result) {
+    return [(result.amounts[metric.key] ?? 0) * metric.scale, result.samples.reduce((sum, v) => sum + v, 0)];
+}
+/** The same terms, summed across the whole matrix. */
+function totals(metric, matrix) {
+    let amount = 0, ms = 0;
+    for (const result of ran(matrix)) {
+        const [a, t] = terms(metric, result);
+        amount += a;
+        ms += t;
+    }
+    return [amount, ms];
+}
+function compute(kind, span, amount, ms) {
+    if (!ms || !amount)
+        return null;
+    return kind == 'throughput' ? (amount * timespans[span]) / ms : ms / timespans[span] / amount;
+}
+/**
+ * Settle each metric's timespan against the matrix as a whole.
+ * Inferring per row would give each row a different heading, so the totals decide it once.
+ */
+export function resolveMetrics(matrix) {
+    return matrix.test.metrics.map(metric => {
+        const [amount, ms] = totals(metric, matrix);
+        const span = metric.span
+            ?? (!amount || !ms
+                ? 'ms'
+                : metric.kind == 'throughput'
+                    ? inferThroughputSpan(amount, ms)
+                    : inferCostSpan(amount, ms));
+        return {
+            ...metric,
+            span,
+            label: metric.kind == 'throughput' ? `${metric.unit}/${span}` : `${span}/${metric.unit}`,
+        };
+    });
+}
+/** A metric's value for one configuration, or `null` when there is nothing to divide. */
+export function caseValue(metric, result) {
+    return compute(metric.kind, metric.span, ...terms(metric, result));
+}
+/** A metric's value across the whole matrix. */
+export function aggregateValue(metric, matrix) {
+    return compute(metric.kind, metric.span, ...totals(metric, matrix));
+}
+/** Timing statistics for a case, in milliseconds. */
+export function timing(result) {
+    return stats(result.samples);
+}
+/** Iterations per second, the metric every test has whether or not it declares one. */
+export function opsPerSecond(result) {
+    const { mean } = timing(result);
+    return mean ? 1000 / mean : null;
+}
+/**
+ * The columns a matrix reports: the built-in timings, then whatever the test declared.
+ * Aggregate metrics come last since they hold a single number rather than a column of them.
+ */
+export function columns(matrix) {
+    const list = [
+        {
+            label: 'avg',
+            higherIsBetter: false,
+            format: duration,
+            value: result => timing(result).mean || null,
+            aggregate: false,
+        },
+        {
+            label: 'ops/s',
+            higherIsBetter: true,
+            format: sig,
+            value: opsPerSecond,
+            aggregate: false,
+        },
+    ];
+    for (const metric of resolveMetrics(matrix)) {
+        list.push({
+            label: metric.label,
+            higherIsBetter: metric.higherIsBetter,
+            format: sig,
+            value: result => caseValue(metric, result),
+            total: cases => aggregateValue(metric, { ...matrix, cases }),
+            aggregate: metric.aggregate,
+        });
+    }
+    return list;
+}

package/dist/pool.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Map over `items` with at most `limit` running at once, keeping the results in input order.
+ * A `limit` of 1 is a plain serial loop.
+ */
+export declare function mapPool<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/pool.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/**
+ * Map over `items` with at most `limit` running at once, keeping the results in input order.
+ * A `limit` of 1 is a plain serial loop.
+ */
+export async function mapPool(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        for (let i = next++; i < items.length; i = next++)
+            results[i] = await fn(items[i], i);
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+    return results;
+}

package/dist/refs.d.ts

@@ -0,0 +1,36 @@
+/** Names that mean "whatever is in the working tree right now", which is never built or checked out. */
+export declare const workingRefs: string[];
+/** A state to benchmark: either the working tree or a git worktree checked out at some reference. */
+export interface Ref {
+    /** As given on the command line */
+    name: string;
+    /** Where the tests run */
+    dir: string;
+    /** `null` for the working tree */
+    sha: string | null;
+}
+export interface RefOptions {
+    /** Where worktrees are kept between runs */
+    cache: string;
+    /** Shell command that makes a worktree runnable */
+    build: string;
+    /** Directory holding the tests, copied into each worktree so every reference runs the same tests */
+    root: string;
+    /** Build even when the worktree is already at the right commit */
+    rebuild?: boolean;
+    onStep?(message: string): void;
+}
+/** The root of the repository containing `from`. */
+export declare function repoRoot(from?: string): Promise<string>;
+/**
+ * Check out every reference and make it runnable.
+ *
+ * Checkout is serial because `git worktree add` takes a repository-wide lock, but building is not,
+ * and building is where nearly all of the time goes. Nothing here is timed, so the concurrency
+ * costs the measurements nothing.
+ */
+export declare function prepareRefs(names: string[], options: RefOptions): Promise<Ref[]>;
+/** Check out one reference into a reusable worktree, build it, and stage the tests inside it. */
+export declare function prepareRef(name: string, options: RefOptions): Promise<Ref>;
+/** Remove every cached worktree. */
+export declare function cleanRefs(cache: string): Promise<void>;

package/dist/refs.js

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { execFile as execFileCallback } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, join, relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const execFile = promisify(execFileCallback);
+/** Names that mean "whatever is in the working tree right now", which is never built or checked out. */
+export const workingRefs = ['.', 'working', 'wip'];
+async function git(repo, ...args) {
+    const { stdout } = await execFile('git', ['-C', repo, ...args], { maxBuffer: 1 << 26 });
+    return stdout.trim();
+}
+/** The root of the repository containing `from`. */
+export async function repoRoot(from = process.cwd()) {
+    return await git(from, 'rev-parse', '--show-toplevel');
+}
+function slug(ref) {
+    return ref.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'ref';
+}
+/**
+ * Copy the tests into a worktree.
+ *
+ * The tests have to come from the working tree rather than the checkout, since an old reference
+ * predates them; they have to be copied rather than symlinked, since Node resolves bare imports
+ * from a file's real path and a symlink would reach the working tree's `node_modules` instead of
+ * the worktree's.
+ */
+async function copyTests(repo, dir, root) {
+    const target = join(dir, relative(repo, root));
+    if (resolve(target) == resolve(root))
+        return;
+    await cp(root, target, {
+        recursive: true,
+        filter: source => {
+            const name = basename(source);
+            return name != 'node_modules' && !name.startsWith('.');
+        },
+    });
+}
+/**
+ * Check out every reference and make it runnable.
+ *
+ * Checkout is serial because `git worktree add` takes a repository-wide lock, but building is not,
+ * and building is where nearly all of the time goes. Nothing here is timed, so the concurrency
+ * costs the measurements nothing.
+ */
+export async function prepareRefs(names, options) {
+    const repo = await repoRoot();
+    const staged = [];
+    for (const name of names) {
+        if (workingRefs.includes(name)) {
+            staged.push({ name, dir: repo, sha: null, build: false });
+            continue;
+        }
+        const sha = await git(repo, 'rev-parse', name + '^{commit}');
+        const dir = join(options.cache, slug(name));
+        const stamp = join(dir, '.zbench-ref');
+        const current = existsSync(stamp) ? (await readFile(stamp, 'utf-8')).trim() : null;
+        if (current == sha && !options.rebuild) {
+            staged.push({ name, dir, sha, build: false });
+            continue;
+        }
+        if (existsSync(dir)) {
+            await git(repo, 'worktree', 'remove', '--force', dir).catch(() => { });
+            await rm(dir, { recursive: true, force: true });
+        }
+        await mkdir(options.cache, { recursive: true });
+        options.onStep?.(`checking out ${name} (${sha.slice(0, 8)})`);
+        await git(repo, 'worktree', 'add', '--detach', dir, sha);
+        staged.push({ name, dir, sha, build: true });
+    }
+    const building = staged.filter(ref => ref.build).map(ref => ref.name);
+    if (building.length)
+        options.onStep?.(`building ${building.join(', ')}`);
+    await Promise.all(staged.map(async ({ dir, sha, build }) => {
+        if (sha === null)
+            return;
+        await copyTests(repo, dir, options.root);
+        if (!build)
+            return;
+        await execFile('sh', ['-c', options.build], { cwd: dir, maxBuffer: 1 << 26 });
+        await writeFile(join(dir, '.zbench-ref'), sha + '\n');
+    }));
+    return staged.map(({ name, dir, sha }) => ({ name, dir, sha }));
+}
+/** Check out one reference into a reusable worktree, build it, and stage the tests inside it. */
+export async function prepareRef(name, options) {
+    const [ref] = await prepareRefs([name], options);
+    return ref;
+}
+/** Remove every cached worktree. */
+export async function cleanRefs(cache) {
+    const repo = await repoRoot();
+    if (!existsSync(cache))
+        return;
+    const listed = await git(repo, 'worktree', 'list', '--porcelain');
+    for (const line of listed.split('\n')) {
+        if (!line.startsWith('worktree '))
+            continue;
+        const dir = line.slice('worktree '.length);
+        if (resolve(dir).startsWith(resolve(cache)))
+            await git(repo, 'worktree', 'remove', '--force', dir);
+    }
+    await rm(cache, { recursive: true, force: true });
+    await git(repo, 'worktree', 'prune');
+}

package/dist/report.d.ts

@@ -0,0 +1,14 @@
+import type { Comparison, RefResults } from './compare.js';
+import type { Suite } from './config.js';
+import { type Matrix } from './measure.js';
+import type { CaseResult } from './runner.js';
+/** Print one matrix as a table, followed by its aggregate measurements. */
+export declare function reportMatrix(matrix: Matrix): void;
+/** Print every test's tables for a single state. */
+export declare function reportRun(suite: Suite, cases: CaseResult[]): void;
+/** Print the delta tables that follow each state's own tables. */
+export declare function reportComparison(comparisons: Comparison[], refs: RefResults[]): void;
+/** A one-line note about what the numbers were produced under. */
+export declare function reportEnvironment(cpu: number, mem: number, iterations: number, warmup: number, jobs: number): void;
+/** List the tests and configurations that would run, without running them. */
+export declare function reportList(suite: Suite): void;