@adeu/core 1.23.0 → 1.26.0

package/src/engine.ts

@@ -437,6 +437,26 @@ export class RedlineEngine {
       raw_sub_edits = [];
     }
 
+    // Hunks made purely of style markers are projection artifacts, never
+    // user intent: they arise when a PLAIN target fuzzy-matched styled
+    // document text ("Net 90 Days" against "**Net 90 Days**"), and the
+    // resulting `**`-deletion sub-edits target virtual spans that can never
+    // apply — phantom skips while the formatting silently stays (QA
+    // 2026-07-19 F-02 sibling). Edits that DO declare markers never reach
+    // this word-diff path (they resolve as whole-span markdown proxies).
+    const _marker_only = (text: string): boolean => {
+      const stripped = text.trim();
+      return stripped.length > 0 && /^[*_]+$/.test(stripped);
+    };
+    raw_sub_edits = raw_sub_edits.filter(
+      (e: any) =>
+        !(
+          (!e.target_text || _marker_only(e.target_text)) &&
+          (!e.new_text || _marker_only(e.new_text)) &&
+          (e.target_text || e.new_text)
+        ),
+    );
+
     if (!raw_sub_edits || raw_sub_edits.length === 0) {
       const fallback_edit: any = {
         type: "modify",
@@ -1394,6 +1414,15 @@ export class RedlineEngine {
     anchor_run: Run | null,
     anchor_paragraph: Paragraph | null,
     reuse_id: string,
+    // The attached DOM element the insertion physically follows. anchor_run
+    // supplies STYLING and may already be detached (the deletion step clones
+    // runs into <w:del> and replaces the originals); suffix relocation for
+    // paragraph-splitting insertions keys on this element instead.
+    positional_anchor_el: Element | null = null,
+    // When the edit declares explicit emphasis markers, the markers are
+    // authoritative: strip inherited bold/italic from the anchor style
+    // (QA 2026-07-19 F-02).
+    suppress_emphasis: boolean = false,
   ): {
     first_node: Element | null;
     last_p: Element | null;
@@ -1424,10 +1453,48 @@ export class RedlineEngine {
       current_p = walker;
     }
 
-    // Drop trailing empty line. "foo\n\nbar\n\n" splits to
-    // ['foo', '', 'bar', '']; that trailing empty is just a terminator, not
-    // a real empty paragraph.
-    while (lines.length > 1 && lines[lines.length - 1] === "") {
+    // Suffix nodes: content that follows the anchor inside current_p. When
+    // the inserted text carries paragraph breaks, this content belongs in
+    // the LAST new paragraph. The positional anchor is attached to the
+    // DOM, and the insertion lands immediately after it, so its following
+    // child-of-paragraph siblings are exactly the suffix.
+    const suffix_nodes: Element[] = [];
+    const pos_source =
+      positional_anchor_el && positional_anchor_el.parentNode
+        ? positional_anchor_el
+        : anchor_run !== null && anchor_run._element.parentNode
+          ? anchor_run._element
+          : null;
+    if (current_p !== null && pos_source !== null) {
+      let pos_anchor: Element | null = pos_source;
+      while (pos_anchor && pos_anchor.parentNode !== current_p) {
+        pos_anchor = pos_anchor.parentNode as Element | null;
+        if (pos_anchor === current_p) {
+          pos_anchor = null;
+          break;
+        }
+      }
+      if (pos_anchor) {
+        const relocatable = new Set(["w:r", "w:ins", "w:del"]);
+        let nxt = pos_anchor.nextSibling;
+        while (nxt) {
+          if (nxt.nodeType === 1 && relocatable.has((nxt as Element).tagName)) {
+            suffix_nodes.push(nxt as Element);
+          }
+          nxt = nxt.nextSibling;
+        }
+      }
+    }
+
+    // Drop the trailing empty line ONLY when there is no suffix to relocate.
+    // "foo\n\nbar\n\n" splits to ['foo', '', 'bar', '']; without a suffix
+    // the trailing empty is just a terminator, but with one it is the fresh
+    // destination paragraph the suffix moves into.
+    while (
+      lines.length > 1 &&
+      lines[lines.length - 1] === "" &&
+      suffix_nodes.length === 0
+    ) {
       lines.pop();
     }
     if (lines.length === 0) {
@@ -1454,6 +1521,7 @@ export class RedlineEngine {
         anchor_run,
         reuse_id,
         xmlDoc,
+        suppress_emphasis,
       );
       first_node = inline_ins;
       // Caller will attach `inline_ins` to the DOM later — keep it for now.
@@ -1539,6 +1607,7 @@ export class RedlineEngine {
         anchor_run,
         reuse_id,
         xmlDoc,
+        suppress_emphasis,
       );
       if (content_ins) {
         new_p.appendChild(content_ins);
@@ -1555,6 +1624,16 @@ export class RedlineEngine {
       }
     }
 
+    // Relocate the suffix into the last new paragraph: the paragraph break
+    // the insertion introduced splits current_p at the anchor, so everything
+    // after the anchor continues in the final inserted paragraph.
+    if (!block_mode && last_p && suffix_nodes.length > 0) {
+      for (const node of suffix_nodes) {
+        node.parentNode?.removeChild(node);
+        last_p.appendChild(node);
+      }
+    }
+
     return { first_node, last_p, last_ins, used_block_mode: block_mode };
   }
 
@@ -1568,6 +1647,7 @@ export class RedlineEngine {
     anchor_run: Run | null,
     reuse_id: string,
     xmlDoc: Document,
+    suppress_emphasis: boolean = false,
   ): Element | null {
     if (!line_text && line_text !== "") return null;
     const ins = this._create_track_change_tag("w:ins", "", reuse_id);
@@ -1577,25 +1657,26 @@ export class RedlineEngine {
     }
     for (const [segText, segProps] of segments) {
       const r = xmlDoc.createElement("w:r");
-      // Inherit run formatting (e.g. bold from a heading style) only when we
-      // have an anchor run AND we are not overriding via segment props.
+      // Inherit run formatting from the anchor so partial replacements inside
+      // a styled span keep the style (matching Word's type-into-selection
+      // behavior and the Python engine — the old blanket strip made
+      // "Important" -> "Critical" inside a bold span come out unstyled).
       if (anchor_run && anchor_run._element) {
         const anchor_rPr = findChild(anchor_run._element, "w:rPr");
         if (anchor_rPr) {
           const clone = anchor_rPr.cloneNode(true) as Element;
-          // Strip vanish / strike to avoid invisible inserts, and emphasis
-          // (bold/italic) so inserted replacement text does not silently
-          // inherit the anchor run's character formatting (BUG-23-2). Explicit
-          // markdown emphasis is re-applied per-segment via _apply_run_props.
-          for (const tag of [
-            "w:vanish",
-            "w:strike",
-            "w:dstrike",
-            "w:i",
-            "w:iCs",
-            "w:b",
-            "w:bCs",
-          ]) {
+          // Always strip vanish / strike (invisible inserts) and italic
+          // (BUG-23-2: an inserted replacement must not silently inherit the
+          // surrounding italic styling). Bold is preserved — it usually
+          // carries structural meaning (headings, defined terms) — UNLESS
+          // the edit's own markers are authoritative (QA 2026-07-19 F-02):
+          // `**X**` -> `_X_` must yield italic-only, `**X**` -> `X` plain.
+          // Mirrors the Python engine's _track_insert_inline exactly.
+          const strip_tags = ["w:vanish", "w:strike", "w:dstrike", "w:i", "w:iCs"];
+          if (suppress_emphasis) {
+            strip_tags.push("w:b", "w:bCs");
+          }
+          for (const tag of strip_tags) {
             const found = findChild(clone, tag);
             if (found) clone.removeChild(found);
           }
@@ -1628,7 +1709,13 @@ export class RedlineEngine {
       return [stripped_text.substring(2).trim(), "List Paragraph"];
     }
 
-    const match = stripped_text.match(/^\d+\.\s+/);
+    // Numbered lists: the projection emits ordered items with a CONSTANT
+    // "1. " marker (Markdown renumbers), so only that exact shape converts
+    // back into a list style. Any other leading number ("2024. Year in
+    // review", "3. Clause text") is literal document text. Continuation
+    // items inside an existing list anchor keep full "\d+." handling via
+    // the list-anchored insertion path.
+    const match = stripped_text.match(/^1\.\s+/);
     if (match) {
       return [stripped_text.substring(match[0].length).trim(), "List Number"];
     }
@@ -1636,6 +1723,28 @@ export class RedlineEngine {
     return [text, null];
   }
 
+  /**
+   * True when this edit's target or replacement text carries explicit
+   * bold/italic markers, making the markers AUTHORITATIVE for the inserted
+   * runs' formatting. Replacing `**X**` with `_X_` must yield italic-only
+   * text, and replacing `**X**` with `X` must yield plain text — inheriting
+   * the replaced span's run properties on top of (or instead of) the
+   * requested markers silently produces the wrong document while the report
+   * claims success (QA 2026-07-19 F-02). Plain-text edits (no markers on
+   * either side) keep inheriting the context style so partial replacements
+   * inside a styled span never lose formatting.
+   */
+  private _edit_declares_emphasis(edit: any): boolean {
+    for (const text of [edit?.target_text, edit?.new_text]) {
+      if (!text || (!text.includes("**") && !text.includes("_"))) continue;
+      const segments = this._parse_inline_markdown(text);
+      if (segments.some(([, props]: [string, any]) => props && Object.keys(props).length > 0)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   private _parse_inline_markdown(
     text: string,
     baseStyle: any = {},
@@ -1978,6 +2087,23 @@ export class RedlineEngine {
       const is_regex = (edit as any).regex || false;
       const match_mode = (edit as any).match_mode || "strict";
 
+      if (is_regex) {
+        // An unparsable pattern must be diagnosed as a regex problem. Without
+        // this check it falls through the matcher's silent guard and surfaces
+        // as "target text not found", sending the user hunting for a typo in
+        // the document instead of in the pattern (QA 2026-07-19 F-13).
+        try {
+          new RegExp(edit.target_text);
+        } catch (regex_err: any) {
+          errors.push(
+            `- Edit ${i + 1 + index_offset} Failed: target_text is not a valid regular expression ` +
+              `(${regex_err?.message ?? regex_err}). Fix the pattern, or set "regex": false to ` +
+              "match the text literally.",
+          );
+          continue;
+        }
+      }
+
       let matches = this.mapper.find_all_match_indices(
         edit.target_text,
         is_regex,
@@ -2796,6 +2922,14 @@ export class RedlineEngine {
       actions_skipped: skipped_actions,
       edits_applied: applied_edits,
       edits_skipped: skipped_edits,
+      // edits_applied counts change OBJECTS; this is the total number of
+      // document occurrences they modified (match_mode="all" fan-out), so
+      // automation never has to guess which of the two a count means
+      // (QA 2026-07-19 F-21).
+      occurrences_modified: edits_reports.reduce(
+        (sum: number, r: any) => sum + (r.occurrences_modified || 0),
+        0,
+      ),
       skipped_details: this.skipped_details,
       edits: edits_reports,
       engine: "node",
@@ -2823,6 +2957,7 @@ export class RedlineEngine {
       }
       edit._applied_status = false;
       edit._error_msg = null;
+      edit._any_sub_failure = false;
     }
 
     for (const edit of edits) {
@@ -2841,15 +2976,22 @@ export class RedlineEngine {
         resolved_edits.push([edit, edit.new_text || null]);
       } else if (edit.type === "insert_row" || edit.type === "delete_row") {
         let matches = this.mapper.find_all_match_indices(edit.target_text);
+        let resolved_mapper = this.mapper;
         if (matches.length === 0) {
           if (!this.clean_mapper) {
             this.clean_mapper = new DocumentMapper(this.doc, true);
           }
           matches = this.clean_mapper.find_all_match_indices(edit.target_text);
+          resolved_mapper = this.clean_mapper;
         }
 
         if (matches.length > 0) {
+          // Record WHICH mapper produced the offset: a clean-view index
+          // resolved against the raw mapper lands rows at the wrong position
+          // once earlier edits in the batch put tracked changes in the
+          // anchor row.
           edit._resolved_start_idx = matches[0][0];
+          edit._active_mapper_ref = resolved_mapper;
           resolved_edits.push([edit, null]);
         } else {
           skipped++;
@@ -2954,18 +3096,25 @@ export class RedlineEngine {
         this.skipped_details.push(msg);
         edit._applied_status = false;
         edit._error_msg = msg;
+        edit._any_sub_failure = true;
         const parent = edit._parent_edit_ref;
         if (parent) {
           parent._applied_status = false;
           parent._error_msg = msg;
+          parent._any_sub_failure = true;
         }
         continue;
       }
 
       let success = false;
       if (edit.type === "modify") {
-        const rebuild = edit._split_group_id !== undefined && edit._split_group_id !== null;
-        success = this._apply_single_edit_indexed(edit, orig_new, rebuild);
+        // Never rebuild the map inside the sweep: sub-edits apply in strictly
+        // descending offset order, and every DOM mutation (run splits, w:del
+        // wraps, w:ins insertions, bottom-up paragraph merges) happens at or
+        // above the current offset, so spans below it stay valid in the stale
+        // map. Rebuilding here made regex + match_mode="all"
+        // O(occurrences × document) (QA 2026-07-19 F-06).
+        success = this._apply_single_edit_indexed(edit, orig_new, false);
       } else if (edit.type === "insert_row" || edit.type === "delete_row") {
         success = this._apply_table_edit(edit, false);
       }
@@ -3023,8 +3172,10 @@ export class RedlineEngine {
         this.skipped_details.push(msg);
         edit._applied_status = false;
         edit._error_msg = msg;
+        edit._any_sub_failure = true;
         const parent = edit._parent_edit_ref;
         if (parent) {
+          parent._any_sub_failure = true;
           if (!parent._applied_status) {
             parent._applied_status = false;
             parent._error_msg = msg;
@@ -3033,7 +3184,25 @@ export class RedlineEngine {
       }
     }
 
-    return [applied, skipped];
+    // Return LOGICAL edit counts over the caller's input list: one
+    // match_mode="all" edit over N occurrences is one applied edit (its
+    // occurrence count lives in _occurrences_modified / the report), never N
+    // (QA 2026-07-19 F-21). An edit with any failed or skipped sub-edit
+    // counts as skipped so the all-or-nothing batch contract is unchanged.
+    let applied_logical = 0;
+    let skipped_logical = 0;
+    for (const input_edit of edits) {
+      if (typeof input_edit !== "object" || input_edit === null) {
+        skipped_logical++;
+        continue;
+      }
+      if (input_edit._applied_status && !input_edit._any_sub_failure) {
+        applied_logical++;
+      } else {
+        skipped_logical++;
+      }
+    }
+    return [applied_logical, skipped_logical];
   }
 
   public apply_review_actions(actions: any[]): [number, number] {
@@ -3160,7 +3329,11 @@ export class RedlineEngine {
       edit._resolved_start_idx !== null
         ? edit._resolved_start_idx
         : edit._match_start_index || 0;
-    const [anchor_run, anchor_para] = this.mapper.get_insertion_anchor(
+    // The offset must be looked up in the coordinate space it was resolved
+    // in: a clean-view offset applied to the raw
+    // mapper points at earlier text once tracked changes exist.
+    const active_mapper: DocumentMapper = edit._active_mapper_ref || this.mapper;
+    const [anchor_run, anchor_para] = active_mapper.get_insertion_anchor(
       start_idx,
       rebuild_map,
     );
@@ -3396,9 +3569,22 @@ export class RedlineEngine {
         const actual_cells = actual_doc_text.split("|");
         const new_cells = current_effective_new_text.split("|");
 
-        if (actual_cells.length === new_cells.length && actual_cells.length > 1) {
+        if (actual_cells.length !== new_cells.length) {
+          throw new BatchValidationError([
+            `Target text spans ${actual_cells.length} table cells, but replacement provides ${new_cells.length}. To modify text without altering table structure (rows or columns), ensure the replacement contains the exact same number of '|' separators (e.g., replace with 'CellC | ' to empty the second cell).`
+          ]);
+        }
+
+        if (actual_cells.length > 1) {
           const sub_edits: any[] = [];
-          let search_offset = start_idx;
+
+          // actual_doc_text IS the document slice at
+          // [start_idx, start_idx + len): per-cell offsets are exact
+          // arithmetic over that slice — never a search of mapper.full_text,
+          // which cannot distinguish repeated cell text and lands in the
+          // wrong cell when the matched range starts inside a " | "
+          // separator.
+          let cell_start_in_target = 0;
 
           // Determine which cell receives the comment
           let target_comment_idx = 0;
@@ -3414,14 +3600,10 @@ export class RedlineEngine {
             const n_cell = new_cells[cell_idx];
             const a_clean = a_cell.trim();
             const n_clean = n_cell.trim();
-
-            let actual_start = search_offset;
-            if (a_clean) {
-              actual_start = this.mapper.full_text.indexOf(a_clean, search_offset);
-              if (actual_start === -1 || actual_start > search_offset + 10) {
-                actual_start = search_offset;
-              }
-            }
+            const actual_start =
+              start_idx +
+              cell_start_in_target +
+              (a_clean ? a_cell.indexOf(a_clean) : 0);
 
             const should_attach_comment = (edit.comment !== null && edit.comment !== undefined) && (cell_idx === target_comment_idx);
 
@@ -3441,27 +3623,18 @@ export class RedlineEngine {
               }
             }
 
-            if (a_clean) {
-              search_offset = actual_start + a_clean.length;
-            }
-
-            const next_pipe = this.mapper.full_text.indexOf(" | ", search_offset);
-            if (next_pipe !== -1 && next_pipe <= search_offset + 10) {
-              search_offset = next_pipe + 3;
-            } else {
-              search_offset += a_cell.length + 1;
-            }
+            cell_start_in_target += a_cell.length + 1; // +1 for the '|'
           }
 
           for (const sub of sub_edits) {
             all_sub_edits.push(sub);
           }
           continue;
-        } else {
-          throw new BatchValidationError([
-            `Target text spans ${actual_cells.length} table cells, but replacement provides ${new_cells.length}. To modify text without altering table structure (rows or columns), ensure the replacement contains the exact same number of '|' separators (e.g., replace with 'CellC | ' to empty the second cell).`
-          ]);
         }
+        // Exactly one "cell": the target merely brushes a separator (its
+        // match range starts or ends inside " | ") without crossing into
+        // another cell's text. That is an ordinary in-cell edit — fall
+        // through to the standard resolution.
       }
 
       let has_markdown = false;
@@ -3575,6 +3748,26 @@ export class RedlineEngine {
         }
       }
 
+      // After trimming shared context, an edit whose target remainder is
+      // EMPTY is a pure insertion with exactly one hunk. Resolve it
+      // directly at the effective offset instead of word-diffing the full
+      // strings: dmp's alignment can cross-match punctuation between the
+      // shared context and the inserted text (pairing the period of "two."
+      // with "marker.") and split the insertion apart.
+      if (!final_target && final_new) {
+        all_sub_edits.push({
+          type: "modify",
+          target_text: "",
+          new_text: final_new,
+          comment: edit.comment,
+          _resolved_start_idx: effective_start_idx,
+          _match_start_index: effective_start_idx,
+          _internal_op: "INSERTION",
+          _active_mapper_ref: active_mapper,
+        });
+        continue;
+      }
+
       const sub_edits = this._word_diff_sub_edits(
         actual_doc_text,
         current_effective_new_text,
@@ -3663,6 +3856,14 @@ export class RedlineEngine {
       }
     }
 
+    // Explicit bold/italic markers in the edit make the markers
+    // authoritative: inserted runs must not additionally inherit the replaced
+    // span's emphasis (QA 2026-07-19 F-02). Keys on THIS resolved edit's
+    // post-trim fields: identical markers on both sides were absorbed into
+    // context (formatting unchanged — keep inheriting), and plain edits
+    // fuzzy-matched onto styled text never receive marker hunks at all.
+    const suppress_emphasis = this._edit_declares_emphasis(edit);
+
     if (op === "STYLE_ONLY" || op === "STYLE_AND_TEXT") {
       const [anchor_run, anchor_para] = active_mapper.get_insertion_anchor(
         start_idx,
@@ -3804,15 +4005,15 @@ export class RedlineEngine {
     if (op === "INSERTION") {
       let final_new_text = edit.new_text || "";
 
-      // QA 2026-07-18 C1: a MACHINE-PINNED pure insertion (diff/text
-      // round-trip output: authored with an empty target and no parent
-      // edit) positioned in the separator gap between the body and a
-      // following part used to anchor on the NEXT part's first paragraph,
-      // writing the new final body paragraph into word/footer1.xml.
-      // Re-anchor it to the end of the body and force new-paragraph
-      // semantics. Insertions DERIVED from a target-anchored edit (parent
-      // ref set — e.g. prepending "DRAFT " to "FOOTER MARKER") keep the
-      // user's chosen anchor: their context names the part they meant.
+      // A MACHINE-PINNED pure insertion (diff/text round-trip output:
+      // authored with an empty target and no parent edit) positioned in the
+      // separator gap between the body and a following part anchors to the
+      // end of the BODY with forced new-paragraph semantics — anchoring on
+      // the next part's first paragraph writes the new final body paragraph
+      // into word/footer1.xml. Insertions DERIVED from a target-anchored
+      // edit (parent ref set — e.g. prepending "DRAFT " to "FOOTER MARKER")
+      // keep the user's chosen anchor: their context names the part they
+      // meant.
       let boundary_anchor: TextSpan | null = null;
       const boundary =
         typeof (active_mapper as any).part_boundary_at === "function"
@@ -3923,6 +4124,7 @@ export class RedlineEngine {
             anchor_run,
             ins_id!,
             xmlDoc,
+            suppress_emphasis,
           );
           if (content_ins) new_p.appendChild(content_ins);
           body.insertBefore(new_p, _bug233_target_para);
@@ -3957,6 +4159,8 @@ export class RedlineEngine {
         anchor_run,
         anchor_para,
         ins_id!,
+        null,
+        suppress_emphasis,
       );
 
       if (!result.first_node) return false;
@@ -4168,6 +4372,10 @@ export class RedlineEngine {
         style_source_run,
         mod_anchor_para,
         ins_id!,
+        // The insertion physically follows the deletion block; the style
+        // run was detached when the deletion cloned it into <w:del>.
+        last_del,
+        suppress_emphasis,
       );
 
       if (result.first_node) {
@@ -4221,6 +4429,8 @@ export class RedlineEngine {
             anchor,
             first_span.paragraph,
             ins_id!,
+            null,
+            suppress_emphasis,
           );
           if (result.first_node) {
             p1_el.appendChild(result.first_node);

package/src/index.ts

@@ -5,7 +5,7 @@ export function identifyEngine() {
 export { DocumentObject } from './docx/bridge.js';
 export { DocumentMapper, TextSpan } from './mapper.js';
 export { RedlineEngine, BatchValidationError, validate_edit_strings, describe_illegal_control_chars } from './engine.js';
-export { generate_edits_from_text, generate_structured_edits, trim_common_context, create_unified_diff, create_word_patch_diff, DiffEdit } from './diff.js';
+export { generate_edits_from_text, generate_structured_edits, trim_common_context, create_unified_diff, create_word_patch_diff, collect_media_difference_warnings, DiffEdit } from './diff.js';
 export { apply_edits_to_markdown, MarkupEditReport } from './markup.js';
 export { paginate, split_structural_appendix, PaginationResult, PageInfo } from './pagination.js';
 export { extract_outline, OutlineNode } from './outline.js';

package/src/ingest.ts

@@ -347,16 +347,25 @@ export function build_paragraph_text(
           new_wrappers[0] === current_wrappers[0] &&
           new_wrappers[1] === current_wrappers[1]
         ) {
+          // Hoisted leading whitespace may sit before the incoming segment's
+          // opening marker ("**A**" + " **B**" -> "**A B**"), mirroring the
+          // mapper's part-level elision exactly (QA 2026-07-19 F-03).
+          const escaped_prefix = new_style[0].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+          const lead_match =
+            new_style[0] !== "" || new_style[1] !== ""
+              ? seg.match(new RegExp("^(\\s*)" + escaped_prefix))
+              : null;
           if (
             new_style[0] === current_style[0] &&
             new_style[1] === current_style[1] &&
             current_style[0] !== "" &&
             pending_text.endsWith(current_style[1]) &&
-            seg.startsWith(new_style[0])
+            lead_match !== null
           ) {
             pending_text =
               pending_text.slice(0, -current_style[1].length) +
-              seg.slice(new_style[0].length);
+              lead_match[1] +
+              seg.slice(lead_match[0].length);
           } else {
             pending_text += seg;
           }