@cosyte/terminology 0.0.5 → 0.0.7

package/dist/index.cjs

@@ -199,6 +199,9 @@ var TerminologyError = class _TerminologyError extends Error {
   /**
    * @param code - The stable {@link FatalCode} describing the fault.
    * @param message - A **value-free** structural description (path + fault; never an input value).
+   *   Every piece of it must be engine-owned — a literal, a frozen-table entry, or a locus this
+   *   package built. This string reaches `err.stack`, so interpolating a caller-supplied or
+   *   document-derived value into it is how a diagnostic becomes a leak.
    */
   constructor(code, message) {
     super(message);
@@ -652,13 +655,16 @@ function parseCsvRows(content) {
 function parseCsv(content) {
   return parseCsvRows(content).rows;
 }
-function requireHeader(header, name) {
+var MISSING_COLUMN_MESSAGE = Object.freeze({
+  code: "CSV source: the configured 'code' column is not present in the header row",
+  display: "CSV source: the configured 'display' column is not present in the header row",
+  status: "CSV source: the configured 'status' column is not present in the header row",
+  property: "CSV source: a configured property column is not present in the header row"
+});
+function requireHeader(header, name, role) {
   const idx = header.indexOf(name);
   if (idx < 0) {
-    throw new TerminologyError(
-      FATAL_CODES.TERM_CODESYSTEM_MALFORMED,
-      `CSV source: required column '${name}' is not present in the header row`
-    );
+    throw new TerminologyError(FATAL_CODES.TERM_CODESYSTEM_MALFORMED, MISSING_COLUMN_MESSAGE[role]);
   }
   return idx;
 }
@@ -682,12 +688,12 @@ function parseCsvSource(source) {
       })
     );
   }
-  const codeIdx = requireHeader(header, source.columns.code);
-  const displayIdx = requireHeader(header, source.columns.display);
-  const statusIdx = source.columns.status !== void 0 ? requireHeader(header, source.columns.status) : void 0;
+  const codeIdx = requireHeader(header, source.columns.code, "code");
+  const displayIdx = requireHeader(header, source.columns.display, "display");
+  const statusIdx = source.columns.status !== void 0 ? requireHeader(header, source.columns.status, "status") : void 0;
   const propIdx = (source.columns.properties ?? []).map((n) => ({
     name: n,
-    index: requireHeader(header, n)
+    index: requireHeader(header, n, "property")
   }));
   const needCols = Math.max(codeIdx, displayIdx, statusIdx ?? 0, ...propIdx.map((p) => p.index)) + 1;
   const concepts = /* @__PURE__ */ new Map();
@@ -1291,48 +1297,54 @@ function makeCoding(system, code, display, version) {
   if (display !== void 0) init.display = display;
   return coding(init);
 }
-function cannotExpand(detail, system) {
+function cannotExpand(detail, path) {
   const d = { code: "TERM_VALUESET_CANNOT_EXPAND", detail };
-  if (system !== void 0) d.system = system;
+  if (path !== void 0) d.path = path;
   return Object.freeze(d);
 }
-function truncated(detail, system) {
+function truncated(detail, path) {
   const d = { code: "TERM_VALUESET_EXPANSION_TRUNCATED", detail };
-  if (system !== void 0) d.system = system;
+  d.path = path;
   return Object.freeze(d);
 }
+function underPath(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 intersectInto(into, other) {
   for (const k of into.keys()) if (!other.has(k)) into.delete(k);
   return into;
 }
-function expandReferencedValueSets(urls, ctx, visited) {
+function expandReferencedValueSets(urls, ctx, visited, path) {
   const diagnostics = [];
   let complete = true;
   let acc = null;
-  for (const url of urls) {
+  for (const [i, url] of urls.entries()) {
+    const refPath = `${path}.valueSet[${String(i)}]`;
     if (visited.has(url)) {
-      diagnostics.push(cannotExpand("cyclic value set reference", url));
+      diagnostics.push(cannotExpand("cyclic value set reference", refPath));
       complete = false;
       acc = /* @__PURE__ */ new Map();
       continue;
     }
     const vs = ctx.valueSets?.get(url);
     if (vs === void 0) {
-      diagnostics.push(cannotExpand("referenced value set not supplied", url));
+      diagnostics.push(cannotExpand("referenced value set not supplied", refPath));
       complete = false;
       acc = /* @__PURE__ */ new Map();
       continue;
     }
     const exp = expandInternal(vs, ctx, /* @__PURE__ */ new Set([...visited, url]));
     if (!exp.complete) complete = false;
-    for (const d of exp.diagnostics) diagnostics.push(d);
+    for (const d of exp.diagnostics) diagnostics.push(underPath(d, refPath));
     const members = /* @__PURE__ */ new Map();
     for (const c of exp.contains) members.set(codingKey(c.system, c.code), c);
     acc = acc === null ? members : intersectInto(acc, members);
   }
   return { members: acc ?? /* @__PURE__ */ new Map(), complete, diagnostics };
 }
-function expandComponent(component, ctx, visited) {
+function expandComponent(component, ctx, visited, path) {
   const diagnostics = [];
   let complete = true;
   const { system, version, concept, filter, valueSet: valueSet2 } = component;
@@ -1347,18 +1359,18 @@ function expandComponent(component, ctx, visited) {
     }
   } else if (hasFilter || system !== void 0 && !hasVs) {
     if (system === void 0) {
-      diagnostics.push(cannotExpand("intensional filter without a code system 'system'"));
+      diagnostics.push(cannotExpand("intensional filter without a code system 'system'", path));
       return { members: /* @__PURE__ */ new Map(), complete: false, diagnostics };
     }
     const cs = ctx.codeSystems?.get(system);
     if (cs === void 0) {
-      diagnostics.push(cannotExpand("code system not supplied for intensional include", system));
+      diagnostics.push(cannotExpand("code system not supplied for intensional include", path));
       return { members: /* @__PURE__ */ new Map(), complete: false, diagnostics };
     }
     if (hasFilter) {
       const unsupported = unsupportedOps(filter);
       if (unsupported.length > 0) {
-        diagnostics.push(cannotExpand("unsupported filter operator", system));
+        diagnostics.push(cannotExpand("unsupported filter operator", path));
         return { members: /* @__PURE__ */ new Map(), complete: false, diagnostics };
       }
       const sub = buildSubsumption(cs);
@@ -1382,7 +1394,7 @@ function expandComponent(component, ctx, visited) {
     }
   }
   if (hasVs) {
-    const refs = expandReferencedValueSets(valueSet2, ctx, visited);
+    const refs = expandReferencedValueSets(valueSet2, ctx, visited, path);
     for (const d of refs.diagnostics) diagnostics.push(d);
     if (!refs.complete) complete = false;
     base = base === null ? refs.members : intersectInto(base, refs.members);
@@ -1407,7 +1419,7 @@ function expandInternal(vs, ctx, visited) {
     if (vs.expansion.truncated) {
       complete = false;
       diagnostics.push(
-        truncated("pre-computed expansion is incomplete (truncated or too-costly)", vs.url)
+        truncated("pre-computed expansion is incomplete (truncated or too-costly)", "expansion")
       );
     }
     const out = {
@@ -1422,14 +1434,14 @@ function expandInternal(vs, ctx, visited) {
     const included = /* @__PURE__ */ new Map();
     const diagnostics = [];
     let complete = true;
-    for (const inc of vs.compose.include) {
-      const r = expandComponent(inc, ctx, visited);
+    for (const [i, inc] of vs.compose.include.entries()) {
+      const r = expandComponent(inc, ctx, visited, `compose.include[${String(i)}]`);
       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);
     }
-    for (const exc of vs.compose.exclude) {
-      const r = expandComponent(exc, ctx, visited);
+    for (const [i, exc] of vs.compose.exclude.entries()) {
+      const r = expandComponent(exc, ctx, visited, `compose.exclude[${String(i)}]`);
       for (const d of r.diagnostics) diagnostics.push(d);
       for (const k of r.members.keys()) included.delete(k);
       if (!r.complete) {
@@ -1456,12 +1468,17 @@ function expand(vs, ctx = {}) {
 }
 
 // src/valueset/validate.ts
-function cannotExpand2(detail, system) {
+function cannotExpand2(detail, path) {
   const d = { code: "TERM_VALUESET_CANNOT_EXPAND", detail };
-  if (system !== void 0) d.system = system;
+  if (path !== void 0) d.path = path;
   return Object.freeze(d);
 }
-function matchComponent(target, component, ctx, visited) {
+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) {
   const diagnostics = [];
   const { system, concept, filter, valueSet: valueSet2 } = component;
   const hasConcept = concept !== void 0;
@@ -1475,18 +1492,18 @@ function matchComponent(target, component, ctx, visited) {
     baseMatched = concept.some((c) => c.code === target.code);
   } else if (hasFilter || system !== void 0 && !hasVs) {
     if (system === void 0) {
-      diagnostics.push(cannotExpand2("intensional filter without a code system 'system'"));
+      diagnostics.push(cannotExpand2("intensional filter without a code system 'system'", path));
       baseMatched = false;
       baseComplete = false;
     } else {
       const cs = ctx.codeSystems?.get(system);
       if (cs === void 0) {
-        diagnostics.push(cannotExpand2("code system not supplied for intensional include", system));
+        diagnostics.push(cannotExpand2("code system not supplied for intensional include", path));
         baseMatched = false;
         baseComplete = false;
       } else if (hasFilter) {
         if (unsupportedOps(filter).length > 0) {
-          diagnostics.push(cannotExpand2("unsupported filter operator", system));
+          diagnostics.push(cannotExpand2("unsupported filter operator", path));
           baseMatched = false;
           baseComplete = false;
         } else {
@@ -1501,21 +1518,22 @@ function matchComponent(target, component, ctx, visited) {
   let refDefiniteFalse = false;
   let refUndetermined = false;
   if (hasVs) {
-    for (const url of valueSet2) {
+    for (const [i, url] of valueSet2.entries()) {
+      const refPath = `${path}.valueSet[${String(i)}]`;
       if (visited.has(url)) {
-        diagnostics.push(cannotExpand2("cyclic value set reference", url));
+        diagnostics.push(cannotExpand2("cyclic value set reference", refPath));
         refUndetermined = true;
         continue;
       }
       const vs = ctx.valueSets?.get(url);
       if (vs === void 0) {
-        diagnostics.push(cannotExpand2("referenced value set not supplied", url));
+        diagnostics.push(cannotExpand2("referenced value set not supplied", refPath));
         refUndetermined = true;
         continue;
       }
       const m = validateInternal(target, vs, ctx, /* @__PURE__ */ new Set([...visited, url]));
       if (m.undetermined) {
-        for (const d of m.diagnostics) diagnostics.push(d);
+        for (const d of m.diagnostics) diagnostics.push(underPath2(d, refPath));
         refUndetermined = true;
       } else if (!m.result) {
         refDefiniteFalse = true;
@@ -1552,7 +1570,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)", vs.url)
+        cannotExpand2("pre-computed expansion is incomplete (truncated or too-costly)", "expansion")
       ]);
     }
     return decided(false, target);
@@ -1561,16 +1579,16 @@ function validateInternal(target, vs, ctx, visited) {
     const diagnostics = [];
     let includedDefinite = false;
     let anyIncludeUndetermined = false;
-    for (const inc of vs.compose.include) {
-      const m = matchComponent(target, inc, ctx, visited);
+    for (const [i, inc] of vs.compose.include.entries()) {
+      const m = matchComponent(target, inc, ctx, visited, `compose.include[${String(i)}]`);
       for (const d of m.diagnostics) diagnostics.push(d);
       if (m.complete && m.matched) includedDefinite = true;
       if (!m.complete) anyIncludeUndetermined = true;
     }
     let excludedDefinite = false;
     let anyExcludeUndetermined = false;
-    for (const exc of vs.compose.exclude) {
-      const m = matchComponent(target, exc, ctx, visited);
+    for (const [i, exc] of vs.compose.exclude.entries()) {
+      const m = matchComponent(target, exc, ctx, visited, `compose.exclude[${String(i)}]`);
       for (const d of m.diagnostics) diagnostics.push(d);
       if (m.complete && m.matched) excludedDefinite = true;
       if (!m.complete) anyExcludeUndetermined = true;
@@ -3715,7 +3733,29 @@ function parseEssence(xml) {
   atoms.sort((a, b) => b.code.length - a.code.length);
   const atomByCode = new Map(atoms.map((a) => [a.code, a]));
   const prefixByCode = new Map(prefixes.map((p) => [p.code, p]));
-  return { prefixes, atoms, atomByCode, prefixByCode };
+  return freezeEssence({ prefixes, atoms, atomByCode, prefixByCode });
+}
+function refuseTableWrite() {
+  throw new TypeError("the UCUM unit table is immutable");
+}
+function sealLookup(map) {
+  return Object.defineProperties(map, {
+    set: { value: refuseTableWrite },
+    delete: { value: refuseTableWrite },
+    clear: { value: refuseTableWrite }
+  });
+}
+function freezeEssence(essence) {
+  for (const atom of essence.atoms) {
+    if (atom.value) Object.freeze(atom.value);
+    Object.freeze(atom);
+  }
+  for (const prefix of essence.prefixes) Object.freeze(prefix);
+  Object.freeze(essence.atoms);
+  Object.freeze(essence.prefixes);
+  sealLookup(essence.atomByCode);
+  sealLookup(essence.prefixByCode);
+  return Object.freeze(essence);
 }
 var cached;
 function loadUcumEssence() {
@@ -3893,32 +3933,37 @@ function power(r, p) {
   }
   return { kind: "linear", factor: Math.pow(r.factor, p), dims };
 }
-var DIMENSIONLESS = { kind: "linear", factor: 1, dims: {} };
-var atomMemo = /* @__PURE__ */ new Map();
-var inProgress = /* @__PURE__ */ new Set();
+var DIMENSIONLESS = Object.freeze({
+  kind: "linear",
+  factor: 1,
+  dims: Object.freeze({})
+});
+var atomMemo = /* @__PURE__ */ new WeakMap();
+var inProgress = /* @__PURE__ */ new WeakSet();
 function reduceAtomLinear(atom) {
   if (atom.base) return { kind: "linear", factor: 1, dims: { [atom.dim ?? atom.code]: 1 } };
   if (atom.arbitrary) return { kind: "linear", factor: 1, dims: { [`arb:${atom.code}`]: 1 } };
-  const cached2 = atomMemo.get(atom.code);
+  const cached2 = atomMemo.get(atom);
   if (cached2) return cached2;
-  if (inProgress.has(atom.code)) {
-    throw new Error(`cyclic UCUM atom definition for '${atom.code}'`);
+  if (inProgress.has(atom)) {
+    throw new Error("cyclic UCUM atom definition in the unit table");
   }
   if (!atom.value) {
-    atomMemo.set(atom.code, DIMENSIONLESS);
-    return DIMENSIONLESS;
+    throw new Error("UCUM atom has no linear definition");
   }
-  inProgress.add(atom.code);
-  const parsed = parseUcum(atom.value.unit);
-  if (!parsed.ok) {
-    inProgress.delete(atom.code);
-    throw new Error(`unparseable UCUM essence definition for '${atom.code}'`);
+  inProgress.add(atom);
+  try {
+    const parsed = parseUcum(atom.value.unit);
+    if (!parsed.ok) {
+      throw new Error("unparseable UCUM essence definition in the unit table");
+    }
+    const reduced = linearReduceTerm(parsed.node);
+    const result = multiply({ kind: "linear", factor: atom.value.factor, dims: {} }, reduced);
+    atomMemo.set(atom, result);
+    return result;
+  } finally {
+    inProgress.delete(atom);
   }
-  const reduced = linearReduceTerm(parsed.node);
-  const result = multiply({ factor: atom.value.factor, dims: {} }, reduced);
-  inProgress.delete(atom.code);
-  atomMemo.set(atom.code, result);
-  return result;
 }
 function reduceSimpleLinear(node) {
   const base = reduceAtomLinear(node.atom);
@@ -3938,7 +3983,7 @@ function linearReduceComponent(comp) {
   }
 }
 function linearReduceTerm(node) {
-  let acc = DIMENSIONLESS;
+  let acc = { kind: "linear", factor: 1, dims: {} };
   for (const { sign, node: comp } of node.factors) {
     acc = multiply(acc, power(linearReduceComponent(comp), sign));
   }
@@ -4120,10 +4165,15 @@ function applyGem(map, source) {
   if (combinations !== void 0) matched.combinations = combinations;
   return Object.freeze(matched);
 }
+var NOT_INVERTIBLE_MESSAGE = /* @__PURE__ */ new Map([
+  ["9-to-10", "GEM map (direction 9-to-10) cannot be inverted \u2014 load the 10-to-9 GEM file instead"],
+  ["10-to-9", "GEM map (direction 10-to-9) cannot be inverted \u2014 load the 9-to-10 GEM file instead"]
+]);
+var NOT_INVERTIBLE_UNKNOWN_DIRECTION = "GEM map cannot be inverted \u2014 load the reverse GEM file instead";
 function invertGem(map) {
   throw new TerminologyError(
     FATAL_CODES.TERM_MAP_NOT_INVERTIBLE,
-    `GEM map (direction ${map.direction}) cannot be inverted \u2014 load the reverse GEM file instead`
+    NOT_INVERTIBLE_MESSAGE.get(map.direction) ?? NOT_INVERTIBLE_UNKNOWN_DIRECTION
   );
 }
 
@@ -4703,7 +4753,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.0.5";
+var VERSION = "0.0.7";
 
 exports.COMPLEX_MAP_SOURCE_SYSTEM = COMPLEX_MAP_SOURCE_SYSTEM;
 exports.DIAGNOSTIC_CODES = DIAGNOSTIC_CODES;