Metadata-Version: 2.4
Name: slopbuster
Version: 0.5.1
Summary: Surgical code-sanitization engine that turns vibe-coded Python into clean, professional code.
Author-email: Tallow <tallow@example.com>
License-Expression: MIT
Keywords: code-quality,refactor,clean-code,ai-slop,formatter,linter
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Requires-Dist: ruff
Requires-Dist: rich
Requires-Dist: radon>=6.0.1
Requires-Dist: mccabe>=0.7.0
Dynamic: license-file

# VibeCheck

> **Precision cleaning for the professional engineer.**

VibeCheck is a **surgical code-sanitization engine**. It transforms "vibe-coded" (AI-assisted or hastily written) Python into clean, professional source code by removing conversational filler, redundant documentation, and low-effort naming — without changing program behavior.

Directory support, rich reports, and a conservative approach keep it safe for real codebases. Pro tier (separate binary) adds unlimited scale and extras.

## Key Features

- **AI Reflective Stripper**: Removes the #1 AI tell — meta comments like "Note that I've implemented...", "Hope this helps!", "As you can see...".
- **Redundant Docstring Cleaner (AST-Powered)**: Deletes docstrings that merely echo the function or class name (e.g. `def get_data(): """get data"""`).
- **Naming Analyzer**: Detects low-effort variables (`data`, `res`, `tmp`, `result`, `obj`...) and reports them in a dedicated table.
- **Metadata-Aware Pipeline**: Strategies populate rich `VibeReport` metadata (counts, issues list) for detailed analysis and "Boy Scout" recommendations.
- **Cognitive Load Index**: Multi-factor score (cyclomatic complexity via radon + slop density + nesting).
- **Structural Normalizer**: Collapses excessive blank lines and trims erratic whitespace.
- **Boy Scout Recommendations**: Actionable clean-code advice printed when issues are found.
- **Pro tier**: The separate `vibecheck-pro` binary (via Lemon Squeezy) unlocks `--aggressive`, full `ruff format`, `--json-report`, unlimited batch sizes, and more. The free `pip` package has soft limits.

## Before & After

### Before
```python
# vibes
# Note that i've implemented the logic below to handle the response
def get_data(data):
    """get data"""
    # lol slop
    res = data
    return res
```

### After (cleaned by VibeCheck)
```python
def get_data(data):
    res = data
    return res
```

**Report:**
- Slop Indicators Removed: 3
- Structural Improvements: 1 (redundant docstring)
- Suspicious Naming: `data`, `res` flagged (see table below)

Names are reported by default; pass `--fix-names` to auto-rename via AST transformation.

## Advanced Metrics & Reporting

VibeCheck computes a **Cognitive Load Index** (0-100) using:
- Cyclomatic complexity (via radon)
- Slop / vibe-keyword density
- Structural nesting depth

It produces a rich `VibeReport` consumed by the CLI for tables and recommendations.

Example report (with the new Naming table):

```text
      Clarity Analysis: my_code.py        
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Metric               ┃ Value        ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Original Vibe        │ Chaotic      │
│ Clean Vibe           │ Stable       │
│ Slop Indicators Removed │ 3          │
│ Structural Improvements │ 1          │
│ Cognitive Load Index │ 42.0         │
└──────────────────────┴──────────────┘

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Suspicious Naming Detected ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Suspicious variable: res   │
│ Suspicious variable: data  │
└────────────────────────────┘

┌────────────────────────────────────────────┐
│ Boy Scout Recommendation                   │
├────────────────────────────────────────────┤
│ Suspicious variable/function names         │
│ detected. Use more descriptive names...    │
└────────────────────────────────────────────┘
```

See `vibecheck/core/interfaces.py` for the full VibeReport dataclass.

## Usage

```bash
# Analyze only (no writes)
vibecheck my_code.py --report-only
# or explicitly
vibecheck clean my_code.py --report-only

# Clean the file in place (creates no backup — use git)
vibecheck my_code.py

# Auto-rename suspicious variables/functions
vibecheck src/ --fix-names

# Only clean files modified since the last commit (git-aware)
vibecheck --git

# Git-stash dirty state first then clean (safety net)
vibecheck src/ --backup

# Install a pre-commit hook to clean staged .py files
vibecheck install-hooks
```

The primary command is `clean <path>` (defaults to `.`). Both files and directories (recursive) are supported. Use `--report-only` for analysis without edits. Always commit or backup first.

### Pro features (Pro binary)

The free package (`pip install slopbuster`) is fully functional for most use. Pro is delivered as a standalone binary via Lemon Squeezy (no key, just drop `vibecheck-pro` in your PATH).

```bash
# With the Pro binary in PATH (name auto-enables full features)
vibecheck-pro src/ --aggressive --json-report report.json
```

See `vibecheck clean --help` (or `vibecheck-pro ...`) for options. Pro removes the free tier's 10-file batch soft limit and enables aggressive patterns + ruff format + JSON export.

## Example Report

```text
      Clarity Analysis: my_code.py        
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Metric               ┃ Value        ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Original Vibe        │ Chaotic      │
│ Clean Vibe           │ Professional │
│ Slop Indicators      │ 14           │
│ Cognitive Load Index │ 4.2          │
└──────────────────────┴──────────────┘
```

## Installation

From PyPI (recommended):

```bash
pip install slopbuster
# or
uv pip install slopbuster
```

For development (uv recommended):

```bash
git clone ...
cd vibecheck_repo
uv sync --dev   # or uv pip install -e . -r <(uv pip compile --group dev ...)
```

Check version:

```bash
vibecheck --version
```

## Free vs Pro

VibeCheck core is free and open source (MIT) on PyPI.

- **Free** (`pip install slopbuster`): Full pipeline, reports, naming fixes, git integration, hooks, etc. Soft limit: max 10 files per batch/directory operation (single files always allowed). When the limit is hit it prints an upgrade link.
- **Pro** (commercial binary): Unlimited files, `--aggressive` patterns, post-clean `ruff format`, `--json-report`, and future extras. Distributed as a standalone executable via Lemon Squeezy (no PyPI, no keys). Just place `vibecheck-pro` in PATH — the binary name auto-enables Pro mode.

Purchase / download the Pro binary at the [Lemon Squeezy store](https://buy.lemonsqueezy.com/vibecheck-pro). After purchase Lemon Squeezy emails the direct download link.

The `vibecheck-pro/` build configuration lives alongside the free source (see `vibecheck-pro.spec` + `scripts/build_pro_binary.sh`).

## Pro Tier

Pro features (available in the Lemon Squeezy binary):

- Unlimited batch/directory size (free has 10-file soft cap)
- `--aggressive`: Additional patterns (todo/hack/temp etc.)
- Post-clean `ruff format` (free only does `ruff check --fix`)
- `--json-report path.json`: Structured output for CI/tooling

Example (once the Pro binary is in PATH):

```bash
vibecheck-pro dirty/ --json-report report.json --aggressive
```

Feedback and feature requests are very welcome.

---

## Donate

If VibeCheck saves you time and you want to say thanks:

- **Ko-fi**: https://ko-fi.com/devot

All donations fund further development of VibeCheck and sibling projects.

---

## License

MIT
