Coverage for /home/runner/work/bijux-cli/bijux-cli/src/bijux_cli/contracts/audit.py: 100%

1# SPDX-License-Identifier: MIT 

2# Copyright © 2025 Bijan Mousavi 

3 

4"""Defines the contract for the audit logging and diagnostics service. 

5 

6This module specifies the `AuditProtocol`, a formal interface that any 

7auditing service within the application must implement. This ensures a 

8consistent API for logging command executions and performing system health 

9checks, promoting modularity and testability. 

10""" 

11 

12from __future__ import annotations 

13 

14from typing import Any, Protocol, TypeVar, runtime_checkable 

15 

16from bijux_cli.contracts.process import ProcessPoolProtocol 

17 

18T = TypeVar("T") 

19 

20 

21@runtime_checkable 

22class AuditProtocol( 

23 ProcessPoolProtocol, 

24 Protocol, 

25): 

26 """Defines the contract for audit logging and system diagnostics. 

27 

28 This interface specifies the methods required for securely logging command 

29 executions, retrieving audit trails, and performing diagnostic checks on 

30 the CLI environment. It inherits from `ProcessPoolProtocol` to manage 

31 command execution. 

32 """ 

33 

34 def log(self, cmd: list[str], *, executor: str) -> None: 

35 """Logs a command execution for auditing purposes. 

36 

37 Args: 

38 cmd (list[str]): The command and its arguments to log. 

39 executor (str): The name or identifier of the entity that executed 

40 the command. 

41 

42 Returns: 

43 None: 

44 """ 

45 ... 

46 

47 def get_commands(self) -> list[dict[str, Any]]: 

48 """Returns a copy of all recorded audit commands. 

49 

50 Returns: 

51 list[dict[str, Any]]: A list of dictionaries, where each dictionary 

52 represents a logged command execution. 

53 """ 

54 ... 

55 

56 def cli_audit(self) -> None: 

57 """Performs a CLI-specific audit and status check. 

58 

59 This method is the entry point for the `bijux audit` command. 

60 Implementations should gather and log the current audit status without 

61 raising exceptions or executing external commands. 

62 

63 Returns: 

64 None: 

65 """ 

66 ...