# CLI Diff Auditor

A CLI tool that automatically audits code diffs before commit by scanning staged changes for common issues like debug statements, console.log calls, TODO comments, missing error handling, and security vulnerabilities. Features configurable rules, auto-fix support, and git pre-commit hook integration.

![CI](https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-diff-auditor/actions/workflows/ci.yml/badge.svg)
![Version](https://img.shields.io/badge/version-1.0.0-blue)
![Python](https://img.shields.io/badge/python-3.8+-green)

## Features

- Scans staged git changes for common issues
- Configurable rule system with YAML configuration
- Auto-fix support for certain problems
- Git pre-commit hook integration
- Summary report with severity levels (error, warning, info)
- JSON output for CI integration
- Colorful terminal output using Rich

## Installation

```bash
pip install cli-diff-auditor
```

Or from source:

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-diff-auditor.git
cd cli-diff-auditor
pip install -e ".[dev]"
```

## Usage

### Basic Audit

```bash
# Audit staged changes
diff-auditor audit

# Audit all changed files (not just staged)
diff-auditor audit --all-changed

# Audit specific files
diff-auditor audit src/file.py tests/file.py
```

### Auto-fix Issues

```bash
# Automatically fix issues where possible
diff-auditor audit --auto-fix
```

### Pre-commit Hook

```bash
# Install pre-commit hook
diff-auditor hook install

# Remove pre-commit hook
diff-auditor hook uninstall
```

### Check Command

```bash
# Quick check without detailed output
diff-auditor check
```

## Configuration

Create a `.cli-diff-auditor.yaml` or `diff-auditor-rules.yml` file in your project root:

```yaml
rules:
  debug_statements:
    enabled: true
    severity: error
    pattern: "(console\\.log|print\\(|p\\()"
    auto_fix: false
    description: "Debug statements should not be committed"

  todo_comments:
    enabled: true
    severity: warning
    pattern: "(TODO|FIXME|HACK|XXX):.*"
    auto_fix: false
    description: "TODO comments should be addressed before commit"

  print_statements:
    enabled: true
    severity: warning
    pattern: "^\\s*print\\("
    auto_fix: false
    description: "Print statements may leak sensitive information"

  hardcoded_secrets:
    enabled: true
    severity: error
    pattern: "(api_key|apikey|secret|password|token)\\s*=\\s*['\"][a-zA-Z0-9_]{20,}['\"]"
    auto_fix: false
    description: "Potential hardcoded secrets detected"

  missing_error_handling:
    enabled: true
    severity: warning
    pattern: "except:\\s*$"
    auto_fix: false
    description: "Bare except clause catches all exceptions"

  long_lines:
    enabled: true
    severity: info
    pattern: "^.{121,}$"
    auto_fix: false
    description: "Lines should not exceed 120 characters"

custom_rules:
  - name: "sql_injection"
    pattern: "(execute|query)\\([^)]*\\%s.*\\+"
    severity: error
    description: "Potential SQL injection vulnerability"
    auto_fix: false
```

## Built-in Rules

| Rule | Severity | Description |
|------|----------|-------------|
| debug_statements | error | Catches `console.log`, `p()`, `print()` statements |
| todo_comments | warning | Catches TODO, FIXME, HACK, XXX comments |
| print_statements | warning | Catches print() statements |
| hardcoded_secrets | error | Detects potential hardcoded secrets |
| missing_error_handling | warning | Detects bare except clauses |
| long_lines | info | Flags lines exceeding 120 characters |
| console_log | error | Catches console.log statements |
| debugger_statement | error | Catches debugger statements |

## Exit Codes

- `0`: No issues found or only info level issues
- `1`: Warnings found
- `2`: Errors found
- `3`: Configuration error

## Examples

### Basic Usage

```bash
$ diff-auditor audit
🔍 Scanning staged changes...

📊 Audit Summary:
  Errors: 2
  Warnings: 3
  Info: 1

❌ ERRORS:
  src/utils.py:15 - Potential hardcoded secret detected
  tests/test_main.py:8 - console.log statement found

⚠️  WARNINGS:
  src/main.py:42 - TODO comment found
  src/main.py:100 - Bare except clause detected
  src/utils.py:55 - print() statement found

ℹ️  INFO:
  src/main.py:120 - Line exceeds 120 characters
```

### JSON Output (CI Integration)

```bash
$ diff-auditor audit --json
{
  "status": "errors_found",
  "summary": {
    "errors": 2,
    "warnings": 3,
    "info": 1
  },
  "issues": [
    {
      "file": "src/utils.py",
      "line": 15,
      "rule": "hardcoded_secrets",
      "severity": "error",
      "message": "Potential hardcoded secret detected"
    },
    ...
  ]
}
```

### Install Pre-commit Hook

```bash
$ diff-auditor hook install
✅ Pre-commit hook installed successfully at .git/hooks/pre-commit
```

The hook will now run `diff-auditor check` before each commit and block commits with errors.

## Development

### Setup

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-diff-auditor.git
cd cli-diff-auditor
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest tests/ -v
pytest tests/ --cov=src --cov-report=term-missing
```

### Project Structure

```
cli-diff-auditor/
├── src/
│   └── cli_diff_auditor/
│       ├── __init__.py
│       ├── analyzer.py       # File analyzer and audit result classes
│       ├── autofix.py        # Auto-fix functionality
│       ├── cli.py            # Main CLI interface
│       ├── diff_parser.py    # Diff parsing engine
│       ├── hook.py           # Pre-commit hook integration
│       └── rules.py          # Rule definitions and configuration
├── tests/
│   ├── test_analyzer.py
│   ├── test_autofix.py
│   ├── test_cli.py
│   ├── test_diff_parser.py
│   ├── test_integration.py
│   └── test_rules.py
├── pyproject.toml
├── setup.py
└── README.md
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `pytest tests/ -v`
5. Submit a pull request

## License

MIT License