fhirsmith 0.11.1 → 0.12.0

package/tx/cs/cs-api.md

@@ -105,7 +105,7 @@ All are `async`.
 | `parent(code)` | `null` | The parent concept, for hierarchical code systems. |
 | `extensions(code)` | `null` | FHIR extensions on the concept, if any. |
 | `properties(code)` | `[]` | The defined properties for the concept. |
-| `incompleteValidationMessage(code)` | `null` | A message explaining why validation may be incomplete (used by SCT). |
+| `incompleteValidationMessage(code)` | `null` | A message explaining why validation may be incomplete. No provider overrides this: SNOMED expressions are checked against the concept model, and the only things it cannot check are ones SNOMED itself publishes no rule for. |
 | `sameConcept(a, b)` | `false` | Returns `true` if `a` and `b` refer to the same concept (e.g. different expression forms). |
 | `isDisplay(designation)` | `false` | Called for designations not already marked with a standard display use code; return `true` to treat the designation as a display. |
 | `subsumesTest(codeA, codeB)` | `'not-subsumed'` | Returns one of `equivalent`, `subsumes`, `subsumed-by`, or `not-subsumed`. |

package/tx/cs/cs-snomed.js

@@ -148,6 +148,58 @@ class SnomedServices {
       refSetIndex: this.refSetIndex
     }, this.isAIndex);
 
+    // The expression services check the MRCM attribute ranges, but those are ECL
+    // and the ECL engine lives here, so hand them an evaluator. Returning null
+    // means "could not decide", and leaves the value unchecked.
+    this.expressionServices.eclConstraintMatcher = (constraint, value) => this.mrcmRangeSatisfied(constraint, value);
+    this._mrcmRangeCache = new Map();
+  }
+
+  /**
+   * Does this refinement value satisfy an MRCM range constraint?
+   *
+   * @param {string} constraint - the rangeConstraint ECL, e.g. "<< 182353008 |Side|"
+   * @param {SnomedExpression} value - the refinement's value expression
+   * @returns {boolean|null} null when the constraint cannot be evaluated
+   */
+  mrcmRangeSatisfied(constraint, value) {
+    let entry = this._mrcmRangeCache.get(constraint);
+    if (entry === undefined) {
+      entry = null;
+      try {
+        const ast = new ECLParser(new ECLLexer(constraint).tokenize()).parse();
+        const ctxt = this._evalECLNode(ast, null);
+        entry = {
+          ast: ast,
+          wildcard: !!ctxt.eclWildcard,
+          members: new Set(this._eclToIndexArray(ctxt))
+        };
+      } catch (error) {
+        // Concrete value ranges (dec/int/str) and anything else the ECL engine
+        // does not support: remembered as unusable so it is parsed only once.
+        entry = null;
+      }
+      this._mrcmRangeCache.set(constraint, entry);
+    }
+    if (!entry) {
+      return null;
+    }
+    if (entry.wildcard) {
+      return true;
+    }
+
+    const concepts = (value.concepts || []).filter(c => c.reference != null && c.reference !== NO_REFERENCE);
+    const refined = value.hasRefinements() || value.hasRefinementGroups();
+    if (!refined) {
+      if (concepts.length === 0) {
+        return null; // a concrete value, or nothing we can resolve
+      }
+      // Every focus concept of a plain value must be in the constraint's set.
+      return concepts.every(c => entry.members.has(c.reference));
+    }
+    // A refined value: ask the ECL engine whether the expression satisfies the
+    // constraint (it knows that a refinement of X is still << X).
+    return this._eclExpressionSatisfies({ expression: value }, entry.ast, null);
   }
 
   close() {
@@ -664,7 +716,7 @@ class SnomedServices {
     // we actually need the full concept list, otherwise filterSize returns 0
     // and the iteration yields nothing. Materialise active concepts now.
     if (forIteration && result.eclWildcard && (!result.descendants || result.descendants.length === 0)) {
-      result.descendants = this._eclEnumerateActiveConcepts(opContext);
+      result.descendants = this._eclEnumerateAllConcepts(opContext);
       delete result.eclWildcard;
       // The materialised wildcard form differs from the lazy (eclWildcard) form,
       // so mark it: the filter cache must not share it across iteration modes.
@@ -677,31 +729,29 @@ class SnomedServices {
   };
 
   /**
-   * Return every active concept's index. Used to materialise wildcard results
-   * when the filter needs to be iterated over (e.g. $expand).
+   * Return every concept's index. Used to materialise wildcard results when the
+   * filter needs to be iterated over (e.g. $expand).
+   *
+   * `*` means every concept the server knows, so this deliberately walks the
+   * concept table rather than descending from 138875005 |SNOMED CT Concept|.
+   * Two kinds of concept are in the table but not reachable from that root:
+   * inactive concepts (their is-a relationships are inactive too), and the
+   * foundation-metadata concepts that a subset carries without their is-a
+   * relationships - module concepts above all. Both belong in `*`, and both are
+   * counted by countAllCodes, so descending from the root made $expand of a
+   * `constraint = *` filter disagree with $expand of the whole code system.
+   *
+   * Inactive concepts are not filtered out here: activeOnly is applied by the
+   * expansion itself (see ValueSetExpander.processCodes), which is what lets one
+   * enumeration serve both activeOnly=true and activeOnly=false.
    * @returns {number[]}
    */
-  _eclEnumerateActiveConcepts = function (opContext) {
-    // The wildcard `*` enumerates the SNOMED CT concept hierarchy: the root
-    // 138875005 |SNOMED CT Concept| and its descendants. This excludes the
-    // foundation-metadata concepts that appear in a subset's concept table
-    // (referenced by the RF2 files as module / type / acceptability ... ids)
-    // without their is-a relationships, so they are not reachable from the root
-    // and are not returned by `*` (matching Snowstorm). On a full edition every
-    // real concept is under the root, so nothing is lost.
-    const rootRes = this.concepts.findConcept(138875005n);
-    if (rootRes && rootRes.found) {
-      return this.filterIsA(138875005n, true).descendants;
-    }
-    // Fallback (no recognisable root): every active concept.
+  _eclEnumerateAllConcepts = function (opContext) {
     const all = [];
     const n = this.concepts.count();
     for (let i = 0; i < n; i++) {
-      if (opContext) opContext.deadCheck('ecl:enumerateActiveConcepts');
-      const concept = this.concepts.getConceptByCount(i);
-      if ((concept.flags & 0x0F) === 0) {
-        all.push(concept.index);
-      }
+      if (opContext) opContext.deadCheck('ecl:enumerateAllConcepts');
+      all.push(this.concepts.getConceptByCount(i).index);
     }
     return all;
   };
@@ -918,7 +968,7 @@ class SnomedServices {
   };
 
   /**
-   * Wildcard — all active concepts.  The eclWildcard flag tells filterCheck /
+   * Wildcard — every concept, active or not.  The eclWildcard flag tells filterCheck /
    * filterLocate to accept every active concept without enumeration.
    * @returns {SnomedFilterContext}
    */
@@ -1312,15 +1362,15 @@ class SnomedServices {
 
   /**
    * Like _eclToIndexArray, but if the context is a bare wildcard (no
-   * descendants populated) it materialises the full active-concept list
-   * via _eclEnumerateActiveConcepts. Used by dotted/refined evaluation,
+   * descendants populated) it materialises the full concept list
+   * via _eclEnumerateAllConcepts. Used by dotted/refined evaluation,
    * which need an explicit concept set to iterate over.
    * @param {SnomedFilterContext} ctx
    * @returns {number[]}
    */
   _eclResolveSet = function (ctx, opContext) {
     if (ctx.eclWildcard && (!ctx.descendants || ctx.descendants.length === 0)) {
-      return this._eclEnumerateActiveConcepts(opContext);
+      return this._eclEnumerateAllConcepts(opContext);
     }
     return this._eclToIndexArray(ctx);
   };
@@ -1369,9 +1419,9 @@ class SnomedServices {
     const rightSet = new Set(this._eclToIndexArray(right));
 
     if (left.eclWildcard) {
-      // Wildcard minus the right set: use the shared active-concept enumeration
-      // (the root hierarchy) so `*` behaves consistently everywhere.
-      result.descendants = this._eclEnumerateActiveConcepts(opContext)
+      // Wildcard minus the right set: use the shared enumeration so `*` behaves
+      // consistently everywhere.
+      result.descendants = this._eclEnumerateAllConcepts(opContext)
         .filter(idx => !rightSet.has(idx));
       return result;
     }
@@ -1605,13 +1655,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 +1682,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).
@@ -1717,19 +1784,6 @@ class SnomedProvider extends BaseCSServices {
     }
   }
 
-  async incompleteValidationMessage(context) {
-
-    const ctxt = await this.#ensureContext(context);
-
-    if (!ctxt) return null;
-
-    if (ctxt.isComplex()) {
-      return "The expression is grammatically correct and the concepts are valid, but the expression has not been checked against the SNOMED CT concept model (MRCM)";
-    } else {
-      return null;
-    }
-  }
-
   async locateIsA(code, parent, disallowParent = false) {
 
 
@@ -1864,25 +1918,37 @@ class SnomedProvider extends BaseCSServices {
       if (ctxt instanceof SnomedExpressionContext) {
         // ignore concepts for now, but list refinements and refinement groups
         for (const refinement of ctxt.expression.refinements) {
-          const codeA = refinement.name.code;
-          const codeB = refinement.value.describe();
-          const description = await this.display(codeB);
-          let p = this._addCodeProperty(params, 'property', codeA, codeB, null, description);
-          p.part.push({name: 'code-display', valueString: await this.display(codeA)});
+          await this._addRefinementProperty(params, refinement);
         }
         for (const refinementGroup of ctxt.expression.refinementGroups) {
           for (const refinement of refinementGroup.refinements) {
-            const codeA = refinement.name.code;
-            const codeB = refinement.value.describe();
-            const description = await this.display(codeB);
-            let p = this._addCodeProperty(params, 'property', codeA, codeB, null, description);
-            p.part.push({name: 'code-display', valueString: await this.display(codeA)});
+            await this._addRefinementProperty(params, refinement);
           }
         }
       }
     }
   }
 
+  /**
+   * Report one refinement of a post-coordinated expression as a lookup property.
+   *
+   * The value is handled as an expression, not as a string: SnomedExpression's
+   * describe() is a human-readable rendering that joins concepts and refinements
+   * with commas ("85562004,272741003=24028007"), so round-tripping it through
+   * display() parsed it back as SCG and failed on any refined value.
+   *
+   * @param {Object} params - the Parameters being built
+   * @param {SnomedRefinement} refinement
+   */
+  async _addRefinementProperty(params, refinement) {
+    const codeA = refinement.name.code;
+    const value = SnomedExpressionContext.fromExpression('', refinement.value);
+    const codeB = await this.code(value);
+    const description = await this.display(value);
+    const p = this._addCodeProperty(params, 'property', codeA, codeB, null, description);
+    p.part.push({name: 'code-display', valueString: await this.display(codeA)});
+  }
+
   // Filter support
   async doesFilter(prop, op, value) {
     if (prop === 'concept') {
@@ -2114,7 +2180,7 @@ class SnomedProvider extends BaseCSServices {
     // A wildcard (`*`) set is lazy - it carries the eclWildcard flag rather than a
     // materialised descendant list - so count the active concepts it denotes.
     if (set.eclWildcard && (!set.descendants || set.descendants.length === 0)) {
-      return this.sct._eclEnumerateActiveConcepts(this.opContext).length;
+      return this.sct._eclEnumerateAllConcepts(this.opContext).length;
     }
     if (set.matches && set.matches.length > 0) {
       return set.matches.length;
@@ -2166,7 +2232,7 @@ class SnomedProvider extends BaseCSServices {
     const reference = ctxt.getReference();
 
     if (set.eclWildcard) {
-      return this.sct.isActive(reference) ? ctxt : null;
+      return ctxt; // `*` is every concept; inactive ones included
     }
 
     // A post-coordinated expression validated against an ECL value set: test the
@@ -2249,7 +2315,7 @@ class SnomedProvider extends BaseCSServices {
       return this.#descendantsHas(set, reference);
     }
     if (set.eclWildcard) {
-      return this.sct.isActive(reference);
+      return true; // `*` is every concept; inactive ones included
     }
     return false;
   }

package/tx/library/conceptmap.js

@@ -173,6 +173,45 @@ class ConceptMap extends CanonicalResource {
     return result;
   }
 
+  /**
+   * The canonical references this map defers to. Only group.unmapped.otherMap creates
+   * such a dependency: a map that names another map cannot be resolved without it, so
+   * it has to be consulted first.
+   * @returns {string[]} canonical references, as written (may or may not be versioned)
+   */
+  listDependencies() {
+    const result = [];
+    for (const g of this.jsonObj.group || []) {
+      if (g.unmapped && g.unmapped.mode === 'other-map' && g.unmapped.otherMap) {
+        if (!result.includes(g.unmapped.otherMap)) {
+          result.push(g.unmapped.otherMap);
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * The groups that would have been consulted for this coding, whether or not any of
+   * their elements matched. group.unmapped only applies to a group that was in scope
+   * for the translation, so the caller needs the same source/target test that
+   * listTranslations applies - without the per-element filter.
+   * @returns {Object[]} the matching group objects
+   */
+  listGroupsInScope(coding, targetScope, targetSystem) {
+    const result = [];
+    const vurl = VersionUtilities.vurl(coding.system, coding.version);
+    const all = this.canonicalMatches(targetScope, this.targetScope);
+    for (const g of this.jsonObj.group || []) {
+      const sourceOk = this.canonicalMatches(vurl, g.source);
+      const targetOk = !targetSystem || this.canonicalMatches(targetSystem, g.target);
+      if (all || (sourceOk && targetOk)) {
+        result.push(g);
+      }
+    }
+    return result;
+  }
+
   listTranslationsReverse(coding, targetScope, sourceSystem) {
     let result = [];
     let vurl = VersionUtilities.vurl(coding.system, coding.version);

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/parameter-check.js

@@ -0,0 +1,139 @@
+//
+// Checking what a code system provider adds to a $lookup response
+//
+// extendLookup() hands the provider the response parameter list and lets it
+// push whatever it likes. Most providers push values they built themselves out
+// of curated content, where the shape is known good. Some pass data through
+// from a remote API, where a value can be any JSON at all - an object, an
+// array, a null - and a structure like that in a FHIR primitive produces a
+// response that is not valid FHIR.
+//
+// That's a bug in the provider, not something the client did, so it fails the
+// operation (500/exception) rather than shipping a malformed response and
+// leaving someone downstream to work out where it came from.
+//
+
+// value[x] elements carried by a JSON string
+const STRING_VALUES = new Set([
+  'valueString', 'valueCode', 'valueUri', 'valueUrl', 'valueCanonical',
+  'valueId', 'valueOid', 'valueUuid', 'valueMarkdown', 'valueBase64Binary',
+  'valueDate', 'valueDateTime', 'valueTime', 'valueInstant'
+]);
+
+// value[x] elements carried by a JSON integer
+const INTEGER_VALUES = new Set(['valueInteger', 'valuePositiveInt', 'valueUnsignedInt']);
+
+// The one complex type a lookup property is allowed to carry. Its own members
+// are all primitives (system, version, code, display, userSelected), so an
+// object or array inside one is just as wrong as it would be at the top.
+const CODING_VALUE = 'valueCoding';
+
+function describe(value) {
+  if (value === null) {
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    return 'an array';
+  }
+  return 'a ' + typeof value;
+}
+
+function fail(source, path, message) {
+  throw new Error(`Code system provider ${source} produced an invalid $lookup response at ${path}: ${message}`);
+}
+
+function checkCoding(value, source, path) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    fail(source, path, `valueCoding must be an object, not ${describe(value)}`);
+  }
+  for (const [key, member] of Object.entries(value)) {
+    if (member === null || member === undefined) {
+      continue;
+    }
+    const type = typeof member;
+    if (type !== 'string' && type !== 'number' && type !== 'boolean') {
+      fail(source, path, `valueCoding.${key} must be a primitive, not ${describe(member)}`);
+    }
+  }
+}
+
+function checkValue(key, value, source, path) {
+  if (STRING_VALUES.has(key)) {
+    if (typeof value !== 'string') {
+      fail(source, path, `${key} must be a string, not ${describe(value)}`);
+    }
+    return;
+  }
+  if (INTEGER_VALUES.has(key)) {
+    if (!Number.isInteger(value)) {
+      fail(source, path, `${key} must be an integer, not ${describe(value)}`);
+    }
+    return;
+  }
+  if (key === 'valueDecimal') {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      fail(source, path, `${key} must be a finite number, not ${describe(value)}`);
+    }
+    return;
+  }
+  if (key === 'valueBoolean') {
+    if (typeof value !== 'boolean') {
+      fail(source, path, `${key} must be a boolean, not ${describe(value)}`);
+    }
+    return;
+  }
+  if (key === CODING_VALUE) {
+    checkCoding(value, source, path);
+    return;
+  }
+  fail(source, path, `${key} is not a value type a lookup property may carry`);
+}
+
+function checkParameter(param, source, path) {
+  if (param === null || typeof param !== 'object' || Array.isArray(param)) {
+    fail(source, path, `a parameter must be an object, not ${describe(param)}`);
+  }
+  if (typeof param.name !== 'string' || param.name === '') {
+    fail(source, path, `a parameter must have a name, not ${describe(param.name)}`);
+  }
+
+  const name = param.name;
+  const valueKeys = Object.keys(param).filter(key => key.startsWith('value'));
+  if (valueKeys.length > 1) {
+    fail(source, `${path}.${name}`, `a parameter may carry one value, not ${valueKeys.length} (${valueKeys.join(', ')})`);
+  }
+  for (const key of valueKeys) {
+    checkValue(key, param[key], source, `${path}.${name}`);
+  }
+
+  if (param.part !== undefined) {
+    if (!Array.isArray(param.part)) {
+      fail(source, `${path}.${name}`, `part must be an array, not ${describe(param.part)}`);
+    }
+    for (const part of param.part) {
+      checkParameter(part, source, `${path}.${name}`);
+    }
+  }
+}
+
+/**
+ * Check the parameters a provider added to a lookup response.
+ *
+ * @param {Array} params - the whole response parameter list
+ * @param {number} fromIndex - where the provider's own additions start, so
+ *   that only what extendLookup() added is checked
+ * @param {string} source - the code system, for the error message
+ * @throws {Error} if the provider produced something that isn't valid FHIR
+ */
+function checkAddedParameters(params, fromIndex, source) {
+  if (!Array.isArray(params)) {
+    return;
+  }
+  for (let i = fromIndex; i < params.length; i++) {
+    checkParameter(params[i], source || 'unknown', 'parameter');
+  }
+}
+
+module.exports = {
+  checkAddedParameters
+};

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());