feat(validator): FHIR NPM package pipeline + validation completeness hardening

[sandhums]

Summary

Two layers of work on helios-fhir-validator (plus its REST wiring):

1. FHIR NPM/IG package materialization — a curated on-disk package cache, offline package.json dependency resolution, and StructureDefinition → FHIR Schema layer conversion, wired into ValidationService as CompositeResolver overlays.
2. A completeness/hardening pass over the validation engine itself, driven by a four-axis audit (Helios style, FHIR-version correctness, idiomatic Rust, and coverage of the FHIR validation dimensions).

No second validation engine: packages compile into the same cooperative schema-set walk introduced in #232.

1. Package pipeline

• Cache + resolution (src/packages/): curated cache layout, ensure_from_path accepting both .tgz archives and IG-publisher output directories, offline dependency resolution from package.json, and materialization into SchemaRegistry layers (profiles only; abstract definitions skipped).
• Configurable sources: HFS_FHIR_PACKAGE_CACHE / HFS_FHIR_PACKAGES (path, publisher output dir, or URL). Fail-loud if a configured package cannot load — no silent empty overlay.
• FHIR-version correctness:
  • resolve_packages rejects packages whose manifest fhirVersions is incompatible with the target version (packages/version.rs handles full versions 4.0.1, MIME-style 4.0, and R4-style labels).
  • materialize_package_layers_by_version partitions layers per FhirVersion; ValidationService keys its package layers by version so an R5 request never sees R4 overlays.
• Sample package fixture: a bundled, anonymized sample.tgz (with pack.sh and source JSON) exercises cache → resolve → materialize → validate end to end without network access.

2. Engine completeness

Slicing

• All five discriminator types compiled and evaluated: value/pattern (partial-match patterns, multi-discriminator), type, profile, binding, and exists (expected presence read from the slice differential: min >= 1 ⇒ present, max = 0 ⇒ absent).
• Restricted-FHIRPath discriminator paths parsed properly (paren-aware — extension urls contain dots): dotted selections, $this, extension('url') (compiled to a dedicated containment matcher, incl. nested complex-extension chains), and ofType(Type) / choice-aware navigation (value resolves to valueQuantity). resolve() remains unsupported and degrades gracefully (slice kept, matcher and min dropped, conversion warning).
• Reslicing: parent/child slice names scope the child to the parent's match; sliceIsConstraining slices inherit matchers instead of matching nothing.
• Rules coverage (open/closed/openAtEnd/ordered/@default, prohibited max: 0 slices) preserved.

Value-domain keywords

• maxLength, minValue[x], maxValue[x] carried through the converter and enforced in the walk (ordered comparison for numbers and date/time strings), with new error kinds max-length / min-value / max-value.

References and bindings

• refers enforcement (type.targetProfile): flag-gated via ValidationOptions::enforce_refers (off by default for conformance-suite parity); rejects references whose target type is not among the allowed profiles' types (reference-target).
• extensible bindings: opt-in via EffectHandlers::check_extensible_bindings, emitting warning-severity issues (required bindings remain errors).

QuestionnaireResponse validation

• New questionnaire module validating a QR against its Questionnaire: required items, answer type vs item type, answerOption / answerValueSet membership (via the terminology provider), enableWhen gating, and unknown linkIds.
• REST wiring via a QuestionnaireLookup trait on ValidationService.
• #Pending - REST-side QuestionnaireLookup path, needs ValidationService plumbing in the rest crate's test suite

3. REST / service wiring (crates/rest/src/validation.rs)

• Package layers keyed per FhirVersion, loaded through the version-partitioned materializer.
• TerminologyMode (Off / Embedded / Remote) replaces the bare optional provider.
• New error kinds mapped to OperationOutcome issue types.

4. Style / idiomatic Rust

• PackageError migrated to thiserror; crate README.md + manifest readme key; lib.rs docs restructured with an honest "current limitations" section; clippy-clean across the crate.

Intentionally out of scope

• Live npm registry client / network fetch on $validate (cache is preseeded or fed via ensure_from_path).
• Terminology (CodeSystem/ValueSet) packaging — remains HTS.
• Full ValueSet expansion for binding discriminators naming a canonical URL.
• resolve() discriminator paths and resolve-ref matchers (need an instance graph).
• mustHaveValue/valueAlternatives (R5) and computable mustSupport checking.

Tests

• Upstream FHIR Schema conformance suite unchanged and passing (exact ordered error matching).

• New extended fixtures: value_keywords, reslicing, slice_matchers (type/profile/binding/extension-sugar), exists_extension_matchers (exists + extension-path matchers, nested chains).

• New suites: refers_enforcement.rs, extensible_bindings.rs, packages_tests.rs additions (fhirVersions rejection, sample.tgz end-to-end), non-ignored R4 pack smoke test.

• Converter goldens for every new mapping (slice-discriminators, binding-slice, exists-extension-discriminators).

• Questionnaire unit tests cover required items, answer-type mismatch, unknown linkIds, enableWhen gating (incl. enableBehavior: any and a warning for answered-but-disabled items), answerOption membership, and answerValueSet membership via a stub terminology provider (skipped, not failed, without a provider).

• cargo test -p helios-fhir-validator — all suites green

• cargo clippy -p helios-fhir-validator --all-targets — no warnings

• cargo check -p helios-rest

Made with Cursor