apply-edit-block 0.1.0__tar.gz

apply_edit_block-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+*.log
+.DS_Store

apply_edit_block-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: apply-edit-block
+Version: 0.1.0
+Summary: Apply search/replace edit blocks from coding agents to source text, with a fallback ladder for near-exact matches.
+Project-URL: Homepage, https://github.com/pjdurden/apply-edit-block
+Project-URL: Source, https://github.com/pjdurden/apply-edit-block
+Author: Prajjwal Chittori
+License: MIT
+Keywords: coding-agent,diff,edit,fuzzy-match,patch,search-replace
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# apply-edit-block
+
+Apply search/replace edit blocks from coding agents to source text, with a fallback ladder for near-exact matches. This is the Python port of the [JavaScript `apply-edit-block` package](https://github.com/pjdurden/apply-edit-block).
+
+## The problem
+
+Coding agents (and the humans steering them) emit edits as a block of "find this text, replace it with this text." The search text is almost never byte-exact: the model drops trailing whitespace, reindents a block, paraphrases a comment, or gets one word wrong in an otherwise correct match. Aider, Cline, Roo, Continue, and a pile of homegrown tools each reimplement their own ladder of fallback matching strategies to cope with this, usually as a tangle of regexes buried inside a larger apply-patch function. There are a handful of small competing packages for this and no clear winner, and none of them report which strategy actually matched so callers can log and tune it.
+
+This package is that ladder, pulled out on its own. It matches search text against source text using five strategies of decreasing strictness, applies the replacement, and reports which strategy it used and how confident the match was. It does the matching only: no filesystem access, no git, no diff generation.
+
+## Install
+
+```
+pip install apply-edit-block
+```
+
+## Usage
+
+```python
+from apply_edit_block import apply_edit, apply_edits, parse_blocks, similarity
+
+source = '''function greet(name):
+    print("hi " + name)
+'''
+
+# The model dropped a trailing space, but the exact strategy still
+# finds it via the fallback ladder.
+edit = {
+    "search": '    print("hi " + name) ',
+    "replace": '    print(f"hi {name}")',
+}
+
+result = apply_edit(source, edit)
+print(result.strategy)  # 'trailing-ws'
+print(result.text)
+# function greet(name):
+#     print(f"hi {name}")
+
+# Parse the conventional fenced format agents emit and apply every block.
+patch = '''
+<<<<<<< SEARCH
+    print("hi " + name)
+=======
+    print(f"hi {name}")
+>>>>>>> REPLACE
+'''
+edits = parse_blocks(patch)
+multi = apply_edits(source, edits)
+print(multi.ok, multi.applied)  # True 1
+
+# similarity() is the same scoring function 'fuzzy' uses internally.
+print(similarity("a\nb\nc", "a\nb\nz"))  # 0.6666666666666666
+```
+
+## API
+
+### `apply_edit(source, edit, *, anchor_slack=2, threshold=0.85) -> EditResult`
+
+- `source: str` - the full file contents.
+- `edit` - an `Edit` dataclass, or a dict with `search: str` and `replace: str` keys.
+- `anchor_slack: int` (default `2`) - for the `'anchor'` strategy, how far the source's line gap between the first/last non-empty search lines may differ from the search's.
+- `threshold: float` (default `0.85`) - for the `'fuzzy'` strategy, the minimum similarity score required to accept a window.
+- Returns an `EditResult`, a frozen dataclass:
+  ```python
+  @dataclass(frozen=True)
+  class EditResult:
+      ok: bool
+      text: str                    # edited source on success, ORIGINAL source on failure
+      strategy: Optional[str]      # 'exact' | 'trailing-ws' | 'indent' | 'anchor' | 'fuzzy' | 'empty-search' | None
+      similarity: float            # 1 on exact match; best similarity found otherwise (0..1)
+      start: int                   # char offset of match start in the original source, -1 on failure
+      end: int                     # char offset of match end (exclusive) in the original source, -1 on failure
+  ```
+- Raises `TypeError` only if `source` or the edit's `search` is not a string. A failed match never raises; it returns `ok=False`.
+- An empty `search` string means "prepend `replace` to the file": `ok=True`, `strategy='empty-search'`, `start=0`, `end=0`.
+
+The strategies are tried in this order, stopping at the first success:
+
+1. **`exact`** - plain substring search.
+2. **`trailing-ws`** - line-by-line comparison with trailing whitespace stripped from every line on both sides.
+3. **`indent`** - line-by-line comparison with each line's leading whitespace stripped. On success, the indent delta (the matched source line's indentation minus the search's first line's indentation) is applied to every line of the replacement: add spaces for a positive delta, strip up to that many leading spaces for a negative one. Blank replacement lines are left blank.
+4. **`anchor`** - matches only on the first and last non-empty lines of `search`, and requires the line gap between them in the source to be within `anchor_slack` of the search's gap. Useful when an interior line was paraphrased.
+5. **`fuzzy`** - slides a window the size of `search`'s line count over the source and scores each window with `similarity()`; the best-scoring window is accepted if its score is at least `threshold`.
+
+On failure, `similarity` reports the best score `fuzzy` saw while sliding, so callers can tune `threshold`.
+
+### `apply_edits(source, edits, *, anchor_slack=2, threshold=0.85) -> MultiResult`
+
+Applies a list of edits in order, each to the output of the previous one.
+
+```python
+@dataclass(frozen=True)
+class MultiResult:
+    ok: bool
+    text: str
+    results: List[EditResult]
+    applied: int
+```
+
+`ok` is true only if every edit applied. On the first failure it stops immediately: `text` is the source as of the last successful edit, `results` holds one `EditResult` per edit attempted (including the failing one), and `applied` is the count that succeeded.
+
+### `parse_blocks(text) -> List[Edit]`
+
+Parses the conventional fenced format:
+
+```
+<<<<<<< SEARCH
+old code
+=======
+new code
+>>>>>>> REPLACE
+```
+
+Marker lines are matched by prefix (`<{3,}`, `={3,}`, `>{3,}`), so 3 or more marker characters and trailing text on the marker line (`<<<<<<< SEARCH`, `======= divider`) are both tolerated. Text outside a block is ignored. Returns `[]` when there are no blocks. A block that opens but never closes (no matching `>>>>>>>` line before the text ends, or before a new `<<<<<<<` line starts another block) is skipped, not treated as an error.
+
+Returns a list of `Edit` dataclass instances (not dicts):
+
+```python
+@dataclass(frozen=True)
+class Edit:
+    search: str
+    replace: str
+```
+
+`Edit` instances and plain `{"search": ..., "replace": ...}` dicts are interchangeable everywhere an `edit` argument is accepted, so the output of `parse_blocks` can be passed straight into `apply_edit` / `apply_edits`, and so can your own dicts.
+
+### `similarity(a, b) -> float`
+
+Normalized line-level similarity between two strings, `0..1`. This is the exact function the `'fuzzy'` strategy uses internally, exported so callers can score candidate matches themselves or tune `threshold` against real data.
+
+## How it works
+
+`similarity()` splits both strings on `\n` and computes the longest common subsequence (LCS) of the two line arrays, using exact string equality per line, then divides by the length of the longer array. This is a classic O(n*m) dynamic-programming LCS, not a character-level edit distance. That tradeoff is deliberate: it is cheap to reason about and it is what makes the `'fuzzy'` strategy tolerate one bad line out of ten (LCS of 9, divided by 10, is 0.9) without needing a fuzzy string-distance library.
+
+The tradeoff has a real limit: a line that differs by even one character (extra indentation, a changed variable name, a dropped semicolon) counts as a total non-match for that line in the LCS, since comparison is exact-string, not per-character. That is why `'indent'` and `'trailing-ws'` exist as their own strategies rather than being folded into `'fuzzy'`: they normalize a specific, common kind of per-line noise before comparing, so a whole block that only differs in leading or trailing whitespace still counts as fully matched rather than scoring low on `similarity`.
+
+The `'anchor'` strategy is the loosest exact-match strategy: it trusts only the first and last non-empty lines of `search` and a line-count budget for what's in between, so it can survive a paraphrased comment or a rewritten line in the middle of an otherwise-recognizable block. It does not use `similarity` at all.
+
+All offsets (`start`, `end`) are character indices into the original `source` string that was passed in, and `end` is exclusive, so `source[start:end]` is always the exact text that was replaced.
+
+This module has zero runtime dependencies and is a single file (`apply_edit_block.py`).
+
+The original JavaScript version, with the same behavior, lives at the repository root: [`../index.js`](../index.js).
+
+## License
+
+MIT

apply_edit_block-0.1.0/README.md

@@ -0,0 +1,147 @@
+# apply-edit-block
+
+Apply search/replace edit blocks from coding agents to source text, with a fallback ladder for near-exact matches. This is the Python port of the [JavaScript `apply-edit-block` package](https://github.com/pjdurden/apply-edit-block).
+
+## The problem
+
+Coding agents (and the humans steering them) emit edits as a block of "find this text, replace it with this text." The search text is almost never byte-exact: the model drops trailing whitespace, reindents a block, paraphrases a comment, or gets one word wrong in an otherwise correct match. Aider, Cline, Roo, Continue, and a pile of homegrown tools each reimplement their own ladder of fallback matching strategies to cope with this, usually as a tangle of regexes buried inside a larger apply-patch function. There are a handful of small competing packages for this and no clear winner, and none of them report which strategy actually matched so callers can log and tune it.
+
+This package is that ladder, pulled out on its own. It matches search text against source text using five strategies of decreasing strictness, applies the replacement, and reports which strategy it used and how confident the match was. It does the matching only: no filesystem access, no git, no diff generation.
+
+## Install
+
+```
+pip install apply-edit-block
+```
+
+## Usage
+
+```python
+from apply_edit_block import apply_edit, apply_edits, parse_blocks, similarity
+
+source = '''function greet(name):
+    print("hi " + name)
+'''
+
+# The model dropped a trailing space, but the exact strategy still
+# finds it via the fallback ladder.
+edit = {
+    "search": '    print("hi " + name) ',
+    "replace": '    print(f"hi {name}")',
+}
+
+result = apply_edit(source, edit)
+print(result.strategy)  # 'trailing-ws'
+print(result.text)
+# function greet(name):
+#     print(f"hi {name}")
+
+# Parse the conventional fenced format agents emit and apply every block.
+patch = '''
+<<<<<<< SEARCH
+    print("hi " + name)
+=======
+    print(f"hi {name}")
+>>>>>>> REPLACE
+'''
+edits = parse_blocks(patch)
+multi = apply_edits(source, edits)
+print(multi.ok, multi.applied)  # True 1
+
+# similarity() is the same scoring function 'fuzzy' uses internally.
+print(similarity("a\nb\nc", "a\nb\nz"))  # 0.6666666666666666
+```
+
+## API
+
+### `apply_edit(source, edit, *, anchor_slack=2, threshold=0.85) -> EditResult`
+
+- `source: str` - the full file contents.
+- `edit` - an `Edit` dataclass, or a dict with `search: str` and `replace: str` keys.
+- `anchor_slack: int` (default `2`) - for the `'anchor'` strategy, how far the source's line gap between the first/last non-empty search lines may differ from the search's.
+- `threshold: float` (default `0.85`) - for the `'fuzzy'` strategy, the minimum similarity score required to accept a window.
+- Returns an `EditResult`, a frozen dataclass:
+  ```python
+  @dataclass(frozen=True)
+  class EditResult:
+      ok: bool
+      text: str                    # edited source on success, ORIGINAL source on failure
+      strategy: Optional[str]      # 'exact' | 'trailing-ws' | 'indent' | 'anchor' | 'fuzzy' | 'empty-search' | None
+      similarity: float            # 1 on exact match; best similarity found otherwise (0..1)
+      start: int                   # char offset of match start in the original source, -1 on failure
+      end: int                     # char offset of match end (exclusive) in the original source, -1 on failure
+  ```
+- Raises `TypeError` only if `source` or the edit's `search` is not a string. A failed match never raises; it returns `ok=False`.
+- An empty `search` string means "prepend `replace` to the file": `ok=True`, `strategy='empty-search'`, `start=0`, `end=0`.
+
+The strategies are tried in this order, stopping at the first success:
+
+1. **`exact`** - plain substring search.
+2. **`trailing-ws`** - line-by-line comparison with trailing whitespace stripped from every line on both sides.
+3. **`indent`** - line-by-line comparison with each line's leading whitespace stripped. On success, the indent delta (the matched source line's indentation minus the search's first line's indentation) is applied to every line of the replacement: add spaces for a positive delta, strip up to that many leading spaces for a negative one. Blank replacement lines are left blank.
+4. **`anchor`** - matches only on the first and last non-empty lines of `search`, and requires the line gap between them in the source to be within `anchor_slack` of the search's gap. Useful when an interior line was paraphrased.
+5. **`fuzzy`** - slides a window the size of `search`'s line count over the source and scores each window with `similarity()`; the best-scoring window is accepted if its score is at least `threshold`.
+
+On failure, `similarity` reports the best score `fuzzy` saw while sliding, so callers can tune `threshold`.
+
+### `apply_edits(source, edits, *, anchor_slack=2, threshold=0.85) -> MultiResult`
+
+Applies a list of edits in order, each to the output of the previous one.
+
+```python
+@dataclass(frozen=True)
+class MultiResult:
+    ok: bool
+    text: str
+    results: List[EditResult]
+    applied: int
+```
+
+`ok` is true only if every edit applied. On the first failure it stops immediately: `text` is the source as of the last successful edit, `results` holds one `EditResult` per edit attempted (including the failing one), and `applied` is the count that succeeded.
+
+### `parse_blocks(text) -> List[Edit]`
+
+Parses the conventional fenced format:
+
+```
+<<<<<<< SEARCH
+old code
+=======
+new code
+>>>>>>> REPLACE
+```
+
+Marker lines are matched by prefix (`<{3,}`, `={3,}`, `>{3,}`), so 3 or more marker characters and trailing text on the marker line (`<<<<<<< SEARCH`, `======= divider`) are both tolerated. Text outside a block is ignored. Returns `[]` when there are no blocks. A block that opens but never closes (no matching `>>>>>>>` line before the text ends, or before a new `<<<<<<<` line starts another block) is skipped, not treated as an error.
+
+Returns a list of `Edit` dataclass instances (not dicts):
+
+```python
+@dataclass(frozen=True)
+class Edit:
+    search: str
+    replace: str
+```
+
+`Edit` instances and plain `{"search": ..., "replace": ...}` dicts are interchangeable everywhere an `edit` argument is accepted, so the output of `parse_blocks` can be passed straight into `apply_edit` / `apply_edits`, and so can your own dicts.
+
+### `similarity(a, b) -> float`
+
+Normalized line-level similarity between two strings, `0..1`. This is the exact function the `'fuzzy'` strategy uses internally, exported so callers can score candidate matches themselves or tune `threshold` against real data.
+
+## How it works
+
+`similarity()` splits both strings on `\n` and computes the longest common subsequence (LCS) of the two line arrays, using exact string equality per line, then divides by the length of the longer array. This is a classic O(n*m) dynamic-programming LCS, not a character-level edit distance. That tradeoff is deliberate: it is cheap to reason about and it is what makes the `'fuzzy'` strategy tolerate one bad line out of ten (LCS of 9, divided by 10, is 0.9) without needing a fuzzy string-distance library.
+
+The tradeoff has a real limit: a line that differs by even one character (extra indentation, a changed variable name, a dropped semicolon) counts as a total non-match for that line in the LCS, since comparison is exact-string, not per-character. That is why `'indent'` and `'trailing-ws'` exist as their own strategies rather than being folded into `'fuzzy'`: they normalize a specific, common kind of per-line noise before comparing, so a whole block that only differs in leading or trailing whitespace still counts as fully matched rather than scoring low on `similarity`.
+
+The `'anchor'` strategy is the loosest exact-match strategy: it trusts only the first and last non-empty lines of `search` and a line-count budget for what's in between, so it can survive a paraphrased comment or a rewritten line in the middle of an otherwise-recognizable block. It does not use `similarity` at all.
+
+All offsets (`start`, `end`) are character indices into the original `source` string that was passed in, and `end` is exclusive, so `source[start:end]` is always the exact text that was replaced.
+
+This module has zero runtime dependencies and is a single file (`apply_edit_block.py`).
+
+The original JavaScript version, with the same behavior, lives at the repository root: [`../index.js`](../index.js).
+
+## License
+
+MIT

apply_edit_block-0.1.0/apply_edit_block.py

@@ -0,0 +1,407 @@
+"""
+apply-edit-block
+A standalone strategy ladder for applying "search/replace" edit blocks
+(the kind coding agents emit) to source text, with graceful fallbacks
+when the search text is not byte-exact.
+
+This is a Python port of the JavaScript package `apply-edit-block`. See
+the JavaScript source (index.js) at the repository root for the
+original implementation; this module matches its behavior exactly.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, NamedTuple, Optional, Union
+
+__all__ = [
+    "Edit",
+    "EditResult",
+    "MultiResult",
+    "apply_edit",
+    "apply_edits",
+    "parse_blocks",
+    "similarity",
+    "DEFAULT_ANCHOR_SLACK",
+    "DEFAULT_THRESHOLD",
+]
+
+# Internal defaults. Plain data, edit freely if you fork this file.
+DEFAULT_ANCHOR_SLACK = 2
+DEFAULT_THRESHOLD = 0.85
+
+
+@dataclass(frozen=True)
+class Edit:
+    """A single search/replace edit block."""
+
+    search: str
+    replace: str
+
+
+@dataclass(frozen=True)
+class EditResult:
+    """The result of applying a single edit block."""
+
+    ok: bool
+    text: str
+    strategy: Optional[str]
+    similarity: float
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
+class MultiResult:
+    """The result of applying a sequence of edit blocks."""
+
+    ok: bool
+    text: str
+    results: List[EditResult] = field(default_factory=list)
+    applied: int = 0
+
+
+EditLike = Union[Edit, Dict[str, Any]]
+
+
+class _Line(NamedTuple):
+    """A source line with its char offsets: source[start:end] == text."""
+
+    text: str
+    start: int
+    end: int
+
+
+_TRAILING_WS_RE = re.compile(r"[ \t]+$")
+_LEADING_WS_RE = re.compile(r"^[ \t]+")
+_LEADING_WS_MATCH_RE = re.compile(r"^[ \t]*")
+
+
+def _strip_trailing(line: str) -> str:
+    """Strip trailing spaces/tabs from a line."""
+    return _TRAILING_WS_RE.sub("", line)
+
+
+def _strip_leading(line: str) -> str:
+    """Strip leading spaces/tabs from a line."""
+    return _LEADING_WS_RE.sub("", line)
+
+
+def _leading_ws(line: str) -> str:
+    """Return the leading whitespace substring of a line."""
+    m = _LEADING_WS_MATCH_RE.match(line)
+    return m.group(0) if m else ""
+
+
+def _get_lines(source: str) -> List[_Line]:
+    """Split source into line records with char offsets, so a matched
+    line range maps to [start, end)."""
+    lines: List[_Line] = []
+    offset = 0
+    for text in source.split("\n"):
+        end = offset + len(text)
+        lines.append(_Line(text=text, start=offset, end=end))
+        offset = end + 1  # account for the '\n' removed by split
+    return lines
+
+
+def _build_result(
+    source: str,
+    replace_text: str,
+    strategy: str,
+    start: int,
+    end: int,
+    sim: float,
+) -> EditResult:
+    """Build a successful EditResult by splicing replace_text into
+    source at [start, end)."""
+    text = source[:start] + replace_text + source[end:]
+    return EditResult(ok=True, text=text, strategy=strategy, similarity=sim, start=start, end=end)
+
+
+class _SlideHit(NamedTuple):
+    index: int
+    start: int
+    end: int
+
+
+def _slide_match(
+    source_lines: List[_Line], search_lines: List[str], normalize
+) -> Optional[_SlideHit]:
+    """Slide a window matching search_lines against source_lines
+    line-by-line under a comparator."""
+    n = len(search_lines)
+    if len(source_lines) < n:
+        return None
+    normalized_search = [normalize(l) for l in search_lines]
+    for i in range(0, len(source_lines) - n + 1):
+        matched = True
+        for j in range(n):
+            if normalize(source_lines[i + j].text) != normalized_search[j]:
+                matched = False
+                break
+        if matched:
+            return _SlideHit(index=i, start=source_lines[i].start, end=source_lines[i + n - 1].end)
+    return None
+
+
+class _IndentHit(NamedTuple):
+    start: int
+    end: int
+    delta: int
+
+
+def _try_indent(source_lines: List[_Line], search_lines: List[str]) -> Optional[_IndentHit]:
+    """Strategy 3: 'indent' - compare with leading whitespace stripped,
+    then compute the shift."""
+    hit = _slide_match(source_lines, search_lines, _strip_leading)
+    if hit is None:
+        return None
+    source_indent = len(_leading_ws(source_lines[hit.index].text))
+    search_indent = len(_leading_ws(search_lines[0]))
+    return _IndentHit(start=hit.start, end=hit.end, delta=source_indent - search_indent)
+
+
+def _apply_indent_delta(replace: str, delta: int) -> str:
+    """Apply a uniform indent shift to every non-blank line of the
+    replacement."""
+    if delta == 0:
+        return replace
+
+    def shift_line(line: str) -> str:
+        if line.strip() == "":
+            return line
+        if delta > 0:
+            return " " * delta + line
+        return line[min(-delta, len(_leading_ws(line))):]
+
+    return "\n".join(shift_line(l) for l in replace.split("\n"))
+
+
+class _AnchorHit(NamedTuple):
+    start: int
+    end: int
+
+
+def _try_anchor(
+    source_lines: List[_Line], search_lines: List[str], anchor_slack: int
+) -> Optional[_AnchorHit]:
+    """Strategy 4: 'anchor' - match on the first/last non-empty search
+    lines with slack on the gap."""
+    non_empty_idxs = [i for i, l in enumerate(search_lines) if l.strip() != ""]
+    if not non_empty_idxs:
+        return None
+    first_idx = non_empty_idxs[0]
+    last_idx = non_empty_idxs[-1]
+    first_line = search_lines[first_idx].strip()
+    last_line = search_lines[last_idx].strip()
+    expected_gap = last_idx - first_idx
+    for i in range(len(source_lines)):
+        if source_lines[i].text.strip() != first_line:
+            continue
+        for j in range(i, len(source_lines)):
+            if source_lines[j].text.strip() != last_line:
+                continue
+            if abs(j - i - expected_gap) <= anchor_slack:
+                return _AnchorHit(start=source_lines[i].start, end=source_lines[j].end)
+    return None
+
+
+def _lcs_length(a: List[str], b: List[str]) -> int:
+    """Longest common subsequence length between two arrays, by
+    element equality."""
+    n = len(a)
+    m = len(b)
+    dp = [[0] * (m + 1) for _ in range(n + 1)]
+    for i in range(1, n + 1):
+        for j in range(1, m + 1):
+            if a[i - 1] == b[j - 1]:
+                dp[i][j] = dp[i - 1][j - 1] + 1
+            else:
+                dp[i][j] = max(dp[i - 1][j], dp[i][j - 1])
+    return dp[n][m]
+
+
+def similarity(a: str, b: str) -> float:
+    """Normalized line-level similarity between two strings, 0..1.
+
+    Computed as the longest-common-subsequence over the two line
+    arrays, divided by the longer array's length. Used by the 'fuzzy'
+    strategy.
+    """
+    lines_a = a.split("\n")
+    lines_b = b.split("\n")
+    max_len = max(len(lines_a), len(lines_b))
+    return _lcs_length(lines_a, lines_b) / max_len
+
+
+class _FuzzyResult(NamedTuple):
+    match: Optional[_AnchorHit]
+    best_score: float
+
+
+def _try_fuzzy(source_lines: List[_Line], search_lines: List[str], threshold: float) -> _FuzzyResult:
+    """Strategy 5: 'fuzzy' - slide a window and score it against the
+    search text."""
+    search_text = "\n".join(search_lines)
+    win_size = len(search_lines)
+    if len(source_lines) < win_size:
+        whole = "\n".join(l.text for l in source_lines)
+        return _FuzzyResult(match=None, best_score=similarity(search_text, whole))
+    best_score = -1.0
+    best_index = -1
+    for i in range(0, len(source_lines) - win_size + 1):
+        window_text = "\n".join(l.text for l in source_lines[i : i + win_size])
+        score = similarity(search_text, window_text)
+        if score > best_score:
+            best_score = score
+            best_index = i
+    if best_score >= threshold:
+        match = _AnchorHit(start=source_lines[best_index].start, end=source_lines[best_index + win_size - 1].end)
+        return _FuzzyResult(match=match, best_score=best_score)
+    return _FuzzyResult(match=None, best_score=best_score)
+
+
+def _field(edit: EditLike, name: str) -> Any:
+    """Read `name` off an Edit dataclass or a dict, mirroring JS's
+    permissive property access on edit.search / edit.replace."""
+    if isinstance(edit, dict):
+        return edit.get(name)
+    return getattr(edit, name, None)
+
+
+def apply_edit(
+    source: str,
+    edit: EditLike,
+    *,
+    anchor_slack: int = DEFAULT_ANCHOR_SLACK,
+    threshold: float = DEFAULT_THRESHOLD,
+) -> EditResult:
+    """Apply one search/replace edit block to source text, trying a
+    ladder of matching strategies from strict to fuzzy and stopping at
+    the first success.
+
+    `edit` may be an `Edit` dataclass or a dict with `search`/`replace`
+    keys.
+
+    Raises `TypeError` if `source` or the search text is not a string.
+    A failed match never raises; it returns `ok=False` with the
+    original `source` in `text`.
+    """
+    if not isinstance(source, str):
+        raise TypeError("source must be a string")
+    search = _field(edit, "search") if edit is not None else None
+    if edit is None or not isinstance(search, str):
+        raise TypeError("edit.search must be a string")
+
+    replace_raw = _field(edit, "replace")
+    replace = replace_raw if isinstance(replace_raw, str) else ""
+
+    if search == "":
+        return EditResult(ok=True, text=replace + source, strategy="empty-search", similarity=1, start=0, end=0)
+
+    # 1. exact
+    exact_idx = source.find(search)
+    if exact_idx != -1:
+        return _build_result(source, replace, "exact", exact_idx, exact_idx + len(search), 1)
+
+    source_lines = _get_lines(source)
+    search_lines = search.split("\n")
+
+    # 2. trailing-ws
+    tw = _slide_match(source_lines, search_lines, _strip_trailing)
+    if tw is not None:
+        sim = similarity(search, source[tw.start : tw.end])
+        return _build_result(source, replace, "trailing-ws", tw.start, tw.end, sim)
+
+    # 3. indent
+    ind = _try_indent(source_lines, search_lines)
+    if ind is not None:
+        sim = similarity(search, source[ind.start : ind.end])
+        adjusted = _apply_indent_delta(replace, ind.delta)
+        return _build_result(source, adjusted, "indent", ind.start, ind.end, sim)
+
+    # 4. anchor
+    anc = _try_anchor(source_lines, search_lines, anchor_slack)
+    if anc is not None:
+        sim = similarity(search, source[anc.start : anc.end])
+        return _build_result(source, replace, "anchor", anc.start, anc.end, sim)
+
+    # 5. fuzzy
+    fz = _try_fuzzy(source_lines, search_lines, threshold)
+    if fz.match is not None:
+        sim = similarity(search, source[fz.match.start : fz.match.end])
+        return _build_result(source, replace, "fuzzy", fz.match.start, fz.match.end, sim)
+
+    return EditResult(ok=False, text=source, strategy=None, similarity=max(fz.best_score, 0), start=-1, end=-1)
+
+
+def apply_edits(
+    source: str,
+    edits: List[EditLike],
+    *,
+    anchor_slack: int = DEFAULT_ANCHOR_SLACK,
+    threshold: float = DEFAULT_THRESHOLD,
+) -> MultiResult:
+    """Apply a list of edits in order, each to the output of the
+    previous one. Stops at the first failure."""
+    text = source
+    results: List[EditResult] = []
+    applied = 0
+    for edit in edits:
+        result = apply_edit(text, edit, anchor_slack=anchor_slack, threshold=threshold)
+        results.append(result)
+        if not result.ok:
+            return MultiResult(ok=False, text=text, results=results, applied=applied)
+        text = result.text
+        applied += 1
+    return MultiResult(ok=True, text=text, results=results, applied=applied)
+
+
+_START_RE = re.compile(r"^<{3,}")
+_DIVIDER_RE = re.compile(r"^={3,}")
+_END_RE = re.compile(r"^>{3,}")
+
+
+def parse_blocks(text: str) -> List[Edit]:
+    """Parse the conventional fenced search/replace block format:
+
+    ```
+    <<<<<<< SEARCH
+    old code
+    =======
+    new code
+    >>>>>>> REPLACE
+    ```
+
+    Tolerates 3+ marker characters and trailing text on marker lines.
+    An unclosed block is skipped rather than treated as an error.
+
+    Returns a list of `Edit` dataclass instances (not dicts).
+    """
+    lines = text.split("\n")
+    blocks: List[Edit] = []
+    state = "none"  # 'none' | 'search' | 'replace'
+    search_lines: List[str] = []
+    replace_lines: List[str] = []
+    for line in lines:
+        if _START_RE.match(line):
+            state = "search"
+            search_lines = []
+            replace_lines = []
+            continue
+        if state == "search":
+            if _DIVIDER_RE.match(line):
+                state = "replace"
+            else:
+                search_lines.append(line)
+            continue
+        if state == "replace":
+            if _END_RE.match(line):
+                blocks.append(Edit(search="\n".join(search_lines), replace="\n".join(replace_lines)))
+                state = "none"
+            else:
+                replace_lines.append(line)
+
+    return blocks

apply_edit_block-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apply-edit-block"
+version = "0.1.0"
+description = "Apply search/replace edit blocks from coding agents to source text, with a fallback ladder for near-exact matches."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "Prajjwal Chittori"}]
+keywords = ["edit", "patch", "diff", "search-replace", "coding-agent", "fuzzy-match"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/pjdurden/apply-edit-block"
+Source = "https://github.com/pjdurden/apply-edit-block"
+
+[tool.hatch.build.targets.wheel]
+include = ["apply_edit_block.py", "py.typed"]

apply_edit_block-0.1.0/test_apply_edit_block.py

@@ -0,0 +1,234 @@
+"""Tests for apply_edit_block, ported one for one from the JavaScript
+test suite at ../test/apply-edit-block.test.js, plus the extra indent
+cases specified for this port."""
+
+import unittest
+
+from apply_edit_block import Edit, apply_edit, apply_edits, parse_blocks, similarity
+
+
+class ApplyEditTest(unittest.TestCase):
+    def test_exact_match_reports_strategy_exact_and_similarity_1(self):
+        source = "const x = 1;\nconst y = 2;\n"
+        result = apply_edit(source, {"search": "const x = 1;\n", "replace": "const x = 100;\n"})
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.strategy, "exact")
+        self.assertEqual(result.similarity, 1)
+        self.assertEqual(result.text, "const x = 100;\nconst y = 2;\n")
+        self.assertEqual(result.start, 0)
+        self.assertEqual(result.end, 13)
+
+    def test_trailing_whitespace_in_search_matches_via_trailing_ws(self):
+        source = "function foo() {\n  return 1;\n}\n"
+        search = "function foo() {   \n  return 1;  \n}\n"
+        result = apply_edit(source, {"search": search, "replace": "function foo() {\n  return 2;\n}\n"})
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.strategy, "trailing-ws")
+        self.assertEqual(result.text, "function foo() {\n  return 2;\n}\n")
+
+    def test_indent_mismatch_matches_via_indent_and_reapplies_source_indentation(self):
+        source = "      if (x) {\n        doThing();\n      }\n"
+        search = "  if (x) {\n    doThing();\n  }"
+        replace = "  if (x) {\n    doOther();\n\n    doMore();\n  }"
+        result = apply_edit(source, {"search": search, "replace": replace})
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.strategy, "indent")
+        self.assertEqual(
+            result.text,
+            "      if (x) {\n        doOther();\n\n        doMore();\n      }\n",
+        )
+
+    def test_indent_strategy_leaves_blank_replacement_lines_blank(self):
+        source = "    a();\n    b();\n"
+        search = "a();\nb();"
+        replace = "a();\n\nb();"
+        result = apply_edit(source, {"search": search, "replace": replace})
+        self.assertEqual(result.strategy, "indent")
+        self.assertEqual(result.text, "    a();\n\n    b();\n")
+
+    def test_indent_strategy_handles_negative_delta_by_stripping_leading_spaces(self):
+        source = "a();\nb();\n"
+        search = "    a();\n    b();"
+        replace = "    a();\n    c();"
+        result = apply_edit(source, {"search": search, "replace": replace})
+        self.assertEqual(result.strategy, "indent")
+        self.assertEqual(result.text, "a();\nc();\n")
+
+    def test_anchor_strategy_matches_on_first_last_nonempty_lines_when_middle_differs(self):
+        source = "\n".join(
+            [
+                "function calc(a, b) {",
+                "  const sum = a + b;",
+                "  const product = a * b;",
+                "  return sum + product;",
+                "}",
+            ]
+        )
+        search = "\n".join(
+            [
+                "function calc(a, b) {",
+                "  // a different comment entirely",
+                "  return sum + product;",
+                "}",
+            ]
+        )
+        result = apply_edit(source, {"search": search, "replace": "function calc(a, b) {\n  return 0;\n}"})
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.strategy, "anchor")
+        self.assertEqual(result.text, "function calc(a, b) {\n  return 0;\n}")
+
+    def test_anchor_strategy_respects_anchor_slack_on_line_count_gap(self):
+        source = "\n".join(["START", "a", "b", "c", "d", "e", "END"])
+        search = "\n".join(["START", "x", "END"])  # gap 1 in search vs gap 5 in source
+        failure = apply_edit(source, {"search": search, "replace": "GONE"}, anchor_slack=2)
+        self.assertEqual(failure.strategy, None)
+        success = apply_edit(source, {"search": search, "replace": "GONE"}, anchor_slack=5)
+        self.assertEqual(success.strategy, "anchor")
+        self.assertEqual(success.text, "GONE")
+
+    def test_one_word_typo_inside_10_line_block_matches_via_fuzzy(self):
+        lines = [f"  line{i} = {i};" for i in range(1, 11)]
+        source = "\n".join(lines)
+        search_lines = lines[:]
+        search_lines[0] = search_lines[0].replace("line1", "lyne1")  # typo breaks the anchor too
+        result = apply_edit(source, {"search": "\n".join(search_lines), "replace": "REPLACED_BLOCK"})
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.strategy, "fuzzy")
+        self.assertEqual(result.text, "REPLACED_BLOCK")
+        self.assertTrue(result.similarity >= 0.85 and result.similarity < 1)
+
+    def test_fuzzy_strategy_respects_the_threshold_option(self):
+        lines = [f"  line{i} = {i};" for i in range(1, 11)]
+        source = "\n".join(lines)
+        search_lines = lines[:]
+        search_lines[0] = "lyne1 = totally different content here"
+        search = "\n".join(search_lines)
+        result = apply_edit(source, {"search": search, "replace": "X"}, threshold=0.95)
+        self.assertEqual(result.ok, False)
+        self.assertTrue(result.similarity < 0.95)
+
+    def test_garbage_search_text_fails_cleanly(self):
+        source = "const a = 1;\nconst b = 2;\n"
+        result = apply_edit(source, {"search": "totally unrelated garbage §§§", "replace": "x"})
+        self.assertEqual(result.ok, False)
+        self.assertEqual(result.text, source)
+        self.assertEqual(result.strategy, None)
+        self.assertEqual(result.start, -1)
+        self.assertEqual(result.end, -1)
+        self.assertTrue(result.similarity >= 0 and result.similarity < 1)
+
+    def test_empty_search_string_prepends_the_replacement(self):
+        source = "body\n"
+        result = apply_edit(source, {"search": "", "replace": "header\n"})
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.strategy, "empty-search")
+        self.assertEqual(result.similarity, 1)
+        self.assertEqual(result.start, 0)
+        self.assertEqual(result.end, 0)
+        self.assertEqual(result.text, "header\nbody\n")
+
+    def test_apply_edit_raises_typeerror_for_non_string_source_or_search(self):
+        with self.assertRaises(TypeError):
+            apply_edit(42, {"search": "a", "replace": "b"})
+        with self.assertRaises(TypeError):
+            apply_edit("src", {"search": 42, "replace": "b"})
+
+    def test_apply_edit_accepts_edit_dataclass_as_well_as_dict(self):
+        source = "const x = 1;\n"
+        result = apply_edit(source, Edit(search="const x = 1;\n", replace="const x = 2;\n"))
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.text, "const x = 2;\n")
+
+    def test_parse_blocks_returns_two_blocks_in_order(self):
+        text = "\n".join(
+            [
+                "<<<<<<< SEARCH",
+                "foo1",
+                "=======",
+                "bar1",
+                ">>>>>>> REPLACE",
+                "unrelated text in between",
+                "<<<<<<<<< SEARCH extra",
+                "foo2",
+                "========= extra",
+                "bar2",
+                ">>>>>>>>> REPLACE extra",
+            ]
+        )
+        blocks = parse_blocks(text)
+        self.assertEqual(len(blocks), 2)
+        self.assertEqual(blocks[0], Edit(search="foo1", replace="bar1"))
+        self.assertEqual(blocks[1], Edit(search="foo2", replace="bar2"))
+
+    def test_parse_blocks_skips_an_unclosed_block_and_returns_empty(self):
+        text = "\n".join(["<<<<<<< SEARCH", "foo", "=======", "bar"])
+        self.assertEqual(parse_blocks(text), [])
+
+    def test_parse_blocks_returns_empty_when_there_are_no_blocks(self):
+        self.assertEqual(parse_blocks("just some plain text\nwith no markers"), [])
+
+    def test_apply_edits_stops_at_the_first_failure_and_reports_applied(self):
+        source = "aaa\nbbb\nccc\n"
+        edits = [
+            {"search": "aaa", "replace": "AAA"},
+            {"search": "not-there-at-all", "replace": "X"},
+            {"search": "ccc", "replace": "CCC"},
+        ]
+        result = apply_edits(source, edits)
+        self.assertEqual(result.ok, False)
+        self.assertEqual(result.applied, 1)
+        self.assertEqual(result.text, "AAA\nbbb\nccc\n")
+        self.assertEqual(len(result.results), 2)
+        self.assertEqual(result.results[0].ok, True)
+        self.assertEqual(result.results[1].ok, False)
+
+    def test_apply_edits_applies_every_edit_in_sequence_when_all_succeed(self):
+        source = "aaa\nbbb\nccc\n"
+        edits = [
+            {"search": "aaa", "replace": "AAA"},
+            {"search": "bbb", "replace": "BBB"},
+            {"search": "ccc", "replace": "CCC"},
+        ]
+        result = apply_edits(source, edits)
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.applied, 3)
+        self.assertEqual(result.text, "AAA\nBBB\nCCC\n")
+
+    def test_similarity_is_1_for_identical_strings_and_lower_for_different_ones(self):
+        self.assertEqual(similarity("a\nb\nc", "a\nb\nc"), 1)
+        self.assertTrue(similarity("a\nb\nc", "x\ny\nz") < 1)
+        self.assertEqual(similarity("", ""), 1)
+
+    def test_similarity_is_the_exact_function_used_to_score_the_fuzzy_strategy(self):
+        source = "\n".join(["  line1 = 1;", "  line2 = 2;", "  line3 = 2;"])
+        search = "\n".join(["  line1 = 1;", "  line2 = 2;", "  line3 = 99;"])
+        result = apply_edit(source, {"search": search, "replace": "X"}, threshold=0.5)
+        expected = similarity(search, source)
+        self.assertEqual(result.similarity, expected)
+
+    # --- extra indent cases specified for this port, checked character for character ---
+
+    def test_indent_strategy_positive_delta_with_nested_block_char_for_char(self):
+        source = "      if (cond) {\n        doStuff();\n      }\n"
+        search = "  if (cond) {\n    doStuff();\n  }"
+        replace = "  if (cond) {\n    doOther();\n\n    if (nested) {\n      doNested();\n    }\n  }"
+        result = apply_edit(source, {"search": search, "replace": replace})
+        self.assertEqual(result.strategy, "indent")
+        expected = (
+            "      if (cond) {\n        doOther();\n\n        if (nested) {\n"
+            "          doNested();\n        }\n      }\n"
+        )
+        self.assertEqual(result.text, expected)
+
+    def test_indent_strategy_negative_delta_with_nested_block_char_for_char(self):
+        source = "  if (cond) {\n    doStuff();\n  }\n"
+        search = "      if (cond) {\n        doStuff();\n      }"
+        replace = "      if (cond) {\n        doOther();\n\n        if (nested) {\n          doNested();\n        }\n      }"
+        result = apply_edit(source, {"search": search, "replace": replace})
+        self.assertEqual(result.strategy, "indent")
+        expected = "  if (cond) {\n    doOther();\n\n    if (nested) {\n      doNested();\n    }\n  }\n"
+        self.assertEqual(result.text, expected)
+
+
+if __name__ == "__main__":
+    unittest.main()