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