paper_trail_diff 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 205c52c1f80517b072fa68452447963c3d7245ba0707b049d5ebd5d2528727b3
-  data.tar.gz: 65cc6e544662366fc185719a3660b29c3a9796f7c003fe7eeff4c551c9114c11
+  metadata.gz: e747358edb04ac2ea49e43b11eb8b5b8e811c426b50b017ed6d1c72162bb4632
+  data.tar.gz: b330e3bb80e43e478a0e88ff7afeb2b6576d3550af0a54075948fb0e60dc045d
 SHA512:
-  metadata.gz: 78c62fcbc641a5f2dd029e69bf656453612a6f2768b1e3268048a13ea9fb4d17ff934048e36cb0798ae3d37aa3102f3c39ef289effdd2f96087796636e1ac921
-  data.tar.gz: 3ba0a0592b1dd997c6177f2ad654bc28a93b00aebd5f83720732b7edaf08200c43aae19ac8e6eae2bbe351147343a2a8cf38b6352ca9427a9f2ad35f1be7c36d
+  metadata.gz: 8bcf171950fd74de94c8118dabf3f911e8db3923ce4ed48463c505b3b5748bafbb9c39819b7af49841bf3ea3f6635e797c9536f5d845a42f0a9df9eb1018d1de
+  data.tar.gz: 2eb4d0d286b9daf4ed91e1d0d674c6835569ef3912a2712034fad27d31648c5eeed1e410f34fbfbec3d59808b5d82f178df84b896a233eaec570c3b24b6b52ab

data/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.12.0] - 2026-08-19
+
+### Changed
+
+- Report an array inside a JSON column by membership rather than as one opaque
+  value. `nested_changes` now returns a `PaperTrailDiff::ArrayChange` for a pair
+  of arrays, carrying `added`, `removed` and `reordered?` alongside the whole
+  `from` and `to` it already had. Position is deliberately not reported:
+  elements carry no identity, so an insertion at the front makes every later
+  index look changed and one insertion reads as several edits. Membership is
+  answerable without claiming any pairing. Matching is by value and respects
+  duplicates, so `["a", "a"]` to `["a"]` reports one removal. The one thing
+  membership cannot see -- the same elements in a new order -- is named rather
+  than passed over. An element that is itself an object is reported whole,
+  since saying which of its fields changed would require pairing before- and
+  after-elements that nothing in the value licenses.
+
 ## [0.11.0] - 2026-08-18
 
 ### Added

data/README.md

@@ -386,9 +386,30 @@ PaperTrailDiff.nested_changes({ "a.b" => 1, "a" => { "b" => 1 } },
 # => { ["a.b"] => <from 1 to 2>, ["a", "b"] => <from 1 to 3> }
 ```
 
-**Arrays are reported whole, not by index.** Their elements carry no identity, so
-an insertion at the front would make every later index look changed. This is the
-same rule the collection comparator follows for records it cannot identify.
+**Arrays are reported by membership, not by position.** Elements carry no
+identity, so an insertion at the front would make every later index look
+changed — one insertion described as several edits. An `ArrayChange` says what
+was added and removed, matching by value and respecting duplicates:
+
+```ruby
+change = PaperTrailDiff.nested_changes(
+  { "keywords" => %w[apollo nasa] },
+  { "keywords" => %w[saturn apollo nasa] }
+).fetch(["keywords"])
+
+change.added      # => ["saturn"]
+change.removed    # => []
+change.reordered? # => false
+change.from       # => ["apollo", "nasa"]   (the whole values remain)
+```
+
+Membership cannot see one thing, so it is named rather than passed over: the
+same elements in a new order report `reordered?` as true with nothing added or
+removed.
+
+An element that is itself an object is reported whole. Saying which field of
+which object changed would need a pairing of before-elements with
+after-elements, and nothing in the value licenses that pairing.
 
 **An absent key is not a null one.** `{"a": null}` and `{}` mean different things
 in JSON, and an audit trail that showed them alike would be lying about one of

data/lib/paper_trail_diff/nested_comparator.rb

@@ -16,11 +16,11 @@ module PaperTrailDiff
   # names and locales routinely do -- and joining would make `a.b` ambiguous
   # between one key and two.
   #
-  # Arrays are leaves. Their elements carry no identity, so an insertion at the
-  # front makes every later index look changed; reporting "element 2 changed"
-  # would be confidently wrong about a list that merely shifted. The whole array
-  # is reported as one change, which is the same rule the collection comparator
-  # follows for records it cannot identify.
+  # Arrays are reported by membership, not by position -- see ArrayChange. Their
+  # elements carry no identity, so an insertion at the front makes every later
+  # index look changed, and one insertion reads as several edits. What is added
+  # and removed can be answered without claiming any pairing; what cannot is the
+  # same elements in a new order, so that is named rather than passed over.
   #
   # An absent key is not a null one. `{"a": null}` and `{}` mean different
   # things in JSON and an audit trail that conflated them would be lying about
@@ -32,7 +32,7 @@ module PaperTrailDiff
     def ABSENT.to_s = 'absent'
     ABSENT.freeze
 
-    #: (untyped, untyped) -> Hash[Array[String], ValueChange]
+    #: (untyped, untyped) -> nested_changes
     def self.call(from_value, to_value)
       new(from_value, to_value).call
     end
@@ -46,12 +46,12 @@ module PaperTrailDiff
     # Returns the changed paths, or an empty hash when the pair is not two
     # structures this can look inside. An empty result therefore means "nothing
     # to report at this depth", and the caller still has the whole-value change.
-    #: () -> Hash[Array[String], ValueChange]
+    #: () -> nested_changes
     def call
       from_structure, to_structure = structures
       return {} unless from_structure && to_structure
 
-      changes = {} #: Hash[Array[String], ValueChange]
+      changes = {} #: nested_changes
       walk(from_structure, to_structure, [], changes)
       changes.freeze
     end
@@ -82,22 +82,33 @@ module PaperTrailDiff
       parsed if parsed.is_a?(Hash)
     end
 
-    #: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], Hash[Array[String], ValueChange]) -> void
+    #: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
     def walk(from_hash, to_hash, path, changes)
       keys(from_hash, to_hash).each do |key|
         from_item = from_hash.key?(key) ? from_hash[key] : ABSENT
         to_item = to_hash.key?(key) ? to_hash[key] : ABSENT
         next if from_item == to_item
 
-        here = [*path, key.to_s]
+        here = [*path, key.to_s].freeze
         if from_item.is_a?(Hash) && to_item.is_a?(Hash)
           walk(from_item, to_item, here, changes)
         else
-          changes[here.freeze] = ValueChange.new(from: from_item, to: to_item)
+          changes[here] = change_for(from_item, to_item)
         end
       end
     end
 
+    # Two arrays are a membership change; anything else is a change to the
+    # value as a whole, including an array facing something that is not one.
+    #: (untyped, untyped) -> nested_change
+    def change_for(from_item, to_item)
+      if from_item.is_a?(Array) && to_item.is_a?(Array)
+        ArrayChange.new(from: from_item, to: to_item)
+      else
+        ValueChange.new(from: from_item, to: to_item)
+      end
+    end
+
     # Sorted so a report reads the same twice, and stringified because a hash
     # loaded from JSON and one built in Ruby can key the same field differently.
     #: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[untyped]

data/lib/paper_trail_diff/value_objects.rb

@@ -20,6 +20,72 @@ module PaperTrailDiff
     end
   end
 
+  # A change to an array inside a value the database stores whole, reported by
+  # membership rather than by position.
+  #
+  # Position would be the obvious thing to report and the wrong one: elements
+  # here carry no identity, so inserting at the front makes every later index
+  # look changed, and one insertion is described as several edits. Membership is
+  # answerable without claiming any pairing -- "gained \"saturn v\"" is true
+  # whether the array is a set, a queue, or a ranked list.
+  #
+  # That leaves one case membership cannot see, so it is named rather than
+  # hidden: the same elements in a different order. `reordered?` says so.
+  #
+  # An element that is itself a Hash or Array is reported whole. Saying which
+  # field of which object changed would require pairing before-elements with
+  # after-elements, and nothing in the value licenses that pairing.
+  class ArrayChange
+    attr_reader :from #: Array[untyped]
+    attr_reader :to #: Array[untyped]
+    attr_reader :added #: Array[untyped]
+    attr_reader :removed #: Array[untyped]
+
+    #: (from: Array[untyped], to: Array[untyped]) -> void
+    def initialize(from:, to:)
+      @from = Support.immutable_copy(from)
+      @to = Support.immutable_copy(to)
+      @added = Support.immutable_copy(ArrayChange.surplus(to, from))
+      @removed = Support.immutable_copy(ArrayChange.surplus(from, to))
+      freeze
+    end
+
+    # Elements of `left` with no counterpart left in `right`, matching by value
+    # and respecting duplicates, so ["a", "a"] -> ["a"] reports one removal
+    # rather than none.
+    #: (Array[untyped], Array[untyped]) -> Array[untyped]
+    def self.surplus(left, right)
+      pool = right.dup
+      left.reject do |item|
+        index = pool.index(item)
+        index ? pool.delete_at(index) || true : false
+      end
+    end
+
+    # Same elements, different sequence. Only meaningful for a change that was
+    # recorded at all, which this only is when the two sides differ.
+    #: () -> bool
+    def reordered?
+      added.empty? && removed.empty?
+    end
+
+    #: () -> bool
+    def empty?
+      from == to
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        from: Support.serialize(from),
+        to: Support.serialize(to),
+        added: Support.serialize(added),
+        removed: Support.serialize(removed),
+        reordered: reordered?
+      }
+    end
+  end
+
   # Attribute and nested-association changes for a record whose identity did not change.
   class RecordChange
     attr_reader :record #: RecordReference

data/lib/paper_trail_diff/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.11.0'
+  VERSION = '0.12.0'
 end

data/lib/paper_trail_diff.rb

@@ -92,6 +92,8 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
 #     type attribute_changes = Hash[String, ValueChange]
 #     type association_diff = ToOneAssociationDiff | CollectionAssociationDiff
 #     type association_diffs = Hash[String, association_diff]
+#     type nested_change = ValueChange | ArrayChange
+#     type nested_changes = Hash[Array[String], nested_change]
 #     type association_snapshots = Hash[String, AssociationSnapshot]
 #     type identity = Array[untyped]
 #     type comparison_input = Hash[String | Symbol, untyped]
@@ -344,7 +346,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     # list that merely shifted would otherwise look changed throughout. A key
     # that was absent reads as `NestedComparator::ABSENT` rather than nil, which
     # JSON uses for a present null.
-    #: (untyped, ?untyped) -> Hash[Array[String], ValueChange]
+    #: (untyped, ?untyped) -> nested_changes
     def nested_changes(change, to_value = nil)
       # Tested by type rather than by responding to `from`: ActiveSupport gives
       # String#from, so duck-typing here quietly reads a plain string as a pair.

data/sig/generated/paper_trail_diff/nested_comparator.rbs

@@ -13,11 +13,11 @@ module PaperTrailDiff
   # names and locales routinely do -- and joining would make `a.b` ambiguous
   # between one key and two.
   #
-  # Arrays are leaves. Their elements carry no identity, so an insertion at the
-  # front makes every later index look changed; reporting "element 2 changed"
-  # would be confidently wrong about a list that merely shifted. The whole array
-  # is reported as one change, which is the same rule the collection comparator
-  # follows for records it cannot identify.
+  # Arrays are reported by membership, not by position -- see ArrayChange. Their
+  # elements carry no identity, so an insertion at the front makes every later
+  # index look changed, and one insertion reads as several edits. What is added
+  # and removed can be answered without claiming any pairing; what cannot is the
+  # same elements in a new order, so that is named rather than passed over.
   #
   # An absent key is not a null one. `{"a": null}` and `{}` mean different
   # things in JSON and an audit trail that conflated them would be lying about
@@ -30,8 +30,8 @@ module PaperTrailDiff
 
     def to_s: () -> untyped
 
-    # : (untyped, untyped) -> Hash[Array[String], ValueChange]
-    def self.call: (untyped, untyped) -> Hash[Array[String], ValueChange]
+    # : (untyped, untyped) -> nested_changes
+    def self.call: (untyped, untyped) -> nested_changes
 
     # : (untyped, untyped) -> void
     def initialize: (untyped, untyped) -> void
@@ -39,8 +39,8 @@ module PaperTrailDiff
     # Returns the changed paths, or an empty hash when the pair is not two
     # structures this can look inside. An empty result therefore means "nothing
     # to report at this depth", and the caller still has the whole-value change.
-    # : () -> Hash[Array[String], ValueChange]
-    def call: () -> Hash[Array[String], ValueChange]
+    # : () -> nested_changes
+    def call: () -> nested_changes
 
     private
 
@@ -57,8 +57,13 @@ module PaperTrailDiff
     # : (untyped) -> Hash[untyped, untyped]?
     def structure: (untyped) -> Hash[untyped, untyped]?
 
-    # : (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], Hash[Array[String], ValueChange]) -> void
-    def walk: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], Hash[Array[String], ValueChange]) -> void
+    # : (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
+    def walk: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
+
+    # Two arrays are a membership change; anything else is a change to the
+    # value as a whole, including an array facing something that is not one.
+    # : (untyped, untyped) -> nested_change
+    def change_for: (untyped, untyped) -> nested_change
 
     # Sorted so a report reads the same twice, and stringified because a hash
     # loaded from JSON and one built in Ruby can key the same field differently.

data/sig/generated/paper_trail_diff/value_objects.rbs

@@ -14,6 +14,51 @@ module PaperTrailDiff
     def to_h: () -> Hash[Symbol, untyped]
   end
 
+  # A change to an array inside a value the database stores whole, reported by
+  # membership rather than by position.
+  #
+  # Position would be the obvious thing to report and the wrong one: elements
+  # here carry no identity, so inserting at the front makes every later index
+  # look changed, and one insertion is described as several edits. Membership is
+  # answerable without claiming any pairing -- "gained \"saturn v\"" is true
+  # whether the array is a set, a queue, or a ranked list.
+  #
+  # That leaves one case membership cannot see, so it is named rather than
+  # hidden: the same elements in a different order. `reordered?` says so.
+  #
+  # An element that is itself a Hash or Array is reported whole. Saying which
+  # field of which object changed would require pairing before-elements with
+  # after-elements, and nothing in the value licenses that pairing.
+  class ArrayChange
+    attr_reader from: Array[untyped]
+
+    attr_reader to: Array[untyped]
+
+    attr_reader added: Array[untyped]
+
+    attr_reader removed: Array[untyped]
+
+    # : (from: Array[untyped], to: Array[untyped]) -> void
+    def initialize: (from: Array[untyped], to: Array[untyped]) -> void
+
+    # Elements of `left` with no counterpart left in `right`, matching by value
+    # and respecting duplicates, so ["a", "a"] -> ["a"] reports one removal
+    # rather than none.
+    # : (Array[untyped], Array[untyped]) -> Array[untyped]
+    def self.surplus: (Array[untyped], Array[untyped]) -> Array[untyped]
+
+    # Same elements, different sequence. Only meaningful for a change that was
+    # recorded at all, which this only is when the two sides differ.
+    # : () -> bool
+    def reordered?: () -> bool
+
+    # : () -> bool
+    def empty?: () -> bool
+
+    # : () -> Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
   # Attribute and nested-association changes for a record whose identity did not change.
   class RecordChange
     attr_reader record: RecordReference

data/sig/generated/paper_trail_diff.rbs

@@ -99,8 +99,8 @@ module PaperTrailDiff
   # list that merely shifted would otherwise look changed throughout. A key
   # that was absent reads as `NestedComparator::ABSENT` rather than nil, which
   # JSON uses for a present null.
-  # : (untyped, ?untyped) -> Hash[Array[String], ValueChange]
-  def self.nested_changes: (untyped, ?untyped) -> Hash[Array[String], ValueChange]
+  # : (untyped, ?untyped) -> nested_changes
+  def self.nested_changes: (untyped, ?untyped) -> nested_changes
 end
 
 module PaperTrailDiff
@@ -114,6 +114,10 @@ module PaperTrailDiff
 
   type association_diffs = Hash[String, association_diff]
 
+  type nested_change = ValueChange | ArrayChange
+
+  type nested_changes = Hash[Array[String], nested_change]
+
   type association_snapshots = Hash[String, AssociationSnapshot]
 
   type identity = Array[untyped]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail_diff
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Alex Williams
@@ -212,11 +212,11 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   bug_tracker_uri: https://github.com/aheathwilliams/paper_trail_diff/issues
-  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.11.0/CHANGELOG.md
-  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.11.0/README.md
+  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.12.0/CHANGELOG.md
+  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.12.0/README.md
   homepage_uri: https://github.com/aheathwilliams/paper_trail_diff
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.11.0
+  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.12.0
 rdoc_options: []
 require_paths:
 - lib