fhirsmith 0.17.0 → 0.18.0

package/tx/sct/expressions.js

@@ -22,10 +22,14 @@ const NO_REFERENCE = 0xFFFFFFFF;
 const MRCM_ATTRIBUTE_DOMAIN_REFSET = 723561005n;
 const MRCM_ATTRIBUTE_RANGE_REFSET = 723562003n;
 // contentTypeId values that apply when validating a postcoordinated expression.
-// 723593002 (precoordinated only) and 723595009 (new precoordinated only) are
-// rules about authoring precoordinated concepts and do not constrain expressions.
+// 723594008 (all precoordinated content) and 723593002 (all new precoordinated
+// content) are rules about authoring precoordinated concepts and do not constrain
+// expressions. (723594008 was used here as the postcoordinated type until Oct 2026,
+// which brought the body-structure part-of attributes into the domain rules and
+// dropped |Has ingredient|, and swapped the range used for the attributes that
+// have a precoordinated-specific range.)
 const MRCM_CONTENT_TYPE_ALL = 723596005n;
-const MRCM_CONTENT_TYPE_POSTCOORDINATED = 723594008n;
+const MRCM_CONTENT_TYPE_POSTCOORDINATED = 723595009n;
 // ruleStrengthId value for an optional rule (the other value, 723597001, is mandatory).
 const MRCM_RULE_STRENGTH_OPTIONAL = 723598006n;
 
@@ -1657,8 +1661,8 @@ class SnomedExpressionServices {
         this.checkRefinement(refinement);
         this.checkRefinementDomain(expression, refinement);
         this.checkRefinementRange(refinement);
-        this.checkRefinementGrouped(expression, refinement);
       }
+      this.selfGroupRefinements(expression);
     }
 
     if (expression.hasRefinementGroups()) {
@@ -1679,9 +1683,10 @@ class SnomedExpressionServices {
    * focus concept the attribute is applied to must be in one of the attribute's
    * domains (see applicableDomainRules for how several rules combine).
    *
-   * Attributes with no rule in this edition's MRCM are not checked, and neither
-   * is cardinality (checkExpressionCardinality), grouping (checkRefinementGrouped)
-   * or the range constraint (checkRefinementRange, which needs ECL).
+   * An attribute with no rule in this edition's MRCM is not allowed at all (see
+   * applicableDomainRules). Cardinality (checkExpressionCardinality), grouping
+   * (selfGroupRefinements) and the range constraint (checkRefinementRange, which
+   * needs ECL) are checked elsewhere.
    *
    * @param {SnomedExpression} expression - the expression the refinement is on
    * @param {SnomedRefinement} refinement
@@ -1692,6 +1697,11 @@ class SnomedExpressionServices {
       return;
     }
     const result = this.applicableDomainRules(expression, attribute);
+    if (result.noDomain) {
+      const attrDesc = this.describeConceptForMessage(attribute);
+      throw new Error(`The SNOMED CT concept model does not define any domain for the attribute ${attrDesc},`
+        + ` so it cannot be used in an expression`);
+    }
     if (result.failed) {
       const attrDesc = this.describeConceptForMessage(attribute);
       const focusDesc = result.focus.map(f => this.describeConceptForMessage(f)).join(' + ');
@@ -1722,10 +1732,11 @@ class SnomedExpressionServices {
    *
    * @param {SnomedExpression} expression
    * @param {number} attribute - concept index of the attribute
-   * @returns {{rules: Array, focus: number[], failed: string|null}} the rules that
+   * @returns {{rules: Array, focus: number[], failed: string|null, noDomain?: boolean}} the rules that
    *   apply (for cardinality and grouping - empty when the attribute is out of
    *   domain), the focus concepts, and when the attribute is not allowed on this
-   *   focus, a description of the domain(s) it is restricted to
+   *   focus, a description of the domain(s) it is restricted to (noDomain is set
+   *   when there are none at all)
    */
   applicableDomainRules(expression, attribute) {
     const rules = this.mrcmAttributeDomains().get(attribute);
@@ -1735,12 +1746,21 @@ class SnomedExpressionServices {
         focus.push(concept.reference);
       }
     }
-    if (!rules || rules.length === 0 || focus.length === 0) {
-      // This edition's concept model says nothing about this attribute (3 active
-      // attributes internationally have no domain rule and appear in no
-      // postcoordination domain template), so there is nothing to check it against.
+    if (this.mrcmAttributeDomains().size === 0 || focus.length === 0) {
+      // No MRCM in this edition (or nothing to check against), so the domain check is off
       return { rules: rules || [], focus, failed: null };
     }
+    if (!rules || rules.length === 0) {
+      // The MRCM attribute domain reference set is the list of attributes that may
+      // be used, and in which domains: an attribute it says nothing about (for
+      // postcoordinated content) is not allowed anywhere. Internationally that is
+      // a handful of concept model attributes that only appear in precoordinated
+      // definitions (|Has definitional manifestation|, |Subject of information|,
+      // the body structure part-of attributes), and it also catches the linkage
+      // concepts that are not concept model attributes at all. This matches
+      // Ontoserver (Oct 2026); before that an attribute with no rule was not checked.
+      return { rules: [], focus, failed: 'nowhere', noDomain: true };
+    }
 
     const holds = rule => focus.some(f => rule.isRefset
       ? this.conceptInRefSet(rule.domain, f)
@@ -1772,44 +1792,77 @@ class SnomedExpressionServices {
   }
 
   /**
-   * Check that an attribute the MRCM marks as grouped is actually in a relationship
-   * group. This is only ever called for refinements that are NOT in a group.
-   *
-   * The MRCM attribute domain reference set carries a `grouped` flag per rule, and it
-   * is a real constraint rather than a stylistic preference: `363698007 |Finding site|`
-   * is grouped, so `40468003:363698007=10200004` is not a valid expression even though
-   * every part of it is - it has to be written `40468003:{363698007=10200004}`. The
-   * distinction matters because a group is what ties an attribute to the others that
-   * apply with it, and an expression that omits the braces has not said which.
+   * Move each ungrouped refinement whose attribute the MRCM marks as grouped into a
+   * relationship group of its own.
    *
-   * SNOMED's postcoordination guide calls the ungrouped form Close To User Form and
-   * defines a transformation ("Adding a Self-grouped Attribute") that converts it to
-   * the Classifiable Form. That transformation is not implemented here, so the
-   * ungrouped form is rejected rather than silently repaired: telling the caller their
-   * expression is not classifiable is honest, quietly guessing what they meant is not.
+   * The MRCM attribute domain reference set carries a `grouped` flag per rule:
+   * `363698007 |Finding site|` is grouped, so the classifiable form of
+   * `40468003:363698007=10200004` is `40468003:{363698007=10200004}`. SNOMED's
+   * postcoordination guide calls the ungrouped spelling Close To User Form and
+   * defines the transformation to the Classifiable Form ("Adding a Self-grouped
+   * Attribute"): each such attribute is placed in a group by itself. That is what
+   * this does, so the ungrouped spelling is accepted (as Ontoserver and Snowstorm
+   * accept it) and everything downstream - cardinality, rendering, the normal form
+   * and so subsumption - sees the grouped form. Until Oct 2026 the ungrouped
+   * spelling was rejected instead.
    *
-   * As elsewhere in this check, an attribute with no rule in this edition's MRCM is
-   * left alone. Only the rules for the domain(s) the focus concept is in count
-   * (see applicableDomainRules), and where several of those apply the strictest wins.
+   * Only the rules for the domain(s) the focus concept is in count (see
+   * applicableDomainRules); an attribute that is ungrouped in every applicable
+   * rule, or that has no applicable rule, is left where it is.
    *
-   * @param {SnomedExpression} expression - the expression the refinement is on
-   * @param {SnomedRefinement} refinement - a refinement outside any group
+   * @param {SnomedExpression} expression - an expression with ungrouped refinements,
+   *   whose references have already been resolved and whose domains have been checked
    */
-  checkRefinementGrouped(expression, refinement) {
-    const attribute = refinement.name ? refinement.name.reference : NO_REFERENCE;
-    if (attribute === undefined || attribute === null || attribute === NO_REFERENCE) {
-      return;
-    }
-    const rules = this.applicableDomainRules(expression, attribute).rules;
-    if (rules.length === 0) {
-      return;
+  selfGroupRefinements(expression) {
+    const keep = [];
+    for (const refinement of expression.refinements) {
+      const attribute = refinement.name ? refinement.name.reference : NO_REFERENCE;
+      let grouped = false;
+      if (attribute !== undefined && attribute !== null && attribute !== NO_REFERENCE) {
+        const rules = this.applicableDomainRules(expression, attribute).rules;
+        grouped = rules.some(rule => rule.grouped);
+      }
+      if (grouped) {
+        const group = new SnomedRefinementGroup();
+        group.refinements.push(refinement);
+        expression.refinementGroups.push(group);
+      } else {
+        keep.push(refinement);
+      }
     }
-    if (!rules.some(rule => rule.grouped)) {
-      return;
+    expression.refinements = keep;
+  }
+
+  /**
+   * The inverse of selfGroupRefinements, for rendering an expression for a user: a
+   * group holding a single refinement whose attribute the MRCM never groups (laterality,
+   * say) is written as an ungrouped refinement, which is how the normal form rules put
+   * it. The canonical form groups every refinement (see SnomedExpression.canonical), which
+   * is right for subsumption but reads oddly as output. An attribute with any applicable
+   * grouped rule, or no rule at all, stays in its group.
+   *
+   * @param {SnomedExpression} expression - with its references resolved; modified in place
+   * @returns {SnomedExpression} the same expression
+   */
+  ungroupNeverGroupedRefinements(expression) {
+    const keep = [];
+    for (const group of expression.refinementGroups) {
+      let ungroup = false;
+      if (group.refinements.length === 1) {
+        const attribute = group.refinements[0].name ? group.refinements[0].name.reference : NO_REFERENCE;
+        if (attribute !== undefined && attribute !== null && attribute !== NO_REFERENCE) {
+          const rules = this.applicableDomainRules(expression, attribute).rules;
+          ungroup = rules.length > 0 && rules.every(rule => !rule.grouped);
+        }
+      }
+      if (ungroup) {
+        expression.refinements.push(group.refinements[0]);
+      } else {
+        keep.push(group);
+      }
     }
-    const attrDesc = this.describeConceptForMessage(attribute);
-    throw new Error(`The SNOMED CT concept model requires the attribute ${attrDesc} to be in a`
-      + ` relationship group, so it cannot be used ungrouped (write it as {${attrDesc} = ...})`);
+    expression.refinementGroups = keep;
+    return expression;
   }
 
   /**
@@ -2022,10 +2075,9 @@ class SnomedExpressionServices {
    * rangeConstraint ECL string.
    *
    * Where an attribute has a range specifically for postcoordinated content
-   * (contentTypeId 723594008) that one replaces the general "all content" range
-   * rather than adding to it - 11 attributes internationally do this. After that
-   * rule every attribute has exactly one applicable constraint, so there is no
-   * question of ANDing or ORing them.
+   * (contentTypeId 723595009) that one replaces the general "all content" range
+   * rather than adding to it. After that rule every attribute has exactly one
+   * applicable constraint, so there is no question of ANDing or ORing them.
    *
    * @returns {Map<number, string>}
    */
@@ -2260,10 +2312,15 @@ class SnomedExpressionServices {
         }
       }
       if (!ok) {
+        const desc = this.describeConceptForMessage(concept.reference);
+        const limitDesc = limits.map(l => {
+          const ix = this.conceptIndexOf(BigInt(l));
+          return ix === null ? l : this.describeConceptForMessage(ix);
+        });
         if (limits.length == 1) {
-          throw new Error(`Concept ${concept.code} is not valid in this context (must be a ${limits[0]})`);
+          throw new Error(`Concept ${desc} is not valid in this context (must be a descendant of ${limitDesc[0]})`);
         } else {
-          throw new Error(`Concept ${concept.code} is not valid in this context (must be a descendent of one of ${limits})`);
+          throw new Error(`Concept ${desc} is not valid in this context (must be a descendant of one of ${limitDesc.join(', ')})`);
         }
       }
     }
@@ -2420,7 +2477,11 @@ class SnomedExpressionServices {
    * Validate refinement
    */
   checkRefinement(refinement) {
-    this.checkConcept(refinement.name, ['410662002', '106237007']);
+    // Only concept model attributes (410662002) may be used as attributes. The wider
+    // 106237007 |Linkage concept| used to be allowed too, which let in things like
+    // 20401003 |With| and 280452008 |Interpretation| that are not attributes in the
+    // concept model (and could never have an MRCM rule anyway).
+    this.checkConcept(refinement.name, ['410662002']);
     this.checkExpression(refinement.value);
   }
 

package/tx/syndication/syndication-feed.js

@@ -0,0 +1,218 @@
+/**
+ * Renders the syndication store as an Atom feed for one tx endpoint, following the
+ * Terminology Syndication Feed IG (NCTS ASF profile), with RFC 5005 archived feeds for
+ * paging:
+ *
+ *   {endpoint}/syndication            the current document - the newest entries, fewer
+ *                                     than a page of them - linked to the newest archive
+ *   {endpoint}/syndication/archive/n  archive n (1 = oldest), exactly PAGE_SIZE entries,
+ *                                     linked to archive n-1. Entries are never changed or
+ *                                     removed, so an archive never changes once it exists
+ *   {endpoint}/syndication/files/x    a resource file copied into the store
+ *
+ * The IG's query-string filters are not supported.
+ */
+
+const crypto = require('crypto');
+const { VersionUtilities } = require('../../library/version-utilities');
+
+const PAGE_SIZE = 30;
+const ATOM_NS = 'http://www.w3.org/2005/Atom';
+const NCTS_NS = 'http://ns.electronichealth.net.au/ncts/syndication/asf/extensions/1.0.0';
+const FH_NS = 'http://purl.org/syndication/history/1.0';
+const ASF_PROFILE = 'http://ns.electronichealth.net.au/ncts/syndication/asf/profile/1.0.0';
+
+/**
+ * Escape for XML and HTML. Characters XML 1.0 does not allow at all (C0 controls other than
+ * tab/newline/return, unpaired surrogates, U+FFFE/U+FFFF) are dropped: they come from package
+ * and resource metadata, and one of them would make the document unparseable - for good, in
+ * the case of an archive, which never changes.
+ */
+function esc(s) {
+  return String(s ?? '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/** major.minor for an endpoint's FHIR version */
+function feedFhirVersion(fhirVersion) {
+  return VersionUtilities.getMajMin(String(fhirVersion));
+}
+
+/**
+ * The feed id for an endpoint: stable for as long as the store exists, whatever host name
+ * the feed is read through (RFC 4287 4.2.6). The archive documents share it (RFC 5005).
+ */
+function feedId(storeId, endpointPath) {
+  const h = crypto.createHash('sha1').update(storeId + '|' + endpointPath).digest('hex');
+  return `urn:uuid:${h.substring(0, 8)}-${h.substring(8, 12)}-5${h.substring(13, 16)}-` +
+    `${((parseInt(h.substring(16, 18), 16) & 0x3f) | 0x80).toString(16)}${h.substring(18, 20)}-${h.substring(20, 32)}`;
+}
+
+/**
+ * Which entries go in which document.
+ * @param {Object[]} entries - the endpoint's entries, oldest first
+ * @param {number|null} page - archive number, or null for the current document
+ * @returns {{archives: number, entries: Object[]}|null} null if there is no such archive
+ */
+function selectPage(entries, page) {
+  const archives = Math.floor(entries.length / PAGE_SIZE);
+  if (page == null) {
+    return { archives, entries: entries.slice(archives * PAGE_SIZE) };
+  }
+  if (!Number.isInteger(page) || page < 1 || page > archives) {
+    return null;
+  }
+  return { archives, entries: entries.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE) };
+}
+
+function linkHref(entry, base) {
+  return entry.link.href || `${base}/syndication/files/${entry.link.file}`;
+}
+
+function isFhirCategory(entry) {
+  return entry.category.term.startsWith('FHIR_');
+}
+
+function renderEntry(entry, base, fhirVersion) {
+  const lines = [];
+  lines.push('  <entry>');
+  lines.push(`    <id>${esc(entry.id)}</id>`);
+  lines.push(`    <title>${esc(entry.title)}</title>`);
+  lines.push(`    <updated>${esc(entry.inducted)}</updated>`);
+  lines.push(`    <published>${esc(entry.inducted)}</published>`);
+  if (entry.summary) {
+    lines.push(`    <summary>${esc(entry.summary)}</summary>`);
+  }
+  if (entry.rights) {
+    lines.push(`    <rights>${esc(entry.rights)}</rights>`);
+  }
+  const c = entry.category;
+  lines.push(`    <category scheme="${esc(c.scheme)}" term="${esc(c.term)}"${c.label ? ` label="${esc(c.label)}"` : ''}/>`);
+  const l = entry.link;
+  lines.push(`    <link rel="alternate" href="${esc(linkHref(entry, base))}" type="${esc(l.type)}" length="${l.length}" ncts:sha256Hash="${esc(l.sha256)}"/>`);
+  lines.push(`    <ncts:contentItemIdentifier>${esc(entry.identifier)}</ncts:contentItemIdentifier>`);
+  lines.push(`    <ncts:contentItemVersion>${esc(entry.version)}</ncts:contentItemVersion>`);
+  if (isFhirCategory(entry)) {
+    lines.push(`    <ncts:fhirVersion>${esc(entry.fhirVersion || fhirVersion)}</ncts:fhirVersion>`);
+  }
+  lines.push('  </entry>');
+  return lines.join('\n');
+}
+
+/**
+ * @param {Object} params
+ * @param {SyndicationStore} params.store
+ * @param {string} params.endpointPath - e.g. /tx/r4
+ * @param {string} params.fhirVersion - the endpoint's FHIR version
+ * @param {string} params.base - absolute url of the endpoint, e.g. https://tx.fhir.org/tx/r4
+ * @param {number|null} params.page - archive number, or null for the current document
+ * @param {string} [params.title] - server title
+ * @param {string} [params.serverVersion]
+ * @returns {string|null} the Atom document, or null if there is no such archive
+ */
+function renderAtom(params) {
+  const fhirVersion = feedFhirVersion(params.fhirVersion);
+  const all = params.store.entriesFor(fhirVersion);
+  const sel = selectPage(all, params.page);
+  if (!sel) {
+    return null;
+  }
+  const feedUrl = `${params.base}/syndication`;
+  const archiveUrl = (n) => `${feedUrl}/archive/${n}`;
+  const self = params.page == null ? feedUrl : archiveUrl(params.page);
+  // the newest entry in this document; an empty one dates from when the store was started
+  const updated = sel.entries.length > 0 ? sel.entries[sel.entries.length - 1].inducted : params.store.created;
+
+  const out = [];
+  out.push('<?xml version="1.0" encoding="UTF-8"?>');
+  out.push(`<feed xmlns="${ATOM_NS}" xmlns:ncts="${NCTS_NS}" xmlns:fh="${FH_NS}">`);
+  out.push(`  <id>${esc(feedId(params.store.id, params.endpointPath))}</id>`);
+  out.push(`  <title>${esc((params.title || 'FHIRsmith') + ' Syndication Feed (FHIR ' + fhirVersion + ')')}</title>`);
+  out.push(`  <subtitle>Content loaded by the terminology server at ${esc(params.base)}</subtitle>`);
+  out.push(`  <updated>${esc(updated)}</updated>`);
+  out.push(`  <generator uri="https://github.com/HealthIntersections/FHIRsmith"${params.serverVersion ? ` version="${esc(params.serverVersion)}"` : ''}>FHIRsmith</generator>`);
+  out.push(`  <link rel="self" type="application/atom+xml" href="${esc(self)}"/>`);
+  out.push(`  <link rel="current" type="application/atom+xml" href="${esc(feedUrl)}"/>`);
+  if (params.page == null) {
+    if (sel.archives > 0) {
+      out.push(`  <link rel="prev-archive" type="application/atom+xml" href="${esc(archiveUrl(sel.archives))}"/>`);
+    }
+  } else {
+    out.push('  <fh:archive/>');
+    if (params.page > 1) {
+      out.push(`  <link rel="prev-archive" type="application/atom+xml" href="${esc(archiveUrl(params.page - 1))}"/>`);
+    }
+    // no next-archive: it would change the newest archive when the next one is made, and an
+    // archive never changes (RFC 5005 makes it optional; consumers walk back from current)
+  }
+  out.push(`  <ncts:atomSyndicationFormatProfile>${ASF_PROFILE}</ncts:atomSyndicationFormatProfile>`);
+  // newest first; consumers go by <updated>, not order
+  for (const entry of [...sel.entries].reverse()) {
+    out.push(renderEntry(entry, params.base, fhirVersion));
+  }
+  out.push('</feed>');
+  return out.join('\n') + '\n';
+}
+
+/**
+ * The same document, for people: a table of entries with links to the other documents.
+ * Takes the same parameters as renderAtom; returns HTML content (no page), or null.
+ */
+function renderHtml(params) {
+  const fhirVersion = feedFhirVersion(params.fhirVersion);
+  const all = params.store.entriesFor(fhirVersion);
+  const sel = selectPage(all, params.page);
+  if (!sel) {
+    return null;
+  }
+  const feedUrl = `${params.base}/syndication`;
+  const atomUrl = params.page == null ? feedUrl : `${feedUrl}/archive/${params.page}`;
+  const h = [];
+  h.push('<p>The content this server has loaded, as a <a href="https://build.fhir.org/ig/FHIR/fhir-syndication-ig/en/">Terminology Syndication Feed</a>. ');
+  h.push(`Subscribe to <a href="${esc(atomUrl)}?_format=atom">${esc(feedUrl)}</a> in a feed reader or syndication client. `);
+  h.push(`${all.length} ${all.length === 1 ? 'entry' : 'entries'} in all.</p>`);
+
+  const nav = [];
+  if (params.page == null) {
+    if (sel.archives > 0) {
+      nav.push(`<a href="${esc(feedUrl)}/archive/${sel.archives}">Older</a>`);
+    }
+  } else {
+    if (params.page > 1) {
+      nav.push(`<a href="${esc(feedUrl)}/archive/${params.page - 1}">Older</a>`);
+    }
+    nav.push(params.page < sel.archives
+      ? `<a href="${esc(feedUrl)}/archive/${params.page + 1}">Newer</a>`
+      : `<a href="${esc(feedUrl)}">Newer</a>`);
+    nav.push(`<a href="${esc(feedUrl)}">Newest</a>`);
+  }
+  const navHtml = nav.length > 0 ? `<p>${nav.join(' | ')}</p>` : '';
+  h.push(navHtml);
+
+  if (sel.entries.length === 0) {
+    h.push('<p><i>No entries</i></p>');
+  } else {
+    h.push('<table class="grid">');
+    h.push('<tr><th>Title</th><th>Type</th><th>Version</th><th>Added</th><th>Download</th></tr>');
+    for (const e of [...sel.entries].reverse()) {
+      h.push('<tr>');
+      h.push(`<td>${esc(e.title)}${e.summary ? `<br/><span style="color: grey">${esc(e.summary)}</span>` : ''}${e.rights ? `<br/><i>${esc(e.rights)}</i>` : ''}</td>`);
+      h.push(`<td>${esc(e.category.term)}${isFhirCategory(e) ? ` (R${esc((e.fhirVersion || fhirVersion).split('.')[0])})` : ''}</td>`);
+      h.push(`<td><code>${esc(e.version)}</code></td>`);
+      h.push(`<td>${esc(e.inducted.substring(0, 10))}</td>`);
+      h.push(`<td><a href="${esc(linkHref(e, params.base))}">${esc(e.link.length.toLocaleString())} bytes</a><br/><span style="font-size: 0.8em; color: grey">sha256: ${esc(e.link.sha256)}</span></td>`);
+      h.push('</tr>');
+    }
+    h.push('</table>');
+  }
+  h.push(navHtml);
+  return h.join('\n');
+}
+
+module.exports = { renderAtom, renderHtml, selectPage, feedId, feedFhirVersion, esc, PAGE_SIZE };