fhirsmith 0.12.0 → 0.13.1

package/tx/importers/import-loinc.module.js

@@ -274,17 +274,23 @@ class LoincModule extends BaseTerminologyModule {
       throw new Error(`Source directory not found: ${sourceDir}`);
     }
 
+    // The accessory files are required, not optional. Without them the import silently
+    // succeeds and the server then answers questions wrongly rather than saying it cannot:
+    // no ComponentHierarchyBySystem means an empty closure and $subsumes replying
+    // 'not-subsumed' to everything, which is indistinguishable from a real answer.
     const requiredFiles = [
       'LoincTable/Loinc.csv',
-      'AccessoryFiles/PartFile/Part.csv'
-    ];
-
-    const optionalFiles = [
+      'AccessoryFiles/PartFile/Part.csv',
       'AccessoryFiles/ConsumerName/ConsumerName.csv',
       'AccessoryFiles/AnswerFile/AnswerList.csv',
       'AccessoryFiles/PartFile/LoincPartLink_Primary.csv',
       'AccessoryFiles/AnswerFile/LoincAnswerListLink.csv',
-      'AccessoryFiles/ComponentHierarchyBySystem/ComponentHierarchyBySystem.csv',
+      'AccessoryFiles/ComponentHierarchyBySystem/ComponentHierarchyBySystem.csv'
+    ];
+
+    // Translations are a different case: a main-only import is a legitimate thing to want,
+    // and their absence costs designations, not correctness
+    const optionalFiles = [
       'AccessoryFiles/LinguisticVariants/LinguisticVariants.csv'
     ];
 
@@ -1214,8 +1220,9 @@ class LoincDataMigrator {
   async processHierarchy(db, sourceDir, step, options) {
     const filePath = path.join(sourceDir, 'AccessoryFiles/ComponentHierarchyBySystem/ComponentHierarchyBySystem.csv');
     if (!fs.existsSync(filePath)) {
-      if (options.verbose) console.warn(`Hierarchy file not found: ${filePath}`);
-      return;
+      // Validation should have caught this already; if we get here, fail rather than build a
+      // cache with an empty closure that answers subsumption questions with a confident no
+      throw new Error(`Required file missing: ${filePath}`);
     }
 
     if (options.verbose) console.log('Processing Hierarchy...');

package/tx/importers/import-sct.module.js

@@ -13,6 +13,9 @@ const {
 } = require('../sct/structures');
 const {SnomedExpressionServices} = require("../sct/expressions");
 
+// definitionStatusId values from the RF2 concept file
+const SNOMED_DEFINITION_STATUS_PRIMITIVE = 900000000000074008n;
+
 class SnomedModule extends BaseTerminologyModule {
 
   constructor() {
@@ -1342,7 +1345,13 @@ class SnomedImporter {
 
     for (let i = 0; i < this.conceptList.length; i++) {
       const concept = this.conceptList[i];
-      const flags = concept.active ? 0 : 1;
+      // Bits 0-3 are the status (MASK_CONCEPT_STATUS); bit 4 (MASK_CONCEPT_PRIMITIVE) says the
+      // concept is primitive. Without the primitive bit every concept looks fully defined, and
+      // normal form generation then runs for concepts that have no definition to expand.
+      let flags = concept.active ? 0 : 1;
+      if (concept.definitionStatusId === SNOMED_DEFINITION_STATUS_PRIMITIVE) {
+        flags |= SnomedConceptList.MASK_CONCEPT_PRIMITIVE;
+      }
       const effectiveTime = this.convertDateToSnomedDate(concept.effectiveTime);
 
       concept.index = this.concepts.addConcept(concept.id, effectiveTime, flags);

package/tx/library/codesystem.js

@@ -3,6 +3,7 @@ const {CanonicalResource} = require("./canonical-resource");
 const {codeSystemFromR5, codeSystemToR5} = require("../xversion/xv-codesystem");
 const {getValuePrimitive} = require("../../library/utilities");
 const {VersionUtilities} = require("../../library/version-utilities");
+const {countNested} = require("./nesting-limit");
 
 const CodeSystemContentMode = Object.freeze({
   Complete: 'complete',
@@ -33,18 +34,30 @@ class CodeSystem extends CanonicalResource {
     super(jsonObj, fhirVersion);
     // Convert to R5 format internally (modifies input for performance)
     this.jsonObj = codeSystemToR5(this.jsonObj, fhirVersion);
-    if (!noMaps) {
-      try {
+    try {
+      // Bound the nesting before anything walks the concept tree recursively - see
+      // nesting-limit.js. It has to precede validate(), which recurses itself, and it
+      // runs on the noMaps path too: validate() is skipped there, but the count below
+      // and every later consumer still walk the tree. The count is a by-product, so
+      // callers (e.g. the resource cache) get a cheap O(1) sense of the resource size
+      // without a second traversal.
+      // Optional chaining because this runs ahead of validate()'s "expected object"
+      // guard, and a null body must still get that message rather than a TypeError.
+      this._conceptCount = countNested(this.jsonObj?.concept, 'concept', 'Invalid CodeSystem: concept');
+      if (!noMaps) {
         this.validate();
-      } catch (e) {
-        const id = this.jsonObj?.url ? `${this.jsonObj.url}|${this.jsonObj.version || ''}` : this.jsonObj?.name || 'unknown';
-        throw new Error(`${e.message} (in ${id})`);
       }
+    } catch (e) {
+      const id = this.jsonObj?.url ? `${this.jsonObj.url}|${this.jsonObj.version || ''}` : this.jsonObj?.name || 'unknown';
+      const wrapped = new Error(`${e.message} (in ${id})`);
+      // Don't let the rewrap swallow the HTTP shape the thrower asked for.
+      if (e.statusCode) { wrapped.statusCode = e.statusCode; }
+      if (e.issueCode) { wrapped.issueCode = e.issueCode; }
+      throw wrapped;
+    }
+    if (!noMaps) {
       this.buildMaps();
     }
-    // Precalculated at construction so callers (e.g. the resource cache) have a
-    // cheap O(1) sense of how large this resource is.
-    this._conceptCount = CodeSystem._countConcepts(this.jsonObj.concept);
   }
 
   /**
@@ -56,25 +69,6 @@ class CodeSystem extends CanonicalResource {
     return this._conceptCount;
   }
 
-  /**
-   * Recursively count concepts (including nested `concept` children).
-   * @param {Array} concepts
-   * @returns {number}
-   */
-  static _countConcepts(concepts) {
-    if (!Array.isArray(concepts)) {
-      return 0;
-    }
-    let n = 0;
-    for (const c of concepts) {
-      n++;
-      if (c && c.concept) {
-        n += CodeSystem._countConcepts(c.concept);
-      }
-    }
-    return n;
-  }
-
   /**
    * Map of code to concept object for fast lookup
    * @type {Map<string, Object>}

package/tx/library/nesting-limit.js

@@ -0,0 +1,79 @@
+/**
+ * Bounds on how deeply a resource may nest itself.
+ *
+ * FHIR lets both CodeSystem.concept and ValueSet.expansion.contains nest without
+ * limit, and both are walked recursively all over this codebase (the expansion map,
+ * the concept count, the renderer, the expander's index, the R5->R4 converter, ...).
+ * A hostile resource of a few hundred KB can therefore blow the JS stack, and even
+ * if every one of those walkers were made iterative, `JSON.stringify` -- which we do
+ * not control -- overflows at a nesting depth of roughly 1800 on node 22.
+ *
+ * Rather than harden each walker in turn and hope the next one added remembers, we
+ * bound the nesting once, when the resource is constructed. Everything downstream is
+ * then safe by construction, including code that does not exist yet.
+ *
+ * The limit is deliberately far below where anything actually breaks. Real nesting
+ * mirrors the hierarchy of a code system -- SNOMED CT is about 30 deep, LOINC parts
+ * about 10, ICD-10 about 5 -- so 100 is well past any legitimate resource while
+ * leaving more than an order of magnitude of headroom against the stack.
+ *
+ * @module tx/library/nesting-limit
+ */
+
+/**
+ * Maximum nesting depth allowed in a resource's self-recursive structure.
+ * @type {number}
+ */
+const MAX_NESTING_DEPTH = 100;
+
+/**
+ * Walks a self-nesting FHIR structure iteratively, counting its entries and
+ * enforcing {@link MAX_NESTING_DEPTH}.
+ *
+ * The walk uses an explicit stack, so it costs no JS stack depth of its own and can
+ * safely be pointed at a tree deep enough to overflow a recursive walker. It is the
+ * one traversal that has to survive hostile input; every other walker in the codebase
+ * runs after this one has passed.
+ *
+ * Non-array input counts as zero, matching the tolerant behaviour of the recursive
+ * counters this replaces - structural type checking is the caller's business.
+ *
+ * @param {Array} items - Top-level array of the nesting structure
+ * @param {string} childProperty - Name of the property holding nested children ('concept', 'contains')
+ * @param {string} path - Path used in the error message ('CodeSystem.concept')
+ * @returns {number} Total number of entries, nested ones included
+ * @throws {Error} If nesting exceeds MAX_NESTING_DEPTH, tagged statusCode 400 / issueCode 'structure'
+ */
+function countNested(items, childProperty, path) {
+  if (!Array.isArray(items)) {
+    return 0;
+  }
+
+  let count = 0;
+  // Each frame is a list to walk plus the depth at which its entries sit.
+  const stack = [{ list: items, depth: 1 }];
+
+  while (stack.length > 0) {
+    const { list, depth } = stack.pop();
+    if (depth > MAX_NESTING_DEPTH) {
+      // The worker error handlers honour statusCode/issueCode when they are present on
+      // a plain Error, so tag it: this is a bad resource from the client, not a server
+      // fault, and it should come back as a 400 rather than the default 500/exception.
+      const e = new Error(
+        `${path} is nested more than ${MAX_NESTING_DEPTH} levels deep, which is not supported`);
+      e.statusCode = 400;
+      e.issueCode = 'structure';
+      throw e;
+    }
+    for (const item of list) {
+      count++;
+      if (item && Array.isArray(item[childProperty]) && item[childProperty].length > 0) {
+        stack.push({ list: item[childProperty], depth: depth + 1 });
+      }
+    }
+  }
+
+  return count;
+}
+
+module.exports = { MAX_NESTING_DEPTH, countNested };

package/tx/library/operation-outcome.js

@@ -1,5 +1,80 @@
 const {validateParameter} = require("../../library/utilities");
 
+const TX_ISSUE_TYPE_SYSTEM = "http://hl7.org/fhir/tools/CodeSystem/tx-issue-type";
+
+/**
+ * Every issue this server emits carries a tx-issue-type coding in details.coding, and the
+ * human readable account of the problem in details.text. Nothing a client needs is allowed
+ * to live *only* in diagnostics: the test harness strips diagnostics outright, so anything
+ * that lives there alone is, by construction, invisible to a test. diagnostics itself is
+ * still sent -- it is the right place for server-specific detail, and dropping it would
+ * take away something useful to get a property no test could have relied on anyway.
+ *
+ * Most issues name their tx-issue-type explicitly. This map is the backstop for the ones
+ * that do not, so that "always has a coding" holds without every one of the ~170 Issue
+ * construction sites having to be revisited at once. It is keyed on the FHIR issue-type,
+ * which is the coarser of the two vocabularies, so an explicit code is always better.
+ */
+const DEFAULT_TX_ISSUE_TYPE = {
+  'not-found': 'not-found',
+  'code-invalid': 'invalid-code',
+  'invalid': 'invalid-data',
+  'structure': 'invalid-data',
+  'required': 'invalid-data',
+  'value': 'invalid-data',
+  'processing': 'invalid-data',
+  'exception': 'invalid-data',
+  'unknown': 'invalid-data',
+  'conflict': 'invalid-data',
+  'business-rule': 'business-rule',
+  'too-costly': 'too-costly',
+  'not-supported': 'not-supported',
+};
+
+/**
+ * The tx-issue-type for an issue that did not name one. Informational issues that are not
+ * about a code or a value set -- the server banner, say -- are not tx issues at all and get
+ * no coding; everything else does.
+ */
+function defaultTxIssueType(code, severity) {
+  if (severity === 'information' && (code === 'informational' || !code)) {
+    return null;
+  }
+  return DEFAULT_TX_ISSUE_TYPE[code] || 'invalid-data';
+}
+
+/**
+ * Build a single issue from loose parts. Prefer throwing an Issue -- this is for the
+ * handful of places that build an outcome directly, so that they cannot drift away from
+ * the shape Issue.asIssue() produces.
+ *
+ * `diagnostics` still goes out on the wire. The rule is that nothing a client needs may
+ * live *only* there, because the test harness strips it before it compares -- not that the
+ * server should stop saying anything. Callers with real internal detail to add (a stack
+ * location, a request id, what the server was doing when it gave up) pass it; the rest get
+ * the message, which is what this server has always sent.
+ */
+function buildIssue(severity, code, message, txIssueType = null, diagnostics = undefined) {
+  const res = { severity, code, details: { text: message } };
+  const tx = txIssueType || defaultTxIssueType(code, severity);
+  if (tx) {
+    res.details.coding = [{ system: TX_ISSUE_TYPE_SYSTEM, code: tx }];
+  }
+  const diag = diagnostics === undefined ? message : diagnostics;
+  if (diag) {
+    res.diagnostics = diag;
+  }
+  return res;
+}
+
+/** Build a one issue OperationOutcome from loose parts. */
+function buildOperationOutcome(severity, code, message, txIssueType = null, diagnostics = undefined) {
+  return {
+    resourceType: 'OperationOutcome',
+    issue: [buildIssue(severity, code, message, txIssueType, diagnostics)],
+  };
+}
+
 class Issue extends Error {
   level;
   cause;
@@ -33,8 +108,9 @@ class Issue extends Error {
     if (this.path) {
       res.expression = [this.path]
     }
-    if (this.issueCode) {
-      res.details.coding = [{ system: "http://hl7.org/fhir/tools/CodeSystem/tx-issue-type", code : this.issueCode }];
+    const issueCode = this.issueCode || defaultTxIssueType(this.cause, this.level);
+    if (issueCode) {
+      res.details.coding = [{ system: TX_ISSUE_TYPE_SYSTEM, code : issueCode }];
     }
     if (this.msgId) {
       res.extension = [{ url: "http://hl7.org/fhir/StructureDefinition/operationoutcome-message-id", valueString: this.msgId }];
@@ -129,4 +205,22 @@ class OperationOutcome {
   }
 }
 
-module.exports = { OperationOutcome, Issue };
+/**
+ * Turn a thrown error into an OperationOutcome. Two conventions meet here, and this is the
+ * only place that has to know about both: an Issue carries the FHIR issue type in `cause`
+ * and the tx-issue-type in `issueCode`, while a plain Error tagged by whatever threw it
+ * carries the FHIR issue type in `issueCode` and the tx-issue-type in `txIssueType`. Either
+ * way the result has details.text and a tx-issue-type coding.
+ */
+function outcomeFromError(error) {
+  if (error instanceof Issue) {
+    const oo = new OperationOutcome();
+    oo.addIssue(error);
+    return oo.jsonObj;
+  }
+  return buildOperationOutcome('error', error.issueCode || 'exception',
+    error.message || String(error), error.txIssueType || null, error.diagnostics);
+}
+
+module.exports = { OperationOutcome, Issue, buildIssue, buildOperationOutcome,
+  outcomeFromError, defaultTxIssueType, TX_ISSUE_TYPE_SYSTEM };

package/tx/library/valueset.js

@@ -1,5 +1,6 @@
 const {CanonicalResource} = require("./canonical-resource");
 const {valueSetToR5, valueSetFromR5} = require("../xversion/xv-valueset");
+const {countNested} = require("./nesting-limit");
 
 /**
  * Represents a FHIR ValueSet resource with version conversion support
@@ -27,7 +28,7 @@ class ValueSet extends CanonicalResource {
     this.buildMaps();
     // Precalculated at construction so callers (e.g. the resource cache) have a
     // cheap O(1) sense of how large this resource is.
-    this._conceptCount = ValueSet._countConcepts(this.jsonObj);
+    this._conceptCount = ValueSet._countConcepts(this.jsonObj, this._containsCount);
   }
 
   /**
@@ -42,7 +43,7 @@ class ValueSet extends CanonicalResource {
     return this._conceptCount;
   }
 
-  static _countConcepts(jsonObj) {
+  static _countConcepts(jsonObj, containsCount) {
     let n = 0;
     const compose = jsonObj && jsonObj.compose;
     if (compose) {
@@ -53,24 +54,7 @@ class ValueSet extends CanonicalResource {
         n += Array.isArray(exc.concept) ? exc.concept.length : 0;
       }
     }
-    if (jsonObj && jsonObj.expansion) {
-      n += ValueSet._countContains(jsonObj.expansion.contains);
-    }
-    return n;
-  }
-
-  static _countContains(items) {
-    if (!Array.isArray(items)) {
-      return 0;
-    }
-    let n = 0;
-    for (const it of items) {
-      n++;
-      if (it && it.contains) {
-        n += ValueSet._countContains(it.contains);
-      }
-    }
-    return n;
+    return n + (containsCount || 0);
   }
 
   /**
@@ -79,6 +63,13 @@ class ValueSet extends CanonicalResource {
    */
   codeMap = new Map();
 
+  /**
+   * Number of entries in expansion.contains, nested ones included. Counted by the
+   * depth-bounding walk in validate(), so the tree is only traversed once.
+   * @type {number}
+   */
+  _containsCount = 0;
+
   /**
    * Static factory method for convenience
    * @param {string} jsonString - JSON string representation of ValueSet
@@ -158,6 +149,11 @@ class ValueSet extends CanonicalResource {
       if (this.jsonObj.expansion.contains && !Array.isArray(this.jsonObj.expansion.contains)) {
         throw new Error('Invalid ValueSet: expansion.contains must be an array if present');
       }
+      // Bound the nesting before anything walks it recursively - see nesting-limit.js.
+      // This has to happen before buildMaps(), which is itself a recursive walker, so
+      // it lives here rather than alongside the concept count in the constructor.
+      this._containsCount = countNested(this.jsonObj.expansion.contains, 'contains',
+        'Invalid ValueSet: expansion.contains');
     }
   }
 

package/tx/library.js

@@ -23,6 +23,7 @@ const {UniiServicesFactory} = require("./cs/cs-unii");
 const {SnomedServicesFactory} = require("./cs/cs-snomed");
 const {CPTServicesFactory} = require("./cs/cs-cpt");
 const {OMOPServicesFactory} = require("./cs/cs-omop");
+const {ICD11ServicesFactory} = require("./cs/cs-icd11");
 const {PackageValueSetProvider} = require("./vs/vs-package");
 const {PackageConceptMapProvider} = require("./cm/cm-package");
 const {IETFLanguageCodeFactory} = require("./cs/cs-lang");
@@ -277,6 +278,10 @@ class Library {
         await this.loadOmop(details, isDefault, mode);
         break;
 
+      case 'icd11':
+        await this.loadIcd11(details, isDefault, mode);
+        break;
+
       case 'npm':
         await this.loadNpm(packageManager, details, isDefault, mode, false);
         break;
@@ -457,7 +462,7 @@ class Library {
         break;
       }
       case "mimetypes" : {
-        const mime = new MimeTypeServicesFactory(this.i18n);
+        const mime = new MimeTypeServicesFactory(this.i18n, this.cacheFolder, this.log);
         await mime.load();
         this.registerProvider('internal', mime);
         break;
@@ -591,6 +596,23 @@ class Library {
     this.registerProvider(omopFN, omop, isDefault);
   }
 
+  /**
+   * ICD-11 is three code systems in one database - the MMS and ICF linearizations and the
+   * Foundation - so one source line registers a factory per system that the database
+   * actually contains. registerProvider is keyed on system(), so they cannot share one.
+   */
+  async loadIcd11(details, isDefault, mode) {
+    const icdFN = await this.getOrDownloadFile(details);
+    if (mode === "fetch" || mode === "npm") {
+      return;
+    }
+    for (const sys of await ICD11ServicesFactory.listSystems(icdFN)) {
+      const factory = new ICD11ServicesFactory(this.i18n, icdFN, sys.code);
+      await factory.load();
+      this.registerProvider(icdFN, factory, isDefault);
+    }
+  }
+
   /**
    * Returns true if the given url/version should be excluded from npm/url package loading.
    * Matches against the ignored list using either plain url or url#version.

package/tx/ocl/cache/cache-utils.cjs

@@ -1,5 +1,7 @@
 const fs = require('fs/promises');
 const fsSync = require('fs');
+const Logger = require('../../../library/logger');
+const oclLog = Logger.getInstance().child({ module: 'ocl' });
 
 async function ensureCacheDirectories(...dirs) {
   for (const dir of dirs) {
@@ -10,12 +12,12 @@ async function ensureCacheDirectories(...dirs) {
     try {
       await fs.mkdir(dir, { recursive: true });
     } catch (error) {
-      console.error('[OCL] Failed to create cache directory:', dir, error.message);
+      oclLog.error(`Failed to create cache directory: ${dir} ${error.message}`);
     }
   }
 }
 
-function getColdCacheAgeMs(cacheFilePath, logPrefix = '[OCL]') {
+function getColdCacheAgeMs(cacheFilePath) {
   try {
     const stats = fsSync.statSync(cacheFilePath);
     if (!stats || !Number.isFinite(stats.mtimeMs)) {
@@ -25,7 +27,7 @@ function getColdCacheAgeMs(cacheFilePath, logPrefix = '[OCL]') {
     return Math.max(0, Date.now() - stats.mtimeMs);
   } catch (error) {
     if (error && error.code !== 'ENOENT') {
-      console.error(`${logPrefix} Failed to inspect cold cache file ${cacheFilePath}: ${error.message}`);
+      oclLog.error(`Failed to inspect cold cache file ${cacheFilePath}: ${error.message}`);
     }
     return null;
   }