@adeu/core 1.21.0 → 1.23.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;
@@ -197,6 +215,8 @@ declare class BatchValidationError extends Error {
     errors: string[];
     constructor(errors: string[]);
 }
+declare function describe_illegal_control_chars(text: string): string | null;
+declare function validate_edit_strings(edits: any[], index_offset?: number): string[];
 declare class RedlineEngine {
     doc: DocumentObject;
     author: string;
@@ -243,8 +263,8 @@ declare class RedlineEngine {
      * Snapshots the document text around a resolved edit BEFORE anything is
      * applied. Previews rendered after the batch mutates the DOM cannot slice
      * full_text at the stored offsets: applied edits shift offsets and inject
-     * tracked-change markup, which produced garbled previews mixing unrelated
-     * edits and internal scaffolding (QA H1).
+     * tracked-change markup, garbling previews with unrelated edits and
+     * internal scaffolding (QA H1).
      */
     private _capture_preview_context;
     /**
@@ -263,8 +283,8 @@ declare class RedlineEngine {
     private _build_full_match_preview;
     /**
      * The "new text" a batch report should show for an edit. InsertTableRow has
-     * no new_text field — surface its cell contents instead of the misleading
-     * empty string the report used to print (QA M4).
+     * no new_text field — surface its cell contents rather than a misleading
+     * empty string (QA M4).
      */
     private static _report_new_text;
     private _build_edit_context_previews;
@@ -303,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
@@ -393,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;
@@ -413,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.
@@ -454,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';
@@ -475,6 +583,42 @@ interface FinalizeResult {
 }
 declare function finalize_document(doc: DocumentObject, options: FinalizeOptions): Promise<FinalizeResult>;
 
+/**
+ * Time-budgeted execution of USER/LLM-supplied regular expressions.
+ *
+ * `regex: true` on a ModifyText edit and `search_regex` on read_docx hand an
+ * LLM-controlled pattern to V8's backtracking engine. A pathological pattern
+ * like `(a|a)*$` against a run of repeated characters hangs the event loop
+ * indefinitely (QA 2026-07-17 F5 — ReDoS; mirrors the Python fix).
+ *
+ * JS regexes cannot be interrupted in-thread, but V8 CAN interrupt regex
+ * execution running inside a `vm` context with a `timeout` — that is the
+ * mechanism used here. `node:vm` is a builtin, preserving the zero-dependency
+ * bundle constraint.
+ *
+ * Only USER-SUPPLIED patterns belong here. The engine's own generated
+ * patterns (fuzzy matchers etc.) are built to be linear-time.
+ */
+declare const USER_PATTERN_TIMEOUT_MS = 2000;
+declare class RegexTimeoutError extends Error {
+    pattern: string;
+    constructor(pattern: string);
+}
+/**
+ * All non-overlapping matches of a user pattern, under the wall-clock budget.
+ * Invalid patterns throw SyntaxError exactly like `new RegExp(...)` would.
+ * The budget covers the ENTIRE scan, not just the first match.
+ */
+declare function userFindAllMatches(pattern: string, text: string, flags?: string): Array<{
+    start: number;
+    end: number;
+}>;
+/** First match of a user pattern under the wall-clock budget, or null. */
+declare function userSearch(pattern: string, text: string, flags?: string): {
+    start: number;
+    end: number;
+} | null;
+
 declare function identifyEngine(): string;
 
-export { BatchValidationError, DocumentMapper, DocumentObject, type FinalizeOptions, type FinalizeResult, type OutlineNode, type PageInfo, type PaginationResult, RedlineEngine, type TextSpan, _extractTextFromDoc, apply_edits_to_markdown, create_unified_diff, create_word_patch_diff, extractTextFromBuffer, extract_outline, finalize_document, generate_edits_from_text, identifyEngine, paginate, split_structural_appendix, trim_common_context };
+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;
@@ -197,6 +215,8 @@ declare class BatchValidationError extends Error {
     errors: string[];
     constructor(errors: string[]);
 }
+declare function describe_illegal_control_chars(text: string): string | null;
+declare function validate_edit_strings(edits: any[], index_offset?: number): string[];
 declare class RedlineEngine {
     doc: DocumentObject;
     author: string;
@@ -243,8 +263,8 @@ declare class RedlineEngine {
      * Snapshots the document text around a resolved edit BEFORE anything is
      * applied. Previews rendered after the batch mutates the DOM cannot slice
      * full_text at the stored offsets: applied edits shift offsets and inject
-     * tracked-change markup, which produced garbled previews mixing unrelated
-     * edits and internal scaffolding (QA H1).
+     * tracked-change markup, garbling previews with unrelated edits and
+     * internal scaffolding (QA H1).
      */
     private _capture_preview_context;
     /**
@@ -263,8 +283,8 @@ declare class RedlineEngine {
     private _build_full_match_preview;
     /**
      * The "new text" a batch report should show for an edit. InsertTableRow has
-     * no new_text field — surface its cell contents instead of the misleading
-     * empty string the report used to print (QA M4).
+     * no new_text field — surface its cell contents rather than a misleading
+     * empty string (QA M4).
      */
     private static _report_new_text;
     private _build_edit_context_previews;
@@ -303,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
@@ -393,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;
@@ -413,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.
@@ -454,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';
@@ -475,6 +583,42 @@ interface FinalizeResult {
 }
 declare function finalize_document(doc: DocumentObject, options: FinalizeOptions): Promise<FinalizeResult>;
 
+/**
+ * Time-budgeted execution of USER/LLM-supplied regular expressions.
+ *
+ * `regex: true` on a ModifyText edit and `search_regex` on read_docx hand an
+ * LLM-controlled pattern to V8's backtracking engine. A pathological pattern
+ * like `(a|a)*$` against a run of repeated characters hangs the event loop
+ * indefinitely (QA 2026-07-17 F5 — ReDoS; mirrors the Python fix).
+ *
+ * JS regexes cannot be interrupted in-thread, but V8 CAN interrupt regex
+ * execution running inside a `vm` context with a `timeout` — that is the
+ * mechanism used here. `node:vm` is a builtin, preserving the zero-dependency
+ * bundle constraint.
+ *
+ * Only USER-SUPPLIED patterns belong here. The engine's own generated
+ * patterns (fuzzy matchers etc.) are built to be linear-time.
+ */
+declare const USER_PATTERN_TIMEOUT_MS = 2000;
+declare class RegexTimeoutError extends Error {
+    pattern: string;
+    constructor(pattern: string);
+}
+/**
+ * All non-overlapping matches of a user pattern, under the wall-clock budget.
+ * Invalid patterns throw SyntaxError exactly like `new RegExp(...)` would.
+ * The budget covers the ENTIRE scan, not just the first match.
+ */
+declare function userFindAllMatches(pattern: string, text: string, flags?: string): Array<{
+    start: number;
+    end: number;
+}>;
+/** First match of a user pattern under the wall-clock budget, or null. */
+declare function userSearch(pattern: string, text: string, flags?: string): {
+    start: number;
+    end: number;
+} | null;
+
 declare function identifyEngine(): string;
 
-export { BatchValidationError, DocumentMapper, DocumentObject, type FinalizeOptions, type FinalizeResult, type OutlineNode, type PageInfo, type PaginationResult, RedlineEngine, type TextSpan, _extractTextFromDoc, apply_edits_to_markdown, create_unified_diff, create_word_patch_diff, extractTextFromBuffer, extract_outline, finalize_document, generate_edits_from_text, identifyEngine, paginate, split_structural_appendix, trim_common_context };
+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 };