paper_trail_diff 0.12.0 → 0.13.1

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, record_transition: 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, ?prepared_record_after: untyped) -> void
     def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
       tree:,
       ignore_policy:,
@@ -14,7 +14,8 @@ module PaperTrailDiff
       full_snapshotter:,
       partial_snapshotter:,
       association_reader:,
-      record_transition:
+      record_transition:,
+      prepared_record_after: nil
     )
       @tree = tree
       @ignore_policy = ignore_policy
@@ -24,16 +25,14 @@ module PaperTrailDiff
       @partial_snapshotter = partial_snapshotter
       @components = {} #: Hash[Array[String], [AssociationTree, SnapshotNormalizer]]
       @event_refresher = ActivityEventSnapshotRefresher.new(
-        traversal: traversal,
-        pool: pool,
+        traversal: traversal, pool: pool,
         components: method(:components),
         association_reader: association_reader,
-        record_transition: record_transition
+        record_transition: record_transition,
+        prepared_record_after: prepared_record_after
       )
       @root_refresher = ActivityRootSnapshotRefresher.new(
-        tree: tree,
-        traversal: traversal,
-        normalizer: normalizer,
+        tree: tree, traversal: traversal, normalizer: normalizer,
         record_after: @event_refresher.method(:record_after),
         changeset: @event_refresher.method(:deserialized_changeset),
         partial_snapshotter: method(:partial_snapshot)

data/lib/paper_trail_diff/collection_comparator.rb

@@ -28,25 +28,21 @@ module PaperTrailDiff
     # @rbs @to: AssociationSnapshot
     # @rbs @record_comparer: untyped
 
+    # A transition names the one record that changed between adjacent
+    # snapshots. With matching identities it is an update; otherwise the
+    # before record left and the after record joined.
     #: (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
+      if before && after && before.identity == after.identity
+        change = @record_comparer.call(before, after)
+        return difference(added: [], removed: [], changed: change ? [change] : [])
+      end
 
-      @record_comparer.call(before, after)
+      difference(added: [after].compact, removed: [before].compact, changed: [])
     end
 
     #: () -> Array[RecordChange]?
@@ -70,17 +66,16 @@ module PaperTrailDiff
 
     #: (Array[RecordSnapshot], Array[RecordSnapshot]) -> Array[[RecordSnapshot, RecordSnapshot]]?
     def collect_aligned_pairs(from_records, to_records)
-      seen = {} #: Hash[identity, bool]
+      seen = Set.new #: Set[identity]
       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)
+        raise_duplicate_identity!(identity) unless seen.add?(identity)
         return unless identity == to_record.identity
 
-        seen[identity] = true
         changed << [from_record, to_record] unless from_record.equal?(to_record)
         index += 1
       end
@@ -148,21 +143,24 @@ module PaperTrailDiff
     # result is rendered.
     #: (identity) -> Array[untyped]
     def sortable_identity(identity)
-      [identity.fetch(0), *sortable_id(identity.fetch(1))]
+      [identity.fetch(0), sortable_id(identity.fetch(1))]
     end
 
+    # Only the order of the group numbers matters, so moving the lowest one
+    # down or the highest one up changes nothing; the spec checks the order.
+    # mutant:disable
     #: (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]
+      when Numeric then [0, id]
+      when String, Symbol then [1, id.to_s]
+      else [2, id.inspect]
       end
     end
 
     #: (identity) -> void
     def raise_duplicate_identity!(identity)
-      raise ArgumentError, "duplicate record identity: #{identity.inspect}"
+      raise ArgumentError, "duplicate record identity: #{identity}"
     end
   end
 end

data/lib/paper_trail_diff/collection_identity_index.rb

@@ -6,19 +6,16 @@ module PaperTrailDiff
   class CollectionIdentityIndex
     #: (Array[untyped]) -> void
     def initialize(records)
-      @positions = {} #: Hash[Array[untyped], Integer]
+      @identities = Set.new #: Set[Array[untyped]]
       @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?
+    #: (String, untyped) -> Integer?
     def position(type, id)
-      @serialized_positions[[type.to_s, id.to_s]]
+      @serialized_positions[[type, id.to_s]]
     end
 
     #: (untyped) -> Integer?
@@ -28,26 +25,25 @@ module PaperTrailDiff
 
     private
 
-    # @rbs @positions: Hash[Array[untyped], Integer]
+    # @rbs @identities: Set[Array[untyped]]
     # @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}"
+      unless @identities.add?(identity)
+        raise ArgumentError, "duplicate record identity: #{identity}"
       end
 
-      @positions[identity] = index
-      @serialized_positions[[record.type.to_s, record.id.to_s]] = index
+      @serialized_positions[[record.type, 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
+      @id_positions[key] = (index unless @id_positions.key?(key))
     end
   end
 end

data/lib/paper_trail_diff/deleted_analysis_batch.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Analyzes missing roots together without pretending that they have live rows.
+  class DeletedAnalysisBatch
+    #: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, ?version_scope: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      model, identities:, time_range:, analyzer:, history_preparer:, version_scope: nil
+    )
+      @model = model
+      @identities = identities
+      @time_range = time_range
+      @analyzer = analyzer
+      @history_preparer = history_preparer
+      @version_scope = version_scope
+    end
+
+    #: () -> Hash[Array[String], Analysis?]
+    def call
+      empty = {} #: Hash[Array[String], Analysis?]
+      return empty.freeze if @identities.empty?
+
+      records = historical_roots
+      selected = BatchedRootVersions.new(
+        records, time_range: @time_range, version_scope: @version_scope
+      ).call
+      prepare(records, selected)
+      analyses = records.to_h do |record|
+        key = Endpoint.identity(record)
+        plan = selected.fetch(key)
+        [key, plan.empty? ? Analysis.empty : @analyzer.call(record, plan)]
+      end
+      with_unavailable(analyses)
+    end
+
+    private
+
+    #: (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
+    def with_unavailable(analyses)
+      @identities.to_h { |key| [Support.immutable_copy(key), analyses[key]] }.freeze
+    end
+
+    # @rbs @model: untyped
+    # @rbs @identities: Array[Array[String]]
+    # @rbs @time_range: TimeRange?
+    # @rbs @analyzer: untyped
+    # @rbs @history_preparer: untyped
+    # @rbs @version_scope: untyped
+
+    # These records supply identity and model metadata only. Every reported
+    # value comes from the batched historical plan; no per-root reify or live
+    # lookup is needed to get into the comparison engine.
+    #: () -> Array[untyped]
+    def historical_roots
+      loader = PreparedVersionStateLoader.new
+      destroy_versions.map do |version|
+        model = loader.call(version)&.model_class || Endpoint.model_class(version)
+        record = model.new
+        record[model.primary_key] = version.item_id
+        record
+      end
+    end
+
+    #: () -> Array[untyped]
+    def destroy_versions
+      destroys = @model.paper_trail.version_class.where(
+        item_type: @model.base_class.name, item_id: @identities.map(&:last), event: 'destroy'
+      )
+      versions = VersionQuery.chronological(destroys)
+      versions.group_by { |version| version.item_id.to_s }.values.map do |history|
+        Support.chronological_sort(history).last
+      end
+    end
+
+    #: (Array[untyped]) -> Hash[Symbol, untyped]
+    def preparation_range(versions)
+      { start_at: @time_range&.begin_time,
+        end_at: [@time_range&.end_time, versions.map(&:created_at).max].compact.max }
+    end
+
+    #: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+    def prepare(records, selected)
+      records.group_by(&:class).each_value do |group|
+        versions = group.flat_map do |record|
+          selected.fetch(Endpoint.identity(record)).reconstruction_versions
+        end
+        next if versions.empty?
+
+        @history_preparer.call(group, versions, **preparation_range(versions))
+      end
+    end
+  end
+end

data/lib/paper_trail_diff/direct_record_state_loader.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Completes plain recorded state without invoking model initialization or writers.
+  # Decline model behavior whose values require an actual ActiveRecord instance.
+  class DirectRecordStateLoader
+    #: () -> void
+    def initialize
+      @loader = PreparedVersionStateLoader.new
+      @supported = {} #: Hash[untyped, bool]
+      @defaults = {} #: Hash[untyped, Hash[untyped, untyped]]
+    end
+
+    #: (untyped) -> PreparedRecordState?
+    def call(version)
+      state = @loader.call(version)
+      complete(state) if state
+    end
+
+    #: (PreparedRecordState) -> PreparedRecordState?
+    def complete(state)
+      model = state.model_class
+      return unless supported?(model)
+
+      defaults = @defaults[model] ||= model.column_defaults
+      attributes = defaults.merge(state.attributes).to_h do |name, value|
+        [name, model.type_for_attribute(name).cast(value)]
+      end
+      PreparedRecordState.from_attributes(model, attributes)
+    end
+
+    private
+
+    # @rbs @loader: PreparedVersionStateLoader
+    # @rbs @supported: Hash[untyped, bool]
+    # @rbs @defaults: Hash[untyped, Hash[untyped, untyped]]
+
+    #: (untyped) -> bool
+    def supported?(model)
+      return @supported[model] if @supported.key?(model)
+
+      @supported[model] = plain_model?(model) && plain_attributes?(model)
+    end
+
+    #: (untyped) -> bool
+    def plain_model?(model)
+      !model.primary_key.is_a?(Array) && !model.default_scopes? &&
+        model._initialize_callbacks.empty? &&
+        %i[initialize attributes []= write_attribute id].all? do |name|
+          framework_class?(model.instance_method(name).owner)
+        end
+    end
+
+    #: (untyped) -> bool
+    def plain_attributes?(model)
+      return false if encrypted?(model)
+      return false unless model.attribute_types.keys.sort == model.column_names.sort
+      return false if application_defaults?(model)
+
+      model.attribute_types.values.all? { |type| framework_class?(type.class) }
+    end
+
+    #: (untyped) -> bool
+    def application_defaults?(model)
+      model._default_attributes.each_value.any? do |attribute|
+        attribute.class.name.to_s.end_with?('UserProvidedDefault')
+      end
+    end
+
+    #: (untyped) -> bool
+    def encrypted?(model)
+      !!(model.respond_to?(:encrypted_attributes) && model.encrypted_attributes&.any?)
+    end
+
+    #: (untyped) -> bool
+    def framework_class?(value)
+      value.name.to_s.start_with?('ActiveRecord::', 'ActiveModel::')
+    end
+  end
+end

data/lib/paper_trail_diff/endpoint.rb

@@ -82,6 +82,16 @@ module PaperTrailDiff
       raise InvalidEndpointError, "cannot resolve endpoint model: #{model_type}", cause: e
     end
 
+    # The record's own PaperTrail versions, under whatever name the model gave
+    # the association.
+    #: (untyped) -> untyped
+    def versions(record)
+      record.public_send(record.class.versions_association_name)
+    rescue NoMethodError => e
+      message = 'record does not expose a PaperTrail version history'
+      raise InvalidTimelineRangeError, message, cause: e
+    end
+
     #: (untyped) -> untyped
     def reload_record(record)
       validate_record!(record)

data/lib/paper_trail_diff/engine.rb

@@ -71,6 +71,8 @@ module PaperTrailDiff
         raise ArgumentError, 'association kind changed between snapshots'
       end
 
+      # Kinds are symbols, so `!=`, `equal?`, and `eql?` all agree here.
+      # mutant:disable
       #: (AssociationSnapshot?, AssociationSnapshot?) -> bool
       def kinds_differ?(from_association, to_association)
         return false unless from_association && to_association
@@ -131,9 +133,9 @@ module PaperTrailDiff
         ).call
       end
 
-      #: (RecordSnapshot?, RecordSnapshot?) -> bool
+      #: (RecordSnapshot?, RecordSnapshot?) -> boolish
       def same_identity?(from_record, to_record)
-        from_record && to_record ? from_record.identity == to_record.identity : false
+        from_record && to_record && from_record.identity == to_record.identity
       end
     end
   end

data/lib/paper_trail_diff/errors.rb

@@ -8,6 +8,9 @@ module PaperTrailDiff
   # Raised when a public option has an invalid type, key, value, or path.
   class ConfigurationError < Error; end
 
+  # Raised when nested data keys cannot be represented by unique string paths.
+  class AmbiguousNestedKeyError < Error; end
+
   # Raised when compare endpoints do not belong to the same PaperTrail item.
   class VersionMismatchError < Error; end
 
@@ -36,6 +39,12 @@ module PaperTrailDiff
   # Truncating instead would hand back a report that is short without saying so.
   class BatchLimitExceededError < Error; end
 
+  # Historical candidate loading exceeded its explicitly bounded work budget.
+  class FilterLimitExceededError < Error; end
+
+  # A batch selected a known expensive association without explicitly opting in.
+  class UnsupportedBatchPathError < ConfigurationError; end
+
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error; end
 

data/lib/paper_trail_diff/historical_association_reifier.rb

@@ -51,7 +51,7 @@ module PaperTrailDiff
     def reify_has_many(record, reflection)
       if reflection.options[:through]
         reify_association(record, reflection.through_reflection)
-        reifier(:HasManyThrough).reify(reflection, record, options, @transaction_id)
+        reify_through(record, reflection)
         return
       end
 
@@ -65,6 +65,31 @@ module PaperTrailDiff
       )
     end
 
+    # PT-AT's collection-source helper reifies every has_many on each join
+    # record. Walk only the requested source instead, including nested throughs.
+    #: (untyped, untyped) -> void
+    def reify_through(record, reflection)
+      source = reflection.source_reflection
+      if source.belongs_to?
+        reifier(:HasManyThrough).reify(reflection, record, options, @transaction_id)
+        return
+      end
+
+      members = through_members(record, reflection, source)
+      association = record.association(reflection.name)
+      association.target = members.uniq { |member| [member.class.base_class.name, member.id] }
+      association.loaded!
+    end
+
+    #: (untyped, untyped, untyped) -> Array[untyped]
+    def through_members(record, reflection, source)
+      joins = Array(record.public_send(reflection.through_reflection.name)) #: Array[untyped]
+      joins.flat_map do |join|
+        reify_association(join, source)
+        Array(join.public_send(source.name))
+      end
+    end
+
     #: (untyped, untyped) -> void
     def reify_habtm(record, reflection)
       unless @habtm_transaction_id

data/lib/paper_trail_diff/historical_filter.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects roots by the values they held at any point in the window, with an
+  # explicit ceiling on version loading.
+  #
+  # A version records the state *before* its own change, so the versions in
+  # the window supply the state at its start and after every change but the
+  # last. The state after the last change lives in the first version after
+  # the window, or in the live row when nothing follows; a destroy leaves none.
+  class HistoricalFilter
+    DEFAULT_VERSION_LIMIT = 10_000
+    CANDIDATE_BATCH = 250
+
+    #: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
+    def initialize(model, predicate:, time_range:, limit:, max_versions:)
+      @model = model
+      @predicate = validate_predicate(predicate)
+      @time_range = time_range
+      @limit = limit
+      @max_versions = validate_budget(max_versions)
+      @loaded = 0
+      @state_loader = PreparedVersionStateLoader.new
+    end
+
+    #: (Array[String]) -> Array[String]
+    def call(candidates)
+      matched = [] #: Array[String]
+      candidates.each_slice(CANDIDATE_BATCH) do |slice|
+        versions = candidate_versions(slice)
+        closing = closing_states(slice, versions)
+        slice.each do |id|
+          next unless held?(versions.fetch(id, []), closing[id])
+
+          matched << id
+          reject_root_limit! if matched.length > @limit
+        end
+      end
+      matched
+    end
+
+    private
+
+    # @rbs @model: untyped
+    # @rbs @predicate: untyped
+    # @rbs @time_range: TimeRange?
+    # @rbs @limit: Integer
+    # @rbs @max_versions: Integer
+    # @rbs @loaded: Integer
+    # @rbs @state_loader: PreparedVersionStateLoader
+
+    #: (untyped) -> untyped
+    def validate_predicate(predicate)
+      return predicate if predicate.respond_to?(:call)
+      unless predicate.is_a?(Hash)
+        raise ConfigurationError, 'historical_filter: must respond to call or be an attribute hash'
+      end
+
+      attributes = predicate.transform_keys(&:to_s)
+      unknown = attributes.keys - @model.attribute_names
+      if unknown.any?
+        raise ConfigurationError,
+              "unknown historical attributes: #{unknown.join(', ')}"
+      end
+
+      Support.immutable_copy(attributes)
+    end
+
+    #: (untyped) -> Integer
+    def validate_budget(value)
+      return value if value.instance_of?(Integer) && value.positive?
+
+      raise ConfigurationError, 'max_filter_versions: must be a positive Integer'
+    end
+
+    #: (Array[String]) -> Hash[String, Array[untyped]]
+    def candidate_versions(ids)
+      relation = @model.paper_trail.version_class.where(item_type: @model.base_class.name,
+                                                        item_id: ids)
+      range = @time_range
+      relation = range.scope(relation) if range
+      # One past the remaining budget is enough to know it was exceeded.
+      versions = VersionQuery.chronological(relation).limit(@max_versions - @loaded + 1)
+      account_versions!(versions.length)
+      versions.group_by { |version| version.item_id.to_s }
+    end
+
+    #: (Array[untyped], untyped) -> boolish
+    def held?(versions, closing)
+      return true if versions.any? { |version| matches?(version) }
+      return false unless closing
+
+      Endpoint.version?(closing) ? matches?(closing) : record_matches?(closing)
+    end
+
+    # What each candidate held after its last change in the window.
+    #: (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
+    def closing_states(ids, versions)
+      open = ids.reject { |id| versions.fetch(id, []).last&.event == 'destroy' }
+      trailing = trailing_versions(open)
+      trailing.merge(live_records(open - trailing.keys))
+    end
+
+    #: (Array[String]) -> Hash[String, untyped]
+    def trailing_versions(ids)
+      range = @time_range
+      return {} unless range
+
+      relation = @model.paper_trail.version_class.where(item_type: @model.base_class.name,
+                                                        item_id: ids)
+      trailing = range.first_trailing_versions(relation)
+      account_versions!(trailing.length)
+      trailing
+    end
+
+    #: (Array[String]) -> Hash[String, untyped]
+    def live_records(ids)
+      @model.unscoped.where(@model.primary_key => ids).to_h { |record| [record.id.to_s, record] }
+    end
+
+    #: (untyped) -> boolish
+    def record_matches?(record)
+      return @predicate.call(record) unless @predicate.instance_of?(Hash)
+
+      @predicate.all? { |name, expected| record.attributes.fetch(name) == expected }
+    end
+
+    #: (Integer) -> void
+    def account_versions!(count)
+      @loaded += count
+      return unless @loaded > @max_versions
+
+      raise FilterLimitExceededError,
+            "historical_filter: exceeds max_filter_versions: #{@max_versions}; " \
+            'narrow the window or explicitly increase the version budget'
+    end
+
+    #: (untyped) -> boolish
+    def matches?(version)
+      if @predicate.instance_of?(Hash)
+        return false unless version.object
+
+        return attributes_match?(version)
+      end
+
+      state = version.reify(dup: true)
+      state && @predicate.call(state)
+    end
+
+    #: (untyped) -> bool
+    def attributes_match?(version)
+      state = @state_loader.call(version)
+      unless state
+        raise ConfigurationError,
+              'historical_filter: cannot read recorded attributes directly; use a bounded callable'
+      end
+
+      @predicate.all? do |name, expected|
+        unless state.attributes.key?(name)
+          raise ConfigurationError,
+                "historical_filter: #{name} was not recorded in version #{version.id}"
+        end
+
+        state.attributes.fetch(name) == expected
+      end
+    end
+
+    #: () -> void
+    def reject_root_limit!
+      raise BatchLimitExceededError,
+            "historical_filter: matched more than #{@limit} roots; narrow the window " \
+            'or the filter, or raise limit: to the population you intend to analyze'
+    end
+  end
+end