paper_trail_diff 0.9.0 → 0.11.0

data/lib/paper_trail_diff/nested_comparator.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'json'
+
+module PaperTrailDiff
+  # Compares the inside of a value a database column holds whole.
+  #
+  # A JSON or jsonb column reifies to one Hash, so an ordinary attribute diff
+  # can only say that the blob changed. This says which keys changed, leaving
+  # the surrounding diff untouched.
+  #
+  # Three decisions worth knowing about.
+  #
+  # Paths are arrays, not dotted strings. A JSON key may contain a dot -- host
+  # names and locales routinely do -- and joining would make `a.b` ambiguous
+  # between one key and two.
+  #
+  # Arrays are leaves. Their elements carry no identity, so an insertion at the
+  # front makes every later index look changed; reporting "element 2 changed"
+  # would be confidently wrong about a list that merely shifted. The whole array
+  # is reported as one change, which is the same rule the collection comparator
+  # follows for records it cannot identify.
+  #
+  # An absent key is not a null one. `{"a": null}` and `{}` mean different
+  # things in JSON and an audit trail that conflated them would be lying about
+  # one of them, so absence is its own value rather than nil.
+  class NestedComparator
+    # Stands in for a key that was not there at all.
+    ABSENT = Object.new
+    def ABSENT.inspect = '#<PaperTrailDiff absent>'
+    def ABSENT.to_s = 'absent'
+    ABSENT.freeze
+
+    #: (untyped, untyped) -> Hash[Array[String], ValueChange]
+    def self.call(from_value, to_value)
+      new(from_value, to_value).call
+    end
+
+    #: (untyped, untyped) -> void
+    def initialize(from_value, to_value)
+      @from_value = from_value
+      @to_value = to_value
+    end
+
+    # Returns the changed paths, or an empty hash when the pair is not two
+    # structures this can look inside. An empty result therefore means "nothing
+    # to report at this depth", and the caller still has the whole-value change.
+    #: () -> Hash[Array[String], ValueChange]
+    def call
+      from_structure, to_structure = structures
+      return {} unless from_structure && to_structure
+
+      changes = {} #: Hash[Array[String], ValueChange]
+      walk(from_structure, to_structure, [], changes)
+      changes.freeze
+    end
+
+    private
+
+    # @rbs @from_value: untyped
+    # @rbs @to_value: untyped
+
+    # Both sides have to be readable as a Hash for a nested answer to mean
+    # anything. A column that held text on one side and JSON on the other
+    # changed wholesale, and saying so is the accurate report.
+    #: () -> [Hash[untyped, untyped]?, Hash[untyped, untyped]?]
+    def structures
+      [structure(@from_value), structure(@to_value)]
+    end
+
+    #: (untyped) -> Hash[untyped, untyped]?
+    def structure(value)
+      return value if value.is_a?(Hash)
+      return unless value.is_a?(String)
+
+      parsed = begin
+        JSON.parse(value)
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+      parsed if parsed.is_a?(Hash)
+    end
+
+    #: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], Hash[Array[String], ValueChange]) -> void
+    def walk(from_hash, to_hash, path, changes)
+      keys(from_hash, to_hash).each do |key|
+        from_item = from_hash.key?(key) ? from_hash[key] : ABSENT
+        to_item = to_hash.key?(key) ? to_hash[key] : ABSENT
+        next if from_item == to_item
+
+        here = [*path, key.to_s]
+        if from_item.is_a?(Hash) && to_item.is_a?(Hash)
+          walk(from_item, to_item, here, changes)
+        else
+          changes[here.freeze] = ValueChange.new(from: from_item, to: to_item)
+        end
+      end
+    end
+
+    # Sorted so a report reads the same twice, and stringified because a hash
+    # loaded from JSON and one built in Ruby can key the same field differently.
+    #: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[untyped]
+    def keys(from_hash, to_hash)
+      (from_hash.keys | to_hash.keys).sort_by(&:to_s)
+    end
+  end
+end

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -68,8 +68,8 @@ module PaperTrailDiff
       ).build
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:, within:, version_scope: nil, close_on: nil, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
+    def activity_timeline(record, from:, to:, within:, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       payload = @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
       Instrumentation.instrument('activity_timeline', payload) do
         @traversal_preparer.call(record.class, historical: true)
@@ -77,21 +77,21 @@ module PaperTrailDiff
         reject_live_habtm_activity!(record.class) if Endpoint.record?(to) || live
         steps = activity_builder(
           record, from: from, to: to, within: within, version_scope: version_scope,
-                  live_endpoint: live, snapshots: snapshots
+                  live_endpoint: live, snapshots: snapshots, group: group
         ).build
         payload[:step_count] = steps.length
         steps
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
-    def analyze(record, from:, to:, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
+    def analyze(record, from:, to:, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       @traversal_preparer.call(record.class, historical: true)
       live = live_endpoint_for(record, close_on, within)
       if activity
         return analyze_activity(
           record, from: from, to: to, within: within, version_scope: version_scope,
-                  live_endpoint: live, snapshots: snapshots
+                  live_endpoint: live, snapshots: snapshots, group: group
         )
       end
 
@@ -119,6 +119,24 @@ module PaperTrailDiff
       end
     end
 
+    # Selects the roots from a relation before running the ordinary batch, so a
+    # caller reporting on a population does not have to rediscover which of its
+    # members changed. The roots the relation could not reach come back named
+    # rather than dropped -- see `PaperTrailDiff.analyze_scope`.
+    #: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
+    def analyze_scope(scope, limit:, within:, activity: false, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
+      raise ConfigurationError, 'limit: is required when selecting roots by scope' if limit.nil?
+
+      selection = ScopedRootSelection.new(
+        scope, time_range: within.nil? ? nil : TimeRange.new(within), limit: limit
+      ).call
+      ScopedAnalysis.new(
+        analyses: analyze_many(selection.records, within: within, activity: activity,
+                                                  version_scope: version_scope, close_on: close_on),
+        unreachable: selection.unreachable
+      )
+    end
+
     private
 
     # @rbs @association_tree: AssociationTree
@@ -133,12 +151,12 @@ module PaperTrailDiff
     # @rbs @timeline_snapshotter: TimelineSnapshotProvider
     # @rbs @activity_snapshotter: ActivitySnapshotProvider
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool) -> Analysis
-    def analyze_activity(record, from:, to:, within:, version_scope:, live_endpoint:, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
+    def analyze_activity(record, from:, to:, within:, version_scope:, live_endpoint:, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       reject_live_habtm_activity!(record.class) if live_endpoint
       activity_builder(
         record, from: from, to: to, within: within, version_scope: version_scope,
-                live_endpoint: live_endpoint, snapshots: snapshots
+                live_endpoint: live_endpoint, snapshots: snapshots, group: group
       ).analyze
     end
 
@@ -234,8 +252,8 @@ module PaperTrailDiff
       )
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool) -> ActivityTimelineBuilder
-    def activity_builder(record, from:, to:, within:, version_scope: nil, live_endpoint: nil, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
+    def activity_builder(record, from:, to:, within:, version_scope: nil, live_endpoint: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       ActivityTimelineBuilder.new(
         record,
         range: TimelineRange.new(
@@ -244,7 +262,8 @@ module PaperTrailDiff
         ),
         tree: @association_tree,
         snapshotter: @activity_snapshotter,
-        snapshots: snapshots
+        snapshots: snapshots,
+        group: group
       )
     end
 

data/lib/paper_trail_diff/prepared_history_loader.rb

@@ -129,7 +129,7 @@ module PaperTrailDiff
 
     #: (untyped) -> bool
     def versioned?(model_class)
-      model_class.respond_to?(:paper_trail)
+      Support.versioned?(model_class)
     end
 
     #: (untyped, untyped) -> Array[String]

data/lib/paper_trail_diff/scoped_analysis.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # What the relation form of `analyze_many` returns: the analyses, plus the
+  # roots the relation could not reach.
+  #
+  # `to_ary` is defined so the pair destructures, which keeps the common case
+  # reading like the plain Hash the record form returns:
+  #
+  #   analyses, unreachable = PaperTrailDiff.analyze_many(scope: ..., limit: 500)
+  #
+  # It deliberately does not pretend to be a Hash beyond that. Somebody
+  # iterating this object should have to decide which half they meant.
+  class ScopedAnalysis
+    attr_reader :analyses #: Hash[Array[String], Analysis]
+    attr_reader :unreachable #: Array[Array[String]]
+
+    #: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]]) -> void
+    def initialize(analyses:, unreachable:)
+      @analyses = analyses
+      @unreachable = Support.immutable_copy(unreachable)
+      freeze
+    end
+
+    #: () -> [Hash[Array[String], Analysis], Array[Array[String]]]
+    def to_ary
+      [analyses, unreachable]
+    end
+  end
+end

data/lib/paper_trail_diff/scoped_root_selection.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Chooses the roots a batch will analyze from a relation instead of from an
+  # array the caller assembled, so a reporting page does not reimplement the
+  # root selection this gem already performs.
+  #
+  # Two populations are deliberately kept apart, because conflating them would
+  # make the report wrong in a way nothing announces:
+  #
+  # - A root whose live row does not satisfy the relation is filtered out. That
+  #   is what the caller asked for, and it needs no reporting.
+  # - A root whose live row is gone cannot be filtered at all. The relation's
+  #   conditions read the live table, and a destroyed root has nothing there to
+  #   read -- even though its history is intact, and the state it held when it
+  #   was destroyed may well have satisfied those conditions. Reifying every
+  #   candidate to find out would cost the batched query plan this class exists
+  #   to provide.
+  #
+  # So the second population is returned by name rather than dropped. A caller
+  # that does not care can ignore it; one auditing deletions is told where to
+  # look instead of silently coming up short.
+  #
+  # Note that a relation filters on current state, not on state during the
+  # window. `where(status: 'published')` selects what is published now, which is
+  # not the same set as what was published while the window was open.
+  class ScopedRootSelection
+    # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
+    # gem supports 3.1.
+    class Result
+      attr_reader :records #: Array[untyped]
+      attr_reader :unreachable #: Array[Array[String]]
+
+      #: (records: Array[untyped], unreachable: Array[Array[String]]) -> void
+      def initialize(records:, unreachable:)
+        @records = records
+        @unreachable = unreachable
+        freeze
+      end
+    end
+
+    #: (untyped, time_range: TimeRange?, limit: Integer) -> void
+    def initialize(scope, time_range:, limit:)
+      @scope = normalize_scope(scope)
+      @time_range = time_range
+      @limit = validate_limit(limit)
+    end
+
+    #: () -> Result
+    def call
+      candidates = versioned_ids
+      return Result.new(records: [], unreachable: []) if candidates.empty?
+
+      live = live_ids(candidates)
+      Result.new(
+        records: selected_records(live),
+        unreachable: (candidates - live).map { |id| identity(id) }.freeze
+      )
+    end
+
+    private
+
+    # @rbs @scope: untyped
+    # @rbs @time_range: TimeRange?
+    # @rbs @limit: Integer
+
+    # Accepts a model class as readily as a relation: `Article` and
+    # `Article.where(...)` both name a population, and `all` is what makes them
+    # the same kind of thing.
+    #: (untyped) -> untyped
+    def normalize_scope(scope)
+      unless scope.respond_to?(:all) && scope.respond_to?(:where)
+        raise ConfigurationError, 'scope: must be an ActiveRecord relation or model class'
+      end
+
+      relation = scope.all
+      return relation if Support.versioned?(relation.model)
+
+      raise UnversionedAssociationError,
+            "scope: #{relation.model.name} is not versioned, so it has no history to select from"
+    end
+
+    #: (Integer) -> Integer
+    def validate_limit(limit)
+      return limit if limit.is_a?(Integer) && limit.positive?
+
+      raise ConfigurationError, 'limit: must be a positive Integer'
+    end
+
+    # Every root whose history moved inside the window, destroyed ones included.
+    # This is the gem's own notion of "which roots changed", answered from the
+    # version table alone so that it does not depend on rows still existing.
+    #: () -> Array[String]
+    def versioned_ids
+      relation = version_class.where(item_type: item_type)
+      range = @time_range
+      relation = range.scope(relation) if range
+      relation.distinct.pluck(:item_id).map(&:to_s).uniq
+    end
+
+    # Which of those candidates still have a row, asked without the relation's
+    # conditions so that "filtered out" and "no longer exists" stay separable.
+    #: (Array[String]) -> Array[String]
+    def live_ids(candidates)
+      base_class.unscoped.where(primary_key => candidates).pluck(primary_key).map(&:to_s)
+    end
+
+    # Loading one past the limit is what turns an oversized page into an error
+    # rather than a silently truncated report.
+    #: (Array[String]) -> Array[untyped]
+    def selected_records(live)
+      return [] if live.empty?
+
+      records = @scope.where(primary_key => live).limit(@limit + 1).to_a
+      return records.freeze unless records.length > @limit
+
+      raise BatchLimitExceededError,
+            "scope: selected more than #{@limit} roots; narrow the window or the " \
+            'relation, or raise limit: to the page size you intend to analyze'
+    end
+
+    #: (String) -> Array[String]
+    def identity(id)
+      [item_type, id].freeze
+    end
+
+    #: () -> String
+    def item_type
+      base_class.name.to_s
+    end
+
+    #: () -> untyped
+    def base_class
+      @scope.model.base_class
+    end
+
+    #: () -> untyped
+    def primary_key
+      @scope.model.primary_key
+    end
+
+    #: () -> untyped
+    def version_class
+      @scope.model.paper_trail.version_class
+    end
+  end
+end

data/lib/paper_trail_diff/support.rb

@@ -81,6 +81,19 @@ module PaperTrailDiff
       versions.each_cons(2).find { |left, right| left.created_at == right.created_at }
     end
 
+    # Whether a model records history at all.
+    #
+    # PaperTrail defines `paper_trail` on every ActiveRecord model, so asking
+    # whether a class responds to it says nothing -- it is true for models that
+    # never called `has_paper_trail`, and reading history from one of those fails
+    # at the version class rather than at the question. Only configured options
+    # distinguish the two, which is why this lives in one place: the predicate is
+    # easy to write in a form that looks right and always answers true.
+    #: (untyped) -> bool
+    def versioned?(model_class)
+      model_class.respond_to?(:paper_trail_options) && !model_class.paper_trail_options.nil?
+    end
+
     #: (untyped) -> bool
     def sequential_id?(id)
       id.is_a?(Integer) || id.to_s.match?(/\A\d+\z/)

data/lib/paper_trail_diff/time_activity_timeline_builder.rb

@@ -4,9 +4,15 @@
 module PaperTrailDiff
   # Builds activity views for mutations selected by a wall-clock range.
   class TimeActivityTimelineBuilder
-    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
-    def initialize(record, range:, tree:, snapshotter:, snapshots: false)
+    include ActivityGrouping
+
+    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
+    def initialize(record, range:, tree:, snapshotter:, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists
       @snapshots = snapshots
+      @group = group
+      # Merging a group compares its outer states, so the snapshots must survive
+      # the build even when the caller did not ask to keep them.
+      @retain = snapshots || grouping?
       @record = record
       @range = range
       @tree = tree
@@ -92,15 +98,14 @@ module PaperTrailDiff
         events,
         @snapshotter,
         include_step: ->(event) { @range.include?(event.version) },
-        snapshots: @snapshots
+        snapshots: @retain
       ).call
     end
 
     #: (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
     def activity_steps(history, closing)
-      return history.steps unless closing
-
-      (history.steps + [closing]).freeze
+      steps = closing ? history.steps + [closing] : history.steps
+      group_steps(steps).freeze
     end
 
     # Root versions inside the window that the plan does not report are context
@@ -136,7 +141,7 @@ module PaperTrailDiff
         from_boundary: ActivityBoundary.from_version(version),
         to_boundary: ActivityBoundary.destroyed(version),
         from_snapshot: history.root_snapshots[ActivityRootSteps.version_key(version)],
-        to_snapshot: nil, retain: @snapshots
+        to_snapshot: nil, retain: @retain
       )
     end
 
@@ -151,7 +156,7 @@ module PaperTrailDiff
       ActivityStep.between(
         from_boundary: previous,
         to_boundary: ActivityBoundary.current(record, captured_at: captured_at),
-        from_snapshot: history.last_snapshot, to_snapshot: snapshot, retain: @snapshots
+        from_snapshot: history.last_snapshot, to_snapshot: snapshot, retain: @retain
       )
     end
 

data/lib/paper_trail_diff/traversal_preparer.rb

@@ -17,6 +17,7 @@ module PaperTrailDiff
 
       ensure_association_tracking! if historical
       @traversal.validate!(model_class)
+      ensure_versioned_targets!(model_class) if historical
     end
 
     private
@@ -24,6 +25,30 @@ module PaperTrailDiff
     # @rbs @tree: AssociationTree
     # @rbs @traversal: AssociationTraversal
 
+    # A model PaperTrail never versioned has no history to reconstruct, so a
+    # comparison over it can only ever answer "nothing changed" -- which is a
+    # wrong answer rather than an empty one. Live-to-live comparison reads
+    # current state and is unaffected, so this applies to historical work only.
+    #: (untyped) -> void
+    def ensure_versioned_targets!(model_class)
+      @traversal.selected_reflections(model_class).each do |path, reflection|
+        # A polymorphic target is not known until a row names it; `diagnose`
+        # reports that separately rather than guessing here.
+        next if reflection.polymorphic?
+        next if versioned?(reflection.klass)
+
+        raise UnversionedAssociationError,
+              "association #{path} cannot be compared historically: " \
+              "#{reflection.klass.name} is not versioned. Add `has_paper_trail` to it, " \
+              'or mirror the fields you need onto a model that has it.'
+      end
+    end
+
+    #: (untyped) -> bool
+    def versioned?(model_class)
+      Support.versioned?(model_class)
+    end
+
     #: () -> void
     def ensure_association_tracking!
       paper_trail = Object.const_get(:PaperTrail) #: untyped

data/lib/paper_trail_diff/version.rb

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