Error Handling Auditor

A CLI tool that scans codebases for error handling issues across Python, JavaScript/TypeScript, Go, and Rust. Designed for CLI use, CI pipelines, and LLM-based PR review workflows.

Installation

pip install error-auditor

Or install from source:

git clone https://github.com/example/error-auditor
cd error-auditor
pip install -e .

Usage

Full Repository Scan

Scan an entire codebase for error handling issues:

# Scan a directory
error-auditor scan ./src

# Scan multiple paths
error-auditor scan ./src ./lib ./pkg

# Scan specific languages only
error-auditor scan . --lang python,go

# Exclude directories
error-auditor scan . -e "**/test/**" -e "**/vendor/**" -e "**/__pycache__/**"

PR Review Mode (Diff Scanning)

Scan only changed lines from a git diff - ideal for PR reviews:

# Pipe git diff directly
git diff main..HEAD | error-auditor diff

# Compare against origin
git diff origin/main | error-auditor diff

# Use a patch file
error-auditor diff --diff changes.patch

# Specify base path for file resolution
git diff HEAD~1 | error-auditor diff --base-path ./src

CI Integration

# Exit with code 1 if errors found
error-auditor scan ./src --ci

# Fail on warnings or higher
error-auditor scan ./src --ci --fail-on warning

# PR check - only fail on new issues
git diff $BASE_SHA..$HEAD_SHA | error-auditor diff --ci --fail-on error

Output Formats

# Human-readable text (default)
error-auditor scan ./src

# JSON for LLM consumption or programmatic use
error-auditor scan ./src -f json

# JSON to file
error-auditor scan ./src -f json -o report.json

# SARIF for IDE/GitHub Code Scanning integration
error-auditor scan ./src -f sarif -o results.sarif

# Compact JSON (no pretty printing)
error-auditor scan ./src -f json --compact

Filtering

# Only show errors (hide warnings and info)
error-auditor scan ./src --min-severity error

# Only show warnings and above
error-auditor scan ./src --min-severity warning

Stdin Mode

Check code snippets directly:

# Pipe code directly
echo 'try:
    risky()
except:
    pass' | error-auditor check -l python

# Check with specific filename for language detection
cat myfile.go | error-auditor check -n myfile.go

List Available Rules

error-auditor rules

Detected Issues

Python

JavaScript/TypeScript

Go

Rust

Output Examples

Text Output

src/api.py:42:5 error[bare-except]: Bare except clause catches all exceptions
   |
42 | except:
   |     ^^^
   = suggestion: Specify exception type: `except Exception as e:`

Found 1 issue(s): 1 error(s), 0 warning(s)

JSON Output

{
  "summary": {
    "total": 1,
    "errors": 1,
    "warnings": 0,
    "info": 0,
    "files_scanned": 5
  },
  "issues": [
    {
      "file": "src/api.py",
      "line": 42,
      "column": 5,
      "severity": "error",
      "rule": "bare-except",
      "message": "Bare except clause catches all exceptions including KeyboardInterrupt and SystemExit",
      "code_snippet": "except:",
      "suggestion": "Specify exception type: `except Exception as e:`",
      "language": "python"
    }
  ]
}

GitHub Actions Example

name: Error Handling Check

on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install error-auditor
        run: pip install error-auditor

      - name: Full scan (informational)
        run: error-auditor scan . -f json -o full-report.json
        continue-on-error: true

      - name: Check changed files only
        run: |
          git diff origin/${{ github.base_ref }}..HEAD | \
            error-auditor diff --ci --fail-on error

LLM PR Review Integration

The JSON output is designed for LLM consumption in PR review workflows:

# Generate report for LLM
git diff origin/main | error-auditor diff -f json > /tmp/issues.json

# Feed to your LLM review pipeline
cat /tmp/issues.json | your-llm-review-tool

The structured output includes:

• File path, line, and column for precise location
• Severity level for prioritization
• Rule name for categorization
• Code snippet for context
• Actionable suggestion for fixes

Exit Codes

License

MIT