paper_trail_diff 0.1.0

data/lib/paper_trail_diff/snapshot_normalizer.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Reuses immutable nodes whose normalized state did not change at a selected path.
+  class SnapshotPool
+    def initialize
+      @records = {} #: Hash[Array[untyped], RecordSnapshot]
+      @associations = {} #: Hash[String, AssociationSnapshot]
+    end
+
+    #: (String, RecordSnapshot) -> RecordSnapshot
+    def record(path, snapshot)
+      key = [path, snapshot.type, snapshot.id]
+      previous = @records[key]
+      return previous if previous && equivalent_record?(previous, snapshot)
+
+      @records[key] = snapshot
+    end
+
+    #: (String, AssociationSnapshot) -> AssociationSnapshot
+    def association(path, snapshot)
+      previous = @associations[path]
+      if previous && previous.kind == snapshot.kind && previous.records == snapshot.records
+        return previous
+      end
+
+      @associations[path] = snapshot
+    end
+
+    private
+
+    # @rbs @records: Hash[Array[untyped], RecordSnapshot]
+    # @rbs @associations: Hash[String, AssociationSnapshot]
+
+    #: (RecordSnapshot, RecordSnapshot) -> bool
+    def equivalent_record?(left, right)
+      left.attributes == right.attributes &&
+        left.associations.keys == right.associations.keys &&
+        left.associations.all? do |name, association|
+          other = right.associations[name]
+          other && association.kind == other.kind && association.records == other.records
+        end
+    end
+  end
+
+  # Converts an ActiveRecord graph into immutable, persistence-independent snapshots.
+  class SnapshotNormalizer
+    #: (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, ?pool: SnapshotPool) -> void
+    def initialize(tree:, ignore_policy:, traversal:, pool: SnapshotPool.new)
+      @tree = tree
+      @ignore_policy = ignore_policy
+      @traversal = traversal
+      @pool = pool
+      @structural_columns = {} #: Hash[String, Array[String]]
+    end
+
+    #: (untyped, reifier: untyped) -> RecordSnapshot?
+    def call(record, reifier:)
+      reflections = reflections_for(record, @tree, '')
+      normalize_record(record, @tree, '', reifier, reflections)
+    end
+
+    # Normalizes one member of an already selected association branch.
+    #: (untyped, tree: AssociationTree, path: String, incoming: untyped, reifier: untyped) -> RecordSnapshot?
+    def call_child(record, tree:, path:, incoming:, reifier:)
+      return unless record
+
+      @structural_columns[path] ||= @traversal.incoming_relationship_columns(incoming)
+      reflections = reflections_for(record, tree, path)
+      reifier.reify(record, reflections) unless reflections.empty?
+      normalize_record(record, tree, path, reifier, reflections)
+    end
+
+    # Normalizes scalar attributes without traversing or loading associations.
+    #: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
+    def attributes_for(record, tree:, path:)
+      reflections = reflections_for(record, tree, path)
+      normalized_attributes(record, reflections, path)
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @ignore_policy: IgnorePolicy
+    # @rbs @traversal: AssociationTraversal
+    # @rbs @pool: SnapshotPool
+    # @rbs @structural_columns: Hash[String, Array[String]]
+
+    #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot?
+    def normalize_record(record, tree, path, reifier, reflections)
+      return unless record
+
+      snapshot = RecordSnapshot.new(
+        type: record.class.name,
+        id: record.id,
+        attributes: normalized_attributes(record, reflections, path),
+        associations: normalize_associations(record, tree, path, reifier, reflections)
+      )
+      path.empty? ? snapshot : @pool.record(path, snapshot)
+    end
+
+    #: (untyped, Array[untyped], String) -> snapshot_attributes
+    def normalized_attributes(record, reflections, path)
+      attributes = record.attributes.dup
+      excluded_attributes(record, reflections, path).each { |name| attributes.delete(name) }
+      attributes
+    end
+
+    #: (untyped, Array[untyped], String) -> Array[String]
+    def excluded_attributes(record, reflections, path)
+      primary_key = record.class.primary_key #: untyped
+      primary_keys = primary_key.is_a?(Array) ? primary_key : [primary_key]
+      # @type var primary_keys: Array[untyped]
+      primary_keys = primary_keys.map { |key| key.to_s } # rubocop:disable Style/SymbolProc
+      ignored = @ignore_policy.attributes_for(path)
+      structural = @structural_columns.fetch(path, [])
+      (primary_keys + ignored + relationship_columns(reflections) + structural).uniq
+    end
+
+    #: (Array[untyped]) -> Array[String]
+    def relationship_columns(reflections)
+      reflections.select { |reflection| reflection.macro == :belongs_to }.flat_map do |reflection|
+        columns = [reflection.foreign_key.to_s]
+        columns << reflection.foreign_type.to_s if reflection.polymorphic?
+        columns
+      end
+    end
+
+    #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> Hash[String, AssociationSnapshot]
+    def normalize_associations(record, tree, path, reifier, reflections)
+      reflections.to_h do |reflection|
+        name = reflection.name.to_s
+        subtree = tree.child(name)
+        raise ConfigurationError, "missing traversal subtree: #{name}" unless subtree
+
+        [name, association_snapshot(record, reflection, subtree, path, reifier)]
+      end
+    end
+
+    #: (untyped, untyped, AssociationTree, String, untyped) -> AssociationSnapshot
+    def association_snapshot( # rubocop:disable Metrics/AbcSize
+      record,
+      reflection,
+      subtree,
+      path,
+      reifier
+    )
+      associated = record.public_send(reflection.name)
+      records = if AssociationSnapshot.collection_kind?(reflection.macro)
+                  associated.to_a
+                else
+                  Array(associated).compact
+                end
+      child_path = Support.association_path(path, reflection.name.to_s)
+      @structural_columns[child_path] ||= @traversal.incoming_relationship_columns(reflection)
+      snapshot = AssociationSnapshot.new(
+        kind: reflection.macro,
+        records: normalize_children(records, subtree, child_path, reifier)
+      )
+      @pool.association(child_path, snapshot)
+    end
+
+    #: (Array[untyped], AssociationTree, String, untyped) -> Array[RecordSnapshot]
+    def normalize_children(records, tree, path, reifier)
+      reflections_by_class = {} #: Hash[String, Array[untyped]]
+      records.filter_map do |child|
+        type = child.class.name
+        reflections = reflections_by_class[type] ||= reflections_for(child, tree, path)
+        reifier.reify(child, reflections) unless reflections.empty?
+        normalize_record(child, tree, path, reifier, reflections)
+      end
+    end
+
+    #: (untyped, AssociationTree, String) -> Array[untyped]
+    def reflections_for(record, tree, path)
+      return [] unless record
+
+      @traversal.reflections_for(record.class, tree, path: path)
+    end
+  end
+end

data/lib/paper_trail_diff/step.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # One adjacent transition in a PaperTrail timeline.
+  class Step
+    attr_reader :from_version #: untyped
+    attr_reader :to_version #: untyped
+    attr_reader :diff #: Diff
+
+    #: (from_version: untyped, to_version: untyped, diff: Diff) -> void
+    def initialize(from_version:, to_version:, diff:)
+      @from_version = from_version
+      @to_version = to_version
+      @diff = diff
+      freeze
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        from_version_id: from_version.id,
+        to_version_id: to_version.id,
+        diff: diff.to_h
+      }
+    end
+  end
+end

data/lib/paper_trail_diff/support.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Internal helpers for isolating and serializing values held by result objects.
+  module Support
+    module_function
+
+    #: (untyped) -> untyped
+    def immutable_copy(value)
+      return value if value.frozen?
+
+      case value
+      when Hash
+        immutable_hash(value)
+      when Array
+        value.map { |item| immutable_copy(item) }.freeze
+      else
+        duplicate_and_freeze(value)
+      end
+    end
+
+    #: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def immutable_hash(value)
+      copy = {} #: Hash[untyped, untyped]
+      value.each do |key, item|
+        copy[immutable_copy(key)] = immutable_copy(item)
+      end
+      copy.freeze
+    end
+    private_class_method :immutable_hash
+
+    #: (untyped) -> untyped
+    def serialize(value)
+      case value
+      when Hash
+        serialized = {} #: Hash[untyped, untyped]
+        value.each do |key, item|
+          serialized[key] = serialize(item)
+        end
+        serialized
+      when Array
+        value.map { |item| serialize(item) }
+      else
+        paper_trail_diff_value?(value) ? value.to_h : value
+      end
+    end
+
+    #: (untyped) -> Array[untyped]
+    def chronological_version_key(version)
+      [version.created_at, version.id.to_s.rjust(32, '0')]
+    end
+
+    #: (untyped, untyped) -> Integer
+    def compare_versions(left, right)
+      chronological_version_key(left) <=> chronological_version_key(right) ||
+        raise(ConfigurationError, 'versions have incomparable timestamps')
+    end
+
+    #: (String, String) -> String
+    def association_path(parent, name)
+      parent.empty? ? name : "#{parent}.#{name}"
+    end
+
+    #: (untyped) -> untyped
+    def duplicate_and_freeze(value)
+      value.dup.freeze
+    rescue TypeError
+      value
+    end
+    private_class_method :duplicate_and_freeze
+
+    #: (untyped) -> bool
+    def paper_trail_diff_value?(value)
+      class_name = value.class.name
+      class_name&.start_with?('PaperTrailDiff::') && value.respond_to?(:to_h)
+    end
+    private_class_method :paper_trail_diff_value?
+  end
+end

data/lib/paper_trail_diff/timeline_builder.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects and compares a chronological slice of a record's version history.
+  class TimelineBuilder
+    #: (untyped, from: untyped, to: untyped, snapshotter: untyped) -> void
+    def initialize(record, from:, to:, snapshotter:)
+      @record = record
+      @from = from
+      @to = to
+      @snapshotter = snapshotter
+    end
+
+    #: () -> Array[Step]
+    def build
+      steps, = compare_history(selected_versions)
+      steps
+    end
+
+    #: () -> Analysis
+    def analyze
+      steps, first_snapshot, last_snapshot = compare_history(selected_versions)
+      Analysis.new(
+        diff: Engine.compare(first_snapshot, last_snapshot),
+        timeline: steps
+      )
+    end
+
+    private
+
+    # @rbs @record: untyped
+    # @rbs @from: untyped
+    # @rbs @to: untyped
+    # @rbs @snapshotter: untyped
+
+    #: (Array[untyped]) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
+    def compare_history(versions)
+      @snapshotter.prepare(@record, versions) if @snapshotter.respond_to?(:prepare)
+      first_snapshot = @snapshotter.call(versions.first)
+      previous_snapshot = first_snapshot
+      steps = versions.each_cons(2).map do |from_version, to_version|
+        current_snapshot = @snapshotter.call(to_version)
+        step = Step.new(
+          from_version: from_version,
+          to_version: to_version,
+          diff: Engine.compare(previous_snapshot, current_snapshot)
+        )
+        previous_snapshot = current_snapshot
+        step
+      end.freeze
+      [steps, first_snapshot, previous_snapshot]
+    end
+
+    #: () -> Array[untyped]
+    def selected_versions
+      VersionRange.new(@record, from: @from, to: @to).select
+    end
+  end
+end

data/lib/paper_trail_diff/timeline_snapshot_provider.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
+  class TimelineSnapshotProvider
+    #: (HistoricalSnapshotStore) -> void
+    def initialize(store)
+      @store = store
+    end
+
+    #: (untyped, Array[untyped]) -> void
+    def prepare(record, versions)
+      @store.prepare(record, versions)
+    end
+
+    #: (untyped) -> RecordSnapshot?
+    def call(version)
+      @store.uncached(version, version)
+    end
+
+    # @rbs @store: HistoricalSnapshotStore
+  end
+end

data/lib/paper_trail_diff/value_objects.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # A directional change between two structured values.
+  class ValueChange
+    attr_reader :from #: untyped
+    attr_reader :to #: untyped
+
+    #: (from: untyped, to: untyped) -> void
+    def initialize(from:, to:)
+      @from = Support.immutable_copy(from)
+      @to = Support.immutable_copy(to)
+      freeze
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      { from: Support.serialize(from), to: Support.serialize(to) }
+    end
+  end
+
+  # Attribute and nested-association changes for a record whose identity did not change.
+  class RecordChange
+    attr_reader :record #: RecordReference
+    attr_reader :attributes #: Hash[String, ValueChange]
+    attr_reader :associations #: Hash[String, ToOneAssociationDiff | CollectionAssociationDiff]
+
+    #: (record: RecordSnapshot, attributes: attribute_changes, ?associations: association_diffs) -> void
+    def initialize(record:, attributes:, associations: {})
+      @record = record.reference
+      @attributes = Support.immutable_copy(attributes)
+      @associations = Support.immutable_copy(associations)
+      freeze
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      value = { record: Support.serialize(record), attributes: Support.serialize(attributes) }
+      value[:associations] = Support.serialize(associations) unless associations.empty?
+      value
+    end
+  end
+
+  # Relationship and associated-record changes for belongs_to or has_one.
+  class ToOneAssociationDiff
+    attr_reader :kind #: Symbol
+    attr_reader :relationship #: ValueChange?
+    attr_reader :changed #: RecordChange?
+
+    #: (kind: Symbol, relationship: ValueChange?, changed: RecordChange?) -> void
+    def initialize(kind:, relationship:, changed:)
+      @kind = kind
+      @relationship = relationship
+      @changed = changed
+      freeze
+    end
+
+    #: () -> bool
+    def empty?
+      relationship.nil? && changed.nil?
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        kind: kind,
+        relationship: Support.serialize(relationship),
+        changed: Support.serialize(changed)
+      }
+    end
+  end
+
+  # Membership and associated-record changes for has_many.
+  class CollectionAssociationDiff
+    attr_reader :kind #: Symbol
+    attr_reader :added #: Array[RecordSnapshot]
+    attr_reader :removed #: Array[RecordSnapshot]
+    attr_reader :changed #: Array[RecordChange]
+
+    #: (kind: Symbol, added: Array[RecordSnapshot], removed: Array[RecordSnapshot], changed: Array[RecordChange]) -> void
+    def initialize(kind:, added:, removed:, changed:)
+      @kind = kind
+      @added = added.dup.freeze
+      @removed = removed.dup.freeze
+      @changed = changed.dup.freeze
+      freeze
+    end
+
+    #: () -> bool
+    def empty?
+      added.empty? && removed.empty? && changed.empty?
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        kind: kind,
+        added: Support.serialize(added),
+        removed: Support.serialize(removed),
+        changed: Support.serialize(changed)
+      }
+    end
+  end
+
+  # The complete structured difference between two normalized endpoints.
+  class Diff
+    attr_reader :record_presence_change #: ValueChange?
+    attr_reader :attributes #: Hash[String, ValueChange]
+    attr_reader :associations #: Hash[String, ToOneAssociationDiff | CollectionAssociationDiff]
+
+    #: (?record_presence_change: ValueChange?, ?attributes: attribute_changes, ?associations: association_diffs) -> void
+    def initialize(record_presence_change: nil, attributes: {}, associations: {})
+      @record_presence_change = record_presence_change
+      @attributes = Support.immutable_copy(attributes)
+      @associations = Support.immutable_copy(associations)
+      freeze
+    end
+
+    #: () -> bool
+    def empty?
+      record_presence_change.nil? && attributes.empty? && associations.empty?
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        record_presence_change: Support.serialize(record_presence_change),
+        attributes: Support.serialize(attributes),
+        associations: Support.serialize(associations)
+      }
+    end
+  end
+end

data/lib/paper_trail_diff/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  VERSION = '0.1.0'
+end

data/lib/paper_trail_diff/version_range.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects an inclusive, chronological range from a record's root versions.
+  class VersionRange
+    #: (untyped, from: untyped, to: untyped) -> void
+    def initialize(record, from:, to:)
+      @record = record
+      @from = from
+      @to = to
+    end
+
+    #: () -> Array[untyped]
+    def select
+      relation = versions_relation
+      validate_boundary!(@from, relation, boundary: :from)
+      validate_boundary!(@to, relation, boundary: :to)
+      if Support.compare_versions(@from, @to).positive?
+        raise InvalidTimelineRangeError, '`from` version must not follow `to` version'
+      end
+
+      select_relation(
+        relation.where(created_at: @from.created_at..@to.created_at),
+        through: @to
+      )
+    end
+
+    #: () -> Array[untyped]
+    def select_through_latest
+      relation = versions_relation
+      validate_boundary!(@from, relation, boundary: :from)
+      select_relation(relation.where(created_at: @from.created_at..))
+    end
+
+    private
+
+    # @rbs @record: untyped
+    # @rbs @from: untyped
+    # @rbs @to: untyped
+
+    #: () -> untyped
+    def versions_relation
+      association_name = @record.class.versions_association_name
+      @record.public_send(association_name)
+    rescue NoMethodError => e
+      message = 'record does not expose a PaperTrail version history'
+      raise InvalidTimelineRangeError, message, cause: e
+    end
+
+    #: (untyped, ?through: untyped) -> Array[untyped]
+    def select_relation(relation, through: nil)
+      selected = relation.to_a.select do |version|
+        next false if Support.compare_versions(@from, version).positive?
+        next true unless through
+
+        Support.compare_versions(version, through) <= 0
+      end
+      selected.sort_by { |version| Support.chronological_version_key(version) }
+    end
+
+    #: (untyped, untyped, boundary: Symbol) -> void
+    def validate_boundary!(requested, relation, boundary:)
+      Endpoint.validate!(requested)
+      return if valid_boundary?(requested, relation)
+
+      raise InvalidTimelineRangeError, "`#{boundary}` version is not in the record history"
+    rescue InvalidEndpointError, NoMethodError
+      raise InvalidTimelineRangeError, "`#{boundary}` version is not in the record history"
+    end
+
+    #: (untyped, untyped) -> bool
+    def valid_boundary?(requested, relation)
+      expected_identity = [@record.class.base_class.name.to_s, @record.id.to_s]
+      Endpoint.version?(requested) &&
+        requested.instance_of?(relation.klass) &&
+        Endpoint.identity(requested) == expected_identity &&
+        relation.where(id: requested.id).exists?
+    end
+  end
+end