Registry / devops / why-broke

why-broke

JSON →
library1.4.2jsnpmunverified

why-broke is a command-line utility designed for causal debugging of build failures in JavaScript/TypeScript projects. It tackles the common problem of "it worked yesterday, but not today" by detecting subtle environmental and dependency changes that conventional version control systems like Git might miss. The tool operates by taking a "good state" snapshot of the system, which includes critical factors like Node.js version, operating system, lockfile hashes, package manifest versions, key configuration files (e.g., `tsconfig`, `webpack`), and essential environment variable keys. When a build subsequently fails, why-broke compares the current "bad state" against the last known good state to pinpoint the root cause, such as silent dependency updates, missing environment variables, or unexpected Node.js version discrepancies. As of version 1.4.2, it incorporates a causal inference engine with specialized detectors for runtime, dependencies, configuration, environment, and Git status. The package is actively maintained and appears to follow a typical semantic versioning release cadence based on its version history. Its primary differentiator is its focus on diagnosing *why* a build failed rather than merely *where* it failed, offering actionable fixes.

npm install why-broke
INSTALL
IMPORT
SIG · WHY-BROKE
W
why-broke
devopsjavascriptv1.4.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

init
import { init } from 'why-broke';
const init = require('why-broke').init;
why-broke is primarily a CLI tool; direct programmatic imports like this are not officially documented but might be possible if a programmatic API exists. This assumes an 'init' function mirroring the CLI command.
record
import { record } from 'why-broke';
import record from 'why-broke';
This speculates a named export for the 'record' functionality. CommonJS require for named exports would typically be 'require("why-broke").record'.
check
import { check } from 'why-broke';
const check = require('why-broke');
Assumes a named 'check' function. The 'wrong' example attempts a default import or a full module import to a variable named 'check', which would be incorrect for a named export.

This TypeScript example demonstrates installing, initializing, and using `why-broke` to wrap a build command programmatically, typical for CI/CD pipelines or automated development scripts.

import { exec } from 'child_process'; import path from 'path'; // This script demonstrates common why-broke usages programmatically, // often seen in build scripts or advanced CI/CD setups where shell commands // are orchestrated via Node.js. const projectRoot = process.cwd(); // Assumes script is run from project root async function setupAndRunWhyBroke() { console.log('1. Installing why-broke as a dev dependency...'); // Ensure why-broke is available. In a real scenario, this might be in package.json. await new Promise<void>((resolve, reject) => { exec('npm install --save-dev why-broke', { cwd: projectRoot }, (err, stdout, stderr) => { if (err) { console.error(`Installation failed: ${stderr}`); return reject(err); } console.log(stdout); resolve(); }); }); console.log('\n2. Initializing why-broke in the project...'); // This sets up automatic state recording on 'npm install' await new Promise<void>((resolve, reject) => { exec('npx why-broke init', { cwd: projectRoot }, (err, stdout, stderr) => { if (err) { console.error(`Init failed: ${stderr}`); return reject(err); } console.log(stdout); resolve(); }); }); console.log('\n3. Attempting a wrapped build with why-broke...'); // why-broke will record a "good state" if this build succeeds, // or diagnose if it fails. await new Promise<void>((resolve, reject) => { exec('npx why-broke "npm run build"', { cwd: projectRoot }, (err, stdout, stderr) => { console.log(stdout); // why-broke's diagnostic output will be here if (stderr) { console.error(stderr); } if (err) { console.error(`\nBuild command failed with exit code ${err.code}.`); console.error('why-broke should have provided a diagnosis above.'); return reject(err); } console.log('\nBuild succeeded. why-broke might have recorded a new good state.'); resolve(); }); }); console.log('\nDemonstration complete.'); } setupAndRunWhyBroke().catch(error => { console.error('An error occurred during the why-broke demonstration:', error); process.exit(1); });
why-broke --version
Debug
Known issues
gotchaThe `.why-broke.json` snapshot file stores local environmental state and should never be committed to version control. Committing it can lead to confusing or incorrect diagnostics when shared across different machines or environments.
fix
Add `.why-broke.json` to your project's `.gitignore` file immediately after initializing `why-broke` to prevent accidental commits.
affects: >=1.0
gotcha`why-broke`'s accuracy heavily depends on a reliable "good state" baseline. If this baseline is outdated, corrupted, or was recorded during a temporarily broken state, subsequent diagnostic reports may be misleading or inaccurate.
fix
Manually re-record a verified good state by running `npx why-broke record` whenever you are certain the project is building and running correctly.
affects: >=1.0
gotchaThe `GitDetector` within `why-broke` provides change reports with `LOW` confidence for aspects like Git history or dirty working directories. These reports are less definitive than `HIGH` confidence reports from other detectors.
fix
Corroborate findings from the `GitDetector` with manual inspection of `git status` and `git log` for a more certain diagnosis regarding Git-related drift.
affects: >=1.4
Errors
Common errors & fixes
command not found: why-broke
The `why-broke` package is not installed globally or locally, or `npx` cannot locate it in the current environment's PATH.
fix
Install `why-broke` globally via `npm install -g why-broke` or as a dev dependency with `npm install --save-dev why-broke`. Ensure `npx` is available and in your system's PATH.
✖ Command failed. Diagnosing cause... (followed by an empty or unhelpful report)
The previously recorded "good state" baseline is missing, corrupted, or was set when the project was already in a problematic state, preventing meaningful comparison.
fix
Run `npx why-broke record` when your project is in a verified working condition to establish a fresh, reliable baseline for future comparisons.
Error: EACCES: permission denied, open '.why-broke.json'
The user executing `why-broke` does not have sufficient file system write permissions to create or modify the `.why-broke.json` file in the project's root directory.
fix
Ensure the user has write permissions in the project root. Avoid running `npm` or `npx` commands with `sudo` unless absolutely necessary, as this can lead to incorrect file ownership and permissions.
Upgrade
Version history
1.4.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
18 hits · last 30 days
node
16
Resources
why-broke — npm install why-broke · libregistry