paper_trail_diff 0.16.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 +566 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -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 +3 -13
  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 +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -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 +74 -40
  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 +194 -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 +19 -5
  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 +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  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 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  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 +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +170 -42
  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 +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  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 +41 -19
  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 +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  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 +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -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 +192 -91
  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 +37 -21
  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 +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  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 +0 -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 +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -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 +36 -2
  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 +121 -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 +15 -6
  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 +9 -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 +11 -5
  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 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  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 +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +103 -14
  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 +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  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 +27 -8
  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 +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  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 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -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 +111 -52
  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 +15 -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 +13 -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 +28 -6
  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
@@ -147,7 +147,7 @@ module PaperTrailDiff
147
147
  #: (untyped, TimeRange?) -> void
148
148
  def initialize(reflection, time_range)
149
149
  super
150
- @table = arel::Table.new(reflection.join_table)
150
+ @table = Support.arel::Table.new(reflection.join_table)
151
151
  columns = join_columns
152
152
  @type = columns.fetch(reflection.foreign_key)
153
153
  @filter_type = columns.fetch(reflection.association_foreign_key)
@@ -166,7 +166,7 @@ module PaperTrailDiff
166
166
 
167
167
  #: () -> Hash[String, Symbol?]
168
168
  def join_columns
169
- connected do |connection|
169
+ Support.with_connection(@owner) do |connection|
170
170
  connection.columns(@reflection.join_table).to_h { |column| [column.name, column.type] }
171
171
  end
172
172
  end
@@ -176,30 +176,11 @@ module PaperTrailDiff
176
176
  # mutant:disable
177
177
  #: () -> untyped
178
178
  def quoted_owner_column
179
- connected do |connection|
180
- arel.sql("#{connection.quote_table_name(@reflection.join_table)}." \
181
- "#{connection.quote_column_name(@reflection.foreign_key)}")
179
+ Support.with_connection(@owner) do |connection|
180
+ Support.arel.sql("#{connection.quote_table_name(@reflection.join_table)}." \
181
+ "#{connection.quote_column_name(@reflection.foreign_key)}")
182
182
  end
183
183
  end
184
-
185
- # Arel ships no signatures; see VersionQuery. Any spelling of the
186
- # constant finds the same module.
187
- # mutant:disable
188
- #: () -> untyped
189
- def arel
190
- Object.const_get(:Arel)
191
- end
192
-
193
- # Active Record 7.1 has no `with_connection`; see VersionAssociationCandidateScope.
194
- # Only that version takes the fallback, so no spec run on a newer one can
195
- # tell its mutations apart.
196
- # mutant:disable
197
- #: [T] () { (untyped) -> T } -> T
198
- def connected(&block)
199
- return @owner.with_connection(&block) if @owner.respond_to?(:with_connection)
200
-
201
- yield(@owner.connection)
202
- end
203
184
  end
204
185
 
205
186
  # The owners whose versions PT-AT recorded a HABTM target with, keyed by
@@ -15,9 +15,6 @@ module PaperTrailDiff
15
15
  # per root. Ids stay in a subquery while the columns compared share a type;
16
16
  # otherwise they are read and the edge runs over them in slices.
17
17
  class AssociationActivitySelection
18
- SLICE = 250
19
- private_constant :SLICE
20
-
21
18
  # The ids a one-column subquery selects, with that column's type: a
22
19
  # database compares columns of one type only, and PostgreSQL rejects an
23
20
  # integer key against a string item_id outright.
@@ -56,11 +53,14 @@ module PaperTrailDiff
56
53
  sources.flat_map { |ids| ids.is_a?(Query) ? ids.values : ids }.uniq
57
54
  end
58
55
 
59
- #: (untyped, tree: AssociationTree, time_range: TimeRange?) -> void
60
- def initialize(model, tree:, time_range:)
56
+ # Only the versions `version_scope` keeps select a root, on its
57
+ # associations as on its own versions.
58
+ #: (untyped, tree: AssociationTree, time_range: TimeRange?, ?version_scope: untyped) -> void
59
+ def initialize(model, tree:, time_range:, version_scope: nil)
61
60
  @model = model
62
61
  @traversal = AssociationTraversal.new(tree)
63
62
  @time_range = time_range
63
+ @version_scope = version_scope
64
64
  end
65
65
 
66
66
  # The roots' ids, each source a subquery or an array of values.
@@ -74,6 +74,7 @@ module PaperTrailDiff
74
74
  # @rbs @model: untyped
75
75
  # @rbs @traversal: AssociationTraversal
76
76
  # @rbs @time_range: TimeRange?
77
+ # @rbs @version_scope: untyped
77
78
 
78
79
  # Ids of `model` records with a change somewhere below them in `tree`: the
79
80
  # targets that changed, or that reach a change further down.
@@ -126,7 +127,7 @@ module PaperTrailDiff
126
127
  edge = AssociationActivityEdge::BelongsTo.new(reflection, @time_range)
127
128
  edge.target_types.flat_map do |name|
128
129
  typed = AssociationActivityEdge::BelongsTo.new(reflection, @time_range, foreign_type: name)
129
- follow(typed, changed(target_class(name)))
130
+ follow(typed, changed(AssociationTraversal.named_class(name)))
130
131
  end
131
132
  end
132
133
 
@@ -148,10 +149,10 @@ module PaperTrailDiff
148
149
  return [] unless Support.versioned?(model)
149
150
 
150
151
  versions = model.paper_trail.version_class
151
- relation = versions.where(item_type: model.base_class.name)
152
- relation = relation.where(item_id: item_ids) if item_ids
152
+ relation = item_ids ? VersionQuery.for_items(model, item_ids) : VersionQuery.for_model(model)
153
153
  range = @time_range
154
154
  relation = range.scope(relation) if range
155
+ relation = @version_scope.call(relation) if @version_scope
155
156
  [Query.new(relation, versions.arel_table[:item_id],
156
157
  versions.type_for_attribute('item_id').type)]
157
158
  end
@@ -172,7 +173,7 @@ module PaperTrailDiff
172
173
 
173
174
  #: (AssociationActivityEdge, Array[untyped]) -> Array[untyped]
174
175
  def read(edge, values)
175
- values.each_slice(SLICE).flat_map do |slice|
176
+ values.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
176
177
  edge.relation(slice).pluck(edge.column)
177
178
  end.compact.uniq
178
179
  end
@@ -184,14 +185,5 @@ module PaperTrailDiff
184
185
  def subquery(source, type)
185
186
  source if source.is_a?(Query) && source.type == type
186
187
  end
187
-
188
- # A type naming no class has no versions to read; `changed` skips one that
189
- # names an unversioned class.
190
- #: (String) -> untyped
191
- def target_class(name)
192
- Object.const_get(name)
193
- rescue NameError
194
- nil
195
- end
196
188
  end
197
189
  end
@@ -69,7 +69,7 @@ module PaperTrailDiff
69
69
 
70
70
  #: (untyped, prefix: String, ancestry: Array[untyped], depth: Integer) -> Array[AssociationDescriptor]
71
71
  def describe_and_descend(reflection, prefix:, ancestry:, depth:)
72
- path = association_path(prefix, reflection.name.to_s)
72
+ path = Support.association_path(prefix, reflection.name)
73
73
  target_class = reflection_target(reflection)
74
74
  cycle = target_class ? ancestry.include?(target_class) : false
75
75
  descriptor = descriptor_for(reflection, path, target_class, cycle)
@@ -126,10 +126,5 @@ module PaperTrailDiff
126
126
  def reflection_target_name(reflection)
127
127
  reflection.class_name.to_s unless reflection.polymorphic?
128
128
  end
129
-
130
- #: (String, String) -> String
131
- def association_path(prefix, name)
132
- prefix.empty? ? name : "#{prefix}.#{name}"
133
- end
134
129
  end
135
130
  end
@@ -18,16 +18,19 @@ module PaperTrailDiff
18
18
  'history is recorded by primary key'
19
19
  end
20
20
 
21
+ # The association's foreign key column, or nil for a composite key, which
22
+ # loaded history cannot index. Active Record names a column as a string.
23
+ #: (untyped) -> String?
24
+ def self.scalar_foreign_key(reflection)
25
+ key = reflection.foreign_key
26
+ key unless key.is_a?(Array)
27
+ end
28
+
21
29
  # The reflection, or the first part of a through, keyed on a column other
22
30
  # than its owner's or target's primary key.
23
31
  #: (untyped) -> untyped
24
32
  def self.keyed_part(reflection)
25
- return reflection if other_key?(reflection)
26
- return unless reflection.through_reflection?
27
-
28
- [reflection.through_reflection, reflection.source_reflection].filter_map do |part|
29
- keyed_part(part)
30
- end.first
33
+ [reflection, *AssociationTraversal.through_parts(reflection)].find { |part| other_key?(part) }
31
34
  end
32
35
  private_class_method :keyed_part
33
36
 
@@ -31,6 +31,17 @@ module PaperTrailDiff
31
31
  source_type.nil? || type == source_type.to_s
32
32
  end
33
33
 
34
+ # Every part a through passes, at any depth: its through part and that
35
+ # part's own parts, then its source part and that part's own parts.
36
+ #: (untyped) -> Array[untyped]
37
+ def self.through_parts(reflection)
38
+ return [] unless reflection.through_reflection?
39
+
40
+ [reflection.through_reflection, reflection.source_reflection].flat_map do |part|
41
+ [part, *through_parts(part)]
42
+ end
43
+ end
44
+
34
45
  # The class a stored type names, or nil when it names none.
35
46
  # This class defines no constants of its own, so the one mutation left,
36
47
  # `const_get` on it rather than on Object, finds the same class.
@@ -42,6 +53,15 @@ module PaperTrailDiff
42
53
  nil
43
54
  end
44
55
 
56
+ # The class a belongs_to's target is, given the type a polymorphic one
57
+ # stored: nil when that names no class.
58
+ #: (untyped, untyped) -> untyped
59
+ def self.stored_target(reflection, type)
60
+ return reflection.klass unless reflection.polymorphic?
61
+
62
+ named_class(type.to_s)
63
+ end
64
+
45
65
  # A type left by a renamed or removed model names no class. Active Record
46
66
  # and PT-AT raise a bare NameError for it, which does not say where it is.
47
67
  #: (untyped, untyped, String) -> untyped
@@ -159,6 +179,7 @@ module PaperTrailDiff
159
179
  def initialize(tree)
160
180
  @tree = tree
161
181
  @reflection_cache = {}
182
+ @habtm_paths = {} #: Hash[untyped, Array[String]]
162
183
  end
163
184
 
164
185
  #: (untyped) -> void
@@ -171,6 +192,18 @@ module PaperTrailDiff
171
192
  collect_reflections(model_class, @tree, path: '').freeze
172
193
  end
173
194
 
195
+ # The names the versions of the records on the requested paths are stored
196
+ # under: each association's class and every part a through passes. A
197
+ # polymorphic belongs_to names its target's class only in each record, so
198
+ # it adds none.
199
+ #: (untyped) -> Array[String]
200
+ def path_types(model_class)
201
+ selected_reflections(model_class).flat_map do |_path, reflection|
202
+ parts = [reflection, *self.class.through_parts(reflection)].reject(&:polymorphic?)
203
+ parts.map { |part| part.klass.base_class.name }
204
+ end.uniq
205
+ end
206
+
174
207
  #: (untyped, untyped) -> void
175
208
  def ensure_habtm_history!(model_class, version)
176
209
  paths = habtm_paths(model_class)
@@ -181,11 +214,18 @@ module PaperTrailDiff
181
214
  raise IncompleteAssociationHistoryError, message
182
215
  end
183
216
 
217
+ # Every snapshot of a version asks, so each class's answer is kept; the
218
+ # tree and the class decide it. Reading it again each time answers the
219
+ # same, which is why mutant leaves the cache alone.
220
+ # mutant:disable
184
221
  #: (untyped) -> Array[String]
185
222
  def habtm_paths(model_class)
186
- selected_reflections(model_class).filter_map do |path, reflection|
187
- path if habtm_reflection?(reflection)
188
- end.freeze
223
+ @habtm_paths.fetch(model_class) do
224
+ selected = selected_reflections(model_class)
225
+ @habtm_paths[model_class] = selected.filter_map do |path, reflection|
226
+ path if habtm_reflection?(reflection)
227
+ end.freeze
228
+ end
189
229
  end
190
230
 
191
231
  # HABTM join rows have no versions of their own, so membership changes
@@ -203,10 +243,12 @@ module PaperTrailDiff
203
243
  # A model and a tree resolve to the same reflections wherever they are
204
244
  # read: a tree is only ever walked from one place, the root tree at the
205
245
  # root and a subtree below it. Beyond that, the path only names a failure,
206
- # and a failure is not cached.
246
+ # and a failure is not cached. Each record is read at every boundary, so
247
+ # the lookup builds no key.
207
248
  #: (untyped, AssociationTree, path: String) -> Array[untyped]
208
249
  def reflections_for(model_class, tree, path:)
209
- @reflection_cache[[model_class, tree]] ||= requested_reflections(model_class, tree, path)
250
+ by_class = @reflection_cache[tree] ||= {}
251
+ by_class[model_class] ||= requested_reflections(model_class, tree, path)
210
252
  end
211
253
 
212
254
  # Active Record names keys as strings. A polymorphic child also points back
@@ -222,7 +264,8 @@ module PaperTrailDiff
222
264
  private
223
265
 
224
266
  # @rbs @tree: AssociationTree
225
- # @rbs @reflection_cache: Hash[Array[untyped], Array[untyped]]
267
+ # @rbs @reflection_cache: Hash[AssociationTree, Hash[untyped, Array[untyped]]]
268
+ # @rbs @habtm_paths: Hash[untyped, Array[String]]
226
269
 
227
270
  #: (untyped, AssociationTree, path: String) -> Array[Array[untyped]]
228
271
  def collect_reflections(model_class, tree, path:)
@@ -2,16 +2,16 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Resolves `:first` endpoints for a whole batch in a fixed number of queries per
6
- # model class. Left to the caller this is a per-root lookup, which reintroduces
7
- # exactly the queries a batched comparison exists to remove.
5
+ # Resolves `:first` endpoints for a whole batch in one query per 500 roots
6
+ # of a model class. Left to the caller this is a per-root lookup, which
7
+ # reintroduces exactly the queries a batched comparison exists to remove.
8
8
  class BatchBoundaryResolver
9
9
  BOUNDARIES = %i[first].freeze
10
10
 
11
11
  class << self
12
12
  #: (untyped) -> bool
13
13
  def symbolic?(endpoint)
14
- endpoint.is_a?(Symbol)
14
+ endpoint.instance_of?(Symbol)
15
15
  end
16
16
  end
17
17
 
@@ -25,11 +25,11 @@ module PaperTrailDiff
25
25
  # decide what an absent history means rather than being handed nil.
26
26
  #: () -> Array[[untyped, untyped]]
27
27
  def call
28
- return @pairs unless @pairs.flatten(1).any? { |endpoint| symbolic?(endpoint) }
28
+ return @pairs unless @pairs.flatten.any? { |endpoint| symbolic?(endpoint) }
29
29
 
30
- index = boundary_index
30
+ firsts = first_versions
31
31
  @pairs.map do |from, to|
32
- [resolve(from, to, index), resolve(to, from, index)]
32
+ [resolve(from, to, firsts), resolve(to, from, firsts)]
33
33
  end
34
34
  end
35
35
 
@@ -42,8 +42,8 @@ module PaperTrailDiff
42
42
  self.class.symbolic?(endpoint)
43
43
  end
44
44
 
45
- #: (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
46
- def resolve(endpoint, other, index)
45
+ #: (untyped, untyped, Hash[Array[String], untyped]) -> untyped
46
+ def resolve(endpoint, other, firsts)
47
47
  return endpoint unless symbolic?(endpoint)
48
48
  raise ConfigurationError, TimelineRange::LAST_REMOVED if endpoint == :last
49
49
 
@@ -58,71 +58,62 @@ module PaperTrailDiff
58
58
  'a :first endpoint needs the other endpoint to name a record'
59
59
  end
60
60
 
61
- index.dig(identity, endpoint) || endpoint
61
+ firsts[identity] || endpoint
62
62
  end
63
63
 
64
64
  # A symbol carries no identity of its own, so the pair's other endpoint has
65
65
  # to say which record is meant.
66
66
  #: (untyped) -> Array[String]?
67
67
  def anchor_identity(endpoint)
68
- return if endpoint.nil? || symbolic?(endpoint)
69
-
70
68
  Endpoint.identity(endpoint)
71
69
  rescue InvalidEndpointError
72
70
  nil
73
71
  end
74
72
 
75
- #: () -> Hash[Array[String], Hash[Symbol, untyped]]
76
- def boundary_index
77
- index = {} #: Hash[Array[String], Hash[Symbol, untyped]]
78
- anchors.group_by { |model_class, _id| model_class }.each do |model_class, entries|
79
- add_model_boundaries(index, model_class, entries.map { |_klass, id| id }.uniq)
73
+ # Each named record's earliest version, by the record's identity, in one
74
+ # statement for each 500 records of a model class.
75
+ #: () -> Hash[Array[String], untyped]
76
+ def first_versions
77
+ firsts = {} #: Hash[Array[String], untyped]
78
+ anchors.group_by(&:first).each do |model_class, entries|
79
+ firsts.merge!(first_versions_of(model_class, entries.map(&:last)))
80
80
  end
81
- index
81
+ firsts
82
82
  end
83
83
 
84
+ # The model of each endpoint that names a record, with the record or its
85
+ # versions' id: a query reads a record's own id, as BatchedRootVersions'
86
+ # does. A version of a model that no longer exists names none, so its pair
87
+ # keeps its symbol.
84
88
  #: () -> Array[[untyped, untyped]]
85
89
  def anchors
86
- @pairs.flatten(1).filter_map { |endpoint| anchor(endpoint) }.uniq
90
+ @pairs.flatten.filter_map { |endpoint| anchor(endpoint) }
87
91
  end
88
92
 
89
93
  #: (untyped) -> [untyped, untyped]?
90
94
  def anchor(endpoint)
91
- return if endpoint.nil? || symbolic?(endpoint)
92
-
93
95
  if Endpoint.version?(endpoint)
94
96
  [Endpoint.model_class(endpoint), endpoint.item_id]
95
97
  elsif Endpoint.record?(endpoint)
96
- [endpoint.class, endpoint.id]
98
+ [endpoint.class, endpoint]
97
99
  end
98
100
  rescue InvalidEndpointError
99
101
  nil
100
102
  end
101
103
 
102
- #: (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
103
- def add_model_boundaries(index, model_class, ids)
104
- firsts = first_versions(model_class, ids)
105
- ids.each do |id|
106
- index[identity_key(model_class, id)] = { first: firsts[id.to_s] }
107
- end
108
- end
109
-
110
- # Each root's earliest version by time, in one query whatever the size of
111
- # the batch. The lowest id is not the earliest version when ids are not
104
+ # Each root's earliest version by time, in one query for every 500 roots.
105
+ # The lowest id is not the earliest version when ids are not
112
106
  # sequential, as with UUIDs, so time decides and the usual ordering breaks
113
107
  # a tie -- refusing one that ids cannot order.
114
- #: (untyped, Array[untyped]) -> Hash[String, untyped]
115
- def first_versions(model_class, ids)
108
+ #: (untyped, Array[untyped]) -> Hash[Array[String], untyped]
109
+ def first_versions_of(model_class, ids)
116
110
  table = model_class.paper_trail.version_class.arel_table
117
- candidates = VersionQuery.for_items(model_class, ids)
118
- .where(VersionQuery.no_earlier_version(table)).to_a
119
- candidates.group_by { |version| version.item_id.to_s }
111
+ first = VersionQuery.no_earlier_version(table)
112
+ candidates = ids.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
113
+ VersionQuery.for_items(model_class, slice).where(first)
114
+ end
115
+ candidates.group_by { |version| Support.record_identity(model_class, version.item_id) }
120
116
  .transform_values { |versions| Support.chronological_sort(versions).first }
121
117
  end
122
-
123
- #: (untyped, untyped) -> Array[String]
124
- def identity_key(model_class, id)
125
- [model_class.base_class.name.to_s, id.to_s]
126
- end
127
118
  end
128
119
  end
@@ -35,19 +35,9 @@ module PaperTrailDiff
35
35
  #: (untyped) -> bool
36
36
  def self.cut_part?(reflection)
37
37
  reflection.collection? &&
38
- (ScopeCondition.ranked_parts?(reflection) || through_parts(reflection).any?(&:has_one?))
38
+ (ScopeCondition.ranked_parts?(reflection) ||
39
+ AssociationTraversal.through_parts(reflection).any?(&:has_one?))
39
40
  end
40
41
  private_class_method :cut_part?
41
-
42
- # Every part a through passes, at any depth.
43
- #: (untyped) -> Array[untyped]
44
- def self.through_parts(reflection)
45
- return [] unless reflection.through_reflection?
46
-
47
- [reflection.through_reflection, reflection.source_reflection].flat_map do |part|
48
- [part, *through_parts(part)]
49
- end
50
- end
51
- private_class_method :through_parts
52
42
  end
53
43
  end
@@ -0,0 +1,72 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Prepares the association history of a batch's roots, once per model class
6
+ # across every version the batch replays, then analyzes each root from its
7
+ # plan over its own window. AnalysisBatch and DeletedAnalysisBatch differ
8
+ # only in how they find their roots and plans.
9
+ class BatchedRootAnalyses
10
+ # A root whose window moved to the start of a transaction crossing its
11
+ # edge has its window in `windows`; the others take `time_range`.
12
+ #: (time_range: TimeRange?, windows: Hash[Array[String], TimeRange], history_preparer: untyped, analyzer: untyped) -> void
13
+ def initialize(time_range:, windows:, history_preparer:, analyzer:)
14
+ @time_range = time_range
15
+ @windows = windows
16
+ @history_preparer = history_preparer
17
+ @analyzer = analyzer
18
+ end
19
+
20
+ # Preparation reads the roots' current association state as a fallback,
21
+ # so a batch that has already loaded them passes them as `loaded`, rather
22
+ # than have preparation walk that state one root at a time.
23
+ #: (Array[untyped], Hash[Array[String], RootVersionPlan], ?loaded: Hash[Array[String], untyped]) -> Hash[Array[String], Analysis]
24
+ def call(records, plans, loaded: {})
25
+ records.group_by(&:class).each_value { |group| prepare(group, plans, loaded) }
26
+ records.to_h do |record|
27
+ key = Endpoint.identity(record)
28
+ window = @windows.fetch(key, @time_range)
29
+ [Support.immutable_copy(key), analysis(record, plans.fetch(key), window)]
30
+ end
31
+ end
32
+
33
+ private
34
+
35
+ # @rbs @time_range: TimeRange?
36
+ # @rbs @windows: Hash[Array[String], TimeRange]
37
+ # @rbs @history_preparer: untyped
38
+ # @rbs @analyzer: untyped
39
+
40
+ # Roots that close on their current state are prepared even without a
41
+ # version in the window, since their descendants may have changed there.
42
+ #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
43
+ def prepare(records, plans, loaded)
44
+ selected = records.map { |record| plans.fetch(Endpoint.identity(record)) }
45
+ versions = selected.flat_map(&:reconstruction_versions)
46
+ live = selected.any?(&:closing_record)
47
+ return if versions.empty? && !live
48
+
49
+ roots = records.map { |record| loaded.fetch(Endpoint.identity(record), record) }
50
+ @history_preparer.call(roots, versions, **preparation_range(versions, live: live))
51
+ end
52
+
53
+ # A plan closing on the live record reads history up to now; the others
54
+ # stop at the window's end or at the last version they replay past it, so
55
+ # a past window does not load everything since.
56
+ #: (Array[untyped], live: bool) -> Hash[Symbol, untyped]
57
+ def preparation_range(versions, live:)
58
+ ends = [versions.map(&:created_at).max, @time_range&.end_time, (Time.now.utc if live)]
59
+ { start_at: TransactionCut.earliest_start(@time_range, @windows), end_at: ends.compact.max }
60
+ end
61
+
62
+ # A root with no versions in range has nothing to report, which is an
63
+ # empty result rather than a failed request -- unless it closes on its
64
+ # current state, where its descendants may still have moved.
65
+ #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
66
+ def analysis(record, plan, window)
67
+ return @analyzer.empty.with_window(window) if plan.empty? && !plan.closing_record
68
+
69
+ @analyzer.call(record, plan, window).with_window(window)
70
+ end
71
+ end
72
+ end
@@ -5,27 +5,31 @@ module PaperTrailDiff
5
5
  # Builds one root's Analysis inside a batch, from versions the batch already
6
6
  # selected and history it already prepared.
7
7
  class BatchedRootAnalyzer
8
- #: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, ?within: untyped) -> void
9
- def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:, view:, within: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
10
- @tree = tree
8
+ # `traversal` holds the tree and reads its reflections for every root of
9
+ # the batch.
10
+ #: (timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, traversal: AssociationTraversal) -> void
11
+ def initialize( # rubocop:disable Metrics/ParameterLists
12
+ timeline_snapshotter:, activity_snapshotter:, preparer:, activity:, view:, traversal:
13
+ )
14
+ @traversal = traversal
11
15
  @timeline_snapshotter = timeline_snapshotter
12
16
  @activity_snapshotter = activity_snapshotter
13
17
  @preparer = preparer
14
18
  @activity = activity
15
19
  @view = view
16
- @within = within
17
20
  end
18
21
 
19
- # `window` is the root's window as the batch moved it to transaction edges.
20
- #: (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
21
- def call(record, plan, window = nil)
22
+ # `window` is the root's window as the batch moved it to transaction edges,
23
+ # or nil when the batch reads each root's whole history.
24
+ #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
25
+ def call(record, plan, window)
22
26
  @preparer.call(record.class, historical: true)
23
27
  return activity_analysis(record, plan, window) if @activity
24
28
 
25
29
  TimelineBuilder.new(
26
30
  record,
27
31
  from: plan.versions.first,
28
- to: plan.closing_record || plan.versions.last,
32
+ to: plan.final_endpoint,
29
33
  within: nil,
30
34
  plan: plan,
31
35
  snapshotter: @timeline_snapshotter
@@ -40,23 +44,21 @@ module PaperTrailDiff
40
44
 
41
45
  private
42
46
 
43
- # @rbs @tree: AssociationTree
47
+ # @rbs @traversal: AssociationTraversal
44
48
  # @rbs @timeline_snapshotter: untyped
45
49
  # @rbs @activity_snapshotter: untyped
46
50
  # @rbs @preparer: untyped
47
51
  # @rbs @activity: bool
48
- # @rbs @within: untyped
49
52
  # @rbs @view: ActivityView
50
53
 
51
54
  #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
52
55
  def activity_analysis(record, plan, window)
53
56
  range = TimelineRange.new(
54
- record, from: (@within ? nil : plan.versions.first),
55
- to: (@within ? nil : plan.closing_record || plan.versions.last),
56
- within: (window || @within if @within), plan: plan
57
+ record, from: (plan.versions.first unless window), to: (plan.final_endpoint unless window),
58
+ within: window, plan: plan
57
59
  )
58
60
  ActivityTimelineBuilder.new(
59
- record, range: range, tree: @tree, snapshotter: @activity_snapshotter, view: @view
61
+ record, range: range, snapshotter: @activity_snapshotter, view: @view, traversal: @traversal
60
62
  ).analyze
61
63
  end
62
64
  end