paper_trail_diff 0.13.1 → 0.14.0

data/lib/paper_trail_diff/association_activity_edge.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # One association edge read backwards for a window: given the ids of records
+  # on its far side, the query for the owners that held them while it was open.
+  #
+  # `filter_type` is the type of the column those ids are compared with, and
+  # `type` that of the owner column the query selects, so a caller can keep a
+  # subquery only where the database can compare the two.
+  class AssociationActivityEdge
+    attr_reader :column #: untyped
+    attr_reader :type #: Symbol?
+    attr_reader :filter_type #: Symbol?
+
+    #: (untyped, TimeRange?) -> void
+    def initialize(reflection, time_range)
+      @reflection = reflection
+      @time_range = time_range
+      @owner = reflection.active_record
+    end
+
+    #: () -> bool
+    def available?
+      !@reflection.foreign_key.is_a?(Array)
+    end
+
+    #: (untyped) -> untyped
+    def relation(_filter)
+      raise NotImplementedError, "#{self.class} must build its relation"
+    end
+
+    private
+
+    # @rbs @reflection: untyped
+    # @rbs @time_range: TimeRange?
+    # @rbs @owner: untyped
+
+    # The window plus the state when it opened, which is what
+    # VersionAssociationCandidateScope selects for an activity analysis.
+    #: (untyped, untyped) -> untyped
+    def candidates(versions, relation)
+      range = @time_range
+      return relation unless range
+
+      VersionAssociationCandidateScope.new(versions, range.begin_time, end_at: range.end_time)
+                                      .call(relation)
+    end
+
+    #: (untyped, String) -> Symbol?
+    def column_type(model, name)
+      model.type_for_attribute(name).type
+    end
+
+    # A relation is compared as its SQL; ids are compared as values.
+    #: (untyped) -> untyped
+    def arel_value(filter)
+      filter.respond_to?(:arel) ? filter.arel : filter
+    end
+
+    # The owners a child pointed at when the window opened or after a change
+    # inside it, as PT-AT recorded them on the child's own versions.
+    class Child < AssociationActivityEdge
+      #: (untyped, TimeRange?) -> void
+      def initialize(reflection, time_range)
+        super
+        @versions = reflection.klass.paper_trail.version_class
+        @associations = reflection.klass.paper_trail.version_association_class
+        @column = @associations.arel_table[:foreign_key_id]
+        @type = column_type(@associations, 'foreign_key_id')
+        @filter_type = column_type(@versions, 'item_id')
+      end
+
+      #: (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)
+        candidates(@versions, relation)
+      end
+
+      private
+
+      # @rbs @versions: untyped
+      # @rbs @associations: untyped
+
+      #: () -> Array[String?]
+      def owner_types
+        [nil, '', @owner.name, @owner.base_class.name]
+      end
+    end
+
+    # The owners that pointed at a target when the window opened or after a
+    # change inside it, as PT-AT recorded them on the owners' versions.
+    class BelongsTo < AssociationActivityEdge
+      #: (untyped, TimeRange?, ?foreign_type: String?) -> void
+      def initialize(reflection, time_range, foreign_type: nil)
+        super(reflection, time_range)
+        @foreign_type = foreign_type
+        @versions = @owner.paper_trail.version_class
+        @associations = @owner.paper_trail.version_association_class
+        @column = @versions.arel_table[:item_id]
+        @type = column_type(@versions, 'item_id')
+        @filter_type = column_type(@associations, 'foreign_key_id')
+      end
+
+      # The types a polymorphic key's rows name, the only way to know its targets.
+      #: () -> Array[String]
+      def target_types
+        candidates(@versions, owner_rows(foreign_key_name: @reflection.foreign_key))
+          .distinct.pluck(@associations.arel_table[:foreign_type]).compact
+      end
+
+      # The owners that pointed at a target of this edge's type when the window
+      # opened or after a change inside it, whichever target that was.
+      #: () -> untyped
+      def typed_owners
+        conditions = { foreign_key_name: @reflection.foreign_key, foreign_type: @foreign_type }
+        candidates(@versions, owner_rows(conditions)).select(@column)
+      end
+
+      #: (untyped) -> untyped
+      def relation(filter)
+        conditions = { foreign_key_name: @reflection.foreign_key, foreign_key_id: filter }
+        conditions[:foreign_type] = @foreign_type if @foreign_type
+        candidates(@versions, owner_rows(conditions))
+      end
+
+      private
+
+      # @rbs @foreign_type: String?
+      # @rbs @versions: untyped
+      # @rbs @associations: untyped
+
+      #: (Hash[Symbol, untyped]) -> untyped
+      def owner_rows(conditions)
+        @associations.joins(:version).where(conditions)
+                     .where(@versions.table_name => { item_type: @owner.base_class.name })
+      end
+    end
+
+    # The owners a HABTM join row links to a target now. A join table has no
+    # model to type its columns, so the owner column is read by quoted name.
+    class LiveHabtm < AssociationActivityEdge
+      #: (untyped, TimeRange?) -> void
+      def initialize(reflection, time_range)
+        super
+        @table = arel::Table.new(reflection.join_table)
+        columns = join_columns
+        @type = columns.fetch(reflection.foreign_key)
+        @filter_type = columns.fetch(reflection.association_foreign_key)
+        @column = quoted_owner_column
+      end
+
+      #: (untyped) -> untyped
+      def relation(filter)
+        target = @table[@reflection.association_foreign_key]
+        @owner.base_class.unscoped.from(@table).where(target.in(arel_value(filter)))
+      end
+
+      private
+
+      # @rbs @table: untyped
+
+      #: () -> Hash[String, Symbol?]
+      def join_columns
+        connected do |connection|
+          connection.columns(@reflection.join_table).to_h { |column| [column.name, column.type] }
+        end
+      end
+
+      # Some adapters take the quoted name as a plain string too, but a raw SQL
+      # check may not, so it is marked as SQL; no SQLite spec can tell.
+      # mutant:disable
+      #: () -> untyped
+      def quoted_owner_column
+        connected do |connection|
+          arel.sql("#{connection.quote_table_name(@reflection.join_table)}." \
+                   "#{connection.quote_column_name(@reflection.foreign_key)}")
+        end
+      end
+
+      # Arel ships no signatures; see VersionQuery. Any spelling of the
+      # constant finds the same module.
+      # mutant:disable
+      #: () -> untyped
+      def arel
+        Object.const_get(:Arel)
+      end
+
+      # Active Record 7.1 has no `with_connection`; see VersionAssociationCandidateScope.
+      # Only that version takes the fallback, so no spec run on a newer one can
+      # tell its mutations apart.
+      # mutant:disable
+      #: [T] () { (untyped) -> T } -> T
+      def connected(&block)
+        return @owner.with_connection(&block) if @owner.respond_to?(:with_connection)
+
+        yield(@owner.connection)
+      end
+    end
+
+    # The owners whose versions PT-AT recorded a HABTM target with, keyed by
+    # the transaction each version was saved in.
+    class RecordedHabtm < AssociationActivityEdge
+      #: (untyped, TimeRange?) -> void
+      def initialize(reflection, time_range)
+        super
+        @versions = @owner.paper_trail.version_class
+        @associations = @owner.paper_trail.version_association_class
+        @column = @versions.arel_table[:item_id]
+        @type = column_type(@versions, 'item_id')
+        @filter_type = column_type(@associations, 'foreign_key_id')
+      end
+
+      #: () -> bool
+      def available?
+        @versions.column_names.include?('transaction_id')
+      end
+
+      #: (untyped) -> untyped
+      def relation(filter)
+        transactions = @associations.where(foreign_key_name: @reflection.name,
+                                           foreign_key_id: filter).select(:version_id)
+        relation = @versions.where(item_type: @owner.base_class.name, transaction_id: transactions)
+        range = @time_range
+        range ? relation.where(created_at: range.begin_time..) : relation
+      end
+
+      # @rbs @versions: untyped
+      # @rbs @associations: untyped
+    end
+  end
+end

data/lib/paper_trail_diff/association_activity_selection.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Finds the roots whose requested associations changed in a window, so that
+  # selecting by activity includes a record whose own row did not change.
+  #
+  # A root qualifies when a record on one of its requested paths has a version
+  # in the window while it belonged to that root: when the window opened, or
+  # after a change inside it. Those are the memberships PT-AT recorded, and the
+  # ones an activity analysis reads. For `has_many :through`, the join rows are
+  # on the path too, since creating or destroying one changes membership.
+  #
+  # Each edge is one query, walked from the leaves toward the root, never one
+  # per root. Ids stay in a subquery while the columns compared share a type;
+  # otherwise they are read and the edge runs over them in slices.
+  class AssociationActivitySelection
+    SLICE = 250
+    private_constant :SLICE
+
+    # The ids a one-column subquery selects, with that column's type: a
+    # database compares columns of one type only, and PostgreSQL rejects an
+    # integer key against a string item_id outright.
+    class Query
+      attr_reader :relation #: untyped
+      attr_reader :column #: untyped
+      attr_reader :type #: Symbol?
+
+      #: (untyped, untyped, Symbol?) -> void
+      def initialize(relation, column, type)
+        @relation = relation.select(column)
+        @column = column
+        @type = type
+        freeze
+      end
+
+      # A key PT-AT recorded as empty names no record, so it is left out.
+      #: () -> Array[untyped]
+      def values
+        @relation.distinct.pluck(@column).compact
+      end
+
+      # The ids with no match in `keys`, a subquery of the keys that exist.
+      #: (untyped) -> Array[untyped]
+      def missing(keys)
+        @relation.where(@column.not_in(keys)).distinct.pluck(@column)
+      end
+    end
+
+    # @rbs!
+    #   type source = Query | Array[untyped]
+
+    # Every id the sources name, read from the database where needed.
+    #: (Array[source]) -> Array[untyped]
+    def self.values(sources)
+      sources.flat_map { |ids| ids.is_a?(Query) ? ids.values : ids }.uniq
+    end
+
+    #: (untyped, tree: AssociationTree, time_range: TimeRange?) -> void
+    def initialize(model, tree:, time_range:)
+      @model = model
+      @traversal = AssociationTraversal.new(tree)
+      @time_range = time_range
+    end
+
+    # The roots' ids, each source a subquery or an array of values.
+    #: () -> Array[source]
+    def call
+      reach(@model, @traversal.tree, '')
+    end
+
+    private
+
+    # @rbs @model: untyped
+    # @rbs @traversal: AssociationTraversal
+    # @rbs @time_range: TimeRange?
+
+    # Ids of `model` records with a change somewhere below them in `tree`: the
+    # targets that changed, or that reach a change further down.
+    #: (untyped, AssociationTree, String) -> Array[source]
+    def reach(model, tree, path)
+      @traversal.reflections_for(model, tree, path: path).flat_map do |reflection|
+        next polymorphic_owners(reflection) if reflection.polymorphic?
+
+        target = reflection.klass
+        subtree = tree.child(reflection.name) #: AssociationTree
+        child_path = Support.association_path(path, reflection.name)
+        owners(reflection, changed(target) + reach(target, subtree, child_path))
+      end
+    end
+
+    #: (untyped, Array[source]) -> Array[source]
+    def owners(reflection, ids)
+      return [] if ids.empty?
+      return through_owners(reflection, ids) if reflection.through_reflection?
+
+      edges(reflection).flat_map { |edge| follow(edge, ids) }
+    end
+
+    # A join row that changes moves membership as surely as a target that does.
+    #: (untyped, Array[source]) -> Array[source]
+    def through_owners(reflection, ids)
+      through = reflection.through_reflection
+      source_type = reflection.options[:source_type]
+      joins = if source_type
+                typed_joins(reflection, ids, source_type)
+              else
+                owners(reflection.source_reflection, ids) + changed(through.klass)
+              end
+      owners(through, joins)
+    end
+
+    # Under `source_type:`, only join rows of that type are members, so only
+    # targets of that type and changes to those rows count.
+    #: (untyped, Array[source], untyped) -> Array[source]
+    def typed_joins(reflection, ids, source_type)
+      edge = AssociationActivityEdge::BelongsTo.new(reflection.source_reflection, @time_range,
+                                                    foreign_type: source_type)
+      follow(edge, ids) + changed(reflection.through_reflection.klass, edge.typed_owners)
+    end
+
+    # A polymorphic key's targets are known only from the types its rows name,
+    # and a path stops at one, so only the targets' own changes count.
+    #: (untyped) -> Array[source]
+    def polymorphic_owners(reflection)
+      edge = AssociationActivityEdge::BelongsTo.new(reflection, @time_range)
+      edge.target_types.flat_map do |name|
+        typed = AssociationActivityEdge::BelongsTo.new(reflection, @time_range, foreign_type: name)
+        follow(typed, changed(target_class(name)))
+      end
+    end
+
+    #: (untyped) -> Array[AssociationActivityEdge]
+    def edges(reflection)
+      kinds = case reflection.macro
+              when :belongs_to then [AssociationActivityEdge::BelongsTo]
+              when :has_and_belongs_to_many
+                [AssociationActivityEdge::LiveHabtm, AssociationActivityEdge::RecordedHabtm]
+              else [AssociationActivityEdge::Child]
+              end
+      kinds.map { |kind| kind.new(reflection, @time_range) }.select(&:available?)
+    end
+
+    # Records with a version in the window, or only those of them `item_ids`
+    # selects: under `source_type:`, the join rows that had that type.
+    #: (untyped, ?untyped) -> Array[source]
+    def changed(model, item_ids = nil)
+      return [] unless Support.versioned?(model)
+
+      versions = model.paper_trail.version_class
+      relation = versions.where(item_type: model.base_class.name)
+      relation = relation.where(item_id: item_ids) if item_ids
+      range = @time_range
+      relation = range.scope(relation) if range
+      [Query.new(relation, versions.arel_table[:item_id],
+                 versions.type_for_attribute('item_id').type)]
+    end
+
+    # One edge for each source. A subquery whose column type matches the
+    # filtered column stays a subquery; anything else is read, and the edge
+    # runs over its values in slices.
+    #: (AssociationActivityEdge, Array[source]) -> Array[source]
+    def follow(edge, sources)
+      sources.filter_map do |source|
+        query = subquery(source, edge.filter_type)
+        next Query.new(edge.relation(query.relation), edge.column, edge.type) if query
+
+        found = read(edge, self.class.values([source]))
+        found unless found.empty?
+      end
+    end
+
+    #: (AssociationActivityEdge, Array[untyped]) -> Array[untyped]
+    def read(edge, values)
+      values.each_slice(SLICE).flat_map do |slice|
+        edge.relation(slice).pluck(edge.column)
+      end.compact.uniq
+    end
+
+    # Sources are only ever a Query or a plain Array, so the one mutation
+    # left, `instance_of?` for `is_a?`, cannot change an answer.
+    # mutant:disable
+    #: (source, Symbol?) -> Query?
+    def subquery(source, type)
+      source if source.is_a?(Query) && source.type == type
+    end
+
+    # A type naming no class has no versions to read; `changed` skips one that
+    # names an unversioned class.
+    #: (String) -> untyped
+    def target_class(name)
+      Object.const_get(name)
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/paper_trail_diff/association_discovery.rb

@@ -62,7 +62,7 @@ module PaperTrailDiff
 
     #: (untyped, prefix: String, ancestry: Array[untyped], depth: Integer) -> Array[AssociationDescriptor]
     def discover(model_class, prefix:, ancestry:, depth:)
-      supported_reflections(model_class).flat_map do |reflection|
+      supported_reflections(model_class, root: prefix.empty?).flat_map do |reflection|
         describe_and_descend(reflection, prefix: prefix, ancestry: ancestry, depth: depth)
       end
     end
@@ -98,18 +98,13 @@ module PaperTrailDiff
       )
     end
 
-    #: (untyped) -> Array[untyped]
-    def supported_reflections(model_class)
-      model_class.reflect_on_all_associations
-                 .select { |reflection| SUPPORTED_ASSOCIATION_MACROS.include?(reflection.macro) }
-                 .reject { |reflection| paper_trail_versions?(model_class, reflection) }
-                 .sort_by { |reflection| reflection.name.to_s }
-    end
-
-    #: (untyped, untyped) -> bool
-    def paper_trail_versions?(model_class, reflection)
-      model_class.respond_to?(:versions_association_name) &&
-        reflection.name.to_s == model_class.versions_association_name.to_s
+    # Only what a request accepts, so every listed path can be requested.
+    #: (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)
+      end
+      reflections.sort_by { |reflection| reflection.name.to_s }
     end
 
     #: (untyped) -> untyped