@adeu/core 1.18.0 → 1.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adeu/core",
-  "version": "1.18.0",
+  "version": "1.18.2",
   "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.feedback.test.ts

@@ -31,7 +31,11 @@ describe("Feedback Layer & Dry Run Verification", () => {
     expect(stats.version).toBeDefined();
   });
 
-  it("punctuation anchor triggers warning", async () => {
+  it("punctuation anchor: no warning on clean apply", async () => {
+    // A punctuated anchor that matches and applies cleanly must NOT raise the
+    // tokenization-splitting warning. The redline preview already reports the
+    // change; a warning here is a false positive that pushes agents into
+    // needless "cleaner anchor" retries.
     const doc = await createTestDocument();
     addParagraph(doc, "Refer to sample_term_name in Section 4.");
     const engine = new RedlineEngine(doc, "Reviewer TS");
@@ -41,9 +45,37 @@ describe("Feedback Layer & Dry Run Verification", () => {
     ]);
 
     const report = stats.edits[0];
+    expect(report.status).toBe("applied");
+    expect(report.warning).toBeNull();
+
+    // Same expectation under dry_run.
+    const doc2 = await createTestDocument();
+    addParagraph(doc2, "Refer to sample_term_name in Section 4.");
+    const engine2 = new RedlineEngine(doc2, "Reviewer TS");
+    const dryStats = (engine2 as any).process_batch([
+      { type: "modify", target_text: "sample_term_name", new_text: "validated_term_name" }
+    ], true);
+    const dryReport = dryStats.edits[0];
+    expect(dryReport.status).toBe("applied");
+    expect(dryReport.warning).toBeNull();
+  });
+
+  it("punctuation anchor: warns only when match fails", async () => {
+    // When a punctuated anchor fails to match, the warning IS surfaced as
+    // recovery context (the punctuation may be why the match missed).
+    const doc = await createTestDocument();
+    addParagraph(doc, "Refer to sample_term_name in Section 4.");
+    const engine = new RedlineEngine(doc, "Reviewer TS");
+
+    const stats = (engine as any).process_batch([
+      { type: "modify", target_text: "phantom_term-x", new_text: "anything" }
+    ], true);
+
+    const report = stats.edits[0];
+    expect(report.status).toBe("failed");
     expect(report.warning).not.toBeNull();
     expect(report.warning.toLowerCase()).toContain("punctuation");
-    expect(report.warning).toContain("sample_term_name");
+    expect(report.warning).toContain("phantom_term-x");
   });
 
   it("dry_run does not mutate and reports safely", async () => {

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++) {
@@ -322,8 +327,19 @@ export class RedlineEngine {
     this.comments_manager = new CommentsManager(this.doc);
   }
 
+  /**
+   * Return a hint when a short, single-token anchor contains punctuation that
+   * can split awkwardly, else null.
+   *
+   * Surface this ONLY for edits that actually failed to match/apply. On a
+   * successful edit the batch report already carries the redline preview, so
+   * emitting this would be a false positive: the punctuation (dates,
+   * `[_name_]` placeholders, `____` blanks) is frequently the literal target
+   * and the edit succeeds despite it. Mirrors the Python engine.
+   */
   private _check_punctuation_warning(target_text: string): string | null {
     if (!target_text) return null;
+    if (target_text.length > 20 || target_text.includes(" ")) return null;
     if (target_text.includes("_") || target_text.includes("-")) {
       return `Warning: target_text '${target_text}' contains tokenization-splitting punctuation ('_' or '-'). This can trigger mid-word splits in the diff engine. Consider using a longer plain-prose anchor.`;
     }
@@ -386,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;
@@ -1347,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) {
@@ -1420,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;
@@ -1572,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,
@@ -1810,8 +1862,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;
       }
@@ -1850,10 +1911,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);
       }
@@ -1894,11 +1952,16 @@ export class RedlineEngine {
         for (let i = 0; i < edits.length; i++) {
           const edit = edits[i];
           const single_errors = this.validate_edits([edit], i);
-          const warning = this._check_punctuation_warning(
-            (edit as any).target_text || "",
-          );
           if (single_errors.length > 0) {
             skipped_edits++;
+            // Only surface the punctuation-anchor warning when the edit actually
+            // failed. A clean apply already returns the redline preview, so the
+            // warning is pure noise on success — and it misleads agents into
+            // hunting for a "cleaner" anchor that was never needed (e.g. on
+            // placeholders/dates where the punctuation IS the literal target).
+            const warning = this._check_punctuation_warning(
+              (edit as any).target_text || "",
+            );
             edits_reports.push({
               status: "failed",
               target_text: (edit as any).target_text || "",
@@ -1918,7 +1981,7 @@ export class RedlineEngine {
               status: "applied",
               target_text: (edit as any).target_text || "",
               new_text: (edit as any).new_text || "",
-              warning: warning,
+              warning: null,
               error: null,
               critic_markup: previews[0],
               clean_text: previews[1],
@@ -1935,6 +1998,9 @@ export class RedlineEngine {
               this.skipped_details.length > 0
                 ? this.skipped_details[this.skipped_details.length - 1]
                 : "Failed to apply edit";
+            const warning = this._check_punctuation_warning(
+              (edit as any).target_text || "",
+            );
             edits_reports.push({
               status: "failed",
               target_text: (edit as any).target_text || "",
@@ -1975,23 +2041,25 @@ 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) {
           const success = (edit as any)._applied_status || false;
           const error_msg = (edit as any)._error_msg || null;
-          const warning = this._check_punctuation_warning(
-            (edit as any).target_text || "",
-          );
           let critic_markup = null;
           let clean_text = null;
+          // Punctuation-anchor warning is failure-context only: on success the
+          // redline preview below already reports the change cleanly.
+          let warning: string | null = null;
           if (success) {
             const previews = this._build_edit_context_previews(edit);
             critic_markup = previews[0];
             clean_text = previews[1];
+          } else {
+            warning = this._check_punctuation_warning(
+              (edit as any).target_text || "",
+            );
           }
           edits_reports.push({
             status: success ? "applied" : "failed",
@@ -2017,7 +2085,7 @@ export class RedlineEngine {
       skipped_details: this.skipped_details,
       edits: edits_reports,
       engine: "node",
-      version: "1.10.0",
+      version: "1.18.2",
     };
   }
 
@@ -2562,7 +2630,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,
@@ -2915,7 +2986,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
@@ -3076,7 +3148,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!);