@cosyte/dicom 0.0.6 → 0.0.8

package/dist/index.cjs

@@ -11,7 +11,7 @@ var __export = (target, all) => {
 };
 
 // src/version.ts
-var VERSION = "0.0.6";
+var VERSION = "0.0.8";
 
 // src/dictionary/index.ts
 var dictionary_exports = {};
@@ -11735,6 +11735,12 @@ var WARNING_CODES = {
   // === Reserved by later phases (declared, not emitted in Phase 2) ===
   DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED: "DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED",
   // reserved by Phase 7 - not emitted in Phase 2
+  DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED: "DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED",
+  // emitted by deidentify(), never by the parser
+  DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE: "DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE",
+  // emitted by deidentify(), never by the parser
+  DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE: "DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE",
+  // emitted by deidentify(), never by the parser
   DICOM_PRIVATE_CREATOR_UNKNOWN: "DICOM_PRIVATE_CREATOR_UNKNOWN"
   // reserved by Phase 6 - not emitted in Phase 2
 };
@@ -11748,13 +11754,30 @@ var WARNING_MESSAGES = Object.freeze({
   DICOM_PRIVATE_TAG_NO_CREATOR: "Private element ({tag}) has no Private Creator registered for its block; treating as VR=UN.",
   DICOM_GROUP_LENGTH_IN_DATASET: "Retired Group Length element ({tag}) encountered in dataset; preserved as-is.",
   DICOM_NONZERO_RESERVED_BYTES: "Element ({tag}) has non-zero reserved bytes between VR and length (first byte {n}, second byte {n2}); ignoring.",
-  DICOM_SQ_NOT_DESCENDED: "Element ({tag}) resolved to VR=SQ from the dictionary but its defined-length value is not a valid item stream; kept as opaque bytes and NOT descended, so nothing nested inside it is visible to navigation or de-identification.",
+  DICOM_SQ_NOT_DESCENDED: "Element ({tag}) resolved to VR=SQ from the dictionary but its defined-length value is not a valid item stream; kept as opaque bytes and NOT descended, so nothing nested inside it is visible to navigation, and deidentify() cannot audit it. See DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE.",
   DICOM_UN_PARSED_AS_SQ: "Element ({tag}) has VR=UN with undefined length; descended as Implicit VR LE sequence per CP-246.",
   DICOM_EMPTY_ITEM_IN_SEQUENCE: "Sequence ({tag}) contains an empty item (length=0); tolerated.",
   DICOM_PIXEL_DATA_LENGTH_MISMATCH: "(7FE0,0010) PixelData declared length {n} does not match computed {n2} bytes.",
   DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR: "Private element ({tag}) under Implicit VR LE has no VR override; falling back to UN.",
   DICOM_PRIVATE_CREATOR_UNKNOWN: "Private element ({tag}) has a Private Creator the active profile's private dictionary does not name; falling back to UN. The creator string is not reproduced here - read the (gggg,00EE) element if you need it.",
   DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED: "Pixel Data is present and Burned In Annotation is not 'NO'; this metadata-only de-identifier cannot inspect or clean pixels. Recognizable text may remain burned into the image.",
+  DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED: "Element ({tag}) {vr} was kept by the action table, but its value ends with {n} whole Data Element(s) - an over-declared Value Length swallowed what followed it. Emptied rather than kept, because the action table cannot see an attribute encoded inside a value. Read report.embeddedAttributes for the tags that were hidden there.",
+  // Deliberately short. One of these is raised per un-auditable element, so a
+  // long message is multiplied by an element count the input controls; the
+  // reasoning belongs in the docs, not in a string repeated thousands of times.
+  DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE: "Element ({tag}) is VR=SQ with no parsed items, so its {n} value bytes could not be audited (PS3.15 E.1.1); emptied. See report.unauditableSequences.",
+  // Deliberately short for the same reason as the code above: one per element,
+  // and the element count is chosen by the input.
+  //
+  // NEITHER THE TAG NOR THE VR IS ECHOED, and that is specific to this code
+  // rather than caution. Every other factory's {tag} is composed from a real
+  // Data Element header; the condition that raises THIS one is that the header
+  // was fabricated from bytes inside some element's value, so its four tag bytes
+  // and its two VR bytes are document content. `renderTag` shape-checks a tag
+  // and cannot refuse one, so the withholding has to happen at the call site.
+  // The byte offset locates the element instead, and is a position this parser
+  // counted rather than anything the document said.
+  DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE: "An element at byte offset {n2} carries an on-wire VR that is not one of the 34 PS3.5 6.2 defines, so its {n} value bytes are not a Value Field this library decoded; emptied (PS3.15 E.1.1). Its tag and VR are withheld: an earlier under-declared length can make them fragments of some element's value. See report.undefinedVrElements.",
   DICOM_BOM_IN_TEXT_VR: "Element ({tag}) {vr} value begins with a UTF-8 BOM; stripped on decode.",
   DICOM_TRAILING_NULL_IN_TEXT_VR: "Element ({tag}) {vr} value has a trailing NULL pad where SPACE is expected; trimmed.",
   DICOM_UI_TRAILING_SPACE: "Element ({tag}) UI value is SPACE-padded; UI requires NULL padding (PS3.5 \xA76.2). Trimmed.",
@@ -11832,6 +11855,25 @@ function privateCreatorUnknown(position, tag) {
 function burnedInAnnotationNotRemoved(position) {
   return build(WARNING_CODES.DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED, position);
 }
+function embeddedAttributeRemoved(position, tag, vr, count) {
+  return build(WARNING_CODES.DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED, position, {
+    tag,
+    vr,
+    n: count
+  });
+}
+function sequenceNotAuditable(position, tag, byteLength) {
+  return build(WARNING_CODES.DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE, position, {
+    tag,
+    n: byteLength
+  });
+}
+function undefinedVrNotAuditable(position, byteLength) {
+  return build(WARNING_CODES.DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE, position, {
+    n: byteLength,
+    n2: position.byteOffset
+  });
+}
 function bomInTextVR(position, tag, vr) {
   return build(WARNING_CODES.DICOM_BOM_IN_TEXT_VR, position, { tag, vr });
 }
@@ -14656,6 +14698,132 @@ function uidValueMultiplicity(rawBytes) {
   return raw.split("\\").length;
 }
 
+// src/deident/embedded.ts
+var KNOWN_VRS2 = new Set(Object.keys(BE_VR_STRIDE));
+var UNDEFINED_LENGTH4 = 4294967295;
+var FFFE_GROUP = 65534;
+var SCANNABLE_CARRIER_VRS = /* @__PURE__ */ new Set([
+  "AE",
+  "AS",
+  "CS",
+  "DA",
+  "DS",
+  "DT",
+  "IS",
+  "LO",
+  "LT",
+  "PN",
+  "SH",
+  "ST",
+  "TM",
+  "UC",
+  "UI",
+  "UR",
+  "UT"
+]);
+var ALLOWED_CONTROL_BYTES = /* @__PURE__ */ new Set([
+  9,
+  // TAB
+  10,
+  // LF
+  12,
+  // FF
+  13,
+  // CR
+  27
+  // ESC
+]);
+var CONTROL_TOLERANT_VRS = /* @__PURE__ */ new Set(["LT", "ST", "UT"]);
+var ESC_ONLY_VRS = /* @__PURE__ */ new Set(["LO", "SH", "UC", "PN"]);
+var MAX_SCAN_BYTES = 1 << 20;
+var MIN_HEADER = 8;
+function readU16(buf, off, littleEndian) {
+  return littleEndian ? buf.readUInt16LE(off) : buf.readUInt16BE(off);
+}
+function readU32(buf, off, littleEndian) {
+  return littleEndian ? buf.readUInt32LE(off) : buf.readUInt32BE(off);
+}
+function decodeAt(value, off, encoding) {
+  if (off + MIN_HEADER > value.length) return void 0;
+  const littleEndian = encoding !== "explicitBE";
+  const group = readU16(value, off, littleEndian);
+  const element = readU16(value, off + 2, littleEndian);
+  if (group === FFFE_GROUP) {
+    return { next: off + 8, tag: void 0 };
+  }
+  if (group === 0 && element === 0) return void 0;
+  const tag = joinTag(group, element);
+  if (encoding === "implicit") {
+    const length2 = readU32(value, off + 4, littleEndian);
+    if (length2 === UNDEFINED_LENGTH4 || length2 % 2 !== 0) return void 0;
+    const next2 = off + 8 + length2;
+    return next2 > value.length ? void 0 : { next: next2, tag };
+  }
+  const vr = value.toString("latin1", off + 4, off + 6);
+  if (!KNOWN_VRS2.has(vr)) return void 0;
+  if (LONG_FORM_VRS.has(vr)) {
+    if (off + 12 > value.length) return void 0;
+    if (value[off + 6] !== 0 || value[off + 7] !== 0) return void 0;
+    const length2 = readU32(value, off + 8, littleEndian);
+    if (length2 === UNDEFINED_LENGTH4 || length2 % 2 !== 0) return void 0;
+    const next2 = off + 12 + length2;
+    return next2 > value.length ? void 0 : { next: next2, tag };
+  }
+  const length = readU16(value, off + 6, littleEndian);
+  if (length % 2 !== 0) return void 0;
+  const next = off + 8 + length;
+  return next > value.length ? void 0 : { next, tag };
+}
+function isScannableCarrier(vr) {
+  return SCANNABLE_CARRIER_VRS.has(vr);
+}
+function hasByteOutsideRepertoire(region, carrierVr) {
+  const allFive = CONTROL_TOLERANT_VRS.has(carrierVr);
+  const escOnly = ESC_ONLY_VRS.has(carrierVr);
+  for (const byte of region) {
+    if (byte >= 32 && byte !== 127) continue;
+    if (allFive && ALLOWED_CONTROL_BYTES.has(byte)) continue;
+    if (escOnly && byte === 27) continue;
+    return true;
+  }
+  return false;
+}
+function findEmbeddedAttributes(value, carrierVr, encoding, isActionable) {
+  if (!isScannableCarrier(carrierVr)) return void 0;
+  if (value.length < MIN_HEADER) return void 0;
+  const windowStart = value.length > MAX_SCAN_BYTES ? value.length - MAX_SCAN_BYTES : 0;
+  const window = value.subarray(windowStart);
+  const n = window.length;
+  const half = (n >> 1) + 1;
+  const tiles = new Uint8Array(half);
+  const hit = new Uint8Array(half);
+  for (let off = n - MIN_HEADER & -2; off >= 0; off -= 2) {
+    const decoded = decodeAt(window, off, encoding);
+    if (decoded === void 0) continue;
+    const atEnd = decoded.next === n;
+    const onward = decoded.next < n ? tiles[decoded.next >> 1] === 1 : false;
+    if (!atEnd && !onward) continue;
+    tiles[off >> 1] = 1;
+    const actionable = decoded.tag !== void 0 && isActionable(decoded.tag);
+    const onwardHit = decoded.next < n ? hit[decoded.next >> 1] === 1 : false;
+    if (actionable || onwardHit) hit[off >> 1] = 1;
+  }
+  for (let off = 0; off + MIN_HEADER <= n; off += 2) {
+    if (hit[off >> 1] !== 1) continue;
+    if (!hasByteOutsideRepertoire(window.subarray(off), carrierVr)) return void 0;
+    const tags = [];
+    let pos = off;
+    while (pos < n) {
+      const decoded = decodeAt(window, pos, encoding);
+      if (decoded === void 0) break;
+      if (decoded.tag !== void 0) tags.push(decoded.tag);
+      pos = decoded.next;
+    }
+    return tags;
+  }
+  return void 0;
+}
+
 // src/deident/types.ts
 var DEIDENTIFY_OPTIONS = Object.freeze([
   "CleanGraphics",
@@ -14727,6 +14895,9 @@ var BODY_ENCODING2 = {
   "1.2.840.10008.1.2.2": "explicitBE",
   "1.2.840.10008.1.2.1.99": "explicitLE"
 };
+var MAX_UNAUDITABLE_SEQUENCE_FINDINGS = 64;
+var MAX_UNDEFINED_VR_FINDINGS = 64;
+var KNOWN_VRS3 = new Set(Object.keys(BE_VR_STRIDE));
 function validateRetain(retain) {
   const valid = new Set(DEIDENTIFY_OPTIONS);
   const active = /* @__PURE__ */ new Set();
@@ -14840,6 +15011,64 @@ function isPrivateCreatorElement(tag) {
   const { element } = splitTag(tag);
   return element >= 16 && element <= 255;
 }
+function actsOnTag(tag, ctx) {
+  if (isPrivateTag(tag)) return true;
+  const action = annexE(tag);
+  if (action === void 0) return false;
+  return resolveAction(effectiveCode(action, ctx.active)) !== "K";
+}
+function hasUndefinedVr(el) {
+  return !KNOWN_VRS3.has(el.vr);
+}
+function keepOrEmpty(el, ctx, contextPath, out) {
+  if (hasUndefinedVr(el)) {
+    emptyUndefinedVrElement(el, ctx, contextPath, out);
+    return false;
+  }
+  const hidden = findEmbeddedAttributes(el.rawBytes, el.vr, ctx.encoding, (t) => actsOnTag(t, ctx));
+  if (hidden === void 0) {
+    out.elements.set(el.tag, el);
+    return true;
+  }
+  out.elements.set(el.tag, freshScalar(el, buffer.Buffer.alloc(0), 0));
+  out.embeddedAttributes.push({
+    tag: el.tag,
+    vr: el.vr,
+    hidden,
+    ...contextPath.length > 0 ? { contextPath: [...contextPath] } : {}
+  });
+  out.warnings.push(
+    embeddedAttributeRemoved({ byteOffset: el.byteOffset }, el.tag, el.vr, hidden.length)
+  );
+  return false;
+}
+function emptyUndefinedVrElement(el, ctx, contextPath, out) {
+  out.elements.set(el.tag, freshScalar(el, buffer.Buffer.alloc(0), 0));
+  if (ctx.budget.undefinedVrElements >= MAX_UNDEFINED_VR_FINDINGS) return;
+  ctx.budget.undefinedVrElements += 1;
+  out.undefinedVrElements.push({
+    byteOffset: el.byteOffset,
+    byteLength: el.rawBytes.length,
+    ...contextPath.length > 0 ? { contextPath: [...contextPath] } : {}
+  });
+  out.warnings.push(undefinedVrNotAuditable({ byteOffset: el.byteOffset }, el.rawBytes.length));
+}
+function isUnauditableSequence(el) {
+  return el.vr === "SQ" && el.items === void 0;
+}
+function emptyUnauditableSequence(el, ctx, contextPath, out) {
+  out.elements.set(el.tag, rebuildSequence(el, [], ctx.encoding));
+  if (ctx.budget.unauditableSequences >= MAX_UNAUDITABLE_SEQUENCE_FINDINGS) return;
+  ctx.budget.unauditableSequences += 1;
+  out.unauditableSequences.push({
+    tag: el.tag,
+    byteLength: el.rawBytes.length,
+    ...contextPath.length > 0 ? { contextPath: [...contextPath] } : {}
+  });
+  out.warnings.push(
+    sequenceNotAuditable({ byteOffset: el.byteOffset }, el.tag, el.rawBytes.length)
+  );
+}
 function creatorsInScope(source) {
   const byBlock = /* @__PURE__ */ new Map();
   for (const el of source) {
@@ -14866,21 +15095,26 @@ function processElements(source, ctx, contextPath) {
   const out = {
     elements: /* @__PURE__ */ new Map(),
     attributes: [],
-    removedPrivateTags: []
+    removedPrivateTags: [],
+    embeddedAttributes: [],
+    unauditableSequences: [],
+    undefinedVrElements: [],
+    warnings: []
   };
   const creators = creatorsInScope(source);
   for (const el of source) {
     if (isPrivateTag(el.tag)) {
-      if (keepsPrivate(el, ctx, creators)) out.elements.set(el.tag, el);
+      if (keepsPrivate(el, ctx, creators)) keepOrEmpty(el, ctx, contextPath, out);
       else out.removedPrivateTags.push(el.tag);
       continue;
     }
     const action = annexE(el.tag);
     if (action === void 0) {
-      if (el.vr === "SQ" && el.items !== void 0) {
-        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
+      if (el.vr === "SQ") {
+        if (isUnauditableSequence(el)) emptyUnauditableSequence(el, ctx, contextPath, out);
+        else out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
       } else {
-        out.elements.set(el.tag, el);
+        keepOrEmpty(el, ctx, contextPath, out);
       }
       continue;
     }
@@ -14892,8 +15126,7 @@ function processElements(source, ctx, contextPath) {
     let applied;
     switch (resolved) {
       case "K":
-        out.elements.set(el.tag, el);
-        applied = "kept";
+        applied = keepOrEmpty(el, ctx, contextPath, out) ? "kept" : "emptied";
         break;
       case "X":
         applied = "removed";
@@ -14935,6 +15168,10 @@ function descendSequence(el, ctx, contextPath, out) {
     const inner = processElements(item.elements(), ctx, childPath);
     out.attributes.push(...inner.attributes);
     out.removedPrivateTags.push(...inner.removedPrivateTags);
+    out.embeddedAttributes.push(...inner.embeddedAttributes);
+    out.unauditableSequences.push(...inner.unauditableSequences);
+    out.undefinedVrElements.push(...inner.undefinedVrElements);
+    out.warnings.push(...inner.warnings);
     newItems.push(new Item({ index, warnings: [], elements: inner.elements }));
   });
   return rebuildSequence(el, newItems, ctx.encoding);
@@ -14951,13 +15188,23 @@ function applySequenceAction(el, resolved, action, ctx, contextPath, out) {
       applied = "emptied";
       break;
     case "C":
-      out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
-      applied = "cleaned";
+      if (isUnauditableSequence(el)) {
+        emptyUnauditableSequence(el, ctx, contextPath, out);
+        applied = "emptied";
+      } else {
+        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
+        applied = "cleaned";
+      }
       break;
     case "U":
     case "K":
-      out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
-      applied = "kept";
+      if (isUnauditableSequence(el)) {
+        emptyUnauditableSequence(el, ctx, contextPath, out);
+        applied = "emptied";
+      } else {
+        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
+        applied = "kept";
+      }
       break;
   }
   out.attributes.push(auditAttribute(el.tag, action, resolved, applied, contextPath));
@@ -15003,8 +15250,18 @@ function deidentify(ds, options = {}) {
     active,
     remap,
     profile: options.profile,
-    encoding};
-  const { elements, attributes, removedPrivateTags } = processElements(ds.elements(), ctx, []);
+    encoding,
+    budget: { unauditableSequences: 0, undefinedVrElements: 0 }
+  };
+  const processed = processElements(ds.elements(), ctx, []);
+  const {
+    elements,
+    attributes,
+    removedPrivateTags,
+    embeddedAttributes,
+    unauditableSequences,
+    undefinedVrElements
+  } = processed;
   elements.set(
     TAG_PATIENT_IDENTITY_REMOVED,
     insertedScalar(TAG_PATIENT_IDENTITY_REMOVED, "CS", buffer.Buffer.from("YES", "latin1"), littleEndian)
@@ -15014,7 +15271,7 @@ function deidentify(ds, options = {}) {
     TAG_DEIDENTIFICATION_METHOD,
     insertedScalar(TAG_DEIDENTIFICATION_METHOD, "LO", buffer.Buffer.from(method, "latin1"), littleEndian)
   );
-  const warnings = [];
+  const warnings = [...processed.warnings];
   if (hasUncleanedBurnedIn(ds)) {
     const offset = ds.get(TAG_PIXEL_DATA)?.byteOffset ?? 0;
     warnings.push(burnedInAnnotationNotRemoved({ byteOffset: offset, fileMeta: false }));
@@ -15029,6 +15286,9 @@ function deidentify(ds, options = {}) {
   const report = {
     attributes,
     removedPrivateTags,
+    embeddedAttributes,
+    unauditableSequences,
+    undefinedVrElements,
     uidMap: remap.cache,
     warnings,
     retained: [...active]