MIL-005: Step 4 - Save progress

Review record RC-027 (Go, autonomous mode, not independent).

Task: MIL-005#1
Task: MIL-005#2
Task: MIL-005#3
Task: MIL-005#4
Task: MIL-005#5

tests/unit/application/test_open_study_session.py

@@ -7,6 +7,7 @@ import pytest
 from flash_card.application.dto.card_dto import CardDto
 from flash_card.application.use_cases.open_study_session import open_study_session
 from flash_card.domain.entities.card import Card
+from flash_card.domain.entities.deck import Deck
 from flash_card.domain.entities.vocabulary import Vocabulary
 from flash_card.domain.errors.vocabulary_errors import VocabularyNotFoundError
 from flash_card.domain.value_objects.language_pair import LanguagePair
@@ -20,6 +21,18 @@ class _FakeRepository:
         return self._vocabulary
 
 
+class _RecordingProgress:
+    def __init__(self, stored: Deck | None = None) -> None:
+        self.stored = stored
+        self.saved: list[tuple[Card, ...]] = []
+
+    def load(self) -> Deck | None:
+        return self.stored
+
+    def save(self, deck: Deck) -> None:
+        self.saved.append(deck.cards)
+
+
 class _MissingRepository:
     def load(self) -> Vocabulary:
         raise VocabularyNotFoundError("missing")
@@ -33,7 +46,7 @@ def test_open_study_session_builds_session_over_all_cards() -> None:
     cards = (Card("aku", "mig"), Card("kau", "du"))
     repository = _FakeRepository(Vocabulary(LanguagePair("ms", "da"), cards))
 
-    session = open_study_session(repository, _first)
+    session = open_study_session(repository, _RecordingProgress(), _first)
 
     assert session.remaining == 2
     assert session.next_card() == CardDto("aku", "mig", "ms", "da")
@@ -41,4 +54,33 @@ def test_open_study_session_builds_session_over_all_cards() -> None:
 
 def test_open_study_session_propagates_repository_error() -> None:
     with pytest.raises(VocabularyNotFoundError):
-        open_study_session(_MissingRepository(), _first)
+        open_study_session(_MissingRepository(), _RecordingProgress(), _first)
+
+
+def test_open_study_session_prefers_saved_progress() -> None:
+    pair = LanguagePair("ms", "da")
+    vocabulary = Vocabulary(pair, (Card("aku", "mig"), Card("kau", "du")))
+    progress = _RecordingProgress(Deck(pair, [Card("kau", "du")]))
+
+    session = open_study_session(_FakeRepository(vocabulary), progress, _first)
+
+    assert session.remaining == 1
+    assert session.next_card() == CardDto("kau", "du", "ms", "da")
+
+
+def test_open_study_session_skips_vocabulary_when_progress_exists() -> None:
+    progress = _RecordingProgress(Deck(LanguagePair("ms", "da"), []))
+
+    session = open_study_session(_MissingRepository(), progress, _first)
+
+    assert session.remaining == 0
+
+
+def test_open_study_session_never_saves_on_start() -> None:
+    vocabulary = Vocabulary(LanguagePair("ms", "da"), (Card("aku", "mig"),))
+    progress = _RecordingProgress()
+
+    session = open_study_session(_FakeRepository(vocabulary), progress, _first)
+    session.next_card()
+
+    assert progress.saved == []

tests/unit/application/test_study_session.py

@@ -17,8 +17,20 @@ def _first(cards: Sequence[Card]) -> Card:
     return cards[0]
 
 
-def _session(*cards: Card) -> StudySession:
-    return StudySession(Deck(PAIR, cards), _first)
+class _RecordingProgress:
+    def __init__(self) -> None:
+        self.saved: list[tuple[Card, ...]] = []
+
+    def load(self) -> Deck | None:
+        return None
+
+    def save(self, deck: Deck) -> None:
+        self.saved.append(deck.cards)
+
+
+def _session(*cards: Card, progress: _RecordingProgress | None = None) -> StudySession:
+    store = _RecordingProgress() if progress is None else progress
+    return StudySession(Deck(PAIR, cards), _first, store)
 
 
 def test_current_card_is_none_before_first_draw() -> None:
@@ -58,3 +70,38 @@ def test_remaining_counts_cards_in_deck() -> None:
     session = _session(A, B)
     session.next_card()
     assert session.remaining == 2
+
+
+def test_mark_known_removes_current_card_and_saves_remaining_once() -> None:
+    progress = _RecordingProgress()
+    session = _session(A, B, progress=progress)
+    session.next_card()
+    session.mark_known()
+    assert session.remaining == 1
+    assert session.current_card is None
+    assert progress.saved == [(B,)]
+
+
+def test_mark_known_saves_nothing_when_no_current_card() -> None:
+    progress = _RecordingProgress()
+    session = _session(A, progress=progress)
+    session.mark_known()
+    assert session.remaining == 1
+    assert progress.saved == []
+
+
+def test_mark_known_on_last_card_leaves_session_finished() -> None:
+    progress = _RecordingProgress()
+    session = _session(A, progress=progress)
+    session.next_card()
+    session.mark_known()
+    assert progress.saved == [()]
+    assert session.next_card() is None
+
+
+def test_next_card_never_saves() -> None:
+    progress = _RecordingProgress()
+    session = _session(A, B, progress=progress)
+    session.next_card()
+    session.next_card()
+    assert progress.saved == []

tests/unit/infrastructure/test_csv_progress_repository.py

@@ -0,0 +1,112 @@
+"""Tests of write_word_list and CsvProgressRepository."""
+
+from pathlib import Path
+
+import pytest
+
+from flash_card.domain.entities.card import Card
+from flash_card.domain.entities.deck import Deck
+from flash_card.domain.errors.vocabulary_errors import VocabularyFormatError
+from flash_card.domain.value_objects.language_pair import LanguagePair
+from flash_card.infrastructure.persistence.csv_progress_repository import (
+    CsvProgressRepository,
+)
+from flash_card.infrastructure.persistence.csv_word_list import (
+    read_word_list,
+    write_word_list,
+)
+
+PAIR = LanguagePair("ms", "da")
+CARDS = (Card("aku", "mig"), Card("kau", "du"))
+
+
+def test_write_word_list_round_trips_through_read_word_list(tmp_path: Path) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    assert read_word_list(path) == (PAIR, CARDS)
+
+
+def test_write_word_list_writes_header_and_rows_with_semicolon(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    raw = path.read_bytes()
+    assert raw.decode("utf-8-sig") == "ms;da\naku;mig\nkau;du\n"
+    assert b"\r" not in raw
+
+
+def test_write_word_list_keeps_non_ascii_text(tmp_path: Path) -> None:
+    path = tmp_path / "w.csv"
+    cards = (Card("chaque", "each"), Card("parlé", "speak"))
+    write_word_list(path, LanguagePair("fr", "en"), cards)
+    assert read_word_list(path)[1] == cards
+
+
+def test_write_word_list_writes_header_only_for_no_cards(tmp_path: Path) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, ())
+    assert read_word_list(path) == (PAIR, ())
+
+
+def test_write_word_list_creates_parent_folder(tmp_path: Path) -> None:
+    path = tmp_path / "data" / "deep" / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    assert path.is_file()
+
+
+def test_write_word_list_replaces_file_and_leaves_no_temporary_file(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    write_word_list(path, PAIR, CARDS[:1])
+    assert read_word_list(path)[1] == CARDS[:1]
+    assert [item.name for item in tmp_path.iterdir()] == ["w.csv"]
+
+
+def test_write_word_list_keeps_old_file_and_no_temporary_when_write_fails(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    unencodable = (Card("aku", "\ud800"),)
+    with pytest.raises(UnicodeEncodeError):
+        write_word_list(path, PAIR, unencodable)
+    assert read_word_list(path)[1] == CARDS
+    assert [item.name for item in tmp_path.iterdir()] == ["w.csv"]
+
+
+def test_progress_load_returns_none_when_file_is_missing(tmp_path: Path) -> None:
+    assert CsvProgressRepository(tmp_path / "p.csv").load() is None
+
+
+def test_progress_load_returns_empty_deck_for_header_only_file(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "p.csv"
+    path.write_text("ms;da\n", encoding="utf-8")
+    deck = CsvProgressRepository(path).load()
+    assert deck is not None
+    assert deck.is_empty
+    assert deck.language_pair == PAIR
+
+
+def test_progress_load_raises_format_error_and_keeps_malformed_file(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "p.csv"
+    content = b"ms;da\naku;mig;extra\n"
+    path.write_bytes(content)
+    with pytest.raises(VocabularyFormatError):
+        CsvProgressRepository(path).load()
+    assert path.read_bytes() == content
+
+
+def test_progress_save_then_load_returns_same_cards(tmp_path: Path) -> None:
+    repository = CsvProgressRepository(tmp_path / "p.csv")
+    repository.save(Deck(PAIR, CARDS))
+    deck = repository.load()
+    assert deck is not None
+    assert deck.cards == CARDS
+    assert deck.language_pair == PAIR

tests/unit/test_flash_card_view_model.py

@@ -20,8 +20,22 @@ def _first(cards: Sequence[Card]) -> Card:
     return cards[0]
 
 
-def _session(code: str, *cards: Card) -> StudySession:
-    return StudySession(Deck(LanguagePair(code, "da"), cards), _first)
+class _RecordingProgress:
+    def __init__(self) -> None:
+        self.saved: list[tuple[Card, ...]] = []
+
+    def load(self) -> Deck | None:
+        return None
+
+    def save(self, deck: Deck) -> None:
+        self.saved.append(deck.cards)
+
+
+def _session(
+    code: str, *cards: Card, progress: _RecordingProgress | None = None
+) -> StudySession:
+    store = _RecordingProgress() if progress is None else progress
+    return StudySession(Deck(LanguagePair(code, "da"), cards), _first, store)
 
 
 def test_view_model_draws_first_card_on_construction() -> None:
@@ -90,3 +104,45 @@ def test_next_card_resets_side_to_front() -> None:
     assert view_model.side is Side.FRONT
     assert view_model.language_name == "Malay"
     assert view_model.text == "kau"
+
+
+def test_is_known_saves_remaining_and_shows_next_front() -> None:
+    progress = _RecordingProgress()
+    view_model = FlashCardViewModel(_session("ms", A, B, progress=progress))
+    view_model.flip_card()
+    view_model.is_known()
+    assert progress.saved == [(B,)]
+    assert view_model.side is Side.FRONT
+    assert view_model.text == "kau"
+    assert not view_model.is_finished
+
+
+def test_is_known_on_last_card_finishes() -> None:
+    progress = _RecordingProgress()
+    view_model = FlashCardViewModel(_session("ms", A, progress=progress))
+    view_model.is_known()
+    assert view_model.is_finished
+    assert view_model.text == FINISHED_MESSAGE
+    assert progress.saved == [()]
+
+
+def test_is_known_does_nothing_when_finished() -> None:
+    progress = _RecordingProgress()
+    view_model = FlashCardViewModel(_session("ms", progress=progress))
+    view_model.is_known()
+    assert view_model.is_finished
+    assert progress.saved == []
+
+
+def test_next_card_does_nothing_when_finished() -> None:
+    view_model = FlashCardViewModel(_session("ms"))
+    view_model.next_card()
+    assert view_model.is_finished
+    assert view_model.text == FINISHED_MESSAGE
+
+
+def test_next_card_never_saves() -> None:
+    progress = _RecordingProgress()
+    view_model = FlashCardViewModel(_session("ms", A, B, progress=progress))
+    view_model.next_card()
+    assert progress.saved == []