"""Docs checks for agent temp-artifact cleanup guidance (#261).

Failed subagent runs left throwaway helper scripts (e.g.
``_encode_commit_payload.py``, ``_emit_payload.py``) in the shared working
tree, polluting ``git status`` and tripping issue-lock / preflight gates.
These tests keep the cleanup runbook guidance present and the ignore
patterns in place so stray helpers can never dirty a worktree again.
"""
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parent.parent
RUNBOOK = REPO_ROOT / "docs" / "llm-workflow-runbooks.md"
GITIGNORE = REPO_ROOT / ".gitignore"

ARTIFACT_PATTERNS = ("_encode_*.py", "_emit_*.py", "_inline_*.py")


def _runbook_text():
    assert RUNBOOK.is_file(), "missing docs/llm-workflow-runbooks.md"
    return RUNBOOK.read_text(encoding="utf-8")


def _gitignore_text():
    assert GITIGNORE.is_file(), "missing .gitignore"
    return GITIGNORE.read_text(encoding="utf-8")


def test_runbook_has_agent_temp_artifact_cleanup_section():
    text = _runbook_text()
    assert "## Agent temp artifact cleanup" in text, (
        "runbook lacks an 'Agent temp artifact cleanup' section")
    assert "#261" in text, "cleanup guidance does not reference issue #261"


def test_runbook_names_known_stray_artifacts():
    text = _runbook_text()
    for name in ("_encode_commit_payload.py", "_emit_payload.py"):
        assert name in text, f"runbook does not name stray artifact {name!r}"


def test_runbook_covers_all_artifact_patterns():
    text = _runbook_text()
    for pattern in ("_encode_*", "_emit_*", "_inline_*"):
        assert pattern in text, f"runbook does not cover pattern {pattern!r}"


def test_runbook_requires_cleanup_after_commit_or_abort():
    text = _runbook_text().lower()
    assert "delete" in text or "remove" in text
    for phase in ("completes", "aborts"):
        assert phase in text, (
            f"runbook does not require cleanup when the MCP commit {phase}")


def test_runbook_explains_lock_and_preflight_impact():
    text = _runbook_text().lower()
    assert "gitea_lock_issue" in text
    assert "preflight" in text or "pre-flight" in text


def test_gitignore_blocks_agent_helper_patterns():
    lines = [
        ln.strip() for ln in _gitignore_text().splitlines()
        if ln.strip() and not ln.strip().startswith("#")
    ]
    for pattern in ARTIFACT_PATTERNS:
        assert pattern in lines, f".gitignore lacks pattern {pattern!r}"


def test_no_stray_agent_helpers_in_repo_root():
    """Acceptance: artifacts stay removed from default worktrees."""
    stray = [
        p.name for pattern in ARTIFACT_PATTERNS
        for p in REPO_ROOT.glob(pattern)
    ]
    assert not stray, f"stray agent helper artifacts present: {stray}"