json-source-edit 0.1.0__tar.gz

json_source_edit-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,155 @@
+# 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/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "json-source-edit"
+version = "0.1.0"
+description = "Surgical, byte-preserving JSON editing — change only what you intend to change."
+authors = [{name = "Jérémie Lumbroso"}]
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+keywords = ["json", "json-patch", "diff", "text-editing", "format-preserving"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Markup",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "json-source-map>=1.0.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+]
+
+[project.urls]
+Homepage = "https://github.com/jlumbroso/json-source-edit"
+Repository = "https://github.com/jlumbroso/json-source-edit"
+Provenance = "https://github.com/jlumbroso/json-source-edit/blob/main/PROVENANCE.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

json_source_edit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

json_source_edit-0.1.0/src/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-0.1.0/src/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)