big-brocode

Explain and surface JavaScript/TypeScript/React errors fast, with optional TypeScript-powered scanning and SARIF/ESLint outputs.

Highlights

• CLI that accepts raw error text, codes, or stack traces.
• Project/file analyzer that runs lightweight heuristics plus real TypeScript diagnostics.
• Multiple output formats: text, JSON, ESLint-compatible, SARIF.
• Safe autofix hook (apply fixes where available).

Install

npm install -g big-brocode
# or per-project
npm install --save-dev big-brocode

Quick Start

Explain a single error string:

bigbro "TS2339: Property 'x' does not exist on type 'User'"

Explain with explicit options:

bigbro --message "TypeError: Cannot read properties of undefined" --language javascript
bigbro --code 2304 --language typescript
bigbro --stack "TypeError: Cannot read properties of undefined
    at src/app.js:10:5"

Analyze files or projects:

# Analyze all JS/TS files under a directory
bigbro analyze fixtures

# Specific glob(s)
bigbro analyze "src/**/*.ts" "app/**/*.tsx"

# JSON output (exit code 0 if findings, 2 if none)
bigbro analyze fixtures --format json

# ESLint-format output
bigbro analyze fixtures --format eslint

# SARIF output
bigbro analyze fixtures --format sarif

Autofix (experimental/safe):

bigbro analyze src --fix

Options (CLI)

• -m, --message <text>: Error message to explain.
• -l, --language <lang>: javascript, typescript, javascriptreact, typescriptreact.
• -c, --code <num>: Numeric error code (e.g., 2339).
• -s, --stack <string>: Stack trace string (auto-detects language).
• --format text|json|eslint|sarif: Output format (default text unless --json).
• --project, -p <path>: Path to tsconfig.json for diagnostics.
• --no-typescript: Skip TypeScript diagnostics during analyze.
• --fix: Apply safe autofixes where available.
• --all: Return all matching explanations instead of best match.
• --json: Shortcut for JSON output in explain mode.
• --schema: Print JSON schema for explain output.
• -h, --help: Show help.

Exit Codes

• Explain mode: 0 on explanation found, 2 when none.
• Analyze mode: 0 when findings exist, 2 when no findings.

Library Usage (ESM)

import {
  explainError,
  explainFromStackTrace,
  analyzeFile,
  analyzeFiles,
} from "big-brocode";

const entry = explainError({ message: "TS2339: Property 'x' does not exist" });
const stackEntry = explainFromStackTrace(stackString);
const single = analyzeFile("src/example.ts");
const many = analyzeFiles(["src/**/*.ts"]);

Dev Notes

• Build: npm run build
• Watch: npm run watch
• Node: tested on Node 18+.
• Source lives in src/, distributed ESM in dist/.

Sample Fixtures

Handy for smoke tests (already in the repo):

• fixtures/ts-errors.ts — common TS errors (2339, 2322, 7006, 2304).
• fixtures/react-hook.tsx — invalid hook placement warning.
• fixtures/error-texts.js — raw error strings to trigger detectors.

Publishing

• Ensure npm run build succeeds.
• Confirm dist/cli.js starts with a shebang for global installs.
• Publish: npm publish