overtake 2.0.0 → 2.0.2

package/bin/overtake.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env -S node --experimental-vm-modules --no-warnings --expose-gc
-import '../src/cli.ts';
+import '../build/cli.js';

package/build/cli.js

@@ -0,0 +1,157 @@
+import { createRequire, register } from 'node:module';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { stat, readFile, writeFile, glob } from 'node:fs/promises';
+import { Benchmark, printTableReports, printJSONReports, printSimpleReports, printMarkdownReports, printHistogramReports, printComparisonReports, reportsToBaseline, DEFAULT_REPORT_TYPES, DEFAULT_WORKERS, } from './index.js';
+import { REPORT_TYPES } from './types.js';
+import { resolveHookUrl } from './utils.js';
+register(resolveHookUrl);
+const require = createRequire(import.meta.url);
+const { name, version, description } = require('../package.json');
+const BENCHMARK_URL = Symbol.for('overtake.benchmarkUrl');
+const FORMATS = ['simple', 'json', 'pjson', 'table', 'markdown', 'histogram'];
+const { values: opts, positionals: patterns } = parseArgs({
+    args: process.argv.slice(2),
+    allowPositionals: true,
+    options: {
+        'report-types': { type: 'string', short: 'r', multiple: true },
+        workers: { type: 'string', short: 'w' },
+        format: { type: 'string', short: 'f' },
+        'abs-threshold': { type: 'string' },
+        'rel-threshold': { type: 'string' },
+        'warmup-cycles': { type: 'string' },
+        'max-cycles': { type: 'string' },
+        'min-cycles': { type: 'string' },
+        'no-gc-observer': { type: 'boolean' },
+        progress: { type: 'boolean' },
+        'save-baseline': { type: 'string' },
+        'compare-baseline': { type: 'string' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+    },
+});
+if (opts.version) {
+    console.log(version);
+    process.exit(0);
+}
+if (opts.help || patterns.length === 0) {
+    console.log(`${name} v${version} - ${description}
+
+Usage: overtake [options] <paths...>
+
+Options:
+  -r, --report-types <type>       statistic type, repeat for multiple (-r ops -r p99)
+  -w, --workers <n>               number of concurrent workers (default: ${DEFAULT_WORKERS})
+  -f, --format <format>           output format: ${FORMATS.join(', ')} (default: simple)
+  --abs-threshold <ns>            absolute error threshold in nanoseconds
+  --rel-threshold <frac>          relative error threshold (0-1)
+  --warmup-cycles <n>             warmup cycles before measuring
+  --max-cycles <n>                maximum measurement cycles per feed
+  --min-cycles <n>                minimum measurement cycles per feed
+  --no-gc-observer                disable GC overlap detection
+  --progress                      show progress bar
+  --save-baseline <file>          save results to baseline file
+  --compare-baseline <file>       compare results against baseline file
+  -v, --version                   show version
+  -h, --help                      show this help`);
+    process.exit(0);
+}
+const reportTypes = opts['report-types']?.length
+    ? opts['report-types'].filter((t) => REPORT_TYPES.includes(t))
+    : DEFAULT_REPORT_TYPES;
+const format = opts.format && FORMATS.includes(opts.format) ? opts.format : 'simple';
+const executeOptions = {
+    reportTypes,
+    workers: opts.workers ? parseInt(opts.workers) : DEFAULT_WORKERS,
+    absThreshold: opts['abs-threshold'] ? parseFloat(opts['abs-threshold']) : undefined,
+    relThreshold: opts['rel-threshold'] ? parseFloat(opts['rel-threshold']) : undefined,
+    warmupCycles: opts['warmup-cycles'] ? parseInt(opts['warmup-cycles']) : undefined,
+    maxCycles: opts['max-cycles'] ? parseInt(opts['max-cycles']) : undefined,
+    minCycles: opts['min-cycles'] ? parseInt(opts['min-cycles']) : undefined,
+    gcObserver: !opts['no-gc-observer'],
+    progress: opts.progress ?? false,
+    format,
+};
+let baseline = null;
+if (opts['compare-baseline']) {
+    try {
+        const content = await readFile(opts['compare-baseline'], 'utf8');
+        baseline = JSON.parse(content);
+    }
+    catch {
+        console.error(`Warning: Could not load baseline file: ${opts['compare-baseline']}`);
+    }
+}
+const files = new Set((await Promise.all(patterns.map((pattern) => Array.fromAsync(glob(pattern, { cwd: process.cwd() })).catch(() => [])))).flat());
+const allBaselineResults = {};
+for (const file of files) {
+    const stats = await stat(file).catch(() => false);
+    if (stats && stats.isFile()) {
+        const identifier = pathToFileURL(file).href;
+        let instance;
+        globalThis.benchmark = (...args) => {
+            if (instance) {
+                throw new Error('Only one benchmark per file is supported');
+            }
+            instance = Benchmark.create(...args);
+            return instance;
+        };
+        try {
+            await import(identifier);
+        }
+        catch (e) {
+            console.error(`Error loading ${file}: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        if (instance) {
+            let reports;
+            try {
+                reports = await instance.execute({
+                    ...executeOptions,
+                    [BENCHMARK_URL]: identifier,
+                });
+            }
+            catch (e) {
+                console.error(`Error executing ${file}: ${e instanceof Error ? e.message : String(e)}`);
+                continue;
+            }
+            if (opts['save-baseline']) {
+                const bd = reportsToBaseline(reports);
+                Object.assign(allBaselineResults, bd.results);
+            }
+            if (baseline) {
+                printComparisonReports(reports, baseline);
+            }
+            else {
+                switch (format) {
+                    case 'json':
+                        printJSONReports(reports);
+                        break;
+                    case 'pjson':
+                        printJSONReports(reports, 2);
+                        break;
+                    case 'table':
+                        printTableReports(reports);
+                        break;
+                    case 'markdown':
+                        printMarkdownReports(reports);
+                        break;
+                    case 'histogram':
+                        printHistogramReports(reports);
+                        break;
+                    default:
+                        printSimpleReports(reports);
+                }
+            }
+        }
+    }
+}
+if (opts['save-baseline'] && Object.keys(allBaselineResults).length > 0) {
+    const baselineData = {
+        version: 1,
+        timestamp: new Date().toISOString(),
+        results: allBaselineResults,
+    };
+    await writeFile(opts['save-baseline'], JSON.stringify(baselineData, null, 2));
+    console.log(`Baseline saved to: ${opts['save-baseline']}`);
+}

package/build/executor.d.ts

@@ -1,5 +1,5 @@
-import { Report } from './reporter.ts';
-import { type ExecutorRunOptions, type ReportOptions, type BenchmarkOptions, type ReportTypeList, type ProgressCallback } from './types.ts';
+import { Report } from './reporter.js';
+import { type ExecutorRunOptions, type ReportOptions, type BenchmarkOptions, type ReportTypeList, type ProgressCallback } from './types.js';
 export type ExecutorReport<R extends ReportTypeList> = Record<R[number], Report> & {
     count: number;
     heapUsedKB: number;

package/build/executor.js

@@ -0,0 +1,139 @@
+import { Worker } from 'node:worker_threads';
+import { once } from 'node:events';
+import { pathToFileURL } from 'node:url';
+import { createReport, computeStats, Report } from './reporter.js';
+import { cmp, assertNoClosure, normalizeFunction } from './utils.js';
+import { Control, CONTROL_SLOTS, COMPLETE_VALUE, } from './types.js';
+const BENCHMARK_URL = Symbol.for('overtake.benchmarkUrl');
+export const createExecutor = (options) => {
+    const { workers, warmupCycles, maxCycles, minCycles, absThreshold, relThreshold, gcObserver = true, reportTypes, onProgress, progressInterval = 100 } = options;
+    const benchmarkUrl = options[BENCHMARK_URL];
+    const resolvedBenchmarkUrl = typeof benchmarkUrl === 'string' ? benchmarkUrl : pathToFileURL(process.cwd()).href;
+    const pending = [];
+    const activeWorkers = new Set();
+    let running = 0;
+    const schedule = async (task) => {
+        running++;
+        try {
+            return await runTask(task);
+        }
+        finally {
+            running--;
+            if (pending.length > 0) {
+                const next = pending.shift();
+                schedule(next.task).then(next.resolve, next.reject);
+            }
+        }
+    };
+    const pushAsync = (task) => {
+        if (running < workers) {
+            return schedule(task);
+        }
+        return new Promise((resolve, reject) => {
+            pending.push({ task, resolve: resolve, reject });
+        });
+    };
+    const runTask = async ({ id, setup, teardown, pre, run, post, data }) => {
+        const setupCode = setup ? normalizeFunction(setup.toString()) : undefined;
+        const teardownCode = teardown ? normalizeFunction(teardown.toString()) : undefined;
+        const preCode = pre ? normalizeFunction(pre.toString()) : undefined;
+        const runCode = normalizeFunction(run.toString());
+        const postCode = post ? normalizeFunction(post.toString()) : undefined;
+        if (setupCode)
+            assertNoClosure(setupCode, 'setup');
+        if (teardownCode)
+            assertNoClosure(teardownCode, 'teardown');
+        if (preCode)
+            assertNoClosure(preCode, 'pre');
+        assertNoClosure(runCode, 'run');
+        if (postCode)
+            assertNoClosure(postCode, 'post');
+        const controlSAB = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * CONTROL_SLOTS);
+        const durationsSAB = new SharedArrayBuffer(BigUint64Array.BYTES_PER_ELEMENT * maxCycles);
+        const workerFile = new URL('./worker.js', import.meta.url);
+        const workerData = {
+            benchmarkUrl: resolvedBenchmarkUrl,
+            setupCode,
+            teardownCode,
+            preCode,
+            runCode,
+            postCode,
+            data,
+            warmupCycles,
+            minCycles,
+            absThreshold,
+            relThreshold,
+            gcObserver,
+            controlSAB,
+            durationsSAB,
+        };
+        const worker = new Worker(workerFile, {
+            workerData,
+        });
+        activeWorkers.add(worker);
+        const control = new Int32Array(controlSAB);
+        let progressIntervalId;
+        if (onProgress && id) {
+            progressIntervalId = setInterval(() => {
+                const progress = control[Control.PROGRESS] / COMPLETE_VALUE;
+                onProgress({ id, progress });
+            }, progressInterval);
+        }
+        const WORKER_TIMEOUT_MS = 300_000;
+        const exitPromise = once(worker, 'exit');
+        const timeoutId = setTimeout(() => worker.terminate(), WORKER_TIMEOUT_MS);
+        let workerError;
+        try {
+            const [exitCode] = await exitPromise;
+            clearTimeout(timeoutId);
+            if (progressIntervalId)
+                clearInterval(progressIntervalId);
+            if (exitCode !== 0) {
+                workerError = `worker exited with code ${exitCode}`;
+            }
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (progressIntervalId)
+                clearInterval(progressIntervalId);
+            workerError = err instanceof Error ? err.message : String(err);
+        }
+        activeWorkers.delete(worker);
+        const count = control[Control.INDEX];
+        const heapUsedKB = control[Control.HEAP_USED];
+        const durations = new BigUint64Array(durationsSAB).slice(0, count).sort(cmp);
+        const DCE_THRESHOLD_OPS = 5_000_000_000;
+        let dceWarning = false;
+        if (count > 0) {
+            let sum = 0n;
+            for (const d of durations)
+                sum += d;
+            const avgNs = Number(sum / BigInt(count)) / 1000;
+            const opsPerSec = avgNs > 0 ? 1_000_000_000 / avgNs : Infinity;
+            if (opsPerSec > DCE_THRESHOLD_OPS) {
+                dceWarning = true;
+            }
+        }
+        const stats = count > 0 ? computeStats(durations) : undefined;
+        const report = reportTypes
+            .map((type) => [type, createReport(durations, type, stats)])
+            .concat([
+            ['count', count],
+            ['heapUsedKB', heapUsedKB],
+            ['dceWarning', dceWarning],
+            ['error', workerError],
+        ]);
+        return Object.fromEntries(report);
+    };
+    return {
+        pushAsync,
+        kill() {
+            for (const w of activeWorkers)
+                w.terminate();
+            activeWorkers.clear();
+            for (const p of pending)
+                p.reject(new Error('Executor killed'));
+            pending.length = 0;
+        },
+    };
+};

package/build/gc-watcher.js

@@ -0,0 +1,16 @@
+export class GCWatcher {
+    #registry = new FinalizationRegistry(() => { });
+    start() {
+        const target = {};
+        const ref = new WeakRef(target);
+        this.#registry.register(target, null, ref);
+        return { ref };
+    }
+    seen(marker) {
+        const collected = marker.ref.deref() === undefined;
+        if (!collected) {
+            this.#registry.unregister(marker.ref);
+        }
+        return collected;
+    }
+}

package/build/index.d.ts

@@ -1,5 +1,5 @@
-import { type ExecutorOptions, type ExecutorReport } from './executor.ts';
-import { type MaybePromise, type StepFn, type SetupFn, type TeardownFn, type FeedFn, type ReportType, type ReportTypeList } from './types.ts';
+import { type ExecutorOptions, type ExecutorReport } from './executor.js';
+import { type MaybePromise, type StepFn, type SetupFn, type TeardownFn, type FeedFn, type ReportType, type ReportTypeList } from './types.js';
 declare global {
     const benchmark: typeof Benchmark.create;
 }