@adeu/core 1.18.1 → 1.18.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adeu/core",
-  "version": "1.18.1",
+  "version": "1.18.4",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.comment-preservation.test.ts

@@ -0,0 +1,174 @@
+// FILE: node/packages/core/src/engine.comment-preservation.test.ts
+import { describe, it, expect } from "vitest";
+import { zipSync, strToU8 } from "fflate";
+import { DocumentObject } from "./docx/bridge.js";
+import { extract_comments_data } from "./comments.js";
+import { RedlineEngine } from "./engine.js";
+
+/**
+ * Regression test for author-aware comment preservation on accept/reject.
+ *
+ * Bug: accepting a tracked change whose run is wrapped by a comment caused
+ * `_clean_wrapping_comments` to delete that comment unconditionally — even when
+ * it belonged to another author. In the playbook-commenting scenario this
+ * silently erased the counterparty's ("Supplier's Counsel") annotation the
+ * instant their insertion (Chg:2) was accepted, destroying provenance and
+ * failing the "keep the counterparty comment" requirement.
+ *
+ * Fix: a wrapping comment authored by someone else has its range markers
+ * detached (so the accept proceeds with no orphaned anchor) but its BODY is
+ * kept in the comments part. Own-authored wrapping comments are still deleted.
+ *
+ * The triggering document is built in-memory as a minimal valid .docx so the
+ * test doesn't depend on the contents of any golden fixture: a paragraph with a
+ * foreign <w:ins id="2"> whose run is wrapped by comment id="1" from that same
+ * foreign author.
+ */
+
+const WORD_XMLNS =
+  'xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" ' +
+  'xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" ' +
+  'xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"';
+
+function xmlDecl(body: string): string {
+  return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' + body;
+}
+
+/**
+ * Build a minimal, valid DOCX buffer containing a wrapped foreign insertion:
+ *
+ *   commentRangeStart(1) → <w:ins id=2 author=insAuthor>run("INSERTED")</w:ins>
+ *   → commentRangeEnd(1) → <w:r><w:commentReference id=1/></w:r>
+ *
+ * plus a comments part with one comment id=1 authored by commentAuthor, body
+ * "robust protection". Includes [Content_Types].xml (with the comments
+ * Override) and word/_rels/document.xml.rels so `load()` classifies the parts.
+ */
+async function buildWrappedInsertionDoc(
+  insAuthor: string,
+  commentAuthor: string,
+): Promise<DocumentObject> {
+  const contentTypes = xmlDecl(
+    `<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+  <Override PartName="/word/comments.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"/>
+</Types>`,
+  );
+
+  const rootRels = xmlDecl(
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
+</Relationships>`,
+  );
+
+  const documentRels = xmlDecl(
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments" Target="comments.xml"/>
+</Relationships>`,
+  );
+
+  const documentXml = xmlDecl(
+    `<w:document ${WORD_XMLNS}>
+  <w:body>
+    <w:p w14:paraId="00000001">
+      <w:r><w:t xml:space="preserve">Prefix text. </w:t></w:r>
+      <w:commentRangeStart w:id="1"/>
+      <w:ins w:id="2" w:author="${insAuthor}" w:date="2026-01-01T00:00:00Z"><w:r><w:t>INSERTED</w:t></w:r></w:ins>
+      <w:commentRangeEnd w:id="1"/>
+      <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="1"/></w:r>
+      <w:r><w:t xml:space="preserve"> suffix text.</w:t></w:r>
+    </w:p>
+  </w:body>
+</w:document>`,
+  );
+
+  const commentsXml = xmlDecl(
+    `<w:comments ${WORD_XMLNS}>
+  <w:comment w:id="1" w:author="${commentAuthor}" w:date="2026-01-01T00:00:00Z" w:initials="SC"><w:p><w:r><w:t>robust protection</w:t></w:r></w:p></w:comment>
+</w:comments>`,
+  );
+
+  const zip: Record<string, Uint8Array> = {
+    "[Content_Types].xml": strToU8(contentTypes),
+    "_rels/.rels": strToU8(rootRels),
+    "word/document.xml": strToU8(documentXml),
+    "word/comments.xml": strToU8(commentsXml),
+    "word/_rels/document.xml.rels": strToU8(documentRels),
+  };
+
+  const buf = Buffer.from(zipSync(zip));
+  return DocumentObject.load(buf);
+}
+
+describe("author-aware wrapping-comment preservation", () => {
+  it("keeps a foreign author's wrapping comment when their change is accepted", async () => {
+    const doc = await buildWrappedInsertionDoc(
+      "Supplier's Counsel",
+      "Supplier's Counsel",
+    );
+
+    // Sanity: comment present before we touch anything.
+    const before = extract_comments_data(doc.pkg);
+    expect(Object.keys(before).length).toBe(1);
+    expect(before["1"].text).toContain("robust protection");
+
+    // We ("Authority Counsel") accept the counterparty's insertion Chg:2.
+    const engine = new RedlineEngine(doc, "Authority Counsel");
+    engine.process_batch(
+      [{ type: "accept", target_id: "Chg:2" } as any],
+      false,
+    );
+
+    // The counterparty's comment body must survive the accept.
+    const after = extract_comments_data(doc.pkg);
+    expect(after["1"]?.text).toContain("robust protection");
+
+    // The accept must actually have taken effect: the <w:ins> is unwrapped.
+    const savedBuf = await doc.save();
+    const reloaded = await DocumentObject.load(savedBuf);
+    expect(reloaded.element.getElementsByTagName("w:ins").length).toBe(0);
+
+    // Comment survives the roundtrip too.
+    const afterRoundtrip = extract_comments_data(reloaded.pkg);
+    expect(afterRoundtrip["1"]?.text).toContain("robust protection");
+  });
+
+  it("keeps a foreign author's wrapping comment when their change is rejected", async () => {
+    const doc = await buildWrappedInsertionDoc(
+      "Supplier's Counsel",
+      "Supplier's Counsel",
+    );
+
+    const engine = new RedlineEngine(doc, "Authority Counsel");
+    engine.process_batch(
+      [{ type: "reject", target_id: "Chg:2" } as any],
+      false,
+    );
+
+    // Rejecting removes the inserted TEXT, but the wrapping annotation (a
+    // separate comment) is preserved rather than collaterally deleted.
+    const after = extract_comments_data(doc.pkg);
+    expect(after["1"]?.text).toContain("robust protection");
+  });
+
+  it("still deletes our OWN wrapping comment when we accept our own change", async () => {
+    // Control: when the wrapping comment is ours, cleanup is unchanged — it is
+    // removed, matching prior behavior (keeping our own now-resolved note is not
+    // required).
+    const doc = await buildWrappedInsertionDoc(
+      "Authority Counsel",
+      "Authority Counsel",
+    );
+
+    const engine = new RedlineEngine(doc, "Authority Counsel");
+    engine.process_batch(
+      [{ type: "accept", target_id: "Chg:2" } as any],
+      false,
+    );
+
+    const after = extract_comments_data(doc.pkg);
+    expect(after["1"]).toBeUndefined();
+  });
+});

package/src/engine.ts

@@ -65,7 +65,6 @@ function insertAtIndex(parent: Element, index: number, child: Node) {
   }
 }
 
-
 function safeCloneEdit(val: any, seen: WeakMap<any, any> = new WeakMap()): any {
   if (val === null || typeof val !== "object") {
     return val;
@@ -127,7 +126,10 @@ function restoreSnapshot(doc: any, snapshot: any): void {
   }
 }
 
-function stripMatchingHeadingHashes(target: string, newText: string): [string, string] {
+function stripMatchingHeadingHashes(
+  target: string,
+  newText: string,
+): [string, string] {
   if (!target || !newText) return [target, newText];
   const targetMatch = target.match(/^(#+)\s+/);
   const newMatch = newText.match(/^(#+)\s+/);
@@ -150,7 +152,10 @@ export class BatchValidationError extends Error {
   }
 }
 
-export function validate_edit_strings(edits: any[], index_offset: number = 0): string[] {
+export function validate_edit_strings(
+  edits: any[],
+  index_offset: number = 0,
+): string[] {
   const errors: string[] = [];
 
   for (let i = 0; i < edits.length; i++) {
@@ -397,7 +402,8 @@ export class RedlineEngine {
     let target_text = edit.target_text || "";
     let new_text = edit.new_text || "";
 
-    const [clean_target, target_style] = this._parse_markdown_style(target_text);
+    const [clean_target, target_style] =
+      this._parse_markdown_style(target_text);
     if (target_style && target_style.startsWith("Heading")) {
       const prefix_len = target_text.length - clean_target.length;
       start_idx += prefix_len;
@@ -1358,7 +1364,29 @@ export class RedlineEngine {
 
     insertAfter(ref_run, new_end);
   }
-
+  /**
+   * Read a comment's author directly from the comments part. Used by
+   * _clean_wrapping_comments to decide whether a wrapping comment belongs to
+   * another author (and must be preserved when its anchored change is
+   * accepted/rejected) or to us (safe to delete). Reads the part rather than
+   * the mapper because the mapper's comments_map is not rebuilt between review
+   * actions, so it can be stale mid-batch. Returns null if not found.
+   */
+  private _get_comment_author(c_id: string): string | null {
+    const part = this.doc.pkg.parts.find(
+      (p) =>
+        p.contentType ===
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml",
+    );
+    if (!part) return null;
+    const comments = findAllDescendants(part._element, "w:comment");
+    for (const c of comments) {
+      if (c.getAttribute("w:id") === c_id) {
+        return c.getAttribute("w:author");
+      }
+    }
+    return null;
+  }
   private _clean_wrapping_comments(element: Element) {
     let first_node: Element = element;
     while (true) {
@@ -1431,7 +1459,21 @@ export class RedlineEngine {
     for (const s of starts_to_remove) {
       const c_id = s.getAttribute("w:id");
       if (c_id && end_ids.has(c_id)) {
-        this.comments_manager.deleteComment(c_id);
+        // Author-aware preservation. A comment that merely WRAPS the change
+        // being accepted/rejected is a separate annotation — often the
+        // counterparty's note explaining the very edit we are resolving.
+        // Deleting it silently destroys their provenance (and, e.g., fails a
+        // "keep the counterparty's comment" review requirement). So: always
+        // detach the range markers (leaving no orphaned anchor, which lets the
+        // accept/reject proceed cleanly), but only delete the comment BODY when
+        // it is ours. Foreign-authored comment bodies are kept in the comments
+        // part. When the author can't be read we default to preserving, since
+        // deletion is the irreversible, higher-cost mistake.
+        const author = this._get_comment_author(c_id);
+        const is_own = author !== null && author === this.author;
+        if (is_own) {
+          this.comments_manager.deleteComment(c_id);
+        }
         if (s.parentNode) s.parentNode.removeChild(s);
         for (const e of ends_to_remove) {
           let e_id: string | null = null;
@@ -1583,10 +1625,9 @@ export class RedlineEngine {
         if (edit.target_text.includes("|")) {
           matches = matches.slice(0, 1);
         } else {
-          const positions: [number, number][] = matches.map(([start, length]) => [
-            start,
-            start + length,
-          ]);
+          const positions: [number, number][] = matches.map(
+            ([start, length]) => [start, start + length],
+          );
           errors.push(
             format_ambiguity_error(
               i + 1 + index_offset,
@@ -1694,30 +1735,35 @@ export class RedlineEngine {
             }
           }
         }
-        if (insAuthors.size > 0 || commentAuthors.size > 0) {
+        if (insAuthors.size > 0) {
           // A single (strict/first) modification whose target lies ENTIRELY
-          // inside foreign-authored insertion(s), with no foreign comment
-          // overlap, is allowed: track_delete_run splits the enclosing <w:ins>
-          // and nests the change, producing valid tracked-change XML. Refuse the
-          // remaining cases — match_mode "all" fan-outs, partial overlaps that
-          // straddle the insertion boundary, and edits touching another author's
-          // comment range.
-          const fullyWithinForeignIns =
-            insAuthors.size > 0 &&
-            !hasNonForeignRealText &&
-            commentAuthors.size === 0;
+          // inside foreign-authored insertion(s) is allowed: track_delete_run
+          // splits the enclosing <w:ins> and nests the change, producing valid
+          // tracked-change XML. Refuse the remaining cases — match_mode "all"
+          // fan-outs and partial overlaps that straddle the insertion
+          // boundary.
+          const fullyWithinForeignIns = !hasNonForeignRealText;
           if (
-            (match_mode === "strict" || match_mode === "first") &&
-            fullyWithinForeignIns
+            !(
+              (match_mode === "strict" || match_mode === "first") &&
+              fullyWithinForeignIns
+            )
           ) {
+            errors.push(
+              `- Edit ${i + 1 + index_offset} Failed: Modification targets an active insertion from another author (${Array.from(insAuthors).join(", ")}). Accept that change first or scope your edit outside of it.`,
+            );
             continue;
           }
-          const nestedAuthors = new Set<string>([
-            ...insAuthors,
-            ...commentAuthors,
-          ]);
+        }
+        // Foreign comment ranges do NOT block deliberate single-occurrence
+        // edits: amending body text under a colleague's comment is a normal
+        // review workflow, and the comment anchor survives the tracked change.
+        // Only blind match_mode="all" fan-outs are refused, so a bulk
+        // replacement cannot silently sweep through another author's
+        // annotations (transactional rollback).
+        if (commentAuthors.size > 0 && match_mode === "all") {
           errors.push(
-            `- Edit ${i + 1 + index_offset} Failed: Modification targets an active insertion from another author (${Array.from(nestedAuthors).join(", ")}). Accept that change first or scope your edit outside of it.`,
+            `- Edit ${i + 1 + index_offset} Failed: match_mode="all" would sweep through a comment range from another author (${Array.from(commentAuthors).join(", ")}). Target the commented text deliberately with match_mode "strict" or "first", or scope your edit outside of it.`,
           );
         }
       }
@@ -1821,8 +1867,17 @@ export class RedlineEngine {
   ): any {
     // Pre-process edits: strip identical leading heading hashes from target_text and new_text
     for (const c of changes) {
-      if (c && typeof c === "object" && (c as any).type === "modify" && (c as any).target_text && (c as any).new_text) {
-        const [strippedTarget, strippedNew] = stripMatchingHeadingHashes((c as any).target_text, (c as any).new_text);
+      if (
+        c &&
+        typeof c === "object" &&
+        (c as any).type === "modify" &&
+        (c as any).target_text &&
+        (c as any).new_text
+      ) {
+        const [strippedTarget, strippedNew] = stripMatchingHeadingHashes(
+          (c as any).target_text,
+          (c as any).new_text,
+        );
         (c as any).target_text = strippedTarget;
         (c as any).new_text = strippedNew;
       }
@@ -1861,10 +1916,7 @@ export class RedlineEngine {
         actions.length > 0 ? this.validate_review_actions(actions) : [];
       const validate_edits_now = edits.length > 0 && action_errors.length > 0;
       const edit_errors = validate_edits_now ? this.validate_edits(edits) : [];
-      const all_errors = [
-        ...action_errors,
-        ...edit_errors,
-      ];
+      const all_errors = [...action_errors, ...edit_errors];
       if (all_errors.length > 0) {
         throw new BatchValidationError(all_errors);
       }
@@ -1994,9 +2046,7 @@ export class RedlineEngine {
           throw err;
         }
 
-        applied_edits = edits.filter(
-          (e) => (e as any)._applied_status,
-        ).length;
+        applied_edits = edits.filter((e) => (e as any)._applied_status).length;
         skipped_edits = edits.length - applied_edits;
 
         for (const edit of edits) {
@@ -2040,7 +2090,7 @@ export class RedlineEngine {
       skipped_details: this.skipped_details,
       edits: edits_reports,
       engine: "node",
-      version: "1.10.0",
+      version: "1.18.2",
     };
   }
 
@@ -2585,7 +2635,10 @@ export class RedlineEngine {
             const t_seg = target_segs[k];
             const n_seg = new_segs[k];
             if (t_seg !== n_seg) {
-              const [seg_prefix, seg_suffix] = trim_common_context(t_seg, n_seg);
+              const [seg_prefix, seg_suffix] = trim_common_context(
+                t_seg,
+                n_seg,
+              );
               const seg_target = t_seg.substring(
                 seg_prefix,
                 t_seg.length - seg_suffix,
@@ -2938,7 +2991,8 @@ export class RedlineEngine {
       const is_inline_first = result.first_node.tagName === "w:ins";
       if (is_inline_first) {
         if (anchor_run) {
-          const anchor_parent = anchor_run._element.parentNode as Element | null;
+          const anchor_parent = anchor_run._element
+            .parentNode as Element | null;
           if (anchor_parent && anchor_parent.tagName === "w:ins") {
             // Inserting inside another author's pending <w:ins>: split it so our
             // new <w:ins> lands as a sibling right after the anchor run, never
@@ -3099,7 +3153,11 @@ export class RedlineEngine {
             // nested in their <w:ins> and splice our new <w:ins> in right after
             // it by splitting their <w:ins>, so we never nest <w:ins> in
             // <w:ins>.
-            this._insert_and_split_ins(del_parent, last_del!, result.first_node);
+            this._insert_and_split_ins(
+              del_parent,
+              last_del!,
+              result.first_node,
+            );
           } else {
             // Inline: place the first <w:ins> immediately after last_del.
             insertAfter(result.first_node, last_del!);