python-vibe-guard 0.7.1__py3-none-any.whl

python_vibe_guard-0.7.1.dist-info/METADATA

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: python-vibe-guard
+Version: 0.7.1
+Summary: Runtime anti-pattern scanner for async Python — detects what AI-generated code gets wrong
+License: MIT
+Keywords: async,linter,fastapi,asyncio,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# python-vibe-guard
+
+[![tests](https://github.com/Joaquinriosheredia/python-vibe-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/Joaquinriosheredia/python-vibe-guard/actions/workflows/ci.yml)
+
+## The incident
+
+A FastAPI service that handled 50 concurrent requests in staging started timing out in production at 200 rps. The team spent two days adding replicas, tweaking Gunicorn workers, and profiling CPU — nothing helped. The p99 latency was 8 seconds for an endpoint that should take 80ms.
+
+> Scenario based on a common pattern observed in async Python codebases.
+> Reproduced in controlled testing with locust against a FastAPI service.
+
+Root cause: one engineer had asked an AI assistant to "add a retry with backoff" to an async handler. The AI generated `time.sleep(2)` inside the `async def`. In staging with a handful of requests it was invisible. In production it froze the entire event loop for 2 seconds per request, serializing all 200 concurrent calls through a single bottleneck.
+
+The code passed every unit test. It passed the integration tests. It shipped to production in a Friday deploy.
+
+**python-vibe-guard catches this in CI before it reaches staging.**
+
+---
+
+## What it detects
+
+Twenty patterns that AI models generate repeatedly, that pass all static checks, and that silently destroy async performance under real load:
+
+### A. Event Loop Blocking
+
+Synchronous calls inside `async def` — each stalls the event loop for its entire duration, serializing all concurrent requests.
+
+| Rule | Pattern | Gate | Runtime effect |
+|------|---------|------|----------------|
+| PYVIBE-001 | `time.sleep()` inside `async def` | `async def` | Freezes entire event loop for sleep duration |
+| PYVIBE-002 | `requests.*` inside `async def` | `async def` | Blocks OS thread, serializes all concurrent I/O |
+| PYVIBE-007 | `subprocess.run/call/check_output/Popen` inside `async def` | `async def` | Blocks OS thread for entire subprocess duration |
+| PYVIBE-008 | `sqlite3.connect()` inside `async def` | `async def` | Synchronous file I/O blocks the event loop |
+| PYVIBE-009 | `open()` builtin inside `async def` | `async def` | Synchronous file I/O blocks the event loop |
+| PYVIBE-010 | `httpx.get/post/put/…` inside `async def` | `async def` | httpx sync API blocks OS thread for full HTTP round-trip |
+| PYVIBE-011 | `os.system/popen/waitpid` inside `async def` | `async def` | Blocking OS calls with no direct async equivalent |
+| PYVIBE-016 | `httpx.Client()` instantiated inside `async def` | `async def` | Sync client blocks OS thread per request; `httpx.AsyncClient()` is excluded |
+
+### B. Async Lifecycle Misuse
+
+Incorrect use of asyncio primitives that raise `RuntimeError` at runtime or silently discard tasks mid-execution.
+
+| Rule | Pattern | Gate | Runtime effect |
+|------|---------|------|----------------|
+| PYVIBE-003 | `asyncio.run()` inside `async def` | `async def` | `RuntimeError: This event loop is already running` |
+| PYVIBE-012 | `asyncio.create_task()` with discarded return value | `async def` | Task GC'd mid-execution; exceptions silently swallowed |
+| PYVIBE-013 | `asyncio.gather()` without `return_exceptions=True` | `async def` | First exception leaks remaining tasks; no per-task error handling |
+| PYVIBE-014 | `asyncio.ensure_future()` with discarded return value | `async def` | Same GC hazard as PYVIBE-012; pre-3.7 API still common in older codebases |
+| PYVIBE-015 | `loop.run_until_complete()` inside `async def` | `async def` | `RuntimeError: This event loop is already running` |
+
+### C. Concurrency & State Hazards
+
+Patterns that introduce data races, swallowed errors, or runaway loops under concurrent async load.
+
+| Rule | Pattern | Gate | Runtime effect |
+|------|---------|------|----------------|
+| PYVIBE-004 | `threading.Lock/RLock/…` inside `async def` | `async def` | Blocks event loop under contention |
+| PYVIBE-005 | `@app.task` / `@shared_task` without `soft_time_limit` or `time_limit` | decorator | Worker hangs forever if external call never returns |
+| PYVIBE-006 | `ContextVar.set()` inside `async def` without `try/finally reset()` | `async def` | Context leaks into sibling async tasks |
+| PYVIBE-017 | `except Exception: pass` / bare `except: pass` (empty body) | any | Swallows all errors silently; bare except also catches `KeyboardInterrupt`/`SystemExit` |
+| PYVIBE-018 | `while True:` inside `async def` with no `await` in body | `async def` | Event loop blocked indefinitely; CPU hits 100% |
+| PYVIBE-019 | retry `for`/`while` loop in `async def` with no backoff in `except` | `async def` | Tight retry loop on failure: thousands of failed requests/sec, cascading failures |
+| PYVIBE-020 | `put_nowait()` without `asyncio.QueueFull` handler | any | `QueueFull` propagates unhandled; item is silently lost on bounded queues |
+
+**Severity notes:**
+- PYVIBE-005: `CRITICAL` — checks per-task decorator arguments only. **If your project sets a global `task_time_limit` via `app.conf.task_time_limit`, `app.conf.update(...)`, or in `celeryconfig.py` / `settings.py`, tasks already covered by that global limit will still be flagged.** Add per-task limits (self-documenting, immune to config drift) or suppress with `# noqa: PYVIBE-005`.
+- PYVIBE-009: `CRITICAL` in production files; automatically downgraded to `WARNING` in test files (`test_*.py`, `*_test.py`, `tests/`). **Context matters:** `open()` in a hot-path request handler blocks all concurrent coroutines (CRITICAL); `open()` in a startup/lifespan function runs before requests are served and has zero practical impact. The rule cannot distinguish these contexts via AST — if you use `open()` in an `async def` lifespan or one-time initializer, the idiomatic fix is to use plain `def` instead (FastAPI's own docs do this), which avoids the flag entirely.
+- PYVIBE-017: bare `except` → `CRITICAL` (catches `KeyboardInterrupt`/`SystemExit`); `except Exception` with empty body → `WARNING`. Specific exceptions (`except ValueError: pass`) are not flagged.
+- PYVIBE-013 in test files: automatically downgraded to `WARNING` in files matching `test_*.py`, `*_test.py`, or paths under `tests/` — exceptions should propagate for assertions in test code.
+- PYVIBE-019: `WARNING` — flags `except` that ends with `continue` or is solely `pass` with no sleep/backoff call. Suppressed when an escalation pattern (`if … : raise/break`) is present.
+- PYVIBE-020: `WARNING` — fires in any function context (sync and async). Suppressed when the `put_nowait()` is inside a `try` whose handlers include `asyncio.QueueFull`, `QueueFull`, bare `except`, or `Exception`.
+
+---
+
+## Validation
+
+### 100-repo sweep (automated, v0.7.0)
+
+Automated scan of 100 GitHub repos (`stars:>100`, updated last year, async Python keywords). Script: [`validation/run_massive_scan.py`](validation/run_massive_scan.py).
+
+| Metric | Value |
+|--------|-------|
+| Repos scanned | 100 |
+| .py files | 64,335 |
+| Total violations | 3,639 |
+
+**Rule prevalence (top 10):**
+
+| Rule | Hits | Repos affected | % of repos |
+|------|------|----------------|-----------|
+| PYVIBE-017 `except Exception: pass` | 999 | 57 | **57%** |
+| PYVIBE-013 `gather()` no return_exceptions | 766 | 47 | **47%** |
+| PYVIBE-019 retry loop no backoff | 408 | 43 | **43%** |
+| PYVIBE-009 `open()` in async def | 178 | 33 | **33%** |
+| PYVIBE-005 `@task` no time_limit | 882 | 15 | 15% |
+| PYVIBE-001 `time.sleep` in async | 55 | 16 | 16% |
+| PYVIBE-012 orphaned `create_task()` | 58 | 13 | 13% |
+| PYVIBE-008 `sqlite3` in async def | 121 | 10 | 10% |
+| PYVIBE-018 `while True` no await | 36 | 10 | 10% |
+| PYVIBE-006 ContextVar no reset | 19 | 10 | 10% |
+
+Full data: [`validation/aggregate.json`](validation/aggregate.json) · [`validation/massive-results.md`](validation/massive-results.md)
+
+### Reference scan — 4 repos (reproducible)
+
+| Repo | .py files | Violations |
+|------|-----------|-----------|
+| [fastapi/fastapi](https://github.com/tiangolo/fastapi) | 1 121 | 5 |
+| [celery/celery](https://github.com/celery/celery) | 416 | 363 |
+| [aio-libs/aiohttp](https://github.com/aio-libs/aiohttp) | 164 | 29 |
+| [encode/httpx](https://github.com/encode/httpx) | 60 | 0 |
+| **Total** | **1 761** | **397** |
+
+Raw data: [`validation/breakdown.json`](validation/breakdown.json)
+
+**Notable findings:**
+
+- **home-assistant/core** — 418 violations across 17,702 files; 331 PYVIBE-013, 21 PYVIBE-018.
+- **Celery** — 352 tasks without `time_limit`; workers can hang indefinitely on broker timeouts.
+- **aiortc, anyio, uvicorn** — `while True` loops without `await` in production async I/O code (PYVIBE-018, 29 confirmed real hits after async-generator FP fix).
+- **aiohttp examples** — `open()` in async WebSocket handlers; synchronous I/O in production-facing code.
+
+---
+
+## Installation
+
+```bash
+pip install python-vibe-guard
+```
+
+Or run without installing:
+
+```bash
+pip install -e .
+```
+
+---
+
+## Usage
+
+```bash
+# Scan a file
+python -m pyvibe path/to/file.py
+
+# Scan a directory recursively
+python -m pyvibe src/
+
+# JSON output for CI/CD pipelines
+python -m pyvibe src/ --json
+
+# Exclude directories (adds to built-in defaults: venv, .venv, __pycache__, …)
+python -m pyvibe src/ --exclude tests
+
+# Exit code: 0 = clean, 1 = violations found, 2 = path error
+```
+
+### Example output
+
+```
+  python-vibe-guard
+  ─────────────────────────────────────────────
+
+  demo/bad_async.py
+
+  [CRITICAL] [PYVIBE-001] — line 14
+     Function : process_order()
+     Problem  : time.sleep() blocks the entire event loop
+     Fix      : Use `await asyncio.sleep(n)` instead
+
+  [CRITICAL] [PYVIBE-002] — line 20
+     Function : fetch_user()
+     Problem  : requests.get() is synchronous — blocks the event loop
+     Fix      : Use `async with httpx.AsyncClient() as c: await c.get(url)`
+
+  [CRITICAL] [PYVIBE-003] — line 26
+     Function : orchestrate()
+     Problem  : asyncio.run() inside async def raises RuntimeError at runtime
+     Fix      : Use `await coroutine()` directly — asyncio.run() is for sync entrypoints only
+
+  [CRITICAL] [PYVIBE-004] — line 32
+     Function : update_counter()
+     Problem  : threading.Lock() blocks the event loop under contention
+     Fix      : Use `asyncio.Lock()` with `async with lock:` instead
+
+  ─────────────────────────────────────────────
+  4 violation(s) in 1 file(s)
+```
+
+---
+
+## CI/CD integration
+
+Add to your GitHub Actions workflow:
+
+```yaml
+- name: python-vibe-guard scan
+  run: |
+    pip install python-vibe-guard
+    python -m pyvibe src/ --json
+```
+
+The scanner exits with code `1` when violations are found, failing the CI job.
+
+---
+
+## Pre-commit integration
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/Joaquinriosheredia/python-vibe-guard
+    rev: v0.7.0
+    hooks:
+      - id: python-vibe-guard
+```
+
+Then install the hook:
+
+```bash
+pre-commit install
+```
+
+The hook runs on every `git commit`, scans all Python files in the project, and blocks the commit if any violations are found.
+
+---
+
+## Design
+
+- **Pure AST, zero runtime dependencies** — uses only Python's built-in `ast` module
+- **Each rule is an independent `ast.NodeVisitor`** — easy to add, disable, or extend
+- **Gate on `async def`** — most rules check `_current_async_func` before firing; PYVIBE-017 (silent except) fires in any function context
+- **No import resolution** — works on any Python file without installing its dependencies
+- **Test-aware severity** — PYVIBE-013 is automatically downgraded to WARNING in test files
+
+---
+
+## Run the demo
+
+```bash
+python -m pyvibe demo/bad_async.py
+```
+
+Expected: 20 findings (17 CRITICAL + 3 WARNING for PYVIBE-017 `except Exception`, PYVIBE-019 retry without backoff, and PYVIBE-020 `put_nowait` without handler), one per rule. `demo/bad_async.py` also contains a sync function that mirrors the async-specific patterns — those produce zero findings.
+
+---
+
+## Run the tests
+
+```bash
+python -m pytest tests/ -v
+# or
+python tests/test_rules.py
+```
+
+123 tests: true positives + false-positive guards for every rule.
+
+---
+
+## Ecosystem
+
+This project is part of the **vibe-guard** family of runtime anti-pattern scanners:
+
+- [java-vibe-guard](https://github.com/jouninno/java-vibe-guard) — Spring Boot / async Java (blocking Kafka, @Transactional + Virtual Threads)
+- **python-vibe-guard** — FastAPI / asyncio (this project)
+
+---
+
+## License
+
+MIT

python_vibe_guard-0.7.1.dist-info/RECORD

@@ -0,0 +1,31 @@
+pyvibe/__init__.py,sha256=RaANGbRu5e-vehwXI1-Qe2ggPPfs1TQaZj072JdbLk4,22
+pyvibe/__main__.py,sha256=pHY5xMbHOrlR3yByOHZAONVsv7p3V_7nBGGrQ5pzRv0,36
+pyvibe/analyzer.py,sha256=DY9pvWuKY8ITxERQM9AUY5m6joKf-1A5tCpKycJp94Y,5851
+pyvibe/cli.py,sha256=3xd5cCrXgIRQlRNB6QjIxKnHvVyqwaInnHeNuwHAjOM,4832
+pyvibe/rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyvibe/rules/async_requests.py,sha256=9Z3Hj5Ic-BqlqyVffHxkAW8_RcT97H0jkj6L7BurJ54,2463
+pyvibe/rules/async_sleep.py,sha256=puUEjX7y2HT7X8a2MMTBhEQK9M1IywI1RNB36zD9V10,1459
+pyvibe/rules/asyncio_run.py,sha256=UvNKWW0yaLkRdC2yr_zEvBAgz9jEGB-lv7p2rYOCrQs,1649
+pyvibe/rules/base.py,sha256=kdzLvia9wgECAIYFcMqlxwTQumZFTQyIokMMAYeKFuE,2424
+pyvibe/rules/celery_time_limit.py,sha256=mauGXJm6iSzMyih1P-4XNFkbMUD31TJkKcCUyNCzNRc,4864
+pyvibe/rules/contextvar_cleanup.py,sha256=bQF9NITk4UpZUzwGZsb1Pty7B55Xqzqj88zRTUeVvLI,5478
+pyvibe/rules/create_task_orphan.py,sha256=d3kTOypIbPgJHWVt7BIJQTi3IPEgs74e3l92EEpjw3g,1884
+pyvibe/rules/ensure_future_orphan.py,sha256=T9_bxaKh-yxMFzdgK5cyNfbUnv_FdLAMH4hZ-hlmDLE,1809
+pyvibe/rules/gather_no_return_exceptions.py,sha256=-330iwoBgQmxJpFjc7VTVa2pNX0ngqdS2LsibiX0qwQ,2311
+pyvibe/rules/httpx_client_sync.py,sha256=JuB0B_33V4ebsvDtjd3TccyUKwhkCiWWSq6g_I20jYI,1671
+pyvibe/rules/httpx_sync.py,sha256=rJsrkVCGR1gDfIR77KsgWP-9mDMj83RyLut40sV9LvQ,1849
+pyvibe/rules/loop_run_until_complete.py,sha256=f1DY1cuqAQ0Lrlra_-BHuk3Zyro36OgC_P0_K9Y2NXY,1571
+pyvibe/rules/open_async.py,sha256=4PQ-Qc1PALp-cOBqSxxFUgxLb0u8uXYLSKYnOFaZ1Qw,1432
+pyvibe/rules/os_blocking.py,sha256=vSxQXwnv0sHIfWjjm3l1Vev7Ju3epqk61sBN2Q6iH84,1688
+pyvibe/rules/queue_put_nowait.py,sha256=hxOkxSczLFqZsWGYGoFAiQwZcC13qp1LRwmyJDnV6TQ,3813
+pyvibe/rules/retry_no_backoff.py,sha256=W9Ckm1rijRP91bigZazVfJTALX7DHidSTATHRBwpIHk,10077
+pyvibe/rules/silent_except.py,sha256=C8Xmhg2M9oZa_yMDTICFTn4BXEBCZyr7BHxy03cmWDw,3623
+pyvibe/rules/sqlite_async.py,sha256=FlgCwgEscFrQ6M4mJPcOHRSSfRGb0v4h-iXgW-Mif58,3242
+pyvibe/rules/subprocess_async.py,sha256=K-Bt-QFSNH_-KvCnDuB_z7yBf6RwTV1bbyaP5t9rzK4,2001
+pyvibe/rules/threading_lock.py,sha256=Qf947NaTfdys4pqwb5DMB8O9aNgtC3QaN_20ukwa8Yk,3621
+pyvibe/rules/while_true_no_await.py,sha256=bHV7Quf2_1kNu_pFOMjt-AbQkBW8-ue3uwd6qDHtoFE,4366
+python_vibe_guard-0.7.1.dist-info/METADATA,sha256=GvTxw7r3tnRnMZn2KxCtP7EuyY2RNcand8WDX7Ed0vQ,13154
+python_vibe_guard-0.7.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_vibe_guard-0.7.1.dist-info/entry_points.txt,sha256=ASoyE-lbzauH_Ow-_tgfXHl1EJ5ANP0eHpgfq-dDNbQ,43
+python_vibe_guard-0.7.1.dist-info/top_level.txt,sha256=5yep6lXEG4duf4CyVYiCK9c_9p3iBBnkFjqgxr0t2iw,7
+python_vibe_guard-0.7.1.dist-info/RECORD,,

python_vibe_guard-0.7.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_vibe_guard-0.7.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyvibe = pyvibe.cli:main

python_vibe_guard-0.7.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyvibe

pyvibe/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.7.0"

pyvibe/__main__.py

@@ -0,0 +1,3 @@
+from pyvibe.cli import main
+
+main()

pyvibe/analyzer.py

@@ -0,0 +1,163 @@
+import ast
+from pathlib import Path
+from typing import FrozenSet, List
+
+from pyvibe.rules.base import Violation
+from pyvibe.rules.async_sleep import AsyncSleepRule
+from pyvibe.rules.async_requests import AsyncRequestsRule
+from pyvibe.rules.asyncio_run import AsyncioRunRule
+from pyvibe.rules.threading_lock import ThreadingLockRule
+from pyvibe.rules.contextvar_cleanup import ContextVarCleanupRule
+from pyvibe.rules.celery_time_limit import CeleryTaskTimeLimitRule
+from pyvibe.rules.subprocess_async import SubprocessAsyncRule
+from pyvibe.rules.sqlite_async import SqliteAsyncRule
+from pyvibe.rules.open_async import OpenAsyncRule
+from pyvibe.rules.httpx_sync import HttpxSyncRule
+from pyvibe.rules.os_blocking import OsBlockingRule
+from pyvibe.rules.create_task_orphan import CreateTaskOrphanRule
+from pyvibe.rules.gather_no_return_exceptions import GatherNoReturnExceptionsRule
+from pyvibe.rules.ensure_future_orphan import EnsureFutureOrphanRule
+from pyvibe.rules.loop_run_until_complete import LoopRunUntilCompleteRule
+from pyvibe.rules.httpx_client_sync import HttpxClientSyncRule
+from pyvibe.rules.silent_except import SilentExceptRule
+from pyvibe.rules.while_true_no_await import WhileTrueNoAwaitRule
+from pyvibe.rules.retry_no_backoff import RetryNoBackoffRule
+from pyvibe.rules.queue_put_nowait import QueuePutNowaitRule
+
+ALL_RULES = [
+    AsyncSleepRule,
+    AsyncRequestsRule,
+    AsyncioRunRule,
+    ThreadingLockRule,
+    CeleryTaskTimeLimitRule,
+    SubprocessAsyncRule,
+    SqliteAsyncRule,
+    OpenAsyncRule,
+    HttpxSyncRule,
+    OsBlockingRule,
+    ContextVarCleanupRule,
+    CreateTaskOrphanRule,
+    GatherNoReturnExceptionsRule,
+    EnsureFutureOrphanRule,
+    LoopRunUntilCompleteRule,
+    HttpxClientSyncRule,
+    SilentExceptRule,
+    WhileTrueNoAwaitRule,
+    RetryNoBackoffRule,
+    QueuePutNowaitRule,
+]
+
+ALL_RULE_IDS: FrozenSet[str] = frozenset(r.RULE_ID for r in ALL_RULES)
+
+# Rules downgraded CRITICAL → WARNING when the violation is inside a test file.
+# time.sleep in fixtures, subprocess in service-startup helpers, open() in
+# async test helpers (e.g. asyncssh, aiofiles own test suites), and Celery task
+# fixtures in test suites (e.g. celery/t/) that intentionally omit time_limit.
+TEST_FILE_DOWNGRADE: FrozenSet[str] = frozenset({
+    "PYVIBE-001",  # time.sleep — valid in timing tests
+    "PYVIBE-005",  # celery task — fixtures intentionally omit time_limit
+    "PYVIBE-006",  # ContextVar.set — test subjects verifying propagation
+    "PYVIBE-007",  # subprocess.run — launching test servers/processes
+    "PYVIBE-008",  # sqlite3.connect — smoke tests using real sqlite
+    "PYVIBE-009",  # open() — test helpers, aiofiles own test suite
+    "PYVIBE-012",  # create_task orphan — concurrent setup in tests
+    "PYVIBE-013",  # gather no return_exceptions — test stubs
+    "PYVIBE-014",  # ensure_future orphan — concurrent setup in tests
+    "PYVIBE-016",  # httpx.Client sync — test transport fixtures
+})
+
+
+def _is_test_file(filepath: str) -> bool:
+    p = Path(filepath)
+    name = p.name
+    parts = p.parts
+    return (
+        name.startswith("test_")
+        or name.endswith("_test.py")
+        or "tests" in parts
+        or "test" in parts
+    )
+
+
+def analyze_source(
+    source: str,
+    filepath: str = "<string>",
+    *,
+    downgrade_in_tests: FrozenSet[str] = TEST_FILE_DOWNGRADE,
+) -> List[Violation]:
+    """Parse source and run all rules. Returns list of violations.
+
+    downgrade_in_tests: rule IDs whose severity is lowered to WARNING when
+    the file is detected as a test file. Pass frozenset() to disable all
+    downgrading, or ALL_RULE_IDS to downgrade every rule.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    source_lines = source.splitlines()
+    violations = []
+    for RuleClass in ALL_RULES:
+        if RuleClass is SilentExceptRule:
+            visitor = RuleClass(source_lines)
+        else:
+            visitor = RuleClass()
+        visitor.visit(tree)
+        violations.extend(visitor.violations)
+
+    if downgrade_in_tests and _is_test_file(filepath):
+        for v in violations:
+            if v.rule_id in downgrade_in_tests:
+                v.severity = "WARNING"
+
+    violations.sort(key=lambda v: v.line)
+    return violations
+
+
+def analyze_file(
+    path: Path,
+    *,
+    downgrade_in_tests: FrozenSet[str] = TEST_FILE_DOWNGRADE,
+) -> List[Violation]:
+    source = path.read_text(encoding="utf-8", errors="ignore")
+    return analyze_source(source, filepath=str(path), downgrade_in_tests=downgrade_in_tests)
+
+
+DEFAULT_EXCLUDES = frozenset({
+    "venv", ".venv", "env", "__pycache__", ".git",
+    "node_modules", ".tox", "dist", "build", ".eggs",
+})
+
+
+def analyze_directory(
+    root: Path,
+    exclude: frozenset = DEFAULT_EXCLUDES,
+    *,
+    skip_test_files: bool = False,
+    downgrade_in_tests: FrozenSet[str] = TEST_FILE_DOWNGRADE,
+) -> dict:
+    """Walk directory and analyze all .py files. Returns {path: [violations]}.
+
+    Directories whose *name* appears in `exclude` are skipped entirely.
+    skip_test_files: if True, files matching test_*.py / *_test.py / tests/* are
+    omitted from results entirely rather than downgraded.
+    """
+    results = {}
+    for py_file in _walk(root, exclude):
+        if skip_test_files and _is_test_file(str(py_file)):
+            continue
+        violations = analyze_file(py_file, downgrade_in_tests=downgrade_in_tests)
+        if violations:
+            results[py_file] = violations
+    return results
+
+
+def _walk(root: Path, exclude: frozenset):
+    """Yield .py files under root, skipping any directory in exclude."""
+    for entry in sorted(root.iterdir()):
+        if entry.is_dir():
+            if entry.name not in exclude:
+                yield from _walk(entry, exclude)
+        elif entry.suffix == ".py":
+            yield entry

pyvibe/cli.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+python-vibe-guard — runtime anti-pattern scanner for async Python
+
+Usage:
+    python -m pyvibe <path>                   # file or directory
+    python -m pyvibe <path> --json            # machine-readable output
+    python -m pyvibe <path> --no-test-files   # skip test files entirely
+    python -m pyvibe <path> --downgrade-in-tests  # WARNING instead of CRITICAL in all test files
+"""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from pyvibe import __version__
+from pyvibe.analyzer import (
+    analyze_file,
+    analyze_directory,
+    DEFAULT_EXCLUDES,
+    ALL_RULE_IDS,
+    TEST_FILE_DOWNGRADE,
+    _is_test_file,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="pyvibe",
+        description="Detect runtime anti-patterns in async Python code",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("path", help="File or directory to scan")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    parser.add_argument(
+        "--exclude",
+        metavar="DIR",
+        action="append",
+        default=[],
+        help=(
+            "Directory name to exclude (can be repeated). "
+            "Added on top of the built-in defaults: "
+            + ", ".join(sorted(DEFAULT_EXCLUDES))
+        ),
+    )
+    parser.add_argument(
+        "--no-test-files",
+        action="store_true",
+        help=(
+            "Exclude test files from the scan entirely "
+            "(files matching test_*.py, *_test.py, or under tests/ / test/)"
+        ),
+    )
+    parser.add_argument(
+        "--downgrade-in-tests",
+        action="store_true",
+        help=(
+            "Downgrade ALL violations in test files from CRITICAL to WARNING. "
+            "Default: only PYVIBE-001, PYVIBE-007, and PYVIBE-013 are downgraded."
+        ),
+    )
+    args = parser.parse_args()
+
+    target = Path(args.path)
+    if not target.exists():
+        print(f"Error: {target} does not exist", file=sys.stderr)
+        sys.exit(2)
+
+    exclude = DEFAULT_EXCLUDES | frozenset(args.exclude)
+
+    # Resolve test-file handling flags (mutually exclusive in effect)
+    if args.no_test_files:
+        skip_test_files = True
+        downgrade_in_tests = frozenset()
+    elif args.downgrade_in_tests:
+        skip_test_files = False
+        downgrade_in_tests = ALL_RULE_IDS
+    else:
+        skip_test_files = False
+        downgrade_in_tests = TEST_FILE_DOWNGRADE
+
+    if target.is_file():
+        if target.suffix != ".py":
+            file_results = {}
+        elif skip_test_files and _is_test_file(str(target)):
+            file_results = {}
+        else:
+            file_results = {target: analyze_file(target, downgrade_in_tests=downgrade_in_tests)}
+    else:
+        file_results = analyze_directory(
+            target,
+            exclude=exclude,
+            skip_test_files=skip_test_files,
+            downgrade_in_tests=downgrade_in_tests,
+        )
+
+    total_violations = sum(len(v) for v in file_results.values())
+    total_files = sum(1 for v in file_results.values() if v)
+
+    if args.json:
+        output = []
+        for path, violations in file_results.items():
+            for v in violations:
+                output.append({
+                    "file": str(path),
+                    "rule": v.rule_id,
+                    "severity": v.severity,
+                    "line": v.line,
+                    "function": v.function_name,
+                    "message": v.message,
+                    "evidence": v.evidence,
+                })
+        print(json.dumps(output, indent=2))
+    else:
+        _print_human(file_results, total_violations, total_files)
+
+    sys.exit(1 if total_violations > 0 else 0)
+
+
+def _print_human(file_results: dict, total_violations: int, total_files: int):
+    print()
+    print("  python-vibe-guard")
+    print("  ─────────────────────────────────────────────")
+    print()
+
+    if not file_results:
+        print("  No violations found\n")
+        return
+
+    for path, violations in file_results.items():
+        if not violations:
+            continue
+        print(f"  {path}")
+        print()
+        for v in violations:
+            print(f"  [{v.severity}] [{v.rule_id}] — line {v.line}")
+            print(f"     Function : {v.function_name}()")
+            print(f"     Problem  : {v.message}")
+            print(f"     Fix      : {v.evidence}")
+            print()
+
+    print("  ─────────────────────────────────────────────")
+    print(f"  {total_violations} violation(s) in {total_files} file(s)")
+    print()
+
+
+if __name__ == "__main__":
+    main()