paper_trail_diff 0.2.0 → 0.3.0

data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb

@@ -11,16 +11,17 @@ module PaperTrailDiff
     }.freeze
     private_constant :RECORD_AFTER_HANDLERS
 
-    #: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped) -> void
-    def initialize(traversal:, pool:, components:, association_reader: nil)
+    #: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped) -> void
+    def initialize(traversal:, pool:, components:, association_reader: nil, record_transition: nil)
       @traversal = traversal
       @pool = pool
       @components = components
       @association_reader = association_reader || method(:historical_reader)
+      @record_transition = record_transition
     end
 
     #: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent?) -> [bool, RecordSnapshot?]
-    def call( # rubocop:disable Metrics/MethodLength
+    def call( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       root_endpoint,
       context_endpoint,
       previous,
@@ -38,13 +39,17 @@ module PaperTrailDiff
       unless collection_routes.empty?
         return [false, nil] if unsafe_through_membership_event?(collection_routes, event.version)
 
+        delta = activity_snapshot_delta(event.version)
+        return [false, nil] if unsafe_nested_membership_delta?(collection_routes, delta)
+
         return collection_target_snapshot(
           root_endpoint,
           context_endpoint,
           previous,
           normalizer,
           collection_routes,
-          event.version
+          event.version,
+          delta
         )
       end
 
@@ -64,6 +69,7 @@ module PaperTrailDiff
     # @rbs @pool: SnapshotPool
     # @rbs @components: untyped
     # @rbs @association_reader: untyped
+    # @rbs @record_transition: untyped
 
     #: (Array[Array[untyped]], untyped) -> bool
     def unsafe_through_membership_event?(routes, version)
@@ -77,35 +83,111 @@ module PaperTrailDiff
       end
     end
 
-    #: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped) -> [bool, RecordSnapshot]
+    #: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
+    def unsafe_nested_membership_delta?(routes, delta)
+      return false unless delta
+
+      routes.any? do |route|
+        route.length > 1 && delta.relationship_changed?(route.last.fetch(1))
+      end
+    end
+
+    #: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> [bool, RecordSnapshot]
     def collection_target_snapshot( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
       root_endpoint,
       context_endpoint,
       previous,
       normalizer,
       routes,
-      version
+      version,
+      delta
     )
-      record = record_after(version)
+      fallback_record = [] #: Array[untyped]
       snapshot = previous
       routes.each do |route|
-        _name, reflection, subtree, path = route.last
-        replacement = if record
-                        normalize_event_record(
-                          record,
-                          reflection,
-                          subtree,
-                          path,
-                          normalizer,
-                          root_endpoint,
-                          context_endpoint
-                        )
-                      end
+        record, replacement = collection_route_event_state(
+          snapshot,
+          route,
+          version,
+          delta,
+          fallback_record,
+          normalizer,
+          root_endpoint,
+          context_endpoint
+        )
         snapshot, = replace_collection_route(snapshot, route, version, record, replacement)
       end
       [true, snapshot]
     end
 
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, untyped, untyped) -> [untyped, RecordSnapshot?]
+    def collection_route_event_state( # rubocop:disable Metrics/ParameterLists
+      snapshot,
+      route,
+      version,
+      delta,
+      fallback_record,
+      normalizer,
+      root_endpoint,
+      context_endpoint
+    )
+      existing = existing_delta_record(snapshot, route, version, delta) if delta
+      return [delta, delta.apply(existing)] if delta && existing
+
+      fallback_record << record_after(version) if fallback_record.empty?
+      record = fallback_record.first
+      return [record, nil] unless record
+
+      [record, normalized_collection_event_record(
+        record, route, normalizer, root_endpoint, context_endpoint
+      )]
+    end
+
+    #: (untyped, Array[untyped], SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
+    def normalized_collection_event_record(
+      record,
+      route,
+      normalizer,
+      root_endpoint,
+      context_endpoint
+    )
+      _name, reflection, subtree, path = route.last
+      normalize_event_record(
+        record,
+        reflection,
+        subtree,
+        path,
+        normalizer,
+        root_endpoint,
+        context_endpoint
+      )
+    end
+
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?) -> RecordSnapshot?
+    def existing_delta_record(snapshot, route, version, delta)
+      return unless delta && route.length.between?(1, 2)
+
+      owner = route.length == 1 ? snapshot : nested_delta_owner(snapshot, route, delta)
+      return unless owner
+
+      association = owner.associations.fetch(route.last.fetch(0))
+      position = association.position_for_id(version.item_id)
+      association.records.fetch(position) if position
+    end
+
+    #: (RecordSnapshot, Array[untyped], ActivitySnapshotDelta) -> RecordSnapshot?
+    def nested_delta_owner(snapshot, route, delta)
+      parent_name = route.first.fetch(0)
+      reflection = route.last.fetch(1)
+      association = snapshot.associations.fetch(parent_name)
+      owner_id = relationship_owner_id(delta, reflection, state: :before)
+      position = association.position_for_id(owner_id)
+      return unless position
+
+      owner = association.records.fetch(position)
+      owner if member_of_owner?(delta, reflection, owner, state: :before)
+    end
+
     #: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
     def direct_collection_routes( # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       model_class,
@@ -150,15 +232,31 @@ module PaperTrailDiff
       name, reflection, _subtree, path = route.fetch(depth)
       association = snapshot.associations.fetch(name)
       changed = false
+      transition_before = nil #: RecordSnapshot?
+      transition_after = nil #: RecordSnapshot?
+      membership_preserved = true
       updated_records = if depth == route.length - 1
-                          child = if record && member_of_owner?(record, reflection, snapshot)
-                                    replacement
-                                  end
-                          replace_collection_record(
-                            association.records,
+                          child = collection_event_child(
+                            association,
                             version,
-                            child
-                          ).tap { |value| changed = !value.equal?(association.records) }
+                            record,
+                            reflection,
+                            snapshot,
+                            replacement
+                          )
+                          records, transition_before, transition_after, membership_preserved =
+                            replace_collection_record(association, version, child)
+                          records.tap { |value| changed = !value.equal?(association.records) }
+                        elsif (targeted = replace_targeted_collection_parent(
+                          association,
+                          route,
+                          version,
+                          record,
+                          replacement,
+                          depth
+                        ))
+                          records, transition_before, transition_after, changed = targeted
+                          records
                         else
                           association.records.map do |child_snapshot|
                             updated, child_changed = replace_collection_route(
@@ -169,15 +267,28 @@ module PaperTrailDiff
                               replacement,
                               depth: depth + 1
                             )
-                            changed ||= child_changed
+                            if child_changed
+                              transition_before = nil if changed
+                              transition_after = nil if changed
+                              unless changed
+                                transition_before = child_snapshot
+                                transition_after = updated
+                              end
+                              changed = true
+                            end
                             updated
-                          end
+                          end.freeze
                         end
       return [snapshot, false] unless changed
 
       updated_association = @pool.association(
         path,
-        AssociationSnapshot.new(kind: association.kind, records: updated_records)
+        association.transition_to(
+          updated_records,
+          before: transition_before,
+          after: transition_after,
+          membership_preserved: membership_preserved
+        )
       )
       updated_snapshot = RecordSnapshot.new(
         type: snapshot.type,
@@ -190,6 +301,73 @@ module PaperTrailDiff
       [updated_snapshot, true]
     end
 
+    #: (AssociationSnapshot, untyped, untyped, untyped, RecordSnapshot, RecordSnapshot?) -> RecordSnapshot?
+    def collection_event_child( # rubocop:disable Metrics/ParameterLists
+      association, version, record, reflection, owner, replacement
+    )
+      return unless record
+
+      unless record.is_a?(ActivitySnapshotDelta)
+        return replacement if member_of_owner?(record, reflection, owner)
+
+        return
+      end
+      unless record.relationship_changed?(reflection)
+        return replacement if association.position_for_id(version.item_id)
+
+        return
+      end
+
+      replacement if member_of_owner?(record, reflection, owner)
+    end
+
+    #: (AssociationSnapshot, Array[untyped], untyped, untyped, RecordSnapshot?, Integer) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]?
+    def replace_targeted_collection_parent( # rubocop:disable Metrics/ParameterLists
+      association,
+      route,
+      version,
+      record,
+      replacement,
+      depth
+    )
+      return unless depth == route.length - 2
+
+      reflection = route.fetch(depth + 1).fetch(1)
+      position = nested_owner_position(association, reflection, version, record)
+      return unless position
+
+      before = association.records.fetch(position)
+      after, changed = replace_collection_route(
+        before,
+        route,
+        version,
+        record,
+        replacement,
+        depth: depth + 1
+      )
+      targeted_parent_replacement(association.records, position, before, after, changed)
+    end
+
+    #: (Array[RecordSnapshot], Integer, RecordSnapshot, RecordSnapshot, bool) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]
+    def targeted_parent_replacement(records, position, before, after, changed)
+      return [records, nil, nil, false] unless changed
+
+      updated = records.dup
+      updated[position] = after
+      [updated.freeze, before, after, true]
+    end
+
+    #: (AssociationSnapshot, untyped, untyped, untyped) -> Integer?
+    def nested_owner_position(association, reflection, version, record)
+      membership_record = record || version.reify(dup: true)
+      return unless membership_record
+      return if membership_record.is_a?(ActivitySnapshotDelta) &&
+                membership_record.relationship_changed?(reflection)
+
+      owner_id = relationship_owner_id(membership_record, reflection, state: :after)
+      association.position_for_id(owner_id)
+    end
+
     #: (untyped, untyped, RecordSnapshot, AssociationTree, SnapshotNormalizer, untyped) -> [bool, RecordSnapshot?]
     def belongs_to_target_snapshot( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
       root_endpoint,
@@ -291,7 +469,7 @@ module PaperTrailDiff
                             )
                             changed ||= record_changed
                             updated
-                          end
+                          end.freeze
                         end
       return [snapshot, false] unless changed
 
@@ -318,7 +496,7 @@ module PaperTrailDiff
 
       updated = records.dup
       replacement ? updated[index] = replacement : updated.delete_at(index)
-      updated
+      updated.freeze
     end
 
     #: (untyped) -> untyped
@@ -409,10 +587,23 @@ module PaperTrailDiff
       changes
     end
 
-    #: (untyped, untyped, RecordSnapshot) -> bool
-    def member_of_owner?(record, reflection, owner) # rubocop:disable Metrics/AbcSize
+    #: (untyped) -> ActivitySnapshotDelta?
+    def activity_snapshot_delta(version)
+      return unless version.event.to_s == 'update' && version.object
+
+      transition = @record_transition&.call(version)
+      return unless transition
+
+      ActivitySnapshotDelta.new(
+        before_attributes: transition.fetch(0),
+        after_attributes: transition.fetch(1)
+      )
+    end
+
+    #: (untyped, untyped, RecordSnapshot, ?state: Symbol) -> bool
+    def member_of_owner?(record, reflection, owner, state: :after) # rubocop:disable Metrics/AbcSize
       foreign_keys = Array(reflection.foreign_key)
-      actual_ids = foreign_keys.map { |key| record.public_send(key) }
+      actual_ids = foreign_keys.map { |key| event_attribute(record, key, state: state) }
       expected_ids = Array(owner.id)
       # @type var expected_ids: Array[untyped]
       # Explicit blocks keep the inline RBS checker from inferring an unusable Proc type.
@@ -421,7 +612,7 @@ module PaperTrailDiff
       return false unless actual == expected
       return true unless reflection.options[:as]
 
-      type = record.public_send(reflection.type).to_s
+      type = event_attribute(record, reflection.type, state: state).to_s
       owner_types = [
         owner.type.to_s,
         reflection.active_record.name.to_s,
@@ -430,6 +621,23 @@ module PaperTrailDiff
       owner_types.include?(type)
     end
 
+    #: (untyped, untyped, state: Symbol) -> untyped
+    def event_attribute(record, name, state:)
+      if record.is_a?(ActivitySnapshotDelta)
+        return state == :before ? record.before_value(name) : record.after_value(name)
+      end
+
+      record.public_send(name)
+    end
+
+    #: (untyped, untyped, state: Symbol) -> untyped
+    def relationship_owner_id(record, reflection, state:)
+      owner_ids = Array(reflection.foreign_key).map do |foreign_key|
+        event_attribute(record, foreign_key, state: state)
+      end
+      owner_ids.one? ? owner_ids.first : owner_ids
+    end
+
     #: (untyped, untyped, AssociationTree, String, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
     def normalize_event_record( # rubocop:disable Metrics/ParameterLists
       record,
@@ -459,22 +667,30 @@ module PaperTrailDiff
       HistoricalAssociationReifier.new(context_endpoint, habtm_version: habtm_version)
     end
 
-    #: (Array[RecordSnapshot], untyped, RecordSnapshot?) -> Array[RecordSnapshot]
-    def replace_collection_record(records, version, replacement)
-      index = records.index do |record|
-        record.id.to_s == version.item_id.to_s &&
-          record.type.to_s == replacement_type(version, replacement)
-      end
-      return records unless replacement || index
+    #: (AssociationSnapshot, untyped, RecordSnapshot?) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]
+    def replace_collection_record(association, version, replacement)
+      records = association.records
+      position = association.position(
+        replacement_type(version, replacement),
+        version.item_id
+      )
+      return [records, nil, nil, true] unless replacement || position
+
+      before = records.fetch(position) if position
+      updated = replacement_collection_records(records, position, replacement)
+      [updated, before, replacement, !before.nil? && !replacement.nil?]
+    end
 
+    #: (Array[RecordSnapshot], Integer?, RecordSnapshot?) -> Array[RecordSnapshot]
+    def replacement_collection_records(records, position, replacement)
       updated = records.dup
       if replacement
-        index ? updated[index] = replacement : updated << replacement
+        position ? updated[position] = replacement : updated << replacement
       else
-        position = index || raise(ConfigurationError, 'missing collection event identity')
+        position ||= raise(ConfigurationError, 'missing collection event identity')
         updated.delete_at(position)
       end
-      updated
+      updated.freeze
     end
 
     #: (untyped, RecordSnapshot?) -> String

data/lib/paper_trail_diff/activity_history.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Immutable snapshots and steps produced by one activity-history pass.
+  class ActivityHistory
+    attr_reader :steps #: Array[ActivityStep]
+    attr_reader :root_snapshots #: Hash[Array[untyped], RecordSnapshot?]
+    attr_reader :first_snapshot #: RecordSnapshot?
+    attr_reader :last_snapshot #: RecordSnapshot?
+
+    #: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?) -> void
+    def initialize(steps:, root_snapshots:, first_snapshot:, last_snapshot:)
+      @steps = steps.freeze
+      @root_snapshots = root_snapshots.freeze
+      @first_snapshot = first_snapshot
+      @last_snapshot = last_snapshot
+      freeze
+    end
+
+    #: () -> ActivityHistory
+    def self.empty
+      new(steps: [], root_snapshots: {}, first_snapshot: nil, last_snapshot: nil)
+    end
+  end
+
+  # Builds activity steps while retaining root snapshots for combined analysis.
+  class ActivityHistoryBuilder
+    #: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped) -> void
+    def initialize(root_versions, events, snapshotter, current: nil, include_step: nil)
+      @root_versions = root_versions
+      @events = events
+      @snapshotter = snapshotter
+      @current = current
+      @include_step = include_step
+    end
+
+    #: () -> ActivityHistory
+    def call
+      reset
+      sequence.each { |event, snapshot| consume(event, snapshot) }
+      ActivityHistory.new(
+        steps: @steps,
+        root_snapshots: @root_snapshots,
+        first_snapshot: @first_snapshot,
+        last_snapshot: final_snapshot
+      )
+    end
+
+    private
+
+    # @rbs @root_versions: Array[untyped]
+    # @rbs @events: Array[ActivityEvent]
+    # @rbs @snapshotter: untyped
+    # @rbs @current: untyped
+    # @rbs @include_step: untyped
+    # @rbs @steps: Array[ActivityStep]
+    # @rbs @root_snapshots: Hash[Array[untyped], RecordSnapshot?]
+    # @rbs @first_snapshot: RecordSnapshot?
+    # @rbs @previous_snapshot: RecordSnapshot?
+    # @rbs @selected_last_snapshot: RecordSnapshot?
+    # @rbs @previous_boundary: ActivityBoundary?
+    # @rbs @previous_event: ActivityEvent?
+
+    #: () -> void
+    def reset
+      @steps = []
+      @root_snapshots = {}
+      @first_snapshot = nil
+      @first_snapshot_seen = false
+      @previous_snapshot = nil
+      @selected_last_snapshot = nil
+      @previous_boundary = nil
+      @previous_event = nil
+    end
+
+    #: () -> ActivitySnapshotSequence
+    def sequence
+      ActivitySnapshotSequence.new(
+        @root_versions,
+        @events,
+        @snapshotter,
+        current: @current
+      )
+    end
+
+    #: (ActivityEvent, RecordSnapshot?) -> void
+    def consume(event, snapshot)
+      capture_first(snapshot)
+      boundary = ActivityBoundary.from_version(event.version)
+      @root_snapshots[version_key(event.version)] = snapshot if event.root?
+      append_step(boundary, snapshot) if @previous_boundary
+      @previous_boundary = boundary
+      @previous_event = event
+      @previous_snapshot = snapshot
+    end
+
+    #: (RecordSnapshot?) -> void
+    def capture_first(snapshot)
+      return if @first_snapshot_seen
+
+      @first_snapshot = snapshot
+      @first_snapshot_seen = true
+    end
+
+    #: (ActivityBoundary, RecordSnapshot?) -> void
+    def append_step(boundary, snapshot)
+      return unless include_previous_step?
+
+      previous_boundary = @previous_boundary
+      return unless previous_boundary
+
+      @steps << ActivityStep.new(
+        from_boundary: previous_boundary,
+        to_boundary: boundary,
+        diff: Engine.compare(@previous_snapshot, snapshot)
+      )
+      @selected_last_snapshot = snapshot
+    end
+
+    #: () -> bool
+    def include_previous_step?
+      !@include_step || @include_step.call(@previous_event)
+    end
+
+    #: () -> RecordSnapshot?
+    def final_snapshot
+      @include_step ? @selected_last_snapshot : @previous_snapshot
+    end
+
+    #: (untyped) -> Array[untyped]
+    def version_key(version)
+      [version.class.name, version.id]
+    end
+  end
+end

data/lib/paper_trail_diff/activity_range.rb

@@ -4,11 +4,18 @@
 module PaperTrailDiff
   # Tests activity versions against a historical-version or wall-clock range end.
   class ActivityRange
+    attr_reader :start_time #: untyped
+    attr_reader :end_time #: untyped
+
     #: (untyped, untyped) -> void
-    def initialize(start_version, end_boundary)
-      @start_version = start_version
+    def initialize(start_boundary, end_boundary)
+      @start_boundary = start_boundary
       @end_boundary = end_boundary
-      @start_key = Support.chronological_version_key(start_version)
+      @start_key = if Endpoint.version?(start_boundary)
+                     Support.chronological_version_key(start_boundary)
+                   end
+      @start_time = Endpoint.version?(start_boundary) ? start_boundary.created_at : start_boundary
+      @end_time = Endpoint.version?(end_boundary) ? end_boundary.created_at : end_boundary
       @end_key = if Endpoint.version?(end_boundary)
                    Support.chronological_version_key(end_boundary)
                  end
@@ -17,23 +24,37 @@ module PaperTrailDiff
     #: (untyped) -> bool
     def include?(version)
       key = Support.chronological_version_key(version)
-      key_before_or_equal?(@start_key, key) && before_end?(version, key)
+      after_start?(version, key) && before_end?(version, key)
     end
 
     # Narrows an Active Record version relation by timestamp. Exact tie-breaking
     # remains in #include? so this works for integer, UUID, and custom version IDs.
     #: (untyped) -> untyped
     def scope(relation)
-      relation.where(created_at: @start_version.created_at..end_time)
+      relation.where(created_at: @start_time..end_time)
+    end
+
+    #: () -> bool
+    def current_end?
+      !Endpoint.version?(@end_boundary)
     end
 
     private
 
-    # @rbs @start_version: untyped
+    # @rbs @start_boundary: untyped
     # @rbs @end_boundary: untyped
-    # @rbs @start_key: Array[untyped]
+    # @rbs @start_key: Array[untyped]?
+    # @rbs @start_time: untyped
     # @rbs @end_key: Array[untyped]?
 
+    #: (untyped, Array[untyped]) -> bool
+    def after_start?(version, key)
+      start_key = @start_key
+      return key_before_or_equal?(start_key, key) if start_key
+
+      version.created_at >= @start_time
+    end
+
     #: (untyped, Array[untyped]) -> bool
     def before_end?(version, key)
       end_key = @end_key
@@ -42,11 +63,6 @@ module PaperTrailDiff
       version.created_at <= @end_boundary
     end
 
-    #: () -> untyped
-    def end_time
-      Endpoint.version?(@end_boundary) ? @end_boundary.created_at : @end_boundary
-    end
-
     #: (Array[untyped], Array[untyped]) -> bool
     def key_before_or_equal?(left, right)
       comparison = left <=> right