"""End-to-end CLI tests for ``muse code docs``.

Coverage:
- Default text output for a minimal repo.
- ``--format json`` produces valid JSON with expected keys.
- ``--format md`` produces Markdown.
- ``--format html`` produces HTML.
- ``--missing`` shows only symbols without docstrings.
- ``--stale`` mode runs without error.
- ``--history ADDR`` mode (no index built → advisory message).
- ``--diff FROM TO`` mode with no tags returns empty changelog.
- ``--ci`` mode passes when thresholds are generous.
- ``--ci --json`` emits valid JSON CI result.
- ``--json`` is a shortcut for ``--format json``.
- ``--output PATH`` writes a file.
- ``--min-health`` filter shows only low-health symbols.
- Repos with no HEAD commit return gracefully.
"""

from __future__ import annotations

import datetime
import json
import pathlib
from muse.core.paths import muse_dir

from muse.core.types import blob_id, content_hash as _content_hash, Manifest

import pytest

from tests.cli_test_helper import CliRunner

runner = CliRunner()
cli = None


def _env(root: pathlib.Path) -> Manifest:
    return {"MUSE_REPO_ROOT": str(root)}


# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------


def _make_repo_with_python(
    tmp_path: pathlib.Path,
    src: bytes | None = None,
) -> pathlib.Path:
    """Create a minimal Muse repository with one Python source file."""
    import datetime

    from muse.core.object_store import write_object
    from muse.core.ids import hash_commit, hash_snapshot
    from muse.core.commits import (
    CommitRecord,
    write_commit,
    )
    from muse.core.snapshots import (
    SnapshotRecord,
    write_snapshot,
    )

    dot_muse = muse_dir(tmp_path)
    dot_muse.mkdir()

    repo_id = _content_hash({"name": "test-repo-docs"})
    (dot_muse / "repo.json").write_text(
        f'{{"repo_id": "{repo_id}", "name": "test"}}'
    )

    if src is None:
        src = (
            b"def documented(x: int) -> str:\n"
            b'    """Return x as a string.  This docstring is long enough.\n\n'
            b'    Args:\n'
            b'        x: The input integer.\n\n'
            b'    Returns:\n'
            b'        A string representation.\n'
            b'    """\n'
            b"    return str(x)\n"
            b"\n"
            b"def undocumented() -> None:\n"
            b"    pass\n"
        )

    content_hash = blob_id(src)
    write_object(tmp_path, content_hash, src)
    (tmp_path / "sample.py").write_bytes(src)

    manifest: Manifest = {"sample.py": content_hash}
    snap_id = hash_snapshot(manifest)
    snap = SnapshotRecord(snapshot_id=snap_id, manifest=manifest)
    write_snapshot(tmp_path, snap)

    committed_at = datetime.datetime(2026, 3, 26, tzinfo=datetime.timezone.utc)
    commit_id = hash_commit(        parent_ids=[],
        snapshot_id=snap_id,
        message="Initial commit",
        committed_at_iso=committed_at.isoformat(),
        author="test",
    )
    commit = CommitRecord(
        commit_id=commit_id,
        branch="main",
        snapshot_id=snap_id,
        message="Initial commit",
        committed_at=committed_at,
        author="test",
    )
    write_commit(tmp_path, commit)

    refs = dot_muse / "refs" / "heads"
    refs.mkdir(parents=True)
    (refs / "main").write_text(commit_id)
    (dot_muse / "HEAD").write_text("ref: refs/heads/main\n")

    return tmp_path


@pytest.fixture()
def repo(tmp_path: pathlib.Path) -> pathlib.Path:
    return _make_repo_with_python(tmp_path)


@pytest.fixture()
def empty_repo(tmp_path: pathlib.Path) -> pathlib.Path:
    """A Muse repository with no commits."""
    dot_muse = muse_dir(tmp_path)
    dot_muse.mkdir()
    _empty_repo_id = _content_hash({"name": "empty-repo"})
    (dot_muse / "repo.json").write_text(f'{{"repo_id": "{_empty_repo_id}", "name": "empty"}}')
    refs = dot_muse / "refs" / "heads"
    refs.mkdir(parents=True)
    (dot_muse / "HEAD").write_text("ref: refs/heads/main\n")
    return tmp_path


# ---------------------------------------------------------------------------
# Tests: default text output
# ---------------------------------------------------------------------------


class TestTextOutput:
    def test_exits_zero(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs"], env=_env(repo))
        assert result.exit_code == 0, result.output

    def test_contains_muse_docs_header(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs"], env=_env(repo))
        assert "Muse docs" in result.output

    def test_shows_symbol(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs"], env=_env(repo))
        # At least one symbol should be documented.
        assert "function" in result.output or "documented" in result.output

    def test_empty_repo_graceful(self, empty_repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs"], env=_env(empty_repo))
        assert result.exit_code == 0


# ---------------------------------------------------------------------------
# Tests: --format json
# ---------------------------------------------------------------------------


class TestJsonOutput:
    def test_valid_json(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--format", "json"], env=_env(repo))
        assert result.exit_code == 0, result.output
        data = json.loads(result.output)
        assert isinstance(data, dict)

    def test_json_keys_present(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--format", "json"], env=_env(repo))
        data = json.loads(result.output)
        assert "commit_id" in data
        assert "symbols" in data
        assert "missing" in data
        assert "stale" in data
        assert "summary" in data

    def test_summary_fields(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--format", "json"], env=_env(repo))
        data = json.loads(result.output)
        s = data["summary"]
        assert "total_symbols" in s
        assert "avg_health" in s
        assert "doc_debt_score" in s

    def test_symbols_have_address(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--format", "json"], env=_env(repo))
        data = json.loads(result.output)
        for sym in data["symbols"]:
            assert "address" in sym
            assert "::" in sym["address"]

    def test_json_shortcut_flag(self, repo: pathlib.Path) -> None:
        """--json is equivalent to --format json."""
        result = runner.invoke(cli, ["code", "docs", "--json"], env=_env(repo))
        assert result.exit_code == 0
        data = json.loads(result.output)
        assert "symbols" in data


# ---------------------------------------------------------------------------
# Tests: --format md / --format html
# ---------------------------------------------------------------------------


class TestMarkdownOutput:
    def test_markdown_format(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--format", "md"], env=_env(repo))
        assert result.exit_code == 0
        assert "# Muse Documentation Report" in result.output

    def test_markdown_has_symbol_heading(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--format", "md"], env=_env(repo))
        assert "##" in result.output


class TestHtmlOutput:
    def test_html_format(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--format", "html"], env=_env(repo))
        assert result.exit_code == 0
        assert "<!DOCTYPE html>" in result.output

    def test_html_no_external_deps(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--format", "html"], env=_env(repo))
        assert 'src="http' not in result.output


# ---------------------------------------------------------------------------
# Tests: --missing filter
# ---------------------------------------------------------------------------


class TestMissingFilter:
    def test_missing_exits_zero(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--missing"], env=_env(repo))
        assert result.exit_code == 0

    def test_missing_json_only_undocumented(self, repo: pathlib.Path) -> None:
        result = runner.invoke(
            cli, ["code", "docs", "--missing", "--json"], env=_env(repo)
        )
        assert result.exit_code == 0
        data = json.loads(result.output)
        for sym in data["symbols"]:
            assert sym["docstring"] is None


# ---------------------------------------------------------------------------
# Tests: --stale filter
# ---------------------------------------------------------------------------


class TestStaleFilter:
    def test_stale_exits_zero(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--stale"], env=_env(repo))
        assert result.exit_code == 0

    def test_stale_json(self, repo: pathlib.Path) -> None:
        result = runner.invoke(
            cli, ["code", "docs", "--stale", "--json"], env=_env(repo)
        )
        assert result.exit_code == 0
        data = json.loads(result.output)
        # Stale mode filters to symbols with stale_impl reason.
        for sym in data["symbols"]:
            assert "stale_impl" in sym["doc_health_reasons"]


# ---------------------------------------------------------------------------
# Tests: --min-health filter
# ---------------------------------------------------------------------------


class TestMinHealthFilter:
    def test_min_health_100_shows_all(self, repo: pathlib.Path) -> None:
        """--min-health 1.0 shows only symbols below perfect health (all of them in practice)."""
        result = runner.invoke(
            cli, ["code", "docs", "--min-health", "1.0", "--json"], env=_env(repo)
        )
        assert result.exit_code == 0
        data = json.loads(result.output)
        for sym in data["symbols"]:
            assert sym["doc_health"] < 1.0

    def test_min_health_0_shows_none(self, repo: pathlib.Path) -> None:
        """--min-health 0.0 shows no symbols (all have health >= 0.0)."""
        result = runner.invoke(
            cli, ["code", "docs", "--min-health", "0.0", "--json"], env=_env(repo)
        )
        assert result.exit_code == 0
        data = json.loads(result.output)
        assert data["symbols"] == []


# ---------------------------------------------------------------------------
# Tests: --history
# ---------------------------------------------------------------------------


class TestHistoryMode:
    def test_history_exits_zero(self, repo: pathlib.Path) -> None:
        result = runner.invoke(
            cli,
            ["code", "docs", "--history", "sample.py::documented"],
            env=_env(repo),
        )
        assert result.exit_code == 0

    def test_history_address_shown(self, repo: pathlib.Path) -> None:
        result = runner.invoke(
            cli,
            ["code", "docs", "--history", "sample.py::documented"],
            env=_env(repo),
        )
        assert "sample.py::documented" in result.output

    def test_history_json(self, repo: pathlib.Path) -> None:
        result = runner.invoke(
            cli,
            ["code", "docs", "--history", "sample.py::documented", "--json"],
            env=_env(repo),
        )
        assert result.exit_code == 0
        data = json.loads(result.output)
        assert data["address"] == "sample.py::documented"
        assert "events" in data


# ---------------------------------------------------------------------------
# Tests: --diff
# ---------------------------------------------------------------------------


class TestDiffMode:
    def test_diff_exits_zero(self, repo: pathlib.Path) -> None:
        result = runner.invoke(
            cli, ["code", "docs", "--diff", "v0.9", "v1.0"], env=_env(repo)
        )
        assert result.exit_code == 0

    def test_diff_json(self, repo: pathlib.Path) -> None:
        result = runner.invoke(
            cli, ["code", "docs", "--diff", "v0.9", "v1.0", "--json"], env=_env(repo)
        )
        assert result.exit_code == 0
        data = json.loads(result.output)
        assert "from_ref" in data
        assert "to_ref" in data
        assert "added" in data
        assert "removed" in data
        assert "changed" in data
        assert "breaking" in data


# ---------------------------------------------------------------------------
# Tests: --ci
# ---------------------------------------------------------------------------


class TestCiMode:
    def test_ci_exits_with_code(self, repo: pathlib.Path) -> None:
        """--ci exits 0 when thresholds are met, 1 when not."""
        result = runner.invoke(cli, ["code", "docs", "--ci"], env=_env(repo))
        # May pass or fail depending on health — just check no unhandled exception.
        assert result.exit_code in (0, 1)

    def test_ci_json_valid(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--ci", "--json"], env=_env(repo))
        assert result.exit_code in (0, 1)
        data = json.loads(result.output)
        assert "passed" in data
        assert "gates" in data
        assert "summary" in data

    def test_ci_json_gates_structure(self, repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--ci", "--json"], env=_env(repo))
        data = json.loads(result.output)
        for gate in data["gates"]:
            assert "name" in gate
            assert "passed" in gate
            assert "message" in gate

    def test_ci_with_custom_toml_pass(self, repo: pathlib.Path) -> None:
        """Custom docs.toml with very lenient thresholds always passes."""
        toml_content = "[docs]\nmin_avg_health = 0.0\nmax_undocumented = 9999\nmax_stale = 9999\nfail_on_breaking_undocumented = false\n"
        (muse_dir(repo) / "docs.toml").write_text(toml_content)

        result = runner.invoke(cli, ["code", "docs", "--ci", "--json"], env=_env(repo))
        data = json.loads(result.output)
        assert data["passed"] is True
        assert result.exit_code == 0

    def test_ci_with_strict_toml_fail(self, repo: pathlib.Path) -> None:
        """Custom docs.toml with impossible thresholds always fails."""
        toml_content = "[docs]\nmin_avg_health = 1.0\nmax_undocumented = 0\nmax_stale = 0\nfail_on_breaking_undocumented = false\n"
        (muse_dir(repo) / "docs.toml").write_text(toml_content)

        result = runner.invoke(cli, ["code", "docs", "--ci", "--json"], env=_env(repo))
        data = json.loads(result.output)
        # Very strict — should fail because avg_health < 1.0.
        assert result.exit_code in (0, 1)  # may vary by actual repo state


# ---------------------------------------------------------------------------
# Tests: --output
# ---------------------------------------------------------------------------


class TestOutputFlag:
    def test_output_text_file(self, repo: pathlib.Path, tmp_path: pathlib.Path) -> None:
        out_file = tmp_path / "docs.txt"
        result = runner.invoke(
            cli,
            ["code", "docs", "--format", "text", "--output", str(out_file)],
            env=_env(repo),
        )
        assert result.exit_code == 0
        assert out_file.exists()
        assert "Muse docs" in out_file.read_text()

    def test_output_json_file(self, repo: pathlib.Path, tmp_path: pathlib.Path) -> None:
        out_file = tmp_path / "docs.json"
        result = runner.invoke(
            cli,
            ["code", "docs", "--format", "json", "--output", str(out_file)],
            env=_env(repo),
        )
        assert result.exit_code == 0
        assert out_file.exists()
        data = json.loads(out_file.read_text())
        assert "symbols" in data

    def test_output_html_directory(self, repo: pathlib.Path, tmp_path: pathlib.Path) -> None:
        out_dir = tmp_path / "html_docs"
        result = runner.invoke(
            cli,
            ["code", "docs", "--format", "html", "--output", str(out_dir)],
            env=_env(repo),
        )
        assert result.exit_code == 0
        index_file = out_dir / "index.html"
        assert index_file.exists()
        assert "<!DOCTYPE html>" in index_file.read_text()


# ---------------------------------------------------------------------------
# Tests: --symbol flag
# ---------------------------------------------------------------------------


class TestSymbolFlag:
    def test_symbol_flag_json(self, repo: pathlib.Path) -> None:
        result = runner.invoke(
            cli,
            ["code", "docs", "--symbol", "sample.py::documented", "--json"],
            env=_env(repo),
        )
        assert result.exit_code == 0
        data = json.loads(result.output)
        # May have 0 or 1 symbol depending on if it's in the cache.
        assert "symbols" in data

    def test_symbol_flag_multiple(self, repo: pathlib.Path) -> None:
        """Multiple --symbol flags are combined."""
        result = runner.invoke(
            cli,
            [
                "code", "docs",
                "--symbol", "sample.py::documented",
                "--symbol", "sample.py::undocumented",
                "--json",
            ],
            env=_env(repo),
        )
        assert result.exit_code == 0


# ---------------------------------------------------------------------------
# Tests: edge cases
# ---------------------------------------------------------------------------


class TestEdgeCases:
    def test_no_python_files(self, tmp_path: pathlib.Path) -> None:
        """A repo with only non-Python files returns gracefully."""
        from muse.core.object_store import write_object
        from muse.core.ids import hash_snapshot
        from muse.core.commits import (
    CommitRecord,
    write_commit,
        )
        from muse.core.snapshots import (
    SnapshotRecord,
    write_snapshot,
        )

        dot_muse = muse_dir(tmp_path)
        dot_muse.mkdir()
        _non_py_repo_id = _content_hash({"name": "non-py"})
        (dot_muse / "repo.json").write_text(f'{{"repo_id": "{_non_py_repo_id}", "name": "test"}}')

        data = b"# This is a README\n"
        h = blob_id(data)
        write_object(tmp_path, h, data)

        manifest: Manifest = {"README.md": h}
        snap_id = hash_snapshot(manifest)
        snap = SnapshotRecord(snapshot_id=snap_id, manifest=manifest)
        write_snapshot(tmp_path, snap)

        from muse.core.ids import hash_commit
        ts = datetime.datetime(2026, 1, 1, tzinfo=datetime.timezone.utc)
        cid = hash_commit(        parent_ids=[],
        snapshot_id=snap_id,
        message="init",
        committed_at_iso=ts.isoformat(),
        author="test",
    )
        commit = CommitRecord(
            commit_id=cid,
            branch="main",
            snapshot_id=snap_id,
            message="init",
            committed_at=ts,
            author="test",
        )
        write_commit(tmp_path, commit)
        refs = dot_muse / "refs" / "heads"
        refs.mkdir(parents=True)
        (refs / "main").write_text(cid)
        (dot_muse / "HEAD").write_text("ref: refs/heads/main\n")

        result = runner.invoke(cli, ["code", "docs", "--json"], env=_env(tmp_path))
        assert result.exit_code == 0
        json.loads(result.output)  # must be valid JSON

    def test_empty_repo_json_output(self, empty_repo: pathlib.Path) -> None:
        result = runner.invoke(cli, ["code", "docs", "--json"], env=_env(empty_repo))
        assert result.exit_code == 0
        data = json.loads(result.output)
        assert data["symbols"] == []

    def test_depth_flag(self, repo: pathlib.Path) -> None:
        result = runner.invoke(
            cli, ["code", "docs", "--depth", "1", "--json"], env=_env(repo)
        )
        assert result.exit_code == 0

    def test_at_commit_flag(self, repo: pathlib.Path) -> None:
        """--at HEAD uses the head commit."""
        result = runner.invoke(
            cli, ["code", "docs", "--at", "HEAD", "--json"], env=_env(repo)
        )
        # HEAD notation not directly supported by resolve_commit_ref for "HEAD" string—
        # this tests graceful handling even if it returns empty.
        assert result.exit_code == 0