paper_trail_diff 0.3.0 → 0.4.0

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_root_steps.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Root checkpoint steps recovered from the snapshots an activity pass retained,
+  # so a combined result does not reconstruct the same boundaries twice.
+  module ActivityRootSteps
+    module_function
+
+    #: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    def call(root_versions, root_snapshots)
+      snapshots = root_versions.map { |version| root_snapshots.fetch(version_key(version)) }
+      root_versions.each_cons(2).with_index.map do |versions, index|
+        Step.new(
+          from_version: versions.fetch(0),
+          to_version: versions.fetch(1),
+          diff: Engine.compare(snapshots.fetch(index), snapshots.fetch(index + 1))
+        )
+      end.freeze
+    end
+
+    #: (untyped) -> Array[untyped]
+    def version_key(version)
+      [version.class.name, version.id]
+    end
+  end
+end

data/lib/paper_trail_diff/activity_snapshot_sequence.rb

@@ -11,9 +11,14 @@ module PaperTrailDiff
       @preparer = preparer
     end
 
-    #: (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)
+    #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def prepare(
+      record,
+      root_versions,
+      start_at: root_versions.first.created_at,
+      end_at: root_versions.last.created_at
+    )
+      @preparer.call(record, root_versions, start_at: start_at, end_at: end_at)
     end
 
     #: (untyped, untyped) -> RecordSnapshot?

data/lib/paper_trail_diff/activity_timeline_builder.rb

@@ -17,6 +17,7 @@ module PaperTrailDiff
     #: () -> Array[ActivityStep]
     def build
       return time_builder.build if @range.time?
+      return no_steps if @range.unresolved?
       return build_to_current if Endpoint.record?(@to)
 
       Endpoint.validate!(@to)
@@ -27,6 +28,7 @@ module PaperTrailDiff
     #: () -> Analysis
     def analyze
       return time_builder.analyze if @range.time?
+      return Analysis.empty if @range.unresolved?
 
       unless Endpoint.version?(@to)
         raise InvalidTimelineRangeError, '`to` must be a root PaperTrail version'
@@ -35,7 +37,7 @@ module PaperTrailDiff
       root_versions = @range.select
       prepare_history(root_versions)
       events = collect_events(root_versions)
-      build_analysis(root_versions, event_history(root_versions, events))
+      build_analysis(root_versions, events, event_history(root_versions, events))
     end
 
     private
@@ -47,6 +49,12 @@ module PaperTrailDiff
     # @rbs @tree: AssociationTree
     # @rbs @snapshotter: untyped
 
+    #: () -> Array[ActivityStep]
+    def no_steps
+      steps = [] #: Array[ActivityStep]
+      steps.freeze
+    end
+
     #: () -> Array[ActivityStep]
     def build_between_versions
       root_versions = @range.select
@@ -60,7 +68,9 @@ module PaperTrailDiff
       validate_current_range!
       current_snapshot, captured_at = capture_current
       root_versions = VersionRange.new(@record, from: @from, to: @from).select_through_latest
-      prepare_history(root_versions)
+      # Descendants can move after the last root version, so the prepared range
+      # ends at the captured instant rather than at that version.
+      prepare_history(root_versions, end_at: captured_at)
       events = collect_events(root_versions, range_end: captured_at)
       build_event_steps(
         root_versions,
@@ -102,15 +112,12 @@ module PaperTrailDiff
       ).call
     end
 
-    #: (Array[untyped], ?start_at: untyped) -> void
-    def prepare_history(root_versions, start_at: nil)
+    #: (Array[untyped], ?end_at: untyped) -> void
+    def prepare_history(root_versions, end_at: nil)
       return unless @snapshotter.respond_to?(:prepare)
+      return @snapshotter.prepare(@record, root_versions) unless end_at
 
-      if start_at
-        @snapshotter.prepare(@record, root_versions, start_at: start_at)
-      else
-        @snapshotter.prepare(@record, root_versions)
-      end
+      @snapshotter.prepare(@record, root_versions, end_at: end_at)
     end
 
     #: (Array[untyped], Array[ActivityEvent], ?current: untyped, ?final_boundary: ActivityBoundary?, ?final_snapshot: RecordSnapshot?) -> Array[ActivityStep]
@@ -122,6 +129,18 @@ module PaperTrailDiff
       final_snapshot: nil
     )
       history = event_history(root_versions, events, current: current)
+      activity_steps(
+        history,
+        events,
+        final_boundary || destroyed_boundary(root_versions),
+        final_snapshot
+      )
+    end
+
+    # Appends the transition into an explicit closing boundary, which is either
+    # a requested current record or the absence a final root destroy leaves.
+    #: (ActivityHistory, Array[ActivityEvent], ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
+    def activity_steps(history, events, final_boundary, final_snapshot)
       steps = history.steps.dup
       previous_event = events.last
       previous_boundary = ActivityBoundary.from_version(previous_event.version) if previous_event
@@ -135,6 +154,16 @@ module PaperTrailDiff
       steps.freeze
     end
 
+    # A destroyed root has no later version, but its own event states that
+    # nothing follows it, so the removal can still close the timeline.
+    #: (Array[untyped]) -> ActivityBoundary?
+    def destroyed_boundary(root_versions)
+      version = root_versions.last
+      return unless version && version.event.to_s == 'destroy'
+
+      ActivityBoundary.destroyed(version)
+    end
+
     #: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
     def event_history(root_versions, events, current: nil)
       ActivityHistoryBuilder.new(
@@ -145,32 +174,18 @@ module PaperTrailDiff
       ).call
     end
 
-    #: (Array[untyped], ActivityHistory) -> Analysis
-    def build_analysis(root_versions, history)
-      snapshots = root_versions.map do |version|
-        history.root_snapshots.fetch(version_key(version))
-      end
+    # Only the activity view gains the closing removal. The endpoint diff and
+    # the root timeline keep their `compare` and `timeline` semantics, under
+    # which the state at a destroy version is the state before the deletion.
+    #: (Array[untyped], Array[ActivityEvent], ActivityHistory) -> Analysis
+    def build_analysis(root_versions, events, history)
       Analysis.new(
         diff: Engine.compare(history.first_snapshot, history.last_snapshot),
-        timeline: build_root_steps(root_versions, snapshots),
-        activity_timeline: history.steps
-      )
-    end
-
-    #: (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
-    def build_root_steps(root_versions, snapshots)
-      root_versions.each_cons(2).with_index.map do |versions, index|
-        Step.new(
-          from_version: versions.fetch(0),
-          to_version: versions.fetch(1),
-          diff: Engine.compare(snapshots.fetch(index), snapshots.fetch(index + 1))
+        timeline: ActivityRootSteps.call(root_versions, history.root_snapshots),
+        activity_timeline: activity_steps(
+          history, events, destroyed_boundary(root_versions), nil
         )
-      end.freeze
-    end
-
-    #: (untyped) -> Array[untyped]
-    def version_key(version)
-      [version.class.name, version.id]
+      )
     end
 
     #: () -> TimeActivityTimelineBuilder

data/lib/paper_trail_diff/analysis.rb

@@ -8,6 +8,15 @@ module PaperTrailDiff
     attr_reader :timeline #: Array[Step]
     attr_reader :activity_timeline #: Array[ActivityStep]?
 
+    # The result for a record whose requested history contains no versions,
+    # which is an empty history rather than a failed request.
+    #: () -> Analysis
+    def self.empty
+      timeline = [] #: Array[Step]
+      activity_timeline = [] #: Array[ActivityStep]
+      new(diff: Diff.new, timeline: timeline, activity_timeline: activity_timeline)
+    end
+
     #: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
     def initialize(diff:, timeline:, activity_timeline: nil)
       @diff = diff

data/lib/paper_trail_diff/branch_snapshot_refresher.rb

@@ -159,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

@@ -142,9 +142,22 @@ module PaperTrailDiff
       identities.sort_by { |identity| sortable_identity(identity) }
     end
 
+    # Identities sort by type first so that mixed id types stay comparable, then
+    # naturally within one type. Ordering by the printed form instead would put
+    # id 10 before id 2, which is deterministic but reads as unsorted wherever a
+    # result is rendered.
     #: (identity) -> Array[untyped]
     def sortable_identity(identity)
-      [identity.fetch(0), identity.fetch(1).inspect]
+      [identity.fetch(0), *sortable_id(identity.fetch(1))]
+    end
+
+    #: (untyped) -> Array[untyped]
+    def sortable_id(id)
+      case id
+      when Numeric then [0, id, '']
+      when String, Symbol then [1, 0, id.to_s]
+      else [2, 0, id.inspect]
+      end
     end
 
     #: (identity) -> void

data/lib/paper_trail_diff/collection_transition.rb

@@ -7,9 +7,12 @@ module PaperTrailDiff
     attr_reader :before #: RecordSnapshot?
     attr_reader :after #: RecordSnapshot?
 
+    # The origin is recorded by serial rather than by reference, because
+    # holding it would retain every earlier snapshot at the same path for the
+    # whole timeline.
     #: (from: AssociationSnapshot, before: RecordSnapshot?, after: RecordSnapshot?) -> void
     def initialize(from:, before:, after:)
-      @from_object_id = from.object_id
+      @from_serial = from.serial
       @before = before
       @after = after
       freeze
@@ -17,9 +20,9 @@ module PaperTrailDiff
 
     #: (AssociationSnapshot) -> bool
     def from?(association)
-      @from_object_id == association.object_id
+      @from_serial == association.serial
     end
 
-    # @rbs @from_object_id: Integer
+    # @rbs @from_serial: Integer
   end
 end

data/lib/paper_trail_diff/endpoint.rb

@@ -10,10 +10,35 @@ module PaperTrailDiff
     def validate_pair!(from_endpoint, to_endpoint)
       validate!(from_endpoint)
       validate!(to_endpoint)
-      return if identity(from_endpoint) == identity(to_endpoint)
+      unless identity(from_endpoint) == identity(to_endpoint)
+        raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
+      end
+
+      validate_order!(from_endpoint, to_endpoint)
+    end
+
+    # Two versions carry no visible cue about which is earlier, so transposing
+    # them is easy to do by accident and impossible to detect afterwards: the
+    # result is a valid inverse diff and carries no direction of its own. It is
+    # also redundant, because the two orders differ only in which side of each
+    # change is `from`. A current-record endpoint is exempt: it is self-evidently
+    # the live state, so putting it first is a deliberate reverse comparison.
+    #: (untyped, untyped) -> void
+    def validate_order!(from_endpoint, to_endpoint)
+      return unless reversed_versions?(from_endpoint, to_endpoint)
+
+      raise ReversedEndpointsError,
+            'version endpoints must be given in chronological order; ' \
+            'swap them to read the same difference in the other direction'
+    end
+
+    #: (untyped, untyped) -> bool
+    def reversed_versions?(from_endpoint, to_endpoint)
+      return false unless version?(from_endpoint) && version?(to_endpoint)
 
-      raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
+      Support.compare_versions(from_endpoint, to_endpoint).positive?
     end
+    private_class_method :reversed_versions?
 
     #: (untyped) -> void
     def validate!(endpoint)

data/lib/paper_trail_diff/errors.rb

@@ -11,6 +11,9 @@ module PaperTrailDiff
   # Raised when compare endpoints do not belong to the same PaperTrail item.
   class VersionMismatchError < Error; end
 
+  # Raised when comparison endpoints are given in reverse chronological order.
+  class ReversedEndpointsError < Error; end
+
   # Raised when a live endpoint is not a clean, persisted ActiveRecord record.
   class InvalidEndpointError < Error; end
 

data/lib/paper_trail_diff/historical_association_reifier.rb

@@ -11,7 +11,10 @@ module PaperTrailDiff
         @habtm_transaction_id = habtm_version.transaction_id
       end
       @version_at = version.created_at
-      @reified_associations = {} #: Hash[Array[untyped], bool]
+      # Keyed on record identity rather than `object_id`, which Ruby may reuse
+      # once an earlier record in the same pass has been collected.
+      reified = {} #: Hash[untyped, Hash[untyped, bool]]
+      @reified_associations = reified.compare_by_identity
     end
 
     #: (untyped, Array[untyped]) -> void
@@ -24,14 +27,14 @@ module PaperTrailDiff
     # @rbs @transaction_id: untyped
     # @rbs @habtm_transaction_id: untyped
     # @rbs @version_at: untyped
-    # @rbs @reified_associations: Hash[Array[untyped], bool]
+    # @rbs @reified_associations: Hash[untyped, Hash[untyped, bool]]
 
     #: (untyped, untyped) -> void
     def reify_association(record, reflection)
-      key = [record.object_id, reflection.name]
-      return if @reified_associations[key]
+      reified = @reified_associations[record] ||= {} #: Hash[untyped, bool]
+      return if reified[reflection.name]
 
-      @reified_associations[key] = true
+      reified[reflection.name] = true
       case reflection.macro
       when :belongs_to
         reifier(:BelongsTo).reify(reflection, record, options, @transaction_id)

data/lib/paper_trail_diff/historical_snapshot_store.rb

@@ -16,14 +16,20 @@ module PaperTrailDiff
       @prepared_histories = {} #: Hash[Array[untyped], PreparedHistory]
     end
 
-    #: (untyped, Array[untyped], ?start_at: untyped) -> void
-    def prepare(record, root_versions, start_at: root_versions.first.created_at)
+    #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def prepare(
+      record,
+      root_versions,
+      start_at: root_versions.first.created_at,
+      end_at: root_versions.last.created_at
+    )
       return if @tree.empty?
 
       @prepared_history = PreparedHistoryLoader.new(
         record,
         root_versions: root_versions,
         start_at: start_at,
+        end_at: end_at,
         tree: @tree,
         traversal: @traversal
       ).call
@@ -139,6 +145,7 @@ module PaperTrailDiff
         root_ids: records.map(&:id),
         root_versions: root_versions,
         start_at: root_versions.map(&:created_at).min,
+        end_at: root_versions.map(&:created_at).max,
         tree: @tree,
         traversal: @traversal,
         live_records: @live_graph_collector.call(records)

data/lib/paper_trail_diff/prepared_association_reifier.rb

@@ -10,7 +10,10 @@ module PaperTrailDiff
       @boundary = boundary
       @habtm_boundary = habtm_boundary
       @fallback = fallback
-      @reified = {} #: Hash[Array[untyped], bool]
+      # Keyed on record identity rather than `object_id`, which Ruby may reuse
+      # once an earlier record in the same pass has been collected.
+      reified = {} #: Hash[untyped, Hash[untyped, bool]]
+      @reified = reified.compare_by_identity
     end
 
     #: (untyped, Array[untyped]) -> void
@@ -24,14 +27,14 @@ module PaperTrailDiff
     # @rbs @boundary: untyped
     # @rbs @habtm_boundary: untyped
     # @rbs @fallback: HistoricalAssociationReifier
-    # @rbs @reified: Hash[Array[untyped], bool]
+    # @rbs @reified: Hash[untyped, Hash[untyped, bool]]
 
     #: (untyped, untyped) -> void
     def reify_association(record, reflection)
-      key = [record.object_id, reflection.name]
-      return if @reified[key]
+      reified = @reified[record] ||= {} #: Hash[untyped, bool]
+      return if reified[reflection.name]
 
-      @reified[key] = true
+      reified[reflection.name] = true
       handled, records = @history.resolve(
         record,
         reflection,

data/lib/paper_trail_diff/prepared_edge_loader.rb

@@ -164,13 +164,15 @@ module PaperTrailDiff
       { model_class.name.to_s => group }
     end
 
+    # Keyed rather than scanned so that a wide edge stays linear in its width.
     #: (Array[Array[untyped]]) -> Hash[String, Array[untyped]]
     def group_ids_by_owner(pairs)
-      grouped = {} #: Hash[String, Array[untyped]]
-      pairs.each_with_object(grouped) do |(owner_id, child_id), result|
-        ids = result[owner_id.to_s] ||= []
-        ids << child_id unless ids.include?(child_id)
+      grouped = {} #: Hash[String, Hash[untyped, true]]
+      pairs.each do |owner_id, child_id|
+        ids = grouped[owner_id.to_s] ||= {} #: Hash[untyped, true]
+        ids[child_id] = true
       end
+      grouped.transform_values(&:keys)
     end
 
     #: (Hash[String, Array[untyped]], Hash[String, Array[untyped]]) -> Hash[String, Array[untyped]]

data/lib/paper_trail_diff/prepared_history_loader.rb

@@ -4,7 +4,7 @@
 module PaperTrailDiff
   # Expands the explicit association tree into a request-scoped PreparedHistory.
   class PreparedHistoryLoader
-    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?live_records: Array[untyped]) -> void
+    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
       record,
       root_versions:,
@@ -12,13 +12,14 @@ module PaperTrailDiff
       traversal:,
       root_ids: [record.id],
       start_at: root_versions.first.created_at,
+      end_at: nil,
       live_records: []
     )
       @record = record
       @root_ids = root_ids
       @tree = tree
       @traversal = traversal
-      @records = PreparedRecordIndex.new(start_at, live_records: live_records)
+      @records = PreparedRecordIndex.new(start_at, end_at: end_at, live_records: live_records)
       @history = PreparedHistory.new(@records)
       @edges = PreparedEdgeLoader.new(@records, root_versions, start_at: start_at)
       @prepared = {} #: Hash[Array[String], Array[String]]