cpdocs API documentation
Project documentation Docs

File: cpdocs/rust_backend.py

1# SPDX-FileCopyrightText: 2026 cpdocs developers2# SPDX-License-Identifier: Apache-2.03"""Rustdoc-JSON backend for the shared cpdocs API graph."""4 5from __future__ import annotations6 7import json8from pathlib import Path9 10from .model import ApiEntity, ApiGraph, ApiParameter, ApiSignature, SourceLocation, stable_entity_id11 12_KIND_MAP = {13    "module": "module",14    "struct": "struct",15    "enum": "enum",16    "trait": "trait",17    "function": "function",18    "type_alias": "type_alias",19    "constant": "constant",20    "static": "variable",21    "macro": "macro",22    "proc_macro": "macro",23    "union": "union",24}25 26 27def _rust_type(value: object) -> str:28    """Render the stable, user-facing portion of a rustdoc JSON type node."""29 30    if value is None:31        return ""32    if isinstance(value, str):33        return value34    if isinstance(value, list):35        return ", ".join(filter(None, (_rust_type(item) for item in value)))36    if not isinstance(value, dict) or not value:37        return ""38    if "primitive" in value:39        return str(value["primitive"])40    if "generic" in value:41        return str(value["generic"])42    if "infer" in value:43        return "_"44    if "slice" in value:45        return f"[{_rust_type(value['slice'])}]"46    if "array" in value and isinstance(value["array"], dict):47        array = value["array"]48        length = array.get("len", "_")49        return f"[{_rust_type(array.get('type'))}; {length}]"50    if "tuple" in value:51        parts = value["tuple"] if isinstance(value["tuple"], list) else []52        rendered = ", ".join(_rust_type(item) for item in parts)53        if len(parts) == 1:54            rendered += ","55        return f"({rendered})"56    if "borrowed_ref" in value and isinstance(value["borrowed_ref"], dict):57        ref = value["borrowed_ref"]58        lifetime = ref.get("lifetime")59        lifetime_text = f"'{lifetime} " if isinstance(lifetime, str) and lifetime else ""60        mutable = "mut " if ref.get("is_mutable") else ""61        return f"&{lifetime_text}{mutable}{_rust_type(ref.get('type'))}"62    if "raw_pointer" in value and isinstance(value["raw_pointer"], dict):63        pointer = value["raw_pointer"]64        qualifier = "mut" if pointer.get("is_mutable") else "const"65        return f"*{qualifier} {_rust_type(pointer.get('type'))}"66    if "resolved_path" in value and isinstance(value["resolved_path"], dict):67        path = value["resolved_path"]68        name = str(path.get("name", ""))69        args = path.get("args")70        rendered_args: list[str] = []71        if isinstance(args, dict):72            angle = args.get("angle_bracketed")73            if isinstance(angle, dict):74                raw_args = angle.get("args")75                if isinstance(raw_args, list):76                    for argument in raw_args:77                        if not isinstance(argument, dict):78                            continue79                        if "type" in argument:80                            rendered_args.append(_rust_type(argument["type"]))81                        elif "lifetime" in argument:82                            rendered_args.append(str(argument["lifetime"]))83                        elif "const" in argument:84                            rendered_args.append(str(argument["const"]))85        if rendered_args:86            name += "<" + ", ".join(rendered_args) + ">"87        return name88    if "impl_trait" in value:89        bounds = value["impl_trait"] if isinstance(value["impl_trait"], list) else []90        return "impl " + " + ".join(filter(None, (_rust_type(item) for item in bounds)))91    if "dyn_trait" in value:92        traits = value["dyn_trait"] if isinstance(value["dyn_trait"], list) else []93        return "dyn " + " + ".join(filter(None, (_rust_type(item) for item in traits)))94    # rustdoc evolves its JSON schema. Unknown type variants stay localized to this adapter rather95    # than leaking backend-specific structure into ApiGraph or the renderer.96    return next((_rust_type(item) for item in value.values() if _rust_type(item)), "")97 98 99def _function_signature(item: dict[str, object]) -> tuple[ApiSignature | None, list[str]]:100    inner = item.get("inner")101    if not isinstance(inner, dict):102        return None, []103    function = inner.get("function")104    if not isinstance(function, dict):105        return None, []106    signature = function.get("sig")107    parameters: list[ApiParameter] = []108    returns = ""109    if isinstance(signature, dict):110        inputs = signature.get("inputs")111        if isinstance(inputs, list):112            for raw in inputs:113                if isinstance(raw, list) and len(raw) >= 2:114                    parameters.append(ApiParameter(name=str(raw[0]), type=_rust_type(raw[1])))115        returns = _rust_type(signature.get("output"))116    properties: list[str] = ["pub"]117    header = function.get("header")118    if isinstance(header, dict):119        for field, label in (("is_const", "const"), ("is_async", "async"), ("is_unsafe", "unsafe")):120            if header.get(field):121                properties.append(label)122        abi = header.get("abi")123        if isinstance(abi, str) and abi not in {"", "Rust"}:124            properties.append(f'extern "{abi}"')125    return ApiSignature(126        parameters=tuple(parameters), returns=returns, qualifiers=tuple(properties[1:])127    ), properties128 129 130def _inner_kind(item: dict[str, object]) -> str | None:131    inner = item.get("inner")132    if not isinstance(inner, dict) or not inner:133        return None134    return next(iter(inner))135 136 137def build_rust_graph(138    *, rustdoc_json: Path, project: str, version: str = "main", project_root: Path | None = None139) -> ApiGraph:140    try:141        raw = json.loads(rustdoc_json.read_text(encoding="utf-8"))142    except (OSError, json.JSONDecodeError) as error:143        raise RuntimeError(f"Cannot read rustdoc JSON {rustdoc_json}: {error}") from error144    if not isinstance(raw, dict):145        raise RuntimeError(f"Unexpected rustdoc JSON root in {rustdoc_json}")146 147    index = raw.get("index")148    paths = raw.get("paths")149    if not isinstance(index, dict) or not isinstance(paths, dict):150        raise RuntimeError("rustdoc JSON does not contain index/paths maps")151 152    graph = ApiGraph(project=project, version=version, language="rust")153    rust_to_entity: dict[str, str] = {}154    path_to_id: dict[str, str] = {}155 156    for rust_id, raw_item in index.items():157        if not isinstance(raw_item, dict):158            continue159        visibility = raw_item.get("visibility")160        if visibility not in {"public", None} and not (161            isinstance(visibility, dict) and "public" in visibility162        ):163            continue164        kind_value = _inner_kind(raw_item)165        kind = _KIND_MAP.get(kind_value or "")166        if kind is None:167            continue168        path_info = paths.get(rust_id)169        path_values = path_info.get("path") if isinstance(path_info, dict) else None170        if isinstance(path_values, list) and path_values:171            qualified = "::".join(str(value) for value in path_values)172        else:173            name = raw_item.get("name")174            if not isinstance(name, str) or not name:175                continue176            qualified = name177        name = str(raw_item.get("name") or qualified.rsplit("::", 1)[-1])178        entity_id = stable_entity_id("rust", kind, qualified)179        source = None180        span = raw_item.get("span")181        if isinstance(span, dict) and isinstance(span.get("filename"), str):182            filename = Path(str(span["filename"]))183            if project_root is not None:184                try:185                    filename_text = (186                        filename.resolve().relative_to(project_root.resolve()).as_posix()187                    )188                except (OSError, ValueError):189                    filename_text = filename.as_posix()190            else:191                filename_text = filename.as_posix()192            begin = span.get("begin")193            line = None194            column = None195            if isinstance(begin, list) and len(begin) >= 2:196                if isinstance(begin[0], int):197                    line = begin[0]198                if isinstance(begin[1], int):199                    column = begin[1]200            source = SourceLocation(filename_text, line, column)201            if project_root is not None:202                physical = filename if filename.is_absolute() else project_root / filename203                try:204                    graph.sources.setdefault(filename_text, physical.read_text(encoding="utf-8"))205                except (OSError, UnicodeDecodeError):206                    pass207        function_signature, function_properties = _function_signature(raw_item)208        entity = ApiEntity(209            id=entity_id,210            language="rust",211            kind=kind,212            name=name,213            qualified_name=qualified,214            signatures=[function_signature] if function_signature is not None else [],215            documentation=str(raw_item.get("docs") or ""),216            source=source,217            properties=function_properties or ["pub"],218        )219        graph.add(entity)220        rust_to_entity[str(rust_id)] = entity_id221        path_to_id[qualified] = entity_id222 223    # Infer hierarchy from semantic paths. rustdoc ids are deliberately not exposed outside this224    # adapter; renderer URLs depend only on the normalized cpdocs identity.225    for entity in graph.entities.values():226        parent_path = (227            entity.qualified_name.rsplit("::", 1)[0] if "::" in entity.qualified_name else ""228        )229        parent = path_to_id.get(parent_path)230        if parent and parent != entity.id:231            entity.parent = parent232 233    graph.rebuild_children()234    return graph