pkg-bisect 🔍

Binary search tool to find which npm package version introduced a bug.

The Problem

You know your tests passed with [email protected] but fail with [email protected]. Which exact version broke it? Manually testing each version is tedious.

The Solution

pkg-bisect uses binary search to efficiently find the first failing version:

pkg-bisect some-package 2.0.0 2.5.0 "npm test"

It will:

1. Fetch all versions between 2.0.0 and 2.5.0 from npm registry
2. Binary search through them
3. Install each candidate version
4. Run your test command
5. Report the exact version where things broke

Installation

npm install -g pkg-bisect

Usage

pkg-bisect <package> <good-version> <bad-version> <test-command>

Example:

pkg-bisect react 18.2.0 18.3.1 "npm test"

Example with custom script:

pkg-bisect lodash 4.17.20 4.17.21 "node my-test.js"

How It Works

1. Fetch versions from npm registry API
2. Filter range between known good and bad versions
3. Binary search:
   • Test middle version
   • If pass → bug is in newer half
   • If fail → bug is in older half or this one
   • Repeat until culprit found
4. Report the first version where test fails

Efficiency: For 100 versions, checks only ~7 versions instead of all 100.

Requirements

• Node.js 18+
• npm/yarn in your project
• A reproducible test command that exits with code 0 (pass) or non-zero (fail)

Example Output

🎯 Finding regression in some-package
   Good: 2.0.0
   Bad:  2.5.0
   Test: npm test

📊 12 versions to check

🔍 Bisecting 12 versions...

[0...6...11] Testing [email protected]
📦 Installing [email protected]...
🧪 Running: npm test
✅ Test passed

[7...9...11] Testing [email protected]
📦 Installing [email protected]...
🧪 Running: npm test
❌ Test failed

[7...8...8] Testing [email protected]
📦 Installing [email protected]...
🧪 Running: npm test
✅ Test passed

🐛 FOUND IT!
   [email protected] is the first broken version
   Previous version (2.4.0) was good

API

You can also use it programmatically:

import { pkgBisect } from 'pkg-bisect';

const culprit = await pkgBisect(
  'some-package',
  '2.0.0',
  '2.5.0',
  'npm test'
);

console.log(`Broken in: ${culprit}`);

License

MIT

Author

Polaroid (@prodigieux)

Built with 🤖 during a 3AM #buildinpublic session