feat(api): add framework-neutral PanelComparison for ordered panel IDs, failure precedence, capture states, and combined structural/state counts without changing adapter output or diagnostic values.

[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 (05c5365) to head (abb8bb2).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff            @@
##               main      #37   +/-   ##
=========================================
  Coverage     99.95%   99.95%           
- Complexity     2063     2075   +12     
=========================================
  Files           157      158    +1     
  Lines          8278     8328   +50     
=========================================
+ Hits           8274     8324   +50     
  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: d7c8666d-4ed3-4697-a57b-f2c0d2ae2af8

📥 Commits

Reviewing files that changed from the base of the PR and between 05c5365 and abb8bb2.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• src/Comparison/PanelComparison.php
• tests/Comparison/PanelComparisonTest.php
• tests/Provider/PanelComparisonProvider.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. (7)

• GitHub Check: phpunit / PHP 8.4-windows-2022
• GitHub Check: phpunit / PHP 8.3-windows-2022
• GitHub Check: phpunit / PHP 8.5-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
• GitHub Check: Verify Vite build reproduces dist.

🧰 Additional context used

🪛 LanguageTool

CHANGELOG.md

[style] ~42-~42: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...percentages, trends, and panel links. - feat(api): add framework-neutral `PanelCompa...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🪛 PHPMD (2.15.0)

tests/Provider/PanelComparisonProvider.php

[warning] 20-207: The method comparisons() has 188 lines of code. Current threshold is set to 100. Avoid really long methods. (undefined)

(ExcessiveMethodLength)

---

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

(StaticAccess)

tests/Comparison/PanelComparisonTest.php

[error] 34-34: Avoid using static access to class '\PHPForge\Debug\Comparison\PanelComparison' in method 'testBetweenPreservesPanelContracts'. (undefined)

(StaticAccess)

src/Comparison/PanelComparison.php

[warning] 24-24: Avoid variables with short names like $id. Configured minimum length is 3. (undefined)

(ShortVariable)

---

[warning] 57-57: Avoid unused local variables such as '$_label'. (undefined)

(UnusedLocalVariable)

---

[error] 78-81: Avoid using static access to class 'PHPForge\Debug\Comparison\PayloadDifference' in method 'between'. (undefined)

(StaticAccess)

---

[warning] 112-112: Avoid variables with short names like $id. Configured minimum length is 3. (undefined)

(ShortVariable)

---

[warning] 121-121: Avoid variables with short names like $id. Configured minimum length is 3. (undefined)

(ShortVariable)

🔇 Additional comments (5)

src/Comparison/PanelComparison.php (1)

16-129: LGTM!

README.md (1)

136-155: LGTM!

Also applies to: 177-180

CHANGELOG.md (1)

42-42: LGTM!

tests/Provider/PanelComparisonProvider.php (1)

9-207: LGTM!

tests/Comparison/PanelComparisonTest.php (1)

13-73: LGTM!

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Added panel comparison capabilities with ordered panel results, capture-state transitions, failure precedence, and combined structural change counts.
  • Added documentation for using panel comparisons and coordinating related revisions.

• Tests

  • Added coverage for panel ordering, labels, capture states, structural differences, state-only changes, and unchanged diagnostic output.

Walkthrough

Adds the framework-neutral PanelComparison API. It compares panel payloads and failure envelopes, reports capture-state transitions, orders panel IDs, and preserves existing adapter output and serialized diagnostics.

Changes

Panel comparison API

Layer / File(s)	Summary
Comparison contract and implementation src/Comparison/PanelComparison.php, README.md, CHANGELOG.md	Adds ordered immutable panel results with capture states and structural difference counts. Documents ID ordering, failure precedence, state transitions, adapter mapping, and coordinated publication.
Comparison characterization tests tests/Comparison/PanelComparisonTest.php, tests/Provider/PanelComparisonProvider.php	Covers panel selection, ordering, absent and failure states, structural counts, state-only changes, difference detection, and unchanged serialized diagnostics.

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

Merge Risk: ⚪ Minimal · up to abb8b

This adds a panel-comparison API without changing existing adapter output or serialized diagnostics. The documented comparison behavior is covered by tests, with no remaining merge-readiness risk identified.

Sequence Diagram(s)

sequenceDiagram
  participant Baseline as DebugSnapshot baseline
  participant Target as DebugSnapshot target
  participant Comparison as PanelComparison::between
  participant Results as PanelComparison results
  Comparison->>Baseline: read payload and failure IDs
  Comparison->>Target: read payload and failure IDs
  Comparison->>Comparison: order IDs and compute states and counts
  Comparison->>Results: create ordered immutable results

Loading

Poem

A rabbit checks each panel in line
States and counts align and shine
Failures take their proper place
Empty leaves keep their trace
Diagnostics rest, unchanged and fine

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	❓ Inconclusive	The description correctly identifies the change as a non-breaking new feature, but it does not describe the PanelComparison API or its behavior.	Add a brief summary of the PanelComparison API, including panel ordering, failure precedence, capture states, and combined structural/state counts.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the new PanelComparison API and its main behaviors. It is detailed but remains related to the primary changeset.
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 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/add-panel-comparison

---

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.}