@adeu/core 1.25.0 → 1.26.0

package/package.json

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

package/src/diff.ts

@@ -1,3 +1,4 @@
+import { unzipSync } from "fflate";
 import diff_match_patch from "diff-match-patch";
 import { DeleteTableRow, InsertTableRow, ModifyText } from "./models.js";
 import type {
@@ -475,6 +476,55 @@ function _drop_image_marker_hunks(
   return kept;
 }
 
+/**
+ * Removes generated hunks whose pinned range cuts INTO a read-only image
+ * marker without covering it whole — the shape an alt-text-only difference
+ * produces (`RED` -> `BLUE` inside `![RED logo](docx-image:1)`). The engine
+ * categorically rejects such edits, so emitting them makes diff output
+ * unappliable by apply (QA 2026-07-19 F-04/F-14). Hunks that contain
+ * complete markers are judged by _drop_image_marker_hunks instead.
+ */
+function _drop_marker_interior_hunks(
+  edits: ModifyText[],
+  text_orig: string,
+  warnings: string[],
+): ModifyText[] {
+  const marker_spans: [number, number][] = [];
+  for (const m of text_orig.matchAll(_IMAGE_MARKER_RE)) {
+    marker_spans.push([m.index!, m.index! + m[0].length]);
+  }
+  if (marker_spans.length === 0) return edits;
+
+  const kept: ModifyText[] = [];
+  let warned = false;
+  for (const e of edits) {
+    const idx = e._match_start_index;
+    if (idx === undefined || idx === null) {
+      kept.push(e);
+      continue;
+    }
+    const end = idx + (e.target_text || "").length;
+    const cuts_into_marker = marker_spans.some(
+      ([m_start, m_end]) =>
+        m_start < end && idx < m_end && !(idx <= m_start && m_end <= end),
+    );
+    if (!cuts_into_marker) {
+      kept.push(e);
+      continue;
+    }
+    if (!warned) {
+      warnings.push(
+        "An image's alternative text differs between the documents. Image markers " +
+          "(![alt](docx-image:N)) are read-only projections, so this difference cannot be " +
+          "expressed as a text edit — it was skipped; update the image or its alt text " +
+          "manually in Word.",
+      );
+      warned = true;
+    }
+  }
+  return kept;
+}
+
 /**
  * True when every projected row reads exactly as its cells joined by " | ".
  * Rows wrapped in tracked-row CriticMarkup ({++ … ++} / {-- … --}) do not,
@@ -704,8 +754,12 @@ export function generate_structured_edits(
         `${kinds_m.join(" + ") || "none"}); comparing flattened text instead. Header/footer ` +
         "additions or removals cannot be expressed as text edits.",
     );
-    const flat = _drop_image_marker_hunks(
-      generate_edits_from_text(text_orig, text_mod),
+    const flat = _drop_marker_interior_hunks(
+      _drop_image_marker_hunks(
+        generate_edits_from_text(text_orig, text_mod),
+        warnings,
+      ),
+      text_orig,
       warnings,
     );
     return { edits: [...flat], warnings };
@@ -848,11 +902,18 @@ export function generate_structured_edits(
   }
 
   // Our own output must never trip the engine's read-only image-marker
-  // validation: an added/removed image becomes a warning, not an edit.
+  // validation: an added/removed image becomes a warning, not an edit —
+  // and so does an alt-text change, whose hunk lands INSIDE a marker.
   const modify_edits = edits.filter(
     (e): e is ModifyText => e.type === "modify",
   );
-  const kept_modifies = new Set(_drop_image_marker_hunks(modify_edits, warnings));
+  const kept_modifies = new Set(
+    _drop_marker_interior_hunks(
+      _drop_image_marker_hunks(modify_edits, warnings),
+      text_orig,
+      warnings,
+    ),
+  );
   const final_edits = edits.filter(
     (e) => e.type !== "modify" || kept_modifies.has(e as ModifyText),
   );
@@ -860,6 +921,70 @@ export function generate_structured_edits(
   return { edits: final_edits, warnings };
 }
 
+/**
+ * Compares embedded media bytes (word/media/*) between two DOCX packages.
+ * Adeu's diff is a text comparison: two documents whose images differ but
+ * whose projections agree produce an empty diff, which reads as "visually
+ * identical" unless the caller says otherwise (QA 2026-07-19 F-04). Returns
+ * warning strings describing changed/added/removed media members; empty when
+ * the media sets are byte-identical (or either package is unreadable — the
+ * caller has already surfaced package-level errors).
+ */
+export function collect_media_difference_warnings(
+  original_docx: Uint8Array,
+  modified_docx: Uint8Array,
+): string[] {
+  const media_hashes = (data: Uint8Array): Map<string, string> => {
+    const hashes = new Map<string, string>();
+    try {
+      const unzipped = unzipSync(data);
+      for (const [name, bytes] of Object.entries(unzipped)) {
+        if (!name.startsWith("word/media/")) continue;
+        // FNV-1a over the bytes: cheap, dependency-free content fingerprint.
+        let h1 = 0x811c9dc5;
+        let h2 = 0xcbf29ce4;
+        for (let i = 0; i < bytes.length; i++) {
+          h1 = Math.imul(h1 ^ bytes[i], 0x01000193) >>> 0;
+          h2 = Math.imul(h2 ^ bytes[bytes.length - 1 - i], 0x01000193) >>> 0;
+        }
+        hashes.set(name, `${bytes.length}:${h1.toString(16)}:${h2.toString(16)}`);
+      }
+    } catch {
+      return new Map();
+    }
+    return hashes;
+  };
+
+  const hashes_orig = media_hashes(original_docx);
+  const hashes_mod = media_hashes(modified_docx);
+
+  const changed: string[] = [];
+  const added: string[] = [];
+  const removed: string[] = [];
+  for (const [name, hash] of hashes_orig) {
+    if (!hashes_mod.has(name)) removed.push(name);
+    else if (hashes_mod.get(name) !== hash) changed.push(name);
+  }
+  for (const name of hashes_mod.keys()) {
+    if (!hashes_orig.has(name)) added.push(name);
+  }
+  changed.sort();
+  added.sort();
+  removed.sort();
+  if (changed.length + added.length + removed.length === 0) return [];
+
+  const parts: string[] = [];
+  if (changed.length) parts.push(`${changed.length} changed`);
+  if (added.length) parts.push(`${added.length} added`);
+  if (removed.length) parts.push(`${removed.length} removed`);
+  const names = [...changed, ...added, ...removed].slice(0, 5).join(", ");
+  return [
+    `The documents' embedded media differ (${parts.join(", ")}: ${names}). This diff compares ` +
+      "TEXT only — an empty edit list does not mean the documents are visually identical. " +
+      "Image changes must be applied manually in Word.",
+  ];
+}
+
 export function create_unified_diff(
   original_text: string,
   modified_text: string,

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",
@@ -1399,6 +1419,10 @@ export class RedlineEngine {
     // 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;
@@ -1497,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.
@@ -1582,6 +1607,7 @@ export class RedlineEngine {
         anchor_run,
         reuse_id,
         xmlDoc,
+        suppress_emphasis,
       );
       if (content_ins) {
         new_p.appendChild(content_ins);
@@ -1621,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);
@@ -1630,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);
           }
@@ -1695,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 = {},
@@ -2037,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,
@@ -2855,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",
@@ -2882,6 +2957,7 @@ export class RedlineEngine {
       }
       edit._applied_status = false;
       edit._error_msg = null;
+      edit._any_sub_failure = false;
     }
 
     for (const edit of edits) {
@@ -3020,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);
       }
@@ -3089,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;
@@ -3099,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] {
@@ -3753,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,
@@ -4013,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);
@@ -4047,6 +4159,8 @@ export class RedlineEngine {
         anchor_run,
         anchor_para,
         ins_id!,
+        null,
+        suppress_emphasis,
       );
 
       if (!result.first_node) return false;
@@ -4261,6 +4375,7 @@ export class RedlineEngine {
         // 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) {
@@ -4314,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;
           }