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

{ballpython-2.0.0.dist-info → ballpython-2.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ballpython
-Version: 2.0.0
+Version: 2.0.2
 Summary: The Ultimate Static Python Intelligence, Healing, Type Verification, and Security Suite
 Author: Developer
 License-Expression: MIT
@@ -47,6 +47,7 @@ Zero external LLM dependencies, zero mock modes, and built for deterministic dev
    - Modernizes deprecated syntax via `pyupgrade` (`UP`).
    - Applies deterministic PEP 8 formatting (`ruff format` / `black` / pure-Python formatter).
    - Wraps long `from ... import (...)` statements exceeding configured `line-length`.
+   - Modernizes legacy typing to PEP 585/604 syntax (`List[T]` -> `list[T]`, `Optional[T]` -> `T | None`), singleton comparisons, and `class X(object)` inheritance via `Modernizer` (disable with `--no-modernize`).
 
 4. **Dead Code Detector (`DeadCodeDetector`)**:
    - Builds a cross-file symbol definition and reference graph across a project.
@@ -54,6 +55,7 @@ Zero external LLM dependencies, zero mock modes, and built for deterministic dev
    - Respects public exports in `__all__` and framework decorators (`@app.route`, `@pytest.fixture`, `@abstractmethod`, etc.).
    - Detects unreachable code following unconditional `return`, `raise`, `break`, `continue`, or `sys.exit()`.
    - Identifies empty pass blocks with no comments.
+   - Auto-prunes unreachable code, redundant `pass` statements, and `if False:` branches via `DeadCodeFixer` (enable with `dead-code --fix`, disable in the pipeline with `--no-dead-code`).
 
 5. **Static Security Scanner (`SecurityScanner`)**:
    - Detects dangerous function calls: `eval()`, `exec()`, `compile()`, `pickle.loads()`, `os.system()`, and unsafe `yaml.load()` lacking `SafeLoader`.
@@ -103,12 +105,13 @@ pip install -e ".[dev,security]"
 ### Subcommands
 
 #### `fix` (Default Action)
-Heals syntax, resolves imports, prunes unused imports/variables, fixes lint violations, and formats code:
+Heals syntax, modernizes legacy typing (PEP 585/604), prunes dead code, resolves imports, fixes lint violations, and formats code:
 ```bash
 py -m pycleaner fix src/
 py -m pycleaner fix --diff path/to/script.py
 py -m pycleaner fix --no-backup src/
 py -m pycleaner fix --parallel --workers 4 src/
+py -m pycleaner fix --no-modernize --no-dead-code src/
 ```
 
 #### `check` (Dry-Run CI Verification)
@@ -139,6 +142,7 @@ Finds unused functions, unused classes, empty pass branches, and dead code:
 ```bash
 py -m pycleaner dead-code .
 py -m pycleaner dead-code --json .
+py -m pycleaner dead-code --fix .
 ```
 
 #### `audit` (Project Dependency Verification)
@@ -188,7 +192,7 @@ pycleaner path/to/file.py          # Equivalent to: pycleaner fix path/to/file.p
 
 ## Configuration
 
-`pycleaner` automatically reads configuration from `pyproject.toml` under `[tool.pycleaner]` or from `.pycleaner.toml`.
+`pycleaner` automatically reads configuration from `pyproject.toml` under `[tool.pycleaner]` or from `.pycleaner.toml`. An explicit file can be forced with `pycleaner --config path/to/pyproject.toml <command> ...`, which overrides target-path auto-discovery.
 
 ### `pyproject.toml` Example
 
@@ -294,12 +298,14 @@ for func in violations:
 from pycleaner import DeadCodeDetector
 
 detector = DeadCodeDetector()
-report = detector.analyze_project("src/")
+report = detector.scan_project("src/")
 
-for item in report.unused_symbols:
-    print(f"Unused {item.kind} '{item.name}' at {item.filepath}:{item.lineno}")
+print(f"{report.count} dead code item(s) across {report.files_scanned} file(s).")
 
-for item in report.unreachable_code:
+for item in report.items:
+    print(f"Dead {item.kind} '{item.name}' at {item.filepath}:{item.lineno}")
+
+for item in report.by_kind("unreachable"):
     print(f"Unreachable code at {item.filepath}:{item.lineno} ({item.reason})")
 ```
 

ballpython-2.0.2.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=GMc3bYj3wg2AM_SZn_MRDq4i0f0PTaVq_ITR5spiOgI,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=9mAWc8JxcWavwpJP9aYeiDSfzYrH1eZLmeZ54xRouOY,21841
+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.2.dist-info/METADATA,sha256=tpostFTk54cwmBz56dghrw0fOAZVcsJPKA1N9NMUtZ4,12459
+ballpython-2.0.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ballpython-2.0.2.dist-info/entry_points.txt,sha256=6ux-5UxoVSmlK5p9M-GDVt24sCdwTQq9wgRDkpMIYU8,81
+ballpython-2.0.2.dist-info/top_level.txt,sha256=u6lmy8RWZ_saxCZAQTL7EijB4sunegOiVyk5fHjpwLk,21
+ballpython-2.0.2.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.2"
 __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,
+            }