@adeu/core 1.20.0 → 1.22.0

package/dist/index.d.cts

@@ -75,6 +75,7 @@ declare class DocumentMapper {
     spans: TextSpan[];
     appendix_start_index: number;
     private _text_chunks;
+    private _plain_projection;
     constructor(doc: DocumentObject, clean_view?: boolean, original_view?: boolean);
     private _build_map;
     private _map_blocks;
@@ -86,6 +87,28 @@ declare class DocumentMapper {
     private _add_virtual_text;
     private _replace_smart_quotes;
     private _make_fuzzy_regex;
+    /**
+     * 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;
+    /**
+     * 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;
     find_match_index(target_text: string, is_regex?: boolean): [number, number];
     find_all_match_indices(target_text: string, is_regex?: boolean): [number, number][];
     find_target_runs(target_text: string): Run[];
@@ -174,6 +197,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;
@@ -207,6 +232,43 @@ declare class RedlineEngine {
      * escalating the regex further.
      */
     private _nearest_match_hint;
+    private static readonly _PREVIEW_WRAPPER_PAIRS;
+    /**
+     * Makes a fixed-width slice of the raw-view projection presentable: drops
+     * complete {>>...<<} meta blocks (annotations of pre-existing changes, not
+     * part of this edit) and any wrapper fragments the window boundary chopped
+     * in half. Without this, previews leak internal scaffolding like
+     * "[Chg:5 delete]" (QA H1). Mirrors the Python engine.
+     */
+    private static _tidy_preview_context;
+    /**
+     * 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, garbling previews with unrelated edits and
+     * internal scaffolding (QA H1).
+     */
+    private _capture_preview_context;
+    /**
+     * Like _capture_preview_context, but snapshots the context around the
+     * ORIGINAL edit's full matched span (stashed by _pre_resolve_heuristic_edit),
+     * so the report preview can present the complete logical change of a
+     * compound modification instead of its first sub-edit.
+     */
+    private _capture_parent_preview_context;
+    /**
+     * Renders the preview from the edit's full matched span. The common
+     * prefix/suffix between matched and replacement text is moved into the
+     * surrounding context so the {--...--}{++...++} block shows the minimal
+     * complete change.
+     */
+    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 rather than a misleading
+     * empty string (QA M4).
+     */
+    private static _report_new_text;
     private _build_edit_context_previews;
     private _scan_existing_ids;
     private _get_heading_path_and_page;
@@ -328,6 +390,12 @@ declare class RedlineEngine {
     private _clean_wrapping_comments;
     private _delete_comments_in_element;
     validate_edits(edits: any[], index_offset?: number): string[];
+    /**
+     * Number of columns (w:tc elements) in the table row containing the text at
+     * [start, start+length) in `mapper`, or null if that text is not inside a
+     * table row.
+     */
+    private static _column_count_at;
     validate_review_actions(actions: any[]): string[];
     process_batch(changes: DocumentChange[], dry_run?: boolean): any;
     private _process_batch_internal;
@@ -409,6 +477,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, 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 };

package/dist/index.d.ts

@@ -75,6 +75,7 @@ declare class DocumentMapper {
     spans: TextSpan[];
     appendix_start_index: number;
     private _text_chunks;
+    private _plain_projection;
     constructor(doc: DocumentObject, clean_view?: boolean, original_view?: boolean);
     private _build_map;
     private _map_blocks;
@@ -86,6 +87,28 @@ declare class DocumentMapper {
     private _add_virtual_text;
     private _replace_smart_quotes;
     private _make_fuzzy_regex;
+    /**
+     * 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;
+    /**
+     * 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;
     find_match_index(target_text: string, is_regex?: boolean): [number, number];
     find_all_match_indices(target_text: string, is_regex?: boolean): [number, number][];
     find_target_runs(target_text: string): Run[];
@@ -174,6 +197,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;
@@ -207,6 +232,43 @@ declare class RedlineEngine {
      * escalating the regex further.
      */
     private _nearest_match_hint;
+    private static readonly _PREVIEW_WRAPPER_PAIRS;
+    /**
+     * Makes a fixed-width slice of the raw-view projection presentable: drops
+     * complete {>>...<<} meta blocks (annotations of pre-existing changes, not
+     * part of this edit) and any wrapper fragments the window boundary chopped
+     * in half. Without this, previews leak internal scaffolding like
+     * "[Chg:5 delete]" (QA H1). Mirrors the Python engine.
+     */
+    private static _tidy_preview_context;
+    /**
+     * 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, garbling previews with unrelated edits and
+     * internal scaffolding (QA H1).
+     */
+    private _capture_preview_context;
+    /**
+     * Like _capture_preview_context, but snapshots the context around the
+     * ORIGINAL edit's full matched span (stashed by _pre_resolve_heuristic_edit),
+     * so the report preview can present the complete logical change of a
+     * compound modification instead of its first sub-edit.
+     */
+    private _capture_parent_preview_context;
+    /**
+     * Renders the preview from the edit's full matched span. The common
+     * prefix/suffix between matched and replacement text is moved into the
+     * surrounding context so the {--...--}{++...++} block shows the minimal
+     * complete change.
+     */
+    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 rather than a misleading
+     * empty string (QA M4).
+     */
+    private static _report_new_text;
     private _build_edit_context_previews;
     private _scan_existing_ids;
     private _get_heading_path_and_page;
@@ -328,6 +390,12 @@ declare class RedlineEngine {
     private _clean_wrapping_comments;
     private _delete_comments_in_element;
     validate_edits(edits: any[], index_offset?: number): string[];
+    /**
+     * Number of columns (w:tc elements) in the table row containing the text at
+     * [start, start+length) in `mapper`, or null if that text is not inside a
+     * table row.
+     */
+    private static _column_count_at;
     validate_review_actions(actions: any[]): string[];
     process_batch(changes: DocumentChange[], dry_run?: boolean): any;
     private _process_batch_internal;
@@ -409,6 +477,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, 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 };