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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-vibe-guard
-Version: 0.11.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
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
 
 # python-vibe-guard
 
@@ -177,6 +178,14 @@ python -m pyvibe explain PYVIBE-002
 python -m pyvibe baseline create src/     # snapshot current findings
 python -m pyvibe src/ --baseline          # only reports findings NOT in the baseline
 
+# 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
 ```
 
@@ -216,7 +225,7 @@ python -m pyvibe src/ --baseline          # only reports findings NOT in the bas
      Fix      : Use `asyncio.Lock()` with `async with lock:` instead
 
   ─────────────────────────────────────────────
-  4 violation(s) in 1 file(s)
+  4 reported · 0 suppressed
 ```
 
 `Suggested fix:` blocks are generated from the real code on the flagged line — they are
@@ -291,6 +300,103 @@ produces exit code `0`.
 and reviewed like any other file; gitignore it if each contributor/CI run should
 regenerate its own baseline instead.
 
+### Suppressing findings
+
+For one-off exceptions, use an inline comment right in the source:
+
+```python
+# pyvibe: ignore PYVIBE-008
+conn = sqlite3.connect(...)              # suppressed — standalone comment targets the next line
+
+conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008   # suppressed — trailing comment targets its own line
+
+time.sleep(n)  # pyvibe: ignore PYVIBE-001, PYVIBE-003     # multiple rules, comma-separated
+
+# pyvibe: ignore-next-line PYVIBE-008
+conn = sqlite3.connect(...)              # suppressed — always targets the next line
+```
+
+`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`):
+
+```toml
+[tool.pyvibe]
+ignore = ["PYVIBE-019"]
+exclude = ["tests/**", "examples/**", "docs/**"]
+
+[tool.pyvibe.severity]
+PYVIBE-008 = "warning"
+```
+
+- `ignore`: rule IDs suppressed everywhere, project-wide.
+- `exclude`: glob patterns (relative to the `pyvibe.toml` directory) for files/directories
+  to skip entirely.
+- `[tool.pyvibe.severity]`: per-rule severity override (`"critical"` or `"warning"`),
+  applied after the built-in test-file downgrade.
+
+Both mechanisms feed into the same summary line:
+
+```
+  4 reported · 2 suppressed
+```
+
+Add `--verbose` to see exactly what was suppressed and why:
+
+```
+  Suppressed:
+    PYVIBE-008 app/db.py:42 (inline)
+    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
@@ -388,7 +494,7 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-268 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, and baseline mode 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.11.0 → python_vibe_guard-0.12.1}/README.md

@@ -162,6 +162,14 @@ python -m pyvibe explain PYVIBE-002
 python -m pyvibe baseline create src/     # snapshot current findings
 python -m pyvibe src/ --baseline          # only reports findings NOT in the baseline
 
+# 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
 ```
 
@@ -201,7 +209,7 @@ python -m pyvibe src/ --baseline          # only reports findings NOT in the bas
      Fix      : Use `asyncio.Lock()` with `async with lock:` instead
 
   ─────────────────────────────────────────────
-  4 violation(s) in 1 file(s)
+  4 reported · 0 suppressed
 ```
 
 `Suggested fix:` blocks are generated from the real code on the flagged line — they are
@@ -276,6 +284,103 @@ produces exit code `0`.
 and reviewed like any other file; gitignore it if each contributor/CI run should
 regenerate its own baseline instead.
 
+### Suppressing findings
+
+For one-off exceptions, use an inline comment right in the source:
+
+```python
+# pyvibe: ignore PYVIBE-008
+conn = sqlite3.connect(...)              # suppressed — standalone comment targets the next line
+
+conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008   # suppressed — trailing comment targets its own line
+
+time.sleep(n)  # pyvibe: ignore PYVIBE-001, PYVIBE-003     # multiple rules, comma-separated
+
+# pyvibe: ignore-next-line PYVIBE-008
+conn = sqlite3.connect(...)              # suppressed — always targets the next line
+```
+
+`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`):
+
+```toml
+[tool.pyvibe]
+ignore = ["PYVIBE-019"]
+exclude = ["tests/**", "examples/**", "docs/**"]
+
+[tool.pyvibe.severity]
+PYVIBE-008 = "warning"
+```
+
+- `ignore`: rule IDs suppressed everywhere, project-wide.
+- `exclude`: glob patterns (relative to the `pyvibe.toml` directory) for files/directories
+  to skip entirely.
+- `[tool.pyvibe.severity]`: per-rule severity override (`"critical"` or `"warning"`),
+  applied after the built-in test-file downgrade.
+
+Both mechanisms feed into the same summary line:
+
+```
+  4 reported · 2 suppressed
+```
+
+Add `--verbose` to see exactly what was suppressed and why:
+
+```
+  Suppressed:
+    PYVIBE-008 app/db.py:42 (inline)
+    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
@@ -373,7 +478,7 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-268 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, and baseline mode 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.11.0 → python_vibe_guard-0.12.1}/pyproject.toml

@@ -4,10 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-vibe-guard"
-version = "0.11.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"
+dependencies = [
+    "tomli>=2.0.1; python_version < '3.11'",
+]
 license = {text = "MIT"}
 keywords = ["async", "linter", "fastapi", "asyncio", "static-analysis"]
 classifiers = [

{python_vibe_guard-0.11.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.11.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
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
 
 # python-vibe-guard
 
@@ -177,6 +178,14 @@ python -m pyvibe explain PYVIBE-002
 python -m pyvibe baseline create src/     # snapshot current findings
 python -m pyvibe src/ --baseline          # only reports findings NOT in the baseline
 
+# 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
 ```
 
@@ -216,7 +225,7 @@ python -m pyvibe src/ --baseline          # only reports findings NOT in the bas
      Fix      : Use `asyncio.Lock()` with `async with lock:` instead
 
   ─────────────────────────────────────────────
-  4 violation(s) in 1 file(s)
+  4 reported · 0 suppressed
 ```
 
 `Suggested fix:` blocks are generated from the real code on the flagged line — they are
@@ -291,6 +300,103 @@ produces exit code `0`.
 and reviewed like any other file; gitignore it if each contributor/CI run should
 regenerate its own baseline instead.
 
+### Suppressing findings
+
+For one-off exceptions, use an inline comment right in the source:
+
+```python
+# pyvibe: ignore PYVIBE-008
+conn = sqlite3.connect(...)              # suppressed — standalone comment targets the next line
+
+conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008   # suppressed — trailing comment targets its own line
+
+time.sleep(n)  # pyvibe: ignore PYVIBE-001, PYVIBE-003     # multiple rules, comma-separated
+
+# pyvibe: ignore-next-line PYVIBE-008
+conn = sqlite3.connect(...)              # suppressed — always targets the next line
+```
+
+`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`):
+
+```toml
+[tool.pyvibe]
+ignore = ["PYVIBE-019"]
+exclude = ["tests/**", "examples/**", "docs/**"]
+
+[tool.pyvibe.severity]
+PYVIBE-008 = "warning"
+```
+
+- `ignore`: rule IDs suppressed everywhere, project-wide.
+- `exclude`: glob patterns (relative to the `pyvibe.toml` directory) for files/directories
+  to skip entirely.
+- `[tool.pyvibe.severity]`: per-rule severity override (`"critical"` or `"warning"`),
+  applied after the built-in test-file downgrade.
+
+Both mechanisms feed into the same summary line:
+
+```
+  4 reported · 2 suppressed
+```
+
+Add `--verbose` to see exactly what was suppressed and why:
+
+```
+  Suppressed:
+    PYVIBE-008 app/db.py:42 (inline)
+    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
@@ -388,7 +494,7 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-268 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, and baseline mode 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.11.0 → python_vibe_guard-0.12.1}/python_vibe_guard.egg-info/SOURCES.txt

@@ -4,17 +4,21 @@ python_vibe_guard.egg-info/PKG-INFO
 python_vibe_guard.egg-info/SOURCES.txt
 python_vibe_guard.egg-info/dependency_links.txt
 python_vibe_guard.egg-info/entry_points.txt
+python_vibe_guard.egg-info/requires.txt
 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
+pyvibe/config.py
 pyvibe/diff.py
 pyvibe/explain.py
 pyvibe/rule_docs.py
 pyvibe/sarif.py
+pyvibe/suppressions.py
 pyvibe/rules/__init__.py
 pyvibe/rules/async_requests.py
 pyvibe/rules/async_sleep.py
@@ -37,9 +41,12 @@ 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
 tests/test_exclude.py
 tests/test_explain.py
 tests/test_rules.py
-tests/test_sarif.py
+tests/test_sarif.py
+tests/test_suppressions.py

python_vibe_guard-0.12.1/python_vibe_guard.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[:python_version < "3.11"]
+tomli>=2.0.1

python_vibe_guard-0.12.1/pyvibe/__init__.py

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

{python_vibe_guard-0.11.0 → python_vibe_guard-0.12.1}/pyvibe/analyzer.py

@@ -1,8 +1,10 @@
 import ast
 from pathlib import Path
-from typing import FrozenSet, List, Optional
+from typing import FrozenSet, List, Optional, Tuple
 
+from pyvibe.config import PyvibeConfig, is_excluded
 from pyvibe.rules.base import Violation
+from pyvibe.suppressions import parse_inline_suppressions
 from pyvibe.rules.async_sleep import AsyncSleepRule
 from pyvibe.rules.async_requests import AsyncRequestsRule
 from pyvibe.rules.asyncio_run import AsyncioRunRule
@@ -90,22 +92,29 @@ def _is_test_file(filepath: str) -> bool:
     )
 
 
-def analyze_source(
+def analyze_source_full(
     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.
+    config: Optional[PyvibeConfig] = None,
+) -> Tuple[List[Violation], List[Tuple[Violation, str]]]:
+    """Parse source and run all rules. Returns (reported, suppressed) where
+    suppressed is a list of (Violation, reason) with reason "inline" (a
+    `# pyvibe: ignore ...` comment) or "config" (pyvibe.toml's [tool.pyvibe]
+    ignore list).
 
     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.
+
+    config: optional PyvibeConfig (see pyvibe/config.py) applying a global
+    ignore list and per-rule severity overrides on top of the above.
     """
     try:
         tree = ast.parse(source)
     except SyntaxError:
-        return []
+        return [], []
 
     source_lines = source.splitlines()
     violations = []
@@ -124,8 +133,53 @@ def analyze_source(
             if v.rule_id in downgrade_in_tests:
                 v.severity = "WARNING"
 
+    if config and config.severity:
+        for v in violations:
+            if v.rule_id in config.severity:
+                v.severity = config.severity[v.rule_id]
+
     violations.sort(key=lambda v: v.line)
-    return violations
+
+    inline_suppressions = parse_inline_suppressions(source)
+    reported: List[Violation] = []
+    suppressed: List[Tuple[Violation, str]] = []
+    for v in violations:
+        if v.rule_id in inline_suppressions.get(v.line, frozenset()):
+            suppressed.append((v, "inline"))
+        elif config and v.rule_id in config.ignore:
+            suppressed.append((v, "config"))
+        else:
+            reported.append(v)
+
+    return reported, suppressed
+
+
+def analyze_source(
+    source: str,
+    filepath: str = "<string>",
+    *,
+    downgrade_in_tests: FrozenSet[str] = TEST_FILE_DOWNGRADE,
+    config: Optional[PyvibeConfig] = None,
+) -> List[Violation]:
+    """Parse source and run all rules. Returns the reported (non-suppressed)
+    violations — see analyze_source_full() for the suppressed ones too.
+    """
+    reported, _ = analyze_source_full(
+        source, filepath, downgrade_in_tests=downgrade_in_tests, config=config
+    )
+    return reported
+
+
+def analyze_file_full(
+    path: Path,
+    *,
+    downgrade_in_tests: FrozenSet[str] = TEST_FILE_DOWNGRADE,
+    config: Optional[PyvibeConfig] = None,
+) -> Tuple[List[Violation], List[Tuple[Violation, str]]]:
+    source = path.read_text(encoding="utf-8", errors="ignore")
+    return analyze_source_full(
+        source, filepath=str(path), downgrade_in_tests=downgrade_in_tests, config=config
+    )
 
 
 def analyze_file(
@@ -133,12 +187,15 @@ def analyze_file(
     *,
     downgrade_in_tests: FrozenSet[str] = TEST_FILE_DOWNGRADE,
     line_filter: Optional[FrozenSet[int]] = None,
+    config: Optional[PyvibeConfig] = None,
 ) -> List[Violation]:
     """line_filter: if given, only violations whose `line` is in this set
     are returned (used by `pyvibe review` to report only diff-touched lines).
     """
     source = path.read_text(encoding="utf-8", errors="ignore")
-    violations = analyze_source(source, filepath=str(path), downgrade_in_tests=downgrade_in_tests)
+    violations = analyze_source(
+        source, filepath=str(path), downgrade_in_tests=downgrade_in_tests, config=config
+    )
     if line_filter is not None:
         violations = [v for v in violations if v.line in line_filter]
     return violations
@@ -156,23 +213,55 @@ def analyze_directory(
     *,
     skip_test_files: bool = False,
     downgrade_in_tests: FrozenSet[str] = TEST_FILE_DOWNGRADE,
+    config: Optional[PyvibeConfig] = None,
 ) -> 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.
+    config: optional PyvibeConfig — files matching its exclude glob patterns
+    are also skipped entirely.
     """
     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 config and is_excluded(py_file, config):
+            continue
+        violations = analyze_file(py_file, downgrade_in_tests=downgrade_in_tests, config=config)
         if violations:
             results[py_file] = violations
     return results
 
 
+def analyze_directory_full(
+    root: Path,
+    exclude: frozenset = DEFAULT_EXCLUDES,
+    *,
+    skip_test_files: bool = False,
+    downgrade_in_tests: FrozenSet[str] = TEST_FILE_DOWNGRADE,
+    config: Optional[PyvibeConfig] = None,
+) -> Tuple[dict, List[Tuple[Path, Violation, str]]]:
+    """Like analyze_directory(), but also returns the suppressed findings
+    (across every scanned file) as a flat list of (path, Violation, reason).
+    """
+    results = {}
+    all_suppressed: List[Tuple[Path, Violation, str]] = []
+    for py_file in _walk(root, exclude):
+        if skip_test_files and _is_test_file(str(py_file)):
+            continue
+        if config and is_excluded(py_file, config):
+            continue
+        reported, suppressed = analyze_file_full(
+            py_file, downgrade_in_tests=downgrade_in_tests, config=config
+        )
+        if reported:
+            results[py_file] = reported
+        all_suppressed.extend((py_file, v, reason) for v, reason in suppressed)
+    return results, all_suppressed
+
+
 def _walk(root: Path, exclude: frozenset):
     """Yield .py files under root, skipping any directory in exclude."""
     for entry in sorted(root.iterdir()):