package_reference.py

"""Generate package reference sections from live workspace metadata.

Architecture
------------
This Sphinx extension auto-generates the "Copyable config snippet" and
"Package metadata" sections that appear on every ``docs/packages/<name>.md``
page.  Surface documentation (config values, directives, roles) is owned by
the autodoc directives in ``sphinx-autodoc-sphinx`` (``autoconfigvalues``)
and ``sphinx-autodoc-docutils`` (``autodirectives`` / ``autoroles``) —
invoke them on the page directly.

It works in three layers:

1. **Workspace discovery** (``workspace_packages()``) — walks
   ``packages/*/pyproject.toml`` to find every publishable package and reads
   its name, version, description, classifiers, and GitHub URL.

2. **Surface extraction** (``collect_extension_surface()``) — replays the
   extension's ``setup()`` against
   :func:`sphinx_autodoc_docutils.replay_setup`, the shared workspace
   recorder, and maps the captured ``app.add_*`` calls into a
   ``SurfaceDict``.  The collected surface is consumed by
   ``_register_extension_objects()`` to populate the py-domain so
   cross-references resolve.

3. **Rendering** (``package_reference_markdown()``) — emits the copyable
   conf snippet and metadata block, which the ``PackageReferenceDirective``
   injects into the page via a raw docutils node.

Adding a new package
--------------------
No code changes are required.  Once a ``packages/<name>/pyproject.toml``
exists with a ``[project]`` table the package is picked up automatically on
the next docs build.

Examples
--------
>>> package = workspace_packages()[0]
>>> package["name"] in {
...     "gp-furo-theme",
...     "sphinx-vite-builder",
...     "sphinx-gp-opengraph",
...     "sphinx-gp-sitemap",
...     "gp-sphinx",
...     "sphinx-fonts",
...     "sphinx-gp-theme",
...     "sphinx-autodoc-argparse",
...     "sphinx-autodoc-docutils",
...     "sphinx-autodoc-fastmcp",
...     "sphinx-autodoc-pytest-fixtures",
...     "sphinx-autodoc-sphinx",
... }
True

>>> surface = collect_extension_surface("sphinx_fonts")
>>> any(item["name"] == "sphinx_fonts" for item in surface["config_values"])
True
"""

from __future__ import annotations

import importlib
import inspect
import logging
import os
import pathlib
import pkgutil
import sys
import typing as t

from sphinx.util.docutils import SphinxDirective

from sphinx_autodoc_docutils import SetupRecorder, replay_setup

if t.TYPE_CHECKING:
    from docutils import nodes

if sys.version_info >= (3, 11):
    import tomllib
else:
    import tomli as tomllib  # type: ignore[import-not-found]

logger = logging.getLogger(__name__)


class SurfaceDict(t.TypedDict):
    """Collected extension surface rows keyed by registration category."""

    module: str
    config_values: list[dict[str, str]]
    directives: list[dict[str, str]]
    roles: list[dict[str, str]]
    lexers: list[dict[str, str]]
    themes: list[dict[str, str]]


def ensure_workspace_imports() -> None:
    """Ensure each workspace package ``src`` directory is importable.

    Examples
    --------
    >>> ensure_workspace_imports()
    """
    for package in workspace_packages():
        src_path = os.fspath(pathlib.Path(package["package_dir"]) / "src")
        if src_path not in sys.path:
            sys.path.insert(0, src_path)


def workspace_root() -> pathlib.Path:
    """Return the repository root for the current docs build.

    Examples
    --------
    >>> workspace_root().is_dir()
    True
    """
    return pathlib.Path(__file__).resolve().parents[2]


def workspace_packages() -> list[dict[str, str]]:
    """Return publishable workspace packages and their module names.

    Examples
    --------
    >>> names = [package["name"] for package in workspace_packages()]
    >>> "gp-sphinx" in names
    True
    """
    packages_dir = workspace_root() / "packages"
    packages: list[dict[str, str]] = []
    for pyproject_path in sorted(packages_dir.glob("*/pyproject.toml")):
        with pyproject_path.open("rb") as handle:
            project = tomllib.load(handle)["project"]
        src_dir = pyproject_path.parent / "src"
        module_dir = next((path for path in src_dir.iterdir() if path.is_dir()), None)
        if module_dir is None:
            continue
        packages.append(
            {
                "name": str(project["name"]),
                "module_name": module_dir.name,
                "package_dir": str(pyproject_path.parent),
                "description": str(project.get("description", "")),
                "version": str(project["version"]),
                "repository": str(project.get("urls", {}).get("Repository", "")),
                "maturity": maturity_from_classifiers(
                    t.cast("list[str]", project.get("classifiers", [])),
                ),
            },
        )
    return packages


def maturity_from_classifiers(classifiers: list[str]) -> str:
    """Return the short maturity label derived from project classifiers.

    Examples
    --------
    >>> maturity_from_classifiers(["Development Status :: 4 - Beta"])
    'Beta'
    >>> maturity_from_classifiers([])
    'Unknown'
    """
    for classifier in classifiers:
        if classifier.startswith("Development Status :: 3"):
            return "Alpha"
        if classifier.startswith("Development Status :: 4"):
            return "Beta"
        if classifier.startswith("Development Status :: 5"):
            return "Production/Stable"
    return "Unknown"


def extension_modules(module_name: str) -> list[str]:
    """Return importable submodules that expose a Sphinx ``setup()`` function.

    Examples
    --------
    >>> "sphinx_autodoc_argparse" in extension_modules("sphinx_autodoc_argparse")
    True
    >>> "sphinx_autodoc_argparse.exemplar" in extension_modules("sphinx_autodoc_argparse")
    True
    """
    ensure_workspace_imports()
    try:
        module = importlib.import_module(module_name)
    except ImportError:
        logger.warning("package-reference: could not import %r", module_name)
        return []
    modules = []
    if callable(getattr(module, "setup", None)):
        modules.append(module_name)

    package_paths = getattr(module, "__path__", None)
    if package_paths is None:
        return modules

    for module_info in pkgutil.walk_packages(package_paths, prefix=f"{module_name}."):
        try:
            submodule = importlib.import_module(module_info.name)
        except ImportError:
            logger.warning(
                "package-reference: could not import submodule %r",
                module_info.name,
            )
            continue
        if callable(getattr(submodule, "setup", None)):
            modules.append(module_info.name)
    return modules


def summarize(text: str | None) -> str:
    """Return the first non-empty sentence-like summary from a docstring.

    Examples
    --------
    >>> summarize("One sentence.\\n    Two sentence.")
    'One sentence.'
    >>> summarize(None)
    ''
    """
    if not text:
        return ""
    stripped = inspect.cleandoc(text).strip()
    if not stripped:
        return ""
    first_line = stripped.splitlines()[0].strip()
    if first_line:
        return first_line
    return stripped


def render_value(value: object) -> str:
    """Render a compact literal representation for docs tables.

    Examples
    --------
    >>> render_value(True)
    '`True`'
    >>> render_value(["a", "b"])
    "`['a', 'b']`"
    """
    return f"`{value!r}`"


def render_types(types: object, default: object) -> str:
    """Render a readable type cell for a config-value table.

    Examples
    --------
    >>> render_types([dict], {})
    '`dict`'
    >>> render_types(None, "x")
    '`str`'
    """
    if isinstance(types, (list, tuple, set, frozenset)) and types:
        names = sorted(
            getattr(item, "__name__", str(item))
            for item in t.cast("t.Iterable[object]", types)
        )
        return f"`{' | '.join(names)}`"
    if default is None:
        return "`None`"
    return f"`{type(default).__name__}`"


# Re-export the shared recorder so existing references and doctests in this
# module still work; new code should import SetupRecorder from
# sphinx_autodoc_docutils directly.
RecorderApp = SetupRecorder


def _extract_arg(
    index: int,
    key: str,
    args: tuple[object, ...],
    kwargs: dict[str, object],
) -> object | None:
    """Pick a Sphinx app-method argument from positional or keyword form.

    Sphinx APIs accept both forms — e.g. ``app.add_directive("foo", Foo)``
    AND ``app.add_directive(name="foo", cls=Foo)`` — so a recorder consumer
    that only indexes ``args[N]`` raises ``IndexError`` (or silently misses
    the registration) on the keyword form. Mirror's the helper used in
    ``sphinx_autodoc_docutils._directives``.

    Examples
    --------
    >>> _extract_arg(0, "name", ("foo",), {})
    'foo'
    >>> _extract_arg(0, "name", (), {"name": "foo"})
    'foo'
    >>> _extract_arg(1, "cls", (), {}) is None
    True
    """
    if len(args) > index:
        return args[index]
    return kwargs.get(key)


def collect_extension_surface(module_name: str) -> SurfaceDict:
    """Collect config values, directives, roles, and lexers for an extension.

    Examples
    --------
    >>> surface = collect_extension_surface("sphinx_autodoc_pytest_fixtures")
    >>> any(item["name"] == "autofixtures" for item in surface["directives"])
    True
    """
    ensure_workspace_imports()
    try:
        importlib.import_module(module_name)
    except ImportError:
        logger.warning("package-reference: could not import %r", module_name)
        return SurfaceDict(
            module=module_name,
            config_values=[],
            directives=[],
            roles=[],
            lexers=[],
            themes=[],
        )
    app = replay_setup(module_name)
    if app is None:
        return SurfaceDict(
            module=module_name,
            config_values=[],
            directives=[],
            roles=[],
            lexers=[],
            themes=[],
        )

    config_values: list[dict[str, str]] = []
    directives: list[dict[str, str]] = []
    role_items: list[dict[str, str]] = []
    lexers: list[dict[str, str]] = []
    themes: list[dict[str, str]] = []

    for name, args, kwargs in app.calls:
        if name == "add_config_value":
            option = _extract_arg(0, "name", args, kwargs)
            if option is None:
                continue
            default = _extract_arg(1, "default", args, kwargs)
            rebuild = _extract_arg(2, "rebuild", args, kwargs) or ""
            types = _extract_arg(3, "types", args, kwargs)
            config_values.append(
                {
                    "name": str(option),
                    "default": render_value(default),
                    "rebuild": f"`{rebuild}`" if rebuild else "",
                    "types": render_types(types, default),
                },
            )
        elif name == "add_directive":
            directive_name = _extract_arg(0, "name", args, kwargs)
            directive_cls = _extract_arg(1, "cls", args, kwargs)
            if directive_name is None or directive_cls is None:
                continue
            directives.append(
                {
                    "name": str(directive_name),
                    "kind": "directive",
                    "callable": object_path(directive_cls),
                    "summary": summarize(getattr(directive_cls, "__doc__", None)),
                    "options": directive_options_markdown(directive_cls),
                },
            )
        elif name == "add_directive_to_domain":
            domain = _extract_arg(0, "domain", args, kwargs)
            directive_name = _extract_arg(1, "name", args, kwargs)
            directive_cls = _extract_arg(2, "cls", args, kwargs)
            if domain is None or directive_name is None or directive_cls is None:
                continue
            directives.append(
                {
                    "name": f"{domain}:{directive_name}",
                    "kind": "domain directive",
                    "callable": object_path(directive_cls),
                    "summary": summarize(getattr(directive_cls, "__doc__", None)),
                    "options": directive_options_markdown(directive_cls),
                },
            )
        elif name == "add_crossref_type":
            directive_name = _extract_arg(0, "directivename", args, kwargs)
            if directive_name is None:
                continue
            role_name = _extract_arg(1, "rolename", args, kwargs) or directive_name
            directives.append(
                {
                    "name": f"std:{directive_name}",
                    "kind": "cross-reference directive",
                    "callable": "{py:meth}`~sphinx.application.Sphinx.add_crossref_type`",
                    "summary": "Registers a standard-domain cross-reference target.",
                    "options": "",
                },
            )
            role_items.append(
                {
                    "name": f"std:{role_name}",
                    "kind": "cross-reference role",
                    "callable": "{py:meth}`~sphinx.application.Sphinx.add_crossref_type`",
                    "summary": "Registers a standard-domain cross-reference role.",
                },
            )
        elif name == "add_role":
            role_name = _extract_arg(0, "name", args, kwargs)
            role_fn = _extract_arg(1, "role", args, kwargs)
            if role_name is None or role_fn is None:
                continue
            role_items.append(
                {
                    "name": str(role_name),
                    "kind": "role",
                    "callable": object_path(role_fn),
                    "summary": summarize(getattr(role_fn, "__doc__", None)),
                },
            )
        elif name == "add_role_to_domain":
            domain = _extract_arg(0, "domain", args, kwargs)
            role_name = _extract_arg(1, "name", args, kwargs)
            role_fn = _extract_arg(2, "role", args, kwargs)
            if domain is None or role_name is None or role_fn is None:
                continue
            role_items.append(
                {
                    "name": f"{domain}:{role_name}",
                    "kind": "domain role",
                    "callable": object_path(role_fn),
                    "summary": summarize(getattr(role_fn, "__doc__", None)),
                },
            )
        elif name == "add_lexer":
            alias = _extract_arg(0, "alias", args, kwargs)
            lexer = _extract_arg(1, "lexer", args, kwargs)
            if alias is None or lexer is None:
                continue
            lexers.append(
                {
                    "name": str(alias),
                    "callable": object_path(lexer),
                },
            )
        elif name == "add_html_theme":
            theme_name = _extract_arg(0, "name", args, kwargs)
            theme_path = _extract_arg(1, "theme_path", args, kwargs)
            if theme_name is None or theme_path is None:
                continue
            themes.append(
                {
                    "name": str(theme_name),
                    "path": f"`{theme_path}`",
                },
            )

    return {
        "module": module_name,
        "config_values": unique_by_name(config_values),
        "directives": unique_by_name(directives),
        "roles": unique_by_name(role_items),
        "lexers": unique_by_name(lexers),
        "themes": unique_by_name(themes),
    }


def object_path(value: object) -> str:
    """Return a ``{py:obj}`` cross-reference for an arbitrary object.

    Uses the ``~`` prefix so Sphinx renders just the short name as link text.

    Examples
    --------
    >>> object_path(SurfaceDict)
    '{py:obj}`~package_reference.SurfaceDict`'
    """
    module_name = getattr(value, "__module__", type(value).__module__)
    object_name = getattr(value, "__name__", type(value).__name__)
    return f"{{py:obj}}`~{module_name}.{object_name}`"


def unique_by_name(items: list[dict[str, str]]) -> list[dict[str, str]]:
    """Deduplicate rows while preserving their first-seen order.

    Examples
    --------
    >>> unique_by_name([{"name": "x"}, {"name": "x"}, {"name": "y"}])
    [{'name': 'x'}, {'name': 'y'}]
    """
    seen: set[str] = set()
    result: list[dict[str, str]] = []
    for item in items:
        name = item["name"]
        if name in seen:
            continue
        seen.add(name)
        result.append(item)
    return result


def directive_options_markdown(directive_cls: object) -> str:
    """Render a Markdown table of directive options, if any.

    Examples
    --------
    >>> from sphinx_autodoc_argparse.directive import ArgparseDirective
    >>> "module" in directive_options_markdown(ArgparseDirective)
    True
    """
    option_spec = getattr(directive_cls, "option_spec", None)
    if not isinstance(option_spec, dict) or not option_spec:
        return ""
    lines = [
        "",
        "| Option | |",
        "| --- | --- |",
    ]
    for option_name in sorted(str(key) for key in option_spec):
        lines.append(f"| `:{option_name}:` | Registered option |")
    return "\n".join(lines)


def package_reference_markdown(package_name: str) -> str:
    """Render the copyable conf snippet and metadata block for a package page.

    Surface documentation (config values, directives, roles, lexers, themes)
    is owned by the autodoc directives in ``sphinx-autodoc-sphinx`` and
    ``sphinx-autodoc-docutils`` — invoke them directly on the page.

    Returns an empty string and logs a warning when ``package_name`` is not
    found among the workspace packages.

    Examples
    --------
    >>> "Copyable config snippet" in package_reference_markdown("sphinx-fonts")
    True
    >>> "pypi.org/project/sphinx-fonts" in package_reference_markdown("sphinx-fonts")
    True
    >>> package_reference_markdown("nonexistent-package")
    ''
    """
    package = next(
        (item for item in workspace_packages() if item["name"] == package_name),
        None,
    )
    if package is None:
        logger.warning("package-reference: unknown package %r", package_name)
        return ""
    module_name = package["module_name"]
    extension_blocks = [
        collect_extension_surface(name) for name in extension_modules(module_name)
    ]

    lines = [
        "## Copyable config snippet",
        "",
        "```python",
        "extensions = [",
    ]

    if extension_blocks:
        for block in extension_blocks:
            lines.append(f'    "{block["module"]}",')
    elif package_name == "gp-sphinx":
        lines.append('    "gp_sphinx",')
    else:
        lines.append(f'    "{module_name}",')

    lines.extend(["]", "```", ""])

    if package["repository"]:
        pypi_url = f"https://pypi.org/project/{package_name}/"
        lines.extend(
            [
                "## Package metadata",
                "",
                f"- Source on GitHub: [{package_name}]({package['repository']}/tree/main/packages/{package_name})",
                f"- PyPI: [{package_name}]({pypi_url})",
                f"- Maturity: `{package['maturity']}`",
                "",
            ],
        )

    if package_name == "gp-sphinx":
        lines.extend(
            [
                "## Public surface",
                "",
                "This package is a coordinator rather than a Sphinx extension module.",
                "Its public runtime surface is documented in {doc}`/configuration` and {doc}`/api`.",
                "",
            ],
        )

    return "\n".join(lines)


def maturity_badge(maturity: str) -> str:
    """Return a sphinx-design badge role for use in grid markdown output.

    Used only in :func:`workspace_package_grid_markdown` which produces raw
    MyST markdown strings.  Per-page package headers use the ``gp-sphinx-package-meta``
    directive (see ``docs/_ext/sab_meta.py``) which emits SAB-native badges.

    Examples
    --------
    >>> maturity_badge("Alpha")
    '{bdg-warning-line}`Alpha`'
    """
    if maturity == "Alpha":
        return "{bdg-warning-line}`Alpha`"
    if maturity == "Beta":
        return "{bdg-success-line}`Beta`"
    return f"{{bdg-secondary-line}}`{maturity}`"


def workspace_package_grid_markdown() -> str:
    """Render the package index grid from workspace metadata.

    Examples
    --------
    >>> "grid-item-card" in workspace_package_grid_markdown()
    True
    >>> "+++" in workspace_package_grid_markdown()
    True
    """
    lines = [
        "::::{grid} 1 1 2 2",
        ":gutter: 2 2 3 3",
        "",
    ]
    for package in workspace_packages():
        lines.extend(
            [
                f":::{{grid-item-card}} {package['name']}",
                f":link: {package['name']}",
                ":link-type: doc",
                "",
                str(package["description"]),
                "",
                "+++",
                maturity_badge(package["maturity"]),
                ":::",
                "",
            ],
        )
    lines.append("::::")
    return "\n".join(lines)


def _register_extension_objects(
    app: t.Any,
    env: t.Any,
) -> None:
    """Populate the Sphinx py domain so {py:obj} callables resolve as links.

    Runs on ``env-check-consistency`` — after all source files are read and
    ``clear_doc()`` calls are complete, but before the write phase resolves
    cross-references.  Registering earlier (e.g. ``env-before-read-docs``)
    fails because ``clear_doc()`` wipes domain entries whose docname matches
    the page being re-read.

    Examples
    --------
    >>> class _MockPyDomain:
    ...     objects: dict[str, object] = {}
    >>> class _MockEnv:
    ...     domains: dict[str, object] = {"py": _MockPyDomain()}
    >>> _register_extension_objects(None, _MockEnv())
    >>> "sphinx_autodoc_docutils._directives.AutoDirective" in _MockPyDomain.objects
    True
    """
    try:
        from sphinx.domains.python import ObjectEntry

        py_domain = env.domains["py"]
    except (KeyError, AttributeError, ImportError):
        return

    for package in workspace_packages():
        pkg_docname = f"packages/{package['name']}"

        for ext_module_name in extension_modules(package["module_name"]):
            recorder = replay_setup(ext_module_name)
            if recorder is None:
                continue

            raw_objs: list[tuple[object, str]] = []  # (obj, objtype)
            for call_name, args, _kwargs in recorder.calls:
                if call_name == "add_directive" and len(args) >= 2:
                    raw_objs.append((args[1], "class"))
                elif call_name == "add_directive_to_domain" and len(args) >= 3:
                    raw_objs.append((args[2], "class"))
                elif call_name == "add_role" and len(args) >= 2:
                    obj = args[1]
                    raw_objs.append(
                        (obj, "function" if not inspect.isclass(obj) else "class"),
                    )
                elif call_name == "add_role_to_domain" and len(args) >= 3:
                    obj = args[2]
                    raw_objs.append(
                        (obj, "function" if not inspect.isclass(obj) else "class"),
                    )
                elif call_name == "add_lexer" and len(args) >= 2:
                    raw_objs.append((args[1], "class"))

            for obj, objtype in raw_objs:
                mod = getattr(obj, "__module__", None) or type(obj).__module__
                name = getattr(obj, "__name__", None) or type(obj).__name__
                full_name = f"{mod}.{name}"
                if full_name in py_domain.objects:
                    continue
                node_id = full_name.replace(".", "-")
                py_domain.objects[full_name] = ObjectEntry(
                    docname=pkg_docname,
                    node_id=node_id,
                    objtype=objtype,
                    aliased=False,
                )


class PackageReferenceDirective(SphinxDirective):
    """Render a generated package reference block inside a page."""

    required_arguments = 1
    has_content = False

    def run(self) -> list[nodes.Node]:
        package_name = self.arguments[0]
        return self.parse_text_to_nodes(package_reference_markdown(package_name))


class WorkspacePackageGridDirective(SphinxDirective):
    """Render the packages index grid from workspace package metadata."""

    has_content = False

    def run(self) -> list[nodes.Node]:
        return self.parse_text_to_nodes(workspace_package_grid_markdown())


def setup(app: t.Any) -> dict[str, object]:
    """Register the package-reference directive for documentation pages.

    Examples
    --------
    >>> fake = RecorderApp()
    >>> metadata = setup(fake)
    >>> metadata["parallel_read_safe"]
    True
    """
    ensure_workspace_imports()
    app.add_directive("package-reference", PackageReferenceDirective)
    app.add_directive("workspace-package-grid", WorkspacePackageGridDirective)
    app.connect("env-check-consistency", _register_extension_objects)
    return {
        "parallel_read_safe": True,
        "parallel_write_safe": True,
        "version": "0.0.1",
    }