🦅 why-broke

It worked yesterday. Why not today?

The Problem

You pull the code. You run npm start. It crashes. You didn't change anything. So why is it broken?

Standard tools show Where it crashed (Stack Trace). why-broke shows Why it crashed (What changed).

The Solution

We take a tiny snapshot of your system when it works. When it breaks, we compare the difference.

We instantly spot the invisible things that Git misses:

• 📦 Silent Updates: A dependency upgraded and broke you.
• 🔐 Missing Info: You forgot a new .env key.
• ⚡ Wrong Tools: You are running Node 18, but the team switched to 20.

� Installation

Option A: Global (Good for local dev)

npm install -g why-broke

Option B: Dev Dependency (Best for Teams/CI)

npm install --save-dev why-broke

�🚀 Usage

1. The Recommended Way (Set & Forget)

Run this once in your project root:

npx why-broke init

Now, every time you run npm install, we automatically save the "Good State" in the background.

2. The One-Off Way (Auto-Pilot)

Wrap your build command. We watch it for you.

npx why-broke "npm run build"

• Success? We save the "Good State" silently.
• Failure? We wake up and tell you what changed.

3. Manual Control

npx why-broke record   # "This works!"
npx why-broke check    # "Whoops, it's broken."

📸 What it looks like

When your build fails, why-broke gives you a clear root cause analysis:

✖ Command failed. Diagnosing cause...

 HIGH  [Runtime Drift]
       Node version changed from v18.16.0 to v20.2.0
       └─ Fix: Switch back to v18.16.0 using nvm.

 HIGH  [Dependency Integrity]
       Lockfile has changed. Underlying dependencies have drifted.
       └─ Fix: Run "npm ci" to restore exact versions.

 MED   [Dependency Definition]
       axios changed in package.json: ^1.4.0 -> ^1.5.0
       └─ Fix: Revert axios to ^1.4.0 or check changelogs.

🤖 CI/CD Integration

Use why-broke in GitHub Actions to debug "It works strictly on my machine" issues.

example-workflow.yml

steps:
  - uses: actions/checkout@v3
  - uses: actions/setup-node@v3
  
  # Run your build with Auto-Pilot
  - name: Build & Analyze
    run: npx why-broke "npm run build"

If the build passes, we record the baseline. If it fails later, we tell you why.

❓ FAQ

Q: Where is the snapshot stored? A: In a file called .why-broke.json in your project root.

Q: Should I commit .why-broke.json? A: No. Add it to your .gitignore. This file represents your local machine's working state.

Q: Does it read my source code? A: No. We only hash package-lock.json and check process.env keys. We never read or store your actual code or secrets.

🧠 Causal Inference Engine (v1.4)

We don't just dump a diff. We run a probabilistic analysis using 5 specialized detectors:

| Detector | Checks | Confidence | | :--- | :--- | :--- | | RuntimeDetector | Node Version, OS, CPU Architecture. | HIGH | | DependencyDetector | Lockfile hash, Manifest versions, Integrity. | HIGH | | ConfigDetector | Critical configs (tsconfig, webpack, Docker). | HIGH | | EnvDetector | Missing keys (ignores volatile npm_ vars). | HIGH | | GitDetector | Commit history, Dirty state, Branch drift. | LOW |

License

MIT