paper_trail_diff 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e747358edb04ac2ea49e43b11eb8b5b8e811c426b50b017ed6d1c72162bb4632
-  data.tar.gz: b330e3bb80e43e478a0e88ff7afeb2b6576d3550af0a54075948fb0e60dc045d
+  metadata.gz: a4e484cc975317987834dd585f1bc5432985575c66b473b1db5c31b3feb4995d
+  data.tar.gz: 127f6d1e5ae63a839be293ea22beb6493108b90f3cbc71d34bdf1814613a54ab
 SHA512:
-  metadata.gz: 8bcf171950fd74de94c8118dabf3f911e8db3923ce4ed48463c505b3b5748bafbb9c39819b7af49841bf3ea3f6635e797c9536f5d845a42f0a9df9eb1018d1de
-  data.tar.gz: 2eb4d0d286b9daf4ed91e1d0d674c6835569ef3912a2712034fad27d31648c5eeed1e410f34fbfbec3d59808b5d82f178df84b896a233eaec570c3b24b6b52ab
+  metadata.gz: 9d65a4239a738367dd8b0536670b2f00cecfae7283db328c87308323fd19d8080fa13eed2a8910d7a0e67a2380f286c65d1b4c943a72bd1903f3d1695b2dfc18
+  data.tar.gz: f316b5892247e31b58a2531dd86073c812327e27bd36f5d4f020efd47d543e280b94ab513467d58a6445173106b89c1378716df471077ee7f1e35fe4bd0999d9

data/CHANGELOG.md

@@ -3,6 +3,133 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.13.0] - 2026-10-28
+
+### Breaking changes
+
+- `:last` is no longer accepted as an endpoint. It named the last version, whose
+  recorded state is the one *before* the latest change, so ranges ending there
+  silently left that change out. Omit `to:` to end at current state, or pass a
+  version. Passing `:last` raises with that advice.
+- `analyze_many` without `within:` now ends each record's history at its current
+  state, so the latest change is included. It previously stopped at the last
+  version.
+- Batch methods reject scoped associations, default-scoped targets, and
+  `has_many :through` associations whose source is not a `belongs_to`, because
+  they need queries per record. The error names the association. Pass
+  `allow_expensive: true` to accept that cost.
+- `Step#to_h` returns `{ from:, to:, diff: }`, the same shape as
+  `ActivityStep#to_h`, with boundary hashes on both sides. Read the version ids
+  from `from[:version_id]` and `to[:version_id]` instead of `from_version_id`
+  and `to_version_id`; `metadata: true` adds details to both boundaries.
+- `analyze_many` takes only an array of records. Use `analyze_scope` with a
+  model or relation; `analyze_many(scope:, limit:)` and the scoped options it
+  accepted have been removed.
+
+### Added
+
+- `report(scope, since:, limit:)` for recent activity through current state.
+- `historical_filter:` on `analyze_scope` and `report`, selecting records by
+  values they had at any point in the window: their state when it started and
+  after each change inside it. Pass an attribute hash, which reads stored values
+  without reifying, or a callable. `max_filter_versions:` (default 10,000) caps
+  the versions it loads and raises `FilterLimitExceededError` beyond that.
+- `include_deleted: true` on `analyze_scope` and `report`, returning analyses of
+  deleted records in `deleted` (`nil` when no destroy version was recorded).
+  Existing and deleted records together count toward `limit:`.
+- `ScopedAnalysis#roots`, the selected records in relation order.
+- `timeline`, `activity_timeline`, and `analyze` default to `from: :first` and
+  `to: record`, so `timeline(article)` covers the whole history through the
+  current saved record.
+- `source_boundary` on both step types names the event whose change a step
+  reports. For a transaction group it is the first event.
+- `metadata: true` on `to_h` for boundaries, steps, and analyses adds author,
+  event, transaction ID, and record. `ActivityStep#to_h(snapshots: true)` and
+  `Analysis#to_h(snapshots: true)` include retained states.
+- `group:` and `snapshots:` on `analyze_many` and `analyze_scope` with
+  `activity: true`.
+- Explicit current-record `to:` endpoints on `timeline` and `analyze`.
+
+### Changed
+
+- A `within:` window with no version after its last change closes on the current
+  record instead of raising `IncompleteTimeRangeError`. Nothing has been
+  recorded since that change, so the current record holds what it produced.
+  This also applies to windows in which only chosen associations changed.
+  `close_on: :current` is no longer needed and is still accepted.
+- Live-ended HABTM activity is rejected only when a range actually ends at the
+  current record, including in batches.
+- `compare` with `associations:` reads association state from the prepared
+  history `compare_many` uses, instead of PT-AT's timestamp-only reifier.
+- Plain recorded attributes of root and direct-child records are read without
+  building a model instance per historical state. Models with initialization
+  callbacks, custom types or defaults, default scopes, or encrypted attributes
+  still use PaperTrail's `reify`.
+- Batch activity reports share association discovery and prepared history
+  across records, and each analysis reuses its checkpoint snapshots, so standard
+  reports no longer add queries per record.
+- Activity without changesets uses prepared successor states instead of a query
+  per event.
+- `has_many :through` reconstruction visits only the requested source
+  association.
+- Scope selection keeps candidate records in a database subquery when
+  `versions.item_id` and the primary key share a column type, reads joined rows
+  in pages of 250, and sorts `unreachable`.
+- `snapshots: true` without `activity: true` raises `ConfigurationError`, as
+  `group:` already did, instead of being ignored.
+- The README is now a set of recipes; the full API reference and architecture
+  notes are separate pages.
+
+### Fixed
+
+- Association timelines no longer raise `duplicate record identity` when
+  `versions.item_id` is a string column (PaperTrail's setup for UUID keys) and
+  associated models use integer keys.
+- Columns listed in `has_paper_trail skip:` are left out of snapshots. PaperTrail
+  never stores them, so comparing history with the current record reported them
+  as changed from their default.
+- `analyze_many(..., activity: true)` reports association activity for a record
+  with no version of its own in the window, matching `analyze`. It previously
+  returned an empty analysis.
+- Histories stored with PaperTrail's JSON serializer or a `json`/`jsonb` object
+  column no longer report every timestamp as changed when compared with the
+  current record.
+- Association changes at versions sharing a timestamp are placed by version id,
+  so `compare`, `compare_many`, and `timeline` no longer put them on the wrong
+  side of a boundary. Ties that ids cannot order raise
+  `AmbiguousVersionOrderError`.
+- A window that closes on the record's deletion ends its `diff` and
+  `to_snapshot` at "no record". A record created and deleted inside the window
+  previously read as added.
+- `compare_many` resolves `:first` to each record's earliest version by time,
+  not the lowest id, which differs for UUID version ids.
+- `version_scope:` is honored on activity timelines that end at the current
+  record.
+- Batch, single-record, and scoped activity results agree on the reporting
+  window and closing state.
+- A lone creation or update in an activity window that ends at the current
+  record is reported.
+- Joined relations count unique records against `limit:` without adding SQL
+  `DISTINCT`, so ordering by joined columns works on PostgreSQL and SQL Server.
+- Nested results are fully frozen, including nested paths and empty results.
+- Nested object diffs match string and symbol keys consistently and raise
+  `AmbiguousNestedKeyError` on collisions instead of losing a change.
+
+### Development
+
+- CI runs both suites on PostgreSQL 17, MySQL 8.4, and SQL Server 2022 alongside
+  the SQLite Ruby/PaperTrail matrix. Database adapters are optional development
+  dependencies.
+- The type-check gate fails on Steep internal errors and checks public API call
+  examples.
+- RuboCop runs with the rubocop-performance and rubocop-rspec plugins.
+- Consistency specs check that every method agrees on seeded, generated
+  histories across schema and serializer variants.
+- Mutation testing with mutant covers the comparison code, in CI and through
+  `rake mutant`. New specs close the gaps it found: attributes present on only
+  one side, a record removed, singular relationships added or removed, and
+  JSON values held in Hash, Array, or String subclasses.
+
 ## [0.12.0] - 2026-08-19
 
 ### Changed

data/QUICKSTART.md

@@ -1,11 +1,16 @@
 # 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.
+This guide sets up PaperTrail, saves a few versions of an article, and reads
+its changes with `paper_trail_diff`. You need Ruby, Bundler, and Rails installed.
+The gem supports Ruby 3.1+ with PaperTrail 16 or 17; your Rails and PaperTrail
+versions may require a newer Ruby.
 
-Every command and console snippet below is meant to be run in order against a
-scratch application, so nothing here assumes models you already have:
+Already using PaperTrail? Skip the setup and use your own model in
+[Create a little history](#3-create-a-little-history).
+
+Otherwise, start with a new Rails application. Run the following examples in
+order. Commands run in your terminal; Ruby examples run in the Rails console
+unless a file path is shown:
 
 ```console
 rails new diff-demo --minimal
@@ -27,13 +32,14 @@ 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.
+table. `--with-changes` adds `object_changes`, which PaperTrail uses for
+`version.changeset`. Keep it if you want PaperTrail to store the changed values
+for each event. This gem can also compare the full earlier records saved in
+PaperTrail's `object` column.
 
 ## 2. Version a model
 
-Create the model this guide uses, then declare it versioned:
+Create an article model and tell PaperTrail to track its changes:
 
 ```console
 bin/rails generate model Article title:string
@@ -47,7 +53,7 @@ class Article < ApplicationRecord
 end
 ```
 
-Restart the Rails console after changing the Gemfile or an initializer.
+Restart the Rails console after changing dependencies, model configuration, or an initializer.
 
 ## 3. Create a little history
 
@@ -64,8 +70,8 @@ article.update!(title: "Final")
 published_version = article.versions.last
 ```
 
-The variable names are intentional. PaperTrail versions contain the state
-*before* their event:
+PaperTrail saves the record's values **before** each change. Its public
+`reify` method builds an earlier record from a version:
 
 ```ruby
 draft_version.reify.title     # => "Draft"
@@ -93,13 +99,18 @@ diff.to_h
 # }
 ```
 
-`compare` reports only the net difference between its endpoints. It does not
-report intermediate changes.
+Pass the PaperTrail versions themselves to `compare`; you do not need to call
+`reify` first. The result has one entry per changed attribute, with `from` and
+`to` values. Unchanged attributes are left out.
+
+`compare` reports the net difference between the two records. For every change
+in between, use `timeline`, shown below. Reading a diff does not save or modify
+any record.
 
 ### Compare a version with current state
 
-Pass the persisted record explicitly when the second endpoint should be the
-current database state:
+Pass `article` instead of a second version to compare with its current saved
+values:
 
 <!-- executable:quickstart-current -->
 ```ruby
@@ -108,12 +119,13 @@ 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.
+The article must still exist in the database and have no unsaved changes.
+The gem reloads it before comparing. `article.versions.last` is different: it
+contains the values from before the latest recorded change.
 
-## 5. Build a checkpoint timeline
+## 5. Read changes between versions
 
-Create one more historical endpoint:
+Save another change so PaperTrail records the previous title, `"Final"`:
 
 <!-- executable:quickstart-timeline-state -->
 ```ruby
@@ -121,7 +133,7 @@ article.update!(title: "Archived")
 final_version = article.versions.last # reifies to "Final"
 ```
 
-Then compare every adjacent root version:
+Read the changes between each pair of article versions:
 
 <!-- executable:quickstart-timeline -->
 ```ruby
@@ -140,13 +152,17 @@ end
 visible_steps = steps.reject(&:empty?)
 ```
 
-Empty steps remain in the timeline. Filter them only when the application's
-display does not need every version boundary.
+Each item in `steps` has a `diff`, just like the comparison above. Steps with
+no reported changes are kept; `reject(&:empty?)` removes them for display.
 
-### Select mutations by time
+Without `from:` and `to:`, `PaperTrailDiff.timeline(article)` reads the whole
+history through the current saved article, including the change to
+`"Archived"`. Pass a version as `to:` when the result should stay the same after
+later edits.
 
-Use `within:` when the application has a reporting window rather than saved
-endpoint versions:
+### Select changes by time
+
+Use `within:` to choose changes by their PaperTrail version's `created_at`:
 
 <!-- executable:quickstart-time-range -->
 ```ruby
@@ -160,28 +176,72 @@ end
 # => [["Draft", "Published"], ["Published", "Final"]]
 ```
 
-The half-open range selects the mutations recorded by `draft_version` and
-`published_version`. The excluded `final_version` is still used as the trailing
-boundary needed to reveal the last selected mutation. PaperTrail versions are
-pre-change snapshots, so a range containing mutations must have a later root
-version. The gem raises `PaperTrailDiff::IncompleteTimeRangeError` instead of
-assuming that the current record is the missing endpoint.
+Ruby's `...` excludes the end of the range. Here the selected versions are
+`draft_version` and `published_version`.
 
-## 6. Choose the right API
+Each PaperTrail version stores the values **before** its own change, so the
+values after the window's last change are in the next version, `final_version`.
+The gem reads that version even though it is outside the window. When no later
+version exists, nothing has been recorded since, and the gem reads the current
+saved article instead.
 
-| Need | Call |
-| --- | --- |
-| Net difference between two endpoints | `compare` |
-| Net differences for many current records | `compare_many` |
-| 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` |
+### Report through now
+
+To report on many articles, pass a model or ActiveRecord relation to `report`.
+It includes changes from `since:` through now:
+
+```ruby
+report = PaperTrailDiff.report(
+  Article.all, since: 1.day.ago, limit: 100, include_deleted: true
+)
+report.analyses # Hash: [model name, ID string] => report for an existing record
+report.deleted # Same keys for deleted records; nil if no destroy version was saved
+report.analyses.each_value { |analysis| analysis.diff.to_h }
+```
+
+`limit: 100` is a safety ceiling. If more than 100 existing and deleted articles
+are selected, the call raises instead of returning a partial report. Omit
+`include_deleted:` if you only need articles that still exist.
+
+An article needs its own PaperTrail version in the time window to be selected.
+Editing a comment alone does not select its article. A relation's `where`
+conditions check current values; they cannot check a deleted article's values.
+
+For one article, use a window ending now:
+
+<!-- executable:quickstart-current-window -->
+```ruby
+current_steps = PaperTrailDiff.timeline(article, within: 1.day.ago..Time.current)
+```
 
-`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.
+The same `within:` option works on `activity_timeline`, `analyze`,
+`analyze_many`, and `analyze_scope`.
 
-## 7. Ignore noise fields
+## 6. Choose a method
+
+| What you need | Method |
+| --- | --- |
+| Net difference between two versions, or a version and the current record | `compare(from, to)` |
+| The same for a list of `{ from:, to: }` pairs, one per record | `compare_many(pairs)` |
+| Each change to one record, version by version | `timeline(record)` |
+| Each change to one record and its chosen associations, with who made it | `activity_timeline(record, associations: ...)` |
+| Net difference and timeline together | `analyze(record)` |
+| The same, plus the activity timeline | `analyze(record, activity: true)` |
+| Analyses for an array of records | `analyze_many(records)` |
+| Analyses for the records a relation selects, over a time window | `analyze_scope(scope, within:, limit:)` |
+| Recent activity through now, for the records a relation selects | `report(scope, since:, limit:)` |
+
+Use the batch methods for many records so they can share database queries.
+Some scoped associations and `has_many :through` histories still need queries
+for each record. Batch calls reject those with `UnsupportedBatchPathError`.
+The error names the association. `allow_expensive: true` permits that extra work;
+see the [performance guide](docs/performance.md) before using it in a large report.
+
+When associations are included, `timeline` compares their values at the article's
+versions. `activity_timeline` also reports the comments' own version events, even
+when the article was not edited. The next section on associations shows this.
+
+## 7. Choose fields to ignore
 
 `updated_at` is ignored by default. Passing `ignore:` replaces that default:
 
@@ -196,16 +256,16 @@ PaperTrailDiff.compare(
 PaperTrailDiff.compare(
   draft_version,
   published_version,
-  ignore: [] # compare every available scalar attribute
+  ignore: [] # include updated_at too
 )
 ```
 
-See the main README for exact path-specific ignore rules.
+See the [API reference](docs/reference.md) to ignore different fields on different associations.
 
 ## 8. Add association history when needed
 
-Associations are optional. Add PT-AT only when the application needs historical
-association reconstruction:
+To compare an article's earlier comments, install the optional
+`paper_trail-association_tracking` plugin (called PT-AT in the reference):
 
 ```console
 bundle add paper_trail-association_tracking
@@ -214,14 +274,18 @@ bin/rails db:migrate
 ```
 
 The generator creates `version_associations` and enables
-`PaperTrail.config.track_associations`. This section also needs a second model:
+`PaperTrail.config.track_associations` in an initializer. If your application
+already has that initializer, check that it contains
+`PaperTrail.config.track_associations = true`.
+
+Add a comment model:
 
 ```console
 bin/rails generate model Comment article:references body:string
 bin/rails db:migrate
 ```
 
-Every model whose historical state is needed must be versioned:
+Add `has_paper_trail` to both models so their earlier values are recorded:
 
 ```ruby
 class Article < ApplicationRecord
@@ -235,7 +299,14 @@ class Comment < ApplicationRecord
 end
 ```
 
-Take an explicit root checkpoint before the example change:
+The article option `synchronize_version_creation_timestamp: false` lets
+manually saved versions record the time they were taken. Restart the console
+after this setup and reload your article with `article = Article.first!`.
+
+Use PaperTrail's `paper_trail.save_with_version` to save an article version even
+though none of its attributes changed. That gives the comparison a starting
+point before adding the comment. The transaction also records the information
+needed for association history:
 
 <!-- executable:quickstart-association -->
 ```ruby
@@ -257,7 +328,7 @@ diff.associations["comments"].added.first.attributes["body"]
 # => "First comment"
 ```
 
-Nested paths are explicit and bounded:
+If your models also define `replies` and `author`, name those associations to include them:
 
 ```ruby
 diff = PaperTrailDiff.compare(
@@ -267,7 +338,7 @@ diff = PaperTrailDiff.compare(
 )
 ```
 
-To see versioned child events without touching the article after each change:
+To show the comment creation as its own activity step, without updating the article:
 
 <!-- executable:quickstart-activity -->
 ```ruby
@@ -279,47 +350,46 @@ steps = PaperTrailDiff.activity_timeline(
 )
 
 steps.reject(&:empty?).each do |step|
-  boundary = step.to_boundary
-  puts "#{boundary.item_type} ##{boundary.item_id}"
+  source = step.source_boundary
+  puts "#{source.item_type} ##{source.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.
-
-For a historical reporting window, replace `from:` and `to:` with `within:`:
+`source_boundary` describes the version responsible for a step. Its `item_type`
+and `item_id` are PaperTrail's model name and record ID. It also exposes the
+version's `whodunnit` and `event`. See the README for a feed using these values.
 
-```ruby
-steps = PaperTrailDiff.activity_timeline(
-  article,
-  within: report_start...report_end,
-  associations: ["comments"]
-)
-```
+To keep the result fixed after later edits, save another article version with
+`paper_trail.save_with_version` inside a transaction, then pass that version
+instead of `to: current`.
 
-This selects versioned comment activity directly, even if the article had no
-mutation during the window. Take a root checkpoint after `report_end`; it gives
-the gem the historical context needed to expose the final child mutation.
+You can also pass `within: start_time...end_time`. This single-article method
+includes comment changes even if the article was not edited in that period.
+Unlike this method, a relation-based `report` needs an article version in the
+window to select that article.
 
 ## 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.
-- A `within:` window containing mutations needs a later root checkpoint. The
-  trailing version is reconstruction context and may appear as a step's ending
-  boundary even though its own mutation is outside the window.
+- `article.versions.last.reify` gives the article **before** its latest recorded
+  change. Pass `article` to read the current saved values.
+- PaperTrail's creation version returns `nil` from `reify`. There was no record
+  before creation; the diff reports the record being added.
+- A range ending at the current article includes changes PaperTrail never
+  recorded, such as `update_columns`. Pass a version as `to:` to stop at
+  recorded history.
 - `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.
+- Only the associations listed in `associations:` are included. Asking for
+  comments does not automatically include every association on each comment.
 - 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).
+For association support, performance, error handling, ignore rules, and all
+available result methods, see the
+[API reference](docs/reference.md). For complete activity-feed and batch-report
+recipes, including deleted records, see the [README](README.md).
 
 Upstream setup references:
 [PaperTrail installation](https://github.com/paper-trail-gem/paper_trail#1b-installation)