@cosyte/terminology 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -25,6 +25,146 @@ this file is maintained by hand (Changesets handles the version bump and publish
 
 ### Fixed
 
+- **A loaded GEM map, complex map and RxNorm drug graph froze their wrapper and handed out plain
+  `Map`s inside it, so whoever held one could delete a diagnosis mapping, add a target the steward's
+  file never authored, or empty a medication's ingredient edges** (`TERMINOLOGY-INNER-MAPS-UNSEALED`).
+  `Object.freeze` cannot reach a `Map` — its entries live in an internal slot rather than in
+  properties — so freezing the model left `set` / `delete` / `clear` working on every index it points
+  at, and the `readonly` on those fields was a compile-time claim only.
+
+  Measured on `dd8465b`, before any fix: one `push` into `loadGems(…).entries.get("0010")` made
+  `applyGem` answer with a target that is in no GEM file; `entries.delete("0010")` turned the same
+  source into a typed `TERM_CROSSWALK_UNMAPPED`; `graph.edges.clear()` left `ingredientsOf` answering
+  `targets: []` for every drug while `edgeCount` still reported the loaded figure; and
+  `graph.concepts.set(…)` put a concept the caller's release never shipped where navigation would
+  return it. The candidate and rule lists were nominally `readonly` in the same way — writing over
+  element `0` landed too.
+
+  A code system's `concepts`, a GEM's and a complex map's `entries`, and a drug graph's `concepts` /
+  `edges` / `ndcs` are each now a **read-only view** of a map rather than the map itself — those six
+  indexes, not every field this package types `ReadonlyMap` — and every list, entry and warning
+  reachable from one of those models is frozen. Reads are exactly a `Map`'s: `get`, `has`, `size`,
+  `keys`, `values`, `entries`, `forEach`, iteration, `new Map(view)`.
+
+  **Two behaviour changes to know before you write against one.** A view is not a `Map` instance, so
+  `instanceof Map` is now `false` on `CodeSystem.concepts`, a `GemMap`'s and a `ComplexMap`'s
+  `entries`, and a graph's `concepts` / `edges` / `ndcs`; it prints as a plain object, `Object.keys`
+  lists its own methods, and `JSON.stringify` renders it as `{"size":2}` where a `Map` rendered `{}`.
+  And a model carrying one therefore **cannot be structured-cloned** — `structuredClone` and
+  `worker.postMessage` raise a `DataCloneError`, `v8.serialize` a plain `Error`, where before each
+  produced a working copy. Clone what the other side needs instead: `new Map(cs.concepts)`. A loaded
+  `ConceptMap`, `ValueSet` or unit table carries no view and clones as it always did. That refusal is
+  deliberate rather than incidental. Hiding the view's methods would make the clone _succeed_ and
+  hand back a model
+  whose indexes were empty while `count` / `conceptCount` / `edgeCount` still reported the loaded
+  figures — this defect's own shape, arriving silently. It is pinned as a test, not left as prose.
+
+  Not being a `Map` is also what closes the second route rather than only the first: replacing a
+  `Map`'s three mutators leaves `Map.prototype.set.call(theMap, …)` reaching the internal slot
+  directly, and a view has no slot to reach. `CodeSystem.concepts` was sealed that weaker way — a
+  fabricated concept could be forced into a loaded release and `lookup` would return it — and is a
+  view now too.
+
+  **The bundled UCUM table is deliberately not part of this and is unchanged.** `atomByCode` and
+  `prefixByCode` stay real `Map`s whose `set` / `delete` / `clear` are replaced by a refusal, so an
+  entry forced through `Map.prototype` still lands there. That residual is bounded and stays
+  documented: `parseUcum` resolves an atom by scanning the frozen `atoms` array, never through a
+  lookup map, so a forced entry changes no validation, reduction or `ucumEqual` answer — only the
+  caller's own `get` is lied to.
+
+  The guarantee is that the loaded model does not change, not that a write throws: a named mutator
+  raises a `TypeError` in either mode, while a frozen list or entry throws in strict mode and is
+  silently ignored in sloppy mode, which the CJS build lets a caller observe. Every route is
+  therefore asserted by the **reading** it would have changed as well as by the refusal, and a
+  reachability sweep walks **all seven** `load*` models for anything still writable, so a field added
+  later is covered without anyone maintaining a list of routes. The UCUM table is pinned in that
+  sweep as the named exception rather than skipped, so converting it later has to be deliberate. The
+  sweep carries its own negative controls: a planted mutable object and a raw `Map` behind a frozen
+  wrapper both have to be reported.
+
+- **`parseEssence`'s example imported it from `@cosyte/terminology/ucum/essence`, a subpath the
+  package's `exports` does not declare.** It is package-internal and not re-exported from the entry
+  point; the example says so and imports it the way this package's own code does. Consumers reach the
+  table through `loadUcumEssence()`, which is unchanged.
+
+- **Three `/* v8 ignore */` hints in `src/ucum/essence.ts` were inert, and are now plain comments.**
+  The branches they claimed to exclude were reported uncovered either way — measured with and
+  without a `--` reason suffix and under `--coverage.experimentalAstAwareRemapping` — so the hints
+  stated a coverage exclusion that no run performed. The package's posture is the one
+  `vitest.config.ts` already records for `rxnorm/`: an unreachable `noUncheckedIndexedAccess`
+  fallback stays visibly uncovered under a directory floor of 90, rather than being hidden by an
+  assertion about reachability that the next reader inherits with no way to check it. No coverage
+  figure moved, which is what proves they were inert.
+
+- **A GEM source with more than one combination scenario had no deterministic test**, so the
+  comparator that orders them was reached only when a `fast-check` draw happened to generate a second
+  scenario — `Array.prototype.sort` never calls one for a single-element array. Scenarios are
+  alternative valid representations of the same source, so their order is part of the answer. Covered
+  now by a fixture whose file order is deliberately scenario 2 first. Found while measuring this
+  slice; `vitest run --coverage --exclude 'test/property/**'` reports `crosswalk/` at 100% functions
+  with it and 95.45% without.
+
+- **The UCUM unit table `loadUcumEssence()` hands out was `readonly` to TypeScript only, so a unit's
+  definition could be rewritten in place — and doing so fabricated a unit equivalence that outlived
+  putting the table back** (`TERMINOLOGY-MUTABLE-ESSENCE-TABLE`). One table is shared by every caller
+  and by the engine's own reducer, `essence.ts` froze nothing, and `reduce` memoizes each atom's
+  reduction against the atom object. So corrupting a loaded atom **before that atom's first
+  reduction** wrote the memo, and the reading survived restoring the table exactly as shipped.
+
+  Measured on `bf153cb`, and live on published `0.0.5` and `0.0.6` alike — `0.0.6` is that commit plus
+  a version bump. Defining the loaded litre as `1` with no prior
+  touch of `L`: `ucumEqual("L", "1")` and `ucumEqual("mg/L", "mg")` both answered `true` where the
+  same calls without it answered `false`, and `mmol/L` fell from `6.0221407599999985e+23 × m-3` to a
+  dimensionless `6.02214076e+20` — **a concentration comparing equal to a mass**. Two further routes
+  to the same readings on that build: writing the nested definition object in place
+  (`atom.value.unit = "1"`), and replacing an element of the `atoms` array, which is the one
+  `parseUcum` scans, so it hands the parser a forged atom without touching the memo at all.
+
+  This is the half that keying the memo on the atom **object** did not reach. That closed the route
+  where the atom was one you had _built_; this is the route where the atom is one you were _handed_,
+  and the consequence class is identical. Neither substitutes for the other.
+
+  The table is frozen when it is parsed, deeply: every atom, every atom's definition object, every
+  prefix, and both arrays. Shallow would have been worth nothing — freezing the atom alone leaves
+  `atom.value.unit`, which reproduces all three readings. `atomByCode` and `prefixByCode` refuse
+  `set`, `delete` and `clear`, which `Object.freeze` cannot do for a `Map`. `parseEssence` freezes
+  what it returns on the same rule.
+
+  **The guarantee is that the table does not change, not that a write throws.** `Object.freeze`
+  refuses a write by throwing in strict mode and ignoring it in sloppy mode, and this package ships a
+  CJS build a sloppy-mode caller can require; the table is the one that was parsed either way. The
+  tests assert the readings, and the `TypeError` only as how a strict-mode caller observes it.
+
+  **Two things this does not claim, both measured rather than reasoned.** `Map.prototype.set.call()`
+  can still force an entry into a lookup map — no `Map` can be made immutable in place — and what
+  that reaches is bounded and pinned in both directions: `parseUcum` resolves an atom by scanning
+  `atoms`, never through `atomByCode`, so a forced entry changes **no** reduction and no `ucumEqual`
+  answer, only what the caller's own `get` returns. And the values `parseUcum` and `reduce` hand back
+  are deliberately still per-call and mutable.
+
+  **No reduction changes.** 3,080 expressions built from the table — every atom bare, squared,
+  inverted and annotated; every prefix over rotating metric atoms; rotating ratios, products and
+  grouped powers; and the shapes the README and the tests name — plus 312 `ucumEqual` pairs, reduce
+  byte-identically on `bf153cb` and on this tree (3,393 output lines, one sha256).
+
+  One knock-on, stated because getting it wrong is easy: freezing the table removes **a** route to
+  `reduce`'s cyclic-definition guard, not the last one. Two routes that look like they should reach
+  it do not, and both are now pinned as tests — naming a table atom in a definition (it is resolved
+  against the loaded table, so your atom can _name_ one but never _be_ one; a self-referential `Pa`
+  taken off a table copy resolves to the shipped pascal and answers `1000 × g.m-1.s-2`), and
+  corrupting a loaded atom, which is what is now refused. The route that does reach it needs no table
+  at all: `UcumAtom.value` is `readonly` to TypeScript, which an **accessor** satisfies, and the
+  definition is read after the atom is marked in progress, so a getter can re-enter `reduce` for the
+  same atom. That is a supported public call, and the guard is pinned by it under a 100,000-byte atom
+  code — so all three of `reduce`'s messages are again asserted whole, against both `message` and
+  `err.stack`, with the caller's own code as the unbounded value in each.
+
+  Also here: the `/* v8 ignore next */` on `reduce`'s `atom.base` line is removed. It justified
+  itself with a property of the bundled table — every base atom there carries a `dim` — for a line
+  reachable through the exported surface with a caller-built `{ base: true }` atom that carries none.
+  That arm is answered on the atom's own code, is now covered by a test rather than excluded, and
+  changes nothing for the table's own base units.
+
 - **A `UnitNode` you assembled yourself could change how `reduce` and `ucumEqual` answer for a unit
   parsed out of the bundled UCUM table, for the rest of the process**
   (`TERMINOLOGY-ATOMMEMO-POISONING`). `reduce` is exported and takes a caller-built node, and

package/README.md

@@ -208,7 +208,17 @@ _names_, listed under [What is bundled](#what-is-bundled).
   NDC you asked about, so log the `code` and the locus rather than the whole result — a code _in
   patient context_ can be PHI.
 - **Zero runtime dependencies. Dual ESM + CJS.** Node stdlib only; built with `tsup`, validated with
-  `attw`. Immutable by construction (every returned value is deep-frozen).
+  `attw`. A release you load is frozen, its indexes included: a code system's concepts, a GEM's or a
+  complex map's entries and a drug graph's concepts, edges and NDCs are each a read-only **view** of a
+  map rather than the map itself, so nothing holding one can add, delete or clear an entry, whichever
+  way it tries. A view is not a `Map` instance, so a model carrying one cannot be `structuredClone`d
+  or posted to a worker — copy out what you need (`new Map(cs.concepts)`). The bundled unit table is frozen deeply, atom by atom and definition by
+  definition, because it is shared with the engine's own reducer; its two lookup maps refuse `set`,
+  `delete` and `clear` by name, and an entry forced past that through `Map.prototype` changes nothing
+  the engine reads, because `parseUcum` resolves an atom by scanning the frozen atom array rather than
+  through a lookup map. The AST and
+  the reduction that `parseUcum` and `reduce` hand back are per-call values you own, and mutating one
+  changes nothing for anyone else.
 
 ## What is bundled
 

package/dist/index.cjs

@@ -567,6 +567,31 @@ function translate(sourceCoding, map) {
   );
 }
 
+// src/common/frozen-map.ts
+function frozenMap(source, what) {
+  const refuse = () => {
+    throw new TypeError(`Cannot mutate ${what} (it is immutable)`);
+  };
+  const view = {
+    get size() {
+      return source.size;
+    },
+    get: (key) => source.get(key),
+    has: (key) => source.has(key),
+    keys: () => source.keys(),
+    values: () => source.values(),
+    entries: () => source.entries(),
+    forEach: (callback, thisArg) => {
+      for (const [key, value] of source) callback.call(thisArg, value, key, view);
+    },
+    [Symbol.iterator]: () => source[Symbol.iterator](),
+    set: refuse,
+    delete: refuse,
+    clear: refuse
+  };
+  return Object.freeze(view);
+}
+
 // src/codesystem/status.ts
 var defaultStatusMapper = (raw) => {
   switch (raw.trim().toUpperCase()) {
@@ -973,15 +998,6 @@ function parseRrf(source) {
 }
 
 // src/codesystem/load.ts
-function sealConceptMap(map) {
-  const guard = () => {
-    throw new TypeError("Cannot mutate a loaded CodeSystem's concepts map (it is immutable)");
-  };
-  for (const method of ["set", "delete", "clear"]) {
-    Object.defineProperty(map, method, { value: guard, writable: false, configurable: false });
-  }
-  return map;
-}
 function loadCodeSystem(source) {
   let concepts;
   let warnings;
@@ -1019,7 +1035,7 @@ function loadCodeSystem(source) {
     }
   }
   out.count = concepts.size;
-  out.concepts = sealConceptMap(concepts);
+  out.concepts = frozenMap(concepts, "a loaded CodeSystem's concepts map");
   out.warnings = Object.freeze(warnings);
   return Object.freeze(out);
 }
@@ -3733,7 +3749,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() {
@@ -4047,21 +4085,25 @@ function loadGems(source) {
     if (trimmed === "") continue;
     const fields = trimmed.split(/\s+/);
     if (fields.length !== 3) {
-      warnings.push({
-        code: "TERM_GEM_MALFORMED_ROW",
-        line: i + 1,
-        detail: `expected 3 whitespace-delimited fields, found ${String(fields.length)}`
-      });
+      warnings.push(
+        Object.freeze({
+          code: "TERM_GEM_MALFORMED_ROW",
+          line: i + 1,
+          detail: `expected 3 whitespace-delimited fields, found ${String(fields.length)}`
+        })
+      );
       continue;
     }
     const [src, tgt, flagStr] = fields;
     const flags = decodeFlags(flagStr);
     if (flags === void 0) {
-      warnings.push({
-        code: "TERM_GEM_MALFORMED_ROW",
-        line: i + 1,
-        detail: "flag field is not a 5-digit code"
-      });
+      warnings.push(
+        Object.freeze({
+          code: "TERM_GEM_MALFORMED_ROW",
+          line: i + 1,
+          detail: "flag field is not a 5-digit code"
+        })
+      );
       continue;
     }
     const entry = { source: src, flags };
@@ -4072,11 +4114,12 @@ function loadGems(source) {
     else entries.set(src, [frozen]);
     count++;
   }
+  for (const list of entries.values()) Object.freeze(list);
   return Object.freeze({
     direction: source.direction,
     ...source.version !== void 0 ? { version: source.version } : {},
     count,
-    entries,
+    entries: frozenMap(entries, "a loaded GEM map's entries"),
     warnings: Object.freeze(warnings)
   });
 }
@@ -4224,11 +4267,13 @@ function parseRf2(content) {
     const groupN = Number(at(f, iGroup));
     const priorityN = Number(at(f, iPriority));
     if (source === "" || !Number.isFinite(groupN) || !Number.isFinite(priorityN)) {
-      warnings.push({
-        code: "TERM_COMPLEX_MAP_MALFORMED_ROW",
-        line: i + 1,
-        detail: "row is missing referencedComponentId / mapGroup / mapPriority"
-      });
+      warnings.push(
+        Object.freeze({
+          code: "TERM_COMPLEX_MAP_MALFORMED_ROW",
+          line: i + 1,
+          detail: "row is missing referencedComponentId / mapGroup / mapPriority"
+        })
+      );
       continue;
     }
     rows.push({
@@ -4271,7 +4316,7 @@ function loadComplexMap(input) {
   }
   const out = {
     count,
-    entries,
+    entries: frozenMap(entries, "a loaded complex map's entries"),
     warnings
   };
   if (input.version !== void 0) out.version = input.version;
@@ -4565,9 +4610,9 @@ function loadRxNormGraph(source) {
   const ndcs = source.sat !== void 0 ? parseNdcs(source.sat, warnings) : /* @__PURE__ */ new Map();
   for (const list of edges.values()) Object.freeze(list);
   const out = {
-    concepts,
-    edges,
-    ndcs,
+    concepts: frozenMap(concepts, "a loaded RxNorm graph's concepts"),
+    edges: frozenMap(edges, "a loaded RxNorm graph's edges"),
+    ndcs: frozenMap(ndcs, "a loaded RxNorm graph's NDC index"),
     conceptCount: concepts.size,
     edgeCount,
     warnings: Object.freeze(warnings)
@@ -4731,7 +4776,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.0.6";
+var VERSION = "0.0.8";
 
 exports.COMPLEX_MAP_SOURCE_SYSTEM = COMPLEX_MAP_SOURCE_SYSTEM;
 exports.DIAGNOSTIC_CODES = DIAGNOSTIC_CODES;