fhirsmith 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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).
 
+## [v0.5.0] - 2026-02-19
+
+### Added
+- Prototype Implementation of $related operation
+
+### Changed
+- A great deal of QA work preparing the server to run tx.fhir.org, which led to 100s of fixes 
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 1288 HL7 terminology service tests (modes tx.fhir.org,omop,general,snomed, tests v1.9.1-SNAPSHOT, runner v6.8.0)
+
 ## [v0.4.2] - 2026-02-05
 ### Changed
 - Even More testing the release process; some tidy up to testing data

package/README.md

@@ -190,7 +190,7 @@ Available tags:
 
 ### Windows Installation
 
-You can install as a windows service using [windows-install.js](windows-install.js). You might need to 
+You can install as a windows service using [windows-install.js](utilities/windows-install.js). You might need to 
 hack that. 
 
 ## Releases

package/library/cron-utilities.js

@@ -0,0 +1,136 @@
+/**
+ * Convert a cron expression to a human-readable summary
+ * Supports standard 5-field cron: minute hour day-of-month month day-of-week
+ * @param {string} cron
+ * @returns {string}
+ */
+function describeCron(cron) {
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    return `Invalid cron expression (expected 5 fields, got ${parts.length})`;
+  }
+
+  const [minute, hour, dom, month, dow] = parts;
+
+  const allStar = (f) => f === '*';
+  const isStep = (f) => f.includes('/');
+  const stepVal = (f) => parseInt(f.split('/')[1]);
+
+  // Every minute: * * * * *
+  if (allStar(minute) && allStar(hour) && allStar(dom) && allStar(month) && allStar(dow)) {
+    return 'Every minute';
+  }
+
+  // */N minutes: */N * * * *
+  if (isStep(minute) && allStar(hour) && allStar(dom) && allStar(month) && allStar(dow)) {
+    const n = stepVal(minute);
+    return n === 1 ? 'Every minute' : `Every ${n} minutes`;
+  }
+
+  // Every hour at minute M: M * * * *
+  if (!allStar(minute) && !isStep(minute) && allStar(hour) && allStar(dom) && allStar(month) && allStar(dow)) {
+    const m = parseInt(minute);
+    return m === 0 ? 'Every hour, on the hour' : `Every hour at minute ${m}`;
+  }
+
+  // Every N hours: 0 */N * * *  (or M */N * * *)
+  if (!isStep(minute) && isStep(hour) && allStar(dom) && allStar(month) && allStar(dow)) {
+    const n = stepVal(hour);
+    const m = parseInt(minute);
+    const hourPart = n === 1 ? 'Every hour' : `Every ${n} hours`;
+    return m === 0 ? hourPart : `${hourPart} at minute ${m}`;
+  }
+
+  // Specific hour and minute: M H * * *
+  if (!allStar(minute) && !isStep(minute) && !allStar(hour) && !isStep(hour) && allStar(dom) && allStar(month) && allStar(dow)) {
+    const timeStr = formatTime(hour, minute);
+    return `Every day at ${timeStr}`;
+  }
+
+  // Specific day of week: M H * * D
+  if (!allStar(minute) && !allStar(hour) && allStar(dom) && allStar(month) && !allStar(dow)) {
+    const timeStr = formatTime(hour, minute);
+    const days = parseDow(dow);
+    return `${days} at ${timeStr}`;
+  }
+
+  // Specific day of month: M H D * *
+  if (!allStar(minute) && !allStar(hour) && !allStar(dom) && !isStep(dom) && allStar(month) && allStar(dow)) {
+    const timeStr = formatTime(hour, minute);
+    const d = ordinal(parseInt(dom));
+    return `On the ${d} of every month at ${timeStr}`;
+  }
+
+  // Specific month and day: M H D Mo *
+  if (!allStar(minute) && !allStar(hour) && !allStar(dom) && !allStar(month) && allStar(dow)) {
+    const timeStr = formatTime(hour, minute);
+    const d = ordinal(parseInt(dom));
+    const mo = parseMonth(month);
+    return `Every year on ${mo} ${d} at ${timeStr}`;
+  }
+
+  // Fallback: describe each field
+  return describeFallback(minute, hour, dom, month, dow);
+}
+
+function formatTime(hour, minute) {
+  const h = parseInt(hour);
+  const m = parseInt(minute);
+  const period = h >= 12 ? 'PM' : 'AM';
+  const h12 = h === 0 ? 12 : h > 12 ? h - 12 : h;
+  return m === 0 ? `${h12}${period}` : `${h12}:${String(m).padStart(2, '0')}${period}`;
+}
+
+function ordinal(n) {
+  const s = ['th', 'st', 'nd', 'rd'];
+  const v = n % 100;
+  return n + (s[(v - 20) % 10] || s[v] || s[0]);
+}
+
+const DOW_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const MONTH_NAMES = ['', 'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December'];
+
+function parseDow(field) {
+  const indices = expandField(field, 0, 7).map(d => d % 7);
+  if (indices.length === 5 && !indices.includes(0) && !indices.includes(6)) return 'Weekdays';
+  if (indices.length === 2 && indices.includes(0) && indices.includes(6)) return 'Weekends';
+  return 'Every ' + indices.map(i => DOW_NAMES[i]).join(', ');
+}
+
+function parseMonth(field) {
+  const indices = expandField(field, 1, 12);
+  return indices.map(i => MONTH_NAMES[i]).join(', ');
+}
+
+function expandField(field, min, max) {
+  const results = new Set();
+  for (const part of field.split(',')) {
+    if (part.includes('/')) {
+      const [range, step] = part.split('/');
+      const s = parseInt(step);
+      const start = range === '*' ? min : parseInt(range);
+      for (let i = start; i <= max; i += s) results.add(i);
+    } else if (part.includes('-')) {
+      const [a, b] = part.split('-').map(Number);
+      for (let i = a; i <= b; i++) results.add(i);
+    } else if (part === '*') {
+      for (let i = min; i <= max; i++) results.add(i);
+    } else {
+      results.add(parseInt(part));
+    }
+  }
+  return [...results].sort((a, b) => a - b);
+}
+
+function describeFallback(minute, hour, dom, month, dow) {
+  const parts = [];
+  if (minute !== '*') parts.push(`minute ${minute}`);
+  if (hour !== '*') parts.push(`hour ${hour}`);
+  if (dom !== '*') parts.push(`day ${dom}`);
+  if (month !== '*') parts.push(`month ${month}`);
+  if (dow !== '*') parts.push(`weekday ${dow}`);
+  return `Runs at: ${parts.join(', ')}`;
+}
+
+module.exports = { describeCron };

package/library/html-server.js

@@ -7,6 +7,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const escape = require('escape-html');
 
 class HtmlServer {
   log;
@@ -44,23 +45,6 @@ class HtmlServer {
     return this.templates.has(templateName);
   }
 
-  // HTML Utilities
-  escapeHtml(text) {
-    if (typeof text !== 'string') {
-      return String(text);
-    }
-    
-    const map = {
-      '&': '&',
-      '<': '&lt;',
-      '>': '&gt;',
-      '"': '&quot;',
-      "'": '&#39;'
-    };
-    
-    return text.replace(/[&<>"']/g, function(m) { return map[m]; });
-  }
-
   // Page Rendering - simple template substitution
   renderPage(templateName, title, content, options = {}) {
     const template = this.getTemplate(templateName);
@@ -80,21 +64,21 @@ class HtmlServer {
     
     // Perform template replacements
     let html = template
-      .replace(/\[%title%\]/g, this.escapeHtml(title))
+      .replace(/\[%title%\]/g, escape(title))
       .replace(/\[%content%\]/g, content) // Content is assumed to be already-safe HTML
-      .replace(/\[%ver%\]/g, this.escapeHtml(renderOptions.version))
-      .replace(/\[%download-date%\]/g, this.escapeHtml(renderOptions.downloadDate))
-      .replace(/\[%total-resources%\]/g, this.escapeHtml(renderOptions.totalResources.toLocaleString()))
-      .replace(/\[%total-packages%\]/g, this.escapeHtml(renderOptions.totalPackages.toLocaleString()))
-      .replace(/\[%endpoint-path%\]/g, this.escapeHtml(renderOptions.endpointpath))
-      .replace(/\[%fhir-version%\]/g, this.escapeHtml(renderOptions.fhirversion))
-      .replace(/\[%ms%\]/g, this.escapeHtml(renderOptions.processingTime.toString()));
+      .replace(/\[%ver%\]/g, escape(renderOptions.version))
+      .replace(/\[%download-date%\]/g, escape(renderOptions.downloadDate))
+      .replace(/\[%total-resources%\]/g, escape(renderOptions.totalResources.toLocaleString()))
+      .replace(/\[%total-packages%\]/g, escape(renderOptions.totalPackages.toLocaleString()))
+      .replace(/\[%endpoint-path%\]/g, escape(renderOptions.endpointpath))
+      .replace(/\[%fhir-version%\]/g, escape(renderOptions.fhirversion))
+      .replace(/\[%ms%\]/g, escape(renderOptions.processingTime.toString()));
     
     // Handle any custom template variables
     if (options.templateVars) {
       for (const [key, value] of Object.entries(options.templateVars)) {
         const placeholder = `[%${key}%]`;
-        const escapedValue = typeof value === 'string' ? this.escapeHtml(value) : String(value);
+        const escapedValue = typeof value === 'string' ? escape(value) : String(value);
         html = html.replace(new RegExp(placeholder.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), escapedValue);
       }
     }
@@ -110,7 +94,7 @@ class HtmlServer {
       res.send(html);
     } catch (error) {
       this.log.error('[HtmlServer] Error rendering page:', error);
-      res.status(500).send(`<h1>Error</h1><p>Failed to render page: ${this.escapeHtml(error.message)}</p>`);
+      res.status(500).send(`<h1>Error</h1><p>Failed to render page: ${escape(error.message)}</p>`);
     }
   }
 
@@ -118,7 +102,7 @@ class HtmlServer {
     const errorContent = `
       <div class="alert alert-danger">
         <h4>Error</h4>
-        <p>${this.escapeHtml(error.message || error)}</p>
+        <p>${escape(error.message || error)}</p>
       </div>
     `;
     
@@ -128,7 +112,7 @@ class HtmlServer {
       res.send(html);
     } catch (renderError) {
       this.log.error('[HtmlServer] Error rendering error page:', renderError);
-      res.status(statusCode).send(`<h1>Error</h1><p>Failed to render error page: ${this.escapeHtml(renderError.message)}</p>`);
+      res.status(statusCode).send(`<h1>Error</h1><p>Failed to render error page: ${escape(renderError.message)}</p>`);
     }
   }
 

package/library/html.js

@@ -1,4 +1,6 @@
 const {validateParameter, validateOptionalParameter} = require("./utilities");
+const escape = require('escape-html');
+
 const NodeType = {
   Document: 'Document',
   Element: 'Element',
@@ -723,7 +725,7 @@ class XhtmlNode {
     const newline = effectivePretty ? '\n' : '';
 
     if (this.nodeType === NodeType.Text) {
-      return this.#escapeHtml(this.content || '');
+      return escape(this.content || '');
     }
 
     if (this.nodeType === NodeType.Comment) {
@@ -771,13 +773,6 @@ class XhtmlNode {
     return '';
   }
 
-  #escapeHtml(text) {
-    return text
-      .replace(/&/g, '&')
-      .replace(/</g, '&lt;')
-      .replace(/>/g, '&gt;');
-  }
-
   #escapeAttr(text) {
     return String(text)
       .replace(/&/g, '&amp;')

package/library/languages.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const os = require('os');
-const {validateParameter, validateOptionalParameter, Utilities} = require("./utilities");
+const {validateOptionalParameter, Utilities} = require("./utilities");
+const {join} = require("node:path");
 
 /**
  * Language part types for matching depth
@@ -22,6 +23,7 @@ class LanguageEntry {
   constructor() {
     this.code = '';
     this.displays = [];
+    this.translations = new Map(); // language code -> translated display name
   }
 }
 
@@ -120,7 +122,7 @@ class Language {
     if (index < parts.length) {
       this.language = parts[index];
       if (this.language != '*' && languageDefinitions && !languageDefinitions.languages.has(this.language)) {
-        throw new Error("The language '"+this.language+"' in the code '"+this.language+"' is not valid");
+        throw new Error("The language '"+this.language+"' in the code '"+this.code+"' is not valid");
       }
       index++;
     }
@@ -130,7 +132,7 @@ class Language {
       const part = parts[index];
       if (part.length === 3 && /^[a-zA-Z]{3}$/.test(part)) {
         if (languageDefinitions && !languageDefinitions.extLanguages.has(part)) {
-          throw new Error("The extLanguage '"+part+"' in the code '"+code+"' is not valid");
+          throw new Error("The extLanguage '"+part+"' in the code '"+this.code+"' is not valid");
         }
         this.extLang.push(part.toLowerCase());
         index++;
@@ -144,7 +146,7 @@ class Language {
       const part = parts[index];
       if (part.length === 4 && /^[a-zA-Z]{4}$/.test(part)) {
         if (languageDefinitions && !languageDefinitions.scripts.has(part)) {
-          throw new Error("The script '"+part+"' in the code '"+code+"' is not valid");
+          throw new Error("The script '"+part+"' in the code '"+this.code+"' is not valid");
         }
         this.script = part.charAt(0).toUpperCase() + part.slice(1).toLowerCase();
         index++;
@@ -157,7 +159,7 @@ class Language {
       if ((part.length === 2 && /^[a-zA-Z]{2}$/.test(part)) ||
         (part.length === 3 && /^[0-9]{3}$/.test(part))) {
         if (languageDefinitions && !languageDefinitions.regions.has(part)) {
-          throw new Error("The region '"+part+"' in the code '"+code+"' is not valid");
+          throw new Error("The region '"+part+"' in the code '"+this.code+"' is not valid");
         }
         this.region = part.toUpperCase();
         index++;
@@ -187,9 +189,10 @@ class Language {
       } else if (part.length === 1 && part !== 'x') {
         // Extension
         this.extension = part + '-' + parts.slice(index + 1).join('-');
+        index++;
         break;
       } else {
-        index++;
+        throw new Error("Unable to recognised '"+parts[index]+"' as a valid part in the language code "+this.code);
       }
     }
   }
@@ -496,10 +499,12 @@ class LanguageDefinitions {
   /**
    * Load definitions from IETF language subtag registry file
    */
-  static async fromFile(filePath) {
+  static async fromFiles(filePath) {
     const definitions = new LanguageDefinitions();
-    const content = fs.readFileSync(filePath, 'utf8');
+    const content = fs.readFileSync(join(filePath, "lang.dat"), 'utf8');
     definitions._load(content);
+    definitions._loadTranslations(join(filePath, "languages.csv"), definitions.languages);
+    definitions._loadTranslations(join(filePath, "regions.csv"), definitions.regions);
     return definitions;
   }
 
@@ -589,6 +594,88 @@ class LanguageDefinitions {
     return [vars, i];
   }
 
+  /**
+   * Load translations from a CSV file into an existing map of entries.
+   * CSV format: code,english,french,german,spanish,arabic,chinese,russian,japanese,swahili
+   * The language codes for the translation columns:
+   */
+  _loadTranslations(csvPath, targetMap) {
+    if (!fs.existsSync(csvPath)) {
+      return;
+    }
+    const content = fs.readFileSync(csvPath, 'utf8');
+    const lines = content.split('\n');
+    if (lines.length < 2) return;
+
+    const header = this._parseCsvLine(lines[0]);
+    // header[0] = 'code', header[1..] = language names mapped to codes
+    const langCodeMap = {
+      'english': 'en',
+      'french': 'fr',
+      'german': 'de',
+      'spanish': 'es',
+      'arabic': 'ar',
+      'chinese': 'zh',
+      'russian': 'ru',
+      'japanese': 'ja',
+      'swahili': 'sw'
+    };
+
+    const columnLangs = header.slice(1).map(h => langCodeMap[h.toLowerCase()] || h.toLowerCase());
+
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      const fields = this._parseCsvLine(line);
+      if (fields.length < 2) continue;
+
+      const code = fields[0];
+      const entry = targetMap.get(code);
+      if (!entry) continue;
+
+      for (let j = 1; j < fields.length && j < header.length; j++) {
+        const langCode = columnLangs[j - 1];
+        const value = fields[j];
+        if (value) {
+          entry.translations.set(langCode, value);
+        }
+      }
+    }
+  }
+
+  /**
+   * Parse a single CSV line, handling quoted fields with commas
+   */
+  _parseCsvLine(line) {
+    const fields = [];
+    let current = '';
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+      const ch = line[i];
+      if (inQuotes) {
+        if (ch === '"' && i + 1 < line.length && line[i + 1] === '"') {
+          current += '"';
+          i++;
+        } else if (ch === '"') {
+          inQuotes = false;
+        } else {
+          current += ch;
+        }
+      } else {
+        if (ch === '"') {
+          inQuotes = true;
+        } else if (ch === ',') {
+          fields.push(current);
+          current = '';
+        } else {
+          current += ch;
+        }
+      }
+    }
+    fields.push(current);
+    return fields;
+  }
+
   /**
    * Load language entry
    */
@@ -671,39 +758,56 @@ class LanguageDefinitions {
    *
    * @return {Language} parsed language (or null)
    */
-  parse(code) {
-    if (!code) return null;
+  parse(code, msg) {
+    if (!code) {
+      if (msg) {
+        msg.message = 'No code provided';
+      }
+      return null;
+    }
 
     // Check cache first
     if (this.parsed.has(code)) {
       return this.parsed.get(code);
     }
 
-    const parts = code.split('-');
-    let index = 0;
-
-    // Validate language
-    if (index >= parts.length) return null;
-    const langCode = parts[index].toLowerCase();
-    if (!this.languages.has(langCode) && langCode !== '*') {
-      return null; // Invalid language code
+    try {
+      const lang = new Language(code, this);
+      // Cache the result
+      this.parsed.set(code, lang);
+      return lang;
+    } catch (e) {
+      if (msg) {
+        msg.message = e.message;
+      }
+      return null;
     }
-
-    const lang = new Language(code);
-
-    // Cache the result
-    this.parsed.set(code, lang);
-    return lang;
   }
 
   /**
-   * Get display name for language
+   * Get display name for language, optionally translated
    */
   getDisplayForLang(code, displayIndex = 0) {
     const lang = this.languages.get(code);
     return lang && lang.displays[displayIndex] ? lang.displays[displayIndex] : code;
   }
 
+  /**
+   * Get translated display name for a language code
+   * @param {string} code - the language subtag
+   * @param {string} displayLang - the language to translate into (e.g. 'fr', 'de')
+   * @returns {string} translated name, or English name, or the code itself
+   */
+  getTranslatedDisplayForLang(code, displayLang) {
+    const lang = this.languages.get(code);
+    if (!lang) return code;
+    if (displayLang) {
+      const translated = lang.translations.get(displayLang);
+      if (translated) return translated;
+    }
+    return lang.displays[0] || code;
+  }
+
   /**
    * Get display name for region
    */
@@ -712,6 +816,22 @@ class LanguageDefinitions {
     return region && region.displays[displayIndex] ? region.displays[displayIndex] : code;
   }
 
+  /**
+   * Get translated display name for a region code
+   * @param {string} code - the region subtag
+   * @param {string} displayLang - the language to translate into (e.g. 'fr', 'de')
+   * @returns {string} translated name, or English name, or the code itself
+   */
+  getTranslatedDisplayForRegion(code, displayLang) {
+    const region = this.regions.get(code);
+    if (!region) return code;
+    if (displayLang) {
+      const translated = region.translations.get(displayLang);
+      if (translated) return translated;
+    }
+    return region.displays[0] || code;
+  }
+
   /**
    * Get display name for script
    */
@@ -734,18 +854,21 @@ class LanguageDefinitions {
     }
 
     let result = this.getDisplayForLang(lang.language, displayIndex);
-
     const parts = [];
-    if (lang.script) {
-      parts.push(`Script=${this.getDisplayForScript(lang.script, 0)}`);
-    }
-    if (lang.region) {
-      parts.push(`Region=${this.getDisplayForRegion(lang.region, 0)}`);
-    }
-    if (lang.variant) {
-      const variant = this.variants.get(lang.variant);
-      const variantDisplay = variant && variant.displays[0] ? variant.displays[0] : lang.variant;
-      parts.push(`Variant=${variantDisplay}`);
+    if (lang.region && !lang.script && !lang.variant) {
+      parts.push(`${this.getDisplayForRegion(lang.region, 0)}`);
+    } else {
+      if (lang.script) {
+        parts.push(`Script=${this.getDisplayForScript(lang.script, 0)}`);
+      }
+      if (lang.region) {
+        parts.push(`Region=${this.getDisplayForRegion(lang.region, 0)}`);
+      }
+      if (lang.variant) {
+        const variant = this.variants.get(lang.variant);
+        const variantDisplay = variant && variant.displays[0] ? variant.displays[0] : lang.variant;
+        parts.push(`Variant=${variantDisplay}`);
+      }
     }
 
     if (parts.length > 0) {
@@ -776,4 +899,4 @@ module.exports = {
   LanguageScript,
   LanguageRegion,
   LanguageVariant
-};
+};

package/library/package-manager.js

@@ -413,6 +413,7 @@ class PackageManager {
                 }
             } catch (error) {
                 // Try next server
+                console.info("Error looking for "+packageId+" on "+server+": "+error);
                 continue;
             }
         }
@@ -586,6 +587,50 @@ class PackageManager {
         }
     }
 
+    /**
+     * Fetch a package directly from a URL (e.g., a CI build .tgz)
+     * @param {string} url - URL to a package.tgz file
+     * @returns {Promise<string>} Path to extracted package folder
+     */
+    async fetchUrl(url) {
+        console.log("Fetch Package from URL: " + url);
+        const client = new CIBuildClient();
+        const packageData = await client.fetchFromUrlSpecific(url);
+
+        // Extract to a temp location to read package.json for name and version
+        const tempKey = `_url_temp_${Date.now()}`;
+        const tempPath = await this.extractToCache(tempKey, 'url', packageData);
+        const tempFullPath = path.join(this.cacheFolder, tempPath);
+
+        // Read package name and version from the extracted package
+        const pkgJsonPath = path.join(tempFullPath, 'package', 'package.json');
+        const pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf8'));
+        const packageId = pkgJson.name;
+        const version = pkgJson.version;
+
+        if (!packageId || !version) {
+            throw new Error(`Package at ${url} has no name or version in package.json`);
+        }
+
+        // Use the same cache key format as npm packages
+        const finalName = `${packageId}#${version}`;
+        const finalPath = path.join(this.cacheFolder, finalName);
+
+        // If it already exists, the same package is already loaded - that's a config error
+        try {
+            await fs.access(finalPath);
+            await fs.rm(tempFullPath, { recursive: true, force: true });
+            throw new Error(`Package ${finalName} already exists in cache. Check library config for duplicates (url: ${url})`);
+        } catch (e) {
+            if (e.message.includes('already exists')) throw e;
+            // Doesn't exist yet, rename temp to final
+            await fs.rename(tempFullPath, finalPath);
+        }
+
+        this.totalDownloaded = this.totalDownloaded + packageData.length;
+        return finalName;
+    }
+
     /**
      * Extract package to cache folder
      * @param {string} packageId - Package identifier
@@ -856,7 +901,9 @@ class PackageContentLoader {
     }
 
     fhirVersion() {
-        return this.package.fhirVersions[0];
+        // Handle both modern 'fhirVersions' and older 'fhir-version-list' formats
+        const versions = this.package.fhirVersions || this.package['fhir-version-list'];
+        return versions ? versions[0] : undefined;
     }
 
     id() {