Fix error handling for non-subject value and value stratifiers

[lukedegruchy]

Summary

PR #913 (issue #909) added support for non-subject value stratifiers to use both CQL functions and scalar expressions, but left gaps in error handling: expressions that don't exist in the CQL library produced raw CqlException stack traces, and expressions returning invalid types (e.g. a list of FHIR resources instead of a scalar) were silently accepted, producing nonsense strata. This MR closes those gaps with proper validation and domain-specific exceptions.

1. Wrap unresolvable stratifier expressions in StratifierExpressionNotFoundException: In FunctionEvaluationHandler.processNonSubValueStratifier(), the call to isExpressionFunctionRef() now catches CqlException and re-throws as a contextual StratifierExpressionNotFoundException that includes the expression name and measure URL.
2. Validate non-function expression result types against allowed stratifier types: PopulationBasisValidator.validateExpressionResultType() now throws InvalidStratifierExpressionTypeException (instead of InvalidRequestException) for value stratifier expressions whose result types are not in the allowed set (e.g. Encounter instead of String/Code/Integer). This applies to both VALUE and NON_SUBJECT_VALUE stratifier types.
3. Compact and actionable error messages: Value stratifier error messages now deduplicate result types, include the population basis for non-subject value stratifiers, and state what was expected ("Expected a scalar type" or "Expected a scalar or scalar-returning function").
4. New domain exceptions follow architecture decision: Both StratifierExpressionNotFoundException and InvalidStratifierExpressionTypeException extend RuntimeException directly, not HAPI FHIR REST exceptions, per the project's architecture decision.
5. 7 new integration tests and 6 new Measure JSON fixtures covering: non-existent expression, non-scalar/non-function expression (resource list), valid scalar only, valid function only, function with wrong parameter type, and boolean-basis VALUE stratifier with a resource list expression.

Code Review Suggestions

• Verify that StratifierExpressionNotFoundException and InvalidStratifierExpressionTypeException are caught by the catch-all Exception handlers in MeasureEvaluationResultHandler and routed to contained OperationOutcome (not thrown to the caller). The tests assert OperationOutcome, but confirm the catch-all behavior is intentional for these specific exception types vs. failing fast.
• The prettyDistinctClassNames() helper deduplicates by Class::getSimpleName. Confirm there are no cases where two distinct classes share a simple name (e.g. org.hl7.fhir.r4.model.Encounter vs a hypothetical CQL Encounter type) that would lose information in the error message.
• The multi-catch InvalidRequestException | InvalidStratifierExpressionTypeException in R4PopulationBasisValidatorTest.validateStratifierBasisTypeErrorPath() is a test-only convenience. Confirm the production code paths throw the correct specific exception for each stratifier type: InvalidRequestException for criteria-based, InvalidStratifierExpressionTypeException for value/non-subject-value.
• The InvalidStratifierExpressionTypeException has two constructors: a String message form and a structured form with 5 parameters. Only the String message form is used in production code. Confirm whether the structured constructor should be kept or removed.

QA Test Suggestions

Setup

Evaluate a FHIR R4 Measure with $evaluate-measure using the test data from the MeasureTest/input directory (LibrarySimple CQL library, patient-9 with 2 encounters). All tests use cohort scoring.

• Non-existent stratifier expression: Evaluate a Measure with a non-subject value stratifier component pointing to an expression that does not exist in the CQL library (e.g. "This Expression Does Not Exist"). Verify the MeasureReport contains a contained OperationOutcome referencing both the bad expression name and the measure URL, and the report has ERROR status.
• Resource list expression as non-subject value stratifier: Evaluate a Measure with Encounter population basis and a stratifier component pointing to a CQL define that returns [Encounter] E (a list of resources, not a scalar). Verify the MeasureReport contains a contained OperationOutcome with a message indicating "Expected a scalar or scalar-returning function".
• Resource list expression as boolean-basis VALUE stratifier: Same as above but with boolean/subject population basis. Verify the OperationOutcome message says "Expected a scalar type" (without mentioning function, since VALUE stratifiers don't support functions).
• Valid scalar stratifier: Evaluate a Measure with Encounter population basis and a stratifier component pointing to a CQL define returning a String (e.g. "Patient Age Bracket" returning "21--41"). Verify the MeasureReport completes successfully with the expected stratum values.
• Valid function stratifier: Evaluate a Measure with Encounter population basis and a stratifier component pointing to a CQL define function that takes an Encounter and returns a String (e.g. "Encounter Status Stratifier"). Verify the MeasureReport completes with per-encounter strata (e.g. "finished", "in-progress").
• Function with wrong parameter type: Evaluate a Measure with Encounter population basis and a stratifier component pointing to a CQL function whose parameter type doesn't match the population basis (e.g. a function taking Interval<DateTime> instead of Encounter). Verify the MeasureReport contains a contained OperationOutcome referencing "CQL Exception while evaluating function".
• Regression: existing stratifier tests: Run the full MeasureStratifierTest suite and verify no regressions in existing cohort, proportion, and ratio stratifier scenarios (criteria-based, value-based, multi-component).

[github-actions]

Formatting check succeeded!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
86.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud