El juez y el cuaderno: Stockfish y MLflow

"""Download Stockfish 19 into ``tools/stockfish/`` (gitignored). Idempotent.

Usage: ``uv run python scripts/get_stockfish.py [--force]``

Windows gets ``stockfish-windows-x86-64-universal.zip`` (sf_19 ships no separate avx2 build; the
universal binary picks the best code path at runtime). Linux gets
``stockfish-ubuntu-x86-64-avx2.tar``. The executable ends up as ``tools/stockfish/stockfish.exe``
or ``tools/stockfish/stockfish``.
"""

from __future__ import annotations

import argparse
import io
import os
import platform
import shutil
import stat
import sys
import tarfile
import urllib.request
import zipfile
from pathlib import Path

RELEASE = "sf_19"
BASE_URL = f"https://github.com/official-stockfish/Stockfish/releases/download/{RELEASE}"
ASSETS = {
    "Windows": "stockfish-windows-x86-64-universal.zip",
    "Linux": "stockfish-ubuntu-x86-64-avx2.tar",
}

def repo_root() -> Path:
    home = os.environ.get("RUKH_HOME")
    return Path(home).expanduser().resolve() if home else Path(__file__).resolve().parents[1]


def target_path(dest: Path) -> Path:
    return dest / ("stockfish.exe" if platform.system() == "Windows" else "stockfish")


def download(url: str) -> bytes:
    print(f"downloading {url}")
    request = urllib.request.Request(url, headers={"User-Agent": "rukh/get_stockfish"})
    with urllib.request.urlopen(request, timeout=120) as response:
        return response.read()

def is_executable_member(name: str) -> bool:
    """True for the engine binary inside the release archive, never for a ``src/`` file.

    Windows archives ship ``stockfish-<variant>.exe``; the others ship a plain binary with no
    extension. Both archives also contain the sources under ``src/``, which must be skipped.
    """
    path = Path(name)
    if "src" in path.parts or not path.name.startswith("stockfish"):
        return False
    if platform.system() == "Windows":
        return path.suffix == ".exe"
    return path.suffix == ""

def extract_executable(asset: str, payload: bytes, target: Path) -> None:
    """Pull the single ``stockfish*`` executable out of the archive into ``target``."""
    target.parent.mkdir(parents=True, exist_ok=True)
    if asset.endswith(".zip"):
        with zipfile.ZipFile(io.BytesIO(payload)) as archive:
            names = [
                n for n in archive.namelist() if not n.endswith("/") and is_executable_member(n)
            ]
            if not names:
                raise SystemExit(f"no stockfish executable inside {asset}")
            with archive.open(names[0]) as src, target.open("wb") as dst:
                shutil.copyfileobj(src, dst)
    else:
        with tarfile.open(fileobj=io.BytesIO(payload), mode="r:*") as archive:
            members = [
                m for m in archive.getmembers() if m.isfile() and is_executable_member(m.name)
            ]
            if not members:
                raise SystemExit(f"no stockfish executable inside {asset}")
            src = archive.extractfile(members[0])
            if src is None:
                raise SystemExit(f"cannot read {members[0].name} from {asset}")
            with src, target.open("wb") as dst:
                shutil.copyfileobj(src, dst)
    if platform.system() != "Windows":
        target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)

def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("--force", action="store_true", help="Re-download even if present.")
    parser.add_argument(
        "--dest",
        type=Path,
        default=repo_root() / "tools" / "stockfish",
        help="Destination directory (default: <repo>/tools/stockfish).",
    )
    args = parser.parse_args(argv)

    system = platform.system()
    asset = ASSETS.get(system)
    if asset is None:
        print(f"unsupported platform {system!r}; download Stockfish manually", file=sys.stderr)
        return 2

    target = target_path(args.dest)
    if target.is_file() and not args.force:
        print(f"already present: {target}")
        return 0

    payload = download(f"{BASE_URL}/{asset}")
    print(f"received {len(payload) / 1e6:.1f} MB")
    extract_executable(asset, payload, target)
    print(f"installed {target}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

"""Tests for scripts/get_stockfish.py: archive member selection."""

from __future__ import annotations

import importlib.util
import io
import tarfile
import zipfile
from pathlib import Path
from types import ModuleType

import pytest

pytestmark = pytest.mark.unit

SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "get_stockfish.py"


@pytest.fixture(scope="module")
def script() -> ModuleType:
    spec = importlib.util.spec_from_file_location("get_stockfish", SCRIPT)
    assert spec is not None and spec.loader is not None
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


def _zip(entries: dict[str, bytes]) -> bytes:
    buffer = io.BytesIO()
    with zipfile.ZipFile(buffer, "w") as archive:
        for name, payload in entries.items():
            archive.writestr(name, payload)
    return buffer.getvalue()


def _tar(entries: dict[str, bytes]) -> bytes:
    buffer = io.BytesIO()
    with tarfile.open(fileobj=buffer, mode="w") as archive:
        for name, payload in entries.items():
            info = tarfile.TarInfo(name)
            info.size = len(payload)
            archive.addfile(info, io.BytesIO(payload))
    return buffer.getvalue()


def test_windows_zip_picks_the_exe_not_the_sources(
    script: ModuleType, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.setattr(script.platform, "system", lambda: "Windows")
    payload = _zip(
        {
            "stockfish/src/stockfish.cpp": b"// source",
            "stockfish/src/stockfish.h": b"// header",
            "stockfish/stockfish-windows-x86-64-universal.exe": b"MZ-binary",
        }
    )
    target = tmp_path / "stockfish.exe"
    script.extract_executable("stockfish-windows-x86-64-universal.zip", payload, target)
    assert target.read_bytes() == b"MZ-binary"


def test_linux_tar_picks_the_plain_binary_not_the_sources(
    script: ModuleType, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.setattr(script.platform, "system", lambda: "Linux")
    payload = _tar(
        {
            "stockfish/src/stockfish.cpp": b"// source",
            "stockfish/src/stockfish": b"// source dir file without extension",
            "stockfish/stockfish-ubuntu-x86-64-avx2": b"ELF-binary",
        }
    )
    target = tmp_path / "stockfish"
    script.extract_executable("stockfish-ubuntu-x86-64-avx2.tar", payload, target)
    assert target.read_bytes() == b"ELF-binary"


def test_archive_with_only_sources_fails(
    script: ModuleType, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.setattr(script.platform, "system", lambda: "Windows")
    payload = _zip({"stockfish/src/stockfish.cpp": b"// source"})
    with pytest.raises(SystemExit, match="no stockfish executable"):
        script.extract_executable("stockfish.zip", payload, tmp_path / "stockfish.exe")

"""Tests for rukh.engine: Stockfish detection and the engine check."""

from __future__ import annotations

import json
from pathlib import Path

import pytest
from typer.testing import CliRunner

from rukh import engine
from rukh.cli import app
from rukh.engine import (
    EngineCheckResult,
    EngineError,
    EngineNotFound,
    engine_check,
    find_stockfish,
)

# The two live tests carry only `engine`, so `-m unit` never needs the Stockfish binary.
unit = pytest.mark.unit

@unit
def test_find_stockfish_honours_env(rukh_home: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    fake = rukh_home / "sf.exe"
    fake.write_bytes(b"")
    monkeypatch.setenv("RUKH_STOCKFISH", str(fake))
    assert find_stockfish() == fake


@unit
def test_find_stockfish_env_missing_file_raises(
    rukh_home: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    missing = rukh_home / "missing.exe"
    monkeypatch.setenv("RUKH_STOCKFISH", str(missing))
    monkeypatch.setattr(engine.shutil, "which", lambda _name: None)
    with pytest.raises(EngineNotFound, match=r"RUKH_STOCKFISH=.*missing\.exe is not a file"):
        find_stockfish()


@unit
def test_find_stockfish_looks_in_tools(rukh_home: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    monkeypatch.delenv("RUKH_STOCKFISH", raising=False)
    monkeypatch.setattr(engine.shutil, "which", lambda _name: None)
    assert find_stockfish() is None
    tools = rukh_home / "tools" / "stockfish"
    tools.mkdir(parents=True)
    binary = tools / "stockfish.exe"
    binary.write_bytes(b"")
    assert find_stockfish() == binary


@unit
def test_find_stockfish_falls_back_to_path(
    rukh_home: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.delenv("RUKH_STOCKFISH", raising=False)
    monkeypatch.setattr(engine.shutil, "which", lambda _name: str(rukh_home / "on-path"))
    assert find_stockfish() == rukh_home / "on-path"


@unit
def test_engine_check_without_binary_raises(
    rukh_home: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.delenv("RUKH_STOCKFISH", raising=False)
    monkeypatch.setattr(engine.shutil, "which", lambda _name: None)
    with pytest.raises(EngineNotFound):
        engine_check()


@unit
def test_cli_engine_check_without_binary_fails_cleanly(
    rukh_home: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.delenv("RUKH_STOCKFISH", raising=False)
    monkeypatch.setattr(engine.shutil, "which", lambda _name: None)
    result = CliRunner().invoke(app, ["engine", "check"])
    assert result.exit_code == 1
    assert "Stockfish" in result.output

class _FakeEngine:
    """Stand-in for ``SimpleEngine``: speaks UCI but is not Stockfish (no ``UCI_Elo``)."""

    def __init__(self) -> None:
        self.id = {"name": "not-stockfish"}
        self.options: dict[str, object] = {}

    def __enter__(self) -> _FakeEngine:
        return self

    def __exit__(self, *exc: object) -> None:
        return None


def _use_fake_engine(rukh_home: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
    binary = rukh_home / "not-stockfish.exe"
    binary.write_bytes(b"")
    monkeypatch.setenv("RUKH_STOCKFISH", str(binary))
    monkeypatch.setattr(
        engine.chess.engine.SimpleEngine, "popen_uci", staticmethod(lambda *_a, **_k: _FakeEngine())
    )
    return binary


@unit
def test_engine_check_without_uci_elo_raises_engine_error(
    rukh_home: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    _use_fake_engine(rukh_home, monkeypatch)
    with pytest.raises(EngineError, match="does not expose UCI_Elo; is it Stockfish?"):
        engine_check()


@unit
def test_engine_error_is_a_value_error() -> None:
    assert issubclass(EngineError, ValueError)


@unit
def test_cli_engine_check_without_uci_elo_fails_cleanly(
    rukh_home: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    _use_fake_engine(rukh_home, monkeypatch)
    result = CliRunner().invoke(app, ["engine", "check"])
    assert result.exit_code == 1
    assert "does not expose UCI_Elo" in result.output
    assert "Traceback" not in result.output

@pytest.mark.engine
@pytest.mark.skipif(find_stockfish() is None, reason="Stockfish binary not found")
def test_engine_check_plays_a_short_game() -> None:
    result = engine_check(elo=1400, plies=10, seed=0)
    assert isinstance(result, EngineCheckResult)
    assert result.uci_elo_min == 1320
    assert result.uci_elo_max == 3190
    assert result.elo == 1400
    assert 0 < result.plies_played <= 10
    assert result.name.lower().startswith("stockfish")
    assert result.result in {"1-0", "0-1", "1/2-1/2", "*"}


@pytest.mark.engine
@pytest.mark.skipif(find_stockfish() is None, reason="Stockfish binary not found")
def test_cli_engine_check_json() -> None:
    args = ["engine", "check", "--elo", "1400", "--plies", "6", "--json"]
    result = CliRunner().invoke(app, args)
    assert result.exit_code == 0, result.output
    payload = json.loads(result.output)
    assert payload["uci_elo_min"] == 1320
    assert payload["plies_played"] > 0

"""Tests for rukh.env and the `rukh info` command."""

from __future__ import annotations

import json
from pathlib import Path

import pytest
from typer.testing import CliRunner

from rukh import paths
from rukh.cli import app
from rukh.env import EnvReport, collect

pytestmark = pytest.mark.unit

def test_collect_returns_report_with_python_and_mlflow(rukh_home: Path) -> None:
    report = collect()
    assert isinstance(report, EnvReport)
    assert report.python.startswith("3.12")
    assert report.mlflow_uri.startswith("sqlite:///")
    assert report.data_dir == str(rukh_home / "data")
    assert report.mlruns_dir == str(rukh_home / "mlruns")
    assert isinstance(report.cuda, bool)


def test_collect_survives_missing_torch(rukh_home: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    import builtins

    real_import = builtins.__import__

    def fake_import(name: str, *args: object, **kwargs: object) -> object:
        if name == "torch" or name.startswith("torch."):
            raise ImportError("torch is not installed")
        return real_import(name, *args, **kwargs)  # type: ignore[arg-type]

    monkeypatch.setattr(builtins, "__import__", fake_import)
    report = collect()
    assert report.torch is None
    assert report.cuda is False
    assert report.gpu is None

def test_paths_follow_rukh_home(rukh_home: Path) -> None:
    assert paths.root() == rukh_home
    assert paths.data_dir() == rukh_home / "data"
    assert paths.mlruns_dir() == rukh_home / "mlruns"
    assert paths.tools_dir() == rukh_home / "tools"


def test_paths_default_to_repo_root(monkeypatch: pytest.MonkeyPatch, repo_root: Path) -> None:
    monkeypatch.delenv("RUKH_HOME", raising=False)
    assert paths.root() == repo_root

def test_info_json_is_parseable(rukh_home: Path) -> None:
    result = CliRunner().invoke(app, ["info", "--json"])
    assert result.exit_code == 0, result.output
    payload = json.loads(result.output)
    assert set(EnvReport.model_fields) <= set(payload)
    assert payload["python"].startswith("3.12")
    assert payload["mlflow_uri"].startswith("sqlite:///")


def test_info_human_output_mentions_python(rukh_home: Path) -> None:
    result = CliRunner().invoke(app, ["info"])
    assert result.exit_code == 0, result.output
    assert "python" in result.output
    assert "3.12" in result.output

"""Tests for rukh.tracking: local MLflow store and run helper."""

from __future__ import annotations

import re
import shutil
import sys
from pathlib import Path

import mlflow
import pytest

from rukh import __version__
from rukh.tracking import flatten, git_sha, start_run, tracking_uri, ui_command

pytestmark = pytest.mark.unit

def test_tracking_uri_points_to_sqlite_under_mlruns(rukh_home: Path) -> None:
    uri = tracking_uri(create=False)
    assert uri == f"sqlite:///{(rukh_home / 'mlruns' / 'mlflow.db').as_posix()}"
    assert not (rukh_home / "mlruns").exists()
    tracking_uri()
    assert (rukh_home / "mlruns").is_dir()


def test_flatten_nested_dict() -> None:
    assert flatten({"a": {"b": 1, "c": {"d": "x"}}, "e": [1, 2]}) == {
        "a.b": "1",
        "a.c.d": "x",
        "e": "[1, 2]",
    }


def test_start_run_logs_flattened_params_and_tags(rukh_home: Path) -> None:
    with start_run("t", {"a": {"b": 1}}, tags={"purpose": "test"}) as run:
        run_id = run.info.run_id
    assert (rukh_home / "mlruns" / "mlflow.db").is_file()

    mlflow.set_tracking_uri(tracking_uri())
    runs = mlflow.search_runs(experiment_names=["rukh"], output_format="list")
    found = [r for r in runs if r.info.run_id == run_id]
    assert len(found) == 1
    logged = found[0]
    assert logged.info.run_name == "t"
    assert logged.data.params["a.b"] == "1"
    assert logged.data.tags["rukh_version"] == __version__
    assert logged.data.tags["purpose"] == "test"
    assert logged.info.status == "FINISHED"

def test_git_sha_is_the_source_tree_sha_even_with_rukh_home_elsewhere(
    rukh_home: Path, repo_root: Path
) -> None:
    if shutil.which("git") is None:
        pytest.skip("git is not installed")
    if not (repo_root / ".git").exists():
        pytest.skip("source tree is not a git checkout")
    assert not (rukh_home / ".git").exists()
    sha = git_sha()
    assert sha is not None and re.fullmatch(r"[0-9a-f]{40}", sha), sha


def test_ui_command_uses_the_current_interpreter() -> None:
    argv = ui_command(host="0.0.0.0", port=5001)
    assert argv[:4] == [sys.executable, "-m", "mlflow", "ui"]
    assert argv[argv.index("--host") + 1] == "0.0.0.0"
    assert argv[argv.index("--port") + 1] == "5001"

def test_cli_has_mlflow_ui_command() -> None:
    from typer.testing import CliRunner

    from rukh.cli import app

    result = CliRunner().invoke(app, ["mlflow", "ui", "--help"])
    assert result.exit_code == 0, result.output
    assert "--port" in result.output