ballpython 2.0.0__py3-none-any.whl → 2.0.3__py3-none-any.whl

ballpython-2.0.3.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: ballpython
+Version: 2.0.3
+Summary: The Ultimate Static Python Intelligence, Healing, Type Verification, and Security Suite
+Author: Developer
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ruff>=0.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: isort>=5.13.0; extra == "dev"
+Provides-Extra: security
+Requires-Dist: cryptography>=41.0.0; extra == "security"
+Requires-Dist: defusedxml>=0.7.1; extra == "security"
+
+# ballpython
+
+[![PyPI version](https://img.shields.io/pypi/v/ballpython.svg)](https://pypi.org/project/ballpython/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/ballpython.svg)](https://pypi.org/project/ballpython/)
+[![CI](https://github.com/moonrox420/ball-python/actions/workflows/ci.yml/badge.svg)](https://github.com/moonrox420/ball-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**The zero-config Python code cleaner, syntax healer, and quality suite.**
+
+`ballpython` automatically repairs broken syntax, resolves missing imports, prunes dead code, scans for security vulnerabilities, and formats your code in a single command. Zero LLM dependencies, 100% offline, and fast.
+
+Both `ballpython` and `pycleaner` CLI commands are identical.
+
+---
+
+## Installation
+
+```bash
+pip install ballpython
+```
+
+---
+
+## Quickstart
+
+### 1. Fix and format your code
+Run `ballpython` on any file or directory. It automatically heals syntax errors, resolves missing imports, removes unused variables, and applies canonical formatting:
+
+```bash
+ballpython .
+```
+
+### 2. Check code in CI (Dry Run)
+Check for syntax errors, security vulnerabilities, dead code, and linting violations without modifying any files on disk:
+
+```bash
+ballpython check .
+```
+
+---
+
+## What It Does Automatically
+
+When you run `ballpython`, all engines run under the hood in one pass:
+
+* **Syntax Healing:** Repairs missing statement colons (`def`, `class`, `if`), accidental `=` assignments in conditionals, unclosed parentheses/brackets, tab/space mixups, and legacy Python 2 except/print statements.
+* **Smart Import Resolution:** Resolves undefined symbols to standard library modules and common aliases, inserts `TYPE_CHECKING` guards, and prunes unused imports.
+* **Formatting & Modernization:** Formats code to PEP 8 standards (powered by `ruff`), modernizes legacy type annotations (PEP 585/604), and removes redundant `object` inheritance.
+* **Dead Code Pruning:** Discovers and eliminates unreachable code, empty pass blocks, and unused private definitions.
+* **Security & Taint Audit:** Detects hardcoded API secrets, SQL/command injection patterns, and unsafe `eval`/`exec`/`pickle` calls.
+* **Type Verification:** Verifies function call signatures against bundled Typeshed stubs.
+
+---
+
+## Pre-Commit Hook
+
+Add `ballpython` to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/moonrox420/ball-python
+    rev: v2.0.3
+    hooks:
+      - id: pycleaner
+        args: ["check"]
+```
+
+---
+
+## Configuration
+
+Optional configuration can be placed in `pyproject.toml` under `[tool.pycleaner]`:
+
+```toml
+[tool.pycleaner]
+exclude = ["migrations/", "generated/"]
+line-length = 88
+```
+
+---
+
+## License
+
+MIT License.

ballpython-2.0.3.dist-info/RECORD

@@ -0,0 +1,34 @@
+ballpython/__init__.py,sha256=d8ONxgaz9jml_fHPVvg867Vt5jGRhGTqzWPtux3WJOc,206
+ballpython/__main__.py,sha256=aCRr0vnZfKYHDrPHBsYSjX5xTxtFJpTTSPVUSZTBK-I,136
+ballpython/cli.py,sha256=LllCLRAQQ-fRR_lIXwmd2e3Q7DLCIvf-5jHBXsAhJWs,125
+ballpython/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pycleaner/__init__.py,sha256=dK4jaytHQuXqaK3pqum6o8z8JrRLU-XHUfv_NBOtdxs,2894
+pycleaner/__main__.py,sha256=8QBFrPyxId563F6cipPMNVEBTG8TIZUgxQfp8gk1VSI,135
+pycleaner/baseline.py,sha256=DS32C8_G8khYYNJo42FVv6Cc58lJj7NUmPOzWNfQwlU,3856
+pycleaner/cache.py,sha256=WhCiMkuL6ryWVr3l3XrYLLoI7A3bRF8jNxpOyedNW8M,10761
+pycleaner/cli.py,sha256=NhMMmLcf7RMuKjc0rjCmSGYn5ns_yib2rUbXRJDVaYY,73034
+pycleaner/complexity_analyzer.py,sha256=uGC40cHCcr1tshzfIUw56sodEDySMFR3kGmjo7nq_1c,14977
+pycleaner/config.py,sha256=XhloyaY_9pdwbQuc3QaAPCerLeXz-i1da4xT50h-pjY,8514
+pycleaner/dead_code_detector.py,sha256=1DwtBSZL1ug1OI9-6jcJyxkhqHmJ0F8ZR19POI2zO3c,26549
+pycleaner/dependency_auditor.py,sha256=yQhpN_nfJhEFaBPKVTzndpGas_U2OHyKP_Pifa5YrWA,16070
+pycleaner/discovery.py,sha256=dt3OmHg886hy_Z0p80ccMyDkITQxz4biaJY_zB3MU_g,6151
+pycleaner/explanations.py,sha256=2OOU_l3YL5o_Br_6fP6MF8HlY75-1JRmw3eTYT2lu8M,14219
+pycleaner/import_resolver.py,sha256=JnAysZeYtXlmmM0LEnb9HBdkHnEsNwwp4QlxebRxGNE,32189
+pycleaner/linter_formatter.py,sha256=LB5j66OCASU8WG8QgRFpSX7C2c7_UNMBgkJh2hSWxAY,20857
+pycleaner/modernizer.py,sha256=L9hxXXfdyTwf8itDO58y6bW5LobGo6dg8q537QdiYbM,12946
+pycleaner/pipeline.py,sha256=ZG7_9PNz0jBadFrZoiI7juLtUJXglGQhLgQhrLJqEac,20612
+pycleaner/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pycleaner/security_scanner.py,sha256=h7WSPYf40X-PBlJVOsJL-KaknDaOcWCMhcPwXkUvlbA,21986
+pycleaner/syntax_healer.py,sha256=TlIMKIJhaX9GED3e2JNzNMJ5aXmL9eLJMCu7xKSjdv8,26711
+pycleaner/taint_engine.py,sha256=96cZdDpSPbo5b13zIZY18f_4GJm_tw0clqCZMBtjXMQ,26481
+pycleaner/test_generator.py,sha256=TJsNJSojc6eIsaKZkwMlpnb-MKHuDpNLZCPnMlO-a8M,19663
+pycleaner/type_checker.py,sha256=h09QI_8MRHv83s23myjSYFdMTsWoQ900ffBJHtRuhmE,34087
+pycleaner/typeshed_resolver.py,sha256=N-kWU_CI5DG59lQMkt7wMW9sHYjNCBdfFS42b4y2Kr4,12742
+pycleaner/verifier.py,sha256=pOfSLRNHe4qDUYJG8mxDxjY6Ph8QKBdJZmqBtoJX87w,17937
+pycleaner/frameworks/__init__.py,sha256=7MLgg469hCNtQR6dsE5gZcAZkCywJHz9zOPrbH8NmrE,3415
+pycleaner/frameworks/plugins.py,sha256=K3J4mVJw2MR_pa6Mhmo5oZOX8pUesL8lx9LUo4RLrNo,9390
+ballpython-2.0.3.dist-info/METADATA,sha256=K1nMS6fIKnHpTsJ0mRLaKNv_o1TFuzb7SI_KgywGCaw,3466
+ballpython-2.0.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ballpython-2.0.3.dist-info/entry_points.txt,sha256=6ux-5UxoVSmlK5p9M-GDVt24sCdwTQq9wgRDkpMIYU8,81
+ballpython-2.0.3.dist-info/top_level.txt,sha256=u6lmy8RWZ_saxCZAQTL7EijB4sunegOiVyk5fHjpwLk,21
+ballpython-2.0.3.dist-info/RECORD,,

pycleaner/__init__.py

@@ -10,19 +10,38 @@ dataflow taint vulnerabilities, and synthesizes automated behavioral test suites
 
 from __future__ import annotations
 
-__version__ = "2.0.0"
+from pycleaner.discovery import (
+    DEFAULT_IGNORED_DIRS,
+    PROTECTED_FILE_PATTERNS,
+    collect_project_python_files,
+    is_ignored_directory,
+    is_protected_file,
+)
+
+__version__ = "2.0.3"
 __all__ = [
+    "BaselineFingerprint",
+    "BaselineManager",
     "CleanPipeline",
     "CleanResult",
     "ComplexityAnalyzer",
     "ComplexityReport",
+    "ContentAddressableCache",
+    "CounterExample",
     "DeadCodeDetector",
+    "DeadCodeFixResult",
+    "DeadCodeFixer",
     "DeadCodeReport",
     "DependencyAuditor",
     "GeneratedTestSuite",
     "ImportResolver",
+    "IsolatedDifferentialVerifier",
     "LinterFormatter",
+    "ModernizeResult",
+    "Modernizer",
+    "ProofReceipt",
     "PyCleanerConfig",
+    "RuleExplanation",
     "SecurityReport",
     "SecurityScanner",
     "SyntaxHealer",
@@ -35,15 +54,27 @@ __all__ = [
     "TypeFinding",
     "TypeReport",
     "TypeshedResolver",
+    "VerificationTier",
+    "get_explanation",
+    "list_rules",
     "load_config",
 ]
 
+from pycleaner.baseline import BaselineFingerprint, BaselineManager
+from pycleaner.cache import ContentAddressableCache
 from pycleaner.complexity_analyzer import ComplexityAnalyzer, ComplexityReport
 from pycleaner.config import PyCleanerConfig, load_config
-from pycleaner.dead_code_detector import DeadCodeDetector, DeadCodeReport
+from pycleaner.dead_code_detector import (
+    DeadCodeDetector,
+    DeadCodeFixer,
+    DeadCodeFixResult,
+    DeadCodeReport,
+)
 from pycleaner.dependency_auditor import DependencyAuditor
+from pycleaner.explanations import RuleExplanation, get_explanation, list_rules
 from pycleaner.import_resolver import ImportResolver
 from pycleaner.linter_formatter import LinterFormatter
+from pycleaner.modernizer import Modernizer, ModernizeResult
 from pycleaner.pipeline import CleanPipeline, CleanResult
 from pycleaner.security_scanner import SecurityReport, SecurityScanner
 from pycleaner.syntax_healer import SyntaxHealer
@@ -51,3 +82,9 @@ from pycleaner.taint_engine import TaintEngine, TaintFinding, TaintReport
 from pycleaner.test_generator import GeneratedTestSuite, TestCase, TestGenerator
 from pycleaner.type_checker import TypeChecker, TypeFinding, TypeReport
 from pycleaner.typeshed_resolver import TypeshedResolver
+from pycleaner.verifier import (
+    CounterExample,
+    IsolatedDifferentialVerifier,
+    ProofReceipt,
+    VerificationTier,
+)

pycleaner/baseline.py

@@ -0,0 +1,127 @@
+"""
+pycleaner.baseline
+==================
+
+Technical Debt Ratchet and Baseline Management Engine.
+
+Enables incremental adoption of PyCleaner on legacy codebases by snapshotting
+existing diagnostic violations into `.pycleaner/baseline.json`. Future CI/CD
+checks ensure that existing technical debt can only decrease, never increase.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class BaselineFingerprint:
+    rule: str
+    file: str
+    line: int
+    symbol: str
+
+    def to_hash(self) -> str:
+        raw = f"{self.rule}:{self.file}:{self.line}:{self.symbol}"
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "rule": self.rule,
+            "file": self.file,
+            "line": self.line,
+            "symbol": self.symbol,
+            "hash": self.to_hash(),
+        }
+
+
+class BaselineManager:
+    """Manages baseline generation, loading, and ratchet comparison."""
+
+    def __init__(self, baseline_path: Path | str = ".pycleaner/baseline.json") -> None:
+        self.baseline_path = Path(baseline_path)
+
+    def load_fingerprints(self) -> set[str]:
+        """Loads baseline issue hashes from disk."""
+        if not self.baseline_path.exists():
+            return set()
+        try:
+            data = json.loads(self.baseline_path.read_text(encoding="utf-8"))
+            fingerprints = data.get("fingerprints", [])
+            return {
+                fp.get("hash")
+                for fp in fingerprints
+                if isinstance(fp, dict) and fp.get("hash")
+            }
+        except json.JSONDecodeError:
+            return set()
+
+    def save_baseline(
+        self,
+        fingerprints: list[BaselineFingerprint],
+        root_dir: Path,
+    ) -> Path:
+        """Serializes fingerprints to the baseline JSON file."""
+        self.baseline_path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "version": 1,
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "root_dir": str(root_dir.resolve()),
+            "issue_count": len(fingerprints),
+            "fingerprints": [fp.to_dict() for fp in fingerprints],
+        }
+        self.baseline_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+        return self.baseline_path
+
+    @staticmethod
+    def create_fingerprint(
+        rule: str,
+        file_path: Path | str,
+        line: int,
+        symbol: str,
+        root_dir: Path | None = None,
+    ) -> BaselineFingerprint:
+        """Constructs a deterministic fingerprint with normalized relative path."""
+        p = Path(file_path)
+        if root_dir is not None:
+            try:
+                rel = str(p.resolve().relative_to(root_dir.resolve())).replace(
+                    "\\", "/"
+                )
+            except ValueError:
+                rel = p.name
+        else:
+            rel = p.name
+
+        return BaselineFingerprint(
+            rule=rule,
+            file=rel,
+            line=line,
+            symbol=symbol,
+        )
+
+    def filter_new_issues(
+        self,
+        issues: list[BaselineFingerprint],
+    ) -> tuple[list[BaselineFingerprint], list[BaselineFingerprint]]:
+        """
+        Separates issues into (tolerated_baseline_issues, new_debt_issues).
+        Returns:
+            (tolerated, new_debt)
+        """
+        known_hashes = self.load_fingerprints()
+        tolerated: list[BaselineFingerprint] = []
+        new_debt: list[BaselineFingerprint] = []
+
+        for issue in issues:
+            if issue.to_hash() in known_hashes:
+                tolerated.append(issue)
+            else:
+                new_debt.append(issue)
+
+        return tolerated, new_debt

pycleaner/cache.py

@@ -0,0 +1,282 @@
+"""
+pycleaner.cache
+===============
+
+Content-Addressable Incremental Cache and Provenance Ledger for PyCleaner.
+
+Provides:
+- SQLite-backed, WAL-journaled content-addressable caching keyed by SHA-256(content + config).
+- Dependency invalidation tracking via AST-extracted import graphs.
+- Audit provenance ledger recording every verified repair with seed and diff receipts.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pycleaner.pipeline import CleanResult
+from pycleaner.verifier import VerificationTier
+
+
+def compute_content_hash(source: str, config_hash: str = "") -> str:
+    """Computes a deterministic SHA-256 hash of the source code and configuration."""
+    hasher = hashlib.sha256()
+    hasher.update(source.encode("utf-8"))
+    if config_hash:
+        hasher.update(config_hash.encode("utf-8"))
+    return hasher.hexdigest()
+
+
+def extract_file_dependencies(source: str) -> list[str]:
+    """Extracts imported module names using AST analysis for dependency tracking."""
+    deps: list[str] = []
+    try:
+        tree = ast.parse(source)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    deps.append(alias.name.split(".")[0])
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                deps.append(node.module.split(".")[0])
+    except SyntaxError:
+        pass  # Best-effort dependency extraction; syntax errors handled downstream
+    return sorted(set(deps))
+
+
+class ContentAddressableCache:
+    """
+    High-performance incremental cache backed by SQLite with write-ahead logging (WAL).
+    Guarantees sub-millisecond cache lookups for unchanged files.
+    """
+
+    def __init__(self, db_path: Path | str = ".pycleaner/cache.db") -> None:
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def _get_connection(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self.db_path), timeout=10.0)
+        conn.execute("PRAGMA journal_mode=WAL;")
+        conn.execute("PRAGMA synchronous=NORMAL;")
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        with self._get_connection() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS file_cache (
+                    content_hash TEXT PRIMARY KEY,
+                    file_path TEXT NOT NULL,
+                    config_hash TEXT NOT NULL,
+                    cleaned_code TEXT NOT NULL,
+                    is_valid_python INTEGER NOT NULL,
+                    changed INTEGER NOT NULL,
+                    error TEXT,
+                    syntax_repairs TEXT NOT NULL,
+                    modernize_transforms TEXT NOT NULL,
+                    dead_code_pruned TEXT NOT NULL,
+                    resolved_imports TEXT NOT NULL,
+                    unresolved_symbols TEXT NOT NULL,
+                    lint_changed INTEGER NOT NULL,
+                    format_changed INTEGER NOT NULL,
+                    verification_tier TEXT,
+                    dependencies TEXT NOT NULL,
+                    updated_at REAL NOT NULL
+                );
+                """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_file_cache_path
+                ON file_cache (file_path);
+                """)
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS provenance_ledger (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    timestamp TEXT NOT NULL,
+                    file_path TEXT NOT NULL,
+                    transformation_type TEXT NOT NULL,
+                    verification_tier TEXT NOT NULL,
+                    seed INTEGER,
+                    diff TEXT NOT NULL
+                );
+                """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_provenance_path
+                ON provenance_ledger (file_path);
+                """)
+            conn.commit()
+
+    def get(
+        self,
+        file_path: Path | str,
+        source: str,
+        config_hash: str = "",
+    ) -> CleanResult | None:
+        """
+        Retrieves a cached CleanResult if content_hash matches.
+        Returns None on cache miss.
+        """
+        expected_hash = compute_content_hash(source, config_hash)
+        from pycleaner.pipeline import CleanResult
+
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                SELECT * FROM file_cache
+                WHERE content_hash = ?;
+                """,
+                (expected_hash,),
+            )
+            row = cursor.fetchone()
+            if row is None:
+                return None
+
+            tier = None
+            if row["verification_tier"]:
+                try:
+                    tier = VerificationTier(row["verification_tier"])
+                except ValueError:
+                    tier = None
+
+            return CleanResult(
+                path=Path(row["file_path"]),
+                original_code=source,
+                cleaned_code=row["cleaned_code"],
+                changed=bool(row["changed"]),
+                is_valid_python=bool(row["is_valid_python"]),
+                syntax_repairs=json.loads(row["syntax_repairs"]),
+                modernize_transforms=json.loads(row["modernize_transforms"]),
+                dead_code_pruned=json.loads(row["dead_code_pruned"]),
+                resolved_imports=json.loads(row["resolved_imports"]),
+                unresolved_symbols=json.loads(row["unresolved_symbols"]),
+                lint_changed=bool(row["lint_changed"]),
+                format_changed=bool(row["format_changed"]),
+                error=row["error"],
+                verification_tier=tier,
+            )
+
+    def set(
+        self,
+        file_path: Path | str,
+        source: str,
+        result: CleanResult,
+        config_hash: str = "",
+    ) -> None:
+        """Stores or updates the CleanResult in the incremental cache keyed by content_hash."""
+        canonical_path = str(Path(file_path).resolve())
+        content_hash = compute_content_hash(source, config_hash)
+        deps = extract_file_dependencies(source)
+        tier_str = result.verification_tier.value if result.verification_tier else None
+
+        with self._get_connection() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO file_cache (
+                    content_hash, file_path, config_hash, cleaned_code,
+                    is_valid_python, changed, error, syntax_repairs,
+                    modernize_transforms, dead_code_pruned, resolved_imports,
+                    unresolved_symbols, lint_changed, format_changed,
+                    verification_tier, dependencies, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);
+                """,
+                (
+                    content_hash,
+                    canonical_path,
+                    config_hash,
+                    result.cleaned_code,
+                    1 if result.is_valid_python else 0,
+                    1 if result.changed else 0,
+                    result.error,
+                    json.dumps(result.syntax_repairs),
+                    json.dumps(result.modernize_transforms),
+                    json.dumps(result.dead_code_pruned),
+                    json.dumps(result.resolved_imports),
+                    json.dumps(result.unresolved_symbols),
+                    1 if result.lint_changed else 0,
+                    1 if result.format_changed else 0,
+                    tier_str,
+                    json.dumps(deps),
+                    time.time(),
+                ),
+            )
+            conn.commit()
+
+    def record_provenance(
+        self,
+        file_path: Path | str,
+        transformation_type: str,
+        verification_tier: str,
+        seed: int | None,
+        diff: str,
+    ) -> None:
+        """Records an immutable audit entry into the provenance ledger."""
+        canonical_path = str(Path(file_path).resolve())
+        now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        with self._get_connection() as conn:
+            conn.execute(
+                """
+                INSERT INTO provenance_ledger (
+                    timestamp, file_path, transformation_type,
+                    verification_tier, seed, diff
+                ) VALUES (?, ?, ?, ?, ?, ?);
+                """,
+                (
+                    now,
+                    canonical_path,
+                    transformation_type,
+                    verification_tier,
+                    seed,
+                    diff,
+                ),
+            )
+            conn.commit()
+
+    def get_provenance(self, limit: int = 50) -> list[dict[str, Any]]:
+        """Returns the most recent records from the provenance ledger."""
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                SELECT timestamp, file_path, transformation_type,
+                       verification_tier, seed, diff
+                FROM provenance_ledger
+                ORDER BY id DESC
+                LIMIT ?;
+                """,
+                (limit,),
+            )
+            return [dict(row) for row in cursor.fetchall()]
+
+    def invalidate(self, file_path: Path | str) -> None:
+        """Invalidates the cache entry for a specific file path."""
+        canonical_path = str(Path(file_path).resolve())
+        with self._get_connection() as conn:
+            conn.execute(
+                "DELETE FROM file_cache WHERE file_path = ?;", (canonical_path,)
+            )
+            conn.commit()
+
+    def clear(self) -> None:
+        """Clears all entries from the cache database."""
+        with self._get_connection() as conn:
+            conn.execute("DELETE FROM file_cache;")
+            conn.commit()
+
+    def get_stats(self) -> dict[str, Any]:
+        """Returns statistics on cache utilization and database storage."""
+        with self._get_connection() as conn:
+            cursor = conn.execute("SELECT COUNT(*) as cnt FROM file_cache;")
+            total_entries = cursor.fetchone()["cnt"]
+            cursor = conn.execute("SELECT COUNT(*) as cnt FROM provenance_ledger;")
+            provenance_entries = cursor.fetchone()["cnt"]
+            db_size = self.db_path.stat().st_size if self.db_path.exists() else 0
+            return {
+                "file_cache_entries": total_entries,
+                "provenance_entries": provenance_entries,
+                "db_size_bytes": db_size,
+            }