docxmlater 11.0.10 → 12.0.1

package/src/xml/XMLBuilder.ts

@@ -162,9 +162,12 @@ export class XMLBuilder {
     // Add attributes
     if (element.attributes) {
       for (const [key, value] of Object.entries(element.attributes)) {
-        if (value !== undefined && value !== null && value !== false) {
-          // Handle boolean attributes
-          const attrValue = value === true ? key : String(value);
+        if (value !== undefined && value !== null) {
+          // Booleans serialize as ST_OnOff literals (ECMA-376 §22.9.2.13).
+          // Explicit false must emit "0" — dropping it would flip an explicit
+          // override to inherited/on under CT_OnOff presence semantics.
+          // Callers signal absence with undefined, never false.
+          const attrValue = value === true ? '1' : value === false ? '0' : String(value);
           // Use escapeXmlAttribute for attribute values (Issue #8)
           xml += ` ${key}="${XMLBuilder.escapeXmlAttribute(attrValue)}"`;
         }
@@ -245,18 +248,47 @@ export class XMLBuilder {
       .replace(/'/g, ''');
   }
 
+  /** The five predefined XML 1.0 named entities */
+  private static readonly NAMED_ENTITIES: Record<string, string> = {
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    amp: '&',
+  };
+
   /**
    * Unescapes XML entities back to original characters
+   * Decodes the five predefined named entities plus numeric character
+   * references (&#8217; / &#xA0;), which XML 1.0 §4.1 requires every
+   * conforming processor to expand — third-party producers emit them, and
+   * leaving them raw double-escapes the ampersand on save.
    * @param text Text with XML entities
    * @returns Unescaped text
    */
   static unescapeXml(text: string): string {
-    return text
-      .replace(/&lt;/g, '<')
-      .replace(/&gt;/g, '>')
-      .replace(/&quot;/g, '"')
-      .replace(/&apos;/g, "'")
-      .replace(/&amp;/g, '&'); // Must be last to avoid double-unescaping
+    // Single pass so text produced by one decode is never re-decoded by a
+    // later one (e.g. '&#38;amp;' must yield '&amp;', not '&').
+    return text.replace(
+      /&(?:(lt|gt|quot|apos|amp)|#x([0-9A-Fa-f]+)|#(\d+));/g,
+      (match, named?: string, hex?: string, dec?: string) => {
+        if (named !== undefined) {
+          return XMLBuilder.NAMED_ENTITIES[named] ?? match;
+        }
+        const code = hex !== undefined ? parseInt(hex, 16) : Number(dec);
+        // Code points outside the XML 1.0 Char production (NUL, surrogates,
+        // beyond U+10FFFF) would make the decoded string unserializable —
+        // keep the raw reference instead of injecting an invalid character.
+        const isXmlChar =
+          code === 0x9 ||
+          code === 0xa ||
+          code === 0xd ||
+          (code >= 0x20 && code <= 0xd7ff) ||
+          (code >= 0xe000 && code <= 0xfffd) ||
+          (code >= 0x10000 && code <= 0x10ffff);
+        return isXmlChar ? String.fromCodePoint(code) : match;
+      }
+    );
   }
 
   /**
@@ -633,11 +665,7 @@ export class XMLBuilder {
     const builder = new XMLBuilder();
     const element = XMLBuilder.objectToElement(obj, rootName);
     if (element) {
-      if (typeof element === 'string') {
-        builder.text(element);
-      } else {
-        builder.elements.push(element);
-      }
+      builder.elements.push(element);
     }
     return builder.build();
   }
@@ -649,22 +677,21 @@ export class XMLBuilder {
   private static objectToElement(
     obj: ParsedXmlObject | string | number | boolean | null | undefined,
     name: string
-  ): XMLElement | string | null {
+  ): XMLElement | null {
     if (obj === null || obj === undefined) {
       return null;
     }
 
-    if (typeof obj !== 'object' || obj === null) {
-      return String(obj);
+    if (typeof obj !== 'object') {
+      // The parser collapses text-only elements to their primitive value, so
+      // the wrapping tag must be re-emitted here — bare text inside container
+      // elements (e.g. w:r) is invalid WordprocessingML.
+      return { name, children: [String(obj)] };
     }
 
     const attributes: Record<string, string | number | boolean> = {};
     const children: (XMLElement | string)[] = [];
 
-    if (obj['#text'] && Object.keys(obj).length === 1) {
-      return String(obj['#text']);
-    }
-
     for (const key in obj) {
       if (key.startsWith('@_')) {
         const attrName = key.substring(2);
@@ -674,7 +701,40 @@ export class XMLBuilder {
         }
       } else if (key === '#text') {
         children.push(String(obj[key]));
-      } else {
+      }
+    }
+
+    // _orderedChildren is parser metadata, never document content. When
+    // present, it restores the original interleaving of same-named siblings
+    // (e.g. w:t / w:tab / w:t in a run) that the keyed object form loses.
+    const orderedChildren = obj['_orderedChildren'] as
+      | { type: string; index: number }[]
+      | undefined;
+
+    if (orderedChildren && orderedChildren.length > 0) {
+      for (const childInfo of orderedChildren) {
+        const childValue = obj[childInfo.type];
+        if (childValue === undefined) {
+          continue;
+        }
+        const item = Array.isArray(childValue)
+          ? childValue[childInfo.index]
+          : childInfo.index === 0
+            ? childValue
+            : undefined;
+        if (item === undefined) {
+          continue;
+        }
+        const childElement = XMLBuilder.objectToElement(item, childInfo.type);
+        if (childElement) {
+          children.push(childElement);
+        }
+      }
+    } else {
+      for (const key in obj) {
+        if (key.startsWith('@_') || key === '#text' || key === '_orderedChildren') {
+          continue;
+        }
         const childObj = obj[key];
         if (Array.isArray(childObj)) {
           childObj.forEach((item) => {

package/src/xml/XMLParser.ts

@@ -139,8 +139,9 @@ export class XMLParser {
         continue;
       }
 
-      // Find the end of opening tag
-      const openEnd = xml.indexOf('>', startIdx);
+      // Find the end of opening tag (quote-aware: attribute values may
+      // legally contain a raw '>')
+      const openEnd = XMLParser.findTagEnd(xml, startIdx);
       if (openEnd === -1) break;
 
       // Check if self-closing
@@ -333,8 +334,9 @@ export class XMLParser {
     const startIdx = xml.indexOf(startTag);
     if (startIdx === -1) return undefined;
 
-    // Find the end of the opening tag
-    const openEnd = xml.indexOf('>', startIdx);
+    // Find the end of the opening tag (quote-aware: attribute values may
+    // legally contain a raw '>')
+    const openEnd = XMLParser.findTagEnd(xml, startIdx);
     if (openEnd === -1) return undefined;
 
     // Find the closing tag
@@ -344,6 +346,28 @@ export class XMLParser {
     return xml.substring(openEnd + 1, endIdx);
   }
 
+  /**
+   * Finds the first '>' at or after startPos that is not inside a quoted
+   * attribute value. XML 1.0 §2.3 permits a raw '>' inside attribute values
+   * (only '<', '&', and the delimiting quote must be escaped), so a bare
+   * indexOf('>') can end a tag header mid-attribute.
+   * @private
+   */
+  private static findTagEnd(xml: string, startPos: number): number {
+    let quote: string | undefined;
+    for (let pos = startPos; pos < xml.length; pos++) {
+      const ch = xml[pos];
+      if (quote) {
+        if (ch === quote) quote = undefined;
+      } else if (ch === '"' || ch === "'") {
+        quote = ch;
+      } else if (ch === '>') {
+        return pos;
+      }
+    }
+    return -1;
+  }
+
   /**
    * Extracts a complete self-closing tag with its attributes
    * Handles cases where multiple similar tags exist (e.g., <w:sz.../> and <w:szCs.../>)
@@ -371,19 +395,17 @@ export class XMLParser {
 
       // Valid separators after tag name: space, '/', or '>'
       if (charAfterTag === ' ' || charAfterTag === '/' || charAfterTag === '>') {
-        // Found the exact tag, now find its end
-        const endIdx = xml.indexOf('/>', startIdx);
-        if (endIdx === -1) {
-          // Try finding a closing tag instead (non-self-closing)
-          const closeTagStart = xml.indexOf('>', startIdx);
-          if (closeTagStart === -1) return undefined;
-
-          // Return attributes portion
-          return xml.substring(startIdx + startPattern.length, closeTagStart);
-        }
-
-        // Return attributes portion (between tag name and />)
-        return xml.substring(startIdx + startPattern.length, endIdx);
+        // Found the exact tag. Bound the search to this element's own tag
+        // header: a global indexOf('/>') can land inside a later sibling
+        // when the target is written in expanded form (<tag ...></tag>),
+        // attributing the sibling's attributes to this tag.
+        const tagEnd = XMLParser.findTagEnd(xml, startIdx + startPattern.length);
+        if (tagEnd === -1) return undefined;
+
+        // Self-closing: exclude the trailing '/'; expanded form: attributes
+        // run up to the '>' of the open tag.
+        const attrEnd = xml[tagEnd - 1] === '/' ? tagEnd - 1 : tagEnd;
+        return xml.substring(startIdx + startPattern.length, attrEnd);
       }
 
       // Not the exact tag (e.g., found "w:sz" when looking for "w:s")
@@ -477,6 +499,27 @@ export class XMLParser {
       return { value: {}, endPos: xml.length };
     }
 
+    // Skip processing instructions (e.g. <?mso-application ...?>); without
+    // this, '?' fails the element-name match and the PI body is mangled
+    // into text one character at a time
+    if (xml.substring(openTagStart, openTagStart + 2) === '<?') {
+      const piEnd = xml.indexOf('?>', openTagStart + 2);
+      if (piEnd !== -1) {
+        return XMLParser.parseElementToObject(xml, piEnd + 2, options, depth);
+      }
+      return { value: {}, endPos: xml.length };
+    }
+
+    // Skip CDATA found where an element is expected (e.g. at the root);
+    // CDATA inside element content is preserved by the content loop below
+    if (xml.substring(openTagStart, openTagStart + 9) === '<![CDATA[') {
+      const cdataEnd = xml.indexOf(']]>', openTagStart + 9);
+      if (cdataEnd !== -1) {
+        return XMLParser.parseElementToObject(xml, cdataEnd + 3, options, depth);
+      }
+      return { value: {}, endPos: xml.length };
+    }
+
     // Extract element name
     const nameMatch = /^([a-zA-Z0-9:_-]+)/.exec(xml.substring(openTagStart + 1));
     if (!nameMatch) {
@@ -485,7 +528,8 @@ export class XMLParser {
 
     const originalElementName: string = nameMatch[1] || '';
     let elementName: string = originalElementName;
-    const tagHeaderEnd = xml.indexOf('>', openTagStart);
+    // Quote-aware scan: attribute values may legally contain a raw '>'
+    const tagHeaderEnd = XMLParser.findTagEnd(xml, openTagStart);
     if (tagHeaderEnd === -1) {
       return { value: {}, endPos: xml.length };
     }
@@ -558,6 +602,19 @@ export class XMLParser {
         }
       }
 
+      // CDATA: append the payload verbatim — its content is by definition
+      // already unescaped, so entity decoding must not be applied
+      if (content.startsWith('<![CDATA[', nextTag)) {
+        const cdataEnd = content.indexOf(']]>', nextTag + 9);
+        if (cdataEnd === -1) {
+          textContent += content.substring(nextTag + 9);
+          break;
+        }
+        textContent += content.substring(nextTag + 9, cdataEnd);
+        pos = cdataEnd + 3;
+        continue;
+      }
+
       // Parse child element (increment depth for children)
       const childResult = XMLParser.parseElementToObject(content, nextTag, options, depth + 1);
       const childObj = childResult.value as ParsedXMLObject;
@@ -602,6 +659,11 @@ export class XMLParser {
     // Add children
     if (children.length > 0) {
       const coalescedChildren = XMLParser.coalesceChildren(children, options);
+      // Mixed content with no attributes leaves elementValue as a bare
+      // string; fold it into object form so merging children keeps the text
+      if (typeof elementValue === 'string') {
+        elementValue = { [options.textNodeName]: elementValue };
+      }
       if (typeof elementValue === 'object' && !Array.isArray(elementValue)) {
         elementValue = { ...elementValue, ...coalescedChildren };
       } else {
@@ -705,10 +767,15 @@ export class XMLParser {
       // Add prefix to attribute name
       const prefixedName = options.attributeNamePrefix + attrName;
 
+      // Unescape XML entities so stored attribute values are the actual
+      // decoded strings, matching text-node handling and extractAttribute.
+      // This prevents double-escaping when the value is later re-serialized.
+      const decodedValue = XMLBuilder.unescapeXml(attrValue);
+
       // Parse attribute value
       attributes[prefixedName] = options.parseAttributeValue
-        ? XMLParser.parseValue(attrValue)
-        : attrValue;
+        ? XMLParser.parseValue(decodedValue)
+        : decodedValue;
     }
 
     return attributes;

package/src/zip/ZipHandler.ts

@@ -14,7 +14,9 @@ import {
   SizeLimitOptions,
   DEFAULT_SIZE_LIMITS,
 } from './types.js';
+import { ResourceLimitError } from './errors.js';
 import { getGlobalLogger, createScopedLogger, ILogger } from '../utils/logger.js';
+import { normalizePath } from '../utils/validation.js';
 
 // Create scoped logger for ZipHandler operations
 function getLogger(): ILogger {
@@ -41,16 +43,19 @@ export class ZipHandler {
    * Validates document size against configured limits
    * @param sizeMB - Size in megabytes
    * @param limits - Size limit options (merged with defaults)
-   * @throws Error if size exceeds maximum
+   * @throws {ResourceLimitError} If the compressed size exceeds maxSizeMB
    */
   private validateDocumentSize(sizeMB: number, limits: Required<SizeLimitOptions>): void {
     const logger = getLogger();
     const { warningSizeMB, maxSizeMB } = limits;
 
-    // Check maximum size (if enabled)
+    // Check maximum size (if enabled). Throw the typed ResourceLimitError so this
+    // compressed-size guard is catchable by the same type as the uncompressed/ratio/
+    // entry-count guards enforced downstream in ZipReader — callers can distinguish a
+    // hostile/oversized payload from a genuinely corrupt archive.
     if (maxSizeMB > 0 && sizeMB > maxSizeMB) {
       logger.error('Document exceeds maximum size', { sizeMB: sizeMB.toFixed(1), maxSizeMB });
-      throw new Error(
+      throw new ResourceLimitError(
         `Document size (${sizeMB.toFixed(1)}MB) exceeds maximum supported size (${maxSizeMB}MB). ` +
           `This would likely cause out-of-memory errors. Consider:\n` +
           `- Compressing/optimizing images\n` +
@@ -98,15 +103,26 @@ export class ZipHandler {
     const limits = this.getSizeLimits(options);
     this.validateDocumentSize(sizeMB, limits);
 
-    await this.reader.loadFromFile(filePath, options);
-
-    // Copy all files from reader to writer for modification
-    const files = this.reader.getAllFiles();
-    this.writer.clear();
-    this.writer.addFiles(files);
-
-    this.mode = 'modify';
-    logger.info('DOCX file loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    try {
+      await this.reader.loadFromFile(filePath, options);
+
+      // Copy all files from reader to writer for modification
+      const files = this.reader.getAllFiles();
+      this.writer.clear();
+      this.writer.addFiles(files);
+
+      this.mode = 'modify';
+      logger.info('DOCX file loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    } catch (error) {
+      // A failed reload must not leave the handler serving the previously loaded
+      // archive. Reset to a deterministically empty state so getFile/save/etc.
+      // cannot silently return stale content. A fresh reader discards any
+      // partially-extracted files and the stale `loaded` flag.
+      this.writer.clear();
+      this.reader = new ZipReader();
+      this.mode = 'write';
+      throw error;
+    }
   }
 
   /**
@@ -125,15 +141,26 @@ export class ZipHandler {
     const limits = this.getSizeLimits(options);
     this.validateDocumentSize(sizeMB, limits);
 
-    await this.reader.loadFromBuffer(buffer, options);
-
-    // Copy all files from reader to writer for modification
-    const files = this.reader.getAllFiles();
-    this.writer.clear();
-    this.writer.addFiles(files);
-
-    this.mode = 'modify';
-    logger.info('DOCX buffer loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    try {
+      await this.reader.loadFromBuffer(buffer, options);
+
+      // Copy all files from reader to writer for modification
+      const files = this.reader.getAllFiles();
+      this.writer.clear();
+      this.writer.addFiles(files);
+
+      this.mode = 'modify';
+      logger.info('DOCX buffer loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    } catch (error) {
+      // A failed reload must not leave the handler serving the previously loaded
+      // archive. Reset to a deterministically empty state so getFile/save/etc.
+      // cannot silently return stale content. A fresh reader discards any
+      // partially-extracted files and the stale `loaded` flag.
+      this.writer.clear();
+      this.reader = new ZipReader();
+      this.mode = 'write';
+      throw error;
+    }
   }
 
   // ==================== FILE OPERATIONS ====================
@@ -300,6 +327,13 @@ export class ZipHandler {
     if (!file) {
       return false;
     }
+    // Guard against degenerate rename where source and destination collapse to
+    // the same archive key (identical strings or backslash/forward-slash variants).
+    // Without this, addFile would overwrite the single entry and the subsequent
+    // removeFile would delete it, silently destroying the file.
+    if (normalizePath(oldPath) === normalizePath(newPath)) {
+      return true;
+    }
     this.addFile(newPath, file.content, {
       binary: file.isBinary,
       date: file.date,
@@ -336,6 +370,12 @@ export class ZipHandler {
     if (!this.copyFile(srcPath, destPath)) {
       return false;
     }
+    // Guard against degenerate move where source and destination collapse to the
+    // same archive key. copyFile already re-added the (identical) entry, so the
+    // removeFile below would delete it, silently destroying the file.
+    if (normalizePath(srcPath) === normalizePath(destPath)) {
+      return true;
+    }
     this.removeFile(srcPath);
     return true;
   }