error-handling-check 0.1.0
Scan codebases for error handling issues across Python, JS/TS, Go, and Rust
License: MIT
Requires Python: >=3.9
Keywords: error-handling, static-analysis, linter, code-quality

# 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

```bash
pip install error-auditor
```

Or install from source:

```bash
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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
error-auditor rules
```

## Detected Issues

### Python

| Rule | Severity | Description |
|------|----------|-------------|
| `bare-except` | error | Bare `except:` catches all exceptions including KeyboardInterrupt |
| `broad-except` | warning | Catching broad `Exception` without re-raise or logging |
| `pass-in-except` | warning | Empty except block with just `pass` |

### JavaScript/TypeScript

| Rule | Severity | Description |
|------|----------|-------------|
| `empty-catch` | warning | Empty catch block in try/catch |
| `empty-catch-callback` | warning | Empty `.catch()` callback on promises |

### Go

| Rule | Severity | Description |
|------|----------|-------------|
| `ignored-error` | warning | Error return explicitly ignored with `_` |
| `unchecked-error` | warning | Error assigned but never checked |

### Rust

| Rule | Severity | Description |
|------|----------|-------------|
| `unwrap-used` | warning | `.unwrap()` can panic at runtime |
| `poor-expect-message` | info | `.expect()` with non-descriptive message |
| `unwrap-or-default` | info | `.unwrap_or_default()` may hide errors |
| `unused-result` | warning | `Result` value not used or checked |

## 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

```json
{
  "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

```yaml
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:

```bash
# 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

| Code | Meaning |
|------|---------|
| 0 | No issues found (or below threshold) |
| 1 | Issues found at or above `--fail-on` severity |
| 2 | Configuration or runtime error |

## License

MIT