UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

475 lines • 18.3 kB
/** * In-Place AST Modifier * * Modifies the revised document's AST in-place to add track changes markup. * This replaces the reconstruction-based approach with direct tree manipulation. */ import { childElements, findChildByTagName, insertAfterElement, wrapElement } from '../../primitives/index.js'; import { allocateRevisionId, convertToDelText, createEl, findAncestorByTag, getMoveRangeIds, parentElement, } from './inPlaceModifier-shared.js'; export const TRACK_CHANGE_WRAPPERS = new Set([ 'w:ins', 'w:del', 'w:moveFrom', 'w:moveTo', ]); /** * Resolve the run associated with an atom boundary. * * For collapsed field atoms, sourceRunElement points at the first run in the * field sequence. For insertion-point tracking we often need the trailing run, * otherwise deleted/moved fragments can be inserted inside the field sequence. */ export function getAtomRunAtBoundary(atom, boundary) { if (atom.collapsedFieldAtoms && atom.collapsedFieldAtoms.length > 0) { const fieldAtoms = boundary === 'start' ? atom.collapsedFieldAtoms : [...atom.collapsedFieldAtoms].reverse(); for (const fieldAtom of fieldAtoms) { const run = fieldAtom.sourceRunElement ?? findAncestorByTag(fieldAtom, 'w:r'); if (run) return run; } } return atom.sourceRunElement ?? findAncestorByTag(atom, 'w:r'); } /** * Resolve all run elements represented by an atom. * * For collapsed-field atoms, we must treat the entire field run sequence as a * single logical unit. Wrapping only the first run leaves trailing field-code * runs untracked, which can leak revised field text after Reject All. */ export function getAtomRuns(atom) { if (!atom.collapsedFieldAtoms || atom.collapsedFieldAtoms.length === 0) { const run = atom.sourceRunElement ?? findAncestorByTag(atom, 'w:r'); return run ? [run] : []; } const runs = []; const seen = new Set(); for (const fieldAtom of atom.collapsedFieldAtoms) { const run = fieldAtom.sourceRunElement ?? findAncestorByTag(fieldAtom, 'w:r'); if (!run || seen.has(run)) continue; seen.add(run); runs.push(run); } return runs; } /** * True iff `atom` represents a collapsed-field sequence (a complex field * captured as a single logical atom). See {@link getAtomRuns} for the * multi-run resolution. */ export function isCollapsedFieldAtom(atom) { return !!(atom.collapsedFieldAtoms && atom.collapsedFieldAtoms.length > 0); } /** * Convert a run node to the correct insertion anchor. * * If the run is wrapped in a track-change container, the insertion anchor * must be the wrapper (a paragraph child), not the nested run. */ export function getRunInsertionAnchor(run) { const parent = parentElement(run); if (parent && TRACK_CHANGE_WRAPPERS.has(parent.tagName)) { return parent; } return run; } /** * Wrap a run element with track change markup. * * This is the shared implementation for wrapAsInserted, wrapAsDeleted, * and the inner wrapping logic of move operations. * * @param options - Wrapping options * @returns true if wrapped, false if run was already wrapped or has no parent */ export function wrapRunWithTrackChange(options) { const { run, tagName, author, dateStr, state, convertTextToDelText: convertText = false } = options; // Skip if already wrapped if (state.wrappedRuns.has(run)) { return false; } // Skip if the run has no parent in the tree if (!run.parentNode) { return false; } // Convert w:t to w:delText if requested (for deleted content) if (convertText) { convertToDelText(run); } const id = allocateRevisionId(state); const wrapper = createEl(tagName, { 'w:id': String(id), 'w:author': author, 'w:date': dateStr, }); wrapElement(run, wrapper); state.wrappedRuns.add(run); return true; } /** * Ensure w:pPr/w:rPr exists and add a paragraph-mark revision marker (w:ins/w:del) * in the paragraph properties. * * This is the critical piece for whole-paragraph insert/delete idempotency: * - Reject All should remove inserted paragraphs entirely (no stub breaks) * - Accept All should remove deleted paragraphs entirely */ export function addParagraphMarkRevisionMarker(paragraph, markerTag, author, dateStr, state) { // Find or create pPr. let pPr = findChildByTagName(paragraph, 'w:pPr'); if (!pPr) { pPr = createEl('w:pPr'); // pPr should be the first child in a paragraph. paragraph.insertBefore(pPr, paragraph.firstChild); } const existingMarker = findParagraphMarkRevisionMarker(pPr, markerTag); // Find or create rPr within pPr (paragraph mark properties). let rPr = findChildByTagName(pPr, 'w:rPr'); if (!rPr) { rPr = createEl('w:rPr'); // CT_PPr ordering: ... base props ..., w:rPr, w:sectPr?, w:pPrChange? // Insert rPr in schema-correct position (before sectPr/pPrChange). const sectPr = findChildByTagName(pPr, 'w:sectPr'); const pPrChange = findChildByTagName(pPr, 'w:pPrChange'); const insertBefore = sectPr ?? pPrChange ?? null; if (insertBefore) { pPr.insertBefore(rPr, insertBefore); } else { pPr.appendChild(rPr); } } // Avoid duplicating markers. A legacy/bypass path may already have put the // paragraph-mark marker in another w:rPr under the same pPr; keep that marker // and normalize its revision context instead of adding a second CT_ParaRPr child. if (existingMarker) { existingMarker.setAttribute('w:author', author); existingMarker.setAttribute('w:date', dateStr); if (!existingMarker.getAttribute('w:id')) { existingMarker.setAttribute('w:id', String(allocateRevisionId(state))); } // The bypass path may have left the marker mid-sequence (or in another // w:rPr); move it to the schema-correct slot in the canonical rPr. placeParagraphMarkRevisionMarker(rPr, existingMarker, markerTag); return; } const id = allocateRevisionId(state); const marker = createEl(markerTag, { 'w:id': String(id), 'w:author': author, 'w:date': dateStr, }); placeParagraphMarkRevisionMarker(rPr, marker, markerTag); } /** * Position a paragraph-mark revision marker in its schema-correct rPr slot. * * CT_ParaRPr ordering: the tracked-change group (w:ins, w:del, w:moveFrom, * w:moveTo — in that order) comes before every formatting child (w:rStyle, * w:rFonts, ...). So w:ins always goes first, and w:del goes right after a * w:ins sibling when one exists, else first. */ export function placeParagraphMarkRevisionMarker(rPr, marker, markerTag) { const insSibling = markerTag === 'w:del' ? findChildByTagName(rPr, 'w:ins') : null; if (insSibling) { if (insSibling.nextSibling !== marker) { insertAfterElement(insSibling, marker); } } else if (rPr.firstChild !== marker) { rPr.insertBefore(marker, rPr.firstChild); } } function findParagraphMarkRevisionMarker(pPr, markerTag) { for (const child of childElements(pPr)) { if (child.tagName !== 'w:rPr') continue; const marker = findChildByTagName(child, markerTag); if (marker) return marker; } return null; } // @lean-segment: field-wrapper-emission // Lean traceability anchor — cited by verification/lean/LeanSpike/Spec.lean and // packages/docx-core/src/integration/lean-spec-bridge.test.ts. These wrapping // primitives (wrapAsInserted/wrapAsDeleted and the move/format variants below) // emit whole field sequences as SINGLE track-change wrappers, which is why the // engine currently satisfies the stronger `fieldContextNeutral ∀ ctx` property. // When ECMA-376 field fragmentation lands (#217) this anchor marks the code the // Lean predicate-strength choice depends on. Grep this anchor, not line numbers. export function wrapAsInserted(run, author, dateStr, state) { return wrapRunWithTrackChange({ run, tagName: 'w:ins', author, dateStr, state, }); } /** * Wrap a run element with <w:del> to mark it as deleted. * Also converts w:t to w:delText within the run. * * @param run - The w:r element to wrap * @param author - Author name for track changes * @param dateStr - Formatted date string * @param state - Revision ID state * @returns true if wrapped, false if run was already wrapped or has no parent */ export function wrapAsDeleted(run, author, dateStr, state) { return wrapRunWithTrackChange({ run, tagName: 'w:del', author, dateStr, state, convertTextToDelText: true, }); } export const MOVE_CONFIG = { from: { wrapperTag: 'w:moveFrom', rangeStartTag: 'w:moveFromRangeStart', rangeEndTag: 'w:moveFromRangeEnd', rangeIdKey: 'sourceRangeId', convertTextToDelText: true, // Moved-from content appears as deleted }, to: { wrapperTag: 'w:moveTo', rangeStartTag: 'w:moveToRangeStart', rangeEndTag: 'w:moveToRangeEnd', rangeIdKey: 'destRangeId', convertTextToDelText: false, // Moved-to content keeps w:t }, }; /** * Wrap a run element with move tracking (shared implementation for moveFrom/moveTo). * * @param run - The w:r element to wrap * @param moveName - Name for linking source and destination * @param direction - 'from' for moveFrom, 'to' for moveTo * @param author - Author name * @param dateStr - Formatted date * @param state - Revision ID state * @returns true if wrapped */ export function wrapAsMove(run, moveName, direction, author, dateStr, state) { if (state.wrappedRuns.has(run)) { return false; } const parent = parentElement(run); if (!parent) { return false; } const config = MOVE_CONFIG[direction]; const ids = getMoveRangeIds(state, moveName); const moveId = allocateRevisionId(state); const rangeId = ids[config.rangeIdKey]; // Convert w:t to w:delText if needed (for moveFrom content) if (config.convertTextToDelText) { convertToDelText(run); } // Create range start marker const rangeStart = createEl(config.rangeStartTag, { 'w:id': String(rangeId), 'w:name': moveName, 'w:author': author, 'w:date': dateStr, }); // Create move wrapper const moveWrapper = createEl(config.wrapperTag, { 'w:id': String(moveId), 'w:author': author, 'w:date': dateStr, }); // Create range end marker const rangeEnd = createEl(config.rangeEndTag, { 'w:id': String(rangeId), }); // Insert: rangeStart -> moveWrapper(run) -> rangeEnd run.parentNode.insertBefore(rangeStart, run); wrapElement(run, moveWrapper); insertAfterElement(moveWrapper, rangeEnd); state.wrappedRuns.add(run); return true; } /** * Wrap a run element with <w:moveFrom> for moved-from content. * * @param run - The w:r element to wrap * @param moveName - Name for linking source and destination * @param author - Author name * @param dateStr - Formatted date * @param state - Revision ID state * @returns true if wrapped */ export function wrapAsMoveFrom(run, moveName, author, dateStr, state) { return wrapAsMove(run, moveName, 'from', author, dateStr, state); } /** * Wrap a run element with <w:moveTo> for moved-to content. * * @param run - The w:r element to wrap * @param moveName - Name for linking source and destination * @param author - Author name * @param dateStr - Formatted date * @param state - Revision ID state * @returns true if wrapped */ export function wrapAsMoveTo(run, moveName, author, dateStr, state) { return wrapAsMove(run, moveName, 'to', author, dateStr, state); } /** * Add format change tracking to a run's properties. * * @param run - The w:r element with changed formatting * @param oldRunProperties - The original run properties (w:rPr) * @param author - Author name * @param dateStr - Formatted date * @param state - Revision ID state */ export function addFormatChange(run, oldRunProperties, author, dateStr, state) { // Find or create w:rPr let rPr = findChildByTagName(run, 'w:rPr'); if (!rPr) { rPr = createEl('w:rPr'); // Insert rPr at the beginning of run's children run.insertBefore(rPr, run.firstChild); } // CT_RPr permits at most one w:rPrChange. Comparison can visit multiple // format-changed atoms from the same split run, so keep the latest snapshot // instead of stacking invalid siblings. for (const child of childElements(rPr)) { if (child.tagName === 'w:rPrChange') { rPr.removeChild(child); } } // Create rPrChange const id = allocateRevisionId(state); const rPrChange = createEl('w:rPrChange', { 'w:id': String(id), 'w:author': author, 'w:date': dateStr, }); // Clone old properties into a w:rPr wrapper inside rPrChange (OOXML spec requires // rPrChange to contain a single w:rPr child holding the previous formatting). if (oldRunProperties) { const oldRPr = createEl('w:rPr'); for (const child of childElements(oldRunProperties)) { const cloned = child.cloneNode(true); oldRPr.appendChild(cloned); } rPrChange.appendChild(oldRPr); } // Add rPrChange to rPr rPr.appendChild(rPrChange); } /** * Add a paragraph property change element (w:pPrChange) to record the "before" * state of paragraph properties. This is needed for Google Docs to display * inserted paragraphs as tracked changes. * * The child `<w:pPr>` inside `w:pPrChange` must conform to CT_PPrBase — it * MUST NOT contain w:rPr, w:sectPr, or w:pPrChange. * * @param paragraph - The w:p element * @param author - Author name * @param dateStr - Formatted date * @param state - Revision ID state */ export function addParagraphPropertyChange(paragraph, author, dateStr, state) { let pPr = findChildByTagName(paragraph, 'w:pPr'); if (!pPr) { pPr = createEl('w:pPr'); paragraph.insertBefore(pPr, paragraph.firstChild); } // Idempotent — don't add a second pPrChange. if (findChildByTagName(pPr, 'w:pPrChange')) return; const id = allocateRevisionId(state); const pPrChange = createEl('w:pPrChange', { 'w:id': String(id), 'w:author': author, 'w:date': dateStr, }); // Clone current pPr content as "before" snapshot. // pPrChange child pPr must be CT_PPrBase — exclude rPr, rPrChange, sectPr, pPrChange. const EXCLUDED = new Set(['w:rPr', 'w:rPrChange', 'w:pPrChange', 'w:sectPr']); const oldPPr = createEl('w:pPr'); for (const child of childElements(pPr)) { if (!EXCLUDED.has(child.tagName)) oldPPr.appendChild(child.cloneNode(true)); } pPrChange.appendChild(oldPPr); pPr.appendChild(pPrChange); // pPrChange goes last in pPr per schema } /** * Tag names that represent visible content inside a w:r element. * A run containing at least one of these is considered substantive (non-empty). */ export const RUN_VISIBLE_CONTENT_TAGS = new Set([ 'w:t', 'w:tab', 'w:br', 'w:cr', 'w:drawing', 'w:object', 'w:pict', 'w:sym', 'w:fldChar', 'w:instrText', ]); /** * Returns true if a w:r element contains at least one visible content child. * Empty runs (containing only w:rPr or nothing) return false. */ export function runHasVisibleContent(run) { for (let i = 0; i < run.childNodes.length; i++) { const child = run.childNodes[i]; if (child.nodeType === 1 && RUN_VISIBLE_CONTENT_TAGS.has(child.tagName)) { return true; } } return false; } /** * Wrap an inserted empty paragraph with <w:ins>. * * For empty paragraphs (no content, only pPr), we wrap the entire paragraph. * * @param paragraph - The w:p element * @param author - Author name * @param dateStr - Formatted date * @param state - Revision ID state */ export function wrapParagraphAsInserted(paragraph, author, dateStr, state) { // Mark the paragraph MARK as inserted (<w:pPr><w:rPr><w:ins/>). For a genuinely // inserted paragraph the paragraph break itself is a tracked insertion, so this // marker is what makes Reject All remove the whole paragraph (mark + content) and // Accept All keep it. The individual runs are wrapped in <w:ins> separately; this // function only adds the paragraph-mark marker. // // We ALWAYS emit the marker, including for non-empty paragraphs. A prior heuristic // omitted it when the paragraph had substantive run content, on the (uncited) belief // that Google Docs hides w:ins-wrapped runs that coexist with a PPR-INS marker. That // is false — Google Docs renders the inserted runs identically with or without // PPR-INS, and rejecting WITH the marker is cleaner there (it leaves no empty // paragraph). Omitting the marker forced Reject All to guess via a content-based // "all content is inside w:ins" heuristic that over-deleted foreign paragraphs whose // mark is untracked (i.e. text inserted into a pre-existing paragraph, which Word and // LibreOffice keep as an empty paragraph on reject). Reject is now purely mark-based // (see rejectAllChanges / rejectChanges), which requires this marker to be present. addParagraphMarkRevisionMarker(paragraph, 'w:ins', author, dateStr, state); return true; } /** * Wrap a deleted empty paragraph with <w:del>. * * @param paragraph - The w:p element * @param author - Author name * @param dateStr - Formatted date * @param state - Revision ID state */ export function wrapParagraphAsDeleted(paragraph, author, dateStr, state) { // See wrapParagraphAsInserted: represent paragraph deletion via a paragraph-mark // revision marker in w:pPr/w:rPr so Accept/Reject All behaves correctly. addParagraphMarkRevisionMarker(paragraph, 'w:del', author, dateStr, state); return true; } //# sourceMappingURL=inPlaceModifier-wrappers.js.map