Class HashFingerprintCache

ci/fingerprint/core.py:531–690

Aggregate hash-based fingerprint cache backed by ``zccache-fingerprint`` CLI. Generates a single blake3 hash from the entire file set. All-or-nothing: if any file changes, the whole set is considered dirty. Best for "run all tests" or "compile all examples" style decisions.

class HashFingerprintCache:
    """
    Aggregate hash-based fingerprint cache backed by ``zccache-fingerprint`` CLI.

    Generates a single blake3 hash from the entire file set.  All-or-nothing:
    if any file changes, the whole set is considered dirty.

    Best for "run all tests" or "compile all examples" style decisions.
    """

    def __init__(
        self,
        cache_dir: Path,
        subpath: str,
        timestamp_file: Optional[Path] = None,
    ):
        """
        Initialize hash fingerprint cache.

        Args:
            cache_dir: Base cache directory (e.g., Path(".cache"))
            subpath: Subdirectory name for this cache (e.g., "js_lint", "native_build")
            timestamp_file: Optional path to write timestamp when changes are detected.
        """
        self.cache_dir = cache_dir
        self.subpath = subpath
        self.timestamp_file = timestamp_file

        # Create cache directory structure
        self.fingerprint_dir = cache_dir / "fingerprint"
        self.fingerprint_dir.mkdir(parents=True, exist_ok=True)

        # Cache file path
        self.cache_file = self.fingerprint_dir / f"{subpath}.json"

    def check_needs_update(
        self,
        include: list[str] | None = None,
        exclude: list[str] | None = None,
        *,
        root: str = ".",
        ext: list[str] | None = None,
    ) -> bool:
        """
        Check if files need to be processed.

        Delegates to ``zccache-fingerprint --cache-type hash check``.
        Exit 0 = run needed.  Exit 1 = skip (cache hit).

        Use ``ext`` + ``root`` for fastest scanning (simple suffix match,
        scoped directory walk).  Use ``include`` for glob-pattern matching.

        Args:
            include: Glob patterns for files to monitor.
                     Cannot be combined with ``ext``.
            exclude: Optional patterns to exclude.
            root: Root directory for scanning (default: ".").
            ext: File extensions without dot (e.g., ["h", "cpp"]).