paper_trail_diff 0.13.1 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +630 -0
- data/QUICKSTART.md +30 -10
- data/README.md +91 -13
- data/docs/architecture.md +62 -18
- data/docs/performance.md +116 -298
- data/docs/reference.md +554 -102
- data/docs/testing.md +93 -14
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
- data/lib/paper_trail_diff/activity_boundary.rb +83 -26
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
- data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
- data/lib/paper_trail_diff/activity_event.rb +41 -10
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
- data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
- data/lib/paper_trail_diff/activity_history.rb +34 -9
- data/lib/paper_trail_diff/activity_range.rb +32 -5
- data/lib/paper_trail_diff/activity_relationship.rb +12 -0
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
- data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
- data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
- data/lib/paper_trail_diff/activity_view.rb +69 -0
- data/lib/paper_trail_diff/analysis.rb +13 -1
- data/lib/paper_trail_diff/analysis_batch.rb +24 -30
- data/lib/paper_trail_diff/approximate_paths.rb +48 -0
- data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
- data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
- data/lib/paper_trail_diff/association_discovery.rb +14 -11
- data/lib/paper_trail_diff/association_key.rb +56 -0
- data/lib/paper_trail_diff/association_traversal.rb +180 -47
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
- data/lib/paper_trail_diff/batch_preload.rb +53 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
- data/lib/paper_trail_diff/change_row.rb +133 -0
- data/lib/paper_trail_diff/collection_comparator.rb +5 -32
- data/lib/paper_trail_diff/comparison_batch.rb +37 -10
- data/lib/paper_trail_diff/configuration.rb +35 -12
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
- data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
- data/lib/paper_trail_diff/deprecation.rb +61 -0
- data/lib/paper_trail_diff/diagnostics.rb +105 -102
- data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
- data/lib/paper_trail_diff/endpoint.rb +26 -3
- data/lib/paper_trail_diff/errors.rb +5 -2
- data/lib/paper_trail_diff/fallback_paths.rb +38 -0
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
- data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
- data/lib/paper_trail_diff/historical_filter.rb +19 -10
- data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
- data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
- data/lib/paper_trail_diff/nested_comparator.rb +19 -18
- data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
- data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
- data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
- data/lib/paper_trail_diff/prepared_history.rb +70 -53
- data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
- data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
- data/lib/paper_trail_diff/recorded_changes.rb +83 -0
- data/lib/paper_trail_diff/recorded_class.rb +53 -0
- data/lib/paper_trail_diff/root_version_selection.rb +4 -2
- data/lib/paper_trail_diff/scope_condition.rb +386 -0
- data/lib/paper_trail_diff/scope_ranking.rb +206 -0
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
- data/lib/paper_trail_diff/snapshot.rb +16 -1
- data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
- data/lib/paper_trail_diff/support.rb +38 -6
- data/lib/paper_trail_diff/time_range.rb +37 -18
- data/lib/paper_trail_diff/time_version_range.rb +5 -5
- data/lib/paper_trail_diff/timeline_builder.rb +7 -7
- data/lib/paper_trail_diff/timeline_range.rb +9 -1
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
- data/lib/paper_trail_diff/transaction_cut.rb +181 -0
- data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
- data/lib/paper_trail_diff/version_boundary.rb +37 -8
- data/lib/paper_trail_diff/version_query.rb +34 -10
- data/lib/paper_trail_diff/version_range.rb +8 -15
- data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
- data/lib/paper_trail_diff/version_table.rb +60 -0
- data/lib/paper_trail_diff.rb +126 -55
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
- data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
- data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
- data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
- data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
- data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
- data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
- data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
- data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
- data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
- data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
- data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
- data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
- data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
- data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
- data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
- data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
- data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
- data/sig/generated/paper_trail_diff/errors.rbs +5 -2
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
- data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
- data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
- data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
- data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
- data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
- data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
- data/sig/generated/paper_trail_diff/support.rbs +20 -2
- data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
- data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
- data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
- data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
- data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
- data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
- data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
- data/sig/generated/paper_trail_diff.rbs +47 -25
- metadata +62 -10
- data/lib/paper_trail_diff/activity_grouping.rb +0 -38
- data/lib/paper_trail_diff/batch_safety.rb +0 -55
- data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
- data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
- data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
- data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 4cc17a3d2f233d6f9bcc44605687ef4cabf1611f957ad41d0471b35236b8ab8d
|
|
4
|
+
data.tar.gz: e123b779da0c52350cb05b4ed18f8585626d8cbcf45e3c737cfe43777f7bcf14
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 65f32e4a83fd05ba8cfece667be5842d41f9452ae84f49f495ff8ad0051b87c76ebddfb07c1a99c09227689eaa393286ca0737042bf6b6f7c6dffea0b77039bf
|
|
7
|
+
data.tar.gz: 217119550346fc0eed08759dd20aa1a2fb53bd71dde161e43ef1243f191159fc7c1225924a6c39059dda8e2df4c4b17f0f1abed694938a2824a89e722e88e0d7
|
data/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,636 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file. The
|
|
4
4
|
project follows [Semantic Versioning](https://semver.org/).
|
|
5
5
|
|
|
6
|
+
## [0.15.0] - 2026-10-31
|
|
7
|
+
|
|
8
|
+
### Breaking changes
|
|
9
|
+
|
|
10
|
+
- An association whose model keeps its versions, or its PT-AT version
|
|
11
|
+
associations, in different tables than its owner's raises
|
|
12
|
+
`UnsupportedAssociationError` in every method, and `association_paths`
|
|
13
|
+
leaves it out. History read through it was wrong: PT-AT records a child's
|
|
14
|
+
membership with the child's versions but reads it from the owner's tables,
|
|
15
|
+
so a child that moved to another owner was never reported as removed, and a
|
|
16
|
+
root with its own version table raised `ActiveRecord::StatementInvalid`.
|
|
17
|
+
|
|
18
|
+
- An association keyed on a column other than a primary key
|
|
19
|
+
(`primary_key: :legacy_id`), or a `has_many :through` with such a part,
|
|
20
|
+
raises `UnsupportedAssociationError` up front in every method, and
|
|
21
|
+
`association_paths` leaves it out. PT-AT records which record a child
|
|
22
|
+
pointed at by that record's ID, and history matched children by ID, so an
|
|
23
|
+
article's history showed another article's comments, and a comment's past
|
|
24
|
+
article was the wrong one. Comparisons against the current record were
|
|
25
|
+
right, so the same range disagreed with itself.
|
|
26
|
+
- An association path history cannot read, such as one with a scope written
|
|
27
|
+
as SQL text, a scope that takes the owner, or a condition on a string
|
|
28
|
+
column on MySQL or SQL Server, raises `UnsupportedAssociationError` in every
|
|
29
|
+
method that reads history, unless you pass the new `allow_approximate: true`.
|
|
30
|
+
The gem reads such a path with PT-AT, which rebuilds an association from its
|
|
31
|
+
current members and never checks the scope against them: a record that
|
|
32
|
+
entered the scope since was reported as a member it was not, so a comment
|
|
33
|
+
moved into `-> { where("position > 2") }` showed as changed rather than
|
|
34
|
+
added. Single-record methods did this without warning, and batch methods
|
|
35
|
+
described it only as costly.
|
|
36
|
+
- `include_deleted: true` keeps only the deleted records that met the
|
|
37
|
+
relation's conditions when they were destroyed, in both `deleted` and
|
|
38
|
+
`unreachable`. It returned every deleted record of the model that changed in
|
|
39
|
+
the window, so a report on one account's articles included other accounts'
|
|
40
|
+
deleted articles with their contents. The relation's conditions must be
|
|
41
|
+
plain conditions on the model's own columns; a join or SQL text raises
|
|
42
|
+
`ConfigurationError`.
|
|
43
|
+
|
|
44
|
+
### Added
|
|
45
|
+
|
|
46
|
+
- `diagnose` reports every reason `compare` would refuse the same request as
|
|
47
|
+
an error, with `compare`'s message, so `ok?` is false whenever `compare`
|
|
48
|
+
would refuse. It said `ok?` for a path `compare` reads only approximately,
|
|
49
|
+
such as a scope written as SQL text, raised on an unknown or unsupported
|
|
50
|
+
association instead of reporting it, and checked only the join model a
|
|
51
|
+
`has_many :through` goes through first, not every model it reads. It
|
|
52
|
+
takes `allow_approximate:`, and with `true` reports such a path as an
|
|
53
|
+
`:approximate_association` warning. The new error codes are
|
|
54
|
+
`:unknown_association`, `:unsupported_association`, and
|
|
55
|
+
`:approximate_association`; an unversioned target's message now matches
|
|
56
|
+
`compare`'s.
|
|
57
|
+
|
|
58
|
+
- `diagnose` takes the current record as either endpoint, as `compare` does,
|
|
59
|
+
so `compare(version, record)` can be checked before it runs. Its version
|
|
60
|
+
checks then run from the version to the latest one. An endpoint that is
|
|
61
|
+
neither a version nor a saved record raises `InvalidEndpointError` naming
|
|
62
|
+
that, rather than `VersionMismatchError`.
|
|
63
|
+
|
|
64
|
+
- Activity steps list the events whose changes they show as `step.sources`,
|
|
65
|
+
oldest first. A step from `group: :transaction` lists every event in the
|
|
66
|
+
transaction, each with its own author, record, and version ID, where
|
|
67
|
+
`source_boundary` names only the first. `to_h(metadata: true)` adds a
|
|
68
|
+
`sources` list.
|
|
69
|
+
- `recorded_changes: true` on `activity_timeline`, on `analyze`, `analyze_many`,
|
|
70
|
+
and `analyze_scope` with `activity: true`, and on `report` gives each
|
|
71
|
+
boundary the changes its version recorded, as `recorded_changes(version)`
|
|
72
|
+
returns them. The versions are already loaded, so it adds no queries, and it
|
|
73
|
+
replaces the reference recipe that loaded every step's version again.
|
|
74
|
+
Without the option, `boundary.recorded_changes` raises `ConfigurationError`
|
|
75
|
+
rather than returning `nil`. Names in `ignore:` or `ignore: { all: }` are
|
|
76
|
+
left out, and so are names on the root path, `"$"`, for the root's own
|
|
77
|
+
versions. Names on an association path are not, because a child's version
|
|
78
|
+
does not say which path reached it.
|
|
79
|
+
- `change_rows` on an activity step, on an `Analysis` built with
|
|
80
|
+
`activity: true`, and on a `report` or `analyze_scope` result flattens
|
|
81
|
+
activity into `ChangeRow` objects: one per edited field, and one per record
|
|
82
|
+
that appeared or disappeared followed by its fields. Each names its record,
|
|
83
|
+
association path, and source version, and `to_h` gives a flat hash. It
|
|
84
|
+
replaces the README recipe for turning a report into rows, which had no rows
|
|
85
|
+
for whole records, so a record added or removed with only blank fields left
|
|
86
|
+
no trace.
|
|
87
|
+
|
|
88
|
+
- `associations:` takes what `includes` takes: a single name
|
|
89
|
+
(`associations: :comments`) or hashes of names to what to include below them
|
|
90
|
+
(`associations: [:author, { comments: :replies }]`), as well as the arrays of
|
|
91
|
+
names and dotted paths it took before.
|
|
92
|
+
|
|
93
|
+
- `nested_changes` compares two top-level arrays, as a `json` column can hold,
|
|
94
|
+
and reports one `ArrayChange` at the empty path, `[]`. It returned `{}`,
|
|
95
|
+
although arrays nested in an object were compared.
|
|
96
|
+
|
|
97
|
+
### Changed
|
|
98
|
+
|
|
99
|
+
- The reference describes how PT-AT records HABTM membership and how the gem
|
|
100
|
+
credits it. A change made between two root versions is credited to the
|
|
101
|
+
step after the earlier one, so a checkpoint's capture is credited to whoever
|
|
102
|
+
saved the version before it; a checkpoint just before the change as well
|
|
103
|
+
credits it to its author. Only the first version an instance saves after
|
|
104
|
+
changing a HABTM is right; PT-AT never forgets the instance's changes, not
|
|
105
|
+
even on `reload`. A later save from it records the old membership, and the
|
|
106
|
+
gem reports members removed and added again that never left.
|
|
107
|
+
|
|
108
|
+
- The performance guide describes current behavior instead of logging each
|
|
109
|
+
past change: what the batch methods cost, what still grows with a report,
|
|
110
|
+
the version indexes, what costs a query per record, historical filters,
|
|
111
|
+
large reports, and how to measure. Its measurements were taken again. The
|
|
112
|
+
earlier ones remain in `benchmark/results/` and in the changelog.
|
|
113
|
+
|
|
114
|
+
- `historical_filter:` reads the history of the relation's records only, and
|
|
115
|
+
of deleted records, which a relation cannot test. It read every record of
|
|
116
|
+
the model that changed in the window, so a report on one account's articles
|
|
117
|
+
raised `BatchLimitExceededError` when another account had more matching
|
|
118
|
+
articles than `limit:`, and spent `max_filter_versions:` on their versions.
|
|
119
|
+
Matching deleted records no longer count toward `limit:` unless
|
|
120
|
+
`include_deleted: true` is given, as without a filter.
|
|
121
|
+
|
|
122
|
+
- The reference says how a record created without a version, such as one
|
|
123
|
+
imported with `insert_all`, and history pruned with `has_paper_trail
|
|
124
|
+
limit:` read.
|
|
125
|
+
|
|
126
|
+
- `IncompleteTimeRangeError` no longer advises the deprecated
|
|
127
|
+
`close_on: :current`. The quickstart and performance guide no longer say
|
|
128
|
+
that `has_many :through` or limited associations need the opt-ins, and the
|
|
129
|
+
reference says that `association_paths` lists paths that need
|
|
130
|
+
`allow_approximate: true`.
|
|
131
|
+
|
|
132
|
+
- The quickstart sets PaperTrail's `yaml_column_permitted_classes`. In a new
|
|
133
|
+
Rails 8.1 app, versions hold timestamps as `ActiveSupport::TimeWithZone`,
|
|
134
|
+
and the quickstart's first `reify` raised `Psych::DisallowedClass` without
|
|
135
|
+
it. Its documentation spec now reads a version in that form.
|
|
136
|
+
|
|
137
|
+
- The README and architecture guide recommend a second version index,
|
|
138
|
+
`(item_type, created_at, item_id)`. Batch methods with `since:` or
|
|
139
|
+
`within:` find changed records by type and time, which the one index they
|
|
140
|
+
recommended cannot narrow, so each report read every version of the model:
|
|
141
|
+
about 230 ms instead of 2 ms on PostgreSQL with 5 million versions.
|
|
142
|
+
- The gemspec requires Active Record 7.1 to 8.1. CI tests 7.2 through 8.1,
|
|
143
|
+
and the suite passes on 7.1. It named only PaperTrail, so Bundler could
|
|
144
|
+
install the gem with Active Record 6.1 or 7.0, whose relations and Arel
|
|
145
|
+
nodes the gem reads differently.
|
|
146
|
+
- `close_on:` is deprecated and warns through the new
|
|
147
|
+
`PaperTrailDiff.deprecator`. It has had no effect since a window began
|
|
148
|
+
closing on the current record by default; remove it. In a Rails app,
|
|
149
|
+
register the deprecator with
|
|
150
|
+
`Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator`.
|
|
151
|
+
- `allow_expensive:` is deprecated and has no effect. It refused exactly the
|
|
152
|
+
paths `allow_approximate:` refuses, so batch methods needed both or
|
|
153
|
+
neither; `allow_approximate: true` alone now accepts such a path in every
|
|
154
|
+
method, and `UnsupportedBatchPathError` is no longer raised. Batch methods
|
|
155
|
+
refuse such a path before their first query, as before, now with
|
|
156
|
+
`UnsupportedAssociationError`.
|
|
157
|
+
- `reload_live_endpoints:` is deprecated and warns. It still works until it
|
|
158
|
+
is removed. Skipping the reload saves a query for the records and one per
|
|
159
|
+
association level in each call, 2 for 500 articles with their comments,
|
|
160
|
+
and reads values from objects that may be stale; it also needs every
|
|
161
|
+
requested association loaded, and reads limited ones again anyway. It was
|
|
162
|
+
on `compare`, `compare_many`, and `activity_timeline` only. Remove it.
|
|
163
|
+
|
|
164
|
+
### Fixed
|
|
165
|
+
|
|
166
|
+
- A HABTM member created in the same transaction as the checkpoint that
|
|
167
|
+
records it is a member at that checkpoint, as a member attached there
|
|
168
|
+
already was. It was left out, because it had no state before the
|
|
169
|
+
transaction, so the checkpoint missed it and a comparison from the
|
|
170
|
+
checkpoint to now reported it added.
|
|
171
|
+
|
|
172
|
+
- `association_paths` leaves out an association whose target, or a model its
|
|
173
|
+
`has_many :through` goes through, has no `has_paper_trail`, such as the
|
|
174
|
+
`file_attachment` and `file_blob` that `has_one_attached` defines. Every
|
|
175
|
+
request that reads history refused them with `UnversionedAssociationError`,
|
|
176
|
+
so a settings screen built from the list offered paths that always failed.
|
|
177
|
+
|
|
178
|
+
- `diagnose` reports `:tied_version_timestamps`, and `compare` emits
|
|
179
|
+
`ambiguous_association_boundary.paper_trail_diff`, only when the request can
|
|
180
|
+
read a path with PT-AT: one history reads only approximately, a composite
|
|
181
|
+
foreign key, or a polymorphic `belongs_to`. PT-AT places association changes
|
|
182
|
+
by timestamp alone. For every other path, since 0.14.0, versions that share a
|
|
183
|
+
timestamp are ordered by ID, so a change between them is reported, yet both
|
|
184
|
+
warned that it could not be detected. A request refused for a path PT-AT
|
|
185
|
+
would read now raises before the notification.
|
|
186
|
+
|
|
187
|
+
- `timeline`, `activity_timeline`, and `analyze` read every version of a
|
|
188
|
+
model whose versions association has a scope
|
|
189
|
+
(`has_paper_trail versions: { scope: }`), as the other methods already did.
|
|
190
|
+
They read only the versions the scope kept, so a change saved in a version
|
|
191
|
+
it left out was credited to the next one kept: with a bot's edits hidden,
|
|
192
|
+
an editor's step showed the bot's later edit too, and the same record and
|
|
193
|
+
window gave different steps in `analyze` and `analyze_many`. A version the
|
|
194
|
+
scope leaves out is also accepted as an endpoint. To report only some
|
|
195
|
+
changes, pass `version_scope:`.
|
|
196
|
+
|
|
197
|
+
- Activity steps leave out the versions a record saved while it was outside
|
|
198
|
+
the root's tree. A comment edited on another article, then moved to this
|
|
199
|
+
one, brought that edit into the article's timeline as a step, and a
|
|
200
|
+
transaction group's `sources` listed it. Saved together with a comment added
|
|
201
|
+
to the article, the edit took the credit for the addition. The same went for
|
|
202
|
+
a comment edited after it moved away or left a scope, and for an author
|
|
203
|
+
renamed after the article changed authors. A version now counts when its
|
|
204
|
+
record is in the tree before or after its transaction. The versions of a
|
|
205
|
+
`has_many :through`'s join rows are all still kept.
|
|
206
|
+
|
|
207
|
+
- `timeline`, `activity_timeline`, `analyze`, and `analyze_many` raise
|
|
208
|
+
`InvalidEndpointError` naming what they were given when it is not a record
|
|
209
|
+
of a versioned model, such as `nil`, a model class, a relation, or a
|
|
210
|
+
version. They raised a bare `NoMethodError`, or said to provide `from` and
|
|
211
|
+
`to`. `report` names `since` when it is `nil` or a range.
|
|
212
|
+
|
|
213
|
+
- A scope ordered by a datetime, such as
|
|
214
|
+
`-> { order(created_at: :desc, id: :desc).limit(3) }`, is read from history
|
|
215
|
+
under Rails' default time-zone-aware attributes. Rails wraps those
|
|
216
|
+
attributes' types, which hid the datetime, so every method raised
|
|
217
|
+
`UnsupportedAssociationError` for the documented recipe.
|
|
218
|
+
|
|
219
|
+
- A `Date` bound of `within:` or `since:` is a whole day in `Time.zone`, and
|
|
220
|
+
a string a time in `Time.zone`, or in UTC without one. They were read in
|
|
221
|
+
the server's own zone, so the same window covered different hours on
|
|
222
|
+
different servers, and a same-day `Date..Date` window covered one instant
|
|
223
|
+
and found nothing.
|
|
224
|
+
|
|
225
|
+
- A `has_many :through` whose join model is not versioned raises
|
|
226
|
+
`UnversionedAssociationError` naming the join model when its history is
|
|
227
|
+
read, and `diagnose` reports it as an error, so `ok?` is false. A
|
|
228
|
+
comparison raised a bare `KeyError` while `diagnose` reported only a
|
|
229
|
+
warning.
|
|
230
|
+
|
|
231
|
+
- `reload_live_endpoints: false` reads an association with a `limit` or
|
|
232
|
+
`offset`, directly or in a part it goes through, or a scope that takes the
|
|
233
|
+
owner, again for each record. Active Record's `preload` applies the limit across all the records
|
|
234
|
+
it loads, so with three articles preloaded, two kept one comment each and
|
|
235
|
+
the third none, and their unchanged comments were reported as removed.
|
|
236
|
+
|
|
237
|
+
- A root and its associations that share one version table other than
|
|
238
|
+
PaperTrail's `versions` can be compared. Association lookups joined PT-AT's
|
|
239
|
+
version associations to the `versions` table whatever table the versions
|
|
240
|
+
were in, so every method raised `ActiveRecord::StatementInvalid`.
|
|
241
|
+
|
|
242
|
+
- A `within:` or `since:` window whose edge falls inside a transaction that
|
|
243
|
+
saved a version of the root record reports the whole transaction in the
|
|
244
|
+
later window. A window starting between a comment edit and the `touch: true`
|
|
245
|
+
article version saved with it showed the edit at the article's next change,
|
|
246
|
+
credited to that change's author, and the window ending there left it out;
|
|
247
|
+
when the article saved first, its version was in one window and the comment
|
|
248
|
+
edit in the other. Each root's edges move back to the transaction's start,
|
|
249
|
+
read in a fixed number of queries per batch.
|
|
250
|
+
|
|
251
|
+
- `activity_timeline`, and `analyze` with `activity: true`, no longer report a
|
|
252
|
+
child version saved in the same transaction as the root version that ends
|
|
253
|
+
the range. A `touch: true` parent version is saved this way after every
|
|
254
|
+
child save. PT-AT rebuilds the parent's associations at that version as they
|
|
255
|
+
were before the transaction, so the child's step was always empty and its
|
|
256
|
+
change was reported nowhere. The range now ends before that transaction, as
|
|
257
|
+
`compare` and `timeline` already did. End at a later version or at the
|
|
258
|
+
current record to include the change, with `group: :transaction` to credit it
|
|
259
|
+
to the child's version.
|
|
260
|
+
- A range that starts at a version now starts before that version's
|
|
261
|
+
transaction, as one that ends there already ended. A child version saved
|
|
262
|
+
earlier in the same transaction, such as the update behind a `touch: true`
|
|
263
|
+
parent version, was read after its change, so `compare`, `analyze`,
|
|
264
|
+
`timeline`, and `activity_timeline` from that version left the change out.
|
|
265
|
+
It was also missing from the range ending there, so a history split at that
|
|
266
|
+
version reported it nowhere. It is now inside the range that starts there.
|
|
267
|
+
- A past `within:` window in `activity_timeline`, and in `analyze`,
|
|
268
|
+
`analyze_many`, `analyze_scope`, and `report` with `activity: true`, no
|
|
269
|
+
longer includes association changes made after it. When the root had no
|
|
270
|
+
version after the window, the window closed on current state, so a comment
|
|
271
|
+
edited in August appeared in a July window, in its last step, `to_snapshot`,
|
|
272
|
+
and `diff`; with a later root version the same window was right. It now
|
|
273
|
+
closes on current state only when nothing on a requested path was recorded
|
|
274
|
+
after it. The reasoning in 0.8.0, that nothing had been recorded since,
|
|
275
|
+
checked only the root's own versions. `timeline`, and `analyze` without
|
|
276
|
+
`activity:`, still run their last step to the root's next version or the
|
|
277
|
+
current record; the reference now says so.
|
|
278
|
+
- Association scopes read from history now cover `IS NULL` and `IS NOT NULL`
|
|
279
|
+
on a column of any type, such as a soft-delete scope's
|
|
280
|
+
`where(deleted_at: nil)`, and `NOT` with SQL's rules for NULL, such as
|
|
281
|
+
`where.not(position: [1, nil])`. These were read with PT-AT before, so a
|
|
282
|
+
record restored from a soft delete showed as changed rather than added, and
|
|
283
|
+
batch methods refused them without `allow_expensive: true`. A condition on a
|
|
284
|
+
PostgreSQL `citext` column, which compares without regard to case, is no
|
|
285
|
+
longer read as exact text.
|
|
286
|
+
- A `historical_filter:` hash casts its values, and the recorded ones, to each
|
|
287
|
+
attribute's type before comparing them, as `where` does. An enum given as a
|
|
288
|
+
symbol (`{ status: :published }`), and a date or time read from a `json` or
|
|
289
|
+
`jsonb` version column, which PaperTrail returns as a string, never matched,
|
|
290
|
+
so the report silently selected nothing.
|
|
291
|
+
- Versions from two version tables saved in the same instant raise
|
|
292
|
+
`AmbiguousVersionOrderError`, as the reference promises, instead of being
|
|
293
|
+
ordered by their ids. Each table counts its ids separately, so their order
|
|
294
|
+
said nothing about which change came first, and an activity timeline built
|
|
295
|
+
from them could credit a change to the wrong step.
|
|
296
|
+
- `compare_many`, `analyze_many`, `analyze_scope`, and `report` load a
|
|
297
|
+
`has_one` of every current record in one query again, as before 0.14.0.
|
|
298
|
+
0.14.0 meant to load only a `has_one` with a declared limit or offset per
|
|
299
|
+
record, but checked the association's scope, to which Active Record adds
|
|
300
|
+
`limit(1)` for every `has_one`, so every `has_one` cost one query per
|
|
301
|
+
record.
|
|
302
|
+
- `report`, `analyze_scope`, and `analyze_many` with `activity: true` no
|
|
303
|
+
longer read a root's current row once more for activity through a
|
|
304
|
+
`has_many :through` after its last version. The batch has already loaded
|
|
305
|
+
it, so the query count no longer grows with the number of roots.
|
|
306
|
+
- A snapshot's collections list their records by type, then ID, as the
|
|
307
|
+
reference says, wherever the snapshot was read from. Snapshots rebuilt from
|
|
308
|
+
history or carried through an activity timeline listed them in the order
|
|
309
|
+
they were found, and a ranked association in its query's order, so `to_h` of
|
|
310
|
+
the same state differed between methods. Diffs were already ordered.
|
|
311
|
+
- With a `json` or `jsonb` `object` column, an activity step no longer
|
|
312
|
+
reports an unchanged timestamp as changed. PaperTrail returns such a
|
|
313
|
+
column's times as strings, and a step after a child's update carried them
|
|
314
|
+
into the snapshot as they were, so the next step that read the child again
|
|
315
|
+
reported `created_at` changing from a string to the same time. Activity now
|
|
316
|
+
casts them as it does every other recorded state. The specs had covered the
|
|
317
|
+
JSON serializer on a text column only, which PaperTrail casts.
|
|
318
|
+
|
|
319
|
+
### Development
|
|
320
|
+
|
|
321
|
+
- A new oracle suite, `rake spec_oracle`, checks rebuilt history against the
|
|
322
|
+
truth rather than against other gem methods. It makes seeded random edits to
|
|
323
|
+
an article graph one transaction at a time, records the live state after
|
|
324
|
+
each, and compares every endpoint, timeline step, activity step, window, and
|
|
325
|
+
batch result with those states. It also checks that two windows meeting
|
|
326
|
+
between transactions or inside one report each step once, scoped membership
|
|
327
|
+
against Active Record, and a tree of one model whose children have
|
|
328
|
+
encrypted, serialized, enum, custom-type, decimal, and JSON attributes.
|
|
329
|
+
`rake spec` runs it, so CI runs it on every database. `ORACLE_SEEDS` and
|
|
330
|
+
`ORACLE_STEPS` widen a run. See `docs/testing.md`.
|
|
331
|
+
- `PTD_PROBE_ALLOW_APPROXIMATE=1` makes the reconstruction probe pass
|
|
332
|
+
`allow_approximate: true`, so its PT-AT-read scenario runs rather than
|
|
333
|
+
raising, and neither benchmark passes the deprecated `close_on:` any more.
|
|
334
|
+
- On SQL Server the association specs keep their versions 5 ms apart. Specs
|
|
335
|
+
that compare the gem with PT-AT failed at random there: PT-AT compares
|
|
336
|
+
version times through SQL text, which the SQL Server adapter writes as
|
|
337
|
+
`datetime` values up to 1/300 s off, and after the host clock stepped back
|
|
338
|
+
the test clock packed versions microseconds apart until it caught up.
|
|
339
|
+
- The reporting benchmark loads the monotonic test clock, so its results no
|
|
340
|
+
longer depend on the host clock. A clock that stepped backwards, as WSL2's
|
|
341
|
+
does, could date a root's destroy before its last update, and
|
|
342
|
+
`deleted_roots` then raised `IncompleteTimeRangeError`. The seeded history
|
|
343
|
+
and query counts are unchanged. Allocations rise by under 1% in
|
|
344
|
+
`many_roots` and `retained_activity`, where the gem reads the clock once
|
|
345
|
+
per root. The investigation scripts that seed through the same workload
|
|
346
|
+
load the clock too; `scalar_cost.rb` freezes time in front of it, so its
|
|
347
|
+
parity check still sees one instant.
|
|
348
|
+
|
|
349
|
+
## [0.14.0] - 2026-10-29
|
|
350
|
+
|
|
351
|
+
### Breaking changes
|
|
352
|
+
|
|
353
|
+
- A `has_and_belongs_to_many` with a scope, or whose target has a default
|
|
354
|
+
scope, raises `UnsupportedAssociationError` up front in every method, and
|
|
355
|
+
`association_paths` leaves it out. PT-AT records a HABTM's members through
|
|
356
|
+
its scope when the owner saves, so a target that entered the scope between
|
|
357
|
+
saves was missing from history, and `activity_timeline` raised `KeyError`.
|
|
358
|
+
Replace it with a `has_many :through` a versioned join model.
|
|
359
|
+
- `report`, and `analyze_scope` with `activity: true`, also select a record
|
|
360
|
+
when only a record on one of its requested `associations:` changed in the
|
|
361
|
+
window: editing a comment selects its article. They used to skip it, although
|
|
362
|
+
`analyze_many` reports that activity. A report can therefore return more
|
|
363
|
+
records and reach `limit:` sooner. Nested paths count at every level,
|
|
364
|
+
`has_many :through` counts its join rows, and a child that moved selects its
|
|
365
|
+
old and new owner. Selection adds one query per association level, not per
|
|
366
|
+
record. Checkpoint analyses (`activity: false`) are unchanged: they compare a
|
|
367
|
+
record's own versions, so only those select it. To keep only records that
|
|
368
|
+
changed themselves, drop analyses whose `timeline` is empty. A record
|
|
369
|
+
selected through a HABTM path in a window that ends at the current record
|
|
370
|
+
raises `UnsupportedLiveActivityError`, as one that changed itself already
|
|
371
|
+
does.
|
|
372
|
+
- A path that continues past a polymorphic `belongs_to`, such as
|
|
373
|
+
`"notable.comments"`, raises `UnsupportedAssociationError`. The part after
|
|
374
|
+
it used to be ignored without a word.
|
|
375
|
+
- A HABTM below the root, such as `"tags.articles"`, `"author.articles.tags"`,
|
|
376
|
+
or `"comments.article.tags"`, raises `UnsupportedAssociationError` up front
|
|
377
|
+
in every method, naming the path and the HABTM. `association_paths` leaves
|
|
378
|
+
such a path out. PT-AT records HABTM membership only when its owner saves a
|
|
379
|
+
version, in rows that do not name the owner, so a root checkpoint holds the
|
|
380
|
+
root's membership alone. These paths read the root's rows instead and
|
|
381
|
+
returned a wrong diff. An article that joined a tag went unreported, and
|
|
382
|
+
against the current record every member read as added. A sibling article
|
|
383
|
+
reached through its author was given the root's tags. `activity_timeline`
|
|
384
|
+
raised `KeyError`. Only a path that led back to the root, like
|
|
385
|
+
`"comments.article.tags"`, read correctly; request `"tags"` instead.
|
|
386
|
+
- A root HABTM read at a version saved in the same transaction as a version of
|
|
387
|
+
another record with a HABTM of that name raises
|
|
388
|
+
`IncompleteAssociationHistoryError`, naming the association and the
|
|
389
|
+
transaction, when PT-AT recorded members there. Those rows do not say which
|
|
390
|
+
record they belong to, so the root used to read every such record's members
|
|
391
|
+
as its own: two articles updated in one transaction each gained the other's
|
|
392
|
+
tags, and an unchanged article reported them removed. It happened in every
|
|
393
|
+
method, with no error. A transaction where only one record with that
|
|
394
|
+
association saved a version, or where none recorded a member, reads as
|
|
395
|
+
before, and `diagnose` reports the shared case as `habtm_transaction_shared`.
|
|
396
|
+
Save HABTM owners' versions in separate transactions, as a
|
|
397
|
+
[checkpoint](docs/reference.md#saving-a-checkpoint) does.
|
|
398
|
+
|
|
399
|
+
### Added
|
|
400
|
+
|
|
401
|
+
- `recorded_changes(version)` returns what PaperTrail stored with one version
|
|
402
|
+
in `object_changes`, as a frozen hash of `ValueChange` objects, typed by the
|
|
403
|
+
version's model. Unlike PaperTrail's `version.changeset`, it never loads the
|
|
404
|
+
record, so it costs no query per version and still types a deleted record's
|
|
405
|
+
values. It returns `nil` when nothing was recorded, and takes an `ignore:`
|
|
406
|
+
array that defaults to `updated_at`.
|
|
407
|
+
|
|
408
|
+
### Changed
|
|
409
|
+
|
|
410
|
+
- Batch reads of a `has_many :through` and of a polymorphic `belongs_to` no
|
|
411
|
+
longer call `reify` on each root version. They are read from stored
|
|
412
|
+
attributes like other associations. In the reconstruction probe, `report`
|
|
413
|
+
over a through went from 7 `reify` calls per root to none and builds about
|
|
414
|
+
half as many model instances. Results are unchanged. A type that names no
|
|
415
|
+
class, an unversioned target, and a scope that cannot be read as conditions
|
|
416
|
+
still take the record path.
|
|
417
|
+
- Batch methods read an association scope, or a target's default scope, made
|
|
418
|
+
of plain conditions on the target's columns (equality, `IN`, `nil`, their
|
|
419
|
+
`where.not` forms, combined with `and` and `or`) from prepared history, so
|
|
420
|
+
they no longer need `allow_expensive: true` for it and its query count no
|
|
421
|
+
longer grows with the records. String conditions are read this way only on
|
|
422
|
+
SQLite and PostgreSQL. Scopes that take the owner and other conditions are
|
|
423
|
+
still rejected without the opt-in. A default-scoped model whose scope assigns
|
|
424
|
+
no attributes is read without `reify`.
|
|
425
|
+
- Batch methods also read a `limit` or `offset`, and the order of a `has_one`,
|
|
426
|
+
from prepared history when the order is total, reaching the primary key, and
|
|
427
|
+
sorts only by integer, boolean, or integer enum columns of the target. NULL
|
|
428
|
+
sorts as each adapter puts it by default. In the reconstruction probe,
|
|
429
|
+
`report` over `order(:id).limit(1)` went from 252 queries and 160 `reify`
|
|
430
|
+
calls at 20 roots, with the opt-in, to 32 queries and none without it. A
|
|
431
|
+
string order, an order with ties, and a `has_one :through` over a ranked
|
|
432
|
+
part are still rejected without the opt-in.
|
|
433
|
+
- Batch methods also rank by date columns, and by datetime columns when the
|
|
434
|
+
column declares a precision that history keeps and times are stored in UTC,
|
|
435
|
+
such as `order(created_at: :desc).limit(5)` with YAML history. JSON history
|
|
436
|
+
keeps milliseconds by default, so with it only a `datetime(3)` column is
|
|
437
|
+
read. A time-of-day column, and a datetime without a precision, are still
|
|
438
|
+
rejected without the opt-in.
|
|
439
|
+
- Batch methods read a `has_many :through` over a part with a `limit`,
|
|
440
|
+
`offset`, or `has_one` order, and one with its own `limit` or `offset`, from
|
|
441
|
+
prepared history without the opt-in.
|
|
442
|
+
- The README recipe for deleted records also reads each record as it was just
|
|
443
|
+
before deletion, which a record created inside the window has no other
|
|
444
|
+
snapshot of.
|
|
445
|
+
- The documentation now says where a change saved without a version, such as
|
|
446
|
+
with `update_columns`, appears: in the step for that record's previous
|
|
447
|
+
recorded change, credited to its author, anywhere in a range. It used to say
|
|
448
|
+
only that the last step of a range ending at the current record shows them,
|
|
449
|
+
and that a step's diff is exactly what its event changed. Ending a range at a
|
|
450
|
+
version leaves out only the writes after it. Specs pin this behavior, which
|
|
451
|
+
is unchanged.
|
|
452
|
+
- The README has a recipe that turns a report into one row per changed field,
|
|
453
|
+
with the record, whether it changed, appeared, or disappeared, and the step's
|
|
454
|
+
author, event, and time.
|
|
455
|
+
- Batch methods no longer need `allow_expensive: true` for a
|
|
456
|
+
`has_many :through` whose source is a `has_many`, such as an author's
|
|
457
|
+
comments through articles. It is read from prepared history like the other
|
|
458
|
+
associations, so its queries no longer grow with the records: the five-record
|
|
459
|
+
probe in `docs/performance.md` went from 200 queries to 20.
|
|
460
|
+
|
|
461
|
+
### Fixed
|
|
462
|
+
|
|
463
|
+
- A `limit` or `offset` scope, or an ordered `has_one`, read at a version
|
|
464
|
+
returns the records its query returned then, when the order is total and
|
|
465
|
+
sorts by columns batch methods can rank. It used to start from
|
|
466
|
+
the association's current rows, so a range whose records later changed
|
|
467
|
+
reported the wrong ones: with comments `first` and `second` under
|
|
468
|
+
`order(:id).limit(1)`, destroying `first` and adding `third` reported
|
|
469
|
+
`third` added instead of `second`. Other ranked scopes still read the
|
|
470
|
+
current rows.
|
|
471
|
+
- A `has_many :through` reads its parts as its own query does, keeping their
|
|
472
|
+
conditions but not their `limit`, `offset`, or `has_one` cut. History used
|
|
473
|
+
to apply them, and read with the opt-in it could raise PT-AT's
|
|
474
|
+
`FoundMoreThanOne`; batched history kept only one record through a `has_one`
|
|
475
|
+
part. A through's own `limit` or `offset` counts a record reached through
|
|
476
|
+
two join records twice, as the query does.
|
|
477
|
+
- Batch comparisons with a current endpoint load a `has_many :through` over a
|
|
478
|
+
part with a `limit`, `offset`, or `has_one` per record. Active Record's
|
|
479
|
+
preloader applied the part's limit across every record in the batch, so a
|
|
480
|
+
record could show another's members or none.
|
|
481
|
+
- A record reached through two join records is one member of a current
|
|
482
|
+
association, as it already was of a historical one, so a through loaded per
|
|
483
|
+
record no longer raises a duplicate identity error.
|
|
484
|
+
- In a batch, a `has_one` with an `offset` is loaded per record at the current
|
|
485
|
+
end. The preloader applied the offset across all records at once, so a
|
|
486
|
+
record could show another record's member.
|
|
487
|
+
- Activity reports a change to a `belongs_to` target that is an STI subclass.
|
|
488
|
+
When the target was destroyed, or its `type` changed between a subclass and
|
|
489
|
+
another class, activity reported nothing while checkpoint analysis reported
|
|
490
|
+
it, because a target's version names only the base class. This includes the
|
|
491
|
+
same target further down a path, such as `"note.badge"`.
|
|
492
|
+
- An association that only an STI subclass declares can be requested on a
|
|
493
|
+
root of that subclass in every method. Without an `item_subtype` column on
|
|
494
|
+
versions, each version resolved to the base class, so every method raised
|
|
495
|
+
`UnknownAssociationError`. The subclass is now read from the type the
|
|
496
|
+
version stored, or for a `create`, from its recorded changes. A stored type
|
|
497
|
+
that names no class raises `InvalidEndpointError`.
|
|
498
|
+
- A `has_many :through` with `source_type:` holds only the records reached
|
|
499
|
+
through join records of that type, in every method. History used to ignore
|
|
500
|
+
the option, so a join record pointing at another type made its target a
|
|
501
|
+
member: a holder whose links named a tag reported the tag among its authors,
|
|
502
|
+
and the tag's changes opened activity steps and selected the holder in
|
|
503
|
+
`report`. The current record was read correctly, so a comparison with it
|
|
504
|
+
reported the tag as removed. A join record whose type changes now adds or
|
|
505
|
+
removes its target in the step of that version.
|
|
506
|
+
- A scoped or default-scoped association read from history now holds the
|
|
507
|
+
records that met the scope at each point. It used to ignore the scope's
|
|
508
|
+
conditions for history: a record that left the scope was reported as
|
|
509
|
+
changed instead of removed, one that entered it as changed instead of
|
|
510
|
+
added, and a record outside the scope could be reported as removed when it
|
|
511
|
+
was destroyed or moved. Activity reports entering or leaving the scope as
|
|
512
|
+
an addition or removal at the version that did it.
|
|
513
|
+
- `compare` and `compare_many` between two versions report a `has_many` child
|
|
514
|
+
that moved to another owner afterwards. They reported no change: the
|
|
515
|
+
comparison read associations through PT-AT, which finds children by the keys
|
|
516
|
+
their versions recorded after each change, so the child was not found at the
|
|
517
|
+
earlier version. Version pairs now read the same prepared history as a
|
|
518
|
+
comparison with the current record, including for a record that was deleted.
|
|
519
|
+
- Historical analysis through a polymorphic `belongs_to` works in every method.
|
|
520
|
+
Only comparisons between two versions used to work: timelines, analyses,
|
|
521
|
+
reports, and comparisons with the current record raised `ArgumentError`.
|
|
522
|
+
Batches load the targets with one query per target class. A target class
|
|
523
|
+
without `has_paper_trail` raises `UnversionedAssociationError` when a record
|
|
524
|
+
names it, rather than a `NoMethodError` from PT-AT, and a default-scoped
|
|
525
|
+
target class is read as its association returns it. A type that names no
|
|
526
|
+
class, such as one a renamed model left in its versions, raises
|
|
527
|
+
`IncompleteAssociationHistoryError` naming the record and the type, rather
|
|
528
|
+
than a `NameError` that names neither.
|
|
529
|
+
- Activity leaves out the `belongs_to` target a record moves to in the
|
|
530
|
+
version that closes the window. Its changes inside the window used to add
|
|
531
|
+
empty steps, attributed to a record the root never pointed at there.
|
|
532
|
+
- Activity reports a change to a `belongs_to` target, or to the source of a
|
|
533
|
+
`has_many :through`, when the record pointing at it did not change in the
|
|
534
|
+
window: an author renamed under an article nobody edited. It used to report
|
|
535
|
+
nothing. A record that changed its target in the window also reports
|
|
536
|
+
changes to the target it pointed at before.
|
|
537
|
+
- `include_deleted: true` with `activity: true` reports the association
|
|
538
|
+
activity of a deleted record that did not change itself in the window. Its
|
|
539
|
+
analysis used to be empty.
|
|
540
|
+
- History of an association to an STI subclass, such as
|
|
541
|
+
`has_many :pinned_badges, class_name: 'PinnedBadge'`, holds only that class
|
|
542
|
+
and its subclasses, as the live association does. It used to hold the
|
|
543
|
+
sibling classes' records too, so a range ending at the current record
|
|
544
|
+
reported them as removed. Activity used to report a sibling's changes under
|
|
545
|
+
the association too, and to open a step for each version of a sibling or of
|
|
546
|
+
its children.
|
|
547
|
+
- Activity reports a record whose STI type changed in the step of the version
|
|
548
|
+
that changed it, as a removal of the old type and an addition of the new,
|
|
549
|
+
and adds it to or removes it from an association to an STI subclass there.
|
|
550
|
+
It used to add the new type alongside the old one and leave the old one in
|
|
551
|
+
place until a later step, or to the end of a range ending at a version.
|
|
552
|
+
- `activity_timeline`, and `analyze` with `activity: true`, return no steps for
|
|
553
|
+
a range that ends at a version when `version_scope:` keeps none of its
|
|
554
|
+
versions, as a checkpoint timeline does. They used to raise `NoMethodError`.
|
|
555
|
+
- `analyze_scope` and `report` list `unreachable` in the same sorted order
|
|
556
|
+
whatever the type of `versions.item_id`. With a string `item_id` it used to
|
|
557
|
+
follow the database's order.
|
|
558
|
+
- On SQL Server, activity places a version saved within two milliseconds of a
|
|
559
|
+
window's start or end on the side it was saved. The window's bounds used to
|
|
560
|
+
be rounded to 1/300 second, so such a version could be read as outside the
|
|
561
|
+
window, or one just past its end as inside it.
|
|
562
|
+
- A `has_many :through` that goes through a `has_and_belongs_to_many`, as its
|
|
563
|
+
`through:`, its `source:`, or further down its chain, raises
|
|
564
|
+
`UnsupportedAssociationError` up front in every method, naming the path and
|
|
565
|
+
the HABTM. Comparing two versions used to raise `NoMethodError` from inside
|
|
566
|
+
PT-AT, and analyses `ActiveRecord::StatementInvalid`. A `has_many :through`
|
|
567
|
+
Active Record cannot follow at all, such as one through a polymorphic
|
|
568
|
+
`belongs_to`, likewise raises Active Record's own error in every method,
|
|
569
|
+
where historical work used to fail partway with `ArgumentError` or
|
|
570
|
+
`NoMethodError`.
|
|
571
|
+
- `association_paths` leaves out a `has_many :through` that goes through a
|
|
572
|
+
`has_and_belongs_to_many`, so every path it lists can be requested. It
|
|
573
|
+
decides with the same check a request makes. It used to list such a path,
|
|
574
|
+
and a settings screen built from it offered one that failed when picked. A
|
|
575
|
+
model it reaches with a `has_many :through` Active Record cannot follow,
|
|
576
|
+
such as one through a polymorphic `belongs_to`, raises Active Record's own
|
|
577
|
+
error, where discovery used to raise `ArgumentError`, `NameError`, or
|
|
578
|
+
`NoMethodError` from inside the reflection, or list a path that raised when
|
|
579
|
+
requested.
|
|
580
|
+
- A `has_many :through` whose source is a `has_many` follows records that
|
|
581
|
+
move. A comment moved to another article leaves the first article's author
|
|
582
|
+
and joins the other's, and an article that moves to another author takes its
|
|
583
|
+
comments with it. Analyses, timelines, and comparisons with the current
|
|
584
|
+
record used to report no change for such a move, and could report a record
|
|
585
|
+
that left and came back as changed. They read these associations through
|
|
586
|
+
PT-AT, which finds a record by the keys its later versions recorded.
|
|
587
|
+
- A `has_many :through` whose `through:` is itself a `has_many :through`, such
|
|
588
|
+
as `has_many :comment_reviewers, through: :comments, source: :reviewer` with
|
|
589
|
+
`comments` through `articles`, reports its changes in analyses, timelines,
|
|
590
|
+
and batches. It used to read as empty at every point, so it never reported a
|
|
591
|
+
change.
|
|
592
|
+
|
|
593
|
+
### Development
|
|
594
|
+
|
|
595
|
+
- Mutation testing also covers `ScopeCondition`, which decides the records an
|
|
596
|
+
association scope admits. The reconstruction probe has a `scoped` scenario.
|
|
597
|
+
- The consistency specs also check that activity selection includes every
|
|
598
|
+
record whose analysis reports a change.
|
|
599
|
+
- Mutation testing also covers `TimeRange`, `VersionRange`,
|
|
600
|
+
`TimeVersionRange`, `BatchedRootVersions`, and `DeletedAnalysisBatch`, each
|
|
601
|
+
with a unit spec of its own; all 5,485 mutations across the fourteen classes
|
|
602
|
+
are caught.
|
|
603
|
+
- Mutation testing also covers `RecordedChanges`; all 257 of its mutations are
|
|
604
|
+
caught.
|
|
605
|
+
- Mutation testing also covers the association code: `ScopedRootSelection`,
|
|
606
|
+
`AssociationActivitySelection`, `AssociationActivityEdge`,
|
|
607
|
+
`ActivityTargetCandidateLoader`, `PreparedHistoryLoader`,
|
|
608
|
+
`PreparedEdgeLoader`, `ActivityTimelineBuilder`,
|
|
609
|
+
`ActivityTransactionGrouper`, and `BatchSafety`, each with a spec of its
|
|
610
|
+
own. All 10,732 mutations across the 24 classes are caught.
|
|
611
|
+
- Mutation testing also covers `AssociationTraversal`, which decides which
|
|
612
|
+
association paths a request accepts, with a spec of its own; all 764 of its
|
|
613
|
+
mutations are caught.
|
|
614
|
+
- Mutation testing also covers range and boundary handling:
|
|
615
|
+
`ActivityRange`, `VersionAssociationCandidateScope`, and
|
|
616
|
+
`PreparedActivityIndex`, each with a spec of its own; all 1,507 of their
|
|
617
|
+
mutations are caught.
|
|
618
|
+
- Mutation testing also covers `HabtmTransactionOwners`, which decides whether
|
|
619
|
+
a transaction's HABTM members can be read as one record's, with a spec of
|
|
620
|
+
its own.
|
|
621
|
+
- `benchmark/investigation/reconstruction.rb` runs again: the association
|
|
622
|
+
fixtures load the monotonic test clock they use. Its `prepared-through`
|
|
623
|
+
experiment and `benchmark/investigation/prepared_through_override.rb` are
|
|
624
|
+
removed, since the gem now reads those throughs that way.
|
|
625
|
+
- `spec/association/through_membership_spec.rb` writes out the expected
|
|
626
|
+
membership of a `has_many :through` with a `has_many` source over moves,
|
|
627
|
+
deletions, transactions, and changes saved without a version, alone and in
|
|
628
|
+
a batch.
|
|
629
|
+
- `ActivityEventRouteFinder` no longer checks for a polymorphic `belongs_to`
|
|
630
|
+
before following a path below it. Validation already rejects such a path,
|
|
631
|
+
so the check could not be reached.
|
|
632
|
+
- The `PreparedHistoryLoader` spec checks that an edge into a versioned model
|
|
633
|
+
with records stays prepared. A full mutation run of the 29 classes now
|
|
634
|
+
catches all 13,284 mutations.
|
|
635
|
+
|
|
6
636
|
## [0.13.1] - 2026-10-28
|
|
7
637
|
|
|
8
638
|
### Fixed
|