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
@@ -86,7 +86,7 @@ module PaperTrailDiff
86
86
  #: (?prefix: String) -> Array[String]
87
87
  def paths(prefix: '')
88
88
  children.flat_map do |name, subtree|
89
- path = prefix.empty? ? name : "#{prefix}.#{name}"
89
+ path = Support.association_path(prefix, name)
90
90
  [path, *subtree.paths(prefix: path)]
91
91
  end.freeze
92
92
  end
@@ -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,15 +27,11 @@ 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
- plan = selected.fetch(key)
33
- window = windows.fetch(key, @time_range)
34
- [key, plan.empty? ? Analysis.empty : @analyzer.call(record, plan, window)]
35
- 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))
36
35
  with_unavailable(analyses)
37
36
  end
38
37
 
@@ -44,6 +43,7 @@ module PaperTrailDiff
44
43
  end
45
44
 
46
45
  # @rbs @model: untyped
46
+ # @rbs @traversal: AssociationTraversal?
47
47
  # @rbs @context_required: bool
48
48
  # @rbs @identities: Array[Array[String]]
49
49
  # @rbs @time_range: TimeRange?
@@ -52,7 +52,10 @@ module PaperTrailDiff
52
52
  # @rbs @version_scope: untyped
53
53
 
54
54
  # A root destroyed before the window had no state inside it to read, so
55
- # 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.
56
59
  #: (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
57
60
  def plans(records, destroys, windows)
58
61
  start = @time_range&.begin_time
@@ -66,7 +69,8 @@ module PaperTrailDiff
66
69
  def plans_for(records, context_required, windows)
67
70
  BatchedRootVersions.new(
68
71
  records, time_range: @time_range, version_scope: @version_scope,
69
- live_endpoints: nil, context_required: context_required, windows: windows
72
+ live_endpoints: nil, context_required: context_required,
73
+ whole: @context_required, windows: windows
70
74
  ).call
71
75
  end
72
76
 
@@ -84,28 +88,13 @@ module PaperTrailDiff
84
88
  end
85
89
  end
86
90
 
91
+ # Each statement reads the destroys of 500 records.
87
92
  #: () -> Array[untyped]
88
93
  def destroy_versions
89
- destroys = VersionQuery.for_items(@model, @identities.map(&:last)).where(event: 'destroy')
90
- # Oldest first, so each item keeps its latest destroy.
91
- VersionQuery.chronological(destroys).index_by(&:item_id).values
92
- end
93
-
94
- #: (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
95
- def preparation_range(versions, windows)
96
- { start_at: TransactionCut.earliest_start(@time_range, windows),
97
- end_at: [@time_range&.end_time, versions.map(&:created_at).max].compact.max }
98
- end
99
-
100
- #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
101
- def prepare(records, selected, windows)
102
- records.group_by(&:class).each_value do |group|
103
- versions = group.flat_map do |record|
104
- selected.fetch(Endpoint.identity(record)).reconstruction_versions
105
- end
106
- next if versions.empty?
107
-
108
- @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
109
98
  end
110
99
  end
111
100
  end
@@ -14,19 +14,31 @@ module PaperTrailDiff
14
14
  unless condition
15
15
  raise ConfigurationError,
16
16
  'include_deleted: cannot test deleted records against this relation: its ' \
17
- "conditions must be plain conditions on #{model.name}'s own columns, as an " \
18
- "association scope's must; select deleted records some other way"
17
+ "conditions must be equality, IN, NULL, or range tests on #{model.name}'s " \
18
+ 'own columns, and a range or a text comparison must be on a column whose ' \
19
+ 'values compare in Ruby as the database compares them, as for an ' \
20
+ 'association scope; select deleted records some other way'
19
21
  end
20
22
 
21
23
  @condition = condition
22
24
  @loader = DirectRecordStateLoader.new
23
25
  end
24
26
 
27
+ # nil when the relation's conditions cannot be read.
28
+ #: (untyped) -> DeletedRootFilter?
29
+ def self.readable(relation)
30
+ new(relation)
31
+ rescue ConfigurationError
32
+ nil
33
+ end
34
+
25
35
  # A root whose destroy PaperTrail did not record has no state to test
26
- # and stays, as it has no state to report either. One whose destroy
27
- # recorded no state is left out.
36
+ # and stays, as it has no state to report either, unless the relation
37
+ # selects nothing. One whose destroy recorded no state is left out.
28
38
  #: (Array[Array[String]]) -> Array[Array[String]]
29
39
  def call(identities)
40
+ return [] if @condition.none?
41
+
30
42
  states = destroyed_states(identities.map(&:last))
31
43
  identities.select do |identity|
32
44
  id = identity.last
@@ -55,13 +67,20 @@ module PaperTrailDiff
55
67
  AssociationTraversal.sti_member?(model, attributes) && @condition.matches?(attributes)
56
68
  end
57
69
 
58
- # The state each root held before its latest destroy.
70
+ # The state each root held before its latest destroy, read in slices: a
71
+ # report lists every deleted root it reached, and SQL Server cannot plan an
72
+ # IN list of thousands.
59
73
  #: (Array[String]) -> Hash[String, Hash[String, untyped]?]
60
74
  def destroyed_states(ids)
61
- destroys = VersionQuery.for_items(model, ids).where(event: 'destroy')
62
- VersionQuery.chronological(destroys).to_h do |version|
63
- [version.item_id.to_s, @loader.call(version)&.attributes || reified_attributes(version)]
75
+ states = {} #: Hash[String, Hash[String, untyped]?]
76
+ ids.each_slice(Support::IDS_PER_STATEMENT) do |slice|
77
+ destroys = VersionQuery.for_items(model, slice).where(event: 'destroy')
78
+ VersionQuery.chronological(destroys).each do |version|
79
+ states[version.item_id.to_s] =
80
+ @loader.call(version)&.attributes || reified_attributes(version)
81
+ end
64
82
  end
83
+ states
65
84
  end
66
85
 
67
86
  # Read directly, with a column `skip:` left out of history as its default,
@@ -72,8 +91,8 @@ module PaperTrailDiff
72
91
  # mutant:disable
73
92
  #: (untyped) -> Hash[String, untyped]?
74
93
  def reified_attributes(version)
75
- version.reify(dup: true, has_many: false, has_one: false, belongs_to: false,
76
- 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
77
96
  end
78
97
  end
79
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
@@ -88,11 +87,13 @@ module PaperTrailDiff
88
87
  def call
89
88
  unless @versions.empty?
90
89
  model_class = Endpoint.model_class(@versions.fetch(0))
91
- # Runs whether or not associations are selected: unorderable versions
92
- # corrupt a scalar timeline just as surely, and a report that inspected
93
- # nothing has no business answering `ok?`.
94
- inspect_version_sequence(model_class)
95
- inspect_associations(model_class) unless @tree.empty?
90
+ ReadSnapshot.call([model_class]) do
91
+ # Runs whether or not associations are selected: unorderable versions
92
+ # corrupt a scalar timeline just as surely, and a report that inspected
93
+ # nothing has no business answering `ok?`.
94
+ inspect_version_sequence(model_class)
95
+ inspect_associations(model_class) unless @tree.empty?
96
+ end
96
97
  end
97
98
  DiagnosticReport.new(issues: @issues)
98
99
  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