Function find_missing_entries

openkb/lint.py:348–416

Find files in raw/ that have no corresponding wiki entries. When ``kb_dir`` is provided, each raw file is first resolved through the hash registry (``kb_dir/.openkb/hashes.json``): registered files are checked against their ``doc_name`` artifacts, which can differ from the raw stem

(
    raw: Path,
    wiki: Path,
    *,
    kb_dir: Path | None = None,
)

def find_missing_entries(
    raw: Path,
    wiki: Path,
    *,
    kb_dir: Path | None = None,
) -> list[str]:
    """Find files in raw/ that have no corresponding wiki entries.

    When ``kb_dir`` is provided, each raw file is first resolved through
    the hash registry (``kb_dir/.openkb/hashes.json``): registered files
    are checked against their ``doc_name`` artifacts, which can differ
    from the raw stem (watch-mode/URL ingests keep the original filename
    in raw/ — e.g. ``2509.11420.pdf`` → ``2509-11420.md`` — and collision
    suffixes rename artifacts too). Files with no registry entry fall back
    to the stem heuristic: "present" means a sources/ or summaries/ page
    with the same stem.

    Args:
        raw: Path to the raw documents directory.
        wiki: Path to the wiki root directory.
        kb_dir: Root of the knowledge base. When None, only the legacy
            stem heuristic is used.

    Returns:
        List of filenames in raw/ with no wiki entry.
    """
    sources_dir = wiki / "sources"
    summaries_dir = wiki / "summaries"

    sources_stems = {p.stem for p in sources_dir.glob("*.md")} if sources_dir.exists() else set()
    summary_stems = (
        {p.stem for p in summaries_dir.glob("*.md")} if summaries_dir.exists() else set()
    )
    known_stems = sources_stems | summary_stems

    registry = None
    if kb_dir is not None:
        registry_file = kb_dir / ".openkb" / "hashes.json"
        if registry_file.exists():
            # Deferred import: converter pulls in pymupdf/markitdown,
            # which lint doesn't otherwise need at import time.
            from openkb.converter import _registry_path
            from openkb.state import HashRegistry

            registry = HashRegistry(registry_file)

    missing: list[str] = []
    if raw.exists():
        for f in raw.iterdir():
            if not f.is_file():
                continue
            if registry is not None:
                meta = registry.get_by_path(_registry_path(f, kb_dir))
                if meta is not None:
                    # Registered file — the registry's doc_name is the
                    # single source of truth for artifact names.
                    doc_name = meta.get("doc_name") or Path(meta.get("name", f.name)).stem
                    present = (