paper_trail_diff 0.1.0

data/lib/paper_trail_diff/prepared_history.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Batched record states and relationship candidates for one activity range.
+  class PreparedHistory
+    DIRECT_RESOLVERS = {
+      belongs_to: :resolve_belongs_to,
+      has_one: :resolve_children,
+      has_many: :resolve_children,
+      has_and_belongs_to_many: :resolve_habtm
+    }.freeze
+    private_constant :DIRECT_RESOLVERS
+
+    #: (PreparedRecordIndex) -> void
+    def initialize(records)
+      @records = records
+      @edges = {} #: Hash[Array[String], Hash[String, Hash[Symbol, untyped]]]
+      @unsupported = {} #: Hash[Array[String], bool]
+      @habtm = {} #: Hash[Array[String], Hash[String, Array[untyped]]]
+    end
+
+    #: (untyped, untyped, Hash[String, Hash[Symbol, untyped]]) -> void
+    def merge_edge(owner_class, reflection, groups)
+      key = edge_key(owner_class, reflection)
+      empty = {} #: Hash[String, Hash[Symbol, untyped]]
+      @edges[key] = merge_groups(@edges.fetch(key, empty), groups)
+    end
+
+    #: (untyped, untyped) -> Hash[String, Hash[Symbol, untyped]]
+    def edge(owner_class, reflection)
+      empty = {} #: Hash[String, Hash[Symbol, untyped]]
+      @edges.fetch(edge_key(owner_class, reflection), empty)
+    end
+
+    #: (untyped, untyped) -> void
+    def mark_unsupported(owner_class, reflection)
+      @unsupported[edge_key(owner_class, reflection)] = true
+    end
+
+    #: (untyped, untyped, Hash[String, Array[untyped]]) -> void
+    def register_habtm(owner_class, reflection, memberships)
+      @habtm[edge_key(owner_class, reflection)] = memberships.transform_keys(&:to_s)
+    end
+
+    #: (untyped, untyped, untyped, habtm_boundary: untyped) -> [bool, Array[untyped]]
+    def resolve(record, reflection, boundary, habtm_boundary:)
+      return [false, []] unless supported?(record.class, reflection)
+
+      records = if reflection.options[:through]
+                  through_records(record, reflection, boundary, habtm_boundary)
+                else
+                  direct_records(record, reflection, boundary, habtm_boundary)
+                end
+      records ? [true, records] : [false, []]
+    end
+
+    private
+
+    # @rbs @records: PreparedRecordIndex
+    # @rbs @edges: Hash[Array[String], Hash[String, Hash[Symbol, untyped]]]
+    # @rbs @unsupported: Hash[Array[String], bool]
+    # @rbs @habtm: Hash[Array[String], Hash[String, Array[untyped]]]
+
+    #: (untyped, untyped) -> bool
+    def supported?(owner_class, reflection)
+      !@unsupported[edge_key(owner_class, reflection)] &&
+        reflection.scope.nil? && !default_scoped?(reflection.klass)
+    end
+
+    #: (untyped) -> bool
+    def default_scoped?(model_class)
+      model_class.default_scopes?
+    end
+
+    #: (untyped, untyped, untyped, untyped) -> Array[untyped]?
+    def direct_records(record, reflection, boundary, habtm_boundary)
+      resolver = DIRECT_RESOLVERS.fetch(reflection.macro)
+      send(resolver, record, reflection, boundary, habtm_boundary)
+    end
+
+    #: (untyped, untyped, untyped, untyped) -> Array[untyped]?
+    def resolve_belongs_to(record, reflection, boundary, _habtm_boundary)
+      belongs_to_records(record, reflection, boundary)
+    end
+
+    #: (untyped, untyped, untyped, untyped) -> Array[untyped]
+    def resolve_children(record, reflection, boundary, _habtm_boundary)
+      child_records(record, reflection, boundary)
+    end
+
+    #: (untyped, untyped, untyped, untyped) -> Array[untyped]?
+    def resolve_habtm(record, reflection, boundary, habtm_boundary)
+      habtm_records(record, reflection, boundary, habtm_boundary)
+    end
+
+    #: (untyped, untyped, untyped) -> Array[untyped]?
+    def belongs_to_records(record, reflection, boundary)
+      foreign_key = scalar_foreign_key(reflection)
+      return unless foreign_key
+
+      id = record.public_send(foreign_key)
+      return [] if id.nil?
+
+      model_class = belongs_to_class(record, reflection)
+      return unless model_class && @records.loaded?(model_class, id)
+
+      Array(@records.record_before(model_class, id, boundary)).compact
+    end
+
+    #: (untyped, untyped, untyped) -> Array[untyped]
+    def child_records(record, reflection, boundary)
+      edge(record.class, reflection).values.flat_map do |group|
+        model_class = group.fetch(:model)
+        group.fetch(:ids).filter_map do |id|
+          child = @records.record_before(model_class, id, boundary)
+          child if child && member_of?(child, reflection, record)
+        end
+      end
+    end
+
+    #: (untyped, untyped, untyped, untyped) -> Array[untyped]?
+    def habtm_records(record, reflection, boundary, habtm_boundary)
+      transaction_id = transaction_id_for(habtm_boundary)
+      return unless transaction_id
+
+      empty = {} #: Hash[String, Array[untyped]]
+      ids = @habtm.fetch(edge_key(record.class, reflection), empty)[transaction_id.to_s]
+      return unless ids
+
+      ids.filter_map do |id|
+        @records.record_before(reflection.klass, id, boundary)
+      end
+    end
+
+    #: (untyped, untyped, untyped, untyped) -> Array[untyped]?
+    def through_records(record, reflection, boundary, habtm_boundary)
+      handled, intermediates = resolve(
+        record,
+        reflection.through_reflection,
+        boundary,
+        habtm_boundary: habtm_boundary
+      )
+      return unless handled
+
+      resolved = resolve_sources(intermediates, reflection, boundary, habtm_boundary)
+      return unless resolved.all?(&:first)
+
+      unique_records(resolved.flat_map(&:last))
+    end
+
+    #: (Array[untyped], untyped, untyped, untyped) -> Array[[bool, Array[untyped]]]
+    def resolve_sources(intermediates, reflection, boundary, habtm_boundary)
+      intermediates.map do |intermediate|
+        resolve(
+          intermediate,
+          reflection.source_reflection,
+          boundary,
+          habtm_boundary: habtm_boundary
+        )
+      end
+    end
+
+    #: (untyped, untyped, untyped) -> bool
+    def member_of?(child, reflection, owner)
+      foreign_key = scalar_foreign_key(reflection)
+      return false unless foreign_key
+      return false unless child.public_send(foreign_key).to_s == owner.id.to_s
+      return true unless reflection.options[:as]
+
+      owner_types(reflection, owner).include?(child.public_send(reflection.type).to_s)
+    end
+
+    #: (untyped) -> String?
+    def scalar_foreign_key(reflection)
+      key = reflection.foreign_key
+      key.to_s unless key.is_a?(Array)
+    end
+
+    #: (untyped, untyped) -> untyped
+    def belongs_to_class(record, reflection)
+      return reflection.klass unless reflection.polymorphic?
+
+      Object.const_get(record.public_send(reflection.foreign_type).to_s)
+    rescue NameError
+      nil
+    end
+
+    #: (untyped, untyped) -> Array[String]
+    def owner_types(reflection, owner)
+      types = [owner.class.name, owner.class.base_class.name, reflection.active_record.name]
+      types.map(&:to_s).uniq
+    end
+
+    #: (untyped) -> untyped
+    def transaction_id_for(boundary)
+      boundary.transaction_id
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def unique_records(records)
+      records.uniq { |record| [record.class.base_class.name, record.id.to_s] }
+    end
+
+    #: (untyped, untyped) -> Array[String]
+    def edge_key(owner_class, reflection)
+      [owner_class.base_class.name.to_s, reflection.name.to_s]
+    end
+
+    #: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
+    def merge_groups(existing, incoming)
+      existing.merge(incoming) do |_name, left, right|
+        left.merge(ids: (left.fetch(:ids) | right.fetch(:ids)))
+      end
+    end
+  end
+end

data/lib/paper_trail_diff/prepared_history_loader.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Expands the explicit association tree into a request-scoped PreparedHistory.
+  class PreparedHistoryLoader
+    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal) -> void
+    def initialize(record, root_versions:, tree:, traversal:)
+      @record = record
+      @tree = tree
+      @traversal = traversal
+      @records = PreparedRecordIndex.new(root_versions.first)
+      @history = PreparedHistory.new(@records)
+      @edges = PreparedEdgeLoader.new(@records, root_versions)
+      @prepared = {} #: Hash[Array[String], Array[String]]
+    end
+
+    #: () -> PreparedHistory
+    def call
+      load_node(@record.class, [@record.id], @tree, path: '')
+      @history
+    end
+
+    private
+
+    # @rbs @record: untyped
+    # @rbs @tree: AssociationTree
+    # @rbs @traversal: AssociationTraversal
+    # @rbs @records: PreparedRecordIndex
+    # @rbs @history: PreparedHistory
+    # @rbs @edges: PreparedEdgeLoader
+    # @rbs @prepared: Hash[Array[String], Array[String]]
+
+    #: (untyped, Array[untyped], AssociationTree, path: String) -> void
+    def load_node(model_class, ids, tree, path:)
+      load_records(model_class, ids)
+      @traversal.reflections_for(model_class, tree, path: path).each do |reflection|
+        subtree = tree.child(reflection.name)
+        next unless subtree
+
+        groups = prepare_reflection(model_class, ids, reflection)
+        load_groups(groups)
+        child_path = Support.association_path(path, reflection.name.to_s)
+        groups.each_value do |group|
+          load_node(group.fetch(:model), group.fetch(:ids), subtree, path: child_path)
+        end
+      end
+    end
+
+    #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
+    def prepare_reflection(owner_class, owner_ids, reflection)
+      return prepare_through(owner_class, owner_ids, reflection) if reflection.options[:through]
+
+      prepare_edge(owner_class, owner_ids, reflection)
+    end
+
+    #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
+    def prepare_through(owner_class, owner_ids, reflection)
+      through_groups = prepare_edge(owner_class, owner_ids, reflection.through_reflection)
+      targets = {} #: Hash[String, Hash[Symbol, untyped]]
+      through_groups.each_value do |group|
+        load_groups({ group.fetch(:model).name.to_s => group })
+        source = prepare_edge(group.fetch(:model), group.fetch(:ids), reflection.source_reflection)
+        targets = merge_groups(targets, source)
+      end
+      @history.merge_edge(owner_class, reflection, targets)
+      @history.mark_unsupported(owner_class, reflection) if deferred_macro?(reflection)
+      targets
+    end
+
+    #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
+    def prepare_edge(owner_class, owner_ids, reflection)
+      missing = unprepared_ids(owner_class, owner_ids, reflection)
+      return @history.edge(owner_class, reflection) if missing.empty?
+
+      groups, memberships = @edges.call(owner_class, missing, reflection)
+      @history.merge_edge(owner_class, reflection, groups)
+      @history.register_habtm(owner_class, reflection, memberships) if memberships
+      mark_prepared(owner_class, missing, reflection)
+      mark_unsupported(owner_class, reflection, groups)
+      load_groups(groups)
+      @history.edge(owner_class, reflection)
+    end
+
+    #: (untyped, Array[untyped], untyped) -> Array[untyped]
+    def unprepared_ids(owner_class, ids, reflection)
+      prepared = @prepared.fetch(edge_key(owner_class, reflection), [])
+      ids.reject { |id| prepared.include?(id.to_s) }
+    end
+
+    #: (untyped, Array[untyped], untyped) -> void
+    def mark_prepared(owner_class, ids, reflection)
+      key = edge_key(owner_class, reflection)
+      @prepared[key] = (@prepared.fetch(key, []) | ids.map(&:to_s))
+    end
+
+    #: (untyped, untyped, Hash[String, Hash[Symbol, untyped]]) -> void
+    def mark_unsupported(owner_class, reflection, groups)
+      unsupported = deferred_macro?(reflection) || reflection.foreign_key.is_a?(Array) ||
+                    groups.values.any? { |group| !versioned?(group.fetch(:model)) }
+      @history.mark_unsupported(owner_class, reflection) if unsupported
+    end
+
+    #: (untyped) -> bool
+    def deferred_macro?(reflection)
+      reflection.options[:through] && !reflection.source_reflection.belongs_to?
+    end
+
+    #: (Hash[String, Hash[Symbol, untyped]]) -> void
+    def load_groups(groups)
+      groups.each_value { |group| load_records(group.fetch(:model), group.fetch(:ids)) }
+    end
+
+    #: (untyped, Array[untyped]) -> void
+    def load_records(model_class, ids)
+      @records.load(model_class, ids) if versioned?(model_class)
+    end
+
+    #: (untyped) -> bool
+    def versioned?(model_class)
+      model_class.respond_to?(:paper_trail)
+    end
+
+    #: (untyped, untyped) -> Array[String]
+    def edge_key(owner_class, reflection)
+      [owner_class.base_class.name.to_s, reflection.name.to_s]
+    end
+
+    #: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
+    def merge_groups(left, right)
+      left.merge(right) do |_name, first, second|
+        first.merge(ids: (first.fetch(:ids) | second.fetch(:ids)))
+      end
+    end
+  end
+end

data/lib/paper_trail_diff/prepared_record_index.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Immutable scalar state from a PaperTrail version or live-record fallback.
+  class PreparedRecordState
+    #: (untyped) -> void
+    def initialize(record)
+      @model_class = record.class
+      @attributes = Support.immutable_copy(record.attributes)
+      freeze
+    end
+
+    #: () -> untyped
+    def instantiate
+      @model_class.new(@attributes)
+    end
+
+    # @rbs @model_class: untyped
+    # @rbs @attributes: Hash[untyped, untyped]
+  end
+
+  # Versions and live fallback for one model identity.
+  class PreparedRecordSeries
+    attr_reader :versions #: Array[untyped]
+
+    #: (versions: Array[untyped], live: PreparedRecordState?) -> void
+    def initialize(versions:, live:)
+      @versions = versions.freeze
+      @live = live
+      @states = {} #: Hash[untyped, PreparedRecordState?]
+    end
+
+    #: (untyped) -> untyped
+    def record_before(boundary)
+      version = versions.find { |candidate| eligible?(candidate, boundary) }
+      return state_for(version)&.instantiate if version
+
+      @live&.instantiate
+    end
+
+    #: () -> Array[untyped]
+    def records
+      version_records = versions.filter_map { |version| state_for(version)&.instantiate }
+      live = @live
+      live ? [*version_records, live.instantiate] : version_records
+    end
+
+    private
+
+    # @rbs @live: PreparedRecordState?
+    # @rbs @states: Hash[untyped, PreparedRecordState?]
+
+    #: (untyped, untyped) -> bool
+    def eligible?(version, boundary)
+      version.created_at >= boundary.created_at || same_transaction?(version, boundary)
+    end
+
+    #: (untyped, untyped) -> bool
+    def same_transaction?(version, boundary)
+      transaction_id = boundary.transaction_id if boundary.respond_to?(:transaction_id)
+      transaction_id && version.respond_to?(:transaction_id) &&
+        version.transaction_id == transaction_id
+    end
+
+    #: (untyped) -> PreparedRecordState?
+    def state_for(version)
+      return @states[version.id] if @states.key?(version.id)
+
+      record = version.reify(
+        dup: true,
+        has_many: false,
+        has_one: false,
+        belongs_to: false,
+        has_and_belongs_to_many: false
+      )
+      @states[version.id] = record && PreparedRecordState.new(record)
+    end
+  end
+
+  # Request-scoped scalar history loaded once per model identity.
+  class PreparedRecordIndex
+    #: (untyped) -> void
+    def initialize(start_version)
+      @start_time = start_version.created_at
+      @series = {} #: Hash[Array[String], PreparedRecordSeries]
+    end
+
+    #: (untyped, Array[untyped]) -> void
+    def load(model_class, ids)
+      missing = missing_ids(model_class, ids)
+      return if missing.empty?
+
+      versions = versions_for(model_class, missing).group_by { |version| version.item_id.to_s }
+      live = live_records_for(model_class, missing).to_h { |record| [record.id.to_s, record] }
+      missing.each { |id| add_series(model_class, id, versions, live) }
+    end
+
+    #: (untyped, untyped, untyped) -> untyped
+    def record_before(model_class, id, boundary)
+      @series.fetch(identity(model_class, id)).record_before(boundary)
+    end
+
+    #: (untyped, Array[untyped]) -> Array[untyped]
+    def records_for(model_class, ids)
+      ids.flat_map { |id| @series.fetch(identity(model_class, id)).records }
+    end
+
+    #: (untyped, untyped) -> bool
+    def loaded?(model_class, id)
+      @series.key?(identity(model_class, id))
+    end
+
+    private
+
+    # @rbs @start_time: untyped
+    # @rbs @series: Hash[Array[String], PreparedRecordSeries]
+
+    #: (untyped, untyped) -> Array[String]
+    def identity(model_class, id)
+      [model_class.base_class.name.to_s, id.to_s]
+    end
+
+    #: (untyped, Array[untyped]) -> Array[untyped]
+    def missing_ids(model_class, ids)
+      ids.compact.uniq.reject { |id| @series.key?(identity(model_class, id)) }
+    end
+
+    #: (untyped, untyped, Hash[String, Array[untyped]], Hash[String, untyped]) -> void
+    def add_series(model_class, id, versions, live)
+      record = live[id.to_s]
+      @series[identity(model_class, id)] = PreparedRecordSeries.new(
+        versions: versions.fetch(id.to_s, []),
+        live: record && PreparedRecordState.new(record)
+      )
+    end
+
+    #: (untyped, Array[untyped]) -> Array[untyped]
+    def versions_for(model_class, ids)
+      model_class.paper_trail.version_class.where(
+        item_type: model_class.base_class.name,
+        item_id: ids
+      ).where('created_at >= ?', @start_time).order(:id).to_a
+    end
+
+    #: (untyped, Array[untyped]) -> Array[untyped]
+    def live_records_for(model_class, ids)
+      primary_key = model_class.primary_key
+      return [] if primary_key.is_a?(Array)
+
+      model_class.base_class.unscoped.where(primary_key => ids).to_a
+    end
+  end
+end

data/lib/paper_trail_diff/snapshot.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Immutable identity shared by snapshots and stable-record changes.
+  class RecordReference
+    attr_reader :type #: String
+    attr_reader :id #: untyped
+
+    #: (type: String, id: untyped) -> void
+    def initialize(type:, id:)
+      @type = Support.immutable_copy(type.to_s)
+      @id = Support.immutable_copy(id)
+      freeze
+    end
+
+    #: (reference_key) -> untyped
+    def [](key)
+      case key.to_s
+      when 'type' then type
+      when 'id' then id
+      end
+    end
+
+    #: (reference_key) -> untyped
+    def fetch(key)
+      value = self[key]
+      return value if %w[type id].include?(key.to_s)
+
+      raise KeyError, "key not found: #{key.inspect}"
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      { type: type, id: id }
+    end
+  end
+
+  # A normalized association in a bounded record snapshot tree.
+  class AssociationSnapshot
+    COLLECTION_KINDS = %i[has_many has_and_belongs_to_many].freeze
+    SUPPORTED_KINDS = %i[belongs_to has_one has_many has_and_belongs_to_many].freeze
+    private_constant :COLLECTION_KINDS, :SUPPORTED_KINDS
+
+    class << self
+      #: (Symbol) -> bool
+      def collection_kind?(kind)
+        COLLECTION_KINDS.include?(kind)
+      end
+    end
+
+    attr_reader :kind #: Symbol
+    attr_reader :records #: Array[RecordSnapshot]
+
+    #: (kind: Symbol, records: Array[RecordSnapshot]) -> void
+    def initialize(kind:, records:)
+      unless SUPPORTED_KINDS.include?(kind)
+        raise ArgumentError, "unsupported association kind: #{kind.inspect}"
+      end
+      if !self.class.collection_kind?(kind) && records.length > 1
+        raise ArgumentError, "#{kind} association snapshots accept at most one record"
+      end
+
+      @kind = kind
+      @records = records.dup.freeze
+      freeze
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      { kind: kind, records: Support.serialize(records) }
+    end
+  end
+
+  # An immutable, ActiveRecord-independent representation of a reified record.
+  class RecordSnapshot
+    attr_reader :type #: String
+    attr_reader :id #: untyped
+    attr_reader :identity #: Array[untyped]
+    attr_reader :attributes #: Hash[String, untyped]
+    attr_reader :associations #: Hash[String, AssociationSnapshot]
+
+    #: (type: String, id: untyped, attributes: snapshot_attributes, ?associations: snapshot_associations) -> void
+    def initialize(type:, id:, attributes:, associations: {})
+      @type = Support.immutable_copy(type.to_s)
+      @id = Support.immutable_copy(id)
+      @identity = [@type, @id].freeze
+      @attributes = normalize_hash(attributes)
+      @associations = normalize_hash(associations)
+      freeze
+    end
+
+    #: () -> RecordReference
+    def reference
+      RecordReference.new(type: type, id: id)
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      value = {
+        type: type,
+        id: id,
+        attributes: Support.serialize(attributes)
+      }
+      value[:associations] = Support.serialize(associations) unless associations.empty?
+      value
+    end
+
+    private
+
+    #: (Hash[untyped, untyped]) -> Hash[String, untyped]
+    def normalize_hash(hash)
+      normalized = {} #: Hash[String, untyped]
+      hash.sort_by { |key, _value| key.to_s }.each do |key, value|
+        normalized[Support.immutable_copy(key.to_s)] = Support.immutable_copy(value)
+      end
+      normalized.freeze
+    end
+  end
+end