fhirsmith 0.18.1 → 1.0.0

package/ips/nationality.js

@@ -0,0 +1,120 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+/**
+ * The nationality step - the first processing step: which nation an IPS document is from,
+ * as far as the document itself says. Few national IGs give a way to tell, so this is a
+ * short list of signs, to grow as more are found:
+ *
+ *   US  the Bundle claims the US Patient Summary profile (Bundle-us-pcs), or a US Core
+ *       extension is used anywhere in the document
+ *   AU  the Bundle claims the AU Patient Summary profile (au-ps-bundle)
+ *
+ * The result is { jurisdiction, reasons: [{ jurisdiction, text }] }: jurisdiction is the
+ * nation's ISO 3166 two-letter code, or null when it is unknown - nothing points to a nation,
+ * or the signs point to more than one (then the reasons say which).
+ *
+ * @module ips/nationality
+ */
+
+const US_CORE_EXTENSIONS = 'http://hl7.org/fhir/us/core/StructureDefinition/';
+// how many extension urls a reason names
+const MAX_NAMED = 3;
+
+/** The profiles a resource claims (meta.profile), without their versions. */
+function profilesOf(resource) {
+  const p = resource?.meta?.profile;
+  return Array.isArray(p) ? p.filter(x => typeof x === 'string').map(x => x.split('|')[0]) : [];
+}
+
+/** Every extension url in the document, at any depth, each once. */
+function extensionUrls(node, found = new Set()) {
+  if (Array.isArray(node)) {
+    for (const n of node) {
+      extensionUrls(n, found);
+    }
+  } else if (node && typeof node === 'object') {
+    for (const [k, v] of Object.entries(node)) {
+      if ((k === 'extension' || k === 'modifierExtension') && Array.isArray(v)) {
+        for (const e of v) {
+          if (e && typeof e.url === 'string') {
+            found.add(e.url);
+          }
+        }
+      }
+      extensionUrls(v, found);
+    }
+  }
+  return found;
+}
+
+/** A Bundle profile that says which nation a document is from. */
+function profileRule(jurisdiction, url, name) {
+  return (bundle) => (profilesOf(bundle).includes(url) ? `the Bundle claims the ${name} profile (${url})` : null);
+}
+
+const RULES = [
+  { jurisdiction: 'US', test: profileRule('US', 'http://hl7.org/fhir/us/pcs/StructureDefinition/Bundle-us-pcs', 'US Patient Summary') },
+  {
+    jurisdiction: 'US',
+    test: (bundle, urls) => {
+      const core = [...urls].filter(u => u.startsWith(US_CORE_EXTENSIONS)).sort();
+      if (core.length === 0) {
+        return null;
+      }
+      const named = core.slice(0, MAX_NAMED).map(u => u.substring(US_CORE_EXTENSIONS.length)).join(', ');
+      return `US Core extension${core.length === 1 ? ' is' : 's are'} used (${named}${core.length > MAX_NAMED ? ` and ${core.length - MAX_NAMED} more` : ''})`;
+    }
+  },
+  { jurisdiction: 'AU', test: profileRule('AU', 'http://hl7.org.au/fhir/ps/StructureDefinition/au-ps-bundle', 'AU Patient Summary') }
+];
+
+/**
+ * Which nation a document is from.
+ * @param {Object} bundle
+ * @returns {{jurisdiction: string|null, reasons: Array<{jurisdiction: string, text: string}>}}
+ */
+function determineNationality(bundle) {
+  const urls = extensionUrls(bundle);
+  const reasons = [];
+  for (const rule of RULES) {
+    const text = rule.test(bundle, urls);
+    if (text) {
+      reasons.push({ jurisdiction: rule.jurisdiction, text });
+    }
+  }
+  const nations = [...new Set(reasons.map(r => r.jurisdiction))];
+  return { jurisdiction: nations.length === 1 ? nations[0] : null, reasons };
+}
+
+/** What the result says, in a sentence. */
+function nationalityText(result) {
+  if (!result) {
+    return null;
+  }
+  const reasons = Array.isArray(result.reasons) ? result.reasons : [];
+  if (result.jurisdiction) {
+    return `From ${result.jurisdiction}: ${reasons.map(r => r.text).join('; ')}`;
+  }
+  if (reasons.length > 0) {
+    const nations = [...new Set(reasons.map(r => r.jurisdiction))];
+    return `Nationality unknown: the document has signs of more than one nation (${nations.map(n => `${n}: ${reasons.filter(r => r.jurisdiction === n).map(r => r.text).join('; ')}`).join(' - ')})`;
+  }
+  return 'Nationality unknown: nothing in the document says which nation it is from (only US and Australian documents can be recognised so far)';
+}
+
+const nationalityStep = {
+  name: 'nationality',
+  async run(row, project, module) {
+    const started = Date.now();
+    const result = determineNationality(row.bundle);
+    module.store.saveResult(row.id, 'nationality', { ms: Date.now() - started, ...result });
+    module.store.setNationality(row.id, result.jurisdiction);
+    return `nationality: ${result.jurisdiction || 'unknown'}`;
+  }
+};
+
+module.exports = { determineNationality, nationalityText, nationalityStep, RULES };

package/ips/pipeline.js

@@ -9,13 +9,16 @@
  * One process works through the queue (ips.js: processQueue), and runs these steps over
  * each document, in this order:
  *
- *   1. translate     translate CodeableConcepts that fail the terminology check to codes that pass it
- *   2. narrative     generate the narrative with the IPS presenter (presenter.js), into the analysed copy
- *   3. validation    validate the (translated) document with the FHIR validator (fhir-validator-wrapper)
- *   4. terminology   check each CodeableConcept against the value sets for international exchange
- *   5. piqi          measure the quality of the document with PIQI                        (not yet)
- *   6. profiles      check the document against each clinical profile (profiles.js)
- *   7. ai            assess the document for consistency and its terminology with an AI service (ai-client.js)
+ *   0. nationality   which nation the document is from, as far as it says (nationality.js)
+ *   1. analysis      look at each resource and section for what a reader should know (analysis.js)
+ *   2. translate     translate CodeableConcepts that fail the terminology check to codes that pass it
+ *   3. narrative     generate the narrative with the IPS presenter (presenter.js), into the analysed copy
+ *   4. validation    validate the (translated) document with the FHIR validator (fhir-validator-wrapper)
+ *   5. national      validate it against each national profile (the national IGs' profiles on Bundle)
+ *   6. terminology   check each CodeableConcept against the value sets for international exchange
+ *   7. piqi          measure the quality of the document with PIQI                        (not yet)
+ *   8. profiles      check the document against each clinical profile (profiles.js)
+ *   9. ai            assess the document for consistency and its terminology with an AI service (ai-client.js)
  *
  * Each step is { name, run(row, project, module) -> result }. A step keeps what it finds in
  * one of two places: as a result stored against the document (store.saveResult - the
@@ -34,6 +37,8 @@ const { Presenter } = require('./presenter');
 const ai = require('./ai-client');
 const { evaluateAsync } = require('./fhirpath-ips');
 const { checkNarrative } = require('../library/narrative-check');
+const { analysisStep } = require('./analysis');
+const { nationalityStep } = require('./nationality');
 
 const IPS_BUNDLE_PROFILE = 'http://hl7.org/fhir/uv/ips/StructureDefinition/Bundle-uv-ips';
 const VALIDATE_TIMEOUT_MS = 120000;
@@ -99,14 +104,13 @@ const validation = {
     }
     const cfg = module.config.validator || {};
     const profiles = Array.isArray(cfg.profiles) ? cfg.profiles : [IPS_BUNDLE_PROFILE];
-    // the validator's own IPS checks (code systems and value sets the IPS expects), unless
-    // the configuration turns them off
-    const checkIpsCodes = cfg.checkIpsCodes !== false;
+    // no checkIpsCodes: validator 7.0.4 dropped its IPS code checks, and refuses the parameter
+    // ("Unable to process param checkIpsCodes"), failing every validation
     const started = Date.now();
     // fhir-validator-wrapper 1.5.0 or later: earlier versions sent the profiles in a form the
     // validator service refuses
     // the analysed copy: the translations are in it, and the validator should see them
-    const outcome = await v.validate(JSON.stringify(row.analysed || row.bundle), { profiles, checkIpsCodes, timeout: VALIDATE_TIMEOUT_MS });
+    const outcome = await v.validate(JSON.stringify(row.analysed || row.bundle), { profiles, timeout: VALIDATE_TIMEOUT_MS });
     if (!outcome || outcome.resourceType !== 'OperationOutcome') {
       throw new Error('The validator did not return an OperationOutcome');
     }
@@ -122,6 +126,64 @@ const validation = {
   }
 };
 
+/**
+ * National profiles: the document is validated against each national profile - the
+ * national IG's package is loaded into the validator first (once), then the document is
+ * validated against the IG's profile on Bundle, as the validation step validates it. For
+ * each profile, the result keeps the OperationOutcome and whether the document passed: no
+ * errors (or fatal issues). A profile whose package can't be loaded, or that the validator
+ * can't validate against, is kept with the reason (pass is then null), and doesn't stop the
+ * pipeline.
+ */
+const national = {
+  name: 'national',
+  async run(row, project, module) {
+    const list = module.store.nationalProfiles();
+    const started = Date.now();
+    if (list.length === 0) {
+      module.store.saveResult(row.id, 'national', { ms: 0, profiles: [] });
+      return 'national profiles: none';
+    }
+    const v = module.validator;
+    if (!v) {
+      throw new Error('The validator is not configured (modules.ips.validator)');
+    }
+    if (!v.isRunning()) {
+      throw new Error('The validator is not running');
+    }
+    const doc = JSON.stringify(row.analysed || row.bundle);
+    const profiles = [];
+    for (const np of list) {
+      const entry = { id: np.id, jurisdiction: np.jurisdiction, packageId: np.packageId, version: np.version, url: np.url };
+      const t0 = Date.now();
+      try {
+        await module.loadNationalPackage(np.packageId, np.version);
+        const outcome = await v.validate(doc, { profiles: [np.url], timeout: VALIDATE_TIMEOUT_MS });
+        if (!outcome || outcome.resourceType !== 'OperationOutcome') {
+          throw new Error('The validator did not return an OperationOutcome');
+        }
+        entry.counts = issueCounts(outcome);
+        entry.pass = !entry.counts.error && !entry.counts.fatal;
+        entry.outcome = outcome;
+      } catch (e) {
+        entry.pass = null;
+        entry.error = e.message;
+      }
+      entry.ms = Date.now() - t0;
+      profiles.push(entry);
+    }
+    module.store.saveResult(row.id, 'national', {
+      ms: Date.now() - started,
+      validatorVersion: typeof v.jarVersion === 'function' ? v.jarVersion() : null,
+      profiles
+    });
+    const passed = profiles.filter(p => p.pass === true).length;
+    const failed = profiles.filter(p => p.pass === false).length;
+    const unchecked = profiles.length - passed - failed;
+    return `national profiles: ${passed} passed, ${failed} failed` + (unchecked ? `, ${unchecked} not checked` : '');
+  }
+};
+
 // ---- the terminology check ------------------------------------------------------------
 
 /**
@@ -485,6 +547,56 @@ function translationOf(coding) {
   };
 }
 
+const SNOMED_CT = 'http://snomed.info/sct';
+
+/**
+ * The SNOMED CT edition a document's codes are taken to be from when they don't say: the
+ * edition of a national profile for the nation the document is from (the nationality step).
+ * Only the translate step uses it - the terminology check takes the codes as they are, so a
+ * code that is fine as it is passes whatever its edition, and one whose edition says otherwise
+ * doesn't.
+ * @returns {{edition: string, packageId: string, version: string, jurisdiction: string}|null}
+ */
+function defaultSnomedEdition(module, row) {
+  const jurisdiction = module.store.readResult(row.id, 'nationality')?.result?.jurisdiction;
+  if (!jurisdiction) {
+    return null;
+  }
+  const np = module.store.nationalProfiles().find(p => p.jurisdiction === jurisdiction && p.snomedEdition);
+  return np ? { edition: np.snomedEdition, packageId: np.packageId, version: np.version, jurisdiction } : null;
+}
+
+/** A concept with its SNOMED CT codings that have no version given the edition (a copy; the concept is unchanged). */
+function withSnomedEdition(concept, edition) {
+  if (!edition || !Array.isArray(concept.coding)) {
+    return concept;
+  }
+  return { ...concept, coding: concept.coding.map(c => (c && c.system === SNOMED_CT && !c.version ? { ...c, version: `${SNOMED_CT}/${edition}` } : c)) };
+}
+
+/** The SNOMED CT edition a version names (its module id, without the release date), or the version itself. */
+function editionOf(system, version) {
+  if (system === SNOMED_CT && typeof version === 'string') {
+    const m = version.match(/^http:\/\/snomed\.info\/x?sct\/(\d+)(?:\/version\/\d+)?$/);
+    if (m) {
+      return m[1];
+    }
+  }
+  return version;
+}
+
+/**
+ * Whether a concept already has a coding: the same system and code, and - when both say - the
+ * same version. A version that differs makes it a different coding: the same SNOMED CT code in
+ * the International Edition is what a translation from a national edition is for, even though
+ * the code is the same (SNOMED CT versions are compared by edition, not release). A coding with
+ * no version already stands for the code, whatever the translation's version.
+ */
+function hasCoding(codings, coding) {
+  return codings.some(x => x && x.system === coding.system && x.code === coding.code &&
+    (!x.version || !coding.version || editionOf(x.system, x.version) === editionOf(coding.system, coding.version)));
+}
+
 /** A CodeableConcept as the server should see it: without our extensions. */
 function withoutOurExtensions(concept) {
   const c = structuredClone(concept);
@@ -525,6 +637,8 @@ const translate = {
     const budget = { left: MAX_CHECKS_PER_DOCUMENT };
     const cache = module.txCache || (module.txCache = new Map());
     const started = Date.now();
+    // SNOMED CT codes with no version are taken to be from the edition of the document's nation
+    const defaultEdition = defaultSnomedEdition(module, row);
     // what happened to each concept, for the translation view
     const entries = [];
     // the same resource in two sections, and the same concept in two places: once
@@ -558,11 +672,11 @@ const translate = {
         } else if (budget.left <= 0) {
           translation = { matches: [], failed: true, check, message: `not translated - the document has more codes than are checked (${MAX_CHECKS_PER_DOCUMENT})` };
         } else {
-          const cacheKey = `translate|${key}`;
+          const cacheKey = `translate|${defaultEdition ? defaultEdition.edition : ''}|${key}`;
           translation = cache.get(cacheKey);
           if (!translation) {
             budget.left--;
-            translation = await translateConcept(module.tx, valueSets, withoutOurExtensions(c.concept), target);
+            translation = await translateConcept(module.tx, valueSets, withSnomedEdition(withoutOurExtensions(c.concept), defaultEdition?.edition), target);
             if (!translation.failed) {
               if (cache.size >= MAX_CACHED_ANSWERS) {
                 cache.delete(cache.keys().next().value);
@@ -592,7 +706,7 @@ const translate = {
       }
       let added = 0;
       for (const m of translation.matches) {
-        if (codings.some(x => x && x.system === m.coding.system && x.code === m.coding.code)) {
+        if (hasCoding(codings, m.coding)) {
           entry.added.push({ ...m, present: true });
           continue; // already there
         }
@@ -617,7 +731,7 @@ const translate = {
         entry.message = translation.matches.length > 0 ? 'The translation gave only codings the concept already has' : (translation.message || 'The terminology server has no translation');
       }
     }
-    module.store.saveResult(row.id, 'translate', { ms: Date.now() - started, server: module.tx.url, counts, entries });
+    module.store.saveResult(row.id, 'translate', { ms: Date.now() - started, server: module.tx.url, counts, entries, ...(defaultEdition ? { defaultEdition } : {}) });
     return `translate: ${counts.translated} of ${counts.tried} concepts translated (${counts.codings} codings added)` +
       (counts.failed ? `, ${counts.failed} not translated (see the log)` : '');
   }
@@ -1003,10 +1117,10 @@ const aiStep = {
 };
 
 /** The steps, in order. Only the ones that exist yet. */
-const STEPS = [translate, narrative, validation, terminology, profilesStep, aiStep];
+const STEPS = [nationalityStep, analysisStep, translate, narrative, validation, national, terminology, profilesStep, aiStep];
 
 module.exports = {
-  STEPS, translate, narrative, validation, terminology, profiles: profilesStep, ai: aiStep, checkConstraint, valueSetsIn, lookupDisplay, checkConcept, documentForAi, assessmentOf, aiSystemPrompt, AI_SYSTEM_PROMPT, checkOf, addCheck, stripChecks, translateConcept, translationOf,
+  STEPS, analysis: analysisStep, translate, narrative, validation, national, terminology, profiles: profilesStep, ai: aiStep, checkConstraint, valueSetsIn, lookupDisplay, checkConcept, documentForAi, assessmentOf, aiSystemPrompt, AI_SYSTEM_PROMPT, checkOf, addCheck, stripChecks, translateConcept, translationOf, defaultSnomedEdition, withSnomedEdition, hasCoding,
   validateCodeInValueSet, validateCodeInSystem, issueCounts, issueSummary,
   IPS_BUNDLE_PROFILE, CHECK_EXTENSION, TRANSLATION_EXTENSION, MAX_CHECKS_PER_DOCUMENT, MAX_CACHED_ANSWERS
 };

package/ips/presenter.js

@@ -969,6 +969,6 @@ const GENERIC = {
 };
 
 module.exports = {
-  Presenter, COLUMNS, GENERIC, describeResource, NONE,
+  Presenter, COLUMNS, GENERIC, describeResource, codeText, NONE,
   dateText, periodText, quantityText, rangeText, humanNameText, addressText, identifierText, contactPointText, annotationText
 };