Coverage for  / home / runner / work / bijux-cli / bijux-cli / src / bijux_cli / cli / commands / diagnostics / docs.py: 100%

1# SPDX-License-Identifier: Apache-2.0 

2# Copyright © 2025 Bijan Mousavi 

3 

4"""Pure helpers for the `docs` command (intent + payload builders).""" 

5 

6from __future__ import annotations 

7 

8from collections.abc import Mapping 

9from dataclasses import asdict, is_dataclass 

10from pathlib import Path 

11import platform 

12 

13from bijux_cli.cli.core.command import ascii_safe 

14from bijux_cli.core.enums import OutputFormat 

15from bijux_cli.core.version import __version__ 

16 

17CLI_VERSION = __version__ 

18 

19 

20def _default_output_path(base: Path, fmt: OutputFormat) -> Path: 

21 """Computes the default output file path for a CLI spec.""" 

22 return base / f"spec.{fmt.value}" 

23 

24 

25def _resolve_output_target( 

26 out: Path | None, fmt: OutputFormat 

27) -> tuple[str, Path | None]: 

28 """Resolves the output target and file path for the CLI spec.""" 

29 if out is None: 

30 path = _default_output_path(Path.cwd(), fmt) 

31 return str(path), path 

32 if str(out) == "-": 

33 return "-", None 

34 if out.is_dir(): 

35 path = _default_output_path(out, fmt) 

36 return str(path), path 

37 return str(out), out 

38 

39 

40def _build_spec_payload(include_runtime: bool) -> dict[str, object]: 

41 """Builds the CLI specification payload.""" 

42 from bijux_cli.cli.commands import list_registered_command_names 

43 

44 version_str = ascii_safe(CLI_VERSION, "version") 

45 payload: dict[str, object] = { 

46 "version": version_str, 

47 "commands": list_registered_command_names(), 

48 } 

49 if include_runtime: 

50 return { 

51 "version": payload["version"], 

52 "commands": payload["commands"], 

53 "python": ascii_safe(platform.python_version(), "python_version"), 

54 "platform": ascii_safe(platform.platform(), "platform"), 

55 } 

56 return payload 

57 

58 

59def _spec_mapping(spec: Mapping[str, object]) -> dict[str, object]: 

60 """Convert a spec payload into a mapping for service calls.""" 

61 data = asdict(spec) if is_dataclass(spec) else dict(spec) 

62 return {key: value for key, value in data.items() if value is not None} 

63 

64 

65__all__ = [ 

66 "CLI_VERSION", 

67 "_build_spec_payload", 

68 "_default_output_path", 

69 "_resolve_output_target", 

70 "_spec_mapping", 

71]