paper_trail_diff 0.14.0 → 0.15.0

data/lib/paper_trail_diff/timeline_snapshot_provider.rb

@@ -2,22 +2,35 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
+  # Prepares the snapshot store for TimelineBuilder, one root at a time.
   class TimelineSnapshotProvider
     #: (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
     def initialize(store, live_snapshotter:)
       @store = store
       @live_snapshotter = live_snapshotter
-      @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
     end
 
-    #: (untyped, Array[untyped]) -> void
+    #: (untyped, Array[untyped]) -> PreparedTimelineSnapshots
     def prepare(record, versions)
-      # Adjacent steps share endpoints. Keep their immutable snapshots for this
-      # root only, including nil create states, and release them before the next
-      # root so batch memory does not retain every reconstructed graph.
-      @snapshots.clear
-      @store.prepare(record, versions)
+      history = @store.prepare(record, versions)
+      PreparedTimelineSnapshots.new(history, store: @store, live_snapshotter: @live_snapshotter)
+    end
+
+    # @rbs @store: HistoricalSnapshotStore
+    # @rbs @live_snapshotter: untyped
+  end
+
+  # One root's timeline snapshots, read with the history prepared for it.
+  # Adjacent steps share endpoints, so each immutable snapshot, including a
+  # nil create state, is kept for this root only and released with it, and
+  # batch memory does not retain every reconstructed graph.
+  class PreparedTimelineSnapshots
+    #: (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
+    def initialize(history, store:, live_snapshotter:)
+      @history = history
+      @store = store
+      @live_snapshotter = live_snapshotter
+      @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
     end
 
     # A window closing on current state ends at the live record rather than at a
@@ -28,19 +41,13 @@ module PaperTrailDiff
       return @snapshots[key] if @snapshots.key?(key)
 
       @snapshots[key] = if Endpoint.record?(endpoint)
-                          live_snapshot(endpoint)
+                          @live_snapshotter.call(endpoint)
                         else
-                          @store.uncached(endpoint, endpoint)
+                          @store.uncached(endpoint, endpoint, history: @history)
                         end
     end
 
-    private
-
-    #: (untyped) -> RecordSnapshot?
-    def live_snapshot(record)
-      @live_snapshotter.call(record)
-    end
-
+    # @rbs @history: PreparedHistory?
     # @rbs @store: HistoricalSnapshotStore
     # @rbs @live_snapshotter: untyped
     # @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]

data/lib/paper_trail_diff/transaction_cut.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Moves each edge of a wall-clock window that falls inside one of a root's
+  # transactions back to where that transaction began, so the transaction is
+  # wholly in the later window.
+  #
+  # PT-AT reads a root's associations at the start of the transaction of the
+  # root version it reifies. A window starting just after a child saved its
+  # part of such a transaction therefore starts from the state before that
+  # child's change, and one ending there ends at it too, so the change belonged
+  # to no window and surfaced at the next transaction, under its author.
+  #
+  # Only the root's own versions on either side of an edge are consulted:
+  # rows locked by an update keep two transactions of one root from
+  # interleaving, so a transaction holding a root version and crossing the edge
+  # holds the root's nearest version on one side of it. Each edge is moved from
+  # where it was asked for, never from where another edge moved, so adjacent
+  # windows move their shared edge alike.
+  module TransactionCut
+    # One edge of a window. A strict edge keeps versions recorded at its
+    # instant on the left, as an inclusive end does. A plain class rather than
+    # Data.define, which arrived in Ruby 3.2 while this gem supports 3.1.
+    class Edge
+      #: (Time, bool) -> void
+      def initialize(time, strict)
+        @time = time
+        @strict = strict
+        freeze
+      end
+
+      #: (untyped) -> untyped
+      def left(column)
+        @strict ? column.lteq(@time) : column.lt(@time)
+      end
+
+      #: (untyped) -> untyped
+      def right(column)
+        @strict ? column.gt(@time) : column.gteq(@time)
+      end
+
+      #: (untyped, later: bool) -> untyped
+      def side(column, later:)
+        later ? right(column) : left(column)
+      end
+
+      # @rbs @time: Time
+      # @rbs @strict: bool
+    end
+
+    # Roots per statement: two lookups each stays under SQLite's limit of 500
+    # terms in a compound SELECT.
+    SLICE = 200
+    private_constant :SLICE
+
+    # The same as `windows` for a batch of roots, keyed by identity.
+    #: (Array[untyped], TimeRange?) -> Hash[Array[String], TimeRange]
+    def self.batch_windows(records, range)
+      return {} unless range
+
+      moved = {} #: Hash[Array[String], TimeRange]
+      records.group_by(&:class).each_with_object(moved) do |(model_class, group), by_identity|
+        identities = group.to_h { |record| [record.id.to_s, Endpoint.identity(record)] }
+        windows(model_class, group, range).each do |id, window|
+          by_identity[identities.fetch(id)] = window
+        end
+      end
+    end
+
+    # Where history for a batch must be read from: the earliest moved start.
+    #: (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
+    def self.earliest_start(range, windows)
+      return unless range
+
+      [range.begin_time, *windows.each_value.map(&:begin_time)].min
+    end
+
+    # The windows that move, keyed by root id. A root missing from the result
+    # keeps the window as asked.
+    #: (untyped, Array[untyped], TimeRange) -> Hash[String, TimeRange]
+    def self.windows(model_class, records, range)
+      versions = transaction_versions(model_class)
+      return {} unless versions
+
+      starts = moved_edges(versions, records, Edge.new(range.begin_time, false))
+      ends = moved_edges(versions, records, Edge.new(range.end_time, !range.exclude_end?))
+      (starts.keys | ends.keys).to_h { |id| [id, moved(range, starts[id], ends[id])] }
+    end
+
+    #: (untyped) -> untyped
+    def self.transaction_versions(model_class)
+      return unless model_class.paper_trail.version_class.column_names.include?('transaction_id')
+
+      VersionQuery.for_model(model_class)
+    end
+    private_class_method :transaction_versions
+
+    # Each root's earliest start among its transactions that cross the edge.
+    #: (untyped, Array[untyped], Edge) -> Hash[String, Time]
+    def self.moved_edges(versions, records, edge)
+      roots = nearest_roots(versions, records, edge)
+      moved = {} #: Hash[String, Time]
+      starts = crossing_starts(versions.klass, roots.keys, edge)
+      starts.each_with_object(moved) do |(transaction, start), edges|
+        roots.fetch(transaction).each { |id| edges[id] = [edges[id], start].compact.min }
+      end
+    end
+    private_class_method :moved_edges
+
+    # The roots whose versions next to the edge each transaction holds.
+    #: (untyped, Array[untyped], Edge) -> Hash[untyped, Array[String]]
+    def self.nearest_roots(versions, records, edge)
+      records.each_slice(SLICE).flat_map { |slice| nearest(versions, slice, edge) }
+             .group_by(&:last).transform_values { |pairs| pairs.map(&:first) }
+    end
+    private_class_method :nearest_roots
+
+    # Each root's nearest versions on either side of an edge, as [id,
+    # transaction] pairs; versions tied at the nearest instant are all kept.
+    # One indexed lookup per root and side, where a single query over the
+    # roots would read every version before the edge. The lookups are written
+    # once with the root's id left open, as building a relation for each root
+    # costs more than the query. Rows read as SQL text come back as the adapter
+    # returns them, so the transaction is cast as the grouped query's keys are.
+    #: (untyped, Array[untyped], Edge) -> Array[[String, untyped]]
+    def self.nearest(versions, records, edge)
+      lookup = nearest_lookups(versions, edge)
+      item_id = versions.type_for_attribute('item_id')
+      lookups = records.map do |record|
+        versions.sanitize_sql_array([lookup, *Array.new(4, item_id.serialize(record.id))])
+      end
+      transaction = versions.type_for_attribute('transaction_id')
+      versions.connection.select_rows(lookups.join(' UNION ALL ')).map do |id, value|
+        [id.to_s, transaction.cast(value)]
+      end
+    end
+    private_class_method :nearest
+
+    # Both sides' lookups for a root whose id is each `?`.
+    #: (untyped, Edge) -> String
+    def self.nearest_lookups(versions, edge)
+      own = versions.where("#{versions.quoted_table_name}.item_id = ?")
+      "#{nearest_lookup(own, edge, false)} UNION ALL #{nearest_lookup(own, edge, true)}"
+    end
+    private_class_method :nearest_lookups
+
+    #: (untyped, Edge, bool) -> String
+    def self.nearest_lookup(own, edge, later)
+      column = own.arel_table[:created_at]
+      instant = own.where(edge.side(column, later: later))
+                   .reorder(created_at: later ? :asc : :desc).limit(1).select(:created_at)
+      own.where(column.eq(instant.arel)).where.not(transaction_id: nil)
+         .select(:item_id, :transaction_id).to_sql
+    end
+    private_class_method :nearest_lookup
+
+    # Where each transaction that has versions on both sides of the edge began.
+    #: (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
+    def self.crossing_starts(version_class, transactions, edge)
+      return {} if transactions.empty?
+
+      column = version_class.arel_table[:created_at]
+      scope = version_class.where(transaction_id: transactions)
+      scope.where(edge.left(column))
+           .where(transaction_id: scope.where(edge.right(column)).select(:transaction_id))
+           .group(:transaction_id).minimum(:created_at)
+    end
+    private_class_method :crossing_starts
+
+    #: (TimeRange, Time?, Time?) -> TimeRange
+    def self.moved(range, start, finish)
+      begin_time = start || range.begin_time
+      return TimeRange.new(begin_time...[finish, begin_time].max) if finish
+      return TimeRange.new(begin_time...range.end_time) if range.exclude_end?
+
+      TimeRange.new(begin_time..range.end_time)
+    end
+    private_class_method :moved
+  end
+end

data/lib/paper_trail_diff/traversal_preparer.rb

@@ -4,62 +4,167 @@
 module PaperTrailDiff
   # Checks that a model can be traversed before any reconstruction starts, and
   # that association tracking is actually available when history is involved.
+  # `diagnose` reports the same refusals instead of raising the first.
   class TraversalPreparer
-    #: (tree: AssociationTree, traversal: AssociationTraversal) -> void
-    def initialize(tree:, traversal:)
+    # One reason to refuse a request: the error `call` raises, and the code
+    # and path `diagnose` reports.
+    class Refusal
+      attr_reader :error #: untyped
+      attr_reader :code #: Symbol
+      attr_reader :message #: String
+      attr_reader :path #: String?
+
+      #: (untyped, Symbol, String, ?String?) -> void
+      def initialize(error, code, message, path = nil)
+        @error = error
+        @code = code
+        @message = message
+        @path = path
+        freeze
+      end
+    end
+
+    PROBLEMS = {
+      unversioned_association_target: '%<model>s is not versioned',
+      unversioned_through_model: 'it goes through %<model>s, which is not versioned'
+    }.freeze
+
+    # Each model a path's history needs versions of and has none, with the
+    # refusal's code: the target, then each model a has_many :through goes
+    # through. A polymorphic target is not known until a row names it;
+    # `diagnose` reports that separately rather than guessing here.
+    #: (untyped) -> Array[[Symbol, untyped]]
+    def self.unversioned_models(reflection)
+      return [] if reflection.polymorphic?
+
+      target = [:unversioned_association_target, reflection.klass] #: [Symbol, untyped]
+      through = through_models(reflection).map do |model|
+        [:unversioned_through_model, model] #: [Symbol, untyped]
+      end
+      [target, *through].reject { |_code, model| Support.versioned?(model) }
+    end
+
+    # A has_many :through reads past membership from the versions of the
+    # models it goes through, so each of them needs history too.
+    #: (untyped) -> Array[untyped]
+    def self.through_models(reflection)
+      return [] unless reflection.through_reflection?
+
+      [reflection.through_reflection, reflection.source_reflection].flat_map do |part|
+        part.polymorphic? ? through_models(part) : [part.klass, *through_models(part)]
+      end.uniq - [reflection.klass]
+    end
+    private_class_method :through_models
+
+    #: (tree: AssociationTree, traversal: AssociationTraversal, ?allow_approximate: bool) -> void
+    def initialize(tree:, traversal:, allow_approximate: false)
+      unless [true, false].include?(allow_approximate)
+        raise ConfigurationError, 'allow_approximate: must be true or false'
+      end
+
       @tree = tree
       @traversal = traversal
+      @allow_approximate = allow_approximate
+      @refusals = {} #: Hash[Array[untyped], Array[Refusal]]
     end
 
     #: (untyped, historical: bool) -> void
     def call(model_class, historical:)
-      return if @tree.empty?
+      refusal = refusals(model_class, historical: historical).first
+      raise refusal.error, refusal.message if refusal
+    end
 
-      ensure_association_tracking! if historical
-      @traversal.validate!(model_class)
-      ensure_versioned_targets!(model_class) if historical
+    # Every reason to refuse a request over the model, in the order `call`
+    # raises them. Live-to-live comparison reads current state, so only the
+    # traversal itself is checked for it.
+    #: (untyped, historical: bool) -> Array[Refusal]
+    def refusals(model_class, historical:)
+      return [] if @tree.empty?
+
+      @refusals[[model_class, historical]] ||= collect(model_class, historical).freeze
     end
 
     private
 
     # @rbs @tree: AssociationTree
     # @rbs @traversal: AssociationTraversal
+    # @rbs @allow_approximate: bool
+    # @rbs @refusals: Hash[Array[untyped], Array[Refusal]]
+
+    #: (untyped, bool) -> Array[Refusal]
+    def collect(model_class, historical)
+      found = [] #: Array[Refusal]
+      found << tracking_refusal if historical && !association_tracking?
+      unresolved = traversal_refusal(model_class)
+      return found << unresolved if unresolved
+      return found unless historical
+
+      found.concat(unversioned_refusals(model_class), approximate_refusals(model_class))
+    end
+
+    #: (untyped) -> Refusal?
+    def traversal_refusal(model_class)
+      @traversal.validate!(model_class)
+      nil
+    rescue UnknownAssociationError, UnsupportedAssociationError => e
+      code = e.is_a?(UnknownAssociationError) ? :unknown_association : :unsupported_association
+      Refusal.new(e.class, code, e.message)
+    end
+
+    # A path prepared history cannot read is read with PT-AT, which rebuilds
+    # an association from its current members, swapping in older versions of
+    # them. A record that entered the association since, such as one moved
+    # into a scope or restored from a soft delete, then reads as a member it
+    # was not, and one that left reads as missing. Only a caller who accepts
+    # that may read such a path.
+    #: (untyped) -> Array[Refusal]
+    def approximate_refusals(model_class)
+      return [] if @allow_approximate
+
+      ApproximatePaths.call(@traversal, model_class).map do |path, reason|
+        message = "association #{path} cannot be read exactly from history (#{reason}): " \
+                  'PT-AT rebuilds it from its current members, so a record that entered or ' \
+                  'left it since is reported wrongly; remove this path, make its scope plain ' \
+                  'conditions on the target\'s own columns, or pass allow_approximate: true'
+        Refusal.new(UnsupportedAssociationError, :approximate_association, message, path)
+      end
+    end
 
     # A model PaperTrail never versioned has no history to reconstruct, so a
     # comparison over it can only ever answer "nothing changed" -- which is a
     # wrong answer rather than an empty one. Live-to-live comparison reads
     # current state and is unaffected, so this applies to historical work only.
-    #: (untyped) -> void
-    def ensure_versioned_targets!(model_class)
-      @traversal.selected_reflections(model_class).each do |path, reflection|
-        # A polymorphic target is not known until a row names it; `diagnose`
-        # reports that separately rather than guessing here.
-        next if reflection.polymorphic?
-        next if versioned?(reflection.klass)
-
-        raise UnversionedAssociationError,
-              "association #{path} cannot be compared historically: " \
-              "#{reflection.klass.name} is not versioned. Add `has_paper_trail` to it, " \
-              'or mirror the fields you need onto a model that has it.'
+    #: (untyped) -> Array[Refusal]
+    def unversioned_refusals(model_class)
+      @traversal.selected_reflections(model_class).flat_map do |path, reflection|
+        self.class.unversioned_models(reflection).map do |code, model|
+          unversioned(path, model, code)
+        end
       end
     end
 
-    #: (untyped) -> bool
-    def versioned?(model_class)
-      Support.versioned?(model_class)
+    #: (String, untyped, Symbol) -> Refusal
+    def unversioned(path, model_class, code)
+      problem = format(PROBLEMS.fetch(code), model: model_class.name)
+      message = "association #{path} cannot be compared historically: #{problem}. " \
+                "Add `has_paper_trail` to #{model_class.name}, or mirror the fields you need " \
+                'onto a model that has it.'
+      Refusal.new(UnversionedAssociationError, code, message, path)
     end
 
-    #: () -> void
-    def ensure_association_tracking!
+    #: () -> bool
+    def association_tracking?
       paper_trail = Object.const_get(:PaperTrail) #: untyped
       config = paper_trail.config #: untyped
-      available = defined?(::PaperTrailAssociationTracking) &&
-                  config.respond_to?(:track_associations?) &&
-                  config.track_associations?
-      return if available
+      !!(defined?(::PaperTrailAssociationTracking) &&
+        config.respond_to?(:track_associations?) && config.track_associations?)
+    end
 
-      message = 'association tracking must be loaded and enabled to compare historical associations'
-      raise AssociationTrackingUnavailableError, message
+    #: () -> Refusal
+    def tracking_refusal
+      Refusal.new(AssociationTrackingUnavailableError, :association_tracking_unavailable,
+                  'association tracking must be loaded and enabled to compare historical ' \
+                  'associations')
     end
   end
 end

data/lib/paper_trail_diff/version.rb

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

data/lib/paper_trail_diff/version_boundary.rb

@@ -18,13 +18,49 @@ module PaperTrailDiff
       return true unless version_record?(boundary)
       return true if same_version?(candidate, boundary)
 
-      unless orderable_tie?(candidate, boundary)
+      unless Support.orderable_tie?(candidate, boundary)
         raise AmbiguousVersionOrderError, Support.ambiguous_message([boundary, candidate])
       end
 
       Support.compare_versions(candidate, boundary) >= 0
     end
 
+    # A range starting at a version starts before that version's transaction,
+    # as PT-AT reads associations there. A version saved earlier in the same
+    # transaction, such as the child update behind a `touch: true` parent
+    # version, can be recorded before the start, so the start moves back to
+    # the earliest version of each root's first transaction in the range.
+    # History loaded from the start alone would read that child after its
+    # change.
+    #: (Array[untyped], untyped) -> untyped
+    def transaction_start(root_versions, start_at)
+      opening = opening_transactions(root_versions, start_at)
+      return start_at if opening.empty?
+
+      earliest = root_versions.first.class.where(transaction_id: opening).minimum(:created_at)
+      earliest && earliest < start_at ? earliest : start_at
+    end
+
+    # The transaction of each root's first version at or after the start.
+    #: (Array[untyped], untyped) -> Array[untyped]
+    def opening_transactions(root_versions, start_at)
+      return [] unless start_at
+
+      root_versions.reject { |version| version.created_at < start_at }
+                   .sort_by { |version| Support.chronological_version_key(version) }
+                   .uniq { |version| [version.item_type.to_s, version.item_id.to_s] }
+                   .filter_map { |version| transaction_id(version) }.uniq
+    end
+    private_class_method :opening_transactions
+
+    # A custom version class need not carry the column, and PaperTrail leaves
+    # it nil outside a transaction. Both read as "no transaction here", which
+    # groups with nothing.
+    #: (untyped) -> untyped
+    def transaction_id(version)
+      version.transaction_id if version.respond_to?(:transaction_id)
+    end
+
     #: (untyped) -> bool
     def version_record?(value)
       value.respond_to?(:id) && value.respond_to?(:item_type) &&
@@ -37,12 +73,5 @@ module PaperTrailDiff
       left.class.table_name == right.class.table_name && left.id.to_s == right.id.to_s
     end
     private_class_method :same_version?
-
-    #: (untyped, untyped) -> bool
-    def orderable_tie?(left, right)
-      left.class.table_name == right.class.table_name &&
-        Support.sequential_id?(left.id) && Support.sequential_id?(right.id)
-    end
-    private_class_method :orderable_tie?
   end
 end

data/lib/paper_trail_diff/version_query.rb

@@ -14,28 +14,52 @@ module PaperTrailDiff
       relation.reorder(created_at: :asc, id: :asc)
     end
 
+    # Every version of a model's items. They are read from the version class
+    # rather than through the model's versions association, whose scope may
+    # leave some out: a history replayed without them credits their changes to
+    # the next version kept.
+    #: (untyped) -> untyped
+    def for_model(model_class)
+      model_class.paper_trail.version_class.where(item_type: model_class.base_class.name)
+    end
+
+    # The versions of the given items, read the same way.
+    #: (untyped, untyped) -> untyped
+    def for_items(model_class, ids)
+      for_model(model_class).where(item_id: ids)
+    end
+
     # Keeps each item's earliest version among those the block also accepts:
     # no other version of the same item that the block accepts is earlier. A
     # correlated NOT EXISTS stays portable where window functions are not.
     #: (untyped) ?{ (untyped) -> untyped } -> untyped
     def no_earlier_version(table, &block)
+      no_nearer_version(table, later: true, &block)
+    end
+
+    # The same for either side of an instant: each item's earliest version
+    # when the versions lie after it, and its latest when they lie before.
+    #: (untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
+    def no_nearer_version(table, later:, &block)
       arel = Object.const_get(:Arel) #: untyped
-      earlier = table.alias('paper_trail_diff_earlier_versions')
+      other = table.alias('paper_trail_diff_earlier_versions')
       arel.const_get(:SelectManager).new
-          .from(earlier)
+          .from(other)
           .project(arel.sql('1'))
-          .where(earlier_version(table, earlier, &block))
+          .where(nearer_version(table, other, later: later, &block))
           .exists
           .not
     end
 
-    #: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
-    def earlier_version(table, earlier)
-      same_item = earlier[:item_type].eq(table[:item_type])
-                                     .and(earlier[:item_id].eq(table[:item_id]))
-                                     .and(earlier[:created_at].lt(table[:created_at]))
-      block_given? ? same_item.and(yield(earlier)) : same_item
+    #: (untyped, untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
+    def nearer_version(table, other, later:)
+      created_at = other[:created_at]
+      nearer = later ? created_at.lt(table[:created_at]) : created_at.gt(table[:created_at])
+      same_item = other[:item_type].eq(table[:item_type])
+                                   .and(other[:item_id].eq(table[:item_id]))
+                                   .and(nearer)
+      block_given? ? same_item.and(yield(other)) : same_item
     end
-    private_class_method :earlier_version
+    private_class_method :nearer_version
   end
 end

data/lib/paper_trail_diff/version_scope_filter.rb

@@ -7,9 +7,17 @@ module PaperTrailDiff
   # caller, because the one that reveals the last selected mutation is drawn
   # from them.
   class VersionScopeFilter
+    # A filter is a callable that narrows the version relation.
+    #: (untyped) -> untyped
+    def self.validated(scope)
+      return scope if scope.nil? || scope.respond_to?(:call)
+
+      raise ConfigurationError, 'version_scope: must respond to call'
+    end
+
     #: (untyped) -> void
     def initialize(scope)
-      @scope = validated(scope)
+      @scope = self.class.validated(scope)
     end
 
     #: (untyped, Array[untyped]) -> Array[untyped]
@@ -31,15 +39,6 @@ module PaperTrailDiff
       Set.new(scope.call(relation).pluck(:id))
     end
 
-    private
-
     # @rbs @scope: untyped
-
-    #: (untyped) -> untyped
-    def validated(scope)
-      return scope if scope.nil? || scope.respond_to?(:call)
-
-      raise ConfigurationError, 'version_scope: must respond to call'
-    end
   end
 end