Initial upload: VibeGuard AI Code Anti-Pattern Detector v0.1.0
This commit is contained in:
415
README.md
415
README.md
@@ -1,3 +1,414 @@
|
||||
# vibeguard
|
||||
# VibeGuard
|
||||
|
||||
A CLI tool that scans code repositories for anti-patterns commonly introduced by AI coding assistants. Detects magic strings, inconsistent error handling, missing type annotations, and hardcoded values across Python, JavaScript, TypeScript, Go, and Rust.
|
||||
[](https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard/actions)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.python.org/downloads/)
|
||||
|
||||
VibeGuard is a CLI tool that scans code repositories for anti-patterns commonly introduced by AI coding assistants. It detects patterns like magic strings without constants, inconsistent error handling, missing type annotations, overly complex one-liners, and hardcoded values.
|
||||
|
||||
## Features
|
||||
|
||||
- **Multi-language Support**: Analyzes Python, JavaScript, TypeScript, Go, and Rust code
|
||||
- **31+ Anti-Patterns**: Detects common AI-generated code issues across all supported languages
|
||||
- **Severity Levels**: Categorizes issues by severity (critical, error, warning, info)
|
||||
- **CI/CD Integration**: Works with GitHub Actions, GitLab CI, and other CI systems
|
||||
- **Multiple Report Formats**: Generates JSON, HTML, and SARIF reports
|
||||
- **Fix Suggestions**: Provides actionable suggestions with code examples
|
||||
- **Pre-commit Hooks**: Integrates with pre-commit for local scanning
|
||||
|
||||
## Installation
|
||||
|
||||
### From PyPI (Recommended)
|
||||
|
||||
```bash
|
||||
pip install vibeguard
|
||||
```
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard.git
|
||||
cd vibeguard
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### Using Homebrew
|
||||
|
||||
```bash
|
||||
brew install vibeguard
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Analysis
|
||||
|
||||
Scan the current directory for AI anti-patterns:
|
||||
|
||||
```bash
|
||||
vibeguard analyze .
|
||||
```
|
||||
|
||||
Scan a specific directory:
|
||||
|
||||
```bash
|
||||
vibeguard analyze /path/to/your/project
|
||||
```
|
||||
|
||||
### Output Formats
|
||||
|
||||
**Console Output (Default):**
|
||||
```bash
|
||||
vibeguard analyze .
|
||||
```
|
||||
|
||||
**JSON Output:**
|
||||
```bash
|
||||
vibeguard analyze . --output json
|
||||
# or
|
||||
vibeguard analyze . --json
|
||||
```
|
||||
|
||||
**HTML Report:**
|
||||
```bash
|
||||
vibeguard analyze . --html report.html
|
||||
```
|
||||
|
||||
**SARIF Report (for GitHub Code Scanning):**
|
||||
```bash
|
||||
vibeguard analyze . --sarif results.sarif
|
||||
```
|
||||
|
||||
### Severity Filtering
|
||||
|
||||
Only show issues at or above a certain severity level:
|
||||
|
||||
```bash
|
||||
vibeguard analyze . --severity error # Only show errors and critical
|
||||
vibeguard analyze . --severity critical # Only show critical issues
|
||||
```
|
||||
|
||||
### Verbose Mode
|
||||
|
||||
Enable verbose output for detailed information:
|
||||
|
||||
```bash
|
||||
vibeguard analyze . -v
|
||||
# or
|
||||
vibeguard analyze . --verbose
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
VibeGuard can be configured using a `.vibeguard.toml` configuration file in your project root.
|
||||
|
||||
### Example Configuration
|
||||
|
||||
```toml
|
||||
[analyze]
|
||||
severity_threshold = "warning" # Options: critical, error, warning, info
|
||||
incremental = true
|
||||
workers = 4
|
||||
|
||||
[patterns]
|
||||
# Enable all patterns
|
||||
enabled = ["all"]
|
||||
# Disable specific patterns
|
||||
disabled = ["PY001", "JS001"]
|
||||
|
||||
[ignore]
|
||||
paths = [
|
||||
"tests/",
|
||||
"docs/",
|
||||
"*.min.js",
|
||||
]
|
||||
|
||||
[output]
|
||||
theme = "default"
|
||||
show_fixes = true
|
||||
show_snippets = true
|
||||
max_snippet_lines = 5
|
||||
|
||||
[github]
|
||||
comment_on_pr = true
|
||||
create_check_runs = true
|
||||
```
|
||||
|
||||
### CLI Options Override Configuration
|
||||
|
||||
CLI options can override configuration file settings:
|
||||
|
||||
```bash
|
||||
vibeguard analyze . --config /path/to/custom/config.toml
|
||||
vibeguard analyze . --severity error --exit-zero
|
||||
```
|
||||
|
||||
## Anti-Patterns Detected
|
||||
|
||||
### Python
|
||||
|
||||
| ID | Name | Severity | Description |
|
||||
|----|------|----------|-------------|
|
||||
| PY001 | Magic String | Warning | Long string literal without explanation |
|
||||
| PY002 | Hardcoded Value | Warning | Hardcoded numeric value that should be a constant |
|
||||
| PY003 | Missing Return Type | Info | Function without return type annotation |
|
||||
| PY004 | Missing Docstring | Info | Function without docstring |
|
||||
| PY005 | Bare Except | Error | Catching all exceptions without specific type |
|
||||
| PY006 | Type Check Pattern | Warning | Using type() instead of isinstance() |
|
||||
|
||||
### JavaScript
|
||||
|
||||
| ID | Name | Severity | Description |
|
||||
|----|------|----------|-------------|
|
||||
| JS001 | Console Log | Warning | Console.log statement left in code |
|
||||
| JS002 | Var Keyword | Warning | Using var instead of const/let |
|
||||
| JS003 | Magic String | Warning | Long string literal without explanation |
|
||||
| JS004 | Hardcoded Value | Warning | Hardcoded numeric value |
|
||||
| JS005 | Inconsistent Error Handling | Info | Generic error variable name |
|
||||
| JS006 | Unnecessary Promise Wrapper | Warning | Unnecessary Promise constructor wrapper |
|
||||
|
||||
### TypeScript
|
||||
|
||||
| ID | Name | Severity | Description |
|
||||
|----|------|----------|-------------|
|
||||
| TS001 | Any Type Usage | Warning | Using 'any' type defeats TypeScript's purpose |
|
||||
| TS002 | Interface Naming | Info | Interface name should use PascalCase |
|
||||
| TS003 | Enum Usage | Info | Enum vs const object consideration |
|
||||
|
||||
### Go
|
||||
|
||||
| ID | Name | Severity | Description |
|
||||
|----|------|----------|-------------|
|
||||
| GO001 | Ignored Error | Error | Error being ignored with blank identifier |
|
||||
| GO002 | Context Background | Warning | Using context.Background() in production code |
|
||||
| GO003 | Potential Goroutine Leak | Warning | Goroutine without proper lifetime management |
|
||||
| GO004 | Magic String | Warning | Long string literal without explanation |
|
||||
| GO005 | Error Wrapping | Warning | Error not wrapped with %w verb |
|
||||
| GO006 | Naked Return | Warning | Naked return in function with multiple return values |
|
||||
|
||||
### Rust
|
||||
|
||||
| ID | Name | Severity | Description |
|
||||
|----|------|----------|-------------|
|
||||
| RS001 | Unnecessary Clone | Warning | Calling clone() on a Copy type |
|
||||
| RS002 | Allow Unused | Info | Allowing unused code instead of removing it |
|
||||
| RS003 | Expect Panic | Warning | Using expect() which can panic |
|
||||
| RS004 | Magic String | Warning | Long string literal without explanation |
|
||||
| RS005 | Unnecessary Boxing | Info | Unnecessary Box::new() usage |
|
||||
| RS006 | Into Iterator Consumption | Info | intoiter() consumes the collection |
|
||||
|
||||
### General Patterns
|
||||
|
||||
| ID | Name | Severity | Description |
|
||||
|----|------|----------|-------------|
|
||||
| GEN001 | Empty Catch Block | Error | Empty catch/except block that ignores errors |
|
||||
| GEN002 | Debug Code | Warning | Debug code left in production |
|
||||
| GEN003 | Inconsistent Naming | Info | Inconsistent naming convention in code |
|
||||
| GEN004 | Deep Nesting | Warning | Code with excessive nesting depth |
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
Create a workflow file at `.github/workflows/vibeguard.yml`:
|
||||
|
||||
```yaml
|
||||
name: VibeGuard
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, master]
|
||||
pull_request:
|
||||
branches: [main, master]
|
||||
|
||||
jobs:
|
||||
vibeguard:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.11'
|
||||
- name: Install VibeGuard
|
||||
run: pip install vibeguard
|
||||
- name: Run VibeGuard
|
||||
run: vibeguard analyze . --severity error --sarif results.sarif
|
||||
- name: Upload SARIF results
|
||||
if: always()
|
||||
uses: github/codeql-action/upload-sarif@v3
|
||||
with:
|
||||
sarif_file: results.sarif
|
||||
category: "/vibeguard"
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
vibeguard:
|
||||
image: python:3.11-slim
|
||||
script:
|
||||
- pip install vibeguard
|
||||
- vibeguard analyze . --severity error --sarif gl-sarif.json
|
||||
artifacts:
|
||||
when: always
|
||||
paths:
|
||||
- gl-sarif.json
|
||||
reports:
|
||||
sarif: gl-sarif.json
|
||||
```
|
||||
|
||||
### Pre-commit Hook
|
||||
|
||||
Add to your `.pre-commit-config.yaml`:
|
||||
|
||||
```yaml
|
||||
- repo: https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard
|
||||
rev: v0.1.0
|
||||
hooks:
|
||||
- id: vibeguard
|
||||
stages: [pre-commit]
|
||||
args: ['--severity', 'warning']
|
||||
```
|
||||
|
||||
## Report Formats
|
||||
|
||||
### JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"issues": [
|
||||
{
|
||||
"pattern": "PY001",
|
||||
"file": "src/main.py",
|
||||
"line": 42,
|
||||
"severity": "warning",
|
||||
"message": "Magic string detected",
|
||||
"suggestion": "Extract to a named constant"
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"critical": 0,
|
||||
"error": 2,
|
||||
"warning": 15,
|
||||
"info": 8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SARIF Format
|
||||
|
||||
SARIF (Static Analysis Results Interchange Format) is supported for integration with GitHub Code Scanning and other tools.
|
||||
|
||||
```bash
|
||||
vibeguard analyze . --sarif results.sarif
|
||||
```
|
||||
|
||||
### HTML Report
|
||||
|
||||
Generates a detailed HTML report with:
|
||||
- Summary statistics
|
||||
- Issues grouped by severity
|
||||
- Code snippets with highlighting
|
||||
- Fix suggestions
|
||||
|
||||
## Development
|
||||
|
||||
### Setting Up Development Environment
|
||||
|
||||
```bash
|
||||
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard.git
|
||||
cd vibeguard
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest tests/ -v
|
||||
|
||||
# Run unit tests only
|
||||
pytest tests/unit/ -v
|
||||
|
||||
# Run integration tests only
|
||||
pytest tests/integration/ -v
|
||||
|
||||
# Run with coverage
|
||||
pytest tests/ -v --cov=vibeguard
|
||||
```
|
||||
|
||||
### Linting and Type Checking
|
||||
|
||||
```bash
|
||||
# Black formatting
|
||||
black vibeguard tests
|
||||
|
||||
# Ruff linting
|
||||
ruff check .
|
||||
|
||||
# Type checking
|
||||
mypy vibeguard
|
||||
```
|
||||
|
||||
### Adding New Patterns
|
||||
|
||||
To add a new anti-pattern, extend the pattern definitions in `vibeguard/patterns/manager.py`:
|
||||
|
||||
```python
|
||||
Pattern(
|
||||
id="PY007",
|
||||
name="Your Pattern Name",
|
||||
description="Description of the pattern",
|
||||
severity=Severity.WARNING,
|
||||
languages=["python"],
|
||||
message="Your message",
|
||||
suggestion="Fix suggestion",
|
||||
category="category-name",
|
||||
)
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
vibeguard/
|
||||
├── cli/ # Command-line interface
|
||||
│ ├── commands/ # CLI commands (analyze, init, report)
|
||||
│ ├── output/ # Output rendering
|
||||
│ ├── main.py # CLI entry point
|
||||
│ └── theme.py # Rich console theme
|
||||
├── analyzers/ # Language-specific analyzers
|
||||
│ ├── languages/ # Python, JS, TS, Go, Rust analyzers
|
||||
│ ├── base.py # Base analyzer class
|
||||
│ └── factory.py # Analyzer factory
|
||||
├── patterns/ # Anti-pattern definitions
|
||||
│ ├── definitions.py # Pattern and Issue classes
|
||||
│ └── manager.py # Pattern loading and management
|
||||
├── reports/ # Report generation
|
||||
│ └── generator.py # JSON, HTML, SARIF generation
|
||||
├── integrations/ # CI/CD integrations
|
||||
│ └── github.py # GitHub API integration
|
||||
├── utils/ # Utilities
|
||||
│ ├── config.py # Configuration handling
|
||||
│ └── file_finder.py # File discovery
|
||||
├── templates/ # HTML report templates
|
||||
├── tests/ # Test suite
|
||||
└── __main__.py # Package entry point
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
|
||||
1. Fork the repository
|
||||
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
|
||||
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. Push to the branch (`git push origin feature/AmazingFeature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- Inspired by the growing discussion around AI-generated code quality in open-source projects
|
||||
- Built with Click, Rich, and Tree-sitter for robust CLI and parsing capabilities
|
||||
|
||||
Reference in New Issue
Block a user