paper_trail_diff 0.2.0 → 0.3.1

data/lib/paper_trail_diff/collection_identity_index.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Immutable positions for one collection membership and ordering.
+  class CollectionIdentityIndex
+    #: (Array[untyped]) -> void
+    def initialize(records)
+      @positions = {} #: Hash[Array[untyped], Integer]
+      @serialized_positions = {} #: Hash[Array[String], Integer]
+      @id_positions = {} #: Hash[String, Integer?]
+      records.each_with_index { |record, index| register(record, index) }
+      @positions.freeze
+      @serialized_positions.freeze
+      @id_positions.freeze
+      freeze
+    end
+
+    #: (untyped, untyped) -> Integer?
+    def position(type, id)
+      @serialized_positions[[type.to_s, id.to_s]]
+    end
+
+    #: (untyped) -> Integer?
+    def position_for_id(id)
+      @id_positions[id.to_s]
+    end
+
+    private
+
+    # @rbs @positions: Hash[Array[untyped], Integer]
+    # @rbs @serialized_positions: Hash[Array[String], Integer]
+    # @rbs @id_positions: Hash[String, Integer?]
+
+    #: (untyped, Integer) -> void
+    def register(record, index)
+      identity = record.identity
+      if @positions.key?(identity)
+        raise ArgumentError, "duplicate record identity: #{identity.inspect}"
+      end
+
+      @positions[identity] = index
+      @serialized_positions[[record.type.to_s, record.id.to_s]] = index
+      register_id(record.id, index)
+    end
+
+    #: (untyped, Integer) -> void
+    def register_id(id, index)
+      key = id.to_s
+      @id_positions[key] = @id_positions.key?(key) ? nil : index
+    end
+  end
+end

data/lib/paper_trail_diff/collection_transition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # One collection mutation between structurally adjacent snapshots.
+  class CollectionTransition
+    attr_reader :before #: RecordSnapshot?
+    attr_reader :after #: RecordSnapshot?
+
+    #: (from: AssociationSnapshot, before: RecordSnapshot?, after: RecordSnapshot?) -> void
+    def initialize(from:, before:, after:)
+      @from_object_id = from.object_id
+      @before = before
+      @after = after
+      freeze
+    end
+
+    #: (AssociationSnapshot) -> bool
+    def from?(association)
+      @from_object_id == association.object_id
+    end
+
+    # @rbs @from_object_id: Integer
+  end
+end

data/lib/paper_trail_diff/comparison_batch.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Validates and executes independent comparisons with shared live endpoint loading.
+  class ComparisonBatch
+    #: (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      comparisons,
+      live_loader:,
+      preparer:,
+      history_preparer:,
+      historical_snapshotter:,
+      live_normalizer:
+    )
+      @comparisons = comparisons
+      @live_loader = live_loader
+      @preparer = preparer
+      @history_preparer = history_preparer
+      @historical_snapshotter = historical_snapshotter
+      @live_normalizer = live_normalizer
+    end
+
+    #: () -> comparison_results
+    def call
+      pairs = comparison_pairs
+      pairs.each { |from, to| Endpoint.validate_pair!(from, to) }
+      ensure_unique_identities!(pairs)
+      prepare_endpoint_classes!(pairs)
+      live_records = load_live_records(pairs.flatten)
+      prepare_historical_batches!(pairs, live_records)
+      live_snapshots = normalize_live_records(live_records)
+
+      pairs.to_h do |from, to|
+        identity = Support.immutable_copy(Endpoint.identity(from))
+        [identity, compare(from, to, live_snapshots)]
+      end.freeze
+    end
+
+    private
+
+    # @rbs @comparisons: Array[comparison_input]
+    # @rbs @live_loader: untyped
+    # @rbs @preparer: untyped
+    # @rbs @history_preparer: untyped
+    # @rbs @historical_snapshotter: untyped
+    # @rbs @live_normalizer: untyped
+
+    #: (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
+    def compare(from, to, live_snapshots)
+      Engine.compare(snapshot(from, live_snapshots), snapshot(to, live_snapshots))
+    end
+
+    #: (untyped, Hash[identity, RecordSnapshot]) -> RecordSnapshot?
+    def snapshot(endpoint, live_snapshots)
+      return @historical_snapshotter.call(endpoint) if Endpoint.version?(endpoint)
+
+      live_snapshots.fetch(Endpoint.identity(endpoint))
+    end
+
+    #: (Array[untyped]) -> Hash[identity, untyped]
+    def load_live_records(endpoints)
+      records = endpoints.reject { |endpoint| Endpoint.version?(endpoint) }.uniq do |record|
+        Endpoint.identity(record)
+      end
+      @live_loader.call(records)
+    end
+
+    #: (Hash[identity, untyped]) -> Hash[identity, RecordSnapshot]
+    def normalize_live_records(records)
+      records.transform_values { |record| @live_normalizer.call(record) }
+    end
+
+    #: (Array[[untyped, untyped]], Hash[identity, untyped]) -> void
+    def prepare_historical_batches!(pairs, live_records)
+      grouped = historical_versions(pairs, live_records).group_by do |version|
+        Endpoint.model_class(version)
+      end
+      grouped.each_value do |versions|
+        records = versions.map { |version| live_records.fetch(Endpoint.identity(version)) }.uniq
+        @history_preparer.call(records, versions)
+      end
+    end
+
+    #: (Array[[untyped, untyped]], Hash[identity, untyped]) -> Array[untyped]
+    def historical_versions(pairs, live_records)
+      selected = pairs.flatten.select do |endpoint|
+        Endpoint.version?(endpoint) && live_records.key?(Endpoint.identity(endpoint))
+      end
+      selected.uniq { |version| [version.class.name, version.id] }
+    end
+
+    #: () -> Array[[untyped, untyped]]
+    def comparison_pairs
+      unless @comparisons.is_a?(Array)
+        raise ConfigurationError, 'comparisons: must be an array of from:/to: hashes'
+      end
+
+      @comparisons.map.with_index do |comparison, index|
+        comparison_pair(comparison, index)
+      end
+    end
+
+    #: (untyped, Integer) -> [untyped, untyped]
+    def comparison_pair(comparison, index)
+      valid_comparison!(comparison, index)
+      [endpoint(comparison, :from), endpoint(comparison, :to)]
+    end
+
+    #: (untyped, Integer) -> void
+    def valid_comparison!(comparison, index)
+      if comparison.is_a?(Hash)
+        keys = comparison.keys.map(&:to_s)
+        return if keys.sort == %w[from to] && keys.length == 2
+      end
+
+      message = "comparisons[#{index}]: must contain exactly from: and to:"
+      raise ConfigurationError, message
+    end
+
+    #: (Hash[untyped, untyped], Symbol) -> untyped
+    def endpoint(comparison, name)
+      comparison.key?(name) ? comparison.fetch(name) : comparison.fetch(name.to_s)
+    end
+
+    #: (Array[[untyped, untyped]]) -> void
+    def ensure_unique_identities!(pairs)
+      identities = pairs.map { |from, _to| Endpoint.identity(from) }
+      return if identities.uniq.length == identities.length
+
+      raise ConfigurationError, 'comparisons: root identities must be unique'
+    end
+
+    #: (Array[[untyped, untyped]]) -> void
+    def prepare_endpoint_classes!(pairs)
+      endpoint_requirements(pairs).each do |model_class, historical|
+        @preparer.call(model_class, historical: historical)
+      end
+    end
+
+    #: (Array[[untyped, untyped]]) -> Hash[untyped, bool]
+    def endpoint_requirements(pairs)
+      requirements = {} #: Hash[untyped, bool]
+      pairs.flatten.each_with_object(requirements) do |endpoint, collected|
+        historical = Endpoint.version?(endpoint)
+        model_class = historical ? Endpoint.model_class(endpoint) : endpoint.class
+        collected[model_class] = collected.fetch(model_class, false) || historical
+      end
+    end
+  end
+end

data/lib/paper_trail_diff/engine.rb

@@ -124,51 +124,11 @@ module PaperTrailDiff
 
       #: (AssociationSnapshot, AssociationSnapshot) -> CollectionAssociationDiff
       def compare_collection(from_association, to_association)
-        from_records = index_records(from_association.records)
-        to_records = index_records(to_association.records)
-
-        CollectionAssociationDiff.new(
-          kind: from_association.kind,
-          added: records_missing_from(to_records, from_records),
-          removed: records_missing_from(from_records, to_records),
-          changed: changed_records(from_records, to_records)
-        )
-      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)
-
-          compare_record(from_record, to_record)
-        end
-      end
-
-      #: (Array[RecordSnapshot]) -> Hash[Array[untyped], RecordSnapshot]
-      def index_records(records)
-        index = {} #: Hash[identity, RecordSnapshot]
-        records.each do |record|
-          identity = record.identity
-          if index.key?(identity)
-            raise ArgumentError, "duplicate record identity: #{identity.inspect}"
-          end
-
-          index[identity] = record
-        end
-        index
-      end
-
-      #: (Array[Array[untyped]]) -> Array[Array[untyped]]
-      def sorted_identities(identities)
-        identities.sort_by { |type, id| [type, id.inspect] }
+        CollectionComparator.new(
+          from_association,
+          to_association,
+          record_comparer: method(:compare_record)
+        ).call
       end
 
       #: (RecordSnapshot?, RecordSnapshot?) -> bool

data/lib/paper_trail_diff/errors.rb

@@ -14,9 +14,18 @@ module PaperTrailDiff
   # Raised when a live endpoint is not a clean, persisted ActiveRecord record.
   class InvalidEndpointError < Error; end
 
+  # Raised when reload opt-out encounters an association that was not preloaded.
+  class UnloadedAssociationError < InvalidEndpointError; end
+
   # Raised when a timeline boundary is absent or the requested range is reversed.
   class InvalidTimelineRangeError < Error; end
 
+  # Raised when `within` is not a finite, chronological range of time-like values.
+  class InvalidTimeRangeError < InvalidTimelineRangeError; end
+
+  # Raised when an in-range mutation has no later root boundary for reconstruction.
+  class IncompleteTimeRangeError < InvalidTimelineRangeError; end
+
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error; end
 

data/lib/paper_trail_diff/historical_snapshot_store.rb

@@ -10,22 +10,35 @@ module PaperTrailDiff
       @traversal = traversal
       @normalizer = normalizer
       @preparer = preparer
+      @live_graph_collector = LiveGraphCollector.new(tree: tree, traversal: traversal)
       @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
       @prepared_history = nil #: PreparedHistory?
+      @prepared_histories = {} #: Hash[Array[untyped], PreparedHistory]
     end
 
-    #: (untyped, Array[untyped]) -> void
-    def prepare(record, root_versions)
+    #: (untyped, Array[untyped], ?start_at: untyped) -> void
+    def prepare(record, root_versions, start_at: root_versions.first.created_at)
       return if @tree.empty?
 
       @prepared_history = PreparedHistoryLoader.new(
         record,
         root_versions: root_versions,
+        start_at: start_at,
         tree: @tree,
         traversal: @traversal
       ).call
     end
 
+    # Prepares selected history for several roots of the same model class.
+    #: (Array[untyped], Array[untyped]) -> void
+    def prepare_batch(records, root_versions)
+      return if @tree.empty? || records.empty? || root_versions.empty?
+
+      Instrumentation.instrument('prepare_history', batch_payload(records, root_versions)) do
+        register_batch(records, root_versions)
+      end
+    end
+
     #: (untyped, untyped) -> RecordSnapshot?
     def call(root_endpoint, context_endpoint)
       key = snapshot_key(root_endpoint, context_endpoint)
@@ -74,7 +87,7 @@ module PaperTrailDiff
         context_version,
         habtm_version: habtm_version
       )
-      history = @prepared_history
+      history = @prepared_histories[context_key(context_version)] || @prepared_history
       return fallback unless history
 
       PreparedAssociationReifier.new(
@@ -85,14 +98,53 @@ module PaperTrailDiff
       )
     end
 
+    #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    def record_transition(version)
+      history = @prepared_history
+      return unless history
+
+      history.record_transition(Endpoint.model_class(version), version.item_id, version)
+    end
+
     private
 
     # @rbs @tree: AssociationTree
     # @rbs @traversal: AssociationTraversal
     # @rbs @normalizer: SnapshotNormalizer
     # @rbs @preparer: untyped
+    # @rbs @live_graph_collector: LiveGraphCollector
     # @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]
     # @rbs @prepared_history: PreparedHistory?
+    # @rbs @prepared_histories: Hash[Array[untyped], PreparedHistory]
+
+    #: (untyped) -> Array[untyped]
+    def context_key(endpoint)
+      [endpoint.class.name, endpoint.id]
+    end
+
+    #: (Array[untyped], Array[untyped]) -> Hash[Symbol, untyped]
+    def batch_payload(records, root_versions)
+      {
+        root_count: records.length,
+        version_count: root_versions.length,
+        model_type: records.first.class.base_class.name.to_s,
+        batched: true
+      }
+    end
+
+    #: (Array[untyped], Array[untyped]) -> void
+    def register_batch(records, root_versions)
+      history = PreparedHistoryLoader.new(
+        records.first,
+        root_ids: records.map(&:id),
+        root_versions: root_versions,
+        start_at: root_versions.map(&:created_at).min,
+        tree: @tree,
+        traversal: @traversal,
+        live_records: @live_graph_collector.call(records)
+      ).call
+      root_versions.each { |version| @prepared_histories[context_key(version)] = history }
+    end
 
     #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
     def snapshot_from_version(root_version, context_version, tree:, normalizer:)

data/lib/paper_trail_diff/instrumentation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'active_support/notifications'
+
+module PaperTrailDiff
+  # Emits quiet, namespaced runtime events for application-owned diagnostics.
+  module Instrumentation
+    module_function
+
+    #: (String | Symbol, Hash[Symbol, untyped]) { () -> untyped } -> untyped
+    def instrument(event, payload, &)
+      active_support = Object.const_get(:ActiveSupport) #: untyped
+      notifications = active_support.const_get(:Notifications) #: untyped
+      notifications.instrument(
+        "#{event}.paper_trail_diff",
+        payload,
+        &
+      )
+    end
+
+    #: (association_paths: Array[String], reload_live_endpoints: bool) -> Hash[Symbol, untyped]
+    def comparison_payload(association_paths:, reload_live_endpoints:)
+      {
+        association_paths: association_paths,
+        reload_live_endpoints: reload_live_endpoints
+      }
+    end
+  end
+end

data/lib/paper_trail_diff/live_endpoint_batch_loader.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Reloads current-record endpoints and their explicitly selected associations in batches.
+  class LiveEndpointBatchLoader
+    #: (tree: AssociationTree) -> void
+    def initialize(tree:)
+      @tree = tree
+    end
+
+    #: (Array[untyped]) -> Hash[identity, untyped]
+    def call(records)
+      loaded = {} #: Hash[identity, untyped]
+      records.group_by(&:class).each do |model_class, grouped|
+        load_group(model_class, grouped).each do |record|
+          loaded[Endpoint.identity(record)] = record
+        end
+      end
+      ensure_all_loaded!(records, loaded)
+      loaded
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+
+    #: (untyped, Array[untyped]) -> Array[untyped]
+    def load_group(model_class, records)
+      relation = model_class.unscoped.where(model_class.primary_key => records.map(&:id).uniq)
+      loaded = relation.to_a
+      preload_tree(loaded, @tree)
+      loaded
+    end
+
+    #: (Array[untyped], AssociationTree) -> void
+    def preload_tree(records, tree)
+      return if records.empty? || tree.empty?
+
+      records.group_by(&:class).each do |model_class, grouped_records|
+        preload_model_tree(model_class, grouped_records, tree)
+      end
+    end
+
+    #: (untyped, Array[untyped], AssociationTree) -> void
+    def preload_model_tree(model_class, records, tree)
+      batch, individual = selected_reflections(model_class, tree).partition do |reflection, _|
+        batch_safe?(records.fetch(0), reflection)
+      end
+      preload_batch(records, batch.map { |reflection, _| reflection.name })
+      preload_subtrees(records, batch, individually: false)
+      preload_subtrees(records, individual, individually: true)
+    end
+
+    #: (untyped, AssociationTree) -> Array[[untyped, AssociationTree]]
+    def selected_reflections(model_class, tree)
+      tree.children.map do |name, subtree|
+        reflection = model_class.reflect_on_association(name)
+        raise ConfigurationError, "unknown association: #{name}" unless reflection
+
+        [reflection, subtree]
+      end
+    end
+
+    #: (Array[untyped], Array[[untyped, AssociationTree]], individually: bool) -> void
+    def preload_subtrees(records, reflections, individually:)
+      reflections.each do |reflection, subtree|
+        children = if individually
+                     load_individually(records, reflection)
+                   else
+                     targets(records, reflection)
+                   end
+        preload_tree(children, subtree)
+      end
+    end
+
+    #: (Array[untyped], Array[Symbol]) -> void
+    def preload_batch(records, associations)
+      return if associations.empty?
+
+      active_record_preloader.new(
+        records: records,
+        associations: associations
+      ).call
+    end
+
+    #: () -> untyped
+    def active_record_preloader
+      active_record = Object.const_get(:ActiveRecord)
+      active_record.const_get(:Associations).const_get(:Preloader)
+    end
+
+    #: (untyped, untyped) -> bool
+    def batch_safe?(record, reflection)
+      scope = reflection.scope
+      return false if scope && !scope.arity.zero?
+      return true unless reflection.collection?
+
+      relation = record.association(reflection.name).scope
+      relation.limit_value.nil? && relation.offset_value.nil?
+    end
+
+    #: (Array[untyped], untyped) -> Array[untyped]
+    def load_individually(records, reflection)
+      unique_records(records.flat_map do |record|
+        Array(record.association(reflection.name).load_target)
+      end)
+    end
+
+    #: (Array[untyped], untyped) -> Array[untyped]
+    def targets(records, reflection)
+      unique_records(records.flat_map do |record|
+        Array(record.association(reflection.name).target)
+      end)
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def unique_records(records)
+      records.compact.uniq do |record|
+        [record.class.base_class.name.to_s, record.id.to_s]
+      end
+    end
+
+    #: (Array[untyped], Hash[identity, untyped]) -> void
+    def ensure_all_loaded!(records, loaded)
+      missing = records.map { |record| Endpoint.identity(record) }.uniq - loaded.keys
+      return if missing.empty?
+
+      message = 'current record endpoint could not be reloaded from the database'
+      raise InvalidEndpointError, message
+    end
+  end
+end

data/lib/paper_trail_diff/live_endpoint_provider.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects safe reload or validated caller-owned loading for current endpoints.
+  class LiveEndpointProvider
+    attr_reader :reload #: bool
+    attr_reader :comparison_payload #: Hash[Symbol, untyped]
+
+    #: (tree: AssociationTree, traversal: AssociationTraversal, reload: bool) -> void
+    def initialize(tree:, traversal:, reload:)
+      unless [true, false].include?(reload)
+        raise ConfigurationError, 'reload_live_endpoints: must be true or false'
+      end
+
+      @reload = reload
+      @comparison_payload = Instrumentation.comparison_payload(
+        association_paths: tree.paths,
+        reload_live_endpoints: reload
+      ).freeze
+      @loader = if reload
+                  LiveEndpointBatchLoader.new(tree: tree)
+                else
+                  PreloadedEndpointBatchLoader.new(tree: tree, traversal: traversal)
+                end
+    end
+
+    #: (Array[untyped]) -> Hash[identity, untyped]
+    def call(records)
+      Instrumentation.instrument('load_live_endpoints', payload(records)) do
+        @loader.call(records)
+      end
+    end
+
+    private
+
+    # @rbs @loader: untyped
+
+    #: (Array[untyped]) -> Hash[Symbol, untyped]
+    def payload(records)
+      {
+        endpoint_count: records.length,
+        model_types: records.map { |record| record.class.base_class.name.to_s }.uniq.sort.freeze,
+        reload_live_endpoints: reload
+      }
+    end
+  end
+end

data/lib/paper_trail_diff/live_graph_collector.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Flattens an already-preloaded, explicitly bounded live association graph.
+  class LiveGraphCollector
+    #: (tree: AssociationTree, traversal: AssociationTraversal) -> void
+    def initialize(tree:, traversal:)
+      @tree = tree
+      @traversal = traversal
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def call(records)
+      collected = {} #: Hash[Array[untyped], untyped]
+      collect(records, @tree, path: '', into: collected)
+      collected.values
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @traversal: AssociationTraversal
+
+    #: (Array[untyped], AssociationTree, path: String, into: Hash[Array[untyped], untyped]) -> void
+    def collect(records, tree, path:, into:)
+      records.each { |record| into[Endpoint.identity(record)] = record }
+      records.group_by(&:class).each do |model_class, grouped|
+        collect_group(model_class, grouped, tree, path: path, into: into)
+      end
+    end
+
+    #: (untyped, Array[untyped], AssociationTree, path: String, into: Hash[Array[untyped], untyped]) -> void
+    def collect_group(model_class, records, tree, path:, into:)
+      @traversal.reflections_for(model_class, tree, path: path).each do |reflection|
+        subtree = tree.child(reflection.name)
+        next unless subtree
+
+        child_path = Support.association_path(path, reflection.name.to_s)
+        collect(children_for(records, reflection), subtree, path: child_path, into: into)
+      end
+    end
+
+    #: (Array[untyped], untyped) -> Array[untyped]
+    def children_for(records, reflection)
+      records.flat_map do |record|
+        associated = record.public_send(reflection.name)
+        reflection.collection? ? associated.to_a : Array(associated).compact
+      end
+    end
+  end
+end