VibeGuard

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)

pip install vibeguard

From Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard.git
cd vibeguard
pip install -e ".[dev]"

Using Homebrew

brew install vibeguard

Quick Start

Basic Analysis

Scan the current directory for AI anti-patterns:

vibeguard analyze .

Scan a specific directory:

vibeguard analyze /path/to/your/project

Output Formats

Console Output (Default):

vibeguard analyze .

JSON Output:

vibeguard analyze . --output json
# or
vibeguard analyze . --json

HTML Report:

vibeguard analyze . --html report.html

SARIF Report (for GitHub Code Scanning):

vibeguard analyze . --sarif results.sarif

Severity Filtering

Only show issues at or above a certain severity level:

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:

vibeguard analyze . -v
# or
vibeguard analyze . --verbose

Configuration

VibeGuard can be configured using a .vibeguard.toml configuration file in your project root.

Example Configuration

[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:

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:

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

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:

- 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

{
  "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.

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

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard.git
cd vibeguard
pip install -e ".[dev]"

Running Tests

# 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

# 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:

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 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