paper_trail_diff 0.10.0 → 0.12.0

data/sig/generated/paper_trail_diff/activity_grouping.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/paper_trail_diff/activity_grouping.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Shared by the two activity builders. They differ in how they choose
+  # boundaries -- one from an explicit version range, one from a wall-clock
+  # window -- but a transaction has to collapse the same way in both, or the
+  # same history would read differently depending on how it was asked for.
+  module ActivityGrouping
+    private
+
+    # : () -> bool
+    def grouping?: () -> bool
+
+    # Applied last, to finished steps, so grouping sees the same timeline the
+    # caller would otherwise have received.
+    # : (Array[ActivityStep]) -> Array[ActivityStep]
+    def group_steps: (Array[ActivityStep]) -> Array[ActivityStep]
+  end
+end

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -3,8 +3,10 @@
 module PaperTrailDiff
   # Compares adjacent root and selected-descendant activity boundaries.
   class ActivityTimelineBuilder
-    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
-    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
+    include ActivityGrouping
+
+    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
+    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
 
     # : () -> Array[ActivityStep]
     def build: () -> Array[ActivityStep]

data/sig/generated/paper_trail_diff/activity_transaction_grouper.rbs

@@ -0,0 +1,54 @@
+# Generated from lib/paper_trail_diff/activity_transaction_grouper.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Reports one saved transaction as one activity step.
+  #
+  # A parent and its children saved together produce a version each, and the
+  # timeline reports the gap between every pair of them. One deliberate action
+  # therefore arrives as several steps, none of which is the thing the person
+  # did.
+  #
+  # A version records the state before its own event. Two things follow.
+  #
+  # The change a step reports was made by the event that *opens* it, so a step
+  # belongs to the transaction of its `from_boundary`, and consecutive steps
+  # sharing one are the parts of a single save. Grouping on the closing boundary
+  # instead would credit each change to whoever made the next one.
+  #
+  # And a child's new value is revealed only by something later -- a further
+  # version of that child, its destroy version, or the live row. Inside a
+  # transaction there is usually none of those yet, so a step can read as empty
+  # while a change was in fact made at that boundary, and the change surfaces
+  # later, folded in with whatever that step carried. Grouping puts it back
+  # together with the save it belongs to.
+  #
+  # Merging compares the group's outer snapshots rather than combining the
+  # diffs between them. A field set and then restored inside one transaction
+  # has not changed, and only a comparison of the endpoints can say so.
+  #
+  # A boundary with no transaction groups with nothing. PaperTrail leaves the
+  # column nil outside a transaction, and a custom version class need not carry
+  # it at all; treating those as one shared transaction would merge unrelated
+  # history into a single step.
+  class ActivityTransactionGrouper
+    # : (Array[ActivityStep], retain: bool) -> void
+    def initialize: (Array[ActivityStep], retain: bool) -> void
+
+    # : () -> Array[ActivityStep]
+    def call: () -> Array[ActivityStep]
+
+    private
+
+    @retain: bool
+
+    @steps: Array[ActivityStep]
+
+    # : (Array[ActivityStep], ActivityStep) -> bool
+    def continues?: (Array[ActivityStep], ActivityStep) -> bool
+
+    # Rebuilt rather than reused even when a group holds one step, so that every
+    # returned step retains its snapshots on the same terms.
+    # : (Array[ActivityStep]) -> ActivityStep
+    def merge: (Array[ActivityStep]) -> ActivityStep
+  end
+end

data/sig/generated/paper_trail_diff/errors.rbs

@@ -41,6 +41,11 @@ module PaperTrailDiff
   class AmbiguousVersionOrderError < Error
   end
 
+  # Raised when a relation selects more roots than the batch was told to analyze.
+  # Truncating instead would hand back a report that is short without saying so.
+  class BatchLimitExceededError < Error
+  end
+
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error
   end

data/sig/generated/paper_trail_diff/nested_comparator.rbs

@@ -0,0 +1,73 @@
+# Generated from lib/paper_trail_diff/nested_comparator.rb with RBS::Inline
+
+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 reported by membership, not by position -- see ArrayChange. Their
+  # elements carry no identity, so an insertion at the front makes every later
+  # index look changed, and one insertion reads as several edits. What is added
+  # and removed can be answered without claiming any pairing; what cannot is the
+  # same elements in a new order, so that is named rather than passed over.
+  #
+  # 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: untyped
+
+    def inspect: () -> untyped
+
+    def to_s: () -> untyped
+
+    # : (untyped, untyped) -> nested_changes
+    def self.call: (untyped, untyped) -> nested_changes
+
+    # : (untyped, untyped) -> void
+    def initialize: (untyped, untyped) -> void
+
+    # 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.
+    # : () -> nested_changes
+    def call: () -> nested_changes
+
+    private
+
+    @from_value: untyped
+
+    @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: () -> [ Hash[untyped, untyped]?, Hash[untyped, untyped]? ]
+
+    # : (untyped) -> Hash[untyped, untyped]?
+    def structure: (untyped) -> Hash[untyped, untyped]?
+
+    # : (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
+    def walk: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
+
+    # Two arrays are a membership change; anything else is a change to the
+    # value as a whole, including an array facing something that is not one.
+    # : (untyped, untyped) -> nested_change
+    def change_for: (untyped, untyped) -> nested_change
+
+    # 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: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[untyped]
+  end
+end

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -22,16 +22,23 @@ module PaperTrailDiff
     # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
     def timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
-    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
+    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
-    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
+    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
 
     # Analyzes many roots over one shared range, preparing their history once.
     # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
     def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
 
+    # 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: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
+
     private
 
     @activity_snapshotter: ActivitySnapshotProvider
@@ -56,8 +63,8 @@ module PaperTrailDiff
 
     @traversal_preparer: TraversalPreparer
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool) -> Analysis
-    def analyze_activity: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool) -> Analysis
+    # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
+    def analyze_activity: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
 
     # Association membership is resolved by timestamp, so endpoints sharing one
     # cannot be told apart and any association change between them is invisible.
@@ -89,8 +96,8 @@ module PaperTrailDiff
     # : () -> ActivitySnapshotProvider
     def build_activity_snapshotter: () -> ActivitySnapshotProvider
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool) -> ActivityTimelineBuilder
-    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool) -> ActivityTimelineBuilder
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
+    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
 
     # : (untyped) -> void
     def reject_live_habtm_activity!: (untyped) -> void

data/sig/generated/paper_trail_diff/scoped_analysis.rbs

@@ -0,0 +1,25 @@
+# Generated from lib/paper_trail_diff/scoped_analysis.rb with RBS::Inline
+
+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: Hash[Array[String], Analysis], unreachable: Array[Array[String]]) -> void
+
+    # : () -> [Hash[Array[String], Analysis], Array[Array[String]]]
+    def to_ary: () -> [ Hash[Array[String], Analysis], Array[Array[String]] ]
+  end
+end

data/sig/generated/paper_trail_diff/scoped_root_selection.rbs

@@ -0,0 +1,93 @@
+# Generated from lib/paper_trail_diff/scoped_root_selection.rb with RBS::Inline
+
+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: Array[untyped], unreachable: Array[Array[String]]) -> void
+    end
+
+    # : (untyped, time_range: TimeRange?, limit: Integer) -> void
+    def initialize: (untyped, time_range: TimeRange?, limit: Integer) -> void
+
+    # : () -> Result
+    def call: () -> Result
+
+    private
+
+    @limit: Integer
+
+    @scope: untyped
+
+    @time_range: TimeRange?
+
+    # 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: (untyped) -> untyped
+
+    # : (Integer) -> Integer
+    def validate_limit: (Integer) -> Integer
+
+    # 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: () -> Array[String]
+
+    # 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: (Array[String]) -> Array[String]
+
+    # 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: (Array[String]) -> Array[untyped]
+
+    # : (String) -> Array[String]
+    def identity: (String) -> Array[String]
+
+    # : () -> String
+    def item_type: () -> String
+
+    # : () -> untyped
+    def base_class: () -> untyped
+
+    # : () -> untyped
+    def primary_key: () -> untyped
+
+    # : () -> untyped
+    def version_class: () -> untyped
+  end
+end

data/sig/generated/paper_trail_diff/support.rbs

@@ -32,6 +32,17 @@ module PaperTrailDiff
     # : (Array[untyped]) -> Array[untyped]?
     def self?.tied_timestamp_pair: (Array[untyped]) -> Array[untyped]?
 
+    # 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 self?.versioned?: (untyped) -> bool
+
     # : (untyped) -> bool
     def self?.sequential_id?: (untyped) -> bool
 

data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs

@@ -3,8 +3,10 @@
 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: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
+    include ActivityGrouping
+
+    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
+    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
 
     # : () -> Array[ActivityStep]
     def build: () -> Array[ActivityStep]

data/sig/generated/paper_trail_diff/value_objects.rbs

@@ -14,6 +14,51 @@ module PaperTrailDiff
     def to_h: () -> Hash[Symbol, untyped]
   end
 
+  # A change to an array inside a value the database stores whole, reported by
+  # membership rather than by position.
+  #
+  # Position would be the obvious thing to report and the wrong one: elements
+  # here carry no identity, so inserting at the front makes every later index
+  # look changed, and one insertion is described as several edits. Membership is
+  # answerable without claiming any pairing -- "gained \"saturn v\"" is true
+  # whether the array is a set, a queue, or a ranked list.
+  #
+  # That leaves one case membership cannot see, so it is named rather than
+  # hidden: the same elements in a different order. `reordered?` says so.
+  #
+  # An element that is itself a Hash or Array is reported whole. Saying which
+  # field of which object changed would require pairing before-elements with
+  # after-elements, and nothing in the value licenses that pairing.
+  class ArrayChange
+    attr_reader from: Array[untyped]
+
+    attr_reader to: Array[untyped]
+
+    attr_reader added: Array[untyped]
+
+    attr_reader removed: Array[untyped]
+
+    # : (from: Array[untyped], to: Array[untyped]) -> void
+    def initialize: (from: Array[untyped], to: Array[untyped]) -> void
+
+    # Elements of `left` with no counterpart left in `right`, matching by value
+    # and respecting duplicates, so ["a", "a"] -> ["a"] reports one removal
+    # rather than none.
+    # : (Array[untyped], Array[untyped]) -> Array[untyped]
+    def self.surplus: (Array[untyped], Array[untyped]) -> Array[untyped]
+
+    # Same elements, different sequence. Only meaningful for a change that was
+    # recorded at all, which this only is when the two sides differ.
+    # : () -> bool
+    def reordered?: () -> bool
+
+    # : () -> bool
+    def empty?: () -> bool
+
+    # : () -> Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
   # Attribute and nested-association changes for a record whose identity did not change.
   class RecordChange
     attr_reader record: RecordReference

data/sig/generated/paper_trail_diff.rbs

@@ -27,14 +27,47 @@ module PaperTrailDiff
   def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
 
   # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
-  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
-  def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
+  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
+  def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
 
   # Analyzes many roots over one shared time window, preparing their selected
   # history once for the batch instead of once per record. Roots with no
   # versions in the window return an empty `Analysis`.
-  # : (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
-  def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
+  #
+  # Pass `records` to analyze a list you assembled, which returns a Hash keyed
+  # by identity. Pass `scope:` with a `limit:` to have the roots selected for
+  # you from a relation, which returns a `ScopedAnalysis` -- the same Hash,
+  # plus the roots the relation could not reach. See `analyze_scope` for why
+  # that second collection exists.
+  # : (?Array[untyped]?, ?scope: untyped, ?limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> (Hash[identity, Analysis] | ScopedAnalysis)
+  def self.analyze_many: (?Array[untyped]?, ?scope: untyped, ?limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> (Hash[identity, Analysis] | ScopedAnalysis)
+
+  # Analyzes every root the relation reaches whose history moved inside the
+  # window, selecting them in a fixed number of queries rather than making the
+  # caller rediscover them.
+  #
+  # `limit:` is required and exceeding it raises. Selection moves into the gem
+  # here, so the bound on how much work a page can ask for has to move with
+  # it, and a truncated audit report is worse than a refused one.
+  #
+  # Returns a `ScopedAnalysis`, which destructures:
+  #
+  #   analyses, unreachable = PaperTrailDiff.analyze_scope(
+  #     Article.where(status: 'published'), within: july, limit: 500
+  #   )
+  #
+  # `unreachable` names roots that changed in the window but have no live row
+  # left. A relation's conditions are evaluated against the live table, so a
+  # destroyed root cannot be tested against them at all -- its history is
+  # intact and the state it held at destruction may well have matched. Those
+  # roots are reported rather than dropped so that a page auditing deletions
+  # is told where to look instead of quietly coming up short.
+  #
+  # Note also that a relation selects on current state, not on state during
+  # the window: `where(status: 'published')` means published *now*, which is a
+  # different set from what was published while the window was open.
+  # : (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
+  def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
 
   # Returns the association macros this release can normalize.
   # : () -> Array[Symbol]
@@ -47,6 +80,27 @@ module PaperTrailDiff
   # Reports known reconstruction hazards without mutating application state.
   # : (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
   def self.diagnose: (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
+
+  # Looks inside an attribute the database stores whole, such as a JSON or
+  # jsonb column, and reports which keys changed.
+  #
+  #   change = diff.attributes.fetch('config')
+  #   PaperTrailDiff.nested_changes(change)
+  #   # => { ['theme'] => <from "dark" to "light">,
+  #   #      ['limits', 'max'] => <from 10 to 20> }
+  #
+  # Accepts the `ValueChange` an attribute diff already produced, or a bare
+  # pair. Returns an empty hash when the pair is not two readable structures,
+  # which is the honest answer: a column that held text on one side and JSON
+  # on the other changed wholesale, and the caller still has that change.
+  #
+  # Paths are arrays because a JSON key may contain a dot. Arrays are reported
+  # whole rather than by index, since their elements carry no identity and a
+  # list that merely shifted would otherwise look changed throughout. A key
+  # that was absent reads as `NestedComparator::ABSENT` rather than nil, which
+  # JSON uses for a present null.
+  # : (untyped, ?untyped) -> nested_changes
+  def self.nested_changes: (untyped, ?untyped) -> nested_changes
 end
 
 module PaperTrailDiff
@@ -60,6 +114,10 @@ module PaperTrailDiff
 
   type association_diffs = Hash[String, association_diff]
 
+  type nested_change = ValueChange | ArrayChange
+
+  type nested_changes = Hash[Array[String], nested_change]
+
   type association_snapshots = Hash[String, AssociationSnapshot]
 
   type identity = Array[untyped]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail_diff
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Alex Williams
@@ -55,6 +55,7 @@ files:
 - lib/paper_trail_diff/activity_event_record_resolver.rb
 - lib/paper_trail_diff/activity_event_route_finder.rb
 - lib/paper_trail_diff/activity_event_snapshot_refresher.rb
+- lib/paper_trail_diff/activity_grouping.rb
 - lib/paper_trail_diff/activity_history.rb
 - lib/paper_trail_diff/activity_range.rb
 - lib/paper_trail_diff/activity_relationship.rb
@@ -63,6 +64,7 @@ files:
 - lib/paper_trail_diff/activity_snapshot_delta.rb
 - lib/paper_trail_diff/activity_snapshot_sequence.rb
 - lib/paper_trail_diff/activity_timeline_builder.rb
+- lib/paper_trail_diff/activity_transaction_grouper.rb
 - lib/paper_trail_diff/activity_version_collector.rb
 - lib/paper_trail_diff/analysis.rb
 - lib/paper_trail_diff/analysis_batch.rb
@@ -89,6 +91,7 @@ files:
 - lib/paper_trail_diff/live_endpoint_batch_loader.rb
 - lib/paper_trail_diff/live_endpoint_provider.rb
 - lib/paper_trail_diff/live_graph_collector.rb
+- lib/paper_trail_diff/nested_comparator.rb
 - lib/paper_trail_diff/paper_trail_adapter.rb
 - lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb
 - lib/paper_trail_diff/prepared_association_reifier.rb
@@ -98,6 +101,8 @@ files:
 - lib/paper_trail_diff/prepared_record_index.rb
 - lib/paper_trail_diff/root_version_plan.rb
 - lib/paper_trail_diff/root_version_selection.rb
+- lib/paper_trail_diff/scoped_analysis.rb
+- lib/paper_trail_diff/scoped_root_selection.rb
 - lib/paper_trail_diff/snapshot.rb
 - lib/paper_trail_diff/snapshot_normalizer.rb
 - lib/paper_trail_diff/snapshot_traversal.rb
@@ -132,6 +137,7 @@ files:
 - sig/generated/paper_trail_diff/activity_event_record_resolver.rbs
 - sig/generated/paper_trail_diff/activity_event_route_finder.rbs
 - sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs
+- sig/generated/paper_trail_diff/activity_grouping.rbs
 - sig/generated/paper_trail_diff/activity_history.rbs
 - sig/generated/paper_trail_diff/activity_range.rbs
 - sig/generated/paper_trail_diff/activity_relationship.rbs
@@ -140,6 +146,7 @@ files:
 - sig/generated/paper_trail_diff/activity_snapshot_delta.rbs
 - sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs
 - sig/generated/paper_trail_diff/activity_timeline_builder.rbs
+- sig/generated/paper_trail_diff/activity_transaction_grouper.rbs
 - sig/generated/paper_trail_diff/activity_version_collector.rbs
 - sig/generated/paper_trail_diff/analysis.rbs
 - sig/generated/paper_trail_diff/analysis_batch.rbs
@@ -166,6 +173,7 @@ files:
 - sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs
 - sig/generated/paper_trail_diff/live_endpoint_provider.rbs
 - sig/generated/paper_trail_diff/live_graph_collector.rbs
+- sig/generated/paper_trail_diff/nested_comparator.rbs
 - sig/generated/paper_trail_diff/paper_trail_adapter.rbs
 - sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs
 - sig/generated/paper_trail_diff/prepared_association_reifier.rbs
@@ -175,6 +183,8 @@ files:
 - sig/generated/paper_trail_diff/prepared_record_index.rbs
 - sig/generated/paper_trail_diff/root_version_plan.rbs
 - sig/generated/paper_trail_diff/root_version_selection.rbs
+- sig/generated/paper_trail_diff/scoped_analysis.rbs
+- sig/generated/paper_trail_diff/scoped_root_selection.rbs
 - sig/generated/paper_trail_diff/snapshot.rbs
 - sig/generated/paper_trail_diff/snapshot_normalizer.rbs
 - sig/generated/paper_trail_diff/snapshot_traversal.rbs
@@ -202,11 +212,11 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   bug_tracker_uri: https://github.com/aheathwilliams/paper_trail_diff/issues
-  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.10.0/CHANGELOG.md
-  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.10.0/README.md
+  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.12.0/CHANGELOG.md
+  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.12.0/README.md
   homepage_uri: https://github.com/aheathwilliams/paper_trail_diff
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.10.0
+  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.12.0
 rdoc_options: []
 require_paths:
 - lib