feat(benchmarking): add @sourceloop/benchmarking package

[sf-sahil-jassal]

Description

Adds @sourceloop/benchmarking, a package that lets a team write throughput benchmarks as Mocha tests and fail the build when a change makes an operation slower.

bench.describe() and bench.it() wrap tinybench. Each run records its throughput mean in a committed JSON file. The gate compares the current run against the average of the last ten runs and fails the test when the drop is larger than the threshold.

Two rules differ from what bencher, github-action-benchmark and CodSpeed do, and the README says so plainly:

• A regressed run is not added to the history. The window holds until the regression is fixed or accepted, so three merges that each lose 15 percent cannot walk the baseline down past a 40 percent gate one step at a time.
• A new benchmark records samples quietly until it has enough of them. Comparing against a single prior run is a coin flip, not a signal.

The package is ported from an internal perf-testing package that is already in use. Behaviour matches it, except for the renamed environment variables (PERF_* to BENCH_*), the renamed helpers (pit/pdescribe to bench.it/bench.describe), the new minimum sample count, and stricter parsing of numeric settings.

Documentation lives in packages/benchmarking/README.md. Besides the settings table and the rules the gate applies, it covers how to write a benchmark that means something: good and bad examples side by side, why a Promise.all body reports batches per second and not requests per second, and where the noise in a measurement comes from.

Fixes # (issue)

Type of change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• 64 unit tests over the config getters, the reporter, the metric conversion and the Mocha helper
• An acceptance benchmark that runs the package against itself end to end and asserts the sample it recorded
• npm run build, npm run test and npm run lint in the package, all clean

Reproduce with:

npm run build --workspace @sourceloop/benchmarking
npm run test --workspace @sourceloop/benchmarking
npm run lint --workspace @sourceloop/benchmarking
CI=true npm run test:benchmark --workspace @sourceloop/benchmarking

Note that engines.node is ^22.12.0 || >=24 for this package, not the usual 22 || 24. tinybench 5 is ESM only, and require(esm) is stable from Node 22.12 onwards. The README explains this.

Checklist:

• Performed a self-review of my own code
• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Any dependent changes have been merged and published in downstream modules

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud