fhirsmith 0.18.1 → 1.0.0

package/tx/importers/tx-import.js

@@ -5,6 +5,7 @@ const chalk = require('chalk');
 const fs = require('fs');
 const path = require('path');
 const { getConfigManager } = require('./tx-import-settings');
+const terminal = require('./terminal');
 
 class TerminologyImportCLI {
   constructor() {
@@ -71,7 +72,7 @@ class TerminologyImportCLI {
   }
 
   discoverAndLoadModules() {
-    console.log("Looking in " + __dirname);
+    terminal.log("Looking in " + __dirname);
 
     const moduleFiles = fs.readdirSync(__dirname)
       .filter(file => file.endsWith('.module.js') && !file.startsWith('_'))
@@ -107,10 +108,10 @@ class TerminologyImportCLI {
         if (this.isValidModule(moduleInstance)) {
           this.registerModule(moduleInstance);
         } else {
-          console.warn(chalk.yellow(`Warning: Invalid module format in ${moduleFile}`));
+          terminal.warn(chalk.yellow(`Warning: Invalid module format in ${moduleFile}`));
         }
       } catch (error) {
-        console.warn(chalk.yellow(`Warning: Failed to load module ${moduleFile}: ${error.message}`));
+        terminal.warn(chalk.yellow(`Warning: Failed to load module ${moduleFile}: ${error.message}`));
       }
     }
   }
@@ -127,7 +128,7 @@ class TerminologyImportCLI {
     const name = module.getName();
 
     if (this.modules.has(name)) {
-      console.warn(chalk.yellow(`Warning: Module ${name} already registered, skipping`));
+      terminal.warn(chalk.yellow(`Warning: Module ${name} already registered, skipping`));
       return;
     }
 
@@ -141,35 +142,35 @@ class TerminologyImportCLI {
     // Let the module register its subcommands
     module.registerCommands(terminologyCommand, this.program.opts());
 
-    console.log(chalk.green(`✓ Loaded ${name} module`));
+    terminal.log(chalk.green(`✓ Loaded ${name} module`));
   }
 
   listTerminologies() {
-    console.log(chalk.blue.bold('🏥 Available Terminology Importers\\n'));
+    terminal.log(chalk.blue.bold('🏥 Available Terminology Importers\\n'));
 
     if (this.modules.size === 0) {
-      console.log(chalk.yellow('No terminology modules found.'));
-      console.log(chalk.gray('Add modules to the ./modules/ directory.'));
+      terminal.log(chalk.yellow('No terminology modules found.'));
+      terminal.log(chalk.gray('Add modules to the ./modules/ directory.'));
       return;
     }
 
     for (const [name, module] of this.modules) {
-      console.log(chalk.cyan(`${name}:`));
-      console.log(`  ${module.getDescription()}`);
+      terminal.log(chalk.cyan(`${name}:`));
+      terminal.log(`  ${module.getDescription()}`);
 
       if (module.getSupportedFormats) {
         const formats = module.getSupportedFormats();
-        console.log(chalk.gray(`  Formats: ${formats.join(', ')}`));
+        terminal.log(chalk.gray(`  Formats: ${formats.join(', ')}`));
       }
 
       if (module.getEstimatedDuration) {
-        console.log(chalk.gray(`  Typical duration: ${module.getEstimatedDuration()}`));
+        terminal.log(chalk.gray(`  Typical duration: ${module.getEstimatedDuration()}`));
       }
 
-      console.log('');
+      terminal.log('');
     }
 
-    console.log(chalk.gray('Use "tx-import <terminology> --help" for specific options'));
+    terminal.log(chalk.gray('Use "tx-import <terminology> --help" for specific options'));
   }
 
   showHelp(commandName) {
@@ -179,27 +180,27 @@ class TerminologyImportCLI {
     }
 
     if (this.modules.has(commandName)) {
-      console.log(chalk.blue.bold(`Help for ${commandName}:\\n`));
+      terminal.log(chalk.blue.bold(`Help for ${commandName}:\\n`));
       this.program.commands
         .find(cmd => cmd.name() === commandName)
         ?.help();
     } else {
-      console.log(chalk.red(`Unknown command: ${commandName}`));
+      terminal.log(chalk.red(`Unknown command: ${commandName}`));
       this.listTerminologies();
     }
   }
 
   showConfigHelp() {
-    console.log(chalk.blue.bold('📁 Configuration Management\\n'));
-    console.log('Available configuration commands:');
-    console.log('  tx-import config:show     Show saved configuration history');
-    console.log('  tx-import config:clear    Clear saved configuration history');
-    console.log('  tx-import config:export   Export configuration to file');
-    console.log('  tx-import config:import   Import configuration from file');
-    console.log('\\nExamples:');
-    console.log('  tx-import config:show --terminology unii');
-    console.log('  tx-import config:clear --terminology loinc');
-    console.log('  tx-import config:export --output my-config.json');
+    terminal.log(chalk.blue.bold('📁 Configuration Management\\n'));
+    terminal.log('Available configuration commands:');
+    terminal.log('  tx-import config:show     Show saved configuration history');
+    terminal.log('  tx-import config:clear    Clear saved configuration history');
+    terminal.log('  tx-import config:export   Export configuration to file');
+    terminal.log('  tx-import config:import   Import configuration from file');
+    terminal.log('\\nExamples:');
+    terminal.log('  tx-import config:show --terminology unii');
+    terminal.log('  tx-import config:clear --terminology loinc');
+    terminal.log('  tx-import config:export --output my-config.json');
   }
 
   showConfig(options) {
@@ -210,30 +211,30 @@ class TerminologyImportCLI {
       const config = configManager.getPreviousConfig(options.terminology);
 
       if (Object.keys(config).length === 0) {
-        console.log(chalk.yellow(`No saved configuration found for ${options.terminology}`));
+        terminal.log(chalk.yellow(`No saved configuration found for ${options.terminology}`));
         return;
       }
 
-      console.log(chalk.blue.bold(`📋 Saved Configuration for ${options.terminology}:\\n`));
+      terminal.log(chalk.blue.bold(`📋 Saved Configuration for ${options.terminology}:\\n`));
 
       if (config.lastUsed) {
-        console.log(`Last used: ${chalk.white(new Date(config.lastUsed).toLocaleString())}`);
+        terminal.log(`Last used: ${chalk.white(new Date(config.lastUsed).toLocaleString())}`);
       }
 
       Object.entries(config).forEach(([key, value]) => {
         if (key !== 'lastUsed' && key !== 'recentSources') {
           if (Array.isArray(value)) {
-            console.log(`  ${key}: ${chalk.white(value.join(', '))}`);
+            terminal.log(`  ${key}: ${chalk.white(value.join(', '))}`);
           } else {
-            console.log(`  ${key}: ${chalk.white(value)}`);
+            terminal.log(`  ${key}: ${chalk.white(value)}`);
           }
         }
       });
 
       if (config.recentSources && config.recentSources.length > 0) {
-        console.log(`\\n  Recent sources:`);
+        terminal.log(`\\n  Recent sources:`);
         config.recentSources.forEach((src, index) => {
-          console.log(`    ${index + 1}. ${chalk.gray(src)}`);
+          terminal.log(`    ${index + 1}. ${chalk.gray(src)}`);
         });
       }
 
@@ -242,24 +243,24 @@ class TerminologyImportCLI {
       const allHistory = configManager.history;
 
       if (Object.keys(allHistory).length === 0) {
-        console.log(chalk.yellow('No saved configurations found'));
+        terminal.log(chalk.yellow('No saved configurations found'));
         return;
       }
 
-      console.log(chalk.blue.bold('📋 All Saved Configurations:\\n'));
+      terminal.log(chalk.blue.bold('📋 All Saved Configurations:\\n'));
 
       Object.entries(allHistory).forEach(([terminology, config]) => {
-        console.log(chalk.cyan(`${terminology}:`));
+        terminal.log(chalk.cyan(`${terminology}:`));
         if (config.lastUsed) {
-          console.log(`  Last used: ${chalk.white(new Date(config.lastUsed).toLocaleString())}`);
+          terminal.log(`  Last used: ${chalk.white(new Date(config.lastUsed).toLocaleString())}`);
         }
         if (config.source) {
-          console.log(`  Source: ${chalk.gray(config.source)}`);
+          terminal.log(`  Source: ${chalk.gray(config.source)}`);
         }
         if (config.version) {
-          console.log(`  Version: ${chalk.gray(config.version)}`);
+          terminal.log(`  Version: ${chalk.gray(config.version)}`);
         }
-        console.log('');
+        terminal.log('');
       });
     }
   }
@@ -278,9 +279,9 @@ class TerminologyImportCLI {
 
       if (confirmed) {
         configManager.clearAllHistory();
-        console.log(chalk.green('✓ All configuration history cleared'));
+        terminal.log(chalk.green('✓ All configuration history cleared'));
       } else {
-        console.log(chalk.yellow('Configuration clear cancelled'));
+        terminal.log(chalk.yellow('Configuration clear cancelled'));
       }
 
     } else if (options.terminology) {
@@ -293,14 +294,14 @@ class TerminologyImportCLI {
 
       if (confirmed) {
         configManager.clearHistory(options.terminology);
-        console.log(chalk.green(`✓ Configuration history cleared for ${options.terminology}`));
+        terminal.log(chalk.green(`✓ Configuration history cleared for ${options.terminology}`));
       } else {
-        console.log(chalk.yellow('Configuration clear cancelled'));
+        terminal.log(chalk.yellow('Configuration clear cancelled'));
       }
 
     } else {
-      console.log(chalk.red('Please specify --terminology <name> or --all'));
-      console.log('Example: tx-import config:clear --terminology unii');
+      terminal.log(chalk.red('Please specify --terminology <name> or --all'));
+      terminal.log('Example: tx-import config:clear --terminology unii');
     }
   }
 
@@ -310,9 +311,9 @@ class TerminologyImportCLI {
 
     try {
       fs.writeFileSync(options.output, JSON.stringify(data, null, 2));
-      console.log(chalk.green(`✓ Configuration exported to ${options.output}`));
+      terminal.log(chalk.green(`✓ Configuration exported to ${options.output}`));
     } catch (error) {
-      console.log(chalk.red(`✗ Export failed: ${error.message}`));
+      terminal.log(chalk.red(`✗ Export failed: ${error.message}`));
     }
   }
 
@@ -333,16 +334,16 @@ class TerminologyImportCLI {
     try {
       const data = JSON.parse(fs.readFileSync(options.input, 'utf8'));
       configManager.importConfig(data);
-      console.log(chalk.green(`✓ Configuration imported from ${options.input}`));
+      terminal.log(chalk.green(`✓ Configuration imported from ${options.input}`));
     } catch (error) {
-      console.log(chalk.red(`✗ Import failed: ${error.message}`));
+      terminal.log(chalk.red(`✗ Import failed: ${error.message}`));
     }
   }
 
   run() {
     // Show logo and loaded modules
-    console.log(chalk.blue.bold('🏥 TX-Import - Medical Terminology Import Tool'));
-    console.log(chalk.gray(`Loaded ${this.modules.size} terminology module(s)\\n`));
+    terminal.log(chalk.blue.bold('🏥 TX-Import - Medical Terminology Import Tool'));
+    terminal.log(chalk.gray(`Loaded ${this.modules.size} terminology module(s)\\n`));
 
     this.program.parse();
   }

package/tx/library/canonical-resource.js

@@ -1,3 +1,4 @@
+const crypto = require("crypto");
 const {VersionUtilities, VersionPrecision} = require("../../library/version-utilities");
 const {Issue} = require("./operation-outcome");
 
@@ -80,6 +81,54 @@ class CanonicalResource {
     checkContained(this.jsonObj);
   }
 
+  /**
+   * The hash ExpansionCache.computeKey puts in an expansion's cache key for this
+   * resource: the first 16 hex characters of the sha256 of JSON.stringify(json). Computing
+   * it means serialising the whole resource, and a $cache-control cache hands every
+   * resource it holds to every $expand that carries its cache-id, so it is worked out
+   * once and remembered.
+   *
+   * @param {Object} json - the resource (R5 form)
+   * @returns {string}
+   */
+  static computeExpansionKeyHash(json) {
+    return crypto.createHash('sha256')
+      .update(JSON.stringify(json))
+      .digest('hex')
+      .substring(0, 16);
+  }
+
+  /**
+   * This resource's expansion-key hash (see computeExpansionKeyHash), computed on first
+   * use and then remembered. Nothing writes to jsonObj once a resource is in use (the r4/r5 conversion
+   * happens in the constructor, before anything can ask), and the memo is tied to the
+   * jsonObj it was computed from, so replacing jsonObj gets a new hash.
+   * @returns {string}
+   */
+  expansionKeyHash() {
+    const memo = this._expansionKeyHashMemo;
+    if (memo && memo.json === this.jsonObj) {
+      return memo.hash;
+    }
+    return this.setExpansionKeyHash(CanonicalResource.computeExpansionKeyHash(this.jsonObj));
+  }
+
+  /**
+   * Record the expansion-key hash for a store that already knows it, so it is never
+   * recomputed. It must be computeExpansionKeyHash(this.jsonObj). Non-enumerable, so it never serialises
+   * into a response or log, and structuredClone/spread don't copy it onto a different
+   * resource.
+   * @param {string} hash
+   * @returns {string} the hash
+   */
+  setExpansionKeyHash(hash) {
+    Object.defineProperty(this, '_expansionKeyHashMemo', {
+      value: { json: this.jsonObj, hash },
+      enumerable: false, configurable: true, writable: true
+    });
+    return hash;
+  }
+
   get resourceType() {
     return this.jsonObj.resourceType;
   }

package/tx/library/codesystem.js

@@ -4,6 +4,7 @@ const {codeSystemFromR5, codeSystemToR5} = require("../xversion/xv-codesystem");
 const {getValuePrimitive} = require("../../library/utilities");
 const {VersionUtilities} = require("../../library/version-utilities");
 const {countNested} = require("./nesting-limit");
+const regexUtilities = require("../../library/regex-utilities");
 
 const CodeSystemContentMode = Object.freeze({
   Complete: 'complete',
@@ -644,21 +645,109 @@ class CodeSystem extends CanonicalResource {
     this.jsonObj.id = value;
   }
 
+  /**
+   * @returns {string|null} the supplement's type, from the codesystem-supplement-type extension
+   *   (lang-pack, properties, extension-codes...), or null if it doesn't say
+   */
+  supplementType() {
+    const ext = (this.jsonObj.extension || []).find(x => x.url == 'http://hl7.org/fhir/StructureDefinition/codesystem-supplement-type');
+    return ext ? getValuePrimitive(ext) : null;
+  }
+
+  /**
+   * @returns {boolean} true if this is a language pack (codesystem-supplement-type = lang-pack). A
+   *   language pack is only used when it is referenced, unless it is also global (isGlobalSupplement)
+   */
   isLangPack() {
-    // todo: this is a temporary work around until fhir.tx.support.r4#0.37.0 is released that properly marks this as a language pack
+    return this.supplementType() === 'lang-pack';
+  }
+
+  /**
+   * A global supplement is used for the code system it supplements whether or not it is
+   * referenced: a lang-pack or extension-codes supplement marked with codesystem-supplement-global
+   * = true. Any other supplement is only used when it is referenced.
+   *
+   * @returns {boolean} true if this is a global supplement
+   */
+  isGlobalSupplement() {
+    // todo: a work around until fhir.tx.support.r4 is re-released with this language pack marked global
     if (this.jsonObj.url === 'https://terminology.dhp.uz/fhir/CodeSystem/loinc-supplement-uz') {
       return true;
     }
-    // a global language pack is used whether or not it is referenced. The code was 'lang-pack'
-    // until Oct 2026; it is still accepted, so that supplements marked the old way keep working
-    return (this.jsonObj.extension || []).find(x => x.url == 'http://hl7.org/fhir/StructureDefinition/codesystem-supplement-type'
-      && ['global-lang-pack', 'lang-pack'].includes(getValuePrimitive(x)));
+    if (!['lang-pack', 'extension-codes'].includes(this.supplementType())) {
+      return false;
+    }
+    const ext = (this.jsonObj.extension || []).find(x => x.url == 'http://hl7.org/fhir/StructureDefinition/codesystem-supplement-global');
+    return !!ext && getValuePrimitive(ext) === true;
+  }
+
+  /**
+   * @returns {boolean} true if this is an extension-codes supplement (codesystem-supplement-type) - one
+   *   that defines codes in the reserved code space of the code system it supplements
+   */
+  isExtensionCodes() {
+    return this.supplementType() === 'extension-codes';
+  }
+
+  /**
+   * The code spaces the code system's steward has reserved for users to define their own codes in (the
+   * codesystem-reservedCodeSpace extension: reservedCodeSpace is a regular expression that a code must
+   * match in full, and default-display is the display of a code in the space that nothing defines -
+   * 'User-assigned' if it doesn't say). Compiled with re2, since the expressions can come from a request
+   *
+   * @returns {{regex: Object, defaultDisplay: string}[]} the code spaces (empty if there are none)
+   */
+  reservedCodeSpaces() {
+    if (this._reservedCodeSpaces === undefined) {
+      this._reservedCodeSpaces = [];
+      for (const ext of (this.jsonObj.extension || []).filter(x => x.url == 'http://hl7.org/fhir/StructureDefinition/codesystem-reservedCodeSpace')) {
+        const rcs = (ext.extension || []).find(x => x.url == 'reservedCodeSpace');
+        const pattern = rcs ? getValuePrimitive(rcs) : null;
+        if (pattern) {
+          const dd = (ext.extension || []).find(x => x.url == 'default-display');
+          try {
+            this._reservedCodeSpaces.push({
+              regex: regexUtilities.compile('^(?:' + pattern + ')$', this.caseInsensitive() ? 'i' : ''),
+              defaultDisplay: (dd && getValuePrimitive(dd)) || 'User-assigned'
+            });
+          } catch (e) {
+            // an expression that doesn't compile reserves nothing
+          }
+        }
+      }
+    }
+    return this._reservedCodeSpaces;
+  }
+
+  /**
+   * @param {string} code - the code
+   * @returns {{regex: Object, defaultDisplay: string}|null} the reserved code space the code is in, if it is in one
+   */
+  reservedCodeSpaceFor(code) {
+    return code ? (this.reservedCodeSpaces().find(rcs => rcs.regex.test(code)) || null) : null;
+  }
+
+  /**
+   * @param {string} code - the code
+   * @returns {boolean} true if the code is in a code space reserved for users to define their own codes
+   */
+  isInReservedCodeSpace(code) {
+    return this.reservedCodeSpaceFor(code) != null;
   }
 
   isPropUri(code, uri) {
     return (this.jsonObj.property || []).find(x => x.code == code && x.uri == uri);
   }
 
+  /**
+   * The canonical of the code system this one supplements (CodeSystem.supplements),
+   * or undefined if it isn't a supplement.
+   * @returns {string|undefined}
+   */
+  get supplementsUrl() {
+    return this.jsonObj.supplements;
+  }
+
   isSupplementFor(url, version) {
     if (this.jsonObj.content !== 'supplement') {
       return false;

package/tx/library/designations.js

@@ -82,10 +82,43 @@ class SearchFilterText {
     return returnRating ? {passes: false, rating: 0} : false;
   }
 
+  /**
+   * Whether every word of the filter is in the value, a word matching as in passes() (its
+   * stem starts with the filter word's stem). passes() needs only one word
+   */
+  passesAll(value) {
+    validateParameter(value, 'value', String);
+
+    if (this.isNull) {
+      return true;
+    }
+
+    const stems = [];
+    let i = 0;
+    while (i < value.length) {
+      if (this._isAlphaNumeric(value[i])) {
+        const j = i;
+        while (i < value.length && this._isAlphaNumeric(value[i])) {
+          i++;
+        }
+        stems.push(this.stemmer.stem(value.substring(j, i).toLowerCase()));
+      } else {
+        i++;
+      }
+    }
+    return this.stems.every(filterStem => stems.some(stem => stem.startsWith(filterStem)));
+  }
+
   /**
    * Check if designations pass the filter
    */
-  passesDesignations(cds) {
+  /**
+   * Whether any of the designations passes the filter. With a search language (see
+   * CodeSystemProvider.searchLanguage), only designations in that language take part,
+   * compared at the language subtag level; one that doesn't say is in `fallback` (the
+   * code system's language)
+   */
+  passesDesignations(cds, searchLang = null, fallback = 'en') {
     validateOptionalParameter(cds, 'cds', Designations);
 
     if (this.isNull) {
@@ -95,13 +128,23 @@ class SearchFilterText {
     if (!cds) return false;
 
     for (const cd of cds.designations) {
-      if (cd.value && this.passes(cd.value)) {
+      if (cd.value && (!searchLang || SearchFilterText.#languageOf(cd.language, fallback) === searchLang.language) && this.passes(cd.value)) {
         return true;
       }
     }
     return false;
   }
 
+  static #languageOf(lang, fallback) {
+    if (lang && lang.language) {
+      return lang.language;
+    }
+    if (typeof lang === 'string' && lang) {
+      return lang.split('-')[0].toLowerCase();
+    }
+    return (fallback || 'en').split('-')[0].toLowerCase();
+  }
+
   /**
    * Calculate match score against stems
    */

package/tx/library/extensions.js

@@ -25,10 +25,17 @@ const Extensions = {
       resource = resource.jsonObj
     }
     if (resource.implicitRules && 'https://hl7.org/fhir/implicit-rules/omitted-mandatory-interversion-code' != resource.implicitRules) {
-      throw new Issue("error", "business-rule", null, null, 'Cannot process resource "'+name+'" due to the presence of implicit rules \''+resource.implicitRules+'\' @'+place);
+      throw new Issue("error", "business-rule", null, null, 'Cannot process resource "'+name+'" due to the presence of implicit rules \''+resource.implicitRules+'\' @'+place, null, 422);
     }
   },
 
+  /**
+   * @param {Object} element - what may carry modifier extensions
+   * @param {string} place - the code doing the check (unused, for reading)
+   * @param {string} name - the element's path (FHIRPath, e.g. ValueSet.compose.include[0].filter[1]),
+   *   reported as the issue's expression
+   * @param {string} resource - the value set's url|version
+   */
   checkNoModifiers(element, place, name, resource) {
     if (!element) {
       return;
@@ -41,13 +48,12 @@ const Extensions = {
       for (const extension of element.modifierExtension) {
         urls.add(extension.url);
       }
+      // a modifier extension changes the meaning of what it's on, so an unknown one means the value
+      // set can't be processed: a problem with the request's content, not the server (422)
       const resId = resource ? resource : "";
-      const urlList = [...urls].join('\', \'');
-      if (urls.size > 1) {
-        throw new Issue("error", "business-rule", null, null, 'Cannot process resource '+resId+' at "' + name + '" due to the presence of modifier extensions '+urlList);
-      } else {
-        throw new Issue("error", "business-rule", null, null, 'Cannot process resource '+resId+' at "' + name + '" due to the presence of the modifier extension '+urlList);
-      }
+      throw new Issue("error", "business-rule", name, 'VALUESET_MODIFIER_EXTENSION_UNKNOWN',
+        "The value set " + resId + " can't be processed: " + name + " has a modifier extension that isn't understood (" + [...urls].join(', ') + ")",
+        'vs-invalid', 422).handleAsOO(422);
     }
     return true;
   },

package/tx/library/implicit-valuesets.js

@@ -0,0 +1,66 @@
+/**
+ * Choosing which version of a code system an implicit value set URL is drawn from, when
+ * several versions are loaded (SNOMED CT editions, typically). A factory that can say what
+ * form an implicit value set URL takes implements implicitValueSetForm(url), returning
+ * {form: 'generic'|'edition'|'version'} or null:
+ *
+ *   generic  (http://snomed.info/sct?fhir_vs...)  - the version the request asks for
+ *            (system-version and the like, through systemVersionFor) where a loaded version
+ *            matches it, else the default version: the one registered under the bare system
+ *   edition  (http://snomed.info/sct/<edition>?fhir_vs...) - the latest version of that
+ *            edition the server has
+ *   version  (.../version/<date>?fhir_vs...) - that version; only it matches
+ *
+ * @param {Iterable<object>} factories - the registered code system factories (duplicates are ignored)
+ * @param {function(string): object} defaultFor - the default factory for a system url
+ * @param {string} url - the value set url
+ * @param {function(string): (string|null)} [systemVersionFor] - the version the request asks for, for a system
+ * @returns {object|null} the factory to build the value set, or null if none recognises the url
+ */
+function chooseImplicitValueSetFactory(factories, defaultFor, url, systemVersionFor = null) {
+  const matches = [];
+  const seen = new Set();
+  for (const csp of factories) {
+    if (seen.has(csp) || typeof csp.implicitValueSetForm !== 'function') {
+      continue;
+    }
+    seen.add(csp);
+    const form = csp.implicitValueSetForm(url);
+    if (form) {
+      matches.push({ csp, form: form.form });
+    }
+  }
+  if (matches.length === 0) {
+    return null;
+  }
+  if (matches.every(m => m.form === 'generic')) {
+    const requested = systemVersionFor ? systemVersionFor(matches[0].csp.system()) : null;
+    if (requested) {
+      // an edition (with or without its version) or a full version uri; the latest that matches
+      const asked = matches.filter(m => versionMatches(m.csp, requested));
+      if (asked.length > 0) {
+        asked.sort((a, b) => (b.csp.version() || '').localeCompare(a.csp.version() || ''));
+        return asked[0].csp;
+      }
+    }
+    const preferred = defaultFor(matches[0].csp.system());
+    return matches.some(m => m.csp === preferred) ? preferred : matches[0].csp;
+  }
+  // edition or version form: the latest version that matches. Version URIs of one edition
+  // differ only in their date, so they order as strings.
+  const specific = matches.filter(m => m.form !== 'generic');
+  specific.sort((a, b) => (b.csp.version() || '').localeCompare(a.csp.version() || ''));
+  return specific[0].csp;
+}
+
+// Whether a factory's version is the one asked for: the same version, or a version of the
+// edition asked for (SNOMED CT: http://snomed.info/sct/<edition> covers .../version/<date>)
+function versionMatches(csp, requested) {
+  if (typeof csp.isMyEdition === 'function') {
+    return csp.isMyEdition(requested);
+  }
+  const mine = csp.version() || '';
+  return mine === requested || mine.startsWith(requested + '/version/');
+}
+
+module.exports = { chooseImplicitValueSetFactory };