feat(api): centralize request-summary metric calculations and formatting in SummaryMetricComparison, preserving history labels, order, units, rounding, percentages, trends, and panel links.

[terabytesoftw]

Pull Request

• Breaking change (fix or feature that would cause existing functionality to change)
• Bugfix (non-breaking change that fixes an issue)
• CI/build configuration
• Documentation update
• New feature (non-breaking change that adds functionality)
• Refactoring (no functional changes)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.95%. Comparing base (2548ac0) to head (7351bed).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##               main      #36    +/-   ##
==========================================
  Coverage     99.95%   99.95%            
- Complexity     2040     2063    +23     
==========================================
  Files           156      157     +1     
  Lines          8165     8278   +113     
==========================================
+ Hits           8161     8274   +113     
  Misses            4        4            

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 03e06606-1914-4b1b-981c-e630ae374e85

📥 Commits

Reviewing files that changed from the base of the PR and between 2548ac0 and 7351bed.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• src/Comparison/SummaryMetricComparison.php
• tests/Comparison/SummaryMetricComparisonTest.php
• tests/Provider/SummaryMetricComparisonProvider.php

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (5)

• GitHub Check: phpunit / PHP 8.4-windows-2022
• GitHub Check: phpunit / PHP 8.3-windows-2022
• GitHub Check: mutation / PHP 8.5-ubuntu-latest
• GitHub Check: Verify Vite build reproduces dist.
• GitHub Check: mutation / PHP 8.5-ubuntu-latest

⚠️ CI failures not shown inline (1)

Commit Status: codecov/project: codecov/project

Conclusion: failure

99.95% (target 100.00%)

🧰 Additional context used

🪛 PHPMD (2.15.0)

tests/Provider/SummaryMetricComparisonProvider.php

[warning] 14-1056: The class SummaryMetricComparisonProvider has 1043 lines of code. Current threshold is 1000. Avoid really long classes. (undefined)

(ExcessiveClassLength)

---

[warning] 19-554: The method metrics() has 536 lines of code. Current threshold is set to 100. Avoid really long methods. (undefined)

(ExcessiveMethodLength)

---

[warning] 559-1047: The method summaries() has 489 lines of code. Current threshold is set to 100. Avoid really long methods. (undefined)

(ExcessiveMethodLength)

---

[error] 1054-1054: Avoid using static access to class '\PHPForge\Debug\Storage\RequestSummary' in method 'summary'. (undefined)

(StaticAccess)

tests/Comparison/SummaryMetricComparisonTest.php

[error] 32-32: Avoid using static access to class '\PHPForge\Debug\Comparison\SummaryMetricComparison' in method 'testBetweenPreservesAllMetricContracts'. (undefined)

(StaticAccess)

---

[error] 63-63: Avoid using static access to class '\PHPForge\Debug\Comparison\SummaryMetricComparison' in method 'testBetweenPreservesMetricBoundaries'. (undefined)

(StaticAccess)

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Added request-summary metric comparisons with stable ordering and consistent formatting.
  • Displays baseline and target values, changes, percentages, trends, units, and related panel links.
  • Supports status, method, AJAX state, duration, memory, SQL, mail, and database-caller metrics.
  • Handles uncaptured and missing values while preserving existing request summaries.

• Documentation

  • Added usage guidance, metric ordering, formatting rules, and value-handling details to the README.
  • Added the feature to the upcoming changelog.

Walkthrough

The PR adds SummaryMetricComparison::between() for ordered, immutable comparisons of two RequestSummary objects. It formats values, deltas, percentages, trends, units, panel IDs, and uncaptured metrics, with documentation and extensive regression coverage.

Changes

Request Summary Comparison

Layer / File(s)	Summary
Comparison API and metric formatting src/Comparison/SummaryMetricComparison.php, README.md, CHANGELOG.md	Adds the immutable comparison value object and canonical metric output. It formats numeric, text, boolean, status, missing, delta, percentage, trend, unit, and panel values. Documentation and the changelog describe the API contract.
Comparison regression coverage tests/Provider/SummaryMetricComparisonProvider.php, tests/Comparison/SummaryMetricComparisonTest.php	Adds provider data and PHPUnit tests for ordering, exact formatting, missing values, increases, decreases, rounding boundaries, metric boundaries, and unchanged input summaries.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 7351b

This adds a request-summary comparison API with documented formatting and regression coverage. No merge-blocking correctness or runtime risk is currently identified.

Poem

The rabbit checks each metric row,
With tidy units in a glow.
Baselines hop, targets align,
Trends point up or hold the line.
Panel links rest where they should be,
While tests guard every comparison key.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 3 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description identifies this pull request as a non-breaking new feature, which matches the changeset and objectives.
Title check	✅ Passed	The title clearly describes the main change: centralizing request-summary metric calculations and formatting in SummaryMetricComparison while preserving metric output contracts.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 46.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 3 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/centralize-request-summary-metrics

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}