cpdocs API documentation
Project documentation Docs

File: cpdocs/contract.py

1# SPDX-FileCopyrightText: 2026 cpdocs developers2# SPDX-License-Identifier: Apache-2.03"""The contract between cpdocs and a project's build system.4 5cpdocs never knows how a project is built. It hands the build system a *request* and reads back a6*manifest*. There are two phases:7 8``describe``9    The build system reports the project identity, its feature axes, the documentation units and10    the variants worth documenting. Every variant carries the commands that make it concrete.11 12``variant``13    The build system has been configured for exactly one variant and reports, per unit, which files14    form the public API and how they must be parsed.15 16The normative description lives in ``docs/web/reference/contract.md``.17"""18 19from __future__ import annotations20 21import json22from dataclasses import dataclass23from pathlib import Path24from typing import Any25 26CONTRACT_VERSION = 127LANGUAGES = ("c", "cpp", "python", "rust")28 29 30class ContractError(RuntimeError):31    """A request or manifest does not satisfy the cpdocs build-system contract."""32 33 34# --------------------------------------------------------------------------------------------------35# Request36# --------------------------------------------------------------------------------------------------37 38 39@dataclass(frozen=True)40class Request:41    phase: str42    ref: str43    ref_kind: str44    source: Path45    build: Path46    manifest: Path47    variant: str | None48 49    def to_json(self) -> dict[str, object]:50        return {51            "cpdocs-request": CONTRACT_VERSION,52            "phase": self.phase,53            "ref": self.ref,54            "ref-kind": self.ref_kind,55            "variant": self.variant,56            "source": str(self.source),57            "build": str(self.build),58            "manifest": str(self.manifest),59        }60 61    def write(self, path: Path) -> None:62        path.parent.mkdir(parents=True, exist_ok=True)63        path.write_text(json.dumps(self.to_json(), indent=2) + "\n", encoding="utf-8")64 65 66def read_request(path: Path) -> Request:67    raw = _load_json(path, "request")68    if raw.get("cpdocs-request") != CONTRACT_VERSION:69        raise ContractError(f"{path}: unsupported cpdocs-request {raw.get('cpdocs-request')!r}")70    phase = _string(raw, "phase", path)71    if phase not in {"describe", "variant"}:72        raise ContractError(f"{path}: phase must be 'describe' or 'variant'")73    variant = raw.get("variant")74    if phase == "variant" and not isinstance(variant, str):75        raise ContractError(f"{path}: a variant request must name its variant")76    return Request(77        phase=phase,78        ref=_string(raw, "ref", path),79        ref_kind=_string(raw, "ref-kind", path),80        source=Path(_string(raw, "source", path)),81        build=Path(_string(raw, "build", path)),82        manifest=Path(_string(raw, "manifest", path)),83        variant=variant if isinstance(variant, str) else None,84    )85 86 87# --------------------------------------------------------------------------------------------------88# Describe manifest89# --------------------------------------------------------------------------------------------------90 91 92@dataclass(frozen=True)93class FeatureAxis:94    name: str95    values: tuple[str, ...]96 97 98@dataclass(frozen=True)99class UnitDeclaration:100    id: str101    language: str102 103 104@dataclass(frozen=True)105class VariantDeclaration:106    name: str107    primary: bool108    features: dict[str, tuple[str, ...]]109    commands: tuple[tuple[str, ...], ...]110 111 112@dataclass(frozen=True)113class Description:114    project: str115    version: str116    features: tuple[FeatureAxis, ...]117    units: tuple[UnitDeclaration, ...]118    variants: tuple[VariantDeclaration, ...]119    generator: str120 121    @property122    def primary(self) -> VariantDeclaration:123        return next(variant for variant in self.variants if variant.primary)124 125    def variant(self, name: str) -> VariantDeclaration:126        for variant in self.variants:127            if variant.name == name:128                return variant129        raise ContractError(f"describe manifest has no variant {name!r}")130 131 132def read_description(path: Path) -> Description:133    raw = _load_json(path, "describe manifest")134    _check_header(raw, path, "describe")135    project = _mapping(raw.get("project"), "project", path)136 137    axes: list[FeatureAxis] = []138    for name, value in _mapping(raw.get("features", {}), "features", path).items():139        data = _mapping(value, f"features.{name}", path)140        values = _string_tuple(data.get("values"), f"features.{name}.values", path)141        if len(set(values)) != len(values):142            raise ContractError(f"{path}: features.{name}.values contains duplicates")143        axes.append(FeatureAxis(name=name, values=values))144    axis_values = {axis.name: set(axis.values) for axis in axes}145 146    units = _units(raw.get("units"), path)147 148    variants: list[VariantDeclaration] = []149    raw_variants = raw.get("variants")150    if not isinstance(raw_variants, list) or not raw_variants:151        raise ContractError(f"{path}: variants must be a non-empty list")152    for index, value in enumerate(raw_variants):153        where = f"variants[{index}]"154        data = _mapping(value, where, path)155        name = _string(data, "name", path, where)156        features = _features(data.get("features", {}), f"{where}.features", path)157        for axis, selected in features.items():158            if axis not in axis_values:159                raise ContractError(f"{path}: {where} uses undeclared feature axis {axis!r}")160            unknown = sorted(set(selected) - axis_values[axis])161            if unknown:162                raise ContractError(163                    f"{path}: {where} selects unknown {axis} values: {', '.join(unknown)}"164                )165        commands = data.get("commands")166        if not isinstance(commands, list):167            raise ContractError(f"{path}: {where}.commands must be a list of argv lists")168        variants.append(169            VariantDeclaration(170                name=name,171                primary=bool(data.get("primary", False)),172                features=features,173                commands=tuple(174                    _string_tuple(command, f"{where}.commands[{number}]", path)175                    for number, command in enumerate(commands)176                ),177            )178        )179 180    names = [variant.name for variant in variants]181    if len(set(names)) != len(names):182        raise ContractError(f"{path}: variant names must be unique")183    primaries = [variant.name for variant in variants if variant.primary]184    if len(primaries) != 1:185        raise ContractError(f"{path}: exactly one variant must be primary, found {len(primaries)}")186 187    return Description(188        project=_string(project, "name", path, "project"),189        version=str(project.get("version") or ""),190        features=tuple(axes),191        units=units,192        variants=tuple(variants),193        generator=str(raw.get("generator") or ""),194    )195 196 197# --------------------------------------------------------------------------------------------------198# Variant manifest199# --------------------------------------------------------------------------------------------------200 201 202@dataclass(frozen=True)203class ApiRoot:204    path: Path205    generated: bool206 207 208@dataclass(frozen=True)209class ParseOptions:210    standard: str211    include: tuple[Path, ...]212    system_include: tuple[Path, ...]213    define: tuple[str, ...]214    flags: tuple[str, ...]215    compile_database: Path | None216 217 218@dataclass(frozen=True)219class UnitManifest:220    id: str221    language: str222    api: tuple[ApiRoot, ...]223    parse: ParseOptions | None224    package: str | None225    rustdoc_json: Path | None226 227 228@dataclass(frozen=True)229class VariantManifest:230    variant: str231    features: dict[str, tuple[str, ...]]232    units: tuple[UnitManifest, ...]233 234 235def read_variant_manifest(path: Path, *, source: Path) -> VariantManifest:236    """Read one variant manifest; relative paths are resolved against ``source``."""237 238    raw = _load_json(path, "variant manifest")239    _check_header(raw, path, "variant")240    units: list[UnitManifest] = []241    for declaration, value in zip(_units(raw.get("units"), path), raw["units"], strict=True):242        where = f"unit {declaration.id!r}"243        data = _mapping(value, where, path)244        roots = data.get("api", [])245        if not isinstance(roots, list):246            raise ContractError(f"{path}: {where}: api must be a list")247        api: list[ApiRoot] = []248        for index, root in enumerate(roots):249            root_data = _mapping(root, f"{where}.api[{index}]", path)250            api.append(251                ApiRoot(252                    path=_path(_string(root_data, "path", path, where), source),253                    generated=bool(root_data.get("generated", False)),254                )255            )256 257        parse: ParseOptions | None = None258        package: str | None = None259        rustdoc_json: Path | None = None260        if declaration.language in {"c", "cpp"}:261            if not api:262                raise ContractError(f"{path}: {where}: a C/C++ unit needs at least one API root")263            options = _mapping(data.get("parse", {}), f"{where}.parse", path)264            database = options.get("compile-database")265            parse = ParseOptions(266                standard=str(options.get("standard") or ""),267                include=tuple(268                    _path(item, source)269                    for item in _string_tuple(options.get("include", []), "include", path)270                ),271                system_include=tuple(272                    _path(item, source)273                    for item in _string_tuple(274                        options.get("system-include", []), "system-include", path275                    )276                ),277                define=_string_tuple(options.get("define", []), "define", path),278                flags=_string_tuple(options.get("flags", []), "flags", path),279                compile_database=_path(str(database), source) if database else None,280            )281        elif declaration.language == "python":282            if len(api) != 1:283                raise ContractError(f"{path}: {where}: a Python unit needs exactly one API root")284            package = _string(data, "package", path, where)285        elif declaration.language == "rust":286            rustdoc_json = _path(_string(data, "rustdoc-json", path, where), source)287 288        units.append(289            UnitManifest(290                id=declaration.id,291                language=declaration.language,292                api=tuple(api),293                parse=parse,294                package=package,295                rustdoc_json=rustdoc_json,296            )297        )298 299    return VariantManifest(300        variant=_string(raw, "variant", path),301        features=_features(raw.get("features", {}), "features", path),302        units=tuple(units),303    )304 305 306def check_variant(307    manifest: VariantManifest, *, description: Description, requested: str, path: Path308) -> None:309    """Reject a variant manifest that disagrees with what was requested and described."""310 311    if manifest.variant != requested:312        raise ContractError(313            f"{path}: build system answered for variant {manifest.variant!r}, "314            f"cpdocs requested {requested!r}"315        )316    declared = description.variant(requested)317    expected = {axis: tuple(sorted(values)) for axis, values in declared.features.items()}318    actual = {axis: tuple(sorted(values)) for axis, values in manifest.features.items()}319    for axis in {axis.name for axis in description.features}:320        expected.setdefault(axis, ())321        actual.setdefault(axis, ())322    if expected != actual:323        raise ContractError(324            f"{path}: variant {requested!r} was configured with features {actual}, "325            f"but the describe manifest declares {expected}"326        )327    described = [(unit.id, unit.language) for unit in description.units]328    reported = [(unit.id, unit.language) for unit in manifest.units]329    if sorted(described) != sorted(reported):330        raise ContractError(331            f"{path}: variant {requested!r} reports units {reported}, described units are "332            f"{described}"333        )334 335 336# --------------------------------------------------------------------------------------------------337# Helpers338# --------------------------------------------------------------------------------------------------339 340 341def _load_json(path: Path, what: str) -> dict[str, Any]:342    if not path.is_file():343        raise ContractError(f"the build system did not write the {what} {path}")344    try:345        raw = json.loads(path.read_text(encoding="utf-8"))346    except (OSError, json.JSONDecodeError) as error:347        raise ContractError(f"cannot read {what} {path}: {error}") from error348    if not isinstance(raw, dict):349        raise ContractError(f"{path}: {what} must be a JSON object")350    return raw351 352 353def _check_header(raw: dict[str, Any], path: Path, kind: str) -> None:354    if raw.get("cpdocs-manifest") != CONTRACT_VERSION:355        raise ContractError(f"{path}: unsupported cpdocs-manifest {raw.get('cpdocs-manifest')!r}")356    if raw.get("kind") != kind:357        raise ContractError(f"{path}: expected a {kind!r} manifest, found {raw.get('kind')!r}")358 359 360def _mapping(value: object, name: str, path: Path) -> dict[str, Any]:361    if not isinstance(value, dict):362        raise ContractError(f"{path}: {name} must be an object")363    return {str(key): item for key, item in value.items()}364 365 366def _string(data: dict[str, Any], key: str, path: Path, where: str = "") -> str:367    value = data.get(key)368    if not isinstance(value, str) or not value:369        prefix = f"{where}." if where else ""370        raise ContractError(f"{path}: {prefix}{key} must be a non-empty string")371    return value372 373 374def _string_tuple(value: object, name: str, path: Path) -> tuple[str, ...]:375    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):376        raise ContractError(f"{path}: {name} must be a list of strings")377    return tuple(value)378 379 380def _features(value: object, name: str, path: Path) -> dict[str, tuple[str, ...]]:381    data = _mapping(value, name, path)382    return {axis: _string_tuple(item, f"{name}.{axis}", path) for axis, item in data.items()}383 384 385def _units(value: object, path: Path) -> tuple[UnitDeclaration, ...]:386    if not isinstance(value, list) or not value:387        raise ContractError(f"{path}: units must be a non-empty list")388    units: list[UnitDeclaration] = []389    for index, item in enumerate(value):390        data = _mapping(item, f"units[{index}]", path)391        language = _string(data, "language", path, f"units[{index}]")392        if language not in LANGUAGES:393            raise ContractError(394                f"{path}: units[{index}].language must be one of {', '.join(LANGUAGES)}"395            )396        units.append(397            UnitDeclaration(id=_string(data, "id", path, f"units[{index}]"), language=language)398        )399    ids = [unit.id for unit in units]400    if len(set(ids)) != len(ids):401        raise ContractError(f"{path}: unit ids must be unique")402    return tuple(units)403 404 405def _path(value: str, source: Path) -> Path:406    path = Path(value).expanduser()407    return (path if path.is_absolute() else source / path).resolve()