paper_trail_diff 0.12.0 → 0.13.1

data/lib/paper_trail_diff/prepared_state_association_reader.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Reads plain direct edges without creating AR records for their members.
+  class PreparedStateAssociationReader
+    #: (PreparedRecordIndex, untyped) -> void
+    def initialize(records, edges)
+      @records = records
+      @edges = edges
+    end
+
+    #: (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
+    def call(owner, reflection, boundary)
+      return [false, []] unless supported?(reflection)
+
+      if reflection.belongs_to?
+        id = owner.attributes[reflection.foreign_key.to_s]
+        return [true, []] if id.nil?
+
+        handled, state = @records.snapshot_state_before(reflection.klass, id, boundary)
+        return [handled, state ? [state] : []]
+      end
+      children(owner, reflection, boundary)
+    end
+
+    private
+
+    # @rbs @records: PreparedRecordIndex
+    # @rbs @edges: untyped
+
+    #: (untyped) -> bool
+    def supported?(reflection)
+      !reflection.options[:through] && !reflection.polymorphic? && reflection.scope.nil? &&
+        !reflection.klass.default_scopes? && !reflection.foreign_key.is_a?(Array) &&
+        %i[belongs_to has_one has_many].include?(reflection.macro)
+    end
+
+    #: (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
+    def children(owner, reflection, boundary)
+      selected = [] #: Array[PreparedRecordState]
+      @edges.call(owner.model_class, reflection).each_value do |group|
+        ids_for(group, owner).each do |id|
+          handled, child = @records.snapshot_state_before(group.fetch(:model), id, boundary)
+          return [false, []] unless handled
+
+          selected << child if child && member?(child, owner, reflection)
+        end
+      end
+      [true, reflection.collection? ? selected : selected.first(1)]
+    end
+
+    #: (untyped, PreparedRecordState) -> Array[untyped]
+    def ids_for(group, owner)
+      owners = group[:owners]
+      id = owner.attributes[owner.model_class.primary_key].to_s
+      empty = [] #: Array[untyped]
+      owners ? owners.fetch(id, empty) : group.fetch(:ids)
+    end
+
+    #: (PreparedRecordState, PreparedRecordState, untyped) -> bool
+    def member?(child, owner, reflection)
+      owner_id = owner.attributes[owner.model_class.primary_key].to_s
+      return false unless child.attributes[reflection.foreign_key.to_s].to_s == owner_id
+      return true unless reflection.options[:as]
+
+      matching_type?(child, owner.model_class, reflection)
+    end
+
+    #: (PreparedRecordState, untyped, untyped) -> bool
+    def matching_type?(child, model, reflection)
+      types = [model.name, model.base_class.name,
+               reflection.active_record.name]
+      types.include?(child.attributes[reflection.type.to_s].to_s)
+    end
+  end
+end

data/lib/paper_trail_diff/root_version_plan.rb

@@ -27,6 +27,10 @@ module PaperTrailDiff
     # The root versions this plan reports as mutations, which excludes any
     # version present only to reveal what the last of them produced.
     attr_reader :mutations #: Array[untyped]
+    # Whether a wall-clock window closes on the root's own destruction. Its
+    # final state is then the absence the destroy left, just as a window
+    # closing on current state ends at the live record.
+    attr_reader :closes_on_destroy #: bool
 
     class << self
       # Adjacent boundaries, which is what an unfiltered range reports.
@@ -45,20 +49,30 @@ module PaperTrailDiff
         steps = [] #: Array[[untyped, untyped]]
         new(versions: versions, steps: steps)
       end
+
+      # No root version to report or replay: only descendants moved, and the
+      # live record is the root's state throughout.
+      #: (untyped) -> RootVersionPlan
+      def closing_on(record)
+        versions = [] #: Array[untyped]
+        steps = [] #: Array[[untyped, untyped]]
+        new(versions: versions, steps: steps, closing_record: record)
+      end
     end
 
-    #: (versions: Array[untyped], steps: Array[[untyped, untyped]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?, ?closing_record: untyped) -> void
+    #: (versions: Array[untyped], steps: Array[[untyped, untyped]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?, ?closing_record: untyped, ?closes_on_destroy: bool) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
       versions:, steps:, context_version: nil, reconstruction_versions: nil, mutations: nil,
-      closing_record: nil
+      closing_record: nil, closes_on_destroy: false
     )
       @closing_record = closing_record
+      @closes_on_destroy = closes_on_destroy
       @versions = versions.freeze
       @reconstruction_versions = (reconstruction_versions || versions).freeze
       @steps = steps.freeze
       @context_version = context_version
       @mutations = (mutations || default_mutations).freeze
-      @mutation_keys = Set.new(@mutations.map { |version| key(version) }).freeze
+      @mutation_keys = key_set(@mutations)
       freeze
     end
 
@@ -67,6 +81,15 @@ module PaperTrailDiff
       versions.empty?
     end
 
+    #: () -> RootVersionPlan
+    def closing_on_destroy
+      self.class.new(
+        versions: versions, steps: steps, context_version: context_version,
+        reconstruction_versions: reconstruction_versions, mutations: mutations,
+        closing_record: closing_record, closes_on_destroy: true
+      )
+    end
+
     # What the range's final state is read from, which is the live record when
     # the window closes on current state and the last version otherwise.
     #: () -> untyped
@@ -91,6 +114,15 @@ module PaperTrailDiff
       @versions.reject { |version| key(version) == context }
     end
 
+    # A Set only makes the lookup in `mutation?` fast; an Array would answer the
+    # same, which is why mutant leaves this alone.
+    # mutant:disable
+    #: (Array[untyped]) -> Set[Array[untyped]]
+    def key_set(versions)
+      Set.new(versions.map { |version| key(version) })
+    end
+
+    # By class name, so a version still matches after its class is reloaded.
     #: (untyped) -> Array[untyped]
     def key(version)
       [version.class.name, version.id]

data/lib/paper_trail_diff/root_version_selection.rb

@@ -37,10 +37,8 @@ module PaperTrailDiff
       return without_selection if @selected.empty?
 
       closing = revealing_version || @live_endpoint
-      raise IncompleteTimeRangeError, INCOMPLETE if !closing && @windowed && !terminal_destroy?
-      return filtered_plan(closing) if @filtered
-
-      contiguous_plan(closing)
+      plan = @filtered ? filtered_plan(closing) : contiguous_plan(closing)
+      closes_on_destroy?(closing) ? plan.closing_on_destroy : plan
     end
 
     private
@@ -69,13 +67,16 @@ module PaperTrailDiff
     end
 
     # An activity view still needs a root to reconstruct from even when no root
-    # version falls inside the window, because descendants may have moved.
+    # version falls inside the window, because descendants may have moved. With
+    # no later version, a window closing on current state reads the root from
+    # the live record, which is then its state throughout the window.
     #: () -> RootVersionPlan
     def without_selection
       return RootVersionPlan.empty unless @context_required
       if @after_range
         return RootVersionPlan.contiguous([@after_range], context_version: @after_range)
       end
+      return RootVersionPlan.closing_on(@live_endpoint) if @live_endpoint && @windowed
 
       raise IncompleteTimeRangeError, INCOMPLETE
     end
@@ -149,6 +150,16 @@ module PaperTrailDiff
       immediate_successor(@selected.last) || @after_range
     end
 
+    # A window with nothing after its last selected mutation can only close on
+    # that mutation being the record's destruction.
+    #: (untyped) -> bool
+    def closes_on_destroy?(closing)
+      return false if closing || !@windowed
+      raise IncompleteTimeRangeError, INCOMPLETE unless terminal_destroy?
+
+      true
+    end
+
     # A range closing on the record's own destruction needs no later version:
     # nothing can follow it, so demanding one would reject the range forever.
     #: () -> bool

data/lib/paper_trail_diff/scoped_analysis.rb

@@ -15,14 +15,29 @@ module PaperTrailDiff
   class ScopedAnalysis
     attr_reader :analyses #: Hash[Array[String], Analysis]
     attr_reader :unreachable #: Array[Array[String]]
+    # The live records the selection loaded, in the order it loaded them. The
+    # gem already has them; withholding them only makes a caller query the same
+    # rows again to attach its own presentation data. A destroyed root has no
+    # record to hand back, so `roots` and `unreachable` stay complementary.
+    attr_reader :roots #: Array[untyped]
+    # Requested missing-root analyses, kept separate because live SQL conditions
+    # cannot prove which deleted rows matched. nil means no destroy history.
+    attr_reader :deleted #: Hash[Array[String], Analysis?]
 
-    #: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]]) -> void
-    def initialize(analyses:, unreachable:)
+    #: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]], ?roots: Array[untyped], ?deleted: Hash[Array[String], Analysis?]) -> void
+    def initialize(analyses:, unreachable:, roots: [], deleted: {})
       @analyses = analyses
       @unreachable = Support.immutable_copy(unreachable)
+      # Not deep-copied: these are the caller's own model instances, and
+      # freezing them would make an ordinary `record.title` on a lazy attribute
+      # fail. The array itself is frozen so the collection cannot be reshaped.
+      @roots = roots.dup.freeze
+      @deleted = Support.immutable_copy(deleted)
       freeze
     end
 
+    # Two elements, not three: `roots` is reached by name so that existing
+    # destructuring keeps working.
     #: () -> [Hash[Array[String], Analysis], Array[Array[String]]]
     def to_ary
       [analyses, unreachable]

data/lib/paper_trail_diff/scoped_analysis_builder.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects both populations and checks their shared ceiling before analysis.
+  class ScopedAnalysisBuilder
+    #: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      scope, limit:, within:, historical_filter:, max_filter_versions:, include_deleted:,
+      analyzer:, deleted_analyzer:
+    )
+      raise ConfigurationError, 'limit: is required when selecting roots by scope' if limit.nil?
+      unless [true, false].include?(include_deleted)
+        raise ConfigurationError, 'include_deleted: must be true or false'
+      end
+
+      @selection = ScopedRootSelection.new(
+        scope, limit: limit, time_range: within.nil? ? nil : TimeRange.new(within),
+               historical_filter: historical_filter, max_filter_versions: max_filter_versions
+      )
+      @limit = limit
+      @include_deleted = include_deleted
+      @analyzer = analyzer
+      @deleted_analyzer = deleted_analyzer
+    end
+
+    #: () -> ScopedAnalysis
+    def call
+      selection = @selection.call
+      if @include_deleted && selection.records.length + selection.unreachable.length > @limit
+        raise BatchLimitExceededError, 'include_deleted: live and missing roots exceed limit:'
+      end
+
+      ScopedAnalysis.new(
+        analyses: @analyzer.call(selection.records), roots: selection.records,
+        unreachable: selection.unreachable,
+        deleted: @include_deleted ? @deleted_analyzer.call(selection.unreachable) : {}
+      )
+    end
+
+    # @rbs @selection: ScopedRootSelection
+    # @rbs @limit: Integer
+    # @rbs @include_deleted: bool
+    # @rbs @analyzer: untyped
+    # @rbs @deleted_analyzer: untyped
+  end
+end

data/lib/paper_trail_diff/scoped_root_selection.rb

@@ -26,6 +26,9 @@ module PaperTrailDiff
   # window. `where(status: 'published')` selects what is published now, which is
   # not the same set as what was published while the window was open.
   class ScopedRootSelection
+    PAGE_SIZE = 250
+    private_constant :PAGE_SIZE
+
     # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
     # gem supports 3.1.
     class Result
@@ -40,16 +43,25 @@ module PaperTrailDiff
       end
     end
 
-    #: (untyped, time_range: TimeRange?, limit: Integer) -> void
-    def initialize(scope, time_range:, limit:)
+    #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer) -> void
+    def initialize(scope, time_range:, limit:, historical_filter: nil,
+                   max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT)
       @scope = normalize_scope(scope)
       @time_range = time_range
       @limit = validate_limit(limit)
+      @historical_filter = unless historical_filter.nil?
+                             HistoricalFilter.new(base_class, predicate: historical_filter,
+                                                              time_range: time_range, limit: @limit,
+                                                              max_versions: max_filter_versions)
+                           end
     end
 
     #: () -> Result
     def call
+      return database_selection if @historical_filter.nil? && comparable_keys?
+
       candidates = versioned_ids
+      candidates = @historical_filter.call(candidates) if @historical_filter && candidates.any?
       return Result.new(records: [], unreachable: []) if candidates.empty?
 
       live = live_ids(candidates)
@@ -64,6 +76,47 @@ module PaperTrailDiff
     # @rbs @scope: untyped
     # @rbs @time_range: TimeRange?
     # @rbs @limit: Integer
+    # @rbs @historical_filter: untyped
+
+    # Leaves the candidate set in the database. Plucking every root changed in
+    # the window would cost memory and a statement proportional to all activity
+    # in the window -- not to the relation or `limit:` -- so a report on one
+    # record could read every id in a busy table. A subquery keeps the work
+    # bounded by what the relation and the deletions actually contain.
+    #: () -> Result
+    def database_selection
+      candidates = window_versions.select(:item_id)
+      Result.new(
+        records: selected_records(candidates),
+        unreachable: missing_ids.map { |id| identity(id) }.freeze
+      )
+    end
+
+    # Comparing the two columns in SQL needs them to share a type: PostgreSQL
+    # rejects an integer key against a string item_id outright.
+    #: () -> bool
+    def comparable_keys?
+      return false unless primary_key.is_a?(String)
+
+      item_id = version_class.columns_hash['item_id']&.type
+      key = base_class.columns_hash[primary_key]&.type
+      !item_id.nil? && item_id == key
+    end
+
+    # Changed in the window but without a row, found with an anti-join instead
+    # of comparing two plucked lists.
+    #: () -> Array[String]
+    def missing_ids
+      live = base_class.unscoped.select(primary_key)
+      window_versions.where.not(item_id: live).distinct.pluck(:item_id).map(&:to_s).uniq.sort
+    end
+
+    #: () -> untyped
+    def window_versions
+      relation = version_class.where(item_type: item_type)
+      range = @time_range
+      range ? range.scope(relation) : relation
+    end
 
     # Accepts a model class as readily as a relation: `Article` and
     # `Article.where(...)` both name a population, and `all` is what makes them
@@ -93,27 +146,67 @@ module PaperTrailDiff
     # version table alone so that it does not depend on rows still existing.
     #: () -> Array[String]
     def versioned_ids
-      relation = version_class.where(item_type: item_type)
-      range = @time_range
-      relation = range.scope(relation) if range
-      relation.distinct.pluck(:item_id).map(&:to_s).uniq
+      window_versions.distinct.pluck(:item_id).map(&:to_s).uniq
     end
 
     # Which of those candidates still have a row, asked without the relation's
     # conditions so that "filtered out" and "no longer exists" stay separable.
     #: (Array[String]) -> Array[String]
     def live_ids(candidates)
-      base_class.unscoped.where(primary_key => candidates).pluck(primary_key).map(&:to_s)
+      candidates.each_slice(PAGE_SIZE).flat_map do |slice|
+        base_class.unscoped.where(primary_key => slice).pluck(primary_key).map(&:to_s)
+      end
     end
 
-    # Loading one past the limit is what turns an oversized page into an error
-    # rather than a silently truncated report.
-    #: (Array[String]) -> Array[untyped]
+    # Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
+    # relation may order by joined columns or select a PostgreSQL json column.
+    # Read bounded pages until the relation ends or too many unique roots appear.
+    #: (untyped) -> Array[untyped]
     def selected_records(live)
-      return [] if live.empty?
+      return [] if live.is_a?(Array) && live.empty?
+
+      records = {} #: Hash[untyped, untyped]
+      consumed = 0
+      loop do
+        page = record_page(live, consumed)
+        page.each { |record| records[record.id] ||= record }
+        reject_oversized!(records.length)
+        break if page.length < PAGE_SIZE
+
+        consumed += page.length
+      end
+      records.values.freeze
+    end
+
+    #: (untyped, Integer) -> Array[untyped]
+    def record_page(live, consumed)
+      count = page_limit(consumed)
+      return [] if count.zero?
+
+      # An id list or a candidate subquery; both read the same way in SQL.
+      conditions = { primary_key => live } #: Hash[untyped, untyped]
+      ordered_scope.where(conditions)
+                   .offset((@scope.offset_value || 0) + consumed).limit(count).to_a
+    end
+
+    # Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
+    # even when the extra ordering would only have served as a tie-breaker.
+    #: () -> untyped
+    def ordered_scope
+      return @scope unless @scope.order_values.empty?
+
+      @scope.order(primary_key => :asc)
+    end
+
+    #: (Integer) -> Integer
+    def page_limit(consumed)
+      remaining = @scope.limit_value
+      [remaining ? remaining - consumed : PAGE_SIZE, PAGE_SIZE].min
+    end
 
-      records = @scope.where(primary_key => live).limit(@limit + 1).to_a
-      return records.freeze unless records.length > @limit
+    #: (Integer) -> void
+    def reject_oversized!(count)
+      return unless count > @limit
 
       raise BatchLimitExceededError,
             "scope: selected more than #{@limit} roots; narrow the window or the " \

data/lib/paper_trail_diff/snapshot.rb

@@ -171,7 +171,11 @@ module PaperTrailDiff
 
     #: (type: String, id: untyped, attributes: snapshot_attributes, ?associations: snapshot_associations) -> void
     def initialize(type:, id:, attributes:, associations: {})
-      @type = Support.immutable_copy(type.to_s)
+      unless type.is_a?(String)
+        raise ArgumentError, "record type must be a String, not #{type.inspect}"
+      end
+
+      @type = Support.immutable_copy(type)
       @id = Support.immutable_copy(id)
       @identity = [@type, @id].freeze
       @attributes = normalize_hash(attributes)
@@ -184,6 +188,15 @@ module PaperTrailDiff
       RecordReference.new(type: type, id: id)
     end
 
+    # A copy holding a different state for one association.
+    #: (String, AssociationSnapshot) -> RecordSnapshot
+    def with_association(name, association)
+      self.class.new(
+        type: type, id: id, attributes: attributes,
+        associations: associations.merge(name => association)
+      )
+    end
+
     #: () -> Hash[Symbol, untyped]
     def to_h
       value = {