paper_trail_diff 0.15.0 → 0.17.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 (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +724 -1
  3. data/README.md +43 -8
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +89 -32
  6. data/docs/reference.md +427 -96
  7. data/docs/testing.md +260 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +39 -6
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +8 -7
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +31 -36
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
  73. data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +99 -0
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +92 -32
  84. data/lib/paper_trail_diff/scope_ranking.rb +27 -34
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +40 -22
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +9 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +235 -75
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +41 -23
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +32 -44
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +31 -7
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -2,40 +2,47 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Loads direct-child identities active at or after one activity boundary.
5
+ # Loads the children of a has_many or has_one that its owners had from a
6
+ # start onward, from PT-AT's version associations and the live rows.
7
+ # Prepared history and activity both read children through it. A composite
8
+ # foreign key reads none, as loaded history cannot index it.
6
9
  class ActivityChildCandidateLoader
7
- #: (untyped, Array[untyped], untyped, ActivityRange) -> void
8
- def initialize(parent_class, parent_ids, reflection, range)
10
+ #: (untyped, Array[untyped], untyped, untyped) -> void
11
+ def initialize(parent_class, parent_ids, reflection, start_at)
9
12
  @parent_class = parent_class
10
13
  @parent_ids = parent_ids
11
14
  @reflection = reflection
12
- @range = range
15
+ @start_at = start_at
16
+ @foreign_key = AssociationKey.scalar_foreign_key(reflection)
13
17
  end
14
18
 
15
- #: () -> Array[untyped]
16
- def call
17
- historical_ids | current_ids
18
- end
19
-
20
- # One shared query retains the owner and timestamp needed to partition a
21
- # batch's candidates back into each root's exact activity range.
19
+ # Queries shared by a batch's roots keep the owner and timestamp needed to
20
+ # partition its candidates back into each root's exact activity range.
22
21
  #: () -> Array[Array[untyped]]
23
22
  def historical_rows
23
+ foreign_key = @foreign_key
24
+ return [] unless foreign_key
25
+
24
26
  version_class = @parent_class.paper_trail.version_class
25
- versions = version_class.arel_table
26
- associations = @parent_class.paper_trail.version_association_class.arel_table
27
- typed_rows(
28
- candidate_scope(version_class).call(historical_relation(version_class)).distinct.pluck(
29
- associations[:foreign_key_id], versions[:item_id], versions[:created_at], versions[:event]
30
- )
31
- )
27
+ scope = VersionAssociationCandidateScope.new(version_class, @start_at)
28
+ owner_slices.flat_map do |owners|
29
+ relation = scope.call(historical_relation(version_class, foreign_key, owners))
30
+ typed_rows(pluck_rows(relation, version_class))
31
+ end
32
32
  end
33
33
 
34
34
  #: () -> Array[Array[untyped]]
35
35
  def current_pairs
36
- relation = @reflection.klass.base_class.unscoped.where(@reflection.foreign_key => @parent_ids)
37
- relation = relation.where(@reflection.type => parent_types) if @reflection.options[:as]
38
- relation.distinct.pluck(@reflection.foreign_key, @reflection.klass.primary_key)
36
+ foreign_key = @foreign_key
37
+ return [] unless foreign_key
38
+
39
+ # Every row of the table, as history reads them: an STI subclass's
40
+ # siblings are left out where children are resolved.
41
+ owner_slices.flat_map do |owners|
42
+ relation = @reflection.klass.base_class.unscoped.where(foreign_key => owners)
43
+ relation = relation.where(@reflection.type => parent_types) if @reflection.type
44
+ relation.pluck(foreign_key, @reflection.klass.primary_key)
45
+ end
39
46
  end
40
47
 
41
48
  private
@@ -43,7 +50,8 @@ module PaperTrailDiff
43
50
  # @rbs @parent_class: untyped
44
51
  # @rbs @parent_ids: Array[untyped]
45
52
  # @rbs @reflection: untyped
46
- # @rbs @range: ActivityRange
53
+ # @rbs @start_at: untyped
54
+ # @rbs @foreign_key: String?
47
55
 
48
56
  #: (Array[Array[untyped]]) -> Array[Array[untyped]]
49
57
  def typed_rows(rows)
@@ -52,52 +60,33 @@ module PaperTrailDiff
52
60
  end
53
61
  end
54
62
 
55
- #: () -> Array[untyped]
56
- def historical_ids
57
- version_class = @parent_class.paper_trail.version_class
58
- candidate_scope(version_class).call(historical_relation(version_class))
59
- .distinct.pluck(version_class.arel_table[:item_id])
60
- .map { |id| Support.record_id(@reflection.klass, id) }
63
+ # Each statement reads the children of 500 owners.
64
+ #: () -> Enumerator[Array[untyped], untyped]
65
+ def owner_slices
66
+ @parent_ids.each_slice(Support::IDS_PER_STATEMENT)
61
67
  end
62
68
 
63
- #: (untyped) -> untyped
64
- def historical_relation(version_class)
69
+ #: (untyped, String, Array[untyped]) -> untyped
70
+ def historical_relation(version_class, foreign_key, owners)
65
71
  associations = @parent_class.paper_trail.version_association_class
66
72
  VersionTable.joined(associations, version_class).where(
67
- foreign_key_name: @reflection.foreign_key.to_s,
68
- foreign_key_id: @parent_ids,
73
+ foreign_key_name: foreign_key,
74
+ foreign_key_id: owners,
69
75
  foreign_type: parent_types
70
- ).where(version_class.table_name => { item_type: child_item_type })
71
- end
72
-
73
- #: (untyped) -> VersionAssociationCandidateScope
74
- def candidate_scope(version_class)
75
- VersionAssociationCandidateScope.new(
76
- version_class,
77
- @range.start_time,
78
- end_at: @range.end_time
79
- )
80
- end
81
-
82
- #: () -> Array[untyped]
83
- def current_ids
84
- return [] unless @range.current_end?
85
-
86
- relation = @reflection.klass.base_class.unscoped.where(
87
- @reflection.foreign_key => @parent_ids
88
- )
89
- relation = relation.where(@reflection.type => parent_types) if @reflection.options[:as]
90
- relation.distinct.pluck(@reflection.klass.primary_key)
76
+ ).where(version_class.table_name => { item_type: @reflection.klass.base_class.name })
91
77
  end
92
78
 
93
- #: () -> String
94
- def child_item_type
95
- @reflection.klass.base_class.name
79
+ #: (untyped, untyped) -> Array[Array[untyped]]
80
+ def pluck_rows(relation, version_class)
81
+ versions = version_class.arel_table
82
+ associations = @parent_class.paper_trail.version_association_class.arel_table
83
+ relation.pluck(associations[:foreign_key_id], versions[:item_id], versions[:created_at],
84
+ versions[:event])
96
85
  end
97
86
 
98
87
  #: () -> Array[String?]
99
88
  def parent_types
100
- [nil, '', @parent_class.name.to_s, @parent_class.base_class.name.to_s].uniq
89
+ [nil, '', @parent_class.name, @parent_class.base_class.name]
101
90
  end
102
91
  end
103
92
  end
@@ -14,9 +14,10 @@ module PaperTrailDiff
14
14
 
15
15
  #: (Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> bool
16
16
  def safe?(routes, version, delta)
17
- !scoped_route?(routes) &&
17
+ !ActivityEventRouteFinder.scoped_route?(routes) &&
18
18
  !unsafe_through_membership_event?(routes, version) &&
19
- !unsafe_nested_membership_delta?(routes, delta)
19
+ !unsafe_nested_membership_delta?(routes, delta) &&
20
+ !unsafe_owned_relationship_delta?(routes, delta)
20
21
  end
21
22
 
22
23
  #: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> [bool, RecordSnapshot]
@@ -63,15 +64,6 @@ module PaperTrailDiff
63
64
  @route_updater.call(snapshot, change).fetch(0)
64
65
  end
65
66
 
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
-
75
67
  #: (Array[Array[untyped]], untyped) -> bool
76
68
  def unsafe_through_membership_event?(routes, version)
77
69
  return false if version.event.to_s == 'update'
@@ -92,6 +84,36 @@ module PaperTrailDiff
92
84
  end
93
85
  end
94
86
 
87
+ # A delta replaces a record's attributes and keeps its associations, so an
88
+ # edit to a key one of them follows, such as a comment's `reviewer_id`
89
+ # under `comments.reviewer`, would leave the old target in place. The
90
+ # branch is read again instead.
91
+ #: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
92
+ def unsafe_owned_relationship_delta?(routes, delta)
93
+ return false unless delta
94
+
95
+ routes.any? do |route|
96
+ _name, reflection, subtree, = route.last
97
+ subtree.children.each_key.any? do |name|
98
+ keys = owned_keys(reflection.klass.reflect_on_association(name))
99
+ keys.any? { |key| delta.changed?(key) }
100
+ end
101
+ end
102
+ end
103
+
104
+ # The record's own columns that decide what an association of it holds: a
105
+ # belongs_to's key and type, or those of the belongs_to a through starts
106
+ # from. A has_one or has_many follows the record's primary key.
107
+ #: (untyped) -> Array[untyped]
108
+ def owned_keys(reflection)
109
+ return [] unless reflection
110
+ return owned_keys(reflection.through_reflection) if reflection.through_reflection?
111
+ return [] unless reflection.belongs_to?
112
+
113
+ keys = Array(reflection.foreign_key)
114
+ reflection.polymorphic? ? [*keys, reflection.foreign_type] : keys
115
+ end
116
+
95
117
  #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> [untyped, RecordSnapshot?]
96
118
  def route_event_state( # rubocop:disable Metrics/ParameterLists
97
119
  snapshot, route, version, delta, fallback_record, normalizer, endpoints, direct: false
@@ -106,7 +106,7 @@ module PaperTrailDiff
106
106
 
107
107
  #: (AssociationSnapshot, untyped, ActivityCollectionRouteChange) -> Integer?
108
108
  def nested_owner_position(association, reflection, change)
109
- membership_record = change.record || change.version.reify(dup: true)
109
+ membership_record = change.record || Support.reify(change.version, dup: true)
110
110
  return unless membership_record
111
111
  return if membership_record.is_a?(ActivitySnapshotDelta) &&
112
112
  membership_record.relationship_changed?(reflection)
@@ -10,7 +10,7 @@ module PaperTrailDiff
10
10
  #: (version: untyped, branches: Array[String]?, ?join: bool) -> void
11
11
  def initialize(version:, branches:, join: false)
12
12
  @version = version
13
- @branches = branches ? branches.map(&:to_s).uniq.sort.freeze : nil
13
+ @branches = branches ? branches.uniq.sort.freeze : nil
14
14
  @join = join
15
15
  freeze
16
16
  end
@@ -39,7 +39,7 @@ module PaperTrailDiff
39
39
  #: (Array[untyped], ?branch: String?, ?join: bool) -> void
40
40
  def add(versions, branch: nil, join: false)
41
41
  versions.each do |version|
42
- key = [version.class.name, version.id]
42
+ key = Support.row_key(version)
43
43
  existing = @events[key]
44
44
  @events[key] = {
45
45
  version: version,
@@ -98,57 +98,69 @@ module PaperTrailDiff
98
98
  [version.class.name, transaction_id] if transaction_id
99
99
  end
100
100
 
101
- #: (Array[ActivityEvent]) -> void
102
- def initialize(events)
101
+ # An `opening` transaction began before the history's start, so its
102
+ # versions there are not events, yet the state after it has their changes
103
+ # (see PreparedHistoryLoader#reload). The snapshot after
104
+ # it is read whole rather than refreshed from its events alone.
105
+ #: (Array[ActivityEvent], ?opening: Array[Array[untyped]]) -> void
106
+ def initialize(events, opening: [])
103
107
  groups = grouped_events(events)
104
108
  @branches = build_groups(groups)
105
109
  @group_sizes = groups.transform_values(&:length)
110
+ @opening = opening
106
111
  end
107
112
 
113
+ # An event outside a transaction, or in one it was not given, keeps its
114
+ # own.
108
115
  #: (ActivityEvent) -> Array[String]?
109
116
  def branches_for(event)
110
117
  key = transaction_key(event)
111
- return event.branches unless key && @branches.key?(key)
118
+ return if @opening.include?(key)
112
119
 
113
- @branches[key]
120
+ @branches.fetch(key) { event.branches }
114
121
  end
115
122
 
116
123
  #: (ActivityEvent) -> bool
117
124
  def isolated?(event)
118
125
  key = transaction_key(event)
119
- !key || @group_sizes.fetch(key, 0) == 1
126
+ !key || (@group_sizes[key] == 1 && !@opening.include?(key))
127
+ end
128
+
129
+ # Whether two events were saved in one transaction that began inside the
130
+ # history.
131
+ #: (ActivityEvent, ActivityEvent) -> bool
132
+ def shared?(left, right)
133
+ key = transaction_key(left)
134
+ !key.nil? && key == transaction_key(right) && !@opening.include?(key)
120
135
  end
121
136
 
122
137
  private
123
138
 
124
- # @rbs @branches: Hash[Array[untyped], Array[String]?]
125
- # @rbs @group_sizes: Hash[Array[untyped], Integer]
139
+ # @rbs @branches: Hash[Array[untyped]?, Array[String]?]
140
+ # @rbs @group_sizes: Hash[Array[untyped]?, Integer]
141
+ # @rbs @opening: Array[untyped]
126
142
 
127
- #: (Hash[Array[untyped], Array[ActivityEvent]]) -> Hash[Array[untyped], Array[String]?]
143
+ #: (Hash[Array[untyped]?, Array[ActivityEvent]]) -> Hash[Array[untyped]?, Array[String]?]
128
144
  def build_groups(groups)
129
145
  groups.to_h do |key, selected_events|
130
146
  [key, group_branches(selected_events)]
131
147
  end
132
148
  end
133
149
 
134
- #: (Array[ActivityEvent]) -> Hash[Array[untyped], Array[ActivityEvent]]
150
+ # The events of each transaction; one outside a transaction is in none.
151
+ #: (Array[ActivityEvent]) -> Hash[Array[untyped]?, Array[ActivityEvent]]
135
152
  def grouped_events(events)
136
- groups = {} #: Hash[Array[untyped], Array[ActivityEvent]]
137
- events.each do |event|
138
- key = transaction_key(event)
139
- next unless key
140
-
141
- groups[key] ||= [] #: Array[ActivityEvent]
142
- groups[key] << event
143
- end
144
- groups
153
+ events.group_by { |event| transaction_key(event) }.except(nil)
145
154
  end
146
155
 
156
+ # A transaction with a root event is read as the root's; every other
157
+ # event has branches.
147
158
  #: (Array[ActivityEvent]) -> Array[String]?
148
159
  def group_branches(events)
149
160
  return if events.any?(&:root?)
150
161
 
151
- events.flat_map { |event| event.branches || [] }.uniq.sort.freeze
162
+ branches = events.flat_map(&:branches) #: Array[String]
163
+ branches.uniq.sort.freeze
152
164
  end
153
165
 
154
166
  #: (ActivityEvent) -> Array[untyped]?
@@ -4,55 +4,29 @@
4
4
  module PaperTrailDiff
5
5
  # Reconstructs an event's post-change record or immutable scalar delta.
6
6
  class ActivityEventRecordResolver
7
- RECORD_AFTER_HANDLERS = {
8
- 'create' => :created_record_after,
9
- 'update' => :updated_record_after
10
- }.freeze
11
- private_constant :RECORD_AFTER_HANDLERS
12
-
13
7
  #: (?record_transition: untyped, ?prepared_record_after: untyped) -> void
14
8
  def initialize(record_transition: nil, prepared_record_after: nil)
15
9
  @record_transition = record_transition
16
10
  @prepared_record_after = prepared_record_after
17
- @direct_loader = DirectRecordStateLoader.new
18
11
  end
19
12
 
13
+ # The record as the version left it: the state recorded next, which holds
14
+ # any change saved after the version without one of its own. Prepared
15
+ # history answers without a query; without it, the next version or the
16
+ # live row does.
20
17
  #: (untyped, ?direct: bool) -> untyped
21
18
  def record_after(version, direct: false)
22
19
  return if version.event.to_s == 'destroy'
23
20
 
24
21
  if direct
25
- handled, state = direct_after(version)
22
+ handled, state = @prepared_record_after&.call(version, direct: true)
26
23
  return state if handled
27
24
  end
28
25
 
29
26
  handled, prepared = @prepared_record_after&.call(version)
30
27
  return prepared if handled
31
28
 
32
- fallback_record_after(version)
33
- end
34
-
35
- #: (untyped) -> [bool, untyped]
36
- def direct_after(version)
37
- handled, state = @prepared_record_after&.call(version, direct: true)
38
- return [true, state] if handled
39
-
40
- state = direct_record_after(version)
41
- [!state.nil?, state]
42
- end
43
-
44
- #: (untyped) -> untyped
45
- def fallback_record_after(version)
46
- changed_record = changed_record_after(version)
47
- return changed_record if changed_record
48
-
49
- successor = version.next
50
- record = successor&.reify(dup: true)
51
- return record if record
52
-
53
- model_class = Endpoint.model_class(version)
54
- criteria = { model_class.primary_key => version.item_id } #: Hash[untyped, untyped]
55
- model_class.unscoped.find_by(criteria)
29
+ recorded_after(version)
56
30
  end
57
31
 
58
32
  #: (untyped) -> ActivitySnapshotDelta?
@@ -68,28 +42,6 @@ module PaperTrailDiff
68
42
  )
69
43
  end
70
44
 
71
- #: (untyped) -> untyped
72
- def changed_record_after(version)
73
- handler = RECORD_AFTER_HANDLERS[version.event.to_s]
74
- send(handler, version) if handler
75
- end
76
-
77
- #: (untyped) -> untyped
78
- def created_record_after(version)
79
- model_class = Endpoint.model_class(version)
80
- changes = deserialized_changeset(version, model_class)
81
- return unless changes.respond_to?(:each) && !changes.empty?
82
-
83
- model_class.new(after_attributes(changes, model_class))
84
- end
85
-
86
- #: (untyped) -> untyped
87
- def updated_record_after(version)
88
- record = version.reify(dup: true)
89
- changes = deserialized_changeset(version, record&.class)
90
- apply_changes(record, changes)
91
- end
92
-
93
45
  # Mirrors PaperTrail's changeset deserialization without resolving
94
46
  # +version.item+, which would issue one live-record query per event.
95
47
  #: (untyped, untyped) -> untyped
@@ -111,44 +63,16 @@ module PaperTrailDiff
111
63
 
112
64
  # @rbs @record_transition: untyped
113
65
  # @rbs @prepared_record_after: untyped
114
- # @rbs @direct_loader: DirectRecordStateLoader
115
-
116
- #: (untyped) -> PreparedRecordState?
117
- def direct_record_after(version)
118
- model = Endpoint.model_class(version)
119
- changes = deserialized_changeset(version, model)
120
- return unless changes.respond_to?(:each) && !changes.empty?
121
-
122
- before = if version.object
123
- @direct_loader.call(version)
124
- else
125
- PreparedRecordState.from_attributes(
126
- model, {}
127
- )
128
- end
129
- return unless before
130
-
131
- attributes = before.attributes.merge(after_attributes(changes, model))
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
66
 
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))
67
+ #: (untyped) -> untyped
68
+ def recorded_after(version)
69
+ successor = version.next
70
+ record = successor && Support.reify(successor, dup: true)
71
+ return record if record
72
+
73
+ model_class = Endpoint.model_class(version)
74
+ criteria = { model_class.primary_key => version.item_id } #: Hash[untyped, untyped]
75
+ model_class.unscoped.find_by(criteria)
152
76
  end
153
77
 
154
78
  #: (untyped) -> untyped
@@ -162,33 +86,9 @@ module PaperTrailDiff
162
86
  end.to_h
163
87
  end
164
88
 
165
- #: (untyped, untyped) -> Hash[untyped, untyped]
166
- def after_attributes(changes, model_class)
167
- names = model_class.attribute_names
168
- attributes = {} #: Hash[untyped, untyped]
169
- changes.each do |name, values|
170
- next unless names.include?(name.to_s)
171
-
172
- attributes[name] = values.last
173
- end
174
- attributes
175
- end
176
-
177
- #: (untyped, untyped) -> untyped
178
- def apply_changes(record, changes)
179
- return unless record && changes.respond_to?(:each) && !changes.empty?
180
-
181
- changes.each do |name, values|
182
- next unless record.has_attribute?(name) && values.respond_to?(:last)
183
-
184
- record[name] = values.last
185
- end
186
- record
187
- end
188
-
189
89
  #: (untyped, untyped, untyped) -> untyped
190
90
  def standard_changeset(paper_trail, version, model_class)
191
- raw_changes = version.send(:object_changes_deserialized)
91
+ raw_changes = Support.decodable(version.send(:object_changes_deserialized))
192
92
  active_support = Object.const_get(:ActiveSupport) #: untyped
193
93
  changes = active_support.const_get(:HashWithIndifferentAccess).new(raw_changes)
194
94
  serializers = paper_trail.const_get(:AttributeSerializers)
@@ -4,11 +4,20 @@
4
4
  module PaperTrailDiff
5
5
  # Finds explicitly selected collection and belongs-to routes for one event type.
6
6
  class ActivityEventRouteFinder
7
+ # An edit can move a record into or out of a scope, which a change in
8
+ # place cannot show, so an event on a scoped route has its branch read
9
+ # again from history instead.
10
+ #: (Array[Array[untyped]]) -> bool
11
+ def self.scoped_route?(routes)
12
+ routes.any? { |route| route.any? { |entry| ScopeCondition.scoped_path?(entry.fetch(1)) } }
13
+ end
14
+
7
15
  #: (AssociationTraversal) -> void
8
16
  def initialize(traversal)
9
17
  @traversal = traversal
10
18
  @collection_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
11
19
  @belongs_to_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
20
+ @through_parts = {} #: Hash[Array[untyped], bool]
12
21
  end
13
22
 
14
23
  #: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
@@ -21,28 +30,51 @@ module PaperTrailDiff
21
30
  cached(@belongs_to_routes, model_class, tree, target_type, path, :belongs_to)
22
31
  end
23
32
 
33
+ # Whether a has_many through in the tree joins through, or reaches,
34
+ # records of the type. Its membership follows their keys, which a route
35
+ # to the record elsewhere in the tree does not update.
36
+ #: (untyped, AssociationTree, String) -> bool
37
+ def through_part?(model_class, tree, target_type)
38
+ @through_parts.fetch([model_class, tree, target_type]) do |key|
39
+ @through_parts[key] = through_part_below?(model_class, tree, target_type, '')
40
+ end
41
+ end
42
+
24
43
  private
25
44
 
26
45
  # @rbs @traversal: AssociationTraversal
27
46
  # @rbs @collection_routes: Hash[Array[untyped], Array[Array[untyped]]]
28
47
  # @rbs @belongs_to_routes: Hash[Array[untyped], Array[Array[untyped]]]
48
+ # @rbs @through_parts: Hash[Array[untyped], bool]
49
+
50
+ # Validation rejects a path that continues past a polymorphic target, so
51
+ # only a target of one class has a subtree to search.
52
+ #: (untyped, AssociationTree, String, String) -> bool
53
+ def through_part_below?(model_class, tree, target_type, path)
54
+ @traversal.reflections_for(model_class, tree, path: path).any? do |reflection|
55
+ subtree = tree.child(reflection.name) #: AssociationTree
56
+ below = Support.association_path(path, reflection.name)
57
+ through_reaches?(reflection, target_type) ||
58
+ (!subtree.empty? && through_part_below?(reflection.klass, subtree, target_type, below))
59
+ end
60
+ end
61
+
62
+ #: (untyped, String) -> bool
63
+ def through_reaches?(reflection, target_type)
64
+ reflection.through_reflection? &&
65
+ reflection.chain.any? { |part| part.klass.base_class.name == target_type }
66
+ end
29
67
 
30
68
  # Timelines interleave event types, so every requested combination is
31
69
  # retained. Model, tree, and path are fixed per adapter, leaving one entry
32
- # per selected item type.
70
+ # per selected item type. The strings are kept as frozen copies, which a
71
+ # caller cannot change.
33
72
  #: (Hash[Array[untyped], Array[Array[untyped]]], untyped, AssociationTree, String, String, Symbol) -> Array[Array[untyped]]
34
73
  def cached(store, model_class, tree, target_type, path, macro) # rubocop:disable Metrics/ParameterLists
35
- key = [model_class, tree, target_type, path]
36
- existing = store[key]
37
- return existing if existing
38
-
39
- store[cache_key(key)] =
40
- freeze_routes(routes(model_class, tree, target_type, macro, path: path))
41
- end
42
-
43
- #: (Array[untyped]) -> Array[untyped]
44
- def cache_key(key)
45
- key.map { |part| part.is_a?(String) ? -part : part }.freeze
74
+ store.fetch([model_class, tree, target_type, path]) do
75
+ store[[model_class, tree, -target_type, -path]] =
76
+ freeze_routes(routes(model_class, tree, target_type, macro, path: path))
77
+ end
46
78
  end
47
79
 
48
80
  #: (Array[Array[untyped]]) -> Array[Array[untyped]]
@@ -54,18 +86,17 @@ module PaperTrailDiff
54
86
  end
55
87
 
56
88
  #: (untyped, AssociationTree, String, Symbol, path: String) -> Array[Array[untyped]]
57
- def routes(model_class, tree, target_type, macro, path: '')
89
+ def routes(model_class, tree, target_type, macro, path:)
58
90
  @traversal.reflections_for(model_class, tree, path: path).flat_map do |reflection|
59
91
  routes_for_reflection(reflection, tree, target_type, macro, path)
60
92
  end
61
93
  end
62
94
 
95
+ # Each reflection is of a child the tree names.
63
96
  #: (untyped, AssociationTree, String, Symbol, String) -> Array[Array[untyped]]
64
97
  def routes_for_reflection(reflection, tree, target_type, macro, path)
65
98
  name = reflection.name.to_s
66
- subtree = tree.child(name)
67
- return [] unless subtree
68
-
99
+ subtree = tree.child(name) #: AssociationTree
69
100
  child_path = Support.association_path(path, name)
70
101
  entry = [name, reflection, subtree, child_path]
71
102
  direct = [] #: Array[Array[untyped]]
@@ -80,12 +111,12 @@ module PaperTrailDiff
80
111
  #: (untyped, String, Symbol) -> bool
81
112
  def direct_route?(reflection, target_type, macro)
82
113
  reflection.macro == macro && supported_direct_reflection?(reflection, macro) &&
83
- reflection.klass.base_class.name.to_s == target_type
114
+ reflection.klass.base_class.name == target_type
84
115
  end
85
116
 
86
117
  #: (untyped, Symbol) -> bool
87
118
  def supported_direct_reflection?(reflection, macro)
88
- return !reflection.options[:through] if macro == :has_many
119
+ return !reflection.through_reflection? if macro == :has_many
89
120
 
90
121
  !reflection.polymorphic?
91
122
  end
@@ -61,11 +61,11 @@ module PaperTrailDiff
61
61
 
62
62
  tree, normalizer = @components.call(branches)
63
63
  routes = @route_finder.collection_routes(
64
- endpoint_model_class(root_endpoint), tree, event.version.item_type.to_s
64
+ RecordedClass.of_endpoint(root_endpoint), tree, event.version.item_type.to_s
65
65
  )
66
66
  unless routes.empty?
67
67
  delta = @record_resolver.snapshot_delta(event.version)
68
- return [false, nil] unless @collection_applier.safe?(routes, event.version, delta)
68
+ return [false, nil] unless collection_safe?(root_endpoint, tree, routes, event, delta)
69
69
 
70
70
  return @collection_applier.call(
71
71
  root_endpoint,
@@ -99,6 +99,17 @@ module PaperTrailDiff
99
99
 
100
100
  private :belongs_to_applier, :collection_applier, :collection_updater, :configure_appliers
101
101
 
102
+ # A through's membership follows the keys of the records it joins through
103
+ # or reaches, which a route to such a record elsewhere in the tree leaves
104
+ # alone, so the branch is read again instead.
105
+ #: (untyped, AssociationTree, Array[Array[untyped]], ActivityEvent, ActivitySnapshotDelta?) -> bool
106
+ def collection_safe?(root_endpoint, tree, routes, event, delta)
107
+ version = event.version
108
+ !@route_finder.through_part?(RecordedClass.of_endpoint(root_endpoint), tree,
109
+ version.item_type.to_s) &&
110
+ @collection_applier.safe?(routes, version, delta)
111
+ end
112
+
102
113
  #: (untyped) -> untyped
103
114
  def record_after(version)
104
115
  @record_resolver.record_after(version, direct: true)
@@ -108,10 +119,5 @@ module PaperTrailDiff
108
119
  def deserialized_changeset(version, model_class)
109
120
  @record_resolver.deserialized_changeset(version, model_class)
110
121
  end
111
-
112
- #: (untyped) -> untyped
113
- def endpoint_model_class(endpoint)
114
- Endpoint.version?(endpoint) ? RecordedClass.for(endpoint) : endpoint.class
115
- end
116
122
  end
117
123
  end