@adeu/core 1.19.1 → 1.21.0

package/src/mapper.ts

@@ -105,6 +105,12 @@ export function renumber_snapshot_ids(
   return [chg_remap, com_remap];
 }
 
+// Markdown style delimiters the projection emits as VIRTUAL spans around
+// formatted runs (see get_run_style_markers). Literal asterisks/underscores
+// typed in the document live inside real (run-backed) spans and are never
+// confused with these.
+const STYLE_MARKER_TEXTS = new Set(["**", "__", "*", "_"]);
+
 export class DocumentMapper {
   public doc: DocumentObject;
   public clean_view: boolean;
@@ -114,6 +120,7 @@ export class DocumentMapper {
   public spans: TextSpan[] = [];
   public appendix_start_index: number = -1;
   private _text_chunks: string[] = [];
+  private _plain_projection: [string, number[]] | null = null;
 
   constructor(
     doc: DocumentObject,
@@ -132,6 +139,7 @@ export class DocumentMapper {
     this.spans = [];
     this._text_chunks = [];
     this.full_text = "";
+    this._plain_projection = null;
 
     for (const part of iter_document_parts(this.doc)) {
       current_offset = this._map_blocks(part, current_offset);
@@ -800,6 +808,72 @@ export class DocumentMapper {
     return parts.join("");
   }
 
+  /**
+   * Returns [plain_text, offset_map] where plain_text is full_text with the
+   * VIRTUAL markdown style delimiters (bold/italic markers emitted around
+   * formatted runs) removed, and offset_map[i] is the full_text index of
+   * plain_text[i].
+   *
+   * Formatting run boundaries can fall mid-word (e.g. a paragraph projected
+   * as "**Al**pha"), where neither exact matching nor the whitespace-anchored
+   * fuzzy regex can find the plain target "Alpha". Matching against this
+   * projection and mapping the span back to full_text closes that gap (QA H2).
+   *
+   * Built lazily and invalidated by _build_map(): most batches never need it.
+   */
+  private _get_plain_projection(): [string, number[]] {
+    if (this._plain_projection === null) {
+      const chunks: string[] = [];
+      const offsets: number[] = [];
+      for (const s of this.spans) {
+        if (
+          s.run === null &&
+          s.paragraph !== null &&
+          STYLE_MARKER_TEXTS.has(s.text)
+        ) {
+          continue;
+        }
+        chunks.push(s.text);
+        for (let k = s.start; k < s.end; k++) offsets.push(k);
+      }
+      this._plain_projection = [chunks.join(""), offsets];
+    }
+    return this._plain_projection;
+  }
+
+  /**
+   * Matches a markdown-stripped target against the plain projection and maps
+   * each hit back to a [start, length] span in full_text. Interior style
+   * markers end up inside the returned span (so "Alpha" over "**Al**pha"
+   * resolves to the "Al**pha" range); markers just outside the matched
+   * characters are excluded.
+   */
+  private _find_plain_projection_matches(
+    target_text: string,
+  ): [number, number][] {
+    const [plain_text, offsets] = this._get_plain_projection();
+    if (plain_text.length === this.full_text.length) {
+      return []; // No virtual style markers anywhere; nothing new to find.
+    }
+    const norm_target = this._replace_smart_quotes(
+      this._strip_markdown_formatting(target_text),
+    );
+    if (!norm_target) return [];
+    const norm_plain = this._replace_smart_quotes(plain_text);
+    const results: [number, number][] = [];
+    let from = 0;
+    while (true) {
+      const p_start = norm_plain.indexOf(norm_target, from);
+      if (p_start === -1) break;
+      const p_end = p_start + norm_target.length;
+      const raw_start = offsets[p_start];
+      const raw_end = offsets[p_end - 1] + 1;
+      results.push([raw_start, raw_end - raw_start]);
+      from = p_end;
+    }
+    return results;
+  }
+
   public find_match_index(
     target_text: string,
     is_regex: boolean = false,
@@ -827,6 +901,12 @@ export class DocumentMapper {
       return [start_idx, stripped_target.length];
     }
 
+    // 3.5 Plain-projection match: the target crosses a formatting run
+    // boundary (possibly mid-word), so the projection carries style markers
+    // the plain target doesn't have (QA H2).
+    const plain_first = this._find_plain_projection_matches(target_text);
+    if (plain_first.length > 0) return plain_first[0];
+
     try {
       const pattern = new RegExp(this._make_fuzzy_regex(target_text));
       const match = pattern.exec(this.full_text);
@@ -851,34 +931,47 @@ export class DocumentMapper {
       } catch (e) {}
       return [];
     }
-    const escapeRegExp = (str: string) =>
-      str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // Exact tiers use plain indexOf scans, NOT RegExp: building a RegExp from
+    // an arbitrarily long escaped target throws "regular expression too
+    // large" for oversized inputs, crashing validation instead of returning
+    // a clean not-found (QA C2 hardening).
+    const findAllLiteral = (
+      haystack: string,
+      needle: string,
+    ): [number, number][] => {
+      const out: [number, number][] = [];
+      if (!needle) return out;
+      let from = 0;
+      while (true) {
+        const idx = haystack.indexOf(needle, from);
+        if (idx === -1) break;
+        out.push([idx, needle.length]);
+        from = idx + needle.length;
+      }
+      return out;
+    };
 
-    let matches = [
-      ...this.full_text.matchAll(new RegExp(escapeRegExp(target_text), "g")),
-    ];
-    if (matches.length > 0) return matches.map((m) => [m.index!, m[0].length]);
+    let matches = findAllLiteral(this.full_text, target_text);
+    if (matches.length > 0) return matches;
 
     const norm_full = this._replace_smart_quotes(this.full_text);
     const norm_target = this._replace_smart_quotes(target_text);
-    matches = [
-      ...norm_full.matchAll(new RegExp(escapeRegExp(norm_target), "g")),
-    ];
-    if (matches.length > 0) return matches.map((m) => [m.index!, m[0].length]);
+    matches = findAllLiteral(norm_full, norm_target);
+    if (matches.length > 0) return matches;
 
     const stripped_target = this._strip_markdown_formatting(target_text);
-    matches = [
-      ...this.full_text.matchAll(
-        new RegExp(escapeRegExp(stripped_target), "g"),
-      ),
-    ];
-    if (matches.length > 0) return matches.map((m) => [m.index!, m[0].length]);
+    matches = findAllLiteral(this.full_text, stripped_target);
+    if (matches.length > 0) return matches;
+
+    // 3.5 Plain-projection match (target spans a bold/italic run boundary,
+    // possibly mid-word). See _find_plain_projection_matches (QA H2).
+    const plain_matches = this._find_plain_projection_matches(target_text);
+    if (plain_matches.length > 0) return plain_matches;
 
     try {
       const pattern = new RegExp(this._make_fuzzy_regex(target_text), "g");
-      matches = [...this.full_text.matchAll(pattern)];
-      if (matches.length > 0)
-        return matches.map((m) => [m.index!, m[0].length]);
+      const fuzzy = [...this.full_text.matchAll(pattern)];
+      if (fuzzy.length > 0) return fuzzy.map((m) => [m.index!, m[0].length]);
     } catch (e) {}
 
     return [];
@@ -989,7 +1082,27 @@ export class DocumentMapper {
         if (preceding[i].run) return [preceding[i].run, preceding[i].paragraph];
       }
       for (let i = preceding.length - 1; i >= 0; i--) {
-        if (preceding[i].paragraph) return [null, preceding[i].paragraph];
+        const para = preceding[i].paragraph;
+        if (para) {
+          // Every span ending exactly here is virtual (CriticMarkup
+          // wrappers, {>>...<<} meta blocks, prefixes). If real text
+          // precedes this index in the SAME paragraph, anchor after its
+          // last run: falling back to the bare paragraph would drop the
+          // insertion at paragraph start, ahead of the very redlines and
+          // comment ranges that fence off the true position (mirrors the
+          // Python mapper).
+          for (let j = this.spans.length - 1; j >= 0; j--) {
+            const prev = this.spans[j];
+            if (
+              prev.end <= index &&
+              prev.run !== null &&
+              prev.paragraph === para
+            ) {
+              return [prev.run, prev.paragraph];
+            }
+          }
+          return [null, para];
+        }
       }
     }
 

package/src/markup.test.ts

@@ -174,7 +174,7 @@ describe('format_ambiguity_error (Turn Loop Trap mitigation)', () => {
     expect(msg).toContain('FIRST occurrence');
 
     // The original "add more context" guidance is preserved as a third option.
-    expect(msg).toContain('Please provide more surrounding context');
+    expect(msg).toContain('Provide more surrounding context');
   });
 
   it('still throws for fewer than two matches', () => {

package/src/markup.ts

@@ -424,17 +424,23 @@ export function format_ambiguity_error(
 
   // Tell the agent EXACTLY how to re-call. Without this, agents loop forever
   // refining target_text/regex because they never learn that match_mode is the
-  // built-in escape hatch for genuine ambiguity.
+  // built-in escape hatch for genuine ambiguity. The safe strategy (more
+  // context) comes first: blindly switching to "first"/"all" has silently
+  // modified unrelated occurrences — dates, section numbers — in real use
+  // (QA C1), so those options carry an explicit verification warning.
+  // Wording mirrors the Python engine's format_ambiguity_error.
   lines.push("  To resolve, re-send this edit using ONE of these strategies:");
   lines.push(
-    `    1. Set "match_mode": "all" to modify ALL ${total} occurrences (same target_text).`,
+    "    1. RECOMMENDED: Provide more surrounding context in your target_text to uniquely " +
+      'identify a single location (keep the default "match_mode": "strict").',
   );
   lines.push(
-    '    2. Set "match_mode": "first" to modify only the FIRST occurrence (same target_text).',
+    `    2. Set "match_mode": "all" to modify ALL ${total} occurrences — only after verifying ` +
+      "from the occurrence list above that EVERY occurrence should change.",
   );
   lines.push(
-    '    3. Please provide more surrounding context in your target_text to uniquely ' +
-      'identify a single location (keep the default "match_mode": "strict").',
+    '    3. Set "match_mode": "first" to modify only the FIRST occurrence — only after verifying ' +
+      "the first occurrence above is the one you intend to change.",
   );
 
   return lines.join("\n");

package/src/repro.insertion-anchor.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DocumentObject } from "./docx/bridge.js";
+import { RedlineEngine } from "./engine.js";
+import { extractTextFromBuffer } from "./ingest.js";
+import { createTestDocument, addParagraph } from "./test-utils.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Reproduction for the insertion-anchor bug (2026-07, golden.docx):
+// ModifyText("document" -> "finalized document") is diff-minimized to a
+// zero-width INSERTION of "finalized " immediately before "document". The
+// target paragraph already carries tracked changes ({--initial --}
+// {++golden ++}) and three comment ranges, so in the raw projection the
+// insertion index sits right after a virtual {>>...<<} meta block.
+// get_insertion_anchor only looked for a run-backed span ENDING exactly at
+// that index; every span ending there is virtual, so it fell back to
+// (null, paragraph) and the engine dropped the new <w:ins> at the START of
+// the paragraph — "finalized This is the golden document" after accept-all.
+// The fix anchors after the nearest preceding REAL run in the same
+// paragraph (mirrors the Python engine/mapper fix).
+describe("Zero-width insertion anchoring with preceding redlines/comments", () => {
+  it("lands the insertion before its target, not at paragraph start (golden.docx)", async () => {
+    const fixturePath = resolve(
+      __dirname,
+      "../../../../shared/fixtures/golden.docx",
+    );
+    const buf = readFileSync(fixturePath);
+    const doc = await DocumentObject.load(buf);
+    const engine = new RedlineEngine(doc, "T");
+
+    const stats = engine.process_batch([
+      { type: "modify", target_text: "document", new_text: "finalized document" },
+    ]);
+    expect(stats.edits_applied).toBe(1);
+
+    const out = await doc.save();
+    const clean = await extractTextFromBuffer(out, true);
+    expect(clean).toContain("golden finalized document");
+    expect(clean.startsWith("finalized This is")).toBe(false);
+
+    const red = await extractTextFromBuffer(out);
+    expect(red.startsWith("{++finalized")).toBe(false);
+  });
+
+  it("does not nest <w:ins> inside <w:del> when the anchor run is tracked-deleted", async () => {
+    const doc = await createTestDocument();
+    addParagraph(doc, "This is the initial document");
+
+    // Pass 1: track-delete "initial " so the raw projection becomes
+    // "This is the {--initial --}{>>[Chg:1 delete] T<<}document".
+    const engine1 = new RedlineEngine(doc, "T");
+    engine1.process_batch([
+      { type: "modify", target_text: "initial ", new_text: "" },
+    ]);
+    const deleted = await doc.save();
+
+    // Pass 2: zero-width insertion right before "document".
+    const doc2 = await DocumentObject.load(deleted);
+    const engine2 = new RedlineEngine(doc2, "T2");
+    engine2.process_batch([
+      { type: "modify", target_text: "document", new_text: "finalized document" },
+    ]);
+
+    const dels = Array.from(doc2.element.getElementsByTagName("w:del"));
+    for (const del of dels) {
+      expect(del.getElementsByTagName("w:ins").length).toBe(0);
+    }
+
+    const out = await doc2.save();
+    const clean = await extractTextFromBuffer(out, true);
+    expect(clean).toContain("This is the finalized document");
+  });
+
+  it("keeps genuine paragraph-start insertions at the paragraph start", async () => {
+    const doc = await createTestDocument();
+    addParagraph(doc, "Alpha beta gamma");
+    const engine = new RedlineEngine(doc, "T");
+
+    engine.process_batch([
+      { type: "modify", target_text: "Alpha", new_text: "Intro Alpha" },
+    ]);
+
+    const out = await doc.save();
+    const clean = await extractTextFromBuffer(out, true);
+    expect(clean).toContain("Intro Alpha beta gamma");
+  });
+});

package/src/repro_qa_report_v3.test.ts

@@ -172,10 +172,16 @@ describe("QA Report V3 Defects Reproductions", () => {
       } as any,
     ], true);
 
-    expect(res.edits_applied).toBe(1);
-    expect(res.edits_skipped).toBe(1);
+    // Dry-run mirrors the real run's transactional semantics (QA 2026-07-17
+    // M1 parity): a batch with any invalid edit applies nothing. The valid
+    // edit is reported as blocked by the batch, the invalid one keeps its own
+    // error.
+    expect(res.edits_applied).toBe(0);
+    expect(res.edits_skipped).toBe(2);
+    expect(res.edits[0].status).toBe("failed");
+    expect(res.edits[0].error).toContain("transactional");
     expect(res.edits[1].status).toBe("failed");
-    
+
     // Assert that the error message correctly labels it as Edit 2.
     // The buggy unpatched codebase says "Edit 1 Failed:" inside the error message for Edit 2.
     const errorMsg = res.edits[1].error;

package/src/utils/text.ts

@@ -0,0 +1,26 @@
+// FILE: src/utils/text.ts
+// Small text helpers shared by engine output paths. Mirrors the Python
+// engine's adeu/utils/text.py so both engines bound their report output
+// identically (QA C2).
+
+// Default cap for echoing caller-supplied strings (target_text/new_text) back
+// in batch reports and error messages. Reports feed straight into LLM context
+// windows via MCP, so an oversized edit value must never be reflected in full
+// (QA C2: a 2MB new_text was echoed twice, unbounded, in the apply report).
+export const REPORT_ECHO_CAP = 500;
+
+// Tighter cap for the inline redline preview snippets ({--...--}{++...++}),
+// which additionally carry surrounding document context.
+export const PREVIEW_TEXT_CAP = 200;
+
+/**
+ * Bounds `text` to roughly `cap` visible characters, keeping the head and
+ * tail and stating how much was omitted. Returns short strings unchanged.
+ */
+export function truncate_middle(text: string, cap: number): string {
+  if (text === null || text === undefined || text.length <= cap) return text;
+  const head = Math.max(1, Math.floor((cap * 2) / 3));
+  const tail = Math.max(1, cap - head);
+  const omitted = text.length - head - tail;
+  return `${text.slice(0, head)}… [${omitted.toLocaleString("en-US")} chars omitted] …${text.slice(-tail)}`;
+}