paper_trail_diff 0.13.1 → 0.15.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 (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -0,0 +1,386 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # An association scope, or its target's default scope, read as conditions
6
+ # on stored attributes, so membership at a boundary can be decided from each
7
+ # record's state there rather than by a query. A limit, offset or has_one
8
+ # order then ranks the records that meet the conditions (ScopeRanking). It
9
+ # reads the relation the scope builds once and never runs application code
10
+ # per record. A scope it cannot read exactly builds no condition, and the
11
+ # caller keeps its slower path.
12
+ class ScopeCondition
13
+ # Relation parts that leave membership to the where clause and the
14
+ # ranking alone.
15
+ RELATION_VALUES = %i[where order reordering limit offset readonly strict_loading
16
+ extending].freeze
17
+ # Relation parts that load or shape rows without choosing them.
18
+ LOADING_VALUES = %i[includes preload select distinct].freeze
19
+ # Types whose stored values compare in Ruby as the database compares them,
20
+ # named rather than referenced so that loading needs no Active Model.
21
+ VALUE_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
22
+ ActiveModel::Type::ImmutableString].freeze
23
+ TEXT_TYPE = 'ActiveModel::Type::ImmutableString'
24
+ ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
25
+ BIND_PARAM = 'Arel::Nodes::BindParam'
26
+ ATTRIBUTE = 'Arel::Attributes::Attribute'
27
+ # Adapters that compare strings exactly by default. MySQL and SQL Server
28
+ # ignore case and trailing spaces by default, which Ruby cannot follow.
29
+ EXACT_TEXT_ADAPTERS = %w[sqlite3 postgresql].freeze
30
+
31
+ # Raised while reading a node that has no exact plain-Ruby reading.
32
+ class Unreadable < StandardError; end
33
+ private_constant :Unreadable
34
+
35
+ # Whether the reflection filters its target beyond its keys at all.
36
+ #: (untyped) -> bool
37
+ def self.scoped?(reflection)
38
+ !reflection.scope.nil? || reflection.klass.default_scopes?
39
+ end
40
+
41
+ # A through also filters by the scopes of each reflection it passes.
42
+ #: (untyped) -> bool
43
+ def self.scoped_path?(reflection)
44
+ return !reflection.scope.nil? if reflection.polymorphic?
45
+ return true if scoped?(reflection)
46
+ return false unless reflection.through_reflection?
47
+
48
+ scoped_path?(reflection.through_reflection) || scoped_path?(reflection.source_reflection)
49
+ end
50
+
51
+ # Returns nil when the scope cannot be read as plain conditions and an
52
+ # exact ranking. A part of a has_many through is read unranked: the
53
+ # through's query keeps only its conditions.
54
+ #: (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
55
+ def self.build(reflection, model_class = reflection.klass, ranked: true)
56
+ return if ranked && ranked_through?(reflection)
57
+
58
+ relation = scoped_relation(reflection, model_class)
59
+ return unless relation && plain_relation?(relation)
60
+
61
+ clause = relation.where_clause - model_class.unscoped.where_clause
62
+ predicate = Reader.new(model_class).call(clause.ast)
63
+ new(model_class, predicate, (ranking(relation, reflection, model_class) if ranked))
64
+ rescue Unreadable
65
+ nil
66
+ end
67
+
68
+ # A relation's own where clause, default scope included, read as
69
+ # conditions on stored attributes; nil when it cannot be. Its order,
70
+ # limit, and offset choose a page of current rows rather than membership,
71
+ # and loading or selecting columns changes neither, so they are left out.
72
+ # A single-table subclass's type condition is left to the caller, as for
73
+ # an association.
74
+ #: (untyped, untyped) -> ScopeCondition?
75
+ def self.for_relation(relation, model_class)
76
+ extra = relation.values.except(*RELATION_VALUES, *LOADING_VALUES).values
77
+ return unless extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
78
+
79
+ clause = relation.where_clause - model_class.unscoped.where_clause
80
+ new(model_class, Reader.new(model_class).call(clause.ast))
81
+ rescue Unreadable
82
+ nil
83
+ end
84
+
85
+ # nil when the relation picks its members by conditions alone.
86
+ #: (untyped, untyped, untyped) -> ScopeRanking?
87
+ def self.ranking(relation, reflection, model_class)
88
+ return unless ScopeRanking.ranks?(relation, reflection)
89
+
90
+ ScopeRanking.build(relation, reflection, model_class) || raise(Unreadable)
91
+ end
92
+ private_class_method :ranking
93
+
94
+ # A has_one through orders its rows by its own order and then its parts',
95
+ # and takes the first, so one that passes a ranked part is not read. A
96
+ # has_many through keeps only its parts' conditions.
97
+ #: (untyped) -> bool
98
+ def self.ranked_through?(reflection)
99
+ return false if reflection.collection?
100
+
101
+ ranked_parts?(reflection)
102
+ end
103
+
104
+ # Whether any part of a through, at any depth, has a limit, an offset or
105
+ # a has_one order.
106
+ #: (untyped) -> bool
107
+ def self.ranked_parts?(reflection)
108
+ return false unless reflection.through_reflection?
109
+
110
+ [reflection.through_reflection, reflection.source_reflection].any? do |part|
111
+ ranked_part?(part) || ranked_parts?(part)
112
+ end
113
+ end
114
+
115
+ # A polymorphic part's class, and so its scope, is known only per record.
116
+ #: (untyped) -> bool
117
+ def self.ranked_part?(part)
118
+ return false if part.polymorphic?
119
+
120
+ relation = scoped_relation(part, part.klass)
121
+ !relation.nil? && ScopeRanking.ranks?(relation, part)
122
+ end
123
+ private_class_method :ranked_part?
124
+
125
+ # A scope that takes the owner differs per record, so it is never read.
126
+ #: (untyped, untyped) -> untyped
127
+ def self.scoped_relation(reflection, model_class)
128
+ scope = reflection.scope
129
+ relation = model_class.default_scoped
130
+ return relation unless scope
131
+ return unless scope.arity.zero?
132
+
133
+ reflection.scope_for(relation)
134
+ end
135
+ private_class_method :scoped_relation
136
+
137
+ # Some parts, such as the having clause `or` sets, may be present but
138
+ # empty.
139
+ #: (untyped) -> bool
140
+ def self.plain_relation?(relation)
141
+ extra = relation.values.except(*RELATION_VALUES).values
142
+ extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
143
+ end
144
+ private_class_method :plain_relation?
145
+
146
+ #: (untyped, Array[untyped], ?ScopeRanking?) -> void
147
+ def initialize(model_class, predicate, ranking = nil)
148
+ @model_class = model_class
149
+ @predicate = predicate
150
+ @ranking = ranking
151
+ freeze
152
+ end
153
+
154
+ # SQL admits a row only when its condition is true, not when it is
155
+ # unknown.
156
+ #: (Hash[String, untyped]) -> bool
157
+ def matches?(attributes)
158
+ evaluate(@predicate, attributes) == true
159
+ end
160
+
161
+ # The members among records that are each the owner's by key: those that
162
+ # meet the conditions, then ranked.
163
+ #: (Array[untyped]) -> Array[untyped]
164
+ def members(records)
165
+ rank(records.select { |record| matches?(record.attributes) })
166
+ end
167
+
168
+ # Records that meet the conditions, as ranked; unchanged without a
169
+ # ranking.
170
+ #: (Array[untyped]) -> Array[untyped]
171
+ def rank(records)
172
+ ranking = @ranking
173
+ ranking ? ranking.call(records) : records
174
+ end
175
+
176
+ # SQL's three values: a comparison with NULL is unknown (nil) rather than
177
+ # false, except an IS NULL or IS NOT NULL test, an equality with nil, which
178
+ # is always known. Unknown matters only under NOT, which leaves it
179
+ # unknown where false would become true.
180
+ COMPARISONS = {
181
+ eq: ->(value, expected) { expected.nil? || !value.nil? ? value == expected : nil },
182
+ not_eq: ->(value, expected) { expected.nil? || !value.nil? ? value != expected : nil },
183
+ in: ->(value, expected) { expected.include?(value) unless value.nil? },
184
+ not_in: ->(value, expected) { !expected.include?(value) unless value.nil? }
185
+ }.freeze
186
+ private_constant :COMPARISONS
187
+
188
+ private
189
+
190
+ # @rbs @model_class: untyped
191
+ # @rbs @predicate: Array[untyped]
192
+ # @rbs @ranking: ScopeRanking?
193
+
194
+ # true, false, or nil for unknown.
195
+ #: (Array[untyped], Hash[String, untyped]) -> bool?
196
+ def evaluate(predicate, attributes)
197
+ operator, first, second = predicate
198
+ case operator
199
+ when :and then all(first.map { |part| evaluate(part, attributes) })
200
+ when :or then any(first.map { |part| evaluate(part, attributes) })
201
+ when :not then negate(evaluate(first, attributes))
202
+ else COMPARISONS.fetch(operator).call(stored(first, attributes), second)
203
+ end
204
+ end
205
+
206
+ # False if any part is, otherwise unknown if any part is.
207
+ #: (Array[bool?]) -> bool?
208
+ def all(values)
209
+ return false if values.include?(false)
210
+
211
+ true unless values.include?(nil)
212
+ end
213
+
214
+ # True if any part is, otherwise unknown if any part is.
215
+ #: (Array[bool?]) -> bool?
216
+ def any(values)
217
+ return true if values.include?(true)
218
+
219
+ false unless values.include?(nil)
220
+ end
221
+
222
+ #: (bool?) -> bool?
223
+ def negate(value)
224
+ !value unless value.nil?
225
+ end
226
+
227
+ # The form the database holds, as the scope's own values were cast.
228
+ #: (String, Hash[String, untyped]) -> untyped
229
+ def stored(name, attributes)
230
+ @model_class.type_for_attribute(name).serialize(attributes[name])
231
+ end
232
+
233
+ # Builds each reflection's condition once per target class.
234
+ class Cache
235
+ #: () -> void
236
+ def initialize
237
+ @conditions = {} #: Hash[Array[untyped], ScopeCondition?]
238
+ end
239
+
240
+ # nil when the scope cannot be read from stored attributes.
241
+ #: (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
242
+ def call(reflection, model_class = reflection.klass, ranked: true)
243
+ key = [reflection, model_class, ranked]
244
+ return @conditions.fetch(key) if @conditions.key?(key)
245
+
246
+ @conditions[key] = ScopeCondition.build(reflection, model_class, ranked: ranked)
247
+ end
248
+
249
+ # The records the reflection's scope admits, as it ranks them. Its
250
+ # condition must exist.
251
+ #: (untyped, Array[untyped], ?untyped, ranked: bool) -> Array[untyped]
252
+ def select(reflection, records, model_class = reflection.klass, ranked:)
253
+ condition = call(reflection, model_class, ranked: ranked) #: ScopeCondition
254
+ condition.members(records)
255
+ end
256
+
257
+ # @rbs @conditions: Hash[Array[untyped], ScopeCondition?]
258
+ end
259
+
260
+ # Compiles a where clause into nested arrays of plain comparisons.
261
+ class Reader
262
+ #: (untyped) -> void
263
+ def initialize(model_class)
264
+ @model_class = model_class
265
+ end
266
+
267
+ #: (untyped) -> Array[untyped]
268
+ def call(node)
269
+ case node.class.name
270
+ when 'Arel::Nodes::And' then [:and, node.children.map { |child| call(child) }]
271
+ when 'Arel::Nodes::Or' then [:or, either(node).map { |child| call(child) }]
272
+ when 'Arel::Nodes::Grouping' then call(node.expr)
273
+ when 'Arel::Nodes::Not' then [:not, call(node.expr)]
274
+ else comparison(node)
275
+ end
276
+ end
277
+
278
+ private
279
+
280
+ # @rbs @model_class: untyped
281
+
282
+ # An Or is binary before Rails 7.2 and n-ary from it.
283
+ #: (untyped) -> Array[untyped]
284
+ def either(node)
285
+ node.respond_to?(:children) ? node.children : [node.left, node.right]
286
+ end
287
+
288
+ #: (untyped) -> Array[untyped]
289
+ def comparison(node)
290
+ case node.class.name
291
+ when 'Arel::Nodes::Equality' then binary(:eq, node)
292
+ when 'Arel::Nodes::NotEqual' then binary(:not_eq, node)
293
+ when 'Arel::Nodes::HomogeneousIn' then homogeneous_in(node)
294
+ when 'Arel::Nodes::In' then list(:in, node.left, values(node.right))
295
+ when 'Arel::Nodes::NotIn' then list(:not_in, node.left, values(node.right))
296
+ else raise Unreadable
297
+ end
298
+ end
299
+
300
+ # Whether a value is NULL compares alike on every type.
301
+ #: (Symbol, untyped) -> Array[untyped]
302
+ def binary(operator, node)
303
+ expected = value(node.right)
304
+ [operator, column(node.left, null_test: expected.nil?), expected]
305
+ end
306
+
307
+ #: (untyped) -> Array[untyped]
308
+ def homogeneous_in(node)
309
+ list(node.type == :in ? :in : :not_in, node.attribute, node.casted_values)
310
+ end
311
+
312
+ # Active Record writes an empty NOT IN as a condition that is always
313
+ # true, and a NOT IN list holding NULL matches no row.
314
+ #: (Symbol, untyped, Array[untyped]) -> Array[untyped]
315
+ def list(operator, attribute, expected)
316
+ name = column(attribute)
317
+ return [operator, name, expected] if operator == :in
318
+ return [:and, []] if expected.empty?
319
+
320
+ expected.include?(nil) ? [:or, []] : [operator, name, expected]
321
+ end
322
+
323
+ # Ruby comparison stands in for SQL only on the record's own column of
324
+ # a type both compare alike. Whether a value is NULL, any column's
325
+ # type compares alike.
326
+ #: (untyped, ?null_test: bool) -> String
327
+ def column(attribute, null_test: false)
328
+ raise Unreadable unless ATTRIBUTE.eql?(attribute.class.name)
329
+
330
+ table = attribute.relation
331
+ raise Unreadable unless table.name == @model_class.table_name && table.table_alias.nil?
332
+
333
+ name = attribute.name
334
+ column = @model_class.columns_hash[name]
335
+ raise Unreadable unless column && (null_test || comparable?(name, column))
336
+
337
+ name
338
+ end
339
+
340
+ #: (String, untyped) -> bool
341
+ def comparable?(name, column)
342
+ kinds = value_type(@model_class.type_for_attribute(name)).class.ancestors.map(&:name)
343
+ return false unless VALUE_TYPES.intersect?(kinds)
344
+
345
+ !kinds.include?(TEXT_TYPE) || exact_text?(column)
346
+ end
347
+
348
+ # PostgreSQL's citext is text that compares without regard to case.
349
+ #: (untyped) -> bool
350
+ def exact_text?(column)
351
+ EXACT_TEXT_ADAPTERS.include?(@model_class.connection_db_config.adapter) &&
352
+ column.collation.nil? && !column.sql_type.casecmp?('citext')
353
+ end
354
+
355
+ # An enum compares the values it stores, which its subtype describes. A
356
+ # wrapper such as a serialized or encrypted type is none of these.
357
+ #: (untyped) -> untyped
358
+ def value_type(type)
359
+ ENUM_TYPE.eql?(type.class.name) ? type.subtype : type
360
+ end
361
+
362
+ # A list that is not plain values, such as a subquery, is unreadable.
363
+ #: (untyped) -> Array[untyped]
364
+ def values(nodes)
365
+ raise Unreadable unless nodes.instance_of?(Array)
366
+
367
+ nodes.map { |node| value(node) }
368
+ end
369
+
370
+ # A value out of the column's range makes Active Record write a
371
+ # constant condition instead, so it is left unread. Active Record
372
+ # writes IS NULL for a value that is nil before casting, but `= NULL`,
373
+ # which matches nothing, for one that only casts to nil.
374
+ #: (untyped) -> untyped
375
+ def value(node)
376
+ node = node.value if BIND_PARAM.eql?(node.class.name)
377
+ raise Unreadable unless node.respond_to?(:value_for_database)
378
+ raise Unreadable if node.respond_to?(:unboundable?) && node.unboundable?
379
+ return if node.nil?
380
+
381
+ node.value_for_database.tap { |value| raise Unreadable if value.nil? }
382
+ end
383
+ end
384
+ private_constant :Reader
385
+ end
386
+ end
@@ -0,0 +1,206 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # The order, offset and limit by which a scope picks its members from the
6
+ # records that meet its conditions, as the database would rank them. It is
7
+ # read only when the order is total and every key compares in Ruby as SQL
8
+ # compares it; otherwise build returns nil and the caller keeps its slower
9
+ # path.
10
+ class ScopeRanking
11
+ DIRECTIONS = { 'Arel::Nodes::Ascending' => false, 'Arel::Nodes::Descending' => true }.freeze
12
+ ATTRIBUTE = 'Arel::Attributes::Attribute'
13
+ ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
14
+ # Rails wraps a time-zone-aware attribute's type, by default every
15
+ # datetime's, in this delegator; the time it stores is the wrapped type's.
16
+ TIME_ZONE_TYPE = 'ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter'
17
+ # Integers, booleans and dates sort alike everywhere. Strings follow a
18
+ # collation, so they are not read.
19
+ ORDER_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
20
+ ActiveModel::Type::Date].freeze
21
+ # Times sort alike only at the precision both the column and history
22
+ # keep. A time of day is not read: in memory it keeps the date it was
23
+ # given, which the database drops.
24
+ DATETIME_TYPE = 'ActiveModel::Type::DateTime'
25
+ # Where each adapter sorts NULL in an ascending order by default; a
26
+ # descending order reverses it. Another adapter's ranking is not read.
27
+ NULLS_LAST = { 'postgresql' => true, 'sqlite3' => false, 'mysql2' => false,
28
+ 'trilogy' => false, 'sqlserver' => false }.freeze
29
+ # Places in a sort key, of which only the order counts: a value between a
30
+ # NULL sorted first and one sorted last, and false before true. Every
31
+ # value is a number, so that a descending key can negate it.
32
+ NULL_PLACE = { false => -1, true => 1 }.freeze
33
+ VALUE_PLACE = 0
34
+ BOOLEAN_VALUE = { false => 0, true => 1 }.freeze
35
+
36
+ # Whether the relation picks members by rank rather than by condition
37
+ # alone. A has_one takes the first record its order names.
38
+ #: (untyped, untyped) -> bool
39
+ def self.ranks?(relation, reflection)
40
+ !relation.limit_value.nil? || !relation.offset_value.nil? ||
41
+ (reflection.has_one? && !relation.order_values.empty?)
42
+ end
43
+
44
+ # A has_many, through or not, or a direct has_one is ranked per owner as
45
+ # its own query ranks it. A has_many through ranks the rows its join
46
+ # yields, a record reached twice counting twice, by its own order first.
47
+ # Returns nil when the ranking cannot be read exactly.
48
+ #: (untyped, untyped, untyped) -> ScopeRanking?
49
+ def self.build(relation, reflection, model_class)
50
+ return unless own?(reflection) && plain_offset?(relation)
51
+
52
+ keys = keys(relation.order_values, model_class)
53
+ return unless keys
54
+
55
+ nulls_last = NULLS_LAST[model_class.connection_db_config.adapter]
56
+ return if nulls_last.nil?
57
+
58
+ new(model_class, keys, nulls_last, relation.limit_value, relation.offset_value)
59
+ end
60
+
61
+ #: (untyped) -> bool
62
+ def self.own?(reflection)
63
+ reflection.macro == :has_many || (reflection.has_one? && !reflection.through_reflection?)
64
+ end
65
+ private_class_method :own?
66
+
67
+ # Active Record casts a limit to an integer but keeps an offset as given,
68
+ # which may be a String or SQL.
69
+ #: (untyped) -> bool
70
+ def self.plain_offset?(relation)
71
+ !relation.offset_value.is_a?(String)
72
+ end
73
+ private_class_method :plain_offset?
74
+
75
+ # The order's keys up to the primary key, which makes it total. Keys
76
+ # after it never decide anything.
77
+ #: (Array[untyped], untyped) -> Array[[String, bool]]?
78
+ def self.keys(nodes, model_class)
79
+ names = nodes.map { |node| column(node, model_class) }
80
+ total = names.index(model_class.primary_key)
81
+ return unless total
82
+
83
+ deciding = nodes.first(total + 1).zip(names)
84
+ return unless deciding.all? { |_node, name| name }
85
+
86
+ deciding.map do |node, name|
87
+ column = name #: String
88
+ [column, DIRECTIONS.fetch(node.class.name)]
89
+ end
90
+ end
91
+ private_class_method :keys
92
+
93
+ # The record's own column, sorted plainly in one direction.
94
+ #: (untyped, untyped) -> String?
95
+ def self.column(node, model_class)
96
+ return unless DIRECTIONS.key?(node.class.name)
97
+
98
+ attribute = node.expr
99
+ return unless ATTRIBUTE.eql?(attribute.class.name)
100
+
101
+ table = attribute.relation
102
+ return unless table.name == model_class.table_name && table.table_alias.nil?
103
+
104
+ name = attribute.name
105
+ name if orderable?(model_class, name)
106
+ end
107
+ private_class_method :column
108
+
109
+ #: (untyped, String) -> bool
110
+ def self.orderable?(model_class, name)
111
+ return false unless model_class.columns_hash.key?(name)
112
+
113
+ type = stored_type(model_class.type_for_attribute(name))
114
+ kinds = type.class.ancestors.map(&:name)
115
+ ORDER_TYPES.intersect?(kinds) ||
116
+ (kinds.include?(DATETIME_TYPE) && exact_time?(model_class, type))
117
+ end
118
+ private_class_method :orderable?
119
+
120
+ # The type of the value a column stores, under an enum or time zone wrapper.
121
+ #: (untyped) -> untyped
122
+ def self.stored_type(type)
123
+ type = type.subtype if ENUM_TYPE.eql?(type.class.name)
124
+ TIME_ZONE_TYPE.eql?(type.class.name) ? type.__getobj__ : type
125
+ end
126
+ private_class_method :stored_type
127
+
128
+ # Active Record truncates a time to its column's precision before writing
129
+ # it, so history holds the stored value when it keeps that many digits.
130
+ # Times the type stores in UTC sort as the instants they name; local
131
+ # times repeat an hour when clocks go back.
132
+ #: (untyped, untyped) -> bool
133
+ def self.exact_time?(model_class, type)
134
+ precision = type.precision
135
+ digits = StoredTimePrecision.digits(model_class)
136
+ !precision.nil? && (digits.nil? || digits >= precision) && type.default_timezone == :utc
137
+ end
138
+ private_class_method :exact_time?
139
+
140
+ #: (untyped, Array[[String, bool]], bool, Integer?, Integer?) -> void
141
+ def initialize(model_class, keys, nulls_last, limit, offset)
142
+ @model_class = model_class
143
+ @keys = keys
144
+ @nulls_last = nulls_last
145
+ @limit = limit
146
+ @offset = offset
147
+ freeze
148
+ end
149
+
150
+ # The members among records that met the scope's conditions, in order.
151
+ #: (Array[untyped]) -> Array[untyped]
152
+ def call(records)
153
+ offset = @offset
154
+ limit = @limit
155
+ ranked = records.sort_by { |record| sort_key(record.attributes) }
156
+ ranked = ranked.drop(offset) if offset
157
+ limit ? ranked.first(limit) : ranked
158
+ end
159
+
160
+ private
161
+
162
+ # @rbs @model_class: untyped
163
+ # @rbs @keys: Array[[String, bool]]
164
+ # @rbs @nulls_last: bool
165
+ # @rbs @limit: Integer?
166
+ # @rbs @offset: Integer?
167
+
168
+ # Keys compare in turn, and the primary key always decides. A descending
169
+ # key negates its places, which also moves NULL to the other end, as each
170
+ # adapter does by default.
171
+ #: (Hash[String, untyped]) -> Array[Array[Numeric]]
172
+ def sort_key(attributes)
173
+ @keys.map do |name, descending|
174
+ place = place(stored(name, attributes))
175
+ descending ? place.map(&:-@) : place
176
+ end
177
+ end
178
+
179
+ # NULL holds the adapter's place alone, so it never compares as a value.
180
+ # A version saved before its column existed holds NULL there too.
181
+ #: (untyped) -> Array[Numeric]
182
+ def place(value)
183
+ return [NULL_PLACE.fetch(@nulls_last)] if value.nil?
184
+
185
+ [VALUE_PLACE, number(value)]
186
+ end
187
+
188
+ # A time as its seconds, exactly, and a date as its day number.
189
+ #: (untyped) -> Numeric
190
+ def number(value)
191
+ value = BOOLEAN_VALUE.fetch(value, value)
192
+ value = value.jd if value.respond_to?(:jd)
193
+ value.to_r
194
+ end
195
+
196
+ # The value the database sorts by, as the key's type casts it. An enum
197
+ # sorts by the integer it stores; other types are compared cast, since an
198
+ # adapter may serialize a time or date as a wrapper, as SQL Server does.
199
+ #: (String, Hash[String, untyped]) -> untyped
200
+ def stored(name, attributes)
201
+ type = @model_class.type_for_attribute(name)
202
+ value = type.cast(attributes[name])
203
+ ENUM_TYPE.eql?(type.class.name) ? type.serialize(value) : value
204
+ end
205
+ end
206
+ end
@@ -36,6 +36,17 @@ module PaperTrailDiff
36
36
  freeze
37
37
  end
38
38
 
39
+ # Each root's change rows, keyed as `analyses` is: the roots that still
40
+ # exist, then the deleted ones that have history to report. A deleted root
41
+ # without destroy history has no rows and is left out.
42
+ #: () -> Hash[Array[String], Array[ChangeRow]]
43
+ def change_rows
44
+ rows = {} #: Hash[Array[String], Array[ChangeRow]]
45
+ analyses.each { |identity, analysis| rows[identity] = analysis.change_rows }
46
+ deleted.each { |identity, analysis| rows[identity] = analysis.change_rows if analysis }
47
+ rows.freeze
48
+ end
49
+
39
50
  # Two elements, not three: `roots` is reached by name so that existing
40
51
  # destructuring keeps working.
41
52
  #: () -> [Hash[Array[String], Analysis], Array[Array[String]]]
@@ -4,10 +4,10 @@
4
4
  module PaperTrailDiff
5
5
  # Selects both populations and checks their shared ceiling before analysis.
6
6
  class ScopedAnalysisBuilder
7
- #: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped) -> void
7
+ #: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?) -> void
8
8
  def initialize( # rubocop:disable Metrics/ParameterLists
9
9
  scope, limit:, within:, historical_filter:, max_filter_versions:, include_deleted:,
10
- analyzer:, deleted_analyzer:
10
+ analyzer:, deleted_analyzer:, activity_tree: nil
11
11
  )
12
12
  raise ConfigurationError, 'limit: is required when selecting roots by scope' if limit.nil?
13
13
  unless [true, false].include?(include_deleted)
@@ -16,10 +16,11 @@ module PaperTrailDiff
16
16
 
17
17
  @selection = ScopedRootSelection.new(
18
18
  scope, limit: limit, time_range: within.nil? ? nil : TimeRange.new(within),
19
- historical_filter: historical_filter, max_filter_versions: max_filter_versions
19
+ historical_filter: historical_filter, max_filter_versions: max_filter_versions,
20
+ activity_tree: activity_tree
20
21
  )
22
+ @deleted_filter = DeletedRootFilter.new(scope.all) if include_deleted
21
23
  @limit = limit
22
- @include_deleted = include_deleted
23
24
  @analyzer = analyzer
24
25
  @deleted_analyzer = deleted_analyzer
25
26
  end
@@ -27,20 +28,28 @@ module PaperTrailDiff
27
28
  #: () -> ScopedAnalysis
28
29
  def call
29
30
  selection = @selection.call
30
- if @include_deleted && selection.records.length + selection.unreachable.length > @limit
31
+ deleted_filter = @deleted_filter
32
+ return analysis(selection, selection.unreachable, {}) unless deleted_filter
33
+
34
+ unreachable = deleted_filter.call(selection.unreachable)
35
+ if selection.records.length + unreachable.length > @limit
31
36
  raise BatchLimitExceededError, 'include_deleted: live and missing roots exceed limit:'
32
37
  end
33
38
 
34
- ScopedAnalysis.new(
35
- analyses: @analyzer.call(selection.records), roots: selection.records,
36
- unreachable: selection.unreachable,
37
- deleted: @include_deleted ? @deleted_analyzer.call(selection.unreachable) : {}
38
- )
39
+ analysis(selection, unreachable, @deleted_analyzer.call(unreachable))
40
+ end
41
+
42
+ private
43
+
44
+ #: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
45
+ def analysis(selection, unreachable, deleted)
46
+ ScopedAnalysis.new(analyses: @analyzer.call(selection.records), roots: selection.records,
47
+ unreachable: unreachable, deleted: deleted)
39
48
  end
40
49
 
41
50
  # @rbs @selection: ScopedRootSelection
51
+ # @rbs @deleted_filter: DeletedRootFilter?
42
52
  # @rbs @limit: Integer
43
- # @rbs @include_deleted: bool
44
53
  # @rbs @analyzer: untyped
45
54
  # @rbs @deleted_analyzer: untyped
46
55
  end