# VibeGuard

[![CI/CD](https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](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