python-vibe-guard 0.12.0__tar.gz → 0.12.1__tar.gz

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-vibe-guard
-Version: 0.12.0
+Version: 0.12.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
@@ -181,6 +181,11 @@ python -m pyvibe src/ --baseline          # only reports findings NOT in the bas
 # Show suppressed findings (inline comments + pyvibe.toml) alongside the report
 python -m pyvibe src/ --verbose
 
+# Audit inline suppressions: justification coverage + orphaned (unused) suppressions
+python -m pyvibe audit src/
+python -m pyvibe audit src/ --json
+python -m pyvibe audit src/ --fail-on-unused --fail-on-unjustified
+
 # Exit code: 0 = clean, 1 = violations found, 2 = path error
 ```
 
@@ -314,6 +319,14 @@ conn = sqlite3.connect(...)              # suppressed — always targets the nex
 `pyvibe:` is case-insensitive. A directive with no recognizable `PYVIBE-XXX` id is ignored
 (treated as a regular comment).
 
+Add an optional justification after `--` — it's free text, stored and shown in `pyvibe audit`:
+
+```python
+conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008 -- legacy sqlite wrapper
+# pyvibe: ignore-next-line PYVIBE-008 -- startup only
+conn = sqlite3.connect(...)
+```
+
 For project-wide rules, add a `pyvibe.toml` next to your code (python-vibe-guard walks up
 from the scan target to find it, same convention as `pyproject.toml`):
 
@@ -346,6 +359,44 @@ Add `--verbose` to see exactly what was suppressed and why:
     PYVIBE-019 legacy.py:81 (config)
 ```
 
+### `pyvibe audit`
+
+Audits every inline `# pyvibe: ignore` comment in a codebase: how many carry a justification,
+and how many are **orphaned** — the rule they name never actually fires on the target line,
+usually because the underlying code changed since the suppression was added.
+
+```
+$ pyvibe audit src/
+
+Suppressions audit
+──────────────────
+Total suppressions: 12
+With justification: 9 (75%)
+Without justification: 3
+Unused (no violation found): 2
+
+By rule:
+PYVIBE-008   5
+PYVIBE-019   4
+PYVIBE-003   3
+
+Unused suppressions:
+app/legacy.py:41  # pyvibe: ignore PYVIBE-008
+
+Without justification:
+models/db.py:88  # pyvibe: ignore PYVIBE-019
+```
+
+- `--json` — machine-readable output (`total`, `with_justification`, `without_justification`,
+  `unused`, `by_rule`, `unused_suppressions`, `without_justification_suppressions`).
+- `--fail-on-unused` — exit `1` if any orphaned suppression is found.
+- `--fail-on-unjustified` — exit `1` if any suppression is missing a justification.
+- `--max-unused N` — exit `1` if more than `N` orphaned suppressions are found.
+- `--exclude DIR` — same directory-exclusion convention as `pyvibe scan`.
+
+With no flags, `pyvibe audit` is purely informational (exit `0`) — the flags above are what
+you wire into CI to enforce a justification/cleanup policy over time.
+
 ---
 
 ## CI/CD integration
@@ -443,7 +494,7 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-309 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, and suppressions (inline comments + pyvibe.toml) coverage.
+331 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, suppressions (inline comments + pyvibe.toml), and `pyvibe audit` (justifications + orphan detection) coverage.
 
 ---
 

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.1}/README.md

@@ -165,6 +165,11 @@ python -m pyvibe src/ --baseline          # only reports findings NOT in the bas
 # Show suppressed findings (inline comments + pyvibe.toml) alongside the report
 python -m pyvibe src/ --verbose
 
+# Audit inline suppressions: justification coverage + orphaned (unused) suppressions
+python -m pyvibe audit src/
+python -m pyvibe audit src/ --json
+python -m pyvibe audit src/ --fail-on-unused --fail-on-unjustified
+
 # Exit code: 0 = clean, 1 = violations found, 2 = path error
 ```
 
@@ -298,6 +303,14 @@ conn = sqlite3.connect(...)              # suppressed — always targets the nex
 `pyvibe:` is case-insensitive. A directive with no recognizable `PYVIBE-XXX` id is ignored
 (treated as a regular comment).
 
+Add an optional justification after `--` — it's free text, stored and shown in `pyvibe audit`:
+
+```python
+conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008 -- legacy sqlite wrapper
+# pyvibe: ignore-next-line PYVIBE-008 -- startup only
+conn = sqlite3.connect(...)
+```
+
 For project-wide rules, add a `pyvibe.toml` next to your code (python-vibe-guard walks up
 from the scan target to find it, same convention as `pyproject.toml`):
 
@@ -330,6 +343,44 @@ Add `--verbose` to see exactly what was suppressed and why:
     PYVIBE-019 legacy.py:81 (config)
 ```
 
+### `pyvibe audit`
+
+Audits every inline `# pyvibe: ignore` comment in a codebase: how many carry a justification,
+and how many are **orphaned** — the rule they name never actually fires on the target line,
+usually because the underlying code changed since the suppression was added.
+
+```
+$ pyvibe audit src/
+
+Suppressions audit
+──────────────────
+Total suppressions: 12
+With justification: 9 (75%)
+Without justification: 3
+Unused (no violation found): 2
+
+By rule:
+PYVIBE-008   5
+PYVIBE-019   4
+PYVIBE-003   3
+
+Unused suppressions:
+app/legacy.py:41  # pyvibe: ignore PYVIBE-008
+
+Without justification:
+models/db.py:88  # pyvibe: ignore PYVIBE-019
+```
+
+- `--json` — machine-readable output (`total`, `with_justification`, `without_justification`,
+  `unused`, `by_rule`, `unused_suppressions`, `without_justification_suppressions`).
+- `--fail-on-unused` — exit `1` if any orphaned suppression is found.
+- `--fail-on-unjustified` — exit `1` if any suppression is missing a justification.
+- `--max-unused N` — exit `1` if more than `N` orphaned suppressions are found.
+- `--exclude DIR` — same directory-exclusion convention as `pyvibe scan`.
+
+With no flags, `pyvibe audit` is purely informational (exit `0`) — the flags above are what
+you wire into CI to enforce a justification/cleanup policy over time.
+
 ---
 
 ## CI/CD integration
@@ -427,7 +478,7 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-309 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, and suppressions (inline comments + pyvibe.toml) coverage.
+331 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, suppressions (inline comments + pyvibe.toml), and `pyvibe audit` (justifications + orphan detection) coverage.
 
 ---
 

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-vibe-guard"
-version = "0.12.0"
+version = "0.12.1"
 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.12.0 → python_vibe_guard-0.12.1}/python_vibe_guard.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-vibe-guard
-Version: 0.12.0
+Version: 0.12.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
@@ -181,6 +181,11 @@ python -m pyvibe src/ --baseline          # only reports findings NOT in the bas
 # Show suppressed findings (inline comments + pyvibe.toml) alongside the report
 python -m pyvibe src/ --verbose
 
+# Audit inline suppressions: justification coverage + orphaned (unused) suppressions
+python -m pyvibe audit src/
+python -m pyvibe audit src/ --json
+python -m pyvibe audit src/ --fail-on-unused --fail-on-unjustified
+
 # Exit code: 0 = clean, 1 = violations found, 2 = path error
 ```
 
@@ -314,6 +319,14 @@ conn = sqlite3.connect(...)              # suppressed — always targets the nex
 `pyvibe:` is case-insensitive. A directive with no recognizable `PYVIBE-XXX` id is ignored
 (treated as a regular comment).
 
+Add an optional justification after `--` — it's free text, stored and shown in `pyvibe audit`:
+
+```python
+conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008 -- legacy sqlite wrapper
+# pyvibe: ignore-next-line PYVIBE-008 -- startup only
+conn = sqlite3.connect(...)
+```
+
 For project-wide rules, add a `pyvibe.toml` next to your code (python-vibe-guard walks up
 from the scan target to find it, same convention as `pyproject.toml`):
 
@@ -346,6 +359,44 @@ Add `--verbose` to see exactly what was suppressed and why:
     PYVIBE-019 legacy.py:81 (config)
 ```
 
+### `pyvibe audit`
+
+Audits every inline `# pyvibe: ignore` comment in a codebase: how many carry a justification,
+and how many are **orphaned** — the rule they name never actually fires on the target line,
+usually because the underlying code changed since the suppression was added.
+
+```
+$ pyvibe audit src/
+
+Suppressions audit
+──────────────────
+Total suppressions: 12
+With justification: 9 (75%)
+Without justification: 3
+Unused (no violation found): 2
+
+By rule:
+PYVIBE-008   5
+PYVIBE-019   4
+PYVIBE-003   3
+
+Unused suppressions:
+app/legacy.py:41  # pyvibe: ignore PYVIBE-008
+
+Without justification:
+models/db.py:88  # pyvibe: ignore PYVIBE-019
+```
+
+- `--json` — machine-readable output (`total`, `with_justification`, `without_justification`,
+  `unused`, `by_rule`, `unused_suppressions`, `without_justification_suppressions`).
+- `--fail-on-unused` — exit `1` if any orphaned suppression is found.
+- `--fail-on-unjustified` — exit `1` if any suppression is missing a justification.
+- `--max-unused N` — exit `1` if more than `N` orphaned suppressions are found.
+- `--exclude DIR` — same directory-exclusion convention as `pyvibe scan`.
+
+With no flags, `pyvibe audit` is purely informational (exit `0`) — the flags above are what
+you wire into CI to enforce a justification/cleanup policy over time.
+
 ---
 
 ## CI/CD integration
@@ -443,7 +494,7 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-309 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, and suppressions (inline comments + pyvibe.toml) coverage.
+331 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, suppressions (inline comments + pyvibe.toml), and `pyvibe audit` (justifications + orphan detection) coverage.
 
 ---
 

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.1}/python_vibe_guard.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ python_vibe_guard.egg-info/top_level.txt
 pyvibe/__init__.py
 pyvibe/__main__.py
 pyvibe/analyzer.py
+pyvibe/audit.py
 pyvibe/autofix.py
 pyvibe/baseline.py
 pyvibe/cli.py
@@ -40,6 +41,7 @@ pyvibe/rules/sqlite_async.py
 pyvibe/rules/subprocess_async.py
 pyvibe/rules/threading_lock.py
 pyvibe/rules/while_true_no_await.py
+tests/test_audit.py
 tests/test_baseline.py
 tests/test_config.py
 tests/test_diff.py

python_vibe_guard-0.12.1/pyvibe/__init__.py

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

python_vibe_guard-0.12.1/pyvibe/audit.py

@@ -0,0 +1,119 @@
+"""Suppressions audit — `pyvibe audit`.
+
+Cross-references every `# pyvibe: ignore ...` directive found in a file
+against that file's actual violations to answer three questions per
+suppression: does it carry a justification, is it actually suppressing a
+real violation (or is it "orphaned" — no violation of that rule ever
+occurs on the target line), and how do these break down project-wide.
+"""
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from pyvibe.analyzer import DEFAULT_EXCLUDES, _walk, analyze_source_full
+from pyvibe.config import PyvibeConfig, is_excluded
+from pyvibe.suppressions import parse_inline_suppression_directives
+
+
+@dataclass(frozen=True)
+class SuppressionRecord:
+    """One inline suppression, exploded per rule_id (a directive naming
+    multiple rule IDs — `# pyvibe: ignore PYVIBE-008, PYVIBE-019` — yields
+    one record per rule ID, all sharing the same lines/justification).
+    """
+
+    filepath: str
+    comment_line: int
+    target_line: int
+    directive: str
+    rule_id: str
+    justification: Optional[str]
+    used: bool  # False == orphaned: no violation of rule_id found on target_line
+
+
+def audit_file(path: Path, config: Optional[PyvibeConfig] = None) -> List[SuppressionRecord]:
+    source = path.read_text(encoding="utf-8", errors="ignore")
+    _, suppressed = analyze_source_full(source, filepath=str(path), config=config)
+    used_keys = {(v.line, v.rule_id) for v, reason in suppressed if reason == "inline"}
+
+    records = []
+    for directive in parse_inline_suppression_directives(source):
+        for rule_id in sorted(directive.rule_ids):
+            records.append(
+                SuppressionRecord(
+                    filepath=str(path),
+                    comment_line=directive.comment_line,
+                    target_line=directive.target_line,
+                    directive=directive.directive,
+                    rule_id=rule_id,
+                    justification=directive.justification,
+                    used=(directive.target_line, rule_id) in used_keys,
+                )
+            )
+    return records
+
+
+def audit_directory(
+    root: Path,
+    exclude: frozenset = DEFAULT_EXCLUDES,
+    *,
+    config: Optional[PyvibeConfig] = None,
+) -> List[SuppressionRecord]:
+    records: List[SuppressionRecord] = []
+    for py_file in _walk(root, exclude):
+        if config and is_excluded(py_file, config):
+            continue
+        records.extend(audit_file(py_file, config=config))
+    return records
+
+
+def audit_path(
+    target: Path,
+    exclude: frozenset = DEFAULT_EXCLUDES,
+    *,
+    config: Optional[PyvibeConfig] = None,
+) -> List[SuppressionRecord]:
+    """audit_file()/audit_directory(), dispatching on whether target is a
+    file or a directory — same convention as analyzer.analyze_file/_directory.
+    """
+    if target.is_file():
+        if target.suffix != ".py":
+            return []
+        if config and is_excluded(target, config):
+            return []
+        return audit_file(target, config=config)
+    return audit_directory(target, exclude=exclude, config=config)
+
+
+@dataclass(frozen=True)
+class AuditSummary:
+    total: int
+    with_justification: int
+    without_justification: int
+    unused: int
+    by_rule: Dict[str, int]
+    unused_records: List[SuppressionRecord]
+    unjustified_records: List[SuppressionRecord]
+
+
+def summarize(records: List[SuppressionRecord]) -> AuditSummary:
+    total = len(records)
+    with_justification = sum(1 for r in records if r.justification)
+    unjustified_records = [r for r in records if not r.justification]
+    unused_records = [r for r in records if not r.used]
+
+    by_rule: Dict[str, int] = {}
+    for r in records:
+        by_rule[r.rule_id] = by_rule.get(r.rule_id, 0) + 1
+    # Most-suppressed rule first; rule_id ascending breaks ties.
+    by_rule = dict(sorted(by_rule.items(), key=lambda kv: (-kv[1], kv[0])))
+
+    return AuditSummary(
+        total=total,
+        with_justification=with_justification,
+        without_justification=len(unjustified_records),
+        unused=len(unused_records),
+        by_rule=by_rule,
+        unused_records=unused_records,
+        unjustified_records=unjustified_records,
+    )

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.1}/pyvibe/cli.py

@@ -16,11 +16,13 @@ Usage:
     python -m pyvibe <path> --baseline        # scan, suppressing findings already in the baseline
     python -m pyvibe scan <path> --baseline   # equivalent, explicit subcommand form
     python -m pyvibe <path> --verbose         # also list suppressed findings (inline / pyvibe.toml)
+    python -m pyvibe audit [path]             # audit inline suppressions: justification + orphan usage
 
 Suppressing findings:
     # pyvibe: ignore PYVIBE-008              (same line, or the next non-comment line if standalone)
     # pyvibe: ignore PYVIBE-008, PYVIBE-003  (multiple rules)
     # pyvibe: ignore-next-line PYVIBE-008    (always the next line)
+    # pyvibe: ignore PYVIBE-008 -- reason    (optional justification, shown in `pyvibe audit`)
 See pyvibe.toml for project-wide ignore / exclude / severity overrides.
 """
 import argparse
@@ -61,6 +63,10 @@ def main():
         _main_scan(sys.argv[2:])
         return
 
+    if len(sys.argv) > 1 and sys.argv[1] == "audit":
+        _main_audit(sys.argv[2:])
+        return
+
     parser = argparse.ArgumentParser(
         prog="pyvibe",
         description="Detect runtime anti-patterns in async Python code",
@@ -518,6 +524,134 @@ def _main_baseline(argv):
     sys.exit(0)
 
 
+def _main_audit(argv):
+    parser = argparse.ArgumentParser(
+        prog="pyvibe audit",
+        description="Audit inline `# pyvibe: ignore` suppressions: justification coverage + orphaned (unused) suppressions",
+    )
+    parser.add_argument("path", nargs="?", default=".", help="File or directory to audit (default: current directory)")
+    parser.add_argument(
+        "--exclude",
+        metavar="DIR",
+        action="append",
+        default=[],
+        help="Directory name to exclude (can be repeated)",
+    )
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    parser.add_argument(
+        "--fail-on-unused",
+        action="store_true",
+        help="Exit 1 if any orphaned suppression is found (no violation on its target line)",
+    )
+    parser.add_argument(
+        "--fail-on-unjustified",
+        action="store_true",
+        help="Exit 1 if any suppression is missing a `-- justification`",
+    )
+    parser.add_argument(
+        "--max-unused",
+        metavar="N",
+        type=int,
+        default=None,
+        help="Exit 1 if more than N orphaned suppressions are found",
+    )
+    args = parser.parse_args(argv)
+
+    from pyvibe.audit import audit_path, summarize
+
+    target = Path(args.path)
+    if not target.exists():
+        print(f"Error: {target} does not exist", file=sys.stderr)
+        sys.exit(2)
+
+    config = _load_config_or_exit(target)
+    exclude = DEFAULT_EXCLUDES | frozenset(args.exclude)
+
+    records = audit_path(target, exclude=exclude, config=config)
+    summary = summarize(records)
+
+    if args.json:
+        _print_audit_json(summary)
+    else:
+        _print_audit_human(summary)
+
+    failed = (
+        (args.fail_on_unused and summary.unused > 0)
+        or (args.fail_on_unjustified and summary.without_justification > 0)
+        or (args.max_unused is not None and summary.unused > args.max_unused)
+    )
+    sys.exit(1 if failed else 0)
+
+
+def _format_directive(record) -> str:
+    return f"# pyvibe: {record.directive} {record.rule_id}"
+
+
+def _print_audit_human(summary):
+    print()
+    title = "Suppressions audit"
+    print(title)
+    print("─" * len(title))
+
+    if summary.total == 0:
+        print("No suppressions found.")
+        print()
+        return
+
+    pct = round(summary.with_justification / summary.total * 100)
+    print(f"Total suppressions: {summary.total}")
+    print(f"With justification: {summary.with_justification} ({pct}%)")
+    print(f"Without justification: {summary.without_justification}")
+    print(f"Unused (no violation found): {summary.unused}")
+    print()
+
+    print("By rule:")
+    for rule_id, count in summary.by_rule.items():
+        print(f"{rule_id:<12} {count}")
+    print()
+
+    if summary.unused_records:
+        print("Unused suppressions:")
+        for r in summary.unused_records:
+            print(f"{r.filepath}:{r.comment_line}  {_format_directive(r)}")
+        print()
+
+    if summary.unjustified_records:
+        print("Without justification:")
+        for r in summary.unjustified_records:
+            print(f"{r.filepath}:{r.comment_line}  {_format_directive(r)}")
+        print()
+
+
+def _print_audit_json(summary):
+    output = {
+        "total": summary.total,
+        "with_justification": summary.with_justification,
+        "without_justification": summary.without_justification,
+        "unused": summary.unused,
+        "by_rule": summary.by_rule,
+        "unused_suppressions": [
+            {
+                "file": r.filepath,
+                "line": r.comment_line,
+                "rule_id": r.rule_id,
+                "justification": r.justification,
+            }
+            for r in summary.unused_records
+        ],
+        "without_justification_suppressions": [
+            {
+                "file": r.filepath,
+                "line": r.comment_line,
+                "rule_id": r.rule_id,
+                "justification": r.justification,
+            }
+            for r in summary.unjustified_records
+        ],
+    }
+    print(json.dumps(output, indent=2))
+
+
 def _main_explain(argv):
     parser = argparse.ArgumentParser(
         prog="pyvibe explain",

python_vibe_guard-0.12.1/pyvibe/suppressions.py

@@ -0,0 +1,102 @@
+"""Inline suppression comments — `# pyvibe: ignore PYVIBE-XXX[, PYVIBE-YYY]`
+and `# pyvibe: ignore-next-line PYVIBE-XXX`, optionally followed by
+`-- justification text`:
+
+    # pyvibe: ignore PYVIBE-008 -- legacy sqlite wrapper
+    # pyvibe: ignore-next-line PYVIBE-008 -- startup only
+
+Parsed directly from the source text being analyzed (no filesystem I/O),
+so — unlike pyvibe.toml (see pyvibe/config.py) — this is always active with
+no opt-in required.
+"""
+import re
+from dataclasses import dataclass
+from typing import Dict, FrozenSet, List, Optional, Set
+
+_DIRECTIVE_RE = re.compile(
+    r"#\s*pyvibe\s*:\s*(?P<directive>ignore-next-line|ignore)\b(?P<rest>[^\n]*)",
+    re.IGNORECASE,
+)
+_RULE_ID_RE = re.compile(r"PYVIBE-\d{3}", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class SuppressionDirective:
+    """A single parsed `# pyvibe: ignore ...` comment.
+
+    comment_line: the physical line the comment itself is written on.
+    target_line: the line whose violations it suppresses (see module-level
+    ignore/ignore-next-line semantics below).
+    directive: "ignore" or "ignore-next-line", as written.
+    rule_ids: the rule IDs named in the directive (never empty).
+    justification: free text after `--`, or None if not given.
+    """
+
+    comment_line: int
+    target_line: int
+    directive: str
+    rule_ids: FrozenSet[str]
+    justification: Optional[str]
+
+
+def parse_inline_suppression_directives(source: str) -> List[SuppressionDirective]:
+    """Returns every `# pyvibe: ignore[-next-line] ...` directive found in
+    `source`, in file order.
+
+    A directive comment is "standalone" if nothing but whitespace precedes
+    the `#` on its physical line; otherwise it's "trailing" on a code line.
+
+    - `ignore-next-line` always targets the line right after the comment.
+    - `ignore` targets its OWN line when trailing on code (the common case:
+      `conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008`), or the
+      FOLLOWING line when standalone — so a bare `# pyvibe: ignore X` on its
+      own line directly above the flagged code also works, same as
+      `ignore-next-line`.
+    """
+    directives: List[SuppressionDirective] = []
+
+    for lineno, line in enumerate(source.splitlines(), start=1):
+        match = _DIRECTIVE_RE.search(line)
+        if not match:
+            continue
+
+        rest = match.group("rest")
+        if "--" in rest:
+            rule_part, justification_part = rest.split("--", 1)
+            justification = justification_part.strip() or None
+        else:
+            rule_part, justification = rest, None
+
+        rule_ids = frozenset(rid.upper() for rid in _RULE_ID_RE.findall(rule_part))
+        if not rule_ids:
+            continue  # directive with no recognizable rule ID — not our comment
+
+        directive = match.group("directive").lower()
+        is_standalone = line[: match.start()].strip() == ""
+
+        target_line = lineno + 1 if (directive == "ignore-next-line" or is_standalone) else lineno
+
+        directives.append(
+            SuppressionDirective(
+                comment_line=lineno,
+                target_line=target_line,
+                directive=directive,
+                rule_ids=rule_ids,
+                justification=justification,
+            )
+        )
+
+    return directives
+
+
+def parse_inline_suppressions(source: str) -> Dict[int, FrozenSet[str]]:
+    """Returns {line_number: {rule_id, ...}} — 1-indexed line numbers whose
+    violations should be suppressed. See parse_inline_suppression_directives()
+    for the full per-directive detail (justification, comment line, etc.).
+    """
+    suppressions: Dict[int, Set[str]] = {}
+
+    for directive in parse_inline_suppression_directives(source):
+        suppressions.setdefault(directive.target_line, set()).update(directive.rule_ids)
+
+    return {line: frozenset(ids) for line, ids in suppressions.items()}

python_vibe_guard-0.12.1/tests/test_audit.py

@@ -0,0 +1,274 @@
+"""Tests for v0.12b: suppression justifications + `pyvibe audit`
+(pyvibe/suppressions.py's justification parsing, pyvibe/audit.py, and the
+`pyvibe audit` CLI subcommand)."""
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from pyvibe.audit import audit_directory, audit_file, summarize
+from pyvibe.suppressions import parse_inline_suppression_directives, parse_inline_suppressions
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+# ─── justification parsing (parse_inline_suppression_directives) ───────────
+
+def test_trailing_directive_with_justification():
+    src = 'conn = sqlite3.connect("x")  # pyvibe: ignore PYVIBE-008 -- legacy sqlite wrapper\n'
+    directives = parse_inline_suppression_directives(src)
+    assert len(directives) == 1
+    d = directives[0]
+    assert d.rule_ids == frozenset({"PYVIBE-008"})
+    assert d.justification == "legacy sqlite wrapper"
+    assert d.comment_line == 1
+    assert d.target_line == 1
+    assert d.directive == "ignore"
+
+
+def test_ignore_next_line_with_justification():
+    src = "# pyvibe: ignore-next-line PYVIBE-008 -- startup only\nconn = sqlite3.connect(\"x\")\n"
+    directives = parse_inline_suppression_directives(src)
+    assert len(directives) == 1
+    d = directives[0]
+    assert d.justification == "startup only"
+    assert d.comment_line == 1
+    assert d.target_line == 2
+    assert d.directive == "ignore-next-line"
+
+
+def test_directive_without_justification_is_none():
+    src = 'conn = sqlite3.connect("x")  # pyvibe: ignore PYVIBE-008\n'
+    d = parse_inline_suppression_directives(src)[0]
+    assert d.justification is None
+
+
+def test_justification_is_stripped_of_whitespace():
+    src = 'conn = sqlite3.connect("x")  # pyvibe: ignore PYVIBE-008 --   padded reason   \n'
+    d = parse_inline_suppression_directives(src)[0]
+    assert d.justification == "padded reason"
+
+
+def test_empty_justification_after_dashes_is_none():
+    src = 'conn = sqlite3.connect("x")  # pyvibe: ignore PYVIBE-008 --\n'
+    d = parse_inline_suppression_directives(src)[0]
+    assert d.justification is None
+
+
+def test_multiple_rule_ids_share_one_justification():
+    src = 'time.sleep(1)  # pyvibe: ignore PYVIBE-001, PYVIBE-003 -- benchmarked delay\n'
+    d = parse_inline_suppression_directives(src)[0]
+    assert d.rule_ids == frozenset({"PYVIBE-001", "PYVIBE-003"})
+    assert d.justification == "benchmarked delay"
+
+
+def test_parse_inline_suppressions_still_ignores_justification_text():
+    # backward-compat: the simpler dict API used by analyzer.py doesn't
+    # expose justifications, only {line: {rule_ids}}.
+    src = 'conn = sqlite3.connect("x")  # pyvibe: ignore PYVIBE-008 -- legacy\n'
+    assert parse_inline_suppressions(src) == {1: frozenset({"PYVIBE-008"})}
+
+
+# ─── orphan / unused suppression detection (pyvibe/audit.py) ───────────────
+
+USED_AND_ORPHAN_SRC = """\
+import sqlite3
+import time
+
+async def handler():
+    conn = sqlite3.connect("db.sqlite")  # pyvibe: ignore PYVIBE-008 -- legacy sqlite wrapper
+    return conn
+
+def unrelated():
+    x = 1  # pyvibe: ignore PYVIBE-019
+    return x
+"""
+
+
+def test_audit_file_marks_used_suppression(tmp_path):
+    f = tmp_path / "app.py"
+    f.write_text(USED_AND_ORPHAN_SRC)
+
+    records = audit_file(f)
+    used = [r for r in records if r.rule_id == "PYVIBE-008"]
+    assert len(used) == 1
+    assert used[0].used is True
+    assert used[0].justification == "legacy sqlite wrapper"
+
+
+def test_audit_file_marks_orphan_suppression(tmp_path):
+    f = tmp_path / "app.py"
+    f.write_text(USED_AND_ORPHAN_SRC)
+
+    records = audit_file(f)
+    orphan = [r for r in records if r.rule_id == "PYVIBE-019"]
+    assert len(orphan) == 1
+    assert orphan[0].used is False
+    assert orphan[0].justification is None
+    assert orphan[0].comment_line == 9
+
+
+def test_audit_directory_aggregates_across_files(tmp_path):
+    (tmp_path / "app.py").write_text(USED_AND_ORPHAN_SRC)
+    (tmp_path / "clean.py").write_text("x = 1\n")
+
+    records = audit_directory(tmp_path)
+    assert len(records) == 2
+    assert {r.rule_id for r in records} == {"PYVIBE-008", "PYVIBE-019"}
+
+
+# ─── summarize() ────────────────────────────────────────────────────────────
+
+def test_summarize_counts_and_by_rule(tmp_path):
+    (tmp_path / "app.py").write_text(USED_AND_ORPHAN_SRC)
+    records = audit_directory(tmp_path)
+
+    summary = summarize(records)
+
+    assert summary.total == 2
+    assert summary.with_justification == 1
+    assert summary.without_justification == 1
+    assert summary.unused == 1
+    assert summary.by_rule == {"PYVIBE-008": 1, "PYVIBE-019": 1}
+    assert [r.rule_id for r in summary.unused_records] == ["PYVIBE-019"]
+    assert [r.rule_id for r in summary.unjustified_records] == ["PYVIBE-019"]
+
+
+def test_summarize_empty_records():
+    summary = summarize([])
+    assert summary.total == 0
+    assert summary.with_justification == 0
+    assert summary.without_justification == 0
+    assert summary.unused == 0
+    assert summary.by_rule == {}
+    assert summary.unused_records == []
+    assert summary.unjustified_records == []
+
+
+def test_summarize_by_rule_sorted_by_count_desc():
+    from pyvibe.audit import SuppressionRecord
+
+    records = [
+        SuppressionRecord("f.py", 1, 1, "ignore", "PYVIBE-008", None, True),
+        SuppressionRecord("f.py", 1, 1, "ignore", "PYVIBE-008", None, True),
+        SuppressionRecord("f.py", 2, 2, "ignore", "PYVIBE-019", None, True),
+        SuppressionRecord("f.py", 2, 2, "ignore", "PYVIBE-019", None, True),
+        SuppressionRecord("f.py", 3, 3, "ignore", "PYVIBE-019", None, True),
+        SuppressionRecord("f.py", 4, 4, "ignore", "PYVIBE-003", None, True),
+    ]
+    summary = summarize(records)
+    assert list(summary.by_rule.items()) == [
+        ("PYVIBE-019", 3),
+        ("PYVIBE-008", 2),
+        ("PYVIBE-003", 1),
+    ]
+
+
+# ─── `pyvibe audit` CLI (subprocess, human + --json + exit codes) ─────────
+
+def _run_cli(args, cwd):
+    env = {**os.environ, "PYTHONPATH": str(REPO_ROOT)}
+    return subprocess.run(
+        [sys.executable, "-m", "pyvibe", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+
+def test_cli_audit_human_output(tmp_path):
+    (tmp_path / "app.py").write_text(USED_AND_ORPHAN_SRC)
+
+    result = _run_cli(["audit", "."], cwd=tmp_path)
+
+    assert result.returncode == 0
+    assert "Suppressions audit" in result.stdout
+    assert "Total suppressions: 2" in result.stdout
+    assert "With justification: 1 (50%)" in result.stdout
+    assert "Without justification: 1" in result.stdout
+    assert "Unused (no violation found): 1" in result.stdout
+    assert "By rule:" in result.stdout
+    assert "PYVIBE-008" in result.stdout
+    assert "Unused suppressions:" in result.stdout
+    assert "app.py:9" in result.stdout
+    assert "Without justification:" in result.stdout
+
+
+def test_cli_audit_no_suppressions(tmp_path):
+    (tmp_path / "clean.py").write_text("x = 1\n")
+
+    result = _run_cli(["audit", "."], cwd=tmp_path)
+
+    assert result.returncode == 0
+    assert "No suppressions found." in result.stdout
+
+
+def test_cli_audit_json_output(tmp_path):
+    (tmp_path / "app.py").write_text(USED_AND_ORPHAN_SRC)
+
+    result = _run_cli(["audit", ".", "--json"], cwd=tmp_path)
+
+    assert result.returncode == 0
+    data = json.loads(result.stdout)
+    assert data["total"] == 2
+    assert data["with_justification"] == 1
+    assert data["without_justification"] == 1
+    assert data["unused"] == 1
+    assert data["by_rule"] == {"PYVIBE-008": 1, "PYVIBE-019": 1}
+    assert len(data["unused_suppressions"]) == 1
+    assert data["unused_suppressions"][0]["rule_id"] == "PYVIBE-019"
+    assert data["unused_suppressions"][0]["line"] == 9
+    assert len(data["without_justification_suppressions"]) == 1
+
+
+def test_cli_audit_fail_on_unused_exits_1(tmp_path):
+    (tmp_path / "app.py").write_text(USED_AND_ORPHAN_SRC)
+
+    result = _run_cli(["audit", ".", "--fail-on-unused"], cwd=tmp_path)
+
+    assert result.returncode == 1
+
+
+def test_cli_audit_fail_on_unjustified_exits_1(tmp_path):
+    (tmp_path / "app.py").write_text(USED_AND_ORPHAN_SRC)
+
+    result = _run_cli(["audit", ".", "--fail-on-unjustified"], cwd=tmp_path)
+
+    assert result.returncode == 1
+
+
+def test_cli_audit_max_unused_triggers_failure(tmp_path):
+    (tmp_path / "app.py").write_text(USED_AND_ORPHAN_SRC)
+
+    result = _run_cli(["audit", ".", "--max-unused", "0"], cwd=tmp_path)
+    assert result.returncode == 1
+
+    result = _run_cli(["audit", ".", "--max-unused", "5"], cwd=tmp_path)
+    assert result.returncode == 0
+
+
+def test_cli_audit_no_flags_exits_0_even_with_unused(tmp_path):
+    (tmp_path / "app.py").write_text(USED_AND_ORPHAN_SRC)
+
+    result = _run_cli(["audit", "."], cwd=tmp_path)
+
+    assert result.returncode == 0
+
+
+def test_cli_audit_defaults_to_current_directory(tmp_path):
+    (tmp_path / "app.py").write_text(USED_AND_ORPHAN_SRC)
+
+    result = _run_cli(["audit"], cwd=tmp_path)
+
+    assert result.returncode == 0
+    assert "Total suppressions: 2" in result.stdout
+
+
+def test_cli_audit_missing_path_errors(tmp_path):
+    result = _run_cli(["audit", "does-not-exist"], cwd=tmp_path)
+    assert result.returncode == 2
+    assert "does not exist" in result.stderr

python_vibe_guard-0.12.0/pyvibe/__init__.py

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

python_vibe_guard-0.12.0/pyvibe/suppressions.py

@@ -1,53 +0,0 @@
-"""Inline suppression comments — `# pyvibe: ignore PYVIBE-XXX[, PYVIBE-YYY]`
-and `# pyvibe: ignore-next-line PYVIBE-XXX`.
-
-Parsed directly from the source text being analyzed (no filesystem I/O),
-so — unlike pyvibe.toml (see pyvibe/config.py) — this is always active with
-no opt-in required.
-"""
-import re
-from typing import Dict, FrozenSet, Set
-
-_DIRECTIVE_RE = re.compile(
-    r"#\s*pyvibe\s*:\s*(?P<directive>ignore-next-line|ignore)\b(?P<rule_ids>[^\n]*)",
-    re.IGNORECASE,
-)
-_RULE_ID_RE = re.compile(r"PYVIBE-\d{3}", re.IGNORECASE)
-
-
-def parse_inline_suppressions(source: str) -> Dict[int, FrozenSet[str]]:
-    """Returns {line_number: {rule_id, ...}} — 1-indexed line numbers whose
-    violations should be suppressed.
-
-    A directive comment is "standalone" if nothing but whitespace precedes
-    the `#` on its physical line; otherwise it's "trailing" on a code line.
-
-    - `ignore-next-line` always targets the line right after the comment.
-    - `ignore` targets its OWN line when trailing on code (the common case:
-      `conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008`), or the
-      FOLLOWING line when standalone — so a bare `# pyvibe: ignore X` on its
-      own line directly above the flagged code also works, same as
-      `ignore-next-line`.
-    """
-    suppressions: Dict[int, Set[str]] = {}
-
-    for lineno, line in enumerate(source.splitlines(), start=1):
-        match = _DIRECTIVE_RE.search(line)
-        if not match:
-            continue
-
-        rule_ids = {rid.upper() for rid in _RULE_ID_RE.findall(match.group("rule_ids"))}
-        if not rule_ids:
-            continue  # directive with no recognizable rule ID — not our comment
-
-        directive = match.group("directive").lower()
-        is_standalone = line[: match.start()].strip() == ""
-
-        if directive == "ignore-next-line" or is_standalone:
-            target_line = lineno + 1
-        else:
-            target_line = lineno
-
-        suppressions.setdefault(target_line, set()).update(rule_ids)
-
-    return {line: frozenset(ids) for line, ids in suppressions.items()}