Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

6.1 KB
Raw Blame
"""Persistence of linked-folder sync state (``metadata.json``).

``update_folder_sync_state()`` used to mutate the loaded metadata dict and
return without writing it back, so ``last_sync``/``synced_files`` silently
vanished while the API layer logged success. These tests pin the write-back.
The atomicity contract of the shared writer lives in
``tests/services/test_file_io.py``.
"""

from __future__ import annotations

import json
import logging
from pathlib import Path

from deeptutor.api.routers.knowledge import LinkedFolderInfo
from deeptutor.knowledge import manager as manager_module
from deeptutor.knowledge.manager import KnowledgeBaseManager


def _manager_with_linked_folder(tmp_path: Path) -> tuple[KnowledgeBaseManager, Path, str, Path]:
    """A registered KB with one linked folder containing one markdown file."""
    manager = KnowledgeBaseManager(base_dir=str(tmp_path / "kbs"))

    kb_dir = manager.base_dir / "kb"
    kb_dir.mkdir()
    manager.register_knowledge_base("kb")

    source = tmp_path / "notes"
    source.mkdir()
    doc = source / "note.md"
    doc.write_text("hello", encoding="utf-8")

    folder_info = manager.link_folder("kb", str(source))
    assert folder_info["last_sync"] is None
    return manager, kb_dir / "metadata.json", folder_info["id"], doc


def test_update_folder_sync_state_persists_to_disk(tmp_path: Path) -> None:
    manager, metadata_file, folder_id, doc = _manager_with_linked_folder(tmp_path)

    manager.update_folder_sync_state("kb", folder_id, [str(doc)])

    on_disk = json.loads(metadata_file.read_text(encoding="utf-8"))
    folder = on_disk["linked_folders"][0]
    assert "last_sync" in folder
    assert str(doc) in folder["synced_files"]
    assert folder["file_count"] == 1

    # A fresh manager (new process in real life) must see the sync state too.
    reloaded = KnowledgeBaseManager(base_dir=str(manager.base_dir))
    folder = reloaded.get_linked_folders("kb")[0]
    assert "last_sync" in folder
    assert str(doc) in folder["synced_files"]

    info = LinkedFolderInfo(**folder)
    assert info.last_sync == folder["last_sync"]


def test_update_folder_sync_state_unknown_folder_writes_nothing(tmp_path: Path) -> None:
    manager, metadata_file, _folder_id, doc = _manager_with_linked_folder(tmp_path)
    before = metadata_file.read_bytes()

    manager.update_folder_sync_state("kb", "no-such-id", [str(doc)])

    assert metadata_file.read_bytes() == before


def test_sync_snapshot_preserves_change_made_during_indexing(tmp_path: Path) -> None:
    manager, _metadata_file, folder_id, doc = _manager_with_linked_folder(tmp_path)
    staged_mtime = "2026-09-01T10:00:00"
    manager.update_folder_sync_state("kb", folder_id, [str(doc)], {str(doc): staged_mtime})

    changes = manager.detect_folder_changes("kb", folder_id)
    assert changes["modified_files"] == [str(doc)]


def test_empty_successful_sync_records_last_sync_without_changing_file_state(
    tmp_path: Path,
) -> None:
    manager, metadata_file, folder_id, doc = _manager_with_linked_folder(tmp_path)
    manager.update_folder_sync_state("kb", folder_id, [str(doc)])
    before = json.loads(metadata_file.read_text(encoding="utf-8"))["linked_folders"][0]

    manager.update_folder_sync_state("kb", folder_id, [])

    after = json.loads(metadata_file.read_text(encoding="utf-8"))["linked_folders"][0]
    assert after["last_sync"]
    assert after["last_sync"] >= before["last_sync"]
    assert after["synced_files"] == before["synced_files"]


def test_update_folder_sync_state_mtime_failure_is_visible_not_fake_synced(
    tmp_path: Path,
    caplog,
    monkeypatch,
) -> None:
    """A per-file mtime recording failure must surface, not vanish.

    ``update_folder_sync_state()`` used to swallow stat/fromtimestamp errors
    with ``except Exception: pass``. The sync then reported success while the
    file's state was never recorded, hiding the degradation. The failure must
    be logged and the file must stay un-recorded so the next scan re-syncs it.
    """
    manager, metadata_file, folder_id, doc = _manager_with_linked_folder(tmp_path)

    flavour = type(Path())  # PosixPath on POSIX, WindowsPath on Windows

    class _VanishedMidStatPath(flavour):
        """exists() wins the race, stat() loses it (source vanished mid-sync)."""

        def exists(self, **kwargs):
            return True

        def stat(self, **kwargs):
            raise OSError("source vanished before stat")

    monkeypatch.setattr(manager_module, "Path", _VanishedMidStatPath)

    with caplog.at_level(logging.WARNING, logger="deeptutor.knowledge.manager"):
        manager.update_folder_sync_state("kb", folder_id, [str(doc)])

    # Visibility: the swallowed failure is now a logged warning naming the file.
    warnings_for_doc = [
        record
        for record in caplog.records
        if record.levelno >= logging.WARNING and str(doc) in record.getMessage()
    ]
    assert warnings_for_doc, f"expected a logged warning mentioning {doc}, got none"

    # Fallback semantics: the file is not marked synced, so the next scan
    # re-detects it instead of trusting a fabricated "already synced" state.
    on_disk = json.loads(metadata_file.read_text(encoding="utf-8"))
    folder = on_disk["linked_folders"][0]
    assert folder["last_sync"]
    assert str(doc) not in folder["synced_files"]
    assert folder["file_count"] == 0
    assert manager.detect_folder_changes("kb", folder_id)["new_files"] == [str(doc)]


def test_unlink_removes_only_the_source_registration(tmp_path: Path) -> None:
    manager, _metadata_file, folder_id, _doc = _manager_with_linked_folder(tmp_path)
    kb_dir = manager.base_dir / "kb"
    raw_file = kb_dir / "raw" / "note.md"
    index_marker = kb_dir / "version-1" / "index.marker"
    raw_file.parent.mkdir(parents=True)
    index_marker.parent.mkdir(parents=True)
    raw_file.write_text("imported", encoding="utf-8")
    index_marker.write_text("index", encoding="utf-8")

    assert manager.unlink_folder("kb", folder_id) is True

    assert manager.get_linked_folders("kb") == []
    assert raw_file.read_text(encoding="utf-8") == "imported"
    assert index_marker.read_text(encoding="utf-8") == "index"