feat: find_all enumeration, occurrence ambiguity guard, batch operation_index (ISSUES.md #34) (#53)

* feat: find_all enumeration, occurrence ambiguity guard, batch operation_index (ISSUES.md #34)

- Document.find_all(text, paragraph=None) enumerates every match as
  SearchResults whose paragraph_ref/paragraph_occurrence plug directly
  into follow-up edits.
- Omitted occurrence now means the target must be unique in the search
  scope; ambiguous targets raise AmbiguousTextError (new exception with
  search_text, paragraph_ref, paragraph_preview, total_occurrences)
  instead of silently editing the first match. Explicit occurrence=0
  keeps the old behavior per call.
- Out-of-range occurrences in scoped edits report occurrence and
  total_occurrences instead of a self-contradicting 'not found'.
- batch_edit/batch_rewrite raise only BatchOperationError for per-op
  failures (stale hash included), with operation_index and the typed
  underlying exception on original/__cause__. Batches stay atomic.
- Occurrence handling consolidated into _locate_in_paragraph, replacing
  four duplicated find-or-raise paths; dry-run validation shares it.
- Docs (SKILL.md, api.md) and benchmarks updated; 14 new find_all tests
  plus ambiguity, out-of-range, and single-exception-contract suites.

* review: fix same-paragraph batch advice, dedupe occurrence counting

Multi-reviewer findings on PR #53:

- The find_all docs recommended batch_edit for several matches in one
  paragraph, but ops in find_all (ascending) order silently mis-target
  or fail: each edit shifts the occurrence numbering of the matches
  after it in the accepted text view. Corrected all three doc spots
  (Document.find_all docstring, docs/api.md, SKILL.md) to require
  descending occurrence order (an edit never shifts the matches before
  it) with the self-overlapping-string caveat, and added
  TestSameParagraphBatch locking in both the working descending pattern
  and the atomic failure of the ascending one.
- Consolidated the two match-counting idioms into one
  count_in_text_map() helper in xml_editor.py, now used by
  _locate_in_paragraph, count_matches, and CommentManager._find_anchor
  (also drops count_matches' quadratic inner loop).
- Dropped the one-off 'Note:' docstring heading in Document.find_all.

Skipped (reviewed, deliberate): the extra count_matches pass on the
document-wide occurrence=None success path — short-circuiting at the
second match would break the exact total_occurrences the
AmbiguousTextError contract promises.

* review: batch_rewrite rollback, locate naming, exception message dedup

Round-2 multi-reviewer findings on PR #53:

- batch_rewrite now snapshots the DOM and rolls back on mid-apply
  failure, matching batch_edit — the documented 'nothing is applied on
  failure' contract previously rested entirely on upfront validation
  precluding every apply-phase error. Added a rollback test that
  simulates a mid-loop failure (none is reachable today).
- Renamed _find_document_wide to _locate_document_wide: the _find_*
  helpers return None on miss, while this one raises like
  _locate_in_paragraph — the name now signals the find-or-raise
  contract.
- TextNotFoundError docstring now covers the out-of-range occurrence
  case that docs/api.md already documented.
- Factored the 'Current content' message suffix into _append_preview so
  TextNotFoundError and AmbiguousTextError build it identically instead
  of one being period-safe by coincidence.
- Documented why _locate_document_wide counts via count_matches rather
  than count_in_text_map (text maps are per-paragraph; exact total is
  part of the error contract).

Rejected finding: a claim that _apply_single_edit re-validates hashes
mid-batch, breaking same-paragraph descending-order batches — refuted
by the code (apply resolves by index only), the passing
TestSameParagraphBatch, and an end-to-end repro.

* review: complete locate naming, copy-paste-safe find_all examples

Round-3 multi-reviewer findings on PR #53 (correctness reviewer CLEAN):

- Renamed CommentManager._find_anchor to _locate_anchor, completing the
  find-or-raise naming convention round 2 introduced (_find_* helpers
  return None on miss; this one always raises).
- The find_all examples in the docstring, api.md, and SKILL.md now show
  the pattern that is safe for any match distribution — one batch_edit
  over reversed(find_all(...)), which yields the required descending
  occurrence order for same-paragraph ops — instead of the sequential
  loop that only works with one match per paragraph.
- api.md and SKILL.md now note BatchOperationError.original is None for
  batch-level rule violations (missing paragraph ref, duplicate
  paragraph) that have no underlying exception.

* review: reject negative occurrence before the text-map search

CodeRabbit findings on PR #53:

- A negative occurrence passed to the direct (non-batch) edit methods
  reached find_in_text_map, where range(occurrence + 1) never runs and
  the scoped paths crashed with UnboundLocalError (document-wide paths
  produced a nonsensical 'occurrence=-1 requested' message). All three
  locate paths (_locate_in_paragraph, _locate_document_wide,
  CommentManager._locate_anchor) now reject negatives up front with the
  same ValueError the EditOperation constructors raise; regression test
  covers all four public paths.
- Added the missing return annotation on the _edit_calls test helper.

Skipped (deliberate, settled in earlier rounds): the second
count_matches scan on the document-wide occurrence=None path — the
exact total is part of the AmbiguousTextError contract and the
trade-off is documented in _locate_document_wide's docstring.

Author: pablospe

benchmarks/hash_anchored_vs_plain.py

@@ -228,10 +228,13 @@ def benchmark_accuracy():
     shutil.copy(persist_path, d1)
     doc1 = Document.open(d1, force_recreate=True)
 
-    # Disrupting edit: replace BOTH 'committee' in P5
+    # Disrupting edit: replace BOTH 'committee' in P5 (occurrence=0 twice —
+    # after the first replace, the remaining match is the new first one)
     p5_ref = old_refs[5]
-    doc1.replace("committee", "BOARD", paragraph=p5_ref)
-    doc1.replace("committee", "BOARD", paragraph=old_refs[5].split("#")[0] + "#" + _get_fresh_hash(doc1, 5))
+    doc1.replace("committee", "BOARD", paragraph=p5_ref, occurrence=0)
+    doc1.replace(
+        "committee", "BOARD", paragraph=old_refs[5].split("#")[0] + "#" + _get_fresh_hash(doc1, 5), occurrence=0
+    )
 
     # Now try to edit P6-P15 using the OLD occurrence indices
     for para_idx in target_paras:
@@ -283,15 +286,17 @@ def benchmark_accuracy():
     doc2 = Document.open(d2, force_recreate=True)
 
     # Same disrupting edit
-    doc2.replace("committee", "BOARD", paragraph=p5_ref)
-    doc2.replace("committee", "BOARD", paragraph=old_refs[5].split("#")[0] + "#" + _get_fresh_hash(doc2, 5))
+    doc2.replace("committee", "BOARD", paragraph=p5_ref, occurrence=0)
+    doc2.replace(
+        "committee", "BOARD", paragraph=old_refs[5].split("#")[0] + "#" + _get_fresh_hash(doc2, 5), occurrence=0
+    )
 
     # Try to edit P6-P15 using OLD refs (from before edit)
     for para_idx in target_paras:
         old_ref = old_refs[para_idx]
         marker = f"[P{para_idx:02d}]"
         try:
-            doc2.replace("committee", "EDITED", paragraph=old_ref)
+            doc2.replace("committee", "EDITED", paragraph=old_ref, occurrence=0)
             hash_correct += 1
         except HashMismatchError:
             hash_rejected += 1

docs/api.md

@@ -222,6 +222,44 @@ if match:
     )
 ```
 
+#### `find_all(text, paragraph=None)`
+
+Find every match of `text`, in document order. One call replaces the N+1
+`find_text` probes needed to enumerate N hits, and each result carries exactly
+what a follow-up edit needs.
+
+**Parameters:**
+
+- `text` (str): Text to search for (must be non-empty)
+- `paragraph` (str, optional): Paragraph reference (e.g. `P2#f3c1`) to scope the search. `None` searches the whole document. Defaults to None.
+
+**Returns:** list of [`SearchResult`](#searchresult), empty when nothing matches (no-match is not an error for an enumeration API)
+
+**Raises:** `ValueError` if `text` is empty or `paragraph` is malformed; [`ParagraphIndexError`](#exceptions) / [`HashMismatchError`](#exceptions) for an out-of-range or stale `paragraph`.
+
+**Example:**
+
+```python
+# Edit every match in one atomic batch. reversed() puts same-paragraph ops in
+# the required descending occurrence order, so this is safe however the
+# matches are distributed:
+ops = [
+    EditOperation.replace(r.text, "60 days",
+                          paragraph=r.paragraph_ref, occurrence=r.paragraph_occurrence)
+    for r in reversed(doc.find_all("30 days"))
+]
+doc.batch_edit(ops)
+```
+
+Editing one match at a time (`doc.replace(...)` per result) also works when
+every paragraph holds at most one match. With several matches in one
+paragraph, an edit invalidates the paragraph's remaining refs and shifts the
+occurrence numbers of the matches after it — either re-run `find_all` after
+each edit, or batch the same-paragraph ops in **descending** occurrence order
+as above; an edit never shifts the matches before it. (Ascending order
+mis-targets; descending is not valid for search strings that overlap
+themselves, e.g. `"aa"` in `"aaaa"`.)
+
 #### `count_matches(text)`
 
 Count visible text matches across the document.
@@ -239,7 +277,7 @@ if doc.count_matches("Section 5") > 1:
     print("Use paragraph refs and occurrence to target the intended match")
 ```
 
-#### `replace(find, replace_with, *, paragraph, occurrence=0)`
+#### `replace(find, replace_with, *, paragraph, occurrence=None)`
 
 Replace text with tracked changes. When the target sits inside another author's pending insertion, that insertion is preserved: the matched text gets a nested `<w:del>` under your authorship and the replacement lands in your own sibling `<w:ins>` (Word's behavior), instead of silently rewriting the other author's proposal.
 
@@ -248,7 +286,7 @@ Replace text with tracked changes. When the target sits inside another author's
 - `find` (str): Text to find and replace
 - `replace_with` (str): Replacement text
 - `paragraph` (str): Paragraph reference from `list_paragraphs()`, such as `P2#f3c1`
-- `occurrence` (int): Which occurrence within the paragraph, 0-based (0 = first). Defaults to 0.
+- `occurrence` (int | None): Which occurrence within the paragraph, 0-based (0 = first). Omitted → the target must be unique within the paragraph; if it matches more than once, [`AmbiguousTextError`](#ambiguoustexterror) is raised instead of silently editing the first match.
 
 **Returns:** Updated paragraph reference (str)
 
@@ -259,15 +297,15 @@ ref = doc.replace("30 days", "60 days", paragraph="P2#f3c1")
 doc.replace("net", "gross", paragraph=ref)
 ```
 
-#### `delete(text, *, paragraph, occurrence=0)`
+#### `delete(text, *, paragraph, occurrence=None)`
 
 Mark text as deleted with tracked changes. Deleting text inside another author's pending insertion nests a `<w:del>` under your authorship inside their `<w:ins>`, preserving their proposal; only your own pending insertions are edited in place.
 
 **Parameters:**
 
 - `text` (str): Text to mark as deleted
 - `paragraph` (str): Paragraph reference from `list_paragraphs()`, such as `P2#f3c1`
-- `occurrence` (int): Which occurrence within the paragraph, 0-based (0 = first). Defaults to 0.
+- `occurrence` (int | None): Which occurrence within the paragraph, 0-based (0 = first). Omitted → the target must be unique within the paragraph; if it matches more than once, [`AmbiguousTextError`](#ambiguoustexterror) is raised instead of silently editing the first match.
 
 **Returns:** Updated paragraph reference (str)
 
@@ -277,7 +315,7 @@ Mark text as deleted with tracked changes. Deleting text inside another author's
 ref = doc.delete("obsolete clause", paragraph="P5#d4e5")
 ```
 
-#### `insert_after(anchor, text, *, paragraph, occurrence=0)`
+#### `insert_after(anchor, text, *, paragraph, occurrence=None)`
 
 Insert text after anchor with tracked changes. An anchor inside another author's pending insertion produces your own sibling `<w:ins>` (splitting theirs when the anchor falls mid-content) rather than splicing your words into their proposal.
 
@@ -286,7 +324,7 @@ Insert text after anchor with tracked changes. An anchor inside another author's
 - `anchor` (str): Text to find as insertion point
 - `text` (str): Text to insert after the anchor
 - `paragraph` (str): Paragraph reference from `list_paragraphs()`, such as `P2#f3c1`
-- `occurrence` (int): Which occurrence within the paragraph, 0-based (0 = first). Defaults to 0.
+- `occurrence` (int | None): Which occurrence within the paragraph, 0-based (0 = first). Omitted → the target must be unique within the paragraph; if it matches more than once, [`AmbiguousTextError`](#ambiguoustexterror) is raised instead of silently editing the first match.
 
 **Returns:** Updated paragraph reference (str)
 
@@ -296,7 +334,7 @@ Insert text after anchor with tracked changes. An anchor inside another author's
 ref = doc.insert_after("Section 5", " (as amended)", paragraph="P3#b2c4")
 ```
 
-#### `insert_before(anchor, text, *, paragraph, occurrence=0)`
+#### `insert_before(anchor, text, *, paragraph, occurrence=None)`
 
 Insert text before anchor with tracked changes. Foreign pending insertions are treated the same as in `insert_after()`.
 
@@ -305,7 +343,7 @@ Insert text before anchor with tracked changes. Foreign pending insertions are t
 - `anchor` (str): Text to find as insertion point
 - `text` (str): Text to insert before the anchor
 - `paragraph` (str): Paragraph reference from `list_paragraphs()`, such as `P2#f3c1`
-- `occurrence` (int): Which occurrence within the paragraph, 0-based (0 = first). Defaults to 0.
+- `occurrence` (int | None): Which occurrence within the paragraph, 0-based (0 = first). Omitted → the target must be unique within the paragraph; if it matches more than once, [`AmbiguousTextError`](#ambiguoustexterror) is raised instead of silently editing the first match.
 
 **Returns:** Updated paragraph reference (str)
 
@@ -344,6 +382,8 @@ stale, the entire batch is rejected before any edits are applied.
 
 **Returns:** Updated paragraph references in input order (list[str]); with `dry_run=True`, a list of [`EditValidationResult`](#editvalidationresult) instead
 
+**Raises:** [`BatchOperationError`](#batchoperationerror) — the only exception a non-dry-run batch raises for a failing operation, whatever the underlying cause (stale hash, malformed ref, missing text, ambiguous target). `operation_index` names the failing op; `original` (also `__cause__`) holds the underlying typed exception. The batch is atomic: nothing is applied on failure.
+
 **Example:**
 
 ```python
@@ -380,6 +420,8 @@ Rewrite multiple paragraphs after validating paragraph hashes up front.
 
 **Returns:** Updated paragraph references in input order (list[str])
 
+**Raises:** [`BatchOperationError`](#batchoperationerror) — same single-exception contract as `batch_edit()`.
+
 **Example:**
 
 ```python
@@ -391,7 +433,7 @@ new_refs = doc.batch_rewrite([
 
 ### Comment Methods
 
-#### `add_comment(anchor_text, comment, *, paragraph=None, occurrence=0)`
+#### `add_comment(anchor_text, comment, *, paragraph=None, occurrence=None)`
 
 Add a comment anchored to specific text. Anchors are located with the same
 visible-text search used by `count_matches()` and the tracked-change edit
@@ -403,7 +445,7 @@ smart-quote splits, `w:ins` wrappers) are found.
 - `anchor_text` (str): Text to attach the comment to
 - `comment` (str): The comment content
 - `paragraph` (str, optional): Paragraph reference (e.g. `P3#a7b2`) to scope the search. `None` searches the whole document. Defaults to None.
-- `occurrence` (int): Which occurrence to anchor to, 0-based (0 = first). Defaults to 0.
+- `occurrence` (int | None): Which occurrence to anchor to, 0-based (0 = first), counted within `paragraph` when given and document-wide otherwise. Omitted → the anchor must be unique in the search scope, else [`AmbiguousTextError`](#ambiguoustexterror).
 
 **Returns:** The comment ID (int). IDs are allocated sequentially starting at 0 in a document with no existing comments — always use the returned ID rather than guessing.
 
@@ -697,27 +739,27 @@ from docx_editor import EditOperation
 
 ### Constructors
 
-#### `EditOperation.replace(find, replace_with, *, paragraph, occurrence=0)`
+#### `EditOperation.replace(find, replace_with, *, paragraph, occurrence=None)`
 
 - `find` (str): Text to find and replace. Must be non-empty.
 - `replace_with` (str): Replacement text. Empty string is allowed (replacing
   with nothing is a valid tracked deletion).
 
-#### `EditOperation.delete(text, *, paragraph, occurrence=0)`
+#### `EditOperation.delete(text, *, paragraph, occurrence=None)`
 
 - `text` (str): Text to mark as deleted. Must be non-empty.
 
-#### `EditOperation.insert_after(anchor, text, *, paragraph, occurrence=0)`
+#### `EditOperation.insert_after(anchor, text, *, paragraph, occurrence=None)`
 
-#### `EditOperation.insert_before(anchor, text, *, paragraph, occurrence=0)`
+#### `EditOperation.insert_before(anchor, text, *, paragraph, occurrence=None)`
 
 - `anchor` (str): Text to find as insertion point. Must be non-empty.
 - `text` (str): Text to insert.
 
 All constructors also take:
 
 - `paragraph` (str): Paragraph reference from `list_paragraphs()`, such as `P2#f3c1`
-- `occurrence` (int): Which occurrence within the paragraph, 0-based (0 = first). Defaults to 0. Must be >= 0.
+- `occurrence` (int | None): Which occurrence within the paragraph, 0-based (0 = first). Omitted → the target must be unique within the paragraph at apply time; if it matches more than once, the batch fails with a [`BatchOperationError`](#batchoperationerror) wrapping an [`AmbiguousTextError`](#ambiguoustexterror). Must be >= 0 when given.
 
 **Raises:** `ValueError` at construction time if the paragraph ref is malformed,
 `occurrence` is negative, a search-target argument (`find`, delete `text`,
@@ -777,7 +819,8 @@ if all(r.valid for r in results):
 
 ## SearchResult
 
-The result of `Document.find_text()`. Carries no XML/DOM internals.
+The result of `Document.find_text()` (a single match, or None) and
+`Document.find_all()` (a list of them). Carries no XML/DOM internals.
 
 ```python
 from docx_editor import SearchResult
@@ -833,7 +876,11 @@ genuinely need the internals (raw DOM positions), import them from
 
 ### `TextNotFoundError`
 
-Raised when the specified text is not found in the document.
+Raised when the specified text is not found in the document, or when an
+explicit `occurrence` is out of range — the error then carries `occurrence`
+and `total_occurrences` and its message reports the actual count instead of
+claiming the text is absent. Other structured fields: `search_text`,
+`paragraph_ref`, `paragraph_preview`.
 
 ```python
 from docx_editor.exceptions import TextNotFoundError
@@ -844,6 +891,49 @@ except TextNotFoundError as e:
     print(f"Text not found: {e}")
 ```
 
+### `AmbiguousTextError`
+
+Raised when an edit target matches more than once in the search scope and no
+`occurrence` was given. Not a `TextNotFoundError` subclass — the text *was*
+found. Structured fields: `search_text`, `paragraph_ref` (None when
+document-wide), `paragraph_preview` (None when document-wide),
+`total_occurrences`.
+
+```python
+from docx_editor.exceptions import AmbiguousTextError
+
+try:
+    doc.replace("term", "clause", paragraph="P2#f3c1")
+except AmbiguousTextError as e:
+    r = doc.find_all("term", paragraph=e.paragraph_ref)[0]
+    doc.replace("term", "clause", paragraph=r.paragraph_ref,
+                occurrence=r.paragraph_occurrence)
+```
+
+### `BatchOperationError`
+
+The only exception `batch_edit()` / `batch_rewrite()` raise for a failing
+operation. Structured fields: `operation_index` (0-based position of the
+failing op), `reason` (human-readable message), `original` (the underlying
+typed exception, also set as `__cause__`; `None` for batch-level rule
+violations that have no underlying exception, e.g. a missing paragraph ref or
+a duplicate paragraph in `batch_rewrite`).
+
+```python
+from docx_editor.exceptions import BatchOperationError, HashMismatchError
+
+while ops:
+    try:
+        doc.batch_edit(ops)
+        break
+    except BatchOperationError as e:
+        if isinstance(e.original, HashMismatchError):
+            op = ops[e.operation_index]
+            op.paragraph = f"P{e.original.paragraph_index}#{e.original.actual_hash}"
+        else:
+            ops.pop(e.operation_index)
+```
+
 ### `CommentError`
 
 Raised when a comment operation fails.

docx_editor/__init__.py

@@ -37,6 +37,7 @@
 from .comments import Comment
 from .document import Document
 from .exceptions import (
+    AmbiguousTextError,
     BatchOperationError,
     CommentError,
     DocumentNotFoundError,
@@ -88,6 +89,7 @@
     "RevisionError",
     "CommentError",
     "TextNotFoundError",
+    "AmbiguousTextError",
     "HashMismatchError",
     "ParagraphIndexError",
     "BatchOperationError",