"""muse#227 (companion musehub#227) — the identity plugin's own docs must
describe I3 accurately: per-edge signature authorization (enforced at push
time, hub-side, in musehub/graph/push_validator.py), not "quorum soundness"
(a different, unrelated, never-invoked mechanism in musehub/graph/quorum.py).

Before this fix, muse/plugins/identity/plugin.py's module docstring and its
schema() description both labeled I3 "quorum soundness" — pointing readers
at the wrong one of the two non-reconciled "I3" definitions that existed in
the musehub codebase (musehub#227's own audit). Fixed on both sides: this
repo's docs now say "authorization", and musehub/graph/quorum.py no longer
claims the "I3" label at all.
"""
from __future__ import annotations

import re

from muse.plugins.identity import plugin as identity_plugin


def _claims_label(doc: str, label: str) -> bool:
    """True if *doc* uses *label* as an invariant-naming claim (a line
    starting with the label followed eventually by a separator), not just
    mentioning it in passing prose."""
    pattern = re.compile(rf"^\s*{re.escape(label)}\b.*[—:]", re.MULTILINE)
    return bool(pattern.search(doc))


def test_module_docstring_i3_is_authorization_not_quorum_soundness() -> None:
    doc = identity_plugin.__doc__ or ""
    assert _claims_label(doc, "I3")
    # Find just the I3 line for a precise check.
    i3_line = next(
        line for line in doc.splitlines() if re.match(r"^\s*I3\b", line)
    )
    assert "Authorization" in i3_line or "authorization" in i3_line, (
        f"I3 line must describe authorization (the real, enforced "
        f"mechanism), not quorum soundness: {i3_line!r}"
    )
    assert "quorum soundness" not in i3_line.lower(), (
        f"I3 line still says 'quorum soundness' — that's the OTHER, "
        f"never-invoked mechanism (musehub/graph/quorum.py), not what "
        f"push_validator.py actually enforces for I3: {i3_line!r}"
    )


def test_schema_description_i3_is_authorization_not_quorum_soundness() -> None:
    schema = identity_plugin.IdentityPlugin().schema()
    description = schema["description"]
    assert "(I3)" in description
    assert "quorum soundness" not in description.lower(), (
        f"schema() description still calls I3 'quorum soundness': {description!r}"
    )
    assert "authoriz" in description.lower(), (
        f"schema() description should describe I3 as authorization: {description!r}"
    )