blib/lib/App/GHGen/Reporter.pm

filter: Statementstmt 100% 128 / 128 Branchbran 100% 30 / 30 Conditioncond 77.7% 7 / 9 MC/DCmcdc 60.0% 3 / 5 Subroutinesub 100% 9 / 9 Podpod 60.0% 3 / 5 totaltotal 96.7% 180 / 186 CC 31 SCAR 22.4
CC
31
Cov
99%
generate_github_comment
15.0
generate_markdown_report
9.0
estimate_savings
7.0
CRAP 9.4
« lib/App/GHGen/CostEstimator.pm ↑ Summary lib/App/GHGen/Analyzer.pm »
1 package App::GHGen::Reporter;
2  
3 5 ▶use v5.36;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 5 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
8 5 our @EXPORT_OK = qw(
9 generate_markdown_report
10 generate_github_comment
11 estimate_savings
12 );
13  
14 5 our $VERSION = '0.12';
15  
16 =head1 NAME
17  
18 App::GHGen::Reporter - Generate reports for GitHub integration
19  
20 =head1 SYNOPSIS
21  
22 use App::GHGen::Reporter qw(generate_github_comment);
23  
24 my $comment = generate_github_comment(\@issues, \@fixes);
25  
26 =head1 FUNCTIONS
27  
28 =head2 generate_markdown_report($issues, $fixes)
29  
30 Produce a Markdown-formatted report of workflow issues and applied fixes.
31  
32 =head3 Purpose
33  
34 Render a structured Markdown document that summarises detected issues grouped
35 by category, includes suggested fixes, and appends an estimated savings
36 section when applicable.
37  
38 =head3 Arguments
39  
40 =over 4
41  
42 =item C<$issues> (ArrayRef[HashRef], required)
43  
44 Issues to report. Each must have C<type>, C<severity>, C<message>; an
45 optional C<fix> key renders a collapsible C<E<lt>detailsE<gt>> block.
46  
47 =item C<$fixes> (ArrayRef, optional, default C<[]>)
48  
49 List of fixes already applied (used only for the summary count).
50  
51 =back
52  
53 =head3 Returns
54  
55 A non-empty Markdown string beginning with C<# GHGen Workflow Analysis>.
56  
57 =head3 Side Effects
58  
59 None. Pure function.
60  
61 =head3 Usage Example
62  
63 my $md = generate_markdown_report(\@issues, \@fixes);
64 path('report.md')->spew_utf8($md);
65  
66 =head3 API SPECIFICATION
67  
68 =head4 Input
69  
70 {
71 issues => { type => 'arrayref', required => 1 },
72 fixes => { type => 'arrayref', default => [] },
73 }
74  
75 =head4 Output
76  
77 { type => 'scalar' } # Markdown string
78  
79 =head3 FORMAL SPECIFICATION
80  
81 generate_markdown_report : seq Issue × seq Fix → ℤ*
82  
83 result begins with "# GHGen Workflow Analysis"
84 |issues| > 0 ⇒ result contains "## Issues by Category"
85 |issues| = 0 ⇒ result does not contain "## Issues by Category"
86 |fixes| > 0 ⇒ result contains "Fixes applied"
87 savings.minutes > 0 ⇒ result contains "## 💰 Estimated Savings"
88  
89 =cut
90  
91 12 ▶sub generate_markdown_report($issues, $fixes = []) {
Subroutine generate_markdown_report: called CC=9 SCAR=22.0
Pod documented
92 12 my $report = "# GHGen Workflow Analysis\n\n";
93  
94 12 my $total_issues = scalar @$issues;
95 12 my $total_fixes = scalar @$fixes;
96  
97 12 $report .= "## Summary\n\n";
98 12 $report .= "- 📊 **Issues found:** $total_issues\n";
99 12 $report .= "- ✅ **Fixes applied:** $total_fixes\n\n";
100  
101 12 ▶ if (@$issues) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$issues) 9 3 12
102 # Group by type
103 9 my %by_type;
104 9 push @{$by_type{$_->{type}}}, $_ for @$issues;
105  
106 9 $report .= "## Issues by Category\n\n";
107  
108 9 for my $type (sort keys %by_type) {
109 16 my $count = scalar @{$by_type{$type}};
110 16 my $emoji = get_type_emoji($type);
111 16 $report .= "### $emoji " . ucfirst($type) . " ($count)\n\n";
112  
113 16 for my $issue (@{$by_type{$type}}) {
114 18 my $severity_badge = get_severity_badge($issue->{severity});
115 18 $report .= "**$severity_badge $issue->{message}**\n\n";
116  
117 18 ▶ if ($issue->{fix}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($issue->{"fix"}) 15 3 18
118 15 $report .= "<details>\n";
119 15 $report .= "<summary>💡 Suggested Fix</summary>\n\n";
120 15 $report .= "```yaml\n";
121 15 $report .= "$issue->{fix}\n";
122 15 $report .= "```\n\n";
123 15 $report .= "</details>\n\n";
124 }
125 }
126 }
127 }
128  
129 # Add savings estimate if available
130 12 my $savings = estimate_savings($issues);
131 12 ▶ if ($savings->{minutes} > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($savings->{"minutes"} > 0) 8 4 12
132 8 $report .= "## 💰 Estimated Savings\n\n";
133 8 $report .= "By fixing these issues, you could save:\n\n";
134 8 $report .= "- ⏱️ **~$savings->{minutes} CI minutes/month**\n";
135  
136 8 ▶ if ($savings->{cost} > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($savings->{"cost"} > 0) 7 1 8
137 7 $report .= "- 💵 **~\$$savings->{cost}/month** (for private repos)\n";
138 }
139  
140 8 $report .= "\n";
141 }
142  
143 12 return $report;
144 }
145  
146 =head2 generate_github_comment($issues, $fixes, $options)
147  
148 Generate a GitHub Pull-Request comment summarising workflow issues.
149  
150 =head3 Purpose
151  
152 Produce a compact Markdown comment suitable for posting as a PR review
153 comment. Includes a summary table, a collapsible detail block, a how-to-fix
154 section when no fixes were applied, and a potential savings estimate.
155  
156 =head3 Arguments
157  
158 =over 4
159  
160 =item C<$issues> (ArrayRef[HashRef], required)
161  
162 Issues to display. Each must have C<type>, C<severity>, C<message>; an
163 optional C<file> key adds a file reference line.
164  
165 =item C<$fixes> (ArrayRef, optional, default C<[]>)
166  
167 Fixes already applied (used only for the applied-fix count in the header).
168  
169 =item C<$options> (HashRef, optional, default C<{}>)
170  
171 Reserved for future use; currently unused.
172  
173 =back
174  
175 =head3 Returns
176  
177 A non-empty Markdown string starting with C<## 🔍 GHGen Workflow Analysis>.
178  
179 When C<$issues> is empty, the comment contains the phrase
180 C<No issues found!> and is returned early without a table or details block.
181  
182 =head3 Side Effects
183  
184 None. Pure function.
185  
186 =head3 Usage Example
187  
188 my $comment = generate_github_comment(\@issues, \@fixes);
189 # Post $comment via GitHub API
190  
191 =head3 API SPECIFICATION
192  
193 =head4 Input
194  
195 {
196 issues => { type => 'arrayref', required => 1 },
197 fixes => { type => 'arrayref', default => [] },
198 options => { type => 'hashref', default => {} },
199 }
200  
201 =head4 Output
202  
203 { type => 'scalar' } # Markdown string
204  
205 =head3 FORMAL SPECIFICATION
206  
207 generate_github_comment : seq Issue × seq Fix × Options → ℤ*
208  
209 result begins with "## 🔍 GHGen Workflow Analysis"
210 |issues| = 0 ⇒ result contains "No issues found!" ∧ early return
211 |fixes| > 0 ⇒ result contains "Applied" ∧ fix count
212 |issues| > 0 ∧ |fixes| = 0 ⇒ result contains "How to Fix"
213 ∃ i ∈ issues: i.file defined ⇒ result contains i.file
214  
215 =cut
216  
217 15 ▶sub generate_github_comment($issues, $fixes = [], $options = {}) {
Subroutine generate_github_comment: called CC=15 SCAR=27.1
Pod documented
218 15 my $comment = "## 🔍 GHGen Workflow Analysis\n\n";
219  
220 15 my $total_issues = scalar @$issues;
221 15 my $total_fixes = scalar @$fixes;
222  
223 15 ▶ if ($total_fixes > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($total_fixes > 0) 3 12 15
224 3 $comment .= "✅ **Applied $total_fixes automatic fix(es)**\n\n";
225 }
226  
227 15 ▶ if ($total_issues == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($total_issues == 0) 3 12 15
228 3 $comment .= "🎉 **No issues found!** Your workflows look great.\n\n";
229 3 return $comment;
230 }
231  
232 # Summary table
233 12 $comment .= "| Category | Count | Auto-fixable |\n";
234 12 $comment .= "|----------|-------|-------------|\n";
235  
236 12 my %by_type;
237 12 push @{$by_type{$_->{type}}}, $_ for @$issues;
238  
239 12 for my $type (sort keys %by_type) {
240 15 my $count = scalar @{$by_type{$type}};
241 15 ▶ my $fixable = grep { $_->{auto_fixable} // 1 } @{$by_type{$type}};
Condition50%1/2
$_->{"auto_fixable"} // 1
l!l
017
MC/DC0%0/1
$_->{"auto_fixable"} // 1
$_->{"auto_fixable"}
Truth table50%1/2
A
A= $_->{"auto_fixable"}
Aresult
11
00
242 15 my $emoji = get_type_emoji($type);
243 15 $comment .= "| $emoji " . ucfirst($type) . " | $count | $fixable |\n";
244 }
245  
246 12 $comment .= "\n";
247  
248 # Detailed issues
249 12 $comment .= "<details>\n";
250 12 $comment .= "<summary>📋 View Details</summary>\n\n";
251  
252 12 for my $type (sort keys %by_type) {
253 15 $comment .= "### " . get_type_emoji($type) . " " . ucfirst($type) . "\n\n";
254  
255 15 for my $issue (@{$by_type{$type}}) {
256 17 my $badge = get_severity_badge($issue->{severity});
257 17 $comment .= "- $badge **$issue->{message}**\n";
258  
259 17 ▶ if ($issue->{file}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($issue->{"file"}) 5 12 17
260 5 $comment .= " - File: `$issue->{file}`\n";
261 }
262 }
263  
264 15 $comment .= "\n";
265 }
266  
267 12 $comment .= "</details>\n\n";
268  
269 # Add recommendations
270 12 ▶ if ($total_fixes == 0 && $total_issues > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($total_fixes == 0 and $total_issues > 0) 9 3 12
Condition66%2/3
$total_fixes == 0 and $total_issues > 0
!ll&&!rl&&r
309
MC/DC50%1/2
$total_fixes == 0 and $total_issues > 0
$total_fixes == 0 $total_issues > 0
Truth table66%2/3
A and B
A= $total_fixes == 0B= $total_issues > 0
ABresult
0X0
100
111
271 9 $comment .= "### 💡 How to Fix\n\n";
272 9 $comment .= "Run these commands locally:\n\n";
273 9 $comment .= "```bash\n";
274 9 $comment .= "# Install ghgen\n";
275 9 $comment .= "cpanm App::GHGen\n\n";
276 9 $comment .= "# Analyze and fix\n";
277 9 $comment .= "ghgen analyze --fix\n";
278 9 $comment .= "```\n\n";
279  
280 9 $comment .= "Or enable auto-fix in this action:\n\n";
281 9 $comment .= "```yaml\n";
282 9 $comment .= "- uses: nigelhorne/ghgen-action\@v1\n";
283 9 $comment .= " with:\n";
284 9 $comment .= " auto-fix: true\n";
285 9 $comment .= " create-pr: true\n";
286 9 $comment .= "```\n\n";
287 }
288  
289 # Add savings estimate
290 12 my $savings = estimate_savings($issues);
291 12 ▶ if ($savings->{minutes} > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($savings->{"minutes"} > 0) 9 3 12
292 9 $comment .= "### 💰 Potential Savings\n\n";
293 9 $comment .= "By fixing these issues:\n";
294 9 $comment .= "- ⏱️ Save **~$savings->{minutes} CI minutes/month**\n";
295  
296 9 ▶ if ($savings->{cost} > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($savings->{"cost"} > 0) 8 1 9
297 8 $comment .= "- 💵 Save **~\$$savings->{cost}/month** (private repos)\n";
298 }
299  
300 9 $comment .= "\n";
301 }
302  
303 12 $comment .= "---\n";
304 12 $comment .= "*Analysis by [GHGen](https://github.com/your-org/ghgen)*\n";
305  
306 12 return $comment;
307 }
308  
309 =head2 estimate_savings($issues)
310  
311 Estimate CI-minute savings and associated cost reduction from fixing a set of issues.
312  
313 =head3 Purpose
314  
315 For each C<performance> (caching) or C<cost> (concurrency, triggers) issue,
316 add a fixed minute estimate to the running total and compute the equivalent
317 USD saving at the GitHub private-repo rate of $0.008/minute.
318  
319 =head3 Arguments
320  
321 =over 4
322  
323 =item C<$issues> (ArrayRef[HashRef], required)
324  
325 Issue hashes with at least C<type> and C<message>.
326  
327 =back
328  
329 =head3 Returns
330  
331 A hash reference:
332  
333 {
334 minutes => Int, # total estimated minutes saved per month; 0 when no savings
335 cost => Int, # floor(minutes * 0.008); 0 when no savings
336 }
337  
338 =head3 Side Effects
339  
340 None. Pure function.
341  
342 =head3 Usage Example
343  
344 my $s = estimate_savings(\@issues);
345 say "Save $s->{minutes} min/month";
346  
347 =head3 API SPECIFICATION
348  
349 =head4 Input
350  
351 { issues => { type => 'arrayref', required => 1 } }
352  
353 =head4 Output
354  
355 {
356 type => 'hashref',
357 keys => {
358 minutes => { type => 'scalar' },
359 cost => { type => 'scalar' },
360 },
361 }
362  
363 =head3 FORMAL SPECIFICATION
364  
365 estimate_savings : seq Issue → { minutes: ℕ, cost: ℕ }
366  
367 RATE ≔ 0.008
368 savings(i) ≔
369 i.type = performance ∧ i.message =~ /caching/ → 500
370 i.type = cost ∧ i.message =~ /concurrency/ → 50
371 i.type = cost ∧ i.message =~ /triggers/ → 100
372 otherwise → 0
373  
374 total ≔ ∑ { savings(i) ∣ i ∈ issues }
375 result ≔ { minutes ↦ total, cost ↦ floor(total × RATE) }
376  
377 =cut
378  
379 36 ▶sub estimate_savings($issues) {
Subroutine estimate_savings: called CC=7 SCAR=19.5
Pod documented
380 36 my %savings = (
381 minutes => 0,
382 cost => 0,
383 );
384  
385 36 for my $issue (@$issues) {
386 # Estimate savings by issue type
387 48 ▶ if ($issue->{type} eq 'performance') {
Branch: 2 branches
BranchTrueFalseTotal
if ($issue->{'type'} eq 'performance') { } 23 25 48
elsif ($issue->{'type'} eq 'cost') { } 14 11 25
388 # Caching saves ~5 minutes per workflow run
389 # Assume 100 runs/month
390 23 ▶ $savings{minutes} += 500 if $issue->{message} =~ /caching/;
Branch: 1 branch
BranchTrueFalseTotal
if $issue->{"message"} =~ /caching/u 20 3 23
391 } elsif ($issue->{type} eq 'cost') {
392 14 ▶ if ($issue->{message} =~ /concurrency/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($issue->{"message"} =~ /concurrency/u) 9 5 14
393 # Concurrency saves ~50 minutes/month by canceling old runs
394 9 $savings{minutes} += 50;
395 }
396 14 ▶ if ($issue->{message} =~ /triggers/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($issue->{"message"} =~ /triggers/u) 5 9 14
397 # Trigger filters save ~100 minutes/month
398 5 $savings{minutes} += 100;
399 }
400 }
401 }
402  
403 # Private repo pricing: ~$0.008 per minute
404 36 $savings{cost} = int($savings{minutes} * 0.008);
405  
406 36 return \%savings;
407 }
408  
409 54 ▶sub get_type_emoji($type) {
Subroutine get_type_emoji: called CC=2 SCAR=6.9
Pod undocumented
410 54 my %emojis = (
411 performance => '⚡',
412 security => '🔒',
413 cost => '💰',
414 maintenance => '🔧',
415 );
416  
417 54 ▶ return $emojis{$type} // '📌';
Condition100%2/2
$emojis{$type} // "\360\237\223\214"
l!l
513
MC/DC100%1/1
$emojis{$type} // "\360\237\223\214"
$emojis{$type}
Truth table100%2/2
A
A= $emojis{$type}
Aresult
11
00
418 }
419  
420 42 ▶sub get_severity_badge($severity) {
Subroutine get_severity_badge: called CC=2 SCAR=6.9
Pod undocumented
421 42 my %badges = (
422 high => '🔴',
423 medium => '🟡',
424 low => '🟢',
425 );
426  
427 42 ▶ return $badges{$severity} // '⚪';
Condition100%2/2
$badges{$severity} // "\342\232\252"
l!l
393
MC/DC100%1/1
$badges{$severity} // "\342\232\252"
$badges{$severity}
Truth table100%2/2
A
A= $badges{$severity}
Aresult
11
00
428 }
429  
430 =head1 AUTHOR
431  
432 Nigel Horne E<lt>njh@nigelhorne.comE<gt>
433  
434 L<https://github.com/nigelhorne>
435  
436 =head1 LICENSE
437  
438 This is free software; you can redistribute it and/or modify it under
439 the same terms as the Perl 5 programming language system itself.
440  
441 =cut
442  
443 5 1;
« lib/App/GHGen/CostEstimator.pm ↑ Summary lib/App/GHGen/Analyzer.pm »