UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

577 lines • 24.9 kB
import AdmZip from 'adm-zip'; import { writeFileSync } from 'node:fs'; import { DOMParser, XMLSerializer } from '@xmldom/xmldom'; import { replaceParagraphTextRange, getParagraphText, SafeDocxError, } from '@usejunior/docx-core'; import { copyEntriesSkippingDirs, enumerateTextParts, getGeneralTextPartNames, preserveXmlSpace } from './ooxml-parts.js'; import { parseReplacementKey, resolveReplacementValue } from './replacement-keys.js'; const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'; /** * Normalize smart/typographic quotes to ASCII equivalents for matching. * Uses the same canonical quote set as verifier's normalizeText(). * This is a 1-to-1 character mapping so charMap positions remain valid. */ export function normalizeQuotes(text) { return text .replace(/[\u2018\u2019\u2039\u203A]/g, "'") .replace(/[\u201C\u201D\u201A\u201E\u00AB\u00BB]/g, '"'); } /** Maximum replacement iterations per key per paragraph to prevent infinite loops. */ const MAX_REPLACEMENTS_PER_KEY = 200; /** * Element local names that indicate a run is NOT safe to remove even if its text is empty. * These are non-text children that carry visual or structural meaning. */ const UNSAFE_RUN_CHILDREN = new Set([ 'drawing', 'pict', 'object', 'fldChar', 'instrText', 'br', 'cr', 'tab', 'footnoteReference', 'endnoteReference', ]); export async function patchDocument(inputPath, outputPath, replacements, options) { const zip = new AdmZip(inputPath); const parser = new DOMParser(); const serializer = new XMLSerializer(); const parts = enumerateTextParts(zip); const partNames = getGeneralTextPartNames(parts); if (partNames.length === 0) { throw new Error('No OOXML text parts found in DOCX'); } // Parse and classify all keys, normalizing smart quotes const parsedKeys = []; for (const [key, rawValue] of Object.entries(replacements)) { const value = resolveReplacementValue(rawValue); const parsed = parseReplacementKey(key, value); // Normalize smart quotes in search text and context for matching if (parsed.type === 'context') { parsed.searchText = normalizeQuotes(parsed.searchText); parsed.context = normalizeQuotes(parsed.context); } else { parsed.searchText = normalizeQuotes(parsed.searchText); } parsedKeys.push(parsed); } // Deduplicate keys that collide after quote normalization const seenSearchKeys = new Map(); const deduplicatedKeys = []; for (const pk of parsedKeys) { const dedupKey = pk.type === 'context' ? `${pk.context} > ${pk.searchText}` : pk.searchText; const existing = seenSearchKeys.get(dedupKey); if (existing) { if (existing.value !== pk.value) { console.warn(`Patcher: quote-normalized key collision for "${dedupKey}" with different values`); } // Skip duplicate } else { seenSearchKeys.set(dedupKey, pk); deduplicatedKeys.push(pk); } } // Separate by type and sort const contextKeys = deduplicatedKeys .filter((k) => k.type === 'context') .sort((a, b) => b.searchText.length - a.searchText.length); const simpleKeys = deduplicatedKeys .filter((k) => k.type === 'simple') .sort((a, b) => b.searchText.length - a.searchText.length); // Track which parts we modify so we can rebuild the zip cleanly const modifiedParts = new Map(); // A key counts as matched only when its actual replacement operation runs. // Bare search text elsewhere in the document is not evidence that a // context-qualified key satisfied its directional anchor. const matchedKeyLabels = new Set(); for (const partName of partNames) { const entry = zip.getEntry(partName); if (!entry) continue; const xml = entry.getData().toString('utf-8'); const doc = parser.parseFromString(xml, 'text/xml'); const allParagraphs = doc.getElementsByTagNameNS(W_NS, 'p'); // Phase 1: Context keys for (const ck of contextKeys) { for (let i = 0; i < allParagraphs.length; i++) { const para = allParagraphs[i]; const paraText = getParagraphText(para); if (!paraText) continue; const normalizedText = normalizeQuotes(paraText); if (!normalizedText.includes(ck.searchText)) continue; const rowContext = getTableRowContext(para); if (rowContext !== null) { const normalizedRowContext = normalizeQuotes(rowContext); if (!normalizedRowContext.includes(ck.context)) continue; const matched = replaceInParagraph(para, { [ck.searchText]: ck.value }, [ck.searchText], options?.replacementColor); if (matched.has(ck.searchText)) { matchedKeyLabels.add(`${ck.context} > ${ck.searchText}`); } } else { if (!normalizedText.includes(ck.context)) continue; if (replaceFirstAfterContext(para, ck.searchText, ck.context, ck.value, options?.replacementColor)) { matchedKeyLabels.add(`${ck.context} > ${ck.searchText}`); } } } } // Phase 2: Simple keys if (simpleKeys.length > 0) { const simpleReplacements = {}; const simpleSortedKeys = []; for (const sk of simpleKeys) { simpleReplacements[sk.searchText] = sk.value; simpleSortedKeys.push(sk.searchText); } for (let i = 0; i < allParagraphs.length; i++) { for (const key of replaceInParagraph(allParagraphs[i], simpleReplacements, simpleSortedKeys, options?.replacementColor)) { matchedKeyLabels.add(key); } } } modifiedParts.set(partName, Buffer.from(serializer.serializeToString(doc), 'utf-8')); } const zeroMatchKeys = []; for (const pk of deduplicatedKeys) { const keyLabel = pk.type === 'context' ? `${pk.context} > ${pk.searchText}` : pk.searchText; if (!matchedKeyLabels.has(keyLabel)) { zeroMatchKeys.push(keyLabel); } } // Rebuild the zip from scratch using addFile() to avoid adm-zip data // descriptor issues. Some DOCX files use streaming (bit 3) flags which // adm-zip's updateFile/writeZip/toBuffer handle incorrectly. const outZip = new AdmZip(); copyEntriesSkippingDirs(zip, outZip, (entryName, entryData) => modifiedParts.get(entryName) ?? entryData); writeFileSync(outputPath, outZip.toBuffer()); return { outputPath, zeroMatchKeys }; } /** * Get the text content of the first table cell (label cell) in the same row * as the paragraph. Returns null if the paragraph is not inside a table cell. */ export function getTableRowContext(para) { // Walk up to find the containing <w:tr> let node = para.parentNode; let inTc = false; while (node) { const el = node; if (el.localName === 'tc' && el.namespaceURI === W_NS) { inTc = true; } if (el.localName === 'tr' && el.namespaceURI === W_NS) { if (!inTc) return null; // para wasn't in a table cell // Get the first <w:tc> in this row const children = el.childNodes; for (let i = 0; i < children.length; i++) { const child = children[i]; if (child.localName === 'tc' && child.namespaceURI === W_NS) { return extractCellText(child); } } return null; } node = node.parentNode; } return null; } function extractCellText(tc) { const tElements = tc.getElementsByTagNameNS(W_NS, 't'); const parts = []; for (let i = 0; i < tElements.length; i++) { parts.push(tElements[i].textContent ?? ''); } return parts.join('').trim(); } function buildCharMap(runs) { const charMap = []; let fullText = ''; for (let runIndex = 0; runIndex < runs.length; runIndex++) { const text = getRunText(runs[runIndex]); for (let offset = 0; offset < text.length; offset++) { charMap.push({ runIndex, charOffset: offset }); } fullText += text; } return { fullText, charMap }; } export function getRunText(run) { const tElements = run.getElementsByTagNameNS(W_NS, 't'); let text = ''; for (let i = 0; i < tElements.length; i++) { text += tElements[i].textContent ?? ''; } return text; } /** * Set <w:color w:val="..."/> on a run's <w:rPr>. Creates <w:rPr> if absent. * Overwrites any existing <w:color>. */ function setRunColor(run, colorHex) { const doc = run.ownerDocument; let rPr = null; // Find existing <w:rPr> const children = run.childNodes; for (let i = 0; i < children.length; i++) { const child = children[i]; if (child.localName === 'rPr' && child.namespaceURI === W_NS) { rPr = child; break; } } if (!rPr) { rPr = doc.createElementNS(W_NS, 'w:rPr'); run.insertBefore(rPr, run.firstChild); } // Find or create <w:color> const rPrChildren = rPr.childNodes; for (let i = 0; i < rPrChildren.length; i++) { const prop = rPrChildren[i]; if (prop.localName === 'color' && prop.namespaceURI === W_NS) { prop.setAttributeNS(W_NS, 'w:val', colorHex); return; } } const color = doc.createElementNS(W_NS, 'w:color'); color.setAttributeNS(W_NS, 'w:val', colorHex); rPr.appendChild(color); } function setRunText(run, text) { const tElements = run.getElementsByTagNameNS(W_NS, 't'); if (tElements.length === 0) { const doc = run.ownerDocument; const t = doc.createElementNS(W_NS, 'w:t'); preserveXmlSpace(t); t.textContent = text; run.appendChild(t); return; } tElements[0].textContent = text; if (text.startsWith(' ') || text.endsWith(' ')) { preserveXmlSpace(tElements[0]); } for (let i = 1; i < tElements.length; i++) { tElements[i].textContent = ''; } } /** * Collect all <w:r> elements in document order within a paragraph, including * runs nested inside wrapper elements like <w:hyperlink>, <w:ins>, <w:del>, etc. */ function getRunElements(para) { const runs = []; collectRunsRecursive(para, runs); return runs; } function collectRunsRecursive(node, runs) { const children = node.childNodes; if (!children) return; for (let i = 0; i < children.length; i++) { const child = children[i]; if (child.nodeType !== 1) continue; const el = child; if (el.localName === 'r' && el.namespaceURI === W_NS) { runs.push(el); } else if (el.localName !== 'p') { // Recurse into wrapper elements (hyperlink, ins, del, smartTag, etc.) // but don't recurse into nested paragraphs collectRunsRecursive(el, runs); } } } /** * Check if a run is safe to remove when its text is empty. * Returns true only if all element children are <w:rPr> or <w:t>. * Returns false if the run contains drawings, fields, breaks, or other non-text elements. */ export function isRunSafeToRemove(run) { const children = run.childNodes; if (!children) return true; for (let i = 0; i < children.length; i++) { const child = children[i]; if (child.nodeType !== 1) continue; // skip text/comment nodes const name = child.localName; if (!name) return false; if (name === 'rPr' || name === 't') continue; if (UNSAFE_RUN_CHILDREN.has(name)) return false; // Any other element child we don't recognize — not safe return false; } return true; } /** * Legacy charMap-based splice: replace `searchTextLength` characters starting at * `matchStart` with `value`, cleaning up empty runs afterwards. * Used as a fallback when replaceParagraphTextRange throws UNSAFE_CONTAINER_BOUNDARY * (e.g. replacements spanning across hyperlinks or SDTs) or UNSUPPORTED_EDIT * (e.g. replacement spans field results). */ function replaceAtPositionLegacy(runs, charMap, matchStart, searchTextLength, value, replacementColor) { const end = matchStart + searchTextLength; const firstEntry = charMap[matchStart]; const lastEntry = charMap[end - 1]; // A complex Word field is an atomic OOXML construct. Its instruction runs // have no visible characters, while its cached-result runs do, so a // character-range edit can otherwise clear only the result and leave // begin/instr/separate/end behind. Word or LibreOffice will then regenerate // the deleted result on refresh (or display a broken-reference error). // // Expand an intersecting edit to every enclosing field boundary. The loop is // deliberate: expanding across one field can intersect an outer/nested field. let expandedStart = firstEntry.runIndex; let expandedEnd = lastEntry.runIndex; const fieldRanges = getComplexFieldRunRanges(runs); let expanded; do { expanded = false; for (const field of fieldRanges) { if (field.end < expandedStart || field.start > expandedEnd) continue; const nextStart = Math.min(expandedStart, field.start); const nextEnd = Math.max(expandedEnd, field.end); if (nextStart !== expandedStart || nextEnd !== expandedEnd) { expandedStart = nextStart; expandedEnd = nextEnd; expanded = true; } } } while (expanded); if (expandedStart !== firstEntry.runIndex || expandedEnd !== lastEntry.runIndex || fieldRanges.some(field => field.start <= expandedEnd && field.end >= expandedStart)) { replaceExpandedAtomicRange(runs, firstEntry, lastEntry, expandedStart, expandedEnd, value, replacementColor); return; } if (firstEntry.runIndex === lastEntry.runIndex) { const runText = getRunText(runs[firstEntry.runIndex]); setRunText(runs[firstEntry.runIndex], runText.slice(0, firstEntry.charOffset) + value + runText.slice(lastEntry.charOffset + 1)); } else { const firstRunText = getRunText(runs[firstEntry.runIndex]); setRunText(runs[firstEntry.runIndex], firstRunText.slice(0, firstEntry.charOffset) + value); const lastRunText = getRunText(runs[lastEntry.runIndex]); setRunText(runs[lastEntry.runIndex], lastRunText.slice(lastEntry.charOffset + 1)); for (let mid = firstEntry.runIndex + 1; mid < lastEntry.runIndex; mid++) { setRunText(runs[mid], ''); } } if (replacementColor) { setRunColor(runs[firstEntry.runIndex], replacementColor); } // Sweep: remove empty runs that are safe to remove for (let i = runs.length - 1; i >= 0; i--) { if (getRunText(runs[i]) === '' && isRunSafeToRemove(runs[i])) { runs[i].parentNode?.removeChild(runs[i]); } } } /** Pair complex-field begin/end markers in run order, retaining nested pairs. */ function getComplexFieldRunRanges(runs) { const stack = []; const ranges = []; for (let i = 0; i < runs.length; i++) { const chars = runs[i].getElementsByTagNameNS(W_NS, 'fldChar'); for (let j = 0; j < chars.length; j++) { const type = chars[j].getAttributeNS(W_NS, 'fldCharType') || chars[j].getAttribute('w:fldCharType'); if (type === 'begin') { stack.push(i); } else if (type === 'end') { const start = stack.pop(); if (start !== undefined) ranges.push({ start, end: i }); } } } return ranges; } /** * Replace an edit expanded across one or more complete field complexes. * Keep boundary text in its original runs/containers and remove intersected * field instructions/results. Only the replacement inherits the first matched * run's formatting; untouched semantic children retain their document order. */ function replaceExpandedAtomicRange(runs, firstEntry, lastEntry, expandedStart, expandedEnd, value, replacementColor) { const firstText = getRunText(runs[firstEntry.runIndex]); const lastText = getRunText(runs[lastEntry.runIndex]); const prefix = expandedStart === firstEntry.runIndex ? firstText.slice(0, firstEntry.charOffset) : ''; const suffix = expandedEnd === lastEntry.runIndex ? lastText.slice(lastEntry.charOffset + 1) : ''; if (firstEntry.runIndex === lastEntry.runIndex && prefix && suffix) { throw new Error('Unsupported atomic field replacement: both boundary fragments share one run'); } if (prefix && Array.from(runs[firstEntry.runIndex].childNodes).some(child => child.nodeType === 1 && !['rPr', 't'].includes(child.localName ?? ''))) { throw new Error('Unsupported atomic field replacement: semantic children share the prefix boundary run'); } const anchor = runs[expandedStart]; const parent = anchor.parentNode; if (!parent) return; const doc = anchor.ownerDocument; if (value !== '') { const replacementRun = doc.createElementNS(W_NS, 'w:r'); const sourceRPr = runs[firstEntry.runIndex].getElementsByTagNameNS(W_NS, 'rPr')[0]; if (sourceRPr) replacementRun.appendChild(sourceRPr.cloneNode(true)); const text = doc.createElementNS(W_NS, 'w:t'); preserveXmlSpace(text); text.textContent = value; replacementRun.appendChild(text); if (replacementColor) setRunColor(replacementRun, replacementColor); if (prefix) { const boundary = runs[firstEntry.runIndex]; boundary.parentNode.insertBefore(replacementRun, boundary.nextSibling); } else { parent.insertBefore(replacementRun, anchor); } } for (let i = expandedEnd; i >= expandedStart; i--) { const run = runs[i]; let offset = 0; for (const child of Array.from(run.childNodes)) { if (child.nodeType !== 1) continue; const element = child; if (element.namespaceURI !== W_NS) continue; if (element.localName === 't') { const original = element.textContent ?? ''; const start = offset; offset += original.length; const keepPrefix = i === firstEntry.runIndex && prefix ? original.slice(0, Math.max(0, firstEntry.charOffset - start)) : ''; const keepSuffix = i === lastEntry.runIndex && suffix ? original.slice(Math.max(0, lastEntry.charOffset + 1 - start)) : ''; if (keepPrefix || keepSuffix) { element.textContent = keepPrefix + keepSuffix; preserveXmlSpace(element); } else run.removeChild(element); } else if (element.localName === 'fldChar' || element.localName === 'instrText') { run.removeChild(element); } } // Textless semantic children (references, breaks, drawings) are not empty runs. if (getRunText(run) === '' && isRunSafeToRemove(run)) run.parentNode?.removeChild(run); } } /** * Perform a single replacement of searchText with value in the paragraph. * Does NOT loop — replaces only the first match found. * Uses docx-core's replaceParagraphTextRange for correct formatting preservation, * with a legacy charMap fallback for container-boundary cases (hyperlinks, SDTs). */ /** * Replace the first occurrence of searchText that appears AFTER contextText * in the same paragraph. Each call is self-contained — no chaining or order dependency. * Uses docx-core's replaceParagraphTextRange with legacy charMap fallback. */ function replaceFirstAfterContext(para, searchText, contextText, value, replacementColor) { const fullText = getParagraphText(para); const normalizedFull = normalizeQuotes(fullText); const ctxPos = normalizedFull.indexOf(contextText); if (ctxPos === -1) return false; const matchStart = normalizedFull.indexOf(searchText, ctxPos + contextText.length); if (matchStart === -1) return false; try { replaceParagraphTextRange(para, matchStart, matchStart + searchText.length, replacementColor ? [{ text: value, addRunProps: { color: replacementColor } }] : value); } catch (e) { if (e instanceof SafeDocxError && (e.code === 'UNSAFE_CONTAINER_BOUNDARY' || e.code === 'UNSUPPORTED_EDIT')) { const runs = getRunElements(para); const { fullText: legacyText, charMap } = buildCharMap(runs); const normalizedLegacy = normalizeQuotes(legacyText); const legacyCtxPos = normalizedLegacy.indexOf(contextText); if (legacyCtxPos === -1) return false; const legacyPos = normalizedLegacy.indexOf(searchText, legacyCtxPos + contextText.length); if (legacyPos === -1) return false; replaceAtPositionLegacy(runs, charMap, legacyPos, searchText.length, value, replacementColor); } else { throw e; } } return true; } function replaceInParagraph(para, replacements, sortedKeys, replacementColor) { const matchedKeys = new Set(); // Quick check: skip if no keys match const initialText = getParagraphText(para); if (!initialText) return matchedKeys; const normalizedInitial = normalizeQuotes(initialText); if (!sortedKeys.some((key) => normalizedInitial.includes(key))) return matchedKeys; for (const key of sortedKeys) { let iterations = 0; let paraText = getParagraphText(para); while (normalizeQuotes(paraText).includes(key)) { iterations++; if (iterations > MAX_REPLACEMENTS_PER_KEY) { throw new Error(`Patcher: exceeded ${MAX_REPLACEMENTS_PER_KEY} replacements for key "${key}" ` + `in a single paragraph. This usually means the replacement value contains ` + `the search key, creating an infinite loop.`); } const prevText = paraText; const matchStart = normalizeQuotes(paraText).indexOf(key); const replacement = replacements[key]; try { replaceParagraphTextRange(para, matchStart, matchStart + key.length, replacementColor ? [{ text: replacement, addRunProps: { color: replacementColor } }] : replacement); } catch (e) { if (e instanceof SafeDocxError && (e.code === 'UNSAFE_CONTAINER_BOUNDARY' || e.code === 'UNSUPPORTED_EDIT')) { // Fallback: use legacy charMap splice for this specific match const runs = getRunElements(para); const { fullText: legacyText, charMap } = buildCharMap(runs); const legacyPos = normalizeQuotes(legacyText).indexOf(key); if (legacyPos === -1) break; replaceAtPositionLegacy(runs, charMap, legacyPos, key.length, replacement, replacementColor); } else { throw e; } } matchedKeys.add(key); // Re-read paragraph text after DOM modification paraText = getParagraphText(para); // Progress guard: if text didn't change, we're stuck if (paraText === prevText) { throw new Error(`Patcher: no progress replacing key "${key}" — replacement value may contain the search key.`); } } } // Sweep: remove empty runs that are safe to remove (no drawings, fields, etc.) const finalRuns = getRunElements(para); for (let i = finalRuns.length - 1; i >= 0; i--) { if (getRunText(finalRuns[i]) === '' && isRunSafeToRemove(finalRuns[i])) { finalRuns[i].parentNode?.removeChild(finalRuns[i]); } } return matchedKeys; } //# sourceMappingURL=patcher.js.map