@usejunior/docx-core 0.14.0 → 0.16.0

package/dist/atomizer.d.ts

@@ -1,273 +0,0 @@
-/**
- * Atomizer Module
- *
- * Provides factory functions for creating ComparisonUnitAtom instances.
- * Implements the core atomization logic from WmlComparer.
- *
- * @see WmlComparer.cs ComparisonUnitAtom constructor (lines 2314-2343)
- */
-import { ComparisonUnitAtom, CorrelationStatus, OpcPart, WmlElement } from './core-types.js';
-/**
- * Calculate SHA1 hash of a string.
- *
- * Used for quick equality checking of comparison units.
- *
- * @param content - The string content to hash
- * @returns Hexadecimal SHA1 hash string
- */
-export declare function sha1(content: string): string;
-/**
- * Calculate SHA1 hash for a WmlElement.
- *
- * Includes tag name, attributes, and text content for uniqueness.
- * Excludes presentation-only attributes like xml:space that don't affect content.
- *
- * @param element - The element to hash
- * @returns Hexadecimal SHA1 hash string
- */
-export declare function hashElement(element: WmlElement): string;
-/**
- * Find a revision tracking element in the ancestor chain.
- *
- * Searches ancestors from nearest to root for w:ins, w:del, w:moveFrom, or w:moveTo.
- *
- * @param ancestors - Ancestor elements from root to parent
- * @returns The revision tracking element if found, undefined otherwise
- */
-export declare function findRevisionTrackingElement(ancestors: WmlElement[]): WmlElement | undefined;
-/**
- * Determine initial correlation status from revision tracking element.
- *
- * @param revTrackElement - The revision tracking element (if any)
- * @returns Initial correlation status
- */
-export declare function getStatusFromRevisionTracking(revTrackElement: WmlElement | undefined): CorrelationStatus;
-/**
- * Extract Unid attributes from ancestor elements.
- *
- * WmlComparer uses w:Unid attributes to correlate elements between documents.
- *
- * @param ancestors - Ancestor elements from root to parent
- * @returns Array of Unid values found in ancestors
- */
-export declare function extractAncestorUnids(ancestors: WmlElement[]): string[];
-/**
- * Tag names that are paragraph-level OOXML markers.
- *
- * These elements are valid as direct children of <w:p> (and revision wrappers
- * like <w:ins>/<w:del>/<w:moveFrom>/<w:moveTo>) but never inside <w:r>. The
- * rebuild reconstructor emits them as siblings of <w:r>, not leaves wrapped in
- * a synthetic run.
- *
- * Scope: commentRange, bookmark, moveFromRange / moveToRange, and
- * range-permission (permStart / permEnd) markers. Explicit move-range markers
- * coexist with the synthetic emission in wrapWithMoveFrom and wrapWithMoveTo:
- * the reconstructor suppresses synthesis for paragraphs whose atom stream
- * already carries explicit markers of the same kind, so the two paths never
- * double-emit.
- *
- * @conformance ECMA-376 edition 5, Part 1 § 17.13.5
- * @see https://github.com/UseJunior/safe-docx/issues/110
- * @see https://github.com/UseJunior/safe-docx/issues/111
- */
-export declare const PARAGRAPH_LEVEL_TAGS: Set<string>;
-/**
- * Special tag name for empty paragraph boundary atoms.
- * These atoms are created for paragraphs that have no content (only w:pPr).
- */
-export declare const EMPTY_PARAGRAPH_TAG = "__emptyParagraph__";
-export interface AtomizeTreeOptions {
-    /**
-     * Clone leaf nodes into atom.contentElement instead of reusing the parsed AST nodes.
-     *
-     * This prevents boundary normalization (merge/split) from mutating the document AST,
-     * which is required for safe `reconstructionMode: 'inplace'`.
-     *
-     * Default: false (preserve historical behavior/perf).
-     */
-    cloneLeafNodes?: boolean;
-    /**
-     * Allow normalization to merge atoms across run boundaries if formatting matches.
-     *
-     * For `reconstructionMode: 'inplace'`, this should usually be false so that atom
-     * ancestry continues to point at the correct run for wrapping.
-     *
-     * Default: true.
-     */
-    mergeAcrossRuns?: boolean;
-    /**
-     * Allow punctuation normalization to merge across run boundaries.
-     *
-     * Default: true.
-     */
-    mergePunctuationAcrossRuns?: boolean;
-    /**
-     * Split text atoms on word boundaries for fine-grained diffs.
-     *
-     * Default: true.
-     */
-    splitTextIntoWords?: boolean;
-    /**
-     * Atomize paragraph-level markers (commentRange*, bookmark*, moveFromRange*,
-     * moveToRange*, perm* — see PARAGRAPH_LEVEL_TAGS) so the rebuild
-     * reconstructor can re-emit them as siblings of <w:r>.
-     *
-     * MUST be false for inplace mode. Inplace handlers are run-anchored and
-     * silently no-op on atoms with no sourceRunElement, but inplace's bookmark
-     * reconciliation breaks if bookmarkStart/End atoms enter the stream
-     * (orphaned bookmark warnings, round-trip safety check fails).
-     *
-     * Default: false.
-     */
-    atomizeParagraphLevelMarkers?: boolean;
-}
-/**
- * Check if an element is a leaf node for atomization.
- *
- * Leaf nodes are the smallest units that can be compared.
- *
- * @param element - The element to check
- * @returns True if this is a leaf node
- */
-export declare function isLeafNode(element: WmlElement): boolean;
-/**
- * Check if an element is a paragraph-level OOXML marker.
- *
- * Paragraph-level markers (PARAGRAPH_LEVEL_TAGS: commentRange*, bookmark*,
- * moveFromRange*, moveToRange*, perm*) are
- * atomized only when they sit inside a <w:p> ancestor — body/table-sibling
- * placements stay out of the atom stream and are handled by the scaffold-strip
- * block in the reconstructor.
- */
-export declare function isParagraphLevelLeaf(element: WmlElement): boolean;
-/**
- * Options for creating a ComparisonUnitAtom.
- */
-export interface CreateAtomOptions {
-    /** The leaf element (w:t, w:br, etc.) */
-    contentElement: WmlElement;
-    /** Ancestor elements from root to parent of contentElement */
-    ancestors: WmlElement[];
-    /** The OPC part this atom belongs to */
-    part: OpcPart;
-}
-/**
- * Create a ComparisonUnitAtom from a leaf element.
- *
- * Replicates the C# ComparisonUnitAtom constructor logic:
- * 1. Finds revision tracking elements in ancestors
- * 2. Sets initial correlation status based on revision type
- * 3. Extracts ancestor Unids for correlation
- * 4. Calculates SHA1 hash for equality checking
- *
- * @param options - Options containing element, ancestors, and part
- * @returns A new ComparisonUnitAtom
- *
- * @see WmlComparer.cs lines 2314-2343
- */
-export declare function createComparisonUnitAtom(options: CreateAtomOptions): ComparisonUnitAtom;
-/**
- * Atomize a document tree into a flat list of ComparisonUnitAtoms.
- *
- * Recursively traverses the tree, creating atoms for each leaf node.
- * Also creates special atoms for empty paragraphs to preserve document structure.
- *
- * @param node - The current node in the tree
- * @param ancestors - Ancestor elements from root to parent of node
- * @param part - The OPC part this tree belongs to
- * @returns Array of ComparisonUnitAtoms from leaf nodes
- */
-export declare function atomizeTree(node: WmlElement, ancestors: WmlElement[], part: OpcPart, options?: AtomizeTreeOptions): {
-    atoms: ComparisonUnitAtom[];
-    emptyParagraphCount: number;
-};
-/**
- * Get all ancestors of a node by following parent references.
- *
- * @param node - The node to get ancestors for
- * @returns Array of ancestors from root to immediate parent
- */
-export declare function getAncestors(node: WmlElement): WmlElement[];
-/**
- * Assign paragraph indices to atoms based on their w:p ancestors.
- *
- * This enables paragraph grouping in the document reconstructor when
- * merging atoms from different source trees (original vs revised).
- *
- * @param atoms - Array of atoms to assign indices to
- */
-export declare function assignParagraphIndices(atoms: ComparisonUnitAtom[]): void;
-/**
- * Special tag name for collapsed field atoms.
- * These represent Word field codes (REF, PAGEREF, etc.) collapsed to their visible result.
- */
-export declare const COLLAPSED_FIELD_TAG = "__collapsedField__";
-/**
- * Collapse field sequences into single atoms based on visible text.
- *
- * Word fields consist of:
- * - w:fldChar[begin] - field start
- * - w:instrText - field instruction (e.g., "REF _Ref123 \h")
- * - w:fldChar[separate] - separates instruction from result
- * - w:t (one or more) - visible result text
- * - w:fldChar[end] - field end
- *
- * This function collapses each field sequence into a single atom whose hash
- * is based only on the visible text. This allows matching between:
- * - Hardcoded text: "2.6"
- * - Field reference: [REF field]2.6[/field]
- *
- * Both will produce atoms with the same hash if the visible text matches.
- *
- * NOTE: Multi-paragraph fields (like TOC, INDEX) are NOT collapsed because
- * they would lose paragraph structure information.
- *
- * @param atoms - Array of atoms from atomization
- * @returns Array with field sequences collapsed to single atoms
- */
-export declare function collapseFieldSequences(atoms: ComparisonUnitAtom[]): ComparisonUnitAtom[];
-/**
- * Split all w:t atoms into word-level atoms.
- *
- * @param atoms - Array of atoms
- * @returns Array with w:t atoms split into words
- */
-export declare function splitAtomsIntoWords(atoms: ComparisonUnitAtom[]): ComparisonUnitAtom[];
-/**
- * Find the nearest `w:hyperlink` ancestor of an atom, or null.
- *
- * Boundary normalization must never merge text atoms across a hyperlink
- * boundary: the surviving atom keeps a single ancestor chain, so a
- * cross-boundary merge either absorbs adjacent plain text into the link
- * (formatting bleed) or detaches link text from its wrapper.
- *
- * @conformance ECMA-376 edition 5, Part 1 § 17.16.22
- * @see https://github.com/UseJunior/safe-docx/issues/368
- */
-export declare function nearestHyperlinkAncestor(atom: ComparisonUnitAtom): WmlElement | null;
-/**
- * Merge punctuation-only atoms with preceding text.
- *
- * This handles cases where documents have different w:t boundaries around
- * punctuation (e.g., "Conduct" + "," vs "Conduct,"). Punctuation is merged
- * with the preceding word regardless of run formatting differences.
- *
- * @param atoms - Array of atoms
- * @returns Atoms with punctuation merged into preceding text
- */
-export declare function mergePunctuationAtoms(atoms: ComparisonUnitAtom[], options?: Required<Pick<AtomizeTreeOptions, 'mergePunctuationAcrossRuns'>>): ComparisonUnitAtom[];
-/**
- * Merge contiguous w:t atoms within the same run into single atoms.
- *
- * This normalization ensures that identical text split differently across
- * w:t elements in original vs revised documents will produce matching hashes.
- *
- * Example:
- *   Before: ["Def", "initions"] (2 atoms)
- *   After:  ["Definitions"] (1 atom)
- *
- * @param atoms - Array of atoms from atomization
- * @returns Normalized array with contiguous text atoms merged
- */
-export declare function mergeContiguousTextAtoms(atoms: ComparisonUnitAtom[], options?: Required<Pick<AtomizeTreeOptions, 'mergeAcrossRuns'>>): ComparisonUnitAtom[];
-//# sourceMappingURL=atomizer.d.ts.map

package/dist/atomizer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"atomizer.d.ts","sourceRoot":"","sources":["../src/atomizer.ts"],"names":[],"mappings":"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"}