kvgit 0.3.5__tar.gz → 0.3.6__tar.gz

{kvgit-0.3.5 → kvgit-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.5
+Version: 0.3.6
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT

{kvgit-0.3.5 → kvgit-0.3.6}/kvgit/__init__.py

@@ -2,6 +2,7 @@
 
 from .content_types import MergeFn, counter, last_writer_wins
 from .errors import ConcurrencyError, MergeConflict
+from .merges import CantMark, TextMergeFn, make_text_merge, text
 from .namespaced import Namespaced
 from .staged import Staged
 from .store import delete_branches, delete_tags, store
@@ -9,6 +10,7 @@ from .versioned.kv import VersionedKV
 from .versioned.protocol import MergeResult, TagInfo, Versioned
 
 __all__ = [
+    "CantMark",
     "ConcurrencyError",
     "MergeConflict",
     "MergeFn",
@@ -16,11 +18,14 @@ __all__ = [
     "Namespaced",
     "Staged",
     "TagInfo",
+    "TextMergeFn",
     "Versioned",
     "VersionedKV",
     "counter",
     "delete_branches",
     "delete_tags",
     "last_writer_wins",
+    "make_text_merge",
     "store",
+    "text",
 ]

kvgit-0.3.6/kvgit/merges.py

@@ -0,0 +1,247 @@
+"""Text merge with conflict markers.
+
+A batteries-included ``BytesMergeFn`` for line-oriented text: disjoint
+changes merge cleanly, overlapping changes come back with git-style
+``<<<<<<<`` markers instead of raising. Register it as a per-key fn or
+as ``default_merge`` wherever text blobs merge (see ``resolve_merge``).
+
+Anything that cannot be marked — undecodable bytes, NUL bytes, inputs
+over the size cap — raises :class:`CantMark`, which the merge machinery
+files as an ordinary conflict. Callers that need to tell "no encoding"
+from "too big" catch it themselves; callers that don't let it flow.
+"""
+
+from __future__ import annotations
+
+import difflib
+from collections.abc import Callable
+
+from .versioned.protocol import BytesMergeFn
+
+#: Inputs whose combined size exceeds this are refused with
+#: :class:`CantMark` rather than merged. Line-diffing is quadratic-ish
+#: in the worst case (minified single-line megabytes); a merge this big
+#: is a whole-file conflict by inspection anyway.
+MAX_MARK_BYTES = 1024 * 1024
+
+
+class CantMark(Exception):
+    """A value cannot be marker-merged: not text, or too big.
+
+    Raised instead of returning bytes when the inputs are undecodable as
+    UTF-8, contain NUL bytes, or exceed ``MAX_MARK_BYTES`` combined.
+    The merge machinery reports it as a conflict for that key.
+    """
+
+
+def _decode(data: bytes | None) -> list[str]:
+    """Split one side into lines; a removed side is the empty list.
+
+    The markers then show one populated side against nothing, which
+    reads correctly.
+    """
+    if data is None:
+        return []
+    if b"\x00" in data:
+        raise CantMark("NUL byte: not text")
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as e:
+        raise CantMark(f"not UTF-8: {e}") from e
+    return text.splitlines(keepends=True)
+
+
+def _changes(base: list[str], side: list[str]) -> list[tuple[int, int, list[str]]]:
+    """Non-equal opcode intervals of ``side`` against ``base``.
+
+    Each tuple is ``(base_start, base_end, replacement_lines)``;
+    pure insertions have ``base_start == base_end``.
+    """
+    matcher = difflib.SequenceMatcher(None, base, side, autojunk=False)
+    return [
+        (i1, i2, side[j1:j2])
+        for tag, i1, i2, j1, j2 in matcher.get_opcodes()
+        if tag != "equal"
+    ]
+
+
+def _terminate(lines: list[str]) -> list[str]:
+    """Ensure every non-final line ends with a newline.
+
+    A line without a trailing newline glued onto following output would
+    corrupt both; clean regions stay byte-exact (a final line keeps its
+    missing newline), markers pay the newline tax.
+    """
+    fixed: list[str] = []
+    for i, ln in enumerate(lines):
+        if not ln.endswith("\n") and i + 1 < len(lines):
+            ln += "\n"
+        fixed.append(ln)
+    return fixed
+
+
+def _replay(base: list[str], start: int, end: int, events: list[tuple]) -> list[str]:
+    """One side's full content over ``base[start:end]``.
+
+    Base lines outside the side's own hunks, replacement lines inside.
+    Same-side events come from one SequenceMatcher pass, so they are
+    disjoint and the replay is well-defined. Without this, overlapping
+    groups spanning different base ranges would emit only replacement
+    lines and silently drop the base lines between them.
+    """
+    out: list[str] = []
+    pos = start
+    for _, s, e, lines in sorted(events, key=lambda ev: (ev[1], ev[2])):
+        out.extend(base[pos:s])
+        out.extend(lines)
+        pos = max(pos, e)
+    out.extend(base[pos:end])
+    return out
+
+
+def _merge_lines(
+    base: list[str],
+    ours: list[str],
+    theirs: list[str],
+    ours_label: str,
+    theirs_label: str,
+    ours_deleted: bool = False,
+    theirs_deleted: bool = False,
+) -> tuple[list[str], bool]:
+    """Three-way line merge. Returns ``(lines, conflicted)``.
+
+    The ``*_deleted`` flags record raw ``None`` inputs (a removed side),
+    tracked separately from decoded emptiness: an empty base file that
+    one side deletes and the other writes is a modify/delete conflict,
+    not a clean add. Still-absent on an added/added merge (base itself
+    missing) is not a deletion.
+    """
+    if ours == theirs:
+        return list(ours), False
+
+    # Whole-file deletion on one side against any change on the other is
+    # a modify/delete conflict with the survivor shown whole — the
+    # interval machinery below only sees hunks and would drop the
+    # surviving context. (Unchanged-vs-deleted resolves above through
+    # the empty-changes fast paths.)
+    if ours_deleted and theirs != base:
+        return _terminate(
+            [
+                f"<<<<<<< {ours_label}\n",
+                "=======\n",
+                *theirs,
+                f">>>>>>> {theirs_label}\n",
+            ]
+        ), True
+    if theirs_deleted and ours != base:
+        return _terminate(
+            [
+                f"<<<<<<< {ours_label}\n",
+                *ours,
+                "=======\n",
+                f">>>>>>> {theirs_label}\n",
+            ]
+        ), True
+
+    our_changes = _changes(base, ours)
+    their_changes = _changes(base, theirs)
+    if not our_changes:
+        return list(theirs), False
+    if not their_changes:
+        return list(ours), False
+
+    # Merge overlapping change intervals into conflict groups; disjoint
+    # intervals resolve independently. Intervals are half-open over base
+    # positions; pure insertions are points. Join on strict overlap, plus
+    # same-point inserts colliding with each other — an insert merely
+    # adjacent to a change interval resolves cleanly beside it, while two
+    # different inserts at one point genuinely conflict.
+    events = [("ours", s, e, lines) for s, e, lines in our_changes]
+    events += [("theirs", s, e, lines) for s, e, lines in their_changes]
+    events.sort(key=lambda ev: (ev[1], ev[2]))
+
+    # Each group tracks its member events plus its max base end, since
+    # overlap is against the group's full span, not the last event.
+    groups: list[list[tuple]] = []
+    group_ends: list[int] = []
+    for ev in events:
+        _, s, e, _ = ev
+        if groups and (
+            s < group_ends[-1]
+            or (s == e and any(g[1] == g[2] == s for g in groups[-1]))
+        ):
+            groups[-1].append(ev)
+            group_ends[-1] = max(group_ends[-1], e)
+        else:
+            groups.append([ev])
+            group_ends.append(e)
+
+    out: list[str] = []
+    conflicted = False
+    pos = 0
+    for group in groups:
+        start = min(ev[1] for ev in group)
+        end = max(ev[2] for ev in group)
+        out.extend(base[pos:start])
+        ours_ev = [ev for ev in group if ev[0] == "ours"]
+        theirs_ev = [ev for ev in group if ev[0] == "theirs"]
+        if not theirs_ev:
+            out.extend(_replay(base, start, end, ours_ev))
+        elif not ours_ev:
+            out.extend(_replay(base, start, end, theirs_ev))
+        else:
+            ours_full = _replay(base, start, end, ours_ev)
+            theirs_full = _replay(base, start, end, theirs_ev)
+            if ours_full == theirs_full:
+                out.extend(ours_full)
+            else:
+                conflicted = True
+                out.append(f"<<<<<<< {ours_label}\n")
+                out.extend(ours_full)
+                out.append("=======\n")
+                out.extend(theirs_full)
+                out.append(f">>>>>>> {theirs_label}\n")
+        pos = end
+    out.extend(base[pos:])
+
+    return _terminate(out), conflicted
+
+
+def make_text_merge(
+    *, ours_label: str = "ours", theirs_label: str = "theirs"
+) -> BytesMergeFn:
+    """Build a marker-merge fn with custom conflict labels.
+
+    Labels ride git's positions (``<<<<<<< <ours>`` /
+    ``>>>>>>> <theirs>``); pass branch names so conflicts read
+    attributably. Labels may not contain newlines.
+    """
+    for name, label in (("ours_label", ours_label), ("theirs_label", theirs_label)):
+        if "\n" in label:
+            raise ValueError(f"{name} may not contain a newline: {label!r}")
+
+    def merge(old: bytes | None, ours: bytes | None, theirs: bytes | None) -> bytes:
+        total = sum(len(d) for d in (old, ours, theirs) if d is not None)
+        if total > MAX_MARK_BYTES:
+            raise CantMark(f"inputs total {total} bytes over cap {MAX_MARK_BYTES}")
+        merged, _ = _merge_lines(
+            _decode(old),
+            _decode(ours),
+            _decode(theirs),
+            ours_label,
+            theirs_label,
+            ours_deleted=ours is None and old is not None,
+            theirs_deleted=theirs is None and old is not None,
+        )
+        return "".join(merged).encode("utf-8")
+
+    return merge
+
+
+def text(old: bytes | None, ours: bytes | None, theirs: bytes | None) -> bytes:
+    """Marker-merge with default labels. Usable as ``default_merge`` directly."""
+    return make_text_merge()(old, ours, theirs)
+
+
+TextMergeFn = Callable[[bytes | None, bytes | None, bytes | None], bytes]
+"""Type of what :func:`make_text_merge` builds (== ``BytesMergeFn``)."""

{kvgit-0.3.5 → kvgit-0.3.6}/kvgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.5
+Version: 0.3.6
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT

{kvgit-0.3.5 → kvgit-0.3.6}/kvgit.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ kvgit/content_types.py
 kvgit/encoding.py
 kvgit/errors.py
 kvgit/hamt.py
+kvgit/merges.py
 kvgit/namespaced.py
 kvgit/py.typed
 kvgit/staged.py
@@ -37,6 +38,7 @@ kvgit/versioned/protocol.py
 tests/test_content_types.py
 tests/test_delete_branches.py
 tests/test_hamt.py
+tests/test_merges.py
 tests/test_namespaced.py
 tests/test_staged.py
 tests/test_store_factory.py

{kvgit-0.3.5 → kvgit-0.3.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kvgit"
-version = "0.3.5"
+version = "0.3.6"
 description = "Versioned key-value store with git-like commit, branch, and merge semantics."
 authors = [{ name = "ashenfad" }]
 requires-python = ">=3.10"

kvgit-0.3.6/tests/test_merges.py

@@ -0,0 +1,300 @@
+"""Tests for kvgit.merges: marker-merge with git-verified expectations."""
+
+import random
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from kvgit import MergeConflict, VersionedKV as Versioned
+from kvgit.kv.memory import Memory
+from kvgit.merges import CantMark, make_text_merge, text
+
+GIT = shutil.which("git")
+needs_git = pytest.mark.skipif(GIT is None, reason="git binary not available")
+
+_ALPHABET = ["alpha", "beta", "gamma", "delta", "epsilon", "zeta", ""]
+
+BASE = b"a\nb\nc\nd\n"
+
+
+class TestCleanMerges:
+    def test_disjoint_edits_merge(self):
+        assert text(BASE, b"a\nB\nc\nd\n", b"a\nb\nc\nD\n") == b"a\nB\nc\nD\n"
+
+    def test_identical_edits_agree(self):
+        assert text(BASE, b"a\nX\nc\nd\n", b"a\nX\nc\nd\n") == b"a\nX\nc\nd\n"
+
+    def test_one_side_unchanged(self):
+        assert text(BASE, BASE, b"a\nb\nc\nD\n") == b"a\nb\nc\nD\n"
+        assert text(BASE, b"a\nB\nc\nd\n", BASE) == b"a\nB\nc\nd\n"
+
+    def test_added_one_side(self):
+        assert text(None, None, b"new\n") == b"new\n"
+        assert text(None, b"new\n", None) == b"new\n"
+
+    def test_both_deleted(self):
+        assert text(BASE, None, None) == b""
+
+    def test_deleted_vs_unchanged_deletes(self):
+        assert text(BASE, None, BASE) == b""
+        assert text(BASE, BASE, None) == b""
+
+    def test_no_trailing_newline_preserved(self):
+        assert text(b"a\nb", b"a\nB", b"a\nb") == b"a\nB"
+
+    def test_empty_inputs(self):
+        assert text(b"", b"", b"") == b""
+
+
+class TestConflicts:
+    def test_overlap_markers(self):
+        out = text(BASE, b"a\nX\nc\nd\n", b"a\nY\nc\nd\n")
+        assert out == b"a\n<<<<<<< ours\nX\n=======\nY\n>>>>>>> theirs\nc\nd\n"
+
+    def test_added_added_different(self):
+        out = text(None, b"hello\n", b"world\n")
+        assert out == b"<<<<<<< ours\nhello\n=======\nworld\n>>>>>>> theirs\n"
+
+    def test_added_added_same(self):
+        assert text(None, b"same\n", b"same\n") == b"same\n"
+
+    def test_delete_vs_modify(self):
+        out = text(BASE, None, b"a\nb\nc\nD\n")
+        assert out == (b"<<<<<<< ours\n=======\na\nb\nc\nD\n>>>>>>> theirs\n")
+
+    def test_modify_vs_delete(self):
+        out = text(BASE, b"a\nB\nc\nd\n", None)
+        assert out == (b"<<<<<<< ours\na\nB\nc\nd\n=======\n>>>>>>> theirs\n")
+
+    def test_custom_labels(self):
+        fn = make_text_merge(ours_label="main", theirs_label="dev")
+        out = fn(BASE, b"a\nX\nc\nd\n", b"a\nY\nc\nd\n")
+        assert b"<<<<<<< main\n" in out
+        assert b">>>>>>> dev\n" in out
+
+    def test_label_newline_rejected(self):
+        with pytest.raises(ValueError):
+            make_text_merge(ours_label="a\nb")
+
+    def test_deterministic(self):
+        args = (BASE, b"a\nX\nc\nd\n", b"a\nY\nc\nd\n")
+        assert text(*args) == text(*args)
+
+
+class TestReviewRegression:
+    """Regression tests for PR #34 review findings (all reproduced)."""
+
+    def test_overlapping_groups_keep_full_span(self):
+        """P1: overlapping hunks over different base spans must show each
+        side's full content over the union — resolving to ours must not
+        drop unchanged lines (here: `c`). Verified byte-identical to
+        `git merge-file`."""
+        out = text(b"a\nb\nc\n", b"a\nB\nc\n", b"a\nY\nZ\n")
+        assert out == b"a\n<<<<<<< ours\nB\nc\n=======\nY\nZ\n>>>>>>> theirs\n"
+
+    def test_empty_base_delete_vs_write_conflicts(self):
+        """P2: an empty base file one side deletes and the other writes
+        is modify/delete, not a clean add."""
+        out = text(b"", None, b"x\n")
+        assert out == b"<<<<<<< ours\n=======\nx\n>>>>>>> theirs\n"
+        out = text(b"", b"x\n", None)
+        assert out == b"<<<<<<< ours\nx\n=======\n>>>>>>> theirs\n"
+
+    def test_unterminated_survivor_terminated(self):
+        """P2: whole-file delete/modify where the survivor lacks a trailing
+        newline must not glue content to the closing marker."""
+        assert text(b"a", None, b"B") == b"<<<<<<< ours\n=======\nB\n>>>>>>> theirs\n"
+        assert text(b"a", b"B", None) == b"<<<<<<< ours\nB\n=======\n>>>>>>> theirs\n"
+
+
+class TestDocumentedDivergence:
+    def test_adjacent_insert_merges_clean(self):
+        """Ours changes line 2, theirs inserts right after it.
+
+        git merge-file reports a conflict here (hunk-context overlap);
+        the regions genuinely don't overlap, so we merge cleanly. Pinned
+        as a known, safe-direction divergence: clean-where-git-conflicts
+        can never silently lose content the way the reverse could.
+        """
+        out = text(BASE, b"a\nB\nc\nd\n", b"a\nb\nX\nc\nd\n")
+        assert out == b"a\nB\nX\nc\nd\n"
+
+
+class TestCantMark:
+    def test_nul_byte(self):
+        with pytest.raises(CantMark):
+            text(BASE, b"a\x00b", BASE)
+
+    def test_invalid_utf8(self):
+        with pytest.raises(CantMark):
+            text(BASE, b"\xff\xfe binary", BASE)
+
+    def test_oversize(self):
+        big = b"x" * (1024 * 1024 + 1)
+        with pytest.raises(CantMark):
+            text(b"", big, b"")
+
+
+def _git_merge(old: bytes, ours: bytes, theirs: bytes) -> tuple[bytes, int]:
+    """Run git merge-file; returns (stdout, exit code)."""
+    assert GIT is not None
+    with tempfile.TemporaryDirectory() as d:
+        paths = []
+        for name, data in (("old", old), ("ours", ours), ("theirs", theirs)):
+            p = Path(d) / name
+            p.write_bytes(data)
+            paths.append(str(p))
+        proc = subprocess.run(
+            [
+                GIT,
+                "merge-file",
+                "-p",
+                "-L",
+                "ours",
+                "-L",
+                "base",
+                "-L",
+                "theirs",
+                paths[1],
+                paths[0],
+                paths[2],
+            ],
+            capture_output=True,
+            env={"LC_ALL": "C", "PATH": "/usr/bin:/bin"},
+        )
+        return proc.stdout, proc.returncode
+
+
+@needs_git
+class TestGitDifferential:
+    """Ours must match git merge-file byte-exactly on agreement-zone inputs.
+
+    The generator keeps edits separated so hunk contexts cannot overlap
+    (the zone where both algorithms provably agree); trickier shapes live
+    as pinned cases above or in the adversarial test below. Seed-pinned:
+    failures reproduce deterministically.
+    """
+
+    def _triple(self, rng: random.Random) -> tuple[bytes, bytes, bytes]:
+        n = rng.randint(2, 8)
+        base = [rng.choice(_ALPHABET) + f"-{i}" for i in range(n)]
+        ours, theirs = list(base), list(base)
+        # Edits at distinct positions with at least one untouched line
+        # between any two edit sites.
+        positions = rng.sample(range(n), k=min(n, rng.randint(0, 3)))
+        positions.sort()
+        ok = True
+        for prev, cur in zip([-10, *positions], positions, strict=False):
+            if prev != -10 and cur - prev < 2:
+                ok = False
+        if not ok:
+            return self._triple(rng)
+        for p in positions:
+            choice = rng.random()
+            if choice < 0.4:
+                ours[p] = f"ours-{p}"
+                theirs[p] = f"ours-{p}"  # identical edit: must agree
+            elif choice < 0.7:
+                ours[p] = f"ours-{p}"
+            else:
+                theirs[p] = f"theirs-{p}"
+
+        def join(lines: list[str]) -> bytes:
+            return ("".join(line + "\n" for line in lines)).encode()
+
+        return join(base), join(ours), join(theirs)
+
+    def test_matches_git(self):
+        rng = random.Random(0xC0FFEE)
+        checked_clean = 0
+        for _ in range(150):
+            old, ours, theirs = self._triple(rng)
+            git_out, code = _git_merge(old, ours, theirs)
+            mine = text(old, ours, theirs)
+            if code == 0:
+                # Clean merges are uniquely determined: byte equality.
+                assert mine == git_out
+                checked_clean += 1
+            else:
+                # Conflict: agreement on conflict-hood.
+                assert b"<<<<<<< ours\n" in mine
+        assert checked_clean > 50  # generator must exercise clean merges
+
+    def test_adversarial_properties(self):
+        """Where we may legitimately diverge from git (adjacent edits,
+        unterminated lines), assert the sound properties instead: clean
+        git merges still match byte-exactly, and our output never
+        invents lines or emits unbalanced markers."""
+        rng = random.Random(0xBEEF)
+        checked_clean = 0
+        for _ in range(150):
+            old, ours, theirs = self._triple(rng)
+            if rng.random() < 0.5:
+                # Strip a trailing newline: the adjacency trigger.
+                if rng.random() < 0.5 and ours.endswith(b"\n"):
+                    ours = ours.removesuffix(b"\n")
+                elif theirs.endswith(b"\n"):
+                    theirs = theirs.removesuffix(b"\n")
+            git_out, code = _git_merge(old, ours, theirs)
+            mine = text(old, ours, theirs)
+            if code == 0:
+                assert mine == git_out
+                checked_clean += 1
+                continue
+            inputs = {
+                ln.removesuffix("\n")
+                for data in (old, ours, theirs)
+                for ln in data.decode("utf-8").splitlines(keepends=True)
+            }
+            opens = closes = mids = 0
+            for ln in mine.decode("utf-8").splitlines(keepends=True):
+                if ln.startswith("<<<<<<< "):
+                    opens += 1
+                elif ln.startswith(">>>>>>> "):
+                    closes += 1
+                elif ln == "=======\n":
+                    mids += 1
+                else:
+                    # No invented content (modulo the terminator): every
+                    # emitted line comes verbatim from some input.
+                    assert ln.removesuffix("\n") in inputs
+            assert opens == mids == closes
+        assert checked_clean > 0  # the net must catch clean merges too
+
+
+class TestVersionedIntegration:
+    def _two_branches(self):
+        store = Memory()
+        v1 = Versioned(store)
+        v1.commit({"doc": b"a\nb\nc\nd\n"})
+        v2 = Versioned(store)
+        return v1, v2
+
+    def test_default_merge_automerges_text(self):
+        from kvgit.merges import text as text_merge
+
+        v1, v2 = self._two_branches()
+        v1.commit({"doc": b"a\nB\nc\nd\n"})
+        result = v2.commit({"doc": b"a\nb\nc\nD\n"}, default_merge=text_merge)
+        assert result
+        assert v2.get("doc") == b"a\nB\nc\nD\n"
+
+    def test_conflict_filed_without_fn(self):
+        v1, v2 = self._two_branches()
+        v1.commit({"doc": b"a\nB\nc\nd\n"})
+        with pytest.raises(MergeConflict) as exc_info:
+            v2.commit({"doc": b"a\nb\nc\nD\n"})
+        assert "doc" in exc_info.value.conflicting_keys
+
+    def test_binary_conflict_carries_cantmark(self):
+        from kvgit.merges import text as text_merge
+
+        v1, v2 = self._two_branches()
+        v1.commit({"doc": b"a\x00b"})
+        with pytest.raises(MergeConflict) as exc_info:
+            v2.commit({"doc": b"a\nb\nc\nD\n"}, default_merge=text_merge)
+        assert "doc" in exc_info.value.conflicting_keys
+        assert isinstance(exc_info.value.merge_errors["doc"], CantMark)