paper_trail_diff 0.1.0

data/lib/paper_trail_diff/historical_snapshot_store.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Reconstructs and caches immutable historical snapshots for one adapter configuration.
+  class HistoricalSnapshotStore
+    #: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
+    def initialize(tree:, traversal:, normalizer:, preparer:)
+      @tree = tree
+      @traversal = traversal
+      @normalizer = normalizer
+      @preparer = preparer
+      @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
+      @prepared_history = nil #: PreparedHistory?
+    end
+
+    #: (untyped, Array[untyped]) -> void
+    def prepare(record, root_versions)
+      return if @tree.empty?
+
+      @prepared_history = PreparedHistoryLoader.new(
+        record,
+        root_versions: root_versions,
+        tree: @tree,
+        traversal: @traversal
+      ).call
+    end
+
+    #: (untyped, untyped) -> RecordSnapshot?
+    def call(root_endpoint, context_endpoint)
+      key = snapshot_key(root_endpoint, context_endpoint)
+      return @snapshots[key] if @snapshots.key?(key)
+
+      @snapshots[key] = custom(
+        root_endpoint,
+        context_endpoint,
+        tree: @tree,
+        normalizer: @normalizer
+      )
+    end
+
+    #: (untyped, untyped) -> RecordSnapshot?
+    def uncached(root_endpoint, context_endpoint)
+      custom(
+        root_endpoint,
+        context_endpoint,
+        tree: @tree,
+        normalizer: @normalizer
+      )
+    end
+
+    #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
+    def custom(root_endpoint, context_endpoint, tree:, normalizer:)
+      if Endpoint.version?(root_endpoint)
+        return snapshot_from_version(
+          root_endpoint,
+          context_endpoint,
+          tree: tree,
+          normalizer: normalizer
+        )
+      end
+
+      snapshot_from_live_root(
+        root_endpoint,
+        context_endpoint,
+        tree: tree,
+        normalizer: normalizer
+      )
+    end
+
+    #: (untyped, habtm_version: untyped) -> untyped
+    def association_reader(context_version, habtm_version:)
+      fallback = HistoricalAssociationReifier.new(
+        context_version,
+        habtm_version: habtm_version
+      )
+      history = @prepared_history
+      return fallback unless history
+
+      PreparedAssociationReifier.new(
+        history,
+        context_version,
+        habtm_boundary: habtm_version,
+        fallback: fallback
+      )
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @traversal: AssociationTraversal
+    # @rbs @normalizer: SnapshotNormalizer
+    # @rbs @preparer: untyped
+    # @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]
+    # @rbs @prepared_history: PreparedHistory?
+
+    #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
+    def snapshot_from_version(root_version, context_version, tree:, normalizer:)
+      model_class = Endpoint.model_class(root_version)
+      @preparer.call(model_class, historical: true)
+      @traversal.ensure_habtm_history!(model_class, root_version)
+      record = root_version.reify(dup: true)
+      normalize(
+        record,
+        context_version,
+        tree: tree,
+        normalizer: normalizer,
+        habtm_version: root_version
+      )
+    end
+
+    #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
+    def snapshot_from_live_root(root_record, context_version, tree:, normalizer:)
+      record = Endpoint.reload_record(root_record)
+      @preparer.call(record.class, historical: true)
+      normalize(
+        record,
+        context_version,
+        tree: tree,
+        normalizer: normalizer,
+        habtm_version: context_version
+      )
+    end
+
+    #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped) -> RecordSnapshot?
+    def normalize(record, context_version, tree:, normalizer:, habtm_version:)
+      reifier = association_reader(context_version, habtm_version: habtm_version)
+      reflections = [] #: Array[untyped]
+      reflections = @traversal.reflections_for(record.class, tree, path: '') if record
+      reifier.reify(record, reflections) if record && !reflections.empty?
+      normalizer.call(record, reifier: reifier)
+    end
+
+    #: (untyped, untyped) -> Array[untyped]
+    def snapshot_key(root_endpoint, context_endpoint)
+      [
+        root_endpoint.class.name,
+        root_endpoint.id,
+        context_endpoint.class.name,
+        context_endpoint.id
+      ]
+    end
+  end
+end

data/lib/paper_trail_diff/live_association_reader.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Leaves live ActiveRecord associations untouched while sharing snapshot normalization.
+  class LiveAssociationReader
+    #: (untyped, Array[untyped]) -> void
+    def reify(_record, _reflections); end
+  end
+end

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # PaperTrail/ActiveRecord boundary that produces plain record snapshots.
+  class PaperTrailAdapter
+    #: (associations: Array[String | Symbol], ignore: ignore_option) -> void
+    def initialize(associations:, ignore:)
+      @association_tree = AssociationTree.build(associations)
+      @ignore_policy = IgnorePolicy.build(ignore, association_paths: @association_tree.paths)
+      @traversal = AssociationTraversal.new(@association_tree)
+      @snapshot_pool = SnapshotPool.new
+      @normalizer = SnapshotNormalizer.new(
+        tree: @association_tree,
+        ignore_policy: @ignore_policy,
+        traversal: @traversal,
+        pool: @snapshot_pool
+      )
+      @historical_store = build_historical_store
+      @timeline_snapshotter = TimelineSnapshotProvider.new(@historical_store)
+      @activity_snapshotter = build_activity_snapshotter
+    end
+
+    #: (untyped, untyped) -> Diff
+    def compare(from_endpoint, to_endpoint)
+      Endpoint.validate_pair!(from_endpoint, to_endpoint)
+      Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
+    end
+
+    #: (untyped, from: untyped, to: untyped) -> Array[Step]
+    def timeline(record, from:, to:)
+      prepare_traversal!(record.class, historical: true)
+      builder = TimelineBuilder.new(
+        record,
+        from: from,
+        to: to,
+        snapshotter: @timeline_snapshotter
+      )
+      builder.build
+    end
+
+    #: (untyped, from: untyped, to: untyped) -> Array[ActivityStep]
+    def activity_timeline(record, from:, to:)
+      prepare_traversal!(record.class, historical: true)
+      reject_live_habtm_activity!(record.class) if Endpoint.record?(to)
+      ActivityTimelineBuilder.new(
+        record,
+        from: from,
+        to: to,
+        tree: @association_tree,
+        snapshotter: @activity_snapshotter
+      ).build
+    end
+
+    #: (untyped, from: untyped, to: untyped, ?activity: bool) -> Analysis
+    def analyze(record, from:, to:, activity: false)
+      if activity
+        prepare_traversal!(record.class, historical: true)
+        return activity_builder(record, from: from, to: to).analyze
+      end
+
+      prepare_traversal!(record.class, historical: true)
+      TimelineBuilder.new(
+        record,
+        from: from,
+        to: to,
+        snapshotter: @timeline_snapshotter
+      ).analyze
+    end
+
+    private
+
+    # @rbs @association_tree: AssociationTree
+    # @rbs @ignore_policy: IgnorePolicy
+    # @rbs @traversal: AssociationTraversal
+    # @rbs @snapshot_pool: SnapshotPool
+    # @rbs @normalizer: SnapshotNormalizer
+    # @rbs @historical_store: HistoricalSnapshotStore
+    # @rbs @timeline_snapshotter: TimelineSnapshotProvider
+    # @rbs @activity_snapshotter: ActivitySnapshotProvider
+
+    #: () -> HistoricalSnapshotStore
+    def build_historical_store
+      HistoricalSnapshotStore.new(
+        tree: @association_tree,
+        traversal: @traversal,
+        normalizer: @normalizer,
+        preparer: method(:prepare_traversal!)
+      )
+    end
+
+    #: () -> ActivitySnapshotProvider
+    def build_activity_snapshotter
+      refresher = BranchSnapshotRefresher.new(
+        tree: @association_tree,
+        ignore_policy: @ignore_policy,
+        traversal: @traversal,
+        pool: @snapshot_pool,
+        normalizer: @normalizer,
+        full_snapshotter: method(:snapshot_at),
+        partial_snapshotter: @historical_store.method(:custom),
+        association_reader: @historical_store.method(:association_reader)
+      )
+      ActivitySnapshotProvider.new(
+        snapshotter: method(:snapshot_at),
+        refresher: refresher,
+        preparer: @historical_store.method(:prepare)
+      )
+    end
+
+    #: (untyped, from: untyped, to: untyped) -> ActivityTimelineBuilder
+    def activity_builder(record, from:, to:)
+      ActivityTimelineBuilder.new(
+        record,
+        from: from,
+        to: to,
+        tree: @association_tree,
+        snapshotter: @activity_snapshotter
+      )
+    end
+
+    #: (untyped) -> void
+    def reject_live_habtm_activity!(model_class)
+      paths = @traversal.habtm_paths(model_class)
+      return if paths.empty?
+
+      message = "live-ended activity cannot reconstruct HABTM event boundaries: #{paths.join(', ')}"
+      raise UnsupportedLiveActivityError, message
+    end
+
+    #: (untyped) -> RecordSnapshot?
+    def snapshot_for_endpoint(endpoint)
+      Endpoint.version?(endpoint) ? historical_snapshot(endpoint) : live_snapshot(endpoint)
+    end
+
+    #: (untyped) -> RecordSnapshot?
+    def historical_snapshot(version)
+      snapshot_at(version, version)
+    end
+
+    #: (untyped) -> RecordSnapshot?
+    def uncached_historical_snapshot(version)
+      @historical_store.uncached(version, version)
+    end
+
+    #: (untyped, untyped) -> RecordSnapshot?
+    def snapshot_at(root_endpoint, context_endpoint)
+      return live_snapshot(root_endpoint) if Endpoint.record?(context_endpoint)
+
+      @historical_store.call(root_endpoint, context_endpoint)
+    end
+
+    #: (untyped) -> RecordSnapshot
+    def live_snapshot(record)
+      current = Endpoint.reload_record(record)
+      prepare_traversal!(current.class, historical: false)
+      @normalizer.call(current, reifier: LiveAssociationReader.new) ||
+        raise(InvalidEndpointError, 'current record endpoint could not be normalized')
+    end
+
+    #: (untyped, historical: bool) -> void
+    def prepare_traversal!(model_class, historical:)
+      return if @association_tree.empty?
+
+      ensure_association_tracking! if historical
+      @traversal.validate!(model_class)
+    end
+
+    #: () -> void
+    def ensure_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
+
+      message = 'association tracking must be loaded and enabled to compare historical associations'
+      raise AssociationTrackingUnavailableError, message
+    end
+  end
+end

data/lib/paper_trail_diff/prepared_association_reifier.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Resolves indexed associations and delegates unsupported reflections to PT-AT.
+  class PreparedAssociationReifier
+    #: (PreparedHistory, untyped, habtm_boundary: untyped, fallback: HistoricalAssociationReifier) -> void
+    def initialize(history, boundary, habtm_boundary:, fallback:)
+      @history = history
+      @boundary = boundary
+      @habtm_boundary = habtm_boundary
+      @fallback = fallback
+      @reified = {} #: Hash[Array[untyped], bool]
+    end
+
+    #: (untyped, Array[untyped]) -> void
+    def reify(record, reflections)
+      reflections.each { |reflection| reify_association(record, reflection) }
+    end
+
+    private
+
+    # @rbs @history: PreparedHistory
+    # @rbs @boundary: untyped
+    # @rbs @habtm_boundary: untyped
+    # @rbs @fallback: HistoricalAssociationReifier
+    # @rbs @reified: Hash[Array[untyped], bool]
+
+    #: (untyped, untyped) -> void
+    def reify_association(record, reflection)
+      key = [record.object_id, reflection.name]
+      return if @reified[key]
+
+      @reified[key] = true
+      handled, records = @history.resolve(
+        record,
+        reflection,
+        @boundary,
+        habtm_boundary: @habtm_boundary
+      )
+      return @fallback.reify(record, [reflection]) unless handled
+
+      association = record.association(reflection.name)
+      association.target = reflection.collection? ? records : records.first
+      association.loaded!
+    end
+  end
+end

data/lib/paper_trail_diff/prepared_edge_loader.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Loads every historical identity that can participate in one association edge.
+  class PreparedEdgeLoader
+    EDGE_LOADERS = {
+      belongs_to: :belongs_to_edge,
+      has_one: :child_edge,
+      has_many: :child_edge,
+      has_and_belongs_to_many: :habtm_edge
+    }.freeze
+    private_constant :EDGE_LOADERS
+
+    #: (PreparedRecordIndex, Array[untyped]) -> void
+    def initialize(records, root_versions)
+      @records = records
+      @transaction_ids = root_versions.filter_map(&:transaction_id).uniq.freeze
+    end
+
+    #: (untyped, Array[untyped], untyped) -> [Hash[String, Hash[Symbol, untyped]], Hash[String, Array[untyped]]?]
+    def call(owner_class, owner_ids, reflection)
+      loader = EDGE_LOADERS.fetch(reflection.macro)
+      send(loader, owner_class, owner_ids, reflection)
+    end
+
+    private
+
+    # @rbs @records: PreparedRecordIndex
+    # @rbs @transaction_ids: Array[untyped]
+
+    #: (untyped, Array[untyped], untyped) -> [Hash[String, Hash[Symbol, untyped]], nil]
+    def belongs_to_edge(owner_class, owner_ids, reflection)
+      [belongs_to_groups(owner_class, owner_ids, reflection), nil]
+    end
+
+    #: (untyped, Array[untyped], untyped) -> [Hash[String, Hash[Symbol, untyped]], nil]
+    def child_edge(owner_class, owner_ids, reflection)
+      [child_groups(owner_class, owner_ids, reflection), nil]
+    end
+
+    #: (untyped, Array[untyped], untyped) -> [Hash[String, Hash[Symbol, untyped]], Hash[String, Array[untyped]]]
+    def habtm_edge(owner_class, _owner_ids, reflection)
+      habtm_groups(owner_class, reflection)
+    end
+
+    #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
+    def belongs_to_groups(owner_class, owner_ids, reflection)
+      key = scalar_foreign_key(reflection)
+      return {} unless key
+
+      grouped = {} #: Hash[String, Hash[Symbol, untyped]]
+      @records.records_for(owner_class, owner_ids).each do |owner|
+        id = owner.public_send(key)
+        model_class = target_class(reflection, owner)
+        add_identity(grouped, model_class, id) if model_class && id
+      end
+      grouped
+    end
+
+    #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
+    def child_groups(owner_class, owner_ids, reflection)
+      key = scalar_foreign_key(reflection)
+      return {} unless key
+
+      ids = historical_child_ids(owner_class, owner_ids, reflection, key)
+      ids.concat(live_child_ids(owner_class, owner_ids, reflection, key))
+      group_for(reflection.klass, ids)
+    end
+
+    #: (untyped, untyped) -> [Hash[String, Hash[Symbol, untyped]], Hash[String, Array[untyped]]]
+    def habtm_groups(owner_class, reflection)
+      rows = habtm_rows(owner_class, reflection)
+      memberships = @transaction_ids.to_h do |transaction_id|
+        [transaction_id.to_s, membership_ids(rows, transaction_id)]
+      end
+      [group_for(reflection.klass, rows.filter_map(&:foreign_key_id)), memberships]
+    end
+
+    #: (untyped, untyped) -> Array[untyped]
+    def habtm_rows(owner_class, reflection)
+      owner_class.paper_trail.version_association_class.where(
+        version_id: @transaction_ids,
+        foreign_key_name: reflection.name.to_s
+      ).to_a
+    end
+
+    #: (Array[untyped], untyped) -> Array[untyped]
+    def membership_ids(rows, transaction_id)
+      rows.filter_map do |row|
+        row.foreign_key_id if row.version_id.to_s == transaction_id.to_s
+      end.uniq
+    end
+
+    #: (untyped, Array[untyped], untyped, String) -> Array[untyped]
+    def historical_child_ids( # rubocop:disable Metrics/AbcSize
+      owner_class,
+      owner_ids,
+      reflection,
+      foreign_key
+    )
+      version_class = owner_class.paper_trail.version_class
+      relation = owner_class.paper_trail.version_association_class.joins(:version).where(
+        foreign_key_name: foreign_key,
+        foreign_key_id: owner_ids
+      ).where(foreign_type: parent_types(owner_class)).where(
+        version_class.table_name => { item_type: reflection.klass.base_class.name }
+      )
+      relation.distinct.pluck(version_class.arel_table[:item_id])
+    end
+
+    #: (untyped, Array[untyped], untyped, String) -> Array[untyped]
+    def live_child_ids(owner_class, owner_ids, reflection, foreign_key)
+      relation = reflection.klass.base_class.unscoped.where(foreign_key => owner_ids)
+      if reflection.options[:as]
+        relation = relation.where(reflection.type => parent_types(owner_class))
+      end
+      relation.pluck(reflection.klass.primary_key)
+    end
+
+    #: (untyped, untyped) -> untyped
+    def target_class(reflection, owner)
+      return reflection.klass unless reflection.polymorphic?
+
+      Object.const_get(owner.public_send(reflection.foreign_type).to_s)
+    rescue NameError
+      nil
+    end
+
+    #: (Hash[String, Hash[Symbol, untyped]], untyped, untyped) -> void
+    def add_identity(groups, model_class, id)
+      group = groups[model_class.name.to_s] ||= { model: model_class, ids: [] }
+      group.fetch(:ids) << id unless group.fetch(:ids).include?(id)
+    end
+
+    #: (untyped, Array[untyped]) -> Hash[String, Hash[Symbol, untyped]]
+    def group_for(model_class, ids)
+      unique = ids.compact.uniq
+      return {} if unique.empty?
+
+      { model_class.name.to_s => { model: model_class, ids: unique } }
+    end
+
+    #: (untyped) -> String?
+    def scalar_foreign_key(reflection)
+      key = reflection.foreign_key
+      key.to_s unless key.is_a?(Array)
+    end
+
+    #: (untyped) -> Array[String?]
+    def parent_types(owner_class)
+      [nil, '', owner_class.name.to_s, owner_class.base_class.name.to_s].uniq
+    end
+  end
+end