babelfhir-ts 1.5.19 → 1.5.21

package/out/src/generator/emitters/validator/validatorRuntime.js

@@ -0,0 +1,279 @@
+/**
+ * The runtime module every generated package emits as ValidatorOptions.ts.
+ *
+ * Kept apart from the emitter that orchestrates validate() so the emitted source
+ * can be read as source, rather than as a template buried in control flow.
+ */
+/**
+ * Runtime helpers every generated validator may import from ValidatorOptions.
+ * Single source of truth for the emitted import list.
+ */
+export const HELPER_NAMES = ['at', 'arr', 'node', 'elements', 'elementsAt', 'coding', 'codings', 'asResource', 'refsAt'];
+/**
+ * Returns the content of ValidatorOptions.ts — the shared runtime options type
+ * plus the element-probing helpers that every generated validateX() imports.
+ *
+ * The helpers exist so validators can read arbitrary child elements off an
+ * open-world FHIR resource *without* widening to `any`. `any` would disable
+ * checking for every downstream access, which contradicts the type safety this
+ * generator promises; `at()`/`arr()` return `unknown`, so the emitted code must
+ * still narrow before it can do anything with a value.
+ */
+export function generateValidatorOptionsContent() {
+    return `/** Runtime options for generated FHIR validators. */
+export interface ValidatorOptions {
+  /** Terminology server URL for memberOf() evaluation (e.g. "https://tx.fhir.org/r4"). */
+  terminologyUrl?: string;
+  /** FHIR server URL for resolve() evaluation (e.g. "https://hapi.fhir.org/baseR4"). */
+  fhirServerUrl?: string;
+  /** HTTP headers keyed by server URL — used for auth with terminology or FHIR servers. */
+  httpHeaders?: Record<string, string>;
+  /** AbortSignal for cancelling long-running async evaluations. */
+  signal?: AbortSignal;
+  /** Debug tracing callback — invoked for every FHIRPath trace() call. */
+  traceFn?: (value: unknown, label: string) => void;
+  /**
+   * Resolution map for references, keyed by both fullUrl and \`Type/id\`, valued by the
+   * resourceType each key resolves to.
+   *
+   * A Bundle validator populates this for the resources it contains and passes it to
+   * the validators it delegates to, which is what lets a profile check its own
+   * reference target types. Absent it, target types are not checked at all — matching
+   * the reference validator, which reports a wrong target only when it can resolve
+   * the reference, and stays silent on a dangling one even when the type is spelled
+   * out in the reference string.
+   */
+  bundleEntries?: Readonly<Record<string, string>>;
+}
+
+/** Property bag view of a FHIR element. Reads yield \`unknown\`, never \`any\`. */
+export type FhirNode = { readonly [key: string]: unknown };
+
+/**
+ * View an arbitrary value as a property bag, for key enumeration
+ * (\`Object.entries(node(x))\`) and repeated child reads.
+ *
+ * Non-objects become \`{}\` so callers never need a null check.
+ */
+export function node(value: unknown): FhirNode {
+  return typeof value === 'object' && value !== null ? (value as FhirNode) : {};
+}
+
+/**
+ * Read a (possibly nested) child element off an arbitrary FHIR value.
+ *
+ * Returns \`undefined\` as soon as the path leaves an object, so it is safe on
+ * absent, null, primitive and array-valued intermediates alike. This is the one
+ * place the untyped boundary is crossed, replacing a cast at every call site.
+ *
+ * @example at(resource, 'channel', 'payload', 'extension')
+ */
+export function at(value: unknown, ...path: readonly string[]): unknown {
+  let current = value;
+  for (const key of path) {
+    if (typeof current !== 'object' || current === null) return undefined;
+    current = (current as FhirNode)[key];
+  }
+  return current;
+}
+
+/**
+ * View an element as an iterable list of children.
+ *
+ * Exactly equivalent to the \`if (Array.isArray(x)) for (const c of x)\` guard it
+ * replaces: non-array values (absent, null, or a scalar) yield no iterations, so
+ * substituting this helper does not change which elements get validated.
+ */
+export function arr(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** A coding as read by the emitted slice, pattern and binding checks. */
+export interface CodingShape {
+  code?: string;
+  system?: string;
+  display?: string;
+  version?: string;
+}
+
+/**
+ * The properties emitted element checks actually read off a FHIR element.
+ *
+ * Deliberately structural and all-optional: slice discriminators match on
+ * \`url\`/\`code\`/\`system\`, pattern checks walk \`coding\`, and choice-type checks
+ * look for \`value*\` keys. Typing the element this way keeps every access checked,
+ * where a \`(item: any)\` callback parameter would switch checking off entirely.
+ */
+export interface ElementShape {
+  /** Codings when the element is itself a CodeableConcept. */
+  coding?: CodingShape[];
+  /**
+   * Everything else reads as \`unknown\`.
+   *
+   * Discriminator properties are deliberately *not* declared with concrete types:
+   * a FHIR element's \`code\` may be a \`code\` primitive on one profile and a
+   * \`CodeableConcept\` on another, so committing to \`string\` would break the
+   * \`.coding\` reads (and vice versa). \`unknown\` still supports \`===\` comparisons
+   * and \`typeof\` narrowing; use \`at()\` / \`codings()\` to go deeper.
+   */
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Like {@link arr} but typed for element inspection, so emitted callbacks need no
+ * parameter annotation and stay type-checked.
+ *
+ * Non-arrays yield no iterations, matching the \`Array.isArray\` guard this
+ * replaces.
+ */
+export function elements(value: unknown): readonly ElementShape[] {
+  return Array.isArray(value) ? (value as ElementShape[]) : [];
+}
+
+/**
+ * Collect every element sitting at a property path, flattening arrays at each hop.
+ *
+ * One path therefore covers both single and repeating elements
+ * (Composition.author is 1..*, Composition.subject 0..1) and any mix of the two,
+ * which is what \`at()\` cannot do — it stops the moment the path meets an array.
+ * Absent and null intermediates simply contribute nothing.
+ */
+export function elementsAt(value: unknown, path: readonly string[]): unknown[] {
+  let current: unknown[] = [value];
+  for (const key of path) {
+    const next: unknown[] = [];
+    for (const item of current) {
+      const child = at(item, key);
+      if (Array.isArray(child)) next.push(...child);
+      else if (child !== undefined && child !== null) next.push(child);
+    }
+    current = next;
+  }
+  return current;
+}
+
+/**
+ * Collect the literal references found at a property path.
+ *
+ * Only string \`reference\` values are returned; a Reference carrying just an
+ * identifier names no target.
+ */
+export function refsAt(value: unknown, path: readonly string[]): string[] {
+  const found: string[] = [];
+  for (const item of elementsAt(value, path)) {
+    const reference = at(item, 'reference');
+    if (typeof reference === 'string') found.push(reference);
+  }
+  return found;
+}
+
+/**
+ * Read the coded properties an element carries *itself*, as opposed to
+ * {@link codings} which walks into a CodeableConcept's \`.coding\`.
+ *
+ * This is the shape binding checks need for elements typed \`Coding\` or
+ * \`Quantity\`: both expose \`code\`/\`system\` directly. Values that are not strings
+ * are dropped rather than asserted through, so the result is genuinely
+ * \`string | undefined\` and callers can concatenate and compare it without a cast.
+ * A malformed non-string code is reported by the structural type checks instead.
+ */
+export function coding(value: unknown): CodingShape {
+  const source = node(value);
+  const result: CodingShape = {};
+  if (typeof source.code === 'string') result.code = source.code;
+  if (typeof source.system === 'string') result.system = source.system;
+  if (typeof source.display === 'string') result.display = source.display;
+  if (typeof source.version === 'string') result.version = source.version;
+  return result;
+}
+
+/**
+ * View a value as a list of codings.
+ *
+ * Accepts either a CodeableConcept (reads \`.coding\`) or an already-bare array of
+ * Codings, which is what slice discriminators need since the same discriminator
+ * path can be typed either way across profiles. Anything else yields \`[]\`.
+ */
+export function codings(value: unknown): readonly CodingShape[] {
+  if (Array.isArray(value)) return value as CodingShape[];
+  const nested = at(value, 'coding');
+  if (Array.isArray(nested)) return nested as CodingShape[];
+  // A lone Coding. Elements typed Coding 0..1 are neither an array nor a
+  // CodeableConcept — AuditEvent.entity.type in R4 is the common case — and used
+  // to fall through to [], so every slice discriminated on one matched nothing.
+  // That silently disabled the whole within-slice block: the IHE audit profiles
+  // reported "No elements matched required slice" while their max/min child
+  // constraints were never evaluated at all.
+  if (value !== null && typeof value === 'object') {
+    const lone = value as CodingShape;
+    if (lone.system !== undefined || lone.code !== undefined) return [lone];
+  }
+  return [];
+}
+
+/**
+ * Hand an untyped element to a validator expecting a concrete profile type.
+ *
+ * Cross-profile delegation reaches its target through \`at()\`, which yields
+ * \`unknown\`; the callee wants e.g. \`USCorePatient\`. \`T\` is inferred from the
+ * parameter position, so the conversion needs no type import and no
+ * \`Parameters<typeof validateX>[0]\` — the latter breaks outright in packages that
+ * define a FHIR resource named \`Parameters\`, which shadows the utility type, and
+ * it rejects array-valued fields whose element type is the delegate's.
+ *
+ * Widening happens here once rather than at each call site.
+ */
+export function asResource<T>(value: unknown): T {
+  return value as T;
+}
+
+/**
+ * The XHTML element subset FHIR permits in Narrative.div (R4 Narrative).
+ * Anything outside this set — script, style, object, embed, iframe, form,
+ * input — is what txt-1 exists to reject.
+ */
+const NARRATIVE_ELEMENTS = new Set([
+  'a', 'abbr', 'acronym', 'b', 'bdo', 'big', 'blockquote', 'br', 'caption',
+  'cite', 'code', 'col', 'colgroup', 'dd', 'dfn', 'div', 'dl', 'dt', 'em',
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img', 'li', 'ol', 'p',
+  'pre', 'q', 'samp', 'small', 'span', 'strong', 'sub', 'sup', 'table',
+  'tbody', 'td', 'tfoot', 'th', 'thead', 'tr', 'tt', 'ul', 'var',
+]);
+
+/** Void elements that carry meaning without text content. */
+const NARRATIVE_VOID_ELEMENTS = /<\\s*(?:img|br|hr)\\b/i;
+
+/**
+ * txt-1 / txt-2: the narrative must hold some non-whitespace content and use
+ * only the permitted XHTML subset, with no event-handler attributes.
+ *
+ * fhirpath.js does not implement \`htmlChecks()\`, and an unimplemented function
+ * throws out of the whole evaluation, so every profile carrying txt-1 lost all of
+ * its findings. Supplying the function is what keeps the invariant evaluated.
+ */
+export function narrativeHtmlChecks(values: readonly unknown[]): boolean {
+  for (const value of values) {
+    if (typeof value !== 'string') continue;
+
+    // Only the permitted elements, opening or closing.
+    for (const match of value.matchAll(/<\\s*\\/?\\s*([a-zA-Z][a-zA-Z0-9]*)/g)) {
+      if (!NARRATIVE_ELEMENTS.has(match[1].toLowerCase())) return false;
+    }
+    // No inline event handlers (onclick, onload, …).
+    if (/\\son[a-zA-Z]+\\s*=/.test(value)) return false;
+    // Some non-whitespace content, unless a void element carries it.
+    const text = value.replace(/<[^>]*>/g, '').replace(/&[a-zA-Z#0-9]+;/g, ' ');
+    if (text.trim().length === 0 && !NARRATIVE_VOID_ELEMENTS.test(value)) return false;
+  }
+  return true;
+}
+
+/**
+ * FHIRPath functions fhirpath.js lacks, supplied via its userInvocationTable.
+ * Passed as \`userInvocationTable\` in the evaluation options.
+ */
+export const fhirpathUserFunctions = {
+  htmlChecks: { fn: narrativeHtmlChecks, arity: { 0: [] } },
+};
+`;
+}

package/out/src/generator/emitters/validator/validatorTemplates.js

@@ -1,3 +1,95 @@
+/**
+ * Emit the reference target-type check for one profile.
+ *
+ * Driven by a table rather than a block per element: us-core alone declares ~480
+ * reference elements with restricted targets, and inlining a check each would bloat
+ * the emitted file for no gain.
+ *
+ * The check consults options.bundleEntries and does nothing without it, which is what
+ * matches the reference validator: it reports a wrong target only when the reference
+ * resolves, and stays silent on a dangling `Patient/id-x` even though the type is
+ * spelled out there. Parsing the type out of the string instead reports the cases it
+ * ignores and misses the `urn:uuid:` ones it reports.
+ */
+export function buildReferenceTargetTypeValidation(fields, profileUrlToType) {
+    const resolveTargetType = (url) => {
+        const bare = url.split('|')[0];
+        const lastSegment = bare.split('/').pop() || '';
+        if (/^[A-Z][A-Za-z]+$/.test(lastSegment))
+            return lastSegment;
+        return profileUrlToType?.get(bare) ?? profileUrlToType?.get(url);
+    };
+    const rows = [];
+    const seen = new Set();
+    for (const field of fields) {
+        if (field.sliceName)
+            continue;
+        const rel = (field.name || '').replace(/^[^.]+\./, '');
+        if (!rel || rel.includes('[x]') || seen.has(rel))
+            continue;
+        const targets = (field.typeOptions ?? [])
+            .filter(option => option.code === 'Reference')
+            .flatMap(option => option.targetProfileUrls ?? []);
+        if (targets.length === 0)
+            continue;
+        const resolved = targets.map(resolveTargetType);
+        // An unresolved target, or one permitting any resource, leaves the allowed set
+        // unknown — nothing can be rejected against it.
+        if (resolved.some(type => !type))
+            continue;
+        const allowed = [...new Set(resolved)];
+        if (allowed.includes('Resource') || allowed.includes('DomainResource'))
+            continue;
+        seen.add(rel);
+        rows.push(`    { path: ${JSON.stringify(rel.split('.'))}, allowed: ${JSON.stringify(allowed)} },`);
+    }
+    if (rows.length === 0)
+        return '';
+    return `
+  // Reference target types, checked only where a reference resolves
+  if (options?.bundleEntries) {
+    const _rtTargets: ReadonlyArray<{ path: string[]; allowed: string[] }> = [
+${rows.join('\n')}
+    ];
+    for (const _rt of _rtTargets) {
+      for (const _rtRef of refsAt(resource, _rt.path)) {
+        const _rtFound = options.bundleEntries[_rtRef];
+        if (_rtFound !== undefined && !_rt.allowed.includes(_rtFound)) {
+          errors.push("Invalid Resource target type. Found " + _rtFound + ", but expected one of ([" + _rt.allowed.join(', ') + "])");
+        }
+      }
+    }
+  }
+`;
+}
+/**
+ * Emit the resolution map a Bundle passes to the validators it delegates to.
+ *
+ * Keyed by fullUrl and by \`Type/id\`, since a reference may use either form. Only
+ * Bundles can populate it, so only Bundles emit it.
+ */
+export function buildBundleEntryResolution(baseResourceType) {
+    if (baseResourceType !== 'Bundle') {
+        // Outside a Bundle there is nothing to resolve against, so delegates inherit the
+        // caller's options unchanged — including any map the caller was itself given.
+        return `
+  const _delegateOptions = options;
+`;
+    }
+    return `
+  // Resolution map for delegated validators: fullUrl and Type/id → resourceType
+  const _bundleEntries: Record<string, string> = {};
+  for (const _be of arr(at(resource, 'entry'))) {
+    const _beType = at(_be, 'resource', 'resourceType');
+    if (typeof _beType !== 'string') continue;
+    const _beFullUrl = at(_be, 'fullUrl');
+    if (typeof _beFullUrl === 'string') _bundleEntries[_beFullUrl] = _beType;
+    const _beId = at(_be, 'resource', 'id');
+    if (typeof _beId === 'string') _bundleEntries[_beType + '/' + _beId] = _beType;
+  }
+  const _delegateOptions = { ...options, bundleEntries: _bundleEntries };
+`;
+}
 /**
  * Generate Bundle reference resolution validation code.
  * Only applies to Bundle profiles — verifies all references within entries are resolvable.
@@ -93,6 +185,45 @@ export function generateContainedRefValidation(baseResourceType) {
       }
     };
     _checkContainedRef(_res);
+
+    // dom-3: every contained resource must be referenced from the containing
+    // resource. Evaluated here rather than through its FHIRPath form: that
+    // expression builds the fragment as '#'+id, so an absent id makes the whole
+    // predicate empty and the invariant silently passes, where HL7 reports the
+    // resource as unreferenced (its message names it 'null').
+    if (Array.isArray(_res.contained) && _res.contained.length > 0) {
+      const _fragments = new Set<string>();
+      const _collectFragments = (obj: unknown): void => {
+        if (!obj || typeof obj !== 'object') return;
+        if (Array.isArray(obj)) { obj.forEach(_collectFragments); return; }
+        for (const [_k, _v] of Object.entries(obj as Record<string, unknown>)) {
+          if (_k === 'reference' && typeof _v === 'string' && _v.startsWith('#')) {
+            _fragments.add(_v.substring(1));
+          } else {
+            _collectFragments(_v);
+          }
+        }
+      };
+      _collectFragments(_res);
+      // The invariant is satisfied either way round, so a contained resource that
+      // points back at its container with the bare '#' reference also passes.
+      const _refersToContainer = (obj: unknown): boolean => {
+        if (!obj || typeof obj !== 'object') return false;
+        if (Array.isArray(obj)) return obj.some(_refersToContainer);
+        for (const [_k, _v] of Object.entries(obj as Record<string, unknown>)) {
+          if (_k === 'reference' && _v === '#') return true;
+          if (_refersToContainer(_v)) return true;
+        }
+        return false;
+      };
+      for (const _c of _res.contained as Array<Record<string, unknown>>) {
+        const _cid = _c && typeof _c.id === 'string' ? _c.id : undefined;
+        if (_refersToContainer(_c)) continue;
+        if (_cid === undefined || !_fragments.has(_cid)) {
+          errors.push("The contained resource '" + (_cid ?? 'null') + "' is not referenced to from elsewhere in the containing resource nor does it refer to the containing resource (dom-3)");
+        }
+      }
+    }
   }
 `;
 }
@@ -125,6 +256,10 @@ export function generateExtensionStructuralValidation() {
               const e = ext as Record<string, unknown>;
               if (typeof e.url !== 'string' || !e.url) {
                 errors.push('Extension.url is required in order to identify, use and validate the extension');
+              } else if (e.url.includes('|')) {
+                // Extension.url identifies the definition and is not version-pinned;
+                // a '|version' suffix belongs on a canonical reference, not here.
+                errors.push('The extension URL must not contain a version');
               }
               // ext-1: Must have either extensions or value[x], not both
               const hasNestedExt = Array.isArray(e.extension) && e.extension.length > 0;
@@ -147,69 +282,66 @@ export function generateExtensionStructuralValidation() {
   }
 `;
 }
+/** Per-aggregation error text and the predicate that marks a reference unresolvable. */
+const AGGREGATION_RULES = {
+    // A bundled reference resolves only inside a Bundle, so a relative
+    // ResourceType/id reference is unresolvable in standalone validation.
+    bundled: {
+        message: 'Bundle reference not found: ',
+        violates: (ref) => `/^[A-Za-z]+\\//.test(${ref})`,
+    },
+    // A contained reference must be a local #fragment. Fragments that do not
+    // resolve are already reported by generateContainedRefValidation, so this
+    // only catches references that are not contained at all.
+    contained: {
+        message: 'Contained reference not found: ',
+        violates: (ref) => `!${ref}.startsWith('#')`,
+    },
+};
 /**
- * Generate validation for reference fields declared with aggregation=["bundled"].
+ * Generate validation for reference fields whose profile restricts aggregation.
  *
- * The HL7 validator enforces that bundled-aggregation references resolve within
- * a Bundle. When validating a standalone resource (not inside a Bundle) any
- * relative reference (ResourceType/id) on such a field is unresolvable and must
- * be reported as an error to match HL7 parity.
+ * The HL7 validator enforces that such references resolve within the bundle or
+ * resource; when validating a standalone resource, a reference of the wrong form
+ * is unresolvable and must be reported to match HL7 parity.
  *
- * Bundle profiles handle this via {@link generateBundleRefValidation} instead.
+ * Bundle profiles handle the bundled case via {@link generateBundleRefValidation}.
  */
-export function generateBundledAggregationValidation(paths) {
+export function generateAggregationRefValidation(paths) {
     if (paths.length === 0)
         return '';
-    const checks = [];
-    for (const { segments, isArray } of paths) {
-        const _checkRef = (accessor) => `typeof ${accessor}.reference === 'string' && /^[A-Za-z]+\\//.test(${accessor}.reference)`;
-        if (segments.length === 1) {
-            const f = segments[0];
-            if (isArray[0]) {
-                checks.push(`
-    if (Array.isArray(_res.${f})) {
-      for (const _item of _res.${f}) {
-        if (_item && ${_checkRef('_item')}) {
-          errors.push('Bundle reference not found: ' + _item.reference);
-        }
-      }
-    }`);
-            }
-            else {
-                checks.push(`
-    if (_res.${f} && ${_checkRef('_res.' + f)}) {
-      errors.push('Bundle reference not found: ' + _res.${f}.reference);
-    }`);
-            }
+    /**
+     * Emit the descent into `segments`, iterating any array level, then check the
+     * leaf reference. Uses at()/arr() so every hop stays typed as unknown.
+     * Consecutive single-valued segments collapse into one variadic at() call.
+     */
+    const walk = (path, index, expr, pending, indent, id) => {
+        const { segments, isArray, kind } = path;
+        const asArgs = (parts) => parts.map(p => `, '${p}'`).join('');
+        if (index === segments.length) {
+            const { message, violates } = AGGREGATION_RULES[kind];
+            const refVar = `_aggRef${id}`;
+            return `
+${indent}const ${refVar} = at(${expr}${asArgs([...pending, 'reference'])});
+${indent}if (typeof ${refVar} === 'string' && ${violates(refVar)}) {
+${indent}  errors.push('${message}' + ${refVar});
+${indent}}`;
         }
-        else if (segments.length === 2) {
-            const parent = segments[0];
-            const child = segments[1];
-            if (isArray[0]) {
-                checks.push(`
-    if (Array.isArray(_res.${parent})) {
-      for (const _item of _res.${parent}) {
-        if (_item?.${child} && ${_checkRef('_item.' + child)}) {
-          errors.push('Bundle reference not found: ' + _item.${child}.reference);
-        }
-      }
-    }`);
-            }
-            else {
-                checks.push(`
-    if (_res.${parent}?.${child} && ${_checkRef('_res.' + parent + '.' + child)}) {
-      errors.push('Bundle reference not found: ' + _res.${parent}.${child}.reference);
-    }`);
-            }
+        const segment = segments[index];
+        if (isArray[index]) {
+            const itemVar = `_aggItem${id}${index}`;
+            return `
+${indent}for (const ${itemVar} of arr(at(${expr}${asArgs([...pending, segment])}))) {${walk(path, index + 1, itemVar, [], indent + '  ', `${id}${index}`)}
+${indent}}`;
         }
-        // Paths deeper than 2 levels are extremely rare in FHIR profiles
-    }
+        return walk(path, index + 1, expr, [...pending, segment], indent, `${id}${index}`);
+    };
+    const checks = paths.map((path, i) => walk(path, 0, 'resource', [], '    ', String(i)));
     return `
-  // Bundled aggregation: references on fields with aggregation=["bundled"] must be
-  // resolvable within a Bundle. For standalone validation, relative references are errors.
-  {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const _res = resource as unknown as Record<string, any>;${checks.join('')}
+  // Restrictive reference aggregation: a reference on a field limited to
+  // bundled/contained must resolve within the bundle/resource. For standalone
+  // validation, a reference of the wrong form is an error.
+  {${checks.join('')}
   }
 `;
 }