bandsaunter/tests/test_licence.py

"""The licence, and the instructions for installing under it.

Both are files a person reads rather than code that runs, which is exactly why
they are worth a test: nothing else notices when a licence file goes missing
from a package, when the version notice stops naming the terms, or when the
install instructions describe a command that no longer exists.
"""
import re
import subprocess
import sys
from pathlib import Path

import pytest

import bandsaunter

ROOT = Path(__file__).resolve().parent.parent
LICENCE = ROOT / "LICENSE"
INSTALL = ROOT / "INSTALL.md"
README = ROOT / "README.md"


# ---------------------------------------------------------------------------
# The licence itself
# ---------------------------------------------------------------------------

def test_the_licence_is_there_and_is_the_gnu_gpl():
    assert LICENCE.is_file(), "no LICENSE file"
    text = LICENCE.read_text()
    assert "GNU GENERAL PUBLIC LICENSE" in text
    assert "Version 3, 29 June 2007" in text


def test_the_licence_is_the_whole_of_it():
    """A truncated licence is not a licence.  The GPL ends with the notice it
    tells you to attach to a program, so if that is present, so is the rest."""
    text = LICENCE.read_text()
    assert "TERMS AND CONDITIONS" in text
    assert "How to Apply These Terms to Your New Programs" in text
    assert len(text.splitlines()) > 600


def test_the_packaging_metadata_says_the_same_licence():
    body = (ROOT / "pyproject.toml").read_text()
    assert 'license = {text = "GPL-3.0-or-later"}' in body
    assert "GNU General Public License v3 or later" in body


def test_the_readme_says_which_licence_and_points_at_the_file():
    body = README.read_text()
    assert "GNU General Public License" in body
    assert "[LICENSE](LICENSE)" in body


# ---------------------------------------------------------------------------
# What the programs say for themselves
# ---------------------------------------------------------------------------

@pytest.mark.parametrize("program", ["bandsaunter", "saunterbrowse"])
def test_the_version_notice_names_the_version_and_the_terms(program):
    notice = bandsaunter.version_notice(program)
    lines = notice.splitlines()
    assert lines[0] == f"{program} {bandsaunter.__version__}"
    assert "Copyright (C)" in notice
    assert "GNU GPL version 3 or later" in notice
    assert "NO WARRANTY" in notice


def test_the_command_prints_it():
    out = subprocess.run([sys.executable, "-m", "bandsaunter", "--version"],
                         capture_output=True, text=True, timeout=60)
    assert bandsaunter.__version__ in out.stdout
    assert "GPLv3+" in out.stdout
    # Four lines under the version, not reflowed into a paragraph by argparse.
    assert len(out.stdout.strip().splitlines()) == 5


# ---------------------------------------------------------------------------
# The manuals
# ---------------------------------------------------------------------------

@pytest.mark.parametrize("page", ["bandsaunter.1", "saunterbrowse.1"])
def test_both_manuals_have_a_copying_section(page):
    body = (ROOT / "packaging" / page).read_text()
    assert ".SH COPYING" in body
    assert "General\nPublic License" in body or "General Public License" in body


# ---------------------------------------------------------------------------
# The Debian package carries the licence where policy says it must
# ---------------------------------------------------------------------------

def test_the_package_ships_the_licence_at_the_path_policy_requires():
    script = (ROOT / "packaging" / "build-deb.sh").read_text()
    assert "usr/share/doc/bandsaunter/copyright" in script
    assert '"$here/LICENSE"' in script


def test_the_package_ships_the_install_instructions_too():
    assert 'INSTALL.md' in (ROOT / "packaging" / "build-deb.sh").read_text()


# ---------------------------------------------------------------------------
# The install instructions
# ---------------------------------------------------------------------------

def test_the_install_file_exists_and_is_pointed_at_from_the_readme():
    assert INSTALL.is_file(), "no INSTALL.md"
    assert "[INSTALL.md](INSTALL.md)" in README.read_text()


def test_the_install_file_covers_both_ways_of_installing():
    body = INSTALL.read_text()
    assert "./packaging/build-deb.sh" in body
    assert "python3 -m venv" in body
    assert "pip install ." in body


def test_it_warns_about_the_thing_every_debian_user_hits_first():
    """pip refuses to install outside a virtual environment on Debian and
    Fedora.  Someone who has not met PEP 668 reads that error as a broken
    program."""
    body = INSTALL.read_text()
    assert "externally-managed-environment" in body
    assert "PEP 668" in body


def test_it_lists_the_optional_dependencies_and_what_each_one_buys():
    body = INSTALL.read_text()
    for optional in ("espeak-ng", "ffmpeg", "faster-whisper", "vosk",
                     "rtl-sdr", "pyqt6", "openai-whisper", "pocketsphinx"):
        assert optional in body, optional
    # What each one buys, and what is lost without it: the two columns are
    # the point of the table, not the list of names.
    assert "Gives you" in body and "Without it" in body
    assert "Optional." in body


def test_it_lists_the_required_dependencies_and_who_needs_them():
    """Somebody installing from scratch has to be told the whole of it,
    including the one piece pip cannot bring."""
    body = INSTALL.read_text()
    for required in ("python3-numpy", "python3-scipy", "python3-rich",
                     "python3-yaml", "librtlsdr0"):
        assert required in body, required
    assert "Fedora" in body and "Arch" in body


def test_it_says_which_dependency_pip_cannot_install():
    """librtlsdr is a C library, so no virtual environment brings it and it
    is the one thing that has to come from the distribution by hand."""
    body = INSTALL.read_text()
    assert "librtlsdr" in body
    assert "pip` cannot install it" in body or "cannot come from pip" in body
    assert "dnf install rtl-sdr" in body
    assert "pacman -S rtl-sdr" in body
    assert "brew install librtlsdr" in body


def test_it_says_what_reaches_a_network_and_where_it_is_cached():
    """Nothing is fetched behind anybody's back, and somebody installing
    this on a metered or air-gapped machine has to be able to see that."""
    body = INSTALL.read_text()
    for source in ("api.adsbdb.com", "hexdb.io", "tile.openstreetmap.org",
                   "overpass-api.de"):
        assert source in body, source
    assert "~/.cache/bandsaunter/tiles" in body


def test_it_says_how_to_install_the_recogniser_and_the_model():
    """The one part with a real download in it, and the part that has to be
    put in the same environment bandsaunter runs from."""
    body = INSTALL.read_text()
    assert "pip install faster-whisper" in body
    assert "--user --break-system-packages" in body     # the ~/.local layout
    assert "bandsaunter transcribe --engines" in body   # how to check it took
    assert "Systran/faster-whisper-base.en" in body     # what gets downloaded
    assert "~/.cache/huggingface" in body               # and where it lands
    assert "WhisperModel('base.en'" in body             # fetching it on purpose


def test_the_model_the_instructions_name_is_the_one_the_program_asks_for():
    """The instructions download base.en because that is the default; if the
    default moves, they are downloading the wrong thing."""
    from bandsaunter.config import ScanConfig

    assert ScanConfig().transcribe_model in INSTALL.read_text()


def test_it_names_the_ways_a_model_can_be_supplied_without_a_network():
    body = INSTALL.read_text()
    assert "BANDSAUNTER_MODEL_DIR" in body
    assert "/usr/share/bandsaunter/models" in body
    assert "build-repo.sh" in body


def test_it_says_where_the_engine_output_switch_is():
    """A silent minute on the first transcription reads as a hang."""
    assert "BANDSAUNTER_ENGINE_OUTPUT=1" in INSTALL.read_text()


def test_the_environment_variables_it_names_are_the_ones_the_code_reads():
    from bandsaunter import transcribe as tr

    body = INSTALL.read_text()
    for variable in ("BANDSAUNTER_MODEL_DIR", "BANDSAUNTER_ENGINE_OUTPUT"):
        assert variable in body
    assert str(tr.MODEL_DIR) in body or "BANDSAUNTER_MODEL_DIR" in body


def test_the_settings_it_tells_you_to_change_exist():
    from bandsaunter.config import ScanConfig

    fields = set(ScanConfig().__dict__)
    told = set(re.findall(r"bandsaunter config ([a-z_]+)=", INSTALL.read_text()))
    assert told, "the instructions change no settings at all"
    assert told <= fields, told - fields


def test_it_says_what_to_do_when_the_dongle_is_not_found():
    body = INSTALL.read_text()
    assert "dvb_usb_rtl28xxu" in body
    assert "librtlsdr" in body


def test_every_bandsaunter_command_it_tells_you_to_run_exists():
    """An instruction to run a command that was renamed is worse than none."""
    from bandsaunter.cli import build_parser

    known = set()
    for action in build_parser()._subparsers._group_actions:
        known.update(action.choices)
    told = set(re.findall(r"^\s*(?:\$ )?bandsaunter ([a-z]+)",
                          INSTALL.read_text(), re.MULTILINE))
    assert told, "the instructions run no commands at all"
    assert told <= known | {"--version"}, told - known


def test_the_flags_it_tells_you_to_use_are_real():
    from bandsaunter.cli import build_parser

    parser = build_parser()
    for line in ("scan -b 2m --simulate", "adsb --simulate --seconds 30",
                 "devices --test", "transcribe --engines"):
        parser.parse_args(line.split())          # raises SystemExit if not


# ---------------------------------------------------------------------------
# Where it lives
# ---------------------------------------------------------------------------

REPOSITORY = "https://frostwarning.com/git/dustcouncil/bandsaunter"


def test_the_install_instructions_say_where_to_clone_from():
    """This said "git clone <the repository>" for a long time.

    Nothing noticed, because nothing reads the install instructions except
    somebody installing -- who then cannot.  A placeholder in the one
    command a new person types first is the worst place for one, so it is
    checked here rather than hoped about.
    """
    body = INSTALL.read_text()
    clones = re.findall(r"^git clone\s+(\S+)", body, re.MULTILINE)
    assert clones, "the install instructions do not say how to get the source"
    for where in clones:
        assert where.startswith(("http://", "https://", "git@", "ssh://")), \
            f"not a repository anybody can clone: {where!r}"
        assert "<" not in where and ">" not in where, \
            f"still a placeholder: {where!r}"


@pytest.mark.parametrize("path", ["INSTALL.md", "README.md",
                                  "pyproject.toml"])
def test_the_files_a_new_person_reads_have_no_placeholders_left(path):
    """Angle brackets around a word are how a placeholder is written, and
    every one of them is a sentence somebody cannot act on."""
    body = (ROOT / path).read_text()
    # Inside a fenced block a placeholder is an instruction to substitute;
    # outside one it is prose. Both are checked, and both are wrong when the
    # thing to substitute is the repository.
    for bad in ("<the repository>", "<repository>", "<repo>", "<URL>",
                "<url>"):
        assert bad not in body, f"{path} still says {bad}"


def test_the_packaging_metadata_names_the_repository():
    import tomllib

    body = tomllib.load(open(ROOT / "pyproject.toml", "rb"))
    urls = body["project"].get("urls") or {}
    assert urls, "pyproject names no homepage at all"
    assert any(REPOSITORY in v for v in urls.values())


@pytest.mark.parametrize("page", ["bandsaunter.1", "saunterbrowse.1"])
def test_both_manuals_say_where_the_source_is(page):
    body = (ROOT / "packaging" / page).read_text()
    assert REPOSITORY in body, f"{page} does not say where to find the source"


def test_the_built_package_says_where_it_came_from():
    """Debian policy asks for a Homepage field, and an installed package
    that cannot say where it came from is one nobody can update."""
    for script in ("build-deb.sh", "build-repo.sh"):
        body = (ROOT / "packaging" / script).read_text()
        assert f"Homepage: {REPOSITORY}" in body, script
        assert "Maintainer: bandsaunter" not in body, \
            f"{script} still names the package as its own maintainer"


def test_the_tile_server_is_told_where_to_look_this_program_up():
    """Not decoration: the usage policy of the service the default tiles
    come from asks for a User-Agent that identifies the application and
    gives somewhere to look it up, so that an operator with a question
    about the traffic has somebody to ask."""
    from bandsaunter.basemap import USER_AGENT

    assert "bandsaunter/" in USER_AGENT
    assert REPOSITORY in USER_AGENT
    assert bandsaunter.__version__ in USER_AGENT