Integrate MeasureDefScorer Part 1: Foundation for Version-Agnostic Scoring

[lukedegruchy]

Merge Request Description

Summary

This MR implements Part 1 of a 2-part plan to integrate version-agnostic measure scoring into the clinical-reasoning evaluation workflow. Part 1 focuses on creating foundation infrastructure and a new external API for post-hoc measure scoring without modifying existing evaluation behavior. The primary deliverable is MeasureReportScoringFhirAdapter, a version-agnostic API that enables external consumers (specifically the cdr-cr project) to score MeasureReports that already have population counts but lack calculated scores.

1. New External API: Created MeasureReportScoringFhirAdapter as a simplified, version-agnostic entry point for post-hoc MeasureReport scoring, eliminating the need for external consumers to manage version-specific scorers and builders.

2. Score Copying Infrastructure: Added copyScoresFromDef() methods to R4 and DSTU3 MeasureReport builders that copy scores from Def objects to FHIR MeasureReports. This infrastructure is currently inactive (Def objects have null scores in Part 1) and will be activated in Part 2 when MeasureDefScorer is integrated into the evaluation workflow.

3. Def Class Enhancements: Enhanced StratumDef with getMeasureScore() for improvement notation and createSnapshot() for immutable copies, plus added createSnapshot() to MeasureDef and other Def classes to support the Def capture framework.

4. Version-Agnostic Testing Framework: Implemented a comprehensive fhir2deftest package with SelectedDef assertion APIs and adapters that enable writing measure evaluation tests once and running them against multiple FHIR versions (DSTU3, R4, future R5).

5. Deprecation Documentation: Added javadoc notices to IMeasureReportScorer documenting the migration path to the new API while keeping all existing scorer functionality unchanged.

Code Review Suggestions

• External API Design: Review MeasureReportScoringFhirAdapter and IMeasureReportScoringFhirAdapter interface design for usability by external consumers. Verify the static factory pattern and version detection logic align with clinical-reasoning API conventions.

• Score Copying Logic Correctness: In R4MeasureReportBuilder.copyScoresFromDef() and Dstu3MeasureReportBuilder.copyScoresFromDef(), verify the smart matching logic (positional for single groups/stratifiers, ID-based for multiple) correctly handles edge cases like missing IDs, mismatched group counts, and component stratifiers.

• FHIR Resource Mutation Safety: The score copying code uses patterns like if (!group.hasId()) to avoid mutating FHIR resources when checking for IDs. Verify these safe access patterns are consistently applied throughout the copying logic and no inadvertent side effects (like creating empty Coding objects via .getCodingFirstRep()) occur.

• Part 1 Isolation Guarantee: Verify that score copying infrastructure remains truly inactive in Part 1. Check that copyScoresFromDef() is called but does nothing because Def objects have null scores, and old scorers remain the sole source of scores in regular evaluation workflows.

• Def Snapshot Semantics: Review the createSnapshot() methods in GroupDef, StratumDef, and MeasureDef to ensure they create proper immutable copies. Verify that mutable score fields are copied correctly and defensive copying of collections is complete.

• Testing Framework Architecture: Examine the fhir2deftest package design (Fhir2DefUnifiedMeasureTestHandler, FhirVersionTestContext, MeasureServiceAdapter) for potential coupling issues or abstraction leaks that could make multi-version testing fragile.

• Migration Impact on cdr-cr: Consider whether the API changes to IMeasureReportScorer (javadoc deprecation only, no functional changes) adequately guide cdr-cr developers to the new MeasureReportScoringFhirAdapter API without breaking their existing code.

• DefCaptureCallback Integration: Review how DefCaptureCallback is integrated into R4MeasureProcessor and Dstu3MeasureProcessor. Verify callback invocation happens at the correct point (after evaluation, before builder) and the snapshot semantics are correct.

QA Test Suggestions

Setup

• Prepare test data:
  • R4 and DSTU3 Measure resources with proportion scoring
  • Corresponding MeasureReports with population counts but no scores
  • Measures with single and multiple groups
  • Measures with stratifiers (both single-component and multi-component)

Test Cases

• External API Basic Usage (R4): Using MeasureReportScoringFhirAdapter.score(measure, measureReport) with an R4 proportion measure, verify:

  • Scores are correctly calculated and written to the MeasureReport
  • Expected score values match manual calculations (e.g., 75/100 = 0.75)
  • Original population counts remain unchanged

• External API Basic Usage (DSTU3): Repeat the R4 test with DSTU3 resources to verify version detection and routing work correctly.

• External API Version Mismatch Detection: Attempt to score a MeasureReport with a Measure of a different FHIR version (e.g., R4 Measure with DSTU3 MeasureReport). Verify appropriate exception is thrown with clear error message.

• External API Null Input Handling: Test MeasureReportScoringFhirAdapter.score() with null Measure and null MeasureReport inputs. Verify appropriate exceptions with clear messages.

• Regular Evaluation Workflow Unchanged: Run existing measure evaluation tests (e.g., $evaluate-measure operation) and verify:

  • All existing tests pass without modification
  • Scores are still calculated correctly by old scorers
  • No performance regression

• Multiple Groups Score Copying: Create a measure with multiple groups, evaluate it (or create a pre-populated MeasureReport), and verify scores are correctly matched to groups by ID.

• Stratified Measure Score Copying: Create a measure with stratifiers, evaluate it, and verify:

  • Group-level scores are correct
  • Stratum-level scores are correct (once Part 2 activates scoring)
  • Stratifier matching works for both positional (single stratifier) and ID-based (multiple stratifiers) cases

• Component Stratifier Handling: Test measures with multi-component stratifiers (e.g., gender + age group) to verify the matching logic correctly identifies strata by value combinations.

• Def Capture Callback Integration: If tests use MeasureEvaluationOptions.defCaptureCallback, verify:

  • Callback receives a complete MeasureDef snapshot after evaluation
  • Callback can be used to make assertions about evaluation state
  • Callback does not interfere with normal evaluation flow

• COHORT and COMPOSITE Measure Scoring: Test measures with COHORT and COMPOSITE scoring types using the external API. Verify appropriate handling (null scores per FHIR spec, or specific behavior if implemented).

• Improvement Notation Application: Test measures with "decrease" improvement notation and verify scores are correctly inverted at the group level (once Part 2 activates).

[github-actions]

Formatting check succeeded!

[codecov]

Codecov Report

❌ Patch coverage is 60.94183% with 141 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.53%. Comparing base (0f85487) to head (e66cce2).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
...ir/cr/measure/dstu3/Dstu3MeasureReportBuilder.java	24.13%	41 Missing and 3 partials ⚠️
...cqf/fhir/cr/measure/r4/R4MeasureReportBuilder.java	61.17%	14 Missing and 19 partials ⚠️
...e/common/Dstu3MeasureReportScoringFhirAdapter.java	58.92%	19 Missing and 4 partials ⚠️
...sure/common/R4MeasureReportScoringFhirAdapter.java	58.92%	19 Missing and 4 partials ⚠️
...asure/common/IMeasureReportScoringFhirAdapter.java	66.66%	2 Missing and 1 partial ⚠️
...easure/common/MeasureReportScoringFhirAdapter.java	85.71%	2 Missing and 1 partial ⚠️
...opencds/cqf/fhir/cr/measure/common/StratumDef.java	66.66%	3 Missing ⚠️
...ncds/cqf/fhir/cr/measure/common/StratifierDef.java	77.77%	1 Missing and 1 partial ⚠️
...cds/cqf/fhir/cr/measure/r4/R4MeasureProcessor.java	50.00%	1 Missing and 1 partial ⚠️
...s/cqf/fhir/cr/measure/common/MeasureDefScorer.java	50.00%	1 Missing ⚠️
... and 4 more

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #859      +/-   ##
============================================
- Coverage     73.68%   73.53%   -0.15%     
  Complexity      277      277              
============================================
  Files           576      580       +4     
  Lines         27159    27513     +354     
  Branches       3459     3518      +59     
============================================
+ Hits          20011    20233     +222     
- Misses         5432     5522      +90     
- Partials       1716     1758      +42     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.