feat(api): centralize typed structural payload differences and add immutable fluent toolbar item and panel construction while preserving diagnostic values, constructors, and serialized payloads.

[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 (06eb430) to head (b752cc0).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##               main      #35    +/-   ##
==========================================
  Coverage     99.95%   99.95%            
- Complexity     2018     2040    +22     
==========================================
  Files           155      156     +1     
  Lines          8054     8165   +111     
==========================================
+ Hits           8050     8161   +111     
  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: d34c19f8-71fc-427a-9a1c-15df5045e842

📥 Commits

Reviewing files that changed from the base of the PR and between 06eb430 and b752cc0.

📒 Files selected for processing (9)

• CHANGELOG.md
• README.md
• src/Comparison/PayloadDifference.php
• src/Toolbar/ToolbarItem.php
• src/Toolbar/ToolbarPanel.php
• tests/Comparison/PayloadDifferenceTest.php
• tests/Provider/ToolbarItemProvider.php
• tests/Toolbar/ToolbarItemTest.php
• tests/Toolbar/ToolbarPanelTest.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. (3)

• GitHub Check: mutation / PHP 8.5-ubuntu-latest
• GitHub Check: Verify Vite build reproduces dist.
• GitHub Check: mutation / PHP 8.5-ubuntu-latest

🧰 Additional context used

🪛 PHPMD (2.15.0)

src/Toolbar/ToolbarItem.php

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

(ShortVariable)

src/Comparison/PayloadDifference.php

[error] 48-50: The method between uses an else expression. Else clauses are basically not necessary and you can simplify the code by not using them. (undefined)

(ElseExpression)

tests/Toolbar/ToolbarPanelTest.php

[error] 35-35: Avoid using static access to class '\PHPForge\Debug\Toolbar\ToolbarPanel' in method 'testCreateMatchesConstructorDefaults'. (undefined)

(StaticAccess)

---

[error] 131-137: The method testWithNavigationPreservesOriginalAndOtherFields uses an else expression. Else clauses are basically not necessary and you can simplify the code by not using them. (undefined)

(ElseExpression)

tests/Comparison/PayloadDifferenceTest.php

[warning] 22-139: The method payloads() has 118 lines of code. Current threshold is set to 100. Avoid really long methods. (undefined)

(ExcessiveMethodLength)

---

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

(StaticAccess)

---

[error] 173-176: Avoid using static access to class '\PHPForge\Debug\Comparison\PayloadDifference' in method 'testResultRetainsOnlyCounters'. (undefined)

(StaticAccess)

src/Toolbar/ToolbarPanel.php

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

(ShortVariable)

tests/Toolbar/ToolbarItemTest.php

[error] 24-24: Avoid using static access to class '\PHPForge\Debug\Toolbar\ToolbarItem' in method 'testCreateMatchesConstructorDefaults'. (undefined)

(StaticAccess)

---

[error] 83-89: The method testWithIconPreservesOriginalAndOtherFields uses an else expression. Else clauses are basically not necessary and you can simplify the code by not using them. (undefined)

(ElseExpression)

---

[error] 127-133: The method testWithIdPreservesOriginalAndOtherFields uses an else expression. Else clauses are basically not necessary and you can simplify the code by not using them. (undefined)

(ElseExpression)

---

[error] 172-178: The method testWithLabelPreservesOriginalAndOtherFields uses an else expression. Else clauses are basically not necessary and you can simplify the code by not using them. (undefined)

(ElseExpression)

---

[error] 254-260: The method testWithTitlePreservesOriginalAndOtherFields uses an else expression. Else clauses are basically not necessary and you can simplify the code by not using them. (undefined)

(ElseExpression)

---

[error] 299-305: The method testWithUrlPreservesOriginalAndOtherFields uses an else expression. Else clauses are basically not necessary and you can simplify the code by not using them. (undefined)

(ElseExpression)

🔇 Additional comments (5)

src/Toolbar/ToolbarItem.php (1)

35-53: LGTM!

Also applies to: 70-165

src/Toolbar/ToolbarPanel.php (1)

32-39: LGTM!

Also applies to: 68-111

tests/Provider/ToolbarItemProvider.php (1)

1-34: LGTM!

tests/Toolbar/ToolbarItemTest.php (1)

1-307: LGTM!

tests/Toolbar/ToolbarPanelTest.php (1)

1-140: LGTM!

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Added structural payload comparison with counts for added, removed, changed, and unchanged values.
  • Added immutable fluent builders for toolbar items and panels, including configurable icons, labels, status, URLs, and items.
  • Preserved typed values and predictable serialized output, including null and empty-value handling.

• Documentation

  • Added README guidance for payload comparison and fluent toolbar configuration.
  • Added a changelog entry for the upcoming release.

• Tests

  • Added coverage for typed comparisons, immutability, serialization, and toolbar configuration behavior.

Walkthrough

Adds PayloadDifference for typed structural payload counts and adds immutable fluent factories and modifiers for toolbar items and panels. Documentation and PHPUnit tests cover serialization, immutability, replacement behavior, and typed values.

Changes

API features

Layer / File(s)	Summary
Structural payload comparison src/Comparison/PayloadDifference.php, tests/Comparison/PayloadDifferenceTest.php, README.md, CHANGELOG.md	Adds immutable added, removed, changed, and unchanged counters. The implementation preserves typed leaf semantics and source payloads. Tests cover hashing, path escaping, empty arrays, null values, and result properties.
Fluent toolbar models src/Toolbar/ToolbarItem.php, src/Toolbar/ToolbarPanel.php, tests/Toolbar/*, tests/Provider/ToolbarItemProvider.php, README.md	Adds toolbar factories and immutable with... methods. Tests verify constructor compatibility, field preservation, null omission, item replacement, clearing, and serialized payloads.

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

Merge Risk: ⚪ Minimal · up to b752c

This adds typed payload-difference counters and fluent immutable toolbar construction while preserving existing constructors and serialized payload behavior. The changed contracts are covered by focused tests, with no remaining merge-blocking risk identified.

Poem

A rabbit builds fluent bars with care
Each copied field stays in its lair
Payload leaves count, typed and bright
Nulls stay distinct from zero’s light
Immutable paths hop into flight

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main API additions and preservation requirements. It is long, but it remains clear, specific, and related to the changeset.
Description check	✅ Passed	The description identifies the pull request as a non-breaking new feature, which matches the API additions and documentation changes.
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 62.16% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 37 functions across 7 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/centralized-type-structured-payload-history

---

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