@adeu/core 1.22.0 → 1.25.0

package/dist/index.d.cts

@@ -65,6 +65,8 @@ interface TextSpan {
     del_id?: string | null;
     hyperlink_id?: string | null;
     comment_ids?: string[];
+    part_index: number;
+    is_image_marker?: boolean;
 }
 declare class DocumentMapper {
     doc: DocumentObject;
@@ -74,10 +76,26 @@ declare class DocumentMapper {
     full_text: string;
     spans: TextSpan[];
     appendix_start_index: number;
+    part_ranges: [number, number, string][];
+    private _current_part_index;
     private _text_chunks;
     private _plain_projection;
     constructor(doc: DocumentObject, clean_view?: boolean, original_view?: boolean);
     private _build_map;
+    /** [part_index, start, end, kind] for parts that projected any text. */
+    private _nonempty_part_ranges;
+    part_kind_of(part_index: number): string | null;
+    /** Kind of the part whose projected range contains `index`, or null. */
+    part_kind_at(index: number): string | 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.
+     */
+    part_boundary_at(index: number): [number, number] | null;
     private _map_blocks;
     private _map_table;
     private _strip_markdown_formatting;
@@ -305,6 +323,19 @@ declare class RedlineEngine {
     private _getNextId;
     private _create_track_change_tag;
     private _set_text_content;
+    /**
+     * Walks `element` to its XML root element. Word (and LibreOffice, which
+     * refuses to LOAD such files) only supports comment ranges in the main
+     * document story ("w:document") — never in headers, footers, footnotes or
+     * endnotes (QA 2026-07-18 H4/C1).
+     */
+    private _comment_anchor_in_main_story;
+    /**
+     * When the anchor lives outside the main document story, records a
+     * user-visible warning and returns true (caller must skip the comment).
+     * The tracked change itself still applies — only the bubble is dropped.
+     */
+    private _skip_comment_outside_main_story;
     /**
      * Attaches a comment that wraps a contiguous range within a single paragraph.
      * start_element and end_element must both be direct children of parent_element
@@ -395,6 +426,13 @@ declare class RedlineEngine {
      * [start, start+length) in `mapper`, or null if that text is not inside a
      * table row.
      */
+    /**
+     * True when a replacement anchored in a table would ADD line-separated
+     * pipe-delimited content — the text shape of a table row. Writing that
+     * into a cell renders a fake row inside one cell while the real grid
+     * stays unchanged (QA 2026-07-18 C2); such edits must use insert_row.
+     */
+    private static _introduces_table_row_text;
     private static _column_count_at;
     validate_review_actions(actions: any[]): string[];
     process_batch(changes: DocumentChange[], dry_run?: boolean): any;
@@ -415,12 +453,86 @@ declare class RedlineEngine {
     private _apply_single_edit_indexed;
 }
 
+/** Text-space extent of one projected table row plus its cell texts. */
+interface RowGeometry {
+    start: number;
+    end: number;
+    cells: string[];
+}
+/** Text-space extent of one projected top-level table. */
+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).
+ */
+interface ExtractStructure {
+    part_ranges: [number, number, string][];
+    tables: TableGeometry[];
+}
+declare function extractTextFromBuffer(buffer: Buffer, cleanView?: boolean, includeAppendix?: boolean): Promise<string>;
+declare function _extractTextFromDoc(doc: DocumentObject, cleanView?: boolean, includeAppendix?: boolean, return_paragraph_offsets?: boolean, return_structure?: boolean): string | {
+    text: string;
+    paragraph_offsets: Map<any, [number, number]>;
+} | {
+    text: string;
+    structure: ExtractStructure;
+};
+
+type DiffEdit = ModifyText | InsertTableRow | DeleteTableRow;
 declare function trim_common_context(target: string, new_val: string): [number, number];
 declare function generate_edits_from_text(original_text: string, modified_text: string): ModifyText[];
+/**
+ * DOCX-to-DOCX diff over projections extracted with return_structure=true.
+ *
+ * Improvements over a flat generate_edits_from_text pass:
+ *   - each OPC part (header/body/footer/notes) diffs against its
+ *     counterpart, so no edit can span a part boundary and content that
+ *     moved between parts is reported instead of hidden (QA 2026-07-18 C1);
+ *   - table row insertions/deletions become structured insert_row /
+ *     delete_row operations instead of pipe-text edits (QA C2).
+ *
+ * Every ModifyText keeps its _match_start_index pinned into text_orig, which
+ * the engine consumes positionally (the Node engine has no
+ * make_edits_self_contained JSON round trip like the Python CLI).
+ *
+ * Returns { edits, warnings }. Warnings describe fallbacks the caller should
+ * surface (differing part layouts, unanchorable rows, …).
+ */
+declare function generate_structured_edits(text_orig: string, struct_orig: ExtractStructure, text_mod: string, struct_mod: ExtractStructure): {
+    edits: DiffEdit[];
+    warnings: string[];
+};
 declare function create_unified_diff(original_text: string, modified_text: string, context_lines?: number): string;
 declare function create_word_patch_diff(original_text: string, modified_text: string, original_path?: string, modified_path?: string): string;
 
-declare function apply_edits_to_markdown(markdown_text: string, edits: ModifyText[], include_index?: boolean, highlight_only?: boolean): string;
+/** One entry per input edit in apply_edits_to_markdown's edit_reports. */
+interface MarkupEditReport {
+    index: number;
+    status: "applied" | "failed";
+    error: string | null;
+    occurrences: number;
+}
+/**
+ * Applies edits to Markdown text and returns CriticMarkup-annotated output.
+ *
+ * Edit resolution follows the SAME semantics as `apply` (QA 2026-07-18 M1):
+ *   - `regex: true` targets match as regular expressions
+ *   - `match_mode` is honored: "strict" (default) refuses ambiguous targets,
+ *     "first" marks the first occurrence, "all" marks every occurrence
+ *   - a missing target is a per-edit failure, never a silent skip
+ *
+ * When `edit_reports` is provided, one entry per input edit is appended:
+ * { index: 0-based input position, status: "applied"|"failed",
+ *   error: string|null, occurrences: number }.
+ */
+declare function apply_edits_to_markdown(markdown_text: string, edits: ModifyText[], include_index?: boolean, highlight_only?: boolean, edit_reports?: MarkupEditReport[]): string;
 
 /**
  * Stateless paginator for projected DOCX Markdown.
@@ -456,12 +568,6 @@ interface OutlineNode {
 }
 declare function extract_outline(doc: DocumentObject, projected_body: string, body_pages: string[], body_page_offsets: number[], paragraph_offsets?: Record<string, [number, number]> | Map<any, [number, number]> | null): OutlineNode[];
 
-declare function extractTextFromBuffer(buffer: Buffer, cleanView?: boolean): Promise<string>;
-declare function _extractTextFromDoc(doc: DocumentObject, cleanView?: boolean, includeAppendix?: boolean, return_paragraph_offsets?: boolean): string | {
-    text: string;
-    paragraph_offsets: Map<any, [number, number]>;
-};
-
 interface FinalizeOptions {
     filename: string;
     sanitize_mode?: 'full' | 'keep-markup' | 'baseline';
@@ -515,4 +621,4 @@ declare function userSearch(pattern: string, text: string, flags?: string): {
 
 declare function identifyEngine(): string;
 
-export { BatchValidationError, DocumentMapper, DocumentObject, type FinalizeOptions, type FinalizeResult, type OutlineNode, type PageInfo, type PaginationResult, RedlineEngine, RegexTimeoutError, type TextSpan, USER_PATTERN_TIMEOUT_MS, _extractTextFromDoc, apply_edits_to_markdown, create_unified_diff, create_word_patch_diff, describe_illegal_control_chars, extractTextFromBuffer, extract_outline, finalize_document, generate_edits_from_text, identifyEngine, paginate, split_structural_appendix, trim_common_context, userFindAllMatches, userSearch, validate_edit_strings };
+export { BatchValidationError, type DiffEdit, DocumentMapper, DocumentObject, type ExtractStructure, type FinalizeOptions, type FinalizeResult, type MarkupEditReport, type OutlineNode, type PageInfo, type PaginationResult, RedlineEngine, RegexTimeoutError, type RowGeometry, type TableGeometry, type TextSpan, USER_PATTERN_TIMEOUT_MS, _extractTextFromDoc, apply_edits_to_markdown, create_unified_diff, create_word_patch_diff, describe_illegal_control_chars, extractTextFromBuffer, extract_outline, finalize_document, generate_edits_from_text, generate_structured_edits, identifyEngine, paginate, split_structural_appendix, trim_common_context, userFindAllMatches, userSearch, validate_edit_strings };

package/dist/index.d.ts

@@ -65,6 +65,8 @@ interface TextSpan {
     del_id?: string | null;
     hyperlink_id?: string | null;
     comment_ids?: string[];
+    part_index: number;
+    is_image_marker?: boolean;
 }
 declare class DocumentMapper {
     doc: DocumentObject;
@@ -74,10 +76,26 @@ declare class DocumentMapper {
     full_text: string;
     spans: TextSpan[];
     appendix_start_index: number;
+    part_ranges: [number, number, string][];
+    private _current_part_index;
     private _text_chunks;
     private _plain_projection;
     constructor(doc: DocumentObject, clean_view?: boolean, original_view?: boolean);
     private _build_map;
+    /** [part_index, start, end, kind] for parts that projected any text. */
+    private _nonempty_part_ranges;
+    part_kind_of(part_index: number): string | null;
+    /** Kind of the part whose projected range contains `index`, or null. */
+    part_kind_at(index: number): string | 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.
+     */
+    part_boundary_at(index: number): [number, number] | null;
     private _map_blocks;
     private _map_table;
     private _strip_markdown_formatting;
@@ -305,6 +323,19 @@ declare class RedlineEngine {
     private _getNextId;
     private _create_track_change_tag;
     private _set_text_content;
+    /**
+     * Walks `element` to its XML root element. Word (and LibreOffice, which
+     * refuses to LOAD such files) only supports comment ranges in the main
+     * document story ("w:document") — never in headers, footers, footnotes or
+     * endnotes (QA 2026-07-18 H4/C1).
+     */
+    private _comment_anchor_in_main_story;
+    /**
+     * When the anchor lives outside the main document story, records a
+     * user-visible warning and returns true (caller must skip the comment).
+     * The tracked change itself still applies — only the bubble is dropped.
+     */
+    private _skip_comment_outside_main_story;
     /**
      * Attaches a comment that wraps a contiguous range within a single paragraph.
      * start_element and end_element must both be direct children of parent_element
@@ -395,6 +426,13 @@ declare class RedlineEngine {
      * [start, start+length) in `mapper`, or null if that text is not inside a
      * table row.
      */
+    /**
+     * True when a replacement anchored in a table would ADD line-separated
+     * pipe-delimited content — the text shape of a table row. Writing that
+     * into a cell renders a fake row inside one cell while the real grid
+     * stays unchanged (QA 2026-07-18 C2); such edits must use insert_row.
+     */
+    private static _introduces_table_row_text;
     private static _column_count_at;
     validate_review_actions(actions: any[]): string[];
     process_batch(changes: DocumentChange[], dry_run?: boolean): any;
@@ -415,12 +453,86 @@ declare class RedlineEngine {
     private _apply_single_edit_indexed;
 }
 
+/** Text-space extent of one projected table row plus its cell texts. */
+interface RowGeometry {
+    start: number;
+    end: number;
+    cells: string[];
+}
+/** Text-space extent of one projected top-level table. */
+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).
+ */
+interface ExtractStructure {
+    part_ranges: [number, number, string][];
+    tables: TableGeometry[];
+}
+declare function extractTextFromBuffer(buffer: Buffer, cleanView?: boolean, includeAppendix?: boolean): Promise<string>;
+declare function _extractTextFromDoc(doc: DocumentObject, cleanView?: boolean, includeAppendix?: boolean, return_paragraph_offsets?: boolean, return_structure?: boolean): string | {
+    text: string;
+    paragraph_offsets: Map<any, [number, number]>;
+} | {
+    text: string;
+    structure: ExtractStructure;
+};
+
+type DiffEdit = ModifyText | InsertTableRow | DeleteTableRow;
 declare function trim_common_context(target: string, new_val: string): [number, number];
 declare function generate_edits_from_text(original_text: string, modified_text: string): ModifyText[];
+/**
+ * DOCX-to-DOCX diff over projections extracted with return_structure=true.
+ *
+ * Improvements over a flat generate_edits_from_text pass:
+ *   - each OPC part (header/body/footer/notes) diffs against its
+ *     counterpart, so no edit can span a part boundary and content that
+ *     moved between parts is reported instead of hidden (QA 2026-07-18 C1);
+ *   - table row insertions/deletions become structured insert_row /
+ *     delete_row operations instead of pipe-text edits (QA C2).
+ *
+ * Every ModifyText keeps its _match_start_index pinned into text_orig, which
+ * the engine consumes positionally (the Node engine has no
+ * make_edits_self_contained JSON round trip like the Python CLI).
+ *
+ * Returns { edits, warnings }. Warnings describe fallbacks the caller should
+ * surface (differing part layouts, unanchorable rows, …).
+ */
+declare function generate_structured_edits(text_orig: string, struct_orig: ExtractStructure, text_mod: string, struct_mod: ExtractStructure): {
+    edits: DiffEdit[];
+    warnings: string[];
+};
 declare function create_unified_diff(original_text: string, modified_text: string, context_lines?: number): string;
 declare function create_word_patch_diff(original_text: string, modified_text: string, original_path?: string, modified_path?: string): string;
 
-declare function apply_edits_to_markdown(markdown_text: string, edits: ModifyText[], include_index?: boolean, highlight_only?: boolean): string;
+/** One entry per input edit in apply_edits_to_markdown's edit_reports. */
+interface MarkupEditReport {
+    index: number;
+    status: "applied" | "failed";
+    error: string | null;
+    occurrences: number;
+}
+/**
+ * Applies edits to Markdown text and returns CriticMarkup-annotated output.
+ *
+ * Edit resolution follows the SAME semantics as `apply` (QA 2026-07-18 M1):
+ *   - `regex: true` targets match as regular expressions
+ *   - `match_mode` is honored: "strict" (default) refuses ambiguous targets,
+ *     "first" marks the first occurrence, "all" marks every occurrence
+ *   - a missing target is a per-edit failure, never a silent skip
+ *
+ * When `edit_reports` is provided, one entry per input edit is appended:
+ * { index: 0-based input position, status: "applied"|"failed",
+ *   error: string|null, occurrences: number }.
+ */
+declare function apply_edits_to_markdown(markdown_text: string, edits: ModifyText[], include_index?: boolean, highlight_only?: boolean, edit_reports?: MarkupEditReport[]): string;
 
 /**
  * Stateless paginator for projected DOCX Markdown.
@@ -456,12 +568,6 @@ interface OutlineNode {
 }
 declare function extract_outline(doc: DocumentObject, projected_body: string, body_pages: string[], body_page_offsets: number[], paragraph_offsets?: Record<string, [number, number]> | Map<any, [number, number]> | null): OutlineNode[];
 
-declare function extractTextFromBuffer(buffer: Buffer, cleanView?: boolean): Promise<string>;
-declare function _extractTextFromDoc(doc: DocumentObject, cleanView?: boolean, includeAppendix?: boolean, return_paragraph_offsets?: boolean): string | {
-    text: string;
-    paragraph_offsets: Map<any, [number, number]>;
-};
-
 interface FinalizeOptions {
     filename: string;
     sanitize_mode?: 'full' | 'keep-markup' | 'baseline';
@@ -515,4 +621,4 @@ declare function userSearch(pattern: string, text: string, flags?: string): {
 
 declare function identifyEngine(): string;
 
-export { BatchValidationError, DocumentMapper, DocumentObject, type FinalizeOptions, type FinalizeResult, type OutlineNode, type PageInfo, type PaginationResult, RedlineEngine, RegexTimeoutError, type TextSpan, USER_PATTERN_TIMEOUT_MS, _extractTextFromDoc, apply_edits_to_markdown, create_unified_diff, create_word_patch_diff, describe_illegal_control_chars, extractTextFromBuffer, extract_outline, finalize_document, generate_edits_from_text, identifyEngine, paginate, split_structural_appendix, trim_common_context, userFindAllMatches, userSearch, validate_edit_strings };
+export { BatchValidationError, type DiffEdit, DocumentMapper, DocumentObject, type ExtractStructure, type FinalizeOptions, type FinalizeResult, type MarkupEditReport, type OutlineNode, type PageInfo, type PaginationResult, RedlineEngine, RegexTimeoutError, type RowGeometry, type TableGeometry, type TextSpan, USER_PATTERN_TIMEOUT_MS, _extractTextFromDoc, apply_edits_to_markdown, create_unified_diff, create_word_patch_diff, describe_illegal_control_chars, extractTextFromBuffer, extract_outline, finalize_document, generate_edits_from_text, generate_structured_edits, identifyEngine, paginate, split_structural_appendix, trim_common_context, userFindAllMatches, userSearch, validate_edit_strings };