python-vibe-guard 0.7.1__tar.gz → 0.9.0__tar.gz

{python_vibe_guard-0.7.1 → python_vibe_guard-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-vibe-guard
-Version: 0.7.1
+Version: 0.9.0
 Summary: Runtime anti-pattern scanner for async Python — detects what AI-generated code gets wrong
 License: MIT
 Keywords: async,linter,fastapi,asyncio,static-analysis
@@ -163,9 +163,16 @@ python -m pyvibe src/
 # JSON output for CI/CD pipelines
 python -m pyvibe src/ --json
 
+# SARIF 2.1.0 output for GitHub Code Scanning (writes results.sarif)
+python -m pyvibe src/ --sarif
+python -m pyvibe src/ --sarif --sarif-output custom-path.sarif
+
 # Exclude directories (adds to built-in defaults: venv, .venv, __pycache__, …)
 python -m pyvibe src/ --exclude tests
 
+# Show the research evidence behind a rule (accuracy, false positives, sources)
+python -m pyvibe explain PYVIBE-002
+
 # Exit code: 0 = clean, 1 = violations found, 2 = path error
 ```
 
@@ -177,22 +184,29 @@ python -m pyvibe src/ --exclude tests
 
   demo/bad_async.py
 
-  [CRITICAL] [PYVIBE-001] — line 14
+  [CRITICAL] [PYVIBE-001] — line 27
      Function : process_order()
      Problem  : time.sleep() blocks the entire event loop
      Fix      : Use `await asyncio.sleep(n)` instead
+     Suggested fix:
+         await asyncio.sleep(2)
 
-  [CRITICAL] [PYVIBE-002] — line 20
+  [CRITICAL] [PYVIBE-002] — line 33
      Function : fetch_user()
      Problem  : requests.get() is synchronous — blocks the event loop
      Fix      : Use `async with httpx.AsyncClient() as c: await c.get(url)`
+     Suggested fix:
+         async with httpx.AsyncClient() as client:
+             response = await client.get(f"https://api.example.com/users/{user_id}")
 
-  [CRITICAL] [PYVIBE-003] — line 26
+  [CRITICAL] [PYVIBE-003] — line 39
      Function : orchestrate()
      Problem  : asyncio.run() inside async def raises RuntimeError at runtime
      Fix      : Use `await coroutine()` directly — asyncio.run() is for sync entrypoints only
+     Suggested fix:
+         await process_order(42)
 
-  [CRITICAL] [PYVIBE-004] — line 32
+  [CRITICAL] [PYVIBE-004] — line 45
      Function : update_counter()
      Problem  : threading.Lock() blocks the event loop under contention
      Fix      : Use `asyncio.Lock()` with `async with lock:` instead
@@ -201,6 +215,46 @@ python -m pyvibe src/ --exclude tests
   4 violation(s) in 1 file(s)
 ```
 
+`Suggested fix:` blocks are generated from the real code on the flagged line — they are
+printed to the terminal / JSON output only and are never written back to your files.
+Currently available for PYVIBE-001, 002, 003, 007, and 008.
+
+### `pyvibe explain`
+
+Every rule's accuracy claims come from `research/accepted/PYVIBE-XXX.md` — a per-rule
+evidence file with repo-sweep data, an evidence-level grade, and a hit-by-hit precision
+audit. `pyvibe explain` surfaces that in the terminal instead of making you go dig for it:
+
+```bash
+python -m pyvibe explain PYVIBE-002
+```
+
+```
+  PYVIBE-002 — requests.* inside async def
+  ───────────────────────────────────────────────
+
+  Problema:
+    requests.* inside async def
+
+  Por qué ocurre:
+    `requests` is a synchronous HTTP library. Calling it inside an async function
+    blocks the OS thread running the event loop. Under concurrent load this
+    serialises all I/O and eliminates any benefit of async.
+
+  Visto en: 4.0% (10/250 repos, sweep-250 dataset)
+  Nivel de evidencia: B
+  Precisión auditada: ~83%
+  Falsos positivos conocidos: EXECUTOR_WRAPPER; INNER_SYNC_FUNCTION_EXECUTOR; ...
+
+  Fix sugerido:
+    use `httpx.AsyncClient` or `aiohttp.ClientSession` with await.
+
+  Full report: research/accepted/PYVIBE-002.md
+```
+
+If a rule has no evidence file, it prints a clear `No evidence file found for PYVIBE-XXX`
+and exits non-zero — it never invents data.
+
 ---
 
 ## CI/CD integration
@@ -216,6 +270,36 @@ Add to your GitHub Actions workflow:
 
 The scanner exits with code `1` when violations are found, failing the CI job.
 
+### GitHub Code Scanning (SARIF)
+
+```yaml
+- name: python-vibe-guard scan
+  run: |
+    pip install python-vibe-guard
+    python -m pyvibe src/ --sarif
+  continue-on-error: true  # let the upload step surface results in the PR instead
+
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+```
+
+Findings then show up as annotations on the PR diff and in the repo's Security tab,
+each linking back to its `research/accepted/PYVIBE-XXX.md` evidence file via `helpUri`.
+
+---
+
+## GitHub Action
+
+- name: python-vibe-guard
+  uses: joaquinriosheredia/python-vibe-guard-action@v1
+  with:
+    path: src/
+
+Violations appear directly in GitHub Security tab (SARIF).
+Link: https://github.com/Joaquinriosheredia/python-vibe-guard-action
+
 ---
 
 ## Pre-commit integration
@@ -268,7 +352,7 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-123 tests: true positives + false-positive guards for every rule.
+226 tests: true positives + false-positive guards for every rule, plus SARIF output and `pyvibe explain` coverage.
 
 ---
 

{python_vibe_guard-0.7.1 → python_vibe_guard-0.9.0}/README.md

@@ -148,9 +148,16 @@ python -m pyvibe src/
 # JSON output for CI/CD pipelines
 python -m pyvibe src/ --json
 
+# SARIF 2.1.0 output for GitHub Code Scanning (writes results.sarif)
+python -m pyvibe src/ --sarif
+python -m pyvibe src/ --sarif --sarif-output custom-path.sarif
+
 # Exclude directories (adds to built-in defaults: venv, .venv, __pycache__, …)
 python -m pyvibe src/ --exclude tests
 
+# Show the research evidence behind a rule (accuracy, false positives, sources)
+python -m pyvibe explain PYVIBE-002
+
 # Exit code: 0 = clean, 1 = violations found, 2 = path error
 ```
 
@@ -162,22 +169,29 @@ python -m pyvibe src/ --exclude tests
 
   demo/bad_async.py
 
-  [CRITICAL] [PYVIBE-001] — line 14
+  [CRITICAL] [PYVIBE-001] — line 27
      Function : process_order()
      Problem  : time.sleep() blocks the entire event loop
      Fix      : Use `await asyncio.sleep(n)` instead
+     Suggested fix:
+         await asyncio.sleep(2)
 
-  [CRITICAL] [PYVIBE-002] — line 20
+  [CRITICAL] [PYVIBE-002] — line 33
      Function : fetch_user()
      Problem  : requests.get() is synchronous — blocks the event loop
      Fix      : Use `async with httpx.AsyncClient() as c: await c.get(url)`
+     Suggested fix:
+         async with httpx.AsyncClient() as client:
+             response = await client.get(f"https://api.example.com/users/{user_id}")
 
-  [CRITICAL] [PYVIBE-003] — line 26
+  [CRITICAL] [PYVIBE-003] — line 39
      Function : orchestrate()
      Problem  : asyncio.run() inside async def raises RuntimeError at runtime
      Fix      : Use `await coroutine()` directly — asyncio.run() is for sync entrypoints only
+     Suggested fix:
+         await process_order(42)
 
-  [CRITICAL] [PYVIBE-004] — line 32
+  [CRITICAL] [PYVIBE-004] — line 45
      Function : update_counter()
      Problem  : threading.Lock() blocks the event loop under contention
      Fix      : Use `asyncio.Lock()` with `async with lock:` instead
@@ -186,6 +200,46 @@ python -m pyvibe src/ --exclude tests
   4 violation(s) in 1 file(s)
 ```
 
+`Suggested fix:` blocks are generated from the real code on the flagged line — they are
+printed to the terminal / JSON output only and are never written back to your files.
+Currently available for PYVIBE-001, 002, 003, 007, and 008.
+
+### `pyvibe explain`
+
+Every rule's accuracy claims come from `research/accepted/PYVIBE-XXX.md` — a per-rule
+evidence file with repo-sweep data, an evidence-level grade, and a hit-by-hit precision
+audit. `pyvibe explain` surfaces that in the terminal instead of making you go dig for it:
+
+```bash
+python -m pyvibe explain PYVIBE-002
+```
+
+```
+  PYVIBE-002 — requests.* inside async def
+  ───────────────────────────────────────────────
+
+  Problema:
+    requests.* inside async def
+
+  Por qué ocurre:
+    `requests` is a synchronous HTTP library. Calling it inside an async function
+    blocks the OS thread running the event loop. Under concurrent load this
+    serialises all I/O and eliminates any benefit of async.
+
+  Visto en: 4.0% (10/250 repos, sweep-250 dataset)
+  Nivel de evidencia: B
+  Precisión auditada: ~83%
+  Falsos positivos conocidos: EXECUTOR_WRAPPER; INNER_SYNC_FUNCTION_EXECUTOR; ...
+
+  Fix sugerido:
+    use `httpx.AsyncClient` or `aiohttp.ClientSession` with await.
+
+  Full report: research/accepted/PYVIBE-002.md
+```
+
+If a rule has no evidence file, it prints a clear `No evidence file found for PYVIBE-XXX`
+and exits non-zero — it never invents data.
+
 ---
 
 ## CI/CD integration
@@ -201,6 +255,36 @@ Add to your GitHub Actions workflow:
 
 The scanner exits with code `1` when violations are found, failing the CI job.
 
+### GitHub Code Scanning (SARIF)
+
+```yaml
+- name: python-vibe-guard scan
+  run: |
+    pip install python-vibe-guard
+    python -m pyvibe src/ --sarif
+  continue-on-error: true  # let the upload step surface results in the PR instead
+
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+```
+
+Findings then show up as annotations on the PR diff and in the repo's Security tab,
+each linking back to its `research/accepted/PYVIBE-XXX.md` evidence file via `helpUri`.
+
+---
+
+## GitHub Action
+
+- name: python-vibe-guard
+  uses: joaquinriosheredia/python-vibe-guard-action@v1
+  with:
+    path: src/
+
+Violations appear directly in GitHub Security tab (SARIF).
+Link: https://github.com/Joaquinriosheredia/python-vibe-guard-action
+
 ---
 
 ## Pre-commit integration
@@ -253,7 +337,7 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-123 tests: true positives + false-positive guards for every rule.
+226 tests: true positives + false-positive guards for every rule, plus SARIF output and `pyvibe explain` coverage.
 
 ---
 

{python_vibe_guard-0.7.1 → python_vibe_guard-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-vibe-guard"
-version = "0.7.1"
+version = "0.9.0"
 description = "Runtime anti-pattern scanner for async Python — detects what AI-generated code gets wrong"
 readme = "README.md"
 requires-python = ">=3.10"

{python_vibe_guard-0.7.1 → python_vibe_guard-0.9.0}/python_vibe_guard.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-vibe-guard
-Version: 0.7.1
+Version: 0.9.0
 Summary: Runtime anti-pattern scanner for async Python — detects what AI-generated code gets wrong
 License: MIT
 Keywords: async,linter,fastapi,asyncio,static-analysis
@@ -163,9 +163,16 @@ python -m pyvibe src/
 # JSON output for CI/CD pipelines
 python -m pyvibe src/ --json
 
+# SARIF 2.1.0 output for GitHub Code Scanning (writes results.sarif)
+python -m pyvibe src/ --sarif
+python -m pyvibe src/ --sarif --sarif-output custom-path.sarif
+
 # Exclude directories (adds to built-in defaults: venv, .venv, __pycache__, …)
 python -m pyvibe src/ --exclude tests
 
+# Show the research evidence behind a rule (accuracy, false positives, sources)
+python -m pyvibe explain PYVIBE-002
+
 # Exit code: 0 = clean, 1 = violations found, 2 = path error
 ```
 
@@ -177,22 +184,29 @@ python -m pyvibe src/ --exclude tests
 
   demo/bad_async.py
 
-  [CRITICAL] [PYVIBE-001] — line 14
+  [CRITICAL] [PYVIBE-001] — line 27
      Function : process_order()
      Problem  : time.sleep() blocks the entire event loop
      Fix      : Use `await asyncio.sleep(n)` instead
+     Suggested fix:
+         await asyncio.sleep(2)
 
-  [CRITICAL] [PYVIBE-002] — line 20
+  [CRITICAL] [PYVIBE-002] — line 33
      Function : fetch_user()
      Problem  : requests.get() is synchronous — blocks the event loop
      Fix      : Use `async with httpx.AsyncClient() as c: await c.get(url)`
+     Suggested fix:
+         async with httpx.AsyncClient() as client:
+             response = await client.get(f"https://api.example.com/users/{user_id}")
 
-  [CRITICAL] [PYVIBE-003] — line 26
+  [CRITICAL] [PYVIBE-003] — line 39
      Function : orchestrate()
      Problem  : asyncio.run() inside async def raises RuntimeError at runtime
      Fix      : Use `await coroutine()` directly — asyncio.run() is for sync entrypoints only
+     Suggested fix:
+         await process_order(42)
 
-  [CRITICAL] [PYVIBE-004] — line 32
+  [CRITICAL] [PYVIBE-004] — line 45
      Function : update_counter()
      Problem  : threading.Lock() blocks the event loop under contention
      Fix      : Use `asyncio.Lock()` with `async with lock:` instead
@@ -201,6 +215,46 @@ python -m pyvibe src/ --exclude tests
   4 violation(s) in 1 file(s)
 ```
 
+`Suggested fix:` blocks are generated from the real code on the flagged line — they are
+printed to the terminal / JSON output only and are never written back to your files.
+Currently available for PYVIBE-001, 002, 003, 007, and 008.
+
+### `pyvibe explain`
+
+Every rule's accuracy claims come from `research/accepted/PYVIBE-XXX.md` — a per-rule
+evidence file with repo-sweep data, an evidence-level grade, and a hit-by-hit precision
+audit. `pyvibe explain` surfaces that in the terminal instead of making you go dig for it:
+
+```bash
+python -m pyvibe explain PYVIBE-002
+```
+
+```
+  PYVIBE-002 — requests.* inside async def
+  ───────────────────────────────────────────────
+
+  Problema:
+    requests.* inside async def
+
+  Por qué ocurre:
+    `requests` is a synchronous HTTP library. Calling it inside an async function
+    blocks the OS thread running the event loop. Under concurrent load this
+    serialises all I/O and eliminates any benefit of async.
+
+  Visto en: 4.0% (10/250 repos, sweep-250 dataset)
+  Nivel de evidencia: B
+  Precisión auditada: ~83%
+  Falsos positivos conocidos: EXECUTOR_WRAPPER; INNER_SYNC_FUNCTION_EXECUTOR; ...
+
+  Fix sugerido:
+    use `httpx.AsyncClient` or `aiohttp.ClientSession` with await.
+
+  Full report: research/accepted/PYVIBE-002.md
+```
+
+If a rule has no evidence file, it prints a clear `No evidence file found for PYVIBE-XXX`
+and exits non-zero — it never invents data.
+
 ---
 
 ## CI/CD integration
@@ -216,6 +270,36 @@ Add to your GitHub Actions workflow:
 
 The scanner exits with code `1` when violations are found, failing the CI job.
 
+### GitHub Code Scanning (SARIF)
+
+```yaml
+- name: python-vibe-guard scan
+  run: |
+    pip install python-vibe-guard
+    python -m pyvibe src/ --sarif
+  continue-on-error: true  # let the upload step surface results in the PR instead
+
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+```
+
+Findings then show up as annotations on the PR diff and in the repo's Security tab,
+each linking back to its `research/accepted/PYVIBE-XXX.md` evidence file via `helpUri`.
+
+---
+
+## GitHub Action
+
+- name: python-vibe-guard
+  uses: joaquinriosheredia/python-vibe-guard-action@v1
+  with:
+    path: src/
+
+Violations appear directly in GitHub Security tab (SARIF).
+Link: https://github.com/Joaquinriosheredia/python-vibe-guard-action
+
 ---
 
 ## Pre-commit integration
@@ -268,7 +352,7 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-123 tests: true positives + false-positive guards for every rule.
+226 tests: true positives + false-positive guards for every rule, plus SARIF output and `pyvibe explain` coverage.
 
 ---
 

{python_vibe_guard-0.7.1 → python_vibe_guard-0.9.0}/python_vibe_guard.egg-info/SOURCES.txt

@@ -8,7 +8,11 @@ python_vibe_guard.egg-info/top_level.txt
 pyvibe/__init__.py
 pyvibe/__main__.py
 pyvibe/analyzer.py
+pyvibe/autofix.py
 pyvibe/cli.py
+pyvibe/explain.py
+pyvibe/rule_docs.py
+pyvibe/sarif.py
 pyvibe/rules/__init__.py
 pyvibe/rules/async_requests.py
 pyvibe/rules/async_sleep.py
@@ -32,4 +36,6 @@ pyvibe/rules/subprocess_async.py
 pyvibe/rules/threading_lock.py
 pyvibe/rules/while_true_no_await.py
 tests/test_exclude.py
-tests/test_rules.py
+tests/test_explain.py
+tests/test_rules.py
+tests/test_sarif.py

python_vibe_guard-0.9.0/pyvibe/__init__.py

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

{python_vibe_guard-0.7.1 → python_vibe_guard-0.9.0}/pyvibe/analyzer.py

@@ -49,6 +49,17 @@ ALL_RULES = [
 
 ALL_RULE_IDS: FrozenSet[str] = frozenset(r.RULE_ID for r in ALL_RULES)
 
+# Rules that build a concrete "Suggested fix" snippet from the real source
+# text (see pyvibe/autofix.py) and therefore need the full source passed
+# into their constructor.
+_NEEDS_SOURCE: FrozenSet[type] = frozenset({
+    AsyncSleepRule,
+    AsyncRequestsRule,
+    AsyncioRunRule,
+    SubprocessAsyncRule,
+    SqliteAsyncRule,
+})
+
 # 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
@@ -101,6 +112,8 @@ def analyze_source(
     for RuleClass in ALL_RULES:
         if RuleClass is SilentExceptRule:
             visitor = RuleClass(source_lines)
+        elif RuleClass in _NEEDS_SOURCE:
+            visitor = RuleClass(source)
         else:
             visitor = RuleClass()
         visitor.visit(tree)

python_vibe_guard-0.9.0/pyvibe/autofix.py

@@ -0,0 +1,31 @@
+"""Shared helpers for building concrete "Suggested fix" snippets from real source context.
+
+Rules that support autofix suggestions receive the original source text and use
+`ast.get_source_segment` to pull the exact expressions the developer wrote
+(variable names, literals, kwargs) into the suggested replacement, instead of
+a synthetic placeholder like `...`.
+"""
+import ast
+from typing import Optional
+
+
+def render_node(source: str, node: ast.AST) -> Optional[str]:
+    """Return the literal source text of an AST node, or None if unavailable."""
+    return ast.get_source_segment(source, node)
+
+
+def render_call_args(source: str, node: ast.Call) -> str:
+    """Reconstruct the literal argument-list text of a Call node from source."""
+    parts = []
+    for arg in node.args:
+        if isinstance(arg, ast.Starred):
+            seg = render_node(source, arg.value)
+            parts.append(f"*{seg}" if seg else "*args")
+        else:
+            seg = render_node(source, arg)
+            parts.append(seg if seg is not None else "...")
+    for kw in node.keywords:
+        seg = render_node(source, kw.value)
+        seg = seg if seg is not None else "..."
+        parts.append(f"**{seg}" if kw.arg is None else f"{kw.arg}={seg}")
+    return ", ".join(parts)

{python_vibe_guard-0.7.1 → python_vibe_guard-0.9.0}/pyvibe/cli.py

@@ -5,8 +5,10 @@ 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> --sarif           # SARIF 2.1.0 -> results.sarif
     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
+    python -m pyvibe explain PYVIBE-002       # show research evidence for a rule
 """
 import argparse
 import json
@@ -25,6 +27,10 @@ from pyvibe.analyzer import (
 
 
 def main():
+    if len(sys.argv) > 1 and sys.argv[1] == "explain":
+        _main_explain(sys.argv[2:])
+        return
+
     parser = argparse.ArgumentParser(
         prog="pyvibe",
         description="Detect runtime anti-patterns in async Python code",
@@ -32,6 +38,17 @@ def main():
     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(
+        "--sarif",
+        action="store_true",
+        help="Also write SARIF 2.1.0 output (for GitHub Code Scanning)",
+    )
+    parser.add_argument(
+        "--sarif-output",
+        metavar="PATH",
+        default="results.sarif",
+        help="Path to write SARIF output to (default: results.sarif)",
+    )
     parser.add_argument(
         "--exclude",
         metavar="DIR",
@@ -97,6 +114,12 @@ def main():
     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.sarif:
+        from pyvibe.sarif import write_sarif
+
+        write_sarif(file_results, args.sarif_output)
+        print(f"SARIF results written to {args.sarif_output}")
+
     if args.json:
         output = []
         for path, violations in file_results.items():
@@ -109,6 +132,7 @@ def main():
                     "function": v.function_name,
                     "message": v.message,
                     "evidence": v.evidence,
+                    "suggested_fix": v.suggested_fix,
                 })
         print(json.dumps(output, indent=2))
     else:
@@ -137,6 +161,10 @@ def _print_human(file_results: dict, total_violations: int, total_files: int):
             print(f"     Function : {v.function_name}()")
             print(f"     Problem  : {v.message}")
             print(f"     Fix      : {v.evidence}")
+            if v.suggested_fix:
+                print("     Suggested fix:")
+                for line in v.suggested_fix.splitlines():
+                    print(f"         {line}")
             print()
 
     print("  ─────────────────────────────────────────────")
@@ -144,5 +172,27 @@ def _print_human(file_results: dict, total_violations: int, total_files: int):
     print()
 
 
+def _main_explain(argv):
+    parser = argparse.ArgumentParser(
+        prog="pyvibe explain",
+        description="Show the research evidence behind a python-vibe-guard rule",
+    )
+    parser.add_argument("rule_id", help="Rule ID, e.g. PYVIBE-002")
+    args = parser.parse_args(argv)
+
+    from pyvibe.explain import EvidenceNotFoundError, explain_rule
+
+    try:
+        text = explain_rule(args.rule_id)
+    except EvidenceNotFoundError as e:
+        print(str(e))
+        sys.exit(1)
+
+    print()
+    print(text)
+    print()
+    sys.exit(0)
+
+
 if __name__ == "__main__":
     main()