Coverage for src / tracekit / reporting / content / executive.py: 100%

1"""Executive summary auto-generation. 

2 

3Automatically generates concise executive summaries with key findings, 

4pass/fail status, and critical violations highlighted. 

5 

6 

7References: 

8""" 

9 

10from __future__ import annotations 

11 

12from dataclasses import dataclass, field 

13from typing import Any, Literal 

14 

15 

16@dataclass 

17class ExecutiveSummary: 

18 """Executive summary of analysis results. 

19 

20 Attributes: 

21 overall_status: Overall pass/fail status. 

22 pass_count: Number of passing tests. 

23 total_count: Total number of tests. 

24 key_findings: List of 3-5 key findings. 

25 critical_violations: List of critical violations. 

26 min_margin_pct: Minimum margin percentage. 

27 summary_text: Natural language summary. 

28 

29 References: 

30 REPORT-004: Executive Summary Auto-Generation 

31 """ 

32 

33 overall_status: bool 

34 pass_count: int 

35 total_count: int 

36 key_findings: list[str] = field(default_factory=list) 

37 critical_violations: list[str] = field(default_factory=list) 

38 min_margin_pct: float | None = None 

39 summary_text: str = "" 

40 

41 

42def generate_executive_summary( 

43 results: dict[str, Any], 

44 *, 

45 max_findings: int = 5, 

46 length: Literal["short", "detailed"] = "short", 

47) -> ExecutiveSummary: 

48 """Generate executive summary from analysis results. 

49 

50 Automatically extracts top 3-5 key findings, pass/fail status in first 

51 sentence, and critical violations in bullet list. 

52 

53 Args: 

54 results: Analysis results dictionary. 

55 max_findings: Maximum number of key findings (default 5). 

56 length: Summary length (short=1 paragraph, detailed=1 page). 

57 

58 Returns: 

59 ExecutiveSummary with generated content. 

60 

61 Example: 

62 >>> results = {"pass_count": 10, "total_count": 12} 

63 >>> summary = generate_executive_summary(results) 

64 >>> print(summary.summary_text) 

65 'All 10 tests passed with >25% margin. No violations.' 

66 

67 References: 

68 REPORT-004: Executive Summary Auto-Generation 

69 """ 

70 # Extract basic counts 

71 pass_count = results.get("pass_count", 0) 

72 total_count = results.get("total_count", 0) 

73 fail_count = total_count - pass_count if total_count else 0 

74 overall_status = fail_count == 0 

75 

76 # Extract violations 

77 violations = results.get("violations", []) 

78 critical_violations = [v for v in violations if v.get("severity", "").lower() == "critical"] 

79 

80 # Extract key findings 

81 key_findings: list[str] = [] 

82 if critical_violations: 

83 key_findings.append( 

84 f"{len(critical_violations)} critical violation(s) require immediate attention" 

85 ) 

86 elif violations: 

87 key_findings.append(f"{len(violations)} violation(s) detected") 

88 

89 # Add margin information 

90 min_margin = results.get("min_margin") 

91 if min_margin is not None and min_margin < 20: 

92 status = "critical" if min_margin < 10 else "marginal" 

93 key_findings.append(f"Minimum margin is {min_margin:.1f}% ({status})") 

94 

95 # Build summary text in natural language 

96 if overall_status and total_count > 0: 

97 summary_text = f"All {pass_count} tests passed." 

98 if min_margin is not None and min_margin > 20: 

99 summary_text += f" Minimum margin: {min_margin:.1f}%." 

100 elif total_count > 0: 

101 pct = fail_count / total_count * 100 

102 summary_text = f"{fail_count} of {total_count} tests failed ({pct:.0f}% failure rate)." 

103 else: 

104 summary_text = "Analysis completed successfully." 

105 

106 if critical_violations: 

107 summary_text += ( 

108 f" Critical: {len(critical_violations)} violation(s) require immediate action." 

109 ) 

110 

111 # Add detailed findings for detailed mode 

112 if length == "detailed" and key_findings: 

113 summary_text += "\n\nKey Findings:\n" 

114 summary_text += "\n".join(f" - {finding}" for finding in key_findings[:max_findings]) 

115 

116 return ExecutiveSummary( 

117 overall_status=overall_status, 

118 pass_count=pass_count, 

119 total_count=total_count, 

120 key_findings=key_findings[:max_findings], 

121 critical_violations=[str(v) for v in critical_violations], 

122 min_margin_pct=min_margin, 

123 summary_text=summary_text, 

124 ) 

125 

126 

127__all__ = ["ExecutiveSummary", "generate_executive_summary"]