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()