@cosyte/terminology 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.3
+
+### Patch Changes
+
+- 8d1e983: The README follows the house layout, and the package description gains two serial commas. The README now opens with why the engine exists and its status, then install and usage with a link to the guides on docs.cosyte.com, and ends with support, security, contributing, and license. It names the Node.js lines CI tests (22, 24, and 26); its conformance statements and its list of bundled material are unchanged. No code changed.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -7,8 +7,22 @@
 
 # @cosyte/terminology
 
-> A **zero-dependency terminology engine** for US healthcare code systems: FHIR-shaped, BYO-data,
-> and it **never fabricates a code**.
+> A zero-dependency, FHIR-shaped terminology engine for US healthcare code systems that never fabricates a code.
+
+[![npm version](https://img.shields.io/npm/v/@cosyte/terminology.svg)](https://www.npmjs.com/package/@cosyte/terminology)
+[![CI](https://img.shields.io/github/actions/workflow/status/cosyte/terminology/ci.yml?branch=main&label=CI)](https://github.com/cosyte/terminology/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/cosyte/terminology/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
+
+Terminology engine for US healthcare code systems in Node.js and TypeScript: FHIR `$translate`,
+`$lookup`, `$validate-code`, and `$expand` over code systems, value sets, and maps you supply.
+
+## Why this exists
+
+A wrong code, map, or value-set binding does not fail loudly: it becomes a different clinical
+meaning in whatever consumes the answer, and the output still looks valid. So this engine never
+fabricates and never inverts. An unknown or unmapped code comes back as a typed result rather than a
+guess, and a directional map is read only in its authored direction.
 
 `@cosyte/terminology` is **not a wire parser**. It mirrors the FHIR **Terminology Module**
 (`$translate`, `$lookup`, `$validate-code`, `$expand`, …), operating over **consumer-supplied** FHIR
@@ -19,51 +33,56 @@ unit table, the code-system _identities_ (OID ↔ canonical URI), the SNOMED CT
 resolver names, and RxNorm's relationship and term-type names, is listed with its copyright under
 [What is bundled](#what-is-bundled).
 
-> **Status:** the 0.1 line, **published on npm.** The public API is settled: below `1.0.0` a breaking
-> change ships in a new minor version, never a patch, and the changelog says what broke. The
-> **engine is complete**, every operation below ships today. The surface:
->
-> - the code-system **identity resolver** (`resolveSystem`) and the ConceptMap **`$translate`** engine
->   (`loadConceptMap` / `translate`);
-> - the **CodeSystem load layer** (RRF / CSV / fixed-width / FHIR JSON) with **`$lookup`** and
->   **`$validate-code`**;
-> - **ValueSet** binding (`compose` / **`$expand`** / **`$validate-code`**), subsumption read from the
->   release's own hierarchy, measured against HL7's own terminology ecosystem test cases
->   ([terminology ecosystem conformance](#terminology-ecosystem-conformance));
-> - **UCUM** unit validation and canonicalization (`validateUcum` / `ucumEqual`, recognition only, **no
->   magnitude conversion**), gated on the official UCUM functional tests: the **validation** and
->   **conversion** case kinds, against the suite dated 3-Feb 2021, and no other kind
->   ([UCUM conformance](#ucum-conformance));
-> - the **crosswalk resolvers**: the CMS **ICD-9↔ICD-10 GEMs** (`loadGems` / `applyGem`,
->   public-domain) and the NLM **SNOMED CT → ICD-10-CM complex map** (`loadComplexMap` /
->   `applyComplexMap`, BYO: no SNOMED CT refset bundled), never inverted;
-> - the **RxNorm drug graph** (`loadRxNormGraph` + `ingredientsOf` / `genericFor` / `brandsFor` /
->   `doseFormsOf` / `consistsOf` / `resolveNdc` / `approximateMatch`) over a **BYO** RxNorm RRF release,
->   edges read in RxNorm's documented direction and never inverted, an absent `RXCUI`/NDC typed, never
->   fabricated.
->
-> **Bring your own data.** The engine is whole; **no code-system release is bundled.** It runs over
-> the FHIR resources and standard releases _you_ supply: SNOMED CT, CPT, LOINC, UMLS/RxNorm, the CMS
-> GEM files, the NLM complex-map refset, and VSAC value sets are all bring-your-own, under whatever
-> terms their steward sets. The content packs that would change that (RxNorm Prescribable, ICD-10-CM)
-> are not bundled either. For the things that **are** bundled, and under whose copyright, see
-> [What is bundled](#what-is-bundled).
+## Status
+
+**The 0.1 line, published on npm.** The public API is settled: below `1.0.0` a breaking change ships
+in a new minor version, never a patch, and the changelog says what broke. The **engine is
+complete**: every operation below ships today. The surface:
+
+- the code-system **identity resolver** (`resolveSystem`) and the ConceptMap **`$translate`** engine
+  (`loadConceptMap` / `translate`);
+- the **CodeSystem load layer** (RRF / CSV / fixed-width / FHIR JSON) with **`$lookup`** and
+  **`$validate-code`**;
+- **ValueSet** binding (`compose` / **`$expand`** / **`$validate-code`**), subsumption read from the
+  release's own hierarchy, measured against HL7's own terminology ecosystem test cases
+  ([terminology ecosystem conformance](#terminology-ecosystem-conformance));
+- **UCUM** unit validation and canonicalization (`validateUcum` / `ucumEqual`, recognition only, **no
+  magnitude conversion**), gated on the official UCUM functional tests: the **validation** and
+  **conversion** case kinds, against the suite dated 3-Feb 2021, and no other kind
+  ([UCUM conformance](#ucum-conformance));
+- the **crosswalk resolvers**: the CMS **ICD-9↔ICD-10 GEMs** (`loadGems` / `applyGem`,
+  public-domain) and the NLM **SNOMED CT → ICD-10-CM complex map** (`loadComplexMap` /
+  `applyComplexMap`, BYO: no SNOMED CT refset bundled), never inverted;
+- the **RxNorm drug graph** (`loadRxNormGraph` + `ingredientsOf` / `genericFor` / `brandsFor` /
+  `doseFormsOf` / `consistsOf` / `resolveNdc` / `approximateMatch`) over a **BYO** RxNorm RRF release,
+  edges read in RxNorm's documented direction and never inverted, an absent `RXCUI`/NDC typed, never
+  fabricated.
+
+**Bring your own data.** The engine is whole; **no code-system release is bundled.** It runs over the
+FHIR resources and standard releases _you_ supply: SNOMED CT, CPT, LOINC, UMLS/RxNorm, the CMS GEM
+files, the NLM complex-map refset, and VSAC value sets are all bring-your-own, under whatever terms
+their steward sets. The content packs that would change that (RxNorm Prescribable, ICD-10-CM) are not
+bundled either. For the things that **are** bundled, and under whose copyright, see
+[What is bundled](#what-is-bundled).
 
 ## Install
 
-> **On npm.** `@cosyte/terminology` is **published**, on the 0.1 line. The command below
-> installs the real package; the registry, not this page, is the authority on the exact version.
-
 ```bash
 npm install @cosyte/terminology
 ```
 
-Node.js 22 or later, tested on 22 and 24.
+Node.js 22 or later, tested on 22, 24, and 26.
+
+The package is published on the 0.1 line, and the command above installs the real package; the
+registry, not this page, is the authority on the exact version.
+
+## Usage
 
-Runnable programs for the main jobs are in
-[`examples/`](https://github.com/cosyte/terminology/tree/main/examples).
+The guides and the full API reference are at
+[docs.cosyte.com/terminology](https://docs.cosyte.com/terminology). Runnable programs for the main
+jobs are in [`examples/`](https://github.com/cosyte/terminology/tree/main/examples).
 
-## Resolve a code system to its canonical URI
+### Resolve a code system to its canonical URI
 
 ```ts
 import { resolveSystem, isUnknownSystem } from "@cosyte/terminology";
@@ -72,7 +91,7 @@ const r = resolveSystem("2.16.840.1.113883.6.1"); // OID, mnemonic, or URI
 console.log(isUnknownSystem(r) ? "unknown" : r.url); // http://loinc.org
 ```
 
-## Translate a code through a ConceptMap
+### Translate a code through a ConceptMap
 
 ```ts
 import { loadConceptMap, translate } from "@cosyte/terminology";
@@ -114,7 +133,7 @@ if (result.unmapped) {
 When at least one target does assert a relationship, the source is translated exactly as before and
 any `disjoint` row rides along in `result.matches`, in its declared position.
 
-## Look up a code in a code system
+### Look up a code in a code system
 
 ```ts
 import { loadCodeSystem, lookup, validateCode } from "@cosyte/terminology";
@@ -134,7 +153,7 @@ if (hit.found) {
 validateCode(cs, "2160-0").valid; // $validate-code: true iff present; never a guessed true
 ```
 
-## Validate and compare UCUM units
+### Validate and compare UCUM units
 
 Recognition and canonicalization only: **no magnitude conversion** (`5 mg/dL` → `mmol/L` needs the
 analyte's molar mass, a clinical computation this engine refuses).
@@ -166,6 +185,65 @@ functional-test cases it claims, and claims no more than it runs: see
 > `TERM_UCUM_INVALID` (fail-safe, never silently reinterpreted). Magnitude conversion is likewise a
 > deliberate non-goal (recognition and canonicalization only).
 
+### Navigate the RxNorm drug graph
+
+Load a **bring-your-own** RxNorm RRF release and walk the ingredient / brand / clinical-drug /
+dose-form graph. Relationships are read in RxNorm's documented direction (`RELA` is the relationship
+the **second** `RXCUI` has to the **first**); navigation follows only authored edges: the engine
+never synthesizes an inverse, and never fabricates a concept, edge, or NDC.
+
+Authored edges only means the graph you get is RxNorm's, including where its shape surprises you.
+`has_ingredient` is authored from the **clinical** side (`SCDC`/`SCDF`/`SCDG`) to the ingredient
+`IN`, and from the **branded** side (`SBD`/`SBDC`/`SBDF`/`SBDG`) to the **brand name** `BN` rather
+than to the active ingredient. RxNorm authors no ingredient edge on a clinical drug (`SCD`) at all,
+so that query answers with an honest empty set rather than a guess. To reach an active ingredient,
+walk to the **clinical** component and take its edge: `consistsOf` then `ingredientsOf`. From an
+`SBD`, `consistsOf` returns both its branded component (`SBDC`, whose ingredient edge is the brand
+name again) and the clinical `SCDC`; it is the `SCDC` that leads to the `IN`. The **precise** forms
+(`SCDFP`, `SBDFP`, `SCDGP`) carry no ingredient edge at all: an `SCDFP` instead reaches its
+basis-of-strength substances by `has_boss`, a one-to-many relation with a different meaning whose
+targets can be a `PIN` or a plain `IN`, and which `ingredientsOf` does not follow. Read the `tty` of
+what comes back rather than assuming it.
+
+A concept is typed by its **defining** atom, whichever line of `RXNCONSO` that sits on. `PSN`, `SY`,
+and `TMSY` type a _name_ rather than a concept, so they never establish an `RXCUI`'s term type. An
+`RXCUI` no defining atom could type is left out of the graph and reported as
+`TERM_RXNORM_UNTYPED_CONCEPT` on `graph.warnings`, rather than loaded under a synonym's term type:
+a concept that answers with a term type it does not have is a fabricated claim about a drug, and
+this engine refuses instead.
+
+```ts
+import {
+  loadRxNormGraph,
+  ingredientsOf,
+  consistsOf,
+  genericFor,
+  resolveNdc,
+} from "@cosyte/terminology";
+
+const graph = loadRxNormGraph({
+  conso: rxnconsoRrf,
+  rel: rxnrelRrf,
+  sat: rxnsatRrf,
+  version: "RXNORM_2026AA",
+});
+
+ingredientsOf(graph, "316151"); // an SCDC → { found: true, targets: [ { rxcui: "29046", tty: "IN", name: "lisinopril", … } ] }
+ingredientsOf(graph, "314076"); // an SCD → { found: true, targets: [] }, because no such edge is authored
+consistsOf(graph, "314076"); // → the SCDC, the first of the two hops to the ingredient
+genericFor(graph, "104377"); // an SBD → its SCD, via the authored tradename_of edge
+resolveNdc(graph, "00000000001"); // { resolved: true, rxcui: "314076", status: "active", asOf: "RXNORM_2026AA" }
+ingredientsOf(graph, "99999999"); // { found: false, code: "TERM_RXNORM_UNKNOWN_RXCUI" }, never a guess
+```
+
+The engine ships **no** RxNorm release; you supply it (the public-domain Current Prescribable
+Content subset, or the full BYO release). What it does ship is RxNorm's relationship and term-type
+_names_, listed under [What is bundled](#what-is-bundled).
+
+## Conformance
+
+Each claim below is stated in full and held to a fresh run by the package's own test suite.
+
 ### UCUM conformance
 
 The claim in full, so a reader can tell what was run from what was not. UCUM permits a qualified
@@ -189,7 +267,7 @@ here, if the suite's most recent history date stops matching the date named here
 here is not one the tests execute, if a named kind's section carries no case, or if this page and
 `vendor/ucum/NOTICE.md` state different suite dates.
 
-## Terminology ecosystem conformance
+### Terminology ecosystem conformance
 
 The ValueSet layer is measured against **HL7's own FHIR terminology ecosystem test cases**
 (`HL7/fhir-tx-ecosystem-ig`) as well as against tests written here. The claim in full, so a reader
@@ -228,61 +306,6 @@ stale in silence.
 its own process. Nothing here is an approval, a certification, or an endorsement of this package by
 HL7 or by anyone else.
 
-## Navigate the RxNorm drug graph
-
-Load a **bring-your-own** RxNorm RRF release and walk the ingredient / brand / clinical-drug /
-dose-form graph. Relationships are read in RxNorm's documented direction (`RELA` is the relationship
-the **second** `RXCUI` has to the **first**); navigation follows only authored edges: the engine
-never synthesizes an inverse, and never fabricates a concept, edge, or NDC.
-
-Authored edges only means the graph you get is RxNorm's, including where its shape surprises you.
-`has_ingredient` is authored from the **clinical** side (`SCDC`/`SCDF`/`SCDG`) to the ingredient
-`IN`, and from the **branded** side (`SBD`/`SBDC`/`SBDF`/`SBDG`) to the **brand name** `BN` rather
-than to the active ingredient. RxNorm authors no ingredient edge on a clinical drug (`SCD`) at all,
-so that query answers with an honest empty set rather than a guess. To reach an active ingredient,
-walk to the **clinical** component and take its edge: `consistsOf` then `ingredientsOf`. From an
-`SBD`, `consistsOf` returns both its branded component (`SBDC`, whose ingredient edge is the brand
-name again) and the clinical `SCDC`; it is the `SCDC` that leads to the `IN`. The **precise** forms
-(`SCDFP`, `SBDFP`, `SCDGP`) carry no ingredient edge at all: an `SCDFP` instead reaches its
-basis-of-strength substances by `has_boss`, a one-to-many relation with a different meaning whose
-targets can be a `PIN` or a plain `IN`, and which `ingredientsOf` does not follow. Read the `tty` of
-what comes back rather than assuming it.
-
-A concept is typed by its **defining** atom, whichever line of `RXNCONSO` that sits on. `PSN`, `SY`,
-and `TMSY` type a _name_ rather than a concept, so they never establish an `RXCUI`'s term type. An
-`RXCUI` no defining atom could type is left out of the graph and reported as
-`TERM_RXNORM_UNTYPED_CONCEPT` on `graph.warnings`, rather than loaded under a synonym's term type:
-a concept that answers with a term type it does not have is a fabricated claim about a drug, and
-this engine refuses instead.
-
-```ts
-import {
-  loadRxNormGraph,
-  ingredientsOf,
-  consistsOf,
-  genericFor,
-  resolveNdc,
-} from "@cosyte/terminology";
-
-const graph = loadRxNormGraph({
-  conso: rxnconsoRrf,
-  rel: rxnrelRrf,
-  sat: rxnsatRrf,
-  version: "RXNORM_2026AA",
-});
-
-ingredientsOf(graph, "316151"); // an SCDC → { found: true, targets: [ { rxcui: "29046", tty: "IN", name: "lisinopril", … } ] }
-ingredientsOf(graph, "314076"); // an SCD → { found: true, targets: [] }, because no such edge is authored
-consistsOf(graph, "314076"); // → the SCDC, the first of the two hops to the ingredient
-genericFor(graph, "104377"); // an SBD → its SCD, via the authored tradename_of edge
-resolveNdc(graph, "00000000001"); // { resolved: true, rxcui: "314076", status: "active", asOf: "RXNORM_2026AA" }
-ingredientsOf(graph, "99999999"); // { found: false, code: "TERM_RXNORM_UNKNOWN_RXCUI" }, never a guess
-```
-
-The engine ships **no** RxNorm release; you supply it (the public-domain Current Prescribable
-Content subset, or the full BYO release). What it does ship is RxNorm's relationship and term-type
-_names_, listed under [What is bundled](#what-is-bundled).
-
 ## The invariants this engine is built on
 
 - **Never fabricate.** An unmapped source is a typed `unmapped`, never a guessed target. Every target
@@ -349,6 +372,29 @@ with its copyright:
 This section states what is distributed and under whose copyright. It is not legal advice, and makes
 no claim about whether any particular use of these materials is permitted to you.
 
+## Support
+
+Questions, bug reports, and an answer the engine got wrong go in
+[GitHub issues](https://github.com/cosyte/terminology/issues), with the smallest synthetic code
+system, map, or value set that reproduces it. Use synthetic data only: a code in patient context can
+be PHI. [SUPPORT.md](https://github.com/cosyte/.github/blob/main/SUPPORT.md) says where to ask what.
+
+## Security
+
+Report a vulnerability privately, never in a public issue, and with no real patient data in it:
+through GitHub private vulnerability reporting on this repository, or by email to
+[security@cosyte.com](mailto:security@cosyte.com). Our
+[security policy](https://github.com/cosyte/.github/blob/main/SECURITY.md) says how.
+
+## Contributing
+
+For anything that changes what the engine answers, open an issue first, so the behavior can be agreed
+before it is written; typo, link, and test fixes can go straight to a pull request. A contribution
+clears the gate CI runs, listed in
+[AGENTS.md](https://github.com/cosyte/terminology/blob/main/AGENTS.md), and a change a consumer would
+notice adds a changeset (`pnpm changeset`), whose summary becomes the changelog entry. See
+[CONTRIBUTING](https://github.com/cosyte/.github/blob/main/CONTRIBUTING.md).
+
 ## License
 
 [MIT](https://github.com/cosyte/terminology/blob/main/LICENSE) © Cosyte LLC: this package's own code.

package/dist/index.cjs

@@ -4979,7 +4979,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.3";
 
 exports.COMPLEX_MAP_SOURCE_SYSTEM = COMPLEX_MAP_SOURCE_SYSTEM;
 exports.DIAGNOSTIC_CODES = DIAGNOSTIC_CODES;