node-pptx-templater 1.0.5 → 1.0.6

package/CHANGELOG.md

@@ -5,9 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.6] - 2026-06-02
+
+### Added
+
+- **XML Validation & Diagnostics Engine**: Introduced a suite of tools in `src/utils/xmlUtils.js` for XML safety and diagnostics:
+  - `validateXml(xmlString)` — Validates that an XML string is secure and well-formed, checking for DTDs, custom/recursive entities, and XXE.
+  - `safeParseXml(xmlString, file)` — Unified wrapper that runs validation and captures detailed diagnostic error logs (file, line, col, error details, and recommendations) on failure.
+  - `scanForEntities(xmlString)` — Scans and classifies all XML entity references (standard, custom, numeric, and hex).
+  - `analyzeXmlFile(xmlString)` — Computes core file sizing and stats (bytes, lines, elements, attributes, entities).
+  - `reportXmlComplexity(xmlString)` — Inspects structural metrics (maximum tag nesting depth, node count, text-to-markup ratio).
+- **Public API Exports**: The new tools are exported from the main library entry point `src/index.js`.
+
+### Fixed
+
+- **XML Entity Expansion Limit Resolution**: Permanently resolved the `Entity expansion limit exceeded` parser crashes on large template files. Deactivated internal entity expansion in `fast-xml-parser` and replaced it with a fast, secure, non-recursive unescaper handling the 5 standard XML/HTML entities and numeric references (decimal and hex code points) natively.
+- **Vulnerability Protections**: Integrated strict security checks directly into the validator to block DTD abuse, XML bombs (Billion Laughs), and XXE attacks safely before the parser processes them.
+
+### Tests
+
+- Added 13 new unit and integration tests in `tests/unit/XMLSecurity.test.js` validating security protections, large-scale entity processing, diagnostics error recovery, and complexity analysis.
+- Total test count increased from 108 → 121 (all passing).
+
 ## [1.0.5] - 2026-06-02
 
 ### Added
+
 - **Z-Order (Layer Management) System**: Full stacking control for all slide drawing objects — shapes, images, charts, tables, groups, connectors, and SmartArt. Directly manipulates the OpenXML `<p:spTree>` element order, matching PowerPoint's native Bring Forward / Send Backward behavior exactly. New APIs:
   - `getObjectOrder(slideIndex)` — Returns ordered metadata (id, type, zIndex) for every element on a slide, bottom-to-top.
   - `bringForward(options)` — Moves an object one layer up in the stack.
@@ -27,29 +50,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **ZOrderManager**: New dedicated manager class (`src/managers/ZOrderManager.js`) encapsulating all layer logic.
 
 ### Fixed
+
 - **`PPTXTemplater.create()` synchronous readiness**: Added `preloadAll()` call to `#initializeBlank()`. Previously, the blank PPTX template's pre-existing slides were registered but their XML was not cached, causing all synchronous operations (including ZOrderManager) to throw `"Slide N XML not pre-loaded"`.
 
 ### Changed
+
 - **`XMLParser` hybrid parsing**: Added a secondary `preserveOrder: true` fast-xml-parser pass that runs during `parse()` whenever a slide `<p:spTree>` is detected. Extracts DOM element order and attaches it via `Z_ORDER_SYMBOL` to each container. The `build()` method uses a new `serializeContainer()` recursive function to serialize containers in Z_ORDER_SYMBOL order, injecting the result back into the output XML.
 - **`ValidationEngine`**: `validate()` now audits the shape tree for duplicate shape IDs, reporting them as errors.
 
 ### Tests
+
 - Added 12 new integration tests in `tests/integration/ZOrder.test.js` covering all Z-order operations.
 - Total test count increased from 96 → 108 (all passing).
 
 ## [1.0.3] - 2026-06-02
 
 ### Added
+
 - **Dynamic Formatting in updateTable**: Added support for inline cell styling (color fill `fill`, text alignment `align`, and `fontSize`) directly on cell objects passed to `updateTable`.
 - **Comprehensive Tailwind Site**: Overhauled doc builder script to generate a premium Tailwind CSS documentation portal with clientside search, clipboard copying, sitemap.xml, robots.txt, and Schema.org metadata.
 
 ### Fixed
+
 - **XML Element Ordering**: Enforced strict schema-valid element sequence (`a:pPr` -> runs -> `a:endParaRPr`) in slide table cell paragraphs. This resolves the bug where split cells inheriting from template merged cells had their text runs ignored by PowerPoint's XML compiler.
 - **Template Style Inheritance**: Fixed a bug in `updateTable` where cloned rows always copied the first data row (`trs[1]`). The engine now correctly inherits formatting, alignment, and fill styles from matching indices in the template (`trs[i]`) when available.
 
 ## [1.0.2] - 2026-06-02
 
 ### Added
+
 - **Table Cell Merging & Unmerging Engine**: Fully implemented horizontal cell spans (`gridSpan`, `hMerge`), vertical cell spans (`rowSpan`, `vMerge`), and rectangular block merges.
 - **PowerPoint Repair Protection**: Implemented unique 32-bit unsigned `rowId` generation inside `<a16:rowId>` XML tags for all cloned and inserted rows, eliminating PowerPoint's "Repair Mode" error prompts.
 - **Merge Integrations**: Integrated template-driven merges (`merge` configs array and cell-level `colSpan`/`rowSpan`) inside the main `updateTable` orchestrator.
@@ -58,11 +87,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.1] - 2026-05-19
 
 ### Changed
+
 - **CommonJS Target Conversion**: Converted the source code modules compilation and packaging layout from pure ES Modules (ESM) to CommonJS (CJS) to ensure compatibility with standard Node.js deployment, packaging, and edge runtime environments.
 
 ## [1.0.0] - 2026-05-17
 
 ### Added
+
 - `PPTXTemplater` — main orchestrator class with fluent chainable API
 - `ZipManager` — PPTX ZIP archive loading, reading, writing, and re-packaging
 - `XMLParser` — high-performance XML parsing/building via `fast-xml-parser`
@@ -84,6 +115,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - MIT License
 
 ### Architecture
+
 - Zero PPTX generation library dependencies
 - Only uses: `jszip`, `fast-xml-parser`, `fs-extra`, `commander`, `chalk`, `ora`
 - Async/await throughout