@push.rocks/smartlinuxrepo 1.1.1 → 1.2.0

package/ts/rpm/xmlreader.ts

@@ -0,0 +1,680 @@
+import { LinuxRepoError, limitExceeded } from '../shared/errors.js';
+import type { ILinuxPackageLimits } from '../shared/limits.js';
+
+/**
+ * A strict, iterative XML 1.0 scanner over the bytes of one repodata document,
+ * the reading side of `xml.ts`. It checks well-formedness and hands the
+ * elements of each unit (a child of the root) to a handler, without building a
+ * tree. Every refusal is `malformed-index` with the byte offset in
+ * `detail.value`:
+ * - the document must be strict UTF-8 holding only XML characters; an
+ *   optional UTF-8 byte order mark and XML declaration may lead it, and a
+ *   declared `encoding` other than UTF-8 (ASCII case-insensitive) is refused;
+ * - `<!DOCTYPE` (or any other `<!` declaration) is refused, so there are no
+ *   entity definitions: only `&lt; &gt; &amp; &apos; &quot;` and numeric
+ *   references to XML characters are accepted;
+ * - tags must match, attribute names must be unique within a tag and be
+ *   separated by whitespace, values are quoted and hold no `<`, text holds no
+ *   `]]>`, comments hold no `--`, a processing instruction's target is not
+ *   `xml` (except the declaration at the start), and there is exactly one root;
+ * - comments, processing instructions and whitespace may sit before and after
+ *   the root; inside it only whitespace may sit between units; inside a unit
+ *   CDATA sections, comments, processing instructions and empty-element tags
+ *   are accepted.
+ *
+ * Names are matched literally with their prefixes (no namespace processing);
+ * a name starts with an ASCII letter, `_`, `:` or a non-ASCII character and
+ * continues with those, digits, `.` and `-` (every non-ASCII character counts
+ * as a name character, a simplification of the XML name production). Values
+ * handed to the handler are decoded: references replaced, line ends
+ * normalized (CRLF and CR to LF), and in attribute values literal tabs and
+ * line ends become spaces (XML 1.0 sections 2.11 and 3.3.3).
+ *
+ * Bounds: one start tag by `maxHeaderBytes`, one unit by `maxMetadataBytes`,
+ * units and open elements at a time by `maxEntries`.
+ */
+
+export interface IXmlAttribute {
+  readonly name: string;
+  readonly value: string;
+}
+
+/** Receives the elements of one unit; `depth` 0 is the unit element itself. */
+export interface IXmlUnitHandler {
+  /** An element starts; returning true captures its direct character data for `end`. */
+  start(depthArg: number, nameArg: string, attributesArg: readonly IXmlAttribute[]): boolean;
+  /** An element ends; `textArg` is its captured character data, or null when not captured. */
+  end(depthArg: number, nameArg: string, textArg: string | null): void;
+}
+
+export interface IXmlScanOptions {
+  /** The required root element name. */
+  rootName: string;
+  /** The unit element name among the root's children. */
+  unitName: string;
+  /** Whether other root children are accepted (repomd); otherwise they are refused. */
+  keepOtherChildren: boolean;
+  limits: Readonly<ILinuxPackageLimits>;
+  /** A handler for the unit starting at `startArg` (the offset of its `<`). */
+  createUnit(startArg: number): IXmlUnitHandler;
+  /** A unit ended: its bytes are `[startArg, endArg)`. */
+  unit(handlerArg: IXmlUnitHandler, startArg: number, endArg: number): void;
+  /** Another root child ended (only with `keepOtherChildren`). */
+  other(nameArg: string, startArg: number, endArg: number): void;
+}
+
+/** Where the root element's tags sit in the document. */
+export interface IXmlFrameScan {
+  rootStart: number;
+  rootStartEnd: number;
+  rootAttributes: IXmlAttribute[];
+  /** The root end tag `[rootEndStart, rootEnd)`; both equal `rootStartEnd` for an empty-element root. */
+  rootEndStart: number;
+  rootEnd: number;
+}
+
+const LT = 0x3c;
+const GT = 0x3e;
+const AMP = 0x26;
+const SLASH = 0x2f;
+const BANG = 0x21;
+const QUESTION = 0x3f;
+const EQUALS = 0x3d;
+const QUOTE = 0x22;
+const APOSTROPHE = 0x27;
+const SEMICOLON = 0x3b;
+const HASH = 0x23;
+const CR = 0x0d;
+const LF = 0x0a;
+const TAB = 0x09;
+const SPACE = 0x20;
+const BRACKET_CLOSE = 0x5d;
+
+const utf8 = new TextDecoder('utf-8');
+const ascii = (textArg: string) => Uint8Array.from(textArg, (characterArg) => characterArg.charCodeAt(0));
+const COMMENT_OPEN = ascii('<!--');
+const CDATA_OPEN = ascii('<![CDATA[');
+const XML_DECLARATION_OPEN = ascii('<?xml');
+const PREDEFINED: ReadonlyMap<string, string> = new Map([
+  ['lt', '<'],
+  ['gt', '>'],
+  ['amp', '&'],
+  ['apos', "'"],
+  ['quot', '"'],
+]);
+
+function isSpace(byteArg: number): boolean {
+  return byteArg === SPACE || byteArg === TAB || byteArg === LF || byteArg === CR;
+}
+
+function isNameStart(byteArg: number): boolean {
+  return (
+    (byteArg >= 0x61 && byteArg <= 0x7a) ||
+    (byteArg >= 0x41 && byteArg <= 0x5a) ||
+    byteArg === 0x5f ||
+    byteArg === 0x3a ||
+    byteArg >= 0x80
+  );
+}
+
+function isNameChar(byteArg: number): boolean {
+  return isNameStart(byteArg) || (byteArg >= 0x30 && byteArg <= 0x39) || byteArg === 0x2e || byteArg === 0x2d;
+}
+
+function isXmlCharacter(codePointArg: number): boolean {
+  return (
+    codePointArg === 0x09 ||
+    codePointArg === 0x0a ||
+    codePointArg === 0x0d ||
+    (codePointArg >= 0x20 && codePointArg <= 0xd7ff) ||
+    (codePointArg >= 0xe000 && codePointArg <= 0xfffd) ||
+    (codePointArg >= 0x10000 && codePointArg <= 0x10ffff)
+  );
+}
+
+interface IStartTag {
+  name: string;
+  nameStart: number;
+  nameEnd: number;
+  attributes: IXmlAttribute[];
+  /** Offset after the tag's `>`. */
+  end: number;
+  selfClosing: boolean;
+}
+
+interface IOpenElement {
+  name: string;
+  nameStart: number;
+  nameEnd: number;
+  text: string[] | null;
+}
+
+/** Scans one document; see the module comment. */
+export function scanXmlDocument(documentArg: Uint8Array, optionsArg: IXmlScanOptions): IXmlFrameScan {
+  return new XmlScanner(documentArg, optionsArg).scan();
+}
+
+class XmlScanner {
+  private readonly doc: Uint8Array;
+  private readonly buffer: Buffer;
+  private readonly limits: Readonly<ILinuxPackageLimits>;
+
+  constructor(
+    documentArg: Uint8Array,
+    private readonly options: IXmlScanOptions,
+  ) {
+    this.doc = documentArg;
+    this.buffer = Buffer.from(documentArg.buffer, documentArg.byteOffset, documentArg.byteLength);
+    this.limits = options.limits;
+  }
+
+  public scan(): IXmlFrameScan {
+    const doc = this.doc;
+    this.checkCharacters();
+    let pos = 0;
+    if (doc[0] === 0xef && doc[1] === 0xbb && doc[2] === 0xbf) {
+      pos = 3;
+    }
+    if (this.startsWith(pos, XML_DECLARATION_OPEN) && (isSpace(doc[pos + 5]) || doc[pos + 5] === QUESTION)) {
+      pos = this.xmlDeclaration(pos);
+    }
+    pos = this.misc(pos);
+    if (pos >= doc.length || doc[pos] !== LT || !isNameStart(doc[pos + 1])) {
+      throw this.malformed('the document has no root element', pos);
+    }
+    const rootStart = pos;
+    const root = this.startTag(pos);
+    if (root.name !== this.options.rootName) {
+      throw this.malformed(`the root element is <${root.name}>, expected <${this.options.rootName}>`, pos);
+    }
+    let rootEndStart = root.end;
+    let rootEnd = root.end;
+    if (!root.selfClosing) {
+      pos = root.end;
+      let units = 0;
+      for (;;) {
+        while (pos < doc.length && isSpace(doc[pos])) {
+          pos += 1;
+        }
+        if (pos >= doc.length) {
+          throw this.malformed(`the <${root.name}> element is not closed`, rootStart);
+        }
+        if (doc[pos] !== LT) {
+          throw this.malformed(`character data between the units of <${root.name}>`, pos);
+        }
+        if (doc[pos + 1] === SLASH) {
+          rootEndStart = pos;
+          rootEnd = this.endTag(pos, { name: root.name, nameStart: root.nameStart, nameEnd: root.nameEnd, text: null });
+          break;
+        }
+        if (!isNameStart(doc[pos + 1])) {
+          throw this.malformed(`markup other than an element between the units of <${root.name}>`, pos);
+        }
+        const tag = this.startTag(pos);
+        units += 1;
+        if (units > this.limits.maxEntries) {
+          throw limitExceeded('maxEntries', this.limits.maxEntries, `<${root.name}> unit count`);
+        }
+        if (tag.name === this.options.unitName) {
+          const handler = this.options.createUnit(pos);
+          const end = this.element(pos, tag, handler);
+          this.options.unit(handler, pos, end);
+          pos = end;
+        } else if (this.options.keepOtherChildren) {
+          const end = this.element(pos, tag, null);
+          this.options.other(tag.name, pos, end);
+          pos = end;
+        } else {
+          throw this.malformed(`<${root.name}> holds a <${tag.name}> element, expected <${this.options.unitName}>`, pos);
+        }
+      }
+    }
+    pos = this.misc(rootEnd);
+    if (pos < doc.length) {
+      throw this.malformed('content after the root element', pos);
+    }
+    return { rootStart, rootStartEnd: root.end, rootAttributes: root.attributes, rootEndStart, rootEnd };
+  }
+
+  /** Strict UTF-8 holding only XML characters (XML 1.0 `Char`). */
+  private checkCharacters(): void {
+    const doc = this.doc;
+    const length = doc.length;
+    let i = 0;
+    while (i < length) {
+      const b0 = doc[i];
+      if (b0 < 0x80) {
+        if (b0 < 0x20 && b0 !== TAB && b0 !== LF && b0 !== CR) {
+          throw this.malformed('the document holds a control character that is not an XML character', i);
+        }
+        i += 1;
+        continue;
+      }
+      let need: number;
+      let codePoint: number;
+      let low = 0x80;
+      let high = 0xbf;
+      if (b0 >= 0xc2 && b0 <= 0xdf) {
+        need = 1;
+        codePoint = b0 & 0x1f;
+      } else if (b0 >= 0xe0 && b0 <= 0xef) {
+        need = 2;
+        codePoint = b0 & 0x0f;
+        if (b0 === 0xe0) {
+          low = 0xa0;
+        } else if (b0 === 0xed) {
+          high = 0x9f;
+        }
+      } else if (b0 >= 0xf0 && b0 <= 0xf4) {
+        need = 3;
+        codePoint = b0 & 0x07;
+        if (b0 === 0xf0) {
+          low = 0x90;
+        } else if (b0 === 0xf4) {
+          high = 0x8f;
+        }
+      } else {
+        throw this.malformed('the document is not valid UTF-8', i);
+      }
+      if (i + need >= length) {
+        throw this.malformed('the document is not valid UTF-8', i);
+      }
+      for (let k = 1; k <= need; k++) {
+        const b = doc[i + k];
+        if (b < (k === 1 ? low : 0x80) || b > (k === 1 ? high : 0xbf)) {
+          throw this.malformed('the document is not valid UTF-8', i);
+        }
+        codePoint = (codePoint << 6) | (b & 0x3f);
+      }
+      if (!isXmlCharacter(codePoint)) {
+        throw this.malformed('the document holds a code point that is not an XML character', i);
+      }
+      i += need + 1;
+    }
+  }
+
+  /** `<?xml version="1.x" [encoding="UTF-8"] [standalone="yes|no"] ?>`; returns the offset after it. */
+  private xmlDeclaration(startArg: number): number {
+    const doc = this.doc;
+    let pos = startArg + XML_DECLARATION_OPEN.length;
+    const pseudo: Array<[string, string]> = [];
+    for (;;) {
+      const before = pos;
+      while (pos < doc.length && isSpace(doc[pos])) {
+        pos += 1;
+      }
+      if (doc[pos] === QUESTION && doc[pos + 1] === GT) {
+        pos += 2;
+        break;
+      }
+      if (pos === before || !isNameStart(doc[pos])) {
+        throw this.malformed('a malformed XML declaration', startArg);
+      }
+      const nameStart = pos;
+      while (pos < doc.length && isNameChar(doc[pos])) {
+        pos += 1;
+      }
+      const name = this.decode(nameStart, pos);
+      pos = this.skipSpace(pos);
+      if (doc[pos] !== EQUALS) {
+        throw this.malformed('a malformed XML declaration', startArg);
+      }
+      pos = this.skipSpace(pos + 1);
+      const quote = doc[pos];
+      if (quote !== QUOTE && quote !== APOSTROPHE) {
+        throw this.malformed('a malformed XML declaration', startArg);
+      }
+      const valueEnd = doc.indexOf(quote, pos + 1);
+      if (valueEnd < 0) {
+        throw this.malformed('a malformed XML declaration', startArg);
+      }
+      pseudo.push([name, this.decode(pos + 1, valueEnd)]);
+      pos = valueEnd + 1;
+      if (pos - startArg > this.limits.maxHeaderBytes) {
+        throw limitExceeded('maxHeaderBytes', this.limits.maxHeaderBytes, 'XML declaration');
+      }
+    }
+    const names = pseudo.map(([name]) => name);
+    const expected = ['version', 'encoding', 'standalone'].filter((name) => names.includes(name));
+    if (names.length === 0 || names[0] !== 'version' || names.join() !== expected.join()) {
+      throw this.malformed('a malformed XML declaration', startArg);
+    }
+    for (const [name, value] of pseudo) {
+      if (name === 'version' && !/^1\.[0-9]+$/.test(value)) {
+        throw this.malformed('a malformed XML declaration version', startArg);
+      }
+      if (name === 'encoding' && value.toLowerCase() !== 'utf-8') {
+        throw this.malformed(`the document declares the encoding ${JSON.stringify(value)}, not UTF-8`, startArg);
+      }
+      if (name === 'standalone' && value !== 'yes' && value !== 'no') {
+        throw this.malformed('a malformed XML declaration standalone value', startArg);
+      }
+    }
+    return pos;
+  }
+
+  /** Whitespace, comments and processing instructions (prolog and trailer); returns the first other offset. */
+  private misc(startArg: number): number {
+    const doc = this.doc;
+    let pos = startArg;
+    for (;;) {
+      while (pos < doc.length && isSpace(doc[pos])) {
+        pos += 1;
+      }
+      if (pos >= doc.length || doc[pos] !== LT) {
+        return pos;
+      }
+      if (doc[pos + 1] === BANG) {
+        if (!this.startsWith(pos, COMMENT_OPEN)) {
+          throw this.malformed('a declaration (<!DOCTYPE or another <!) outside the root element', pos);
+        }
+        pos = this.comment(pos);
+      } else if (doc[pos + 1] === QUESTION) {
+        pos = this.processingInstruction(pos);
+      } else {
+        return pos;
+      }
+    }
+  }
+
+  /** `<!-- ... -->` without `--` inside; returns the offset after it. */
+  private comment(startArg: number): number {
+    const close = this.buffer.indexOf('--', startArg + COMMENT_OPEN.length, 'latin1');
+    if (close < 0) {
+      throw this.malformed('a comment is not closed', startArg);
+    }
+    if (this.doc[close + 2] !== GT) {
+      throw this.malformed('a comment holds "--"', close);
+    }
+    return close + 3;
+  }
+
+  /** `<?target ...?>` with a target other than `xml`; returns the offset after it. */
+  private processingInstruction(startArg: number): number {
+    const doc = this.doc;
+    let pos = startArg + 2;
+    if (!isNameStart(doc[pos])) {
+      throw this.malformed('a processing instruction without a target', startArg);
+    }
+    while (pos < doc.length && isNameChar(doc[pos])) {
+      pos += 1;
+    }
+    if (this.decode(startArg + 2, pos).toLowerCase() === 'xml') {
+      throw this.malformed('an XML declaration that is not at the start of the document', startArg);
+    }
+    if (!(doc[pos] === QUESTION && doc[pos + 1] === GT) && !isSpace(doc[pos])) {
+      throw this.malformed('a malformed processing instruction target', startArg);
+    }
+    const close = this.buffer.indexOf('?>', pos, 'latin1');
+    if (close < 0) {
+      throw this.malformed('a processing instruction is not closed', startArg);
+    }
+    return close + 2;
+  }
+
+  /** `<name attr="value" ...>` or `<name .../>`. */
+  private startTag(startArg: number): IStartTag {
+    const doc = this.doc;
+    const limit = startArg + this.limits.maxHeaderBytes;
+    let pos = startArg + 1;
+    const nameStart = pos;
+    while (pos < doc.length && isNameChar(doc[pos])) {
+      pos += 1;
+    }
+    const nameEnd = pos;
+    if (pos > limit) {
+      throw limitExceeded('maxHeaderBytes', this.limits.maxHeaderBytes, 'start tag');
+    }
+    const name = this.decode(nameStart, nameEnd);
+    const attributes: IXmlAttribute[] = [];
+    const seen = new Set<string>();
+    for (;;) {
+      if (pos > limit) {
+        throw limitExceeded('maxHeaderBytes', this.limits.maxHeaderBytes, `<${name}> start tag`);
+      }
+      const afterName = pos;
+      pos = this.skipSpace(pos);
+      if (pos >= doc.length) {
+        throw this.malformed(`the <${name}> start tag is not closed`, startArg);
+      }
+      if (doc[pos] === GT) {
+        return { name, nameStart, nameEnd, attributes, end: pos + 1, selfClosing: false };
+      }
+      if (doc[pos] === SLASH && doc[pos + 1] === GT) {
+        return { name, nameStart, nameEnd, attributes, end: pos + 2, selfClosing: true };
+      }
+      if (pos === afterName || !isNameStart(doc[pos])) {
+        throw this.malformed(`a malformed <${name}> start tag`, pos);
+      }
+      const attributeStart = pos;
+      while (pos < doc.length && isNameChar(doc[pos])) {
+        pos += 1;
+      }
+      if (pos > limit) {
+        throw limitExceeded('maxHeaderBytes', this.limits.maxHeaderBytes, `<${name}> start tag`);
+      }
+      const attributeName = this.decode(attributeStart, pos);
+      if (seen.has(attributeName)) {
+        throw this.malformed(`the <${name}> start tag repeats the attribute ${attributeName}`, attributeStart);
+      }
+      seen.add(attributeName);
+      pos = this.skipSpace(pos);
+      if (doc[pos] !== EQUALS) {
+        throw this.malformed(`the attribute ${attributeName} has no value`, attributeStart);
+      }
+      pos = this.skipSpace(pos + 1);
+      const quote = doc[pos];
+      if (quote !== QUOTE && quote !== APOSTROPHE) {
+        throw this.malformed(`the attribute ${attributeName} value is not quoted`, pos);
+      }
+      const valueEnd = doc.indexOf(quote, pos + 1);
+      if (valueEnd < 0 || valueEnd > limit) {
+        if (valueEnd > limit) {
+          throw limitExceeded('maxHeaderBytes', this.limits.maxHeaderBytes, `<${name}> start tag`);
+        }
+        throw this.malformed(`the attribute ${attributeName} value is not closed`, pos);
+      }
+      attributes.push({ name: attributeName, value: this.characterData(pos + 1, valueEnd, true, true) as string });
+      pos = valueEnd + 1;
+    }
+  }
+
+  /** `</name S?>` matching `openArg`; returns the offset after it. */
+  private endTag(startArg: number, openArg: IOpenElement): number {
+    const doc = this.doc;
+    let pos = startArg + 2;
+    const nameStart = pos;
+    while (pos < doc.length && isNameChar(doc[pos])) {
+      pos += 1;
+    }
+    const length = openArg.nameEnd - openArg.nameStart;
+    if (pos - nameStart !== length || this.buffer.compare(this.buffer, openArg.nameStart, openArg.nameEnd, nameStart, pos) !== 0) {
+      throw this.malformed(`an end tag does not match <${openArg.name}>`, startArg);
+    }
+    pos = this.skipSpace(pos);
+    if (doc[pos] !== GT) {
+      throw this.malformed(`a malformed </${openArg.name}> end tag`, startArg);
+    }
+    return pos + 1;
+  }
+
+  /** The content of an element through its end tag; returns the offset after the end tag. */
+  private element(startArg: number, tagArg: IStartTag, handlerArg: IXmlUnitHandler | null): number {
+    const doc = this.doc;
+    const maxEnd = startArg + this.limits.maxMetadataBytes;
+    const capture = handlerArg !== null && handlerArg.start(0, tagArg.name, tagArg.attributes);
+    if (tagArg.selfClosing) {
+      handlerArg?.end(0, tagArg.name, capture ? '' : null);
+      return tagArg.end;
+    }
+    const stack: IOpenElement[] = [{ name: tagArg.name, nameStart: tagArg.nameStart, nameEnd: tagArg.nameEnd, text: capture ? [] : null }];
+    let pos = tagArg.end;
+    while (stack.length > 0) {
+      if (pos > maxEnd) {
+        throw limitExceeded('maxMetadataBytes', this.limits.maxMetadataBytes, `<${tagArg.name}> element`);
+      }
+      if (pos >= doc.length) {
+        throw this.malformed(`the <${stack[stack.length - 1].name}> element is not closed`, startArg);
+      }
+      const top = stack[stack.length - 1];
+      if (doc[pos] !== LT) {
+        let textEnd = doc.indexOf(LT, pos);
+        if (textEnd < 0) {
+          textEnd = doc.length;
+        }
+        const text = this.characterData(pos, textEnd, top.text !== null, false);
+        if (text !== null) {
+          top.text!.push(text);
+        }
+        pos = textEnd;
+        continue;
+      }
+      const next = doc[pos + 1];
+      if (next === SLASH) {
+        const end = this.endTag(pos, top);
+        stack.pop();
+        handlerArg?.end(stack.length, top.name, top.text === null ? null : top.text.join(''));
+        pos = end;
+      } else if (next === BANG) {
+        if (this.startsWith(pos, COMMENT_OPEN)) {
+          pos = this.comment(pos);
+        } else if (this.startsWith(pos, CDATA_OPEN)) {
+          const close = this.buffer.indexOf(']]>', pos + CDATA_OPEN.length, 'latin1');
+          if (close < 0) {
+            throw this.malformed('a CDATA section is not closed', pos);
+          }
+          if (top.text !== null) {
+            top.text.push(normalizeLineEnds(this.decode(pos + CDATA_OPEN.length, close)));
+          }
+          pos = close + 3;
+        } else {
+          throw this.malformed('a declaration inside an element', pos);
+        }
+      } else if (next === QUESTION) {
+        pos = this.processingInstruction(pos);
+      } else if (isNameStart(next)) {
+        // the root, the unit's open elements and the new one
+        if (stack.length + 2 > this.limits.maxEntries) {
+          throw limitExceeded('maxEntries', this.limits.maxEntries, 'open XML elements');
+        }
+        const tag = this.startTag(pos);
+        const depth = stack.length;
+        const captureChild = handlerArg !== null && handlerArg.start(depth, tag.name, tag.attributes);
+        if (tag.selfClosing) {
+          handlerArg?.end(depth, tag.name, captureChild ? '' : null);
+        } else {
+          stack.push({ name: tag.name, nameStart: tag.nameStart, nameEnd: tag.nameEnd, text: captureChild ? [] : null });
+        }
+        pos = tag.end;
+      } else {
+        throw this.malformed('a "<" that starts no markup', pos);
+      }
+    }
+    if (pos > maxEnd) {
+      throw limitExceeded('maxMetadataBytes', this.limits.maxMetadataBytes, `<${tagArg.name}> element`);
+    }
+    return pos;
+  }
+
+  /**
+   * Checks character data or an attribute value in `[startArg, endArg)` (no
+   * `]]>` in text, no `<` in values, only the accepted references) and, when
+   * `decodeArg`, returns its decoded value; otherwise null.
+   */
+  private characterData(startArg: number, endArg: number, decodeArg: boolean, attributeArg: boolean): string | null {
+    const doc = this.doc;
+    const parts: string[] = [];
+    let runStart = startArg;
+    for (let i = startArg; i < endArg; i++) {
+      const b = doc[i];
+      if (b === LT) {
+        throw this.malformed('an attribute value holds "<"', i);
+      }
+      if (b === GT && !attributeArg && i - 2 >= startArg && doc[i - 1] === BRACKET_CLOSE && doc[i - 2] === BRACKET_CLOSE) {
+        throw this.malformed('character data holds "]]>"', i - 2);
+      }
+      if (b !== AMP) {
+        continue;
+      }
+      const semicolon = doc.indexOf(SEMICOLON, i + 1);
+      if (semicolon < 0 || semicolon >= endArg || semicolon - i > 12) {
+        throw this.malformed('a reference is not terminated', i);
+      }
+      const replacement = this.reference(i, semicolon);
+      if (decodeArg) {
+        parts.push(this.literal(runStart, i, attributeArg), replacement);
+      }
+      i = semicolon;
+      runStart = semicolon + 1;
+    }
+    if (!decodeArg) {
+      return null;
+    }
+    parts.push(this.literal(runStart, endArg, attributeArg));
+    return parts.join('');
+  }
+
+  /** The literal run `[startArg, endArg)`: line ends normalized, and in attribute values whitespace to spaces. */
+  private literal(startArg: number, endArg: number, attributeArg: boolean): string {
+    if (startArg === endArg) {
+      return '';
+    }
+    const text = normalizeLineEnds(this.decode(startArg, endArg));
+    return attributeArg ? text.replace(/[\t\n]/g, ' ') : text;
+  }
+
+  /** The character a reference `&...;` stands for. */
+  private reference(startArg: number, semicolonArg: number): string {
+    const doc = this.doc;
+    if (doc[startArg + 1] === HASH) {
+      const hex = doc[startArg + 2] === 0x78;
+      const digits = this.decode(startArg + (hex ? 3 : 2), semicolonArg);
+      if (!(hex ? /^[0-9a-fA-F]+$/ : /^[0-9]+$/).test(digits)) {
+        throw this.malformed('a malformed character reference', startArg);
+      }
+      const codePoint = Number.parseInt(digits, hex ? 16 : 10);
+      if (!isXmlCharacter(codePoint)) {
+        throw this.malformed('a character reference to a character XML does not allow', startArg);
+      }
+      return String.fromCodePoint(codePoint);
+    }
+    const replacement = PREDEFINED.get(this.decode(startArg + 1, semicolonArg));
+    if (replacement === undefined) {
+      throw this.malformed('a reference to an undeclared entity', startArg);
+    }
+    return replacement;
+  }
+
+  private skipSpace(posArg: number): number {
+    let pos = posArg;
+    while (pos < this.doc.length && isSpace(this.doc[pos])) {
+      pos += 1;
+    }
+    return pos;
+  }
+
+  private startsWith(posArg: number, bytesArg: Uint8Array): boolean {
+    if (posArg + bytesArg.length > this.doc.length) {
+      return false;
+    }
+    for (let i = 0; i < bytesArg.length; i++) {
+      if (this.doc[posArg + i] !== bytesArg[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  private decode(startArg: number, endArg: number): string {
+    return utf8.decode(this.doc.subarray(startArg, endArg));
+  }
+
+  private malformed(messageArg: string, offsetArg: number): LinuxRepoError {
+    return new LinuxRepoError('malformed-index', messageArg, { field: `<${this.options.rootName}> document`, value: offsetArg });
+  }
+}
+
+/** XML 1.0 section 2.11: CRLF and lone CR become LF. */
+function normalizeLineEnds(textArg: string): string {
+  return textArg.includes('\r') ? textArg.replace(/\r\n?/g, '\n') : textArg;
+}