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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-vibe-guard
-Version: 0.7.1
+Version: 0.8.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
 ```
 
@@ -201,6 +208,42 @@ python -m pyvibe src/ --exclude tests
   4 violation(s) in 1 file(s)
 ```
 
+### `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 +259,24 @@ 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`.
+
 ---
 
 ## Pre-commit integration
@@ -268,7 +329,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.8.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
 ```
 
@@ -186,6 +193,42 @@ python -m pyvibe src/ --exclude tests
   4 violation(s) in 1 file(s)
 ```
 
+### `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 +244,24 @@ 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`.
+
 ---
 
 ## Pre-commit integration
@@ -253,7 +314,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.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-vibe-guard"
-version = "0.7.1"
+version = "0.8.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.8.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.8.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
 ```
 
@@ -201,6 +208,42 @@ python -m pyvibe src/ --exclude tests
   4 violation(s) in 1 file(s)
 ```
 
+### `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 +259,24 @@ 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`.
+
 ---
 
 ## Pre-commit integration
@@ -268,7 +329,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.8.0}/python_vibe_guard.egg-info/SOURCES.txt

@@ -9,6 +9,9 @@ pyvibe/__init__.py
 pyvibe/__main__.py
 pyvibe/analyzer.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 +35,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.8.0/pyvibe/__init__.py

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

{python_vibe_guard-0.7.1 → python_vibe_guard-0.8.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():
@@ -144,5 +167,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()

python_vibe_guard-0.8.0/pyvibe/explain.py

@@ -0,0 +1,157 @@
+"""`pyvibe explain PYVIBE-XXX` — surfaces the research evidence behind a rule
+in the terminal, so the CLI's "trust us" claims are one command away from
+the actual data (research/accepted/PYVIBE-XXX.md, research/precision-audit.md).
+"""
+import re
+from pathlib import Path
+from typing import List, Optional
+
+from pyvibe.analyzer import ALL_RULES
+from pyvibe.rule_docs import parse_rule_docstring
+
+RULES_BY_ID = {cls.RULE_ID: cls for cls in ALL_RULES}
+
+_PCT_RE = re.compile(r"(\d+)/(\d+)\s*\(([\d.]+)%\)")
+_EVIDENCE_RE = re.compile(r"Evidence Level:?\s*\*{0,2}\s*([A-D]\+?)\b")
+_FP_SECTION_RE = re.compile(
+    r"### Patrones de FP identificados\s*\n(.*?)(?=\n##|\Z)", re.DOTALL
+)
+_FP_PATTERN_NAME_RE = re.compile(r"\*\*([^*]+)\*\*\s*—")
+_VALID_RULE_ID_RE = re.compile(r"^PYVIBE-\d{3}$")
+
+
+class EvidenceNotFoundError(Exception):
+    pass
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def _accepted_path(rule_id: str) -> Path:
+    return _repo_root() / "research" / "accepted" / f"{rule_id}.md"
+
+
+def _precision_audit_path() -> Path:
+    return _repo_root() / "research" / "precision-audit.md"
+
+
+def normalize_rule_id(raw: str) -> str:
+    raw = raw.strip().upper()
+    if raw.startswith("PYVIBE-"):
+        return raw
+    if raw.isdigit():
+        return f"PYVIBE-{int(raw):03d}"
+    return raw
+
+
+def _extract_repo_percentage(doc_text: str) -> str:
+    for line in doc_text.splitlines():
+        if "Repos afectados" not in line:
+            continue
+        matches = _PCT_RE.findall(line)
+        if not matches:
+            return "not reported"
+        count, sample, pct = max(matches, key=lambda m: int(m[1]))
+        return f"{pct}% ({count}/{sample} repos, sweep-250 dataset)"
+    return "not reported"
+
+
+def _extract_evidence_level(doc_text: str) -> str:
+    for line in doc_text.splitlines():
+        if "Evidence Level" not in line:
+            continue
+        m = _EVIDENCE_RE.search(line)
+        if m:
+            return m.group(1)
+    return "not documented"
+
+
+def _extract_audit_row(rule_id: str) -> Optional[List[str]]:
+    path = _precision_audit_path()
+    if not path.exists():
+        return None
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped.startswith(f"| {rule_id} "):
+            return [c.strip() for c in stripped.strip("|").split("|")]
+    return None
+
+
+def _extract_precision(rule_id: str) -> str:
+    row = _extract_audit_row(rule_id)
+    if row and len(row) >= 8:
+        return row[7]
+    return "not audited"
+
+
+def _extract_known_fps(doc_text: str, rule_id: str) -> str:
+    m = _FP_SECTION_RE.search(doc_text)
+    if m:
+        names = _FP_PATTERN_NAME_RE.findall(m.group(1))
+        if names:
+            return "; ".join(n.strip() for n in names)
+
+    row = _extract_audit_row(rule_id)
+    if row and len(row) >= 6:
+        fp, hits, audited = row[5], row[2], row[3]
+        return (
+            f"{fp} false positive(s) found in {audited} manually audited hits "
+            f"(of {hits} total) — see research/precision-audit.md for the "
+            f"hit-by-hit classification."
+        )
+    return "No documented false-positive patterns — see research/precision-audit.md."
+
+
+def explain_rule(raw_rule_id: str) -> str:
+    rule_id = normalize_rule_id(raw_rule_id)
+    if not _VALID_RULE_ID_RE.match(rule_id):
+        # Reject anything that isn't a bare "PYVIBE-###" *before* it touches
+        # a filesystem path — raw_rule_id is attacker-controllable (CLI arg)
+        # and would otherwise let e.g. "../../../etc/passwd" traverse out of
+        # research/accepted/.
+        raise EvidenceNotFoundError(f"No evidence file found for {rule_id}")
+
+    doc_path = _accepted_path(rule_id)
+    if not doc_path.exists():
+        raise EvidenceNotFoundError(f"No evidence file found for {rule_id}")
+
+    doc_text = doc_path.read_text(encoding="utf-8")
+
+    cls = RULES_BY_ID.get(rule_id)
+    if cls is not None:
+        parsed = parse_rule_docstring(cls)
+        title, why, fix = parsed.title, parsed.why, parsed.fix
+    else:
+        first_line = doc_text.splitlines()[0].lstrip("# ").strip()
+        title, why, fix = first_line, "not available", "not available"
+
+    repo_pct = _extract_repo_percentage(doc_text)
+    evidence_level = _extract_evidence_level(doc_text)
+    precision = _extract_precision(rule_id)
+    known_fps = _extract_known_fps(doc_text, rule_id)
+
+    lines = [
+        f"  {rule_id} — {title}",
+        "  " + "─" * 47,
+        "",
+        "  Problema:",
+        f"    {title}",
+        "",
+        "  Por qué ocurre:",
+    ]
+    for para in why.split("\n\n"):
+        lines.append(f"    {para}")
+    lines += [
+        "",
+        f"  Visto en: {repo_pct}",
+        f"  Nivel de evidencia: {evidence_level}",
+        f"  Precisión auditada: {precision}",
+        f"  Falsos positivos conocidos: {known_fps}",
+        "",
+        "  Fix sugerido:",
+        f"    {fix}",
+        "",
+        f"  Full report: research/accepted/{rule_id}.md",
+    ]
+    return "\n".join(lines)

python_vibe_guard-0.8.0/pyvibe/rule_docs.py

@@ -0,0 +1,64 @@
+"""Parses the English docstring every rule class already carries into
+structured (title, mechanism, fix) fields.
+
+Used by both `pyvibe explain` and SARIF rule-catalog generation so the
+two surfaces never drift out of sync with each other.
+"""
+import inspect
+import re
+from typing import NamedTuple
+
+_TITLE_PREFIX_RE = re.compile(r"^PYVIBE-\d+\s*—\s*")
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+class RuleDoc(NamedTuple):
+    title: str
+    why: str
+    fix: str
+
+
+def parse_rule_docstring(cls) -> RuleDoc:
+    """Split a rule class's docstring into title / mechanism / fix.
+
+    Docstring convention (see any file under pyvibe/rules/): the first
+    paragraph is "PYVIBE-XXX — <title>", the closing paragraph starting
+    with "Fix:" is the suggested fix, and everything in between explains
+    the mechanism/runtime effect.
+    """
+    doc = inspect.getdoc(cls) or ""
+    paragraphs = [p.strip() for p in re.split(r"\n\s*\n", doc) if p.strip()]
+    if not paragraphs:
+        rule_id = getattr(cls, "RULE_ID", "")
+        return RuleDoc(title=rule_id, why="", fix="")
+
+    title = _TITLE_PREFIX_RE.sub("", paragraphs[0].splitlines()[0]).strip()
+
+    # The "Fix:" sentence is usually its own paragraph, but a couple of
+    # rules (e.g. PYVIBE-005) tack it onto the end of the preceding
+    # sentence with no blank line in between — so scan line-by-line
+    # within each paragraph rather than requiring "Fix:" at paragraph start.
+    fix = ""
+    why_parts = []
+    for para in paragraphs[1:]:
+        plines = para.splitlines()
+        fix_idx = next(
+            (i for i, line in enumerate(plines) if line.strip().startswith("Fix:")),
+            None,
+        )
+        if fix_idx is None or fix:
+            why_parts.append(_WHITESPACE_RE.sub(" ", para))
+            continue
+
+        before_lines = plines[:fix_idx]
+        fix_lines = list(plines[fix_idx:])
+        fix_lines[0] = fix_lines[0].strip()[len("Fix:"):].strip()
+        fix = _WHITESPACE_RE.sub(" ", " ".join(fix_lines)).strip()
+        if before_lines:
+            why_parts.append(_WHITESPACE_RE.sub(" ", " ".join(before_lines)).strip())
+
+    return RuleDoc(
+        title=title,
+        why="\n\n".join(why_parts),
+        fix=fix or "See rule source for fix guidance.",
+    )

python_vibe_guard-0.8.0/pyvibe/sarif.py

@@ -0,0 +1,95 @@
+"""SARIF 2.1.0 output for GitHub Code Scanning (`pyvibe <path> --sarif`)."""
+import json
+from pathlib import Path
+from typing import Dict, List
+
+from pyvibe import __version__
+from pyvibe.analyzer import ALL_RULES
+from pyvibe.rule_docs import parse_rule_docstring
+from pyvibe.rules.base import Violation
+
+SARIF_SCHEMA_URI = (
+    "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/Schemata/"
+    "sarif-schema-2.1.0.json"
+)
+REPO_URL = "https://github.com/Joaquinriosheredia/python-vibe-guard"
+
+_SEVERITY_TO_LEVEL = {"CRITICAL": "error", "WARNING": "warning"}
+
+
+def _level_for(severity: str) -> str:
+    return _SEVERITY_TO_LEVEL.get(severity, "warning")
+
+
+def _rule_descriptor(cls) -> dict:
+    doc = parse_rule_docstring(cls)
+    return {
+        "id": cls.RULE_ID,
+        "name": cls.__name__,
+        "shortDescription": {"text": doc.title},
+        "fullDescription": {"text": doc.why or doc.title},
+        "help": {"text": doc.fix},
+        "helpUri": f"{REPO_URL}/blob/master/research/accepted/{cls.RULE_ID}.md",
+        "defaultConfiguration": {"level": _level_for(cls.SEVERITY)},
+    }
+
+
+def _artifact_uri(path) -> str:
+    p = Path(path)
+    if p.is_absolute():
+        try:
+            p = p.relative_to(Path.cwd())
+        except ValueError:
+            pass
+    return p.as_posix()
+
+
+def _result(path, v: Violation) -> dict:
+    return {
+        "ruleId": v.rule_id,
+        "level": _level_for(v.severity),
+        "message": {"text": f"{v.message} — Fix: {v.evidence}"},
+        "locations": [
+            {
+                "physicalLocation": {
+                    "artifactLocation": {"uri": _artifact_uri(path)},
+                    "region": {"startLine": v.line},
+                }
+            }
+        ],
+        "properties": {"function": v.function_name},
+    }
+
+
+def build_sarif(file_results: Dict) -> dict:
+    """file_results: {path: [Violation, ...]} as produced by analyze_file /
+    analyze_directory. Every rule is listed in the tool's rule catalog
+    regardless of whether it fired, per SARIF/Code Scanning convention.
+    """
+    rules = [_rule_descriptor(cls) for cls in ALL_RULES]
+    results: List[dict] = [
+        _result(path, v) for path, violations in file_results.items() for v in violations
+    ]
+
+    return {
+        "$schema": SARIF_SCHEMA_URI,
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "python-vibe-guard",
+                        "informationUri": REPO_URL,
+                        "version": __version__,
+                        "rules": rules,
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }
+
+
+def write_sarif(file_results: Dict, output_path) -> None:
+    sarif = build_sarif(file_results)
+    Path(output_path).write_text(json.dumps(sarif, indent=2), encoding="utf-8")

python_vibe_guard-0.8.0/tests/test_explain.py

@@ -0,0 +1,112 @@
+"""Tests for `pyvibe explain PYVIBE-XXX` (pyvibe/explain.py + CLI subcommand)."""
+import subprocess
+import sys
+import os
+from pathlib import Path
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import pytest
+
+from pyvibe.analyzer import ALL_RULE_IDS
+from pyvibe.explain import EvidenceNotFoundError, explain_rule, normalize_rule_id
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+REQUIRED_SECTIONS = [
+    "Problema",
+    "Por qué ocurre",
+    "Visto en",
+    "Nivel de evidencia",
+    "Precisión auditada",
+    "Falsos positivos conocidos",
+    "Fix sugerido",
+]
+
+
+# ─── normalize_rule_id ──────────────────────────────────────────────────────
+
+def test_normalize_rule_id_passthrough():
+    assert normalize_rule_id("PYVIBE-002") == "PYVIBE-002"
+
+
+def test_normalize_rule_id_lowercase():
+    assert normalize_rule_id("pyvibe-002") == "PYVIBE-002"
+
+
+def test_normalize_rule_id_numeric_shorthand():
+    assert normalize_rule_id("2") == "PYVIBE-002"
+    assert normalize_rule_id("20") == "PYVIBE-020"
+
+
+# ─── explain_rule() unit tests ──────────────────────────────────────────────
+
+def test_explain_rule_missing_file_raises_clear_error():
+    with pytest.raises(EvidenceNotFoundError, match="No evidence file found for PYVIBE-999"):
+        explain_rule("PYVIBE-999")
+
+
+def test_explain_rule_rejects_path_traversal():
+    """rule_id is a raw CLI arg — must never escape research/accepted/."""
+    with pytest.raises(EvidenceNotFoundError):
+        explain_rule("../../../../etc/passwd")
+    with pytest.raises(EvidenceNotFoundError):
+        explain_rule("../../README")
+
+
+@pytest.mark.parametrize("rule_id", sorted(ALL_RULE_IDS))
+def test_explain_rule_covers_every_accepted_rule(rule_id):
+    """Every shipped rule has a research doc and produces all 7 sections."""
+    text = explain_rule(rule_id)
+    for section in REQUIRED_SECTIONS:
+        assert section in text, f"{rule_id}: missing section {section!r}"
+
+
+def test_explain_rule_fix_is_not_generic_placeholder():
+    text = explain_rule("PYVIBE-002")
+    assert "httpx.AsyncClient" in text or "aiohttp" in text
+
+
+def test_explain_rule_005_fix_extracted_despite_shared_paragraph():
+    # Regression: PYVIBE-005's "Fix:" line shares a paragraph with the
+    # preceding sentence in the docstring (no blank line separator).
+    text = explain_rule("PYVIBE-005")
+    assert "soft_time_limit=30" in text
+    assert "See rule source for fix guidance." not in text
+
+
+def test_explain_rule_reports_repo_percentage():
+    text = explain_rule("PYVIBE-002")
+    assert "%" in text
+    assert "250" in text
+
+
+# ─── CLI subcommand (subprocess, end-to-end) ────────────────────────────────
+
+def _run_cli(args, cwd=REPO_ROOT):
+    return subprocess.run(
+        [sys.executable, "-m", "pyvibe", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
+
+
+def test_cli_explain_known_rule_exits_zero():
+    result = _run_cli(["explain", "PYVIBE-002"])
+    assert result.returncode == 0
+    assert "PYVIBE-002" in result.stdout
+    for section in REQUIRED_SECTIONS:
+        assert section in result.stdout
+
+
+def test_cli_explain_unknown_rule_prints_clear_message_and_exits_nonzero():
+    result = _run_cli(["explain", "PYVIBE-999"])
+    assert result.returncode == 1
+    assert "No evidence file found for PYVIBE-999" in result.stdout
+
+
+def test_cli_explain_normalizes_numeric_shorthand():
+    result = _run_cli(["explain", "2"])
+    assert result.returncode == 0
+    assert "PYVIBE-002" in result.stdout

python_vibe_guard-0.8.0/tests/test_sarif.py

@@ -0,0 +1,116 @@
+"""Tests for SARIF 2.1.0 output (pyvibe/sarif.py + --sarif CLI flag)."""
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import sys as _sys
+import os
+
+_sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from pyvibe.analyzer import ALL_RULE_IDS, analyze_source
+from pyvibe.sarif import build_sarif
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+VIOLATION_SRC = """\
+import time
+
+async def handler():
+    time.sleep(5)
+"""
+
+CLEAN_SRC = """\
+def handler():
+    pass
+"""
+
+
+# ─── build_sarif() unit tests ──────────────────────────────────────────────
+
+def test_sarif_schema_version():
+    sarif = build_sarif({})
+    assert sarif["version"] == "2.1.0"
+    assert sarif["$schema"].endswith("sarif-schema-2.1.0.json")
+
+
+def test_sarif_rule_catalog_lists_all_rules_even_with_no_hits():
+    sarif = build_sarif({})
+    rule_ids = {r["id"] for r in sarif["runs"][0]["tool"]["driver"]["rules"]}
+    assert rule_ids == set(ALL_RULE_IDS)
+    assert sarif["runs"][0]["results"] == []
+
+
+def test_sarif_rule_descriptor_has_help_uri_pointing_to_research_doc():
+    sarif = build_sarif({})
+    rules_by_id = {r["id"]: r for r in sarif["runs"][0]["tool"]["driver"]["rules"]}
+    rule = rules_by_id["PYVIBE-001"]
+    assert rule["helpUri"].endswith("research/accepted/PYVIBE-001.md")
+    assert rule["shortDescription"]["text"]
+    assert rule["fullDescription"]["text"]
+
+
+def test_sarif_result_has_ruleid_message_and_location():
+    violations = analyze_source(VIOLATION_SRC, filepath="handler.py")
+    sarif = build_sarif({Path("handler.py"): violations})
+    results = sarif["runs"][0]["results"]
+    assert len(results) == 1
+    result = results[0]
+    assert result["ruleId"] == "PYVIBE-001"
+    assert result["level"] == "error"
+    assert "message" in result and result["message"]["text"]
+    loc = result["locations"][0]["physicalLocation"]
+    assert loc["artifactLocation"]["uri"] == "handler.py"
+    assert loc["region"]["startLine"] == 4
+
+
+def test_sarif_level_reflects_downgraded_severity():
+    # PYVIBE-001 is downgraded to WARNING inside test files by default.
+    violations = analyze_source(VIOLATION_SRC, filepath="tests/test_handler.py")
+    sarif = build_sarif({Path("tests/test_handler.py"): violations})
+    result = sarif["runs"][0]["results"][0]
+    assert result["level"] == "warning"
+
+
+# ─── --sarif CLI flag (subprocess, end-to-end) ─────────────────────────────
+
+def _run_cli(args, cwd=REPO_ROOT):
+    return subprocess.run(
+        [sys.executable, "-m", "pyvibe", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
+
+
+def test_cli_sarif_flag_writes_file_with_same_exit_code_as_json():
+    with tempfile.TemporaryDirectory() as tmp:
+        src = Path(tmp) / "bad.py"
+        src.write_text(VIOLATION_SRC)
+        out = Path(tmp) / "out.sarif"
+
+        result = _run_cli([str(src), "--sarif", "--sarif-output", str(out)])
+        json_result = _run_cli([str(src), "--json"])
+
+        assert result.returncode == json_result.returncode == 1
+        assert out.exists()
+        sarif = json.loads(out.read_text())
+        assert sarif["version"] == "2.1.0"
+        assert len(sarif["runs"][0]["results"]) == 1
+        assert sarif["runs"][0]["results"][0]["ruleId"] == "PYVIBE-001"
+
+
+def test_cli_sarif_flag_clean_scan_exits_zero():
+    with tempfile.TemporaryDirectory() as tmp:
+        src = Path(tmp) / "clean.py"
+        src.write_text(CLEAN_SRC)
+        out = Path(tmp) / "out.sarif"
+
+        result = _run_cli([str(src), "--sarif", "--sarif-output", str(out)])
+
+        assert result.returncode == 0
+        sarif = json.loads(out.read_text())
+        assert sarif["runs"][0]["results"] == []
+        assert len(sarif["runs"][0]["tool"]["driver"]["rules"]) == 20

python_vibe_guard-0.7.1/pyvibe/__init__.py

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