paper_trail_diff 0.1.0

data/lib/paper_trail_diff/diagnostics.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # One immutable historical-reconstruction setup finding.
+  class DiagnosticIssue
+    attr_reader :severity #: Symbol
+    attr_reader :code #: Symbol
+    attr_reader :message #: String
+    attr_reader :path #: String?
+    attr_reader :version_id #: untyped
+
+    #: (severity: Symbol, code: Symbol, message: String, ?path: String?, ?version_id: untyped) -> void
+    def initialize(severity:, code:, message:, path: nil, version_id: nil)
+      @severity = severity
+      @code = code
+      @message = Support.immutable_copy(message)
+      @path = Support.immutable_copy(path)
+      @version_id = Support.immutable_copy(version_id)
+      freeze
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        severity: severity,
+        code: code,
+        message: message,
+        path: path,
+        version_id: version_id
+      }
+    end
+  end
+
+  # Immutable diagnostics for a requested historical association comparison.
+  class DiagnosticReport
+    attr_reader :issues #: Array[DiagnosticIssue]
+
+    #: (issues: Array[DiagnosticIssue]) -> void
+    def initialize(issues:)
+      @issues = issues.dup.freeze
+      freeze
+    end
+
+    #: () -> Array[DiagnosticIssue]
+    def errors
+      issues.select { |issue| issue.severity == :error }.freeze
+    end
+
+    #: () -> Array[DiagnosticIssue]
+    def warnings
+      issues.select { |issue| issue.severity == :warning }.freeze
+    end
+
+    #: () -> bool
+    def ok?
+      errors.empty?
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      { ok: ok?, issues: Support.serialize(issues) }
+    end
+  end
+
+  # Performs read-only checks for known PaperTrail/PT-AT reconstruction hazards.
+  class HistoryDiagnostics
+    #: (untyped, untyped, associations: Array[String | Symbol]) -> void
+    def initialize(from_version, to_version, associations:)
+      @from_version = from_version
+      @to_version = to_version
+      @tree = AssociationTree.build(associations)
+      @issues = [] #: Array[DiagnosticIssue]
+    end
+
+    #: () -> DiagnosticReport
+    def call
+      model_class = validated_model_class
+      return DiagnosticReport.new(issues: []) if @tree.empty?
+
+      unless association_tracking_available?
+        add_error(:association_tracking_unavailable, tracking_unavailable_message)
+        return DiagnosticReport.new(issues: @issues)
+      end
+
+      traversal = AssociationTraversal.new(@tree)
+      selected = traversal.selected_reflections(model_class)
+      inspect_targets(selected)
+      inspect_checkpoint_timestamp(model_class)
+      inspect_habtm(selected)
+      DiagnosticReport.new(issues: @issues)
+    end
+
+    private
+
+    # @rbs @from_version: untyped
+    # @rbs @to_version: untyped
+    # @rbs @tree: AssociationTree
+    # @rbs @issues: Array[DiagnosticIssue]
+
+    #: () -> untyped
+    def validated_model_class
+      unless version_identity(@from_version) == version_identity(@to_version)
+        raise VersionMismatchError, 'versions must belong to the same PaperTrail item'
+      end
+
+      Object.const_get(version_type(@from_version))
+    rescue NoMethodError => e
+      raise VersionMismatchError, 'expected PaperTrail version endpoints', cause: e
+    end
+
+    #: (Array[Array[untyped]]) -> void
+    def inspect_targets(selected)
+      selected.each do |path, reflection|
+        if reflection.polymorphic?
+          add_warning(:polymorphic_target_unverified, 'polymorphic target cannot be verified', path)
+          next
+        end
+
+        inspect_versioned_model(reflection.klass, path)
+        inspect_through_model(reflection, path) if reflection.options[:through]
+      end
+    end
+
+    #: (Array[Array[untyped]]) -> void
+    def inspect_habtm(selected)
+      paths = selected.filter_map do |path, reflection|
+        path if reflection.macro == :has_and_belongs_to_many
+      end
+      return if paths.empty?
+
+      inspect_transaction_metadata(paths)
+    end
+
+    #: (untyped) -> void
+    def inspect_checkpoint_timestamp(model_class)
+      return if synchronized_timestamp_disabled?(model_class)
+
+      message = 'manual checkpoints should set synchronize_version_creation_timestamp: false'
+      add_warning(:synchronized_version_timestamp, message)
+    end
+
+    #: (Array[String]) -> void
+    def inspect_transaction_metadata(paths)
+      [@from_version, @to_version].each do |version|
+        if !version.respond_to?(:transaction_id)
+          add_error(:transaction_id_column_missing, 'version has no transaction_id column')
+        elsif version.transaction_id.nil?
+          paths.each do |path|
+            add_error(
+              :transaction_id_missing,
+              'HABTM endpoint has no transaction-backed association snapshot',
+              path,
+              version.id
+            )
+          end
+        end
+      end
+    end
+
+    #: (untyped, String) -> void
+    def inspect_versioned_model(model_class, path)
+      return if model_versioned?(model_class)
+
+      add_warning(
+        :unversioned_association_target,
+        "#{model_class.name} does not appear to have PaperTrail enabled",
+        path
+      )
+    end
+
+    #: (untyped, String) -> void
+    def inspect_through_model(reflection, path)
+      model_class = reflection.through_reflection.klass
+      return if model_versioned?(model_class)
+
+      add_warning(
+        :unversioned_through_model,
+        "#{model_class.name} does not appear to have PaperTrail enabled",
+        path
+      )
+    end
+
+    #: (untyped) -> bool
+    def model_versioned?(model_class)
+      model_class.respond_to?(:paper_trail_options) && !model_class.paper_trail_options.nil?
+    end
+
+    #: (untyped) -> bool
+    def synchronized_timestamp_disabled?(model_class)
+      options = model_class.paper_trail_options
+      options[:synchronize_version_creation_timestamp] == false
+    rescue NoMethodError
+      false
+    end
+
+    #: () -> bool
+    def association_tracking_available?
+      paper_trail = Object.const_get(:PaperTrail) #: untyped
+      config = paper_trail.config #: untyped
+      !!(defined?(::PaperTrailAssociationTracking) &&
+        config.respond_to?(:track_associations?) && config.track_associations?)
+    end
+
+    #: (untyped) -> Array[String]
+    def version_identity(version)
+      [version.item_type.to_s, version.item_id.to_s]
+    end
+
+    #: (untyped) -> String
+    def version_type(version)
+      subtype = version.item_subtype if version.respond_to?(:item_subtype)
+      subtype.to_s.empty? ? version.item_type.to_s : subtype.to_s
+    end
+
+    #: () -> String
+    def tracking_unavailable_message
+      'association tracking must be loaded and enabled to diagnose associations'
+    end
+
+    #: (Symbol, String, ?String?, ?untyped) -> void
+    def add_error(code, message, path = nil, version_id = nil)
+      add_issue(:error, code, message, path, version_id)
+    end
+
+    #: (Symbol, String, ?String?) -> void
+    def add_warning(code, message, path = nil)
+      add_issue(:warning, code, message, path, nil)
+    end
+
+    #: (Symbol, Symbol, String, String?, untyped) -> void
+    def add_issue(severity, code, message, path, version_id)
+      @issues << DiagnosticIssue.new(
+        severity: severity,
+        code: code,
+        message: message,
+        path: path,
+        version_id: version_id
+      )
+    end
+  end
+end

data/lib/paper_trail_diff/endpoint.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Validates and describes explicit PaperTrail-version and live-record endpoints.
+  module Endpoint
+    module_function
+
+    #: (untyped, untyped) -> void
+    def validate_pair!(from_endpoint, to_endpoint)
+      validate!(from_endpoint)
+      validate!(to_endpoint)
+      return if identity(from_endpoint) == identity(to_endpoint)
+
+      raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
+    end
+
+    #: (untyped) -> void
+    def validate!(endpoint)
+      return if version?(endpoint)
+
+      validate_record!(endpoint)
+    end
+
+    #: (untyped) -> bool
+    def version?(endpoint)
+      endpoint.respond_to?(:reify) &&
+        endpoint.respond_to?(:item_type) &&
+        endpoint.respond_to?(:item_id)
+    end
+
+    #: (untyped) -> bool
+    def record?(endpoint)
+      !version?(endpoint) &&
+        endpoint.respond_to?(:persisted?) &&
+        endpoint.respond_to?(:destroyed?) &&
+        endpoint.class.respond_to?(:base_class)
+    end
+
+    #: (untyped) -> Array[String]
+    def identity(endpoint)
+      if version?(endpoint)
+        [endpoint.item_type.to_s, endpoint.item_id.to_s]
+      elsif record?(endpoint)
+        [endpoint.class.base_class.name.to_s, endpoint.id.to_s]
+      else
+        raise InvalidEndpointError, 'expected a PaperTrail version or persisted record endpoint'
+      end
+    end
+
+    #: (untyped) -> untyped
+    def model_class(version)
+      subtype = version.item_subtype if version.respond_to?(:item_subtype)
+      model_type = subtype.to_s.empty? ? version.item_type.to_s : subtype.to_s
+      Object.const_get(model_type)
+    rescue NameError => e
+      raise InvalidEndpointError, "cannot resolve endpoint model: #{model_type}", cause: e
+    end
+
+    #: (untyped) -> untyped
+    def reload_record(record)
+      validate_record!(record)
+      record.class.unscoped.find(record.id)
+    rescue StandardError => e
+      active_record = Object.const_get(:ActiveRecord) #: untyped
+      record_not_found = active_record.const_get(:RecordNotFound) #: untyped
+      raise unless e.is_a?(record_not_found)
+
+      message = 'current record endpoint could not be reloaded from the database'
+      raise InvalidEndpointError, message, cause: e
+    end
+
+    #: (untyped) -> void
+    def validate_record!(record)
+      unless record?(record)
+        raise InvalidEndpointError, 'expected a PaperTrail version or persisted record endpoint'
+      end
+      unless record.persisted? && !record.destroyed?
+        raise InvalidEndpointError, 'current record endpoint must be persisted and not destroyed'
+      end
+      return unless record.respond_to?(:has_changes_to_save?) && record.has_changes_to_save?
+
+      raise InvalidEndpointError, 'current record endpoint must not have unsaved changes'
+    end
+    private_class_method :validate_record!
+  end
+end

data/lib/paper_trail_diff/engine.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Pure snapshot comparison. This class has no ActiveRecord or PaperTrail dependencies.
+  class Engine
+    class << self
+      #: (RecordSnapshot?, RecordSnapshot?) -> Diff
+      def compare(from_snapshot, to_snapshot)
+        return Diff.new if from_snapshot.equal?(to_snapshot)
+
+        if from_snapshot.nil? || to_snapshot.nil?
+          change = ValueChange.new(from: from_snapshot, to: to_snapshot)
+          return Diff.new(record_presence_change: change)
+        end
+
+        Diff.new(
+          attributes: compare_attributes(from_snapshot.attributes, to_snapshot.attributes),
+          associations: compare_associations(from_snapshot.associations, to_snapshot.associations)
+        )
+      end
+
+      private
+
+      #: (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, ValueChange]
+      def compare_attributes(from_attributes, to_attributes)
+        changes = {} #: attribute_changes
+        (from_attributes.keys | to_attributes.keys).sort.each do |name|
+          from_value = from_attributes[name]
+          to_value = to_attributes[name]
+          next if from_value == to_value
+
+          changes[name] = ValueChange.new(from: from_value, to: to_value)
+        end
+        changes
+      end
+
+      #: (association_snapshots, association_snapshots) -> association_diffs
+      def compare_associations(from_associations, to_associations)
+        changes = {} #: association_diffs
+        (from_associations.keys | to_associations.keys).sort.each do |name|
+          next if from_associations[name].equal?(to_associations[name])
+
+          from_association, to_association = association_pair(
+            from_associations[name],
+            to_associations[name]
+          )
+          difference = compare_association(from_association, to_association)
+          changes[name] = difference unless difference.empty?
+        end
+        changes
+      end
+
+      #: (AssociationSnapshot?, AssociationSnapshot?) -> [AssociationSnapshot, AssociationSnapshot]
+      def association_pair(from_association, to_association)
+        validate_association_kinds!(from_association, to_association)
+        association = from_association || to_association
+        # @type var association: AssociationSnapshot
+        kind = association.kind
+
+        [
+          from_association || AssociationSnapshot.new(kind: kind, records: []),
+          to_association || AssociationSnapshot.new(kind: kind, records: [])
+        ]
+      end
+
+      #: (AssociationSnapshot?, AssociationSnapshot?) -> void
+      def validate_association_kinds!(from_association, to_association)
+        return unless kinds_differ?(from_association, to_association)
+
+        raise ArgumentError, 'association kind changed between snapshots'
+      end
+
+      #: (AssociationSnapshot?, AssociationSnapshot?) -> bool
+      def kinds_differ?(from_association, to_association)
+        return false unless from_association && to_association
+
+        from_association.kind != to_association.kind
+      end
+
+      #: (AssociationSnapshot, AssociationSnapshot) -> association_diff
+      def compare_association(from_association, to_association)
+        if AssociationSnapshot.collection_kind?(from_association.kind)
+          return compare_collection(from_association, to_association)
+        end
+
+        compare_to_one(from_association, to_association)
+      end
+
+      #: (AssociationSnapshot, AssociationSnapshot) -> ToOneAssociationDiff
+      def compare_to_one(from_association, to_association)
+        from_record = from_association.records.first
+        to_record = to_association.records.first
+        if same_identity?(from_record, to_record)
+          return ToOneAssociationDiff.new(
+            kind: from_association.kind,
+            relationship: nil,
+            changed: compare_record(from_record, to_record)
+          )
+        end
+
+        ToOneAssociationDiff.new(
+          kind: from_association.kind,
+          relationship: relationship_change(from_record, to_record),
+          changed: nil
+        )
+      end
+
+      #: (RecordSnapshot?, RecordSnapshot?) -> ValueChange?
+      def relationship_change(from_record, to_record)
+        return unless from_record || to_record
+
+        ValueChange.new(from: from_record, to: to_record)
+      end
+
+      #: (RecordSnapshot, RecordSnapshot) -> RecordChange?
+      def compare_record(from_record, to_record)
+        attributes = compare_attributes(from_record.attributes, to_record.attributes)
+        associations = compare_associations(from_record.associations, to_record.associations)
+        return if attributes.empty? && associations.empty?
+
+        RecordChange.new(record: to_record, attributes: attributes, associations: associations)
+      end
+
+      #: (AssociationSnapshot, AssociationSnapshot) -> CollectionAssociationDiff
+      def compare_collection(from_association, to_association)
+        from_records = index_records(from_association.records)
+        to_records = index_records(to_association.records)
+
+        CollectionAssociationDiff.new(
+          kind: from_association.kind,
+          added: records_missing_from(to_records, from_records),
+          removed: records_missing_from(from_records, to_records),
+          changed: changed_records(from_records, to_records)
+        )
+      end
+
+      #: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordSnapshot]
+      def records_missing_from(records, other_records)
+        identities = sorted_identities(records.keys - other_records.keys)
+        identities.map { |identity| records.fetch(identity) }
+      end
+
+      #: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordChange]
+      def changed_records(from_records, to_records)
+        sorted_identities(from_records.keys & to_records.keys).filter_map do |identity|
+          from_record = from_records.fetch(identity)
+          to_record = to_records.fetch(identity)
+          next if from_record.equal?(to_record)
+
+          compare_record(from_record, to_record)
+        end
+      end
+
+      #: (Array[RecordSnapshot]) -> Hash[Array[untyped], RecordSnapshot]
+      def index_records(records)
+        index = {} #: Hash[identity, RecordSnapshot]
+        records.each do |record|
+          identity = record.identity
+          if index.key?(identity)
+            raise ArgumentError, "duplicate record identity: #{identity.inspect}"
+          end
+
+          index[identity] = record
+        end
+        index
+      end
+
+      #: (Array[Array[untyped]]) -> Array[Array[untyped]]
+      def sorted_identities(identities)
+        identities.sort_by { |type, id| [type, id.inspect] }
+      end
+
+      #: (RecordSnapshot?, RecordSnapshot?) -> bool
+      def same_identity?(from_record, to_record)
+        from_record && to_record ? from_record.identity == to_record.identity : false
+      end
+    end
+  end
+end

data/lib/paper_trail_diff/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Base error for failures detected by paper_trail_diff.
+  class Error < StandardError; end
+
+  # Raised when a public option has an invalid type, key, value, or path.
+  class ConfigurationError < Error; end
+
+  # Raised when compare endpoints do not belong to the same PaperTrail item.
+  class VersionMismatchError < Error; end
+
+  # Raised when a live endpoint is not a clean, persisted ActiveRecord record.
+  class InvalidEndpointError < Error; end
+
+  # Raised when a timeline boundary is absent or the requested range is reversed.
+  class InvalidTimelineRangeError < Error; end
+
+  # Raised when a requested ActiveRecord association does not exist.
+  class UnknownAssociationError < Error; end
+
+  # Raised when a requested association macro is not supported.
+  class UnsupportedAssociationError < Error; end
+
+  # Raised when association comparison is requested without an available PT-AT setup.
+  class AssociationTrackingUnavailableError < Error; end
+
+  # Raised when recorded PT-AT metadata cannot reliably reconstruct a selected association.
+  class IncompleteAssociationHistoryError < Error; end
+
+  # Raised when current-ended activity cannot be reconstructed for a selected association.
+  class UnsupportedLiveActivityError < Error; end
+end

data/lib/paper_trail_diff/historical_association_reifier.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Reconstructs selected nested edges at one root PaperTrail endpoint.
+  class HistoricalAssociationReifier
+    #: (untyped, ?habtm_version: untyped) -> void
+    def initialize(version, habtm_version: version)
+      @transaction_id = version.transaction_id if version.respond_to?(:transaction_id)
+      if habtm_version.respond_to?(:transaction_id)
+        @habtm_transaction_id = habtm_version.transaction_id
+      end
+      @version_at = version.created_at
+      @reified_associations = {} #: Hash[Array[untyped], bool]
+    end
+
+    #: (untyped, Array[untyped]) -> void
+    def reify(record, reflections)
+      reflections.each { |reflection| reify_association(record, reflection) }
+    end
+
+    private
+
+    # @rbs @transaction_id: untyped
+    # @rbs @habtm_transaction_id: untyped
+    # @rbs @version_at: untyped
+    # @rbs @reified_associations: Hash[Array[untyped], bool]
+
+    #: (untyped, untyped) -> void
+    def reify_association(record, reflection)
+      key = [record.object_id, reflection.name]
+      return if @reified_associations[key]
+
+      @reified_associations[key] = true
+      case reflection.macro
+      when :belongs_to
+        reifier(:BelongsTo).reify(reflection, record, options, @transaction_id)
+      when :has_one
+        reifier(:HasOne).reify(reflection, record, options, @transaction_id)
+      when :has_many
+        reify_has_many(record, reflection)
+      when :has_and_belongs_to_many
+        reify_habtm(record, reflection)
+      end
+    end
+
+    #: (untyped, untyped) -> void
+    def reify_has_many(record, reflection)
+      if reflection.options[:through]
+        reify_association(record, reflection.through_reflection)
+        reifier(:HasManyThrough).reify(reflection, record, options, @transaction_id)
+        return
+      end
+
+      version_table = record.class.paper_trail.version_class.table_name
+      reifier(:HasMany).reify(
+        reflection,
+        record,
+        options,
+        @transaction_id,
+        version_table
+      )
+    end
+
+    #: (untyped, untyped) -> void
+    def reify_habtm(record, reflection)
+      unless @habtm_transaction_id
+        message = 'HABTM reconstruction requires a transaction-backed endpoint version'
+        raise IncompleteAssociationHistoryError, message
+      end
+
+      paper_trail = Object.const_get(:PaperTrail) #: untyped
+      target_versioned = paper_trail.request.enabled_for_model?(reflection.klass)
+      reifier(:HasAndBelongsToMany).reify(
+        target_versioned,
+        reflection,
+        record,
+        options,
+        @habtm_transaction_id
+      )
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def options
+      {
+        dup: true,
+        mark_for_destruction: false,
+        unversioned_attributes: :nil,
+        version_at: @version_at
+      }
+    end
+
+    #: (Symbol) -> untyped
+    def reifier(name)
+      tracking = Object.const_get(:PaperTrailAssociationTracking) #: untyped
+      reifiers = tracking.const_get(:Reifiers) #: untyped
+      reifiers.const_get(name)
+    rescue NameError => e
+      message = 'loaded association tracking does not support nested reconstruction'
+      raise AssociationTrackingUnavailableError, message, cause: e
+    end
+  end
+end