@ansonlai/docx-redline-js 0.5.1 → 0.5.2

package/docs/TESTING.md

@@ -29,6 +29,7 @@ fixtures rarely contain.
 | Target hot-path parity | `node tests/performance_phase3_target_hot_paths_tests.mjs` | Cached and uncached resolution metadata parity, duplicate safety, snapshots, session invalidation, and pointer-based revision-ID seeding | Machine-independent latency thresholds |
 | List and text-walker parity | `node tests/performance_phase4_list_and_text_parity_tests.mjs` | One shared marker vocabulary and canonical/specialized visible-text agreement across structural characters and revision views | That all specialized mappings are interchangeable |
 | Route compatibility | `node tests/performance_phase5_route_consolidation_tests.mjs` | Direct/legacy list accepted-rejected parity, numbering artifacts, route selection, capability records, and stable public exports | Permission to migrate the retained multi-paragraph compatibility route |
+| Cross-author revision slicing | `node tests/cross_author_slicing_fixtures_tests.mjs`, `node tests/cross_author_carrier_splitting_tests.mjs`, `node tests/cross_author_slicing_synthetic_tests.mjs`, `node tests/cross_author_slicing_real_tests.mjs`, `node tests/cross_author_slicing_hyperlink_roundtrip_tests.mjs`, `node tests/cross_author_slicing_insertion_stress_tests.mjs` | Word-native `<w:ins>` splitting, `<w:del>` nesting, multi-author stacking, straddle boundaries, synthetic matrix (SYN-01..12d), strict package differential replay (PKG-01..06), exact hyperlink/NBSP round trips, and 76 insertion stress scenarios | Non-Word consumers beyond OpenXML XSD validation |
 
 The package-facade regression opens a real ZIP buffer, adds a comment beside an
 existing high ID, validates OPC wiring, and checks an unrelated binary part is
@@ -78,6 +79,23 @@ not correctness gates. Per-operation DOM savepoints are retained because
 redline accuracy, no-op isolation, and rollback fidelity take precedence over
 the aspirational speed target.
 
+## Cross-author revision slicing test suite
+
+The cross-author revision slicing subsystem introduces six complementary test lanes:
+
+1. **Native Word Desktop Fixtures (`tests/cross_author_slicing_fixtures_tests.mjs`)**:
+   Verifies 36 reference `.docx` and `.xml` files generated via Microsoft Word Desktop 365 COM automation across 6 golden scenarios (`insert-interior`, `delete-interior`, `delete-boundary-start`, `delete-boundary-end`, `delete-straddle-baseline-insertion`, and `multi-author-stacked`) in pending, accepted, and rejected states. Proves Word-native OOXML patterns (carrier `<w:ins>` splitting for insertions, direct `<w:del>` nesting inside `<w:ins>` for deletions) and lifecycle parity under `acceptTrackedChangesInOoxml` and `rejectTrackedChangesInOoxml`.
+2. **Carrier Splitting Unit Suite (`tests/cross_author_carrier_splitting_tests.mjs`)**:
+   Tests `splitTrackChangeCarrier` across interior and boundary cuts, multi-run formatting preservation, stable metadata cloning, independent revision ID allocation via `RevisionIdAllocator`, and immutable input handling.
+3. **Synthetic Boundary Matrix (`tests/cross_author_slicing_synthetic_tests.mjs`)**:
+   Executes the full SYN-01 through SYN-12d test matrix covering pure interior inserts, pure interior deletes, boundary start/end cuts, full-content annihilation, baseline/insertion straddles, multi-carrier straddles, formatting preservation, paired replacements, 3-author stacked revisions, and selective author accept/reject lifecycle oracles.
+4. **Checked-In Word Package Differential Suite (`tests/cross_author_slicing_real_tests.mjs`)**:
+   Reconstructs the pre-mutation document packages, applies `slice-cross-author` via the strict `openDocx` package facade, enforces atomic package validation, and compares engine `AcceptAll` and `RejectAll` output against Word Desktop-generated golden packages (PKG-01 through PKG-06).
+5. **Hyperlink and Exact-Text Regression (`tests/cross_author_slicing_hyperlink_roundtrip_tests.mjs`)**:
+   Reproduces the repeated-phrase, hyperlink-boundary, and NBSP-to-space failure through both the low-level engine and document operation runner. It requires exact accepted-view equality, preserves both hyperlink relationship containers, and proves that an unreconstructable slicing mutation returns `PATCH_ROUNDTRIP_MISMATCH` with the original OOXML unchanged.
+6. **Insertion Stress Matrix (`tests/cross_author_slicing_insertion_stress_tests.mjs`)**:
+   Runs 76 deterministic scenarios across carrier start/end/interior positions, repeated phrases, multi-run and formatted carriers, spaces/tabs/NBSP, XML-sensitive characters, emoji/combining Unicode, hyperlink interiors and boundaries, bookmarks, comments, nested deletions, adjacent authors, mixed same/foreign-author carriers, multiple structural containers, consecutive reviewer rounds, and the atomic document runner. Every supported case requires exact current-view, Accept-All, Reject-Current, schema, metadata, and non-empty-wrapper invariants; unsupported nested structures must fail without throwing or returning changed output.
+
 ## Coverage matrix and test selection
 
 Run the deterministic task-by-structure report before choosing the next Word

package/docs/plans/2026-09-08-cross-author-revision-slicing.md

@@ -439,6 +439,76 @@ type ExistingRevisionsPolicy =
   - The repository does not contain the private `agreement.docx` referenced by REAL-01/REAL-02 or the exact `c5bb43ede5...` corpus package referenced by REAL-03. Those named cases remain external acceptance scenarios rather than silently skipped automated tests.
   - REAL-04/REAL-05 require Microsoft Word Desktop COM and visual review. The checked-in fixtures were produced by Word COM, while the normal automated suite deliberately remains deterministic and non-interactive.
 
+### Bug Follow-Up: Hyperlink Boundary Round-Trip Mismatch [FIXED 2026-09-08]
+* **Report Reproduced**: A slicing edit with repeated text, hyperlink runs, and NBSP-to-space substitutions could return `status: "ok"` even though its accepted-view text differed from `modified`.
+* **Root Cause**: `applySurgicalMode` discarded whitespace-only insertion diff segments by checking `textWithoutNewlines.trim().length`. The corresponding NBSP deletion still committed, changing `located at\u00a0example.com` to `located atexample.com`. Structural replacement paths could also proceed after `PAIRING_SKIPPED_STRUCTURAL_BOUNDARY` without a final exact-text oracle.
+* **Fix**:
+  - Whitespace-only insertions are now applied rather than silently skipped.
+  - Every `slice-cross-author` surgical result reconstructs canonical accepted-view text and compares it exactly with the requested clean modified text.
+  - A mismatch returns `PATCH_ROUNDTRIP_MISMATCH`, `hasChanges: false`, diagnostic excerpts and offset, and the exact original OOXML. The document runner/facade therefore treats the operation as unapplied and preserves transactional rollback.
+* **Files Touched**:
+  - `engine/surgical-mode.js`
+  - `engine/oxml-engine.js`
+  - `tests/cross_author_slicing_hyperlink_roundtrip_tests.mjs` (NEW)
+  - `CHANGELOG.md`
+  - `README.md`
+  - `AGENTS.md`
+  - `docs/TESTING.md`
+  - `docs/plans/2026-09-08-cross-author-revision-slicing.md`
+* **Functions Touched / Created**:
+  - `applySurgicalMode` (MODIFIED): retains whitespace-only insertions and enforces the slicing accepted-view postcondition.
+  - `firstMismatchOffset` (NEW): locates the first exact-text divergence.
+  - `excerptAt` (NEW): provides bounded expected/actual diagnostics without returning entire contract paragraphs.
+  - `applyRedlineToOxml` surgical result handling (MODIFIED): restores the exact input OOXML on `PATCH_ROUNDTRIP_MISMATCH`.
+  - Test helpers `run`, `insertion`, `hyperlink`, and `acceptedParagraphText` (NEW).
+* **Regression Coverage**:
+  - Low-level reproduction with two hyperlink relationship containers, repeated `Widget Policy`, and three NBSP-to-space edits.
+  - Full `applyOperationsToDocumentXml` atomic runner reproduction matching the CLI execution path.
+  - Exact Accept-All equality with the submitted modified string.
+  - Explicit fail-closed test proving mismatch status, error code, mismatch offset, and byte-exact original OOXML rollback.
+* **Verification**:
+  - `node tests/cross_author_slicing_hyperlink_roundtrip_tests.mjs` — PASS.
+  - `npm test` — PASS, 93 test files passed and 0 failed.
+  - `npm run lint` — PASS.
+  - `npm run check:types` — PASS; all 123 runtime exports have declarations.
+  - `git diff --check` — PASS (line-ending conversion notices only; no whitespace errors).
+
+### Insertion Stress Follow-Up [COMPLETED 2026-09-08]
+* **Motivation**: Real usage reported failures across a wider variety of insertions after the first hyperlink/NBSP bug. A generated matrix was added to exercise location, payload, structure, lifecycle, and repeated-review dimensions rather than relying on a few fixed examples.
+* **Defects Exposed and Fixed**:
+  1. Leading/trailing spaces, tabs, and NBSP-only additions were classified as no-ops because slicing inherited trim-based text-change detection. `applyRedlineToOxml` now uses exact comparison for `slice-cross-author`.
+  2. Word-token semantic diff cleanup could relocate a pure insertion between repeated phrases, especially inside a hyperlink. `computeInsertionOnlyDiffs` now selects a character-local, no-deletion diff whenever the original is an exact subsequence of the modified text; replacements retain the established word diff and exact round-trip guard.
+  3. In a paragraph containing both current-author and foreign insertion carriers, inserting into the current-author carrier produced illegal nested `w:ins`. `processInsert` now adds a normal run to that existing carrier while continuing to split foreign carriers into siblings.
+* **Coverage Added**:
+  - 76 deterministic scenarios spanning carrier start/end/interior positions; single-, multi-, and formatted runs; repeated tokens; double spaces, tabs, NBSP, XML-sensitive characters, emoji, ZWJ emoji, combining characters, citations, and punctuation.
+  - Hyperlink interiors and both hyperlink boundaries; bookmarks; comment anchors; nested prior deletions; adjacent foreign authors; mixed current/foreign authors; three-container edits; and consecutive second-/third-reviewer rounds.
+  - Exact accepted-view, Accept-All, Reject-Current, validation, unique metadata, hyperlink preservation, and zero-empty-insertion assertions.
+  - Twenty scenarios also execute through `applyOperationsToDocumentXml` with atomic and strict-target settings, matching the CLI runner path.
+  - Nested hyperlink/field structures are required either to produce exact valid output or fail closed without throwing.
+* **Files Touched**:
+  - `pipeline/diff-engine.js`
+  - `engine/oxml-engine.js`
+  - `engine/surgical-mode.js`
+  - `engine/surgical-diff-application.js`
+  - `tests/cross_author_slicing_insertion_stress_tests.mjs` (NEW)
+  - `CHANGELOG.md`
+  - `README.md`
+  - `docs/TESTING.md`
+  - `docs/plans/2026-09-08-cross-author-revision-slicing.md`
+* **Functions Touched / Created**:
+  - `computeInsertionOnlyDiffs` (NEW): detects insertion-only transforms and returns a character-local diff only when it contains no deletion.
+  - `applyRedlineToOxml` (MODIFIED): uses exact slicing change detection, including boundary whitespace.
+  - `applySurgicalMode` (MODIFIED): selects insertion-only versus word diff without changing replacement semantics.
+  - `processInsert` (MODIFIED): inserts directly into an existing same-author carrier in mixed-author paragraphs.
+  - `isSameAuthorInsertion` (NEW): namespace-safe author comparison for carrier coalescing.
+  - Stress helpers `escapeXml`, `run`, `insertion`, `paragraph`, `parsed`, `acceptedText`, `authorOf`, `assertValid`, and `assertInsertionRoundTrip` (NEW).
+* **Verification**:
+  - `node tests/cross_author_slicing_insertion_stress_tests.mjs` — PASS, 76 scenarios.
+  - `npm test` — PASS, 94 test files passed and 0 failed.
+  - `npm run lint` — PASS.
+  - `npm run check:types` — PASS; all 123 runtime exports have declarations.
+  - `git diff --check` — PASS (line-ending conversion notices only; no whitespace errors).
+
 ---
 
 ## 6. Comprehensive Verification Plan (Synthetic & Real Test Series)

package/engine/oxml-engine.js

@@ -307,7 +307,9 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
     }
     const { cleanText: cleanModifiedText, formatHints } = preprocessMarkdown(sanitizedText);
 
-    const hasTextChanges = cleanModifiedText.trim() !== originalText.trim();
+    const hasTextChanges = existingRevisionsPolicy === 'slice-cross-author'
+        ? cleanModifiedText !== originalText
+        : cleanModifiedText.trim() !== originalText.trim();
     const hasFormatHints = formatHints.length > 0;
 
     const { existingFormatHints, textSpans, paragraphs } = extractFormattingFromOoxml(xmlDoc);
@@ -492,7 +494,7 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
             log('[OxmlEngine] Table cell edit: scoping surgical mode to target paragraph');
         }
 
-        const result = applySurgicalMode(
+        const result = applySurgicalMode(
             xmlDoc,
             originalText,
             cleanModifiedText,
@@ -502,10 +504,14 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
             generateRedlines,
             surgicalTarget,
             {},
-            options
-        );
-
-        if (tableCellContext.hasTableWrapper && result.hasChanges && tableCellContext.targetParagraph) {
+            options
+        );
+
+        if (result.status === 'error' && result.error?.code === 'PATCH_ROUNDTRIP_MISMATCH') {
+            return finalize({ ...result, oxml: inputOoxml, hasChanges: false });
+        }
+
+        if (tableCellContext.hasTableWrapper && result.hasChanges && tableCellContext.targetParagraph) {
             log('[OxmlEngine] Stripping table wrapper for table cell paragraph (surgical mode)');
             return finalize({ oxml: serializeParagraphOnly(xmlDoc, tableCellContext.targetParagraph, serializer), hasChanges: true });
         }

package/engine/surgical-diff-application.js

@@ -237,6 +237,12 @@ export function processInsert(xmlDoc, spanIndex, pos, text, author, formatHints
             return true;
         }
 
+        const generateNestedRevision = !(
+            generateRedlines
+            && existingRevisions === 'slice-cross-author'
+            && isSameAuthorInsertion(parent, author)
+        );
+
         if (
             generateRedlines
             && existingRevisions === 'slice-cross-author'
@@ -267,14 +273,14 @@ export function processInsert(xmlDoc, spanIndex, pos, text, author, formatHints
             const afterPieces = sliceRunPieces(xmlDoc, pieces, localInsertPos, getRunTextLength(pieces), false);
 
             insertRunPiecesBefore(xmlDoc, parent, targetSpan.runElement, beforePieces, targetSpan.rPr);
-            insertTextRuns(xmlDoc, parent, targetSpan.runElement, text, targetSpan.rPr, author, formatHints, insertOffset, generateRedlines, revisionMetadata);
+            insertTextRuns(xmlDoc, parent, targetSpan.runElement, text, targetSpan.rPr, author, formatHints, insertOffset, generateNestedRevision, revisionMetadata);
             insertRunPiecesBefore(xmlDoc, parent, targetSpan.runElement, afterPieces, targetSpan.rPr);
             parent.removeChild(targetSpan.runElement);
             return true;
         }
 
         const referenceNode = pos <= targetSpan.charStart ? targetSpan.runElement : targetSpan.runElement.nextSibling;
-        insertTextRuns(xmlDoc, parent, referenceNode, text, targetSpan.rPr, author, formatHints, insertOffset, generateRedlines, revisionMetadata);
+        insertTextRuns(xmlDoc, parent, referenceNode, text, targetSpan.rPr, author, formatHints, insertOffset, generateNestedRevision, revisionMetadata);
         return true;
     }
 
@@ -523,6 +529,12 @@ function isForeignInsertion(node, author) {
     return carrierAuthor.trim().toLowerCase() !== String(author || '').trim().toLowerCase();
 }
 
+function isSameAuthorInsertion(node, author) {
+    if (!isWordElement(node, 'ins')) return false;
+    const carrierAuthor = node.getAttribute('w:author') || node.getAttributeNS?.(NS_W, 'author') || '';
+    return carrierAuthor.trim().toLowerCase() === String(author || '').trim().toLowerCase();
+}
+
 function nextElementSibling(node) {
     let sibling = node?.nextSibling || null;
     while (sibling && sibling.nodeType !== 1) sibling = sibling.nextSibling;

package/engine/surgical-mode.js

@@ -6,7 +6,7 @@
  */
 
 import { getApplicableFormatHints } from '../pipeline/markdown-processor.js';
-import { computeWordDiffs } from '../pipeline/diff-engine.js';
+import { computeInsertionOnlyDiffs, computeWordDiffs } from '../pipeline/diff-engine.js';
 import { getDocumentParagraphs } from './format-extraction.js';
 import { buildSpanIndex, buildSurgicalTextSpans, forEachOverlappingSpan } from './surgical-spans.js';
 import {
@@ -16,6 +16,7 @@ import {
 } from './surgical-diff-application.js';
 import { withOoxmlSourceType } from '../core/word-xml.js';
 import { createReplacementRevisionEvent } from '../core/types.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
 
 function checkSafeAdjacencyForPairing(spanIndex, startPos, endPos, allowInsertionCarrier = false) {
     const spans = [];
@@ -111,7 +112,10 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
         : getDocumentParagraphs(xmlDoc);
 
     const { fullText, textSpans } = buildSurgicalTextSpans(allParagraphs);
-    const diffs = computeWordDiffs(fullText, modifiedText, diffOptions);
+    const insertionOnlyDiffs = options.existingRevisions === 'slice-cross-author'
+        ? computeInsertionOnlyDiffs(fullText, modifiedText)
+        : null;
+    const diffs = insertionOnlyDiffs || computeWordDiffs(fullText, modifiedText, diffOptions);
     const spanIndex = buildSpanIndex(textSpans);
     const pairReplacements = options.pairReplacements === true;
     const warnings = [];
@@ -151,7 +155,7 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
             if (pairReplacements && generateRedlines && hasNextInsert) {
                 const nextText = diffs[i + 1][1];
                 const textWithoutNewlines = nextText.replace(/\n/g, ' ');
-                if (textWithoutNewlines.trim().length > 0) {
+                if (textWithoutNewlines.length > 0) {
                     const checkResult = checkSafeAdjacencyForPairing(
                         spanIndex,
                         originalPos,
@@ -178,7 +182,7 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
                 i++;
                 const [, nextText] = diffs[i];
                 const textWithoutNewlines = nextText.replace(/\n/g, ' ');
-                if (textWithoutNewlines.trim().length > 0) {
+                if (textWithoutNewlines.length > 0) {
                     const insertResult = processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null, insMetadata, options?.insertionAffinity || null, options?.existingRevisions || 'merge-same-author');
                     if (insertResult && typeof insertResult === 'object' && insertResult.error) {
                         return withOoxmlSourceType({
@@ -196,7 +200,7 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
             }
         } else if (op === 1) {
             const textWithoutNewlines = text.replace(/\n/g, ' ');
-            if (textWithoutNewlines.trim().length > 0) {
+            if (textWithoutNewlines.length > 0) {
                 const insertResult = processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null, null, options?.insertionAffinity || null, options?.existingRevisions || 'merge-same-author');
                 if (insertResult && typeof insertResult === 'object' && insertResult.error) {
                     return withOoxmlSourceType({
@@ -214,9 +218,42 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
         }
     }
 
+    const actualText = allParagraphs.map(paragraph => extractCanonicalParagraphText(paragraph)).join('\n');
+    const expectedText = String(modifiedText).replace(/\r\n/g, '\n');
+    if (options.existingRevisions === 'slice-cross-author' && actualText !== expectedText) {
+        const mismatchOffset = firstMismatchOffset(expectedText, actualText);
+        return withOoxmlSourceType({
+            oxml: serializer.serializeToString(xmlDoc),
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'PATCH_ROUNDTRIP_MISMATCH',
+                message: 'Generated OOXML accepted-view text does not match the requested modified text; the mutation was rejected.',
+                mismatchOffset,
+                expectedExcerpt: excerptAt(expectedText, mismatchOffset),
+                actualExcerpt: excerptAt(actualText, mismatchOffset)
+            },
+            ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {})
+        });
+    }
+
     return withOoxmlSourceType({
         oxml: serializer.serializeToString(xmlDoc),
         hasChanges,
         ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {})
     });
 }
+
+function firstMismatchOffset(expected, actual) {
+    const limit = Math.min(expected.length, actual.length);
+    for (let index = 0; index < limit; index++) {
+        if (expected[index] !== actual[index]) return index;
+    }
+    return limit;
+}
+
+function excerptAt(text, offset, radius = 40) {
+    const start = Math.max(0, offset - radius);
+    const end = Math.min(text.length, offset + radius);
+    return text.slice(start, end);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",

package/pipeline/diff-engine.js

@@ -232,6 +232,28 @@ export function computeWordDiffs(originalText, newText, options = {}) {
     return decodeBmpDiffs(charDiffs, wordArray);
 }
 
+/**
+ * Returns a character-local diff only when the modified string can be made
+ * solely by inserting into the original. This prevents word-token cleanup
+ * from relocating small insertions between repeated phrases or containers.
+ *
+ * @param {string} originalText
+ * @param {string} newText
+ * @returns {Array<[number, string]>|null}
+ */
+export function computeInsertionOnlyDiffs(originalText, newText) {
+    if (originalText === newText) return [[0, originalText]];
+    if (!originalText) return [[1, newText]];
+    let originalIndex = 0;
+    for (let modifiedIndex = 0; modifiedIndex < newText.length && originalIndex < originalText.length; modifiedIndex++) {
+        if (newText[modifiedIndex] === originalText[originalIndex]) originalIndex++;
+    }
+    if (originalIndex !== originalText.length) return null;
+
+    const diffs = createDiffEngine().diff_main(originalText, newText);
+    return diffs.some(([op]) => op === -1) ? null : diffs;
+}
+
 /**
  * Computes word-level diff operations with offset tracking.
  *