paper_trail_diff 0.3.0 → 0.4.0

data/lib/paper_trail_diff/activity_collection_event_applier.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Applies a safe collection event across every selected route for its record type.
+  class ActivityCollectionEventApplier
+    #: (record_resolver: ActivityEventRecordResolver, record_normalizer: ActivityEventRecordNormalizer, route_updater: ActivityCollectionRouteUpdater, relationship: ActivityRelationship) -> void
+    def initialize(record_resolver:, record_normalizer:, route_updater:, relationship:)
+      @record_resolver = record_resolver
+      @record_normalizer = record_normalizer
+      @route_updater = route_updater
+      @relationship = relationship
+    end
+
+    #: (Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> bool
+    def safe?(routes, version, delta)
+      !unsafe_through_membership_event?(routes, version) &&
+        !unsafe_nested_membership_delta?(routes, delta)
+    end
+
+    #: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> [bool, RecordSnapshot]
+    def call( # rubocop:disable Metrics/ParameterLists
+      root_endpoint,
+      context_endpoint,
+      previous,
+      normalizer,
+      routes,
+      version,
+      delta
+    )
+      fallback_record = [] #: Array[untyped]
+      endpoints = [root_endpoint, context_endpoint]
+      snapshot = routes.reduce(previous) do |current, route|
+        apply_route(
+          current, route, version, delta, fallback_record, normalizer, endpoints
+        )
+      end
+      [true, snapshot]
+    end
+
+    private
+
+    # @rbs @record_resolver: ActivityEventRecordResolver
+    # @rbs @record_normalizer: ActivityEventRecordNormalizer
+    # @rbs @route_updater: ActivityCollectionRouteUpdater
+    # @rbs @relationship: ActivityRelationship
+
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped]) -> RecordSnapshot
+    def apply_route( # rubocop:disable Metrics/ParameterLists
+      snapshot, route, version, delta, fallback_record, normalizer, endpoints
+    )
+      record, replacement = route_event_state(
+        snapshot, route, version, delta, fallback_record, normalizer, endpoints
+      )
+      change = ActivityCollectionRouteChange.new(
+        route: route,
+        version: version,
+        record: record,
+        replacement: replacement
+      )
+      @route_updater.call(snapshot, change).fetch(0)
+    end
+
+    #: (Array[Array[untyped]], untyped) -> bool
+    def unsafe_through_membership_event?(routes, version)
+      return false if version.event.to_s == 'update'
+
+      routes.any? do |route|
+        route.first(route.length - 1).any? do |entry|
+          entry.fetch(1).options[:through]
+        end
+      end
+    end
+
+    #: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
+    def unsafe_nested_membership_delta?(routes, delta)
+      return false unless delta
+
+      routes.any? do |route|
+        route.length > 1 && delta.relationship_changed?(route.last.fetch(1))
+      end
+    end
+
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped]) -> [untyped, RecordSnapshot?]
+    def route_event_state( # rubocop:disable Metrics/ParameterLists
+      snapshot, route, version, delta, fallback_record, normalizer, endpoints
+    )
+      existing = existing_delta_record(snapshot, route, version, delta) if delta
+      return [delta, delta.apply(existing)] if delta && existing
+
+      fallback_record << @record_resolver.record_after(version) if fallback_record.empty?
+      record = fallback_record.first
+      return [record, nil] unless record
+
+      [record, normalized_event_record(record, route, normalizer, endpoints)]
+    end
+
+    #: (untyped, Array[untyped], SnapshotNormalizer, Array[untyped]) -> RecordSnapshot?
+    def normalized_event_record(record, route, normalizer, endpoints)
+      _name, reflection, subtree, path = route.last
+      @record_normalizer.call(
+        record,
+        reflection: reflection,
+        subtree: subtree,
+        path: path,
+        normalizer: normalizer,
+        root_endpoint: endpoints.fetch(0),
+        context_endpoint: endpoints.fetch(1)
+      )
+    end
+
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?) -> RecordSnapshot?
+    def existing_delta_record(snapshot, route, version, delta)
+      return unless delta && route.length.between?(1, 2)
+
+      owner = route.length == 1 ? snapshot : nested_delta_owner(snapshot, route, delta)
+      return unless owner
+
+      association = owner.associations.fetch(route.last.fetch(0))
+      position = association.position_for_id(version.item_id)
+      association.records.fetch(position) if position
+    end
+
+    #: (RecordSnapshot, Array[untyped], ActivitySnapshotDelta) -> RecordSnapshot?
+    def nested_delta_owner(snapshot, route, delta)
+      parent_name = route.first.fetch(0)
+      reflection = route.last.fetch(1)
+      association = snapshot.associations.fetch(parent_name)
+      owner_id = @relationship.owner_id(delta, reflection, state: :before)
+      position = association.position_for_id(owner_id)
+      return unless position
+
+      owner = association.records.fetch(position)
+      owner if @relationship.member_of_owner?(delta, reflection, owner, state: :before)
+    end
+  end
+end

data/lib/paper_trail_diff/activity_collection_record_updater.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Applies one event to the leaf records of a collection association snapshot.
+  class ActivityCollectionRecordUpdater
+    #: (ActivityRelationship) -> void
+    def initialize(relationship)
+      @relationship = relationship
+    end
+
+    #: (AssociationSnapshot, ActivityCollectionRouteChange, untyped, RecordSnapshot) -> RecordSnapshot?
+    def event_child(association, change, reflection, owner)
+      version = change.version
+      record = change.record
+      replacement = change.replacement
+      return unless record
+
+      unless record.is_a?(ActivitySnapshotDelta)
+        return replacement if @relationship.member_of_owner?(record, reflection, owner)
+
+        return
+      end
+      unless record.relationship_changed?(reflection)
+        return replacement if association.position_for_id(version.item_id)
+
+        return
+      end
+
+      replacement if @relationship.member_of_owner?(record, reflection, owner)
+    end
+
+    #: (AssociationSnapshot, untyped, RecordSnapshot?) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]
+    def call(association, version, replacement)
+      records = association.records
+      position = association.position(replacement_type(version, replacement), version.item_id)
+      return [records, nil, nil, true] unless replacement || position
+
+      before = records.fetch(position) if position
+      updated = replacement_records(records, position, replacement)
+      [updated, before, replacement, !before.nil? && !replacement.nil?]
+    end
+
+    #: (untyped, RecordSnapshot?) -> String
+    def replacement_type(version, replacement)
+      return replacement.type.to_s if replacement
+
+      Endpoint.model_class(version).name.to_s
+    end
+
+    private
+
+    # @rbs @relationship: ActivityRelationship
+
+    #: (Array[RecordSnapshot], Integer?, RecordSnapshot?) -> Array[RecordSnapshot]
+    def replacement_records(records, position, replacement)
+      updated = records.dup
+      if replacement
+        position ? updated[position] = replacement : updated << replacement
+      else
+        position ||= raise(ConfigurationError, 'missing collection event identity')
+        updated.delete_at(position)
+      end
+      updated.freeze
+    end
+  end
+end

data/lib/paper_trail_diff/activity_collection_route_change.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Carries one collection event through recursive immutable route replacement.
+  class ActivityCollectionRouteChange
+    attr_reader :route #: Array[untyped]
+    attr_reader :version #: untyped
+    attr_reader :record #: untyped
+    attr_reader :replacement #: RecordSnapshot?
+
+    #: (route: Array[untyped], version: untyped, record: untyped, replacement: RecordSnapshot?) -> void
+    def initialize(route:, version:, record:, replacement:)
+      @route = route
+      @version = version
+      @record = record
+      @replacement = replacement
+      freeze
+    end
+  end
+end

data/lib/paper_trail_diff/activity_collection_route_updater.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Replaces a collection event record along one explicit immutable snapshot route.
+  class ActivityCollectionRouteUpdater
+    #: (pool: SnapshotPool, relationship: ActivityRelationship) -> void
+    def initialize(pool:, relationship:)
+      @pool = pool
+      @relationship = relationship
+      @record_updater = ActivityCollectionRecordUpdater.new(relationship)
+    end
+
+    #: (RecordSnapshot, ActivityCollectionRouteChange, ?depth: Integer) -> [RecordSnapshot, bool]
+    def call(snapshot, change, depth: 0) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      name, _reflection, _subtree, path = change.route.fetch(depth)
+      association = snapshot.associations.fetch(name)
+      transition = updated_records(association, snapshot, change, depth)
+      records, before, after, membership_preserved, changed = transition
+      return [snapshot, false] unless changed
+
+      updated_association = @pool.association(
+        path,
+        association.transition_to(
+          records,
+          before: before,
+          after: after,
+          membership_preserved: membership_preserved
+        )
+      )
+      updated_snapshot = replace_association(snapshot, name, updated_association)
+      parent_path = depth.zero? ? '' : change.route.fetch(depth - 1).fetch(3)
+      updated_snapshot = @pool.record(parent_path, updated_snapshot) unless parent_path.empty?
+      [updated_snapshot, true]
+    end
+
+    private
+
+    # @rbs @pool: SnapshotPool
+    # @rbs @relationship: ActivityRelationship
+    # @rbs @record_updater: ActivityCollectionRecordUpdater
+
+    #: (AssociationSnapshot, RecordSnapshot, ActivityCollectionRouteChange, Integer) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool, bool]
+    def updated_records(association, owner, change, depth)
+      return leaf_records(association, owner, change) if depth == change.route.length - 1
+
+      targeted = targeted_parent(association, change, depth)
+      if targeted
+        records, before, after, changed = targeted
+        return [records, before, after, true, changed]
+      end
+
+      recursive_records(association, change, depth)
+    end
+
+    #: (AssociationSnapshot, RecordSnapshot, ActivityCollectionRouteChange) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool, bool]
+    def leaf_records(association, owner, change)
+      reflection = change.route.last.fetch(1)
+      child = @record_updater.event_child(association, change, reflection, owner)
+      records, before, after, preserved = @record_updater.call(
+        association, change.version, child
+      )
+      [records, before, after, preserved, !records.equal?(association.records)]
+    end
+
+    #: (AssociationSnapshot, ActivityCollectionRouteChange, Integer) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]?
+    def targeted_parent(association, change, depth)
+      return unless depth == change.route.length - 2
+
+      reflection = change.route.fetch(depth + 1).fetch(1)
+      position = nested_owner_position(association, reflection, change)
+      return unless position
+
+      before = association.records.fetch(position)
+      after, changed = call(before, change, depth: depth + 1)
+      targeted_parent_replacement(association.records, position, before, after, changed)
+    end
+
+    #: (AssociationSnapshot, ActivityCollectionRouteChange, Integer) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool, bool]
+    def recursive_records(association, change, depth)
+      state = [nil, nil, false] #: [RecordSnapshot?, RecordSnapshot?, bool]
+      records = association.records.map do |child|
+        updated, child_changed = call(child, change, depth: depth + 1)
+        state = recursive_transition(state, child, updated, child_changed)
+        updated
+      end.freeze
+      [records, state.fetch(0), state.fetch(1), true, state.fetch(2)]
+    end
+
+    #: ([RecordSnapshot?, RecordSnapshot?, bool], RecordSnapshot, RecordSnapshot, bool) -> [RecordSnapshot?, RecordSnapshot?, bool]
+    def recursive_transition(state, child, updated, child_changed)
+      return state unless child_changed
+      return [nil, nil, true] if state.fetch(2)
+
+      [child, updated, true]
+    end
+
+    #: (Array[RecordSnapshot], Integer, RecordSnapshot, RecordSnapshot, bool) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]
+    def targeted_parent_replacement(records, position, before, after, changed)
+      return [records, nil, nil, false] unless changed
+
+      updated = records.dup
+      updated[position] = after
+      [updated.freeze, before, after, true]
+    end
+
+    #: (AssociationSnapshot, untyped, ActivityCollectionRouteChange) -> Integer?
+    def nested_owner_position(association, reflection, change)
+      membership_record = change.record || change.version.reify(dup: true)
+      return unless membership_record
+      return if membership_record.is_a?(ActivitySnapshotDelta) &&
+                membership_record.relationship_changed?(reflection)
+
+      owner_id = @relationship.owner_id(membership_record, reflection, state: :after)
+      association.position_for_id(owner_id)
+    end
+
+    #: (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
+    def replace_association(snapshot, name, association)
+      RecordSnapshot.new(
+        type: snapshot.type,
+        id: snapshot.id,
+        attributes: snapshot.attributes,
+        associations: snapshot.associations.merge(name => association)
+      )
+    end
+  end
+end

data/lib/paper_trail_diff/activity_event_record_normalizer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Normalizes one event record with the historical reader for its boundary.
+  class ActivityEventRecordNormalizer
+    #: (?association_reader: untyped) -> void
+    def initialize(association_reader: nil)
+      @association_reader = association_reader || method(:historical_reader)
+    end
+
+    #: (untyped, reflection: untyped, subtree: AssociationTree, path: String, normalizer: SnapshotNormalizer, root_endpoint: untyped, context_endpoint: untyped) -> RecordSnapshot?
+    def call( # rubocop:disable Metrics/ParameterLists
+      record,
+      reflection:,
+      subtree:,
+      path:,
+      normalizer:,
+      root_endpoint:,
+      context_endpoint:
+    )
+      boundary = Endpoint.version?(root_endpoint) ? root_endpoint : context_endpoint
+      reifier = @association_reader.call(context_endpoint, habtm_version: boundary)
+      normalizer.call_child(
+        record,
+        tree: subtree,
+        path: path,
+        incoming: reflection,
+        reifier: reifier
+      )
+    end
+
+    private
+
+    # @rbs @association_reader: untyped
+
+    #: (untyped, habtm_version: untyped) -> HistoricalAssociationReifier
+    def historical_reader(context_endpoint, habtm_version:)
+      HistoricalAssociationReifier.new(context_endpoint, habtm_version: habtm_version)
+    end
+  end
+end

data/lib/paper_trail_diff/activity_event_record_resolver.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Reconstructs an event's post-change record or immutable scalar delta.
+  class ActivityEventRecordResolver
+    RECORD_AFTER_HANDLERS = {
+      'create' => :created_record_after,
+      'update' => :updated_record_after
+    }.freeze
+    private_constant :RECORD_AFTER_HANDLERS
+
+    #: (?record_transition: untyped) -> void
+    def initialize(record_transition: nil)
+      @record_transition = record_transition
+    end
+
+    #: (untyped) -> untyped
+    def record_after(version)
+      return if version.event.to_s == 'destroy'
+
+      changed_record = changed_record_after(version)
+      return changed_record if changed_record
+
+      successor = version.next
+      record = successor&.reify(dup: true)
+      return record if record
+
+      model_class = Endpoint.model_class(version)
+      criteria = { model_class.primary_key => version.item_id } #: Hash[untyped, untyped]
+      model_class.unscoped.find_by(criteria)
+    end
+
+    #: (untyped) -> ActivitySnapshotDelta?
+    def snapshot_delta(version)
+      return unless version.event.to_s == 'update' && version.object
+
+      transition = @record_transition&.call(version)
+      return unless transition
+
+      ActivitySnapshotDelta.new(
+        before_attributes: transition.fetch(0),
+        after_attributes: transition.fetch(1)
+      )
+    end
+
+    #: (untyped) -> untyped
+    def changed_record_after(version)
+      handler = RECORD_AFTER_HANDLERS[version.event.to_s]
+      send(handler, version) if handler
+    end
+
+    #: (untyped) -> untyped
+    def created_record_after(version)
+      model_class = Endpoint.model_class(version)
+      changes = deserialized_changeset(version, model_class)
+      return unless changes.respond_to?(:each) && !changes.empty?
+
+      model_class.new(after_attributes(changes, model_class))
+    end
+
+    #: (untyped) -> untyped
+    def updated_record_after(version)
+      record = version.reify(dup: true)
+      changes = deserialized_changeset(version, record&.class)
+      apply_changes(record, changes)
+    end
+
+    # Mirrors PaperTrail's changeset deserialization without resolving
+    # +version.item+, which would issue one live-record query per event.
+    #: (untyped, untyped) -> untyped
+    def deserialized_changeset(version, model_class)
+      return unless model_class && version.class.column_names.include?('object_changes')
+
+      paper_trail = Object.const_get(:PaperTrail) #: untyped
+      adapter = paper_trail.config.object_changes_adapter
+      return adapter.load_changeset(version) if adapter.respond_to?(:load_changeset)
+
+      standard_changeset(paper_trail, version, model_class)
+    end
+
+    private
+
+    # @rbs @record_transition: untyped
+
+    #: (untyped, untyped) -> Hash[untyped, untyped]
+    def after_attributes(changes, model_class)
+      names = model_class.attribute_names
+      attributes = {} #: Hash[untyped, untyped]
+      changes.each do |name, values|
+        next unless names.include?(name.to_s)
+
+        attributes[name] = values.last
+      end
+      attributes
+    end
+
+    #: (untyped, untyped) -> untyped
+    def apply_changes(record, changes)
+      return unless record && changes.respond_to?(:each) && !changes.empty?
+
+      changes.each do |name, values|
+        next unless record.has_attribute?(name) && values.respond_to?(:last)
+
+        record[name] = values.last
+      end
+      record
+    end
+
+    #: (untyped, untyped, untyped) -> untyped
+    def standard_changeset(paper_trail, version, model_class)
+      raw_changes = version.send(:object_changes_deserialized)
+      active_support = Object.const_get(:ActiveSupport) #: untyped
+      changes = active_support.const_get(:HashWithIndifferentAccess).new(raw_changes)
+      serializers = paper_trail.const_get(:AttributeSerializers)
+      serializers.const_get(:ObjectChangesAttribute).new(model_class).deserialize(changes)
+      changes
+    end
+  end
+end

data/lib/paper_trail_diff/activity_event_route_finder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Finds explicitly selected collection and belongs-to routes for one event type.
+  class ActivityEventRouteFinder
+    #: (AssociationTraversal) -> void
+    def initialize(traversal)
+      @traversal = traversal
+      @collection_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
+      @belongs_to_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
+    end
+
+    #: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
+    def collection_routes(model_class, tree, target_type, path: '')
+      cached(@collection_routes, model_class, tree, target_type, path, :has_many)
+    end
+
+    #: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
+    def belongs_to_routes(model_class, tree, target_type, path: '')
+      cached(@belongs_to_routes, model_class, tree, target_type, path, :belongs_to)
+    end
+
+    private
+
+    # @rbs @traversal: AssociationTraversal
+    # @rbs @collection_routes: Hash[Array[untyped], Array[Array[untyped]]]
+    # @rbs @belongs_to_routes: Hash[Array[untyped], Array[Array[untyped]]]
+
+    # Timelines interleave event types, so every requested combination is
+    # retained. Model, tree, and path are fixed per adapter, leaving one entry
+    # per selected item type.
+    #: (Hash[Array[untyped], Array[Array[untyped]]], untyped, AssociationTree, String, String, Symbol) -> Array[Array[untyped]]
+    def cached(store, model_class, tree, target_type, path, macro) # rubocop:disable Metrics/ParameterLists
+      key = [model_class, tree, target_type, path]
+      existing = store[key]
+      return existing if existing
+
+      store[cache_key(key)] =
+        freeze_routes(routes(model_class, tree, target_type, macro, path: path))
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def cache_key(key)
+      key.map { |part| part.is_a?(String) ? -part : part }.freeze
+    end
+
+    #: (Array[Array[untyped]]) -> Array[Array[untyped]]
+    def freeze_routes(routes)
+      routes.each do |route|
+        route.each(&:freeze)
+        route.freeze
+      end.freeze
+    end
+
+    #: (untyped, AssociationTree, String, Symbol, path: String) -> Array[Array[untyped]]
+    def routes(model_class, tree, target_type, macro, path: '')
+      @traversal.reflections_for(model_class, tree, path: path).flat_map do |reflection|
+        routes_for_reflection(reflection, tree, target_type, macro, path)
+      end
+    end
+
+    #: (untyped, AssociationTree, String, Symbol, String) -> Array[Array[untyped]]
+    def routes_for_reflection(reflection, tree, target_type, macro, path)
+      name = reflection.name.to_s
+      subtree = tree.child(name)
+      return [] unless subtree
+
+      child_path = Support.association_path(path, name)
+      entry = [name, reflection, subtree, child_path]
+      direct = [] #: Array[Array[untyped]]
+      direct << [entry] if direct_route?(reflection, target_type, macro)
+      return direct if subtree.empty? || reflection.polymorphic?
+
+      nested = routes(reflection.klass, subtree, target_type, macro, path: child_path)
+      direct.concat(nested.map { |route| [entry, *route] })
+    end
+
+    #: (untyped, String, Symbol) -> bool
+    def direct_route?(reflection, target_type, macro)
+      reflection.macro == macro && supported_direct_reflection?(reflection, macro) &&
+        reflection.klass.base_class.name.to_s == target_type
+    end
+
+    #: (untyped, Symbol) -> bool
+    def supported_direct_reflection?(reflection, macro)
+      return !reflection.options[:through] if macro == :has_many
+
+      !reflection.polymorphic?
+    end
+  end
+end