stat_cache

class HashCache(Protocol):
    """Remembers a file's hash for as long as its ``Stat`` is unchanged."""

    def lookup(self, path: Path, stat: Stat) -> ContentHash | None:
        """The remembered hash of ``path`` at ``stat``, if any."""
        ...

    def store(self, path: Path, stat: Stat, hash: ContentHash) -> None:
        """Remember that ``path`` at ``stat`` hashes to ``hash``."""
        ...

class NoCache:
    """A hash cache that remembers nothing."""

    def lookup(self, path: Path, stat: Stat) -> ContentHash | None:
        """Always a miss."""
        return None

    def store(self, path: Path, stat: Stat, hash: ContentHash) -> None:
        """Forgets immediately."""

@dataclass(frozen=True, slots=True)
class Stat:
    """A file's identity on disk: change any of these and its content may have changed."""

    mtime_ns: int
    size: int
    inode: int
    is_dir: bool

    @classmethod
    def of(cls, path: Path) -> Stat:
        """The stat of ``path`` itself (a symlink is not followed)."""
        status = os.lstat(path)
        return cls(status.st_mtime_ns, status.st_size, status.st_ino, os.path.isdir(path))