Ensure stratifier validation mandates "string" population basis correctly

[lukedegruchy]

Summary

This MR fixes DQM-692, where $evaluate-measure failed for Measures using a lowercase "string" population basis with criteria-based stratifiers. The root cause was a case-sensitive comparison between CQL result type names ("String") and FHIR population basis codes ("string"). The fix also refactors the population basis validation architecture to be FHIR-version-agnostic and improves error messages for invalid population basis codes.

1. Bug fix: Added explicit handling for "string" (and "boolean") primitive FHIR type codes in doesBasisMatchResource, ensuring lowercase FHIR codes match their uppercase Java class counterparts while rejecting invalid uppercase variants like "String".
2. Validation improvement: Replaced the assert-only population basis code validation in R4MeasureDefBuilder with proper InvalidRequestException messages that include the measure URL, suggest the correct code for casing errors, and link to the FHIR spec for unrecognized codes.
3. Architecture refactor: Moved all version-agnostic validation logic from R4PopulationBasisValidator into PopulationBasisValidator as default interface methods. R4 now only supplies type mappings; DSTU3 remains a documented no-op since DSTU3 has no populationBasis extension.
4. Improved value stratifier error messages with stratifier-type-specific wording (DQM-691) — "Value" stratifiers (boolean basis) get a message that omits the irrelevant population basis and lists allowed categorical types. "Non Subject Value" stratifiers (resource basis) include the population basis for context. Both messages suggest using a CRITERIA-based stratifier as an alternative.

Code Review Suggestions

• Verify that the PopulationBasisValidator default methods (especially resolveResourceType) being default rather than private is acceptable from an API surface perspective — they are callable by any implementor, not just internally.
• The doesBasisMatchResource logic now gates Boolean.class and String.class through explicit constant checks and rejects them from the generic getSimpleName() path. Confirm there are no other CQL/FHIR primitive types (e.g. Integer, Decimal) that could hit the same case-sensitivity issue with their FHIR codes.
• The ListResource special case that previously existed in extractResourceType was removed during the refactor. If any existing Measures use "ListResource" as a population basis code, this would be a behavioral change. Verify whether this code path was ever exercised in production.
• The findCaseInsensitiveMatch in R4MeasureDefBuilder iterates all FHIRAllTypes enum values. Confirm this is acceptable for the error path (it only runs on invalid input) and that no enum values have null toCode() results that could cause issues despite the null check.
• The value stratifier error message includes List.copyOf(allowedStratifierValueTypes()) — since this comes from a HashSet, the ordering in the error message is non-deterministic. Verify this is acceptable for log-based alerting or automated error parsing downstream.

QA Test Suggestions

Setup

Load a FHIR R4 server with:

• An Organization resource
• 2+ Patient resources (with different genders, e.g. male and female)
• Encounter resources for each patient
• A CQL Library that includes a string-returning stratifier expression (e.g. if Patient.gender = 'male' then 'male' else 'female')

Test Cases

• Lowercase "string" basis with criteria stratifier: Create a Ratio Measure with populationBasis: "string" and a stratifier.criteria expression returning String values. Run $evaluate-measure with multiple patients. Expect: 200 OK with a COMPLETE MeasureReport containing stratified results.
• Uppercase "String" basis (invalid): Create the same Measure but with populationBasis: "String". Run $evaluate-measure. Expect: an error response containing "has an invalid population basis of 'String'. Did you mean to enter 'string' instead?".
• Nonsensical basis code: Create a Measure with populationBasis: "Foo". Run $evaluate-measure. Expect: an error response containing "has an invalid population basis of 'Foo'" and a reference to the FHIR spec URL.
• Existing Encounter basis measures: Run $evaluate-measure on an existing Encounter-basis Measure with criteria and value stratifiers. Expect: no regression, same results as before.
• Boolean basis measures: Run $evaluate-measure on an existing boolean-basis Measure with stratifiers. Expect: no regression, same results as before.
• Group-level population basis: Create a Measure with populationBasis set at the group level (on Measure.group rather than Measure) using an invalid code. Expect: the same improved error message including the measure URL.

[github-actions]

Formatting check succeeded!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud