paper_trail_diff 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ee80500dbeb48421e7b0e0766a5f5559b73aa71528360a5f1a16866f9e6ccfa
-  data.tar.gz: 6692d3fd2d725918e16da15b4d39312b5e1a42deba3aa8e50a269abfd9fc6bd9
+  metadata.gz: 205c52c1f80517b072fa68452447963c3d7245ba0707b049d5ebd5d2528727b3
+  data.tar.gz: 65cc6e544662366fc185719a3660b29c3a9796f7c003fe7eeff4c551c9114c11
 SHA512:
-  metadata.gz: f809075c65c923ca0dd828e8337477d8461dfa13b2de537a9f99548f0826f867379a33c8bf4a5061476dabd1685829adc5ab21e07052a4d40ebfff4736a44946
-  data.tar.gz: 6212fab6601c900b2701a9401e7e9b66c5236f12da0340788f0641efef759340a29ea6f95e7b51d86c2792d847f5553db8f30d7c96e4370e37ceec0b8a227656
+  metadata.gz: 78c62fcbc641a5f2dd029e69bf656453612a6f2768b1e3268048a13ea9fb4d17ff934048e36cb0798ae3d37aa3102f3c39ef289effdd2f96087796636e1ac921
+  data.tar.gz: 3ba0a0592b1dd997c6177f2ad654bc28a93b00aebd5f83720732b7edaf08200c43aae19ac8e6eae2bbe351147343a2a8cf38b6352ca9427a9f2ad35f1be7c36d

data/CHANGELOG.md

@@ -3,6 +3,100 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.11.0] - 2026-08-18
+
+### Added
+
+- Add `PaperTrailDiff.analyze_scope`, which selects the roots to analyze from an
+  ActiveRecord relation or model class instead of an array the caller assembled,
+  in a fixed number of queries. Also reachable as
+  `PaperTrailDiff.analyze_many(scope: ..., limit: ...)`. Every other option
+  behaves as it does for `analyze_many`.
+- `analyze_scope` returns a `ScopedAnalysis`, which destructures into the usual
+  analyses hash and the roots the relation could not reach. A relation's
+  conditions are evaluated against the live table, so a root destroyed during
+  the window cannot be tested against them at all, even though its history is
+  intact and the state it held at destruction may have matched. Those roots are
+  named rather than dropped, so a page auditing deletions is told where to look
+  instead of coming up short without saying so.
+- Add `PaperTrailDiff.nested_changes`, which reports the keys that changed
+  inside an attribute the database stores whole, such as a JSON or jsonb column
+  or one holding JSON as text. An attribute diff could only say the blob
+  changed, leaving the caller to diff it again by hand. Paths are arrays rather
+  than dotted strings, because a JSON key may itself 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, because
+  `{"a": null}` and `{}` mean different things in JSON and an audit trail that
+  showed them alike would be lying about one of them. Additive: the existing
+  attribute diff is unchanged, and a pair that is not two readable structures
+  reports nothing.
+- Raise `PaperTrailDiff::BatchLimitExceededError` when a relation selects more
+  roots than `limit:` allows. `limit:` is required for `analyze_scope`: root
+  selection moves into the gem, so the bound on how much work one page can ask
+  for moves with it. It refuses rather than truncating, because a report that is
+  quietly short is worse than one that fails.
+- Accept `group: :transaction` on `activity_timeline` and `analyze(activity:
+  true)`, reporting one saved transaction as one step. A parent and its
+  children saved together produce a version each, so one deliberate action
+  arrived as several steps, and some of them read as empty even though a change
+  was made at that boundary: a version records the state before its own event,
+  so a child's new value is revealed only by a later version of that child, its
+  destroy version, or the live row, none of which exists yet inside the
+  transaction. The change therefore surfaced a step or more later, folded in
+  with whatever that step carried. A step belongs to the transaction of the
+  event that opens it, since that is the event whose change it reports; a step
+  therefore belongs to its `from_boundary`'s transaction, and consecutive steps
+  sharing one are the parts of a single save. Merging compares the group's
+  outer states rather than combining the diffs between them, so a field set and
+  restored inside one transaction correctly reports as unchanged. Off by
+  default.
+- Expose `ActivityBoundary#transaction_id`.
+- A boundary that records no transaction groups with nothing. PaperTrail leaves
+  the column nil outside a transaction and a custom version class need not
+  carry it at all, so treating those as one shared transaction would merge
+  unrelated history into a single step.
+
+### Changed
+
+- Check that the generated Appraisal gemfiles match the `Gemfile`, in CI and in
+  `rake release:preflight`. Every other job runs against a generated gemfile, so
+  a dependency changed only in the `Gemfile` was one CI never installed: the
+  jobs passed having exercised the old version.
+
+### Fixed
+
+- Resolve "does this model record history" through one predicate,
+  `Support.versioned?`. Three copies existed and one of them tested only
+  `respond_to?(:paper_trail)`, which PaperTrail defines on every ActiveRecord
+  model and which therefore answers true for models that never called
+  `has_paper_trail`. Nothing reached that copy with an unversioned model, since
+  the traversal preparer rejects those first, so no released behaviour changed --
+  but the check looked right while being unable to fail, and reading history
+  through it would have raised at the version class rather than at the question.
+
+## [0.10.0] - 2026-08-15
+
+### Added
+
+- Add `rake release:preflight`, which runs the full gate and then checks
+  everything that must hold before a tag: a clean working tree, a HEAD that
+  matches its upstream, an unused tag, a dated changelog section for the
+  version, and that the version is not already on RubyGems. It reports and
+  never tags, pushes, or publishes. An unreachable RubyGems is reported as
+  unknown rather than treated as "not published".
+- Raise `PaperTrailDiff::UnversionedAssociationError` when a selected
+  association's target is not versioned and history is being reconstructed.
+  Such a comparison could 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. `diagnose` now reports the same condition as an error
+  rather than a warning, so `ok?` no longer stays true for a comparison that
+  will raise.
+- Document ActiveStorage attachments, which this reaches through:
+  `has_one_attached` points at models Rails owns and PaperTrail never versions,
+  so attachments are audited through a versioned model of your own that mirrors
+  the metadata onto ordinary columns.
+
 ## [0.9.0] - 2026-08-14
 
 ### Added

data/README.md

@@ -152,6 +152,55 @@ that touches a record and its children in quick succession will manage it — so
 this is worth checking before trusting an association history. Recording
 versions at sub-second precision separates them.
 
+### ActiveStorage attachments
+
+`has_one_attached` and `has_many_attached` point at `ActiveStorage::Attachment`
+and `ActiveStorage::Blob`, which Rails owns and PaperTrail does not version.
+There is no history behind them, so a historical comparison over those paths
+raises `PaperTrailDiff::UnversionedAssociationError` rather than reporting that
+nothing changed. Adding `has_paper_trail` to Rails' own models does not rescue
+it either: `has_one_attached` is a scoped `has_one`, and reifying it from
+history is ambiguous.
+
+Audit the attachment through a model you own instead. Give it the facts worth
+auditing as ordinary columns, and version it:
+
+```ruby
+class DocumentRevision < ApplicationRecord
+  belongs_to :attachable, polymorphic: true
+  has_one_attached :file
+  has_paper_trail
+
+  # Attaching a file writes to ActiveStorage's tables, not to this record, so
+  # nothing would be versioned without copying the facts across.
+  after_save :record_file_metadata, if: -> { file.attached? }
+
+  def record_file_metadata
+    blob = file.blob
+    return if filename == blob.filename.to_s && checksum == blob.checksum
+
+    update_columns(
+      filename: blob.filename.to_s, content_type: blob.content_type,
+      byte_size: blob.byte_size, checksum: blob.checksum
+    )
+  end
+end
+```
+
+```ruby
+class Article < ApplicationRecord
+  has_many :document_revisions, as: :attachable
+  has_paper_trail
+end
+
+PaperTrailDiff.compare(before, after, associations: [:document_revisions])
+```
+
+The bytes stay in ActiveStorage; the *auditable facts* live where PaperTrail
+can see them. Nothing about the column names matters to this gem — it reports
+whichever columns changed. What matters is that replacing a file writes to a
+versioned record, because attaching one on its own does not.
+
 ## Choosing an entry point
 
 | You need | Call |
@@ -305,6 +354,47 @@ argument, are loaded per root; other selected branches remain batched. Callers
 should still use an appropriate database transaction when all live queries
 must observe one atomic snapshot.
 
+### Look inside a JSON column
+
+A `json` or `jsonb` column reifies to one Hash, so an attribute diff can only
+say the blob changed. `nested_changes` says which keys changed:
+
+```ruby
+diff = PaperTrailDiff.compare(from_version, to_version)
+
+PaperTrailDiff.nested_changes(diff.attributes.fetch("config"))
+# => { ["theme"]          => <from "dark" to "light">,
+#      ["limits", "max"]  => <from 10 to 20> }
+```
+
+It reads a column that stores JSON as text as readily as a native one, and also
+takes a bare pair: `PaperTrailDiff.nested_changes(from_value, to_value)`.
+
+Nothing about the attribute diff itself changes. A pair that is not two readable
+structures — text on one side and JSON on the other, or a value that does not
+parse — reports nothing, and the caller still has the whole-value change it
+already had.
+
+Three things about the shape are worth knowing:
+
+**Paths are arrays, not dotted strings.** A JSON key may itself contain a dot, so
+`"a.b"` would be ambiguous between one key and two:
+
+```ruby
+PaperTrailDiff.nested_changes({ "a.b" => 1, "a" => { "b" => 1 } },
+                              { "a.b" => 2, "a" => { "b" => 3 } })
+# => { ["a.b"] => <from 1 to 2>, ["a", "b"] => <from 1 to 3> }
+```
+
+**Arrays are reported whole, not by index.** Their elements carry no identity, so
+an insertion at the front would make every later index look changed. This 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 showed them alike would be lying about one of
+them, so a missing key reads as `PaperTrailDiff::NestedComparator::ABSENT`
+rather than `nil`.
+
 ### Reuse already-preloaded current endpoints
 
 `compare`, `compare_many`, and `activity_timeline(..., to: record)` reload
@@ -396,6 +486,54 @@ value is the same `Analysis` that `analyze` returns for one record. A root with
 no versions inside the window gets an empty `Analysis` rather than raising, so a
 listing page needs no special case. Root identities must be unique.
 
+### Letting a relation choose the roots
+
+Assembling that array means querying `versions` for which roots moved, filtering,
+and loading the records — the same selection this gem already performs.
+`analyze_scope` does it for you:
+
+```ruby
+analyses, unreachable = PaperTrailDiff.analyze_scope(
+  Order.where(status: "open"),
+  within: Time.zone.parse("2026-08-01")...Time.zone.parse("2026-09-01"),
+  associations: [:line_items],
+  limit: 500
+)
+```
+
+`analyses` is the same frozen hash `analyze_many` returns. It is also available
+as `PaperTrailDiff.analyze_many(scope: ..., limit: ...)`, and it accepts a model
+class (`Order`) as readily as a relation. Every other option — `within:`,
+`version_scope:`, `associations:`, `ignore:`, `activity:`, `close_on:` — behaves
+exactly as it does for `analyze_many`, and the query cost stays flat in the
+number of roots.
+
+Two things to know before using it.
+
+**`limit:` is required, and exceeding it raises.** Selection moves into the gem
+here, so the bound on how much work one page can ask for has to move with it. It
+refuses rather than truncating, because an audit report that is quietly short is
+worse than one that fails.
+
+**`unreachable` names roots the relation could not reach.** A relation's
+conditions are evaluated against the live table, so a root destroyed during the
+window cannot be tested against them at all — its history is intact, and the
+state it held when it was destroyed may well have matched:
+
+```ruby
+unreachable # => [["Order", "412"]]
+```
+
+These are reported rather than dropped so that a page auditing deletions is told
+where to look instead of silently coming up short. `analyze_many` requires live
+records by design, so to analyze those roots reach for `activity_timeline`, which
+reads history without needing current state.
+
+Note also that a relation selects on **current** state, not on state during the
+window. `where(status: "open")` means open *now*, which is a different set from
+what was open while the window was open. If you need the historical population,
+select on the version history instead and pass the records.
+
 ### Reporting on a subset of root mutations
 
 `version_scope:` narrows which root versions count as *selected mutations*, so a
@@ -616,6 +754,49 @@ boundary. Passing `to: article` is what removes the need to touch the parent
 after an ordinary versioned child mutation; current state is still never
 implicit.
 
+### Reporting one save as one step
+
+A parent and its children saved together produce a version each, so one
+deliberate action arrives as several steps. `group: :transaction` reports it as
+one:
+
+```ruby
+PaperTrailDiff.activity_timeline(
+  article, from: :first, to: article,
+  associations: [:comments], group: :transaction
+)
+```
+
+Given a single transaction that retitled an article, revised one comment, and
+added another, the ungrouped timeline reports three steps — the title change,
+then a step that reads as empty, then the comment changes. Grouped, it reports
+one step carrying the title *and* the comment changes, credited to whoever made
+the save. Off by default; also accepted by `analyze(activity: true)`.
+
+The middle step reads as empty for a reason worth knowing, because it is the
+same rule the rest of this document turns on. A version records the state
+*before* its own event, so 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 change made at
+that boundary surfaces a step or more afterwards, folded in with whatever that
+step carried. Nothing is lost — but "when" and "with what" both read wrong.
+
+Two properties this relies on:
+
+**A step belongs to the transaction of the event that opens it.** That is the
+event whose change the step reports, so grouping on the closing boundary instead
+would credit each change to whoever made the next one.
+
+**Merging compares the group's outer states**, rather than combining the diffs
+between them. A field set and then restored inside one transaction has not
+changed, and only comparing the endpoints can say so.
+
+A boundary that records no transaction groups with nothing. PaperTrail leaves
+`transaction_id` nil outside a transaction, and a custom version class need not
+carry the column at all; treating those as one shared transaction would merge
+unrelated history into a single step. `ActivityBoundary#transaction_id` exposes
+what a boundary recorded.
+
 ### Reading the state behind a step
 
 A step's diff carries what changed. A renderer often needs what did *not* — to

data/lib/paper_trail_diff/activity_boundary.rb

@@ -12,6 +12,10 @@ module PaperTrailDiff
     attr_reader :event #: String?
     attr_reader :whodunnit #: untyped
     attr_reader :record #: RecordReference
+    # The transaction the version was written in, when PaperTrail recorded one.
+    # Several versions saved together share it, which is what lets a timeline
+    # report one save as one step rather than as its parts.
+    attr_reader :transaction_id #: untyped
 
     class << self
       #: (untyped) -> ActivityBoundary
@@ -23,7 +27,8 @@ module PaperTrailDiff
           item_id: version.item_id,
           recorded_at: version.created_at,
           event: version.event,
-          whodunnit: version.whodunnit
+          whodunnit: version.whodunnit,
+          transaction_id: transaction_id(version)
         )
       end
 
@@ -50,12 +55,21 @@ module PaperTrailDiff
           item_id: version.item_id,
           recorded_at: version.created_at,
           event: version.event,
-          whodunnit: version.whodunnit
+          whodunnit: version.whodunnit,
+          transaction_id: transaction_id(version)
         )
       end
+
+      # A custom version class need not carry the column, and PaperTrail leaves
+      # it nil outside a transaction. Both read as "no transaction here", which
+      # groups with nothing.
+      #: (untyped) -> untyped
+      def transaction_id(version)
+        version.transaction_id if version.respond_to?(:transaction_id)
+      end
     end
 
-    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
+    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
       kind:,
       version_id:,
@@ -63,7 +77,8 @@ module PaperTrailDiff
       item_id:,
       recorded_at:,
       event: nil,
-      whodunnit: nil
+      whodunnit: nil,
+      transaction_id: nil
     )
       @kind = kind
       @version_id = Support.immutable_copy(version_id)
@@ -72,6 +87,7 @@ module PaperTrailDiff
       @recorded_at = Support.immutable_copy(recorded_at)
       @event = Support.immutable_copy(event&.to_s)
       @whodunnit = Support.immutable_copy(whodunnit)
+      @transaction_id = Support.immutable_copy(transaction_id)
       @record = RecordReference.new(type: @item_type, id: @item_id)
       freeze
     end

data/lib/paper_trail_diff/activity_grouping.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+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?
+      @group == :transaction
+    end
+
+    # Applied last, to finished steps, so grouping sees the same timeline the
+    # caller would otherwise have received.
+    #: (Array[ActivityStep]) -> Array[ActivityStep]
+    def group_steps(steps)
+      return steps unless grouping?
+
+      ActivityTransactionGrouper.new(steps, retain: @snapshots).call
+    end
+  end
+end

data/lib/paper_trail_diff/activity_timeline_builder.rb

@@ -4,9 +4,15 @@
 module PaperTrailDiff
   # Compares adjacent root and selected-descendant activity boundaries.
   class ActivityTimelineBuilder
-    #: (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
       @from = range.from
       @to = range.to
@@ -155,10 +161,10 @@ module PaperTrailDiff
         steps << ActivityStep.between(
           from_boundary: previous_boundary, to_boundary: final_boundary,
           from_snapshot: history.last_snapshot, to_snapshot: final_snapshot,
-          retain: @snapshots
+          retain: @retain
         )
       end
-      steps.freeze
+      group_steps(steps).freeze
     end
 
     # A destroyed root has no later version, but its own event states that
@@ -178,7 +184,7 @@ module PaperTrailDiff
         events,
         @snapshotter,
         current: current,
-        snapshots: @snapshots
+        snapshots: @retain
       ).call
     end
 
@@ -205,7 +211,8 @@ module PaperTrailDiff
         range: @range,
         tree: @tree,
         snapshotter: @snapshotter,
-        snapshots: @snapshots
+        snapshots: @snapshots,
+        group: @group
       )
     end
   end

data/lib/paper_trail_diff/activity_transaction_grouper.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+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(steps, retain:)
+      @steps = steps
+      @retain = retain
+    end
+
+    #: () -> Array[ActivityStep]
+    def call
+      grouped = [] #: Array[Array[ActivityStep]]
+      @steps.each do |step|
+        open_group = grouped.last
+        if open_group && continues?(open_group, step)
+          open_group << step
+        else
+          grouped << [step]
+        end
+      end
+      grouped.map { |group| merge(group) }
+    end
+
+    private
+
+    # @rbs @steps: Array[ActivityStep]
+    # @rbs @retain: bool
+
+    #: (Array[ActivityStep], ActivityStep) -> bool
+    def continues?(open_group, step)
+      transaction = step.from_boundary.transaction_id
+      return false if transaction.nil?
+
+      open_group.last.from_boundary.transaction_id == transaction
+    end
+
+    # 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(group)
+      first = group.first #: ActivityStep
+      last = group.last #: ActivityStep
+      ActivityStep.between(
+        from_boundary: first.from_boundary,
+        to_boundary: last.to_boundary,
+        from_snapshot: first.from_snapshot,
+        to_snapshot: last.to_snapshot,
+        retain: @retain
+      )
+    end
+  end
+end

data/lib/paper_trail_diff/diagnostics.rb

@@ -175,7 +175,9 @@ module PaperTrailDiff
     def inspect_versioned_model(model_class, path)
       return if model_versioned?(model_class)
 
-      add_warning(
+      # An error rather than a warning: `ok?` must not stay true for a
+      # comparison that cannot work, and this one raises at runtime.
+      add_error(
         :unversioned_association_target,
         "#{model_class.name} does not appear to have PaperTrail enabled",
         path
@@ -196,7 +198,7 @@ module PaperTrailDiff
 
     #: (untyped) -> bool
     def model_versioned?(model_class)
-      model_class.respond_to?(:paper_trail_options) && !model_class.paper_trail_options.nil?
+      Support.versioned?(model_class)
     end
 
     #: (untyped) -> bool

data/lib/paper_trail_diff/errors.rb

@@ -32,9 +32,17 @@ module PaperTrailDiff
   # Raised when versions sharing a timestamp cannot be ordered by their ids.
   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
 
+  # Raised when a selected association's target is not versioned, so its history
+  # cannot be reconstructed at all.
+  class UnversionedAssociationError < Error; end
+
   # Raised when a requested association macro is not supported.
   class UnsupportedAssociationError < Error; end