paper_trail_diff 0.1.0

data/lib/paper_trail_diff/analysis.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Endpoint and root-checkpoint timeline results built from one normalized history.
+  class Analysis
+    attr_reader :diff #: Diff
+    attr_reader :timeline #: Array[Step]
+    attr_reader :activity_timeline #: Array[ActivityStep]?
+
+    #: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
+    def initialize(diff:, timeline:, activity_timeline: nil)
+      @diff = diff
+      @timeline = timeline.dup.freeze
+      @activity_timeline = activity_timeline&.dup&.freeze
+      freeze
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      value = { diff: diff.to_h, timeline: Support.serialize(timeline) }
+      value[:activity_timeline] = Support.serialize(activity_timeline) if activity_timeline
+      value
+    end
+  end
+end

data/lib/paper_trail_diff/association_discovery.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # One discoverable ActiveRecord association path.
+  class AssociationDescriptor
+    attr_reader :path #: String
+    attr_reader :kind #: Symbol
+    attr_reader :target_type #: String?
+    attr_reader :through #: String?
+    attr_reader :polymorphic #: bool
+    attr_reader :cycle #: bool
+
+    #: (path: String, kind: Symbol, target_type: String?, ?through: String?, ?flags: Array[Symbol]) -> void
+    def initialize(path:, kind:, target_type:, through: nil, flags: [])
+      @path = Support.immutable_copy(path)
+      @kind = kind
+      @target_type = Support.immutable_copy(target_type)
+      @through = Support.immutable_copy(through)
+      @polymorphic = flags.include?(:polymorphic)
+      @cycle = flags.include?(:cycle)
+      freeze
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        path: path,
+        kind: kind,
+        target_type: target_type,
+        through: through,
+        polymorphic: polymorphic,
+        cycle: cycle
+      }
+    end
+  end
+
+  # Discovers finite, supported association paths for configuration UIs.
+  class AssociationDiscovery
+    #: (untyped, max_depth: Integer) -> void
+    def initialize(model_or_record, max_depth:)
+      unless max_depth.is_a?(Integer) && max_depth.positive?
+        raise ConfigurationError, 'max_depth: must be a positive integer'
+      end
+
+      @model_class = model_or_record.is_a?(Class) ? model_or_record : model_or_record.class
+      @max_depth = max_depth
+      return if @model_class.respond_to?(:reflect_on_all_associations)
+
+      raise ConfigurationError, 'expected an ActiveRecord model class or record'
+    end
+
+    #: () -> Array[AssociationDescriptor]
+    def call
+      discover(@model_class, prefix: '', ancestry: [@model_class], depth: 1).freeze
+    end
+
+    private
+
+    # @rbs @model_class: untyped
+    # @rbs @max_depth: Integer
+
+    #: (untyped, prefix: String, ancestry: Array[untyped], depth: Integer) -> Array[AssociationDescriptor]
+    def discover(model_class, prefix:, ancestry:, depth:)
+      supported_reflections(model_class).flat_map do |reflection|
+        describe_and_descend(reflection, prefix: prefix, ancestry: ancestry, depth: depth)
+      end
+    end
+
+    #: (untyped, prefix: String, ancestry: Array[untyped], depth: Integer) -> Array[AssociationDescriptor]
+    def describe_and_descend(reflection, prefix:, ancestry:, depth:)
+      path = association_path(prefix, reflection.name.to_s)
+      target_class = reflection_target(reflection)
+      cycle = target_class ? ancestry.include?(target_class) : false
+      descriptor = descriptor_for(reflection, path, target_class, cycle)
+      return [descriptor] unless target_class && !cycle && depth < @max_depth
+
+      descendants = discover(
+        target_class,
+        prefix: path,
+        ancestry: [*ancestry, target_class],
+        depth: depth + 1
+      )
+      [descriptor, *descendants]
+    end
+
+    #: (untyped, String, untyped, bool) -> AssociationDescriptor
+    def descriptor_for(reflection, path, target_class, cycle)
+      flags = [] #: Array[Symbol]
+      flags << :polymorphic if reflection.polymorphic?
+      flags << :cycle if cycle
+      AssociationDescriptor.new(
+        path: path,
+        kind: reflection.macro,
+        target_type: target_class&.name || reflection_target_name(reflection),
+        through: reflection.options[:through]&.to_s,
+        flags: flags
+      )
+    end
+
+    #: (untyped) -> Array[untyped]
+    def supported_reflections(model_class)
+      model_class.reflect_on_all_associations
+                 .select { |reflection| SUPPORTED_ASSOCIATION_MACROS.include?(reflection.macro) }
+                 .reject { |reflection| paper_trail_versions?(model_class, reflection) }
+                 .sort_by { |reflection| reflection.name.to_s }
+    end
+
+    #: (untyped, untyped) -> bool
+    def paper_trail_versions?(model_class, reflection)
+      model_class.respond_to?(:versions_association_name) &&
+        reflection.name.to_s == model_class.versions_association_name.to_s
+    end
+
+    #: (untyped) -> untyped
+    def reflection_target(reflection)
+      reflection.klass unless reflection.polymorphic?
+    rescue NameError
+      nil
+    end
+
+    #: (untyped) -> String?
+    def reflection_target_name(reflection)
+      reflection.class_name.to_s unless reflection.polymorphic?
+    end
+
+    #: (String, String) -> String
+    def association_path(prefix, name)
+      prefix.empty? ? name : "#{prefix}.#{name}"
+    end
+  end
+end

data/lib/paper_trail_diff/association_traversal.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Resolves and validates ActiveRecord reflections for a bounded association tree.
+  class AssociationTraversal
+    #: (AssociationTree) -> void
+    def initialize(tree)
+      @tree = tree
+      @reflection_cache = {}
+    end
+
+    #: (untyped) -> void
+    def validate!(model_class)
+      validate_tree!(model_class, @tree, path: '')
+    end
+
+    #: (untyped) -> Array[Array[untyped]]
+    def selected_reflections(model_class)
+      collect_reflections(model_class, @tree, path: '').freeze
+    end
+
+    #: (untyped, untyped) -> void
+    def ensure_habtm_history!(model_class, version)
+      paths = habtm_paths(model_class)
+      return if paths.empty?
+      return if version.respond_to?(:transaction_id) && version.transaction_id
+
+      message = "HABTM history is incomplete at version #{version.id}: #{paths.join(', ')}"
+      raise IncompleteAssociationHistoryError, message
+    end
+
+    #: (untyped) -> Array[String]
+    def habtm_paths(model_class)
+      selected_reflections(model_class).filter_map do |path, reflection|
+        path if habtm_reflection?(reflection)
+      end.freeze
+    end
+
+    #: (untyped, AssociationTree, path: String) -> Array[untyped]
+    def reflections_for(model_class, tree, path:)
+      key = [model_class.name.to_s, path, tree.object_id]
+      @reflection_cache[key] ||= requested_reflections(model_class, tree, path)
+    end
+
+    #: (untyped) -> Array[String]
+    def incoming_relationship_columns(reflection)
+      direct = %i[has_one has_many].include?(reflection.macro) && !reflection.options[:through]
+      return [] unless direct
+
+      foreign_keys = Array(reflection.foreign_key)
+      # @type var foreign_keys: Array[untyped]
+      columns = foreign_keys.map do |column| # rubocop:disable Style/SymbolProc
+        column.to_s
+      end
+      columns << reflection.type.to_s if reflection.options[:as]
+      columns
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @reflection_cache: Hash[Array[untyped], Array[untyped]]
+
+    #: (untyped, AssociationTree, path: String) -> Array[Array[untyped]]
+    def collect_reflections(model_class, tree, path:)
+      reflections_for(model_class, tree, path: path).flat_map do |reflection|
+        child_path = join_path(path, reflection.name.to_s)
+        result = [[child_path, reflection]]
+        subtree = tree.child(reflection.name)
+        next result unless subtree && !subtree.empty? && !reflection.polymorphic?
+
+        result + collect_reflections(reflection.klass, subtree, path: child_path)
+      end
+    end
+
+    #: (untyped, AssociationTree, path: String) -> void
+    def validate_tree!(model_class, tree, path:)
+      reflections_for(model_class, tree, path: path).each do |reflection|
+        subtree = tree.child(reflection.name)
+        next unless subtree && !subtree.empty? && !reflection.polymorphic?
+
+        child_path = join_path(path, reflection.name.to_s)
+        validate_tree!(reflection.klass, subtree, path: child_path)
+      end
+    end
+
+    #: (untyped, AssociationTree, String) -> Array[untyped]
+    def requested_reflections(model_class, tree, path)
+      tree.children.map do |name, _subtree|
+        resolve_reflection(model_class, name, join_path(path, name))
+      end.freeze
+    end
+
+    #: (untyped, String, String) -> untyped
+    def resolve_reflection(model_class, name, full_path)
+      reflection = model_class.reflect_on_association(name.to_sym)
+      raise UnknownAssociationError, "unknown association: #{full_path}" unless reflection
+
+      if paper_trail_versions?(model_class, reflection)
+        message = "unsupported association #{full_path}: PaperTrail versions"
+        raise UnsupportedAssociationError, message
+      end
+      unless SUPPORTED_ASSOCIATION_MACROS.include?(reflection.macro)
+        raise UnsupportedAssociationError,
+              "unsupported association #{full_path}: #{reflection.macro}"
+      end
+
+      reflection
+    end
+
+    #: (untyped, untyped) -> bool
+    def paper_trail_versions?(model_class, reflection)
+      model_class.respond_to?(:versions_association_name) &&
+        reflection.name.to_s == model_class.versions_association_name.to_s
+    end
+
+    #: (untyped) -> bool
+    def habtm_reflection?(reflection)
+      return true if reflection.macro == :has_and_belongs_to_many
+      return false unless reflection.options[:through]
+
+      habtm_reflection?(reflection.through_reflection)
+    end
+
+    #: (String, String) -> String
+    def join_path(parent, name)
+      parent.empty? ? name : "#{parent}.#{name}"
+    end
+  end
+end

data/lib/paper_trail_diff/branch_snapshot_refresher.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Reconstructs selected root branches and merges them into a prior immutable snapshot.
+  class BranchSnapshotRefresher
+    #: (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped) -> void
+    def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+      tree:,
+      ignore_policy:,
+      traversal:,
+      pool:,
+      normalizer:,
+      full_snapshotter:,
+      partial_snapshotter:,
+      association_reader:
+    )
+      @tree = tree
+      @ignore_policy = ignore_policy
+      @traversal = traversal
+      @pool = pool
+      @full_snapshotter = full_snapshotter
+      @partial_snapshotter = partial_snapshotter
+      @components = {} #: Hash[Array[String], [AssociationTree, SnapshotNormalizer]]
+      @event_refresher = ActivityEventSnapshotRefresher.new(
+        traversal: traversal,
+        pool: pool,
+        components: method(:components),
+        association_reader: association_reader
+      )
+      @root_refresher = ActivityRootSnapshotRefresher.new(
+        tree: tree,
+        traversal: traversal,
+        normalizer: normalizer,
+        record_after: @event_refresher.method(:record_after),
+        changeset: @event_refresher.method(:deserialized_changeset),
+        partial_snapshotter: method(:partial_snapshot)
+      )
+    end
+
+    #: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
+    def advance_root(root_endpoint, context_endpoint, previous_snapshot, event:)
+      handled, incremental = @root_refresher.call(
+        root_endpoint,
+        context_endpoint,
+        previous_snapshot,
+        event
+      )
+      return incremental if handled
+
+      full_snapshot(root_endpoint, context_endpoint)
+    end
+
+    #: (untyped, untyped, RecordSnapshot?, Array[String], ?event: ActivityEvent?, ?isolated: bool) -> RecordSnapshot?
+    def call( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+      root_endpoint,
+      context_endpoint,
+      previous_snapshot,
+      branches,
+      event: nil,
+      isolated: false
+    )
+      return full_snapshot(root_endpoint, context_endpoint) unless previous_snapshot
+      if isolated && event && branches.length > 1
+        return refresh_independent_branches(
+          root_endpoint,
+          context_endpoint,
+          previous_snapshot,
+          branches,
+          event
+        )
+      end
+
+      endpoints = [root_endpoint, context_endpoint]
+      handled, incremental = incremental_event(
+        endpoints,
+        previous_snapshot,
+        branches,
+        event,
+        isolated
+      )
+      return incremental if handled
+
+      partial = partial_snapshot(root_endpoint, context_endpoint, branches)
+      return full_snapshot(root_endpoint, context_endpoint) unless partial
+
+      merge(previous_snapshot, partial)
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @ignore_policy: IgnorePolicy
+    # @rbs @traversal: AssociationTraversal
+    # @rbs @pool: SnapshotPool
+    # @rbs @full_snapshotter: untyped
+    # @rbs @partial_snapshotter: untyped
+    # @rbs @components: Hash[Array[String], [AssociationTree, SnapshotNormalizer]]
+    # @rbs @event_refresher: ActivityEventSnapshotRefresher
+    # @rbs @root_refresher: ActivityRootSnapshotRefresher
+
+    #: (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [bool, RecordSnapshot?]
+    def incremental_event(endpoints, previous, branches, event, isolated)
+      return [false, nil] unless isolated
+
+      @event_refresher.call(
+        endpoints.fetch(0),
+        endpoints.fetch(1),
+        previous,
+        branches,
+        event
+      )
+    end
+
+    #: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent) -> RecordSnapshot?
+    def refresh_independent_branches( # rubocop:disable Metrics/MethodLength
+      root_endpoint,
+      context_endpoint,
+      previous_snapshot,
+      branches,
+      event
+    )
+      snapshot = previous_snapshot
+      remaining = [] #: Array[String]
+      branches.each do |branch|
+        handled, incremental = @event_refresher.call(
+          root_endpoint,
+          context_endpoint,
+          snapshot,
+          [branch],
+          event
+        )
+        if handled
+          snapshot = incremental || snapshot
+        else
+          remaining << branch
+        end
+      end
+      return snapshot if remaining.empty?
+
+      partial = partial_snapshot(root_endpoint, context_endpoint, remaining)
+      return full_snapshot(root_endpoint, context_endpoint) unless partial
+
+      merge(snapshot, partial)
+    end
+
+    #: (untyped, untyped, Array[String]) -> RecordSnapshot?
+    def partial_snapshot(root_endpoint, context_endpoint, branches)
+      tree, normalizer = components(branches)
+      @partial_snapshotter.call(
+        root_endpoint,
+        context_endpoint,
+        tree: tree,
+        normalizer: normalizer
+      )
+    end
+
+    #: (Array[String]) -> [AssociationTree, SnapshotNormalizer]
+    def components(branches)
+      key = branches.sort.freeze
+      @components[key] ||= build_components(key)
+    end
+
+    #: (Array[String]) -> [AssociationTree, SnapshotNormalizer]
+    def build_components(branches)
+      tree = @tree.select(branches)
+      normalizer = SnapshotNormalizer.new(
+        tree: tree,
+        ignore_policy: @ignore_policy,
+        traversal: @traversal,
+        pool: @pool
+      )
+      [tree, normalizer]
+    end
+
+    #: (untyped, untyped) -> RecordSnapshot?
+    def full_snapshot(root_endpoint, context_endpoint)
+      @full_snapshotter.call(root_endpoint, context_endpoint)
+    end
+
+    #: (RecordSnapshot, RecordSnapshot) -> RecordSnapshot
+    def merge(previous, partial)
+      RecordSnapshot.new(
+        type: previous.type,
+        id: previous.id,
+        attributes: previous.attributes,
+        associations: previous.associations.merge(partial.associations)
+      )
+    end
+  end
+end

data/lib/paper_trail_diff/configuration.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # An immutable, bounded tree built from explicit association paths.
+  class AssociationTree
+    attr_reader :children #: Hash[String, AssociationTree]
+
+    class << self
+      #: (untyped) -> AssociationTree
+      def build(values)
+        unless valid_values?(values)
+          raise ConfigurationError, 'associations: must be an array of strings or symbols'
+        end
+
+        tree = {} #: Hash[String, untyped]
+        values.each { |value| add_path(tree, value.to_s) }
+        from_hash(tree)
+      end
+
+      private
+
+      #: (Hash[String, untyped], String) -> void
+      def add_path(tree, path)
+        segments = path.split('.', -1)
+        if segments.empty? || segments.any?(&:empty?) || path == '$'
+          raise ConfigurationError, "invalid association path: #{path.inspect}"
+        end
+
+        segments.inject(tree) do |branch, segment|
+          branch[segment] ||= {} #: Hash[String, untyped]
+        end
+      end
+
+      #: (Hash[String, untyped]) -> AssociationTree
+      def from_hash(tree)
+        children = tree.sort.to_h do |name, branch|
+          [name, from_hash(branch)]
+        end
+        new(children)
+      end
+
+      #: (untyped) -> bool
+      def valid_values?(values)
+        values.is_a?(Array) && values.all? do |value|
+          value.is_a?(String) || value.is_a?(Symbol)
+        end
+      end
+    end
+
+    #: (Hash[String, AssociationTree]) -> void
+    def initialize(children)
+      @children = children.dup.freeze
+      freeze
+    end
+
+    #: () -> bool
+    def empty?
+      children.empty?
+    end
+
+    #: (String | Symbol) -> AssociationTree?
+    def child(name)
+      children[name.to_s]
+    end
+
+    #: (Array[String]) -> AssociationTree
+    def select(names)
+      self.class.new(children.slice(*names))
+    end
+
+    #: (?prefix: String) -> Array[String]
+    def paths(prefix: '')
+      children.flat_map do |name, subtree|
+        path = prefix.empty? ? name : "#{prefix}.#{name}"
+        [path, *subtree.paths(prefix: path)]
+      end.freeze
+    end
+  end
+
+  # Immutable rules for globally and path-specifically excluded attributes.
+  class IgnorePolicy
+    ROOT_PATH = '$'
+    VALID_KEYS = %w[all paths].freeze
+    private_constant :VALID_KEYS
+
+    class << self
+      #: (untyped, association_paths: Array[String]) -> IgnorePolicy
+      def build(value, association_paths:)
+        return new(all: normalize_names(value, context: 'ignore'), paths: {}) if value.is_a?(Array)
+
+        unless value.is_a?(Hash)
+          raise ConfigurationError, 'ignore: must be an array or a hash with all: and paths:'
+        end
+
+        options = normalize_options(value)
+        empty_paths = {} #: Hash[untyped, untyped]
+        new(
+          all: normalize_names(options.fetch('all', []), context: 'ignore[:all]'),
+          paths: normalize_paths(options.fetch('paths', empty_paths), association_paths)
+        )
+      end
+
+      private
+
+      #: (Hash[untyped, untyped]) -> Hash[String, untyped]
+      def normalize_options(value)
+        options = {} #: Hash[String, untyped]
+        value.each do |key, item|
+          name = key.to_s
+          unless VALID_KEYS.include?(name) && !options.key?(name)
+            raise ConfigurationError, "unknown or duplicate ignore option: #{key.inspect}"
+          end
+
+          options[name] = item
+        end
+        options
+      end
+
+      #: (untyped, Array[String]) -> Hash[String, Array[String]]
+      def normalize_paths(value, association_paths)
+        raise ConfigurationError, 'ignore[:paths]: must be a hash' unless value.is_a?(Hash)
+
+        allowed_paths = [ROOT_PATH, *association_paths]
+        paths = {} #: Hash[String, Array[String]]
+        value.each do |path, names|
+          add_path_rule(paths, path, names, allowed_paths)
+        end
+        paths.sort.to_h.freeze
+      end
+
+      #: (Hash[String, Array[String]], untyped, untyped, Array[String]) -> void
+      def add_path_rule(paths, path, names, allowed_paths)
+        normalized_path = path.to_s
+        unless allowed_paths.include?(normalized_path) && !paths.key?(normalized_path)
+          raise ConfigurationError, "unknown or duplicate ignore path: #{path.inspect}"
+        end
+
+        context = "ignore[:paths][#{normalized_path.inspect}]"
+        paths[normalized_path] = normalize_names(names, context: context)
+      end
+
+      #: (untyped, context: String) -> Array[String]
+      def normalize_names(values, context:)
+        valid = values.is_a?(Array) && values.all? do |value|
+          value.is_a?(String) || value.is_a?(Symbol)
+        end
+        raise ConfigurationError, "#{context}: must be an array of strings or symbols" unless valid
+
+        values.map(&:to_s).uniq.sort.freeze
+      end
+    end
+
+    attr_reader :all #: Array[String]
+    attr_reader :paths #: Hash[String, Array[String]]
+
+    #: (all: Array[String], paths: Hash[String, Array[String]]) -> void
+    def initialize(all:, paths:)
+      @all = all.dup.freeze
+      @paths = paths.dup.freeze
+      freeze
+    end
+
+    #: (String) -> Array[String]
+    def attributes_for(path)
+      external_path = path.empty? ? ROOT_PATH : path
+      (all + paths.fetch(external_path, [])).uniq.freeze
+    end
+  end
+end