@cosyte/dicom 0.0.4 → 0.0.6

package/dist/index.d.cts

@@ -401,6 +401,7 @@ declare const WARNING_CODES: {
     readonly DICOM_ODD_LENGTH_VALUE_PADDED: "DICOM_ODD_LENGTH_VALUE_PADDED";
     readonly DICOM_PIXEL_DATA_LENGTH_MISMATCH: "DICOM_PIXEL_DATA_LENGTH_MISMATCH";
     readonly DICOM_PRIVATE_TAG_NO_CREATOR: "DICOM_PRIVATE_TAG_NO_CREATOR";
+    readonly DICOM_SQ_NOT_DESCENDED: "DICOM_SQ_NOT_DESCENDED";
     readonly DICOM_UN_PARSED_AS_SQ: "DICOM_UN_PARSED_AS_SQ";
     readonly DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR: "DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR";
     readonly DICOM_VR_MISMATCH: "DICOM_VR_MISMATCH";
@@ -1624,12 +1625,21 @@ declare function decodeElementValue(element: Element): DicomValue;
 
 /**
  * Parse a `(0008,0005)` Specific Character Set value (a `CS`, possibly
- * multi-valued via `\`) into its trimmed defined terms.
+ * multi-valued via `\`) into its trimmed **defined terms**.
  *
  * The first value may be empty (the ISO-2022 "G0 starts as ISO_IR 6" rule);
  * it is preserved as `""` rather than dropped so {@link resolveDecoderLabel}
  * can apply the default-repertoire fallback.
  *
+ * A component this closed table does not name is not a defined term, and it is
+ * **withheld** rather than returned. This value is multi-valued on the
+ * backslash, every component is a string a sender authored, and the result
+ * lands on `Element.specificCharacterSet`, where it presents itself as an
+ * identifier a downstream package may interpolate: that is the field, and the
+ * delimiter, this package's measured PHI leak ran through. Decoding is
+ * unaffected, because {@link resolveDecoderLabel} already skipped any term it
+ * could not map and skips the withheld marker for the same reason.
+ *
  * @example
  * ```ts
  * import { parseSpecificCharacterSet } from "@cosyte/dicom";
@@ -2339,9 +2349,15 @@ interface DeidentifiedAttribute {
     readonly repeatingGroup?: string;
 }
 /**
- * The audit trail returned alongside the de-identified dataset. Contains no
- * decoded values - only tags, keywords, action codes, and the UID map (whose
- * keys/values are UIDs, not patient data).
+ * The audit trail returned alongside the de-identified dataset.
+ *
+ * Every field except one is composed from static tables: tags, Part 6 keywords,
+ * Annex E action codes, structural `TAG[index]` sequence paths, and registry
+ * warning messages. **`uidMap` is the exception, and it is not value-free.** Its
+ * keys are the source UIDs read out of the file, kept so a caller can make UID
+ * replacement consistent across a study or an archive. A Study or SOP Instance
+ * UID is a unique identifying number, so treat `uidMap` as PHI: the rest of the
+ * report is safe to log, and that field is not.
  *
  * @example
  * ```ts
@@ -2356,7 +2372,11 @@ interface DeidentifyReport {
     readonly attributes: readonly DeidentifiedAttribute[];
     /** Private tags removed under the Basic Profile (kept ones are omitted). */
     readonly removedPrivateTags: readonly Tag[];
-    /** Source UID → replacement UID, for cross-file consistency. */
+    /**
+     * Source UID → replacement UID, for cross-file consistency. The **keys are
+     * document values**, not composed identifiers: this is the one field of the
+     * report that carries PHI.
+     */
     readonly uidMap: ReadonlyMap<string, string>;
     /** Safety warnings - notably burned-in-pixel annotation that cannot be cleaned. */
     readonly warnings: readonly DicomParseWarning[];
@@ -2470,7 +2490,8 @@ declare class DeidentifyError extends Error {
  * nine *metadata-affecting* Annex E Options, driven by the generated Table E.1-1
  * action map ({@link annexE}). It is a **pure** function: the input {@link Dataset}
  * is never mutated; a fresh `Dataset` (with a rebuilt element map and File Meta)
- * is returned alongside a value-free {@link DeidentifyReport}.
+ * is returned alongside a {@link DeidentifyReport} that is value-free except for
+ * `uidMap`, whose keys are the file's own source UIDs.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active
@@ -2508,9 +2529,15 @@ declare class DeidentifyError extends Error {
  * - A private data element kept under `RetainSafePrivate` is kept *verbatim* - if
  *   it is itself a sequence carrying standard PHI attributes, that nested content
  *   is not recursed. The profile vouches the element is safe; nest accordingly.
- * - A sequence whose `items` the parser did not materialize (e.g. an
- *   undefined-length `UN` value stored as an opaque span) is kept verbatim rather
- *   than recursed, so any nested listed attributes are not de-identified.
+ * - A sequence whose `items` the parser did not materialize is kept verbatim
+ *   rather than recursed, so any nested listed attributes are not de-identified.
+ *   That is now a **narrow and announced** set: an undefined-length `UN` value the
+ *   CP-246 descent could not read as a sequence, and a defined-length Implicit VR
+ *   LE value whose resolved `SQ` turned out not to be an item stream - the latter
+ *   carrying `DICOM_SQ_NOT_DESCENDED` on `ds.warnings`. It used to include
+ *   **every** defined-length sequence under Implicit VR LE, silently
+ *   (`DICOM-IMPLICIT-SQ-NOT-DESCENDED`, fixed after `0.0.5`). Check
+ *   `ds.warnings` before treating a report as complete.
  *
  * @module
  */
@@ -2519,8 +2546,10 @@ declare class DeidentifyError extends Error {
  * De-identify a {@link Dataset} per PS3.15 Annex E - the Basic Application Level
  * Confidentiality Profile, plus any Retain/Clean Options passed in `retain`.
  *
- * Pure: `ds` is never mutated. Returns a fresh dataset and a value-free
- * {@link DeidentifyReport} (tags, keywords, action codes, the UID map, warnings).
+ * Pure: `ds` is never mutated. Returns a fresh dataset and a
+ * {@link DeidentifyReport} of tags, keywords, action codes, warnings and the UID
+ * map. Everything in it is composed from static tables except `uidMap`, whose
+ * keys are the source UIDs the file carried: treat that field as PHI.
  *
  * @throws {@link DeidentifyError} (`INVALID_OPTIONS`) for an unknown Retain option
  *   or a malformed `uidRoot`.

package/dist/index.d.ts

@@ -401,6 +401,7 @@ declare const WARNING_CODES: {
     readonly DICOM_ODD_LENGTH_VALUE_PADDED: "DICOM_ODD_LENGTH_VALUE_PADDED";
     readonly DICOM_PIXEL_DATA_LENGTH_MISMATCH: "DICOM_PIXEL_DATA_LENGTH_MISMATCH";
     readonly DICOM_PRIVATE_TAG_NO_CREATOR: "DICOM_PRIVATE_TAG_NO_CREATOR";
+    readonly DICOM_SQ_NOT_DESCENDED: "DICOM_SQ_NOT_DESCENDED";
     readonly DICOM_UN_PARSED_AS_SQ: "DICOM_UN_PARSED_AS_SQ";
     readonly DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR: "DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR";
     readonly DICOM_VR_MISMATCH: "DICOM_VR_MISMATCH";
@@ -1624,12 +1625,21 @@ declare function decodeElementValue(element: Element): DicomValue;
 
 /**
  * Parse a `(0008,0005)` Specific Character Set value (a `CS`, possibly
- * multi-valued via `\`) into its trimmed defined terms.
+ * multi-valued via `\`) into its trimmed **defined terms**.
  *
  * The first value may be empty (the ISO-2022 "G0 starts as ISO_IR 6" rule);
  * it is preserved as `""` rather than dropped so {@link resolveDecoderLabel}
  * can apply the default-repertoire fallback.
  *
+ * A component this closed table does not name is not a defined term, and it is
+ * **withheld** rather than returned. This value is multi-valued on the
+ * backslash, every component is a string a sender authored, and the result
+ * lands on `Element.specificCharacterSet`, where it presents itself as an
+ * identifier a downstream package may interpolate: that is the field, and the
+ * delimiter, this package's measured PHI leak ran through. Decoding is
+ * unaffected, because {@link resolveDecoderLabel} already skipped any term it
+ * could not map and skips the withheld marker for the same reason.
+ *
  * @example
  * ```ts
  * import { parseSpecificCharacterSet } from "@cosyte/dicom";
@@ -2339,9 +2349,15 @@ interface DeidentifiedAttribute {
     readonly repeatingGroup?: string;
 }
 /**
- * The audit trail returned alongside the de-identified dataset. Contains no
- * decoded values - only tags, keywords, action codes, and the UID map (whose
- * keys/values are UIDs, not patient data).
+ * The audit trail returned alongside the de-identified dataset.
+ *
+ * Every field except one is composed from static tables: tags, Part 6 keywords,
+ * Annex E action codes, structural `TAG[index]` sequence paths, and registry
+ * warning messages. **`uidMap` is the exception, and it is not value-free.** Its
+ * keys are the source UIDs read out of the file, kept so a caller can make UID
+ * replacement consistent across a study or an archive. A Study or SOP Instance
+ * UID is a unique identifying number, so treat `uidMap` as PHI: the rest of the
+ * report is safe to log, and that field is not.
  *
  * @example
  * ```ts
@@ -2356,7 +2372,11 @@ interface DeidentifyReport {
     readonly attributes: readonly DeidentifiedAttribute[];
     /** Private tags removed under the Basic Profile (kept ones are omitted). */
     readonly removedPrivateTags: readonly Tag[];
-    /** Source UID → replacement UID, for cross-file consistency. */
+    /**
+     * Source UID → replacement UID, for cross-file consistency. The **keys are
+     * document values**, not composed identifiers: this is the one field of the
+     * report that carries PHI.
+     */
     readonly uidMap: ReadonlyMap<string, string>;
     /** Safety warnings - notably burned-in-pixel annotation that cannot be cleaned. */
     readonly warnings: readonly DicomParseWarning[];
@@ -2470,7 +2490,8 @@ declare class DeidentifyError extends Error {
  * nine *metadata-affecting* Annex E Options, driven by the generated Table E.1-1
  * action map ({@link annexE}). It is a **pure** function: the input {@link Dataset}
  * is never mutated; a fresh `Dataset` (with a rebuilt element map and File Meta)
- * is returned alongside a value-free {@link DeidentifyReport}.
+ * is returned alongside a {@link DeidentifyReport} that is value-free except for
+ * `uidMap`, whose keys are the file's own source UIDs.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active
@@ -2508,9 +2529,15 @@ declare class DeidentifyError extends Error {
  * - A private data element kept under `RetainSafePrivate` is kept *verbatim* - if
  *   it is itself a sequence carrying standard PHI attributes, that nested content
  *   is not recursed. The profile vouches the element is safe; nest accordingly.
- * - A sequence whose `items` the parser did not materialize (e.g. an
- *   undefined-length `UN` value stored as an opaque span) is kept verbatim rather
- *   than recursed, so any nested listed attributes are not de-identified.
+ * - A sequence whose `items` the parser did not materialize is kept verbatim
+ *   rather than recursed, so any nested listed attributes are not de-identified.
+ *   That is now a **narrow and announced** set: an undefined-length `UN` value the
+ *   CP-246 descent could not read as a sequence, and a defined-length Implicit VR
+ *   LE value whose resolved `SQ` turned out not to be an item stream - the latter
+ *   carrying `DICOM_SQ_NOT_DESCENDED` on `ds.warnings`. It used to include
+ *   **every** defined-length sequence under Implicit VR LE, silently
+ *   (`DICOM-IMPLICIT-SQ-NOT-DESCENDED`, fixed after `0.0.5`). Check
+ *   `ds.warnings` before treating a report as complete.
  *
  * @module
  */
@@ -2519,8 +2546,10 @@ declare class DeidentifyError extends Error {
  * De-identify a {@link Dataset} per PS3.15 Annex E - the Basic Application Level
  * Confidentiality Profile, plus any Retain/Clean Options passed in `retain`.
  *
- * Pure: `ds` is never mutated. Returns a fresh dataset and a value-free
- * {@link DeidentifyReport} (tags, keywords, action codes, the UID map, warnings).
+ * Pure: `ds` is never mutated. Returns a fresh dataset and a
+ * {@link DeidentifyReport} of tags, keywords, action codes, warnings and the UID
+ * map. Everything in it is composed from static tables except `uidMap`, whose
+ * keys are the source UIDs the file carried: treat that field as PHI.
  *
  * @throws {@link DeidentifyError} (`INVALID_OPTIONS`) for an unknown Retain option
  *   or a malformed `uidRoot`.