@adeu/core 1.21.0 → 1.22.0

package/dist/index.d.cts

@@ -197,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;
@@ -243,8 +245,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 +265,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;
@@ -475,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

@@ -197,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;
@@ -243,8 +245,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 +265,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;
@@ -475,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.js

@@ -743,6 +743,62 @@ function extract_comments_data(pkg) {
   return data;
 }
 
+// src/utils/safe-regex.ts
+import * as vm from "vm";
+var USER_PATTERN_TIMEOUT_MS = 2e3;
+var RegexTimeoutError = class extends Error {
+  pattern;
+  constructor(pattern) {
+    super(
+      `Regular expression exceeded the ${USER_PATTERN_TIMEOUT_MS / 1e3}s matching time budget (catastrophic backtracking). Simplify the pattern \u2014 nested quantifiers like (a+)+ are the usual cause \u2014 or use a literal target instead.`
+    );
+    this.name = "RegexTimeoutError";
+    this.pattern = pattern;
+  }
+};
+function runBudgeted(pattern, script, sandbox) {
+  try {
+    return vm.runInNewContext(script, sandbox, {
+      timeout: USER_PATTERN_TIMEOUT_MS
+    });
+  } catch (e) {
+    if (e && e.code === "ERR_SCRIPT_EXECUTION_TIMEOUT") {
+      throw new RegexTimeoutError(pattern);
+    }
+    throw e;
+  }
+}
+function userFindAllMatches(pattern, text, flags = "") {
+  const normalized = flags.includes("g") ? flags : flags + "g";
+  const re = new RegExp(pattern, normalized);
+  const raw = runBudgeted(
+    pattern,
+    `{
+      const out = [];
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        out.push({ start: m.index, end: m.index + m[0].length });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      out;
+    }`,
+    { re, text }
+  );
+  return raw.map((r) => ({ start: r.start, end: r.end }));
+}
+function userSearch(pattern, text, flags = "") {
+  const re = new RegExp(pattern, flags.replace("g", ""));
+  const raw = runBudgeted(
+    pattern,
+    `{
+      const m = re.exec(text);
+      m ? { start: m.index, end: m.index + m[0].length } : null;
+    }`,
+    { re, text }
+  );
+  return raw ? { start: raw.start, end: raw.end } : null;
+}
+
 // src/utils/docx.ts
 var QN_W_P = "w:p";
 var QN_W_R = "w:r";
@@ -1817,10 +1873,10 @@ ${header}`;
   find_match_index(target_text, is_regex = false) {
     if (is_regex) {
       try {
-        const pattern = new RegExp(target_text);
-        const match = pattern.exec(this.full_text);
-        if (match) return [match.index, match[0].length];
+        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];
     }
@@ -1849,11 +1905,10 @@ ${header}`;
     if (!target_text) return [];
     if (is_regex) {
       try {
-        const pattern = new RegExp(target_text, "g");
-        const matches2 = [...this.full_text.matchAll(pattern)];
-        if (matches2.length > 0)
-          return matches2.map((m) => [m.index, m[0].length]);
+        const matches2 = userFindAllMatches(target_text, this.full_text);
+        if (matches2.length > 0) return matches2.map((m) => [m.start, m.end - m.start]);
       } catch (e) {
+        if (e instanceof RegexTimeoutError) throw e;
       }
       return [];
     }
@@ -2831,7 +2886,9 @@ function apply_edits_to_markdown(markdown_text, edits, include_index = false, hi
       isolated_target,
       isolated_new,
       edit.comment,
-      orig_idx,
+      // 1-based, matching apply's "Edit N" reports and batch validation
+      // errors (QA 2026-07-17 F10; mirrors Python).
+      orig_idx + 1,
       include_index,
       highlight_only
     );
@@ -2976,12 +3033,36 @@ function sequential_context_hint(applied_so_far) {
   Note: ${applied_so_far} earlier edit(s) in this batch were already applied. Batches apply sequentially \u2014 each edit must target the document text as it reads AFTER the preceding edits (e.g. target the replacement text an earlier edit introduced, not the original wording).`;
 }
 var TRANSACTIONAL_NOT_APPLIED_ERROR = "Not applied: the batch is transactional and other edits failed validation (see their errors). Fix or remove those edits and re-run.";
+var XML_ILLEGAL_CHARS_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f]/g;
+function describe_illegal_control_chars(text) {
+  if (!text) return null;
+  const found = text.match(XML_ILLEGAL_CHARS_RE);
+  if (!found) return null;
+  const codes = Array.from(new Set(found.map((c) => `0x${c.charCodeAt(0).toString(16).padStart(2, "0")}`))).sort();
+  return codes.join(", ");
+}
 function validate_edit_strings(edits, index_offset = 0) {
   const errors = [];
   for (let i = 0; i < edits.length; i++) {
     const edit = edits[i];
     const t_text = edit.target_text || "";
     const n_text = edit.new_text || "";
+    const checked_fields = [
+      ["target_text", t_text],
+      ["new_text", n_text]
+    ];
+    if (edit.comment) checked_fields.push(["comment", edit.comment]);
+    (edit.cells || []).forEach((cell, cell_idx) => {
+      checked_fields.push([`cells[${cell_idx}]`, cell || ""]);
+    });
+    for (const [field_name, field_value] of checked_fields) {
+      const described = describe_illegal_control_chars(field_value);
+      if (described) {
+        errors.push(
+          `- Edit ${i + 1 + index_offset} Failed: \`${field_name}\` contains control character(s) (${described}) that cannot be stored in a DOCX. Remove them and re-submit.`
+        );
+      }
+    }
     if (n_text.includes("{++") || n_text.includes("{--") || n_text.includes("{>>") || n_text.includes("{==")) {
       errors.push(
         `- Edit ${i + 1 + index_offset} Failed: Do not manually write CriticMarkup tags ({++, {--, {>>, {==) in \`new_text\`. The engine handles redlining automatically. To add a comment, use the \`comment\` parameter.`
@@ -3288,8 +3369,8 @@ var RedlineEngine = 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).
    */
   _capture_preview_context(edit) {
     if (edit.type !== "modify") return;
@@ -3390,8 +3471,8 @@ var RedlineEngine = class _RedlineEngine {
   }
   /**
    * 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).
    */
   static _report_new_text(edit) {
     if (edit && edit.type === "insert_row" && Array.isArray(edit.cells)) {
@@ -4676,7 +4757,13 @@ var RedlineEngine = class _RedlineEngine {
         const reports_by_input = new Array(edits.length);
         const validation_failed_idx = /* @__PURE__ */ new Set();
         for (const { edit, i } of ordered_edits) {
-          let single_errors = this.validate_edits([edit], i);
+          let single_errors;
+          try {
+            single_errors = this.validate_edits([edit], i);
+          } catch (e) {
+            if (!(e instanceof RegexTimeoutError)) throw e;
+            single_errors = [`- Edit ${i + 1} Failed: ${e.message}`];
+          }
           if (single_errors.length > 0) {
             if (applied_edits > 0) {
               const hint = sequential_context_hint(applied_edits);
@@ -4761,7 +4848,13 @@ var RedlineEngine = class _RedlineEngine {
           const sequential_errors = [];
           let applied_so_far = 0;
           for (const { edit, i } of ordered_edits) {
-            let single_errors = this.validate_edits([edit], i);
+            let single_errors;
+            try {
+              single_errors = this.validate_edits([edit], i);
+            } catch (e) {
+              if (!(e instanceof RegexTimeoutError)) throw e;
+              single_errors = [`- Edit ${i + 1} Failed: ${e.message}`];
+            }
             if (single_errors.length > 0) {
               if (applied_so_far > 0) {
                 const hint = sequential_context_hint(applied_so_far);
@@ -4875,7 +4968,18 @@ var RedlineEngine = class _RedlineEngine {
           edit._error_msg = msg;
         }
       } else {
-        const resolved = this._pre_resolve_heuristic_edit(edit);
+        let resolved;
+        try {
+          resolved = this._pre_resolve_heuristic_edit(edit);
+        } catch (e) {
+          if (!(e instanceof RegexTimeoutError)) throw e;
+          skipped++;
+          edit._applied_status = false;
+          const msg = `- Failed to apply edit targeting: '${(edit.target_text || "").substring(0, 40)}...' (${e.message})`;
+          this.skipped_details.push(msg);
+          edit._error_msg = msg;
+          continue;
+        }
         if (resolved) {
           if (Array.isArray(resolved)) {
             for (const r of resolved) {
@@ -5034,6 +5138,16 @@ var RedlineEngine = class _RedlineEngine {
         );
         continue;
       }
+      const dup_authors = Array.from(
+        new Set(all_nodes.map((n) => n.getAttribute("w:author") || "Unknown"))
+      ).sort();
+      if (dup_authors.length > 1) {
+        skipped++;
+        this.skipped_details.push(
+          `- Failed to apply action: ${type} on Chg:${target_id} is ambiguous. The document contains ${all_nodes.length} tracked-change elements sharing w:id=${target_id} from different authors (${dup_authors.join(", ")}) \u2014 duplicate revision IDs produced outside this engine (e.g. by a document merge or copy-paste). Acting on this ID would resolve all of them at once. Resolve these changes individually in Word, or apply the intended outcome as an explicit text edit instead.`
+        );
+        continue;
+      }
       for (const node of all_nodes) {
         const is_ins = node.tagName === "w:ins";
         const parent_tag = node.parentNode ? node.parentNode.tagName : "";
@@ -6349,6 +6463,27 @@ function scrub_doc_properties(doc) {
         c.textContent = "";
       }
     });
+    const titles = findDescendantsByLocalName(corePart._element, "title");
+    titles.forEach((c) => {
+      if (c.textContent) {
+        lines.push(`Title kept (review manually): "${c.textContent}"`);
+      }
+    });
+    const leakFields = [
+      ["category", "Category"],
+      ["keywords", "Keywords"],
+      ["subject", "Subject"],
+      ["contentStatus", "Content status"],
+      ["description", "Description/comments"]
+    ];
+    for (const [local, label] of leakFields) {
+      findDescendantsByLocalName(corePart._element, local).forEach((c) => {
+        if (c.textContent) {
+          lines.push(`${label}: ${c.textContent}`);
+          c.textContent = "";
+        }
+      });
+    }
     const revisions = findDescendantsByLocalName(corePart._element, "revision");
     revisions.forEach((c) => {
       if (c.textContent && parseInt(c.textContent) > 1) {
@@ -6554,7 +6689,11 @@ function extract_all_domain_metadata(doc, base_text) {
     for (const term of def_keys) {
       if (definitions[term].count === 0) {
         delete definitions[term];
-        duplicates.delete(term);
+        if (!duplicates.has(term)) {
+          diagnostics.push(
+            `[Warning] Unused Definition: '${term}' is defined but never used.`
+          );
+        }
       }
     }
   }
@@ -7889,10 +8028,13 @@ export {
   DocumentMapper,
   DocumentObject,
   RedlineEngine,
+  RegexTimeoutError,
+  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,
@@ -7900,6 +8042,9 @@ export {
   identifyEngine,
   paginate,
   split_structural_appendix,
-  trim_common_context
+  trim_common_context,
+  userFindAllMatches,
+  userSearch,
+  validate_edit_strings
 };
 //# sourceMappingURL=index.js.map