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.
Files changed (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
data/docs/testing.md CHANGED
@@ -8,7 +8,7 @@ mise exec -- bundle exec rake
8
8
  ```
9
9
 
10
10
  The default task runs the core specs without PT-AT loaded, the association specs
11
- in a separate process, RuboCop (with the rubocop-performance and rubocop-rspec
11
+ and the [oracle checks](#oracle-checks) each in a separate process, RuboCop (with the rubocop-performance and rubocop-rspec
12
12
  plugins), generated-signature verification, and Steep.
13
13
  Ruby blocks in the README, quickstart, and API reference marked with
14
14
  `<!-- executable:... -->` run inside those specs, so documented examples stay
@@ -37,6 +37,49 @@ history, with integer and string `versions.item_id`, YAML and JSON history, and
37
37
  a `has_paper_trail skip:` column. When one fails, its seed reproduces it. Add a
38
38
  variant here when a bug turns out to depend on a schema or configuration.
39
39
 
40
+ ## Oracle checks
41
+
42
+ The consistency checks compare gem methods with each other, so a bug they
43
+ share passes. `spec/oracle` compares them with the truth instead:
44
+
45
+ 1. A seeded generator (`spec/support/oracle.rb`) makes random edits to an
46
+ article graph, one transaction each: root edits and checkpoints, comments
47
+ and replies created, edited, moved, and deleted, an author, a profile, and
48
+ authorships with their authors. Some transactions write several versions.
49
+ 2. After each transaction it records the live state, keyed by the versions
50
+ that transaction wrote, so every version names the state just before it.
51
+ The state comes from the gem's current-record path, which is plain Active
52
+ Record, and is checked against an independent read of each association.
53
+ 3. Every endpoint pair, every timeline step, every activity step (grouped and
54
+ not), and windows through `analyze`, `analyze_many`, and `analyze_scope`
55
+ are compared with the recorded states. Two windows that meet between
56
+ transactions, or inside one, must report each step once, as the window
57
+ spanning both does, through both `activity_timeline` and `analyze_many`.
58
+
59
+ Two more generators cover other shapes. `scoped_membership_spec.rb` moves
60
+ notes in and out of scoped associations (conditions, order, limit, and
61
+ offset) and compares the members at every version with Active Record's own
62
+ answer. `tree_history_spec.rb` edits a tree of one model, so a root can sit
63
+ inside another root's tree, with children whose attributes are encrypted,
64
+ serialized, enums stored as strings, custom types, decimals, and JSON. It reads
65
+ the expected states with plain Active Record, not through the gem.
66
+
67
+ ```console
68
+ mise exec -- bundle exec rake spec_oracle
69
+ ORACLE_SEEDS=1..200 ORACLE_STEPS=40 mise exec -- bundle exec rake spec_oracle
70
+ ```
71
+
72
+ The default seeds keep the run to a few seconds; `rake spec` includes it, so
73
+ the database jobs run it too. Mutant does not, because it would slow every
74
+ mutation. A failure prints its seed and the transactions it made. To fix one,
75
+ reproduce it with that seed, reduce it to the few edits that matter, and add
76
+ that as a named spec beside the code it covers, so the cause is readable
77
+ without the generator.
78
+
79
+ When a bug turns out to depend on a schema, configuration, or kind of edit,
80
+ add it to the generator or as a new context, so the whole class of bug stays
81
+ covered.
82
+
40
83
  ## Mutation testing
41
84
 
42
85
  [Mutant](https://github.com/mbj/mutant) changes the library one expression at
@@ -46,19 +89,46 @@ passes is behavior nothing checks. `mutant.yml` lists the classes it mutates:
46
89
  - what counts as a change: `Engine`, `CollectionComparator`,
47
90
  `CollectionIdentityIndex`, and `NestedComparator`;
48
91
  - which columns are compared: `SnapshotNormalizer` and `SnapshotPool`;
49
- - which history a range or filter reads: `TimelineRange`, `RootVersionPlan`,
50
- and `HistoricalFilter`.
92
+ - which versions a range reads: `TimeRange`, `TimelineRange`, `VersionRange`,
93
+ `TimeVersionRange`, and `RootVersionPlan`;
94
+ - which versions a batch or filter reads: `BatchedRootVersions`,
95
+ `DeletedAnalysisBatch`, and `HistoricalFilter`;
96
+ - what a version recorded: `RecordedChanges`;
97
+ - how a step flattens into rows: `ChangeRow` and `ChangeRows`;
98
+ - which records a scope or report selects: `ScopedRootSelection`,
99
+ `AssociationActivitySelection`, `AssociationActivityEdge`, and
100
+ `DeletedRootFilter`;
101
+ - which children and targets a record had at each point:
102
+ `PreparedHistoryLoader`, `PreparedEdgeLoader`,
103
+ `ActivityTargetCandidateLoader`, and `PreparedActivityIndex`;
104
+ - where an activity range starts and ends, and which association history its
105
+ query reads: `ActivityRange` and `VersionAssociationCandidateScope`;
106
+ - what activity a record shows: `ActivityTimelineBuilder` and
107
+ `ActivityTransactionGrouper`;
108
+ - which association paths a request accepts: `AssociationTraversal` and
109
+ `AssociationKey`;
110
+ - whether a transaction's HABTM members are one record's:
111
+ `HabtmTransactionOwners`;
112
+ - which association paths history cannot read exactly: `ApproximatePaths`;
113
+ - which records an association scope admits, and how it ranks them:
114
+ `ScopeCondition` and `ScopeRanking`.
51
115
 
52
116
  The specs for the classes that read the database use tables of their own
53
- (`spec/support/filter_database.rb`, `spec/support/normalizer_database.rb`), so
54
- they run in both the core and the association suite.
117
+ (`spec/support/filter_database.rb`, `spec/support/normalizer_database.rb`,
118
+ `spec/support/recorded_changes_database.rb`), so they run in both the core and
119
+ the association suite. The association classes need PT-AT, so their specs are
120
+ in `spec/association` and define any extra tables in the spec file itself.
55
121
 
56
- Mutant does not run every spec for every mutation. It runs the specs whose
122
+ Mutant reads `spec/unit` and `spec/association`, never `spec/integration`.
123
+ Even there it does not run every spec for every mutation, only those whose
57
124
  description names the mutated class (`RSpec.describe PaperTrailDiff::Engine`),
58
- and only falls back to wider names such as `PaperTrailDiff` when none does. A
59
- spec named after a behavior, as most integration specs are, never runs. So
60
- each mutated class has a unit spec of its own that catches every mutation in
61
- it, and a class added to `mutant.yml` needs one too.
125
+ falling back to wider names such as `PaperTrailDiff` when none does. A spec
126
+ named after a behavior, as most integration specs are, never runs. So each
127
+ mutated class has a unit spec of its own that catches every mutation in it,
128
+ and a class added to `mutant.yml` needs one too. A spec named after a
129
+ behavior can still name the class it checks with metadata, as the activity
130
+ window specs do: `RSpec.describe 'Activity over a window', mutant_expression:
131
+ 'PaperTrailDiff::ActivityTimelineBuilder'`.
62
132
 
63
133
  Mutant counts a mutation that runs past its time limit as caught, so
64
134
  `mutant.yml` sets the limit well above the time the whole suite takes. With
@@ -87,8 +157,10 @@ BUNDLE_GEMFILE=gemfiles/mutant.gemfile mise exec -- bundle exec mutant run --sin
87
157
  When a mutation survives, either add the spec that would catch it, or, if the
88
158
  mutated code means the same thing, simplify the code to that form. Reserve a
89
159
  `mutant:disable` comment for a method whose surviving mutations all mean the
90
- same thing as the code, and say why next to it. Mutant forks a worker per CPU; `spec/support/mutant_hooks.rb`
91
- gives each worker its own copy of the SQLite fixture database.
160
+ same thing as the code, and say why next to it.
161
+
162
+ Mutant forks a worker per CPU; `spec/support/mutant_hooks.rb` gives each
163
+ worker its own copy of the SQLite fixture database.
92
164
 
93
165
  ## Test clock
94
166
 
@@ -99,8 +171,10 @@ they resynchronize, which made window-based specs fail at random.
99
171
  `spec/support/monotonic_clock.rb` therefore makes `Time.now` strictly
100
172
  increasing, in whole microseconds, for the test process. ActiveRecord
101
173
  timestamps, PaperTrail's `created_at`, and windows built from `Time.now` all
102
- read it, so they stay consistent however the host clock moves. It affects only
103
- the test process; the gem itself reads the ordinary clock.
174
+ read it, so they stay consistent however the host clock moves. The benchmark
175
+ workload, `benchmark/support/workload.rb`, loads it too, because a step back
176
+ could date a root's destroy before its last update. It affects only the specs
177
+ and the benchmark; the gem itself reads the ordinary clock.
104
178
 
105
179
  ## Other databases locally
106
180
 
@@ -135,6 +209,11 @@ PaperTrail's default YAML serializer, the fixtures explicitly permit
135
209
  `ActiveRecord.yaml_column_permitted_classes` configuration. The gem does not
136
210
  change an application's YAML configuration.
137
211
 
212
+ PT-AT compares version times through SQL text, which SQL Server's adapter
213
+ writes as `datetime` values, up to 1/300 s off. So on SQL Server the
214
+ association specs keep their versions 5 ms apart, or the specs that compare
215
+ the gem with PT-AT would fail whenever versions were saved closer together.
216
+
138
217
  The CI service configuration is in `.github/workflows/ci.yml`. PostgreSQL and
139
218
  MySQL create the named database during container initialization. The SQL Server
140
219
  jobs create it explicitly after the service passes its health check.
@@ -25,7 +25,7 @@ module PaperTrailDiff
25
25
  routes = @route_finder.belongs_to_routes(
26
26
  endpoint_model_class(root_endpoint), tree, version.item_type.to_s
27
27
  )
28
- return [false, nil] if routes.empty?
28
+ return [false, nil] if routes.empty? || scoped_route?(routes)
29
29
 
30
30
  snapshot = previous
31
31
  routes.each do |route|
@@ -43,6 +43,15 @@ module PaperTrailDiff
43
43
  # @rbs @record_resolver: ActivityEventRecordResolver
44
44
  # @rbs @record_normalizer: ActivityEventRecordNormalizer
45
45
 
46
+ # An edit can move a target into or out of a scope, which a replacement
47
+ # in place cannot show, so a scoped route's branch is read again instead.
48
+ #: (Array[Array[untyped]]) -> bool
49
+ def scoped_route?(routes)
50
+ routes.any? do |route|
51
+ route.any? { |entry| ScopeCondition.scoped_path?(entry.fetch(1)) }
52
+ end
53
+ end
54
+
46
55
  #: (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
47
56
  def normalized_route_record(route, version, normalizer, root_endpoint, context_endpoint)
48
57
  record = @record_resolver.record_after(version, direct: route.last.fetch(2).empty?)
@@ -91,8 +100,7 @@ module PaperTrailDiff
91
100
  #: (Array[RecordSnapshot], untyped, RecordSnapshot?) -> [Array[RecordSnapshot], bool]
92
101
  def replace_existing_target(records, version, replacement)
93
102
  index = records.index do |record|
94
- record.id.to_s == version.item_id.to_s &&
95
- record.type.to_s == replacement_type(version, replacement)
103
+ record.id.to_s == version.item_id.to_s && same_table?(record, version)
96
104
  end
97
105
  return [records, false] unless index
98
106
 
@@ -101,16 +109,18 @@ module PaperTrailDiff
101
109
  [updated.freeze, true]
102
110
  end
103
111
 
104
- #: (untyped, RecordSnapshot?) -> String
105
- def replacement_type(version, replacement)
106
- return replacement.type.to_s if replacement
107
-
108
- Endpoint.model_class(version).name.to_s
112
+ # The target is matched by id within its table rather than by type name.
113
+ # Without `item_subtype`, a version names only the STI base class, and a
114
+ # row whose type changes is replaced by a record of another class.
115
+ #: (RecordSnapshot, untyped) -> bool
116
+ def same_table?(record, version)
117
+ model = AssociationTraversal.named_class(record.type.to_s)
118
+ !model.nil? && model.base_class == Endpoint.model_class(version).base_class
109
119
  end
110
120
 
111
121
  #: (untyped) -> untyped
112
122
  def endpoint_model_class(endpoint)
113
- Endpoint.version?(endpoint) ? Endpoint.model_class(endpoint) : endpoint.class
123
+ Endpoint.version?(endpoint) ? RecordedClass.for(endpoint) : endpoint.class
114
124
  end
115
125
  end
116
126
  end
@@ -17,9 +17,20 @@ module PaperTrailDiff
17
17
  # report one save as one step rather than as its parts.
18
18
  attr_reader :transaction_id #: untyped
19
19
 
20
+ # @rbs @recorded_changes: untyped
21
+
22
+ # Stands for recorded changes nobody asked to read, which differs from a
23
+ # version that recorded nothing (nil).
24
+ NOT_READ = Object.new.freeze
25
+ NOT_READ_MESSAGE = 'recorded changes were not read; pass recorded_changes: true'
26
+ private_constant :NOT_READ, :NOT_READ_MESSAGE
27
+
20
28
  class << self
21
- #: (untyped) -> ActivityBoundary
22
- def from_version(version)
29
+ # `recorded:` names the attributes to leave out of the version's recorded
30
+ # changes, or is nil when they were not asked for. Reading them decodes
31
+ # `object_changes`, which a caller who does not want them should not pay.
32
+ #: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
33
+ def from_version(version, recorded: nil)
23
34
  new(
24
35
  kind: :version,
25
36
  version_id: version.id,
@@ -28,26 +39,29 @@ module PaperTrailDiff
28
39
  recorded_at: version.created_at,
29
40
  event: version.event,
30
41
  whodunnit: version.whodunnit,
31
- transaction_id: transaction_id(version)
42
+ transaction_id: VersionBoundary.transaction_id(version),
43
+ recorded_changes: recorded_changes(version, recorded)
32
44
  )
33
45
  end
34
46
 
35
- #: (untyped, captured_at: untyped) -> ActivityBoundary
36
- def current(record, captured_at:)
47
+ # The current record has no version, so it recorded nothing.
48
+ #: (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
49
+ def current(record, captured_at:, recorded: nil)
37
50
  new(
38
51
  kind: :current,
39
52
  version_id: nil,
40
53
  item_type: record.class.base_class.name,
41
54
  item_id: record.id,
42
- recorded_at: captured_at
55
+ recorded_at: captured_at,
56
+ recorded_changes: recorded.nil? ? NOT_READ : nil
43
57
  )
44
58
  end
45
59
 
46
60
  # The state a `destroy` version leaves behind. A version records the state
47
61
  # before its own event, so the boundary built from a destroy version still
48
62
  # holds the record; this one is the absence that follows it.
49
- #: (untyped) -> ActivityBoundary
50
- def destroyed(version)
63
+ #: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
64
+ def destroyed(version, recorded: nil)
51
65
  new(
52
66
  kind: :destroyed,
53
67
  version_id: version.id,
@@ -56,20 +70,24 @@ module PaperTrailDiff
56
70
  recorded_at: version.created_at,
57
71
  event: version.event,
58
72
  whodunnit: version.whodunnit,
59
- transaction_id: transaction_id(version)
73
+ transaction_id: VersionBoundary.transaction_id(version),
74
+ recorded_changes: recorded_changes(version, recorded)
60
75
  )
61
76
  end
62
77
 
63
- # A custom version class need not carry the column, and PaperTrail leaves
64
- # it nil outside a transaction. Both read as "no transaction here", which
65
- # groups with nothing.
66
- #: (untyped) -> untyped
67
- def transaction_id(version)
68
- version.transaction_id if version.respond_to?(:transaction_id)
78
+ private
79
+
80
+ #: (untyped, Array[String]?) -> untyped
81
+ def recorded_changes(version, ignore)
82
+ return NOT_READ if ignore.nil?
83
+
84
+ RecordedChanges.call(version, ignore: ignore)
69
85
  end
70
86
  end
71
87
 
72
- #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped) -> void
88
+ # `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
89
+ # for the version; leave it out when they were not read.
90
+ #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: untyped) -> void
73
91
  def initialize( # rubocop:disable Metrics/ParameterLists
74
92
  kind:,
75
93
  version_id:,
@@ -78,7 +96,8 @@ module PaperTrailDiff
78
96
  recorded_at:,
79
97
  event: nil,
80
98
  whodunnit: nil,
81
- transaction_id: nil
99
+ transaction_id: nil,
100
+ recorded_changes: NOT_READ
82
101
  )
83
102
  @kind = kind
84
103
  @version_id = Support.immutable_copy(version_id)
@@ -88,10 +107,29 @@ module PaperTrailDiff
88
107
  @event = Support.immutable_copy(event&.to_s)
89
108
  @whodunnit = Support.immutable_copy(whodunnit)
90
109
  @transaction_id = Support.immutable_copy(transaction_id)
110
+ @recorded_changes = recorded_changes
91
111
  @record = RecordReference.new(type: @item_type, id: @item_id)
92
112
  freeze
93
113
  end
94
114
 
115
+ # What PaperTrail recorded with this boundary's version, as
116
+ # `PaperTrailDiff.recorded_changes` returns it: nil when nothing was
117
+ # recorded, and always nil for the current record, which has no version.
118
+ # Raises unless the timeline was built with `recorded_changes: true`, so a
119
+ # forgotten option cannot pass for a version that recorded nothing.
120
+ #: () -> Hash[String, ValueChange]?
121
+ def recorded_changes
122
+ raise ConfigurationError, NOT_READ_MESSAGE unless recorded_changes?
123
+
124
+ @recorded_changes
125
+ end
126
+
127
+ # Whether this boundary's recorded changes were read.
128
+ #: () -> bool
129
+ def recorded_changes?
130
+ !NOT_READ.equal?(@recorded_changes)
131
+ end
132
+
95
133
  #: () -> bool
96
134
  def version?
97
135
  kind == :version
@@ -115,11 +153,14 @@ module PaperTrailDiff
115
153
  item_type: item_type,
116
154
  item_id: item_id,
117
155
  recorded_at: recorded_at
118
- }
156
+ } #: Hash[Symbol, untyped]
119
157
  return value unless metadata
120
158
 
121
- value.merge(event: event, whodunnit: whodunnit, transaction_id: transaction_id,
122
- record: record.to_h)
159
+ value.merge!(event: event, whodunnit: whodunnit, transaction_id: transaction_id,
160
+ record: record.to_h)
161
+ return value unless recorded_changes?
162
+
163
+ value.merge(recorded_changes: @recorded_changes&.transform_values(&:to_h))
123
164
  end
124
165
  end
125
166
 
@@ -135,28 +176,35 @@ module PaperTrailDiff
135
176
  # get wrong.
136
177
  attr_reader :from_snapshot #: RecordSnapshot?
137
178
  attr_reader :to_snapshot #: RecordSnapshot?
179
+ # The events whose changes this step reports, in the order they happened.
180
+ # That is `source_boundary` alone, unless the step is a transaction group,
181
+ # which holds every event in it: an attribution that names only the first
182
+ # would credit the rest of the save to whoever opened it.
183
+ attr_reader :sources #: Array[ActivityBoundary]
138
184
 
139
185
  # Compares two reconstructed states and keeps them only when asked, which is
140
186
  # every caller's shape: the diff always comes from the pair, the pair itself
141
187
  # is retained on request.
142
- #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
143
- def self.between(from_boundary:, to_boundary:, from_snapshot:, to_snapshot:, retain:)
188
+ #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
189
+ def self.between(from_boundary:, to_boundary:, from_snapshot:, to_snapshot:, retain:, sources: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
144
190
  new(
145
191
  from_boundary: from_boundary,
146
192
  to_boundary: to_boundary,
147
193
  diff: Engine.compare(from_snapshot, to_snapshot),
148
194
  from_snapshot: (from_snapshot if retain),
149
- to_snapshot: (to_snapshot if retain)
195
+ to_snapshot: (to_snapshot if retain),
196
+ sources: sources
150
197
  )
151
198
  end
152
199
 
153
- #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
154
- def initialize(from_boundary:, to_boundary:, diff:, from_snapshot: nil, to_snapshot: nil)
200
+ #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
201
+ def initialize(from_boundary:, to_boundary:, diff:, from_snapshot: nil, to_snapshot: nil, sources: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
155
202
  @from_boundary = from_boundary
156
203
  @to_boundary = to_boundary
157
204
  @diff = diff
158
205
  @from_snapshot = from_snapshot
159
206
  @to_snapshot = to_snapshot
207
+ @sources = (sources || [from_boundary]).dup.freeze
160
208
  freeze
161
209
  end
162
210
 
@@ -170,13 +218,22 @@ module PaperTrailDiff
170
218
  #: () -> ActivityBoundary
171
219
  def source_boundary = from_boundary
172
220
 
221
+ # The diff as flat rows, each attributed to `source_boundary`.
222
+ #: () -> Array[ChangeRow]
223
+ def change_rows
224
+ ChangeRows.call(diff, source: source_boundary)
225
+ end
226
+
227
+ # `metadata: true` also lists `sources`, since who made a change is
228
+ # metadata as much as the source boundary's own author is.
173
229
  #: (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
174
230
  def to_h(metadata: false, snapshots: false)
175
231
  value = {
176
232
  from: from_boundary.to_h(metadata: metadata),
177
233
  to: to_boundary.to_h(metadata: metadata),
178
234
  diff: diff.to_h
179
- }
235
+ } #: Hash[Symbol, untyped]
236
+ value[:sources] = sources.map { |source| source.to_h(metadata: true) } if metadata
180
237
  return value unless snapshots
181
238
 
182
239
  value.merge(from_snapshot: from_snapshot&.to_h, to_snapshot: to_snapshot&.to_h)
@@ -62,7 +62,8 @@ module PaperTrailDiff
62
62
 
63
63
  #: (untyped) -> untyped
64
64
  def historical_relation(version_class)
65
- @parent_class.paper_trail.version_association_class.joins(:version).where(
65
+ associations = @parent_class.paper_trail.version_association_class
66
+ VersionTable.joined(associations, version_class).where(
66
67
  foreign_key_name: @reflection.foreign_key.to_s,
67
68
  foreign_key_id: @parent_ids,
68
69
  foreign_type: parent_types
@@ -14,7 +14,8 @@ module PaperTrailDiff
14
14
 
15
15
  #: (Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> bool
16
16
  def safe?(routes, version, delta)
17
- !unsafe_through_membership_event?(routes, version) &&
17
+ !scoped_route?(routes) &&
18
+ !unsafe_through_membership_event?(routes, version) &&
18
19
  !unsafe_nested_membership_delta?(routes, delta)
19
20
  end
20
21
 
@@ -62,6 +63,15 @@ module PaperTrailDiff
62
63
  @route_updater.call(snapshot, change).fetch(0)
63
64
  end
64
65
 
66
+ # Any edit can move a record into or out of a scope, so a scoped route's
67
+ # branch is read again from history instead.
68
+ #: (Array[Array[untyped]]) -> bool
69
+ def scoped_route?(routes)
70
+ routes.any? do |route|
71
+ route.any? { |entry| ScopeCondition.scoped_path?(entry.fetch(1)) }
72
+ end
73
+ end
74
+
65
75
  #: (Array[Array[untyped]], untyped) -> bool
66
76
  def unsafe_through_membership_event?(routes, version)
67
77
  return false if version.event.to_s == 'update'
@@ -33,12 +33,13 @@ module PaperTrailDiff
33
33
  #: (AssociationSnapshot, untyped, RecordSnapshot?) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]
34
34
  def call(association, version, replacement)
35
35
  records = association.records
36
- position = association.position(replacement_type(version, replacement), version.item_id)
36
+ position = association.position(replacement_type(version, replacement), version.item_id) ||
37
+ retyped_position(association, version)
37
38
  return [records, nil, nil, true] unless replacement || position
38
39
 
39
40
  before = records.fetch(position) if position
40
41
  updated = replacement_records(records, position, replacement)
41
- [updated, before, replacement, !before.nil? && !replacement.nil?]
42
+ [updated, before, replacement, !!before && before.identity == replacement&.identity]
42
43
  end
43
44
 
44
45
  #: (untyped, RecordSnapshot?) -> String
@@ -52,6 +53,19 @@ module PaperTrailDiff
52
53
 
53
54
  # @rbs @relationship: ActivityRelationship
54
55
 
56
+ # A row whose STI type changed is the same row under a new identity, so it
57
+ # is found by id among the records of its table.
58
+ #: (AssociationSnapshot, untyped) -> Integer?
59
+ def retyped_position(association, version)
60
+ position = association.position_for_id(version.item_id)
61
+ return unless position
62
+
63
+ type = association.records.fetch(position).type
64
+ position if Object.const_get(type).base_class == Endpoint.model_class(version).base_class
65
+ rescue NameError
66
+ nil
67
+ end
68
+
55
69
  #: (Array[RecordSnapshot], Integer?, RecordSnapshot?) -> Array[RecordSnapshot]
56
70
  def replacement_records(records, position, replacement)
57
71
  updated = records.dup
@@ -7,10 +7,11 @@ module PaperTrailDiff
7
7
  attr_reader :version #: untyped
8
8
  attr_reader :branches #: Array[String]?
9
9
 
10
- #: (version: untyped, branches: Array[String]?) -> void
11
- def initialize(version:, branches:)
10
+ #: (version: untyped, branches: Array[String]?, ?join: bool) -> void
11
+ def initialize(version:, branches:, join: false)
12
12
  @version = version
13
13
  @branches = branches ? branches.map(&:to_s).uniq.sort.freeze : nil
14
+ @join = join
14
15
  freeze
15
16
  end
16
17
 
@@ -18,6 +19,15 @@ module PaperTrailDiff
18
19
  def root?
19
20
  branches.nil?
20
21
  end
22
+
23
+ # Whether the version is of a through's join row, which links the root to
24
+ # a target without being one.
25
+ #: () -> bool
26
+ def join?
27
+ @join
28
+ end
29
+
30
+ # @rbs @join: bool
21
31
  end
22
32
 
23
33
  # Accumulates each version once while retaining every selected root branch.
@@ -26,14 +36,15 @@ module PaperTrailDiff
26
36
  @events = {} #: Hash[Array[untyped], Hash[Symbol, untyped]]
27
37
  end
28
38
 
29
- #: (Array[untyped], ?branch: String?) -> void
30
- def add(versions, branch: nil)
39
+ #: (Array[untyped], ?branch: String?, ?join: bool) -> void
40
+ def add(versions, branch: nil, join: false)
31
41
  versions.each do |version|
32
42
  key = [version.class.name, version.id]
33
43
  existing = @events[key]
34
44
  @events[key] = {
35
45
  version: version,
36
- branches: merged_branches(existing, branch)
46
+ branches: merged_branches(existing, branch),
47
+ join: join || existing&.fetch(:join) || false
37
48
  }
38
49
  end
39
50
  end
@@ -43,7 +54,8 @@ module PaperTrailDiff
43
54
  @events.values.map do |event|
44
55
  ActivityEvent.new(
45
56
  version: event.fetch(:version),
46
- branches: event.fetch(:branches)
57
+ branches: event.fetch(:branches),
58
+ join: event.fetch(:join)
47
59
  )
48
60
  end
49
61
  end
@@ -64,6 +76,28 @@ module PaperTrailDiff
64
76
 
65
77
  # Resolves the branch union that PT-AT exposes atomically for one transaction.
66
78
  class ActivityTransactionGroups
79
+ # A range ending at a version ends at the state before that version's
80
+ # transaction: PT-AT rebuilds its associations without the changes saved
81
+ # alongside it. A descendant version from that transaction, such as the
82
+ # child update behind a `touch: true` parent version, is therefore past the
83
+ # end. Kept, it would open a step whose change the closing state cannot
84
+ # show, and that change would be reported nowhere. A range ending at a time
85
+ # has no transaction to stop before.
86
+ #: (Array[ActivityEvent], untyped) -> Array[ActivityEvent]
87
+ def self.before_closing(events, range_end)
88
+ key = transaction_key(range_end)
89
+ return events unless key
90
+
91
+ events.reject { |event| !event.root? && transaction_key(event.version) == key }.freeze
92
+ end
93
+
94
+ # A version without a transaction shares one with nothing.
95
+ #: (untyped) -> Array[untyped]?
96
+ def self.transaction_key(version)
97
+ transaction_id = VersionBoundary.transaction_id(version)
98
+ [version.class.name, transaction_id] if transaction_id
99
+ end
100
+
67
101
  #: (Array[ActivityEvent]) -> void
68
102
  def initialize(events)
69
103
  groups = grouped_events(events)
@@ -119,10 +153,7 @@ module PaperTrailDiff
119
153
 
120
154
  #: (ActivityEvent) -> Array[untyped]?
121
155
  def transaction_key(event)
122
- version = event.version
123
- return unless version.respond_to?(:transaction_id) && version.transaction_id
124
-
125
- [version.class.name, version.transaction_id]
156
+ self.class.transaction_key(event.version)
126
157
  end
127
158
  end
128
159
  end
@@ -129,7 +129,26 @@ module PaperTrailDiff
129
129
  return unless before
130
130
 
131
131
  attributes = before.attributes.merge(after_attributes(changes, model))
132
- @direct_loader.complete(PreparedRecordState.from_attributes(model, attributes))
132
+ model_after = class_after(model, attributes)
133
+ return unless model_after
134
+
135
+ @direct_loader.complete(PreparedRecordState.from_attributes(model_after, attributes))
136
+ end
137
+
138
+ # Without `item_subtype` a version names only the STI base class, and a
139
+ # change can move the row to another class, so the type the row holds
140
+ # after the change decides. A type that names no class has no direct
141
+ # state; the caller falls back to reifying the record.
142
+ #: (untyped, Hash[untyped, untyped]) -> untyped
143
+ def class_after(model, attributes)
144
+ column = model.inheritance_column.to_s
145
+ return model unless model.columns_hash.key?(column)
146
+
147
+ type = attributes[column].to_s
148
+ type.empty? ? model.base_class : model.base_class.sti_class_for(type)
149
+ rescue StandardError => e
150
+ active_record = Object.const_get(:ActiveRecord) #: untyped
151
+ raise unless e.is_a?(active_record.const_get(:SubclassNotFound))
133
152
  end
134
153
 
135
154
  #: (untyped) -> untyped
@@ -70,7 +70,8 @@ module PaperTrailDiff
70
70
  entry = [name, reflection, subtree, child_path]
71
71
  direct = [] #: Array[Array[untyped]]
72
72
  direct << [entry] if direct_route?(reflection, target_type, macro)
73
- return direct if subtree.empty? || reflection.polymorphic?
73
+ # Validation rejects a path that continues past a polymorphic target.
74
+ return direct if subtree.empty?
74
75
 
75
76
  nested = routes(reflection.klass, subtree, target_type, macro, path: child_path)
76
77
  direct.concat(nested.map { |route| [entry, *route] })
@@ -111,7 +111,7 @@ module PaperTrailDiff
111
111
 
112
112
  #: (untyped) -> untyped
113
113
  def endpoint_model_class(endpoint)
114
- Endpoint.version?(endpoint) ? Endpoint.model_class(endpoint) : endpoint.class
114
+ Endpoint.version?(endpoint) ? RecordedClass.for(endpoint) : endpoint.class
115
115
  end
116
116
  end
117
117
  end