py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/testcommands/cache_manager.py

@@ -0,0 +1,1156 @@
+"""Cache management module for test commands (the test-result cache adapter).
+
+This module is one of the three adapters over the single cache seam
+:class:`~wl_cli.utils.cache_ledger.CacheLedger` (#213, ADR-0011). It owns what
+this cache decides for itself -- the key inputs, the user-level location and the
+24-hour TTL -- and delegates key spelling, storage, freshness and the error
+policy to the ledger.
+
+Classes in this module:
+- CacheStats: Cache statistics data class
+- CacheMaintenance: Cache purge and statistics over a KeyedStore
+- DependencyAnalyzer: Concrete dependency analyzer with public API
+- CacheKeyGenerator: Generates the cache inputs (and their key) from file
+  content, dependencies and the environment of the verdict
+- CacheManager: Facade that delegates to the specialized components above
+"""
+
+import hashlib
+import json
+import os
+import random
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ...utils.cache_ledger import CacheInputs, CacheLedger, format_key
+from ...utils.cache_store import KeyedStore, is_fresh
+from ...utils.config import get_config
+from .utils.project_root import project_root_for
+
+
+class CacheKeyUnavailableError(RuntimeError):
+    """The cache key cannot be derived truthfully, so nothing may be cached.
+
+    Raised instead of falling back to a weaker key: an entry written under a
+    key that ignored the pytest configuration (or the interpreter) would be
+    served to a later run that is *not* the same run, which is exactly the
+    false green #191 removes. Callers treat it as "skip the cache".
+    """
+
+
+def _log_safe_key(key: str) -> str:
+    """Render a key for a log line, escaping characters the stream cannot encode.
+
+    A lone surrogate is a legal ``str`` but cannot be written to a UTF-8 stdout,
+    so interpolating one raw into a ``print`` raises ``UnicodeEncodeError`` --
+    which in :meth:`CacheManager.delete` would escape as a crash. Every other
+    key, including the empty string and control characters, is returned
+    unchanged, so existing log lines are byte-for-byte unaffected.
+    """
+    return key.encode("utf-8", "backslashreplace").decode("utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Cache location
+# ---------------------------------------------------------------------------
+
+
+def default_test_cache_dir() -> Path:
+    """Resolve the directory the test-result cache lives in.
+
+    User-level on purpose (``test_cache.cache_dir`` from configuration, falling
+    back to ``~/.cache/wl``, plus ``test-cache``): worktrees and the main
+    checkout share it, and the key carries the file path, so the shared store
+    does not collide. The location is this adapter's policy, not a technical
+    debt -- see ADR-0011.
+
+    Returns:
+        Path to the test-cache directory.
+    """
+    cache_root = get_config("test_cache.cache_dir", None)
+    if cache_root and isinstance(cache_root, str):
+        return Path(cache_root).expanduser() / "test-cache"
+
+    return Path.home() / ".cache" / "wl" / "test-cache"
+
+
+# ---------------------------------------------------------------------------
+# CacheStats & CacheMaintenance
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CacheStats:
+    """Cache statistics for display.
+
+    Attributes:
+        total_entries: Number of cached test results
+        total_size_bytes: Total size of all cache files in bytes
+    """
+
+    total_entries: int
+    total_size_bytes: int
+
+
+class CacheMaintenance:
+    """Cache purge and statistics operations over a :class:`KeyedStore`.
+
+    Expiry is judged from each entry's own ``timestamp`` field through
+    :func:`is_fresh` -- never from file mtime -- so the test-cache stack has a
+    single freshness clock.
+    """
+
+    def __init__(self, store: KeyedStore):
+        """Initialize with the store to maintain.
+
+        Args:
+            store: KeyedStore holding the test-cache entries.
+        """
+        self._store = store
+
+    def purge_expired(self, max_age_seconds: float) -> int:
+        """Remove entries whose payload timestamp is older than the limit.
+
+        An entry with no timestamp (or a non-numeric one) counts as expired, and
+        an entry that cannot be read or is not a JSON object is removed as
+        well: those files can never become hits, so a purge reclaims them.
+        Leftover temporary files from interrupted writes are swept too.
+
+        A file whose name is not a legal key (``.json`` yields the empty key,
+        ``a<TAB>b.json`` a control-character key) is reported by
+        ``iter_entry_files`` but refused by ``invalidate``, so the deletion
+        falls back to ``invalidate_file`` -- otherwise statistics counted a
+        file the purge could never reclaim (#172 wave 9).
+
+        Args:
+            max_age_seconds: Maximum age of a fresh entry, in seconds.
+
+        Returns:
+            Number of deleted cache files, temporary files included
+        """
+        deleted = 0
+        for key, entry in self._store.iter_entry_files():
+            if entry is not None and is_fresh(entry, max_age_seconds):
+                continue
+            if self._store.invalidate(key) or self._store.invalidate_file(key):
+                deleted += 1
+        return deleted + self._store.remove_temp_files()
+
+    def clear_all(self) -> int:
+        """Clear all cache entries.
+
+        Returns:
+            Number of deleted cache files
+        """
+        return self._store.clear()
+
+    def get_stats(self) -> CacheStats:
+        """Get current cache statistics.
+
+        ``total_entries`` and ``total_size_bytes`` cover the same set -- every
+        entry file in the store, unusable ones included -- so the two numbers
+        can be reconciled. A purge is what reclaims those unusable files.
+
+        Returns:
+            CacheStats object with current statistics
+        """
+        return CacheStats(
+            total_entries=sum(1 for _ in self._store.iter_entry_files()),
+            total_size_bytes=self._store.total_size_bytes(),
+        )
+
+    def print_stats(self, output: bool = True) -> str:
+        """Format cache statistics as a human-readable string.
+
+        Args:
+            output: Whether to print directly to stdout
+
+        Returns:
+            Formatted string with statistics
+        """
+        stats = self.get_stats()
+
+        def format_size(bytes_value: int) -> str:
+            """Convert bytes to human-readable format."""
+            if bytes_value < 1024:
+                return f"{bytes_value} B"
+            elif bytes_value < 1024 * 1024:
+                return f"{bytes_value / 1024:.1f} KB"
+            elif bytes_value < 1024 * 1024 * 1024:
+                return f"{bytes_value / (1024 * 1024):.1f} MB"
+            else:
+                return f"{bytes_value / (1024 * 1024 * 1024):.1f} GB"
+
+        lines = [
+            "Cache Statistics:",
+            f"  * Entries: {stats.total_entries}",
+            f"  * Total Size: {format_size(stats.total_size_bytes)}",
+        ]
+        result = "\n".join(lines)
+
+        if output:
+            print(result)
+
+        return result
+
+
+# ---------------------------------------------------------------------------
+# DependencyAnalyzer (thin wrapper around BaseDependencyAnalyzer)
+# ---------------------------------------------------------------------------
+
+
+from .base_dependency_analyzer import BaseDependencyAnalyzer  # noqa: E402
+
+
+class DependencyAnalyzer(BaseDependencyAnalyzer):
+    """Analyze Python file dependencies using AST parsing.
+
+    This class provides a public API for analyzing all dependencies
+    of a test file, including indirect dependencies through imports.
+    """
+
+    def __init__(
+        self, module_file_cache: dict[tuple[str, str], Path | None] | None = None
+    ):
+        """Initialize with optional module file cache.
+
+        Args:
+            module_file_cache: Optional cache for found module files
+                 Caches (module_name, src_dir_str) -> Path found result
+        """
+        super().__init__(module_file_cache)
+
+    def analyze(self, test_file: Path) -> list[Path]:
+        """Analyze a test file and recursively find all dependencies.
+
+        Args:
+            test_file: Path to the test file to analyze
+
+        Returns:
+            List of all found dependency file paths
+        """
+        return self._get_test_dependencies(test_file)
+
+
+# ---------------------------------------------------------------------------
+# CacheKeyGenerator
+# ---------------------------------------------------------------------------
+
+
+#: pytest config files, in the order pytest itself tries them in a directory.
+_PYTEST_CONFIG_FILENAMES = ("pytest.ini", "pyproject.toml", "tox.ini", "setup.cfg")
+
+#: Environment variables that change what the child pytest process does.
+#:
+#: The rule for membership is "a different value can change the verdict", not
+#: "the value looks important": a variable that only changes how an identical
+#: run is *reported* stays out, because keying it would turn a legitimate hit
+#: into a re-run.
+_KEY_ENVIRONMENT_VARIABLES = (
+    "PYTHONPATH",
+    "WL_ENVIRONMENT",
+    "CI",
+    "PYTHON_VERSION",
+    # `PYTEST_ADDOPTS` is appended to every pytest command line: it can select,
+    # filter and reconfigure the run, so it belongs in the key (#191).
+    "PYTEST_ADDOPTS",
+    "PYTEST_PLUGINS",
+    "PYTEST_DISABLE_PLUGIN_AUTOLOAD",
+    # `PYTHONWARNINGS` is the child interpreter's warning filter, and `error`
+    # turns a warning into a raised exception -- a different verdict, not a
+    # differently-formatted report. wl appends its own `-W` switches to every
+    # run, so this variable is the only per-run warning input the key could not
+    # see; wl's `-W ignore::UserWarning` is why the reproducing test has to
+    # emit a `FutureWarning` (#209).
+    "PYTHONWARNINGS",
+    # `PYTHONOPTIMIZE` (`-O`/`-OO`) strips `assert` statements before the test
+    # runs, so a test whose only check is an assert can pass under it and fail
+    # without it. Verdict-level, and previously unseen (#209 audit).
+    "PYTHONOPTIMIZE",
+    # `PYTHONDEVMODE` (`-X dev`) widens the startup warning filters and turns
+    # asyncio debug mode on, which emits warnings a test can observe (#209
+    # audit).
+    "PYTHONDEVMODE",
+    # `PYTHONHASHSEED` pins str/bytes hashing. Unset -- and, equivalently, the
+    # explicit value `random` -- means a fresh random seed per process, so no
+    # cache can be sound against *that*; an integer seed can order a set
+    # differently from the run that wrote the entry, so a set value must move
+    # the key (#209 audit).
+    "PYTHONHASHSEED",
+    # `PYTHONUTF8` / `PYTHONIOENCODING` change the child's default text encoding
+    # and stdio encoding, which tests that read, write or compare text observe
+    # (#209 audit).
+    "PYTHONUTF8",
+    "PYTHONIOENCODING",
+    # `PYTEST_TIMEOUT` (pytest-timeout) fails a test that overruns it: a pass
+    # recorded without a limit is not a pass under one (#209 audit).
+    "PYTEST_TIMEOUT",
+)
+
+#: Runs inside the *test* interpreter, never in the wl process: the fingerprint
+#: must describe the interpreter that will run pytest -- wl itself may live in
+#: a different environment (uv tool env vs project .venv).
+_FINGERPRINT_CODE = """
+import json
+import sys
+import importlib.metadata as md
+
+plugins = {}
+try:
+    entry_points = md.entry_points(group="pytest11")
+except Exception:
+    entry_points = ()
+for entry_point in entry_points:
+    dist = getattr(entry_point, "dist", None)
+    try:
+        if dist is None:
+            plugins[entry_point.name] = "unknown"
+        else:
+            plugins[dist.metadata["Name"] or entry_point.name] = dist.version
+    except Exception:
+        plugins[entry_point.name] = "unknown"
+try:
+    pytest_version = md.version("pytest")
+except Exception:
+    pytest_version = None
+print(
+    json.dumps(
+        {
+            "implementation": sys.implementation.name,
+            "version": sys.version,
+            "executable": sys.executable,
+            "prefix": sys.prefix,
+            "base_prefix": getattr(sys, "base_prefix", sys.prefix),
+            "pytest": pytest_version,
+            "plugins": plugins,
+        },
+        sort_keys=True,
+    )
+)
+"""
+
+
+def _interpreter_fingerprint(python_executable: str) -> str:
+    """SHA-256 of what the pytest-running interpreter *is*.
+
+    Covers the interpreter identity (implementation, version, executable,
+    prefix/base prefix) and the pytest/plugin versions importable **by that
+    interpreter**. The old key recorded the pytest version of the wl process,
+    which says nothing when the tests run in a project virtualenv.
+
+    Deliberately unmemoised: the probe costs a subprocess, and callers memoise
+    per run (see :class:`CacheKeyGenerator`). Keeping the memo out of module
+    state means one mis-answered probe cannot leak into an unrelated run.
+
+    Raises:
+        CacheKeyUnavailableError: the interpreter cannot be fingerprinted (missing
+            binary, nonzero exit, unparsable output, no pytest importable).
+            A key without this fingerprint would let a cache entry cross
+            interpreters, so the caller must not cache at all.
+    """
+    try:
+        completed = subprocess.run(
+            [python_executable, "-c", _FINGERPRINT_CODE],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as error:
+        raise CacheKeyUnavailableError(
+            f"cannot fingerprint interpreter {python_executable!r}: {error}"
+        ) from error
+
+    if completed.returncode != 0:
+        raise CacheKeyUnavailableError(
+            f"cannot fingerprint interpreter {python_executable!r}: "
+            f"exit {completed.returncode}: {completed.stderr.strip()[:200]}"
+        )
+    try:
+        payload = json.loads(completed.stdout)
+    except ValueError as error:
+        raise CacheKeyUnavailableError(
+            f"cannot fingerprint interpreter {python_executable!r}: "
+            f"unparsable output: {error}"
+        ) from error
+    if not isinstance(payload, dict) or not payload.get("pytest"):
+        raise CacheKeyUnavailableError(
+            f"cannot fingerprint interpreter {python_executable!r}: "
+            "pytest is not importable by that interpreter"
+        )
+
+    return hashlib.sha256(
+        json.dumps(payload, sort_keys=True).encode("utf-8")
+    ).hexdigest()
+
+
+def _nearest_pytest_config_root(start: Path) -> Path | None:
+    """Nearest ancestor of *start* (inclusive) holding a pytest config file.
+
+    This is pytest's own rootdir rule in miniature (nearest config wins), and
+    it is deliberately independent of the process working directory: the cache
+    key must describe *the file's* environment, not wherever wl was launched.
+    """
+    for directory in (start, *start.parents):
+        for filename in _PYTEST_CONFIG_FILENAMES:
+            if (directory / filename).is_file():
+                return directory
+    return None
+
+
+def _pytest_context_files(test_file: Path) -> list[Path]:
+    """conftest.py files and pytest config files that shape *test_file*'s run.
+
+    pytest builds a verdict out of more than the file and its imports: every
+    ``conftest.py`` between the rootdir and the test's directory is executed
+    before the test, and one config file supplies ``addopts``, ``testpaths``
+    and the plugin set. The AST import graph used to miss all of it, so editing
+    a conftest or ``pytest.ini`` left the cache key byte-for-byte unchanged
+    (#191).
+
+    The walk starts at the test file's own directory and stops at the config
+    root (or, when no config file exists, at the subsystem's project root when
+    that is an ancestor, else the filesystem root) -- the same boundary pytest
+    uses when it decides which conftest files apply.
+    """
+    directory = test_file.parent
+    root = _nearest_pytest_config_root(directory)
+    if root is None:
+        fallback = Path(project_root_for())
+        try:
+            fallback = fallback.resolve()
+        except OSError:
+            pass
+        if fallback in (directory, *directory.parents):
+            root = fallback
+
+    chain: list[Path] = []
+    current = directory
+    while True:
+        chain.append(current)
+        if current == root or current.parent == current:
+            break
+        current = current.parent
+    chain.reverse()
+
+    files: list[Path] = []
+    for item in chain:
+        conftest = item / "conftest.py"
+        if conftest.is_file():
+            files.append(conftest)
+        for filename in _PYTEST_CONFIG_FILENAMES:
+            candidate = item / filename
+            if candidate.is_file():
+                files.append(candidate)
+    return files
+
+
+try:
+    import pytest  # noqa: E402
+
+    HAS_PYTEST = True
+except ImportError:
+    HAS_PYTEST = False
+
+
+class CacheKeyGenerator(BaseDependencyAnalyzer):
+    """Derive the test-result cache inputs for a test file.
+
+    This generator is the test adapter's answer to "what enters the key"
+    (#213, ADR-0011): an ordered list of normalized fragments that the ledger
+    folds into ``test_<sha256>``. The fragments are:
+
+    - Test file path and modification/change times
+    - Test file content
+    - All dependency file paths, times, and content
+    - Every ``conftest.py`` and pytest config file that applies to the file
+      (rootdir down to the file's directory) (#191)
+    - Relevant environment variables: the pytest switches (``PYTEST_ADDOPTS``,
+      ``PYTEST_PLUGINS``, ``PYTEST_DISABLE_PLUGIN_AUTOLOAD``, and
+      ``PYTEST_TIMEOUT``, which the pytest-timeout plugin reads rather than the
+      interpreter startup), the child interpreter's startup inputs
+      (``PYTHONWARNINGS``, ``PYTHONOPTIMIZE``, ``PYTHONDEVMODE``,
+      ``PYTHONHASHSEED``, ``PYTHONUTF8``, ``PYTHONIOENCODING``), and the
+      ambient identity variables (``PYTHONPATH``, ``PYTHON_VERSION``, ``CI``,
+      ``WL_ENVIRONMENT``) (#191, #209)
+    - The wl process's pytest version (if available)
+    - A fingerprint of the interpreter that will run pytest (version, prefix,
+      and the pytest/plugin versions it can import) (#191)
+
+    When a part cannot be read the generator raises
+    :class:`CacheKeyUnavailableError` instead of returning a weaker input set.
+    """
+
+    #: The cache this adapter feeds. Becomes the key's prefix.
+    NAMESPACE = "test"
+
+    def __init__(
+        self, dependency_cache: dict[str, tuple[list[Path], float]] | None = None
+    ):
+        """Initialize with optional dependency cache.
+
+        Args:
+            dependency_cache: Optional shared cache for dependency lookups
+                 Stores (dependencies list, mtime) keyed by file path string
+        """
+        # Initialize base class with empty module file cache
+        super().__init__()
+        self._dependency_cache = (
+            dependency_cache if dependency_cache is not None else {}
+        )
+        self._content_read_warnings: list[str] = []
+        # Interpreter fingerprints, memoised for this generator (= one test
+        # run): a probe costs a subprocess and the key is asked for once per
+        # test file. Failures are memoised too, so an interpreter that cannot
+        # answer is not re-probed for every file in the suite.
+        self._fingerprints: dict[str, str] = {}
+        self._fingerprint_failures: dict[str, str] = {}
+
+    def generate(self, test_file: Path, python_executable: str | None = None) -> str:
+        """Generate the cache key for a test file from its cache inputs.
+
+        Args:
+            test_file: Path to the test file
+            python_executable: Interpreter that will run pytest for this file.
+                Defaults to the interpreter running wl, which is only correct
+                when the two are the same; every production caller passes the
+                real one.
+
+        Returns:
+            The ledger's key: ``test_`` followed by the full SHA-256 digest of
+            the normalized parts.
+
+        Raises:
+            CacheKeyUnavailableError: a part of the key could not be derived
+                truthfully (an unreadable conftest/config file, or an
+                interpreter that cannot be fingerprinted). The caller must then
+                treat the file as uncacheable.
+        """
+        return format_key(self.cache_inputs(test_file, python_executable))
+
+    def cache_inputs(
+        self, test_file: Path, python_executable: str | None = None
+    ) -> CacheInputs:
+        """Build the ordered, normalized fragments that decide this file's key.
+
+        Args:
+            test_file: Path to the test file
+            python_executable: Interpreter that will run pytest for this file.
+
+        Returns:
+            The test adapter's :class:`CacheInputs`.
+
+        Raises:
+            CacheKeyUnavailableError: a part of the key could not be derived
+                truthfully (an unreadable conftest/config file, or an
+                interpreter that cannot be fingerprinted).
+        """
+        parts: list[str] = []
+
+        # Test file path and modification/change times. A path with normalized
+        # separators, so the same file spells the same key on every platform.
+        file_path_str = str(test_file).replace("\\", "/")
+        try:
+            mtime = os.path.getmtime(test_file)
+            ctime = os.path.getctime(test_file)
+        except OSError:
+            mtime = 0.0
+            ctime = 0.0
+        parts.extend((file_path_str, str(mtime), str(ctime)))
+
+        # Test file content. An unreadable file contributes a per-run random
+        # value instead, so its entry can never be mistaken for a real one.
+        try:
+            content = test_file.read_text(encoding="utf-8")
+            if not isinstance(content, str):
+                content = str(content)
+            parts.append(content)
+        except (OSError, UnicodeDecodeError):
+            parts.append(f"{random.random()}-{time.time()}")
+            if file_path_str not in self._content_read_warnings:
+                self._content_read_warnings.append(file_path_str)
+
+        # Dependency files, in sorted path order.
+        dependencies = self._get_test_dependencies(test_file)
+        sorted_dependencies = sorted(dependencies, key=lambda x: str(x))
+        for dep_file in sorted_dependencies:
+            dep_path_str = str(dep_file).replace("\\", "/")
+            parts.append(dep_path_str)
+            try:
+                parts.append(str(os.path.getmtime(dep_file)))
+                parts.append(str(os.path.getctime(dep_file)))
+                parts.append(dep_file.read_text(encoding="utf-8"))
+            except (OSError, UnicodeDecodeError):
+                parts.append(str(time.time()))
+
+        # conftest.py chain + pytest configuration: what pytest loads *around*
+        # the file, which the import graph above cannot see (#191).
+        for context_file in _pytest_context_files(test_file):
+            try:
+                context_stat = context_file.stat()
+                context_content = context_file.read_bytes()
+            except OSError as error:
+                raise CacheKeyUnavailableError(
+                    f"cannot read pytest context file {context_file}: {error}"
+                ) from error
+            parts.extend(
+                (
+                    f"context={context_file}",
+                    str(context_stat.st_mtime_ns),
+                    # A part must be a str; hex keeps the exact bytes without
+                    # asking the digest to carry binary data.
+                    context_content.hex(),
+                )
+            )
+
+        # Add key environment variables to cache key. NUL separates name from
+        # value so no pair can alias another: with a bare `=`, a value that
+        # happens to embed the next `NAME=` prefix (`PYTHONPATH=/xPYTHONOPTIMIZE=1`)
+        # hashes to the same bytes as that variable set separately.
+        for env_var in _KEY_ENVIRONMENT_VARIABLES:
+            if env_var in os.environ:
+                parts.append(f"{env_var}\0{os.environ[env_var]}\0")
+
+        # Add pytest version to cache key
+        if HAS_PYTEST:
+            pytest_version = pytest.__version__
+            parts.append(f"pytest_version={pytest_version}")
+
+        # The interpreter that will actually run pytest, fingerprinted in a
+        # child process: version/prefix *and* the pytest/plugin versions it can
+        # import. Raises CacheKeyUnavailableError rather than keying on a guess.
+        executable = python_executable or sys.executable
+        parts.append(f"interpreter={self._fingerprint(executable)}")
+
+        return CacheInputs(self.NAMESPACE, tuple(parts))
+
+    def _fingerprint(self, python_executable: str) -> str:
+        """Memoised :func:`_interpreter_fingerprint` for this generator."""
+        cached = self._fingerprints.get(python_executable)
+        if cached is not None:
+            return cached
+        failure = self._fingerprint_failures.get(python_executable)
+        if failure is not None:
+            raise CacheKeyUnavailableError(failure)
+        try:
+            digest = _interpreter_fingerprint(python_executable)
+        except CacheKeyUnavailableError as error:
+            self._fingerprint_failures[python_executable] = str(error)
+            raise
+        self._fingerprints[python_executable] = digest
+        return digest
+
+
+# ---------------------------------------------------------------------------
+# CacheManager (facade)
+# ---------------------------------------------------------------------------
+
+
+class CacheManager:
+    """Cache manager for test results (the test-result cache adapter).
+
+    Narrow public cache interface: hit/record/purge/report operations composed
+    over the ledger/CacheKeyGenerator/DependencyAnalyzer/CacheMaintenance
+    behind a thread-safe lock, with read-only per-run hit tracking. The ledger
+    owns the mechanism -- key spelling, atomic writes, freshness and the write
+    error policy; this class keeps only *this cache's* policy: the inputs, the
+    user-level location and the 24-hour TTL (ADR-0011 keeps those per adapter).
+    """
+
+    CACHE_EXPIRY_SECONDS = 86400  # 24 hours
+
+    # Annotated at class level, not only in ``__init__``: mypy does not check
+    # the body of an untyped function, so an attribute assigned only there
+    # would read as ``Any`` at every typed use site.
+    _dependency_analyzer: DependencyAnalyzer
+    _key_generator: CacheKeyGenerator
+    _ledger: CacheLedger
+    _maintenance: CacheMaintenance
+
+    def __init__(self):
+        """Initialize CacheManager."""
+        # Cache statistics
+        self.cache_stats = {
+            "hits": 0,
+            "misses": 0,
+            "expired": 0,
+            "invalid": 0,
+            "total": 0,
+        }
+        # Runtime-set cache hit tracking
+        self._cache_hits: set[Path] = set()
+        # Shared caches passed to components for efficiency
+        self._dependency_cache: dict[str, tuple[list[Path], float]] = {}
+        self._module_file_cache: dict[tuple[str, str], Path | None] = {}
+
+        # Initialize specialized components
+        self._dependency_analyzer = DependencyAnalyzer(self._module_file_cache)
+        self._key_generator = CacheKeyGenerator(self._dependency_cache)
+        # All entry I/O goes through the ledger, rooted at the user-level
+        # test-cache directory and judged against this adapter's 24 hours. The
+        # per-run statistics below still own the "expired"/"invalid" lines, so
+        # they read raw entries and ask the ledger to judge them.
+        self._ledger = CacheLedger(default_test_cache_dir(), self.CACHE_EXPIRY_SECONDS)
+        self._maintenance = CacheMaintenance(self._ledger.store)
+
+        # Thread safety
+        self._ensure_cache_lock()
+
+    def _ensure_cache_lock(self):
+        """Ensure cache lock exists for thread-safe operations with enhanced initialization."""
+        if not hasattr(self, "_cache_lock"):
+            with threading.Lock():
+                if not hasattr(self, "_cache_lock"):
+                    self._cache_lock = threading.RLock()
+
+    @property
+    def cache_dir(self) -> Path:
+        """Directory where cache files are stored."""
+        return self._ledger.store_dir
+
+    @property
+    def cache_hit_files(self) -> frozenset[Path]:
+        """Read-only view of files that hit the cache during the current run."""
+        return frozenset(self._cache_hits)
+
+    def start_run(self) -> None:
+        """Reset per-run hit tracking and counters before a fresh test run."""
+        self._cache_hits = set()
+        self.cache_stats = {
+            "hits": 0,
+            "misses": 0,
+            "expired": 0,
+            "invalid": 0,
+            "total": 0,
+        }
+
+    def get_cache_key(
+        self, test_file: Path, python_executable: str | None = None
+    ) -> str:
+        """Generate cache key based on file content, dependencies and environment.
+
+        Raises:
+            CacheKeyUnavailableError: the key cannot be derived truthfully, so the
+                file must not be cached (see :class:`CacheKeyUnavailableError`).
+        """
+        return self._key_generator.generate(test_file, python_executable)
+
+    def invalidate_file(
+        self,
+        test_file: Path,
+        step_by_step: bool = False,
+        concise: bool = False,
+        python_executable: str | None = None,
+    ) -> None:
+        """Drop *test_file*'s entry.
+
+        A key that cannot be derived names no entry to delete, so an unavailable
+        key is a no-op here rather than an error: the caller's intent (leave no
+        passing entry behind) is already satisfied.
+        """
+        try:
+            cache_key = self.get_cache_key(test_file, python_executable)
+        except CacheKeyUnavailableError:
+            return
+        self.delete(cache_key, step_by_step, concise)
+
+    def get_test_dependencies(self, test_file: Path) -> list[Path]:
+        """Get test file dependencies by analyzing imports, including indirect dependencies."""
+        return self._dependency_analyzer.analyze(test_file)
+
+    def _validate_cache_timestamp(
+        self, data: dict[str, Any], step_by_step: bool = False, concise: bool = False
+    ) -> bool:
+        """Validate cache timestamp.
+
+        The freshness decision itself is :func:`is_fresh` (the stack's single
+        freshness judgement); the checks around it only distinguish the log
+        lines and keep the cache statistics.
+        """
+        try:
+            timestamp = data.get("timestamp")
+            if not timestamp:
+                if not concise and not step_by_step:
+                    print("[Cache] Missing timestamp in cache")
+                return False
+
+            current_time = time.time()
+            # Computed before the freshness check so a non-numeric timestamp
+            # still takes the error path it always has (the ``except`` below).
+            time_diff = current_time - timestamp
+            if not self._ledger.fresh(data, now=current_time):
+                if not concise and not step_by_step:
+                    print(
+                        f"[Cache] Cache expired: current={current_time}, timestamp={timestamp}, diff={time_diff}"
+                    )
+                self.cache_stats["expired"] += 1
+                self.cache_stats["total"] += 1
+                return False
+            else:
+                if not concise and not step_by_step:
+                    print(
+                        f"[Cache] Cache valid: current={current_time}, timestamp={timestamp}, diff={time_diff}"
+                    )
+
+            return True
+        except Exception as e:
+            if not concise and not step_by_step:
+                print(f"[Cache] Error validating timestamp: {e}")
+            return False
+
+    def _validate_cache_result(
+        self, data: dict[str, Any], step_by_step: bool = False
+    ) -> tuple[bool, bool | None]:
+        """Validate cache result format."""
+        result = data.get("result", False)
+        if not isinstance(result, bool):
+            if not step_by_step:
+                print("[Cache] Invalid result format in cache file")
+            self.cache_stats["invalid"] += 1
+            self.cache_stats["total"] += 1
+            return False, None
+        return True, result
+
+    def _check_cache_consistency(
+        self,
+        test_file: Path | None,
+        cache_key: str,
+        step_by_step: bool = False,
+        python_executable: str | None = None,
+    ) -> bool:
+        """Check cache consistency."""
+        if test_file:
+            current_cache_key = self.get_cache_key(test_file, python_executable)
+            if current_cache_key != cache_key:
+                if not step_by_step:
+                    print(
+                        f"[Cache] Cache inconsistent for {test_file.name}, key mismatch"
+                    )
+                self.cache_stats["invalid"] += 1
+                self.cache_stats["total"] += 1
+                return False
+        return True
+
+    def load(
+        self,
+        cache_key: str,
+        test_file: Path | None = None,
+        step_by_step: bool = False,
+        concise: bool = False,
+        python_executable: str | None = None,
+    ) -> bool | None:
+        """Load cached test result with enhanced error handling and consistency check.
+
+        Returns ``None`` -- a miss -- whenever the entry cannot be used: an
+        illegal key (see ``KeyedStore``, which degrades instead of raising), a
+        missing entry, one whose file cannot be read, one that exists but holds
+        corrupt JSON or something other than a JSON object, and one that fails
+        the timestamp/result/consistency checks. Every miss is counted in
+        ``cache_stats``.
+
+        Counting a corrupt or non-object entry as a miss narrows the behaviour
+        from before this class moved onto ``KeyedStore`` (#132), which returned
+        ``None`` silently without touching the counters: the entry is unusable,
+        so it *is* a miss, and counting it makes the stats more honest. The
+        change is intentional and pinned by ``test_cache_manager``. The only
+        reachable route to such an entry is external tampering -- every write
+        here is atomic and goes through :meth:`save`.
+        """
+        try:
+            self._ensure_cache_lock()
+
+            with self._cache_lock:
+                data = self._ledger.read(cache_key)
+                if data is None:
+                    if not concise and not step_by_step:
+                        print(
+                            f"[Cache] Cache file not found: "
+                            f"{_log_safe_key(cache_key)}.json"
+                        )
+                    self.cache_stats["misses"] += 1
+                    self.cache_stats["total"] += 1
+                    return None
+
+                if not self._validate_cache_timestamp(data, step_by_step, concise):
+                    return None
+
+                valid, result = self._validate_cache_result(data, step_by_step)
+                if not valid:
+                    return None
+
+                if not self._check_cache_consistency(
+                    test_file, cache_key, step_by_step, python_executable
+                ):
+                    return None
+
+                if not step_by_step:
+                    print(
+                        f"[Cache] Cache loaded successfully for key: {cache_key[:8]}..."
+                    )
+                self.cache_stats["hits"] += 1
+                self.cache_stats["total"] += 1
+                return result
+        except OSError as e:
+            if not step_by_step:
+                print(f"[Cache] File access error: {e}")
+            self.cache_stats["misses"] += 1
+            self.cache_stats["total"] += 1
+            return None
+        except Exception as e:
+            if not step_by_step:
+                print(f"[Cache] Unexpected error loading cache: {e}")
+            self.cache_stats["misses"] += 1
+            self.cache_stats["total"] += 1
+            return None
+
+    def save(
+        self,
+        cache_key: str,
+        result: bool,
+        step_by_step: bool = False,
+        concise: bool = False,
+    ) -> None:
+        """Save test result to cache with enhanced error handling.
+
+        Reports failure with the ``[Cache] Failed to save`` line instead of a
+        false success: the ledger returns ``False`` for an illegal key (see
+        ``KeyedStore``) or a failed write, and that result is passed on rather
+        than ignored. The entry's ``timestamp`` is the ledger's.
+        """
+        data = {
+            "result": result,
+            "version": "1.0",
+        }
+
+        try:
+            self._ensure_cache_lock()
+
+            with self._cache_lock:
+                if not self._ledger.put(cache_key, data):
+                    if not concise and not step_by_step:
+                        print(
+                            f"[Cache] Failed to save cache for key: "
+                            f"{_log_safe_key(cache_key)}"
+                        )
+                    return
+
+                if not concise and not step_by_step:
+                    print(
+                        f"[Cache] Cache saved successfully for key: {cache_key[:8]}..."
+                    )
+        except OSError as e:
+            if not concise and not step_by_step:
+                print(f"[Cache] File access error saving cache: {e}")
+        except Exception as e:
+            if not concise and not step_by_step:
+                print(f"[Cache] Unexpected error saving cache: {e}")
+
+    def delete(
+        self, cache_key: str, step_by_step: bool = False, concise: bool = False
+    ) -> None:
+        """Delete cache for the specified key with enhanced error handling.
+
+        Reports failure with the ``[Cache] Failed to delete`` line instead of
+        raising: an illegal key (see ``KeyedStore`` -- a non-``str``, the empty
+        string, a path separator, a directory reference, a control character, or
+        a character unencodable as a file name) takes the same path as a missing
+        entry, because an illegal key names no entry to delete. The key is
+        rendered log-safe, so even an unencodable one cannot crash the line.
+        """
+        success = self._ledger.invalidate(cache_key)
+        if not success and not concise and not step_by_step:
+            print(f"[Cache] Failed to delete cache for key: {_log_safe_key(cache_key)}")
+
+    def purge_expired(self) -> None:
+        """Remove cache entries older than 24 hours, judged by payload timestamp."""
+        deleted = self._maintenance.purge_expired(self.CACHE_EXPIRY_SECONDS)
+        if deleted > 0:
+            print(f"[Cache] Cleaned up {deleted} expired cache files")
+
+    def purge_all(self) -> None:
+        """Clean all test cache."""
+        deleted = self._maintenance.clear_all()
+        print(f"\nCleanup completed. Removed {deleted} cache files.")
+
+    def info(self) -> None:
+        """Show cache information."""
+        print(self._maintenance.print_stats(output=False))
+
+        print("\n=== Cache Usage Tips ===")
+        print("- Use --no-cache to skip cache for a single run")
+        print("- Use --clean-cache to remove all cache files")
+        print("- Cache automatically expires after 24 hours")
+
+    def report_summary(self, test_files: list[Path], concise: bool = False) -> None:
+        """Print per-run cache-usage summary from hit tracking."""
+        total_files = len(test_files)
+        cache_hit_count = len(self._cache_hits)
+
+        if cache_hit_count > 0 and not concise:
+            cache_hit_percent = (cache_hit_count / total_files) * 100
+            print(
+                f"Cache usage: {cache_hit_count}/{total_files} files ({cache_hit_percent:.1f}%) used cached results"
+            )
+        elif not concise:
+            print("Cache usage: No cached results used")
+
+    def report_detail(self) -> None:
+        """Print detailed cache statistics and reset the run counters."""
+        print("\n=== Detailed Cache Statistics ===")
+        print(f"Total cache operations: {self.cache_stats['total']}")
+        print(f"Cache hits: {self.cache_stats['hits']}")
+        print(f"Cache misses: {self.cache_stats['misses']}")
+        print(f"Expired caches: {self.cache_stats['expired']}")
+        print(f"Invalid caches: {self.cache_stats['invalid']}")
+
+        if self.cache_stats["total"] > 0:
+            hit_rate = (self.cache_stats["hits"] / self.cache_stats["total"]) * 100
+            miss_rate = (self.cache_stats["misses"] / self.cache_stats["total"]) * 100
+            invalid_rate = (
+                (self.cache_stats["expired"] + self.cache_stats["invalid"])
+                / self.cache_stats["total"]
+            ) * 100
+            print(f"\nCache hit rate: {hit_rate:.1f}%")
+            print(f"Cache miss rate: {miss_rate:.1f}%")
+            print(f"Cache invalidation rate: {invalid_rate:.1f}%")
+
+        self.cache_stats = {
+            "hits": 0,
+            "misses": 0,
+            "expired": 0,
+            "invalid": 0,
+            "total": 0,
+        }
+
+    def all_cached(
+        self,
+        test_files: list[Path],
+        concise: bool = False,
+        python_executable: str | None = None,
+    ) -> bool:
+        """Check if all test files have valid cached results.
+
+        An unavailable key counts as "not cached": the run must happen rather
+        than be skipped on the strength of a key that could not be derived.
+        """
+        if not test_files:
+            return False
+
+        if not concise:
+            print("[Cache] Checking cache for all test files...")
+        for test_file in test_files:
+            try:
+                cache_key = self.get_cache_key(test_file, python_executable)
+                if not concise:
+                    print(
+                        f"[Cache] Checking cache for {test_file.name} (key: {cache_key[:8]}...)"
+                    )
+                cache_result = self.load(
+                    cache_key,
+                    test_file,
+                    concise=concise,
+                    python_executable=python_executable,
+                )
+
+                if cache_result is None:
+                    if not concise:
+                        print(f"[Cache] Cache miss for {test_file.name}")
+                    return False
+                elif not cache_result:
+                    if not concise:
+                        print(
+                            f"[Cache] Cached failure for {test_file.name}, need to re-run"
+                        )
+                    return False
+                else:
+                    if not concise:
+                        print(f"[Cache] Cache hit for {test_file.name}")
+            except Exception as e:
+                if not concise:
+                    print(f"[Cache] Error checking cache for {test_file.name}: {e}")
+                return False
+        return True
+
+    def record_passed_batch(
+        self,
+        test_files: list[Path],
+        concise: bool = False,
+        python_executable: str | None = None,
+    ) -> None:
+        """Record a successful run for exactly the given test files.
+
+        The caller decides *which* files these are -- the set the run actually
+        executed (#191). Only the success path lives here. Attributing an
+        individual failing file (re-running pytest per file) is the runner's
+        job, which then calls :meth:`record_passed_single` / :meth:`delete` per
+        outcome.
+        """
+        print("[Cache] All tests passed, saving cache for all files...")
+        for test_file in test_files:
+            try:
+                cache_key = self.get_cache_key(test_file, python_executable)
+            except CacheKeyUnavailableError as error:
+                print(f"[Cache] Not caching {test_file.name}: {error}")
+                continue
+            try:
+                print(
+                    f"[Cache] Saving cache for {test_file.name} (key: {cache_key[:8]}...)"
+                )
+                self.save(cache_key, True, concise=concise)
+            except Exception as e:
+                print(f"[Cache] Error saving cache for {test_file.name}: {e}")
+
+    def cached_result(
+        self,
+        test_file: Path,
+        step_by_step: bool = False,
+        concise: bool = False,
+        python_executable: str | None = None,
+    ) -> tuple[bool, str, bool, None]:
+        """Check cache for a single test file.
+
+        An unavailable key is reported as a miss, never as a hit and never as
+        an error the caller has to know about.
+        """
+        try:
+            cache_key = self.get_cache_key(test_file, python_executable)
+            cache_result = self.load(
+                cache_key,
+                test_file,
+                step_by_step,
+                concise,
+                python_executable,
+            )
+
+            if cache_result is not None:
+                if not hasattr(self, "_cache_hits"):
+                    self._cache_hits = set()
+                self._cache_hits.add(test_file)
+                return True, "Cache hit", cache_result, None
+            else:
+                return False, "Cache miss", False, None
+        except Exception as e:
+            return False, f"Cache check error: {e}", False, None
+
+    def record_passed_single(
+        self,
+        test_file: Path,
+        step_by_step: bool = False,
+        concise: bool = False,
+        python_executable: str | None = None,
+    ) -> None:
+        """Record a passing single-file result in the cache.
+
+        Silent by design: an unavailable key simply means the file is not
+        cached, which is the same outcome as a save failure.
+        """
+        try:
+            cache_key = self.get_cache_key(test_file, python_executable)
+            self.save(cache_key, True, step_by_step, concise)
+        except Exception:
+            pass