"""Every create_* tool says what it is NOT for (#3123).

WHY THIS EXISTS

Scribe's record kinds are reached for interchangeably — a note written where
a task was owed, a rule written where a snippet belonged — and the moment of
choice is the only moment a correction is cheap. The tool docstring IS the
agent-facing contract (rule 119 puts product guidance there and nowhere
else), so a docstring that only documents parameters answers "how do I call
this" while leaving "should I be calling this at all" unasked.

The gap was lopsided before this: `create_rule` and `start_planning` both
carried a real disambiguator, and `create_note` — far and away the
highest-volume surface — carried none. Guidance sat in the rarest tool and
was missing from the most common one.

WHAT THIS PINS, AND WHAT IT DOES NOT

It asserts STRUCTURE, never wording: each create surface must name at least
two sibling surfaces, so a caller who reached for the wrong one is told
where the right one is. Prose stays free to be rewritten — pinning phrasing
would make every improvement a test failure, and a test that punishes
editing is a test that gets deleted.

It cannot tell whether the guidance is any GOOD. It only catches the
regression that actually happens: a docstring rewritten down to its
parameters, with the "is this even the right tool" paragraph quietly gone.
"""
import re

import pytest

# The create surfaces and where they live. `start_planning` is here because
# it is a create in everything but name — it is how a plan comes into being.
_SURFACES = [
    ("scribe.mcp.tools.notes", "create_note"),
    ("scribe.mcp.tools.tasks", "create_task"),
    ("scribe.mcp.tools.tasks", "start_planning"),
    ("scribe.mcp.tools.snippets", "create_snippet"),
    ("scribe.mcp.tools.processes", "create_process"),
    ("scribe.mcp.tools.rulebooks", "create_rule"),
    ("scribe.mcp.tools.rulebooks", "create_project_rule"),
]

# What a caller could have wanted instead. A surface naming two of these has
# pointed somewhere; naming none has left them where they were.
_ALTERNATIVES = [
    "create_note", "create_task", "create_rule", "create_project_rule",
    "create_snippet", "create_process", "start_planning", "design system",
]


def _doc(module: str, name: str) -> str:
    """The docstring with its whitespace flattened.

    Flattened because a docstring is hard-wrapped: "design system" spans a
    line break in at least one of these, and matching the raw text would
    report it absent. The first draft of this check did exactly that, and
    caught it on itself.
    """
    import importlib

    fn = getattr(importlib.import_module(module), name)
    assert fn.__doc__, f"{name} has no docstring at all"
    return re.sub(r"\s+", " ", fn.__doc__)


@pytest.mark.parametrize(("module", "name"), _SURFACES)
def test_a_create_surface_names_at_least_two_alternatives(module, name):
    """Reaching for the wrong tool must still put the right one in view."""
    doc = _doc(module, name)
    named = {
        alt for alt in _ALTERNATIVES
        if alt != name and re.search(re.escape(alt), doc, re.IGNORECASE)
    }
    assert len(named) >= 2, (
        f"{name}'s docstring names {sorted(named) or 'no'} alternative "
        f"surface(s). A caller who reached for it by mistake gets no "
        f"correction. Say what belongs elsewhere and why — see create_rule "
        f"or create_note for the shape."
    )


@pytest.mark.parametrize(("module", "name"), _SURFACES)
def test_a_create_surface_still_documents_its_arguments(module, name):
    """The guard above must not be satisfiable by deleting the parameter docs.

    Both halves matter and they pull in opposite directions: a docstring can
    be made to pass the disambiguator check by becoming an essay about the
    other tools, which would be a worse contract than the one being fixed.
    """
    assert "Args:" in _doc(module, name), (
        f"{name}'s docstring lost its Args: block — the parameter contract is "
        f"what a caller reads to make the call at all."
    )