docxmlater 11.0.10 → 12.1.0

package/src/validation/RevisionAutoFixer.ts

@@ -17,7 +17,11 @@ import {
   FixAction,
   ValidationIssue,
 } from './ValidationRules.js';
-import { RevisionValidator } from './RevisionValidator.js';
+import {
+  CONTENTLESS_REVISION_TYPES,
+  RevisionValidator,
+  revisionHasContent,
+} from './RevisionValidator.js';
 
 /**
  * Automatically fixes revision validation issues.
@@ -81,9 +85,16 @@ export class RevisionAutoFixer {
         actions.push(...this.fixMissingAuthors(revisions, defaultAuthor, options?.dryRun));
       }
 
-      // Fix orphaned move markers (REV003, REV004)
+      // Fix orphaned move markers (REV003, REV004) — one pairing pass
+      // produces both rules, so gate each side individually to honor
+      // onlyRules/skipRules without mutating revisions the caller excluded.
       if (shouldProcess('REV003') || shouldProcess('REV004')) {
-        actions.push(...this.fixOrphanedMoveMarkers(revisionManager, revisions, options?.dryRun));
+        actions.push(
+          ...this.fixOrphanedMoveMarkers(revisionManager, revisions, options?.dryRun, doc, {
+            moveFrom: shouldProcess('REV003'),
+            moveTo: shouldProcess('REV004'),
+          })
+        );
       }
 
       // Fix missing dates (REV101)
@@ -98,7 +109,7 @@ export class RevisionAutoFixer {
 
       // Fix empty revisions (REV103)
       if (shouldProcess('REV103')) {
-        actions.push(...this.fixEmptyRevisions(revisionManager, revisions, options?.dryRun));
+        actions.push(...this.fixEmptyRevisions(revisionManager, revisions, options?.dryRun, doc));
       }
 
       // Fix non-sequential IDs (REV104)
@@ -297,20 +308,51 @@ export class RevisionAutoFixer {
     return actions;
   }
 
+  /**
+   * Removes a revision from the paragraph content that owns it.
+   *
+   * RevisionManager.removeById() only deregisters the revision from the
+   * manager registry, but serialization reads Paragraph.content directly —
+   * without this step the removed markup would still be written on save.
+   *
+   * @param doc - Document whose paragraphs are searched
+   * @param revision - Revision instance to remove
+   * @returns True if the revision was found and removed from a paragraph
+   */
+  private static removeRevisionFromContent(doc: Document, revision: Revision): boolean {
+    for (const paragraph of doc.getAllParagraphs()) {
+      // replaceContent matches by identity and splices without tracking side effects
+      if (paragraph.replaceContent(revision, [])) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   /**
    * Fix orphaned move markers by removing them.
    *
    * @param revisionManager - RevisionManager instance
    * @param revisions - Array of revisions
    * @param dryRun - If true, only report changes without applying
+   * @param doc - Document to remove the revision content from; without it
+   *   only the manager registry is pruned and saved XML keeps the markup
+   * @param ruleFilter - Which sides of the pairing to fix; REV003 (moveFrom)
+   *   and REV004 (moveTo) are separate rules, so callers honoring
+   *   onlyRules/skipRules must be able to fix one without the other.
+   *   Defaults to both.
    * @returns Array of fix actions
    */
   static fixOrphanedMoveMarkers(
     revisionManager: { removeById(id: number): boolean },
     revisions: Revision[],
-    dryRun?: boolean
+    dryRun?: boolean,
+    doc?: Document,
+    ruleFilter?: { moveFrom?: boolean; moveTo?: boolean }
   ): FixAction[] {
     const actions: FixAction[] = [];
+    const fixMoveFrom = ruleFilter?.moveFrom ?? true;
+    const fixMoveTo = ruleFilter?.moveTo ?? true;
 
     const moveFromIds = new Map<string, Revision>();
     const moveToIds = new Map<string, Revision>();
@@ -326,52 +368,62 @@ export class RevisionAutoFixer {
       }
     }
 
-    // Remove orphaned moveFrom
-    for (const [moveId, rev] of moveFromIds) {
-      if (!moveToIds.has(moveId)) {
-        const issue: ValidationIssue = {
-          code: REVISION_RULES.ORPHANED_MOVE_FROM.code,
-          severity: 'error',
-          message: `Orphaned moveFrom with moveId="${moveId}"`,
-          location: { revisionId: rev.getId() },
-          autoFixable: true,
-        };
-
-        actions.push({
-          issue,
-          action: `Removed orphaned moveFrom (ID: ${rev.getId()}, moveId: ${moveId})`,
-          before: { type: 'moveFrom', moveId },
-          after: null,
-          success: true,
-        });
-
-        if (!dryRun) {
-          revisionManager.removeById(rev.getId());
+    // Remove orphaned moveFrom (REV003)
+    if (fixMoveFrom) {
+      for (const [moveId, rev] of moveFromIds) {
+        if (!moveToIds.has(moveId)) {
+          const issue: ValidationIssue = {
+            code: REVISION_RULES.ORPHANED_MOVE_FROM.code,
+            severity: 'error',
+            message: `Orphaned moveFrom with moveId="${moveId}"`,
+            location: { revisionId: rev.getId() },
+            autoFixable: true,
+          };
+
+          actions.push({
+            issue,
+            action: `Removed orphaned moveFrom (ID: ${rev.getId()}, moveId: ${moveId})`,
+            before: { type: 'moveFrom', moveId },
+            after: null,
+            success: true,
+          });
+
+          if (!dryRun) {
+            revisionManager.removeById(rev.getId());
+            if (doc) {
+              this.removeRevisionFromContent(doc, rev);
+            }
+          }
         }
       }
     }
 
-    // Remove orphaned moveTo
-    for (const [moveId, rev] of moveToIds) {
-      if (!moveFromIds.has(moveId)) {
-        const issue: ValidationIssue = {
-          code: REVISION_RULES.ORPHANED_MOVE_TO.code,
-          severity: 'error',
-          message: `Orphaned moveTo with moveId="${moveId}"`,
-          location: { revisionId: rev.getId() },
-          autoFixable: true,
-        };
-
-        actions.push({
-          issue,
-          action: `Removed orphaned moveTo (ID: ${rev.getId()}, moveId: ${moveId})`,
-          before: { type: 'moveTo', moveId },
-          after: null,
-          success: true,
-        });
-
-        if (!dryRun) {
-          revisionManager.removeById(rev.getId());
+    // Remove orphaned moveTo (REV004)
+    if (fixMoveTo) {
+      for (const [moveId, rev] of moveToIds) {
+        if (!moveFromIds.has(moveId)) {
+          const issue: ValidationIssue = {
+            code: REVISION_RULES.ORPHANED_MOVE_TO.code,
+            severity: 'error',
+            message: `Orphaned moveTo with moveId="${moveId}"`,
+            location: { revisionId: rev.getId() },
+            autoFixable: true,
+          };
+
+          actions.push({
+            issue,
+            action: `Removed orphaned moveTo (ID: ${rev.getId()}, moveId: ${moveId})`,
+            before: { type: 'moveTo', moveId },
+            after: null,
+            success: true,
+          });
+
+          if (!dryRun) {
+            revisionManager.removeById(rev.getId());
+            if (doc) {
+              this.removeRevisionFromContent(doc, rev);
+            }
+          }
         }
       }
     }
@@ -385,38 +437,27 @@ export class RevisionAutoFixer {
    * @param revisionManager - RevisionManager instance
    * @param revisions - Array of revisions
    * @param dryRun - If true, only report changes without applying
+   * @param doc - Document to remove the revision content from; without it
+   *   only the manager registry is pruned and saved XML keeps the markup
    * @returns Array of fix actions
    */
   static fixEmptyRevisions(
     revisionManager: RevisionManager,
     revisions: Revision[],
-    dryRun?: boolean
+    dryRun?: boolean,
+    doc?: Document
   ): FixAction[] {
     const actions: FixAction[] = [];
 
-    const propertyChangeTypes = [
-      'runPropertiesChange',
-      'paragraphPropertiesChange',
-      'tablePropertiesChange',
-      'tableExceptionPropertiesChange',
-      'tableRowPropertiesChange',
-      'tableCellPropertiesChange',
-      'sectionPropertiesChange',
-      'numberingChange',
-    ];
-
     for (const rev of revisions) {
       const type = rev.getType();
 
-      // Skip property changes
-      if (propertyChangeTypes.includes(type)) {
+      // Property changes and cell markers are contentless by design
+      if (CONTENTLESS_REVISION_TYPES.has(type)) {
         continue;
       }
 
-      const runs = rev.getRuns();
-      const hasContent = runs.length > 0 && runs.some((r) => r.getText().length > 0);
-
-      if (!hasContent) {
+      if (!revisionHasContent(rev)) {
         const issue: ValidationIssue = {
           code: REVISION_RULES.EMPTY_REVISION.code,
           severity: 'warning',
@@ -435,6 +476,9 @@ export class RevisionAutoFixer {
 
         if (!dryRun) {
           revisionManager.removeById(rev.getId());
+          if (doc) {
+            this.removeRevisionFromContent(doc, rev);
+          }
         }
       }
     }

package/src/validation/RevisionValidator.ts

@@ -9,6 +9,7 @@
 
 import type { Document } from '../core/Document.js';
 import type { Revision } from '../elements/Revision.js';
+import { isHyperlinkContent, isImageRunContent } from '../elements/RevisionContent.js';
 import {
   REVISION_RULES,
   ValidationIssue,
@@ -18,6 +19,44 @@ import {
 } from './ValidationRules.js';
 import { ValidationRuleRegistry } from './ValidationRuleRegistry.js';
 
+/**
+ * Revision types that are structurally contentless per ECMA-376: property
+ * change markers carry before/after property snapshots rather than runs, and
+ * table cell markers (w:cellIns/w:cellDel/w:cellMerge) annotate the cell
+ * itself. The REV103 empty-content rule must never flag these.
+ *
+ * Shared with RevisionAutoFixer so the validator and fixer cannot drift
+ * apart on which revision types are allowed to be empty.
+ */
+export const CONTENTLESS_REVISION_TYPES: ReadonlySet<string> = new Set([
+  'runPropertiesChange',
+  'paragraphPropertiesChange',
+  'tablePropertiesChange',
+  'tableExceptionPropertiesChange',
+  'tableRowPropertiesChange',
+  'tableCellPropertiesChange',
+  'sectionPropertiesChange',
+  'numberingChange',
+  'tableCellInsert',
+  'tableCellDelete',
+  'tableCellMerge',
+]);
+
+/**
+ * True when a revision carries real content. Per ECMA-376, w:ins/w:del may
+ * contain w:hyperlink and image runs (w:r with w:drawing) in addition to
+ * text runs, so a runs-only text check would falsely flag hyperlink-only
+ * and image-only tracked changes as empty. Shared with RevisionAutoFixer.
+ */
+export function revisionHasContent(rev: Revision): boolean {
+  // Covers text runs and hyperlink display text
+  if (rev.getText().length > 0) {
+    return true;
+  }
+  // Hyperlinks count even without display text; ImageRuns have no text at all
+  return rev.getContent().some((item) => isHyperlinkContent(item) || isImageRunContent(item));
+}
+
 /**
  * Validates document revisions for ECMA-376 compliance.
  *
@@ -67,15 +106,15 @@ export class RevisionValidator {
     if (!skipRules.has('REV001')) {
       allIssues.push(...this.validateRevisionIds(revisions));
     }
-    if (!skipRules.has('REV003') && !skipRules.has('REV004')) {
-      allIssues.push(...this.validateMovePairs(revisions));
-    }
+    // validateMovePairs emits both REV003 and REV004 from one pairing pass;
+    // filter per issue code so skipping one rule does not silently disable
+    // the other (REV004 is error-severity and corruption-relevant).
+    allIssues.push(...this.validateMovePairs(revisions).filter((i) => !skipRules.has(i.code)));
     if (!skipRules.has('REV002')) {
       allIssues.push(...this.validateAuthors(revisions));
     }
-    if (!skipRules.has('REV101') && !skipRules.has('REV102')) {
-      allIssues.push(...this.validateDates(revisions));
-    }
+    // validateDates emits both REV101 and REV102 — same per-code filtering.
+    allIssues.push(...this.validateDates(revisions).filter((i) => !skipRules.has(i.code)));
     if (!skipRules.has('REV103')) {
       allIssues.push(...this.validateContent(revisions));
     }
@@ -302,29 +341,15 @@ export class RevisionValidator {
   static validateContent(revisions: Revision[]): ValidationIssue[] {
     const issues: ValidationIssue[] = [];
 
-    const propertyChangeTypes = [
-      'runPropertiesChange',
-      'paragraphPropertiesChange',
-      'tablePropertiesChange',
-      'tableExceptionPropertiesChange',
-      'tableRowPropertiesChange',
-      'tableCellPropertiesChange',
-      'sectionPropertiesChange',
-      'numberingChange',
-    ];
-
     for (const rev of revisions) {
       const type = rev.getType();
 
-      // Property changes don't need text content
-      if (propertyChangeTypes.includes(type)) {
+      // Property changes and cell markers are contentless by design
+      if (CONTENTLESS_REVISION_TYPES.has(type)) {
         continue;
       }
 
-      const runs = rev.getRuns();
-      const hasContent = runs.length > 0 && runs.some((r) => r.getText().length > 0);
-
-      if (!hasContent) {
+      if (!revisionHasContent(rev)) {
         issues.push(
           createIssueFromRule(
             REVISION_RULES.EMPTY_REVISION,

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) => {