PHPLIB-1736: Add $scoreFusion stage

[kraenhansen]

Merging this PR will:

• Add the $scoreFusion as per its documentation.

Context: Working on COMPASS-8939 adding auto-complete support for $scoreFusion to mongosh.

[GromNaN]

I'll bet 20 Bonusly points that the Copilot agent can generate the PHP aggregation on the first try.

Thank you for contributing the PHP library.

[GromNaN]

That was a positive comment.
In fact, this file is generated, but it is a frame in which we have to write the code with the PHP aggregation builder. This allows us to validate the functioning of the aggregation builder and check the DX.
The tests/Builder/Stage has many examples of this.

The translation logic is very systematic, which means that an AI agent can easily guess what to write based on the expected extended JSON.
This is a suggestion that you complete this piece of code, but we can also take care of it.

[kraenhansen]

Pushed a commit 🤞

[codecov-commenter]

Codecov Report

❌ Patch coverage is 66.66667% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.71%. Comparing base (004a3c0) to head (bef5a4b).
⚠️ Report is 4 commits behind head on v2.x.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/Builder/Stage/FluentFactoryTrait.php	0.00%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               v2.x    #1811      +/-   ##
============================================
- Coverage     87.72%   87.71%   -0.02%     
+ Complexity     3195     3188       -7     
============================================
  Files           424      425       +1     
  Lines          6296     6298       +2     
============================================
+ Hits           5523     5524       +1     
- Misses          773      774       +1     

Flag	Coverage Δ
6.0-replica_set	85.69% <66.66%> (-0.02%)	⬇️
6.0-server	81.69% <66.66%> (-0.02%)	⬇️
6.0-sharded_cluster	85.48% <66.66%> (+0.19%)	⬆️
8.0-replica_set	87.63% <66.66%> (-0.02%)	⬇️
8.0-server	82.53% <66.66%> (-0.02%)	⬇️
8.0-sharded_cluster	87.47% <66.66%> (+0.16%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

[kraenhansen]

The remaining test failure seems unrelated and present in other PRs as well. Could / should I do something to increase the code coverage?

[Copilot]

Pull request overview

This PR adds support for MongoDB's $scoreFusion aggregation stage, which enables hybrid search by combining multiple pipelines using relative score fusion. This implementation provides a PHP builder interface for the stage along with comprehensive test coverage.

• Implements the ScoreFusionStage class with support for input pipelines, score normalization, combination methods, and score details
• Adds factory methods for both static and fluent builder patterns
• Includes test cases with expected JSON output validation

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Builder/Stage/ScoreFusionStage.php	Defines the core ScoreFusionStage class with input, combination, and scoreDetails parameters
src/Builder/Stage/FactoryTrait.php	Adds static factory method scoreFusion() to create stage instances
src/Builder/Stage/FluentFactoryTrait.php	Adds fluent factory method scoreFusion() for pipeline chaining
tests/Builder/Stage/ScoreFusionStageTest.php	Provides test case validating the stage builder against expected pipeline output
tests/Builder/Stage/Pipelines.php	Adds expected JSON output enum case for the scoreFusion example test
generator/config/stage/scoreFusion.yaml	Configuration file defining the stage specification for code generation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.