open-agreements
Version:
Open-source legal template filling CLI and library
502 lines • 20.5 kB
JavaScript
// Human-fillable bracket-prose transform for catalog preview parity.
//
// The CLI fill path (`fillDocx`) swaps `{snake_case}` tokens for caller-supplied
// values — that is the API consumers use programmatically. Humans never see it.
//
// What humans DO see is the file served from usejunior.com/template-downloads/<id>.docx,
// which is run through a different transform that turns `{employer_name}` into
// `[Employer Legal Name]` (with a yellow highlight) so a lawyer opening the file in Word
// can read it as prose and tab through the must-fills.
//
// This module is a TypeScript port of dev-website's `scripts/generate_template_downloads.js`
// transform, so the catalog preview PNGs match what users actually download. The
// CLI fill path is unchanged — design split is intentional.
import { readFileSync } from 'node:fs';
import { basename, join, resolve } from 'node:path';
import AdmZip from 'adm-zip';
import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
import yaml from 'js-yaml';
import { copyEntriesSkippingDirs } from './field-selector/ooxml-parts.js';
const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
const XML_NS = 'http://www.w3.org/XML/1998/namespace';
const W_P_TAG = 'p';
const W_R_TAG = 'r';
const W_RPR_TAG = 'rPr';
const W_T_TAG = 't';
const W_TC_TAG = 'tc';
const W_HIGHLIGHT_TAG = 'highlight';
const XML_SPACE_ATTR = 'xml:space';
const XML_PATH_RE = /^(word|docProps)\/.+\.xml$/;
const IF_MARKER_RE = /\{IF [^}]+\}/g;
const END_IF_MARKER_RE = /\{END-IF\}/g;
const FIELD_RE = /\{([a-z0-9_]+)\}/g;
const PLACEHOLDER_RE = /\{([a-z0-9_]+)\}/g;
const MULTI_SPACE_RE = /\s{2,}/g;
// Cover-notice cross-reference sentinel. The filled pipeline resolves it to the
// live "Section N". In the catalog preview the only sentinels live inside the
// notice's conditional bullets, which cleanupConditionalParagraphs already
// drops — so this is defense-in-depth: if a sentinel ever reaches the preview,
// render a neutral placeholder instead of leaking the raw token. Matches the
// XML-escaped form (`<<…>>`) and, defensively, the raw form.
const XREF_SENTINEL_RE = /(?:<<|<<)xref:oa_xref_[0-9a-f]+(?:>>|>>)/g;
// Field-code elements whose content carries program-readable instructions
// (PAGE, NUMPAGES, etc.) or field markers — MULTI_SPACE_RE must not touch
// these or the rendered field can corrupt (#185, #109).
const FIELD_CODE_PRESERVE_RE = /<(w:instrText|w:fldChar)(\s+[^>]*)?(?:\/>|>[\s\S]*?<\/\1>)/g;
function collapseMultiSpaceOutsideFieldCodes(xml) {
FIELD_CODE_PRESERVE_RE.lastIndex = 0;
const out = [];
let lastIndex = 0;
let match;
while ((match = FIELD_CODE_PRESERVE_RE.exec(xml)) !== null) {
out.push(xml.slice(lastIndex, match.index).replace(MULTI_SPACE_RE, ' '));
out.push(match[0]);
lastIndex = match.index + match[0].length;
}
out.push(xml.slice(lastIndex).replace(MULTI_SPACE_RE, ' '));
return out.join('');
}
const EXACT_IF_MARKER_RE = /^\{IF\s+(!?[^}]+)\}$/;
const EXACT_END_IF_MARKER_RE = /^\{END-IF\}$/;
const HIGHLIGHT_PLACEHOLDER_RE = /(\[[^\]]+\])/g;
const PLACEHOLDER_ONLY_RE = /^\[[^\]]+\]$/;
const GENERIC_SUBLABELS = new Set(['duration']);
function hasOwn(obj, key) {
return Object.prototype.hasOwnProperty.call(obj, key);
}
function unique(values) {
return [...new Set(values.filter(Boolean))];
}
function fallbackFieldLabel(fieldName) {
return String(fieldName || '').trim();
}
function normalizeDisplayLabel(rawLabel) {
let label = String(rawLabel ?? '').replace(MULTI_SPACE_RE, ' ').trim();
if (label.length > 80) {
const sentence = label.split(/(?<=[.!?])\s+/, 1)[0];
if (sentence) {
label = sentence;
}
}
return label.replace(/\.$/, '');
}
function normalizeDefaultText(rawDefault) {
if (rawDefault == null || typeof rawDefault === 'boolean')
return null;
const text = String(rawDefault).replace(MULTI_SPACE_RE, ' ').trim();
return text;
}
function loadTemplateMetadataFields(templateDir) {
const metadataPath = join(templateDir, 'metadata.yaml');
let raw;
try {
raw = readFileSync(metadataPath, 'utf8');
}
catch {
return {};
}
const metadata = yaml.load(raw) ?? {};
const fields = {};
for (const field of metadata.fields ?? []) {
if (field && field.name) {
fields[field.name] = field;
}
}
return fields;
}
function loadStructuredPublicFieldMetadata(templateDir, publicFieldMetadataPath) {
if (!publicFieldMetadataPath)
return {};
let raw;
try {
raw = readFileSync(publicFieldMetadataPath, 'utf8');
}
catch {
return {};
}
const metadata = yaml.load(raw) ?? {};
const templateId = basename(templateDir);
const globalFields = metadata.global ?? {};
const templateFields = metadata.templates?.[templateId] ?? {};
const structuredFields = {};
for (const fieldName of unique([...Object.keys(globalFields), ...Object.keys(templateFields)])) {
const entry = { ...(globalFields[fieldName] ?? {}), ...(templateFields[fieldName] ?? {}) };
const normalizedEntry = {};
if (hasOwn(entry, 'label')) {
const label = normalizeDisplayLabel(entry.label);
if (label)
normalizedEntry.label = label;
}
if (hasOwn(entry, 'default')) {
const defaultText = normalizeDefaultText(entry.default);
if (defaultText !== null)
normalizedEntry.default = defaultText;
}
if (Object.keys(normalizedEntry).length > 0) {
structuredFields[fieldName] = normalizedEntry;
}
}
return structuredFields;
}
function buildFieldDefaults(templateDir) {
const metadataFields = loadTemplateMetadataFields(templateDir);
const defaults = {};
for (const [fieldName, field] of Object.entries(metadataFields)) {
if (!hasOwn(field, 'default'))
continue;
const defaultText = normalizeDefaultText(field.default);
if (defaultText !== null)
defaults[fieldName] = defaultText;
}
return defaults;
}
function extractPlaceholderNames(value) {
if (typeof value !== 'string')
return [];
return [...value.matchAll(PLACEHOLDER_RE)].map((match) => match[1]);
}
function buildEffectiveLabel(label, parentLabel, isSubRow) {
if (!label)
return '';
if (!isSubRow || !parentLabel)
return label;
if (GENERIC_SUBLABELS.has(label.toLowerCase()))
return `${parentLabel} ${label}`;
return label;
}
function collectRowLabels(rows, labels) {
let parentLabel = '';
for (const row of rows) {
if (!row || typeof row !== 'object')
continue;
const rowLabel = normalizeDisplayLabel(row.label ?? '');
if (rowLabel && !row.sub)
parentLabel = rowLabel;
const effectiveLabel = buildEffectiveLabel(rowLabel, parentLabel, Boolean(row.sub));
if (!effectiveLabel)
continue;
for (const key of ['value', 'left', 'right']) {
for (const fieldName of extractPlaceholderNames(row[key])) {
if (!labels[fieldName])
labels[fieldName] = effectiveLabel;
}
}
}
}
function collectStructuredLabels(node, labels = {}) {
if (Array.isArray(node)) {
for (const item of node)
collectStructuredLabels(item, labels);
return labels;
}
if (!node || typeof node !== 'object')
return labels;
const rec = node;
if (Array.isArray(rec.rows))
collectRowLabels(rec.rows, labels);
const label = normalizeDisplayLabel(rec.label ?? '');
if (label) {
for (const key of ['value', 'left', 'right']) {
for (const fieldName of extractPlaceholderNames(rec[key])) {
if (!labels[fieldName])
labels[fieldName] = label;
}
}
}
for (const value of Object.values(rec))
collectStructuredLabels(value, labels);
return labels;
}
function loadTemplateSpec(templateDir, templateSpecsDir) {
if (!templateSpecsDir)
return null;
const specPath = join(templateSpecsDir, `${basename(templateDir)}.json`);
let raw;
try {
raw = readFileSync(specPath, 'utf8');
}
catch {
return null;
}
return JSON.parse(raw);
}
function buildFieldLabels(templateDir, templateSpecsDir) {
const metadataFields = loadTemplateMetadataFields(templateDir);
const templateSpec = loadTemplateSpec(templateDir, templateSpecsDir);
const templateSpecLabels = templateSpec ? collectStructuredLabels(templateSpec) : {};
const fieldLabels = {};
for (const [fieldName, field] of Object.entries(metadataFields)) {
const baseFieldName = fieldName.endsWith('_footer') ? fieldName.slice(0, -7) : fieldName;
const displayFieldName = metadataFields[baseFieldName] ? baseFieldName : fieldName;
const displayField = metadataFields[displayFieldName] ?? field;
const description = field.description ? normalizeDisplayLabel(field.description) : '';
const displayDescription = displayField.description ? normalizeDisplayLabel(displayField.description) : '';
fieldLabels[fieldName] =
templateSpecLabels[fieldName] ||
templateSpecLabels[displayFieldName] ||
displayDescription ||
description ||
fallbackFieldLabel(displayFieldName);
}
return fieldLabels;
}
export function loadHumanizeContext(templateDir, opts = {}) {
const publicFieldMetadata = loadStructuredPublicFieldMetadata(templateDir, opts.publicFieldMetadataPath);
const fieldLabels = buildFieldLabels(templateDir, opts.templateSpecsDir);
for (const [fieldName, metadata] of Object.entries(publicFieldMetadata)) {
if (metadata.label)
fieldLabels[fieldName] = metadata.label;
}
const fieldDefaults = buildFieldDefaults(templateDir);
for (const [fieldName, metadata] of Object.entries(publicFieldMetadata)) {
if (hasOwn(metadata, 'default') && metadata.default !== undefined) {
fieldDefaults[fieldName] = metadata.default;
}
}
return { fieldLabels, fieldDefaults };
}
// --- XML transforms ---
function extractParagraphText(paragraph) {
const textNodes = paragraph.getElementsByTagNameNS(W_NS, W_T_TAG);
const parts = [];
for (let i = 0; i < textNodes.length; i += 1) {
parts.push(textNodes[i].textContent || '');
}
return parts.join('');
}
function isWordElement(node, localName) {
if (!node || typeof node !== 'object')
return false;
const el = node;
return el.nodeType === 1 && el.namespaceURI === W_NS && el.localName === localName;
}
function cleanupConditionalParagraphs(text) {
if (!text.includes('xmlns:w=') || !text.includes('<w:p'))
return text;
const parser = new DOMParser();
let root;
try {
root = parser.parseFromString(text, 'text/xml');
}
catch {
return text;
}
let changed = false;
while (true) {
let updated = false;
const parents = [root.documentElement];
const allDescendants = root.getElementsByTagName('*');
for (let i = 0; i < allDescendants.length; i += 1) {
parents.push(allDescendants[i]);
}
for (const parent of parents) {
if (!parent || !parent.childNodes)
continue;
const children = [];
for (let i = 0; i < parent.childNodes.length; i += 1) {
children.push(parent.childNodes[i]);
}
for (let index = 0; index < children.length; index += 1) {
const child = children[index];
if (!isWordElement(child, W_P_TAG))
continue;
const paragraphText = extractParagraphText(child).trim();
const ifMatch = paragraphText.match(EXACT_IF_MARKER_RE);
const isEndIf = EXACT_END_IF_MARKER_RE.test(paragraphText);
if (!ifMatch && !isEndIf)
continue;
// Inside a table cell, just strip the marker paragraph — preserves cell width.
if (parent.namespaceURI === W_NS && parent.localName === W_TC_TAG) {
parent.removeChild(child);
changed = true;
updated = true;
break;
}
if (isEndIf || !ifMatch) {
parent.removeChild(child);
changed = true;
updated = true;
break;
}
let endIndex = null;
const blockChildren = [];
for (let offset = index + 1; offset < children.length; offset += 1) {
const sibling = children[offset];
if (isWordElement(sibling, W_P_TAG) &&
EXACT_END_IF_MARKER_RE.test(extractParagraphText(sibling).trim())) {
endIndex = offset;
break;
}
blockChildren.push(sibling);
}
parent.removeChild(child);
changed = true;
if (endIndex !== null) {
const endMarker = children[endIndex];
if (endMarker && endMarker.parentNode === parent) {
parent.removeChild(endMarker);
}
// Negated condition `{IF !foo}` — strip the block content too.
if (ifMatch[1].trim().startsWith('!')) {
for (const blockChild of blockChildren) {
const bc = blockChild;
if (bc && bc.parentNode === parent) {
parent.removeChild(bc);
}
}
}
}
updated = true;
break;
}
if (updated)
break;
}
if (!updated)
break;
}
if (!changed)
return text;
return new XMLSerializer().serializeToString(root);
}
function replaceFieldTokens(text, fieldLabels, fieldDefaults) {
return text.replace(FIELD_RE, (_match, fieldName) => {
if (hasOwn(fieldDefaults, fieldName)) {
return fieldDefaults[fieldName];
}
const label = fieldLabels[fieldName] || fallbackFieldLabel(fieldName);
return `[${label}]`;
});
}
function highlightPlaceholderRuns(text) {
if (!text.includes('xmlns:w=') || !text.includes('<w:r'))
return text;
const parser = new DOMParser();
let root;
try {
root = parser.parseFromString(text, 'text/xml');
}
catch {
return text;
}
let changed = false;
while (true) {
let updated = false;
const runs = [];
const runList = root.getElementsByTagNameNS(W_NS, W_R_TAG);
for (let i = 0; i < runList.length; i += 1)
runs.push(runList[i]);
for (const run of runs) {
const childNodes = [];
for (let i = 0; i < run.childNodes.length; i += 1)
childNodes.push(run.childNodes[i]);
const textChildren = childNodes.filter((node) => isWordElement(node, W_T_TAG));
const nonTextChildren = childNodes.filter((node) => {
const el = node;
return (el && el.nodeType === 1 && el.namespaceURI === W_NS &&
el.localName !== W_T_TAG && el.localName !== W_RPR_TAG);
});
if (textChildren.length === 0 || nonTextChildren.length > 0)
continue;
const runText = textChildren.map((node) => node.textContent || '').join('');
const parts = runText.split(HIGHLIGHT_PLACEHOLDER_RE);
if (parts.length === 1)
continue;
const parent = run.parentNode;
if (!parent || parent.nodeType !== 1)
continue;
const baseRPr = childNodes.find((node) => isWordElement(node, W_RPR_TAG));
if (baseRPr &&
baseRPr.getElementsByTagNameNS(W_NS, W_HIGHLIGHT_TAG).length > 0 &&
PLACEHOLDER_ONLY_RE.test(runText)) {
continue;
}
const insertBefore = run.nextSibling;
// Reset lastIndex on the global regex between checks — same instance is reused.
HIGHLIGHT_PLACEHOLDER_RE.lastIndex = 0;
for (const part of parts) {
if (!part)
continue;
const newRun = root.createElementNS(W_NS, 'w:r');
let newRPr = null;
if (baseRPr) {
newRPr = baseRPr.cloneNode(true);
newRun.appendChild(newRPr);
}
// Whole part is a [bracket placeholder] — add yellow highlight.
if (PLACEHOLDER_ONLY_RE.test(part)) {
if (!newRPr) {
newRPr = root.createElementNS(W_NS, 'w:rPr');
newRun.appendChild(newRPr);
}
if (newRPr.getElementsByTagNameNS(W_NS, W_HIGHLIGHT_TAG).length === 0) {
const highlight = root.createElementNS(W_NS, 'w:highlight');
highlight.setAttributeNS(W_NS, 'w:val', 'yellow');
newRPr.appendChild(highlight);
}
}
const textNode = root.createElementNS(W_NS, 'w:t');
textNode.setAttributeNS(XML_NS, XML_SPACE_ATTR, 'preserve');
textNode.appendChild(root.createTextNode(part));
newRun.appendChild(textNode);
parent.insertBefore(newRun, insertBefore);
}
parent.removeChild(run);
changed = true;
updated = true;
break;
}
if (!updated)
break;
}
if (!changed)
return text;
return new XMLSerializer().serializeToString(root);
}
export function prettifyTemplateXml(text, fieldLabels, fieldDefaults, options = {}) {
let output = cleanupConditionalParagraphs(text);
output = output.replace(IF_MARKER_RE, '');
output = output.replace(END_IF_MARKER_RE, '');
output = output.replace(XREF_SENTINEL_RE, 'Section [#]');
output = replaceFieldTokens(output, fieldLabels, fieldDefaults);
output = collapseMultiSpaceOutsideFieldCodes(output);
if (options.highlight !== false) {
output = highlightPlaceholderRuns(output);
}
return output;
}
export function humanizeDocxBuffer(input, ctx) {
const sourceZip = new AdmZip(input);
const destinationZip = new AdmZip();
copyEntriesSkippingDirs(sourceZip, destinationZip, (entryName, entryData) => {
let data = entryData;
if (XML_PATH_RE.test(entryName)) {
let text = data.toString('utf8');
text = cleanupConditionalParagraphs(text);
text = text.replace(IF_MARKER_RE, '');
text = text.replace(END_IF_MARKER_RE, '');
text = text.replace(XREF_SENTINEL_RE, 'Section [#]');
text = replaceFieldTokens(text, ctx.fieldLabels, ctx.fieldDefaults);
text = collapseMultiSpaceOutsideFieldCodes(text);
if (entryName.startsWith('word/')) {
text = highlightPlaceholderRuns(text);
}
data = Buffer.from(text, 'utf8');
}
return data;
});
return destinationZip.toBuffer();
}
/**
* Public API. Reads template.docx from `templateDir`, applies the same humanize
* transform that dev-website's `generate_template_downloads.js` applies, and
* returns the resulting Buffer. The buffer is suitable for rasterizing into a
* catalog preview PNG that matches what users download.
*/
export async function humanizeDocx(templateDir, opts = {}) {
const sourceDocx = resolve(templateDir, 'template.docx');
const input = readFileSync(sourceDocx);
const ctx = loadHumanizeContext(templateDir, opts);
return humanizeDocxBuffer(input, ctx);
}
//# sourceMappingURL=humanize-docx.js.map