fhirsmith 0.11.2 → 0.13.0

package/tx/xml/xml-base.js

@@ -486,12 +486,32 @@ class FhirXmlBase {
 
   /**
    * Escape special characters for XML
+   *
+   * XML 1.0 cannot represent the C0 control characters at all - not literally,
+   * and not as numeric character references either - so a value carrying one
+   * cannot be serialised as XML by any means. Tab, line feed and carriage
+   * return are the three exceptions; DEL (U+007F) is legal in XML 1.0 and is
+   * left alone.
+   *
+   * Rather than emit a document no conformant parser will read, this rejects
+   * the value. Anything reaching here with a control character in it came from
+   * outside (a remote API, an imported file) and should have been caught at
+   * the boundary.
+   *
    * @param {*} value - Value to escape
    * @returns {string}
+   * @throws {Error} if the value contains a character XML cannot carry
    */
   static escapeXml(value) {
     if (value === null || value === undefined) return '';
-    return String(value)
+    const str = String(value);
+    // eslint-disable-next-line no-control-regex
+    const illegal = /[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.exec(str);
+    if (illegal) {
+      const code = illegal[0].charCodeAt(0).toString(16).toUpperCase().padStart(4, '0');
+      throw new Error(`Cannot serialise this content as XML: it contains U+${code} at offset ${illegal.index}, a control character XML does not allow`);
+    }
+    return str
       .replace(/&/g, '&')
       .replace(/</g, '&lt;')
       .replace(/>/g, '&gt;')
@@ -632,122 +652,289 @@ class FhirXmlBase {
  * Simple XML parser for FHIR resources
  * Parses XML string into {name, attributes, children} structure
  */
+/**
+ * A deliberately small XML reader for FHIR resources. It is not a general XML processor: FHIR
+ * XML has no DTDs, no entities beyond the five predefined ones, and carries its values in
+ * attributes, so the grammar it needs is tiny.
+ *
+ * What it does have to be is total. Every input either produces a tree or throws - it must never
+ * loop, and it must never run away with memory or stack. This matters more than it looks: the
+ * server accepts application/fhir+xml on every endpoint, parsing is synchronous, and node is
+ * single threaded, so a parser that fails to terminate does not hang one request, it stops the
+ * process answering anything at all. The cooperative deadCheck cannot help - it needs an await
+ * point, and there isn't one inside a parse.
+ *
+ * Two rules keep that promise, and both are enforced rather than assumed:
+ *
+ *  - no scan may fail silently. Every search for a delimiter goes through #seek(), which throws
+ *    if the delimiter is absent. The bug this replaces was an indexOf() returning -1 whose result
+ *    was assigned to the cursor, sending it back to zero and restarting the parse forever.
+ *  - every loop must consume input. Each iteration asserts the cursor moved forward, so a future
+ *    edit that forgets to advance it fails loudly on the first malformed document instead of
+ *    spinning.
+ */
+
+// FHIR resources nest a couple of dozen deep; narrative markup can go further. This is well
+// clear of anything real and well under the call stack, so deep input is a clean error rather
+// than a RangeError from the recursion in _parseElement.
+const MAX_ELEMENT_DEPTH = 1000;
+
 class FhirXmlParser {
+  /**
+   * @param {string} xml - the document to read
+   */
   constructor(xml) {
+    if (typeof xml !== 'string') {
+      throw new Error('XML input must be a string');
+    }
     this.xml = xml;
     this.pos = 0;
+    this.depth = 0;
   }
 
+  /**
+   * @returns {{name: string, attributes: Object, children: Array}} the root element
+   */
   parse() {
-    this._skipDeclaration();
-    this._skipWhitespace();
-    return this._parseElement();
+    this.#parseProlog();
+    const root = this.#parseElement();
+    return root;
   }
 
-  _skipDeclaration() {
-    this._skipWhitespace();
-    if (this.xml.substring(this.pos, this.pos + 5) === '<?xml') {
-      const end = this.xml.indexOf('?>', this.pos);
-      if (end !== -1) {
-        this.pos = end + 2;
-      }
+  // ========== scanning primitives ==========
+
+  /**
+   * Throw with the position, which is what makes a malformed document diagnosable
+   * @param {string} message
+   */
+  #fail(message) {
+    throw new Error(`${message} at position ${this.pos}`);
+  }
+
+  /**
+   * indexOf that cannot return -1. Every delimiter search goes through here
+   * @param {string} needle
+   * @param {string} what - what we were looking for, for the error message
+   * @returns {number}
+   */
+  #seek(needle, what) {
+    const at = this.xml.indexOf(needle, this.pos);
+    if (at === -1) {
+      this.#fail(`Unterminated ${what}: no '${needle}' found`);
     }
+    return at;
   }
 
-  _skipWhitespace() {
-    while (this.pos < this.xml.length && /\s/.test(this.xml[this.pos])) {
-      this.pos++;
+  /**
+   * Move the cursor, checking it actually moved forward. Called at the end of every loop body
+   * @param {number} was - the cursor before the iteration
+   */
+  #mustHaveAdvanced(was) {
+    if (this.pos <= was) {
+      // not reachable by any input we know of - it means a code path forgot to consume
+      this.#fail('Internal error: the XML parser stopped making progress');
     }
   }
 
-  _parseElement() {
-    this._skipWhitespace();
+  #atEnd() {
+    return this.pos >= this.xml.length;
+  }
 
-    if (this.xml[this.pos] !== '<') {
-      throw new Error(`Expected '<' at position ${this.pos}`);
+  #skipWhitespace() {
+    while (this.pos < this.xml.length && /\s/.test(this.xml[this.pos])) {
+      this.pos++;
     }
-    this.pos++; // Skip '<'
+  }
 
-    // Parse element name
-    const nameEnd = this.xml.substring(this.pos).search(/[\s/>]/);
-    const name = this.xml.substring(this.pos, this.pos + nameEnd);
-    this.pos += nameEnd;
+  #startsWith(text) {
+    return this.xml.startsWith(text, this.pos);
+  }
 
-    // Parse attributes
-    const attributes = {};
-    this._skipWhitespace();
+  // ========== document structure ==========
 
-    while (this.pos < this.xml.length && this.xml[this.pos] !== '>' && this.xml[this.pos] !== '/') {
-      const attr = this._parseAttribute();
-      if (attr) {
-        attributes[attr.name] = attr.value;
+  /**
+   * The XML declaration, and any comments or processing instructions before the root element.
+   * A DOCTYPE is refused outright: FHIR XML has no DTD, and accepting one is how a parser ends
+   * up doing entity expansion on someone else's behalf.
+   */
+  #parseProlog() {
+    this.#skipWhitespace();
+    if (this.#startsWith('<?xml')) {
+      this.pos = this.#seek('?>', 'XML declaration') + 2;
+    }
+    for (;;) {
+      const was = this.pos;
+      this.#skipWhitespace();
+      if (this.#startsWith('<!--')) {
+        this.#skipComment();
+      } else if (this.#startsWith('<!DOCTYPE') || this.#startsWith('<!')) {
+        this.#fail('Document type declarations are not allowed in FHIR XML');
+      } else if (this.#startsWith('<?')) {
+        this.pos = this.#seek('?>', 'processing instruction') + 2;
+      } else {
+        return;
       }
-      this._skipWhitespace();
+      this.#mustHaveAdvanced(was);
     }
+  }
 
-    const children = [];
+  #skipComment() {
+    this.pos = this.#seek('-->', 'comment') + 3;
+  }
 
-    // Self-closing tag
-    if (this.xml[this.pos] === '/') {
-      this.pos += 2; // Skip '/>'
-      return { name, attributes, children };
+  /**
+   * One element and everything inside it.
+   * @returns {{name: string, attributes: Object, children: Array}}
+   */
+  #parseElement() {
+    if (++this.depth > MAX_ELEMENT_DEPTH) {
+      this.depth--;
+      this.#fail(`XML is nested more than ${MAX_ELEMENT_DEPTH} elements deep`);
+    }
+    try {
+      return this.#parseElementInner();
+    } finally {
+      this.depth--;
     }
+  }
 
-    this.pos++; // Skip '>'
+  #parseElementInner() {
+    this.#skipWhitespace();
+    if (this.#atEnd() || this.xml[this.pos] !== '<') {
+      this.#fail("Expected '<'");
+    }
+    this.pos++;
 
-    // Parse children
-    while (this.pos < this.xml.length) {
-      this._skipWhitespace();
+    const name = this.#parseName('element name');
+    const attributes = this.#parseAttributes(name);
 
-      if (this.xml.substring(this.pos, this.pos + 2) === '</') {
-        // Closing tag
-        const closeEnd = this.xml.indexOf('>', this.pos);
-        this.pos = closeEnd + 1;
-        break;
-      }
+    if (this.#startsWith('/>')) {
+      this.pos += 2;
+      return { name, attributes, children: [] };
+    }
+    if (this.#atEnd() || this.xml[this.pos] !== '>') {
+      this.#fail(`Expected '>' or '/>' to close the start tag of <${name}>`);
+    }
+    this.pos++;
 
-      if (this.xml[this.pos] === '<') {
-        // Check for comment
-        if (this.xml.substring(this.pos, this.pos + 4) === '<!--') {
-          const commentEnd = this.xml.indexOf('-->', this.pos);
-          this.pos = commentEnd + 3;
-          continue;
-        }
+    return { name, attributes, children: this.#parseChildren(name) };
+  }
 
-        children.push(this._parseElement());
-      } else {
-        // Text content - skip for FHIR as values are in attributes
-        const textEnd = this.xml.indexOf('<', this.pos);
-        this.pos = textEnd;
-      }
+  /**
+   * An element or attribute name: everything up to whitespace, '/', '>' or '='.
+   * @param {string} what - for the error message
+   * @returns {string}
+   */
+  #parseName(what) {
+    const from = this.pos;
+    while (this.pos < this.xml.length && !/[\s/>=]/.test(this.xml[this.pos])) {
+      this.pos++;
     }
-
-    return { name, attributes, children };
+    if (this.pos === from) {
+      this.#fail(`Expected an ${what}`);
+    }
+    return this.xml.substring(from, this.pos);
   }
 
-  _parseAttribute() {
-    this._skipWhitespace();
+  /**
+   * @param {string} elementName - for error messages
+   * @returns {Object} name to value
+   */
+  #parseAttributes(elementName) {
+    const attributes = {};
+    for (;;) {
+      const was = this.pos;
+      this.#skipWhitespace();
+      if (this.#atEnd()) {
+        this.#fail(`Unterminated start tag <${elementName}>`);
+      }
+      if (this.xml[this.pos] === '>' || this.#startsWith('/>')) {
+        return attributes;
+      }
+      if (this.xml[this.pos] === '/') {
+        this.#fail(`Expected '/>' in the start tag of <${elementName}>`);
+      }
 
-    if (this.xml[this.pos] === '>' || this.xml[this.pos] === '/') {
-      return null;
-    }
+      const name = this.#parseName('attribute name');
+      this.#skipWhitespace();
+      if (this.#atEnd() || this.xml[this.pos] !== '=') {
+        this.#fail(`Expected '=' after the attribute '${name}' of <${elementName}>`);
+      }
+      this.pos++;
+      attributes[name] = this.#parseAttributeValue(name, elementName);
 
-    // Parse attribute name
-    const eqPos = this.xml.indexOf('=', this.pos);
-    const name = this.xml.substring(this.pos, eqPos).trim();
-    this.pos = eqPos + 1;
+      this.#mustHaveAdvanced(was);
+    }
+  }
 
-    // Skip whitespace and opening quote
-    this._skipWhitespace();
+  /**
+   * A quoted attribute value. XML has no unquoted form, and accepting one is what let a stray
+   * character send the cursor somewhere arbitrary
+   * @param {string} name
+   * @param {string} elementName
+   * @returns {string}
+   */
+  #parseAttributeValue(name, elementName) {
+    this.#skipWhitespace();
     const quote = this.xml[this.pos];
+    if (quote !== '"' && quote !== "'") {
+      this.#fail(`The value of the attribute '${name}' of <${elementName}> must be quoted`);
+    }
     this.pos++;
+    const end = this.#seek(quote, `value of the attribute '${name}' of <${elementName}>`);
+    const value = FhirXmlBase.unescapeXml(this.xml.substring(this.pos, end));
+    this.pos = end + 1;
+    return value;
+  }
+
+  /**
+   * Everything between a start tag and its matching end tag. Text is skipped: FHIR carries its
+   * values in attributes, and this parser has never returned character data.
+   * @param {string} elementName
+   * @returns {Array} the child elements
+   */
+  #parseChildren(elementName) {
+    const children = [];
+    for (;;) {
+      const was = this.pos;
+      this.#skipWhitespace();
+      if (this.#atEnd()) {
+        this.#fail(`Unclosed element <${elementName}>: expected </${elementName}>`);
+      }
 
-    // Parse attribute value
-    const valueEnd = this.xml.indexOf(quote, this.pos);
-    const value = FhirXmlBase.unescapeXml(this.xml.substring(this.pos, valueEnd));
-    this.pos = valueEnd + 1;
+      if (this.#startsWith('</')) {
+        this.pos += 2;
+        const closing = this.#parseName('element name');
+        if (closing !== elementName) {
+          this.#fail(`Expected </${elementName}> but found </${closing}>`);
+        }
+        this.#skipWhitespace();
+        if (this.#atEnd() || this.xml[this.pos] !== '>') {
+          this.#fail(`Expected '>' to close </${closing}>`);
+        }
+        this.pos++;
+        return children;
+      }
 
-    return { name, value };
+      if (this.xml[this.pos] === '<') {
+        if (this.#startsWith('<!--')) {
+          this.#skipComment();
+        } else if (this.#startsWith('<![CDATA[')) {
+          this.pos = this.#seek(']]>', 'CDATA section') + 3;
+        } else if (this.#startsWith('<!')) {
+          this.#fail('Declarations are not allowed inside a FHIR XML element');
+        } else if (this.#startsWith('<?')) {
+          this.pos = this.#seek('?>', 'processing instruction') + 2;
+        } else {
+          children.push(this.#parseElement());
+        }
+      } else {
+        // character data - skipped, but it still has to be consumed
+        this.pos = this.#seek('<', `content of <${elementName}>`);
+      }
+
+      this.#mustHaveAdvanced(was);
+    }
   }
 }
 

package/tx/xversion/xv-conceptmap.js

@@ -1,5 +1,63 @@
 const {VersionUtilities} = require("../../library/version-utilities");
 
+// R4/R3 have no ConceptMap.group.unmapped.valueSet or .relationship. The Java version
+// convertors carry them across as these cross-version extensions, so read them back.
+const EXT_UNMAPPED_VALUESET = 'http://hl7.org/fhir/5.0/StructureDefinition/extension-ConceptMap.group.unmapped.valueSet';
+const EXT_UNMAPPED_RELATIONSHIP = 'http://hl7.org/fhir/5.0/StructureDefinition/extension-ConceptMap.group.unmapped.relationship';
+
+/**
+ * R4 spells group.unmapped differently: the target map is 'url' rather than 'otherMap',
+ * and the 'provided' mode is called 'use-source-code' in R5.
+ */
+function unmappedToR5(unmapped) {
+  if (!unmapped) {
+    return;
+  }
+  if (unmapped.mode === 'provided') {
+    unmapped.mode = 'use-source-code';
+  }
+  if (unmapped.url !== undefined && unmapped.otherMap === undefined) {
+    unmapped.otherMap = unmapped.url;
+    delete unmapped.url;
+  }
+  for (const ext of unmapped.extension || []) {
+    if (ext.url === EXT_UNMAPPED_VALUESET && unmapped.valueSet === undefined) {
+      unmapped.valueSet = ext.valueCanonical || ext.valueUri;
+    }
+    if (ext.url === EXT_UNMAPPED_RELATIONSHIP && unmapped.relationship === undefined) {
+      unmapped.relationship = ext.valueCode || ext.valueString;
+    }
+  }
+  if (unmapped.extension) {
+    unmapped.extension = unmapped.extension.filter(e => e.url !== EXT_UNMAPPED_VALUESET && e.url !== EXT_UNMAPPED_RELATIONSHIP);
+    if (unmapped.extension.length === 0) {
+      delete unmapped.extension;
+    }
+  }
+}
+
+/** The inverse of unmappedToR5. */
+function unmappedFromR5(unmapped) {
+  if (!unmapped) {
+    return;
+  }
+  if (unmapped.mode === 'use-source-code') {
+    unmapped.mode = 'provided';
+  }
+  if (unmapped.otherMap !== undefined) {
+    unmapped.url = unmapped.otherMap;
+    delete unmapped.otherMap;
+  }
+  if (unmapped.valueSet !== undefined) {
+    (unmapped.extension = unmapped.extension || []).push({url: EXT_UNMAPPED_VALUESET, valueCanonical: unmapped.valueSet});
+    delete unmapped.valueSet;
+  }
+  if (unmapped.relationship !== undefined) {
+    (unmapped.extension = unmapped.extension || []).push({url: EXT_UNMAPPED_RELATIONSHIP, valueCode: unmapped.relationship});
+    delete unmapped.relationship;
+  }
+}
+
 /**
  * Converts input ConceptMap to R5 format (modifies input object for performance)
  * @param {Object} jsonObj - The input ConceptMap object
@@ -45,8 +103,30 @@ function conceptMapToR5(jsonObj, sourceVersion) {
     // Convert equivalence to relationship in group.element.target
     if (jsonObj.group && Array.isArray(jsonObj.group)) {
       jsonObj.group.forEach(group => {
+        unmappedToR5(group.unmapped);
         if (group.element && Array.isArray(group.element)) {
           group.element.forEach(element => {
+            // R4 has no element.noMap. A target with equivalence = 'unmatched' and no
+            // code is R4's way of saying the same thing: there is positively no map
+            // for this concept. Lift it to noMap and drop the placeholder target, so
+            // everything downstream sees one R5 shape. This mirrors what the Java
+            // convertors do (ConceptMap40_50.convertSourceElementComponent), including
+            // their reservation of 'unmatched' for noMap - a real 'not-related-to'
+            // target converts to 'disjoint' and carries a code, so it is untouched here.
+            if (element.target && Array.isArray(element.target)) {
+              const noMapTargets = element.target.filter(t => t.equivalence === 'unmatched' && !t.code);
+              if (noMapTargets.length > 0) {
+                element.noMap = true;
+                const comment = noMapTargets.find(t => t.comment);
+                if (comment && !element.comment) {
+                  element.comment = comment.comment;
+                }
+                element.target = element.target.filter(t => !(t.equivalence === 'unmatched' && !t.code));
+                if (element.target.length === 0) {
+                  delete element.target;
+                }
+              }
+            }
             if (element.target && Array.isArray(element.target)) {
               element.target.forEach(target => {
                 if (target.equivalence && !target.relationship) {
@@ -142,6 +222,7 @@ function conceptMapR5ToR4(r5Obj) {
   // Convert relationship back to equivalence in group.element.target
   if (r5Obj.group && Array.isArray(r5Obj.group)) {
     r5Obj.group.forEach(group => {
+      unmappedFromR5(group.unmapped);
       if (group.element && Array.isArray(group.element)) {
         group.element.forEach(element => {
           if (element.target && Array.isArray(element.target)) {

package/tx/xversion/xv-parameters.js

@@ -88,6 +88,14 @@ function fixMatchParameterfor5(p) {
 
 function fixMatchParameterfor4(p) {
   if (p.part) {
+    // R4 calls originMap 'source'. originMap is reported in every version; source is added
+    // here for R4 only, and is prohibited everywhere else
+    if (!p.part.find(pp => pp.name === 'source')) {
+      let om = p.part.find(pp => pp.name === 'originMap');
+      if (om && om.valueCanonical) {
+        p.part.push({name: "source", valueCanonical: om.valueCanonical});
+      }
+    }
     if (!p.part.find(pp => pp.name === 'equivalence')) {
       let rel = p.part.find(pp => pp.name === 'relationship');
       if (rel && rel.valueCode) {

package/tx/xversion/xv-valueset.js

@@ -1,7 +1,13 @@
 const {VersionUtilities} = require("../../library/version-utilities");
-const {getValueName} = require("../../library/utilities");
+const {getValueName, getValuePrimitive} = require("../../library/utilities");
 const {Extensions} = require("../library/extensions");
 
+// ValueSet.compose.property is R5 and up - it is how a client says which properties it wants
+// back in an expansion. R4 and R3 have nowhere to put it, so it travels as a cross-version
+// extension, the same one the Java convertors use. Dropping it instead means the expansion
+// comes back without the properties that were asked for, which reads as a server fault.
+const COMPOSE_PROPERTY_EXT = "http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.compose.property";
+
 /**
  * Converts input ValueSet to R5 format (modifies input object for performance)
  * @param {Object} jsonObj - The input ValueSet object
@@ -20,6 +26,7 @@ function valueSetToR5(jsonObj, sourceVersion) {
   for (const inc of jsonObj.compose?.exclude || []) {
     valueSetIncludeToR5(inc);
   }
+  composePropertyToR5(jsonObj.compose);
   if (VersionUtilities.isR4Ver(sourceVersion)) {
     return jsonObj; // No conversion needed
   }
@@ -33,6 +40,28 @@ function valueSetToR5(jsonObj, sourceVersion) {
   throw new Error(`Unsupported FHIR version: ${sourceVersion}`);
 }
 
+/** Read ValueSet.compose.property back out of the cross-version extension. */
+function composePropertyToR5(compose) {
+  if (!compose) {
+    return;
+  }
+  const carried = Extensions.list(compose, COMPOSE_PROPERTY_EXT);
+  if (carried.length === 0) {
+    return;
+  }
+  compose.property = compose.property || [];
+  for (const ext of carried) {
+    const value = getValuePrimitive(ext);
+    if (value !== undefined && value !== null) {
+      compose.property.push(value);
+    }
+  }
+  compose.extension = compose.extension.filter(ext => ext.url !== COMPOSE_PROPERTY_EXT);
+  if (compose.extension.length === 0) {
+    delete compose.extension;
+  }
+}
+
 function valueSetIncludeToR5(inc) {
   for (const filter of inc.filter || []) {
     if (filter._op) {
@@ -84,6 +113,15 @@ function valueSetR5ToR4(r5Obj) {
     delete r5Obj.versionAlgorithmCoding;
   }
 
+  // ValueSet.compose.property has no home in R4, so it goes into the extension
+  if (r5Obj.compose && Array.isArray(r5Obj.compose.property) && r5Obj.compose.property.length > 0) {
+    r5Obj.compose.extension = r5Obj.compose.extension || [];
+    for (const prop of r5Obj.compose.property) {
+      r5Obj.compose.extension.push({ url: COMPOSE_PROPERTY_EXT, valueString: prop });
+    }
+    delete r5Obj.compose.property;
+  }
+
   // Filter out R5-only filter operators in compose
   if (r5Obj.compose && r5Obj.compose.include) {
     r5Obj.compose.include = r5Obj.compose.include.map(include => {