@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/esm/modules/word/core/walker.js

@@ -0,0 +1,570 @@
+/**
+ * DOCX Module - Document Walker (Visitor Pattern)
+ *
+ * Unified traversal engine for the DocxDocument model. Provides a single,
+ * tested implementation of document tree walking that all consumers
+ * (renderers, validators, field engines, template engines, etc.) can use
+ * instead of each implementing their own recursive traversal.
+ *
+ * Design principles:
+ * - Visitor receives enter/leave callbacks for structural elements
+ * - Return "skip" to prune subtrees, "stop" to abort early
+ * - WalkPath provides full context (location, nesting depth, container)
+ * - Options control which parts of the document are visited
+ */
+import { isRun } from "./text-utils.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Walk an entire DocxDocument, calling visitor methods for each element.
+ *
+ * @param doc - The document to walk.
+ * @param visitor - Visitor with callbacks for elements of interest.
+ * @param options - Controls which document parts to include.
+ */
+export function walkDocument(doc, visitor, options) {
+    const opts = {
+        includeHeaders: options?.includeHeaders ?? true,
+        includeFooters: options?.includeFooters ?? true,
+        includeFootnotes: options?.includeFootnotes ?? true,
+        includeEndnotes: options?.includeEndnotes ?? true,
+        includeComments: options?.includeComments ?? false
+    };
+    const basePath = {
+        section: 0,
+        depth: 0,
+        inHeader: false,
+        inFooter: false,
+        inFootnote: false,
+        inEndnote: false,
+        inComment: false,
+        index: 0
+    };
+    // Walk body
+    if (walkBlocks(doc.body, visitor, basePath) === "stop") {
+        return;
+    }
+    // Walk headers
+    if (opts.includeHeaders && doc.headers) {
+        for (const [, headerDef] of doc.headers) {
+            const headerPath = { ...basePath, inHeader: true };
+            if (walkBlocks(headerDef.content.children, visitor, headerPath) ===
+                "stop") {
+                return;
+            }
+        }
+    }
+    // Walk footers
+    if (opts.includeFooters && doc.footers) {
+        for (const [, footerDef] of doc.footers) {
+            const footerPath = { ...basePath, inFooter: true };
+            if (walkBlocks(footerDef.content.children, visitor, footerPath) ===
+                "stop") {
+                return;
+            }
+        }
+    }
+    // Walk footnotes
+    if (opts.includeFootnotes && doc.footnotes) {
+        for (const note of doc.footnotes) {
+            if (note.id <= 0) {
+                continue;
+            } // Skip separator footnotes
+            const notePath = { ...basePath, inFootnote: true };
+            if (walkBlocks(note.content, visitor, notePath) === "stop") {
+                return;
+            }
+        }
+    }
+    // Walk endnotes
+    if (opts.includeEndnotes && doc.endnotes) {
+        for (const note of doc.endnotes) {
+            if (note.id <= 0) {
+                continue;
+            }
+            const notePath = { ...basePath, inEndnote: true };
+            if (walkBlocks(note.content, visitor, notePath) === "stop") {
+                return;
+            }
+        }
+    }
+    // Walk comments
+    if (opts.includeComments && doc.comments) {
+        for (const comment of doc.comments) {
+            const commentPath = { ...basePath, inComment: true };
+            if (walkBlocks(comment.content, visitor, commentPath) === "stop") {
+                return;
+            }
+        }
+    }
+}
+/**
+ * Walk a list of body content blocks (useful for walking sub-documents).
+ *
+ * @param blocks - Body content array to walk.
+ * @param visitor - Visitor with callbacks.
+ * @param basePath - Optional initial path context.
+ * @returns "stop" if traversal was aborted, "continue" otherwise.
+ */
+export function walkBlocks(blocks, visitor, basePath) {
+    const path = basePath ?? {
+        section: 0,
+        depth: 0,
+        inHeader: false,
+        inFooter: false,
+        inFootnote: false,
+        inEndnote: false,
+        inComment: false,
+        index: 0
+    };
+    let section = path.section;
+    for (let i = 0; i < blocks.length; i++) {
+        const block = blocks[i];
+        const currentPath = { ...path, section, index: i };
+        const result = walkBodyContent(block, visitor, currentPath);
+        if (result === "stop") {
+            return "stop";
+        }
+        // A paragraph with sectionProperties marks the end of the current section
+        if (block.type === "paragraph" && block.properties?.sectionProperties && path.depth === 0) {
+            section++;
+        }
+    }
+    return "continue";
+}
+// =============================================================================
+// Internal Traversal
+// =============================================================================
+/**
+ * Maximum nesting depth permitted during traversal. Documents that
+ * legitimately nest content rarely exceed depth ~50; anything beyond
+ * `MAX_WALK_DEPTH` is almost certainly a hostile or malformed input
+ * trying to provoke a stack overflow. Hitting this limit aborts the
+ * walk gracefully (returning `"continue"`) instead of crashing the host.
+ */
+const MAX_WALK_DEPTH = 1000;
+function walkBodyContent(block, visitor, path) {
+    if (path.depth > MAX_WALK_DEPTH) {
+        return "continue";
+    }
+    switch (block.type) {
+        case "paragraph":
+            return walkParagraph(block, visitor, path);
+        case "table":
+            return walkTable(block, visitor, path);
+        case "sdt":
+            return walkSdt(block, visitor, path);
+        case "math":
+            return walkMathBlock(block, visitor, path);
+        case "floatingImage":
+            visitor.visitFloatingImage?.(block, path);
+            return "continue";
+        case "textBox": {
+            const tb = block;
+            const action = visitor.visitTextBox?.(tb, path);
+            if (action === "stop") {
+                return "stop";
+            }
+            if (action === "skip") {
+                return "continue";
+            }
+            if (tb.content) {
+                const innerPath = { ...path, depth: path.depth + 1 };
+                if (walkBlocks(tb.content, visitor, innerPath) === "stop") {
+                    return "stop";
+                }
+            }
+            return "continue";
+        }
+        case "tableOfContents": {
+            const toc = block;
+            visitor.visitTableOfContents?.(toc, path);
+            // Recurse into the cached paragraph rendering so consumers (text
+            // extraction, search/replace, validation) actually see the textual
+            // body of a TOC. The model documents this as "cached content used
+            // when fields are not updated".
+            if (toc.cachedParagraphs && toc.cachedParagraphs.length > 0) {
+                const innerPath = { ...path, depth: path.depth + 1 };
+                if (walkBlocks(toc.cachedParagraphs, visitor, innerPath) === "stop") {
+                    return "stop";
+                }
+            }
+            return "continue";
+        }
+        case "altChunk":
+            visitor.visitAltChunk?.(block, path);
+            return "continue";
+        case "chart":
+            visitor.visitChart?.(block, path);
+            return "continue";
+        case "chartEx":
+            visitor.visitChartEx?.(block, path);
+            return "continue";
+        case "checkBox":
+            visitor.visitCheckBox?.(block, path);
+            return "continue";
+        case "drawingShape": {
+            const shape = block;
+            visitor.visitDrawingShape?.(shape, path);
+            // Shapes can carry their own paragraph text (textContent). Walking
+            // it lets text-aware visitors find shape-embedded text — without
+            // this, replaceText/searchText silently skip them.
+            if (shape.textContent && shape.textContent.length > 0) {
+                const innerPath = { ...path, depth: path.depth + 1 };
+                if (walkBlocks(shape.textContent, visitor, innerPath) === "stop") {
+                    return "stop";
+                }
+            }
+            return "continue";
+        }
+        case "opaqueDrawing":
+            visitor.visitOpaqueDrawing?.(block, path);
+            return "continue";
+        default:
+            return "continue";
+    }
+}
+function walkParagraph(para, visitor, path) {
+    const action = visitor.enterParagraph?.(para, path);
+    if (action === "stop") {
+        return "stop";
+    }
+    if (action === "skip") {
+        visitor.leaveParagraph?.(para, path);
+        return "continue";
+    }
+    // Walk children
+    for (let i = 0; i < para.children.length; i++) {
+        const child = para.children[i];
+        const childPath = { ...path, index: i, depth: path.depth + 1 };
+        const result = walkParagraphChild(child, visitor, childPath);
+        if (result === "stop") {
+            return "stop";
+        }
+    }
+    visitor.leaveParagraph?.(para, path);
+    return "continue";
+}
+function walkParagraphChild(child, visitor, path) {
+    // Type-discriminated dispatch
+    if ("type" in child) {
+        const typed = child;
+        switch (typed.type) {
+            case "hyperlink":
+                return walkHyperlink(child, visitor, path);
+            case "insertedRun": {
+                const ins = child;
+                const action = visitor.visitInsertedRun?.(ins, path);
+                if (action === "stop") {
+                    return "stop";
+                }
+                if (action === "skip") {
+                    return "continue";
+                }
+                // Walk the inner run
+                return walkRun(ins.run, visitor, path);
+            }
+            case "deletedRun":
+                visitor.visitDeletedRun?.(child, path);
+                return "continue";
+            case "movedFromRun":
+                visitor.visitMovedFromRun?.(child, path);
+                return "continue";
+            case "movedToRun": {
+                const moved = child;
+                const action = visitor.visitMovedToRun?.(moved, path);
+                if (action === "stop") {
+                    return "stop";
+                }
+                if (action === "skip") {
+                    return "continue";
+                }
+                return walkRun(moved.run, visitor, path);
+            }
+            case "bookmarkStart":
+                visitor.visitBookmarkStart?.(child, path);
+                return "continue";
+            case "bookmarkEnd":
+                visitor.visitBookmarkEnd?.(child.id, path);
+                return "continue";
+            case "commentRangeStart":
+                visitor.visitCommentRangeStart?.(child, path);
+                return "continue";
+            case "commentRangeEnd":
+                visitor.visitCommentRangeEnd?.(child, path);
+                return "continue";
+            default:
+                // Unknown typed child — might be a Run with a `type` property on content
+                break;
+        }
+    }
+    // Default: treat as Run if it has `content` array
+    if (isRun(child)) {
+        return walkRun(child, visitor, path);
+    }
+    return "continue";
+}
+function walkRun(run, visitor, path) {
+    const action = visitor.enterRun?.(run, path);
+    if (action === "stop") {
+        return "stop";
+    }
+    if (action === "skip") {
+        visitor.leaveRun?.(run, path);
+        return "continue";
+    }
+    // Walk run content
+    if (visitor.visitRunContent) {
+        for (const content of run.content) {
+            visitor.visitRunContent(content, run, path);
+        }
+    }
+    visitor.leaveRun?.(run, path);
+    return "continue";
+}
+function walkHyperlink(hl, visitor, path) {
+    const action = visitor.enterHyperlink?.(hl, path);
+    if (action === "stop") {
+        return "stop";
+    }
+    if (action === "skip") {
+        visitor.leaveHyperlink?.(hl, path);
+        return "continue";
+    }
+    for (let i = 0; i < hl.children.length; i++) {
+        const child = hl.children[i];
+        const childPath = { ...path, index: i, depth: path.depth + 1 };
+        const result = walkParagraphChild(child, visitor, childPath);
+        if (result === "stop") {
+            return "stop";
+        }
+    }
+    visitor.leaveHyperlink?.(hl, path);
+    return "continue";
+}
+function walkTable(table, visitor, path) {
+    const action = visitor.enterTable?.(table, path);
+    if (action === "stop") {
+        return "stop";
+    }
+    if (action === "skip") {
+        visitor.leaveTable?.(table, path);
+        return "continue";
+    }
+    for (let ri = 0; ri < table.rows.length; ri++) {
+        const row = table.rows[ri];
+        const rowPath = { ...path, index: ri, depth: path.depth + 1 };
+        const rowAction = visitor.enterTableRow?.(row, rowPath);
+        if (rowAction === "stop") {
+            return "stop";
+        }
+        if (rowAction === "skip") {
+            visitor.leaveTableRow?.(row, rowPath);
+            continue;
+        }
+        for (let ci = 0; ci < row.cells.length; ci++) {
+            const cell = row.cells[ci];
+            const cellPath = { ...rowPath, index: ci, depth: rowPath.depth + 1 };
+            const cellAction = visitor.enterTableCell?.(cell, cellPath);
+            if (cellAction === "stop") {
+                return "stop";
+            }
+            if (cellAction === "skip") {
+                visitor.leaveTableCell?.(cell, cellPath);
+                continue;
+            }
+            // Walk cell content (paragraphs and nested tables)
+            if (walkBlocks(cell.content, visitor, {
+                ...cellPath,
+                depth: cellPath.depth + 1
+            }) === "stop") {
+                return "stop";
+            }
+            visitor.leaveTableCell?.(cell, cellPath);
+        }
+        visitor.leaveTableRow?.(row, rowPath);
+    }
+    visitor.leaveTable?.(table, path);
+    return "continue";
+}
+function walkSdt(sdt, visitor, path) {
+    const action = visitor.enterSdt?.(sdt, path);
+    if (action === "stop") {
+        return "stop";
+    }
+    if (action === "skip") {
+        visitor.leaveSdt?.(sdt, path);
+        return "continue";
+    }
+    // SDT.content is `(Paragraph | Run | Table)[]`. Inline (run-only) SDTs
+    // are common — content controls wrapping a single Run inside a paragraph.
+    // Previously this filter dropped them entirely, so search/replace, text
+    // extraction, and template engines silently missed text inside inline
+    // SDTs. Walk runs through walkParagraphChild so they get the same run
+    // visitor treatment as runs in any other paragraph.
+    const innerPath = { ...path, depth: path.depth + 1 };
+    for (let i = 0; i < sdt.content.length; i++) {
+        const item = sdt.content[i];
+        const itemPath = { ...innerPath, index: i };
+        if ("type" in item && (item.type === "paragraph" || item.type === "table")) {
+            const result = walkBodyContent(item, visitor, itemPath);
+            if (result === "stop") {
+                return "stop";
+            }
+        }
+        else if ("type" in item && item.type === "sdt") {
+            // Nested SDT — recurse so visitors see the inner content controls.
+            const result = walkSdt(item, visitor, itemPath);
+            if (result === "stop") {
+                return "stop";
+            }
+        }
+        else if (!("type" in item) && isRun(item)) {
+            const result = walkRun(item, visitor, itemPath);
+            if (result === "stop") {
+                return "stop";
+            }
+        }
+    }
+    visitor.leaveSdt?.(sdt, path);
+    return "continue";
+}
+function walkMathBlock(math, visitor, path) {
+    const action = visitor.enterMathBlock?.(math, path);
+    if (action === "stop") {
+        return "stop";
+    }
+    if (action === "skip") {
+        visitor.leaveMathBlock?.(math, path);
+        return "continue";
+    }
+    if (visitor.visitMathContent) {
+        walkMathContentArray(math.content, visitor, path);
+    }
+    visitor.leaveMathBlock?.(math, path);
+    return "continue";
+}
+function walkMathContentArray(contents, visitor, path) {
+    for (const content of contents) {
+        visitor.visitMathContent(content, path);
+        // Recursively walk sub-content
+        switch (content.type) {
+            case "mathFraction":
+                walkMathContentArray(content.numerator, visitor, path);
+                walkMathContentArray(content.denominator, visitor, path);
+                break;
+            case "mathRadical":
+                if (content.degree) {
+                    walkMathContentArray(content.degree, visitor, path);
+                }
+                walkMathContentArray(content.content, visitor, path);
+                break;
+            case "mathSuperScript":
+                walkMathContentArray(content.base, visitor, path);
+                walkMathContentArray(content.superScript, visitor, path);
+                break;
+            case "mathSubScript":
+                walkMathContentArray(content.base, visitor, path);
+                walkMathContentArray(content.subScript, visitor, path);
+                break;
+            case "mathSubSuperScript":
+                walkMathContentArray(content.base, visitor, path);
+                walkMathContentArray(content.subScript, visitor, path);
+                walkMathContentArray(content.superScript, visitor, path);
+                break;
+            case "mathPreSubSuperScript":
+                walkMathContentArray(content.base, visitor, path);
+                walkMathContentArray(content.preSubScript, visitor, path);
+                walkMathContentArray(content.preSuperScript, visitor, path);
+                break;
+            case "mathDelimiter":
+                for (const group of content.content) {
+                    walkMathContentArray(group, visitor, path);
+                }
+                break;
+            case "mathNary":
+                if (content.sub) {
+                    walkMathContentArray(content.sub, visitor, path);
+                }
+                if (content.sup) {
+                    walkMathContentArray(content.sup, visitor, path);
+                }
+                walkMathContentArray(content.content, visitor, path);
+                break;
+            case "mathFunction":
+                walkMathContentArray(content.name, visitor, path);
+                walkMathContentArray(content.content, visitor, path);
+                break;
+            case "mathLimit":
+                walkMathContentArray(content.base, visitor, path);
+                walkMathContentArray(content.limit, visitor, path);
+                break;
+            case "mathMatrix":
+                for (const row of content.rows) {
+                    for (const cell of row) {
+                        walkMathContentArray(cell, visitor, path);
+                    }
+                }
+                break;
+            case "mathAccent":
+            case "mathBar":
+            case "mathBox":
+            case "mathPhantom":
+            case "mathBorderBox":
+                walkMathContentArray(content.content, visitor, path);
+                break;
+            case "mathGroupChar":
+                walkMathContentArray(content.base, visitor, path);
+                break;
+            case "mathEquationArray":
+                for (const row of content.rows) {
+                    walkMathContentArray(row, visitor, path);
+                }
+                break;
+            // mathRun has no children
+        }
+    }
+}
+// =============================================================================
+// Convenience Collectors
+// =============================================================================
+/**
+ * Collect all paragraphs from a document (including nested in tables/SDTs).
+ */
+export function collectParagraphs(doc, options) {
+    const result = [];
+    walkDocument(doc, {
+        enterParagraph(para) {
+            result.push(para);
+            return "continue";
+        }
+    }, options);
+    return result;
+}
+/**
+ * Collect all runs from a document (including nested).
+ */
+export function collectRuns(doc, options) {
+    const result = [];
+    walkDocument(doc, {
+        enterRun(run) {
+            result.push(run);
+            return "continue";
+        }
+    }, options);
+    return result;
+}
+/**
+ * Collect all tables from a document (including nested).
+ */
+export function collectTables(doc, options) {
+    const result = [];
+    walkDocument(doc, {
+        enterTable(table) {
+            result.push(table);
+            return "continue";
+        }
+    }, options);
+    return result;
+}

package/dist/esm/modules/word/crypto.js

@@ -1,18 +1,24 @@
 /**
- * DOCX Module - Encryption & Digital Signatures (Subpath Export)
+ * DOCX Module - Encryption & Digital Signatures (Subpath Entry)
  *
- * Import separately to avoid pulling crypto code into the bundle
- * when only core document building is needed.
+ * Public API at `excelts/word/crypto`. Referenced by
+ * `package.json#exports["./word/crypto"]`. Import this subpath separately to
+ * keep encryption / CFB / signature / font obfuscation code out of bundles
+ * that only need core document building.
  *
  * @example
  * ```ts
- * import { isEncryptedDocx, decryptPackage } from "excelts/word/crypto";
+ * import { isEncryptedDocx, decryptDocx, encryptDocx } from "excelts/word/crypto";
  * import { extractSignatures } from "excelts/word/crypto";
  * ```
  */
 // Encryption utilities
-export { isEncryptedDocx, verifyPassword, decryptPackage, parseEncryptionInfoXml, deriveEncryptionKey, AGILE_BLOCK_KEYS } from "./encryption.js";
+export { isEncryptedDocx, verifyPassword, decryptPackage, decryptDocx, encryptDocx, parseEncryptionInfoXml, deriveEncryptionKey, AGILE_BLOCK_KEYS } from "./security/encryption.js";
+// Encryption error type (also exported from main entry)
+export { DocxEncryptedError } from "./errors.js";
+// CFB (Compound File Binary) reader/writer
+export { readCfb, writeCfb } from "./security/cfb-reader.js";
 // Digital signature utilities
-export { hasDigitalSignatures, parseSignatureXml, extractSignatures, isWellFormedSignature } from "./digital-signatures.js";
+export { hasDigitalSignatures, parseSignatureXml, extractSignatures, isWellFormedSignature } from "./security/digital-signatures.js";
 // Font obfuscation utilities
-export { deobfuscateFont, obfuscateFont, generateFontKey } from "./font-obfuscation.js";
+export { deobfuscateFont, obfuscateFont, generateFontKey } from "./font/font-obfuscation.js";