json-source-edit 0.1.0__py3-none-any.whl

json_source_edit/__init__.py

@@ -0,0 +1,16 @@
+"""json-source-edit: surgical, byte-preserving JSON editing.
+
+"Only change what you intend to change, preserve everything else
+byte-for-byte." See ADR-0013 in the parent codetour-cli project
+(``docs/adr/0013-format-preserving-json-editing.md``) for the design.
+"""
+from .editor import JSONEditor, Modification
+from .operations import UnsupportedRemovePath
+from .validator import SemanticValidationError
+
+__all__ = [
+    "JSONEditor",
+    "Modification",
+    "UnsupportedRemovePath",
+    "SemanticValidationError",
+]

json_source_edit/algorithm.py

@@ -0,0 +1,119 @@
+"""Core edit-application algorithm.
+
+The O(n log n) cursor traversal (ADR-0013's chosen Approach 4: sort edits by
+start position, then build the result in one linear pass, alternating copied
+original-text chunks with spliced-in replacement values), plus the two
+batch-level passes Round 4 added for array-element deletions (§2b):
+coalescing overlapping/adjacent deletion-only edits, and stripping the
+trailing comma a coalesced deletion can orphan.
+"""
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+
+@dataclass
+class Edit:
+    """A single position-based text replacement.
+
+    Positions are always in ORIGINAL-document coordinates (ADR-0013 Round 4
+    §1's coordinate-frame contract) — they never shift to account for other
+    edits in the same batch.
+    """
+
+    start: int
+    end: int
+    replacement: str
+    path: str
+
+
+def coalesce_deletions(edits: List[Edit]) -> List[Edit]:
+    """Merge overlapping/touching deletion-only (``replacement == ""``)
+    edits; leave every other edit untouched.
+
+    Regression: R3-2 (ADR-0013 Round 3) — batch-deleting an array's true
+    last element alongside its immediate predecessor makes both claim the
+    same comma. Cicerone's Option (ii), affirmed in Round 4 §2b: deletions
+    are order-independent, so merging their ranges is semantically safe.
+    """
+    deletions = sorted((e for e in edits if e.replacement == ""), key=lambda e: e.start)
+    others = [e for e in edits if e.replacement != ""]
+    if not deletions:
+        return sorted(others, key=lambda e: e.start)
+
+    merged: List[Edit] = [deletions[0]]
+    for e in deletions[1:]:
+        last = merged[-1]
+        if e.start <= last.end:
+            merged[-1] = Edit(last.start, max(last.end, e.end), "", last.path)
+        else:
+            merged.append(e)
+    return sorted(merged + others, key=lambda e: e.start)
+
+
+def strip_orphaned_trailing_commas(
+    text: str, edits: List[Edit], array_close_by_path: Dict[str, int]
+) -> List[Edit]:
+    """Splicer's addendum to §2b (ADR-0013 Round 4): coalescing alone can
+    still emit invalid JSON. When a (coalesced) deletion range reaches an
+    array's closing bracket but the array isn't being emptied entirely, the
+    element surviving just before the deleted range keeps a now-orphaned
+    trailing comma — it was never last, so it never claimed its own comma.
+
+    ``array_close_by_path`` maps each array's own JSON-pointer path (the
+    parent of any deleted element's path) to the position of that array's
+    ``]`` character itself — i.e. ``source_map[array_path].value_end - 1``,
+    **not** ``value_end`` directly (``value_end`` is exclusive; passing it
+    unadjusted silently no-ops this fix whenever the array isn't the last
+    thing in the document — the off-by-one Round 4 caught in itself, see
+    ``OPS-2.5.8`` / ``TEST-MATRIX-0013.md``).
+    """
+    fixed: List[Edit] = []
+    for e in edits:
+        if e.replacement != "":
+            fixed.append(e)
+            continue
+        start, end = e.start, e.end
+        parent = e.path.rsplit("/", 1)[0]
+        close_pos: Optional[int] = array_close_by_path.get(parent)
+        if (
+            close_pos is not None
+            and close_pos >= end
+            and text[end:close_pos].strip() == ""
+            and start > 0
+            and text[start - 1] == ","
+        ):
+            start -= 1
+        fixed.append(Edit(start, end, e.replacement, e.path))
+    return fixed
+
+
+def apply_edits(original: str, edits: List[Edit]) -> str:
+    """Apply multiple edits to ``original`` in a single linear pass.
+
+    Args:
+        original: the original text.
+        edits: edits to apply (sorted internally; the input list is not
+            mutated).
+
+    Returns:
+        The modified text.
+
+    Raises:
+        ValueError: if any two edits overlap after sorting.
+    """
+    sorted_edits = sorted(edits, key=lambda e: e.start)
+
+    for i in range(len(sorted_edits) - 1):
+        if sorted_edits[i].end > sorted_edits[i + 1].start:
+            raise ValueError(
+                f"Overlapping edits: {sorted_edits[i].path} and {sorted_edits[i + 1].path}"
+            )
+
+    cursor = 0
+    result: List[str] = []
+    for edit in sorted_edits:
+        result.append(original[cursor:edit.start])
+        result.append(edit.replacement)
+        cursor = edit.end
+    result.append(original[cursor:])
+    return "".join(result)

json_source_edit/editor.py

@@ -0,0 +1,240 @@
+"""JSONEditor: format-preserving JSON editing using surgical text replacement.
+
+ADR-0013's core principle: "only change what you intend to change, preserve
+everything else byte-for-byte." Round 4 §1's coordinate-frame contract is
+this class's central discipline: ``self.parsed`` is set once, in
+``__init__``, and **never mutated afterward** — every path, at every layer
+(operation compilation, audit-trail capture, last-element detection),
+resolves against that same pristine parse, regardless of operation order.
+"""
+import difflib
+import json
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from .algorithm import apply_edits, coalesce_deletions, strip_orphaned_trailing_commas
+from .operations import Operation, Remove, Replace, resolve_path
+from .source_map import SourceMap
+from .validator import SemanticValidationError, validate_semantic_postconditions
+from .source_map import generate as generate_source_map
+
+
+@dataclass
+class Modification:
+    """One recorded modification (the audit trail).
+
+    ``old_value`` is always captured from the pristine parse at record time
+    — Round 4 §1 guarantees this is correct regardless of what else has been
+    recorded earlier in the same batch, because nothing before it could have
+    mutated ``parsed``.
+    """
+
+    operation: str  # "replace" or "remove"
+    path: str
+    old_value: Any
+    new_value: Optional[Any]
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+
+
+class JSONEditor:
+    """Format-preserving JSON editor using surgical text replacement."""
+
+    def __init__(self, original_text: str, source_map: SourceMap, parsed: Any):
+        self.original_text = original_text
+        self.source_map = source_map
+        self.parsed = parsed  # NEVER mutated after this point (Round 4 §1)
+        self.operations: List[Operation] = []
+        self.modifications: List[Modification] = []
+
+    @classmethod
+    def from_string(cls, text: str) -> "JSONEditor":
+        """Load JSON from an in-memory string."""
+        parsed = json.loads(text)  # raises real json.JSONDecodeError if malformed
+        smap = generate_source_map(text)
+        return cls(text, smap, parsed)
+
+    @classmethod
+    def from_file(cls, path: Union[str, Path]) -> "JSONEditor":
+        """Load a JSON file with position tracking.
+
+        Reads bytes and decodes UTF-8 explicitly (R3-5) — never
+        ``Path.read_text()``, whose universal-newline translation would
+        silently convert CRLF to LF before any position is computed.
+        """
+        text = Path(path).read_bytes().decode("utf-8")
+        return cls.from_string(text)
+
+    def get_value(self, path: str) -> Any:
+        """Get the value at a JSON path, from the pristine original parse."""
+        return resolve_path(self.parsed, path)
+
+    def replace(self, path: str, value: Any) -> None:
+        """Record a value replacement (does not apply yet)."""
+        old_value = self.get_value(path)
+        self.operations.append(Replace(path, value))
+        self.modifications.append(Modification("replace", path, old_value, value))
+
+    def remove(self, path: str) -> None:
+        """Record a deletion (does not apply yet).
+
+        Scoped to array-element paths for v1 (ADR-0013 Round 4 §2d) —
+        ``operations.UnsupportedRemovePath`` is raised at ``apply()``/
+        ``save()`` time (when the operation actually compiles), not here,
+        matching the ADR's "record now, compile later" split between
+        ``replace()``/``remove()`` and ``apply()``.
+        """
+        old_value = self.get_value(path)
+        self.operations.append(Remove(path))
+        self.modifications.append(Modification("remove", path, old_value, None))
+
+    # Backwards-compatible aliases matching the ADR's original API.
+    def set_value(self, path: str, value: Any) -> None:
+        """Alias for :meth:`replace`."""
+        self.replace(path, value)
+
+    def delete(self, path: str) -> None:
+        """Alias for :meth:`remove`."""
+        self.remove(path)
+
+    def get_modifications(self) -> List[Modification]:
+        """Return a copy of all recorded modifications."""
+        return self.modifications.copy()
+
+    def _array_close_positions(self) -> Dict[str, int]:
+        """For every array touched by a Remove in this batch, the position
+        of that array's own ``]`` character — ``value_end - 1``, never
+        ``value_end`` directly (the off-by-one Round 4 caught in itself,
+        see ``OPS-2.5.8`` / ``TEST-MATRIX-0013.md``). Keyed by the array's
+        own JSON-pointer path so ``strip_orphaned_trailing_commas`` can look
+        up the right array for each deletion, even when a batch touches more
+        than one array.
+        """
+        close_positions: Dict[str, int] = {}
+        for op in self.operations:
+            if isinstance(op, Remove):
+                parent_path = op.path.rsplit("/", 1)[0]
+                if parent_path not in close_positions and parent_path in self.source_map:
+                    close_positions[parent_path] = self.source_map[parent_path].value_end - 1
+        return close_positions
+
+    def _compile_edits(self):
+        edits = []
+        for op in self.operations:
+            edits.extend(op.compile(self.source_map, self.parsed, self.original_text))
+        edits = coalesce_deletions(edits)
+        edits = strip_orphaned_trailing_commas(
+            self.original_text, edits, self._array_close_positions()
+        )
+        return edits
+
+    def apply(self, validate: bool = False) -> str:
+        """Apply all recorded edits and return the modified text (without
+        saving).
+
+        Args:
+            validate: if True, parse the result to confirm it's valid JSON.
+
+        Raises:
+            json.JSONDecodeError: if ``validate=True`` and the result doesn't parse.
+            validator.SemanticValidationError: if ``validate=True`` and the
+                result parses but fails a semantic post-condition (R3-7c) —
+                e.g. a position bug replaced the wrong value. This is the
+                tripwire ``save()``'s fallback-to-full-rewrite strategy
+                depends on; syntactic validity alone isn't enough to trust a
+                surgical edit.
+            operations.UnsupportedRemovePath: if any recorded ``remove()``
+                targets an object-property path (Round 4 §2d).
+            ValueError: if two edits overlap after coalescing.
+        """
+        edits = self._compile_edits()
+        modified = apply_edits(self.original_text, edits)
+        if validate:
+            json.loads(modified)
+            errors = validate_semantic_postconditions(self.modifications, self.parsed, modified)
+            if errors:
+                raise SemanticValidationError(errors)
+        return modified
+
+    def preview_diff(self) -> str:
+        """Generate a unified diff preview of the pending changes."""
+        modified = self.apply(validate=False)
+        return "".join(
+            difflib.unified_diff(
+                self.original_text.splitlines(keepends=True),
+                modified.splitlines(keepends=True),
+                fromfile="original",
+                tofile="modified",
+            )
+        )
+
+    def save(
+        self,
+        path: Optional[Union[str, Path]] = None,
+        backup_suffix: str = ".backup",
+        audit_log: Optional[Union[str, Path]] = None,
+        validate: bool = True,
+    ) -> dict:
+        """Apply all edits and save the result.
+
+        Args:
+            path: output path (defaults to the path this editor was loaded
+                from, if any).
+            backup_suffix: suffix for the backup file, if ``path`` exists.
+            audit_log: path to write the modification log to.
+            validate: parse the result to confirm it's valid JSON.
+
+        Returns:
+            Dict with ``success``, ``modifications_applied``,
+            ``backup_path``, ``audit_log``.
+        """
+        try:
+            modified_text = self.apply(validate=validate)
+        except Exception as e:  # noqa: BLE001 -- deliberately broad, see "fallback"
+            return {
+                "success": False,
+                "error": f"Failed to apply edits: {e}",
+                "fallback": "full_rewrite",
+            }
+
+        backup_path = None
+        if path is not None and Path(path).exists():
+            backup_path = Path(str(path) + backup_suffix)
+            shutil.copy(path, backup_path)
+
+        if path is not None:
+            # R3-5: write bytes explicitly, never Path.write_text() (which
+            # would re-translate "\n" back to the platform's line ending).
+            Path(path).write_bytes(modified_text.encode("utf-8"))
+
+        if audit_log is not None:
+            log_data = {
+                "timestamp": datetime.now().isoformat(),
+                "modifications": [
+                    {
+                        "operation": m.operation,
+                        "path": m.path,
+                        "old_value": m.old_value,
+                        "new_value": m.new_value,
+                        "timestamp": m.timestamp,
+                    }
+                    for m in self.modifications
+                ],
+                "stats": {
+                    "total_operations": len(self.operations),
+                    "bytes_original": len(self.original_text.encode("utf-8")),
+                    "bytes_modified": len(modified_text.encode("utf-8")),
+                },
+            }
+            Path(audit_log).write_bytes(
+                json.dumps(log_data, indent=2, ensure_ascii=False).encode("utf-8")
+            )
+
+        return {
+            "success": True,
+            "modifications_applied": len(self.modifications),
+            "backup_path": backup_path,
+            "audit_log": audit_log,
+        }

json_source_edit/operations.py

@@ -0,0 +1,204 @@
+"""High-level Operation classes (JSON Patch semantics), compiling to
+low-level Edits.
+
+Two-layer design (ADR-0013's Decision): ``Operation`` subclasses are the
+user-facing API; ``compile()`` turns each into one or more ``algorithm.Edit``
+objects. Only ``Replace`` and ``Remove`` are implemented; ``Add``/``Move``/
+``Copy``/``Test`` are stubbed per the founding brief's scope.
+"""
+import json
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, List
+
+from .algorithm import Edit
+from .source_map import SourceMap
+
+
+def resolve_path(obj: Any, path: str) -> Any:
+    """Resolve a JSON Pointer path against ``obj``."""
+    if path in ("", "/"):
+        return obj
+    parts = path.strip("/").split("/")
+    current = obj
+    for part in parts:
+        current = current[int(part)] if isinstance(current, list) else current[part]
+    return current
+
+
+class UnsupportedRemovePath(NotImplementedError):
+    """Raised when ``Remove`` targets a path that has no well-defined
+    deletion (currently: only the document root — ``""``/``"/"`` has no
+    parent container to update, so there's no comma/whitespace rule that
+    could apply). Everything else — array elements and, as of Mission 3
+    (Round 4 §2d's Deferred-1, closed 2026-07-30), object properties at any
+    depth — is supported.
+    """
+
+
+def calculate_deletion_range(path: str, entry, parsed: Any, original_text: str) -> "tuple[int, int]":
+    """Compute the deletion range for a Remove, for either an array element
+    or an object property.
+
+    Resolves R3-2/R3-3/R3-8 (ADR-0013 Round 4 §2c) as one function: last-
+    element/property detection is parsed-aware and static per-op (never
+    adapts to what else is in the batch — that would reintroduce the
+    batch-aware coupling §2b deliberately avoids); the whitespace-consumption
+    rule always additionally claims the leading newline+indent run. This is
+    the freestanding function ``Remove.compile()``'s phantom 3-arg reference
+    (R3-8) was always missing a body for — it now has one, plus the
+    ``original_text`` parameter that reference didn't even name (needed for
+    the comma/whitespace regex analysis; see the module docstring note on
+    ``Operation.compile()``'s signature).
+
+    Array vs. object is decided from the PARENT'S ACTUAL TYPE in the
+    pristine parse, not the path's shape — a dict with an all-digit string
+    key (``{"3": ...}``, legal JSON) is handled correctly for free, rather
+    than needing a special case (Mission 3; previously this was rejected
+    outright, see git history for the earlier ``_ARRAY_INDEX_PATH``-based
+    dispatch this replaced).
+
+    For an object property, the range starts at the KEY (``entry.key_start``)
+    rather than the value — covering ``"key": value`` as one span — with the
+    exact same forward/backward comma-claim and whitespace-consumption rules
+    array elements use, keyed off "is this the last key in the object"
+    instead of "is this the last index in the array".
+    """
+    parent_path, key_or_index = path.rsplit("/", 1)
+    parent = resolve_path(parsed, parent_path) if parent_path else parsed
+
+    if isinstance(parent, list):
+        is_last = int(key_or_index) == len(parent) - 1
+        start = entry.value_start
+    else:
+        keys = list(parent.keys())
+        is_last = key_or_index == keys[-1]
+        start = entry.key_start
+
+    end = entry.value_end
+    if not is_last:
+        m = re.match(r"^(\s*,)", original_text[end:])
+        if m:
+            end += len(m.group(1))
+    else:
+        m = re.search(r",(\s*)$", original_text[:start])
+        if m:
+            start -= len(m.group(0))
+    m2 = re.search(r"(\r?\n[ \t]*)$", original_text[:start])
+    if m2:
+        start -= len(m2.group(1))
+    return start, end
+
+
+@dataclass
+class Operation(ABC):
+    """Base class for JSON Patch operations."""
+
+    path: str
+
+    @abstractmethod
+    def compile(self, source_map: SourceMap, parsed: Any, original_text: str) -> List[Edit]:
+        """Compile this operation into low-level Edits.
+
+        ``parsed`` is always the pristine, never-mutated parse (ADR-0013
+        Round 4 §1's coordinate-frame contract) — every path here resolves
+        in original-document coordinates, regardless of what else is in the
+        same batch. ``original_text`` is needed by ``Remove`` for the
+        comma/whitespace deletion-range analysis (§2c) — the ADR's original
+        two-arg ``compile(source_map, parsed)`` signature had no way to
+        supply this, which is part of why R3-8's ``calculate_deletion_range``
+        reference was left dangling; Round 4 §2c's corrected function takes
+        it explicitly, so this signature does too.
+        """
+
+
+@dataclass
+class Replace(Operation):
+    """Replace operation (JSON Patch ``replace``)."""
+
+    value: Any
+
+    def compile(self, source_map: SourceMap, parsed: Any, original_text: str) -> List[Edit]:
+        entry = source_map[self.path]
+        replacement = json.dumps(self.value, ensure_ascii=False)  # R3-4
+        return [Edit(start=entry.value_start, end=entry.value_end, replacement=replacement, path=self.path)]
+
+
+@dataclass
+class Remove(Operation):
+    """Remove operation (JSON Patch ``remove``).
+
+    Supports both array elements and object properties, at any depth (as of
+    Mission 3, closing Round 4 §2d's Deferred-1). Only the document root has
+    no defined removal — see ``UnsupportedRemovePath``.
+    """
+
+    def compile(self, source_map: SourceMap, parsed: Any, original_text: str) -> List[Edit]:
+        if self.path in ("", "/"):
+            raise UnsupportedRemovePath(
+                f"Remove on {self.path!r} is not supported: the document root "
+                "has no parent container to update a comma/whitespace rule "
+                "against (see ADR-0013 Round 4 §2d)."
+            )
+
+        parent_path, _ = self.path.rsplit("/", 1)
+        parent = resolve_path(parsed, parent_path) if parent_path else parsed
+        if not isinstance(parent, (list, dict)):
+            raise UnsupportedRemovePath(
+                f"Remove on {self.path!r} is not supported: its parent "
+                f"({parent_path!r}) is not an array or object, so there is no "
+                "container to remove an element or property from "
+                "(see ADR-0013 Round 4 §2d)."
+            )
+
+        entry = source_map[self.path]
+        start, end = calculate_deletion_range(self.path, entry, parsed, original_text)
+        return [Edit(start=start, end=end, replacement="", path=self.path)]
+
+
+@dataclass
+class Add(Operation):
+    """Add operation — not yet implemented."""
+
+    value: Any
+
+    def compile(self, source_map: SourceMap, parsed: Any, original_text: str) -> List[Edit]:
+        raise NotImplementedError("Add operation not yet supported")
+
+
+@dataclass
+class Move(Operation):
+    """Move operation — not yet implemented."""
+
+    from_path: str
+    to_path: str
+
+    def compile(self, source_map: SourceMap, parsed: Any, original_text: str) -> List[Edit]:
+        raise NotImplementedError("Move operation not yet supported")
+
+
+@dataclass
+class Copy(Operation):
+    """Copy operation — not yet implemented."""
+
+    from_path: str
+    to_path: str
+
+    def compile(self, source_map: SourceMap, parsed: Any, original_text: str) -> List[Edit]:
+        raise NotImplementedError("Copy operation not yet supported")
+
+
+@dataclass
+class Test(Operation):
+    """Test operation (JSON Patch ``test``) — not yet implemented.
+
+    Named ``Test`` to match JSON Patch's own vocabulary, not a pytest test
+    class; ``__test__ = False`` tells pytest's collector to leave it alone.
+    """
+
+    __test__ = False
+    value: Any
+
+    def compile(self, source_map: SourceMap, parsed: Any, original_text: str) -> List[Edit]:
+        raise NotImplementedError("Test operation not yet supported")

json_source_edit/source_map.py

@@ -0,0 +1,55 @@
+"""Source-map seam.
+
+The only module in this package that imports the third-party `json_source_map`
+library. Everything else calls `generate()` and works with the `SourceMap`/
+`Entry` types defined here.
+
+Per ADR-0013 Round 4 §4 (Cicerone's ack, condition #3): this is the documented
+swap contract. If Phase 4 ever replaces the pinned PyPI dependency
+(`json-source-map==1.0.5`) with an in-house tokenizer, only this file needs to
+change, and the replacement must keep passing the three non-BMP fixtures in
+`TEST-MATRIX-0013.md` §4.8 (`EDGE-4.8.1`-`EDGE-4.8.3`) unchanged.
+"""
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+import json_source_map as _json_source_map
+
+
+@dataclass(frozen=True)
+class Entry:
+    """Position of one JSON value (and, for object properties, its key) in
+    the original source text.
+
+    All positions are Python code-point offsets (``str`` indices) — never
+    UTF-16 code units. ``value_end``/``key_end`` are exclusive: the character
+    at that index is the first character *after* the value/key.
+    """
+
+    value_start: int
+    value_end: int
+    key_start: Optional[int] = None
+    key_end: Optional[int] = None
+
+
+SourceMap = Dict[str, Entry]
+
+
+def generate(text: str) -> SourceMap:
+    """Compute the source map for a JSON document.
+
+    Assumes ``text`` is valid JSON — callers must parse first (so a malformed
+    document surfaces as ``json.JSONDecodeError`` from that parse, not from
+    here; the underlying library wraps decode errors in its own exception
+    type, which this seam deliberately never exposes).
+    """
+    raw = _json_source_map.calculate(text)
+    return {
+        path: Entry(
+            value_start=entry.value_start.position,
+            value_end=entry.value_end.position,
+            key_start=entry.key_start.position if entry.key_start is not None else None,
+            key_end=entry.key_end.position if entry.key_end is not None else None,
+        )
+        for path, entry in raw.items()
+    }

json_source_edit/validator.py

@@ -0,0 +1,156 @@
+"""Semantic post-condition validation (ADR-0013 R3-7c).
+
+``validate=True`` on ``JSONEditor.apply()``/``save()`` previously only
+confirmed the result *parses* — not that it's semantically correct. A
+position-computation bug can produce syntactically valid JSON that silently
+replaced or removed the wrong thing.
+
+Per Cicerone's Phase 2 resequencing (ADR-0013, `docs/inbox/2026-07-29-0719-cicerone-to-splicer-phase-1-ack-phase-2-go-validator-first.md`):
+this is the tripwire the ADR's fallback-to-full-rewrite strategy depends on,
+and it must exist *before* the CLI integration leans on that fallback in
+production — a semantically wrong but syntactically valid result would
+otherwise sail past the fallback trigger.
+"""
+import copy
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, List, Sequence, Tuple
+
+from .operations import resolve_path
+
+if TYPE_CHECKING:  # avoid a circular import: editor.py imports this module
+    from .editor import Modification
+
+
+@dataclass
+class ValidationError:
+    """One semantic post-condition failure."""
+
+    path: str
+    reason: str
+
+
+class SemanticValidationError(ValueError):
+    """Raised by :func:`validate_semantic_postconditions` (and by
+    ``JSONEditor.apply()``/``save()`` when ``validate=True``) if the result
+    parses but fails a semantic post-condition. A ``ValueError`` subclass so
+    it's caught by ``save()``'s existing broad ``except Exception`` and
+    triggers the fallback-to-full-rewrite path, same as any other apply-time
+    failure.
+    """
+
+    def __init__(self, errors: List[ValidationError]):
+        self.errors = errors
+        detail = "; ".join(f"{e.path}: {e.reason}" for e in errors)
+        super().__init__(f"Semantic validation failed: {detail}")
+
+
+def _build_reference_result(original_parsed: Any, modifications: Sequence["Modification"]) -> Any:
+    """Reconstruct the "obviously correct" result by replaying every
+    modification against a deep copy using plain dict/list mutation — the
+    same kind of manipulation the ADR's rejected "full rewrite" alternative
+    would do. This is the reference the surgical edit's *fresh parse* gets
+    checked against.
+
+    Order matters and is deliberate: **replaces first, in original
+    coordinates** (no removal has shifted anything yet, so every replace
+    path resolves exactly like it would against the untouched original —
+    this is Round 4 §1's coordinate-frame contract, replayed here rather
+    than merely asserted), **then removes**, grouped by parent array and
+    applied in descending index order so an earlier ``pop()`` within the
+    same parent doesn't shift a later one out from under it.
+
+    (By the time this runs, ``apply_edits()`` has already succeeded — same-
+    path conflicts like R3-7(b) raise there, via the overlap check, before
+    this function is ever reached — so it doesn't need to detect them.)
+    """
+    result = copy.deepcopy(original_parsed)
+
+    for mod in modifications:
+        if mod.operation != "replace":
+            continue
+        parent_path, _, key = mod.path.rpartition("/")
+        parent = resolve_path(result, parent_path) if parent_path else result
+        if isinstance(parent, list):
+            parent[int(key)] = copy.deepcopy(mod.new_value)
+        else:
+            parent[key] = copy.deepcopy(mod.new_value)
+
+    removed_keys_by_parent: dict = {}
+    for mod in modifications:
+        if mod.operation != "remove":
+            continue
+        parent_path, _, key_or_index = mod.path.rpartition("/")
+        removed_keys_by_parent.setdefault(parent_path, []).append(key_or_index)
+
+    # Regression: Cicerone's retroactive Phase 2a finding (ADR-0013,
+    # `docs/inbox/2026-07-29-0738-cicerone-to-splicer-phase-2-ack-phase-3-go-and-a-confession.md`).
+    # Iterating removed_keys_by_parent in plain dict-insertion order breaks
+    # when one removal's parent path is itself nested under an element another
+    # removal's parent array also touches -- e.g. remove('/steps/1') recorded
+    # before remove('/steps/2/sub/0'): popping /steps index 1 first shifts
+    # what was originally /steps/2 down to /steps/1, so resolving
+    # "/steps/2/sub" afterward reaches the WRONG element (originally /steps/3's
+    # sub, not /steps/2's). Deepest-parent-first avoids this: any deeper path
+    # is either unrelated to a shallower one (order doesn't matter) or nested
+    # under it (and must be resolved before the shallower pop shifts it).
+    #
+    # Mission 3 (object-property Remove, closing Round 4 S2d's Deferred-1):
+    # a parent can now be a list OR a dict, and the two need different
+    # removal semantics -- list indices must be removed in descending order
+    # (an earlier pop() shifts later indices), but dict keys don't shift each
+    # other at all, so plain deletion in any order is fine.
+    for parent_path, keys_or_indices in sorted(
+        removed_keys_by_parent.items(), key=lambda item: item[0].count("/"), reverse=True
+    ):
+        parent = resolve_path(result, parent_path) if parent_path else result
+        if isinstance(parent, list):
+            for idx in sorted({int(k) for k in keys_or_indices}, reverse=True):
+                parent.pop(idx)
+        else:
+            for key in set(keys_or_indices):
+                del parent[key]
+
+    return result
+
+
+def _diff_paths(expected: Any, actual: Any, path: str = "") -> List[Tuple[str, str]]:
+    """Find JSON-pointer paths where ``expected`` and ``actual`` structurally
+    differ, for diagnostic error messages (not just a whole-structure dump)."""
+    if isinstance(expected, dict) and isinstance(actual, dict):
+        diffs = []
+        for key in sorted(set(expected) | set(actual)):
+            child_path = f"{path}/{key}"
+            if key not in expected:
+                diffs.append((child_path, f"unexpected key (not in the expected result)"))
+            elif key not in actual:
+                diffs.append((child_path, "missing (present in the expected result)"))
+            else:
+                diffs.extend(_diff_paths(expected[key], actual[key], child_path))
+        return diffs
+    if isinstance(expected, list) and isinstance(actual, list):
+        if len(expected) != len(actual):
+            return [(path, f"array length mismatch: expected {len(expected)}, got {len(actual)}")]
+        diffs = []
+        for i, (e, a) in enumerate(zip(expected, actual)):
+            diffs.extend(_diff_paths(e, a, f"{path}/{i}"))
+        return diffs
+    if expected != actual:
+        return [(path, f"expected {expected!r}, got {actual!r}")]
+    return []
+
+
+def validate_semantic_postconditions(
+    modifications: Sequence["Modification"], original_parsed: Any, modified_text: str
+) -> List[ValidationError]:
+    """Check R3-7c's post-conditions: replay every recorded modification
+    against a deep copy of the pristine original (plain dict/list mutation,
+    not the surgical text editor) to build the expected result, then
+    structurally diff it against a *fresh* parse of what the surgical edit
+    actually produced. Any difference is a real semantic bug — most likely a
+    position-computation error — that a syntax-only ``json.loads()`` check
+    would never catch.
+    """
+    fresh_parsed = json.loads(modified_text)
+    expected = _build_reference_result(original_parsed, modifications)
+    return [ValidationError(path, reason) for path, reason in _diff_paths(expected, fresh_parsed)]

json_source_edit-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: json-source-edit
+Version: 0.1.0
+Summary: Surgical, byte-preserving JSON editing — change only what you intend to change.
+Author: Jérémie Lumbroso
+License: MIT
+Project-URL: Homepage, https://github.com/jlumbroso/json-source-edit
+Project-URL: Repository, https://github.com/jlumbroso/json-source-edit
+Project-URL: Provenance, https://github.com/jlumbroso/json-source-edit/blob/main/PROVENANCE.md
+Keywords: json,json-patch,diff,text-editing,format-preserving
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: json-source-map>=1.0.5
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# json-source-edit
+
+A Python package for **surgical, byte-preserving JSON editing.** Change
+only what you intend to change — everything else in the file survives
+byte-for-byte, so your diff shows your edit, not a full-file rewrite.
+
+## The problem
+
+The obvious way to edit a JSON file is parse → modify → serialize:
+
+```python
+data = json.loads(text)
+data["steps"][1]["line"] = 433
+text = json.dumps(data, indent=2)
+```
+
+This is correct, and it destroys your diff. Real evidence, from the project
+this package was extracted out of: three simple changes to one file — two
+field updates and one deletion — were *expected* to produce a ~10-line diff.
+The parse-modify-serialize round-trip produced a **500+ line diff** instead.
+
+That's because `json.dumps` doesn't know or care what your original
+formatting was — indentation, key order, quote style, all of it gets
+re-decided from scratch, every time, whether or not you touched it.
+Multiply that by a codebase-sized JSON file and code review becomes
+impossible: every line looks changed, and the actual edit is buried.
+
+`json-source-edit` fixes this at the source: it never re-serializes the
+document. It computes exact byte positions for each change against the
+*original text* and splices replacement bytes into the gaps — the same
+operation a film or tape splicer performs, cut and rejoin at an exact point,
+everything else on the reel undisturbed.
+
+## Install
+
+Not yet on PyPI (see [Status](#status) below). Until then:
+
+```bash
+git clone https://github.com/jlumbroso/json-source-edit
+cd json-source-edit
+pip install -e .
+```
+
+## Usage
+
+```python
+from json_source_edit import JSONEditor
+
+editor = JSONEditor.from_string("""{
+  "title": "Rust Basics",
+  "steps": [
+    {"file": "src/main.rs", "line": 10},
+    {"file": "src/lib.rs", "line": 20}
+  ]
+}""")
+editor.replace("/steps/0/line", 433)
+editor.remove("/steps/1")
+result = editor.apply(validate=True)
+print(editor.preview_diff())
+```
+
+```diff
+--- original
++++ modified
+@@ -1,7 +1,6 @@
+ {
+   "title": "Rust Basics",
+   "steps": [
+-    {"file": "src/main.rs", "line": 10},
+-    {"file": "src/lib.rs", "line": 20}
++    {"file": "src/main.rs", "line": 433}
+   ]
+ }
+```
+
+`validate=True` catches mistakes before they reach you. It reconstructs the
+expected result independently — replaying your edits against a copy of the
+parsed document — and diffs that against what the surgical edit actually
+produced. If they disagree, it raises `SemanticValidationError` instead of
+silently returning something subtly wrong.
+
+`apply()` defaults to `validate=False`; `save()` defaults to `validate=True`
+— writing to disk is where a mistake actually costs you something, so that
+path checks unless you opt out.
+
+Three more methods help you inspect a pending batch before committing to
+it: `get_value`, `get_modifications`, and `preview_diff`.
+
+## Scope
+
+| JSON Patch operation | Status |
+|---|---|
+| `replace` | Supported — any path, any depth |
+| `remove` | Supported — array elements and object properties, any depth, except the document root itself (structurally undefined: the root has no parent container to apply a comma/whitespace rule against) |
+| `add`, `move`, `copy`, `test` | Not implemented — raise `NotImplementedError` |
+
+Multiple `replace`/`remove` calls batch correctly against the same original
+document — every path resolves in original-document coordinates regardless
+of what else is in the batch, so edit order doesn't matter and one deletion
+can't corrupt another edit's position.
+
+## Benchmark (v0)
+
+Reproduce with `python benchmarks/throughput.py` — a standalone script, no
+test framework required.
+
+Methodology: replaces 5% of a flat array's elements at each size, median of
+5 runs, reporting throughput against the *original* document size (the more
+relevant number for "can this handle my file" than edit count alone).
+
+Single-machine numbers, not a controlled benchmark environment — expect
+real variance run to run and machine to machine; rerun locally before
+relying on any of this for capacity planning.
+
+| Size | Elements | Document | Edits | Median time | Throughput |
+|---|---|---|---|---|---|
+| small | 200 | 0.01MB | 10 | 0.65ms | 15,353 edits/sec, 13.7 MB/sec |
+| medium | 2,000 | 0.09MB | 100 | 6.25ms | 15,990 edits/sec, 14.9 MB/sec |
+| large | 20,000 | 0.97MB | 1000 | 87.22ms | 11,465 edits/sec, 11.1 MB/sec |
+
+(Measured on macOS/arm64, Python 3.12.4, 2026-08-01 — see the script's own
+output for full per-run samples; the "large" row in particular showed
+bimodal timing on this machine, a real observation, not smoothed over.)
+
+## Provenance
+
+This package was designed and hardened inside
+[`codetour-cli`](https://github.com/jlumbroso/codetour-cli), across four
+independent review gates, before being extracted here with no known
+remaining incompleteness. See [`PROVENANCE.md`](PROVENANCE.md) for the
+commit-by-commit history and [`docs/adr/0001-extraction-from-codetour-cli.md`](docs/adr/0001-extraction-from-codetour-cli.md)
+for the extraction decisions themselves (import strategy, the dependency
+verdict, the supported-Python-versions floor).
+
+## Credits
+
+The position-mapping this package edits against — turning a JSON document
+into exact byte offsets for every value and key — is done by
+[`json-source-map`](https://pypi.org/project/json-source-map/), a small,
+dependency-free library by David Andersson. It's the one piece of this
+package that isn't ours: everything in `src/json_source_edit/source_map.py`
+is a thin seam around it, and everything else in this package builds on top
+of what it computes. Elegant, narrowly-scoped libraries like this are what
+make a package like this one feasible to write at all.
+
+## Status
+
+Pre-release. 187 tests, 100% line coverage. Not yet on PyPI — CI is scaffolded
+(GitHub Actions test matrix, Python 3.8–3.13) but the publish workflow is
+deliberately inert pending the repo owner's two-step activation (see
+`.github/workflows/publish.yml`).
+
+## License
+
+MIT.

json_source_edit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+json_source_edit/__init__.py,sha256=F3_1rJmu15FJkfelmzbAmEaxso5w7T1YTibbifQRKN4,516
+json_source_edit/algorithm.py,sha256=RtQXYpXrSh1XOuIRpGR20f9BqMZh_lf5vh-KU7cKTtM,4396
+json_source_edit/editor.py,sha256=pOnFnDxwXzixFJT58jdBGb455U9e9ljhgf7vy5-q77E,9883
+json_source_edit/operations.py,sha256=jh4qvZR4aRF9FkaDI8QVNvmWTCmnSoh0BjLcMN8BWXA,7872
+json_source_edit/source_map.py,sha256=omt7Ux5P8jW-bFgeUck6aRw9S-sC_bdm7psl1g7HU_4,1992
+json_source_edit/validator.py,sha256=YNfjKWH56Allcrv47q0FczhgmOfz00fLfVUsLYCMbp4,7436
+json_source_edit-0.1.0.dist-info/licenses/LICENSE,sha256=wG31d7hCq0RBhofxVSp9vS4KgrfFG0vIGyUcoH-HjUo,1075
+json_source_edit-0.1.0.dist-info/METADATA,sha256=zSf4BYQ1msx2mkdMy96bWCd0xFl1_P8Hs0V_8GuVSSQ,7221
+json_source_edit-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+json_source_edit-0.1.0.dist-info/top_level.txt,sha256=8gzUtf0k5nHst4t-V-3inkUaOmElUL_5vu4dWKcARj0,17
+json_source_edit-0.1.0.dist-info/RECORD,,

json_source_edit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

json_source_edit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jérémie Lumbroso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

json_source_edit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+json_source_edit