Skip to content

README.md

Latest commit

 

History

History
370 lines (276 loc) · 10.9 KB

README.md

File metadata and controls

370 lines (276 loc) · 10.9 KB

🧊 Sober Coding

The hangover cure for vibe coding. Analyze AI-generated code quality, locate technical debt, and get actionable fixes.

GitHub stars License: MIT Language-Agnostic Claude Code

中文文档

Philosophy

Vibe coding is fast. Sober coding keeps it alive.

We're not against vibe coding. AI-generated code is the future.

But vibe coding has a fatal flaw: it creates technical debt 10x faster than humans.

Traditional tools (ESLint, SonarQube) catch human coding mistakes. AI-generated code has its own "smell" — duplication patterns, over-generation, missing edge cases, structural redundancy.

Sober Coding specifically targets these AI-native patterns, helping you clean up before technical debt spirals out of control.

The Problem

You vibe-coded a project with Cursor, Claude Code, or Copilot. It runs. But deep down, you know:

  • 🔴 Dead code everywhere — AI generated 5 versions, you kept the last one, the other 4 are still there
  • 🔴 Copy-paste hell — Same logic appears 3 times because AI rewrote it from scratch each time
  • 🔴 No error handling — Happy path is perfect, anything else crashes
  • 🔴 God files — 2000-line utils.py that does everything
  • 🔴 Dependency chaos — 47 packages installed, 12 actually used
  • 🔴 Security holes — Hardcoded secrets, SQL injection, path traversal
  • 🔴 Zero tests — "It works on my machine" is the only test

Sober Coding finds all of this, tells you what to fix first, and how.

Real-World Demo

Scanning a real vibe-coded full-stack project (Python + Vue.js, 50 files, 13k lines):

sober scan ./RedInk
🧊 Sober Coding v0.1.0 — Let's see what we're working with.

Scanning ./RedInk (50 files, 13,579 lines)

╭────────────────────────────────────────╮
│  SOBRIETY SCORE: 0/100  🔴 BLACKOUT  │
╰────────────────────────────────────────╯

  🟠 High (fix this week)
     ERR-001  Empty except block in backend/routes/config_routes.py:231
     ERR-001  Empty except block in backend/services/content.py:111
     ERR-001  Empty catch block in frontend/src/views/HistoryView.vue:189
     ... (7 total)

  🟡 Medium (fix this sprint)
     ARC-004  Deep nesting in backend/app.py:89
     DED-004  Unreachable code in backend/generators/google_genai.py:372
     DUP-001  Exact duplicate code block in backend/generators/image_api.py:68
     ARC-001  God file: backend/generators/google_genai.py (500+ lines)
     ERR-002  No error handling in backend/services/content.py:45
     ... (1,067 total)

  ⚪ Low (when you can)
     DUP-003  Structural clone detected in backend/generators/image_api.py:51
     DED-002  Unused import: Dict in backend/app.py:2
     ... (94 total)

  💊 Run `sober fix ERR-001` to get fix instructions

1,172 issues found. The top offenders:

Issue Count What it means
ARC-004 604 Deep nesting (>4 levels) — AI loves nested if/for/try
DED-004 226 Unreachable code after return/break
DUP-001 180 Exact duplicate code blocks across files
DUP-003 81 Same control-flow structure, different variable names
ERR-002 30 Async calls without error handling

This is what vibe coding looks like under the hood.

Fix Mode

Doesn't just point out problems — tells you how to fix them:

sober fix DUP-012
🔧 DUP-012: Near-duplicate code detected (89% similarity)

  File A: utils/parse.py:45-92
  File B: helpers/format.py:12-58

  WHY IT MATTERS:
  Fix a bug in one, the other still has it. AI didn't know it already wrote this.

  HOW TO FIX:
  1. Extract shared logic into a single function
  2. Both files import from the shared module
  3. Delete the duplicate

  SUGGESTED REFACTOR:
  ┌─ shared/text_utils.py (new) ─────────────────┐
  │ def normalize_text(raw: str) -> str:          │
  │     """Merge of parse.py:45-92 & format.py""" │
  │     ...                                        │
  └────────────────────────────────────────────────┘

  AUTO-FIX AVAILABLE: sober fix DUP-012 --apply

Install

# npm (recommended)
npm install -g sober-coding

# pip
pip install sober-coding

# From source
git clone https://github.com/voidborne-d/sober-coding.git
cd sober-coding && npm link

# Claude Code Skill
npx skills add https://github.com/voidborne-d/sober-coding.git

# ClawHub
clawhub install sober-coding

Zero config. Zero API keys. Runs 100% locally.

Claude Code

Copy slash commands into your project:

cp sober-coding/claude-code/*.md YOUR_PROJECT/.claude/commands/

Then use directly:

/sober-scan              # Full project scan
/sober-fix DUP-012       # Get fix instructions
/sober-report            # Generate HTML report
/sober-watch             # Watch mode — scan on every save

What It Checks

🔒 Security

ID Check Description
SEC-001 Hardcoded secrets API keys, passwords, tokens in source code
SEC-002 SQL injection String concatenation in SQL queries
SEC-003 Path traversal User input directly in file paths
SEC-004 Insecure dependencies Known vulnerable dependency versions
SEC-005 CORS misconfiguration Access-Control-Allow-Origin: *

🏗️ Architecture

ID Check Description
ARC-001 God files Single file exceeding 500 lines
ARC-002 Circular dependencies Circular imports between modules
ARC-003 Mixed concerns API + DB + business logic in one file
ARC-004 Deep nesting More than 4 levels of indentation
ARC-005 Spaghetti imports Import graph entropy

🔄 Duplication

ID Check Description
DUP-001 Exact clones Identical code blocks
DUP-002 Near clones High similarity (>70%), classic AI behavior
DUP-003 Structural clones Same structure, different variable names

⚠️ Error Handling

ID Check Description
ERR-001 Empty catch blocks catch (e) {} swallowing all errors
ERR-002 No error handling Async calls without try-catch
ERR-003 Generic catches Single top-level catch for everything
ERR-004 Missing input validation User input without validation

📦 Dependencies

ID Check Description
DEP-001 Unused dependencies Listed in manifest but never imported
DEP-002 Duplicate functionality lodash AND underscore installed
DEP-003 Outdated versions Major dependencies 2+ versions behind

🧪 Testing

ID Check Description
TST-001 No tests Zero test files found
TST-002 Low coverage Test coverage below threshold
TST-003 No edge cases Only happy path tested

💀 Dead Code

ID Check Description
DED-001 Unused functions Defined but never called
DED-002 Unused imports Imported but never used
DED-003 Commented-out code Large blocks of commented code
DED-004 Unreachable code Code after return/break

Scoring

Score Level Meaning
80-100 🟢 SOBER Clean, maintainable code. Ship it.
60-79 🟡 TIPSY Some issues. Fix before it gets worse.
40-59 🟠 HUNGOVER Significant debt. Needs a cleanup sprint.
0-39 🔴 BLACKOUT Critical issues. Stop building, start fixing.

Each dimension scores 0-10, weighted into the overall score. Weights are configurable.

Supported Languages

Language Scan Fix Auto-Fix
JavaScript / TypeScript ✅ ✅ ✅
Python ✅ ✅ ✅
Go ✅ ✅ 🔜
Rust ✅ ✅ 🔜
Java ✅ ✅ 🔜
Ruby ✅ 🔜 🔜
PHP ✅ 🔜 🔜
C/C++ ✅ 🔜 🔜

Language-agnostic checks (duplication, dead code, dependencies, security) work for all languages.

Config

Zero config to start. Customize with .soberrc.json in your project root:

{
  "thresholds": {
    "god_file_lines": 500,
    "max_nesting": 4,
    "min_test_coverage": 60,
    "duplication_similarity": 70
  },
  "ignore": [
    "node_modules",
    "dist",
    "*.generated.*"
  ],
  "weights": {
    "security": 2.0,
    "architecture": 1.5,
    "duplication": 1.0,
    "error_handling": 1.5,
    "dependencies": 0.8,
    "testing": 1.2,
    "dead_code": 0.8
  },
  "severity": "medium"
}

CI/CD Integration

# GitHub Actions
- name: Sober Check
  run: npx sober-coding scan . --ci --fail-on=critical
# GitLab CI
sober-check:
  script:
    - npx sober-coding scan . --ci --fail-on=high
  allow_failure: false

CI mode outputs SARIF format, compatible with GitHub Code Scanning.

vs. Others

Sober Coding pyscn ESLint/Ruff SonarQube
Built for vibe coding ✅ ✅ ❌ ❌
Language-agnostic ✅ ❌ Python only ❌ per-language ✅
Debt scoring ✅ 0-100 ✅ ❌ ✅
AI pattern detection ✅ ✅ ❌ ❌
Fix suggestions ✅ with code ❌ ❌ partial
Auto-fix ✅ --apply ❌ partial ❌
Zero config ✅ ✅ ❌ ❌
Runs locally ✅ ✅ ✅ ❌ server
Claude Code integration ✅ ❌ ❌ ❌
Free ✅ ✅ ✅ ⚠️ freemium

Roadmap

  • Core scanner engine
  • Security checks (SEC-001~005)
  • Architecture checks (ARC-001~005)
  • Duplication detection (DUP-001~003)
  • Error handling checks (ERR-001~004)
  • Dependency checks (DEP-001~003)
  • Testing checks (TST-001~003)
  • Dead code detection (DED-001~004)
  • CLI with scoring
  • Fix suggestions (sober fix <ID>)
  • .soberrc.json config support
  • CI mode (--ci, --fail-on)
  • Auto-fix engine (--apply)
  • HTML/PDF report generation
  • VS Code extension
  • GitHub Action (marketplace)
  • Watch mode (scan on save)
  • AI pattern fingerprinting (detect which AI generated the code)
  • Team dashboard

Star History

Star History Chart

Contributing

PRs welcome. See CONTRIBUTING.md.

License

MIT — Use it, fork it, ship it. Free forever.