why-broke Causal Debugger

Common errors

• command not found: why-broke

  cause 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)

  cause 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'

  cause 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.

Warnings

• gotcha The `.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.
• 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.
• gotcha The `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.

Install

• npm install why-broke npm
• yarn add why-broke yarn
• pnpm add why-broke pnpm

Imports

• init
  wrong:

  const init = require('why-broke').init;

  correct:

  import { init } from 'why-broke';

  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
  wrong:

  import record from 'why-broke';

  correct:

  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
  wrong:

  const check = require('why-broke');

  correct:

  import { check } from '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.

Quickstart

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);
});