paper_trail_diff 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e85c7b69b7fe2c0c5b8fac36c28e94f0e8cb3e24bb0e84fa312a8c8c4de9a244
+  data.tar.gz: fa7118652d053ac5f882a6382c412534ca3c9fdbc3b613192652e7a3080fa205
+SHA512:
+  metadata.gz: 04d797a11eadc6702892f0e581da107bc6e1a4f2c41f7bf9759bddc1f01534b29389eeb12830b945be378c5cebe4ae3336235326ce21d7423b1f10e3bc48db28
+  data.tar.gz: 15cf3d7c0b099e2fb4c4db6db84c64718afd121d42fc91f8f63e34513d68db54f2c1365354eed648faef435e4d6a4e1645115978f80cbf2834e4e382efb3c773

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The
+project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-08-09
+
+### Added
+
+- Add explicit, bounded nested association paths such as
+  `comments.replies.author`.
+- Add nested association changes to stable-record diffs and selected subtrees
+  to added/removed record snapshots.
+- Add path-aware ignore rules while preserving the existing global array form.
+- Add root and nested `has_and_belongs_to_many` collection diffs, including
+  historical membership, target updates, timelines, and bounded cyclic paths.
+- Reload the configured PaperTrail versions association before resolving
+  timeline boundaries.
+- Rename the root `Diff#record` lifecycle field to the more explicit
+  `Diff#record_presence_change`, including its `to_h` key.
+- Add `activity_timeline` for adjacent root and selected-descendant version
+  boundaries while preserving the root-only semantics of `timeline`.
+- Add one-pass `analyze`, bounded association discovery, and structured history
+  diagnostics.
+- Bound version loads to the requested time range, stream timeline construction,
+  and reuse immutable snapshot subtrees across adjacent boundaries.
+- Apply event-local snapshot deltas for direct `has_many` membership changes at
+  any selected depth and selected non-polymorphic `belongs_to` target events,
+  with safe reconstruction fallbacks for other association shapes.
+- Reconstruct post-create/update records from PaperTrail's serialized change
+  pairs to avoid per-event successor and live-record lookups.
+- Derive combined endpoint, root-timeline, and activity results from one
+  snapshot pass; advance isolated root changes in place and selectively refresh
+  only ambiguous association branches.
+- Add `RecordReference`, consistent configuration error subclasses, traversal
+  foreign-key suppression, and fail-loud HABTM endpoint validation.
+- Fix selective `has_many :through` reconstruction by reifying the hidden
+  through collection before resolving target records.
+- Prepare timeline record states and association membership once per requested
+  range, using indexed resolution for direct relationships, belongs-to-source
+  through collections, and transaction-backed HABTM membership.
+- Retain point-in-time PT-AT reconstruction as a per-reflection fallback for
+  scoped, unversioned, composite-key, and unsupported through shapes.
+- Keep multiple selected descendant events in one transaction atomic instead
+  of applying an individual event delta before the transaction boundary.

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Alex Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,473 @@
+# paper_trail_diff
+
+`paper_trail_diff` adds structured endpoint, checkpoint-timeline, and activity
+comparisons to
+[PaperTrail](https://github.com/paper-trail-gem/paper_trail). It returns immutable
+Ruby value objects and hashes rather than formatted text.
+
+PaperTrail is required. Explicit, bounded association-path comparison is
+available when
+[paper_trail-association_tracking](https://github.com/westonganger/paper_trail-association_tracking)
+(PT-AT) is installed, loaded, and enabled.
+
+Ruby 3.1 or newer and PaperTrail 16 or 17 are supported.
+
+## Installation
+
+Add the gem to your bundle:
+
+```ruby
+gem "paper_trail_diff"
+```
+
+For association history, also add and configure PT-AT using its migrations:
+
+```ruby
+gem "paper_trail-association_tracking"
+```
+
+```ruby
+PaperTrail.config.track_associations = true
+```
+
+All associated models whose historical state is compared must use
+`has_paper_trail`.
+
+## Compare two endpoints
+
+PaperTrail stores an object's state before each recorded event. `compare`
+accepts two explicit endpoints: each may be a PaperTrail version or a clean,
+persisted model instance representing current database state. It reports only
+their net difference:
+
+```ruby
+diff = PaperTrailDiff.compare(article.versions[1], article.versions[4])
+
+diff.attributes["title"].from # => "Draft"
+diff.attributes["title"].to   # => "Published"
+diff.empty?                    # => false
+diff.to_h
+# => {
+#   record_presence_change: nil,
+#   attributes: {
+#     "title" => { from: "Draft", to: "Published" }
+#   },
+#   associations: {}
+# }
+```
+
+Intermediate edits do not affect `compare`. If a title changes and later
+returns to its original value, endpoint comparison reports no title change.
+A `create` version reifies to `nil`; comparing it with a record state produces
+a structured `record_presence_change` instead of fake scalar changes. For
+ordinary updates, `record_presence_change` is `nil`, meaning the root record is
+present at both endpoints; scalar changes remain under `attributes`.
+
+Pass the record explicitly when the desired endpoint is current state:
+
+```ruby
+diff = PaperTrailDiff.compare(
+  article.versions.last,
+  article,
+  associations: ["comments.replies"]
+)
+```
+
+Version and record endpoints may appear in either order. Current state is never
+inferred. The record must be persisted, not destroyed, and free of unsaved
+attribute changes. The gem reloads it unscoped before normalization, so stale
+association caches and in-memory edits are not compared. Use a database
+transaction with an appropriate isolation level when several live association
+queries must represent one atomic application snapshot.
+
+## Build a root-checkpoint timeline
+
+`timeline` accepts two version objects from the supplied record's history. The
+range is inclusive, must be chronological, and produces one `Step` for each
+adjacent pair:
+
+```ruby
+steps = PaperTrailDiff.timeline(
+  article,
+  from: article.versions[1],
+  to: article.versions[4]
+)
+
+steps.first.from_version # the original PaperTrail version
+steps.first.to_version   # the next PaperTrail version
+steps.first.diff         # a PaperTrailDiff::Diff
+steps.first.to_h
+# => { from_version_id: 2, to_version_id: 3, diff: { ... } }
+```
+
+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.
+
+This is deliberately a root-record timeline. Several child changes between two
+root versions appear together in the same step.
+
+## Build an activity timeline
+
+`activity_timeline` merges versions for the root and explicitly selected
+descendants. Child changes can therefore form separate steps instead of waiting
+to be aggregated at the next root checkpoint:
+
+```ruby
+steps = PaperTrailDiff.activity_timeline(
+  article,
+  from: article.versions[1],
+  to: article.versions[4],
+  associations: ["comments.replies", :author]
+)
+
+steps.reject { |step| step.diff.empty? }
+```
+
+Pass the record explicitly as `to:` to include current state without creating a
+final root checkpoint:
+
+```ruby
+steps = PaperTrailDiff.activity_timeline(
+  article,
+  from: article.versions[1],
+  to: article,
+  associations: ["comments.replies", :author]
+)
+```
+
+The result is a frozen array of `ActivityStep` objects. Each step has immutable
+`from_boundary`, `to_boundary`, and `diff` readers. Historical boundaries are
+`kind: :version`; an explicitly requested live endpoint is `kind: :current`:
+
+```ruby
+steps.last.to_boundary.to_h
+# => {
+#   kind: :current,
+#   version_id: nil,
+#   item_type: "Article",
+#   item_id: 42,
+#   recorded_at: 2026-08-08 12:00:00 UTC
+# }
+```
+
+A historical boundary may belong to the root or a selected descendant model.
+PaperTrail versions describe pre-change state, so a mutation becomes visible
+between its version boundary and the next historical or explicit current
+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.
+
+Live-ended HABTM activity is rejected with
+`PaperTrailDiff::UnsupportedLiveActivityError`. HABTM join rows have no model
+versions, so the gem cannot reliably split their membership mutations into
+intermediate events without transaction-backed owner checkpoints. Historical
+HABTM activity and `compare(version, article, associations: [:tags])` remain
+supported where the historical endpoint has usable PT-AT metadata.
+
+Both timeline APIs preserve empty boundaries. A display may filter
+`step.diff.empty?`, while audit-oriented callers can retain every recorded
+boundary.
+
+## Build an endpoint and timeline together
+
+When a caller needs the net endpoint diff and root timeline, `analyze`
+normalizes each selected version once. Pass `activity: true` when the same view
+also needs descendant-aware activity. The endpoint diff and root timeline are
+then derived from the same activity snapshot pass instead of reconstructing the
+root history separately:
+
+```ruby
+analysis = PaperTrailDiff.analyze(
+  article,
+  from: article.versions[1],
+  to: article.versions[4],
+  associations: ["comments.replies"],
+  activity: true
+)
+
+analysis.diff
+analysis.timeline
+analysis.activity_timeline
+```
+
+Without `activity: true`, `analysis.activity_timeline` is `nil` and no activity
+work is performed. `analyze` remains version-bounded; use the standalone
+`activity_timeline(..., to: article)` API for an explicit current endpoint.
+
+`timeline`, `activity_timeline`, and both forms of `analyze` prepare the selected
+historical range once. The loader walks only the explicit association paths and
+builds an immutable temporal index of scalar states, relationship candidates,
+HABTM transaction snapshots, and live fallbacks. Direct relationships,
+`has_many :through` with a `belongs_to` source, and transaction-backed HABTM
+membership are resolved from that index. Endpoint-only `compare` retains the
+lighter two-point reconstruction path.
+
+Activity reconstruction then carries immutable snapshots forward between
+boundaries. Isolated root and descendant events with usable serialized changes
+advance only the affected immutable nodes. Events sharing a PT-AT transaction
+refresh their combined branches atomically. Scoped associations, unversioned
+targets, composite relationship keys, collection-source through associations,
+and other unsupported shapes fall back to the ordinary PT-AT point reifier on
+a per-reflection basis. This hybrid path preserves existing reconstruction
+behavior while avoiding repeated association queries for supported paths.
+
+Activity event discovery is bounded to the selected range. Prepared scalar
+state also retains later successor versions for selected identities because a
+PaperTrail version is a pre-change snapshot and may be the only correct state
+for an earlier boundary. Memory therefore scales with relevant selected
+history, not only with the number of returned steps. Keep requested paths and
+ranges intentional. For large histories, applications should give the database
+a matching composite index. A typical PaperTrail installation can add one
+without making it a requirement of this gem:
+
+```ruby
+add_index :versions, %i[item_type item_id created_at id],
+          name: "index_versions_on_item_and_timeline"
+```
+
+PT-AT's normal index beginning with `foreign_key_name`, `foreign_key_id`, and
+`foreign_type` should also be retained on `version_associations`.
+
+## Ignore noise fields
+
+The comparison APIs ignore `updated_at` by default. `ignore:` replaces that default and
+accepts string or symbol names. The array form applies to the root and every
+selected association:
+
+```ruby
+PaperTrailDiff.compare(from, to, ignore: %i[updated_at lock_version])
+PaperTrailDiff.compare(from, to, ignore: []) # compare every scalar field
+```
+
+For exact path control, pass `all:` plus `paths:`. `$` identifies the root:
+
+```ruby
+PaperTrailDiff.compare(
+  from,
+  to,
+  associations: ["comments.replies"],
+  ignore: {
+    all: [:updated_at],
+    paths: {
+      "$" => [:lock_version],
+      "comments.replies" => [:delivery_state]
+    }
+  }
+)
+```
+
+Hash rules replace the default just like an array. `all:` applies everywhere;
+each path entry applies only at that exact path, not its descendants. Ignore
+paths must be `$` or one of the selected or implicitly selected association
+paths.
+
+Primary keys are always represented as record identity rather than scalar
+attributes.
+
+## Compare associations
+
+Pass explicit names or dot-separated paths. Paths are finite traversal plans,
+not a request to recursively inspect the whole object graph. Ancestors are
+selected implicitly:
+
+```ruby
+diff = PaperTrailDiff.compare(
+  from,
+  to,
+  associations: [:author, :profile, "comments.replies.author"]
+)
+
+diff.associations["author"].relationship
+# => #<PaperTrailDiff::ValueChange ...>  # belongs_to replacement
+
+comments = diff.associations["comments"]
+comments.added   # full RecordSnapshot objects
+comments.removed # full RecordSnapshot objects
+comments.changed # RecordChange objects for stable identities
+
+replies = comments.changed.first.associations["replies"]
+replies.added
+replies.removed
+replies.changed
+```
+
+For `belongs_to` and `has_one`, replacing the related identity is a
+`relationship` change. Updating attributes on the same related identity is a
+`changed` record. For `has_many` and `has_and_belongs_to_many`, membership is
+split into `added` and `removed`; shared identities with scalar changes appear
+in `changed`. The result preserves the reflected macro in `kind`.
+
+Both Rails many-to-many forms are supported. `has_many :through` uses PT-AT's
+history for the versioned join model. HABTM reports membership and target
+attribute changes, but it cannot report join attributes because HABTM has no
+join model.
+
+The same structure repeats at every selected depth. `RecordChange#associations`
+contains nested changes for a stable parent identity. Added and removed record
+snapshots retain their selected subtrees so nested state is not discarded.
+
+Selecting a `belongs_to` removes its foreign-key (and polymorphic type) column
+from scalar changes at that path. Without association selection, that column
+remains a normal scalar attribute. A direct `has_one` or `has_many` edge also
+removes its incoming foreign key from the child snapshot because membership is
+already represented structurally. Join-model attributes for `has_many :through`
+remain available. Cyclic model relationships are safe because only the finite
+paths supplied by the caller are traversed.
+
+Requesting associations for any historical endpoint without loaded and enabled
+PT-AT raises `PaperTrailDiff::AssociationTrackingUnavailableError`. A comparison
+whose endpoints are both live records can normalize associations without PT-AT,
+though it will normally be empty because both records reload the same current
+database state. Unknown names and unsupported macros raise explicit
+`PaperTrailDiff::Error` subclasses.
+Malformed public options raise `PaperTrailDiff::ConfigurationError`, also under
+that base error.
+
+## Discover and diagnose associations
+
+Configuration UIs can use bounded public reflection instead of duplicating the
+gem's macro and cycle logic:
+
+```ruby
+PaperTrailDiff.supported_association_macros
+PaperTrailDiff.association_paths(Article, max_depth: 3).map(&:to_h)
+```
+
+Descriptors include `path`, `kind`, `target_type`, `through`, `polymorphic`, and
+`cycle`. Cycles are marked and not descended; PaperTrail's infrastructure
+`versions` association is excluded.
+
+Before relying on association history, inspect known setup hazards:
+
+```ruby
+report = PaperTrailDiff.diagnose(
+  from_version,
+  to_version,
+  associations: [:tags, "comments.replies"]
+)
+
+report.ok?
+report.errors.map(&:code)
+report.warnings.map(&:code)
+```
+
+Diagnostics are read-only guidance, not proof that arbitrary old data is
+complete. HABTM endpoints without transaction-backed association snapshots fail
+loudly with `PaperTrailDiff::IncompleteAssociationHistoryError` during normal
+comparison as well.
+
+### Recommended checkpoint recipe
+
+For PT-AT history—especially HABTM—use transaction-backed checkpoints, disable
+PaperTrail's version timestamp synchronization on the root, and checkpoint a
+fresh record instance:
+
+```ruby
+class Article < ApplicationRecord
+  has_paper_trail synchronize_version_creation_timestamp: false
+end
+
+def checkpoint_article(article_id)
+  Article.transaction do
+    Article.find(article_id).paper_trail.save_with_version
+  end
+end
+```
+
+A root checkpoint after a batch supplies an immutable historical final state.
+The ordinary `timeline` aggregates that batch; `activity_timeline` uses recorded
+descendant versions to split it into activity boundaries. For an interactive
+view, `activity_timeline(..., to: article)` can instead terminate explicitly at
+current state without touching the root. Prefer checkpoints for reproducible
+audits and HABTM, and prefer an explicit join model with `has_many :through`
+when join attributes or join mutations must appear as first-class history.
+
+## Result objects
+
+The public result types are:
+
+- `PaperTrailDiff::Diff`
+- `PaperTrailDiff::Step`
+- `PaperTrailDiff::ActivityStep`
+- `PaperTrailDiff::ActivityBoundary`
+- `PaperTrailDiff::Analysis`
+- `PaperTrailDiff::ValueChange`
+- `PaperTrailDiff::RecordReference`
+- `PaperTrailDiff::RecordSnapshot`
+- `PaperTrailDiff::RecordChange`
+- `PaperTrailDiff::ToOneAssociationDiff`
+- `PaperTrailDiff::CollectionAssociationDiff`
+- `PaperTrailDiff::AssociationDescriptor`
+- `PaperTrailDiff::DiagnosticReport`
+- `PaperTrailDiff::DiagnosticIssue`
+
+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: ... }`.
+
+## Historical correctness and limitations
+
+The output is only as correct and complete as the historical state PaperTrail
+and PT-AT can reconstruct. In particular:
+
+- attributes skipped by PaperTrail, deleted versions, and changes made while
+  versioning was disabled cannot be recovered;
+- model/schema or serializer changes can affect reification of old versions;
+- comparison and activity APIs add live state only when the caller explicitly
+  passes a persisted record endpoint; the adapter reloads that record, but
+  multiple queries are not automatically one database-isolated snapshot;
+- PT-AT requires its schema, callbacks, versioned child models, and transaction
+  metadata; callback-skipping writes may not be reconstructable;
+- HABTM membership is limited to the join snapshots PT-AT recorded in
+  `version_associations`; historical target attributes require versioned target
+  models, otherwise PT-AT may return live target state;
+- `timeline` and `analyze` are bounded by root versions; `activity_timeline`
+  adds recorded descendant boundaries and may terminate at an explicitly passed
+  current record, while a fully historical result still requires a later root
+  version because PaperTrail stores pre-change snapshots;
+- HABTM join-table mutations do not have their own model versions and therefore
+  cannot become standalone activity boundaries; live-ended HABTM activity is
+  rejected, and a versioned join model should be used when that activity matters;
+- activity discovery uses PT-AT association rows and cannot recover descendant
+  events whose relevant callbacks or association metadata were never recorded;
+- PT-AT has documented edge cases, especially around some `has_one` histories;
+  `paper_trail_diff` respects PT-AT's configured reification error behavior;
+- deeper paths require more historical reconstruction and database work, so
+  callers should select only the branches they need;
+- no implicit or unbounded recursive association traversal is performed.
+
+Review the [PaperTrail version semantics](https://github.com/paper-trail-gem/paper_trail#3-working-with-versions)
+and [PT-AT limitations](https://github.com/westonganger/paper_trail-association_tracking#limitations)
+before relying on reconstructed history for restoration or compliance work.
+
+## Development
+
+The project uses mise for its pinned development tools:
+
+```console
+mise install
+mise exec -- bundle install
+mise exec -- bundle exec rake
+mise exec -- bundle exec rake build
+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.
+Inline `#:` annotations in `lib/` generate the committed RBS files under
+`sig/generated/`.
+
+Release tags matching `v*` publish through RubyGems trusted publishing. Before
+tagging, replace `Unreleased` in the changelog with the release date, run the
+full CI workflow, and configure the repository's `release` environment as a
+trusted publisher on RubyGems. Do not store a long-lived RubyGems API key in
+the repository.
+
+## License
+
+MIT

data/lib/paper_trail_diff/activity_boundary.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Immutable metadata identifying one historical or current activity boundary.
+  class ActivityBoundary
+    attr_reader :kind #: Symbol
+    attr_reader :version_id #: untyped
+    attr_reader :item_type #: String
+    attr_reader :item_id #: untyped
+    attr_reader :recorded_at #: untyped
+
+    class << self
+      #: (untyped) -> ActivityBoundary
+      def from_version(version)
+        new(
+          kind: :version,
+          version_id: version.id,
+          item_type: version.item_type,
+          item_id: version.item_id,
+          recorded_at: version.created_at
+        )
+      end
+
+      #: (untyped, captured_at: untyped) -> ActivityBoundary
+      def current(record, captured_at:)
+        new(
+          kind: :current,
+          version_id: nil,
+          item_type: record.class.base_class.name,
+          item_id: record.id,
+          recorded_at: captured_at
+        )
+      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 = 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)
+      freeze
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        kind: kind,
+        version_id: version_id,
+        item_type: item_type,
+        item_id: item_id,
+        recorded_at: recorded_at
+      }
+    end
+  end
+
+  # One adjacent transition in a descendant-aware activity timeline.
+  class ActivityStep
+    attr_reader :from_boundary #: ActivityBoundary
+    attr_reader :to_boundary #: ActivityBoundary
+    attr_reader :diff #: Diff
+
+    #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
+    def initialize(from_boundary:, to_boundary:, diff:)
+      @from_boundary = from_boundary
+      @to_boundary = to_boundary
+      @diff = diff
+      freeze
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        from: from_boundary.to_h,
+        to: to_boundary.to_h,
+        diff: diff.to_h
+      }
+    end
+  end
+end