paper_trail_diff 0.5.0 → 0.6.0

data/lib/paper_trail_diff/root_version_plan.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Which versions a range reconstructs, and which pairs of them become steps.
+  #
+  # Without a filter those are the same thing: every selected version is a
+  # boundary and adjacent ones bound each other. A filter separates them, because
+  # each selected mutation then has to be bounded by the version that actually
+  # reveals it rather than by the next mutation that happened to be selected.
+  #
+  # A filter also separates what is *reported* from what has to be *replayed*.
+  # The activity view rebuilds state by carrying one snapshot forward across
+  # every event in order, so skipping a filtered-out version would leave that
+  # snapshot holding a state the record had already moved past. `versions` are
+  # the boundaries the steps refer to; `reconstruction_versions` are every root
+  # version the span passes through, which is what any forward replay must walk.
+  class RootVersionPlan
+    attr_reader :versions #: Array[untyped]
+    attr_reader :reconstruction_versions #: Array[untyped]
+    attr_reader :steps #: Array[[untyped, untyped]]
+    attr_reader :context_version #: untyped
+    # The root versions this plan reports as mutations, which excludes any
+    # version present only to reveal what the last of them produced.
+    attr_reader :mutations #: Array[untyped]
+
+    class << self
+      # Adjacent boundaries, which is what an unfiltered range reports.
+      #: (Array[untyped], ?context_version: untyped) -> RootVersionPlan
+      def contiguous(versions, context_version: nil)
+        new(
+          versions: versions,
+          steps: versions.each_cons(2).map { |from, to| [from, to] },
+          context_version: context_version
+        )
+      end
+
+      #: () -> RootVersionPlan
+      def empty
+        versions = [] #: Array[untyped]
+        steps = [] #: Array[[untyped, untyped]]
+        new(versions: versions, steps: steps)
+      end
+    end
+
+    #: (versions: Array[untyped], steps: Array[[untyped, untyped]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?) -> void
+    def initialize(
+      versions:, steps:, context_version: nil, reconstruction_versions: nil, mutations: nil
+    )
+      @versions = versions.freeze
+      @reconstruction_versions = (reconstruction_versions || versions).freeze
+      @steps = steps.freeze
+      @context_version = context_version
+      @mutations = (mutations || default_mutations).freeze
+      @mutation_keys = Set.new(@mutations.map { |version| key(version) }).freeze
+      freeze
+    end
+
+    #: () -> bool
+    def empty?
+      versions.empty?
+    end
+
+    #: (untyped) -> bool
+    def mutation?(version)
+      @mutation_keys.include?(key(version))
+    end
+
+    private
+
+    # @rbs @mutation_keys: Set[Array[untyped]]
+
+    #: () -> Array[untyped]
+    def default_mutations
+      return @versions unless @context_version
+
+      context = key(@context_version)
+      @versions.reject { |version| key(version) == context }
+    end
+
+    #: (untyped) -> Array[untyped]
+    def key(version)
+      [version.class.name, version.id]
+    end
+  end
+end

data/lib/paper_trail_diff/root_version_selection.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Decides which versions a range reports, and which one reveals the last of
+  # them. A version records the state before its own event, so whatever follows
+  # the final selected mutation is the only thing that can show what it produced.
+  # That successor is reconstruction context rather than a reported mutation, so
+  # a filter must never remove it.
+  #
+  # Both the single-record and the batched selectors resolve this here, because
+  # the rule is subtle enough that two copies of it would drift apart.
+  class RootVersionSelection
+    INCOMPLETE = 'time range requires a later root version to reconstruct its final change'
+
+    #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      in_range:, selected:, after_range:, windowed:, context_required: false, filtered: false
+    )
+      @in_range = in_range
+      @selected = selected
+      @after_range = after_range
+      @windowed = windowed
+      @context_required = context_required
+      @filtered = filtered
+    end
+
+    #: () -> RootVersionPlan
+    def call
+      return without_selection if @selected.empty?
+
+      revealing = revealing_version
+      raise IncompleteTimeRangeError, INCOMPLETE if !revealing && @windowed && !terminal_destroy?
+      return filtered_plan(revealing) if @filtered
+
+      versions = revealing ? (@selected + [revealing]) : @selected
+      RootVersionPlan.contiguous(versions, context_version: revealing)
+    end
+
+    private
+
+    # @rbs @in_range: Array[untyped]
+    # @rbs @selected: Array[untyped]
+    # @rbs @after_range: untyped
+    # @rbs @windowed: bool
+    # @rbs @context_required: bool
+    # @rbs @filtered: bool
+
+    # An activity view still needs a root to reconstruct from even when no root
+    # version falls inside the window, because descendants may have moved.
+    #: () -> RootVersionPlan
+    def without_selection
+      return RootVersionPlan.empty unless @context_required
+      if @after_range
+        return RootVersionPlan.contiguous([@after_range], context_version: @after_range)
+      end
+
+      raise IncompleteTimeRangeError, INCOMPLETE
+    end
+
+    # Each selected mutation is bounded by the version that reveals it, not by
+    # the next mutation that happened to be selected. Bounding by the next
+    # selection would fold anything filtered out in between into it, so the same
+    # edit would read differently depending on what followed it.
+    #: (untyped) -> RootVersionPlan
+    def filtered_plan(revealing)
+      steps = @selected.filter_map do |version|
+        successor = version.equal?(@selected.last) ? revealing : immediate_successor(version)
+        [version, successor] if successor
+      end #: Array[[untyped, untyped]]
+      versions = chronological(steps.flatten(1) + closing_versions)
+      RootVersionPlan.new(
+        versions: versions,
+        steps: steps,
+        context_version: revealing,
+        reconstruction_versions: spanned(versions),
+        mutations: @selected
+      )
+    end
+
+    # Nothing can follow a destroy, so it never pairs into a step. It is still a
+    # selected mutation, and the activity view closes on the absence it leaves,
+    # so it has to stay a boundary or a filtered report loses the deletion
+    # entirely — the one event it can least afford to drop.
+    #: () -> Array[untyped]
+    def closing_versions
+      terminal_destroy? ? [@selected.last] : []
+    end
+
+    # Everything the span passes through, filtered out or not. A replay that
+    # skipped the excluded versions would carry a stale state into the next
+    # reported step, so the two selected mutations either side of a gap would
+    # disagree about what the record looked like between them.
+    #: (Array[untyped]) -> Array[untyped]
+    def spanned(versions)
+      first = versions.first
+      last = versions.last
+      return versions unless first && last
+
+      @in_range.select do |candidate|
+        !Support.compare_versions(first, candidate).positive? &&
+          !Support.compare_versions(candidate, last).positive?
+      end
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def chronological(versions)
+      versions.uniq { |version| [version.class.name, version.id] }
+              .sort_by { |version| Support.chronological_version_key(version) }
+    end
+
+    #: (untyped) -> untyped
+    def immediate_successor(version)
+      @in_range.find { |candidate| Support.compare_versions(version, candidate).negative? }
+    end
+
+    # A version left out by a filter is still the state the last selected change
+    # produced, so it is preferred over anything after the range.
+    #: () -> untyped
+    def revealing_version
+      immediate_successor(@selected.last) || @after_range
+    end
+
+    # A range closing on the record's own destruction needs no later version:
+    # nothing can follow it, so demanding one would reject the range forever.
+    #: () -> bool
+    def terminal_destroy?
+      @selected.last&.event.to_s == 'destroy'
+    end
+  end
+end

data/lib/paper_trail_diff/time_activity_timeline_builder.rb

@@ -14,17 +14,19 @@ module PaperTrailDiff
 
     #: () -> Array[ActivityStep]
     def build
-      history, _root_versions, closing = history_and_versions
+      history, _plan, closing = history_and_versions
       activity_steps(history, closing)
     end
 
     #: () -> Analysis
     def analyze
-      history, root_versions, closing = history_and_versions
+      history, plan, closing = history_and_versions
       Analysis.new(
         diff: Engine.compare(history.first_snapshot, history.last_snapshot),
-        timeline: ActivityRootSteps.call(root_versions, history.root_snapshots),
-        activity_timeline: activity_steps(history, closing)
+        timeline: ActivityRootSteps.call(plan, history.root_snapshots),
+        activity_timeline: activity_steps(history, closing),
+        from_snapshot: history.first_snapshot,
+        to_snapshot: history.last_snapshot
       )
     end
 
@@ -35,18 +37,19 @@ module PaperTrailDiff
     # @rbs @tree: AssociationTree
     # @rbs @snapshotter: untyped
 
-    #: () -> [ActivityHistory, Array[untyped], ActivityStep?]
+    #: () -> [ActivityHistory, RootVersionPlan, ActivityStep?]
     def history_and_versions
-      root_versions = @range.select(context_required: !@tree.empty?)
-      return [ActivityHistory.empty, root_versions, nil] if root_versions.empty?
+      plan = @range.select_plan(context_required: !@tree.empty?)
+      root_versions = plan.reconstruction_versions
+      return [ActivityHistory.empty, plan, nil] if root_versions.empty?
 
       prepare_history(root_versions)
       events = collect_events(root_versions)
-      selected = selected_events(events)
-      return [ActivityHistory.empty, root_versions, nil] unless time_events?(selected, events)
+      selected = selected_events(events, plan)
+      return [ActivityHistory.empty, plan, nil] unless time_events?(selected, events)
 
       history = build_history(root_versions, events)
-      [history, root_versions, closing_step(history, selected.last)]
+      [history, plan, closing_step(history, selected.last)]
     end
 
     #: (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
@@ -66,9 +69,18 @@ module PaperTrailDiff
       (history.steps + [closing]).freeze
     end
 
-    #: (Array[ActivityEvent]) -> Array[ActivityEvent]
-    def selected_events(events)
-      events.select { |event| @range.include?(event.version) }
+    # Root versions inside the window that the plan does not report are context
+    # rather than mutations: the version appended to reveal the last selected
+    # change, and anything a filter excluded but the replay still walks. Neither
+    # may be counted as a selected mutation. Descendant events are not filtered,
+    # so window membership is the whole test for them.
+    #: (Array[ActivityEvent], RootVersionPlan) -> Array[ActivityEvent]
+    def selected_events(events, plan)
+      events.select do |event|
+        next false unless @range.include?(event.version)
+
+        !event.root? || plan.mutation?(event.version)
+      end
     end
 
     # The window's last selected mutation is the root's own destruction, so the

data/lib/paper_trail_diff/time_version_range.rb

@@ -4,34 +4,38 @@
 module PaperTrailDiff
   # Selects in-range root versions plus one later reconstruction boundary.
   class TimeVersionRange
-    #: (untyped, time_range: TimeRange) -> void
-    def initialize(record, time_range:)
+    #: (untyped, time_range: TimeRange, ?version_scope: untyped) -> void
+    def initialize(record, time_range:, version_scope: nil)
       @record = record
       @time_range = time_range
+      @version_scope = version_scope
     end
 
     #: (?context_required: bool) -> Array[untyped]
     def select(context_required: false)
-      relation = versions_relation
-      selected = ordered(@time_range.scope(relation).to_a)
-      empty = [] #: Array[untyped]
-      return empty.freeze if selected.empty? && !context_required
-
-      trailing = trailing_version(relation)
-      unless trailing
-        return selected.freeze if terminal_destroy?(selected)
-
-        message = 'time range requires a later root version to reconstruct its final change'
-        raise IncompleteTimeRangeError, message
-      end
+      select_plan(context_required: context_required).versions
+    end
 
-      (selected + [trailing]).freeze
+    #: (?context_required: bool) -> RootVersionPlan
+    def select_plan(context_required: false)
+      relation = versions_relation
+      in_range = ordered(@time_range.scope(relation).to_a)
+      RootVersionSelection.new(
+        in_range: in_range,
+        selected: VersionScopeFilter.new(@version_scope).call(@time_range.scope(relation),
+                                                              in_range),
+        after_range: trailing_version(relation),
+        windowed: true,
+        context_required: context_required,
+        filtered: !@version_scope.nil?
+      ).call
     end
 
     private
 
     # @rbs @record: untyped
     # @rbs @time_range: TimeRange
+    # @rbs @version_scope: untyped
 
     #: () -> untyped
     def versions_relation
@@ -42,15 +46,6 @@ module PaperTrailDiff
       raise InvalidTimelineRangeError, message, cause: e
     end
 
-    # A window closing on the record's own destruction needs no later version:
-    # the destroy reveals the preceding mutation and nothing can follow it, so
-    # demanding a checkpoint that can never be written would reject the range
-    # permanently.
-    #: (Array[untyped]) -> bool
-    def terminal_destroy?(versions)
-      versions.last&.event.to_s == 'destroy'
-    end
-
     #: (untyped) -> untyped
     def trailing_version(relation)
       @time_range.trailing_scope(relation).reorder(created_at: :asc, id: :asc).first

data/lib/paper_trail_diff/timeline_builder.rb

@@ -4,10 +4,15 @@
 module PaperTrailDiff
   # Selects and compares a chronological slice of a record's version history.
   class TimelineBuilder
-    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?) -> void
-    def initialize(record, from:, to:, snapshotter:, within: nil, versions: nil) # rubocop:disable Metrics/ParameterLists
+    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      record, from:, to:, snapshotter:, within: nil, versions: nil, version_scope: nil, plan: nil
+    )
       @record = record
-      @range = TimelineRange.new(record, from: from, to: to, within: within, versions: versions)
+      @range = TimelineRange.new(
+        record, from: from, to: to, within: within,
+                versions: versions, version_scope: version_scope, plan: plan
+      )
       @snapshotter = snapshotter
     end
 
@@ -22,7 +27,9 @@ module PaperTrailDiff
       steps, first_snapshot, last_snapshot = compare_history(selected_versions)
       Analysis.new(
         diff: Engine.compare(first_snapshot, last_snapshot),
-        timeline: steps
+        timeline: steps,
+        from_snapshot: first_snapshot,
+        to_snapshot: last_snapshot
       )
     end
 
@@ -32,24 +39,20 @@ module PaperTrailDiff
     # @rbs @range: TimelineRange
     # @rbs @snapshotter: untyped
 
-    #: (Array[untyped]) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
-    def compare_history(versions)
-      return empty_history if versions.empty?
+    #: (RootVersionPlan) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
+    def compare_history(plan)
+      return empty_history if plan.empty?
 
+      versions = plan.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(
+      steps = plan.steps.map do |from_version, to_version|
+        Step.new(
           from_version: from_version,
           to_version: to_version,
-          diff: Engine.compare(previous_snapshot, current_snapshot)
+          diff: Engine.compare(@snapshotter.call(from_version), @snapshotter.call(to_version))
         )
-        previous_snapshot = current_snapshot
-        step
       end.freeze
-      [steps, first_snapshot, previous_snapshot]
+      [steps, @snapshotter.call(versions.first), @snapshotter.call(versions.last)]
     end
 
     #: () -> [Array[Step], nil, nil]
@@ -58,9 +61,9 @@ module PaperTrailDiff
       [steps.freeze, nil, nil]
     end
 
-    #: () -> Array[untyped]
+    #: () -> RootVersionPlan
     def selected_versions
-      @range.select
+      @range.select_plan
     end
   end
 end

data/lib/paper_trail_diff/timeline_range.rb

@@ -10,10 +10,12 @@ module PaperTrailDiff
     attr_reader :to #: untyped
     attr_reader :time_range #: TimeRange?
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
-    def initialize(record, from:, to:, within:, versions: nil)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?) -> void
+    def initialize(record, from:, to:, within:, versions: nil, version_scope: nil, plan: nil) # rubocop:disable Metrics/ParameterLists
       @record = record
-      @versions = versions&.freeze
+      @plan = plan
+      @versions = (plan ? plan.versions : versions)&.freeze
+      @version_scope = version_scope
       @requested_from = from
       @requested_to = to
       @time_range = build_time_range(within)
@@ -32,6 +34,26 @@ module PaperTrailDiff
 
     # A batch may have selected these versions already, in which case reselecting
     # them per record would undo the batching.
+    # The plan says which pairs of versions become steps, which a filter can
+    # make different from adjacent pairs of the selected versions.
+    #: (?context_required: bool) -> RootVersionPlan
+    def select_plan(context_required: false)
+      preselected = @plan
+      return preselected if preselected
+
+      range = time_range
+      if range
+        return TimeVersionRange.new(
+          @record, time_range: range, version_scope: @version_scope
+        ).select_plan(context_required: context_required)
+      end
+      return RootVersionPlan.empty if unresolved?
+
+      VersionRange.new(
+        @record, from: @from, to: @to, version_scope: @version_scope
+      ).select_plan_for_range
+    end
+
     #: (?context_required: bool) -> Array[untyped]
     def select(context_required: false)
       preselected = @versions
@@ -39,13 +61,13 @@ module PaperTrailDiff
 
       range = time_range
       if range
-        return TimeVersionRange.new(@record, time_range: range).select(
-          context_required: context_required
-        )
+        return TimeVersionRange.new(
+          @record, time_range: range, version_scope: @version_scope
+        ).select(context_required: context_required)
       end
       return empty_versions if unresolved?
 
-      VersionRange.new(@record, from: @from, to: @to).select
+      VersionRange.new(@record, from: @from, to: @to, version_scope: @version_scope).select
     end
 
     #: () -> bool
@@ -68,6 +90,8 @@ module PaperTrailDiff
 
     # @rbs @record: untyped
     # @rbs @versions: Array[untyped]?
+    # @rbs @plan: RootVersionPlan?
+    # @rbs @version_scope: untyped
     # @rbs @requested_from: untyped
     # @rbs @requested_to: untyped
     # @rbs @from: untyped

data/lib/paper_trail_diff/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/paper_trail_diff/version_range.rb

@@ -4,11 +4,34 @@
 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:)
+    #: (untyped, from: untyped, to: untyped, ?version_scope: untyped) -> void
+    def initialize(record, from:, to:, version_scope: nil)
       @record = record
       @from = from
       @to = to
+      @version_scope = version_scope
+    end
+
+    # Same selection as `select`, but keeping the step pairs a filter implies.
+    #: () -> RootVersionPlan
+    def select_plan_for_range
+      relation = validated_relation
+      select_plan(
+        relation.where(created_at: @from.created_at..@to.created_at),
+        through: @to
+      )
+    end
+
+    #: () -> untyped
+    def validated_relation
+      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
+
+      relation
     end
 
     #: () -> Array[untyped]
@@ -38,6 +61,7 @@ module PaperTrailDiff
     # @rbs @record: untyped
     # @rbs @from: untyped
     # @rbs @to: untyped
+    # @rbs @version_scope: untyped
 
     #: () -> untyped
     def versions_relation
@@ -50,13 +74,29 @@ module PaperTrailDiff
 
     #: (untyped, ?through: untyped) -> Array[untyped]
     def select_relation(relation, through: nil)
-      selected = relation.to_a.select do |version|
+      select_plan(relation, through: through).versions
+    end
+
+    #: (untyped, ?through: untyped) -> RootVersionPlan
+    def select_plan(relation, through: nil)
+      in_range = ordered(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)
+      RootVersionSelection.new(
+        in_range: in_range,
+        selected: VersionScopeFilter.new(@version_scope).call(relation, in_range),
+        after_range: nil,
+        windowed: false,
+        filtered: !@version_scope.nil?
+      ).call
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def ordered(versions)
+      versions.sort_by { |version| Support.chronological_version_key(version) }
     end
 
     #: (untyped, untyped, boundary: Symbol) -> void

data/lib/paper_trail_diff/version_scope_filter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Applies a caller's version filter to a range, naming which of its versions
+  # count as selected mutations. The unfiltered versions stay available to the
+  # caller, because the one that reveals the last selected mutation is drawn
+  # from them.
+  class VersionScopeFilter
+    #: (untyped) -> void
+    def initialize(scope)
+      @scope = validated(scope)
+    end
+
+    #: (untyped, Array[untyped]) -> Array[untyped]
+    def call(relation, in_range)
+      scope = @scope
+      return in_range unless scope
+
+      # A narrowed relation is the expected return. Active Support also gives
+      # `pluck` to plain enumerables, so an array of versions works too.
+      chosen = Set.new(scope.call(relation).pluck(:id))
+      in_range.select { |version| chosen.include?(version.id) }
+    end
+
+    private
+
+    # @rbs @scope: untyped
+
+    #: (untyped) -> untyped
+    def validated(scope)
+      return scope if scope.nil? || scope.respond_to?(:call)
+
+      raise ConfigurationError, 'version_scope: must respond to call'
+    end
+  end
+end