node-pptx-templater 1.0.2 → 1.0.3

package/src/core/TemplateEngine.js

@@ -26,15 +26,15 @@
  * This "text normalization" approach correctly handles fragmented placeholders.
  */
 
-const { createLogger } = require('../utils/logger.js');
+const { createLogger } = require('../utils/logger.js')
 
-const logger = createLogger('TemplateEngine');
+const logger = createLogger('TemplateEngine')
 
 /**
  * Default placeholder pattern: {{key}}
  * Can be overridden per-call.
  */
-const DEFAULT_PLACEHOLDER_PATTERN = /\{\{([^{}]+)\}\}/g;
+const DEFAULT_PLACEHOLDER_PATTERN = /\{\{([^{}]+)\}\}/g
 
 /**
  * @class TemplateEngine
@@ -44,13 +44,13 @@ const DEFAULT_PLACEHOLDER_PATTERN = /\{\{([^{}]+)\}\}/g;
  */
 class TemplateEngine {
   /** @private @type {XMLParser} */
-  #xmlParser;
+  #xmlParser
 
   /**
    * @param {XMLParser} xmlParser
    */
   constructor(xmlParser) {
-    this.#xmlParser = xmlParser;
+    this.#xmlParser = xmlParser
   }
 
   /**
@@ -68,28 +68,28 @@ class TemplateEngine {
    *   '{{date}}': '2026-01-01'
    * });
    */
-  replaceTextInXml(slideXml, replacements, pattern = DEFAULT_PLACEHOLDER_PATTERN) {
+  replaceTextInXml(slideXml, replacements) {
     if (!replacements || Object.keys(replacements).length === 0) {
-      return slideXml;
+      return slideXml
     }
 
-    logger.debug(`Replacing ${Object.keys(replacements).length} placeholder(s)`);
+    logger.debug(`Replacing ${Object.keys(replacements).length} placeholder(s)`)
 
     // Step 1: Process paragraph by paragraph to handle fragmented runs
-    let updated = this.#processParagraphs(slideXml, replacements);
+    let updated = this.#processParagraphs(slideXml, replacements)
 
     // Step 2: Simple direct replacement for any remaining unfragmented placeholders
     for (const [placeholder, value] of Object.entries(replacements)) {
-      const escaped = this.#escapeXml(String(value));
-      const placeholderEscaped = this.#escapeXml(placeholder);
+      const escaped = this.#escapeXml(String(value))
+      const placeholderEscaped = this.#escapeXml(placeholder)
 
       // Replace the XML-escaped form (e.g., {{name}} as {{name}})
-      updated = updated.split(placeholderEscaped).join(escaped);
+      updated = updated.split(placeholderEscaped).join(escaped)
       // Replace the plain form (in case it's not escaped in the XML)
-      updated = updated.split(placeholder).join(escaped);
+      updated = updated.split(placeholder).join(escaped)
     }
 
-    return updated;
+    return updated
   }
 
   /**
@@ -103,30 +103,28 @@ class TemplateEngine {
    */
   #processParagraphs(slideXml, replacements) {
     // Find all <a:p>...</a:p> paragraphs
-    let updated = slideXml;
-    let offset = 0;
+    let updated = slideXml
+    let offset = 0
 
-    const paragraphPattern = /<a:p>([\s\S]*?)<\/a:p>/g;
-    let match;
+    const paragraphPattern = /<a:p>([\s\S]*?)<\/a:p>/g
+    let match
 
     while ((match = paragraphPattern.exec(slideXml)) !== null) {
-      const paragraphXml = match[0];
-      const processedParagraph = this.#processParagraph(paragraphXml, replacements);
+      const paragraphXml = match[0]
+      const processedParagraph = this.#processParagraph(paragraphXml, replacements)
 
       if (processedParagraph !== paragraphXml) {
-        // Replace in the updated string (adjust for offset changes)
-        const start = updated.indexOf(paragraphXml, match.index + offset - (match.index));
-
         // More reliable: replace from the beginning of the current search area
-        updated = updated.substring(0, match.index + offset) +
+        updated =
+          updated.substring(0, match.index + offset) +
           processedParagraph +
-          updated.substring(match.index + offset + paragraphXml.length);
+          updated.substring(match.index + offset + paragraphXml.length)
 
-        offset += processedParagraph.length - paragraphXml.length;
+        offset += processedParagraph.length - paragraphXml.length
       }
     }
 
-    return updated;
+    return updated
   }
 
   /**
@@ -139,32 +137,32 @@ class TemplateEngine {
    */
   #processParagraph(paragraphXml, replacements) {
     // Extract all text runs from this paragraph
-    const runs = this.#extractRuns(paragraphXml);
+    const runs = this.#extractRuns(paragraphXml)
 
-    if (runs.length === 0) return paragraphXml;
+    if (runs.length === 0) return paragraphXml
 
     // Combine text from all runs
-    const combinedText = runs.map(r => r.text).join('');
+    const combinedText = runs.map(r => r.text).join('')
 
     // Check if any placeholder appears in the combined text
-    let hasPlaceholder = false;
+    let hasPlaceholder = false
     for (const placeholder of Object.keys(replacements)) {
       if (combinedText.includes(placeholder)) {
-        hasPlaceholder = true;
-        break;
+        hasPlaceholder = true
+        break
       }
     }
 
-    if (!hasPlaceholder) return paragraphXml;
+    if (!hasPlaceholder) return paragraphXml
 
     // Perform replacement on combined text
-    let replacedText = combinedText;
+    let replacedText = combinedText
     for (const [placeholder, value] of Object.entries(replacements)) {
-      replacedText = replacedText.split(placeholder).join(String(value));
+      replacedText = replacedText.split(placeholder).join(String(value))
     }
 
     // Rebuild the paragraph: merge all runs into a single run using first run's format
-    return this.#mergeRunsWithText(paragraphXml, runs, replacedText);
+    return this.#mergeRunsWithText(paragraphXml, runs, replacedText)
   }
 
   /**
@@ -176,25 +174,25 @@ class TemplateEngine {
    * @returns {Array<{xml: string, text: string, start: number, end: number}>}
    */
   #extractRuns(paragraphXml) {
-    const runs = [];
-    const runPattern = /(<a:r(?:\s[^>]*)?>)([\s\S]*?)(<\/a:r>)/g;
-    let match;
+    const runs = []
+    const runPattern = /(<a:r(?:\s[^>]*)?>)([\s\S]*?)(<\/a:r>)/g
+    let match
 
     while ((match = runPattern.exec(paragraphXml)) !== null) {
-      const runXml = match[0];
+      const runXml = match[0]
       // Extract text from <a:t>...</a:t> within this run
-      const tMatch = /<a:t>([\s\S]*?)<\/a:t>/.exec(runXml);
-      const text = tMatch ? this.#unescapeXml(tMatch[1]) : '';
+      const tMatch = /<a:t>([\s\S]*?)<\/a:t>/.exec(runXml)
+      const text = tMatch ? this.#unescapeXml(tMatch[1]) : ''
 
       runs.push({
         xml: runXml,
         text,
         start: match.index,
         end: match.index + runXml.length,
-      });
+      })
     }
 
-    return runs;
+    return runs
   }
 
   /**
@@ -208,25 +206,23 @@ class TemplateEngine {
    * @returns {string} Updated paragraph XML.
    */
   #mergeRunsWithText(paragraphXml, runs, newText) {
-    if (runs.length === 0) return paragraphXml;
+    if (runs.length === 0) return paragraphXml
 
     // Use the first run as the format template
-    const firstRun = runs[0];
+    const firstRun = runs[0]
 
     // Build the replacement run: first run's format + new text
-    const mergedRunXml = this.#setRunText(firstRun.xml, this.#escapeXml(newText));
+    const mergedRunXml = this.#setRunText(firstRun.xml, this.#escapeXml(newText))
 
     // Build new paragraph:
     // Keep everything before first run, insert merged run, remove the rest,
     // keep everything after last run
-    const firstRunStart = firstRun.start;
-    const lastRunEnd = runs[runs.length - 1].end;
+    const firstRunStart = firstRun.start
+    const lastRunEnd = runs[runs.length - 1].end
 
     return (
-      paragraphXml.substring(0, firstRunStart) +
-      mergedRunXml +
-      paragraphXml.substring(lastRunEnd)
-    );
+      paragraphXml.substring(0, firstRunStart) + mergedRunXml + paragraphXml.substring(lastRunEnd)
+    )
   }
 
   /**
@@ -238,12 +234,12 @@ class TemplateEngine {
    * @returns {string} Updated run XML.
    */
   #setRunText(runXml, text) {
-    const tPattern = /(<a:t>)([\s\S]*?)(<\/a:t>)/;
+    const tPattern = /(<a:t>)([\s\S]*?)(<\/a:t>)/
     if (tPattern.test(runXml)) {
-      return runXml.replace(tPattern, `$1${text}$3`);
+      return runXml.replace(tPattern, `$1${text}$3`)
     }
     // If no <a:t>, add one before </a:r>
-    return runXml.replace('</a:r>', `<a:t>${text}</a:t></a:r>`);
+    return runXml.replace('</a:r>', `<a:t>${text}</a:t></a:r>`)
   }
 
   /**
@@ -254,7 +250,7 @@ class TemplateEngine {
    * @returns {boolean}
    */
   containsPlaceholders(text, replacements) {
-    return Object.keys(replacements).some(p => text.includes(p));
+    return Object.keys(replacements).some(p => text.includes(p))
   }
 
   /**
@@ -269,24 +265,24 @@ class TemplateEngine {
    * // → ['{{title}}', '{{date}}', '{{company}}']
    */
   extractPlaceholders(xml, pattern = DEFAULT_PLACEHOLDER_PATTERN) {
-    const placeholders = new Set();
-    const textPattern = /<a:t>([\s\S]*?)<\/a:t>/g;
-    let match;
+    const placeholders = new Set()
+    const textPattern = /<a:t>([\s\S]*?)<\/a:t>/g
+    let match
 
     // Extract text content first, then find placeholders
-    const allText = [];
+    const allText = []
     while ((match = textPattern.exec(xml)) !== null) {
-      allText.push(match[1]);
+      allText.push(match[1])
     }
 
-    const combined = allText.join('');
-    const plPattern = new RegExp(pattern.source, 'g');
-    let plMatch;
+    const combined = allText.join('')
+    const plPattern = new RegExp(pattern.source, 'g')
+    let plMatch
     while ((plMatch = plPattern.exec(combined)) !== null) {
-      placeholders.add(plMatch[0]);
+      placeholders.add(plMatch[0])
     }
 
-    return Array.from(placeholders);
+    return Array.from(placeholders)
   }
 
   /**
@@ -301,7 +297,7 @@ class TemplateEngine {
       .replace(/</g, '&lt;')
       .replace(/>/g, '&gt;')
       .replace(/"/g, '&quot;')
-      .replace(/'/g, '&apos;');
+      .replace(/'/g, '&apos;')
   }
 
   /**
@@ -316,8 +312,8 @@ class TemplateEngine {
       .replace(/&lt;/g, '<')
       .replace(/&gt;/g, '>')
       .replace(/&quot;/g, '"')
-      .replace(/&apos;/g, "'");
+      .replace(/&apos;/g, "'")
   }
 }
 
-module.exports = { TemplateEngine };
+module.exports = { TemplateEngine }

package/src/core/ValidationEngine.js

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview ValidationEngine - Complete validation and checking engine for PowerPoint presentations.
+ */
+
+/**
+ * @class ValidationEngine
+ * @description Runs audits and verification checks on PPTX files.
+ */
+class ValidationEngine {
+  /**
+   * Validates the entire presentation.
+   *
+   * @param {PPTXTemplater} ppt - The presentation templater instance.
+   * @returns {Promise<Object>} Structured report.
+   */
+  static async validatePresentation(ppt) {
+    const errors = []
+    const warnings = []
+
+    // 1. Validate slides and references
+    const slides = ppt.slideManager.getAllSlideInfo()
+    for (const slide of slides) {
+      // Validate slide relationships
+      const relResult = this.validateRelationships(ppt, slide.zipPath)
+      errors.push(...relResult.errors.map(e => `Slide ${slide.index} relationship error: ${e}`))
+      warnings.push(
+        ...relResult.warnings.map(w => `Slide ${slide.index} relationship warning: ${w}`)
+      )
+
+      // Validate slide XML and elements
+      const slideResult = await this.validateSlide(ppt, slide.index)
+      errors.push(...slideResult.errors)
+      warnings.push(...slideResult.warnings)
+    }
+
+    // 2. Validate presentation level relationships
+    const presRelResult = this.validateRelationships(ppt, 'ppt/presentation.xml')
+    errors.push(...presRelResult.errors.map(e => `Presentation relationship error: ${e}`))
+    warnings.push(...presRelResult.warnings.map(w => `Presentation relationship warning: ${w}`))
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
+
+  /**
+   * Validates a single slide's XML and elements (like tables, shapes, charts).
+   *
+   * @param {PPTXTemplater} ppt
+   * @param {number} slideIndex
+   * @returns {Promise<Object>}
+   */
+  static async validateSlide(ppt, slideIndex) {
+    const errors = []
+    const warnings = []
+
+    try {
+      const slideXml = await ppt.slideManager.getSlideXmlAsync(slideIndex)
+
+      // Verify well-formed XML
+      const xmlCheck = ppt.xmlParser.validate(slideXml)
+      if (!xmlCheck.valid) {
+        errors.push(`Slide ${slideIndex} XML syntax error: ${xmlCheck.error}`)
+        return { valid: false, errors, warnings }
+      }
+
+      // Verify tables on the slide
+      const tables = ppt.tableManager.inspectTables(slideIndex, ppt.slideManager)
+      for (const table of tables) {
+        const tableResult = await this.validateTable(ppt, slideIndex, table.id)
+        errors.push(
+          ...tableResult.errors.map(e => `Slide ${slideIndex} Table "${table.name}": ${e}`)
+        )
+        warnings.push(
+          ...tableResult.warnings.map(w => `Slide ${slideIndex} Table "${table.name}": ${w}`)
+        )
+      }
+
+      // Verify charts on the slide
+      const charts = ppt.chartManager.getChartsInSlide(
+        slideIndex,
+        ppt.slideManager,
+        ppt.relationshipManager
+      )
+      for (const chart of charts) {
+        if (!ppt.zipManager.hasFile(chart.zipPath)) {
+          errors.push(
+            `Slide ${slideIndex} referenced chart file does not exist at ${chart.zipPath}`
+          )
+        }
+      }
+
+      // Verify image references on the slide
+      const images = ppt.imageManager.getImages(
+        slideIndex,
+        ppt.slideManager,
+        ppt.relationshipManager
+      )
+      for (const image of images) {
+        if (image.targetPath && !ppt.zipManager.hasFile(image.targetPath)) {
+          errors.push(
+            `Slide ${slideIndex} referenced image file does not exist at ${image.targetPath}`
+          )
+        }
+      }
+    } catch (err) {
+      errors.push(`Slide ${slideIndex} validation error: ${err.message}`)
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
+
+  /**
+   * Validates a table's XML and OpenXML conformity.
+   *
+   * @param {PPTXTemplater} ppt
+   * @param {number} slideIndex
+   * @param {string} tableId
+   * @returns {Promise<Object>}
+   */
+  static async validateTable(ppt, slideIndex, tableId) {
+    const errors = []
+    const warnings = []
+
+    try {
+      const slideXml = await ppt.slideManager.getSlideXmlAsync(slideIndex)
+      const slideObj = ppt.xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+
+      const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+      if (!spTree) {
+        errors.push('Slide shape tree not found')
+        return { valid: false, errors, warnings }
+      }
+
+      let frames = spTree['p:graphicFrame'] || []
+      if (!Array.isArray(frames)) frames = [frames]
+
+      let tbl = null
+      for (const frame of frames) {
+        const t = frame?.['a:graphic']?.['a:graphicData']?.['a:tbl']
+        if (!t) continue
+        const cNvPr = frame?.['p:nvGraphicFramePr']?.['p:cNvPr']
+        if (cNvPr && (cNvPr['@_name'] === tableId || String(cNvPr['@_id']) === tableId)) {
+          tbl = t
+          break
+        }
+      }
+
+      if (!tbl) {
+        errors.push(`Table "${tableId}" not found in slide object`)
+        return { valid: false, errors, warnings }
+      }
+
+      // Check cols against gridcols
+      const cols = tbl['a:tblGrid']?.['a:gridCol'] || []
+      const trs = tbl['a:tr'] || []
+
+      if (cols.length === 0) {
+        errors.push('Table column definitions (tblGrid) are missing')
+      }
+
+      // Check rowIds duplicate values
+      const rowIds = new Set()
+      trs.forEach((tr, rIdx) => {
+        const tcs = tr['a:tc'] || []
+        if (tcs.length !== cols.length) {
+          warnings.push(
+            `Row ${rIdx} cell count (${tcs.length}) does not match grid columns count (${cols.length})`
+          )
+        }
+
+        // Check for rowId
+        const ext = tr['a:extLst']?.['a:ext']
+        const exts = Array.isArray(ext) ? ext : [ext]
+        for (const e of exts) {
+          if (e?.['a16:rowId']) {
+            const val = e['a16:rowId']['@_val']
+            if (val) {
+              if (rowIds.has(val)) {
+                errors.push(`Duplicate a16:rowId "${val}" found at row index ${rIdx}`)
+              }
+              rowIds.add(val)
+            }
+          }
+        }
+      })
+    } catch (err) {
+      errors.push(`Table validation error: ${err.message}`)
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
+
+  /**
+   * Validates relationship mappings for a specific part.
+   *
+   * @param {PPTXTemplater} ppt
+   * @param {string} partPath
+   * @returns {Object}
+   */
+  static validateRelationships(ppt, partPath) {
+    const errors = []
+    const warnings = []
+
+    const relsPath = ppt.relationshipManager.getRelsPath(partPath)
+    if (!ppt.zipManager.hasFile(relsPath)) {
+      warnings.push(`Relationship file missing at ${relsPath}`)
+      return { valid: true, errors, warnings }
+    }
+
+    const rels = ppt.relationshipManager.getRelationships(partPath)
+    const relIds = new Set()
+
+    for (const rel of rels) {
+      if (relIds.has(rel.id)) {
+        errors.push(`Duplicate relationship ID "${rel.id}" inside ${relsPath}`)
+      }
+      relIds.add(rel.id)
+
+      if (rel.targetMode !== 'External') {
+        const resolved = ppt.relationshipManager.resolveTarget(partPath, rel.target)
+        if (!ppt.zipManager.hasFile(resolved)) {
+          errors.push(`Relationship ${rel.id} points to non-existent file: ${resolved}`)
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
+}
+
+module.exports = { ValidationEngine }

package/src/index.js

@@ -24,23 +24,32 @@
  * └─────────────────────────────────────────────────────────────┘
  */
 
-const { PPTXTemplater } = require('./core/PPTXTemplater.js');
-const { ZipManager } = require('./managers/ZipManager.js');
-const { XMLParser } = require('./parsers/XMLParser.js');
-const { SlideManager } = require('./managers/SlideManager.js');
-const { ChartManager } = require('./managers/ChartManager.js');
-const { TableManager } = require('./managers/TableManager.js');
-const { HyperlinkManager } = require('./managers/HyperlinkManager.js');
-const { MediaManager } = require('./managers/MediaManager.js');
-const { RelationshipManager } = require('./managers/RelationshipManager.js');
-const { OutputWriter } = require('./core/OutputWriter.js');
-const { TemplateEngine } = require('./core/TemplateEngine.js');
+const { PPTXTemplater } = require('./core/PPTXTemplater.js')
+const { ZipManager } = require('./managers/ZipManager.js')
+const { XMLParser } = require('./parsers/XMLParser.js')
+const { SlideManager } = require('./managers/SlideManager.js')
+const { ChartManager } = require('./managers/ChartManager.js')
+const { TableManager } = require('./managers/TableManager.js')
+const { ShapeManager } = require('./managers/ShapeManager.js')
+const { ImageManager } = require('./managers/ImageManager.js')
+const { TextManager } = require('./managers/TextManager.js')
+const { HyperlinkManager } = require('./managers/HyperlinkManager.js')
+const { MediaManager } = require('./managers/MediaManager.js')
+const { RelationshipManager } = require('./managers/RelationshipManager.js')
+const { OutputWriter } = require('./core/OutputWriter.js')
+const { TemplateEngine } = require('./core/TemplateEngine.js')
+const { ValidationEngine } = require('./core/ValidationEngine.js')
 
 // Utility exports
-const { generateRelationshipId, parseRelationshipId } = require('./utils/relationshipUtils.js');
-const { validateXML, repairXML } = require('./utils/xmlUtils.js');
-const { createLogger } = require('./utils/logger.js');
-const { PPTXError, SlideNotFoundError, ChartNotFoundError, TableNotFoundError } = require('./utils/errors.js');
+const { generateRelationshipId, parseRelationshipId } = require('./utils/relationshipUtils.js')
+const { validateXML, repairXML } = require('./utils/xmlUtils.js')
+const { createLogger } = require('./utils/logger.js')
+const {
+  PPTXError,
+  SlideNotFoundError,
+  ChartNotFoundError,
+  TableNotFoundError,
+} = require('./utils/errors.js')
 
 module.exports = {
   PPTXTemplater,
@@ -49,11 +58,15 @@ module.exports = {
   SlideManager,
   ChartManager,
   TableManager,
+  ShapeManager,
+  ImageManager,
+  TextManager,
   HyperlinkManager,
   MediaManager,
   RelationshipManager,
   OutputWriter,
   TemplateEngine,
+  ValidationEngine,
   generateRelationshipId,
   parseRelationshipId,
   validateXML,
@@ -62,5 +75,5 @@ module.exports = {
   PPTXError,
   SlideNotFoundError,
   ChartNotFoundError,
-  TableNotFoundError
-};
+  TableNotFoundError,
+}