paper_trail_diff 0.16.0 → 0.17.1

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 +581 -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 +329 -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 +197 -45
  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 +27 -16
  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 +194 -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 +114 -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 +10 -9
  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
@@ -6,12 +6,15 @@ module PaperTrailDiff
6
6
  class DeletedAnalysisBatch
7
7
  # `context_required` reads a root that did not change in the window from
8
8
  # the version after it, so its associations' activity can be reported.
9
- #: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool) -> void
9
+ # `traversal` names the requested paths, which decide where a window's
10
+ # edges move (see TransactionCut).
11
+ #: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool, traversal: AssociationTraversal?) -> void
10
12
  def initialize( # rubocop:disable Metrics/ParameterLists
11
13
  model, identities:, time_range:, analyzer:, history_preparer:, version_scope:,
12
- context_required:
14
+ context_required:, traversal:
13
15
  )
14
16
  @model = model
17
+ @traversal = traversal
15
18
  @context_required = context_required
16
19
  @identities = identities
17
20
  @time_range = time_range
@@ -24,30 +27,23 @@ module PaperTrailDiff
24
27
  def call
25
28
  destroys = destroy_versions
26
29
  records = historical_roots(destroys)
27
- windows = TransactionCut.batch_windows(records, @time_range)
28
- selected = plans(records, destroys, windows)
29
- prepare(records, selected, windows)
30
- analyses = records.to_h do |record|
31
- key = Endpoint.identity(record)
32
- [key, analysis_for(record, selected.fetch(key), windows.fetch(key, @time_range))]
33
- end
30
+ windows = TransactionCut.batch_windows(records, @time_range, traversal: @traversal)
31
+ analyses = BatchedRootAnalyses.new(
32
+ time_range: @time_range, windows: windows, history_preparer: @history_preparer,
33
+ analyzer: @analyzer
34
+ ).call(records, plans(records, destroys, windows))
34
35
  with_unavailable(analyses)
35
36
  end
36
37
 
37
38
  private
38
39
 
39
- #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
40
- def analysis_for(record, plan, window)
41
- analysis = plan.empty? ? @analyzer.empty : @analyzer.call(record, plan, window)
42
- analysis.with_window(window)
43
- end
44
-
45
40
  #: (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
46
41
  def with_unavailable(analyses)
47
42
  @identities.to_h { |key| [Support.immutable_copy(key), analyses[key]] }.freeze
48
43
  end
49
44
 
50
45
  # @rbs @model: untyped
46
+ # @rbs @traversal: AssociationTraversal?
51
47
  # @rbs @context_required: bool
52
48
  # @rbs @identities: Array[Array[String]]
53
49
  # @rbs @time_range: TimeRange?
@@ -56,7 +52,10 @@ module PaperTrailDiff
56
52
  # @rbs @version_scope: untyped
57
53
 
58
54
  # A root destroyed before the window had no state inside it to read, so
59
- # only the others take the version after the window as context.
55
+ # only the others take the version after the window as context. Every
56
+ # root replays the whole of its window for activity on associations: one
57
+ # whose destroy saved in a transaction that crossed the window's start
58
+ # has the destroy inside its moved window.
60
59
  #: (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
61
60
  def plans(records, destroys, windows)
62
61
  start = @time_range&.begin_time
@@ -70,7 +69,8 @@ module PaperTrailDiff
70
69
  def plans_for(records, context_required, windows)
71
70
  BatchedRootVersions.new(
72
71
  records, time_range: @time_range, version_scope: @version_scope,
73
- live_endpoints: nil, context_required: context_required, windows: windows
72
+ live_endpoints: nil, context_required: context_required,
73
+ whole: @context_required, windows: windows
74
74
  ).call
75
75
  end
76
76
 
@@ -88,28 +88,13 @@ module PaperTrailDiff
88
88
  end
89
89
  end
90
90
 
91
+ # Each statement reads the destroys of 500 records.
91
92
  #: () -> Array[untyped]
92
93
  def destroy_versions
93
- destroys = VersionQuery.for_items(@model, @identities.map(&:last)).where(event: 'destroy')
94
- # Oldest first, so each item keeps its latest destroy.
95
- VersionQuery.chronological(destroys).index_by(&:item_id).values
96
- end
97
-
98
- #: (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
99
- def preparation_range(versions, windows)
100
- { start_at: TransactionCut.earliest_start(@time_range, windows),
101
- end_at: [@time_range&.end_time, versions.map(&:created_at).max].compact.max }
102
- end
103
-
104
- #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
105
- def prepare(records, selected, windows)
106
- records.group_by(&:class).each_value do |group|
107
- versions = group.flat_map do |record|
108
- selected.fetch(Endpoint.identity(record)).reconstruction_versions
109
- end
110
- next if versions.empty?
111
-
112
- @history_preparer.call(group, versions, **preparation_range(versions, windows))
94
+ @identities.map(&:last).each_slice(Support::IDS_PER_STATEMENT).flat_map do |ids|
95
+ destroys = VersionQuery.for_items(@model, ids).where(event: 'destroy')
96
+ # Oldest first, so each item keeps its latest destroy.
97
+ VersionQuery.chronological(destroys).index_by(&:item_id).values
113
98
  end
114
99
  end
115
100
  end
@@ -7,9 +7,6 @@ module PaperTrailDiff
7
7
  # table, where a destroyed root has no row, so without this a report on one
8
8
  # account's records would include every account's deletions.
9
9
  class DeletedRootFilter
10
- SLICE = 500
11
- private_constant :SLICE
12
-
13
10
  #: (untyped) -> void
14
11
  def initialize(relation)
15
12
  @relation = relation
@@ -76,7 +73,7 @@ module PaperTrailDiff
76
73
  #: (Array[String]) -> Hash[String, Hash[String, untyped]?]
77
74
  def destroyed_states(ids)
78
75
  states = {} #: Hash[String, Hash[String, untyped]?]
79
- ids.each_slice(SLICE) do |slice|
76
+ ids.each_slice(Support::IDS_PER_STATEMENT) do |slice|
80
77
  destroys = VersionQuery.for_items(model, slice).where(event: 'destroy')
81
78
  VersionQuery.chronological(destroys).each do |version|
82
79
  states[version.item_id.to_s] =
@@ -94,8 +91,8 @@ module PaperTrailDiff
94
91
  # mutant:disable
95
92
  #: (untyped) -> Hash[String, untyped]?
96
93
  def reified_attributes(version)
97
- version.reify(dup: true, has_many: false, has_one: false, belongs_to: false,
98
- has_and_belongs_to_many: false)&.attributes
94
+ Support.reify(version, dup: true, has_many: false, has_one: false, belongs_to: false,
95
+ has_and_belongs_to_many: false)&.attributes
99
96
  end
100
97
  end
101
98
  end
@@ -2,21 +2,13 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Warns about options that do nothing any more and will be removed. In a
6
- # Rails app, register the deprecator to configure it with the app's own:
5
+ # Warns about options that are deprecated and will be removed. None is now,
6
+ # but the deprecator stays, so that an app that registered it still boots
7
+ # and hears of the next one. In a Rails app, register it to configure it
8
+ # with the app's own:
7
9
  #
8
10
  # Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator
9
11
  module Deprecation
10
- CLOSE_ON = 'close_on: is deprecated and has no effect: a window already closes on the ' \
11
- 'current record when nothing on its requested paths was recorded after it. ' \
12
- 'Remove the option.'
13
- ALLOW_EXPENSIVE = 'allow_expensive: is deprecated and has no effect: allow_approximate: true ' \
14
- 'alone accepts a path read with PT-AT, in batch methods too. Remove the ' \
15
- 'option.'
16
- RELOAD_LIVE_ENDPOINTS = 'reload_live_endpoints: is deprecated and will be removed: skipping ' \
17
- 'the reload saves a query for the records and one per association ' \
18
- 'level, and reads values that may be stale. Remove the option.'
19
-
20
12
  # Required when first used, as the library loads nothing it does not need.
21
13
  #: () -> untyped
22
14
  def self.deprecator
@@ -26,36 +18,5 @@ module PaperTrailDiff
26
18
  active_support.const_get(:Deprecation).new('a future release', 'paper_trail_diff')
27
19
  end
28
20
  end
29
-
30
- # The one value close_on: took. It named what ends a wall-clock window,
31
- # so it was meaningless without one, and until it is removed it is still
32
- # checked as it was.
33
- CLOSE_ON_CURRENT = :current
34
-
35
- #: (Symbol?, untyped) -> void
36
- def self.close_on!(close_on, within)
37
- return if close_on.nil?
38
- unless close_on == CLOSE_ON_CURRENT
39
- raise ConfigurationError, "close_on: must be #{CLOSE_ON_CURRENT.inspect} or nil"
40
- end
41
- raise ConfigurationError, 'close_on: requires `within`' if within.nil?
42
-
43
- deprecator.warn(CLOSE_ON)
44
- end
45
-
46
- #: (untyped) -> void
47
- def self.allow_expensive!(allow_expensive)
48
- deprecator.warn(ALLOW_EXPENSIVE) unless allow_expensive.nil?
49
- end
50
-
51
- # The value to use: the option still works until it is removed, and nil
52
- # stands for its old default.
53
- #: (untyped) -> untyped
54
- def self.reload_live_endpoints!(reload)
55
- return true if reload.nil?
56
-
57
- deprecator.warn(RELOAD_LIVE_ENDPOINTS)
58
- reload
59
- end
60
21
  end
61
22
  end
@@ -78,8 +78,7 @@ module PaperTrailDiff
78
78
  @versions = validated_versions(from, to)
79
79
  @tree = AssociationTree.build(associations)
80
80
  @traversal = AssociationTraversal.new(@tree)
81
- @preparer = TraversalPreparer.new(tree: @tree, traversal: @traversal,
82
- allow_approximate: allow_approximate)
81
+ @preparer = TraversalPreparer.new(traversal: @traversal, allow_approximate: allow_approximate)
83
82
  @allow_approximate = allow_approximate
84
83
  @issues = [] #: Array[DiagnosticIssue]
85
84
  end
@@ -10,12 +10,18 @@ module PaperTrailDiff
10
10
  @loader = PreparedVersionStateLoader.new
11
11
  @supported = {} #: Hash[untyped, bool]
12
12
  @defaults = {} #: Hash[untyped, Hash[untyped, untyped]]
13
+ @states = {} #: Hash[Array[untyped], PreparedRecordState?]
13
14
  end
14
15
 
16
+ # Each version is read once: activity reads a root's version again at
17
+ # every event it bounds, and decoding it is most of the cost.
15
18
  #: (untyped) -> PreparedRecordState?
16
19
  def call(version)
20
+ key = Support.row_key(version)
21
+ return @states[key] if @states.key?(key)
22
+
17
23
  state = @loader.call(version)
18
- complete(state) if state
24
+ @states[key] = state && complete(state)
19
25
  end
20
26
 
21
27
  #: (PreparedRecordState) -> PreparedRecordState?
@@ -35,6 +41,7 @@ module PaperTrailDiff
35
41
  # @rbs @loader: PreparedVersionStateLoader
36
42
  # @rbs @supported: Hash[untyped, bool]
37
43
  # @rbs @defaults: Hash[untyped, Hash[untyped, untyped]]
44
+ # @rbs @states: Hash[Array[untyped], PreparedRecordState?]
38
45
 
39
46
  #: (untyped) -> bool
40
47
  def supported?(model)
@@ -4,10 +4,8 @@
4
4
  module PaperTrailDiff
5
5
  # Validates and describes explicit PaperTrail-version and live-record endpoints.
6
6
  module Endpoint
7
- module_function
8
-
9
7
  #: (untyped, untyped) -> void
10
- def validate_pair!(from_endpoint, to_endpoint)
8
+ def self.validate_pair!(from_endpoint, to_endpoint)
11
9
  validate!(from_endpoint)
12
10
  validate!(to_endpoint)
13
11
  unless identity(from_endpoint) == identity(to_endpoint)
@@ -24,7 +22,7 @@ module PaperTrailDiff
24
22
  # change is `from`. A current-record endpoint is exempt: it is self-evidently
25
23
  # the live state, so putting it first is a deliberate reverse comparison.
26
24
  #: (untyped, untyped) -> void
27
- def validate_order!(from_endpoint, to_endpoint)
25
+ def self.validate_order!(from_endpoint, to_endpoint)
28
26
  return unless reversed_versions?(from_endpoint, to_endpoint)
29
27
 
30
28
  raise ReversedEndpointsError,
@@ -33,7 +31,7 @@ module PaperTrailDiff
33
31
  end
34
32
 
35
33
  #: (untyped, untyped) -> bool
36
- def reversed_versions?(from_endpoint, to_endpoint)
34
+ def self.reversed_versions?(from_endpoint, to_endpoint)
37
35
  return false unless version?(from_endpoint) && version?(to_endpoint)
38
36
 
39
37
  Support.compare_versions(from_endpoint, to_endpoint).positive?
@@ -41,7 +39,7 @@ module PaperTrailDiff
41
39
  private_class_method :reversed_versions?
42
40
 
43
41
  #: (untyped) -> void
44
- def validate!(endpoint)
42
+ def self.validate!(endpoint)
45
43
  return if version?(endpoint)
46
44
 
47
45
  validate_record!(endpoint)
@@ -50,86 +48,96 @@ module PaperTrailDiff
50
48
  # The record a method reads the history of: a record, saved or destroyed,
51
49
  # of a model PaperTrail versions.
52
50
  #: (untyped) -> void
53
- def validate_root!(record)
51
+ def self.validate_root!(record)
54
52
  unless record?(record)
55
53
  raise InvalidEndpointError, "expected a record, got #{described(record)}"
56
54
  end
57
55
  return if Support.versioned?(record.class)
58
56
 
59
57
  raise InvalidEndpointError,
60
- "#{record.class.name} is not versioned, so it has no history: add has_paper_trail to it"
58
+ "#{record.class} is not versioned, so it has no history: add has_paper_trail to it"
61
59
  end
62
60
 
63
- # A relation is named rather than inspected, which would load it.
64
- #: (untyped) -> String
65
- def described(value)
61
+ # What a message names the value as. A relation is named rather than
62
+ # inspected, which would load it, and by the name Active Record gives its
63
+ # class. A class without a name is printed, as a class given itself is.
64
+ #: (untyped) -> (String | Module)
65
+ def self.described(value)
66
66
  return 'nil' if value.nil?
67
- return "the class #{value.name}" if value.is_a?(Module)
67
+ return "the class #{value}" if value.is_a?(Module)
68
68
 
69
- value.class.name.to_s
69
+ value.class.name || value.class
70
70
  end
71
71
  private_class_method :described
72
72
 
73
73
  #: (untyped) -> bool
74
- def version?(endpoint)
75
- endpoint.respond_to?(:reify) &&
76
- endpoint.respond_to?(:item_type) &&
77
- endpoint.respond_to?(:item_id)
74
+ def self.version?(endpoint)
75
+ EndpointKind.call(endpoint) == :version
78
76
  end
79
77
 
80
78
  #: (untyped) -> bool
81
- def record?(endpoint)
82
- !version?(endpoint) &&
83
- endpoint.respond_to?(:persisted?) &&
84
- endpoint.respond_to?(:destroyed?) &&
85
- endpoint.class.respond_to?(:base_class)
79
+ def self.record?(endpoint)
80
+ EndpointKind.call(endpoint) == :record
86
81
  end
87
82
 
88
83
  #: (untyped) -> Array[String]
89
- def identity(endpoint)
84
+ def self.identity(endpoint)
90
85
  if version?(endpoint)
91
86
  [endpoint.item_type.to_s, endpoint.item_id.to_s]
92
87
  elsif record?(endpoint)
93
- [endpoint.class.base_class.name.to_s, endpoint.id.to_s]
88
+ Support.record_identity(endpoint.class, endpoint.id)
94
89
  else
95
90
  raise InvalidEndpointError, 'expected a PaperTrail version or persisted record endpoint'
96
91
  end
97
92
  end
98
93
 
99
94
  #: (untyped) -> untyped
100
- def model_class(version)
101
- subtype = version.item_subtype if version.respond_to?(:item_subtype)
102
- model_type = subtype.to_s.empty? ? version.item_type.to_s : subtype.to_s
103
- Object.const_get(model_type)
104
- rescue NameError => e
105
- raise InvalidEndpointError, "cannot resolve endpoint model: #{model_type}", cause: e
95
+ def self.model_class(version)
96
+ subtype = version.item_subtype if subtyped?(version)
97
+ model_named(subtype.to_s.empty? ? version.item_type.to_s : subtype)
98
+ end
99
+
100
+ #: (String) -> untyped
101
+ def self.model_named(type)
102
+ Support.constant(type)
103
+ rescue NameError
104
+ raise InvalidEndpointError, "cannot resolve endpoint model: #{type}"
105
+ end
106
+ private_class_method :model_named
107
+
108
+ # Whether the version has an `item_subtype` to read. An Active Record
109
+ # version is asked whether it was read with the column, which costs less
110
+ # than respond_to? (see Support.per_model) and answers for this row: a
111
+ # version a caller read without the column has none.
112
+ #: (untyped) -> bool
113
+ def self.subtyped?(version)
114
+ return version.respond_to?(:item_subtype) unless version.class.respond_to?(:column_names)
115
+
116
+ version.has_attribute?(:item_subtype)
106
117
  end
118
+ private_class_method :subtyped?
107
119
 
108
120
  # Every PaperTrail version of the record, whatever scope its versions
109
- # association has.
121
+ # association has. Active Record reads a record given as an item_id as its
122
+ # id, so mutant cannot tell `record` from `record.id` here.
123
+ # mutant:disable
110
124
  #: (untyped) -> untyped
111
- def versions(record)
125
+ def self.versions(record)
112
126
  VersionQuery.for_items(record.class, record.id)
113
- rescue NoMethodError => e
114
- message = 'record does not expose a PaperTrail version history'
115
- raise InvalidTimelineRangeError, message, cause: e
127
+ rescue NoMethodError
128
+ raise InvalidTimelineRangeError, 'record does not expose a PaperTrail version history'
116
129
  end
117
130
 
118
131
  #: (untyped) -> untyped
119
- def reload_record(record)
132
+ def self.reload_record(record)
120
133
  validate_record!(record)
121
134
  record.class.unscoped.find(record.id)
122
- rescue StandardError => e
123
- active_record = Object.const_get(:ActiveRecord) #: untyped
124
- record_not_found = active_record.const_get(:RecordNotFound) #: untyped
125
- raise unless e.is_a?(record_not_found)
126
-
127
- message = 'current record endpoint could not be reloaded from the database'
128
- raise InvalidEndpointError, message, cause: e
135
+ rescue Support.constant('ActiveRecord::RecordNotFound')
136
+ raise InvalidEndpointError, 'current record endpoint could not be reloaded from the database'
129
137
  end
130
138
 
131
139
  #: (untyped) -> void
132
- def validate_record!(record)
140
+ def self.validate_record!(record)
133
141
  unless record?(record)
134
142
  raise InvalidEndpointError, 'expected a PaperTrail version or persisted record endpoint'
135
143
  end
@@ -142,4 +150,30 @@ module PaperTrailDiff
142
150
  end
143
151
  private_class_method :validate_record!
144
152
  end
153
+
154
+ # Whether a value is a version, a record, or neither, answered once for
155
+ # each Active Record class (see Support.per_model).
156
+ module EndpointKind
157
+ @kinds = {} #: Hash[untyped, Symbol]
158
+
159
+ #: (untyped) -> Symbol
160
+ def self.call(endpoint)
161
+ kinds = @kinds #: Hash[untyped, Symbol]
162
+ Support.per_model(kinds, endpoint) { |value| classify(value) }
163
+ end
164
+
165
+ #: (untyped) -> Symbol
166
+ def self.classify(endpoint)
167
+ if endpoint.respond_to?(:reify) && endpoint.respond_to?(:item_type) &&
168
+ endpoint.respond_to?(:item_id)
169
+ :version
170
+ elsif endpoint.respond_to?(:persisted?) && endpoint.respond_to?(:destroyed?) &&
171
+ endpoint.class.respond_to?(:base_class)
172
+ :record
173
+ else
174
+ :other
175
+ end
176
+ end
177
+ private_class_method :classify
178
+ end
145
179
  end
@@ -20,13 +20,11 @@ module PaperTrailDiff
20
20
  # Raised when a live endpoint is not a clean, persisted ActiveRecord record.
21
21
  class InvalidEndpointError < Error; end
22
22
 
23
- # Raised when reload opt-out encounters an association that was not preloaded.
24
- class UnloadedAssociationError < InvalidEndpointError; end
25
-
26
23
  # Raised when a timeline boundary is absent or the requested range is reversed.
27
24
  class InvalidTimelineRangeError < Error; end
28
25
 
29
- # Raised when `within` is not a finite, chronological range of time-like values.
26
+ # Raised when `within` is not a chronological range of time-like values with
27
+ # a beginning.
30
28
  class InvalidTimeRangeError < InvalidTimelineRangeError; end
31
29
 
32
30
  # Raised when an in-range mutation has no later root boundary for reconstruction.
@@ -42,11 +40,6 @@ module PaperTrailDiff
42
40
  # Historical candidate loading exceeded its explicitly bounded work budget.
43
41
  class FilterLimitExceededError < Error; end
44
42
 
45
- # No longer raised: `allow_approximate: true` alone accepts the paths it
46
- # refused. Kept until `allow_expensive:` is removed, so code that rescues it
47
- # still loads.
48
- class UnsupportedBatchPathError < ConfigurationError; end
49
-
50
43
  # Raised when a requested ActiveRecord association does not exist.
51
44
  class UnknownAssociationError < Error; end
52
45
 
@@ -26,11 +26,8 @@ module PaperTrailDiff
26
26
 
27
27
  #: (untyped) -> bool
28
28
  def self.composite_key?(reflection)
29
- return true if reflection.foreign_key.is_a?(Array)
30
- return false unless reflection.through_reflection?
31
-
32
- [reflection.through_reflection, reflection.source_reflection].any? do |part|
33
- composite_key?(part)
29
+ [reflection, *AssociationTraversal.through_parts(reflection)].any? do |part|
30
+ part.foreign_key.is_a?(Array)
34
31
  end
35
32
  end
36
33
  private_class_method :composite_key?
@@ -16,11 +16,13 @@ module PaperTrailDiff
16
16
  end
17
17
 
18
18
  # The given transactions (one id or several) in which more than one
19
- # possible owner saved a version, as strings.
19
+ # possible owner saved a version, as strings. Each statement reads up to
20
+ # 500 of them.
20
21
  #: (untyped) -> Array[String]
21
22
  def shared(transaction_ids)
22
- items = @versions.where(transaction_id: transaction_ids).distinct
23
- .pluck(:transaction_id, :item_type, :item_id)
23
+ items = Array(transaction_ids).uniq.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
24
+ @versions.where(transaction_id: slice).distinct.pluck(:transaction_id, :item_type, :item_id)
25
+ end
24
26
  owners = items.select { |_, type, _| owner_type?(type) }
25
27
  owners.group_by { |transaction_id, _, _| transaction_id.to_s }
26
28
  .filter_map { |transaction_id, rows| transaction_id if rows.size > 1 }
@@ -95,7 +95,9 @@ module PaperTrailDiff
95
95
 
96
96
  members = through_members(record, reflection, source)
97
97
  association = record.association(reflection.name)
98
- association.target = members.uniq { |member| [member.class.base_class.name, member.id] }
98
+ association.target = members.uniq do |member|
99
+ Support.record_identity(member.class, member.id)
100
+ end
99
101
  association.loaded!
100
102
  end
101
103
 
@@ -9,17 +9,21 @@ module PaperTrailDiff
9
9
  # the window supply the state at its start and after every change but the
10
10
  # last. The state after the last change lives in the first version after
11
11
  # the window, or in the live row when nothing follows; a destroy leaves none.
12
+ #
13
+ # Each candidate is read over the window its analysis covers, which a
14
+ # transaction crossing an edge moves (see TransactionCut). `windows` gives
15
+ # the moved ones, keyed by id, for a slice of candidates and the window.
12
16
  class HistoricalFilter
13
17
  DEFAULT_VERSION_LIMIT = 10_000
14
- CANDIDATE_BATCH = 250
15
18
 
16
- #: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
17
- def initialize(model, predicate:, time_range:, limit:, max_versions:)
19
+ #: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer, windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]) -> void
20
+ def initialize(model, predicate:, time_range:, limit:, max_versions:, windows:) # rubocop:disable Metrics/ParameterLists
18
21
  @model = model
19
22
  @predicate = validate_predicate(predicate)
20
23
  @time_range = time_range
21
24
  @limit = limit
22
25
  @max_versions = validate_budget(max_versions)
26
+ @windows = windows
23
27
  @loaded = 0
24
28
  @state_loader = PreparedVersionStateLoader.new
25
29
  end
@@ -29,9 +33,9 @@ module PaperTrailDiff
29
33
  #: (Array[String], ?counted: bool) -> Array[String]
30
34
  def call(candidates, counted: true)
31
35
  matched = [] #: Array[String]
32
- candidates.each_slice(CANDIDATE_BATCH) do |slice|
33
- versions = candidate_versions(slice)
34
- closing = closing_states(slice, versions)
36
+ candidates.each_slice(Support::IDS_PER_STATEMENT) do |slice|
37
+ versions, past = own_versions(slice)
38
+ closing = closing_states(slice, versions, past)
35
39
  slice.each do |id|
36
40
  next unless held?(versions.fetch(id, []), closing[id])
37
41
 
@@ -49,6 +53,7 @@ module PaperTrailDiff
49
53
  # @rbs @time_range: TimeRange?
50
54
  # @rbs @limit: Integer
51
55
  # @rbs @max_versions: Integer
56
+ # @rbs @windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]
52
57
  # @rbs @loaded: Integer
53
58
  # @rbs @state_loader: PreparedVersionStateLoader
54
59
 
@@ -86,10 +91,26 @@ module PaperTrailDiff
86
91
  raise ConfigurationError, 'max_filter_versions: must be a positive Integer'
87
92
  end
88
93
 
89
- #: (Array[String]) -> Hash[String, Array[untyped]]
90
- def candidate_versions(ids)
91
- relation = VersionQuery.for_items(@model, ids)
94
+ # Each candidate's versions in its own window, read from the earliest
95
+ # moved start, and the first past each end that moved.
96
+ #: (Array[String]) -> [Hash[String, Array[untyped]], Hash[String, untyped]]
97
+ def own_versions(ids)
92
98
  range = @time_range
99
+ past = {} #: Hash[String, untyped]
100
+ return [candidate_versions(ids, nil), past] unless range
101
+
102
+ windows = @windows.call(ids, range)
103
+ loaded = candidate_versions(ids, OwnWindow.widest(range, windows.values))
104
+ own = loaded.to_h do |id, versions|
105
+ inside, past[id] = OwnWindow.split(windows.fetch(id, range), versions)
106
+ [id, inside]
107
+ end
108
+ [own, past]
109
+ end
110
+
111
+ #: (Array[String], TimeRange?) -> Hash[String, Array[untyped]]
112
+ def candidate_versions(ids, range)
113
+ relation = VersionQuery.for_items(@model, ids)
93
114
  relation = range.scope(relation) if range
94
115
  # One past the remaining budget is enough to know it was exceeded.
95
116
  versions = VersionQuery.chronological(relation).limit(@max_versions - @loaded + 1)
@@ -105,12 +126,16 @@ module PaperTrailDiff
105
126
  Endpoint.version?(closing) ? matches?(closing) : record_matches?(closing)
106
127
  end
107
128
 
108
- # What each candidate held after its last change in the window.
109
- #: (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
110
- def closing_states(ids, versions)
129
+ # What each candidate held after its last change in the window: the
130
+ # first version past an end that moved, read already, or past the end as
131
+ # asked, or the live row.
132
+ #: (Array[String], Hash[String, Array[untyped]], Hash[String, untyped]) -> Hash[String, untyped]
133
+ def closing_states(ids, versions, past)
111
134
  open = ids.reject { |id| versions.fetch(id, []).last&.event == 'destroy' }
112
- trailing = trailing_versions(open)
113
- trailing.merge(live_records(open - trailing.keys))
135
+ ended = past.slice(*open).compact
136
+ rest = open - ended.keys
137
+ trailing = trailing_versions(rest)
138
+ ended.merge(trailing, live_records(rest - trailing.keys))
114
139
  end
115
140
 
116
141
  #: (Array[String]) -> Hash[String, untyped]
@@ -153,7 +178,7 @@ module PaperTrailDiff
153
178
  return attributes_match?(version)
154
179
  end
155
180
 
156
- state = version.reify(dup: true)
181
+ state = Support.reify(version, dup: true)
157
182
  state && @predicate.call(state)
158
183
  end
159
184