@cosyte/terminology 0.0.12 → 0.1.0

package/dist/index.cjs

@@ -72,19 +72,43 @@ var DIAGNOSTIC_CODES = {
   TERM_CONCEPT_HEADER_NOT_BILLABLE: "TERM_CONCEPT_HEADER_NOT_BILLABLE",
   /**
    * A ValueSet `compose` part could **not be expanded**: an intensional `include`/`exclude` whose
-   * code system was not supplied, an unresolvable referenced value set, or a `filter` operator the
-   * engine does not implement. Surfaced as a typed outcome that marks the expansion **incomplete**;
+   * code system was not supplied, an unresolvable referenced value set, a `filter` operator the
+   * engine does not implement, or a component whose declared code system version disagrees with the
+   * supplied release (or names a pin that release carries no version to confirm). Surfaced as a
+   * typed outcome that marks the expansion **incomplete**;
    * the engine **never** fabricates a member and **never** returns a silently-empty "no members"
    * answer for a part it could not compute (a false "not a member" is a clinical error).
    */
   TERM_VALUESET_CANNOT_EXPAND: "TERM_VALUESET_CANNOT_EXPAND",
   /**
    * A **pre-computed** `ValueSet.expansion` is **incomplete**: its `total` exceeds the number of
-   * `contains` entries, or it is flagged too-costly (the VSAC `$expand` >1200-code truncation
-   * hazard). The engine **never treats a truncated expansion as complete membership**: a code
-   * absent from a truncated expansion is `undetermined`, never a confident "not a member".
+   * `contains` entries, it is flagged too-costly (the VSAC `$expand` >1200-code truncation
+   * hazard), or it is marked `unclosed` (the value set is unbounded because it includes
+   * post-coordinated content, so no expansion can enumerate it). The engine **never treats an
+   * incomplete expansion as complete membership**: a code absent from one is `undetermined`, never
+   * a confident "not a member". The diagnostic's `detail` says which of those it was.
    */
   TERM_VALUESET_EXPANSION_TRUNCATED: "TERM_VALUESET_EXPANSION_TRUNCATED",
+  /**
+   * A `ValueSet.compose` component **enumerated** a code the release supplied for its `system` does
+   * not define, so the code was **not admitted** as a member. The never-fabricate invariant applied
+   * to an extensional selection: enumerating a code is the value set's claim that it exists, and
+   * asserting membership for it while holding the very release that shows it does not is the engine
+   * deciding against its own evidence.
+   *
+   * Raised **only** where the evidence is in hand: a release keyed by the component's `system` that
+   * the component's declared `version` (if any) agrees with. No release for that system, a declared
+   * version the supplied release does not agree with, or a component naming no `system` at all
+   * leaves the engine with no contrary evidence, so every enumerated code is carried and **no
+   * diagnostic is raised**: absence of evidence is not evidence the code is undefined.
+   *
+   * The answer stays **decided**, unlike {@link TERM_VALUESET_CANNOT_EXPAND}: the engine computed
+   * membership on the evidence it was given, so `expand` reports `complete: true` and
+   * `validateCodeInValueSet` reports a decided non-member for the dropped code, rather than a lower
+   * bound or a refusal. One diagnostic is raised per affected component, located by that
+   * component's own index path, however many of its codes were dropped.
+   */
+  TERM_VALUESET_ENUMERATED_CODE_UNDEFINED: "TERM_VALUESET_ENUMERATED_CODE_UNDEFINED",
   /**
    * A UCUM unit expression is **not valid**: it does not parse against the UCUM grammar, or it
    * names an atom absent from the vendored UCUM table. A **first-class typed outcome, never an
@@ -489,7 +513,7 @@ function provenanceOf(map, group, sourceSystem) {
   if (group?.target !== void 0) out.targetSystem = group.target;
   return Object.freeze(out);
 }
-function unmappedResult(source, mode, provenance, fixedTarget, otherMapUrl) {
+function unmappedResult(source, mode, provenance, fixedTarget, otherMapUrl, notRelated = []) {
   const out = {
     unmapped: true,
     code: "TERM_TRANSLATE_UNMAPPED",
@@ -499,13 +523,15 @@ function unmappedResult(source, mode, provenance, fixedTarget, otherMapUrl) {
   };
   if (fixedTarget !== void 0) out.fixedTarget = fixedTarget;
   if (otherMapUrl !== void 0) out.otherMapUrl = otherMapUrl;
+  if (notRelated.length > 0) out.notRelated = Object.freeze(notRelated);
   return Object.freeze(out);
 }
 function translate(sourceCoding, map) {
   const source = coding(sourceCoding);
   const system = source.system;
-  const matches = [];
-  let firstMatchGroup;
+  const rows = [];
+  const notRelated = [];
+  let firstRowGroup;
   let sourceCodePresent = false;
   let fallbackGroup;
   for (const group of map.group) {
@@ -522,23 +548,45 @@ function translate(sourceCoding, map) {
           ...t.display !== void 0 ? { display: t.display } : {},
           ...group.targetVersion !== void 0 ? { version: group.targetVersion } : {}
         });
-        const match = {
-          target: targetCoding,
-          relationship: equivalenceToRelationship(t.equivalence),
-          equivalence: t.equivalence
-        };
-        if (t.comment !== void 0) match.comment = t.comment;
-        matches.push(Object.freeze(match));
-        if (firstMatchGroup === void 0) firstMatchGroup = group;
+        if (t.equivalence === "disjoint") {
+          const assertion = {
+            target: targetCoding,
+            relationship: equivalenceToRelationship(t.equivalence),
+            equivalence: t.equivalence
+          };
+          if (t.comment !== void 0) assertion.comment = t.comment;
+          const frozen = Object.freeze(assertion);
+          notRelated.push(frozen);
+          rows.push(frozen);
+        } else {
+          const match = {
+            target: targetCoding,
+            relationship: equivalenceToRelationship(t.equivalence),
+            equivalence: t.equivalence
+          };
+          if (t.comment !== void 0) match.comment = t.comment;
+          rows.push(Object.freeze(match));
+        }
+        if (firstRowGroup === void 0) firstRowGroup = group;
       }
     }
   }
-  if (matches.length > 0) {
-    return Object.freeze({
-      unmapped: false,
-      matches: Object.freeze(matches),
-      provenance: provenanceOf(map, firstMatchGroup, system)
-    });
+  if (rows.length > 0) {
+    if (notRelated.length < rows.length) {
+      return Object.freeze({
+        unmapped: false,
+        matches: Object.freeze(rows),
+        provenance: provenanceOf(map, firstRowGroup, system)
+      });
+    }
+    return unmappedResult(
+      source,
+      "none",
+      provenanceOf(map, firstRowGroup, system),
+      void 0,
+      void 0,
+      notRelated
+    );
   }
   if (!sourceCodePresent && fallbackGroup?.unmapped !== void 0) {
     const um = fallbackGroup.unmapped;
@@ -561,7 +609,7 @@ function translate(sourceCoding, map) {
   return unmappedResult(
     source,
     "none",
-    provenanceOf(map, firstMatchGroup, system),
+    provenanceOf(map, firstRowGroup, system),
     void 0,
     void 0
   );
@@ -1071,6 +1119,7 @@ function validateCode(cs, code) {
 
 // src/valueset/load.ts
 var TOO_COSTLY_EXTENSION = "http://hl7.org/fhir/StructureDefinition/valueset-toocostly";
+var UNCLOSED_EXTENSION = "http://hl7.org/fhir/StructureDefinition/valueset-unclosed";
 function malformed2(path, fault) {
   throw new TerminologyError(FATAL_CODES.TERM_VALUESET_MALFORMED, `ValueSet ${path}: ${fault}`);
 }
@@ -1149,7 +1198,13 @@ function loadCompose(raw, path) {
       (c, i) => loadComponent(c, `${path}.exclude[${String(i)}]`)
     )
   );
-  return Object.freeze({ include, exclude });
+  const out = { include, exclude };
+  if (raw["inactive"] !== void 0) {
+    const inactive = getBoolean(raw, "inactive");
+    if (inactive === void 0) malformed2(`${path}.inactive`, "'inactive' is not a boolean");
+    out.inactive = inactive;
+  }
+  return Object.freeze(out);
 }
 function loadContains(raw, path) {
   if (!isJsonObject(raw)) malformed2(path, "contains entry is not an object");
@@ -1169,6 +1224,18 @@ function isTooCostly(raw) {
   }
   return false;
 }
+function isUnclosed(raw) {
+  for (const ext of getArray(raw, "extension") ?? []) {
+    if (typeof ext === "string") {
+      if (ext === UNCLOSED_EXTENSION) return true;
+      continue;
+    }
+    if (getString(ext, "url") !== UNCLOSED_EXTENSION) continue;
+    if (getBoolean(ext, "valueBoolean") === false) continue;
+    return true;
+  }
+  return false;
+}
 function loadExpansion(raw, path) {
   if (!isJsonObject(raw)) malformed2(path, "expansion is not an object");
   const contains = Object.freeze(
@@ -1177,8 +1244,9 @@ function loadExpansion(raw, path) {
     )
   );
   const total = getNumber(raw, "total");
-  const truncated2 = total !== void 0 && total > contains.length || isTooCostly(raw);
-  const out = { contains, truncated: truncated2 };
+  const unclosed = isUnclosed(raw);
+  const truncated2 = total !== void 0 && total > contains.length || isTooCostly(raw) || unclosed;
+  const out = { contains, truncated: truncated2, unclosed };
   if (total !== void 0) out.total = total;
   return Object.freeze(out);
 }
@@ -1248,11 +1316,12 @@ function valueSet(value) {
     value.split(",").map((v) => v.trim()).filter((v) => v.length > 0)
   );
 }
-function propertyValue(concept, property) {
+function propertyValues(concept, property) {
+  const values = [];
   for (const p of concept.properties) {
-    if (p.code === property) return typeof p.value === "string" ? p.value : String(p.value);
+    if (p.code === property) values.push(typeof p.value === "string" ? p.value : String(p.value));
   }
-  return void 0;
+  return values;
 }
 var UNSUPPORTED = Object.freeze({ matched: false, supported: false });
 function matchesFilter(concept, filter, sub) {
@@ -1268,21 +1337,30 @@ function matchesFilter(concept, filter, sub) {
     case "is-not-a":
       return { matched: !isA(sub, concept.code, filter.value), supported: true };
     case "=": {
-      const actual = onCode ? concept.code : propertyValue(concept, filter.property);
-      return { matched: actual === filter.value, supported: true };
+      if (onCode) return { matched: concept.code === filter.value, supported: true };
+      return {
+        matched: propertyValues(concept, filter.property).includes(filter.value),
+        supported: true
+      };
     }
     case "in": {
       const set = valueSet(filter.value);
-      const actual = onCode ? concept.code : propertyValue(concept, filter.property);
-      return { matched: actual !== void 0 && set.has(actual), supported: true };
+      if (onCode) return { matched: set.has(concept.code), supported: true };
+      return {
+        matched: propertyValues(concept, filter.property).some((v) => set.has(v)),
+        supported: true
+      };
     }
     case "not-in": {
       const set = valueSet(filter.value);
-      const actual = onCode ? concept.code : propertyValue(concept, filter.property);
-      return { matched: actual === void 0 || !set.has(actual), supported: true };
+      if (onCode) return { matched: !set.has(concept.code), supported: true };
+      return {
+        matched: propertyValues(concept, filter.property).every((v) => !set.has(v)),
+        supported: true
+      };
     }
     case "exists": {
-      const present = onCode ? true : propertyValue(concept, filter.property) !== void 0;
+      const present = onCode ? true : propertyValues(concept, filter.property).length > 0;
       const wantPresent = filter.value.trim().toLowerCase() === "true";
       return { matched: present === wantPresent, supported: true };
     }
@@ -1323,6 +1401,43 @@ function truncated(detail, path) {
   d.path = path;
   return Object.freeze(d);
 }
+function enumeratedUndefined(detail, path) {
+  const d = {
+    code: "TERM_VALUESET_ENUMERATED_CODE_UNDEFINED",
+    detail
+  };
+  if (path !== void 0) d.path = path;
+  return Object.freeze(d);
+}
+function expansionIncompleteDetail(unclosed) {
+  return unclosed ? "pre-computed expansion is incomplete (marked unclosed: the value set is unbounded, so the snapshot is a sample of its membership)" : "pre-computed expansion is incomplete (truncated or too-costly)";
+}
+var ACTIVITY_UNCHECKABLE_DETAIL = "active-only value set: no usable code system release to check whether a selected code is active";
+var ENUMERATED_UNDEFINED_DETAIL = "enumerated code is not defined by the supplied code system release, so it is not a member";
+function usableRelease(component, system, ctx) {
+  if (system === void 0) return void 0;
+  const cs = ctx.codeSystems?.get(system);
+  if (cs === void 0) return void 0;
+  if (system === component.system && component.version !== void 0 && cs.version !== component.version) {
+    return void 0;
+  }
+  return cs;
+}
+function screenActive(members, component, ctx) {
+  const kept = /* @__PURE__ */ new Map();
+  let uncheckable = false;
+  for (const [key, member] of members) {
+    const cs = usableRelease(component, member.system, ctx);
+    if (cs === void 0) {
+      uncheckable = true;
+      continue;
+    }
+    const concept = cs.concepts.get(member.code);
+    if (concept?.status !== void 0 && !concept.status.active) continue;
+    kept.set(key, member);
+  }
+  return { members: kept, uncheckable };
+}
 function underPath(d, prefix) {
   const out = { code: d.code, detail: d.detail };
   out.path = d.path === void 0 ? prefix : `${prefix}/${d.path}`;
@@ -1360,7 +1475,7 @@ function expandReferencedValueSets(urls, ctx, visited, path) {
   }
   return { members: acc ?? /* @__PURE__ */ new Map(), complete, diagnostics };
 }
-function expandComponent(component, ctx, visited, path) {
+function expandComponent(component, ctx, visited, path, activeOnly = false) {
   const diagnostics = [];
   let complete = true;
   const { system, version, concept, filter, valueSet: valueSet2 } = component;
@@ -1370,9 +1485,18 @@ function expandComponent(component, ctx, visited, path) {
   let base = null;
   if (hasConcept) {
     base = /* @__PURE__ */ new Map();
+    const release = usableRelease(component, system, ctx);
+    let anyUndefined = false;
     for (const c of concept) {
-      base.set(codingKey(system, c.code), makeCoding(system, c.code, c.display, version));
+      const defined = release?.concepts.get(c.code);
+      if (release !== void 0 && defined === void 0) {
+        anyUndefined = true;
+        continue;
+      }
+      const display = c.display ?? defined?.display;
+      base.set(codingKey(system, c.code), makeCoding(system, c.code, display, version));
     }
+    if (anyUndefined) diagnostics.push(enumeratedUndefined(ENUMERATED_UNDEFINED_DETAIL, path));
   } else if (hasFilter || system !== void 0 && !hasVs) {
     if (system === void 0) {
       diagnostics.push(cannotExpand("intensional filter without a code system 'system'", path));
@@ -1383,6 +1507,27 @@ function expandComponent(component, ctx, visited, path) {
       diagnostics.push(cannotExpand("code system not supplied for intensional include", path));
       return { members: /* @__PURE__ */ new Map(), complete: false, diagnostics };
     }
+    let stampedVersion = version;
+    if (version !== void 0 && cs.version !== version) {
+      if (cs.version === void 0) {
+        diagnostics.push(
+          cannotExpand(
+            "supplied code system declares no version, so the component's declared version is unconfirmed",
+            path
+          )
+        );
+        complete = false;
+        stampedVersion = void 0;
+      } else {
+        diagnostics.push(
+          cannotExpand(
+            "supplied code system version disagrees with the component's declared version",
+            path
+          )
+        );
+        return { members: /* @__PURE__ */ new Map(), complete: false, diagnostics };
+      }
+    }
     if (hasFilter) {
       const unsupported = unsupportedOps(filter);
       if (unsupported.length > 0) {
@@ -1395,7 +1540,7 @@ function expandComponent(component, ctx, visited, path) {
         if (matchesAllFilters(concpt, filter, sub).matched) {
           base.set(
             codingKey(system, concpt.code),
-            makeCoding(system, concpt.code, concpt.display, version)
+            makeCoding(system, concpt.code, concpt.display, stampedVersion)
           );
         }
       }
@@ -1404,7 +1549,7 @@ function expandComponent(component, ctx, visited, path) {
       for (const concpt of cs.concepts.values()) {
         base.set(
           codingKey(system, concpt.code),
-          makeCoding(system, concpt.code, concpt.display, version)
+          makeCoding(system, concpt.code, concpt.display, stampedVersion)
         );
       }
     }
@@ -1418,7 +1563,14 @@ function expandComponent(component, ctx, visited, path) {
       for (const [k, c] of [...base]) if (c.system !== system) base.delete(k);
     }
   }
-  return { members: base ?? /* @__PURE__ */ new Map(), complete, diagnostics };
+  const members = base ?? /* @__PURE__ */ new Map();
+  if (!activeOnly) return { members, complete, diagnostics };
+  const screened = screenActive(members, component, ctx);
+  if (screened.uncheckable) {
+    diagnostics.push(cannotExpand(ACTIVITY_UNCHECKABLE_DETAIL, path));
+    complete = false;
+  }
+  return { members: screened.members, complete, diagnostics };
 }
 function expandInternal(vs, ctx, visited) {
   if (vs.expansion !== void 0) {
@@ -1434,9 +1586,7 @@ function expandInternal(vs, ctx, visited) {
     let complete = true;
     if (vs.expansion.truncated) {
       complete = false;
-      diagnostics.push(
-        truncated("pre-computed expansion is incomplete (truncated or too-costly)", "expansion")
-      );
+      diagnostics.push(truncated(expansionIncompleteDetail(vs.expansion.unclosed), "expansion"));
     }
     const out = {
       complete,
@@ -1450,8 +1600,9 @@ function expandInternal(vs, ctx, visited) {
     const included = /* @__PURE__ */ new Map();
     const diagnostics = [];
     let complete = true;
+    const activeOnly = vs.compose.inactive === false;
     for (const [i, inc] of vs.compose.include.entries()) {
-      const r = expandComponent(inc, ctx, visited, `compose.include[${String(i)}]`);
+      const r = expandComponent(inc, ctx, visited, `compose.include[${String(i)}]`, activeOnly);
       if (!r.complete) complete = false;
       for (const d of r.diagnostics) diagnostics.push(d);
       for (const [k, c] of r.members) if (!included.has(k)) included.set(k, c);
@@ -1489,14 +1640,27 @@ function cannotExpand2(detail, path) {
   if (path !== void 0) d.path = path;
   return Object.freeze(d);
 }
+function expansionIncompleteDetail2(unclosed) {
+  return unclosed ? "pre-computed expansion is incomplete (marked unclosed: the value set is unbounded, so the snapshot is a sample of its membership)" : "pre-computed expansion is incomplete (truncated or too-costly)";
+}
+var ACTIVITY_UNCHECKABLE_DETAIL2 = "active-only value set: no usable code system release to check whether a selected code is active";
+function usableRelease2(component, system, ctx) {
+  if (system === void 0) return void 0;
+  const cs = ctx.codeSystems?.get(system);
+  if (cs === void 0) return void 0;
+  if (system === component.system && component.version !== void 0 && cs.version !== component.version) {
+    return void 0;
+  }
+  return cs;
+}
 function underPath2(d, prefix) {
   const out = { code: d.code, detail: d.detail };
   out.path = d.path === void 0 ? prefix : `${prefix}/${d.path}`;
   return Object.freeze(out);
 }
-function matchComponent(target, component, ctx, visited, path) {
+function matchComponent(target, component, ctx, visited, path, activeOnly = false) {
   const diagnostics = [];
-  const { system, concept, filter, valueSet: valueSet2 } = component;
+  const { system, version, concept, filter, valueSet: valueSet2 } = component;
   const hasConcept = concept !== void 0;
   const hasFilter = filter !== void 0 && filter.length > 0;
   const hasVs = valueSet2 !== void 0 && valueSet2.length > 0;
@@ -1505,7 +1669,8 @@ function matchComponent(target, component, ctx, visited, path) {
   if (system !== void 0 && target.system !== void 0 && system !== target.system) {
     baseMatched = false;
   } else if (hasConcept) {
-    baseMatched = concept.some((c) => c.code === target.code);
+    const release = usableRelease2(component, system, ctx);
+    baseMatched = concept.some((c) => c.code === target.code) && (release === void 0 || release.concepts.get(target.code) !== void 0);
   } else if (hasFilter || system !== void 0 && !hasVs) {
     if (system === void 0) {
       diagnostics.push(cannotExpand2("intensional filter without a code system 'system'", path));
@@ -1517,6 +1682,24 @@ function matchComponent(target, component, ctx, visited, path) {
         diagnostics.push(cannotExpand2("code system not supplied for intensional include", path));
         baseMatched = false;
         baseComplete = false;
+      } else if (version !== void 0 && cs.version !== version) {
+        if (cs.version === void 0) {
+          diagnostics.push(
+            cannotExpand2(
+              "supplied code system declares no version, so the component's declared version is unconfirmed",
+              path
+            )
+          );
+        } else {
+          diagnostics.push(
+            cannotExpand2(
+              "supplied code system version disagrees with the component's declared version",
+              path
+            )
+          );
+        }
+        baseMatched = false;
+        baseComplete = false;
       } else if (hasFilter) {
         if (unsupportedOps(filter).length > 0) {
           diagnostics.push(cannotExpand2("unsupported filter operator", path));
@@ -1531,6 +1714,7 @@ function matchComponent(target, component, ctx, visited, path) {
       }
     }
   }
+  if (system !== void 0 && target.system === void 0 && baseComplete) baseMatched = false;
   let refDefiniteFalse = false;
   let refUndetermined = false;
   if (hasVs) {
@@ -1563,6 +1747,17 @@ function matchComponent(target, component, ctx, visited, path) {
     return { matched: false, complete: true, diagnostics };
   }
   if (baseDefiniteTrue && refDefiniteTrue) {
+    if (activeOnly) {
+      const cs = usableRelease2(component, target.system, ctx);
+      if (cs === void 0) {
+        diagnostics.push(cannotExpand2(ACTIVITY_UNCHECKABLE_DETAIL2, path));
+        return { matched: false, complete: false, diagnostics };
+      }
+      const concept2 = cs.concepts.get(target.code);
+      if (concept2?.status !== void 0 && !concept2.status.active) {
+        return { matched: false, complete: true, diagnostics };
+      }
+    }
     return { matched: true, complete: true, diagnostics };
   }
   return { matched: false, complete: false, diagnostics };
@@ -1586,7 +1781,7 @@ function validateInternal(target, vs, ctx, visited) {
     if (found) return decided(true, target);
     if (vs.expansion.truncated) {
       return undetermined(target, [
-        cannotExpand2("pre-computed expansion is incomplete (truncated or too-costly)", "expansion")
+        cannotExpand2(expansionIncompleteDetail2(vs.expansion.unclosed), "expansion")
       ]);
     }
     return decided(false, target);
@@ -1595,8 +1790,16 @@ function validateInternal(target, vs, ctx, visited) {
     const diagnostics = [];
     let includedDefinite = false;
     let anyIncludeUndetermined = false;
+    const activeOnly = vs.compose.inactive === false;
     for (const [i, inc] of vs.compose.include.entries()) {
-      const m = matchComponent(target, inc, ctx, visited, `compose.include[${String(i)}]`);
+      const m = matchComponent(
+        target,
+        inc,
+        ctx,
+        visited,
+        `compose.include[${String(i)}]`,
+        activeOnly
+      );
       for (const d of m.diagnostics) diagnostics.push(d);
       if (m.complete && m.matched) includedDefinite = true;
       if (!m.complete) anyIncludeUndetermined = true;
@@ -4776,7 +4979,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.0.12";
+var VERSION = "0.1.0";
 
 exports.COMPLEX_MAP_SOURCE_SYSTEM = COMPLEX_MAP_SOURCE_SYSTEM;
 exports.DIAGNOSTIC_CODES = DIAGNOSTIC_CODES;