Initial upload with CI/CD workflow
This commit is contained in:
260
README.md
260
README.md
@@ -1,3 +1,259 @@
|
||||
# cli-diff-auditor
|
||||
# CLI Diff Auditor
|
||||
|
||||
A CLI tool that automatically audits code diffs before commit by scanning staged changes for common issues like debug statements, TODO comments, and security vulnerabilities.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user