Implement the NATO converter with tests and Doxygen comments

Task: MIL-002#2
Refs #9
Refs #10
Refs #11
Refs #12
Refs #13

tests/adapters/test_console.py

@@ -0,0 +1,71 @@
+import pytest
+
+from nato_alphabet import constants
+from nato_alphabet.adapters.console import TerminalConsole
+from nato_alphabet.application.ports import InputClosedError
+from nato_alphabet.main import main
+
+
+def _feed(monkeypatch: pytest.MonkeyPatch, answers: list[str]) -> list[str]:
+    prompts: list[str] = []
+
+    def fake_input(prompt: str = "") -> str:
+        prompts.append(prompt)
+        if not answers:
+            raise EOFError
+        return answers.pop(0)
+
+    monkeypatch.setattr("builtins.input", fake_input)
+    return prompts
+
+
+def test_main_prints_code_words_for_valid_word(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _feed(monkeypatch, ["Hello"])
+
+    status = main()
+
+    lines = capsys.readouterr().out.splitlines()
+    assert status == constants.EXIT_OK
+    assert lines == [constants.RESULT_TEXT, "Hotel", "Echo", "Lima", "Lima", "Oscar"]
+
+
+def test_main_asks_again_after_invalid_word(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    prompts = _feed(monkeypatch, ["h3llo", "Hi"])
+
+    main()
+
+    lines = capsys.readouterr().out.splitlines()
+    assert prompts == [constants.PROMPT_TEXT, constants.PROMPT_TEXT]
+    assert lines == [
+        constants.INVALID_INPUT_TEXT,
+        constants.RESULT_TEXT,
+        "Hotel",
+        "India",
+    ]
+
+
+def test_main_ends_cleanly_on_end_of_input(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _feed(monkeypatch, [])
+
+    status = main()
+
+    assert status == constants.EXIT_OK
+    assert capsys.readouterr().out == ""
+
+
+def test_terminal_console_raises_input_closed_on_interrupt(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def interrupted(prompt: str = "") -> str:
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr("builtins.input", interrupted)
+
+    with pytest.raises(InputClosedError):
+        TerminalConsole().ask_word()

tests/adapters/test_csv_alphabet.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from nato_alphabet.adapters.csv_alphabet import CsvAlphabetSource, load_nato_dict
+
+EXPECTED_ENTRIES = 26
+
+
+def test_load_nato_dict_reads_temporary_csv(tmp_path: Path) -> None:
+    data_file = tmp_path / "alphabet.csv"
+    data_file.write_text("letter,code\na,Alfa\nB,Bravo\n", encoding="utf-8")
+
+    assert load_nato_dict(data_file) == {"A": "Alfa", "B": "Bravo"}
+
+
+def test_load_nato_dict_builds_all_entries_from_packaged_file() -> None:
+    alphabet = load_nato_dict()
+
+    assert len(alphabet) == EXPECTED_ENTRIES
+    assert alphabet["Z"] == "Zulu"
+
+
+def test_csv_alphabet_source_loads_given_file(tmp_path: Path) -> None:
+    data_file = tmp_path / "alphabet.csv"
+    data_file.write_text("letter,code\nA,Alfa\n", encoding="utf-8")
+
+    assert CsvAlphabetSource(data_file).load() == {"A": "Alfa"}

tests/application/test_spell_word_session.py

@@ -0,0 +1,56 @@
+from collections.abc import Mapping
+
+from nato_alphabet.application.ports import InputClosedError
+from nato_alphabet.application.spell_word_session import SpellWordSession
+
+
+class FakeSource:
+    def load(self) -> Mapping[str, str]:
+        return {"A": "Alfa", "B": "Bravo"}
+
+
+class FakeConsole:
+    def __init__(self, words: list[str]) -> None:
+        self._words = words
+        self.asked = 0
+        self.invalid = 0
+        self.shown: list[list[str]] = []
+
+    def ask_word(self) -> str:
+        self.asked += 1
+        if not self._words:
+            raise InputClosedError
+        return self._words.pop(0)
+
+    def show_invalid(self) -> None:
+        self.invalid += 1
+
+    def show_code_words(self, code_words: list[str]) -> None:
+        self.shown.append(code_words)
+
+
+def test_run_shows_code_words_for_valid_word() -> None:
+    console = FakeConsole(["ab"])
+
+    SpellWordSession(FakeSource(), console).run()
+
+    assert console.shown == [["Alfa", "Bravo"]]
+    assert console.asked == 1
+
+
+def test_run_asks_again_after_invalid_word() -> None:
+    console = FakeConsole(["a1", "", "b"])
+
+    SpellWordSession(FakeSource(), console).run()
+
+    assert console.invalid == 2
+    assert console.asked == 3
+    assert console.shown == [["Bravo"]]
+
+
+def test_run_ends_cleanly_when_input_is_closed() -> None:
+    console = FakeConsole([])
+
+    SpellWordSession(FakeSource(), console).run()
+
+    assert console.shown == []

tests/domain/test_spelling.py

@@ -0,0 +1,43 @@
+import pytest
+
+from nato_alphabet.adapters.csv_alphabet import load_nato_dict
+from nato_alphabet.domain.spelling import InvalidWordError, generate_phonetic
+
+ALPHABET = load_nato_dict()
+LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+
+@pytest.mark.parametrize("letter", list(LETTERS))
+def test_generate_phonetic_maps_letter_to_its_code_word(letter: str) -> None:
+    assert generate_phonetic(letter, ALPHABET) == [ALPHABET[letter]]
+
+
+def test_generate_phonetic_uses_known_code_words() -> None:
+    assert generate_phonetic("ADZ", ALPHABET) == ["Alfa", "Delta", "Zulu"]
+
+
+def test_generate_phonetic_covers_all_26_letters() -> None:
+    assert len(generate_phonetic(LETTERS, ALPHABET)) == len(LETTERS)
+
+
+def test_generate_phonetic_is_case_insensitive_for_mixed_case() -> None:
+    assert generate_phonetic("Hello", ALPHABET) == [
+        "Hotel",
+        "Echo",
+        "Lima",
+        "Lima",
+        "Oscar",
+    ]
+
+
+@pytest.mark.parametrize("word", ["a1", "two words", "hi!", "", "ß", "æ"])
+def test_generate_phonetic_raises_for_non_letter_or_empty(word: str) -> None:
+    with pytest.raises(InvalidWordError):
+        generate_phonetic(word, ALPHABET)
+
+
+def test_generate_phonetic_keeps_cause_of_invalid_character() -> None:
+    with pytest.raises(InvalidWordError) as info:
+        generate_phonetic("a1", ALPHABET)
+
+    assert isinstance(info.value.__cause__, KeyError)

tests/test_main_module.py

@@ -0,0 +1,30 @@
+import subprocess
+import sys
+
+from nato_alphabet import constants
+
+
+def _run_module(stdin_text: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, "-m", "nato_alphabet"],
+        input=stdin_text,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=30,
+    )
+
+
+def test_python_dash_m_spells_word_from_piped_input() -> None:
+    result = _run_module("Hi\n")
+
+    assert result.returncode == 0
+    assert constants.RESULT_TEXT in result.stdout
+    assert result.stdout.splitlines()[-2:] == ["Hotel", "India"]
+
+
+def test_python_dash_m_exits_cleanly_on_end_of_input() -> None:
+    result = _run_module("")
+
+    assert result.returncode == 0
+    assert result.stderr == ""