"""evaluation/pipeline.py（evaluate_image）の仕様ベーステスト．

仕様出典:
- docs/04_SPEC/SPEC_04_評価仕様.md
  「出力ファイル仕様」: <dir>/metrics.csv と <dir>/figures/{luminance_map, histogram,
  radial_profile, zone_map}.png
  「metrics.csv カラム定義」: cov, std, max_min_ratio, mean, max, min,
  center_*, middle_*, periphery_*, center_periphery_ratio, gradient_magnitude
- docs/04_SPEC/SPEC_02_シーン定義仕様.md「evaluation」セクション（ROI / zones / metrics）
- docs/04_SPEC/SPEC_01_アーキテクチャ設計.md（evaluate パイプラインの責務分離）

検証する仕様:
- evaluate_image() が CLI と同じ評価を行い，指標の辞書を返す
- save_figures=False のとき figures/ を作らず描画もしない（指標は変わらない）
- 段階ごとの失敗は EvaluationStepError として，どの段階かが分かる文言で送出される
  （CLI はこれを「エラー: …」+ 終了コード 1 に変換するだけ）

テスト方針（testing.md）:
- ファイル I/O はモックせず tmp_path で実ファイルを使う
- 合成輝度マップは seed を固定する
"""

from __future__ import annotations

import matplotlib  # noqa: I001

# headless 環境でも動くよう Agg バックエンドを pyplot より前に設定する
matplotlib.use("Agg")

from pathlib import Path

import numpy
import pytest

from sm_tias_lightsim.evaluation.pipeline import EvaluationStepError, evaluate_image

# SPEC_04「metrics.csv カラム定義（ヘッダ順）」の必須列
_BASE_COLUMNS = ("cov", "std", "max_min_ratio", "mean", "max", "min")
_ZONE_COLUMNS = (
    "center_mean",
    "center_std",
    "middle_mean",
    "middle_std",
    "periphery_mean",
    "periphery_std",
    "center_periphery_ratio",
    "gradient_magnitude",
)
# SPEC_04「可視化規約」の 4 種
_FIGURE_FILES = ("luminance_map.png", "histogram.png", "radial_profile.png", "zone_map.png")


def _make_luminance_array(seed: int = 0, size: int = 128) -> numpy.ndarray:
    """ゼロを含まない合成輝度配列を返す（seed 固定）．"""
    rng = numpy.random.RandomState(seed)
    return numpy.full((size, size), 100.0) + rng.normal(0, 5, (size, size))


def _write_npy(tmp_path: Path, seed: int = 0, size: int = 128) -> Path:
    path = tmp_path / "luminance.npy"
    numpy.save(path, _make_luminance_array(seed=seed, size=size))
    return path


def _write_eval_yaml(
    tmp_path: Path,
    x: int = 16,
    y: int = 16,
    width: int = 96,
    height: int = 96,
    zones_enabled: bool = True,
    radial_profile: bool = True,
) -> Path:
    """評価専用 YAML（トップレベルが EvaluationConfig 互換）を書き出す．"""
    content = f"""\
roi:
  type: image_pixel
  x: {x}
  y: {y}
  width: {width}
  height: {height}
zones:
  enabled: {"true" if zones_enabled else "false"}
  boundaries: [0.33, 0.66]
metrics:
  cov: true
  std: true
  max_min: true
  radial_profile: {"true" if radial_profile else "false"}
"""
    path = tmp_path / "eval_config.yaml"
    path.write_text(content, encoding="utf-8")
    return path


# ---------------------------------------------------------------------------
# 正常系: 既定（save_figures=True）
# ---------------------------------------------------------------------------


def test_returns_metrics_dict(tmp_path: Path):
    """evaluate_image が指標の辞書を返すこと．

    仕様: SPEC_04「metrics.csv カラム定義」の基本 6 指標を含む．
    """
    metrics = evaluate_image(
        _write_npy(tmp_path, seed=0), _write_eval_yaml(tmp_path), tmp_path / "out"
    )
    assert isinstance(metrics, dict)
    for key in _BASE_COLUMNS:
        assert key in metrics, key
        assert isinstance(metrics[key], float)


def test_returned_metrics_are_physically_consistent(tmp_path: Path):
    """返された指標が互いに整合すること（min <= mean <= max・CoV = std/mean）．"""
    metrics = evaluate_image(
        _write_npy(tmp_path, seed=1), _write_eval_yaml(tmp_path), tmp_path / "out"
    )
    assert metrics["min"] <= metrics["mean"] <= metrics["max"]
    assert metrics["cov"] == pytest.approx(metrics["std"] / metrics["mean"], rel=1e-9)
    assert metrics["max_min_ratio"] == pytest.approx(metrics["max"] / metrics["min"], rel=1e-9)


def test_zone_metrics_included_when_zones_enabled(tmp_path: Path):
    """zones.enabled のときゾーン指標が辞書に含まれること（SPEC_04 3 ゾーン分析）．"""
    metrics = evaluate_image(
        _write_npy(tmp_path, seed=2), _write_eval_yaml(tmp_path), tmp_path / "out"
    )
    for key in _ZONE_COLUMNS:
        assert key in metrics, key


def test_creates_metrics_csv(tmp_path: Path):
    """metrics.csv が出力ディレクトリ直下に作られること（SPEC_04 出力ファイル仕様）．"""
    out_dir = tmp_path / "out"
    evaluate_image(_write_npy(tmp_path, seed=3), _write_eval_yaml(tmp_path), out_dir)
    assert (out_dir / "metrics.csv").is_file()


def test_metrics_csv_matches_returned_dict(tmp_path: Path):
    """metrics.csv の内容が戻り値の辞書と一致すること．"""
    import csv

    out_dir = tmp_path / "out"
    metrics = evaluate_image(_write_npy(tmp_path, seed=4), _write_eval_yaml(tmp_path), out_dir)
    with (out_dir / "metrics.csv").open(encoding="utf-8") as fh:
        row = next(csv.DictReader(fh))
    assert set(row) == set(metrics)
    for key, value in row.items():
        assert float(value) == pytest.approx(metrics[key], rel=1e-6)


def test_creates_four_figures_by_default(tmp_path: Path):
    """既定（save_figures 省略）で figures/ に 4 種の PNG が出ること（SPEC_04 可視化規約）．"""
    out_dir = tmp_path / "out"
    evaluate_image(_write_npy(tmp_path, seed=5), _write_eval_yaml(tmp_path), out_dir)
    for name in _FIGURE_FILES:
        assert (out_dir / "figures" / name).is_file(), name


def test_creates_deep_nested_output_dir(tmp_path: Path):
    """出力ディレクトリが親ごと作られること．"""
    out_dir = tmp_path / "a" / "b" / "c"
    evaluate_image(_write_npy(tmp_path, seed=6), _write_eval_yaml(tmp_path), out_dir)
    assert (out_dir / "metrics.csv").is_file()


# ---------------------------------------------------------------------------
# save_figures=False（スイープ用の図なしモード）
# ---------------------------------------------------------------------------


def test_no_figures_dir_when_save_figures_false(tmp_path: Path):
    """save_figures=False のとき figures/ が作られないこと．"""
    out_dir = tmp_path / "out"
    evaluate_image(
        _write_npy(tmp_path, seed=7), _write_eval_yaml(tmp_path), out_dir, save_figures=False
    )
    assert not (out_dir / "figures").exists()


def test_metrics_csv_still_created_when_save_figures_false(tmp_path: Path):
    """save_figures=False でも metrics.csv は出ること（指標だけ欲しい用途）．"""
    out_dir = tmp_path / "out"
    evaluate_image(
        _write_npy(tmp_path, seed=8), _write_eval_yaml(tmp_path), out_dir, save_figures=False
    )
    assert (out_dir / "metrics.csv").is_file()


def test_metrics_identical_with_and_without_figures(tmp_path: Path):
    """図の有無で指標が変わらないこと（描画は評価結果に影響しない）．"""
    npy = _write_npy(tmp_path, seed=9)
    config = _write_eval_yaml(tmp_path)
    with_figs = evaluate_image(npy, config, tmp_path / "with", save_figures=True)
    without_figs = evaluate_image(npy, config, tmp_path / "without", save_figures=False)
    assert set(with_figs) == set(without_figs)
    for key in with_figs:
        assert with_figs[key] == pytest.approx(without_figs[key], rel=1e-12)


def test_summary_omits_figures_line_when_save_figures_false(tmp_path: Path, capsys):
    """save_figures=False のときサマリーに figures/ 行を出さないこと．"""
    evaluate_image(
        _write_npy(tmp_path, seed=10),
        _write_eval_yaml(tmp_path),
        tmp_path / "out",
        save_figures=False,
    )
    out = capsys.readouterr().out
    assert "metrics.csv" in out
    assert "figures/" not in out


def test_summary_includes_figures_line_by_default(tmp_path: Path, capsys):
    """既定ではサマリーに figures/ 行が出ること（従来どおり）．"""
    evaluate_image(_write_npy(tmp_path, seed=11), _write_eval_yaml(tmp_path), tmp_path / "out")
    assert "figures/" in capsys.readouterr().out


def test_no_figure_files_written_anywhere_when_disabled(tmp_path: Path):
    """save_figures=False のとき出力ディレクトリ配下に PNG が 1 つも無いこと．"""
    out_dir = tmp_path / "out"
    evaluate_image(
        _write_npy(tmp_path, seed=12), _write_eval_yaml(tmp_path), out_dir, save_figures=False
    )
    assert list(out_dir.rglob("*.png")) == []


# ---------------------------------------------------------------------------
# 異常系: 段階別の EvaluationStepError
# ---------------------------------------------------------------------------


def test_missing_image_raises_step_error(tmp_path: Path):
    """画像が無いとき EvaluationStepError になること（見つからない旨を含む）．"""
    with pytest.raises(EvaluationStepError) as exc:
        evaluate_image(tmp_path / "nope.npy", _write_eval_yaml(tmp_path), tmp_path / "out")
    assert "画像ファイルが見つかりません" in str(exc.value)


def test_broken_image_raises_load_step_error(tmp_path: Path):
    """壊れた .npy は「画像の読み込みに失敗しました」段階の例外になること．"""
    bad = tmp_path / "broken.npy"
    bad.write_bytes(b"not a npy file")
    with pytest.raises(EvaluationStepError) as exc:
        evaluate_image(bad, _write_eval_yaml(tmp_path), tmp_path / "out")
    assert "画像の読み込みに失敗しました" in str(exc.value)


def test_missing_config_raises_step_error(tmp_path: Path):
    """設定 YAML が無いとき EvaluationStepError になること．"""
    with pytest.raises(EvaluationStepError) as exc:
        evaluate_image(_write_npy(tmp_path, seed=13), tmp_path / "nope.yaml", tmp_path / "out")
    assert "設定 YAML ファイルが見つかりません" in str(exc.value)


def test_invalid_config_raises_config_step_error(tmp_path: Path):
    """ROI 欠落の YAML は「設定 YAML の読み込みに失敗しました」段階の例外になること．"""
    config = tmp_path / "bad.yaml"
    config.write_text("zones:\n  enabled: true\n", encoding="utf-8")
    with pytest.raises(EvaluationStepError) as exc:
        evaluate_image(_write_npy(tmp_path, seed=14), config, tmp_path / "out")
    assert "設定 YAML の読み込みに失敗しました" in str(exc.value)


def test_roi_out_of_bounds_raises_roi_step_error(tmp_path: Path):
    """ROI が画像外のとき「ROI 抽出に失敗しました」段階の例外になること．"""
    config = _write_eval_yaml(tmp_path, x=0, y=0, width=9999, height=9999)
    with pytest.raises(EvaluationStepError) as exc:
        evaluate_image(_write_npy(tmp_path, seed=15), config, tmp_path / "out")
    assert "ROI 抽出に失敗しました" in str(exc.value)


def test_zero_luminance_raises_metrics_step_error(tmp_path: Path):
    """全ゼロ画像は「均一性指標の算出に失敗しました」段階の例外になること．"""
    npy = tmp_path / "zeros.npy"
    numpy.save(npy, numpy.zeros((128, 128), dtype=numpy.float64))
    with pytest.raises(EvaluationStepError) as exc:
        evaluate_image(npy, _write_eval_yaml(tmp_path), tmp_path / "out")
    assert "均一性指標の算出に失敗しました" in str(exc.value)


def test_step_error_is_runtime_error_subclass():
    """EvaluationStepError は RuntimeError 派生であること（呼び出し側の捕捉粒度）．"""
    assert issubclass(EvaluationStepError, RuntimeError)


def test_no_output_written_when_roi_fails(tmp_path: Path):
    """ROI 抽出で失敗したとき metrics.csv は作られないこと（中途半端な出力を残さない）．"""
    out_dir = tmp_path / "out"
    config = _write_eval_yaml(tmp_path, x=0, y=0, width=9999, height=9999)
    with pytest.raises(EvaluationStepError):
        evaluate_image(_write_npy(tmp_path, seed=16), config, out_dir)
    assert not (out_dir / "metrics.csv").exists()