paper_trail_diff 0.2.0 → 0.3.0

data/lib/paper_trail_diff/snapshot.rb

@@ -42,6 +42,21 @@ module PaperTrailDiff
     SUPPORTED_KINDS = %i[belongs_to has_one has_many has_and_belongs_to_many].freeze
     private_constant :COLLECTION_KINDS, :SUPPORTED_KINDS
 
+    # Non-semantic memoization shared by structurally adjacent snapshots. The
+    # cached value is derived only from frozen records and is itself immutable.
+    class IdentityIndexCache
+      #: () -> void
+      def initialize
+        @index = nil #: CollectionIdentityIndex?
+      end
+
+      #: (Array[RecordSnapshot]) -> CollectionIdentityIndex
+      def index(records)
+        @index ||= CollectionIdentityIndex.new(records)
+      end
+    end
+    private_constant :IdentityIndexCache
+
     class << self
       #: (Symbol) -> bool
       def collection_kind?(kind)
@@ -52,8 +67,8 @@ module PaperTrailDiff
     attr_reader :kind #: Symbol
     attr_reader :records #: Array[RecordSnapshot]
 
-    #: (kind: Symbol, records: Array[RecordSnapshot]) -> void
-    def initialize(kind:, records:)
+    #: (kind: Symbol, records: Array[RecordSnapshot], ?identity_index_cache: untyped, ?transition: CollectionTransition?) -> void
+    def initialize(kind:, records:, identity_index_cache: nil, transition: nil)
       unless SUPPORTED_KINDS.include?(kind)
         raise ArgumentError, "unsupported association kind: #{kind.inspect}"
       end
@@ -62,14 +77,62 @@ module PaperTrailDiff
       end
 
       @kind = kind
-      @records = records.dup.freeze
+      @records = records.frozen? ? records : records.dup.freeze
+      @identity_index_cache = identity_index_cache || IdentityIndexCache.new
+      @transition = transition
       freeze
     end
 
+    # Builds a structurally adjacent collection snapshot for internal activity carry-forward.
+    #: (Array[RecordSnapshot], before: RecordSnapshot?, after: RecordSnapshot?, membership_preserved: bool) -> AssociationSnapshot
+    def transition_to(records, before:, after:, membership_preserved:)
+      cache = membership_preserved ? @identity_index_cache : nil
+      transition = if before || after
+                     CollectionTransition.new(from: self, before: before, after: after)
+                   end
+      self.class.new(
+        kind: kind,
+        records: records,
+        identity_index_cache: cache,
+        transition: transition
+      )
+    end
+
+    #: (AssociationSnapshot) -> CollectionTransition?
+    def transition_from(association)
+      @transition if @transition&.from?(association)
+    end
+
+    #: (untyped, untyped) -> Integer?
+    def position(type, id)
+      identity_index.position(type, id)
+    end
+
+    #: (untyped) -> Integer?
+    def position_for_id(id)
+      identity_index.position_for_id(id)
+    end
+
+    #: () -> void
+    def validate_unique_identities!
+      identity_index
+      nil
+    end
+
     #: () -> Hash[Symbol, untyped]
     def to_h
       { kind: kind, records: Support.serialize(records) }
     end
+
+    private
+
+    # @rbs @identity_index_cache: untyped
+    # @rbs @transition: CollectionTransition?
+
+    #: () -> CollectionIdentityIndex
+    def identity_index
+      @identity_index_cache.index(records)
+    end
   end
 
   # An immutable, ActiveRecord-independent representation of a reified record.

data/lib/paper_trail_diff/support.rb

@@ -62,6 +62,15 @@ module PaperTrailDiff
       parent.empty? ? name : "#{parent}.#{name}"
     end
 
+    #: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
+    def merge_record_groups(existing, incoming)
+      existing.merge(incoming) do |_name, left, right|
+        merged = left.merge(right, ids: (left.fetch(:ids) | right.fetch(:ids)))
+        owners = merge_record_owners(left[:owners], right[:owners])
+        owners ? merged.merge(owners: owners) : merged
+      end
+    end
+
     #: (untyped) -> untyped
     def duplicate_and_freeze(value)
       value.dup.freeze
@@ -70,6 +79,15 @@ module PaperTrailDiff
     end
     private_class_method :duplicate_and_freeze
 
+    #: (Hash[String, Array[untyped]]?, Hash[String, Array[untyped]]?) -> Hash[String, Array[untyped]]?
+    def merge_record_owners(left, right)
+      return right unless left
+      return left unless right
+
+      left.merge(right) { |_owner, first, second| first | second }
+    end
+    private_class_method :merge_record_owners
+
     #: (untyped) -> bool
     def paper_trail_diff_value?(value)
       class_name = value.class.name

data/lib/paper_trail_diff/time_activity_timeline_builder.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Builds activity views for mutations selected by a wall-clock range.
+  class TimeActivityTimelineBuilder
+    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
+    def initialize(record, range:, tree:, snapshotter:)
+      @record = record
+      @range = range
+      @tree = tree
+      @snapshotter = snapshotter
+    end
+
+    #: () -> Array[ActivityStep]
+    def build
+      history, = history_and_versions
+      history.steps
+    end
+
+    #: () -> Analysis
+    def analyze
+      history, root_versions = history_and_versions
+      Analysis.new(
+        diff: Engine.compare(history.first_snapshot, history.last_snapshot),
+        timeline: root_steps(root_versions, history.root_snapshots),
+        activity_timeline: history.steps
+      )
+    end
+
+    private
+
+    # @rbs @record: untyped
+    # @rbs @range: TimelineRange
+    # @rbs @tree: AssociationTree
+    # @rbs @snapshotter: untyped
+
+    #: () -> [ActivityHistory, Array[untyped]]
+    def history_and_versions
+      root_versions = @range.select(context_required: !@tree.empty?)
+      return [ActivityHistory.empty, root_versions] if root_versions.empty?
+
+      prepare_history(root_versions)
+      events = collect_events(root_versions)
+      return [ActivityHistory.empty, root_versions] unless time_events?(events)
+
+      history = ActivityHistoryBuilder.new(
+        root_versions,
+        events,
+        @snapshotter,
+        include_step: ->(event) { @range.include?(event.version) }
+      ).call
+      [history, root_versions]
+    end
+
+    #: (Array[untyped]) -> void
+    def prepare_history(root_versions)
+      return unless @snapshotter.respond_to?(:prepare)
+
+      @snapshotter.prepare(@record, root_versions, start_at: @range.begin_time)
+    end
+
+    #: (Array[untyped]) -> Array[ActivityEvent]
+    def collect_events(root_versions)
+      ActivityVersionCollector.new(
+        @record,
+        root_versions: root_versions,
+        tree: @tree,
+        traversal: AssociationTraversal.new(@tree),
+        range_start: @range.begin_time,
+        range_end: root_versions.last
+      ).call
+    end
+
+    #: (Array[ActivityEvent]) -> bool
+    def time_events?(events)
+      selected = events.select { |event| @range.include?(event.version) }
+      return false if selected.empty?
+      return true if later_event?(selected.last, events)
+
+      message = 'time range requires a later activity boundary to reconstruct its final change'
+      raise IncompleteTimeRangeError, message
+    end
+
+    #: (ActivityEvent, Array[ActivityEvent]) -> bool
+    def later_event?(selected, events)
+      events.any? do |event|
+        Support.compare_versions(selected.version, event.version).negative?
+      end
+    end
+
+    #: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    def root_steps(root_versions, root_snapshots)
+      snapshots = root_versions.map do |version|
+        root_snapshots.fetch(version_key(version))
+      end
+      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/time_range.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Validates and applies a finite wall-clock range without loading model state.
+  class TimeRange
+    attr_reader :begin_time #: Time
+    attr_reader :end_time #: Time
+
+    #: (untyped) -> void
+    def initialize(value)
+      unless value.is_a?(Range) && value.begin && value.end
+        raise InvalidTimeRangeError, '`within` must be a finite Range'
+      end
+
+      @begin_time = coerce_time(value.begin, boundary: :begin)
+      @end_time = coerce_time(value.end, boundary: :end)
+      @exclude_end = value.exclude_end?
+      validate_order!
+      freeze
+    end
+
+    #: () -> bool
+    def exclude_end?
+      @exclude_end
+    end
+
+    #: (untyped) -> bool
+    def include?(value)
+      timestamp = coerce_time(value, boundary: :timestamp)
+      return false if timestamp < begin_time
+
+      exclude_end? ? timestamp < end_time : timestamp <= end_time
+    end
+
+    #: (untyped) -> untyped
+    def scope(relation)
+      relation.where(created_at: query_range)
+    end
+
+    #: (untyped) -> untyped
+    def trailing_scope(relation)
+      column = relation.klass.arel_table[:created_at]
+      predicate = exclude_end? ? column.gteq(end_time) : column.gt(end_time)
+      relation.where(predicate)
+    end
+
+    private
+
+    # @rbs @exclude_end: bool
+
+    #: () -> Range[Time]
+    def query_range
+      exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
+    end
+
+    #: (untyped, boundary: Symbol) -> Time
+    def coerce_time(value, boundary:)
+      unless value.respond_to?(:to_time)
+        raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
+      end
+
+      time_value(value).getutc.freeze
+    rescue ArgumentError, NoMethodError, TypeError => e
+      raise InvalidTimeRangeError,
+            "`within` #{boundary} must be time-like",
+            cause: e
+    end
+
+    #: (untyped) -> Time
+    def time_value(value)
+      return value if value.is_a?(Time)
+
+      utc = value.utc if value.respond_to?(:utc)
+      utc.is_a?(Time) ? utc : value.to_time
+    end
+
+    #: () -> void
+    def validate_order!
+      return unless begin_time > end_time
+
+      raise InvalidTimeRangeError, '`within` beginning must not follow its end'
+    end
+  end
+end

data/lib/paper_trail_diff/time_version_range.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects in-range root versions plus one later reconstruction boundary.
+  class TimeVersionRange
+    #: (untyped, time_range: TimeRange) -> void
+    def initialize(record, time_range:)
+      @record = record
+      @time_range = time_range
+    end
+
+    #: (?context_required: bool) -> Array[untyped]
+    def select(context_required: false)
+      relation = versions_relation
+      selected = ordered(@time_range.scope(relation).to_a)
+      empty = [] #: Array[untyped]
+      return empty.freeze if selected.empty? && !context_required
+
+      trailing = trailing_version(relation)
+      unless trailing
+        message = 'time range requires a later root version to reconstruct its final change'
+        raise IncompleteTimeRangeError, message
+      end
+
+      (selected + [trailing]).freeze
+    end
+
+    private
+
+    # @rbs @record: untyped
+    # @rbs @time_range: TimeRange
+
+    #: () -> untyped
+    def versions_relation
+      association_name = @record.class.versions_association_name
+      @record.public_send(association_name)
+    rescue NoMethodError => e
+      message = 'record does not expose a PaperTrail version history'
+      raise InvalidTimelineRangeError, message, cause: e
+    end
+
+    #: (untyped) -> untyped
+    def trailing_version(relation)
+      @time_range.trailing_scope(relation).reorder(created_at: :asc, id: :asc).first
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def ordered(versions)
+      versions.sort_by { |version| Support.chronological_version_key(version) }
+    end
+  end
+end

data/lib/paper_trail_diff/timeline_builder.rb

@@ -4,11 +4,10 @@
 module PaperTrailDiff
   # Selects and compares a chronological slice of a record's version history.
   class TimelineBuilder
-    #: (untyped, from: untyped, to: untyped, snapshotter: untyped) -> void
-    def initialize(record, from:, to:, snapshotter:)
+    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped) -> void
+    def initialize(record, from:, to:, snapshotter:, within: nil)
       @record = record
-      @from = from
-      @to = to
+      @range = TimelineRange.new(record, from: from, to: to, within: within)
       @snapshotter = snapshotter
     end
 
@@ -30,12 +29,13 @@ module PaperTrailDiff
     private
 
     # @rbs @record: untyped
-    # @rbs @from: untyped
-    # @rbs @to: untyped
+    # @rbs @range: TimelineRange
     # @rbs @snapshotter: untyped
 
     #: (Array[untyped]) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
     def compare_history(versions)
+      return empty_history if versions.empty?
+
       @snapshotter.prepare(@record, versions) if @snapshotter.respond_to?(:prepare)
       first_snapshot = @snapshotter.call(versions.first)
       previous_snapshot = first_snapshot
@@ -52,9 +52,15 @@ module PaperTrailDiff
       [steps, first_snapshot, previous_snapshot]
     end
 
+    #: () -> [Array[Step], nil, nil]
+    def empty_history
+      steps = [] #: Array[Step]
+      [steps.freeze, nil, nil]
+    end
+
     #: () -> Array[untyped]
     def selected_versions
-      VersionRange.new(@record, from: @from, to: @to).select
+      @range.select
     end
   end
 end

data/lib/paper_trail_diff/timeline_range.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Chooses explicit-version or wall-clock selection for one timeline request.
+  class TimelineRange
+    attr_reader :from #: untyped
+    attr_reader :to #: untyped
+    attr_reader :time_range #: TimeRange?
+
+    #: (untyped, from: untyped, to: untyped, within: untyped) -> void
+    def initialize(record, from:, to:, within:)
+      @record = record
+      @from = from
+      @to = to
+      @time_range = build_time_range(within)
+      validate_mode!
+      freeze
+    end
+
+    #: (?context_required: bool) -> Array[untyped]
+    def select(context_required: false)
+      range = time_range
+      if range
+        return TimeVersionRange.new(@record, time_range: range).select(
+          context_required: context_required
+        )
+      end
+
+      VersionRange.new(@record, from: @from, to: @to).select
+    end
+
+    #: () -> bool
+    def time?
+      !time_range.nil?
+    end
+
+    #: () -> Time?
+    def begin_time
+      time_range&.begin_time
+    end
+
+    #: (untyped) -> bool
+    def include?(version)
+      range = time_range
+      !range || range.include?(version.created_at)
+    end
+
+    private
+
+    # @rbs @record: untyped
+    # @rbs @from: untyped
+    # @rbs @to: untyped
+
+    #: (untyped) -> TimeRange?
+    def build_time_range(within)
+      TimeRange.new(within) unless within.nil?
+    end
+
+    #: () -> void
+    def validate_mode!
+      if time?
+        return if @from.nil? && @to.nil?
+
+        raise InvalidTimelineRangeError, '`within` cannot be combined with `from` or `to`'
+      end
+      return unless @from.nil? || @to.nil?
+
+      raise InvalidTimelineRangeError, 'provide both `from` and `to`, or provide `within`'
+    end
+  end
+end

data/lib/paper_trail_diff/version.rb

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

data/lib/paper_trail_diff/version_association_candidate_scope.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects association activity from a boundary forward plus the state at that boundary.
+  class VersionAssociationCandidateScope
+    #: (untyped, untyped, ?end_at: untyped) -> void
+    def initialize(version_class, start_at, end_at: nil)
+      @version_class = version_class
+      @start_at = start_at
+      @end_at = end_at
+    end
+
+    #: (untyped) -> untyped
+    def call(relation)
+      return relation unless @start_at
+
+      relation.where(candidate_condition)
+    end
+
+    private
+
+    # @rbs @version_class: untyped
+    # @rbs @start_at: untyped
+    # @rbs @end_at: untyped
+
+    #: () -> String
+    def candidate_condition # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      connection = @version_class.connection
+      outer = connection.quote_table_name(@version_class.table_name)
+      later = connection.quote_table_name('paper_trail_diff_later_versions')
+      start_at = connection.quote(@start_at)
+      destroyed = connection.quote('destroy')
+      activity = activity_condition(outer, start_at)
+      compact_sql(<<~SQL)
+        (
+          #{activity}
+          OR (
+            #{column(outer, 'created_at')} < #{start_at}
+            AND #{column(outer, 'event')} != #{destroyed}
+            AND NOT EXISTS (
+              SELECT 1
+                FROM #{outer} #{later}
+               WHERE #{column(later, 'item_type')} = #{column(outer, 'item_type')}
+                 AND #{column(later, 'item_id')} = #{column(outer, 'item_id')}
+                 AND #{column(later, 'created_at')} < #{start_at}
+                 AND #{column(later, 'created_at')} > #{column(outer, 'created_at')}
+            )
+          )
+        )
+      SQL
+    end
+
+    #: (String, String) -> String
+    def activity_condition(table, start_at)
+      condition = "#{column(table, 'created_at')} >= #{start_at}"
+      return condition unless @end_at
+
+      end_at = @version_class.connection.quote(@end_at)
+      "(#{condition} AND #{column(table, 'created_at')} <= #{end_at})"
+    end
+
+    #: (String, String) -> String
+    def column(table, name)
+      "#{table}.#{@version_class.connection.quote_column_name(name)}"
+    end
+
+    #: (String) -> String
+    def compact_sql(sql)
+      sql.gsub(/\s+/, ' ').strip
+    end
+  end
+end