diff --git a/README.md b/README.md index bc0a43e..b0bdd7e 100644 --- a/README.md +++ b/README.md @@ -87,8 +87,8 @@ npm install @cosyte/ccda **Node `>=22.0.0`** is required, which is what `package.json` declares in `engines.node`. The package ships a **dual ESM and CJS** build with per-condition type declarations, so both `import` and `require` resolve to the right types. There is **one** runtime dependency, -[`@xmldom/xmldom`](https://www.npmjs.com/package/@xmldom/xmldom) (exact-pinned), the hardened W3C-DOM -substrate for C-CDA's XML. +[`@xmldom/xmldom`](https://www.npmjs.com/package/@xmldom/xmldom) (exact-pinned), the W3C-DOM substrate +for C-CDA's XML. ## Usage @@ -157,8 +157,8 @@ round trip unchanged true The parser is **lenient by default**: recoverable vendor quirks become stable-coded `CcdaWarning`s on `doc.warnings` (also forwarded to `options.onWarning`), not failures. `{ strict: true }` escalates the first tolerated deviation to a thrown `CcdaParseError`. Unrecoverable or hostile input (DTD/XXE, -billion-laughs entity expansion, oversized/over-deep/over-wide documents, malformed XML, a -non-`ClinicalDocument` root) is always a thrown `CcdaParseError`. +billion-laughs entity expansion, oversized/over-deep/over-wide documents, XML that does not +parse, a non-`ClinicalDocument` root) is always a thrown `CcdaParseError`. ### The full read surface @@ -1406,8 +1406,8 @@ wired for `` emission, and neither is the section-rebuild path `edi lenient parser that turns real-world, vendor-quirky input into **warnings** rather than failures (Postel's Law). It mirrors the API shape of the reference parser, [`@cosyte/hl7`](https://github.com/cosyte/hl7). Its single runtime dependency is -[`@xmldom/xmldom`](https://www.npmjs.com/package/@xmldom/xmldom) (exact-pinned), the hardened W3C-DOM -substrate for C-CDA's XML. +[`@xmldom/xmldom`](https://www.npmjs.com/package/@xmldom/xmldom) (exact-pinned), the W3C-DOM substrate +for C-CDA's XML. - **Postel's Law**: liberal parser (lenient default + warnings), conservative serializer (always spec-clean), so quirks don't propagate downstream on round-trip. diff --git a/docs-content/installation.md b/docs-content/installation.md index 9b4e268..284c1dc 100644 --- a/docs-content/installation.md +++ b/docs-content/installation.md @@ -9,7 +9,7 @@ sidebar_position: 2 `@cosyte/ccda` is a TypeScript C-CDA toolkit for Node.js. It ships dual **ESM + CJS** builds with per-condition type declarations, so it works from either module system without configuration, and it -has a **single** exact-pinned runtime dependency: the hardened W3C-DOM substrate `@xmldom/xmldom` +has a **single** exact-pinned runtime dependency: the W3C-DOM substrate `@xmldom/xmldom` (C-CDA is XML, so a DOM is unavoidable). > **Status:** **published on npm** and **public**, still pre-alpha on the Cosyte `0.0.x` diff --git a/docs-content/intro.md b/docs-content/intro.md index f3e75f3..590689f 100644 --- a/docs-content/intro.md +++ b/docs-content/intro.md @@ -11,7 +11,7 @@ Parse real-world, vendor-quirky C-CDA and pull fields out in one line, without r `@cosyte/ccda` is a near-zero-dependency TypeScript toolkit following the cosyte parser archetype: a lenient parser (quirks become **warnings**, not failures: Postel's Law), an immutable model, and a spec-clean, round-trip serializer. It mirrors the API shape of the reference parser, `@cosyte/hl7`. -Its single runtime dependency is the hardened W3C-DOM substrate `@xmldom/xmldom` (exact-pinned), +Its single runtime dependency is the W3C-DOM substrate `@xmldom/xmldom` (exact-pinned), configured XXE-safe. > **Status:** **published on npm** and **public**, still pre-alpha on the Cosyte `0.0.x` @@ -111,8 +111,8 @@ doc.warnings.every((w) => w.code === "REQUIRED_SECTION_MISSING"); // => true The parser is **lenient by default**: recoverable vendor quirks become stable-coded warnings on `doc.warnings` (also delivered live to `options.onWarning`), not failures. `{ strict: true }` escalates the first tolerated deviation to a thrown `CcdaParseError`; unrecoverable or hostile input (DTD/XXE, -billion-laughs entity expansion, oversized/over-deep/over-wide documents, malformed XML, a -non-`ClinicalDocument` root) always throws. +billion-laughs entity expansion, oversized/over-deep/over-wide documents, XML that does not +parse, a non-`ClinicalDocument` root) always throws. ## What it extracts today diff --git a/docs-content/quickstart.md b/docs-content/quickstart.md index 38e3dc3..8cc3c16 100644 --- a/docs-content/quickstart.md +++ b/docs-content/quickstart.md @@ -272,8 +272,8 @@ typeof escalated; // => "string" ## Unrecoverable input throws: everything else is a warning -Only unrecoverable structural / hostile input throws a typed `CcdaParseError`: malformed XML, a -non-`ClinicalDocument` root, or a security tripwire (DTD/XXE, entity-expansion, or size/depth/node +Only unrecoverable structural / hostile input throws a typed `CcdaParseError`: XML that does not parse, +a non-`ClinicalDocument` root, or a security tripwire (DTD/XXE, entity-expansion, or size/depth/node limits). A well-formed document with vendor quirks never throws; the quirks collect on `.warnings`. ```ts runnable throws diff --git a/docs-content/spec-notes-tolerance.md b/docs-content/spec-notes-tolerance.md index b9f112e..d840366 100644 --- a/docs-content/spec-notes-tolerance.md +++ b/docs-content/spec-notes-tolerance.md @@ -18,7 +18,7 @@ document is a hard failure. | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | **0 / 1** | Accepted silently: conformant or trivially recoverable. | A section recognized by its `templateId`. | | **2** | **Warning** with a stable code + bounded structural position; recovery continues. Escalates to a throw under `{ strict: true }`. | An unrecognized section LOINC code, a missing `doseQuantity`, a code/narrative mismatch. | -| **3** | **Fatal**: a thrown `CcdaParseError`, always (even in lenient mode). | Malformed XML, a non-`ClinicalDocument` root, a security tripwire. | +| **3** | **Fatal**: a thrown `CcdaParseError`, always (even in lenient mode). | XML that does not parse, a non-`ClinicalDocument` root, a security tripwire. | ## The warning-code model @@ -139,7 +139,7 @@ conformant document parses identically in both modes. ## Fatal codes (always throw) Seven Tier-3 codes are unrecoverable and throw a `CcdaParseError` regardless of `strict`. The first -five are **security fatals** raised by the hardened XML substrate before/while building the DOM, the +five are **security fatals** raised by the XML substrate before/while building the DOM, the load-bearing defense against hostile XML: | Fatal code | Meaning |