@cosyte/terminology 0.0.7 → 0.0.8

package/CHANGELOG.md

@@ -25,6 +25,85 @@ 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

package/README.md

@@ -208,8 +208,15 @@ _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`. The models the engine loads for you are frozen — the bundled unit table deeply so, atom by
-  atom and definition by definition, because it is shared with the engine's own reducer. The AST and
+  `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.
 

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);
 }
@@ -4069,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 };
@@ -4094,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)
   });
 }
@@ -4246,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({
@@ -4293,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;
@@ -4587,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)
@@ -4753,7 +4776,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.0.7";
+var VERSION = "0.0.8";
 
 exports.COMPLEX_MAP_SOURCE_SYSTEM = COMPLEX_MAP_SOURCE_SYSTEM;
 exports.DIAGNOSTIC_CODES = DIAGNOSTIC_CODES;