@adeu/core 1.21.0 → 1.23.0

package/src/ingest.ts

@@ -9,19 +9,46 @@ import {
   get_run_text,
   apply_formatting_to_segments,
   iter_block_items,
-  iter_document_parts,
+  iter_document_parts_with_kind,
   iter_paragraph_content,
 } from "./utils/docx.js";
 import { findChild } from "./docx/dom.js";
 import { build_structural_appendix } from "./domain.js";
 import { extract_comments_data } from "./comments.js";
 
+/** Text-space extent of one projected table row plus its cell texts. */
+export interface RowGeometry {
+  start: number;
+  end: number;
+  cells: string[];
+}
+
+/** Text-space extent of one projected top-level table. */
+export interface TableGeometry {
+  start: number;
+  end: number;
+  rows: RowGeometry[];
+}
+
+/**
+ * Structural map of a projection: which offset ranges belong to which OPC
+ * part, and where top-level table rows live. Produced in the SAME pass as
+ * the text, so offsets always agree with it. Consumed by the diff pipeline
+ * to keep generated edits from crossing part boundaries (QA 2026-07-18 C1)
+ * and to emit structured row operations for table changes (QA C2).
+ */
+export interface ExtractStructure {
+  part_ranges: [number, number, string][]; // [start, end, kind]
+  tables: TableGeometry[];
+}
+
 export async function extractTextFromBuffer(
   buffer: Buffer,
   cleanView = false,
+  includeAppendix = true,
 ): Promise<string> {
   const doc = await DocumentObject.load(buffer);
-  return _extractTextFromDoc(doc, cleanView) as string;
+  return _extractTextFromDoc(doc, cleanView, includeAppendix) as string;
 }
 
 export function _extractTextFromDoc(
@@ -29,14 +56,21 @@ export function _extractTextFromDoc(
   cleanView = false,
   includeAppendix = true,
   return_paragraph_offsets = false,
-): string | { text: string; paragraph_offsets: Map<any, [number, number]> } {
+  return_structure = false,
+):
+  | string
+  | { text: string; paragraph_offsets: Map<any, [number, number]> }
+  | { text: string; structure: ExtractStructure } {
   const comments_map = extract_comments_data(doc.pkg);
 
   const full_text: string[] = [];
   const paragraph_offsets = new Map<any, [number, number]>();
+  const structure: ExtractStructure | null = return_structure
+    ? { part_ranges: [], tables: [] }
+    : null;
   let cursor = 0;
 
-  for (const part of iter_document_parts(doc)) {
+  for (const [part, part_kind] of iter_document_parts_with_kind(doc)) {
     const part_cursor = full_text.length > 0 ? cursor + 2 : cursor;
     const part_text = _extract_blocks(
       part,
@@ -44,10 +78,14 @@ export function _extractTextFromDoc(
       cleanView,
       part_cursor,
       return_paragraph_offsets ? paragraph_offsets : undefined,
+      structure ? structure.tables : undefined,
     );
     if (part_text) {
       if (full_text.length > 0) cursor += 2;
       full_text.push(part_text);
+      if (structure) {
+        structure.part_ranges.push([cursor, cursor + part_text.length, part_kind]);
+      }
       cursor += part_text.length;
     }
   }
@@ -62,15 +100,24 @@ export function _extractTextFromDoc(
   if (return_paragraph_offsets) {
     return { text: base_text, paragraph_offsets };
   }
+  if (structure) {
+    return { text: base_text, structure };
+  }
   return base_text;
 }
 
+/**
+ * table_acc: optional list collecting TableGeometry for TOP-LEVEL tables.
+ * Deliberately not forwarded into cells — nested tables stay invisible to
+ * the structured row-op diff, whose row pairing assumes one flat grid.
+ */
 function _extract_blocks(
   container: any,
   comments_map: any,
   cleanView: boolean,
   cursor: number,
   paragraph_offsets?: Map<any, [number, number]>,
+  table_acc?: TableGeometry[],
 ): string {
   const part = container.part || container;
   const [style_cache, default_pstyle] = _get_style_cache(part);
@@ -129,17 +176,25 @@ function _extract_blocks(
       is_first_para = false;
       is_first_block = false;
     } else if (item instanceof Table) {
+      const geometry: TableGeometry | null = table_acc
+        ? { start: block_start, end: block_start, rows: [] }
+        : null;
       const table_text = extract_table(
         item,
         comments_map,
         cleanView,
         block_start,
         paragraph_offsets,
+        geometry,
       );
       if (table_text) {
         blocks.push(table_text);
         local_cursor = block_start + table_text.length;
         is_first_block = false;
+        if (geometry && table_acc) {
+          geometry.end = block_start + table_text.length;
+          table_acc.push(geometry);
+        }
       } else if (!is_first_block) {
         local_cursor -= 2;
       }
@@ -156,6 +211,7 @@ export function extract_table(
   cleanView: boolean,
   cursor: number,
   paragraph_offsets?: Map<any, [number, number]>,
+  geometry?: TableGeometry | null,
 ): string {
   const rows_text: string[] = [];
   let rows_processed = 0;
@@ -221,6 +277,13 @@ export function extract_table(
 
     rows_text.push(row_str);
     local_cursor = row_start + row_str.length;
+    if (geometry) {
+      geometry.rows.push({
+        start: row_start,
+        end: local_cursor,
+        cells: [...cell_texts],
+      });
+    }
     rows_processed++;
   }
 
@@ -424,7 +487,16 @@ export function build_paragraph_text(
       else if (ev.type === "del_end") delete active_del[ev.id];
       else if (ev.type === "fmt_start") active_fmt[ev.id] = ev;
       else if (ev.type === "fmt_end") delete active_fmt[ev.id];
-      else if (ev.type === "footnote" || ev.type === "endnote") {
+      else if (ev.type === "image") {
+        // Read-only image marker (QA 2026-07-18 M5); hidden with its run in
+        // clean view when it sits inside an active tracked deletion.
+        if (!(cleanView && Object.keys(active_del).length > 0)) {
+          const alt = (ev.date || "image")
+            .replace(/\]/g, ")")
+            .replace(/\n/g, " ");
+          parts.push(`![${alt}](docx-image:${ev.id})`);
+        }
+      } else if (ev.type === "footnote" || ev.type === "endnote") {
         if (pending_text) {
           parts.push(
             `${current_wrappers[0]}${pending_text}${current_wrappers[1]}`,

package/src/mapper.ts

@@ -2,6 +2,7 @@ import { DocumentObject } from "./docx/bridge.js";
 import { Paragraph, Table, Run, DocxEvent } from "./docx/primitives.js";
 import { findAllDescendants, findChild } from "./docx/dom.js";
 import { extract_comments_data } from "./comments.js";
+import { RegexTimeoutError, userFindAllMatches, userSearch } from "./utils/safe-regex.js";
 import {
   _get_style_cache,
   get_paragraph_prefix,
@@ -10,7 +11,7 @@ import {
   is_heading_paragraph,
   is_native_heading,
   iter_block_items,
-  iter_document_parts,
+  iter_document_parts_with_kind,
   iter_paragraph_content,
 } from "./utils/docx.js";
 
@@ -24,6 +25,12 @@ export interface TextSpan {
   del_id?: string | null;
   hyperlink_id?: string | null;
   comment_ids?: string[];
+  // Which OPC part (index into DocumentMapper.part_ranges) this span was
+  // projected from. Text edits may never resolve across two different
+  // parts — the QA 2026-07-18 C1 corruption wrote body text into a footer.
+  part_index: number;
+  // True for the read-only image marker projection ![alt](docx-image:N).
+  is_image_marker?: boolean;
 }
 
 export function renumber_snapshot_ids(
@@ -119,6 +126,11 @@ export class DocumentMapper {
   public full_text: string = "";
   public spans: TextSpan[] = [];
   public appendix_start_index: number = -1;
+  // [start, end, kind] per projected part, in projection order. Spans carry
+  // the matching index in .part_index. Together these let the engine refuse
+  // or re-anchor edits at OPC part boundaries (QA 2026-07-18 C1).
+  public part_ranges: [number, number, string][] = [];
+  private _current_part_index = 0;
   private _text_chunks: string[] = [];
   private _plain_projection: [string, number[]] | null = null;
 
@@ -140,9 +152,15 @@ export class DocumentMapper {
     this._text_chunks = [];
     this.full_text = "";
     this._plain_projection = null;
+    this.part_ranges = [];
+    this._current_part_index = 0;
 
-    for (const part of iter_document_parts(this.doc)) {
+    let part_idx = 0;
+    for (const [part, part_kind] of iter_document_parts_with_kind(this.doc)) {
+      this._current_part_index = part_idx;
+      const part_start = current_offset;
       current_offset = this._map_blocks(part, current_offset);
+      this.part_ranges.push([part_start, current_offset, part_kind]);
 
       if (
         this.spans.length > 0 &&
@@ -151,6 +169,7 @@ export class DocumentMapper {
         this._add_virtual_text("\n\n", current_offset, null);
         current_offset += 2;
       }
+      part_idx++;
     }
 
     while (
@@ -165,6 +184,51 @@ export class DocumentMapper {
     this.appendix_start_index = -1;
   }
 
+  /** [part_index, start, end, kind] for parts that projected any text. */
+  private _nonempty_part_ranges(): [number, number, number, string][] {
+    const out: [number, number, number, string][] = [];
+    for (let i = 0; i < this.part_ranges.length; i++) {
+      const [s, e, k] = this.part_ranges[i];
+      if (e > s) out.push([i, s, e, k]);
+    }
+    return out;
+  }
+
+  public part_kind_of(part_index: number): string | null {
+    if (part_index >= 0 && part_index < this.part_ranges.length) {
+      return this.part_ranges[part_index][2];
+    }
+    return null;
+  }
+
+  /** Kind of the part whose projected range contains `index`, or null. */
+  public part_kind_at(index: number): string | null {
+    for (const [, start, end, kind] of this._nonempty_part_ranges()) {
+      if (start <= index && index <= end) return kind;
+    }
+    return null;
+  }
+
+  /**
+   * When `index` falls strictly AFTER one part's text and at-or-before the
+   * start of the next part's text (i.e. inside the "\n\n" separator or
+   * exactly at the next part's first character), returns
+   * [previous_part_index, next_part_index]. Returns null everywhere else —
+   * including index == previous part's end, which is an ordinary
+   * end-of-part text position, not a boundary gap.
+   */
+  public part_boundary_at(index: number): [number, number] | null {
+    const ranges = this._nonempty_part_ranges();
+    for (let j = 1; j < ranges.length; j++) {
+      const [prev_i, , prev_end] = ranges[j - 1];
+      const [next_i, next_start] = ranges[j];
+      if (prev_end < index && index <= next_start) {
+        return [prev_i, next_i];
+      }
+    }
+    return null;
+  }
+
   private _map_blocks(container: any, offset: number): number {
     let current = offset;
     const c_type = container.constructor.name;
@@ -334,6 +398,7 @@ export class DocumentMapper {
       text: "",
       run: null,
       paragraph,
+      part_index: this._current_part_index,
     };
     this.spans.push(span);
 
@@ -376,6 +441,7 @@ export class DocumentMapper {
             del_id: d_id || undefined,
             hyperlink_id: active_hyperlink_id || undefined,
             comment_ids: c_ids.length > 0 ? c_ids : undefined,
+            part_index: this._current_part_index,
           };
           this.spans.push(s);
           this._text_chunks.push(txt);
@@ -608,7 +674,21 @@ export class DocumentMapper {
         else if (ev.type === "del_end") delete active_del[ev.id];
         else if (ev.type === "fmt_start") active_fmt[ev.id] = ev;
         else if (ev.type === "fmt_end") delete active_fmt[ev.id];
-        else if (ev.type === "footnote" || ev.type === "endnote") {
+        else if (ev.type === "image") {
+          // Read-only image marker (QA 2026-07-18 M5). Hidden when the run is
+          // filtered by the active view, exactly like its neighbouring text.
+          const hidden =
+            (this.clean_view && Object.keys(active_del).length > 0) ||
+            (this.original_view && Object.keys(active_ins).length > 0);
+          if (!hidden) {
+            const alt = (ev.date || "image")
+              .replace(/\]/g, ")")
+              .replace(/\n/g, " ");
+            const txt = `![${alt}](docx-image:${ev.id})`;
+            this._add_virtual_text(txt, current, paragraph, null, true);
+            current += txt.length;
+          }
+        } else if (ev.type === "footnote" || ev.type === "endnote") {
           flush_pending_runs();
           current_wrappers = ["", ""];
           current_style = ["", ""];
@@ -742,6 +822,7 @@ export class DocumentMapper {
     offset: number,
     context_paragraph: Paragraph | null,
     hyperlink_id: string | null = null,
+    is_image_marker = false,
   ) {
     const span: TextSpan = {
       start: offset,
@@ -750,6 +831,8 @@ export class DocumentMapper {
       run: null,
       paragraph: context_paragraph,
       hyperlink_id: hyperlink_id || undefined,
+      part_index: this._current_part_index,
+      is_image_marker: is_image_marker || undefined,
     };
     this.spans.push(span);
     this._text_chunks.push(text);
@@ -879,11 +962,16 @@ export class DocumentMapper {
     is_regex: boolean = false,
   ): [number, number] {
     if (is_regex) {
+      // User/LLM-supplied pattern: run it under a wall-clock budget so a
+      // catastrophic pattern cannot hang the event loop (QA 2026-07-17 F5).
+      // RegexTimeoutError propagates for a clean per-edit error; only
+      // invalid-pattern errors mean "no match" here.
       try {
-        const pattern = new RegExp(target_text);
-        const match = pattern.exec(this.full_text);
-        if (match) return [match.index, match[0].length];
-      } catch (e) {}
+        const match = userSearch(target_text, this.full_text);
+        if (match) return [match.start, match.end - match.start];
+      } catch (e) {
+        if (e instanceof RegexTimeoutError) throw e;
+      }
       return [-1, 0];
     }
 
@@ -923,12 +1011,13 @@ export class DocumentMapper {
     if (!target_text) return [];
 
     if (is_regex) {
+      // Budgeted like find_match_index above (QA 2026-07-17 F5).
       try {
-        const pattern = new RegExp(target_text, "g");
-        const matches = [...this.full_text.matchAll(pattern)];
-        if (matches.length > 0)
-          return matches.map((m) => [m.index!, m[0].length]);
-      } catch (e) {}
+        const matches = userFindAllMatches(target_text, this.full_text);
+        if (matches.length > 0) return matches.map((m) => [m.start, m.end - m.start]);
+      } catch (e) {
+        if (e instanceof RegexTimeoutError) throw e;
+      }
       return [];
     }
     // Exact tiers use plain indexOf scans, NOT RegExp: building a RegExp from

package/src/markup.test.ts

@@ -115,7 +115,8 @@ describe('apply_edits_to_markdown', () => {
       { type: 'modify', target_text: 'C', new_text: 'Z' }
     ];
     const result = apply_edits_to_markdown(text, edits, true);
-    expect(result).toContain('[Edit:0]');
+    // 1-based, matching apply's "Edit N" reports (QA 2026-07-17 F10).
+    expect(result).toContain('[Edit:1]');
     expect(result.indexOf('{++X++}')).toBeLessThan(result.indexOf('{++Y++}'));
     expect(result.indexOf('{++Y++}')).toBeLessThan(result.indexOf('{++Z++}'));
   });