fhirsmith 0.10.1 → 0.11.0

package/tx/cs/cs-uri.js

@@ -162,6 +162,10 @@ class UriServices extends CodeSystemProvider {
     return true;
   }
 
+  canBeExpanded() {
+    return false; // URIs cannot be iterated / enumerated
+  }
+
   // ============================================================================
   // Filtering (not supported for URIs)
   // ============================================================================

package/tx/data/snomed-subset.txt

@@ -22,6 +22,8 @@
 74400008 |Appendicitis (disorder)|
 155729003 |Appendicitis (disorder)|
 307530000 |Appendicitis NOS (disorder)|
+42463004 |Genus Opisthorchis (organism)|
+71650008 |Opisthorchis viverrini (organism)|
 116676008 |Associated morphology (attribute)|
 128045006 |Cellulitis (disorder)|
 20946005 |Fracture, closed (morphologic abnormality)|
@@ -34,14 +36,49 @@
 6990005 |Fracture of shaft of tibia (disorder)|
 <<128241005 |Inflammatory disease of liver (disorder)|
 <<10200004 |Liver structure (body structure)|
+<<90140006 |Structure of intrahepatic biliary tree (body structure)|
 <<364159005 |Liver observable (observable entity)|
 <<227014008 |Liver pate (substance)|
 <<249565005 |Liver finding (finding)|
 <<406459008 |Product containing halibut liver oil (medicinal product)|
 <<776168003 |Product containing only halibut liver oil (medicinal product)|
-<<776168003 |Product containing only halibut liver oil (medicinal product)|
 <<309399009 |Hospital-based dietitian (occupation)|
 <<421813008 |Class Hepaticopsida (organism)|
-<<441802002 |Imaging of liver (procedure)|
+<<441802002 |Computed tomography of liver (procedure)|
 <<119383005 |Specimen from liver (specimen)|
-129433002 |Inspection|
+129433002 |Inspection|
+367430006 |Repair of tendon of hand (procedure)|
+119657005 |Hand repair (procedure)|
+274059009 |Hand tendon operation (procedure)|
+281760001 |Repair of tendon of upper limb (procedure)|
+18701002 |Repair of tendon of hand with graft (procedure)|
+214433003 |Repair of ruptured tendon of hand (procedure)|
+243234005 |Repair of tendon of hand by transfer or transplantation (procedure)|
+26731003 |Repair of tendon of hand by suture (procedure)|
+27106001 |Reconstruction of tendon pulley of hand (procedure)|
+45810006 |Reattachment of tendon of hand (procedure)|
+709291000 |Repair of flexor tendon of hand (procedure)|
+712638006 |Repair of extensor tendon of hand (procedure)|
+76340004 |Plication of tendon of hand (procedure)|
+90650008 |Lengthening of tendon of hand (procedure)|
+90907001 |Shortening of tendon of hand (procedure)|
+91092007 |Myotenontoplasty of hand (procedure)|
+118632007 |Structure of tendon within hand (body structure)|
+13024002 |Tendon structure (body structure)|
+245098002 |Structure of tendon within upper limb (body structure)|
+85562004 |Hand structure (body structure)|
+#Referenced in request
+734139008 |Anatomy structure and part association reference set (foundation metadata concept)|
+#For snomed-procedure-in-display test
+#Required by: validate-code-isa-in-response.json
+41271000119108 |Infective arthritis caused by virus and co-occurrent with hepatitis (disorder)|
+#Required by: expand-ecl-ancOrSelf-response.json, expand-ecl-ancestors-response.json, expand-ecl-parents-response.json, expand-ecl-parentsOrSelf-response.json
+303270005 |Liver and biliary structure (body structure)|
+699602007 |Structure of viscus of abdomen proper (body structure)|
+#Required by: expand-ecl-ancOrSelf-response.json, expand-ecl-ancestors-response.json
+420473002 |Structure of subregion of trunk (body structure)|
+49596003 |Digestive organ (body structure)|
+86762007 |Digestive system (body structure)|
+1197039003 |Structure of lymphatic vessel of liver (body structure)|
+#Required by: lookup-procedure-pc-response.json
+24028007 |Right (qualifier value)|

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

@@ -2407,6 +2407,16 @@ class SnomedImporter {
       const refSet = new RefSet(refSetId);
       refSet.title = displayName;
       refSet.isLangRefset = isLangRefset;
+      // Set the reference set's defining-concept index at creation time, using
+      // this refset's own id. Doing it here (rather than once after the member
+      // loop) is essential when a single RF2 file contains members for more than
+      // one reference set (e.g. the association file carries both 734139008 and
+      // 900000000000526001) — otherwise only the last refset in the file gets a
+      // valid index and the others collapse to index 0.
+      const refSetConcept = this.conceptMap.get(BigInt(refSetId));
+      if (refSetConcept) {
+        refSet.index = refSetConcept.index;
+      }
       this.refSets.set(refSetId, refSet);
     }
     return this.refSets.get(refSetId);
@@ -2585,6 +2595,14 @@ class SnomedImporter {
 
     // Index concepts - optimized version
     for (const concept of this.conceptList) {
+      // Store the concept's module (resolved to its concept index) so that
+      // $lookup can report the 'module' property. Modules whose concept is not
+      // part of the subset are skipped (moduleId stays 0 / property omitted).
+      const moduleConcept = this.conceptMap.get(concept.moduleId);
+      if (moduleConcept && moduleConcept.index != null) {
+        this.concepts.setModuleId(concept.index, moduleConcept.index);
+      }
+
       const refSetRefs = [];
       const refSetValues = [];
 

package/tx/library/designations.js

@@ -214,7 +214,8 @@ const DisplayDifference = {
 const DesignationUse = {
   DISPLAY: {
     system: 'http://terminology.hl7.org/CodeSystem/hl7TermMaintInfra', // http://terminology.hl7.org/CodeSystem/designation-use',
-    code: 'preferredForLanguage' // 'display'
+    code: 'preferredForLanguage', // 'display'
+    display: 'Preferred For Language'
   },
   FSN: {
     system: 'http://snomed.info/sct',
@@ -356,10 +357,7 @@ class Designations {
     designation.status = status;
 
     if (isDisplay) {
-      designation.use = {
-        system: DesignationUse.DISPLAY.system,
-        code: DesignationUse.DISPLAY.code
-      };
+      designation.use = { ...DesignationUse.DISPLAY };
     } else if (use) {
       designation.use = use;
     }

package/tx/library/renderer.js

@@ -157,8 +157,8 @@ class Renderer {
   async renderMetadataTable(res, tbl, sourcePackage) {
     this.renderMetadataVersion(res, tbl);
     await this.renderMetadataProfiles(res, tbl);
-    this.renderMetadataTags(res, tbl);
-    this.renderMetadataLabels(res, tbl);
+    await this.renderMetadataTags(res, tbl);
+    await this.renderMetadataLabels(res, tbl);
     this.renderMetadataLastUpdated(res, tbl);
     this.renderMetadataSource(res, tbl);
     this.renderProperty(tbl, 'TEST_PLAN_LANG', res.language);
@@ -173,6 +173,7 @@ class Renderer {
     this.renderProperty(tbl, 'CANON_REND_COMMITTEE', Extensions.readString(res, 'http://hl7.org/fhir/StructureDefinition/structuredefinition-wg'));
     this.renderPropertyCopy(tbl, 'GENERAL_COPYRIGHT', res.copyright);
     this.renderProperty(tbl, 'EXT_FMM_LEVEL', Extensions.readString(res, 'http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm'));
+    this.renderProperty(tbl, 'EXT_STANDARDS_STATUS', Extensions.readString(res, 'http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status'));
     this.renderProperty(tbl, 'PAT_PERIOD', res.effectivePeriod);
     this.renderPropertyLink(tbl, 'WEB_SOURCE', Extensions.readString(res, 'http://hl7.org/fhir/StructureDefinition/web-source'));
     this.renderProperty(tbl, 'GENERAL_SOURCE', sourcePackage);
@@ -221,41 +222,45 @@ class Renderer {
     }
   }
 
-  renderMetadataTags(res, tbl) {
+  async renderMetadataTags(res, tbl) {
     if (res.meta?.tag) {
       let tr = tbl.tr();
       tr.td().b().tx(this.translate('GENERAL_PROF'));
       if (res.meta.tag.length > 1) {
         let ul = tr.td();
         for (let u of res.meta.tag) {
-          this.renderCoding(ul.li(), u);
+          await this.renderCoding(ul.li(), u);
         }
       } else {
-        this.renderCoding(tr.td(), res.meta.tag[0]);
+        await this.renderCoding(tr.td(), res.meta.tag[0]);
       }
     }
   }
 
-  renderMetadataLabels(res, tbl) {
+  async renderMetadataLabels(res, tbl) {
     if (res.meta?.label) {
       let tr = tbl.tr();
       tr.td().b().tx(this.translate('GENERAL_PROF'));
       if (res.meta.label.length > 1) {
         let ul = tr.td();
         for (let u of res.meta.label) {
-          this.renderCodin(ul.li(), u);
+          await this.renderCoding(ul.li(), u);
         }
       } else {
-        this.renderCoding(tr.td(), res.meta.label[0]);
+        await this.renderCoding(tr.td(), res.meta.label[0]);
       }
     }
   }
 
+  // Inline phrases inherited from the Java core translations (RES_REND_VER = "version: {0}"
+  // etc) are not table labels; when rendering into a name/value table we use the dedicated
+  // *_NAME / *_VALUE phrases instead, and leave the inline phrases to the Java code.
+
   renderMetadataVersion(res, tbl) {
     if (res.meta?.version) {
       let tr = tbl.tr();
-      tr.td().b().tx(this.translate('RES_REND_VER'));
-      tr.td().tx(res.meta.version);
+      tr.td().b().tx(this.translate('RES_REND_VER_NAME'));
+      tr.td().tx(this.translate('RES_REND_VER_VALUE', [res.meta.version]));
     }
   }
 
@@ -263,9 +268,8 @@ class Renderer {
     if (res.meta?.lastUpdated) {
       this._requireValidDate(res.meta.lastUpdated, 'meta.lastUpdated');
       let tr = tbl.tr();
-      // RES_REND_UPDATED is "Last updated: {0}" — supply the formatted date as
-      // the {0} parameter so the placeholder is substituted.
-      tr.td().b().tx(this.translate('RES_REND_UPDATED', [this.displayDate(res.meta.lastUpdated)]));
+      tr.td().b().tx(this.translate('RES_REND_UPDATED_NAME'));
+      tr.td().tx(this.translate('RES_REND_UPDATED_VALUE', [this.displayDate(res.meta.lastUpdated)]));
     }
   }
 
@@ -326,8 +330,8 @@ class Renderer {
   renderMetadataSource(res, tbl) {
     if (res.meta?.source) {
       let tr = tbl.tr();
-      tr.td().b().tx(this.translate('RES_REND_INFO_SOURCE'));
-      tr.td().tx(res.meta.source);
+      tr.td().b().tx(this.translate('RES_REND_INFO_SOURCE_NAME'));
+      tr.td().tx(this.translate('RES_REND_INFO_SOURCE_VALUE', [res.meta.source]));
     }
   }
 
@@ -654,7 +658,7 @@ class Renderer {
     await this.renderMetadataTable(cs, div_.table("grid"), sourcePackage);
 
     // Code system properties
-    const hasProps = this.generateProperties(div_, cs);
+    const hasProps = await this.generateProperties(div_, cs);
 
     // Filters
     this.generateFilters(div_, cs);
@@ -773,18 +777,22 @@ class Renderer {
     }
   }
 
-  generateProperties(x, cs) {
+  async generateProperties(x, cs) {
     if (!cs.property || cs.property.length === 0) {
       return false;
     }
 
+    const EXT_PROPERTY_VALUESET = 'http://hl7.org/fhir/StructureDefinition/codesystem-property-valueset';
+
     // Check what columns we need
     let hasURI = false;
     let hasDescription = false;
+    let hasValueSet = false;
 
     for (const p of cs.property) {
       hasURI = hasURI || !!p.uri;
       hasDescription = hasDescription || !!p.description;
+      hasValueSet = hasValueSet || !!Extensions.has(p, EXT_PROPERTY_VALUESET);
     }
 
     x.para().b().tx(this.translate('GENERAL_PROPS'));
@@ -800,6 +808,9 @@ class Renderer {
     if (hasDescription) {
       tr.th().tx(this.translate('GENERAL_DESC'));
     }
+    if (hasValueSet) {
+      tr.th().tx(this.translate('GENERAL_VALUESET'));
+    }
 
     for (const p of cs.property) {
       const row = tbl.tr();
@@ -811,6 +822,13 @@ class Renderer {
       if (hasDescription) {
         row.td().tx(p.description || '');
       }
+      if (hasValueSet) {
+        const td = row.td();
+        const vsUrl = Extensions.readString(p, EXT_PROPERTY_VALUESET);
+        if (vsUrl) {
+          await this.renderLink(td, vsUrl);
+        }
+      }
     }
 
     return true;
@@ -879,6 +897,9 @@ class Renderer {
     if (columnInfo.hasDefinition) {
       headerRow.th().tx(this.translate('GENERAL_DEFINITION'));
     }
+    if (columnInfo.hasComment) {
+      headerRow.th().tx(this.translate('GENERAL_COMMENTS'));
+    }
     if (columnInfo.hasDeprecated) {
       headerRow.th().tx(this.translate('CODESYSTEM_DEPRECATED'));
     }
@@ -888,6 +909,11 @@ class Renderer {
       headerRow.th().tx(this.getDisplayForProperty(prop) || prop.code);
     }
 
+    // Designation columns (by use + language)
+    for (const desig of columnInfo.designations) {
+      headerRow.th().tx(this.formatDesignationHeader(desig));
+    }
+
     // Render concepts recursively
     for (const concept of cs.concept) {
       await this.addConceptRow(tbl, concept, 0, cs, columnInfo);
@@ -913,17 +939,23 @@ class Renderer {
   }
 
   analyzeConceptColumns(cs) {
+    const EXT_CS_COMMENT = 'http://hl7.org/fhir/StructureDefinition/codesystem-concept-comments';
+    const EXT_DISPLAY_HINT = 'http://hl7.org/fhir/StructureDefinition/structuredefinition-display-hint';
     const info = {
       hasHierarchy: false,
       hasDisplay: false,
       hasDefinition: false,
       hasDeprecated: false,
       hasComment: false,
-      properties: []
+      properties: [],
+      designations: [],
+      useMarkdown: this.hasMarkdownInDefinitions(cs)
     };
 
     // Check which properties are actually used
     const usedProperties = new Set();
+    // Track distinct designations, keyed by use + language.
+    const usedDesignations = new Map();
 
     const analyzeConceptList = (concepts) => {
       for (const c of concepts) {
@@ -943,30 +975,59 @@ class Renderer {
           info.hasDeprecated = true;
         }
 
+        // Check for concept comments
+        if (Extensions.has(c, EXT_CS_COMMENT)) {
+          info.hasComment = true;
+        }
+
         // Track used properties
         if (c.property) {
           for (const prop of c.property) {
             usedProperties.add(prop.code);
           }
         }
+
+        // Track distinct designations (by use + language)
+        if (c.designation) {
+          for (const desig of c.designation) {
+            const key = this.getDesignationKey(desig);
+            if (!usedDesignations.has(key)) {
+              usedDesignations.set(key, { use: desig.use, language: desig.language });
+            }
+          }
+        }
       }
     };
 
     analyzeConceptList(cs.concept || []);
 
+    // If any property carries a display-hint extension, switch to "manual"
+    // column selection: only properties explicitly hinted display/no-link show.
+    const isManual = (cs.property || []).some(p => Extensions.has(p, EXT_DISPLAY_HINT));
+
     // Filter to properties that are actually used
     if (cs.property) {
       for (const prop of cs.property) {
-        if (usedProperties.has(prop.code) && this.showPropertyInTable(prop)) {
+        if (usedProperties.has(prop.code) && this.showPropertyInTable(prop, isManual)) {
           info.properties.push(prop);
         }
       }
     }
 
+    // Convert designation map to array, sorted for stable ordering
+    info.designations = Array.from(usedDesignations.values()).sort((a, b) => {
+      return this.getDesignationKey(a).localeCompare(this.getDesignationKey(b));
+    });
+
     return info;
   }
 
-  showPropertyInTable(prop) {
+  showPropertyInTable(prop, isManual = false) {
+    if (isManual) {
+      // Manual mode: only show properties explicitly hinted display/no-link.
+      const hint = Extensions.readString(prop, 'http://hl7.org/fhir/StructureDefinition/structuredefinition-display-hint');
+      return hint === 'display' || hint === 'no-link';
+    }
     // Skip certain internal properties
     const skipCodes = ['status', 'inactive', 'deprecated', 'notSelectable'];
     return !skipCodes.includes(prop.code);
@@ -977,6 +1038,60 @@ class Renderer {
     return prop.description || prop.code;
   }
 
+  /**
+   * Translations of a concept's definition, carried as translation extensions
+   * on the definition primitive (the sibling _definition element in JSON).
+   * Returns [{lang, value}]. Display translations are intentionally NOT read
+   * here - display variants belong in designations.
+   */
+  definitionTranslations(concept) {
+    const el = concept._definition;
+    if (!el || !el.extension) {
+      return [];
+    }
+    const out = [];
+    for (const ext of el.extension) {
+      if (ext.url === 'http://hl7.org/fhir/StructureDefinition/translation') {
+        const lang = Extensions.readString(ext, 'lang');
+        const value = Extensions.readString(ext, 'content');
+        if (value) {
+          out.push({ lang: lang || '', value });
+        }
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Whether concept definitions should be rendered as markdown. Honours the
+   * codesystem-use-markdown extension; otherwise auto-detects common markdown
+   * constructs in any definition.
+   */
+  hasMarkdownInDefinitions(cs) {
+    const flag = Extensions.readValue(cs, 'http://hl7.org/fhir/StructureDefinition/codesystem-use-markdown');
+    if (flag && typeof flag.valueBoolean === 'boolean') {
+      return flag.valueBoolean;
+    }
+    const looksMarkdown = (str) => {
+      if (!str) {
+        return false;
+      }
+      return /\]\([^)]*\)|^\s*#{1,6}\s+|^\s*[-*+]\s+|^\s*\d+\.\s+/m.test(str);
+    };
+    const walk = (concepts) => {
+      for (const c of concepts || []) {
+        if (looksMarkdown(c.definition)) {
+          return true;
+        }
+        if (c.concept && walk(c.concept)) {
+          return true;
+        }
+      }
+      return false;
+    };
+    return walk(cs.concept || []);
+  }
+
   isDeprecated(concept) {
     if (concept.property) {
       for (const prop of concept.property) {
@@ -987,6 +1102,12 @@ class Renderer {
         }
       }
     }
+    // The valueset-deprecated extension (on compose.include.concept or
+    // expansion.contains) marks a concept as deprecated within this value set.
+    const ext = Extensions.has(concept, 'http://hl7.org/fhir/StructureDefinition/valueset-deprecated');
+    if (ext && ext.valueBoolean === true) {
+      return true;
+    }
     return false;
   }
 
@@ -1031,7 +1152,35 @@ class Renderer {
 
     // Definition column
     if (columnInfo.hasDefinition) {
-      tr.td().tx(concept.definition || '');
+      const td = tr.td();
+      const useMarkdown = columnInfo.useMarkdown;
+      if (concept.definition) {
+        if (useMarkdown) {
+          td.markdown(concept.definition);
+        } else {
+          td.tx(concept.definition);
+        }
+      }
+      // Translations of the definition (translation extension on the
+      // definition primitive) are rendered below the definition, same cell.
+      for (const t of this.definitionTranslations(concept)) {
+        td.br();
+        td.i().tx('(' + t.lang + ') ');
+        if (useMarkdown) {
+          td.markdown(t.value);
+        } else {
+          td.tx(t.value);
+        }
+      }
+    }
+
+    // Comment column
+    if (columnInfo.hasComment) {
+      const td = tr.td();
+      const comment = Extensions.readString(concept, 'http://hl7.org/fhir/StructureDefinition/codesystem-concept-comments');
+      if (comment) {
+        td.tx(comment);
+      }
     }
 
     // Deprecated column
@@ -1040,11 +1189,36 @@ class Renderer {
       if (this.isDeprecated(concept)) {
         td.tx(this.translate('CODESYSTEM_DEPRECATED_TRUE'));
 
-        // Check for replacement
-        const replacedBy = this.getPropertyValue(concept, 'replacedBy');
-        if (replacedBy) {
+        // Replacement: prefer the codesystem-replacedby extension (a Coding),
+        // then fall back to a 'replacedBy' property value.
+        const replacedByExt = Extensions.readValue(concept, 'http://hl7.org/fhir/StructureDefinition/codesystem-replacedby');
+        const replacedByCoding = replacedByExt && replacedByExt.valueCoding;
+        const replacedByProp = this.getPropertyValue(concept, 'replacedBy');
+        if (replacedByCoding) {
+          td.tx(' ' + this.translate('CODESYSTEM_REPLACED_BY') + ' ');
+          const link = this.linkResolver ?
+            await this.linkResolver.resolveCode(this.opContext, replacedByCoding.system, replacedByCoding.version, replacedByCoding.code) : null;
+          if (link) {
+            td.ah(link.link).tx(replacedByCoding.code);
+          } else {
+            td.code().tx(replacedByCoding.code);
+          }
+          if (replacedByCoding.display) {
+            td.tx(' "' + replacedByCoding.display + '"');
+          }
+        } else if (replacedByProp) {
           td.tx(' ' + this.translate('CODESYSTEM_REPLACED_BY') + ' ');
-          td.code().tx(replacedBy);
+          td.code().tx(replacedByProp.value);
+        } else {
+          // No replacement: show the concept-level standards-status reason.
+          const ssExt = Extensions.readValue(concept, 'http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status');
+          if (ssExt) {
+            const reason = Extensions.readString(ssExt, 'http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status-reason');
+            if (reason) {
+              td.tx(' ');
+              td.markdown(reason);
+            }
+          }
         }
       }
     }
@@ -1052,6 +1226,7 @@ class Renderer {
     // Property columns
     for (const prop of columnInfo.properties) {
       const td = tr.td();
+      const noLink = Extensions.readString(prop, 'http://hl7.org/fhir/StructureDefinition/structuredefinition-display-hint') === 'no-link';
       const values = this.getPropertyValues(concept, prop.code);
 
       let first = true;
@@ -1061,7 +1236,16 @@ class Renderer {
         }
         first = false;
 
-        await this.renderPropertyValue(td, val, prop, cs);
+        await this.renderPropertyValue(td, val, prop, cs, noLink);
+      }
+    }
+
+    // Designation columns (by use + language)
+    for (const desigDef of columnInfo.designations) {
+      const td = tr.td();
+      const value = this.getDesignationValue(concept, desigDef);
+      if (value) {
+        td.tx(value);
       }
     }
 
@@ -1098,13 +1282,13 @@ class Renderer {
     return null;
   }
 
-  async renderPropertyValue(td, val, propDef, cs) {
+  async renderPropertyValue(td, val, propDef, cs, noLink = false) {
     if (!val) return;
 
     switch (val.type) {
       case 'code': {
         // If it's a parent reference, link to it
-        if (propDef.code === 'parent' || propDef.code === 'child') {
+        if ((propDef.code === 'parent' || propDef.code === 'child') && !noLink) {
           td.ah('#' + cs.id + '-' + val.value).tx(val.value);
         } else {
           td.code().tx(val.value);
@@ -1113,7 +1297,7 @@ class Renderer {
       }
       case 'coding': {
         const coding = val.value;
-        const link = this.linkResolver ?
+        const link = (!noLink && this.linkResolver) ?
             await this.linkResolver.resolveCode(this.opContext, coding.system, coding.version, coding.code) : null;
         if (link) {
           td.ah(link.link).tx(coding.code);
@@ -1131,7 +1315,7 @@ class Renderer {
       }
       case 'string': {
         // Check if it's a URL
-        if (val.value.startsWith('http://') || val.value.startsWith('https://')) {
+        if (!noLink && (val.value.startsWith('http://') || val.value.startsWith('https://'))) {
           td.ah(val.value).tx(val.value);
         } else {
           td.tx(val.value);
@@ -1215,6 +1399,19 @@ class Renderer {
   }
 
   async renderExpansion(x, vs, tbl) {
+    // Surface expansion-level status extensions as prominent warnings: the
+    // expansion may not contain every code in the value set.
+    if (Extensions.has(vs.expansion, 'http://hl7.org/fhir/StructureDefinition/valueset-unclosed')) {
+      const reason = Extensions.readString(vs.expansion, 'http://hl7.org/fhir/StructureDefinition/valueset-unclosed-reason');
+      const p = x.para();
+      p.b().tx('Warning: ');
+      p.tx('This expansion is not closed - it may not contain all the codes in the value set.' + (reason ? ' ' + reason : ''));
+    }
+    if (Extensions.has(vs.expansion, 'http://hl7.org/fhir/StructureDefinition/valueset-toocostly')) {
+      const p = x.para();
+      p.b().tx('Warning: ');
+      p.tx('This expansion is incomplete - a complete expansion was too costly to produce.');
+    }
     this.renderProperty(tbl, 'Expansion Identifier', vs.expansion.identifier);
     this.renderProperty(tbl, 'Expansion Timestamp', vs.expansion.timestamp);
     this.renderProperty(tbl, 'Expansion Total', vs.expansion.total);

package/tx/library.js

@@ -481,7 +481,11 @@ class Library {
           throw new Error("Unable to load VSAC provider unless vsacCfg is provided in the configuration");
         }
         let vsac = new VSACValueSetProvider(this.vsacCfg, this.stats);
-        vsac.initialize();
+        // Intentionally not awaited: initialize() might run a full VSAC sync on first load,
+        // which can take minutes - we don't want to block startup. But attach a handler
+        // so a failed background sync surfaces as a log error rather than an unhandled
+        // promise rejection.
+        vsac.initialize().catch((err) => this.log.error(`VSAC initialization failed: ${err.message}`));
         this.valueSetProviders.push(vsac);
         this.externalSources.push(vsac);
         //const mem = process.memoryUsage();