@cosyte/astm 0.0.8 → 0.0.10

package/dist/index.cjs

@@ -127,10 +127,59 @@ var WARNING_CODES = {
    * not recognize as one does not open a new message.
    */
   ASTM_RECORD_UNKNOWN_TYPE: "ASTM_RECORD_UNKNOWN_TYPE",
+  /**
+   * The delimiters in force found **no field separator at all** in a record that carries content
+   * beyond its type letter, so the whole record read back as a single field and none of its modeled
+   * fields could be recovered. The raw line is surfaced intact and nothing is dropped, but on a
+   * result record it means the value, the units and the status are all absent from the parsed model.
+   *
+   * This is one signature of a record being read with a delimiter set that does not belong to it,
+   * which is how a delimiter-scoping mistake turns into lost values. It is reported rather than
+   * repaired, because recovering the fields would mean guessing which set the sender meant.
+   *
+   * **Its absence is not evidence that a record was read in its own set.** This tests one of the
+   * four delimiter roles, the field separator, and only in its total form, where that separator
+   * occurs in the line (unescaped). Two whole classes of the same loss are outside it: a foreign set
+   * whose field separator happens to occur somewhere in the line still splits (on the wrong
+   * boundaries, silently, and this can happen to one record inside a run of these warnings); and a
+   * set differing in the repeat, component or escape role usually splits into fields normally,
+   * where a mis-split component can cost a test identity while the value survives, and where an
+   * `&X&` sequence whose body is a delimiter is an opaque atom, so that delimiter does not split
+   * and every field after it shifts. The escape role's worst case has narrowed and not
+   * disappeared: an escape character heading no sequence is now read as a literal and reported
+   * under {@link WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER} rather than merging the rest of the
+   * record, but a delimiter swallowed inside an `&X&` body is reported only by
+   * {@link WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE}, which is tolerable. Treat this code as a
+   * report that one record definitely lost its fields, never as a sweep that would have fired if
+   * any had.
+   */
+  ASTM_RECORD_FIELDS_UNSEPARATED: "ASTM_RECORD_FIELDS_UNSEPARATED",
   /** The header declared delimiters other than the canonical `H|\^&`: tolerated, noted. */
   ASTM_NONSTANDARD_DELIMITERS: "ASTM_NONSTANDARD_DELIMITERS",
   /** An escape sequence body was not one of `&F&`/`&S&`/`&R&`/`&E&`: preserved verbatim. */
   ASTM_UNKNOWN_ESCAPE_SEQUENCE: "ASTM_UNKNOWN_ESCAPE_SEQUENCE",
+  /**
+   * An escape character appeared where no escape sequence starts (an escape sequence is the escape
+   * character, one body character, and the escape character again). It is read as the **literal
+   * character it is** and kept byte-for-byte in the decoded value. Nothing is dropped and no byte is
+   * invented: this flags that the sender did not write the character the spec-clean way, which
+   * is `&E&`.
+   *
+   * **What it replaced is the reason it exists.** The codec used to read such a character as the
+   * opening of a sequence that never closed and merge the whole remainder of the record into the
+   * field it sat in, reporting nothing at all. One `&` in a result value cost the units, the
+   * abnormal flag and the status together and left the status reading `unspecified` rather than
+   * `final`; one in a surname cost the patient's birth date and sex. Emit then re-escaped the merged
+   * text into a spec-clean-looking line that read back as the same wrong value, so the mis-read
+   * survived a round trip without ever surfacing.
+   *
+   * **This code is not a statement about the rest of the record.** It reports one character. A
+   * *different* escape character in the same record may still head a real three-character sequence,
+   * and if that sequence's body happens to be a delimiter (`&|&` under the canonical set) the atom
+   * rule means that delimiter does not split. That case is reported separately, under
+   * {@link WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE}, and it can still cost a field boundary.
+   */
+  ASTM_UNPAIRED_ESCAPE_CHARACTER: "ASTM_UNPAIRED_ESCAPE_CHARACTER",
   /**
    * A result value field carried an *unescaped* component delimiter, so it split into more than one
    * component. Both the full raw value and the split are surfaced and this warning fires: the
@@ -222,6 +271,13 @@ function unknownRecordType(position) {
     position
   };
 }
+function fieldsUnseparated(position) {
+  return {
+    code: WARNING_CODES.ASTM_RECORD_FIELDS_UNSEPARATED,
+    message: "The delimiters in force found no field separator in this record, so its whole content read back as one field and none of its modeled fields could be recovered. The raw line is surfaced intact, and no field is reconstructed, because the set the sender used is unknown.",
+    position
+  };
+}
 function nonStandardDelimiters(position) {
   return {
     code: WARNING_CODES.ASTM_NONSTANDARD_DELIMITERS,
@@ -250,6 +306,13 @@ function unknownEscapeSequence(position) {
     position
   };
 }
+function unpairedEscapeCharacter(position) {
+  return {
+    code: WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER,
+    message: "An escape character headed no escape sequence, read as the literal character it is rather than opening a sequence that never closes. The spec-clean form is the escaped one.",
+    position
+  };
+}
 function ambiguousValueSplit(position) {
   return {
     code: WARNING_CODES.ASTM_RECORD_AMBIGUOUS_VALUE_SPLIT,
@@ -418,17 +481,27 @@ function classifyMessage(records) {
   let hasQuery = false;
   let hasResults = false;
   let hasOrders = false;
+  let hasUnrecognized = false;
   for (const r of records) {
     if (r.type === "Q") hasQuery = true;
     else if (r.type === "R") hasResults = true;
     else if (r.type === "O") hasOrders = true;
+    else if (r.type === "unsupported") hasUnrecognized = true;
   }
   let kind;
   if (hasQuery) kind = "host-query";
+  else if (hasUnrecognized) kind = "indeterminate";
   else if (hasResults) kind = "results";
   else if (hasOrders) kind = "orders";
   else kind = "indeterminate";
-  return { kind, hasQuery, hasResults, hasOrders, isHostQueryRequest: kind === "host-query" };
+  return {
+    kind,
+    hasQuery,
+    hasResults,
+    hasOrders,
+    hasUnrecognized,
+    isHostQueryRequest: kind === "host-query"
+  };
 }
 
 // src/frames/warnings.ts
@@ -542,6 +615,7 @@ var TOLERABLE_CODES = Object.freeze(
   /* @__PURE__ */ new Set([
     WARNING_CODES.ASTM_NONSTANDARD_DELIMITERS,
     WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE,
+    WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER,
     WARNING_CODES.ASTM_RECORD_UNINTERPRETED_QUERY_STATUS
   ])
 );
@@ -826,7 +900,7 @@ var defaultProfile = defineAstmProfile({
 // src/profiles/reference-corpus.ts
 var referenceCorpus = defineAstmProfile({
   name: "referenceCorpus",
-  description: "Non-standard-escape tolerance grounded firsthand in the escape-agnostic OSS reference corpus (python-astm / senaite). Syntactic encoding noise only: the value is preserved verbatim, never a safety-critical value.",
+  description: "Non-standard-escape tolerance grounded firsthand in the escape-agnostic OSS reference corpus (python-astm / senaite). Mostly syntactic encoding noise, with one measured exception: an escape sequence whose body is itself a delimiter is an opaque atom, so that delimiter does not split and a result can lose its units and its status. Read the values; do not rely on this profile leaving only cosmetic deviations behind.",
   provenance: {
     source: "kxepal/python-astm codec.py (BSD) + senaite.astm / senaite.lis2a",
     reference: "https://github.com/kxepal/python-astm/blob/master/astm/codec.py ; https://github.com/senaite/senaite.astm",
@@ -836,7 +910,7 @@ var referenceCorpus = defineAstmProfile({
   tolerate: [
     {
       code: "ASTM_UNKNOWN_ESCAPE_SEQUENCE",
-      rationale: "The OSS reference stack (python-astm codec.py, firsthand-verified) treats '&' as literal data and never decodes escape sequences, so streams from that ecosystem carry non-standard '&\u2026&' bodies our escape-aware tokenizer flags. The body is preserved byte-for-byte in the value; the deviation is recognizable, syntactic, and non-clinical."
+      rationale: "The OSS reference stack (python-astm codec.py, firsthand-verified) treats '&' as literal data and never decodes escape sequences, so streams from that ecosystem carry non-standard '&\u2026&' bodies our escape-aware tokenizer flags. The body is preserved byte-for-byte in the value. NOT always non-clinical, and this is measured rather than assumed: where the body is a delimiter, that delimiter never became a field boundary, so `28.6&|&U/L` reads as one value with no units and no final status. Tolerating this code hides that too."
     }
   ]
 });
@@ -861,7 +935,10 @@ function getDefaultAstmProfile() {
 }
 
 // src/common/escapes.ts
-function decodeEscapes(leaf, d, onUnknown) {
+function isEscapeSequenceAt(text, i, escape) {
+  return text.charAt(i) === escape && text.charAt(i + 2) === escape;
+}
+function decodeEscapes(leaf, d, onUnknown, onUnpaired) {
   const esc = d.escape;
   if (!leaf.includes(esc)) return leaf;
   let out = "";
@@ -873,12 +950,13 @@ function decodeEscapes(leaf, d, onUnknown) {
       i += 1;
       continue;
     }
-    const close = leaf.indexOf(esc, i + 1);
-    if (close === -1) {
-      out += leaf.slice(i);
-      break;
+    if (!isEscapeSequenceAt(leaf, i, esc)) {
+      out += ch;
+      i += 1;
+      onUnpaired?.();
+      continue;
     }
-    const body = leaf.slice(i + 1, close);
+    const body = leaf.charAt(i + 1);
     const replacement = escapeBody(body, d);
     if (replacement === void 0) {
       out += esc + body + esc;
@@ -886,7 +964,7 @@ function decodeEscapes(leaf, d, onUnknown) {
     } else {
       out += replacement;
     }
-    i = close + 1;
+    i += 3;
   }
   return out;
 }
@@ -911,14 +989,9 @@ function splitEscapeAware(text, delimiter, escape) {
   let i = 0;
   while (i < text.length) {
     const ch = text.charAt(i);
-    if (ch === escape) {
-      const close = text.indexOf(escape, i + 1);
-      if (close === -1) {
-        current += text.slice(i);
-        break;
-      }
-      current += text.slice(i, close + 1);
-      i = close + 1;
+    if (ch === escape && isEscapeSequenceAt(text, i, escape)) {
+      current += text.slice(i, i + 3);
+      i += 3;
       continue;
     }
     if (ch === delimiter) {
@@ -935,26 +1008,38 @@ function splitEscapeAware(text, delimiter, escape) {
 }
 
 // src/records/tokenize.ts
-function tokenizeRecord(record, d, onUnknownEscape) {
+function tokenizeRecord(record, d, onUnknownEscape, onUnpairedEscape) {
   const rawFields = splitEscapeAware(record, d.field, d.escape);
-  return rawFields.map((raw, fieldIndex) => toField(raw, d, () => onUnknownEscape?.(fieldIndex)));
+  return rawFields.map(
+    (raw, fieldIndex) => toField(
+      raw,
+      d,
+      () => onUnknownEscape?.(fieldIndex),
+      () => onUnpairedEscape?.(fieldIndex)
+    )
+  );
 }
-function tokenizeHeader(record, d, onUnknownEscape) {
+function tokenizeHeader(record, d, onUnknownEscape, onUnpairedEscape) {
   const defEnd = record.indexOf(d.field, 2);
   const definition = defEnd === -1 ? record.slice(2) : record.slice(2, defEnd);
   const head = [opaqueField(record.slice(0, Math.min(1, record.length))), opaqueField(definition)];
   if (defEnd === -1) return head;
-  const data = tokenizeRecord(record.slice(defEnd + 1), d, (i) => onUnknownEscape?.(i + 2));
+  const data = tokenizeRecord(
+    record.slice(defEnd + 1),
+    d,
+    (i) => onUnknownEscape?.(i + 2),
+    (i) => onUnpairedEscape?.(i + 2)
+  );
   return [...head, ...data];
 }
 function opaqueField(raw) {
   return { raw, components: [raw], repeats: [[raw]] };
 }
-function toField(raw, d, onUnknownEscape) {
+function toField(raw, d, onUnknownEscape, onUnpairedEscape) {
   const rawRepeats = splitEscapeAware(raw, d.repeat, d.escape);
   const repeats = rawRepeats.map(
     (rep) => splitEscapeAware(rep, d.component, d.escape).map(
-      (comp) => decodeEscapes(comp, d, onUnknownEscape)
+      (comp) => decodeEscapes(comp, d, onUnknownEscape, onUnpairedEscape)
     )
   );
   const components = repeats[0] ?? [""];
@@ -1069,7 +1154,15 @@ function buildRecord(line2, recordIndex, d, warnings) {
       unknownEscapeSequence({ recordIndex, recordType: rawType, fieldIndex: fieldIndex + 1 })
     );
   };
-  const fields = rawType === "H" ? tokenizeHeader(line2, d, onUnknownEscape) : tokenizeRecord(line2, d, onUnknownEscape);
+  const onUnpairedEscape = (fieldIndex) => {
+    warnings.push(
+      unpairedEscapeCharacter({ recordIndex, recordType: rawType, fieldIndex: fieldIndex + 1 })
+    );
+  };
+  const fields = rawType === "H" ? tokenizeHeader(line2, d, onUnknownEscape, onUnpairedEscape) : tokenizeRecord(line2, d, onUnknownEscape, onUnpairedEscape);
+  if (fields.length === 1 && line2.slice(1).trim().length > 0) {
+    warnings.push(fieldsUnseparated({ recordIndex, recordType: rawType }));
+  }
   switch (rawType) {
     case "H":
       return {
@@ -2133,18 +2226,37 @@ var AstmFrameEncodeError = class extends Error {
   code;
   /** Index of the offending record within the input, when applicable. */
   recordIndex;
+  /**
+   * Position of the offending character within that record, when applicable:
+   * its index in the string, never the character itself and never its code
+   * point. Enough to find it in the caller's own data.
+   */
+  characterIndex;
   /** @internal */
-  constructor(message, recordIndex) {
+  constructor(message, recordIndex, code = "ASTM_FRAME_EMPTY_RECORD", characterIndex) {
     super(message);
     this.name = "AstmFrameEncodeError";
-    this.code = "ASTM_FRAME_EMPTY_RECORD";
+    this.code = code;
     if (recordIndex !== void 0) this.recordIndex = recordIndex;
+    if (characterIndex !== void 0) this.characterIndex = characterIndex;
   }
 };
-function toBytes(input) {
+var MAX_SINGLE_BYTE_CODE_POINT = 255;
+function toBytes(input, recordIndex) {
   if (typeof input !== "string") return input;
   const out = new Uint8Array(input.length);
-  for (let i = 0; i < input.length; i += 1) out[i] = input.charCodeAt(i) & 255;
+  for (let i = 0; i < input.length; i += 1) {
+    const code = input.charCodeAt(i);
+    if (code > MAX_SINGLE_BYTE_CODE_POINT) {
+      throw new AstmFrameEncodeError(
+        "A record contains a character above U+00FF, which is not a single byte. Encode the record with the character encoding your instrument uses and pass the bytes.",
+        recordIndex,
+        "ASTM_FRAME_UNENCODABLE_CHARACTER",
+        i
+      );
+    }
+    out[i] = code;
+  }
   return out;
 }
 function encodeFrame(text, frameNumber, isFinal) {
@@ -2161,7 +2273,7 @@ function composeAstmFrames(records, options = {}) {
   const out = [];
   let frameNumber = options.startFrameNumber ?? FIRST_FRAME_NUMBER;
   records.forEach((record, recordIndex) => {
-    const bytes = toBytes(record);
+    const bytes = toBytes(record, recordIndex);
     if (bytes.length === 0) {
       throw new AstmFrameEncodeError(
         "Cannot frame an empty record: a frame must carry record bytes.",
@@ -2203,7 +2315,7 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.8";
+var VERSION = "0.0.10";
 
 exports.ALL_ASTM_WARNING_CODES = ALL_ASTM_WARNING_CODES;
 exports.AMBIGUOUS_CODES = AMBIGUOUS_CODES;
@@ -2250,6 +2362,7 @@ exports.delimitersRedeclared = delimitersRedeclared;
 exports.detectFraming = detectFraming;
 exports.encodeComponent = encodeComponent;
 exports.fieldScalar = fieldScalar;
+exports.fieldsUnseparated = fieldsUnseparated;
 exports.frameBadChecksum = frameBadChecksum;
 exports.frameOversize = frameOversize;
 exports.frameSequenceGap = frameSequenceGap;
@@ -2302,6 +2415,7 @@ exports.uninterpretedQueryStatus = uninterpretedQueryStatus;
 exports.unitsAbsent = unitsAbsent;
 exports.unknownEscapeSequence = unknownEscapeSequence;
 exports.unknownRecordType = unknownRecordType;
+exports.unpairedEscapeCharacter = unpairedEscapeCharacter;
 exports.unparseableReferenceRange = unparseableReferenceRange;
 exports.unreadableRedeclaration = unreadableRedeclaration;
 //# sourceMappingURL=index.cjs.map