open-agreements
Version:
Open-source legal template filling CLI and library
577 lines • 24.9 kB
JavaScript
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