paper_trail_diff 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e85c7b69b7fe2c0c5b8fac36c28e94f0e8cb3e24bb0e84fa312a8c8c4de9a244
-  data.tar.gz: fa7118652d053ac5f882a6382c412534ca3c9fdbc3b613192652e7a3080fa205
+  metadata.gz: 808e6dba6570e96679cb5b355b774e8afcd3b6bf81c38c1a0b0fc088d6f9f416
+  data.tar.gz: 5978755e10f821777aadc86b6f4d79728a827cf48c1ba3e95c89a6f627eaea6e
 SHA512:
-  metadata.gz: 04d797a11eadc6702892f0e581da107bc6e1a4f2c41f7bf9759bddc1f01534b29389eeb12830b945be378c5cebe4ae3336235326ce21d7423b1f10e3bc48db28
-  data.tar.gz: 15cf3d7c0b099e2fb4c4db6db84c64718afd121d42fc91f8f63e34513d68db54f2c1365354eed648faef435e4d6a4e1645115978f80cbf2834e4e382efb3c773
+  metadata.gz: '048b927dd9d8274675ae60692ad705ed586c9d31ed6f4c11a581521d86ff8621dedda7daf33a4e4c90223b31a42bc60184c6f376ed4b1363a3cfcb5a2b2ab65a'
+  data.tar.gz: 559ea7552ce0133864a3e55df66097fdbbee3315febf9d04cd7485e0caa14e9deb34625b48ecb660f00cd452ec00b4e12d1180689c88a2b2464e59e71182abb5

data/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] - 2026-08-09
+
+### Added
+
+- Add deterministic `Diff#each_entry` and `Diff#each_change` traversal with
+  immutable `TraversalEntry` values for renderers, counters, exports, and
+  notifications.
+- Add immutable version metadata and record references to activity boundaries.
+- Give checkpoint `Step` objects `from_boundary` and `to_boundary` readers and
+  give both timeline step types an `empty?` predicate.
+- Add a Rails-focused quickstart with minimal endpoint, timeline, ignore, and
+  association examples.
+- Execute selected README and quickstart examples in isolated core and PT-AT
+  test sessions so documented behavior cannot silently drift.
+
 ## [0.1.0] - 2026-08-09
 
 ### Added

data/QUICKSTART.md

@@ -0,0 +1,260 @@
+# Quickstart
+
+This guide gets `paper_trail_diff` running in a Rails application and shows the
+smallest useful examples. Ruby 3.1 or newer and PaperTrail 16 or 17 are
+supported.
+
+## 1. Install the gem
+
+From the Rails application directory:
+
+```console
+bundle add paper_trail_diff
+bin/rails generate paper_trail:install --with-changes
+bin/rails db:migrate
+```
+
+Skip the generator if the application already has a PaperTrail `versions`
+table. The `object_changes` column created by `--with-changes` is recommended
+for efficient activity analysis, although endpoint comparison is based on
+reified state rather than a PaperTrail changeset.
+
+## 2. Version a model
+
+```ruby
+# app/models/article.rb
+class Article < ApplicationRecord
+  has_paper_trail
+end
+```
+
+Restart the Rails console after changing the Gemfile or an initializer.
+
+## 3. Create a little history
+
+Run this in `bin/rails console`:
+
+<!-- executable:quickstart-history -->
+```ruby
+article = Article.create!(title: "Draft")
+
+article.update!(title: "Published")
+draft_version = article.versions.last
+
+article.update!(title: "Final")
+published_version = article.versions.last
+```
+
+The variable names are intentional. PaperTrail versions contain the state
+*before* their event:
+
+```ruby
+draft_version.reify.title     # => "Draft"
+published_version.reify.title # => "Published"
+article.title                 # => "Final" (current database state)
+```
+
+## 4. Compare two states
+
+<!-- executable:quickstart-compare -->
+```ruby
+diff = PaperTrailDiff.compare(draft_version, published_version)
+
+diff.empty? # => false
+diff.attributes["title"].from # => "Draft"
+diff.attributes["title"].to   # => "Published"
+
+diff.to_h
+# => {
+#   record_presence_change: nil,
+#   attributes: {
+#     "title" => { from: "Draft", to: "Published" }
+#   },
+#   associations: {}
+# }
+```
+
+`compare` reports only the net difference between its endpoints. It does not
+report intermediate changes.
+
+### Compare a version with current state
+
+Pass the persisted record explicitly when the second endpoint should be the
+current database state:
+
+<!-- executable:quickstart-current -->
+```ruby
+diff = PaperTrailDiff.compare(published_version, article)
+
+diff.attributes["title"].to # => "Final"
+```
+
+The record must be persisted, not destroyed, and have no unsaved changes.
+Current state is never inferred automatically.
+
+## 5. Build a checkpoint timeline
+
+Create one more historical endpoint:
+
+<!-- executable:quickstart-timeline-state -->
+```ruby
+article.update!(title: "Archived")
+final_version = article.versions.last # reifies to "Final"
+```
+
+Then compare every adjacent root version:
+
+<!-- executable:quickstart-timeline -->
+```ruby
+steps = PaperTrailDiff.timeline(
+  article,
+  from: draft_version,
+  to: final_version
+)
+
+steps.map do |step|
+  change = step.diff.attributes["title"]
+  [change.from, change.to]
+end
+# => [["Draft", "Published"], ["Published", "Final"]]
+
+visible_steps = steps.reject { |step| step.diff.empty? }
+```
+
+Empty steps remain in the timeline. Filter them only when the application's
+display does not need every version boundary.
+
+## 6. Choose the right API
+
+| Need | Call |
+| --- | --- |
+| Net difference between two endpoints | `compare` |
+| One step per root-record version | `timeline` |
+| Steps for root and selected child versions | `activity_timeline` |
+| Net diff and timelines from one history pass | `analyze` |
+
+`timeline` is a root-checkpoint timeline. A child change becomes visible at the
+next root boundary. `activity_timeline` can make a versioned child change its
+own boundary and can end at an explicitly supplied current record.
+
+## 7. Ignore noise fields
+
+`updated_at` is ignored by default. Passing `ignore:` replaces that default:
+
+<!-- executable:quickstart-ignore -->
+```ruby
+PaperTrailDiff.compare(
+  draft_version,
+  published_version,
+  ignore: %i[updated_at lock_version]
+)
+
+PaperTrailDiff.compare(
+  draft_version,
+  published_version,
+  ignore: [] # compare every available scalar attribute
+)
+```
+
+See the main README for exact path-specific ignore rules.
+
+## 8. Add association history when needed
+
+Associations are optional. Add PT-AT only when the application needs historical
+association reconstruction:
+
+```console
+bundle add paper_trail-association_tracking
+bin/rails generate paper_trail_association_tracking:install
+bin/rails db:migrate
+```
+
+The generator creates `version_associations` and enables
+`PaperTrail.config.track_associations`. Every model whose historical state is
+needed must be versioned:
+
+```ruby
+class Article < ApplicationRecord
+  has_many :comments, dependent: :destroy
+  has_paper_trail synchronize_version_creation_timestamp: false
+end
+
+class Comment < ApplicationRecord
+  belongs_to :article
+  has_paper_trail
+end
+```
+
+Take an explicit root checkpoint before the example change:
+
+<!-- executable:quickstart-association -->
+```ruby
+Article.transaction do
+  Article.find(article.id).paper_trail.save_with_version
+end
+before = article.versions.reload.last
+
+article.comments.create!(body: "First comment")
+current = Article.find(article.id)
+
+diff = PaperTrailDiff.compare(
+  before,
+  current,
+  associations: [:comments]
+)
+
+diff.associations["comments"].added.first.attributes["body"]
+# => "First comment"
+```
+
+Nested paths are explicit and bounded:
+
+```ruby
+diff = PaperTrailDiff.compare(
+  before,
+  current,
+  associations: ["comments.replies.author"]
+)
+```
+
+To see versioned child events without touching the article after each change:
+
+<!-- executable:quickstart-activity -->
+```ruby
+steps = PaperTrailDiff.activity_timeline(
+  article,
+  from: before,
+  to: current,
+  associations: ["comments"]
+)
+
+steps.reject { |step| step.diff.empty? }.each do |step|
+  boundary = step.to_boundary
+  puts "#{boundary.item_type} ##{boundary.item_id}"
+end
+```
+
+Use a later transaction-backed root checkpoint instead of `to: current` when
+the result must remain reproducible after the database changes again.
+
+## 9. Common surprises
+
+- PaperTrail stores pre-change snapshots. The current record is not represented
+  by `versions.last`; pass the record explicitly when current state is wanted.
+- `ignore:` replaces the default list. Include `updated_at` yourself when using
+  a custom list and you still want it ignored.
+- Historical associations require PT-AT to be installed, loaded, migrated, and
+  enabled. Restart the console after setup.
+- Only requested association paths are traversed. The gem never recursively
+  discovers the whole model graph.
+- Historical output cannot contain data that PaperTrail or PT-AT did not record
+  or can no longer reconstruct.
+
+For performance guidance, HABTM limitations, diagnostics, discovery, path-aware
+ignore rules, and complete result shapes, continue with the
+[README](README.md).
+
+Upstream setup references:
+[PaperTrail installation](https://github.com/paper-trail-gem/paper_trail#1b-installation)
+and
+[PT-AT installation](https://github.com/westonganger/paper_trail-association_tracking#install).

data/README.md

@@ -12,6 +12,8 @@ available when
 
 Ruby 3.1 or newer and PaperTrail 16 or 17 are supported.
 
+New to the gem? Start with the copyable [Quickstart](QUICKSTART.md).
+
 ## Installation
 
 Add the gem to your bundle:
@@ -95,11 +97,22 @@ steps = PaperTrailDiff.timeline(
 
 steps.first.from_version # the original PaperTrail version
 steps.first.to_version   # the next PaperTrail version
+steps.first.from_boundary # immutable presentation metadata
+steps.first.to_boundary
 steps.first.diff         # a PaperTrailDiff::Diff
+steps.first.empty?        # delegates to the diff
 steps.first.to_h
 # => { from_version_id: 2, to_version_id: 3, diff: { ... } }
 ```
 
+Both timeline types expose `from_boundary`, `to_boundary`, `diff`, and
+`empty?`. A historical boundary has `event`, `whodunnit`, `record`,
+`recorded_at`, `version?`, and `current?` readers. Checkpoint `Step` objects
+also retain their original `from_version` and `to_version` for callers that
+need custom PaperTrail metadata. Existing `Step#to_h` and
+`ActivityBoundary#to_h` shapes remain unchanged; use the readers for the new
+metadata.
+
 Every version boundary remains in the result, even when its diff is empty after
 ignored fields are removed. Equal boundaries return a frozen empty array.
 
@@ -323,6 +336,61 @@ database state. Unknown names and unsupported macros raise explicit
 Malformed public options raise `PaperTrailDiff::ConfigurationError`, also under
 that base error.
 
+## Traverse result trees
+
+The nested tree remains the canonical, lossless result. For renderers,
+counters, exports, and notifications, `Diff#each_change` provides a
+deterministic depth-first stream of semantic changes:
+
+<!-- executable:readme-traversal-changes -->
+```ruby
+diff.each_change do |entry|
+  entry.kind              # :attribute_changed, :record_added, ...
+  entry.association_path  # ["comments", "replies"]
+  entry.record_path       # frozen RecordReference objects
+  entry.association_kind  # :has_many, :belongs_to, ...
+  entry.attribute         # "body" for an attribute entry
+  entry.value             # ValueChange, RecordChange, or RecordSnapshot
+end
+
+counts = diff.each_change.map(&:kind).tally
+```
+
+`record_changed` entries are emitted before that record's attribute and nested
+association changes, allowing an application to count both changed records and
+changed fields. Singular relationship operations are classified separately as
+`relationship_added`, `relationship_removed`, or `relationship_replaced`.
+Root create/delete transitions remain `record_presence_changed`.
+
+Added, removed, and replaced records carry complete bounded snapshots. Use
+`each_entry` when a renderer also needs that nested state without writing a
+second snapshot walker:
+
+<!-- executable:readme-traversal-entries -->
+```ruby
+diff.each_entry do |entry|
+  next unless entry.included_state?
+
+  entry.kind     # :record_included, :attribute_included, :association_included
+  entry.state    # :before or :after
+  entry.context  # :included_state
+end
+```
+
+An included record is historical context, not evidence that the nested record
+changed independently. `each_change` therefore omits included-state entries.
+Both methods return an `Enumerator` when no block is supplied and return the
+diff when called with a block. Entries and their paths are immutable and have
+deterministic `to_h` output. The root location uses empty association and record
+paths; descendant `record_path` values contain only the explicitly traversed
+descendant identities.
+
+Traversal is path-preserving and does not deduplicate. If the same record is
+reachable through two selected paths, it appears at both locations so the
+consumer can choose whether path identity or record identity controls counting.
+Walking a result never performs database access and never discovers additional
+associations.
+
 ## Discover and diagnose associations
 
 Configuration UIs can use bounded public reflection instead of duplicating the
@@ -392,6 +460,7 @@ The public result types are:
 - `PaperTrailDiff::ActivityBoundary`
 - `PaperTrailDiff::Analysis`
 - `PaperTrailDiff::ValueChange`
+- `PaperTrailDiff::TraversalEntry`
 - `PaperTrailDiff::RecordReference`
 - `PaperTrailDiff::RecordSnapshot`
 - `PaperTrailDiff::RecordChange`
@@ -404,11 +473,13 @@ The public result types are:
 They expose readers, are frozen after construction, and provide deterministic
 `to_h` output. Structural hash keys are symbols; attribute and association
 names are strings. Attribute values retain their Ruby types. `RecordChange#record`
-is a `RecordReference` with `type` and `id` readers. `Step` itself is frozen but
-intentionally retains the original, potentially mutable PaperTrail version
-objects for metadata access; `Step#to_h` emits only their IDs. `ActivityStep`
-instead retains only immutable boundary metadata and serializes as
-`{ from: ..., to: ..., diff: ... }`.
+is a `RecordReference` with `type` and `id` readers. `TraversalEntry#record` and
+`#association` return the final components of their corresponding paths. `Step`
+itself is frozen but intentionally retains the original, potentially mutable
+PaperTrail version objects for metadata access; its new boundary readers provide
+an immutable presentation interface, while `Step#to_h` continues to emit only
+version IDs. `ActivityStep` retains only immutable boundary metadata and
+serializes as `{ from: ..., to: ..., diff: ... }`.
 
 ## Historical correctness and limitations
 
@@ -459,6 +530,9 @@ mise exec -- act push -j quality --matrix ruby:4.0 --matrix paper_trail:17
 
 The default Rake task runs core specs without PT-AT loaded, association specs in
 a separate process, RuboCop, generated-signature verification, and Steep.
+Selected Ruby blocks in this README and the quickstart are executed in those
+same isolated test sessions; the `<!-- executable:... -->` marker opts a block
+into the appropriate stateful session.
 Inline `#:` annotations in `lib/` generate the committed RBS files under
 `sig/generated/`.
 

data/lib/paper_trail_diff/activity_boundary.rb

@@ -9,6 +9,9 @@ module PaperTrailDiff
     attr_reader :item_type #: String
     attr_reader :item_id #: untyped
     attr_reader :recorded_at #: untyped
+    attr_reader :event #: String?
+    attr_reader :whodunnit #: untyped
+    attr_reader :record #: RecordReference
 
     class << self
       #: (untyped) -> ActivityBoundary
@@ -18,7 +21,9 @@ module PaperTrailDiff
           version_id: version.id,
           item_type: version.item_type,
           item_id: version.item_id,
-          recorded_at: version.created_at
+          recorded_at: version.created_at,
+          event: version.event,
+          whodunnit: version.whodunnit
         )
       end
 
@@ -34,16 +39,37 @@ module PaperTrailDiff
       end
     end
 
-    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped) -> void
-    def initialize(kind:, version_id:, item_type:, item_id:, recorded_at:)
+    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      kind:,
+      version_id:,
+      item_type:,
+      item_id:,
+      recorded_at:,
+      event: nil,
+      whodunnit: nil
+    )
       @kind = kind
       @version_id = Support.immutable_copy(version_id)
       @item_type = Support.immutable_copy(item_type.to_s)
       @item_id = Support.immutable_copy(item_id)
       @recorded_at = Support.immutable_copy(recorded_at)
+      @event = Support.immutable_copy(event&.to_s)
+      @whodunnit = Support.immutable_copy(whodunnit)
+      @record = RecordReference.new(type: @item_type, id: @item_id)
       freeze
     end
 
+    #: () -> bool
+    def version?
+      kind == :version
+    end
+
+    #: () -> bool
+    def current?
+      kind == :current
+    end
+
     #: () -> Hash[Symbol, untyped]
     def to_h
       {
@@ -70,6 +96,11 @@ module PaperTrailDiff
       freeze
     end
 
+    #: () -> bool
+    def empty?
+      diff.empty?
+    end
+
     #: () -> Hash[Symbol, untyped]
     def to_h
       {

data/lib/paper_trail_diff/association_diff_traversal.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Walks nested singular and collection association differences.
+  class AssociationDiffTraversal < TraversalEmitter
+    #: (^(TraversalEntry) -> void) -> void
+    def initialize(receiver)
+      super
+      @snapshots = SnapshotTraversal.new(receiver)
+    end
+
+    #: (association_diffs, association_path: traversal_association_path, record_path: traversal_record_path) -> void
+    def call(associations, association_path:, record_path:)
+      associations.each do |name, association|
+        child_path = association_path + [name]
+        walk_association(association, child_path, record_path)
+      end
+    end
+
+    #: (Hash[String, ValueChange], association_path: traversal_association_path, record_path: traversal_record_path, association_kind: Symbol?) -> void
+    def attributes(changes, association_path:, record_path:, association_kind:)
+      changes.each do |name, change|
+        emit_attribute(name, change, association_path, record_path, association_kind)
+      end
+    end
+
+    private
+
+    # @rbs @snapshots: SnapshotTraversal
+
+    #: (association_diff, traversal_association_path, traversal_record_path) -> void
+    def walk_association(association, association_path, record_path)
+      if association.is_a?(CollectionAssociationDiff)
+        walk_collection(association, association_path, record_path)
+      else
+        walk_to_one(association, association_path, record_path)
+      end
+    end
+
+    #: (String, ValueChange, traversal_association_path, traversal_record_path, Symbol?) -> void
+    def emit_attribute(name, change, association_path, record_path, association_kind)
+      emit(
+        kind: :attribute_changed,
+        context: :change,
+        association_path: association_path,
+        record_path: record_path,
+        association_kind: association_kind,
+        attribute: name,
+        value: change
+      )
+    end
+
+    #: (CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def walk_collection(association, association_path, record_path)
+      walk_memberships(
+        association.added, :record_added, :after,
+        association, association_path, record_path
+      )
+      walk_memberships(
+        association.removed, :record_removed, :before,
+        association, association_path, record_path
+      )
+      association.changed.each do |change|
+        walk_record_change(change, association.kind, association_path, record_path)
+      end
+    end
+
+    #: (Array[RecordSnapshot], Symbol, traversal_state, CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def walk_memberships( # rubocop:disable Metrics/ParameterLists
+      snapshots, kind, state, association, association_path, record_path
+    )
+      snapshots.each do |snapshot|
+        walk_membership(snapshot, kind, state, association, association_path, record_path)
+      end
+    end
+
+    #: (RecordSnapshot, Symbol, traversal_state, CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def walk_membership( # rubocop:disable Metrics/ParameterLists
+      snapshot, kind, state, association, association_path, record_path
+    )
+      child_records = record_path + [snapshot.reference]
+      emit_membership(snapshot, kind, state, association, association_path, child_records)
+      @snapshots.call(
+        snapshot,
+        association_path: association_path,
+        record_path: child_records,
+        state: state,
+        association_kind: association.kind,
+        include_record: false
+      )
+    end
+
+    #: (RecordSnapshot, Symbol, traversal_state, CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def emit_membership( # rubocop:disable Metrics/ParameterLists
+      snapshot, kind, state, association, association_path, record_path
+    )
+      emit(
+        kind: kind,
+        context: :change,
+        association_path: association_path,
+        record_path: record_path,
+        association_kind: association.kind,
+        state: state,
+        value: snapshot
+      )
+    end
+
+    #: (ToOneAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def walk_to_one(association, association_path, record_path)
+      if association.relationship
+        walk_relationship(association.relationship, association.kind, association_path, record_path)
+      elsif association.changed
+        walk_record_change(association.changed, association.kind, association_path, record_path)
+      end
+    end
+
+    #: (ValueChange, Symbol, traversal_association_path, traversal_record_path) -> void
+    def walk_relationship(change, association_kind, association_path, record_path)
+      emit_relationship(change, association_kind, association_path, record_path)
+      walk_related(change.from, :before, association_kind, association_path, record_path)
+      walk_related(change.to, :after, association_kind, association_path, record_path)
+    end
+
+    #: (ValueChange, Symbol, traversal_association_path, traversal_record_path) -> void
+    def emit_relationship(change, association_kind, association_path, record_path)
+      emit(
+        kind: relationship_kind(change),
+        context: :change,
+        association_path: association_path,
+        record_path: record_path,
+        association_kind: association_kind,
+        value: change
+      )
+    end
+
+    #: (RecordSnapshot?, traversal_state, Symbol, traversal_association_path, traversal_record_path) -> void
+    def walk_related(snapshot, state, association_kind, association_path, record_path)
+      return unless snapshot
+
+      @snapshots.call(
+        snapshot,
+        association_path: association_path,
+        record_path: record_path + [snapshot.reference],
+        state: state,
+        association_kind: association_kind
+      )
+    end
+
+    #: (ValueChange) -> Symbol
+    def relationship_kind(change)
+      return :relationship_added unless change.from
+      return :relationship_removed unless change.to
+
+      :relationship_replaced
+    end
+
+    #: (RecordChange, Symbol, traversal_association_path, traversal_record_path) -> void
+    def walk_record_change(change, association_kind, association_path, record_path)
+      child_records = record_path + [change.record]
+      emit_record_change(change, association_kind, association_path, child_records)
+      attributes(
+        change.attributes,
+        association_path: association_path,
+        record_path: child_records,
+        association_kind: association_kind
+      )
+      call(change.associations, association_path: association_path, record_path: child_records)
+    end
+
+    #: (RecordChange, Symbol, traversal_association_path, traversal_record_path) -> void
+    def emit_record_change(change, association_kind, association_path, record_path)
+      emit(
+        kind: :record_changed,
+        context: :change,
+        association_path: association_path,
+        record_path: record_path,
+        association_kind: association_kind,
+        value: change
+      )
+    end
+  end
+  private_constant :AssociationDiffTraversal
+end