"""DOC-09 guard: the governance verbs are invoked as ``mgf-fed <verb>``.

The consumer/governance CLI moved from ``mgf-common`` to ``mgf-fed`` in the
federation reorg (Wave 3), so docs MUST instruct ``mgf-fed <verb>``, not the
historical ``mgf-common <verb>``. This grep guard fails on a backtick-quoted
``mgf-common <moved-verb>`` invocation anywhere in the docs.

``CHANGELOG.md`` is exempt — it legitimately documents the rename itself
(``app-doctor`` was ``mgf-common doctor``).
"""

from __future__ import annotations

import re
from pathlib import Path

_ROOT = Path(__file__).resolve().parent.parent

# Verbs that moved to `mgf-fed`. `feedback` also covers the `feedback`→
# `feedback-howto` rename; `doctor`→`app-doctor`.
_MOVED_VERBS = (
    "agents",
    "catch-up",
    "catch_up",
    "explain",
    "validate",
    "app-doctor",
    "doctor",
    "standards",
    "version",
    "logs",
    "migrate",
    "bench",
    "bundle",
    "feedback",
    "feedback-howto",
    "federation-sync",
    "start",
    "recipe",
    "new",
    "onboard",
    "sync",
    "adopt",
)
_PATTERN = re.compile(r"`mgf-common\s+(?:" + "|".join(_MOVED_VERBS) + r")\b")
_EXEMPT = {"CHANGELOG.md"}


def _docs() -> list[Path]:
    return [p for p in _ROOT.rglob("*.md") if ".venv" not in p.parts and p.name not in _EXEMPT]


def test_no_stale_mgf_common_verb_invocations() -> None:
    offenders: list[str] = []
    for md in _docs():
        for i, line in enumerate(md.read_text(encoding="utf-8").splitlines(), 1):
            if _PATTERN.search(line):
                offenders.append(f"{md.relative_to(_ROOT).as_posix()}:{i}: {line.strip()}")
    assert not offenders, (
        "DOC-09: governance verbs moved to `mgf-fed` — replace `mgf-common <verb>` "
        "with `mgf-fed <verb>`:\n  " + "\n  ".join(offenders)
    )
