diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 8fd3fb0..3feb25b 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "docket", - "version": "0.31.0", + "version": "0.31.1", "description": "A typed ledger of claims, decisions, and questions with scoped context for agents.", "author": { "name": "Aliasgar Khimani", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 2359be8..c8379db 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "docket", - "version": "0.31.0", + "version": "0.31.1", "description": "A typed ledger of claims, decisions, and questions with scoped context for agents.", "author": { "name": "Aliasgar Khimani", diff --git a/CHANGELOG.md b/CHANGELOG.md index 4913fbc..4c84a3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.31.1] - 2026-11-03 + +### Fixed + +- The merge driver no longer renumbers records that are already on the default branch. When `git merge` brings the default branch into a branch that has not reached it, the branch's new ledger records and feature events take the fresh ids and the default branch's keep theirs, so citations of them elsewhere stay correct. With no default branch to find (`origin/HEAD`, `origin/main`, `origin/master`, `main` or `master`), or under `rebase`, `cherry-pick` and octopus merges, the current side still keeps its ids. + ## [0.31.0] - 2026-10-28 ### Added @@ -807,7 +813,8 @@ the breaking-change notes before upgrading. Versions before 0.6.1 carry no git tag. Their history is in the commit log. -[Unreleased]: https://github.com/NovusEdge/docket/compare/v0.31.0...HEAD +[Unreleased]: https://github.com/NovusEdge/docket/compare/v0.31.1...HEAD +[0.31.1]: https://github.com/NovusEdge/docket/compare/v0.31.0...v0.31.1 [0.31.0]: https://github.com/NovusEdge/docket/compare/v0.30.0...v0.31.0 [0.30.0]: https://github.com/NovusEdge/docket/compare/v0.29.0...v0.30.0 [0.29.0]: https://github.com/NovusEdge/docket/compare/v0.28.0...v0.29.0 diff --git a/VERSION b/VERSION index 26bea73..f176c94 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.31.0 +0.31.1 diff --git a/docket/merge_driver.py b/docket/merge_driver.py index 65c42df..6ea6dde 100644 --- a/docket/merge_driver.py +++ b/docket/merge_driver.py @@ -10,6 +10,8 @@ from __future__ import annotations import json +import os +import shutil import subprocess import sys from pathlib import Path @@ -169,6 +171,64 @@ def _behind(ours: Path, theirs: Path, current: int) -> tuple[str, int] | None: return None +_DEFAULT_BRANCHES = ( + "refs/remotes/origin/main", + "refs/remotes/origin/master", + "refs/heads/main", + "refs/heads/master", +) + + +def _git(*args: str) -> subprocess.CompletedProcess[str] | None: + try: + return subprocess.run(["git", *args], capture_output=True, text=True, timeout=30) + except (OSError, subprocess.SubprocessError): + return None + + +def _default_tip() -> str | None: + """The commit the default branch points at, or None when it cannot be told.""" + named = _git("symbolic-ref", "-q", "refs/remotes/origin/HEAD") + candidates = [named.stdout.strip()] if named and named.returncode == 0 else [] + for ref in (*candidates, *_DEFAULT_BRANCHES): + found = _git("rev-parse", "-q", "--verify", f"{ref}^{{commit}}") + if found and found.returncode == 0: + return found.stdout.strip() + return None + + +def _on_default(commit: str, tip: str) -> bool | None: + result = _git("merge-base", "--is-ancestor", commit, tip) + if result is None or result.returncode not in (0, 1): + return None + return result.returncode == 0 + + +def _merged_commit() -> str | None: + """The one commit `git merge` is merging in, or None (rebase, cherry-pick, octopus).""" + # git writes MERGE_HEAD only after the merge machinery, and so the drivers, + # have run; what a driver can see is GITHEAD_=, set by git merge. + shas = [name[len("GITHEAD_") :] for name in os.environ if name.startswith("GITHEAD_")] + return shas[0] if len(shas) == 1 else None + + +def _theirs_is_published() -> bool: + """Whether THEIRS is the side already on the default branch. + + That is a feature branch merging the default branch in: the merged commit + is reachable from the default branch and HEAD is not. Published records + keep their ids, because other branches and documents cite them, so the + driver then renumbers OURS instead. Every other case, including a default + branch that cannot be found, keeps OURS's ids. git runs the driver from the + top of the work tree. + """ + incoming = _merged_commit() + tip = _default_tip() if incoming else None + if incoming is None or tip is None: + return False + return _on_default(incoming, tip) is True and _on_default("HEAD", tip) is False + + def run(base: Path, ours: Path, theirs: Path) -> int: """Merge THEIRS into OURS in place. 0 when merged, 1 when left in conflict or refused.""" @@ -185,16 +245,18 @@ def run(base: Path, ours: Path, theirs: Path) -> int: ) _conflict(base, ours, theirs) return 1 + swap = _theirs_is_published() + first, second = (theirs, ours) if swap else (ours, theirs) try: if holds_features: - mine, incoming = (features.read(p, lock=False) for p in (ours, theirs)) + mine, incoming = (features.read(p, lock=False) for p in (first, second)) # BASE is read raw: it may still be schema 1, and only matching uses it. tail = _feature_tail(_raw(base), mine, incoming) else: # lock=False: the default lock creates .lock next to git's # temp files at the repository root, where nothing ignores it. old = _base_ledger(base) - mine, incoming = (ledger.read(p, lock=False, strict=True) for p in (ours, theirs)) + mine, incoming = (ledger.read(p, lock=False, strict=True) for p in (first, second)) tail, moved = rebase.merge(old, mine, incoming) ledger.validate_entries(mine + tail) except ( @@ -211,6 +273,9 @@ def run(base: Path, ours: Path, theirs: Path) -> int: print(f"docket: cannot merge {ours.name}: {exc}", file=sys.stderr) _conflict(base, ours, theirs) return 1 + if swap: + # git keeps the file at the OURS path, so the published side's bytes go there first. + shutil.copyfile(theirs, ours) if tail: lines = "".join( json.dumps(r, ensure_ascii=False, separators=(",", ":")) + "\n" for r in tail diff --git a/docs/maintenance.md b/docs/maintenance.md index c2b886c..0f6a09c 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -33,7 +33,7 @@ markers, recover the two branch versions before combining their records. ## Combine records from two branches -When both branches add records, they can allocate the same IDs. With the merge driver registered, `git merge`, `git rebase` and `git cherry-pick` handle this themselves: the other side's new records take fresh IDs and their links follow. Nothing else is needed unless git reports a conflict on the ledger. +When both branches add records, they can allocate the same IDs. With the merge driver registered, `git merge`, `git rebase` and `git cherry-pick` handle this themselves: the other side's new records take fresh IDs and their links follow. The exception is a branch that merges the default branch in: records already on the default branch keep their IDs, because other branches and documents cite them, and the branch's own new records take the fresh ones. Nothing else is needed unless git reports a conflict on the ledger. The driver leaves a conflict when both sides superseded the same record, when a cherry-picked record cites one the target lacks, or when a file does not read. A clone without the driver registered also gets an ordinary conflict. Combining the lines by hand does not resolve it; use `docket rebase` to give the incoming records new IDs and update their links. diff --git a/tests/test_merge_driver.py b/tests/test_merge_driver.py index 5427654..d9a9161 100644 --- a/tests/test_merge_driver.py +++ b/tests/test_merge_driver.py @@ -490,3 +490,109 @@ def test_without_the_config_git_reports_a_conflict(self): self.assertNotEqual(self.git("merge", "--no-edit", "topic", check=False).returncode, 0) text = (self.repo / ".docket" / "ledger.jsonl").read_text(encoding="utf-8") self.assertIn("<<<<<<<", text) + + def diverge(self): + """topic records two linked claims; main records one, after the fork.""" + self.git("checkout", "-qb", "topic") + self.record("Topic one", "t1") + self.docket("claim", "Topic two", "--state", "accepted", "--supports", "c2") + self.git("commit", "-qam", "t2") + self.git("checkout", "-q", "main") + self.record("Main claim", "main") + self.git("checkout", "-q", "topic") + + def pairs(self): + return [(r["id"], r["text"]) for r in self.ledger()] + + def test_a_branch_merging_main_in_keeps_main_ids_and_renumbers_its_own(self): + self.diverge() + self.assertEqual(self.git("merge", "-q", "--no-edit", "main").returncode, 0) + self.assertEqual( + self.pairs(), + [("c1", "Shared"), ("c2", "Main claim"), ("c3", "Topic one"), ("c4", "Topic two")], + ) + self.assertEqual(self.ledger()[3]["supports"], [["c3"]]) + self.assertEqual(self.docket("check").returncode, 0) + + def test_main_merging_a_branch_in_still_renumbers_the_branch(self): + self.diverge() + self.git("checkout", "-q", "main") + self.assertEqual(self.git("merge", "-q", "--no-edit", "topic").returncode, 0) + self.assertEqual( + self.pairs(), + [("c1", "Shared"), ("c2", "Main claim"), ("c3", "Topic one"), ("c4", "Topic two")], + ) + self.assertEqual(self.ledger()[3]["supports"], [["c3"]]) + + def test_a_second_merge_of_main_keeps_main_ids_and_moves_the_branch_again(self): + self.diverge() + self.git("merge", "-q", "--no-edit", "main") + self.git("checkout", "-q", "main") + self.record("Main later", "main2") + self.git("checkout", "-q", "topic") + self.assertEqual(self.git("merge", "-q", "--no-edit", "main").returncode, 0) + self.assertEqual( + self.pairs(), + [ + ("c1", "Shared"), + ("c2", "Main claim"), + ("c3", "Main later"), + ("c4", "Topic one"), + ("c5", "Topic two"), + ], + ) + self.assertEqual(self.ledger()[4]["supports"], [["c4"]]) + + def test_the_driver_reports_which_records_moved(self): + self.diverge() + result = self.git("merge", "--no-edit", "main") + self.assertIn("docket: c2 -> c3", result.stderr + result.stdout) + + def test_without_a_default_branch_the_current_side_keeps_its_ids(self): + self.git("branch", "-m", "main", "trunk") + self.git("checkout", "-qb", "topic") + self.record("Topic claim", "topic") + self.git("checkout", "-q", "trunk") + self.record("Trunk claim", "trunk") + self.git("checkout", "-q", "topic") + self.assertEqual(self.git("merge", "-q", "--no-edit", "trunk").returncode, 0) + self.assertEqual(self.texts(), ["Shared", "Topic claim", "Trunk claim"]) + + def use_features(self): + with (self.repo / ".gitattributes").open("a") as f: + f.write(".docket/features.jsonl merge=docket\n") + self.git("commit", "-qam", "attributes") + + def feature_slugs(self): + return [ + (e["id"], e["slug"]) for e in features.read(self.repo / ".docket" / "features.jsonl") + ] + + def diverge_features(self, default="main"): + self.use_features() + self.git("checkout", "-qb", "topic") + self.docket("feature", "start", "work", "--text", "Work", "--path", "src/**") + self.git("add", "-A") + self.git("commit", "-qm", "topic") + self.git("checkout", "-q", default) + self.docket("feature", "start", "other", "--text", "Other", "--path", "lib/**") + self.git("add", "-A") + self.git("commit", "-qm", "main") + + def test_a_branch_merging_main_in_keeps_main_feature_ids(self): + self.diverge_features() + self.git("checkout", "-q", "topic") + self.assertEqual(self.git("merge", "-q", "--no-edit", "main").returncode, 0) + self.assertEqual(self.feature_slugs(), [("f1", "other"), ("f2", "work")]) + + def test_main_merging_a_feature_branch_in_renumbers_the_branch_feature(self): + self.diverge_features() + self.assertEqual(self.git("merge", "-q", "--no-edit", "topic").returncode, 0) + self.assertEqual(self.feature_slugs(), [("f1", "other"), ("f2", "work")]) + + def test_without_a_default_branch_features_keep_the_current_side_ids(self): + self.git("branch", "-m", "main", "trunk") + self.diverge_features("trunk") + self.git("checkout", "-q", "topic") + self.assertEqual(self.git("merge", "-q", "--no-edit", "trunk").returncode, 0) + self.assertEqual(self.feature_slugs(), [("f1", "work"), ("f2", "other")])