Rebuild the docs around tested examples; shrink README.v2.md to a pitch (#2978)

tests/docs_src/test_shape.py

@@ -0,0 +1,193 @@
+"""Structural invariants every `docs_src/` example must satisfy.
+
+These are deliberately string/regex checks, not an AST analyzer: each predicate
+is branch-free at the call site so the suite stays compatible with the repo's
+100% branch-coverage gate, and a contributor whose doc PR goes red gets a
+one-line reason, not a parser traceback.
+"""
+
+import importlib
+import re
+from itertools import filterfalse
+from pathlib import Path
+
+import pytest
+
+# See test_index.py for why this is a per-module mark and not a conftest hook.
+pytestmark = pytest.mark.filterwarnings("error::mcp.MCPDeprecationWarning")
+
+REPO_ROOT = Path(__file__).parent.parent.parent
+DOCS_SRC = REPO_ROOT / "docs_src"
+
+EXAMPLE_FILES = sorted(p for p in DOCS_SRC.rglob("*.py") if p.name != "__init__.py")
+"""Every example module under `docs_src/` (the `__init__.py` scaffolding is not an example)."""
+
+_PRIVATE_MCP_IMPORT = re.compile(r"^\s*(?:from|import)\s+(mcp(?:\.\w+)*\._\w+)", re.MULTILINE)
+"""A `_`-private segment inside the imported MODULE path: `from mcp.client._memory import X`."""
+
+_PRIVATE_MCP_NAME = re.compile(r"^\s*from\s+(mcp(?:\.\w+)*)\s+import\s+[^#\n]*?\b(_\w+)\b", re.MULTILINE)
+"""A `_`-private NAME imported from a public `mcp` module: `from mcp.client import _memory`."""
+
+RETIRED_NAMES = ("UrlElicitationRequiredError",)
+"""Public SDK names built on protocol surfaces retired by the 2026-07-28 spec.
+
+`UrlElicitationRequiredError` is the `-32042` flow; the spec lists that code as
+reserved-never-reused, so no documentation example may teach it even while the
+symbol is still exported.
+"""
+
+_INCLUDE_DIRECTIVE = re.compile(r"(?:--8<--\s*\"|<!-- snippet-source\s+)(docs_src/[^\s\"]+)")
+"""A `--8<-- "docs_src/..."` mkdocs include or a `<!-- snippet-source docs_src/... -->` README marker."""
+
+_TYPOGRAPHIC_NON_ASCII = re.compile("[\u2014\u2013\u2192\u2026\u2018\u2019\u201c\u201d\u00a0\u2264\u2265\u00a7]")
+"""Typographic characters the documentation never uses: em/en dash, arrow, ellipsis, curly
+quotes, no-break space, comparison signs, section sign. They are written as escapes so this
+file satisfies the very check it implements.
+
+Plain ASCII punctuation is a deliberate style rule, and one of these is also a real bug: a U+2026
+inside a fenced example breaks the fence linter on Windows, where the example source is piped to
+ruff in the platform encoding rather than UTF-8. Emoji are not banned; this is about typography.
+"""
+
+BOOK_PAGES = sorted(
+    {
+        REPO_ROOT / "README.v2.md",
+        REPO_ROOT / "docs" / "index.md",
+        REPO_ROOT / "docs" / "installation.md",
+        *(REPO_ROOT / "docs" / "tutorial").rglob("*.md"),
+        *(REPO_ROOT / "docs" / "run").rglob("*.md"),
+        *(REPO_ROOT / "docs" / "client").rglob("*.md"),
+        *(REPO_ROOT / "docs" / "advanced").rglob("*.md"),
+    }
+)
+"""Every page of the tutorial book plus the README: the files this directory's tests stand behind."""
+
+DOCS_TEST_FILES = sorted(Path(__file__).parent.glob("*.py"))
+"""This directory itself. The prose in these modules' docstrings follows the same typography rule."""
+
+
+def _rel(path: Path) -> str:
+    """A repo-relative path, used as the parametrize id so failures name the file."""
+    return path.relative_to(REPO_ROOT).as_posix()
+
+
+def _module_name(path: Path) -> str:
+    """The dotted import name of an example, derived from its repo-relative path."""
+    return _rel(path).removesuffix(".py").replace("/", ".")
+
+
+def _private_mcp_imports(source: str) -> list[str]:
+    """Every `mcp.*` import in `source` that reaches a `_`-private module OR name.
+
+    Two single-line spellings are covered: a private segment in the module path
+    (`from mcp.client._memory import X`, `import mcp.server._otel`) and a private
+    name pulled from a public module (`from mcp.client import _memory`).
+    """
+    named = [f"{module}.{name}" for module, name in _PRIVATE_MCP_NAME.findall(source)]
+    return _PRIVATE_MCP_IMPORT.findall(source) + named
+
+
+def _retired_names_used(source: str) -> list[str]:
+    """The retired SDK names that appear anywhere in `source`."""
+    return [name for name in RETIRED_NAMES if name in source]
+
+
+def _typographic_chars(text: str) -> list[str]:
+    """Every banned typographic character in `text`, in order of appearance."""
+    return _TYPOGRAPHIC_NON_ASCII.findall(text)
+
+
+def _referenced_examples() -> set[str]:
+    """Every `docs_src/...` path that some docs page or the README actually includes.
+
+    The README is globbed rather than named so this survives the planned
+    `README.v2.md` -> `README.md` rename instead of crashing on a missing file.
+    """
+    pages = [*sorted((REPO_ROOT / "docs").rglob("*.md")), *sorted(REPO_ROOT.glob("README*.md"))]
+    return {ref for page in pages for ref in _INCLUDE_DIRECTIVE.findall(page.read_text(encoding="utf-8"))}
+
+
+def _is_real_file(rel: str) -> bool:
+    """Whether a repo-relative path exists on disk."""
+    return (REPO_ROOT / rel).is_file()
+
+
+def test_private_mcp_import_detector() -> None:
+    """The detector flags both single-line spellings of a private `mcp` reach-in, and only those.
+
+    It does not parse Python: a private name hidden behind an `as` alias or inside a
+    parenthesised multi-line `import` would slip through. Examples are short single-line
+    imports, so the cheap detector is the right trade against a 100-line AST analyzer.
+    """
+    assert _private_mcp_imports("from mcp.client._memory import InMemoryTransport") == ["mcp.client._memory"]
+    assert _private_mcp_imports("import mcp.server._otel") == ["mcp.server._otel"]
+    assert _private_mcp_imports("from mcp.client import _memory") == ["mcp.client._memory"]
+    assert _private_mcp_imports("from mcp.server import MCPServer\nfrom mcp.client.client import Client") == []
+    # only `mcp` is policed: another library's private module is not this test's business
+    assert _private_mcp_imports("from pydantic._internal import _fields") == []
+
+
+def test_retired_name_detector() -> None:
+    """The detector flags a retired name and stays quiet on clean source."""
+    assert _retired_names_used("raise UrlElicitationRequiredError([])") == ["UrlElicitationRequiredError"]
+    assert _retired_names_used("from mcp.server import MCPServer") == []
+
+
+def test_typographic_char_detector() -> None:
+    """The detector flags banned typography and allows plain ASCII and emoji."""
+    assert _typographic_chars("a \u2014 b \u2192 c\u2026") == ["\u2014", "\u2192", "\u2026"]
+    assert _typographic_chars("plain ASCII with a \u2728 emoji is fine") == []
+
+
+@pytest.mark.parametrize("path", EXAMPLE_FILES, ids=_rel)
+def test_example_imports(path: Path) -> None:
+    """The example imports cleanly against the current SDK.
+
+    A renamed symbol, a moved import path, or a changed keyword argument breaks an
+    example at import time, long before anyone reads the page it appears on.
+
+    Honest scope: an example another test in this directory already imported is a
+    `sys.modules` cache hit here and its real coverage is that behavioural test.
+    This test is the floor for the example that has a page but no test yet.
+    """
+    importlib.import_module(_module_name(path))
+
+
+@pytest.mark.parametrize("path", EXAMPLE_FILES, ids=_rel)
+def test_example_uses_only_public_mcp_modules(path: Path) -> None:
+    """An example is the public API contract: it must never import a `_`-private `mcp` module."""
+    assert not _private_mcp_imports(path.read_text(encoding="utf-8")), f"{_rel(path)} reaches into private mcp"
+
+
+@pytest.mark.parametrize("path", EXAMPLE_FILES, ids=_rel)
+def test_example_avoids_retired_api(path: Path) -> None:
+    """An example must not teach an API the 2026-07-28 spec retired, even while it is still exported."""
+    assert not _retired_names_used(path.read_text(encoding="utf-8")), f"{_rel(path)} uses a retired API"
+
+
+@pytest.mark.parametrize("path", [*BOOK_PAGES, *EXAMPLE_FILES, *DOCS_TEST_FILES], ids=_rel)
+def test_page_uses_plain_ascii_punctuation(path: Path) -> None:
+    """A page, example, or docs test never uses em-dashes, arrows, ellipses, or other typographic non-ASCII."""
+    found = _typographic_chars(path.read_text(encoding="utf-8"))
+    assert not found, f"{_rel(path)} contains non-ASCII typography: {sorted(set(found))}"
+
+
+def test_every_example_is_included_by_a_page() -> None:
+    """Every `docs_src/` example is shown by at least one docs page or the README.
+
+    An orphan example is dead documentation: it gets type-checked and tested
+    but no reader ever sees it, so it silently stops describing anything.
+    """
+    examples = {_rel(p) for p in EXAMPLE_FILES}
+    orphans = sorted(examples - _referenced_examples())
+    assert not orphans, f"docs_src files no page includes: {orphans}"
+
+
+def test_every_included_path_exists() -> None:
+    """Every `docs_src/` path a page includes exists on disk.
+
+    `mkdocs build --strict` also enforces this, but only when the docs are
+    built; this puts the same guarantee inside the ordinary `pytest` run.
+    """
+    missing = sorted(filterfalse(_is_real_file, _referenced_examples()))
+    assert not missing, f"pages include docs_src files that do not exist: {missing}"