Class HashRegistry

openkb/state.py:11–127

Persistent registry mapping file SHA-256 hashes to metadata dicts.

class HashRegistry:
    """Persistent registry mapping file SHA-256 hashes to metadata dicts."""

    def __init__(self, path: Path) -> None:
        self._path = path
        if path.exists():
            with path.open("r", encoding="utf-8") as fh:
                self._data: dict[str, dict] = json.load(fh)
        else:
            self._data = {}

    # ------------------------------------------------------------------
    # Query helpers
    # ------------------------------------------------------------------

    def is_known(self, file_hash: str) -> bool:
        """Return True if file_hash is already registered."""
        return file_hash in self._data

    def get(self, file_hash: str) -> dict | None:
        """Return metadata for file_hash, or None if not found."""
        return self._data.get(file_hash)

    def all_entries(self) -> dict[str, dict]:
        """Return a shallow copy of all hash -> metadata entries."""
        return dict(self._data)

    def get_by_path(self, path: str) -> dict | None:
        """Return metadata whose path/raw_path/source_path equals ``path``.

        ``path`` is a registry path string (posix, relative to the KB dir
        when inside it) as produced by ``converter._registry_path``. Entries
        written before the path index existed carry none of these fields and
        never match.
        """
        for metadata in self._data.values():
            if path in (
                metadata.get("path"),
                metadata.get("raw_path"),
                metadata.get("source_path"),
            ):
                return metadata
        return None

    def find_legacy_by_stem(self, stem: str) -> tuple[str, dict] | None:
        """Find a pre-path-index entry matching ``stem``.

        Returns ``(file_hash, metadata)`` for an entry that has no truthy
        ``path`` (a missing or empty ``path`` is treated as unindexed) and
        whose ``doc_name`` — or, for even older entries lacking
        ``doc_name``, the stem of its ``name`` — equals ``stem``. When
        several legacy entries match (pre-fix registries can hold
        same-named entries), the first in insertion order is returned.
        Callers use the hash to backfill ``path`` via :meth:`add`. Returns
        None when every matching name is already path-indexed. The
        comparison is NFKC-normalized on both sides, so macOS NFD
        filenames match their NFC registry entries.
        """