⚡ Quick Start

pip install sloppylint
sloppylint .

# Output:
# CRITICAL (2 issues)
# ============================================================
#   src/api.py:23  mutable_default_arg
#     Mutable default argument - use None instead
#     > def process(items=[]):
#
#   src/db.py:15  bare_except
#     Bare except catches everything including SystemExit
#     > except:
#
# SLOPPY INDEX
# ══════════════════════════════════════════════════
# Information Utility (Noise)    : 24 pts
# Information Quality (Lies)     : 105 pts
# Style / Taste (Soul)           : 31 pts
# Structural Issues              : 45 pts
# ──────────────────────────────────────────────────
# TOTAL SLOP SCORE               : 205 pts
#
# Verdict: SLOPPY

🤔 Why Sloppylint Exists

Traditional linters catch style and syntax issues. But AI-generated code introduces new failure patterns they weren't designed to detect:

• Hallucinated imports - packages and functions that don't exist
• Cross-language leakage - .push(), .equals(), .length in Python
• Placeholder code - pass, TODO, functions that do nothing
• Confident wrongness - code that looks right but fails at runtime

Sloppylint targets these AI-specific patterns that escape Pylint, Flake8, and code review.

🎯 What It Catches

The Three Axes of AI Slop

📥 What You Put In

# Scan a directory
sloppylint src/

# Scan specific files
sloppylint app.py utils.py

# Only high severity issues
sloppylint --severity high

# CI mode - exit 1 if issues found
sloppylint --ci --max-score 50

# Export JSON report
sloppylint --output report.json

📤 What You Get Out

🔍 Pattern Examples

Critical Severity

# 🚨 mutable_default_arg - AI's favorite mistake
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

# 🚨 bare_except - Catches SystemExit, KeyboardInterrupt
try:
    risky_operation()
except:  # Bug: swallows Ctrl+C!
    pass

# ✅ Fix: Catch specific exceptions
try:
    risky_operation()
except ValueError as e:
    logger.error(f"Invalid value: {e}")

High Severity

# 🚨 pass_placeholder - AI gave up
def validate_email(email):
    pass  # TODO: implement

# 🚨 hedging_comment - AI uncertainty
x = calculate()  # should work hopefully

💰 The Value

Why This Matters

Research Says

• 20% of AI package imports reference non-existent libraries — sloppylint catches these
• LLMs leak patterns from other languages they were trained on — sloppylint catches 100+ of these
• 66% of developers say AI code is "almost right" (the dangerous kind)

🛠️ CLI Commands

sloppylint .                    # 🔍 Scan current directory
sloppylint src/ tests/          # 📁 Scan multiple directories
sloppylint --severity high      # ⚡ Only critical/high issues
sloppylint --lenient            # 🎯 Same as --severity high
sloppylint --strict             # 🔬 Report everything
sloppylint --ci                 # 🚦 Exit 1 if any issues
sloppylint --max-score 50       # 📊 Exit 1 if score > 50
sloppylint --output report.json # 📋 Export JSON report
sloppylint --ignore "tests/*"   # 🚫 Exclude patterns
sloppylint --disable magic_number # ⏭️ Skip specific checks
sloppylint --version            # 📌 Show version

✅ Features

Language Patterns Detected

LLMs are trained on code from many languages. When generating Python, they sometimes produce patterns from other languages:

🚫 What Sloppylint Is Not

Sloppylint does not replace:

• Human code review
• Traditional linters (Pylint, Flake8, Ruff)
• Type checkers (mypy, pyright)
• Security scanners (Bandit, Semgrep)

It complements them by catching patterns these tools miss—patterns uniquely common in AI-generated code.

📦 Installation

# Install from PyPI
pip install sloppylint

# With colored output (recommended)
pip install sloppylint[rich]

# With all optional features
pip install sloppylint[all]

# Or install from source for development
git clone https://github.com/rsionnach/sloppylint.git
cd sloppylint
pip install -e ".[dev]"

⚙️ Configuration

Configure via pyproject.toml:

[tool.sloppy]
ignore = ["tests/*", "migrations/*"]
disable = ["magic_number", "debug_print"]
severity = "medium"
max-score = 100
ci = false
format = "detailed"  # or "compact" or "json"

🤝 Contributing

git clone https://github.com/rsionnach/sloppylint.git
cd sloppylint
pip install -e ".[dev]"
pytest tests/ -v  # 68 tests should pass

See AGENTS.md for coding conventions and pattern implementation guide.

📄 License

MIT

🙏 Acknowledgments

Inspiration

• KarpeSlop - The original AI Slop Linter for TypeScript
• Andrej Karpathy's commentary on AI-generated code quality

Research

• Counterfeit Code - MIT research on "looks right but doesn't work" patterns
• Package Hallucinations - USENIX study on hallucinated dependencies