paper_trail_diff 0.2.0 → 0.3.1

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

data/lib/paper_trail_diff/activity_relationship.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Reads event-side foreign keys and matches them to an immutable snapshot owner.
+  class ActivityRelationship
+    #: (untyped, untyped, RecordSnapshot, ?state: Symbol) -> bool
+    def member_of_owner?(record, reflection, owner, state: :after)
+      actual = relationship_owner_values(record, reflection, state: state)
+      expected_ids = Array(owner.id)
+      # @type var expected_ids: Array[untyped]
+      expected = expected_ids.map { |id| id.to_s } # rubocop:disable Style/SymbolProc
+      return false unless actual == expected
+      return true unless reflection.options[:as]
+
+      type = event_attribute(record, reflection.type, state: state).to_s
+      owner_types(reflection, owner).include?(type)
+    end
+
+    #: (untyped, untyped, state: Symbol) -> untyped
+    def owner_id(record, reflection, state:)
+      values = Array(reflection.foreign_key).map do |foreign_key|
+        event_attribute(record, foreign_key, state: state)
+      end
+      values.one? ? values.first : values
+    end
+
+    private
+
+    #: (untyped, untyped, state: Symbol) -> Array[String]
+    def relationship_owner_values(record, reflection, state:)
+      Array(reflection.foreign_key).map do |key|
+        event_attribute(record, key, state: state).to_s
+      end
+    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, RecordSnapshot) -> Array[String]
+    def owner_types(reflection, owner)
+      [
+        owner.type.to_s,
+        reflection.active_record.name.to_s,
+        reflection.active_record.base_class.name.to_s
+      ]
+    end
+  end
+end

data/lib/paper_trail_diff/activity_snapshot_delta.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Internal scalar transition for one isolated PaperTrail update event.
+  class ActivitySnapshotDelta
+    #: (before_attributes: Hash[untyped, untyped], after_attributes: Hash[untyped, untyped]) -> void
+    def initialize(before_attributes:, after_attributes:)
+      @before_attributes = normalize_hash(before_attributes)
+      @after_attributes = normalize_hash(after_attributes)
+      freeze
+    end
+
+    #: (RecordSnapshot) -> RecordSnapshot
+    def apply(snapshot)
+      attributes = snapshot.attributes.dup
+      attributes.each_key do |name|
+        attributes[name] = @after_attributes[name] if @after_attributes.key?(name)
+      end
+      return snapshot if attributes == snapshot.attributes
+
+      RecordSnapshot.new(
+        type: snapshot.type,
+        id: snapshot.id,
+        attributes: attributes,
+        associations: snapshot.associations
+      )
+    end
+
+    #: (untyped) -> untyped
+    def before_value(name)
+      @before_attributes[name.to_s]
+    end
+
+    #: (untyped) -> untyped
+    def after_value(name)
+      @after_attributes[name.to_s]
+    end
+
+    #: (untyped) -> bool
+    def relationship_changed?(reflection)
+      relationship_keys(reflection).any? do |name|
+        before_value(name).to_s != after_value(name).to_s
+      end
+    end
+
+    private
+
+    # @rbs @before_attributes: Hash[String, untyped]
+    # @rbs @after_attributes: Hash[String, untyped]
+
+    #: (Hash[untyped, untyped]) -> Hash[String, untyped]
+    def normalize_hash(hash)
+      hash.to_h { |name, value| [name.to_s, value] }.freeze
+    end
+
+    #: (untyped) -> Array[untyped]
+    def relationship_keys(reflection)
+      keys = Array(reflection.foreign_key)
+      keys << reflection.type if reflection.options[:as]
+      keys
+    end
+  end
+end

data/lib/paper_trail_diff/activity_snapshot_sequence.rb

@@ -11,9 +11,9 @@ module PaperTrailDiff
       @preparer = preparer
     end
 
-    #: (untyped, Array[untyped]) -> void
-    def prepare(record, root_versions)
-      @preparer.call(record, root_versions)
+    #: (untyped, Array[untyped], ?start_at: untyped) -> void
+    def prepare(record, root_versions, start_at: root_versions.first.created_at)
+      @preparer.call(record, root_versions, start_at: start_at)
     end
 
     #: (untyped, untyped) -> RecordSnapshot?

data/lib/paper_trail_diff/activity_timeline_builder.rb

@@ -4,17 +4,19 @@
 module PaperTrailDiff
   # Compares adjacent root and selected-descendant activity boundaries.
   class ActivityTimelineBuilder
-    #: (untyped, from: untyped, to: untyped, tree: AssociationTree, snapshotter: untyped) -> void
-    def initialize(record, from:, to:, tree:, snapshotter:)
+    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
+    def initialize(record, range:, tree:, snapshotter:)
       @record = record
-      @from = from
-      @to = to
+      @from = range.from
+      @to = range.to
+      @range = range
       @tree = tree
       @snapshotter = snapshotter
     end
 
     #: () -> Array[ActivityStep]
     def build
+      return time_builder.build if @range.time?
       return build_to_current if Endpoint.record?(@to)
 
       Endpoint.validate!(@to)
@@ -24,15 +26,16 @@ module PaperTrailDiff
     # Builds all three version-bounded views from one activity snapshot pass.
     #: () -> Analysis
     def analyze
+      return time_builder.analyze if @range.time?
+
       unless Endpoint.version?(@to)
         raise InvalidTimelineRangeError, '`to` must be a root PaperTrail version'
       end
 
-      root_versions = VersionRange.new(@record, from: @from, to: @to).select
+      root_versions = @range.select
       prepare_history(root_versions)
       events = collect_events(root_versions)
-      activity_steps, root_snapshots, = event_history(root_versions, events)
-      build_analysis(root_versions, root_snapshots, activity_steps)
+      build_analysis(root_versions, event_history(root_versions, events))
     end
 
     private
@@ -40,12 +43,13 @@ module PaperTrailDiff
     # @rbs @record: untyped
     # @rbs @from: untyped
     # @rbs @to: untyped
+    # @rbs @range: TimelineRange
     # @rbs @tree: AssociationTree
     # @rbs @snapshotter: untyped
 
     #: () -> Array[ActivityStep]
     def build_between_versions
-      root_versions = VersionRange.new(@record, from: @from, to: @to).select
+      root_versions = @range.select
       prepare_history(root_versions)
       events = collect_events(root_versions)
       build_event_steps(root_versions, events)
@@ -82,20 +86,31 @@ module PaperTrailDiff
       Endpoint.validate_pair!(@record, @to)
     end
 
-    #: (Array[untyped], ?range_end: untyped) -> Array[ActivityEvent]
-    def collect_events(root_versions, range_end: root_versions.last)
+    #: (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
+    def collect_events(
+      root_versions,
+      range_start: root_versions.first,
+      range_end: root_versions.last
+    )
       ActivityVersionCollector.new(
         @record,
         root_versions: root_versions,
         tree: @tree,
         traversal: AssociationTraversal.new(@tree),
+        range_start: range_start,
         range_end: range_end
       ).call
     end
 
-    #: (Array[untyped]) -> void
-    def prepare_history(root_versions)
-      @snapshotter.prepare(@record, root_versions) if @snapshotter.respond_to?(:prepare)
+    #: (Array[untyped], ?start_at: untyped) -> void
+    def prepare_history(root_versions, start_at: nil)
+      return unless @snapshotter.respond_to?(:prepare)
+
+      if start_at
+        @snapshotter.prepare(@record, root_versions, start_at: start_at)
+      else
+        @snapshotter.prepare(@record, root_versions)
+      end
     end
 
     #: (Array[untyped], Array[ActivityEvent], ?current: untyped, ?final_boundary: ActivityBoundary?, ?final_snapshot: RecordSnapshot?) -> Array[ActivityStep]
@@ -106,55 +121,39 @@ module PaperTrailDiff
       final_boundary: nil,
       final_snapshot: nil
     )
-      steps, _root_snapshots, previous_snapshot = event_history(
-        root_versions,
-        events,
-        current: current
-      )
+      history = event_history(root_versions, events, current: current)
+      steps = history.steps.dup
       previous_event = events.last
       previous_boundary = ActivityBoundary.from_version(previous_event.version) if previous_event
       if final_boundary && previous_boundary
         steps << ActivityStep.new(
           from_boundary: previous_boundary,
           to_boundary: final_boundary,
-          diff: Engine.compare(previous_snapshot, final_snapshot)
+          diff: Engine.compare(history.last_snapshot, final_snapshot)
         )
       end
       steps.freeze
     end
 
-    #: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> [Array[ActivityStep], Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?]
-    def event_history(root_versions, events, current: nil) # rubocop:disable Metrics/MethodLength
-      sequence = ActivitySnapshotSequence.new(root_versions, events, @snapshotter, current: current)
-      steps = [] #: Array[ActivityStep]
-      root_snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
-      previous_boundary = nil #: ActivityBoundary?
-      previous_snapshot = nil #: RecordSnapshot?
-      sequence.each do |event, snapshot|
-        boundary = ActivityBoundary.from_version(event.version)
-        root_snapshots[version_key(event.version)] = snapshot if event.root?
-        if previous_boundary
-          steps << ActivityStep.new(
-            from_boundary: previous_boundary,
-            to_boundary: boundary,
-            diff: Engine.compare(previous_snapshot, snapshot)
-          )
-        end
-        previous_boundary = boundary
-        previous_snapshot = snapshot
-      end
-      [steps, root_snapshots, previous_snapshot]
+    #: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
+    def event_history(root_versions, events, current: nil)
+      ActivityHistoryBuilder.new(
+        root_versions,
+        events,
+        @snapshotter,
+        current: current
+      ).call
     end
 
-    #: (Array[untyped], Hash[Array[untyped], RecordSnapshot?], Array[ActivityStep]) -> Analysis
-    def build_analysis(root_versions, root_snapshots, activity_steps)
+    #: (Array[untyped], ActivityHistory) -> Analysis
+    def build_analysis(root_versions, history)
       snapshots = root_versions.map do |version|
-        root_snapshots.fetch(version_key(version))
+        history.root_snapshots.fetch(version_key(version))
       end
       Analysis.new(
-        diff: Engine.compare(snapshots.first, snapshots.last),
+        diff: Engine.compare(history.first_snapshot, history.last_snapshot),
         timeline: build_root_steps(root_versions, snapshots),
-        activity_timeline: activity_steps.freeze
+        activity_timeline: history.steps
       )
     end
 
@@ -173,5 +172,15 @@ module PaperTrailDiff
     def version_key(version)
       [version.class.name, version.id]
     end
+
+    #: () -> TimeActivityTimelineBuilder
+    def time_builder
+      TimeActivityTimelineBuilder.new(
+        @record,
+        range: @range,
+        tree: @tree,
+        snapshotter: @snapshotter
+      )
+    end
   end
 end

data/lib/paper_trail_diff/activity_version_collector.rb

@@ -4,13 +4,20 @@
 module PaperTrailDiff
   # Collects root and selected-descendant versions relevant to one root history range.
   class ActivityVersionCollector
-    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_end: untyped) -> void
-    def initialize(record, root_versions:, tree:, traversal:, range_end: root_versions.last)
+    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_start: untyped, ?range_end: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      record,
+      root_versions:,
+      tree:,
+      traversal:,
+      range_start: root_versions.first,
+      range_end: root_versions.last
+    )
       @record = record
       @root_versions = root_versions
       @tree = tree
       @traversal = traversal
-      @range = ActivityRange.new(root_versions.first, range_end)
+      @range = ActivityRange.new(range_start, range_end)
       @registry = ActivityEventRegistry.new
     end
 
@@ -98,15 +105,10 @@ module PaperTrailDiff
     end
 
     #: (untyped, Array[untyped], untyped) -> Hash[String, untyped]
-    def direct_child_groups(parent_class, parent_ids, reflection) # rubocop:disable Metrics/AbcSize
-      version_class = parent_class.paper_trail.version_class
-      relation = parent_class.paper_trail.version_association_class.joins(:version).where(
-        foreign_key_name: reflection.foreign_key.to_s,
-        foreign_key_id: parent_ids
-      ).where(foreign_type: related_parent_types(parent_class))
-      item_ids = relation.where(
-        version_class.table_name => { item_type: reflection.klass.base_class.name }
-      ).distinct.pluck(version_class.arel_table[:item_id])
+    def direct_child_groups(parent_class, parent_ids, reflection)
+      item_ids = ActivityChildCandidateLoader.new(
+        parent_class, parent_ids, reflection, @range
+      ).call
       return {} if item_ids.empty?
 
       { reflection.klass.name => group(reflection.klass, item_ids) }
@@ -178,11 +180,6 @@ module PaperTrailDiff
       nil
     end
 
-    #: (untyped) -> Array[String?]
-    def related_parent_types(parent_class)
-      [nil, '', parent_class.name.to_s, parent_class.base_class.name.to_s].uniq
-    end
-
     #: (untyped) -> bool
     def in_range?(version)
       @range.include?(version)

data/lib/paper_trail_diff/branch_snapshot_refresher.rb

@@ -4,7 +4,7 @@
 module PaperTrailDiff
   # Reconstructs selected root branches and merges them into a prior immutable snapshot.
   class BranchSnapshotRefresher
-    #: (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped) -> void
+    #: (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped) -> void
     def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
       tree:,
       ignore_policy:,
@@ -13,7 +13,8 @@ module PaperTrailDiff
       normalizer:,
       full_snapshotter:,
       partial_snapshotter:,
-      association_reader:
+      association_reader:,
+      record_transition:
     )
       @tree = tree
       @ignore_policy = ignore_policy
@@ -26,7 +27,8 @@ module PaperTrailDiff
         traversal: traversal,
         pool: pool,
         components: method(:components),
-        association_reader: association_reader
+        association_reader: association_reader,
+        record_transition: record_transition
       )
       @root_refresher = ActivityRootSnapshotRefresher.new(
         tree: tree,
@@ -157,6 +159,8 @@ module PaperTrailDiff
 
     #: (Array[String]) -> [AssociationTree, SnapshotNormalizer]
     def components(branches)
+      return @components[branches] if @components.key?(branches)
+
       key = branches.sort.freeze
       @components[key] ||= build_components(key)
     end

data/lib/paper_trail_diff/collection_comparator.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Compares collection snapshots with a low-allocation path for stable membership.
+  class CollectionComparator
+    #: (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
+    def initialize(from_association, to_association, record_comparer:)
+      @from = from_association
+      @to = to_association
+      @record_comparer = record_comparer
+    end
+
+    #: () -> CollectionAssociationDiff
+    def call
+      transition = @to.transition_from(@from)
+      return transition_difference(transition) if transition
+
+      aligned = aligned_changes
+      return difference(added: [], removed: [], changed: aligned) if aligned
+
+      indexed_difference
+    end
+
+    private
+
+    # @rbs @from: AssociationSnapshot
+    # @rbs @to: AssociationSnapshot
+    # @rbs @record_comparer: untyped
+
+    #: (CollectionTransition) -> CollectionAssociationDiff
+    def transition_difference(transition)
+      @from.validate_unique_identities!
+      @to.validate_unique_identities!
+      before = transition.before
+      after = transition.after
+      changed = compare_transition_records(before, after)
+      difference(
+        added: before.nil? && after ? [after] : [],
+        removed: after.nil? && before ? [before] : [],
+        changed: changed ? [changed] : []
+      )
+    end
+
+    #: (RecordSnapshot?, RecordSnapshot?) -> RecordChange?
+    def compare_transition_records(before, after)
+      return unless before && after && before.identity == after.identity
+
+      @record_comparer.call(before, after)
+    end
+
+    #: () -> Array[RecordChange]?
+    def aligned_changes
+      pairs = aligned_changed_pairs
+      return unless pairs
+
+      pairs.sort_by { |_from, to| sortable_identity(to.identity) }.filter_map do |pair|
+        @record_comparer.call(pair.fetch(0), pair.fetch(1))
+      end
+    end
+
+    #: () -> Array[[RecordSnapshot, RecordSnapshot]]?
+    def aligned_changed_pairs
+      from_records = @from.records
+      to_records = @to.records
+      return unless from_records.length == to_records.length
+
+      collect_aligned_pairs(from_records, to_records)
+    end
+
+    #: (Array[RecordSnapshot], Array[RecordSnapshot]) -> Array[[RecordSnapshot, RecordSnapshot]]?
+    def collect_aligned_pairs(from_records, to_records)
+      seen = {} #: Hash[identity, bool]
+      changed = [] #: Array[[RecordSnapshot, RecordSnapshot]]
+      index = 0
+      while index < from_records.length
+        from_record = from_records.fetch(index)
+        to_record = to_records.fetch(index)
+        identity = from_record.identity
+        raise_duplicate_identity!(identity) if seen.key?(identity)
+        return unless identity == to_record.identity
+
+        seen[identity] = true
+        changed << [from_record, to_record] unless from_record.equal?(to_record)
+        index += 1
+      end
+      changed
+    end
+
+    #: () -> CollectionAssociationDiff
+    def indexed_difference
+      from_records = index_records(@from.records)
+      to_records = index_records(@to.records)
+      difference(
+        added: records_missing_from(to_records, from_records),
+        removed: records_missing_from(from_records, to_records),
+        changed: changed_records(from_records, to_records)
+      )
+    end
+
+    #: (added: Array[RecordSnapshot], removed: Array[RecordSnapshot], changed: Array[RecordChange]) -> CollectionAssociationDiff
+    def difference(added:, removed:, changed:)
+      CollectionAssociationDiff.new(
+        kind: @from.kind,
+        added: added,
+        removed: removed,
+        changed: changed
+      )
+    end
+
+    #: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordSnapshot]
+    def records_missing_from(records, other_records)
+      identities = sorted_identities(records.keys - other_records.keys)
+      identities.map { |identity| records.fetch(identity) }
+    end
+
+    #: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordChange]
+    def changed_records(from_records, to_records)
+      sorted_identities(from_records.keys & to_records.keys).filter_map do |identity|
+        from_record = from_records.fetch(identity)
+        to_record = to_records.fetch(identity)
+        next if from_record.equal?(to_record)
+
+        @record_comparer.call(from_record, to_record)
+      end
+    end
+
+    #: (Array[RecordSnapshot]) -> Hash[identity, RecordSnapshot]
+    def index_records(records)
+      index = {} #: Hash[identity, RecordSnapshot]
+      records.each do |record|
+        identity = record.identity
+        raise_duplicate_identity!(identity) if index.key?(identity)
+
+        index[identity] = record
+      end
+      index
+    end
+
+    #: (Array[identity]) -> Array[identity]
+    def sorted_identities(identities)
+      identities.sort_by { |identity| sortable_identity(identity) }
+    end
+
+    #: (identity) -> Array[untyped]
+    def sortable_identity(identity)
+      [identity.fetch(0), identity.fetch(1).inspect]
+    end
+
+    #: (identity) -> void
+    def raise_duplicate_identity!(identity)
+      raise ArgumentError, "duplicate record identity: #{identity.inspect}"
+    end
+  end
+end