apply-edit-block 0.1.0__py3-none-any.whl

apply_edit_block-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+apply_edit_block.py,sha256=ayf3v92RX3PitQv2VKK3sK83KSZBWI_Ldr4BS79QgdQ,12711
+py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+apply_edit_block-0.1.0.dist-info/METADATA,sha256=Er_Gxh42VxAYcvBdbBCrxNUsTIPsiMccW4BFGYDmlvk,9121
+apply_edit_block-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+apply_edit_block-0.1.0.dist-info/RECORD,,

apply_edit_block-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

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