mechanomeld 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e71318030a041eeb04f082e8ce7d096c015e7462e4273d244026331d79e1c2d
-  data.tar.gz: f66fecdc446f07fdea887099626204f446314353ad77b61602902e491cbf9d9d
+  metadata.gz: 401645183c5b387c8f7ebd914db2d8ff1014c03f86fb65b9d994153510f7482f
+  data.tar.gz: d660d41f97da18bd39e4306e131b4c19d70e809e8da17236f7a4251efa1cf177
 SHA512:
-  metadata.gz: 909d370afa1a826a03f1d7afe2b1fcdc1f639f29d50cb6f50cb532822ae47df2b18d59c7849fb960b5ce05532312ac3a20c809ca3cf0738ab0ff067a4a5571df
-  data.tar.gz: 41686d01f296e39ffb334f94b33a08cd887f201439fd6ce5e907e1f3eb666ec5d14b0576807030e364db49be2bc283d3bd2c36a364709326c9f77d40f2e243ee
+  metadata.gz: 3bb7618d943ad8c284dbc328fe2156599b8a2c39a5a7e218bc2650f076fc16468e7994cab92209c5bfb790e6248969a2616a94967f41ddcdbac03879f54ce9fa
+  data.tar.gz: 65bf168075b5a415b4bd582ab98f474913188106fdba093f5811d1b1d57b94a050dd1a1eff1e542cc566c35c9081da749a11ee3aa05997bdc8ced485fcd40672

data/CHANGELOG.md

@@ -5,32 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [0.1.1] - 2026-09-25
+## [0.1.3] - 2026-10-01
 
 ### Added
 
-- Document#load_incremental applies saved Automerge bytes into an existing document (d60a3eb)
-- Document.load_repo reads a document from automerge-repo's NodeFSStorageAdapter directory (d60a3eb)
-- Document#heads returns the document's change hashes as hex, matching JavaScript's Automerge.getHeads (d60a3eb)
-- Document#includes_heads?(heads) reports whether a document is at or past a set of heads (d60a3eb)
-- Mechanomeld::SyncState, the per-peer sync state, with encode and decode for persistence (eea3a51)
-- Document#generate_sync_message and #receive_sync_message, Automerge's per-document sync protocol (eea3a51)
+- Document#up_to_date_with?(heads), the plain-language name for includes_heads?, which stays as an alias (9c1baa6)
 
-### Changed
-
-- releases also publish an x86_64-linux-musl platform gem (159dd59)
-
-## [0.1.0] - 2026-09-17
+## [0.1.2] - 2026-09-28
 
 ### Added
 
-- Initial release
-- Mechanomeld::Counter, Timestamp, Uint, Bytes, and Text value classes (6df6951)
-- Mechanomeld::Document.load reads documents saved by JavaScript Automerge (c7d31d8)
-- Document#get, #[], and #to_h read values by path (c7d31d8)
-- Document#keys and #length for maps, lists, and text (1d80c0b)
-- Mechanomeld::Document.new(actor_id:) creates an empty document (bccb69c)
-- Document#put, #[]=, #delete, and #save (bccb69c)
-- Document#commit(message:, timestamp:) and #rollback (a8ef491)
-- Document#change commits a block and rolls back if it raises (a8ef491)
-- Mechanomeld::Document.from builds a committed document from a Hash (a8ef491)
+- Document#diff(from_heads, to_heads = heads) returns Automerge's patches between two versions of a document, as Hashes (9c9bf6d)

data/README.md

@@ -40,15 +40,40 @@ doc = Mechanomeld::Document.load_repo("automerge-repo-data", "4NtRZtd6yUtzf8qmEp
 
 ### Heads
 
-`Document#heads` is the document's version: the change hashes JavaScript's `Automerge.getHeads(doc)` returns, as lowercase hex, so the two sides compare with `==`. `Document#includes_heads?(heads)` is true when every hash in `heads` is a change the document already contains, so `heads` is the same version or an older one.
+`Document#heads` is the document's version: the change hashes JavaScript's `Automerge.getHeads(doc)` returns, as lowercase hex, so the two sides compare with `==`. `Document#up_to_date_with?(heads)` is true when the document is at the version `heads` names, or a later one: every hash in `heads` is a change the document already contains. `includes_heads?` is the same method under its older name.
 
 ```ruby
-doc.heads                  # => ["9d434616e7af865757bad75cdebe4151bccf7e29214a71f2a65150846c2a4275"]
-doc.includes_heads?(heads) # => true when the document is at or past `heads`
+doc.heads                   # => ["9d434616e7af865757bad75cdebe4151bccf7e29214a71f2a65150846c2a4275"]
+doc.up_to_date_with?(heads) # => true when the document is at or past `heads`
 ```
 
 Both take hex. automerge-repo's `handle.heads()` returns base58 URL heads, which are not accepted; send `Automerge.getHeads(handle.doc())` from JavaScript instead. A hash that is not 32 bytes of hex raises `Mechanomeld::Error`; a well-formed hash the document does not have is simply not included. Like `save`, both commit any pending change first.
 
+### What changed between two versions
+
+`Document#diff(from_heads, to_heads = doc.heads)` is Automerge's diff: the patches that take the document from one version to another, as Hashes with String keys. Both arguments are hex heads as `Document#heads` returns them; `to_heads` defaults to the current heads, and `[]` as `from_heads` diffs from the empty document.
+
+```ruby
+before = doc.heads
+doc.change { |d| d[["scores", "bravo"]] = 7 }
+doc.diff(before)
+# => [{"action" => "put", "path" => ["scores", "bravo"], "value" => 7, "conflict" => false}]
+```
+
+Every patch has `"action"` and `"path"`. The path addresses the property the patch touches from the root, map keys as Strings and list indexes as Integers, as JavaScript's `Automerge.diff` reports it. The other keys depend on the action:
+
+| action | keys |
+|---|---|
+| `put` | `value`, `conflict` (true when this value won a concurrent write) |
+| `delete` | `index` and `length` when deleting from a list; nothing more for a map key |
+| `insert` | `values`, the elements inserted at `path`'s index, in order |
+| `splice_text` | `value`, the String spliced into a `Text` at `path`'s index |
+| `increment` | `value`, the amount a `Counter` changed by, which may be negative |
+| `conflict` | nothing more: a concurrent write now conflicts at `path` |
+| `mark` | `marks`, each `{"name", "value", "start", "end"}` on a `Text` |
+
+Putting or inserting a map, list, or `Text` yields the empty container (`{}`, `[]`, or `Mechanomeld::Text.new("")`); its contents follow as their own patches. Values use the same Ruby types as `get`. A head that is not hex, or that names a change the document does not contain, raises `Mechanomeld::Error`. Like `save`, `diff` commits any pending change first.
+
 ### Syncing with a peer
 
 `Document#generate_sync_message` and `Document#receive_sync_message` run Automerge's per-document sync protocol, so a Ruby document can exchange just the changes each side lacks with another Automerge peer: JavaScript's `Automerge.generateSyncMessage` / `receiveSyncMessage`, or another Ruby document. A `Mechanomeld::SyncState` tracks what one peer is known to have; keep one per peer for each document.

data/ext/mechanomeld/src/diff.rs

@@ -0,0 +1,100 @@
+//! Converting automerge patches into Ruby hashes.
+//!
+//! Every patch becomes `{"action" => ..., "path" => [...]}` plus the fields that
+//! action carries. `path` addresses the property the patch touches from the root, as
+//! JavaScript's `Automerge.diff` reports it. A put or insert of a map, list, or text
+//! carries the empty container; the children arrive as their own patches.
+
+use automerge::{marks::Mark, ObjType, Patch, PatchAction, Prop, Value as AmValue};
+use magnus::{prelude::*, Error, RHash, Ruby, Value};
+
+use crate::classes::TEXT;
+use crate::errors::error;
+use crate::read;
+
+pub fn patch(ruby: &Ruby, patch: &Patch) -> Result<RHash, Error> {
+    let (action, last) = match &patch.action {
+        PatchAction::PutMap { key, .. } => ("put", Some(Prop::Map(key.clone()))),
+        PatchAction::PutSeq { index, .. } => ("put", Some(Prop::Seq(*index))),
+        PatchAction::Insert { index, .. } => ("insert", Some(Prop::Seq(*index))),
+        PatchAction::SpliceText { index, .. } => ("splice_text", Some(Prop::Seq(*index))),
+        PatchAction::Increment { prop, .. } => ("increment", Some(prop.clone())),
+        PatchAction::Conflict { prop } => ("conflict", Some(prop.clone())),
+        PatchAction::DeleteMap { key } => ("delete", Some(Prop::Map(key.clone()))),
+        PatchAction::DeleteSeq { index, .. } => ("delete", Some(Prop::Seq(*index))),
+        PatchAction::Mark { .. } => ("mark", None),
+    };
+    let path = ruby.ary_new_capa(patch.path.len() + 1);
+    for (_, prop) in &patch.path {
+        path.push(prop_value(ruby, prop))?;
+    }
+    if let Some(prop) = &last {
+        path.push(prop_value(ruby, prop))?;
+    }
+    let hash = ruby.hash_new();
+    hash.aset("action", action)?;
+    hash.aset("path", path)?;
+    match &patch.action {
+        PatchAction::PutMap {
+            value, conflict, ..
+        }
+        | PatchAction::PutSeq {
+            value, conflict, ..
+        } => {
+            hash.aset("value", self::value(ruby, &value.0)?)?;
+            hash.aset("conflict", *conflict)?;
+        }
+        PatchAction::Insert { values, .. } => {
+            let array = ruby.ary_new_capa(values.len());
+            for (item, _, _) in values.iter() {
+                array.push(self::value(ruby, item)?)?;
+            }
+            hash.aset("values", array)?;
+        }
+        PatchAction::SpliceText { value, .. } => {
+            hash.aset("value", ruby.str_new(&value.make_string()))?;
+        }
+        PatchAction::Increment { value, .. } => {
+            hash.aset("value", *value)?;
+        }
+        PatchAction::DeleteSeq { index, length } => {
+            hash.aset("index", *index)?;
+            hash.aset("length", *length)?;
+        }
+        PatchAction::Mark { marks } => {
+            let array = ruby.ary_new_capa(marks.len());
+            for mark in marks {
+                array.push(self::mark(ruby, mark)?)?;
+            }
+            hash.aset("marks", array)?;
+        }
+        PatchAction::Conflict { .. } | PatchAction::DeleteMap { .. } => {}
+    }
+    Ok(hash)
+}
+
+fn prop_value(ruby: &Ruby, prop: &Prop) -> Value {
+    match prop {
+        Prop::Map(key) => ruby.str_new(key).as_value(),
+        Prop::Seq(index) => ruby.integer_from_u64(*index as u64).as_value(),
+    }
+}
+
+fn value(ruby: &Ruby, value: &AmValue<'_>) -> Result<Value, Error> {
+    match value {
+        AmValue::Scalar(scalar) => read::scalar(ruby, scalar),
+        AmValue::Object(ObjType::Map) => Ok(ruby.hash_new().as_value()),
+        AmValue::Object(ObjType::List) => Ok(ruby.ary_new().as_value()),
+        AmValue::Object(ObjType::Text) => read::wrap(ruby, &TEXT, ruby.str_new("")),
+        AmValue::Object(ObjType::Table) => Err(error(ruby, "Automerge tables are not supported")),
+    }
+}
+
+fn mark(ruby: &Ruby, mark: &Mark) -> Result<RHash, Error> {
+    let hash = ruby.hash_new();
+    hash.aset("name", mark.name.as_str())?;
+    hash.aset("value", read::scalar(ruby, &mark.value)?)?;
+    hash.aset("start", mark.start)?;
+    hash.aset("end", mark.end)?;
+    Ok(hash)
+}

data/ext/mechanomeld/src/document.rs

@@ -15,7 +15,7 @@ use magnus::{
 
 use crate::errors::{arg_error, automerge_error, error};
 use crate::sync_state::SyncState;
-use crate::{path, read, write};
+use crate::{diff, path, read, write};
 
 /// Text indexes count Unicode code points, matching Ruby's `String#length`.
 const ENCODING: TextEncoding = TextEncoding::UnicodeCodePoint;
@@ -193,9 +193,10 @@ impl Document {
         Ok(ruby.ary_from_iter(heads.iter().map(ChangeHash::to_string)))
     }
 
-    /// `doc.includes_heads?(heads)`: whether every hex change hash in `heads` is a
-    /// change this document already contains.
-    pub fn includes_heads(ruby: &Ruby, rb_self: &Self, heads: Vec<String>) -> Result<bool, Error> {
+    /// `doc.up_to_date_with?(heads)`: whether this document is at the version `heads`
+    /// names, or a later one: every hex change hash in `heads` is a change it already
+    /// contains. Ruby also exposes it as `includes_heads?`.
+    pub fn up_to_date_with(ruby: &Ruby, rb_self: &Self, heads: Vec<String>) -> Result<bool, Error> {
         let hashes = heads
             .iter()
             .map(|hex| change_hash(ruby, hex))
@@ -206,6 +207,26 @@ impl Document {
             .all(|hash| doc.get_change_meta_by_hash(hash).is_some()))
     }
 
+    /// `doc.diff(from_heads, to_heads = heads)`: the patches that take the document from
+    /// `from_heads` to `to_heads`, as Hashes (see diff.rs for their shape). `[]` as
+    /// `from_heads` diffs from the empty document. Every head must be a change this
+    /// document contains.
+    pub fn diff(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<RArray, Error> {
+        let args = scan_args::<(Vec<String>,), (Option<Vec<String>>,), (), (), (), ()>(args)?;
+        let mut doc = rb_self.doc_mut(ruby)?;
+        let from = known_heads(ruby, &mut doc, &args.required.0)?;
+        let to = match args.optional.0 {
+            Some(heads) => known_heads(ruby, &mut doc, &heads)?,
+            None => doc.get_heads(),
+        };
+        let patches = doc.diff(&from, &to);
+        let array = ruby.ary_new_capa(patches.len());
+        for patch in &patches {
+            array.push(diff::patch(ruby, patch)?)?;
+        }
+        Ok(array)
+    }
+
     /// `doc.generate_sync_message(sync_state)`: the next binary message for the peer
     /// `sync_state` tracks, or nil when there is nothing to send.
     pub fn generate_sync_message(
@@ -245,6 +266,24 @@ fn change_hash(ruby: &Ruby, hex: &str) -> Result<ChangeHash, Error> {
     ChangeHash::from_str(hex).map_err(|e| error(ruby, format!("invalid change hash {hex:?}: {e}")))
 }
 
+/// Parses hex change hashes, rejecting any change `doc` does not contain.
+fn known_heads(
+    ruby: &Ruby,
+    doc: &mut AutoCommit,
+    heads: &[String],
+) -> Result<Vec<ChangeHash>, Error> {
+    heads
+        .iter()
+        .map(|hex| {
+            let hash = change_hash(ruby, hex)?;
+            if doc.get_change_meta_by_hash(&hash).is_none() {
+                return Err(error(ruby, format!("unknown change hash {hex:?}")));
+            }
+            Ok(hash)
+        })
+        .collect()
+}
+
 fn optional_path(ruby: &Ruby, args: &[Value]) -> Result<Vec<Value>, Error> {
     let args = scan_args::<(), (Option<Value>,), (), (), (), ()>(args)?;
     path::segments(args.optional.0.unwrap_or_else(|| ruby.qnil().as_value()))

data/ext/mechanomeld/src/lib.rs

@@ -1,4 +1,5 @@
 mod classes;
+mod diff;
 mod document;
 mod errors;
 mod path;
@@ -27,7 +28,8 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     class.define_method("rollback", method!(Document::rollback, 0))?;
     class.define_method("save", method!(Document::save, 0))?;
     class.define_method("heads", method!(Document::heads, 0))?;
-    class.define_method("includes_heads?", method!(Document::includes_heads, 1))?;
+    class.define_method("up_to_date_with?", method!(Document::up_to_date_with, 1))?;
+    class.define_method("diff", method!(Document::diff, -1))?;
     class.define_method(
         "generate_sync_message",
         method!(Document::generate_sync_message, 1),

data/ext/mechanomeld/src/read.rs

@@ -72,7 +72,11 @@ pub fn scalar(ruby: &Ruby, scalar: &ScalarValue) -> Result<Value, Error> {
 }
 
 /// Builds a scalar wrapper by allocating it and setting `@value`, without running Ruby code.
-fn wrap(ruby: &Ruby, class: &'static Lazy<RClass>, value: impl IntoValue) -> Result<Value, Error> {
+pub fn wrap(
+    ruby: &Ruby,
+    class: &'static Lazy<RClass>,
+    value: impl IntoValue,
+) -> Result<Value, Error> {
     let instance = ruby.get_inner(class).obj_alloc()?;
     let object = RObject::try_convert(instance.as_value())?;
     object.ivar_set("@value", value)?;

data/lib/mechanomeld/document.rb

@@ -2,8 +2,8 @@
 
 module Mechanomeld
   # Native methods (new, load, load_incremental, get, keys, length, put, delete, commit,
-  # rollback, save, heads, includes_heads?, generate_sync_message, receive_sync_message)
-  # are defined in ext/mechanomeld/src/document.rs.
+  # rollback, save, heads, up_to_date_with?, diff, generate_sync_message,
+  # receive_sync_message) are defined in ext/mechanomeld/src/document.rs.
   class Document
     def self.from(hash, actor_id: nil)
       raise ArgumentError, "Automerge document root must be a Hash" unless hash.is_a?(Hash)
@@ -40,6 +40,8 @@ module Mechanomeld
     end
     alias_method :to_hash, :to_h
 
+    alias_method :includes_heads?, :up_to_date_with?
+
     def change(message: nil, timestamp: nil)
       yield self
       commit(message: message, timestamp: timestamp)

data/lib/mechanomeld/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mechanomeld
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mechanomeld
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Jim Gay
@@ -41,6 +41,7 @@ files:
 - ext/mechanomeld/Cargo.toml
 - ext/mechanomeld/extconf.rb
 - ext/mechanomeld/src/classes.rs
+- ext/mechanomeld/src/diff.rs
 - ext/mechanomeld/src/document.rs
 - ext/mechanomeld/src/errors.rs
 - ext/mechanomeld/src/lib.rs