Metadata-Version: 2.4
Name: vibesafex
Version: 0.3.0
Summary: AI-generated code safety scanner for the vibe coding era
Project-URL: Homepage, https://github.com/stef41/vibesafex
Project-URL: Repository, https://github.com/stef41/vibesafex
Project-URL: Issues, https://github.com/stef41/vibesafex/issues
Author: stef41
License: Apache-2.0
License-File: LICENSE
Keywords: ai-code-review,ai-generated-code,claude-code,code-scanner,copilot,cursor,linter,llm,mcp,security,static-analysis,vibe-coding
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# vibesafex

[![CI](https://github.com/stef41/vibesafex/actions/workflows/ci.yml/badge.svg)](https://github.com/stef41/vibesafex/actions/workflows/ci.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/vibesafex.svg)](https://pypi.org/project/vibesafex/)

**Stop shipping AI-generated code you haven't reviewed.**

vibesafex catches the bugs your AI coding agent won't tell you about: hallucinated imports, hardcoded secrets, security vulnerabilities, and dead code.

Built for the vibe coding era. Works with code from Claude Code, Cursor, Copilot, Windsurf, and any AI coding tool.

## Quick Start

```bash
pip install vibesafex
vibesafex scan .
```

## What It Catches

| Code | Category | Severity | What |
|------|----------|----------|------|
| VS100-VS110 | **Security** | error | `eval()`, `exec()`, `shell=True`, SQL injection, `os.system()`, unsafe YAML, weak hashes |
| VS200-VS210 | **Secrets** | error | OpenAI/AWS/GitHub/Anthropic/Stripe API keys, private keys, JWTs, hardcoded credentials |
| VS300 | **Imports** | warning | Hallucinated imports — packages that don't exist (AI's favorite mistake) |
| VS400-VS403 | **Dead Code** | warning | Unused imports, unreachable code, empty `except: pass`, bare except |
| VS500-VS507 | **AI Patterns** | warning | TODO/FIXME left by AI, placeholder functions, `NotImplementedError` stubs, mutable defaults, star imports |

## Usage

### Scan a directory
```bash
vibesafex scan src/
```

### Scan specific files
```bash
vibesafex scan main.py utils.py
```

### Check code from stdin
```bash
echo 'x = eval(input())' | vibesafex check
```

### JSON output (for CI/CD)
```bash
vibesafex scan . --format json
```

### Filter by severity
```bash
vibesafex scan . --severity error          # Only errors
vibesafex scan . --fail-on warning         # Fail CI on warnings too
```

## Python API

```python
from vibesafex import scan_code, scan_file, scan_directory

# Scan a string
issues = scan_code('x = eval(input())')
for issue in issues:
    print(f"{issue.code}: {issue.message}")

# Scan a file
issues = scan_file("main.py")

# Scan a project
result = scan_directory("src/")
print(f"{result.error_count} errors found in {result.files_scanned} files")
```

### Custom scanner configuration

```python
from vibesafex import Scanner

scanner = Scanner(
    severity_threshold="warning",  # Skip info-level
    exclude_dirs={".venv", "migrations"},
)
result = scanner.scan_directory(".")
```

## Example Output

<img src="assets/scan_report.svg" alt="vibesafex scan report" width="800">
<img src="assets/checks_overview.svg" alt="vibesafex checks" width="800">

```
  ✗ main.py:5:0 [error] VS100: Use of eval() - potential code injection vulnerability
  ✗ main.py:8:0 [error] VS200: Possible OpenAI API key
  ⚠ main.py:12:0 [warning] VS300: Import 'magic_ai_lib' - package 'magic_ai_lib' not found (hallucinated import?)
  ⚠ main.py:15:0 [warning] VS501: Function 'process' has empty body (pass) - placeholder
  ℹ main.py:20:0 [info] VS500: TODO comment - AI may have left incomplete implementation

5 files scanned: 2 errors, 2 warnings, 1 info
```

## Pre-commit Hook

```yaml
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: vibesafex
        name: vibesafex
        entry: vibesafex scan --fail-on error
        language: python
        types: [python]
        additional_dependencies: [vibesafex]
```

## Why Not Just Use Ruff/Pylint?

vibesafex focuses specifically on **AI-generated code patterns** that traditional linters miss:

- **Hallucinated imports**: AI confidently imports packages that don't exist. vibesafex checks against stdlib, installed packages, and 200+ known popular packages.
- **Secret leakage**: AI copies real-looking API keys into code. vibesafex detects patterns for 12+ providers.
- **Placeholder code**: AI leaves `pass`, `...`, `NotImplementedError` stubs that slip through review.
- **AI anti-patterns**: Mutable defaults, star imports, excessive `Any` — patterns AI generates more often than humans.

Use vibesafex **alongside** your existing linter, not instead of it.

## See Also

Part of the **stef41 LLM toolkit** — open-source tools for every stage of the LLM lifecycle:

| Project | What it does |
|---------|-------------|
| [tokonomics](https://github.com/stef41/tokonomix) | Token counting & cost management for LLM APIs |
| [datacrux](https://github.com/stef41/datacruxai) | Training data quality — dedup, PII, contamination |
| [castwright](https://github.com/stef41/castwright) | Synthetic instruction data generation |
| [datamix](https://github.com/stef41/datamix) | Dataset mixing & curriculum optimization |
| [toksight](https://github.com/stef41/toksight) | Tokenizer analysis & comparison |
| [trainpulse](https://github.com/stef41/trainpulse) | Training health monitoring |
| [ckpt](https://github.com/stef41/ckptkit) | Checkpoint inspection, diffing & merging |
| [quantbench](https://github.com/stef41/quantbenchx) | Quantization quality analysis |
| [infermark](https://github.com/stef41/infermark) | Inference benchmarking |
| [modeldiff](https://github.com/stef41/modeldiffx) | Behavioral regression testing |
| [injectionguard](https://github.com/stef41/injectionguard) | Prompt injection detection |

## License

Apache 2.0
