Metadata-Version: 2.4
Name: codepolish
Version: 0.1.0
Summary: Detect AI-generated code anti-patterns.
Author-email: CodePolish Team <team@codepolish.dev>
Keywords: ai,linter,ast,slop
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# 💎 CodePolish

[![CI](https://github.com/vikramkrishna1705-beep/CodePolish/actions/workflows/ci.yml/badge.svg)](https://github.com/vikramkrishna1705-beep/CodePolish/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/codepolish.svg)](https://badge.fury.io/py/codepolish)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

![CodePolish Demo](demo.gif)

**Detect AI-generated code anti-patterns in your Python codebase.** CodePolish is a powerful, extensible CLI tool designed to catch AI-specific bugs and hallucinations that traditional linters miss. It helps keep your Python code clean, safe, and free from cross-language leaks.

---

## 🤔 Why CodePolish Exists

Traditional linters (like Flake8, Pylint) are excellent at catching syntax and style issues. However, AI-generated code introduces new, unique failure patterns they weren't designed to detect:

- **Hallucinated imports:** Packages and functions that look real but don't exist in the environment.
- **Cross-language leakage:** JavaScript, Java, or Ruby syntax slipping into Python (e.g., `.push()`, `.length`, `.equals()`).
- **Placeholder code:** `pass`, `TODO`, and functions that do nothing.
- **Confident wrongness:** Code that looks structurally perfect but contains subtle anti-patterns (like mutable defaults).

CodePolish specifically targets these AI-driven anomalies before they hit production.

---

## 🎯 What It Catches

CodePolish evaluates code against four key axes of AI deficiencies:

| Axis | What It Detects | Examples |
|------|-----------------|----------|
| 📢 **Noise** | Debug artifacts, redundant or "hedging" comments | `print("here")`, `# increment x above x += 1` |
| 🤥 **Lies** | Hallucinations, placeholders, wrong state | `def process(): pass`, hallucinated packages, mutable defaults |
| 💀 **Soul** | Over-engineering, bad style | Deep nesting, god functions, overly complex logic |
| 🏗️ **Structure** | General Anti-patterns | Bare excepts, star imports, single-method classes |

---

## ⚡ Quick Start

```bash
pip install codepolish
codepolish check .
```

### Example Output

```text
                        CodePolish Anti-Patterns Found                         
+-----------------------------------------------------------------------------+
| File        | Line | Rule  | Severity | Description                | Points |
|-------------+------+-------+----------+----------------------------+--------|
| bad_code.py |    3 | AI002 | HIGH     | Hallucinated import:       |     25 |
|             |      |       |          | Module                     |        |
|             |      |       |          | 'hallucinated_module' not  |        |
|             |      |       |          | found in current           |        |
|             |      |       |          | environment.               |        |
| bad_code.py |    2 | JS001 | HIGH     | Possible cross-language    |     20 |
|             |      |       |          | Javascript leakage         |        |
|             |      |       |          | detected: 'push'           |        |
| bad_code.py |    1 | AI001 | CRITICAL | Mutable default argument   |     15 |
|             |      |       |          | detected. AI often makes   |        |
|             |      |       |          | this mistake. Use None     |        |
|             |      |       |          | instead.                   |        |
+-----------------------------------------------------------------------------+

Total Anti-Pattern Score: 60
Verdict: SLOPPY
```

---

## 🔍 Pattern Examples

### Critical Severity: AI's Favorite Mistake
```python
# 🚨 AI001: Mutable Default Argument
def process_items(items=[]):  # Bug: shared state between calls
    items.append(1)
    return items

# ✅ Fix: Use None and initialize inside
def process_items(items=None):
    if items is None:
        items = []
    items.append(1)
    return items
```

### High Severity: Cross-Language Leakage
```python
# 🚨 JS001: JavaScript syntax in Python
my_list = [1, 2, 3]
my_list.push(4) # AttributeError: 'list' object has no attribute 'push'

# ✅ Fix: Use standard Python
my_list.append(4)
```

---

## 🌐 Language Patterns Detected

LLMs are trained on code from many languages. When generating Python, they sometimes produce syntax patterns from other environments. CodePolish spots these cross-language leaks:

| Origin Language | Common AI Mistakes | The Python Fix |
|-----------------|--------------------|----------------|
| **JavaScript** | `.push()`, `.length`, `.forEach()` | `.append()`, `len()`, `for` loop |
| **Java** | `.equals()`, `.toString()`, `.isEmpty()` | `==`, `str()`, `not obj` |
| **Ruby** | `.each`, `.nil?`, `.first`, `.last` | `for` loop, `is None`, `[0]`, `[-1]` |
| **Go** | `fmt.Println()`, `nil` | `print()`, `None` |
| **C#** | `.Length`, `.Count`, `.ToLower()` | `len()`, `len()`, `.lower()` |
| **PHP** | `strlen()`, `array_push()`, `explode()` | `len()`, `.append()`, `.split()` |

---

## 🚫 What CodePolish Is Not

CodePolish does **not** replace:
- Human code review
- Traditional linters (Pylint, Flake8, Ruff)
- Type checkers (mypy, pyright)
- Security scanners (Bandit, Semgrep)

It is designed to seamlessly *complement* them by catching the unique patterns introduced by Large Language Models.

---

## 📦 Installation

You can install CodePolish locally using `pip`:

```bash
git clone https://github.com/vikramkrishna1705-beep/CodePolish.git
cd CodePolish
pip install -e .
```

---

## ⚙️ Configuration

You can configure CodePolish by adding a `[tool.codepolish]` section to your `pyproject.toml` file.

```toml
[tool.codepolish]
ignore_rules = ["JS001"]
exclude = ["tests/*", "venv/*", ".git/*"]
```

---

## 🪝 Pre-commit

To use CodePolish with [pre-commit](https://pre-commit.com/), add the following to your `.pre-commit-config.yaml` file:

```yaml
repos:
  - repo: https://github.com/vikramkrishna1705-beep/CodePolish
    rev: v0.1.0  # Use the latest version or commit hash
    hooks:
      - id: codepolish
```

---

## 🛡️ Built-in Rules

CodePolish currently ships with the following built-in detection rules:

| Rule ID | Rule Name | Description | Severity |
|---------|-----------|-------------|----------|
| **AI001** | `MutableDefaultsRule` | Detects dangerous mutable default arguments (e.g., `def func(x=[])`) often hallucinated by AI. | CRITICAL (15) |
| **JS001** | `JSLeakRule` | Detects JavaScript leakage in Python code (e.g., `.push()`, `.length`, `.forEach()`). | HIGH (20) |
| **AI002** | `HallucinatedImportRule` | Detects module imports that don't actually exist in the environment. | HIGH (25) |
| **BP001** | `BareExceptRule` | Detects dangerous bare `except:` clauses that can catch critical system exit signals. | HIGH (20) |

---

## 🧩 Adding Custom Rules

CodePolish uses a dynamic plugin architecture. To add a new rule:

1. Create a new file in `codepolish/rules/` starting with `rule_` (e.g., `rule_my_custom_check.py`).
2. Create a class that inherits from `BaseRule` and implements `ast.NodeVisitor` methods.

```python
import ast
from codepolish.rules import BaseRule

class MyCustomRule(BaseRule):
    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
        if node.name == "do_something_bad":
            self.record_issue(
                node=node,
                rule_id="CUST001",
                description="Found a bad function name.",
                points=10,
                severity="MEDIUM"
            )
        self.generic_visit(node)
```

CodePolish will automatically discover and run your new rule!

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome! 
Feel free to check the [issues page](https://github.com/vikramkrishna1705-beep/CodePolish/issues).

---

## 🙏 Acknowledgments

- **sloppylint**: Major inspiration for the concept of linting AI-generated slop.
- **KarpeSlop**: The original AI Slop Linter for TypeScript.
- **Andrej Karpathy's** commentary on AI-generated code quality.
- **Counterfeit Code** - MIT research on "looks right but doesn't work" patterns.

## 📝 License

This project is licensed under the MIT License.
