fhirsmith 0.11.1 → 0.11.2

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to the Health Intersections Node Server will be documented i
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.11.2 - 2026-08-12
+
+### Fixed
+
+- Update snomed test content
+
+### Fixed
+
+- Fix snomed designation handling for languages
+- Fix for SSEF protection in the validator- 
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 2729 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed, tests v1.9.3, runner v6.10.1)
+
 ## [0.11.1] - 2026-07-30
 
 ### Added

package/library/folder-content-loader.js

@@ -2,6 +2,8 @@ const fs = require('fs').promises;
 const path = require('path');
 const { PackageContentLoader } = require('./package-manager');
 
+const TERMINOLOGY_TYPES = ['CodeSystem', 'ValueSet', 'ConceptMap'];
+
 /**
  * A content loader that scans a folder for JSON FHIR terminology resources
  * (CodeSystem, ValueSet, ConceptMap). It synthesizes the package layout that
@@ -26,14 +28,27 @@ class FolderContentLoader extends PackageContentLoader {
   }
 
   /**
-   * Replaces the standard initialize: there is no package.json or .index.json
-   * to read, so we synthesize an index from the JSON files in the folder.
+   * The synthesized package name reported by id()/pid().
+   * @returns {string}
    */
-  async initialize() {
-    if (this.loaded) {
-      return;
-    }
+  _packageName() {
+    return 'folder.' + path.basename(this.sourceFolder);
+  }
+
+  /**
+   * Whether a file that can't be parsed, or that isn't a terminology resource,
+   * should be quietly skipped. True for folder scans (the folder may hold all
+   * sorts of things); false when a specific file was nominated.
+   * @returns {boolean}
+   */
+  get _skipInvalidFiles() {
+    return true;
+  }
 
+  /**
+   * Check the source exists and is the right kind of thing.
+   */
+  async _validateSource() {
     try {
       const stat = await fs.stat(this.sourceFolder);
       if (!stat.isDirectory()) {
@@ -45,36 +60,63 @@ class FolderContentLoader extends PackageContentLoader {
       }
       throw err;
     }
+  }
+
+  /**
+   * The file names (relative to sourceFolder) to consider.
+   * @returns {Promise<Array<string>>}
+   */
+  async _candidateFiles() {
+    const names = [];
+    const entries = await fs.readdir(this.sourceFolder, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!entry.name.toLowerCase().endsWith('.json')) continue;
+      names.push(entry.name);
+    }
+    return names;
+  }
+
+  /**
+   * Replaces the standard initialize: there is no package.json or .index.json
+   * to read, so we synthesize an index from the JSON files in the source.
+   */
+  async initialize() {
+    if (this.loaded) {
+      return;
+    }
+
+    await this._validateSource();
 
     // Synthesize package metadata so id()/version()/pid() return something usable.
     this.package = {
-      name: 'folder.' + path.basename(this.sourceFolder),
+      name: this._packageName(),
       version: '0.0.0',
       fhirVersions: ['5.0.0']
     };
 
     const files = [];
-    const entries = await fs.readdir(this.sourceFolder, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isFile()) continue;
-      if (!entry.name.toLowerCase().endsWith('.json')) continue;
-
-      const fullPath = path.join(this.sourceFolder, entry.name);
+    for (const name of await this._candidateFiles()) {
+      const fullPath = path.join(this.sourceFolder, name);
       let json;
       try {
         const content = await fs.readFile(fullPath, 'utf8');
         json = JSON.parse(content);
-      } catch {
-        // Skip unreadable / non-JSON files rather than failing the whole load.
-        continue;
+      } catch (e) {
+        // Skip unreadable / non-JSON files rather than failing the whole load,
+        // unless this exact file was the nominated source.
+        if (this._skipInvalidFiles) continue;
+        throw new Error(`Unable to read FHIR resource from ${fullPath}: ${e.message}`);
       }
 
-      if (!json || typeof json !== 'object') continue;
-      const rt = json.resourceType;
-      if (rt !== 'CodeSystem' && rt !== 'ValueSet' && rt !== 'ConceptMap') continue;
+      const rt = json && typeof json === 'object' ? json.resourceType : null;
+      if (!TERMINOLOGY_TYPES.includes(rt)) {
+        if (this._skipInvalidFiles) continue;
+        throw new Error(`${fullPath} is not a CodeSystem, ValueSet or ConceptMap (resourceType = ${rt || 'none'})`);
+      }
 
       files.push({
-        filename: entry.name,
+        filename: name,
         resourceType: rt,
         id: json.id,
         url: json.url,
@@ -88,4 +130,52 @@ class FolderContentLoader extends PackageContentLoader {
   }
 }
 
-module.exports = { FolderContentLoader };
+/**
+ * A content loader for a single nominated JSON file holding one CodeSystem,
+ * ValueSet or ConceptMap. Everything else works exactly as for a folder source:
+ * the file's own directory is the read-only content root, and the provider
+ * caches live in the supplied cacheFolder.
+ *
+ * Unlike a folder scan, a bad file is an error rather than something to skip -
+ * the config named this file explicitly, so failing silently would just hide
+ * a typo.
+ */
+class FileContentLoader extends FolderContentLoader {
+  /**
+   * @param {string} filePath - The JSON file to load
+   * @param {string} cacheFolder - Folder where Package*Provider DBs may live
+   */
+  constructor(filePath, cacheFolder) {
+    super(path.dirname(filePath), cacheFolder);
+    this.filePath = filePath;
+    this.fileName = path.basename(filePath);
+  }
+
+  _packageName() {
+    return 'file.' + this.fileName.replace(/\.json$/i, '');
+  }
+
+  get _skipInvalidFiles() {
+    return false;
+  }
+
+  async _validateSource() {
+    try {
+      const stat = await fs.stat(this.filePath);
+      if (!stat.isFile()) {
+        throw new Error(`File source path is not a file: ${this.filePath}`);
+      }
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        throw new Error(`File source path does not exist: ${this.filePath}`);
+      }
+      throw err;
+    }
+  }
+
+  async _candidateFiles() {
+    return [this.fileName];
+  }
+}
+
+module.exports = { FolderContentLoader, FileContentLoader };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fhirsmith",
-  "version": "0.11.1",
-  "txVersion": "1.9.1",
+  "version": "0.11.2",
+  "txVersion": "1.9.3",
   "description": "A Node.js server that provides a collection of tools to serve the FHIR ecosystem",
   "main": "server.js",
   "engines": {
@@ -46,7 +46,7 @@
     "express-rate-limit": "^7.4.1",
     "express-session": "^1.19.0",
     "fast-xml-parser": "^5.3.4",
-    "fhir-validator-wrapper": "1.2.2",
+    "fhir-validator-wrapper": "1.3.0",
     "fhirpath": "^4.8.3",
     "fs-extra": "^11.3.3",
     "ini": "^6.0.0",

package/tx/cs/cs-api.js

@@ -404,9 +404,15 @@ class CodeSystemProvider {
    * @param {boolean} [significantOnly=false] - when true, emit only the
    *   designations that are significant for a value set expansion (the display,
    *   and - for code systems that distinguish them - the fully specified name
-   *   and the preferred term), rather than every designation in every language.
-   *   The $expand worker passes true; $lookup uses the default (false) to return
-   *   the complete set. Providers that do not distinguish significant
+   *   and the preferred term), rather than every designation. This narrows which
+   *   designations are emitted, NOT which languages: the display for a request is
+   *   chosen downstream by preferredDesignation(displayLanguage), so a provider
+   *   that emits significant designations for one language only makes localized
+   *   expansions fall back to that language. Emit the significant designations
+   *   for every language the concept has.
+   *   The $expand worker passes true when the client did not ask for
+   *   designations; $lookup and includeDesignations=true use the default (false)
+   *   to return the complete set. Providers that do not distinguish significant
    *   designations may ignore this parameter and return all designations either
    *   way.
    * @returns {Designation[]} whatever designations exist (in all languages)

package/tx/cs/cs-snomed.js

@@ -1605,13 +1605,25 @@ class SnomedProvider extends BaseCSServices {
             const K = this.sct._displayConstants();
 
             if (significantOnly) {
-              // $expand: emit the "significant" designations only — the FSN plus
-              // the preferred synonym (US English), active descriptions only.
-              // The preferred synonym is also the display, so it is added as the
-              // display designation (which the expand worker selects for
-              // `display` and skips from the emitted list) and additionally as a
-              // Synonym designation so it still appears in the designation array.
-              let fsn = null, prefSyn = null;
+              // $expand: emit the "significant" designations only — the FSN and
+              // the preferred synonym, active descriptions only. Acceptable
+              // synonyms are the bulk of a SNOMED concept's descriptions and are
+              // not needed to render an expansion, so they are dropped.
+              //
+              // One per LANGUAGE, though, not one overall: the display for a
+              // request is chosen downstream by
+              // Designations.preferredDesignation(displayLanguage), so a concept
+              // that emits only its English terms has nothing for a
+              // displayLanguage=de request to match and silently falls back to
+              // English. Keeping the preferred synonym in every language the
+              // concept has is what makes localized expansions work at all
+              // (e.g. the Swiss edition, whose German terms are preferred in the
+              // Swiss German language refset 2041000195100).
+              //
+              // The edition-default display is also added as the display
+              // designation (which the expand worker selects for `display` when
+              // no language was asked for, and skips from the emitted list).
+              const fsns = new Map(), prefSyns = new Map();
               for (const descIndex of descriptionIndices) {
                 const description = this.sct.descriptions.getDescription(descIndex);
                 if (!description.active) continue;
@@ -1620,15 +1632,20 @@ class SnomedProvider extends BaseCSServices {
                 const kind = this.sct.concepts.getConcept(description.kind);
                 const use = { system: 'http://snomed.info/sct', code: String(kind.identity), display: this.sct.getDisplayName(description.kind) };
                 if (description.kind === K.fsn) {
-                  if (!fsn) fsn = { langCode, use, term };
+                  if (!fsns.has(langCode)) fsns.set(langCode, { langCode, use, term });
                 } else if (this.sct._synonymIsPreferred(description)) {
-                  if (!prefSyn) prefSyn = { langCode, use, term };
+                  if (!prefSyns.has(langCode)) prefSyns.set(langCode, { langCode, use, term });
                 }
               }
               const display = this.sct.getDisplayName(ctxt.getReference());
               if (display) displays.addDesignation(true, 'active', 'en-US', null, display);
-              if (fsn) displays.addDesignation(false, 'active', fsn.langCode, fsn.use, fsn.term);
-              if (prefSyn) displays.addDesignation(false, 'active', prefSyn.langCode, prefSyn.use, prefSyn.term);
+              // FSNs before synonyms, matching the designation order the published
+              // tx-ecosystem expectations were written against (sct/expand-inactive).
+              // Which of the two is chosen as the display is settled by
+              // Designations.preferredDesignation(), which ranks the SNOMED synonym
+              // above the FSN - not by the order they are emitted in.
+              for (const d of fsns.values()) displays.addDesignation(false, 'active', d.langCode, d.use, d.term);
+              for (const d of prefSyns.values()) displays.addDesignation(false, 'active', d.langCode, d.use, d.term);
             } else {
               // $lookup: emit every description (preferred synonym first so the
               // display resolves correctly; order is not otherwise significant).

package/tx/library/designations.js

@@ -610,8 +610,15 @@ class Designations {
 
       for (const activeOnly of [true, false]) {
         for (const matchType of matchTypes) {
+          // _isPreferred before isDisplay, matching the no-language branch above.
+          // The two sets differ only where a provider's own isDisplay() accepts a
+          // designation that isn't a preferred term - today that is the SNOMED FSN,
+          // which isDisplay() accepts and _isPreferred() deliberately does not. Testing
+          // isDisplay first made a request for a language whose concept has both an FSN
+          // and a preferred synonym display the "(disorder)"-suffixed FSN, purely
+          // because the FSN was emitted first.
           for (const cd of this.designations) {
-            if (this._langMatches(lang, cd.language, matchType) && this.isDisplay(cd) && (!activeOnly || cd.isActive())) {
+            if (this._langMatches(lang, cd.language, matchType) && this._isPreferred(cd) && (!activeOnly || cd.isActive())) {
               if (supplements && cd.source) {
                 supplements.add(cd.source);
               }
@@ -619,7 +626,7 @@ class Designations {
             }
           }
           for (const cd of this.designations) {
-            if (this._langMatches(lang, cd.language, matchType) && this._isPreferred(cd)&& (!activeOnly || cd.isActive())) {
+            if (this._langMatches(lang, cd.language, matchType) && this.isDisplay(cd) && (!activeOnly || cd.isActive())) {
               if (supplements && cd.source) {
                 supplements.add(cd.source);
               }

package/tx/library.js

@@ -3,7 +3,7 @@ const path = require('path');
 const crypto = require('crypto');
 const yaml = require('yaml'); // npm install yaml
 const { PackageManager, PackageContentLoader } = require('../library/package-manager');
-const { FolderContentLoader } = require('../library/folder-content-loader');
+const { FolderContentLoader, FileContentLoader } = require('../library/folder-content-loader');
 const { CodeSystem } = require("./library/codesystem");
 const {CountryCodeFactoryProvider} = require("./cs/cs-country");
 const {Iso4217FactoryProvider} = require("./cs/cs-currency");
@@ -301,6 +301,10 @@ class Library {
         await this.loadFolder(details, isDefault, mode);
         break;
 
+      case 'file':
+        await this.loadFile(details, isDefault, mode);
+        break;
+
       default:
         throw new Error(`Unknown source type: ${type}`);
     }
@@ -679,19 +683,68 @@ class Library {
       return;
     }
 
-    const folderPath = path.isAbsolute(details)
-      ? details
-      : path.resolve(path.join(__dirname, '..', details));
+    const folderPath = this.#resolveLocalSourcePath(details);
+    const cacheSubdir = await this.#prepareLocalSourceCache(folderPath);
+    await this.#loadLocalSource(new FolderContentLoader(folderPath, cacheSubdir));
+  }
+
+  /**
+   * Loads a single nominated JSON file holding a CodeSystem, ValueSet or ConceptMap
+   * (source syntax: `file:<path>`). The resource is routed to the appropriate provider
+   * based on its resourceType.
+   *
+   * Unlike a folder source, the file must exist and must be one of the three terminology
+   * resource types - anything else is an error, since the config named it explicitly.
+   *
+   * Relative paths are resolved against the project root (same convention as loadUcum etc.).
+   *
+   * @param {string} details - The file to load
+   * @param {boolean} isDefault - Unused; file sources don't register factories
+   * @param {string} mode - One of "fetch", "cs", "npm"
+   */
+  // eslint-disable-next-line no-unused-vars
+  async loadFile(details, isDefault, mode) {
+    if (mode === "fetch" || mode === "cs") {
+      return;
+    }
+
+    const filePath = this.#resolveLocalSourcePath(details);
+    const cacheSubdir = await this.#prepareLocalSourceCache(filePath);
+    await this.#loadLocalSource(new FileContentLoader(filePath, cacheSubdir));
+  }
+
+  /**
+   * Relative paths in folder:/file: sources are resolved against the project root.
+   * @private
+   */
+  #resolveLocalSourcePath(details) {
+    const text = String(details || '').trim();
+    if (!text) {
+      throw new Error('A local source requires a path, e.g. file:tx/data/my-valueset.json');
+    }
+    return path.isAbsolute(text) ? text : path.resolve(path.join(__dirname, '..', text));
+  }
 
-    // Park the Package*Provider SQLite caches under the terminology cache rather
-    // than polluting the user's source folder, and wipe between runs so edits to
-    // the source folder are reliably picked up.
-    const hash = crypto.createHash('sha1').update(folderPath).digest('hex').substring(0, 16);
+  /**
+   * Parks the Package*Provider SQLite caches under the terminology cache rather
+   * than polluting the user's source folder, and wipes between runs so edits to
+   * the source are reliably picked up.
+   * @private
+   */
+  async #prepareLocalSourceCache(sourcePath) {
+    const hash = crypto.createHash('sha1').update(sourcePath).digest('hex').substring(0, 16);
     const cacheSubdir = path.join(this.cacheFolder, 'folder-source-' + hash);
     await fs.rm(cacheSubdir, { recursive: true, force: true });
     await fs.mkdir(cacheSubdir, { recursive: true });
+    return cacheSubdir;
+  }
 
-    const contentLoader = new FolderContentLoader(folderPath, cacheSubdir);
+  /**
+   * Shared loader for folder- and file-sourced content: registers the loader's
+   * CodeSystems, ValueSets and ConceptMaps with this library.
+   * @private
+   */
+  async #loadLocalSource(contentLoader) {
     await contentLoader.initialize();
 
     this.packageSources.push(contentLoader.id() + "#" + contentLoader.version());