open-agreements
Version:
Open-source legal template filling CLI and library
269 lines • 11.9 kB
JavaScript
/**
* Shared utilities for the fill stage of all pipelines (template, fieldSelector, external).
*/
import AdmZip from 'adm-zip';
import { DOMParser } from '@xmldom/xmldom';
import { enumerateTextParts, getGeneralTextPartNames, getAllTextPartNames, } from './field-selector/ooxml-parts.js';
const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
/**
* Visible placeholder rendered for fields the user hasn't filled yet.
* Makes it obvious what still needs attention in the output document.
*/
export const BLANK_PLACEHOLDER = '_______';
/**
* Scan a DOCX template buffer for fields that have a literal `$` immediately
* before the `{field_name}` tag. Returns the set of field names.
*
* Works by parsing OOXML text parts and concatenating `<w:t>` elements per
* paragraph, then matching `$` + `{field_name}` patterns. Handles cross-run
* splits because text is concatenated at the paragraph level.
*/
export function detectCurrencyFields(docxBuffer) {
const zip = new AdmZip(docxBuffer);
const parser = new DOMParser();
const parts = enumerateTextParts(zip);
const partNames = getGeneralTextPartNames(parts);
const currencyFields = 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 paras = doc.getElementsByTagNameNS(W_NS, 'p');
for (let i = 0; i < paras.length; i++) {
const tElements = paras[i].getElementsByTagNameNS(W_NS, 't');
let fullText = '';
for (let j = 0; j < tElements.length; j++) {
fullText += tElements[j].textContent ?? '';
}
const matches = fullText.matchAll(/\$\{(\w+)\}/g);
for (const m of matches) {
currencyFields.add(m[1]);
}
}
}
return currencyFields;
}
/**
* Strip leading `$` from user values where the DOCX template already has
* a literal `$` before the `{field_name}` tag. Prevents double-dollar
* output like `$$1,000,000`.
*
* This is the DOCX-aware version that works for all pipelines — it scans
* the template buffer directly instead of requiring a replacements map.
*/
export function sanitizeCurrencyValuesFromDocx(values, docxBuffer) {
const currencyFields = detectCurrencyFields(docxBuffer);
if (currencyFields.size === 0)
return values;
const sanitized = { ...values };
for (const field of currencyFields) {
const v = sanitized[field];
if (typeof v === 'string' && v.startsWith('$')) {
sanitized[field] = v.slice(1);
}
}
return sanitized;
}
/**
* Horizontal whitespace that can sit between a tag and a trailing `%`, or
* between a number and its `%` inside a user value. Deliberately excludes
* `\n` — a percent sign on the next line belongs to different prose.
*/
const H_SPACE = ' \\t\\u00A0\\u2007\\u202F';
/** `{field}` immediately followed (modulo horizontal whitespace) by `%`. */
const TAG_THEN_PERCENT = new RegExp(`\\{(\\w+)\\}[${H_SPACE}]*%`, 'g');
/** Any `{field}` tag. */
const ANY_TAG = /\{(\w+)\}/g;
/** A trailing `%` on a user value, with any horizontal whitespace before it. */
const TRAILING_PERCENT = new RegExp(`[${H_SPACE}]*%$`);
/**
* A doubled percent sign (`%%` or `% %`) in rendered output — the artifact left
* when a sign-carrying value lands in a placeholder whose source already
* supplies the `%`. The trailing-sigil twin of the `doubleDollarPattern`.
*
* Shared with the fieldSelector verifier so both entry points flag the same
* shape. Not global: every caller only asks whether a line matches.
*/
export const DOUBLE_PERCENT_PATTERN = /%[\s\u00A0\t]*%/;
/**
* Scan a DOCX template buffer for fields whose `{field_name}` tag is
* immediately followed by a literal `%` — the trailing-sigil mirror of
* {@link detectCurrencyFields}.
*
* A field is reported only when **every** occurrence of its tag carries the
* adjacent `%`. That asymmetry with the currency detector is deliberate and
* is the whole reason this is not a literal mirror: recipes disagree about
* which side of the seam owns the sign (`nvca-rofr-co-sale-agreement` maps the
* key `"[specify percentage]%"`, absorbing the source `%`, while the
* certificate of incorporation and stock purchase agreement map
* `"[specify percentage]"` and leave it in place), so one field can plausibly
* land in a document with the sign on some occurrences and not others. When
* the occurrences disagree there is no value that renders correctly
* everywhere, so we strip nothing and let the `%%` artifact surface loudly in
* the verifier rather than silently dropping the sign from the occurrence that
* needed it.
*
* Works by parsing OOXML text parts and concatenating `<w:t>` elements per
* paragraph, so a tag split across runs is still seen whole.
*/
export function detectPercentFields(docxBuffer) {
const zip = new AdmZip(docxBuffer);
const parser = new DOMParser();
const parts = enumerateTextParts(zip);
// Footnotes included: a percentage placeholder in a footnote owns its sign
// exactly as a body one does, and a footnote rendering `8%%` is a corrupt
// executed document.
const partNames = getAllTextPartNames(parts);
const totalByField = new Map();
const adjacentByField = new Map();
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 paras = doc.getElementsByTagNameNS(W_NS, 'p');
for (let i = 0; i < paras.length; i++) {
const tElements = paras[i].getElementsByTagNameNS(W_NS, 't');
let fullText = '';
for (let j = 0; j < tElements.length; j++) {
fullText += tElements[j].textContent ?? '';
}
for (const m of fullText.matchAll(ANY_TAG)) {
totalByField.set(m[1], (totalByField.get(m[1]) ?? 0) + 1);
}
for (const m of fullText.matchAll(TAG_THEN_PERCENT)) {
adjacentByField.set(m[1], (adjacentByField.get(m[1]) ?? 0) + 1);
}
}
}
const percentFields = new Set();
for (const [field, adjacent] of adjacentByField) {
if (adjacent > 0 && adjacent === totalByField.get(field)) {
percentFields.add(field);
}
}
return percentFields;
}
/**
* Strip a trailing `%` from user values where the DOCX template already has a
* literal `%` after the `{field_name}` tag. Prevents double-percent output
* like `60%%`.
*
* The mirror of {@link sanitizeCurrencyValuesFromDocx} is not literal: `$` is a
* leading sigil and `%` a trailing one, so this strips from the end, and it
* also absorbs any horizontal whitespace the user typed before the sign, a
* non-breaking or figure space included: "60%", "60 %", and a value with a
* U+00A0 before the sign all become "60". A value that is nothing but a
* percent sign is left alone rather than blanked.
*/
export function sanitizePercentValuesFromDocx(values, docxBuffer) {
const percentFields = detectPercentFields(docxBuffer);
if (percentFields.size === 0)
return values;
const sanitized = { ...values };
for (const field of percentFields) {
const v = sanitized[field];
if (typeof v !== 'string')
continue;
const stripped = v.replace(TRAILING_PERCENT, '');
if (stripped !== v && stripped.trim() !== '') {
sanitized[field] = stripped;
}
}
return sanitized;
}
/**
* Concatenate each paragraph's `<w:t>` runs into one string per paragraph,
* over the given OOXML part names. Cross-run splits disappear because the
* text is joined at the paragraph level.
*/
function paragraphTexts(zip, parser, partNames) {
const out = [];
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 paras = doc.getElementsByTagNameNS(W_NS, 'p');
for (let i = 0; i < paras.length; i++) {
const tElements = paras[i].getElementsByTagNameNS(W_NS, 't');
const textParts = [];
for (let j = 0; j < tElements.length; j++) {
textParts.push(tElements[j].textContent ?? '');
}
if (textParts.length > 0) {
out.push(textParts.join(''));
}
}
}
return out;
}
/**
* Verify a filled template DOCX output.
* Runs a subset of checks that are safe for templates:
* - No double dollar signs (catches currency sanitization failures)
* - No double percent signs (catches percentage sanitization failures)
* - No unrendered {template_tags} (catches fill failures)
*
* Does NOT check: leftover brackets (templates don't use them),
* context values present (templates use {IF} conditionals that hide values),
* drafting notes (stripped by fillDocx). Footnote text is read for the
* sigil-doubling checks only — the unrendered-tag check keeps body/header/
* footer/endnote scope, where a leftover footnote tag may be legitimate.
*/
export function verifyTemplateFill(outputPath) {
const zip = new AdmZip(outputPath);
const parser = new DOMParser();
const parts = enumerateTextParts(zip);
const partNames = getGeneralTextPartNames(parts);
const allParagraphs = paragraphTexts(zip, parser, partNames);
const rawFullText = allParagraphs.join('\n');
// Footnotes sit outside the general part list (see `getAllTextPartNames`).
// They feed the sigil-doubling checks only: those are read-only and a corrupt
// footnote is still a corrupt document, while the unrendered-tag check keeps
// its existing scope.
const footnoteText = parts.footnotes
? paragraphTexts(zip, parser, [parts.footnotes]).join('\n')
: '';
const sigilText = footnoteText ? `${rawFullText}\n${footnoteText}` : rawFullText;
const checks = [];
// Check 1: No double dollar signs ($$ or $ $)
const doubleDollarPattern = /\$[\s\u00A0\t]*\$/;
const doubleDollarLines = sigilText.split('\n').filter((line) => doubleDollarPattern.test(line));
checks.push({
name: 'No double dollar signs',
passed: doubleDollarLines.length === 0,
details: doubleDollarLines.length > 0
? `Found ${doubleDollarLines.length} occurrence(s): "${doubleDollarLines[0].trim().slice(0, 80)}"`
: undefined,
});
// Check 2: No double percent signs (%% or % %) — the trailing-sigil twin of
// Check 1. The template already carries the `%` after some placeholders, so a
// sign-carrying value doubles it.
const doublePercentLines = sigilText
.split('\n')
.filter((line) => DOUBLE_PERCENT_PATTERN.test(line));
checks.push({
name: 'No double percent signs',
passed: doublePercentLines.length === 0,
details: doublePercentLines.length > 0
? `Found ${doublePercentLines.length} occurrence(s): "${doublePercentLines[0].trim().slice(0, 80)}"`
: undefined,
});
// Check 3: No unrendered {template_tags}
const unrenderedTags = rawFullText.match(/\{[a-z_][a-z0-9_]*\}/gi) ?? [];
checks.push({
name: 'No unrendered template tags',
passed: unrenderedTags.length === 0,
details: unrenderedTags.length > 0 ? `Found: ${unrenderedTags.join(', ')}` : undefined,
});
return {
passed: checks.every((c) => c.passed),
checks,
};
}
//# sourceMappingURL=fill-utils.js.map