mechanomeld 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e71318030a041eeb04f082e8ce7d096c015e7462e4273d244026331d79e1c2d
-  data.tar.gz: f66fecdc446f07fdea887099626204f446314353ad77b61602902e491cbf9d9d
+  metadata.gz: 17ff6a2f602dc4e7a849a437f26c3d67194da8508f17b093bb8b807b9832ad5e
+  data.tar.gz: 45cb8059e7b6f004f4ae95db489cd203b1d97ba35840ae559a7185c8e493ca5c
 SHA512:
-  metadata.gz: 909d370afa1a826a03f1d7afe2b1fcdc1f639f29d50cb6f50cb532822ae47df2b18d59c7849fb960b5ce05532312ac3a20c809ca3cf0738ab0ff067a4a5571df
-  data.tar.gz: 41686d01f296e39ffb334f94b33a08cd887f201439fd6ce5e907e1f3eb666ec5d14b0576807030e364db49be2bc283d3bd2c36a364709326c9f77d40f2e243ee
+  metadata.gz: 7e7b6c9ad63929ec97f7513fd556d8a8860de99530fd67db5055bc169543dc9ae297a5998c325e9bee3f40a0d20eb4f92310fabf2b072e0c8b4a1723a5e35bbe
+  data.tar.gz: d8a0eb87b94e31175ce1e409e6535a33825bd3789f4c4233706f9eed0e5a34ddefa52813aa1053e00af80f087161f58f30fe2f453f58cc1c4faab957ae54d649

data/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.2] - 2026-09-28
+
+### Added
+
+- Document#diff(from_heads, to_heads = heads) returns Automerge's patches between two versions of a document, as Hashes (9c9bf6d)
+
 ## [0.1.1] - 2026-09-25
 
 ### Added
@@ -19,18 +25,3 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Changed
 
 - releases also publish an x86_64-linux-musl platform gem (159dd59)
-
-## [0.1.0] - 2026-09-17
-
-### 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)

data/README.md

@@ -49,6 +49,31 @@ doc.includes_heads?(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;
@@ -206,6 +206,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 +265,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;
@@ -28,6 +29,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     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("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, includes_heads?, 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)

data/lib/mechanomeld/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mechanomeld
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 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