philiprehberger-differ 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f3a7ba9a12fd481dc78033e4038612fd500b186ae2c908112e22b792d6f954c
-  data.tar.gz: 42758eac8c39f509de50f40f06d21b7d283c8e9c74c7eec8e0ae68b49cdc700a
+  metadata.gz: be3438fd21e7f26548ccf9052163ac43a8a41231f95e772830d1311f4d9fbd9b
+  data.tar.gz: c8bb69a3e019c8ea86204a09011070bb813ef03491f7f5bb95e3a381909687b5
 SHA512:
-  metadata.gz: a37315aa385705c3d8caa99774a13fe7ff65b3b53b1ce42616b804bdedac229788893bc5dbcfd514522cf35ed03392b3c513771e50b67bc23c215e3efb004130
-  data.tar.gz: b49707780c6cbb629a65641cd40fdf7e80e8fa2bbeedd08b9a75556f16ce9749460123e82169ea2d20fc1ca67e43e925695f731bc60fa9afd671e8db594e9fce
+  metadata.gz: '074148fad05b65128d63112b61383e9589f35560e8a3cb990b9689e432e68380b4f52a56052c31468763c88c130624ec1583fb984a4d14320c87eb56a8afdfe8'
+  data.tar.gz: e2972dff73dc4dc4f2f3270e0537ce049885b7e003a793136fce6cb4ae6fa2c07ff0740f2bef7bbb4d5b9e3634b5baf6abb25a06edd8586e286c1f9f429b71da

data/CHANGELOG.md

@@ -1,16 +1,25 @@
 # Changelog
 
-## 0.1.2
-
-- Add License badge to README
-- Add bug_tracker_uri to gemspec
-- Add Requirements section to README
-
 All notable changes to this gem will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-03-17
+
+### Added
+- Ignore paths with symbol support: `Differ.diff(a, b, ignore: [:updated_at, "user.email"])`
+- Similarity score: `Differ.similarity(a, b)` returns Float between 0.0 and 1.0
+- Text formatter: `changeset.to_text` for human-readable +/- output
+- JSON Patch formatter: `changeset.to_json_patch` for RFC 6902 operations
+- Nested array diff by key: `Differ.diff(a, b, array_key: :id)` matches elements by field
+
+## [0.1.2]
+
+- Add License badge to README
+- Add bug_tracker_uri to gemspec
+- Add Requirements section to README
+
 ## [Unreleased]
 
 ## [0.1.0] - 2026-03-15

data/README.md

@@ -44,17 +44,87 @@ result = changeset.apply(old_data)
 
 # Revert changes to produce old version from new
 original = changeset.revert(new_data)
+```
+
+### Ignore Paths
+
+Exclude specific keys from comparison. Supports both symbols and dot-notation strings for nested paths:
+
+```ruby
+changeset = Philiprehberger::Differ.diff(old_data, new_data, ignore: [:updated_at, :metadata])
 
-# Ignore specific paths
-changeset = Philiprehberger::Differ.diff(old_data, new_data, ignore: ['age'])
+# Ignore nested paths
+changeset = Philiprehberger::Differ.diff(old_data, new_data, ignore: ['user.email', 'meta.version'])
+```
+
+### Similarity Score
+
+Get a ratio of unchanged fields to total fields, returned as a Float between 0.0 and 1.0:
+
+```ruby
+score = Philiprehberger::Differ.similarity(old_data, new_data)
+# => 0.5  (half the fields are identical)
+
+score = Philiprehberger::Differ.similarity(old_data, old_data)
+# => 1.0  (identical)
+```
+
+### Text Formatter
+
+Human-readable text output with +/- prefixes:
+
+```ruby
+changeset = Philiprehberger::Differ.diff(
+  { name: 'Alice', age: 30 },
+  { name: 'Bob', email: 'bob@example.com' }
+)
+
+puts changeset.to_text
+# ~ name: "Alice" -> "Bob"
+# - age: 30
+# + email: "bob@example.com"
+```
+
+### JSON Patch Format
+
+Returns an array of RFC 6902 JSON Patch operations:
+
+```ruby
+changeset = Philiprehberger::Differ.diff(
+  { name: 'Alice', age: 30 },
+  { name: 'Bob' }
+)
+
+changeset.to_json_patch
+# => [
+#   { op: "replace", path: "/name", value: "Bob" },
+#   { op: "remove", path: "/age" }
+# ]
+```
+
+### Nested Array Diff by Key
+
+Match array elements by a key field instead of index for smarter array comparison:
+
+```ruby
+old_data = { users: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }] }
+new_data = { users: [{ id: 2, name: 'Bobby' }, { id: 1, name: 'Alice' }] }
+
+# Without array_key: detects changes at every index (order-sensitive)
+# With array_key: matches by :id, only detects Bob -> Bobby change
+changeset = Philiprehberger::Differ.diff(old_data, new_data, array_key: :id)
 ```
 
 ## API
 
-### `Philiprehberger::Differ.diff(old_val, new_val, ignore: [])`
+### `Philiprehberger::Differ.diff(old_val, new_val, ignore: [], array_key: nil)`
 
 Returns a `Changeset` representing all structural differences.
 
+### `Philiprehberger::Differ.similarity(old_val, new_val, ignore: [], array_key: nil)`
+
+Returns a Float between 0.0 (completely different) and 1.0 (identical).
+
 ### `Changeset`
 
 | Method | Description |
@@ -67,6 +137,8 @@ Returns a `Changeset` representing all structural differences.
 | `apply(hash)` | Applies changes to produce the new version |
 | `revert(hash)` | Reverts changes to produce the old version |
 | `to_h` | Serializable hash representation |
+| `to_text` | Human-readable text with +/- prefixes |
+| `to_json_patch` | Array of RFC 6902 JSON Patch operations |
 
 ### `Change`
 

data/lib/philiprehberger/differ/changeset.rb

@@ -41,6 +41,14 @@ module Philiprehberger
         { changes: @changes.map(&:to_h) }
       end
 
+      def to_text
+        Formatters::Text.format(self)
+      end
+
+      def to_json_patch
+        Formatters::JsonPatch.format(self)
+      end
+
       private
 
       def apply_change(hash, change)

data/lib/philiprehberger/differ/comparator.rb

@@ -3,51 +3,88 @@
 module Philiprehberger
   module Differ
     class Comparator
-      def self.call(old_val, new_val, path: '', ignore: [])
-        return [] if ignore.include?(path)
+      def self.call(old_val, new_val, path: '', ignore: [], array_key: nil)
+        return [] if ignored?(path, ignore)
 
+        opts = { ignore: ignore, array_key: array_key }
         case [old_val, new_val]
-        in [Hash, Hash] then compare_hashes(old_val, new_val, path, ignore)
-        in [Array, Array] then compare_arrays(old_val, new_val, path, ignore)
+        in [Hash, Hash] then compare_hashes(old_val, new_val, path, opts)
+        in [Array, Array] then compare_arrays(old_val, new_val, path, opts)
         else compare_scalars(old_val, new_val, path)
         end
       end
 
-      def self.compare_hashes(old_hash, new_hash, path, ignore)
+      def self.ignored?(path, ignore)
+        ignore.any? { |p| p.to_s == path }
+      end
+
+      def self.compare_hashes(old_hash, new_hash, path, opts)
         (old_hash.keys + new_hash.keys).uniq.each_with_object([]) do |key, changes|
           full_path = path.empty? ? key.to_s : "#{path}.#{key}"
-          next if ignore.include?(full_path)
+          next if ignored?(full_path, opts[:ignore])
 
-          changes.concat(hash_key_diff(old_hash, new_hash, key, full_path, ignore))
+          changes.concat(hash_key_diff(old_hash, new_hash, key, full_path, opts))
         end
       end
 
-      def self.hash_key_diff(old_hash, new_hash, key, full_path, ignore)
+      def self.hash_key_diff(old_hash, new_hash, key, full_path, opts)
         if !old_hash.key?(key)
           [Change.new(path: full_path, type: :added, new_value: new_hash[key])]
         elsif !new_hash.key?(key)
           [Change.new(path: full_path, type: :removed, old_value: old_hash[key])]
         else
-          call(old_hash[key], new_hash[key], path: full_path, ignore: ignore)
+          call(old_hash[key], new_hash[key], path: full_path, **opts)
+        end
+      end
+
+      def self.compare_arrays(old_arr, new_arr, path, opts)
+        if opts[:array_key] && old_arr.first.is_a?(Hash)
+          compare_arrays_by_key(old_arr, new_arr, path, opts)
+        else
+          compare_arrays_by_index(old_arr, new_arr, path, opts)
         end
       end
 
-      def self.compare_arrays(old_arr, new_arr, path, ignore)
+      def self.compare_arrays_by_index(old_arr, new_arr, path, opts)
         [old_arr.length, new_arr.length].max.times.each_with_object([]) do |idx, changes|
           full_path = "#{path}.#{idx}"
-          next if ignore.include?(full_path)
+          next if ignored?(full_path, opts[:ignore])
 
-          changes.concat(array_idx_diff(old_arr, new_arr, idx, full_path, ignore))
+          changes.concat(array_idx_diff(old_arr, new_arr, idx, full_path, opts))
         end
       end
 
-      def self.array_idx_diff(old_arr, new_arr, idx, full_path, ignore)
+      def self.array_idx_diff(old_arr, new_arr, idx, full_path, opts)
         if idx >= old_arr.length
           [Change.new(path: full_path, type: :added, new_value: new_arr[idx])]
         elsif idx >= new_arr.length
           [Change.new(path: full_path, type: :removed, old_value: old_arr[idx])]
         else
-          call(old_arr[idx], new_arr[idx], path: full_path, ignore: ignore)
+          call(old_arr[idx], new_arr[idx], path: full_path, **opts)
+        end
+      end
+
+      def self.compare_arrays_by_key(old_arr, new_arr, path, opts)
+        old_map = index_by_key(old_arr, opts[:array_key])
+        new_map = index_by_key(new_arr, opts[:array_key])
+        all_keys = (old_map.keys + new_map.keys).uniq
+        all_keys.each_with_object([]) do |key_val, changes|
+          changes.concat(keyed_element_diff(old_map, new_map, key_val, path, opts))
+        end
+      end
+
+      def self.index_by_key(arr, key)
+        arr.to_h { |item| [item[key], item] }
+      end
+
+      def self.keyed_element_diff(old_map, new_map, key_val, path, opts)
+        full_path = "#{path}.#{key_val}"
+        if !old_map.key?(key_val)
+          [Change.new(path: full_path, type: :added, new_value: new_map[key_val])]
+        elsif !new_map.key?(key_val)
+          [Change.new(path: full_path, type: :removed, old_value: old_map[key_val])]
+        else
+          call(old_map[key_val], new_map[key_val], path: full_path, **opts)
         end
       end
 
@@ -58,7 +95,9 @@ module Philiprehberger
       end
 
       private_class_method :compare_hashes, :compare_arrays, :compare_scalars,
-                           :hash_key_diff, :array_idx_diff
+                           :hash_key_diff, :array_idx_diff, :ignored?,
+                           :compare_arrays_by_index, :compare_arrays_by_key,
+                           :index_by_key, :keyed_element_diff
     end
   end
 end

data/lib/philiprehberger/differ/formatters.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Philiprehberger
+  module Differ
+    module Formatters
+      module Text
+        def self.format(changeset)
+          changeset.changes.map { |c| format_change(c) }.join("\n")
+        end
+
+        def self.format_change(change)
+          case change.type
+          when :added   then "+ #{change.path}: #{change.new_value.inspect}"
+          when :removed then "- #{change.path}: #{change.old_value.inspect}"
+          when :changed then changed_line(change)
+          end
+        end
+
+        def self.changed_line(change)
+          "~ #{change.path}: #{change.old_value.inspect} -> #{change.new_value.inspect}"
+        end
+
+        private_class_method :format_change, :changed_line
+      end
+
+      module JsonPatch
+        def self.format(changeset)
+          changeset.changes.map { |c| format_op(c) }
+        end
+
+        def self.format_op(change)
+          path = "/#{change.path.gsub('.', '/')}"
+          case change.type
+          when :added   then { op: 'add', path: path, value: change.new_value }
+          when :removed then { op: 'remove', path: path }
+          when :changed then { op: 'replace', path: path, value: change.new_value }
+          end
+        end
+
+        private_class_method :format_op
+      end
+    end
+  end
+end

data/lib/philiprehberger/differ/similarity.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module Differ
+    module Similarity
+      def self.call(old_val, new_val, ignore: [], array_key: nil)
+        total = count_fields(old_val, new_val, ignore: ignore, array_key: array_key)
+        return 1.0 if total.zero?
+
+        changes = Comparator.call(old_val, new_val, ignore: ignore, array_key: array_key)
+        changed = changes.length
+        (total - changed).to_f / total
+      end
+
+      def self.count_fields(old_val, new_val, ignore: [], array_key: nil, path: '')
+        case [old_val, new_val]
+        in [Hash, Hash] then count_hash_fields(old_val, new_val, ignore, array_key, path)
+        in [Array, Array] then count_array_fields(old_val, new_val, ignore, array_key, path)
+        else 1
+        end
+      end
+
+      def self.count_hash_fields(old_hash, new_hash, ignore, array_key, path)
+        opts = { ignore: ignore, array_key: array_key }
+        (old_hash.keys + new_hash.keys).uniq.sum do |key|
+          full_path = path.empty? ? key.to_s : "#{path}.#{key}"
+          next 0 if ignore.any? { |p| p.to_s == full_path }
+
+          count_hash_key(old_hash, new_hash, key, full_path, opts)
+        end
+      end
+
+      def self.count_hash_key(old_hash, new_hash, key, full_path, opts)
+        if old_hash.key?(key) && new_hash.key?(key)
+          count_fields(old_hash[key], new_hash[key],
+                       ignore: opts[:ignore], array_key: opts[:array_key], path: full_path)
+        else
+          1
+        end
+      end
+
+      def self.count_array_fields(old_arr, new_arr, ignore, array_key, path)
+        if array_key && old_arr.first.is_a?(Hash)
+          count_keyed_array(old_arr, new_arr, ignore, array_key, path)
+        else
+          count_indexed_array(old_arr, new_arr, ignore, array_key, path)
+        end
+      end
+
+      def self.count_indexed_array(old_arr, new_arr, ignore, array_key, path)
+        [old_arr.length, new_arr.length].max.times.sum do |idx|
+          full_path = "#{path}.#{idx}"
+          next 0 if ignore.any? { |p| p.to_s == full_path }
+          next 1 if idx >= old_arr.length || idx >= new_arr.length
+
+          count_fields(old_arr[idx], new_arr[idx], ignore: ignore, array_key: array_key, path: full_path)
+        end
+      end
+
+      def self.count_keyed_array(old_arr, new_arr, ignore, array_key, path)
+        old_map = old_arr.to_h { |item| [item[array_key], item] }
+        new_map = new_arr.to_h { |item| [item[array_key], item] }
+        count_keyed_array_fields(old_map, new_map, ignore, array_key, path)
+      end
+
+      def self.count_keyed_array_fields(old_map, new_map, ignore, array_key, path)
+        (old_map.keys + new_map.keys).uniq.sum do |key_val|
+          full_path = "#{path}.#{key_val}"
+          next 1 unless old_map.key?(key_val) && new_map.key?(key_val)
+
+          count_fields(old_map[key_val], new_map[key_val], ignore: ignore, array_key: array_key, path: full_path)
+        end
+      end
+
+      private_class_method :count_fields, :count_hash_fields, :count_hash_key,
+                           :count_array_fields, :count_indexed_array, :count_keyed_array,
+                           :count_keyed_array_fields
+    end
+  end
+end

data/lib/philiprehberger/differ/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module Differ
-    VERSION = '0.1.2'
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/differ.rb

@@ -4,14 +4,20 @@ require_relative 'differ/version'
 require_relative 'differ/change'
 require_relative 'differ/changeset'
 require_relative 'differ/comparator'
+require_relative 'differ/formatters'
+require_relative 'differ/similarity'
 
 module Philiprehberger
   module Differ
     class Error < StandardError; end
 
-    def self.diff(old_val, new_val, ignore: [])
-      changes = Comparator.call(old_val, new_val, ignore: ignore)
+    def self.diff(old_val, new_val, ignore: [], array_key: nil)
+      changes = Comparator.call(old_val, new_val, ignore: ignore, array_key: array_key)
       Changeset.new(changes)
     end
+
+    def self.similarity(old_val, new_val, ignore: [], array_key: nil)
+      Similarity.call(old_val, new_val, ignore: ignore, array_key: array_key)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-differ
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-16 00:00:00.000000000 Z
+date: 2026-03-17 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -24,6 +24,8 @@ files:
 - lib/philiprehberger/differ/change.rb
 - lib/philiprehberger/differ/changeset.rb
 - lib/philiprehberger/differ/comparator.rb
+- lib/philiprehberger/differ/formatters.rb
+- lib/philiprehberger/differ/similarity.rb
 - lib/philiprehberger/differ/version.rb
 homepage: https://github.com/philiprehberger/rb-differ
 licenses: