docxmlater 10.4.0 → 11.0.4

package/src/__tests__/helper-methods.test.ts

@@ -1,512 +0,0 @@
-/**
- * Tests for all new helper methods added to docxmlater
- * Tests Document, Paragraph, Table, and Image helper methods
- */
-
-import { Document } from '../core/Document';
-import { Paragraph } from '../elements/Paragraph';
-import { Table } from '../elements/Table';
-import { Image } from '../elements/Image';
-
-describe('Document Helper Methods', () => {
-  let doc: Document;
-
-  beforeEach(() => {
-    doc = Document.create();
-  });
-
-  describe('findText', () => {
-    it('should find text in paragraphs', () => {
-      const para = doc.createParagraph('Hello world, this is a test document with some text.');
-
-      const results = doc.findText('test');
-      expect(results).toHaveLength(1);
-      expect(results[0]?.text).toBe('test');
-      expect(results[0]?.paragraph).toBe(para);
-    });
-
-    it('should find text with case sensitivity', () => {
-      doc.createParagraph('Hello World');
-
-      const results1 = doc.findText('world', { caseSensitive: false });
-      expect(results1).toHaveLength(1);
-
-      const results2 = doc.findText('world', { caseSensitive: true });
-      expect(results2).toHaveLength(0);
-
-      const results3 = doc.findText('World', { caseSensitive: true });
-      expect(results3).toHaveLength(1);
-    });
-
-    it('should find whole words only', () => {
-      doc.createParagraph('This is testing a test case');
-
-      const results1 = doc.findText('test', { wholeWord: false });
-      expect(results1).toHaveLength(2); // "testing" and "test"
-
-      const results2 = doc.findText('test', { wholeWord: true });
-      expect(results2).toHaveLength(1); // only "test"
-    });
-
-    it('should find text in tables', () => {
-      const table = doc.createTable(2, 2);
-      table.getCell(0, 0)?.createParagraph('Cell with test text');
-
-      const results = doc.findText('test');
-      expect(results).toHaveLength(1);
-    });
-  });
-
-  describe('replaceText', () => {
-    it('should replace text in paragraphs', () => {
-      const para = doc.createParagraph('Hello world');
-
-      const count = doc.replaceText('world', 'universe');
-      expect(count).toBe(1);
-      expect(para.getText()).toBe('Hello universe');
-    });
-
-    it('should replace multiple occurrences', () => {
-      const para = doc.createParagraph('test test test');
-
-      const count = doc.replaceText('test', 'example');
-      expect(count).toBe(3);
-      expect(para.getText()).toBe('example example example');
-    });
-
-    it('should replace with case sensitivity', () => {
-      const para = doc.createParagraph('Test test TEST');
-
-      const count1 = doc.replaceText('test', 'example', { caseSensitive: true });
-      expect(count1).toBe(1);
-      expect(para.getText()).toBe('Test example TEST');
-
-      para.setText('Test test TEST');
-      const count2 = doc.replaceText('test', 'example', { caseSensitive: false });
-      expect(count2).toBe(3);
-      expect(para.getText()).toBe('example example example');
-    });
-
-    it('should replace whole words only', () => {
-      const para = doc.createParagraph('testing test tested');
-
-      const count = doc.replaceText('test', 'exam', { wholeWord: true });
-      expect(count).toBe(1);
-      expect(para.getText()).toBe('testing exam tested');
-    });
-  });
-
-  describe('getWordCount', () => {
-    it('should count words in paragraphs', () => {
-      doc.createParagraph('Hello world');
-      doc.createParagraph('This is a test');
-
-      expect(doc.getWordCount()).toBe(6);
-    });
-
-    it('should count words in tables', () => {
-      doc.createParagraph('Hello world');
-      const table = doc.createTable(2, 2);
-      table.getCell(0, 0)?.createParagraph('Table cell text');
-
-      expect(doc.getWordCount()).toBe(5); // 2 + 3
-    });
-
-    it('should handle empty paragraphs', () => {
-      doc.createParagraph('');
-      doc.createParagraph('Hello');
-      doc.createParagraph('');
-
-      expect(doc.getWordCount()).toBe(1);
-    });
-  });
-
-  describe('getCharacterCount', () => {
-    it('should count characters with spaces', () => {
-      doc.createParagraph('Hello world');
-
-      expect(doc.getCharacterCount(true)).toBe(11);
-    });
-
-    it('should count characters without spaces', () => {
-      doc.createParagraph('Hello world');
-
-      expect(doc.getCharacterCount(false)).toBe(10);
-    });
-
-    it('should count characters in tables', () => {
-      doc.createParagraph('Test');
-      const table = doc.createTable(1, 1);
-      table.getCell(0, 0)?.createParagraph('Cell');
-
-      expect(doc.getCharacterCount(true)).toBe(8); // 4 + 4
-    });
-  });
-
-  describe('removeParagraph', () => {
-    it('should remove paragraph by object', () => {
-      const para1 = doc.createParagraph('First');
-      const para2 = doc.createParagraph('Second');
-      const para3 = doc.createParagraph('Third');
-
-      expect(doc.getParagraphCount()).toBe(3);
-
-      const removed = doc.removeParagraph(para2);
-      expect(removed).toBe(true);
-      expect(doc.getParagraphCount()).toBe(2);
-      expect(doc.getParagraphs()).toEqual([para1, para3]);
-    });
-
-    it('should remove paragraph by index', () => {
-      doc.createParagraph('First');
-      doc.createParagraph('Second');
-      doc.createParagraph('Third');
-
-      const removed = doc.removeParagraph(1);
-      expect(removed).toBe(true);
-      expect(doc.getParagraphCount()).toBe(2);
-      expect(doc.getParagraphs()[1]?.getText()).toBe('Third');
-    });
-
-    it('should return false for invalid index', () => {
-      doc.createParagraph('First');
-
-      expect(doc.removeParagraph(-1)).toBe(false);
-      expect(doc.removeParagraph(5)).toBe(false);
-    });
-  });
-
-  describe('removeTable', () => {
-    it('should remove table by object', () => {
-      const table1 = doc.createTable(1, 1);
-      const table2 = doc.createTable(2, 2);
-
-      expect(doc.getTableCount()).toBe(2);
-
-      const removed = doc.removeTable(table1);
-      expect(removed).toBe(true);
-      expect(doc.getTableCount()).toBe(1);
-      expect(doc.getTables()[0]).toBe(table2);
-    });
-
-    it('should remove table by index', () => {
-      doc.createTable(1, 1);
-      doc.createTable(2, 2);
-
-      const removed = doc.removeTable(0);
-      expect(removed).toBe(true);
-      expect(doc.getTableCount()).toBe(1);
-    });
-  });
-
-  describe('insertParagraphAt', () => {
-    it('should insert paragraph at specific position', () => {
-      doc.createParagraph('First');
-      doc.createParagraph('Third');
-
-      const para2 = new Paragraph();
-      para2.addText('Second');
-      doc.insertParagraphAt(1, para2);
-
-      expect(doc.getParagraphCount()).toBe(3);
-      expect(doc.getParagraphs()[1]).toBe(para2);
-    });
-
-    it('should handle edge cases', () => {
-      doc.createParagraph('First');
-
-      const para0 = new Paragraph();
-      para0.addText('Zero');
-      doc.insertParagraphAt(-1, para0);
-      expect(doc.getParagraphs()[0]).toBe(para0);
-
-      const paraLast = new Paragraph();
-      paraLast.addText('Last');
-      doc.insertParagraphAt(100, paraLast);
-      expect(doc.getParagraphs()[doc.getParagraphCount() - 1]).toBe(paraLast);
-    });
-  });
-
-  describe('getHyperlinks', () => {
-    it('should find hyperlinks in paragraphs', () => {
-      doc.createParagraph();
-      // We'd need to properly create a hyperlink through the document's relationship manager
-      // For now, we'll just test that the method returns an empty array
-
-      const links = doc.getHyperlinks();
-      expect(links).toEqual([]);
-    });
-  });
-
-  describe('getBookmarks', () => {
-    it('should find bookmarks in paragraphs', () => {
-      const para = doc.createParagraph('Text');
-      const bookmark = doc.createBookmark('test-bookmark');
-      para.addBookmark(bookmark);
-
-      const bookmarks = doc.getBookmarks();
-      expect(bookmarks).toHaveLength(1);
-      expect(bookmarks[0]?.bookmark).toBe(bookmark);
-      expect(bookmarks[0]?.paragraph).toBe(para);
-    });
-  });
-
-  describe('getImages', () => {
-    it('should return all images', async () => {
-      // This would need actual image files to test properly
-      const images = doc.getImages();
-      expect(images).toEqual([]);
-    });
-  });
-
-  describe('setLanguage/getLanguage', () => {
-    it('should set and get document language', () => {
-      expect(doc.getLanguage()).toBeUndefined();
-
-      doc.setLanguage('en-US');
-      expect(doc.getLanguage()).toBe('en-US');
-
-      doc.setLanguage('es-ES');
-      expect(doc.getLanguage()).toBe('es-ES');
-    });
-  });
-});
-
-describe('Paragraph Helper Methods', () => {
-  let para: Paragraph;
-
-  beforeEach(() => {
-    para = new Paragraph();
-  });
-
-  describe('getWordCount', () => {
-    it('should count words in paragraph', () => {
-      para.addText('Hello world, this is a test');
-      expect(para.getWordCount()).toBe(6);
-    });
-
-    it('should handle empty paragraph', () => {
-      expect(para.getWordCount()).toBe(0);
-    });
-
-    it('should handle multiple runs', () => {
-      para.addText('Hello ');
-      para.addText('world');
-      expect(para.getWordCount()).toBe(2);
-    });
-  });
-
-  describe('getLength', () => {
-    it('should count characters with spaces', () => {
-      para.addText('Hello world');
-      expect(para.getLength(true)).toBe(11);
-    });
-
-    it('should count characters without spaces', () => {
-      para.addText('Hello world');
-      expect(para.getLength(false)).toBe(10);
-    });
-  });
-
-  describe('clone', () => {
-    it('should create a deep copy of paragraph', () => {
-      para.addText('Hello', { bold: true });
-      para.addText(' world', { italic: true });
-      para.setAlignment('center');
-      para.setSpaceBefore(240);
-
-      const cloned = para.clone();
-
-      expect(cloned).not.toBe(para);
-      expect(cloned.getText()).toBe('Hello world');
-      expect(cloned.getFormatting().alignment).toBe('center');
-      expect(cloned.getFormatting().spacing?.before).toBe(240);
-      expect(cloned.getRuns()).toHaveLength(2);
-      expect(cloned.getRuns()[0]?.getFormatting().bold).toBe(true);
-      expect(cloned.getRuns()[1]?.getFormatting().italic).toBe(true);
-    });
-  });
-
-  describe('setBorder', () => {
-    it('should set paragraph borders', () => {
-      para.setBorder({
-        top: { style: 'single', size: 4, color: '000000' },
-        bottom: { style: 'double', size: 8, color: 'FF0000' },
-      });
-
-      const formatting = para.getFormatting() as any;
-      expect(formatting.borders).toBeDefined();
-      expect(formatting.borders.top.style).toBe('single');
-      expect(formatting.borders.bottom.color).toBe('FF0000');
-    });
-  });
-
-  describe('setShading', () => {
-    it('should set paragraph shading', () => {
-      para.setShading({
-        fill: 'FFFF00',
-        pattern: 'solid',
-      });
-
-      const formatting = para.getFormatting() as any;
-      expect(formatting.shading).toBeDefined();
-      expect(formatting.shading.fill).toBe('FFFF00');
-      expect(formatting.shading.pattern).toBe('solid');
-    });
-  });
-
-  describe('setTabs', () => {
-    it('should set tab stops', () => {
-      para.setTabs([
-        { position: 720, val: 'left' },
-        { position: 1440, val: 'center', leader: 'dot' },
-      ]);
-
-      const formatting = para.getFormatting() as any;
-      expect(formatting.tabs).toBeDefined();
-      expect(formatting.tabs).toHaveLength(2);
-      expect(formatting.tabs[0].position).toBe(720);
-      expect(formatting.tabs[1].leader).toBe('dot');
-    });
-  });
-});
-
-describe('Table Helper Methods', () => {
-  let table: Table;
-
-  beforeEach(() => {
-    table = new Table(3, 3);
-  });
-
-  describe('removeRow', () => {
-    it('should remove row at index', () => {
-      expect(table.getRowCount()).toBe(3);
-
-      const removed = table.removeRow(1);
-      expect(removed).toBe(true);
-      expect(table.getRowCount()).toBe(2);
-    });
-
-    it('should return false for invalid index', () => {
-      expect(table.removeRow(-1)).toBe(false);
-      expect(table.removeRow(10)).toBe(false);
-    });
-  });
-
-  describe('insertRow', () => {
-    it('should insert row at position', () => {
-      const row = table.insertRow(1);
-
-      expect(table.getRowCount()).toBe(4);
-      expect(table.getRow(1)).toBe(row);
-    });
-
-    it('should create row with correct column count', () => {
-      const row = table.insertRow(0);
-
-      expect(row.getCellCount()).toBe(3);
-    });
-  });
-
-  describe('addColumn', () => {
-    it('should add column to all rows', () => {
-      table.addColumn();
-
-      expect(table.getColumnCount()).toBe(4);
-      for (const row of table.getRows()) {
-        expect(row.getCellCount()).toBe(4);
-      }
-    });
-
-    it('should add column at specific position', () => {
-      table.getCell(0, 1)?.createParagraph('Middle');
-
-      table.addColumn(1);
-
-      expect(table.getColumnCount()).toBe(4);
-      expect(table.getCell(0, 2)?.getText()).toBe('Middle');
-    });
-  });
-
-  describe('removeColumn', () => {
-    it('should remove column from all rows', () => {
-      const removed = table.removeColumn(1);
-
-      expect(removed).toBe(true);
-      expect(table.getColumnCount()).toBe(2);
-      for (const row of table.getRows()) {
-        expect(row.getCellCount()).toBe(2);
-      }
-    });
-
-    it('should return false for invalid index', () => {
-      expect(table.removeColumn(-1)).toBe(false);
-      expect(table.removeColumn(10)).toBe(false);
-    });
-  });
-
-  describe('getColumnCount', () => {
-    it('should return maximum column count', () => {
-      expect(table.getColumnCount()).toBe(3);
-    });
-
-    it('should return 0 for empty table', () => {
-      const emptyTable = new Table();
-      expect(emptyTable.getColumnCount()).toBe(0);
-    });
-  });
-
-  describe('setColumnWidths', () => {
-    it('should set column widths', () => {
-      table.setColumnWidths([2880, 1440, null]);
-
-      const formatting = table.getFormatting();
-      expect(formatting.tableGrid).toEqual([2880, 1440, undefined]);
-    });
-  });
-});
-
-describe('Image Helper Methods', () => {
-  describe('setAltText/getAltText', () => {
-    it('should set and get alt text', async () => {
-      // Create a simple test image buffer
-      const imageBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47]); // PNG header
-      const image = await Image.fromBuffer(imageBuffer);
-
-      expect(image.getAltText()).toBe('Image');
-
-      image.setAltText('A test image');
-      expect(image.getAltText()).toBe('A test image');
-    });
-  });
-
-  describe('rotate/getRotation', () => {
-    it('should set and get rotation', async () => {
-      const imageBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
-      const image = await Image.fromBuffer(imageBuffer);
-
-      expect(image.getRotation()).toBe(0);
-
-      image.rotate(90);
-      expect(image.getRotation()).toBe(90);
-
-      image.rotate(450); // Should normalize to 90
-      expect(image.getRotation()).toBe(90);
-
-      image.rotate(-90); // Should normalize to 270
-      expect(image.getRotation()).toBe(270);
-    });
-
-    it('should swap dimensions on 90/270 degree rotation', async () => {
-      const imageBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
-      const image = await Image.fromBuffer(imageBuffer, { width: 1000, height: 2000 });
-
-      const originalWidth = image.getWidth();
-      const originalHeight = image.getHeight();
-
-      image.rotate(90);
-      expect(image.getWidth()).toBe(originalHeight);
-      expect(image.getHeight()).toBe(originalWidth);
-    });
-  });
-});

package/src/constants/CLAUDE.md

@@ -1,28 +0,0 @@
-# Constants Module
-
-`src/constants/` — Compile-time constants for limits and OOXML compatibility.
-
-## Files
-
-### `limits.ts`
-Document validation and processing thresholds:
-
-| Category | Constant | Value | Purpose |
-|----------|----------|-------|---------|
-| Property | `MAX_STRING_LENGTH` | 10,000 | Max string property length |
-| Property | `MAX_REVISION` | 999,999 | Max revision ID |
-| File size | `WARNING_SIZE_MB` | 50 | Log warning above this |
-| File size | `ERROR_SIZE_MB` | 150 | Reject above this |
-| XML | `MAX_PARSE_SIZE_MB` | 10 | Per-part parse limit |
-| Memory | `DEFAULT_MAX_HEAP_PERCENT` | 80% | Heap usage threshold |
-| Memory | `DEFAULT_MAX_RSS_MB` | 2,048 | RSS limit |
-| Images | `DEFAULT_MAX_IMAGE_COUNT` | 20 | Max images per doc |
-| Images | `DEFAULT_MAX_TOTAL_SIZE_MB` | 100 | Total image data limit |
-
-### `legacyCompatFlags.ts`
-ECMA-376 compatibility mode constants:
-
-- `LEGACY_COMPAT_ELEMENTS` — 65 boolean flags from CT_Compat (1st edition). Used by `CompatibilityUpgrader` to remove legacy flags during upgrade.
-- `MODERN_COMPAT_SETTINGS` — 5 `compatSetting` entries for Word 2013+ mode (differenceMultilineTableBorder, overrideTableStyleFontSizeAndJustification, enableOpenTypeFeatures, etc.)
-- `useWord2013TrackBottomHyphenation` intentionally omitted (value varies across Word versions)
-- Custom URI compat settings are preserved during upgrade (only Microsoft URI settings replaced)

package/src/core/CLAUDE.md

@@ -1,113 +0,0 @@
-# Core Module
-
-`src/core/` — Document lifecycle, XML parsing/generation, validation, relationships.
-
-## Classes
-
-### Document (`Document.ts`)
-
-Primary entry point. Factory pattern: `Document.create()` (new), `Document.load()`/`loadFromBuffer()` (existing). Disposal pattern: always call `dispose()` when done.
-
-**Load Options:**
-```typescript
-interface DocumentLoadOptions {
-  revisionHandling?: 'accept' | 'strip' | 'preserve';  // default: 'accept'
-  acceptRevisions?: boolean;  // true = parse then accept in-memory
-}
-```
-
-Use `revisionHandling: 'preserve'` to retain `pPrChange` and other revision elements during round-trip.
-
-### DocumentParser (`DocumentParser.ts`)
-
-Converts XML to JavaScript object models. Position-based parsing (ReDoS-safe).
-
-**Key behaviors:**
-- Hyperlink defragmentation (merges consecutive hyperlinks with same URL)
-- Special characters: `<w:tab/>`, `<w:br/>` → string equivalents
-- Multi-paragraph complex fields: assembles fields (like TOC) spanning multiple paragraphs into single `ComplexField` objects
-- Element order via `_orderedChildren` for correct tab/break ordering
-- Body-level bookmarks: `extractBodyLevelBookmarkStarts()`/`extractBodyLevelBookmarkEnds()`
-- Form field data: `parseFormFieldData()` with typed interfaces
-- Footnotes/endnotes: `parseFootnotesXml()`/`parseEndnotesXml()`
-- Unknown elements preserved for round-trip fidelity
-- CT_OnOff parsing: uses `parseOoxmlBoolean()` with `!== undefined` checks to preserve explicit `val="0"` for style override semantics
-- `w:color w:val="auto"` preserved on round-trip (bypasses `normalizeColor()` hex validation)
-- `w14:paraId`/`w14:textId` parsed from paragraph elements and auto-generated for new paragraphs
-- `w:trHeight w:hRule` absent = omit (spec default "auto"), not defaulted to "atLeast"
-
-### DocumentGenerator (`DocumentGenerator.ts`)
-
-Converts object models to DOCX XML. Template-based, on-demand, validates before generation.
-
-Generates: `[Content_Types].xml`, `_rels/.rels`, `word/document.xml`, `word/styles.xml`, `word/numbering.xml`, `word/settings.xml`, `word/fontTable.xml`, `word/_rels/document.xml.rels`, `word/footnotes.xml`, `word/endnotes.xml`, `docProps/core.xml`, `docProps/app.xml`.
-
-### DocumentValidator (`DocumentValidator.ts`)
-
-Estimates final DOCX file size and validates memory usage. Size formula: `(base ~5KB + text*1.5 + images + cells*200) * 0.3 compression`.
-
-### RelationshipManager (`RelationshipManager.ts`)
-
-Manages relationships (images, hyperlinks, headers, footers, comments, footnotes, endnotes, people). Sequential IDs (`rId1`, `rId2`, ...). Singleton types (comments, footnotes, endnotes, people) need check-before-add guard to prevent duplicates on round-trip.
-
-### BaseManager (`BaseManager.ts`)
-
-Abstract base for all manager classes. Subclasses: StylesManager, NumberingManager, ImageManager, BookmarkManager, CommentManager, RevisionManager, FootnoteManager, EndnoteManager, DrawingManager, HeaderFooterManager.
-
-## Data Flow
-
-**Load:** `Document.load()` → `ZipHandler.load()` → extract XML → `DocumentParser.parse()` → parse styles/numbering/relationships → build object model → return Document
-
-**Save:** `Document.save()` → `DocumentValidator.estimateSize()` → `DocumentGenerator.generate()` → generate all XML → `RelationshipManager.generateXML()` → `ZipWriter.create()` → write ZIP
-
-## Revision Acceptance Architecture
-
-The framework implements the **industry-standard in-memory DOM transformation approach** (same as OpenXML PowerTools, Aspose.Words).
-
-**`acceptAllRevisions()` transforms Revision objects in the in-memory model:**
-1. **Insertions (`w:ins`)**: Unwrap — child Runs/Hyperlinks extracted into parent paragraph
-2. **Deletions (`w:del`)**: Remove — revision and content deleted from model
-3. **MoveFrom (`w:moveFrom`)**: Remove — content exists at moveTo destination
-4. **MoveTo (`w:moveTo`)**: Unwrap — keep content, remove wrapper
-5. **Property changes (`w:rPrChange`, etc.)**: Remove metadata, keep current formatting
-
-Because this transforms the in-memory model (not raw XML), standard `save()` regeneration includes both accepted changes AND subsequent modifications.
-
-**`acceptAllRevisionsRawXml()` (legacy):** Sets `skipDocumentXmlRegeneration = true`. Any modifications after this call will NOT be saved.
-
-**Helper Functions:**
-```typescript
-import { acceptRevisionsInMemory, paragraphHasRevisions, getRevisionsFromParagraph, countRevisionsByType } from 'docxmlater';
-
-// Selective acceptance
-const result = acceptRevisionsInMemory(doc, {
-  acceptInsertions: true,
-  acceptDeletions: true,
-  acceptMoves: true,
-  acceptPropertyChanges: false,
-});
-```
-
-## Sanitization & Cleanup Pipeline
-
-All methods below are explicitly called by user code. None run automatically. **Removals are intentional — do not treat as bugs.**
-
-**Post-Processing (`_postProcessDocumentXml`):** Runs during `prepareSave()`, after `updateDocumentXml()` and before `updateSettingsXml()`. Zero overhead when no flags set.
-
-| Method | Removes | Why |
-|--------|---------|-----|
-| `flattenFieldCodes()` | INCLUDEPICTURE fldChar/instrText runs | Outlook bloat. Preserves w:drawing. Other fields untouched. Sets `skipDocumentXmlRegeneration = true`. |
-| `stripOrphanRSIDs()` | Unreferenced RSIDs in settings.xml | 80%+ of settings.xml. Preserves `rsidRoot`. |
-| `clearDirectSpacingForStyles()` | Direct w:spacing on styled paragraphs | Lets style spacing take effect. Protects w:pPrChange/w:rPr. |
-| `cleanupUnusedNumbering()` | Unreferenced numbering defs | Scans 6 sources before removing. |
-| `consolidateNumbering()` | Duplicate abstract numberings | Copy-paste creates 10-50+ identical copies. |
-
-## Performance
-
-| Document Size | Load/Save Time |
-|--------------|----------------|
-| <100KB | <50ms |
-| 100KB-1MB | 100-500ms |
-| >1MB | 500ms-2s |
-
-Buffer operations are 20-30% faster than file I/O. Base memory: ~2MB per Document, ~2 bytes/char, full buffer per image, ~200 bytes/cell.