open-agreements
Version:
Open-source legal template filling CLI and library
99 lines • 4.76 kB
TypeScript
/**
* Auxiliary Part ID Collision Resolution
*
* Auxiliary part IDs (`w:id` on comments, footnotes, endnotes — OOXML
* ST_DecimalNumber) are document-local: independently authored documents
* routinely both start at `w:id="1"`. When the original and revised inputs
* define *different* content under the same ID, the post-reconstruction
* definition merge used to silently skip the source-side definition ("ID
* already present"), leaving anchors from one side bound to the other side's
* content.
*
* Strategy decision (issue #107 offered renumber vs. detect-and-flag): we
* renumber, because detect-and-flag would fail comparisons between any two
* independently authored commented documents — a core use case — and there is
* no collision-free fallback mode to flag into. Renumbering happens *before*
* comparison, on the revised archive, rather than inside the merge step:
* after reconstruction the merged document.xml no longer records which anchor
* came from which side, but at load time the revised archive can be rewritten
* consistently (part definition + every ID-bearing anchor in document.xml,
* header/footer parts, and the note stories — comments may be anchored on
* footnote/endnote text). Downstream, colliding anchors then differ by ID, so
* the LCS emits them as delete/insert pairs and the existing definition merge
* imports the renumbered definition — each anchor resolves to the content it
* was authored against, in both reconstruction modes.
*
* IDs whose definitions are content-identical on both sides are left alone so
* their anchors still match as unchanged content (no duplicate definitions),
* which keeps the common derived-document case byte-stable.
*
* Comment ancillary parts have a second collision axis: commentsExtended.xml
* and commentsIds.xml are keyed by the w14:paraId on comment-content
* paragraphs, not by w:id. We restamp colliding revised-side comment paraIds
* before comparison for the same reason: merged ancillary rows must never bind
* to the other document's comment paragraph.
*
* @see https://github.com/UseJunior/safe-docx/issues/107
* @see https://github.com/UseJunior/safe-docx/issues/448
*/
import type { DocxArchive } from '../../shared/docx/DocxArchive.js';
export interface AuxiliaryPartDescriptor {
label: string;
partPath: string;
referenceTag: string;
entryTag: string;
rootTag: string;
contentType: string;
relationshipType: string;
/**
* Every document.xml / header / footer tag that carries this part's `w:id`.
* Superset of `referenceTag`: comments also anchor via range markers.
*/
idBearingTags: string[];
}
export declare const AUXILIARY_PARTS: AuxiliaryPartDescriptor[];
/**
* Parse an auxiliary part and extract entry elements by ID.
*/
export declare function parseEntries(xml: string, entryTag: string): {
doc: Document;
entries: Map<string, Element>;
};
export interface RenumberedAuxiliaryId {
label: string;
fromId: string;
toId: string;
}
/**
* Detect auxiliary `w:id` values defined with different content on both
* sides and renumber the revised side's definitions and anchors into a fresh
* ID space, so the comparison never binds an anchor to the other document's
* content. Mutates `revisedArchive` in place; the originals' IDs are kept so
* the comparison base (rebuild mode clones the original archive) stays
* untouched.
*
* Anchors are rewritten in every revised-side story that can carry them:
* document.xml, header/footer parts, and the auxiliary parts themselves —
* Word allows comments anchored on footnote/endnote text, so a renumbered
* comment's anchor may live inside footnotes.xml/endnotes.xml.
*
* Returns the applied renumberings (empty on the no-collision fast path).
*/
export declare function renumberCollidingAuxiliaryIds(originalArchive: DocxArchive, revisedArchive: DocxArchive): Promise<RenumberedAuxiliaryId[]>;
export interface RestampedCommentParaId {
fromParaId: string;
toParaId: string;
}
/**
* Restamp revised-side comment paragraph paraIds when they collide with
* original-side comment paraIds that belong to different comment content.
*
* This pass intentionally matches literal Word prefixes (`w14`, `w15`, and
* `w16cid`) for both DOM lookup and raw allocation scans, consistent with the
* rest of this module's prefix-literal auxiliary part handling. Mutates
* `revisedArchive` in place and returns the applied restamps.
*
* @see https://github.com/UseJunior/safe-docx/issues/448
*/
export declare function restampCollidingCommentParaIds(originalArchive: DocxArchive, revisedArchive: DocxArchive): Promise<RestampedCommentParaId[]>;
//# sourceMappingURL=auxiliaryIdCollision.d.ts.map