paper_trail_diff 0.14.0 → 0.16.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 (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -0,0 +1,61 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
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:
7
+ #
8
+ # Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator
9
+ 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
+ # Required when first used, as the library loads nothing it does not need.
21
+ #: () -> untyped
22
+ def self.deprecator
23
+ @deprecator ||= begin
24
+ require 'active_support/deprecation'
25
+ active_support = Object.const_get(:ActiveSupport) #: untyped
26
+ active_support.const_get(:Deprecation).new('a future release', 'paper_trail_diff')
27
+ end
28
+ 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
+ end
61
+ end
@@ -64,65 +64,94 @@ module PaperTrailDiff
64
64
  end
65
65
 
66
66
  # Performs read-only checks for known PaperTrail/PT-AT reconstruction hazards.
67
+ #
68
+ # The endpoints are a comparison's: two versions, or a version and the
69
+ # current record, in either order. Two current records read no history, so
70
+ # nothing is checked.
67
71
  class HistoryDiagnostics
68
- #: (untyped, untyped, associations: Array[String | Symbol]) -> void
69
- def initialize(from_version, to_version, associations:)
70
- @from_version = from_version
71
- @to_version = to_version
72
+ STOPPING_CODES = %i[
73
+ unknown_association unsupported_association association_tracking_unavailable
74
+ ].freeze
75
+
76
+ #: (untyped, untyped, associations: association_option, ?allow_approximate: bool) -> void
77
+ def initialize(from, to, associations:, allow_approximate: false)
78
+ @versions = validated_versions(from, to)
72
79
  @tree = AssociationTree.build(associations)
80
+ @traversal = AssociationTraversal.new(@tree)
81
+ @preparer = TraversalPreparer.new(tree: @tree, traversal: @traversal,
82
+ allow_approximate: allow_approximate)
83
+ @allow_approximate = allow_approximate
73
84
  @issues = [] #: Array[DiagnosticIssue]
74
85
  end
75
86
 
76
87
  #: () -> DiagnosticReport
77
88
  def call
78
- model_class = validated_model_class
79
- # Runs whether or not associations are selected: unorderable versions
80
- # corrupt a scalar timeline just as surely, and a report that inspected
81
- # nothing has no business answering `ok?`.
82
- inspect_version_sequence
83
- return DiagnosticReport.new(issues: @issues) if @tree.empty?
84
-
85
- unless association_tracking_available?
86
- add_error(:association_tracking_unavailable, tracking_unavailable_message)
87
- return DiagnosticReport.new(issues: @issues)
89
+ unless @versions.empty?
90
+ model_class = Endpoint.model_class(@versions.fetch(0))
91
+ ReadSnapshot.call([model_class]) do
92
+ # Runs whether or not associations are selected: unorderable versions
93
+ # corrupt a scalar timeline just as surely, and a report that inspected
94
+ # nothing has no business answering `ok?`.
95
+ inspect_version_sequence(model_class)
96
+ inspect_associations(model_class) unless @tree.empty?
97
+ end
88
98
  end
89
-
90
- traversal = AssociationTraversal.new(@tree)
91
- selected = traversal.selected_reflections(model_class)
92
- inspect_targets(selected)
93
- inspect_checkpoint_timestamp(model_class)
94
- inspect_habtm(model_class, selected)
95
99
  DiagnosticReport.new(issues: @issues)
96
100
  end
97
101
 
98
102
  private
99
103
 
100
- # @rbs @from_version: untyped
101
- # @rbs @to_version: untyped
104
+ # Each refusal a comparison would raise is an error, so `ok?` is false
105
+ # exactly when one would. The checks after them read reflections that must
106
+ # resolve and PT-AT records that must be there.
107
+ #: (untyped) -> void
108
+ def inspect_associations(model_class)
109
+ refusals = @preparer.refusals(model_class, historical: true)
110
+ refusals.each { |refusal| add_error(refusal.code, refusal.message, refusal.path) }
111
+ return if refusals.any? { |refusal| STOPPING_CODES.include?(refusal.code) }
112
+
113
+ selected = @traversal.selected_reflections(model_class)
114
+ inspect_polymorphic_targets(selected)
115
+ inspect_approximate_paths(model_class) if @allow_approximate
116
+ inspect_checkpoint_timestamp(model_class)
117
+ inspect_habtm(model_class, selected)
118
+ end
119
+
120
+ # @rbs @versions: Array[untyped]
102
121
  # @rbs @tree: AssociationTree
122
+ # @rbs @traversal: AssociationTraversal
123
+ # @rbs @preparer: TraversalPreparer
124
+ # @rbs @allow_approximate: bool
103
125
  # @rbs @issues: Array[DiagnosticIssue]
104
126
 
105
- #: () -> untyped
106
- def validated_model_class
107
- unless version_identity(@from_version) == version_identity(@to_version)
108
- raise VersionMismatchError, 'versions must belong to the same PaperTrail item'
127
+ # The endpoints that are versions, in the order given.
128
+ #: (untyped, untyped) -> Array[untyped]
129
+ def validated_versions(from, to)
130
+ Endpoint.validate!(from)
131
+ Endpoint.validate!(to)
132
+ unless Endpoint.identity(from) == Endpoint.identity(to)
133
+ raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
109
134
  end
110
135
 
111
- Object.const_get(version_type(@from_version))
112
- rescue NoMethodError => e
113
- raise VersionMismatchError, 'expected PaperTrail version endpoints', cause: e
136
+ [from, to].select { |endpoint| Endpoint.version?(endpoint) }
114
137
  end
115
138
 
116
139
  #: (Array[Array[untyped]]) -> void
117
- def inspect_targets(selected)
140
+ def inspect_polymorphic_targets(selected)
118
141
  selected.each do |path, reflection|
119
- if reflection.polymorphic?
120
- add_warning(:polymorphic_target_unverified, 'polymorphic target cannot be verified', path)
121
- next
122
- end
142
+ next unless reflection.polymorphic?
123
143
 
124
- inspect_versioned_model(reflection.klass, path)
125
- inspect_through_model(reflection, path) if reflection.options[:through]
144
+ add_warning(:polymorphic_target_unverified, 'polymorphic target cannot be verified', path)
145
+ end
146
+ end
147
+
148
+ # Accepted, but read the way `allow_approximate:` describes.
149
+ #: (untyped) -> void
150
+ def inspect_approximate_paths(model_class)
151
+ ApproximatePaths.call(@traversal, model_class).each do |path, reason|
152
+ add_warning(:approximate_association,
153
+ "association #{path} is read approximately with PT-AT (#{reason}): a " \
154
+ 'record that entered or left it since is reported wrongly', path)
126
155
  end
127
156
  end
128
157
 
@@ -139,9 +168,7 @@ module PaperTrailDiff
139
168
  # transaction that more than one owner recorded members in cannot be read.
140
169
  #: (untyped, Array[Array[untyped]]) -> void
141
170
  def inspect_shared_transactions(model_class, habtm)
142
- versions = [@from_version, @to_version].select do |version|
143
- version.respond_to?(:transaction_id) && version.transaction_id
144
- end
171
+ versions = @versions.select { |version| VersionBoundary.transaction_id(version) }
145
172
  habtm.each do |path, reflection|
146
173
  owners = HabtmTransactionOwners.new(model_class, reflection)
147
174
  versions.each do |version|
@@ -154,15 +181,29 @@ module PaperTrailDiff
154
181
  end
155
182
  end
156
183
 
157
- #: () -> void
158
- def inspect_version_sequence
184
+ # With the current record as one endpoint there is one version, and the
185
+ # sequence runs on from it.
186
+ #: (untyped) -> void
187
+ def inspect_version_sequence(model_class)
188
+ first, last = @versions
159
189
  @issues.concat(
160
- VersionSequenceDiagnostics.new(
161
- @from_version, @to_version, associations_selected: !@tree.empty?
162
- ).call
190
+ VersionSequenceDiagnostics.new(first, last,
191
+ fallback_selected: fallback_selected?(model_class)).call
163
192
  )
164
193
  end
165
194
 
195
+ # Only a path PT-AT reads can lose a change between tied versions, and a
196
+ # traversal that does not resolve reads nothing at all.
197
+ #: (untyped) -> bool
198
+ def fallback_selected?(model_class)
199
+ return false if @tree.empty?
200
+
201
+ refusals = @preparer.refusals(model_class, historical: true)
202
+ return false if refusals.any? { |refusal| STOPPING_CODES.include?(refusal.code) }
203
+
204
+ FallbackPaths.any?(@traversal, model_class, approximate: @allow_approximate)
205
+ end
206
+
166
207
  #: (untyped) -> void
167
208
  def inspect_checkpoint_timestamp(model_class)
168
209
  return if synchronized_timestamp_disabled?(model_class)
@@ -173,7 +214,7 @@ module PaperTrailDiff
173
214
 
174
215
  #: (Array[String]) -> void
175
216
  def inspect_transaction_metadata(paths)
176
- [@from_version, @to_version].each do |version|
217
+ @versions.each do |version|
177
218
  if !version.respond_to?(:transaction_id)
178
219
  add_error(:transaction_id_column_missing, 'version has no transaction_id column')
179
220
  elsif version.transaction_id.nil?
@@ -189,36 +230,6 @@ module PaperTrailDiff
189
230
  end
190
231
  end
191
232
 
192
- #: (untyped, String) -> void
193
- def inspect_versioned_model(model_class, path)
194
- return if model_versioned?(model_class)
195
-
196
- # An error rather than a warning: `ok?` must not stay true for a
197
- # comparison that cannot work, and this one raises at runtime.
198
- add_error(
199
- :unversioned_association_target,
200
- "#{model_class.name} does not appear to have PaperTrail enabled",
201
- path
202
- )
203
- end
204
-
205
- #: (untyped, String) -> void
206
- def inspect_through_model(reflection, path)
207
- model_class = reflection.through_reflection.klass
208
- return if model_versioned?(model_class)
209
-
210
- add_warning(
211
- :unversioned_through_model,
212
- "#{model_class.name} does not appear to have PaperTrail enabled",
213
- path
214
- )
215
- end
216
-
217
- #: (untyped) -> bool
218
- def model_versioned?(model_class)
219
- Support.versioned?(model_class)
220
- end
221
-
222
233
  #: (untyped) -> bool
223
234
  def synchronized_timestamp_disabled?(model_class)
224
235
  options = model_class.paper_trail_options
@@ -227,30 +238,6 @@ module PaperTrailDiff
227
238
  false
228
239
  end
229
240
 
230
- #: () -> bool
231
- def association_tracking_available?
232
- paper_trail = Object.const_get(:PaperTrail) #: untyped
233
- config = paper_trail.config #: untyped
234
- !!(defined?(::PaperTrailAssociationTracking) &&
235
- config.respond_to?(:track_associations?) && config.track_associations?)
236
- end
237
-
238
- #: (untyped) -> Array[String]
239
- def version_identity(version)
240
- [version.item_type.to_s, version.item_id.to_s]
241
- end
242
-
243
- #: (untyped) -> String
244
- def version_type(version)
245
- subtype = version.item_subtype if version.respond_to?(:item_subtype)
246
- subtype.to_s.empty? ? version.item_type.to_s : subtype.to_s
247
- end
248
-
249
- #: () -> String
250
- def tracking_unavailable_message
251
- 'association tracking must be loaded and enabled to diagnose associations'
252
- end
253
-
254
241
  #: (Symbol, String, ?String?, ?untyped) -> void
255
242
  def add_error(code, message, path = nil, version_id = nil)
256
243
  add_issue(:error, code, message, path, version_id)
@@ -47,6 +47,29 @@ module PaperTrailDiff
47
47
  validate_record!(endpoint)
48
48
  end
49
49
 
50
+ # The record a method reads the history of: a record, saved or destroyed,
51
+ # of a model PaperTrail versions.
52
+ #: (untyped) -> void
53
+ def validate_root!(record)
54
+ unless record?(record)
55
+ raise InvalidEndpointError, "expected a record, got #{described(record)}"
56
+ end
57
+ return if Support.versioned?(record.class)
58
+
59
+ raise InvalidEndpointError,
60
+ "#{record.class.name} is not versioned, so it has no history: add has_paper_trail to it"
61
+ end
62
+
63
+ # A relation is named rather than inspected, which would load it.
64
+ #: (untyped) -> String
65
+ def described(value)
66
+ return 'nil' if value.nil?
67
+ return "the class #{value.name}" if value.is_a?(Module)
68
+
69
+ value.class.name.to_s
70
+ end
71
+ private_class_method :described
72
+
50
73
  #: (untyped) -> bool
51
74
  def version?(endpoint)
52
75
  endpoint.respond_to?(:reify) &&
@@ -82,11 +105,11 @@ module PaperTrailDiff
82
105
  raise InvalidEndpointError, "cannot resolve endpoint model: #{model_type}", cause: e
83
106
  end
84
107
 
85
- # The record's own PaperTrail versions, under whatever name the model gave
86
- # the association.
108
+ # Every PaperTrail version of the record, whatever scope its versions
109
+ # association has.
87
110
  #: (untyped) -> untyped
88
111
  def versions(record)
89
- record.public_send(record.class.versions_association_name)
112
+ VersionQuery.for_items(record.class, record.id)
90
113
  rescue NoMethodError => e
91
114
  message = 'record does not expose a PaperTrail version history'
92
115
  raise InvalidTimelineRangeError, message, cause: e
@@ -42,7 +42,9 @@ module PaperTrailDiff
42
42
  # Historical candidate loading exceeded its explicitly bounded work budget.
43
43
  class FilterLimitExceededError < Error; end
44
44
 
45
- # A batch selected a known expensive association without explicitly opting in.
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.
46
48
  class UnsupportedBatchPathError < ConfigurationError; end
47
49
 
48
50
  # Raised when a requested ActiveRecord association does not exist.
@@ -0,0 +1,38 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Whether a request may read a path with PT-AT's reifier rather than from
6
+ # loaded history. PT-AT places association changes by timestamp alone, so
7
+ # only such a path can miss a change between two versions that share one;
8
+ # loaded history orders those versions by id.
9
+ module FallbackPaths
10
+ # A path history reads only approximately counts when it is allowed: a
11
+ # request that does not allow it is refused before anything is read.
12
+ #: (AssociationTraversal, untyped, approximate: bool) -> bool
13
+ def self.any?(traversal, model, approximate:)
14
+ return true if approximate && !ApproximatePaths.call(traversal, model).empty?
15
+
16
+ traversal.selected_reflections(model).any? { |_path, reflection| per_record?(reflection) }
17
+ end
18
+
19
+ # Loaded history cannot index a composite foreign key, and a polymorphic
20
+ # belongs_to's target, with its default scope, is known only per record.
21
+ #: (untyped) -> bool
22
+ def self.per_record?(reflection)
23
+ composite_key?(reflection) || (reflection.belongs_to? && reflection.polymorphic?)
24
+ end
25
+ private_class_method :per_record?
26
+
27
+ #: (untyped) -> bool
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)
34
+ end
35
+ end
36
+ private_class_method :composite_key?
37
+ end
38
+ end
@@ -6,10 +6,8 @@ module PaperTrailDiff
6
6
  class HistoricalAssociationReifier
7
7
  #: (untyped, ?habtm_version: untyped) -> void
8
8
  def initialize(version, habtm_version: version)
9
- @transaction_id = version.transaction_id if version.respond_to?(:transaction_id)
10
- if habtm_version.respond_to?(:transaction_id)
11
- @habtm_transaction_id = habtm_version.transaction_id
12
- end
9
+ @transaction_id = VersionBoundary.transaction_id(version)
10
+ @habtm_transaction_id = VersionBoundary.transaction_id(habtm_version)
13
11
  @version_at = version.created_at
14
12
  # Keyed on record identity rather than `object_id`, which Ruby may reuse
15
13
  # once an earlier record in the same pass has been collected.
@@ -24,8 +24,10 @@ module PaperTrailDiff
24
24
  @state_loader = PreparedVersionStateLoader.new
25
25
  end
26
26
 
27
- #: (Array[String]) -> Array[String]
28
- def call(candidates)
27
+ # More matches than the limit raise, unless the caller does not count
28
+ # them: candidates it only lists, such as deleted roots.
29
+ #: (Array[String], ?counted: bool) -> Array[String]
30
+ def call(candidates, counted: true)
29
31
  matched = [] #: Array[String]
30
32
  candidates.each_slice(CANDIDATE_BATCH) do |slice|
31
33
  versions = candidate_versions(slice)
@@ -34,7 +36,7 @@ module PaperTrailDiff
34
36
  next unless held?(versions.fetch(id, []), closing[id])
35
37
 
36
38
  matched << id
37
- reject_root_limit! if matched.length > @limit
39
+ reject_root_limit! if counted && matched.length > @limit
38
40
  end
39
41
  end
40
42
  matched
@@ -64,7 +66,17 @@ module PaperTrailDiff
64
66
  "unknown historical attributes: #{unknown.join(', ')}"
65
67
  end
66
68
 
67
- Support.immutable_copy(attributes)
69
+ attributes.to_h { |name, value| [name, cast(name, value)] }
70
+ end
71
+
72
+ # Expected and recorded values compare as the attribute casts them, as
73
+ # `where` reads its values: an enum's symbol names its stored value, and a
74
+ # `json` or `jsonb` version column, which PaperTrail does not cast, holds
75
+ # dates and times as strings. Casting also copies a mutable value, so the
76
+ # filter keeps its own.
77
+ #: (String, untyped) -> untyped
78
+ def cast(name, value)
79
+ @model.type_for_attribute(name).cast(value)
68
80
  end
69
81
 
70
82
  #: (untyped) -> Integer
@@ -76,8 +88,7 @@ module PaperTrailDiff
76
88
 
77
89
  #: (Array[String]) -> Hash[String, Array[untyped]]
78
90
  def candidate_versions(ids)
79
- relation = @model.paper_trail.version_class.where(item_type: @model.base_class.name,
80
- item_id: ids)
91
+ relation = VersionQuery.for_items(@model, ids)
81
92
  range = @time_range
82
93
  relation = range.scope(relation) if range
83
94
  # One past the remaining budget is enough to know it was exceeded.
@@ -107,9 +118,7 @@ module PaperTrailDiff
107
118
  range = @time_range
108
119
  return {} unless range
109
120
 
110
- relation = @model.paper_trail.version_class.where(item_type: @model.base_class.name,
111
- item_id: ids)
112
- trailing = range.first_trailing_versions(relation)
121
+ trailing = range.first_trailing_versions(VersionQuery.for_items(@model, ids))
113
122
  account_versions!(trailing.length)
114
123
  trailing
115
124
  end
@@ -162,7 +171,7 @@ module PaperTrailDiff
162
171
  "historical_filter: #{name} was not recorded in version #{version.id}"
163
172
  end
164
173
 
165
- state.attributes.fetch(name) == expected
174
+ cast(name, state.attributes.fetch(name)) == expected
166
175
  end
167
176
  end
168
177