paper_trail_diff 0.14.0 → 0.15.0

data/lib/paper_trail_diff/activity_tree_filter.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Leaves out the events of records that were outside the root's tree.
+  #
+  # A record found in the tree at one time in a range brings every version it
+  # saved in the range, including those it saved while it belonged elsewhere:
+  # a comment edited on another article before it moved to this one, or after
+  # it left a scope. Such a version changes nothing the root shows. As a
+  # boundary it would open a step of its own, and inside a transaction, where
+  # a change surfaces one event late, that step would take the credit for the
+  # root's own change.
+  #
+  # PT-AT reads associations as they were before a transaction, so a record
+  # is judged by two snapshots: the one at its transaction's first event, and
+  # the one after its last, which is the next event's or what the range
+  # closes on. A record in neither was outside the tree throughout.
+  #
+  # The root's own events are always kept, and so are the versions of a
+  # through's join rows, which a snapshot does not hold, and an event whose
+  # step is not reported, which only bounds one that is.
+  class ActivityTreeFilter
+    # `closing` is the snapshot after the last event: the current record's,
+    # or nil when nothing follows, as after the root's destruction.
+    #: (Array[ActivityEvent], reported: untyped, closing: RecordSnapshot?) -> void
+    def initialize(events, reported:, closing:)
+      @reported = reported
+      @closing = closing
+      @starts, @ends = spans(events)
+      @types = {} #: Hash[String, Array[String?]]
+    end
+
+    # Yields each event of the sequence with its snapshot, and whether to keep
+    # it, in order.
+    #: (untyped) { (ActivityEvent, RecordSnapshot?, bool) -> void } -> void
+    def call(sequence)
+      pairs = sequence.to_enum.to_a #: Array[[ActivityEvent, RecordSnapshot?]]
+      pairs.each_with_index do |(event, snapshot), index|
+        yield event, snapshot, keep?(event, index, pairs)
+      end
+    end
+
+    private
+
+    # @rbs @reported: untyped
+    # @rbs @closing: RecordSnapshot?
+    # @rbs @starts: Array[Integer]
+    # @rbs @ends: Array[Integer]
+    # @rbs @types: Hash[String, Array[String?]]
+
+    #: (ActivityEvent, Integer, Array[[ActivityEvent, RecordSnapshot?]]) -> bool
+    def keep?(event, index, pairs)
+      return true if event.root? || event.join? || !reported?(event)
+
+      position = @ends.fetch(index)
+      after = position < pairs.length ? pairs.fetch(position).last : @closing
+      holds?(pairs.fetch(@starts.fetch(index)).last, event) || holds?(after, event)
+    end
+
+    #: (ActivityEvent) -> bool
+    def reported?(event)
+      !@reported || @reported.call(event)
+    end
+
+    # Where each event's transaction starts, and the position just past its
+    # last event. Two transactions can interleave, so a transaction's events
+    # need not be adjacent.
+    #: (Array[ActivityEvent]) -> [Array[Integer], Array[Integer]]
+    def spans(events)
+      keys = transaction_keys(events)
+      first = {} #: Hash[Array[untyped] | Integer, Integer]
+      last = {} #: Hash[Array[untyped] | Integer, Integer]
+      keys.each_with_index do |key, index|
+        first[key] ||= index
+        last[key] = index
+      end
+      [keys.map { |key| first.fetch(key) }, keys.map { |key| last.fetch(key) + 1 }]
+    end
+
+    # A version saved outside a transaction is a transaction of its own,
+    # keyed by its position.
+    #: (Array[ActivityEvent]) -> Array[Array[untyped] | Integer]
+    def transaction_keys(events)
+      events.each_with_index.map do |event, index|
+        ActivityTransactionGroups.transaction_key(event.version) || index
+      end
+    end
+
+    #: (RecordSnapshot?, ActivityEvent) -> bool
+    def holds?(snapshot, event)
+      return false unless snapshot
+
+      version = event.version
+      types = types(version.item_type)
+      branches = event.branches #: Array[String]
+      branches.any? { |name| contains?(snapshot.associations.fetch(name), types, version.item_id) }
+    end
+
+    #: (AssociationSnapshot, Array[String?], untyped) -> bool
+    def contains?(association, types, id)
+      types.any? { |type| association.position(type, id) } || association.records.any? do |record|
+        record.associations.each_value.any? { |nested| contains?(nested, types, id) }
+      end
+    end
+
+    # A version names its record's base class, and a snapshot the record's
+    # own class, which may be any subclass of it.
+    #: (String) -> Array[String?]
+    def types(base_name)
+      @types[base_name] ||= [base_name, *Object.const_get(base_name).descendants.map(&:name)]
+    end
+  end
+end

data/lib/paper_trail_diff/activity_version_collector.rb

@@ -22,13 +22,15 @@ module PaperTrailDiff
       @registry = ActivityEventRegistry.new
     end
 
+    # A tie between version tables, or between ids that do not count up,
+    # raises rather than building a timeline in an arbitrary order.
     #: () -> Array[ActivityEvent]
     def call
       @registry.add(@root_versions)
       collect_tree(@record.class, [@record.id], @tree, path: '', branch: nil) unless @tree.empty?
-      @registry.to_a.sort_by do |event|
-        Support.chronological_version_key(event.version)
-      end.freeze
+      events = @registry.to_a.sort_by { |event| Support.chronological_version_key(event.version) }
+      pair = Support.ambiguous_pair(events.map(&:version))
+      pair ? raise(AmbiguousVersionOrderError, Support.ambiguous_message(pair)) : events.freeze
     end
 
     private
@@ -92,7 +94,7 @@ module PaperTrailDiff
         # A through is always read with prepared history, which knows the
         # join row's state either side of each version.
         @registry.add(@prepared&.join_versions(group, reflection) || group.fetch(:versions),
-                      branch: branch)
+                      branch: branch, join: true)
         source = reflection.source_reflection
         children = edge_groups(group, source, branch)
         merge_groups!(result, children)
@@ -141,7 +143,7 @@ module PaperTrailDiff
         return identity_groups(rows, reflection)
       end
       transaction_ids = parent_versions.filter_map do |version|
-        version.transaction_id if version.respond_to?(:transaction_id)
+        VersionBoundary.transaction_id(version)
       end
       rows = parent_class.paper_trail.version_association_class.where(
         version_id: transaction_ids,

data/lib/paper_trail_diff/activity_view.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # How a request presents its activity steps: whether they keep their
+  # snapshots, whether a transaction's steps merge into one, and which of
+  # their versions' recorded changes they carry. Built and checked once per
+  # request, and read the same way by both activity builders, or the same
+  # history would read differently depending on how it was asked for.
+  class ActivityView
+    # Options only an activity view uses are refused without one.
+    #: (activity: bool, snapshots: bool, group: Symbol?, recorded: IgnorePolicy?) -> ActivityView
+    def self.build(activity:, snapshots:, group:, recorded:)
+      view = new(snapshots: snapshots, group: group, recorded: recorded)
+      return view if activity
+
+      { snapshots: snapshots, recorded_changes: !recorded.nil?, group: !group.nil? }
+        .each do |name, given|
+          raise ConfigurationError, "#{name}: requires activity: true" if given
+        end
+      view
+    end
+
+    #: (?snapshots: bool, ?group: Symbol?, ?recorded: IgnorePolicy?) -> void
+    def initialize(snapshots: false, group: nil, recorded: nil)
+      unless group.nil? || group == :transaction
+        raise ConfigurationError, 'group: must be :transaction or nil'
+      end
+
+      @snapshots = snapshots
+      @group = group
+      @recorded = recorded
+      freeze
+    end
+
+    # Merging a group compares its outer states, so the snapshots must survive
+    # the build even when the caller did not ask to keep them.
+    #: () -> bool
+    def retain?
+      @snapshots || grouping?
+    end
+
+    # The attributes a boundary's version recorded, when they were asked for.
+    #: (root: bool) -> Array[String]?
+    def recorded_attributes(root:)
+      @recorded&.recorded_attributes(root: root)
+    end
+
+    # Applied last, to finished steps, so grouping sees the same timeline the
+    # caller would otherwise have received.
+    #: (Array[ActivityStep]) -> Array[ActivityStep]
+    def present(steps)
+      return steps unless grouping?
+
+      ActivityTransactionGrouper.new(steps, retain: @snapshots).call
+    end
+
+    private
+
+    # @rbs @snapshots: bool
+    # @rbs @group: Symbol?
+    # @rbs @recorded: IgnorePolicy?
+
+    #: () -> bool
+    def grouping?
+      @group == :transaction
+    end
+  end
+end

data/lib/paper_trail_diff/analysis.rb

@@ -11,7 +11,9 @@ module PaperTrailDiff
     attr_reader :to_snapshot #: RecordSnapshot?
 
     # The result for a record whose requested history contains no versions,
-    # which is an empty history rather than a failed request.
+    # which is an empty history rather than a failed request. Its snapshots
+    # are nil because no state was read, not because the record was absent:
+    # reading one would rebuild the whole graph, per record in a batch.
     #: () -> Analysis
     def self.empty
       timeline = [] #: Array[Step]
@@ -31,6 +33,16 @@ module PaperTrailDiff
       freeze
     end
 
+    # Every activity step's rows, in time order. Only the activity timeline says
+    # who made each change, so an analysis built without it has no rows to give.
+    #: () -> Array[ChangeRow]
+    def change_rows
+      steps = activity_timeline
+      raise ConfigurationError, 'change_rows requires activity: true' unless steps
+
+      steps.flat_map(&:change_rows).freeze
+    end
+
     # Reconstructed endpoint states are opt-in, because they carry the whole
     # selected graph whether or not anything changed, which dwarfs the rest of
     # the payload for a wide graph.

data/lib/paper_trail_diff/analysis_batch.rb

@@ -6,16 +6,16 @@ module PaperTrailDiff
   # versions and preparing their association history once for the whole batch
   # rather than once per root.
   class AnalysisBatch
-    #: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool, ?context_required: bool) -> void
+    #: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?context_required: bool) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
       records, time_range:, live_loader:, history_preparer:, analyzer:, version_scope: nil,
-      close_on_current: false, context_required: false
+      context_required: false
     )
       @records = records
       @context_required = context_required
       @time_range = time_range
-      @version_scope = validated_scope(version_scope)
-      @close_on_current = close_on_current
+      # Checked up front rather than failing partway through a batch.
+      @version_scope = VersionScopeFilter.validated(version_scope)
       @live_loader = live_loader
       @history_preparer = history_preparer
       @analyzer = analyzer
@@ -25,16 +25,17 @@ module PaperTrailDiff
     def call
       records = validated_records
       loaded = @live_loader.call(records)
+      windows = TransactionCut.batch_windows(records, @time_range)
       selected = BatchedRootVersions.new(
         records, time_range: @time_range, version_scope: @version_scope,
-                 live_endpoints: (loaded if @close_on_current),
-                 context_required: @context_required
+                 live_endpoints: loaded,
+                 context_required: @context_required, windows: windows
       ).call
-      prepare(records, selected, loaded)
+      prepare(records, selected, loaded, windows)
       records.to_h do |record|
         key = Endpoint.identity(record)
         plan = selected.fetch(key, RootVersionPlan.empty)
-        [Support.immutable_copy(key), analysis_for(record, plan)]
+        [Support.immutable_copy(key), analysis_for(record, plan, windows.fetch(key, @time_range))]
       end.freeze
     end
 
@@ -43,26 +44,19 @@ module PaperTrailDiff
     # @rbs @records: Array[untyped]
     # @rbs @time_range: TimeRange?
     # @rbs @version_scope: untyped
-    # @rbs @close_on_current: bool
     # @rbs @context_required: bool
     # @rbs @live_loader: untyped
     # @rbs @history_preparer: untyped
     # @rbs @analyzer: untyped
 
-    # A filter is a callable that narrows the version relation, so it is checked
-    # up front rather than failing partway through a batch.
-    #: (untyped) -> untyped
-    def validated_scope(scope)
-      return scope if scope.nil? || scope.respond_to?(:call)
-
-      raise ConfigurationError, 'version_scope: must respond to call'
-    end
-
     #: () -> Array[untyped]
     def validated_records
       raise ConfigurationError, 'records: must be an array' unless @records.is_a?(Array)
 
-      @records.each { |record| Endpoint.validate!(record) }
+      @records.each do |record|
+        Endpoint.validate_root!(record)
+        Endpoint.validate!(record)
+      end
       identities = @records.map { |record| Endpoint.identity(record) }
       return @records if identities.uniq.length == identities.length
 
@@ -74,8 +68,8 @@ module PaperTrailDiff
     # The roots are preloaded first, because preparation reads their current
     # association state as a fallback and would otherwise walk it one root at a
     # time.
-    #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
-    def prepare(records, selected, loaded)
+    #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped], Hash[Array[String], TimeRange]) -> void
+    def prepare(records, selected, loaded, windows)
       records.group_by(&:class).each_value do |grouped|
         versions = grouped.flat_map do |record|
           selected.fetch(Endpoint.identity(record), RootVersionPlan.empty).reconstruction_versions
@@ -84,7 +78,7 @@ module PaperTrailDiff
 
         roots = grouped.map { |record| loaded.fetch(Endpoint.identity(record), record) }
         live = closes_live?(grouped, selected)
-        @history_preparer.call(roots, versions, **preparation_range(versions, live: live))
+        @history_preparer.call(roots, versions, **preparation_range(versions, windows, live: live))
       end
     end
 
@@ -97,21 +91,21 @@ module PaperTrailDiff
 
     # A plan closing on the live record reads history up to now; the others
     # stop at the window, so a past window does not load everything since.
-    #: (Array[untyped], ?live: bool) -> Hash[Symbol, untyped]
-    def preparation_range(versions, live: @close_on_current)
-      last = versions.map(&:created_at).max
-      end_at = [last, @time_range&.end_time, (Time.now.utc if live)].compact.max
-      { start_at: @time_range&.begin_time || versions.map(&:created_at).min, end_at: end_at }
+    #: (Array[untyped], Hash[Array[String], TimeRange], live: bool) -> Hash[Symbol, untyped]
+    def preparation_range(versions, windows, live:)
+      times = versions.map(&:created_at)
+      end_at = [times.max, @time_range&.end_time, (Time.now.utc if live)].compact.max
+      { start_at: TransactionCut.earliest_start(@time_range, windows) || times.min, end_at: end_at }
     end
 
     # A root with no versions in range has nothing to report, which is an empty
     # result rather than a failed request -- unless an activity view closes it
     # on current state, where its descendants may still have moved.
-    #: (untyped, RootVersionPlan) -> Analysis
-    def analysis_for(record, plan)
+    #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
+    def analysis_for(record, plan, window)
       return Analysis.empty if plan.empty? && !plan.closing_record
 
-      @analyzer.call(record, plan)
+      @analyzer.call(record, plan, window)
     end
   end
 end

data/lib/paper_trail_diff/approximate_paths.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # The requested paths prepared history cannot read exactly, each with why.
+  # PT-AT reads such a path instead, one record at a time, when the caller
+  # passes `allow_approximate: true`.
+  module ApproximatePaths
+    #: (AssociationTraversal, untyped) -> Array[[String, String]]
+    def self.call(traversal, model)
+      traversal.selected_reflections(model).filter_map do |path, reflection|
+        reason = fallback_reason(reflection, ranked: true)
+        [path, reason] if reason
+      end
+    end
+
+    # A has_many through reads its parts' conditions only, at any depth. A
+    # has_one through over a ranked part is refused whole, so its parts, too,
+    # are checked for conditions alone.
+    #: (untyped, ranked: bool) -> String?
+    def self.fallback_reason(reflection, ranked:)
+      reason = reason_for(reflection, ranked)
+      return reason if reason || !reflection.through_reflection?
+
+      [reflection.through_reflection, reflection.source_reflection].each do |part|
+        part_reason = fallback_reason(part, ranked: false)
+        return part_reason if part_reason
+      end
+      nil
+    end
+    private_class_method :fallback_reason
+
+    # A scope prepared history can read as conditions on stored attributes
+    # is batched like any other path. A polymorphic target's class, and so
+    # its scope, is known only per record.
+    #: (untyped, bool) -> String?
+    def self.reason_for(reflection, ranked)
+      return ('association scope' if reflection.scope) if reflection.polymorphic?
+      if ranked && ScopeCondition.ranked_through?(reflection)
+        return 'limit, offset or has_one order inside a has_one through'
+      end
+      return if ScopeCondition.build(reflection, ranked: ranked)
+
+      reflection.scope ? 'association scope' : 'default-scoped target'
+    end
+    private_class_method :reason_for
+  end
+end

data/lib/paper_trail_diff/association_activity_edge.rb

@@ -74,10 +74,10 @@ module PaperTrailDiff
       #: (untyped) -> untyped
       def relation(filter)
         versions = { item_type: @reflection.klass.base_class.name, item_id: filter }
-        relation = @associations.joins(:version)
-                                .where(foreign_key_name: @reflection.foreign_key,
-                                       foreign_type: owner_types)
-                                .where(@versions.table_name => versions)
+        relation = VersionTable.joined(@associations, @versions)
+                               .where(foreign_key_name: @reflection.foreign_key,
+                                      foreign_type: owner_types)
+                               .where(@versions.table_name => versions)
         candidates(@versions, relation)
       end
 
@@ -136,8 +136,8 @@ module PaperTrailDiff
 
       #: (Hash[Symbol, untyped]) -> untyped
       def owner_rows(conditions)
-        @associations.joins(:version).where(conditions)
-                     .where(@versions.table_name => { item_type: @owner.base_class.name })
+        VersionTable.joined(@associations, @versions).where(conditions)
+                    .where(@versions.table_name => { item_type: @owner.base_class.name })
       end
     end
 

data/lib/paper_trail_diff/association_discovery.rb

@@ -102,11 +102,19 @@ module PaperTrailDiff
     #: (untyped, root: bool) -> Array[untyped]
     def supported_reflections(model_class, root:)
       reflections = model_class.reflect_on_all_associations.reject do |reflection|
-        AssociationTraversal.unsupported_reason(model_class, reflection, root: root)
+        AssociationTraversal.unsupported_reason(model_class, reflection, root: root) ||
+          unversioned?(reflection)
       end
       reflections.sort_by { |reflection| reflection.name.to_s }
     end
 
+    # Every request that reads history refuses a path whose target, or a
+    # model its has_many :through goes through, has no versions.
+    #: (untyped) -> bool
+    def unversioned?(reflection)
+      TraversalPreparer.unversioned_models(reflection).any?
+    end
+
     #: (untyped) -> untyped
     def reflection_target(reflection)
       reflection.klass unless reflection.polymorphic?

data/lib/paper_trail_diff/association_key.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # PT-AT records which record a child pointed at by that record's id, and
+  # history matches children to owners and targets by id. An association
+  # keyed on another column (`primary_key:`) would read other records'
+  # history, so it is refused.
+  module AssociationKey
+    # Why the association, or a part of a through, cannot be read by id.
+    #: (untyped) -> String?
+    def self.unsupported_reason(reflection)
+      part = keyed_part(reflection)
+      return unless part
+
+      "#{part.active_record.name}##{part.name} matches records by " \
+        "#{part.options[:primary_key]} rather than the primary key, and association " \
+        'history is recorded by primary key'
+    end
+
+    # The reflection, or the first part of a through, keyed on a column other
+    # than its owner's or target's primary key.
+    #: (untyped) -> untyped
+    def self.keyed_part(reflection)
+      return reflection if other_key?(reflection)
+      return unless reflection.through_reflection?
+
+      [reflection.through_reflection, reflection.source_reflection].filter_map do |part|
+        keyed_part(part)
+      end.first
+    end
+    private_class_method :keyed_part
+
+    # A belongs_to names a key of its target; any other macro, one of its
+    # owner. A polymorphic target has no single primary key to compare with.
+    #: (untyped) -> bool
+    def self.other_key?(reflection)
+      key = reflection.options[:primary_key]
+      return false unless key
+      return true if reflection.polymorphic?
+
+      model = reflection.belongs_to? ? reflection.klass : reflection.active_record
+      !same_column?(key, model.primary_key)
+    end
+    private_class_method :other_key?
+
+    # Column names are strings once the key is, so the one mutation left,
+    # `eql?` for `==`, answers the same.
+    # mutant:disable
+    #: (untyped, untyped) -> bool
+    def self.same_column?(key, primary_key)
+      key.to_s == primary_key
+    end
+    private_class_method :same_column?
+  end
+end

data/lib/paper_trail_diff/association_traversal.rb

@@ -3,7 +3,7 @@
 
 module PaperTrailDiff
   # Resolves and validates ActiveRecord reflections for a bounded association tree.
-  class AssociationTraversal
+  class AssociationTraversal # rubocop:disable Metrics/ClassLength
     # The class a `belongs_to` points at for this record, reading a polymorphic
     # type column when there is one. Nil when the record points at nothing.
     #: (untyped, untyped) -> untyped
@@ -66,15 +66,24 @@ module PaperTrailDiff
     def self.unsupported_reason(model_class, reflection, root:)
       return 'PaperTrail versions' if paper_trail_versions?(model_class, reflection)
       return reflection.macro.to_s unless SUPPORTED_ASSOCIATION_MACROS.include?(reflection.macro)
-      return habtm_reason(reflection, root) if reflection.macro == :has_and_belongs_to_many
+      if reflection.macro == :has_and_belongs_to_many
+        return habtm_reason(reflection, root) || VersionTable.unsupported_reason(reflection)
+      end
 
       habtm = habtm_in_chain(reflection)
-      return unless habtm
+      return storage_reason(reflection) unless habtm
 
       "it goes through #{habtm.active_record.name}##{habtm.name}, a has_and_belongs_to_many, " \
         'whose hidden join model has no history to compare'
     end
 
+    # History matches records by primary key, within one set of version tables.
+    #: (untyped) -> String?
+    def self.storage_reason(reflection)
+      AssociationKey.unsupported_reason(reflection) || VersionTable.unsupported_reason(reflection)
+    end
+    private_class_method :storage_reason
+
     # PT-AT records a HABTM's membership only when its owner saves a version,
     # in rows keyed by transaction and association name, not by owner. A root
     # checkpoint so holds the root's membership and no one else's: another
@@ -166,7 +175,7 @@ module PaperTrailDiff
     def ensure_habtm_history!(model_class, version)
       paths = habtm_paths(model_class)
       return if paths.empty?
-      return if version.respond_to?(:transaction_id) && version.transaction_id
+      return if VersionBoundary.transaction_id(version)
 
       message = "HABTM history is incomplete at version #{version.id}: #{paths.join(', ')}"
       raise IncompleteAssociationHistoryError, message

data/lib/paper_trail_diff/batch_boundary_resolver.rb

@@ -113,10 +113,9 @@ module PaperTrailDiff
     # a tie -- refusing one that ids cannot order.
     #: (untyped, Array[untyped]) -> Hash[String, untyped]
     def first_versions(model_class, ids)
-      version_class = model_class.paper_trail.version_class
-      table = version_class.arel_table
-      candidates = version_class.where(item_type: model_class.base_class.name.to_s, item_id: ids)
-                                .where(VersionQuery.no_earlier_version(table)).to_a
+      table = model_class.paper_trail.version_class.arel_table
+      candidates = VersionQuery.for_items(model_class, ids)
+                               .where(VersionQuery.no_earlier_version(table)).to_a
       candidates.group_by { |version| version.item_id.to_s }
                 .transform_values { |versions| Support.chronological_sort(versions).first }
     end

data/lib/paper_trail_diff/batch_preload.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Which associations Active Record's preloader loads correctly for many
+  # owners at once.
+  module BatchPreload
+    # The preloader applies a limit or offset to all owners' records at once,
+    # not to each owner's, so such an association is loaded per record. A
+    # has_one is no exception. Through a part with a limit, an offset or a
+    # has_one cut, the preloader keeps what the part alone would load, while
+    # the through's own query keeps the part's conditions only.
+    #
+    # The declared scope is read, not a record's association scope: Active
+    # Record adds `limit(1)` to every has_one's, which would load every
+    # has_one per record.
+    #: (untyped) -> bool
+    def self.safe?(reflection)
+      scope = reflection.scope
+      return false if scope && !scope.arity.zero?
+      return true unless reflection.collection? || reflection.has_one?
+      return false if cut_part?(reflection)
+
+      relation = declared_relation(reflection)
+      relation.limit_value.nil? && relation.offset_value.nil?
+    end
+
+    #: (untyped) -> untyped
+    def self.declared_relation(reflection)
+      relation = reflection.klass.default_scoped
+      reflection.scope ? reflection.scope_for(relation) : relation
+    end
+    private_class_method :declared_relation
+
+    #: (untyped) -> bool
+    def self.cut_part?(reflection)
+      reflection.collection? &&
+        (ScopeCondition.ranked_parts?(reflection) || through_parts(reflection).any?(&:has_one?))
+    end
+    private_class_method :cut_part?
+
+    # Every part a through passes, at any depth.
+    #: (untyped) -> Array[untyped]
+    def self.through_parts(reflection)
+      return [] unless reflection.through_reflection?
+
+      [reflection.through_reflection, reflection.source_reflection].flat_map do |part|
+        [part, *through_parts(part)]
+      end
+    end
+    private_class_method :through_parts
+  end
+end