paper_trail_diff 0.13.0 → 0.14.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 (121) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +318 -0
  3. data/QUICKSTART.md +9 -6
  4. data/README.md +84 -9
  5. data/docs/architecture.md +32 -9
  6. data/docs/performance.md +106 -13
  7. data/docs/reference.md +242 -29
  8. data/docs/testing.md +55 -9
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  11. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  12. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  15. data/lib/paper_trail_diff/activity_range.rb +14 -2
  16. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  18. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  19. data/lib/paper_trail_diff/activity_timeline_builder.rb +30 -24
  20. data/lib/paper_trail_diff/activity_version_collector.rb +31 -20
  21. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  22. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  23. data/lib/paper_trail_diff/association_discovery.rb +8 -13
  24. data/lib/paper_trail_diff/association_traversal.rb +169 -45
  25. data/lib/paper_trail_diff/batch_safety.rb +23 -15
  26. data/lib/paper_trail_diff/batched_root_versions.rb +21 -39
  27. data/lib/paper_trail_diff/collection_comparator.rb +18 -20
  28. data/lib/paper_trail_diff/collection_identity_index.rb +8 -12
  29. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  30. data/lib/paper_trail_diff/deleted_analysis_batch.rb +36 -17
  31. data/lib/paper_trail_diff/diagnostics.rb +26 -8
  32. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  33. data/lib/paper_trail_diff/errors.rb +2 -1
  34. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  35. data/lib/paper_trail_diff/historical_association_reifier.rb +32 -2
  36. data/lib/paper_trail_diff/historical_filter.rb +12 -17
  37. data/lib/paper_trail_diff/historical_snapshot_store.rb +6 -9
  38. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +35 -2
  39. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  40. data/lib/paper_trail_diff/paper_trail_adapter.rb +22 -6
  41. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +1 -1
  42. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  43. data/lib/paper_trail_diff/prepared_edge_loader.rb +29 -45
  44. data/lib/paper_trail_diff/prepared_history.rb +63 -54
  45. data/lib/paper_trail_diff/prepared_history_loader.rb +33 -43
  46. data/lib/paper_trail_diff/prepared_record_index.rb +26 -0
  47. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  48. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  49. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  50. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  51. data/lib/paper_trail_diff/root_version_plan.rb +10 -1
  52. data/lib/paper_trail_diff/scope_condition.rb +331 -0
  53. data/lib/paper_trail_diff/scope_ranking.rb +196 -0
  54. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  55. data/lib/paper_trail_diff/scoped_root_selection.rb +93 -43
  56. data/lib/paper_trail_diff/snapshot.rb +5 -1
  57. data/lib/paper_trail_diff/snapshot_normalizer.rb +50 -47
  58. data/lib/paper_trail_diff/support.rb +9 -4
  59. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -1
  60. data/lib/paper_trail_diff/time_range.rb +9 -13
  61. data/lib/paper_trail_diff/time_version_range.rb +6 -6
  62. data/lib/paper_trail_diff/timeline_range.rb +5 -4
  63. data/lib/paper_trail_diff/version.rb +1 -1
  64. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  65. data/lib/paper_trail_diff/version_query.rb +9 -1
  66. data/lib/paper_trail_diff/version_range.rb +8 -15
  67. data/lib/paper_trail_diff/version_scope_filter.rb +11 -3
  68. data/lib/paper_trail_diff.rb +31 -2
  69. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  70. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  71. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  72. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  73. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -2
  74. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  75. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  76. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  77. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +11 -5
  78. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +10 -4
  79. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  80. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  81. data/sig/generated/paper_trail_diff/association_discovery.rbs +3 -5
  82. data/sig/generated/paper_trail_diff/association_traversal.rbs +84 -9
  83. data/sig/generated/paper_trail_diff/batch_safety.rbs +10 -4
  84. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -8
  85. data/sig/generated/paper_trail_diff/collection_comparator.rbs +6 -3
  86. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +3 -3
  87. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  88. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +16 -4
  89. data/sig/generated/paper_trail_diff/diagnostics.rbs +7 -2
  90. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  91. data/sig/generated/paper_trail_diff/errors.rbs +2 -1
  92. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  93. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  94. data/sig/generated/paper_trail_diff/historical_filter.rbs +6 -6
  95. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +3 -2
  96. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +17 -0
  97. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  99. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  100. data/sig/generated/paper_trail_diff/prepared_history.rbs +33 -22
  101. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  102. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +15 -0
  103. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  104. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  105. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  106. data/sig/generated/paper_trail_diff/root_version_plan.rbs +7 -0
  107. data/sig/generated/paper_trail_diff/scope_condition.rbs +185 -0
  108. data/sig/generated/paper_trail_diff/scope_ranking.rbs +117 -0
  109. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  110. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +41 -7
  111. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +25 -9
  112. data/sig/generated/paper_trail_diff/support.rbs +5 -2
  113. data/sig/generated/paper_trail_diff/time_range.rbs +4 -0
  114. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  115. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -1
  116. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  117. data/sig/generated/paper_trail_diff/version_query.rbs +7 -1
  118. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  119. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -0
  120. data/sig/generated/paper_trail_diff.rbs +21 -2
  121. metadata +20 -4
@@ -0,0 +1,331 @@
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
+ # Types whose stored values compare in Ruby as the database compares them,
18
+ # named rather than referenced so that loading needs no Active Model.
19
+ VALUE_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
20
+ ActiveModel::Type::ImmutableString].freeze
21
+ TEXT_TYPE = 'ActiveModel::Type::ImmutableString'
22
+ ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
23
+ BIND_PARAM = 'Arel::Nodes::BindParam'
24
+ ATTRIBUTE = 'Arel::Attributes::Attribute'
25
+ # Adapters that compare strings exactly by default. MySQL and SQL Server
26
+ # ignore case and trailing spaces by default, which Ruby cannot follow.
27
+ EXACT_TEXT_ADAPTERS = %w[sqlite3 postgresql].freeze
28
+
29
+ # Raised while reading a node that has no exact plain-Ruby reading.
30
+ class Unreadable < StandardError; end
31
+ private_constant :Unreadable
32
+
33
+ # Whether the reflection filters its target beyond its keys at all.
34
+ #: (untyped) -> bool
35
+ def self.scoped?(reflection)
36
+ !reflection.scope.nil? || reflection.klass.default_scopes?
37
+ end
38
+
39
+ # A through also filters by the scopes of each reflection it passes.
40
+ #: (untyped) -> bool
41
+ def self.scoped_path?(reflection)
42
+ return !reflection.scope.nil? if reflection.polymorphic?
43
+ return true if scoped?(reflection)
44
+ return false unless reflection.through_reflection?
45
+
46
+ scoped_path?(reflection.through_reflection) || scoped_path?(reflection.source_reflection)
47
+ end
48
+
49
+ # Returns nil when the scope cannot be read as plain conditions and an
50
+ # exact ranking. A part of a has_many through is read unranked: the
51
+ # through's query keeps only its conditions.
52
+ #: (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
53
+ def self.build(reflection, model_class = reflection.klass, ranked: true)
54
+ return if ranked && ranked_through?(reflection)
55
+
56
+ relation = scoped_relation(reflection, model_class)
57
+ return unless relation && plain_relation?(relation)
58
+
59
+ clause = relation.where_clause - model_class.unscoped.where_clause
60
+ predicate = Reader.new(model_class).call(clause.ast)
61
+ new(model_class, predicate, (ranking(relation, reflection, model_class) if ranked))
62
+ rescue Unreadable
63
+ nil
64
+ end
65
+
66
+ # nil when the relation picks its members by conditions alone.
67
+ #: (untyped, untyped, untyped) -> ScopeRanking?
68
+ def self.ranking(relation, reflection, model_class)
69
+ return unless ScopeRanking.ranks?(relation, reflection)
70
+
71
+ ScopeRanking.build(relation, reflection, model_class) || raise(Unreadable)
72
+ end
73
+ private_class_method :ranking
74
+
75
+ # A has_one through orders its rows by its own order and then its parts',
76
+ # and takes the first, so one that passes a ranked part is not read. A
77
+ # has_many through keeps only its parts' conditions.
78
+ #: (untyped) -> bool
79
+ def self.ranked_through?(reflection)
80
+ return false if reflection.collection?
81
+
82
+ ranked_parts?(reflection)
83
+ end
84
+
85
+ # Whether any part of a through, at any depth, has a limit, an offset or
86
+ # a has_one order.
87
+ #: (untyped) -> bool
88
+ def self.ranked_parts?(reflection)
89
+ return false unless reflection.through_reflection?
90
+
91
+ [reflection.through_reflection, reflection.source_reflection].any? do |part|
92
+ ranked_part?(part) || ranked_parts?(part)
93
+ end
94
+ end
95
+
96
+ # A polymorphic part's class, and so its scope, is known only per record.
97
+ #: (untyped) -> bool
98
+ def self.ranked_part?(part)
99
+ return false if part.polymorphic?
100
+
101
+ relation = scoped_relation(part, part.klass)
102
+ !relation.nil? && ScopeRanking.ranks?(relation, part)
103
+ end
104
+ private_class_method :ranked_part?
105
+
106
+ # A scope that takes the owner differs per record, so it is never read.
107
+ #: (untyped, untyped) -> untyped
108
+ def self.scoped_relation(reflection, model_class)
109
+ scope = reflection.scope
110
+ relation = model_class.default_scoped
111
+ return relation unless scope
112
+ return unless scope.arity.zero?
113
+
114
+ reflection.scope_for(relation)
115
+ end
116
+ private_class_method :scoped_relation
117
+
118
+ # Some parts, such as the having clause `or` sets, may be present but
119
+ # empty.
120
+ #: (untyped) -> bool
121
+ def self.plain_relation?(relation)
122
+ extra = relation.values.except(*RELATION_VALUES).values
123
+ extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
124
+ end
125
+ private_class_method :plain_relation?
126
+
127
+ #: (untyped, Array[untyped], ?ScopeRanking?) -> void
128
+ def initialize(model_class, predicate, ranking = nil)
129
+ @model_class = model_class
130
+ @predicate = predicate
131
+ @ranking = ranking
132
+ freeze
133
+ end
134
+
135
+ #: (Hash[String, untyped]) -> bool
136
+ def matches?(attributes)
137
+ evaluate(@predicate, attributes)
138
+ end
139
+
140
+ # The members among records that are each the owner's by key: those that
141
+ # meet the conditions, then ranked.
142
+ #: (Array[untyped]) -> Array[untyped]
143
+ def members(records)
144
+ rank(records.select { |record| matches?(record.attributes) })
145
+ end
146
+
147
+ # Records that meet the conditions, as ranked; unchanged without a
148
+ # ranking.
149
+ #: (Array[untyped]) -> Array[untyped]
150
+ def rank(records)
151
+ ranking = @ranking
152
+ ranking ? ranking.call(records) : records
153
+ end
154
+
155
+ # SQL compares NULL with nothing, so only an IS NULL test, an equality
156
+ # with nil, matches it.
157
+ COMPARISONS = {
158
+ eq: ->(value, expected) { value == expected },
159
+ not_eq: ->(value, expected) { !value.nil? && value != expected },
160
+ in: ->(value, expected) { !value.nil? && expected.include?(value) },
161
+ not_in: ->(value, expected) { !value.nil? && !expected.include?(value) }
162
+ }.freeze
163
+ private_constant :COMPARISONS
164
+
165
+ private
166
+
167
+ # @rbs @model_class: untyped
168
+ # @rbs @predicate: Array[untyped]
169
+ # @rbs @ranking: ScopeRanking?
170
+
171
+ #: (Array[untyped], Hash[String, untyped]) -> bool
172
+ def evaluate(predicate, attributes)
173
+ operator, first, second = predicate
174
+ case operator
175
+ when :and then first.all? { |part| evaluate(part, attributes) }
176
+ when :or then first.any? { |part| evaluate(part, attributes) }
177
+ else COMPARISONS.fetch(operator).call(stored(first, attributes), second)
178
+ end
179
+ end
180
+
181
+ # The form the database holds, as the scope's own values were cast.
182
+ #: (String, Hash[String, untyped]) -> untyped
183
+ def stored(name, attributes)
184
+ @model_class.type_for_attribute(name).serialize(attributes[name])
185
+ end
186
+
187
+ # Builds each reflection's condition once per target class.
188
+ class Cache
189
+ #: () -> void
190
+ def initialize
191
+ @conditions = {} #: Hash[Array[untyped], ScopeCondition?]
192
+ end
193
+
194
+ # nil when the scope cannot be read from stored attributes.
195
+ #: (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
196
+ def call(reflection, model_class = reflection.klass, ranked: true)
197
+ key = [reflection, model_class, ranked]
198
+ return @conditions.fetch(key) if @conditions.key?(key)
199
+
200
+ @conditions[key] = ScopeCondition.build(reflection, model_class, ranked: ranked)
201
+ end
202
+
203
+ # The records the reflection's scope admits, as it ranks them. Its
204
+ # condition must exist.
205
+ #: (untyped, Array[untyped], ?untyped, ranked: bool) -> Array[untyped]
206
+ def select(reflection, records, model_class = reflection.klass, ranked:)
207
+ condition = call(reflection, model_class, ranked: ranked) #: ScopeCondition
208
+ condition.members(records)
209
+ end
210
+
211
+ # @rbs @conditions: Hash[Array[untyped], ScopeCondition?]
212
+ end
213
+
214
+ # Compiles a where clause into nested arrays of plain comparisons.
215
+ class Reader
216
+ #: (untyped) -> void
217
+ def initialize(model_class)
218
+ @model_class = model_class
219
+ end
220
+
221
+ #: (untyped) -> Array[untyped]
222
+ def call(node)
223
+ case node.class.name
224
+ when 'Arel::Nodes::And' then [:and, node.children.map { |child| call(child) }]
225
+ when 'Arel::Nodes::Or' then [:or, either(node).map { |child| call(child) }]
226
+ when 'Arel::Nodes::Grouping' then call(node.expr)
227
+ else comparison(node)
228
+ end
229
+ end
230
+
231
+ private
232
+
233
+ # @rbs @model_class: untyped
234
+
235
+ # An Or is binary before Rails 7.2 and n-ary from it.
236
+ #: (untyped) -> Array[untyped]
237
+ def either(node)
238
+ node.respond_to?(:children) ? node.children : [node.left, node.right]
239
+ end
240
+
241
+ #: (untyped) -> Array[untyped]
242
+ def comparison(node)
243
+ case node.class.name
244
+ when 'Arel::Nodes::Equality' then binary(:eq, node)
245
+ when 'Arel::Nodes::NotEqual' then binary(:not_eq, node)
246
+ when 'Arel::Nodes::HomogeneousIn' then homogeneous_in(node)
247
+ when 'Arel::Nodes::In' then list(:in, node.left, values(node.right))
248
+ when 'Arel::Nodes::NotIn' then list(:not_in, node.left, values(node.right))
249
+ else raise Unreadable
250
+ end
251
+ end
252
+
253
+ #: (Symbol, untyped) -> Array[untyped]
254
+ def binary(operator, node)
255
+ [operator, column(node.left), value(node.right)]
256
+ end
257
+
258
+ #: (untyped) -> Array[untyped]
259
+ def homogeneous_in(node)
260
+ list(node.type == :in ? :in : :not_in, node.attribute, node.casted_values)
261
+ end
262
+
263
+ # Active Record writes an empty NOT IN as a condition that is always
264
+ # true, and a NOT IN list holding NULL matches no row.
265
+ #: (Symbol, untyped, Array[untyped]) -> Array[untyped]
266
+ def list(operator, attribute, expected)
267
+ name = column(attribute)
268
+ return [operator, name, expected] if operator == :in
269
+ return [:and, []] if expected.empty?
270
+
271
+ expected.include?(nil) ? [:or, []] : [operator, name, expected]
272
+ end
273
+
274
+ # Ruby comparison stands in for SQL only on the record's own column of
275
+ # a type both compare alike.
276
+ #: (untyped) -> String
277
+ def column(attribute)
278
+ raise Unreadable unless ATTRIBUTE.eql?(attribute.class.name)
279
+
280
+ table = attribute.relation
281
+ raise Unreadable unless table.name == @model_class.table_name && table.table_alias.nil?
282
+
283
+ name = attribute.name
284
+ raise Unreadable unless comparable?(name)
285
+
286
+ name
287
+ end
288
+
289
+ #: (String) -> bool
290
+ def comparable?(name)
291
+ column = @model_class.columns_hash[name]
292
+ kinds = value_type(@model_class.type_for_attribute(name)).class.ancestors.map(&:name)
293
+ return false unless column && VALUE_TYPES.intersect?(kinds)
294
+ return true unless kinds.include?(TEXT_TYPE)
295
+
296
+ EXACT_TEXT_ADAPTERS.include?(@model_class.connection_db_config.adapter) &&
297
+ column.collation.nil?
298
+ end
299
+
300
+ # An enum compares the values it stores, which its subtype describes. A
301
+ # wrapper such as a serialized or encrypted type is none of these.
302
+ #: (untyped) -> untyped
303
+ def value_type(type)
304
+ ENUM_TYPE.eql?(type.class.name) ? type.subtype : type
305
+ end
306
+
307
+ # A list that is not plain values, such as a subquery, is unreadable.
308
+ #: (untyped) -> Array[untyped]
309
+ def values(nodes)
310
+ raise Unreadable unless nodes.instance_of?(Array)
311
+
312
+ nodes.map { |node| value(node) }
313
+ end
314
+
315
+ # A value out of the column's range makes Active Record write a
316
+ # constant condition instead, so it is left unread. Active Record
317
+ # writes IS NULL for a value that is nil before casting, but `= NULL`,
318
+ # which matches nothing, for one that only casts to nil.
319
+ #: (untyped) -> untyped
320
+ def value(node)
321
+ node = node.value if BIND_PARAM.eql?(node.class.name)
322
+ raise Unreadable unless node.respond_to?(:value_for_database)
323
+ raise Unreadable if node.respond_to?(:unboundable?) && node.unboundable?
324
+ return if node.nil?
325
+
326
+ node.value_for_database.tap { |value| raise Unreadable if value.nil? }
327
+ end
328
+ end
329
+ private_constant :Reader
330
+ end
331
+ end
@@ -0,0 +1,196 @@
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
+ # Integers, booleans and dates sort alike everywhere. Strings follow a
15
+ # collation, so they are not read.
16
+ ORDER_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
17
+ ActiveModel::Type::Date].freeze
18
+ # Times sort alike only at the precision both the column and history
19
+ # keep. A time of day is not read: in memory it keeps the date it was
20
+ # given, which the database drops.
21
+ DATETIME_TYPE = 'ActiveModel::Type::DateTime'
22
+ # Where each adapter sorts NULL in an ascending order by default; a
23
+ # descending order reverses it. Another adapter's ranking is not read.
24
+ NULLS_LAST = { 'postgresql' => true, 'sqlite3' => false, 'mysql2' => false,
25
+ 'trilogy' => false, 'sqlserver' => false }.freeze
26
+ # Places in a sort key, of which only the order counts: a value between a
27
+ # NULL sorted first and one sorted last, and false before true. Every
28
+ # value is a number, so that a descending key can negate it.
29
+ NULL_PLACE = { false => -1, true => 1 }.freeze
30
+ VALUE_PLACE = 0
31
+ BOOLEAN_VALUE = { false => 0, true => 1 }.freeze
32
+
33
+ # Whether the relation picks members by rank rather than by condition
34
+ # alone. A has_one takes the first record its order names.
35
+ #: (untyped, untyped) -> bool
36
+ def self.ranks?(relation, reflection)
37
+ !relation.limit_value.nil? || !relation.offset_value.nil? ||
38
+ (reflection.has_one? && !relation.order_values.empty?)
39
+ end
40
+
41
+ # A has_many, through or not, or a direct has_one is ranked per owner as
42
+ # its own query ranks it. A has_many through ranks the rows its join
43
+ # yields, a record reached twice counting twice, by its own order first.
44
+ # Returns nil when the ranking cannot be read exactly.
45
+ #: (untyped, untyped, untyped) -> ScopeRanking?
46
+ def self.build(relation, reflection, model_class)
47
+ return unless own?(reflection) && plain_offset?(relation)
48
+
49
+ keys = keys(relation.order_values, model_class)
50
+ return unless keys
51
+
52
+ nulls_last = NULLS_LAST[model_class.connection_db_config.adapter]
53
+ return if nulls_last.nil?
54
+
55
+ new(model_class, keys, nulls_last, relation.limit_value, relation.offset_value)
56
+ end
57
+
58
+ #: (untyped) -> bool
59
+ def self.own?(reflection)
60
+ reflection.macro == :has_many || (reflection.has_one? && !reflection.through_reflection?)
61
+ end
62
+ private_class_method :own?
63
+
64
+ # Active Record casts a limit to an integer but keeps an offset as given,
65
+ # which may be a String or SQL.
66
+ #: (untyped) -> bool
67
+ def self.plain_offset?(relation)
68
+ !relation.offset_value.is_a?(String)
69
+ end
70
+ private_class_method :plain_offset?
71
+
72
+ # The order's keys up to the primary key, which makes it total. Keys
73
+ # after it never decide anything.
74
+ #: (Array[untyped], untyped) -> Array[[String, bool]]?
75
+ def self.keys(nodes, model_class)
76
+ names = nodes.map { |node| column(node, model_class) }
77
+ total = names.index(model_class.primary_key)
78
+ return unless total
79
+
80
+ deciding = nodes.first(total + 1).zip(names)
81
+ return unless deciding.all? { |_node, name| name }
82
+
83
+ deciding.map do |node, name|
84
+ column = name #: String
85
+ [column, DIRECTIONS.fetch(node.class.name)]
86
+ end
87
+ end
88
+ private_class_method :keys
89
+
90
+ # The record's own column, sorted plainly in one direction.
91
+ #: (untyped, untyped) -> String?
92
+ def self.column(node, model_class)
93
+ return unless DIRECTIONS.key?(node.class.name)
94
+
95
+ attribute = node.expr
96
+ return unless ATTRIBUTE.eql?(attribute.class.name)
97
+
98
+ table = attribute.relation
99
+ return unless table.name == model_class.table_name && table.table_alias.nil?
100
+
101
+ name = attribute.name
102
+ name if orderable?(model_class, name)
103
+ end
104
+ private_class_method :column
105
+
106
+ #: (untyped, String) -> bool
107
+ def self.orderable?(model_class, name)
108
+ return false unless model_class.columns_hash.key?(name)
109
+
110
+ type = model_class.type_for_attribute(name)
111
+ type = type.subtype if ENUM_TYPE.eql?(type.class.name)
112
+ kinds = type.class.ancestors.map(&:name)
113
+ ORDER_TYPES.intersect?(kinds) ||
114
+ (kinds.include?(DATETIME_TYPE) && exact_time?(model_class, type))
115
+ end
116
+ private_class_method :orderable?
117
+
118
+ # Active Record truncates a time to its column's precision before writing
119
+ # it, so history holds the stored value when it keeps that many digits.
120
+ # Times the type stores in UTC sort as the instants they name; local
121
+ # times repeat an hour when clocks go back.
122
+ #: (untyped, untyped) -> bool
123
+ def self.exact_time?(model_class, type)
124
+ precision = type.precision
125
+ digits = StoredTimePrecision.digits(model_class)
126
+ !precision.nil? && (digits.nil? || digits >= precision) && type.default_timezone == :utc
127
+ end
128
+ private_class_method :exact_time?
129
+
130
+ #: (untyped, Array[[String, bool]], bool, Integer?, Integer?) -> void
131
+ def initialize(model_class, keys, nulls_last, limit, offset)
132
+ @model_class = model_class
133
+ @keys = keys
134
+ @nulls_last = nulls_last
135
+ @limit = limit
136
+ @offset = offset
137
+ freeze
138
+ end
139
+
140
+ # The members among records that met the scope's conditions, in order.
141
+ #: (Array[untyped]) -> Array[untyped]
142
+ def call(records)
143
+ offset = @offset
144
+ limit = @limit
145
+ ranked = records.sort_by { |record| sort_key(record.attributes) }
146
+ ranked = ranked.drop(offset) if offset
147
+ limit ? ranked.first(limit) : ranked
148
+ end
149
+
150
+ private
151
+
152
+ # @rbs @model_class: untyped
153
+ # @rbs @keys: Array[[String, bool]]
154
+ # @rbs @nulls_last: bool
155
+ # @rbs @limit: Integer?
156
+ # @rbs @offset: Integer?
157
+
158
+ # Keys compare in turn, and the primary key always decides. A descending
159
+ # key negates its places, which also moves NULL to the other end, as each
160
+ # adapter does by default.
161
+ #: (Hash[String, untyped]) -> Array[Array[Numeric]]
162
+ def sort_key(attributes)
163
+ @keys.map do |name, descending|
164
+ place = place(stored(name, attributes))
165
+ descending ? place.map(&:-@) : place
166
+ end
167
+ end
168
+
169
+ # NULL holds the adapter's place alone, so it never compares as a value.
170
+ # A version saved before its column existed holds NULL there too.
171
+ #: (untyped) -> Array[Numeric]
172
+ def place(value)
173
+ return [NULL_PLACE.fetch(@nulls_last)] if value.nil?
174
+
175
+ [VALUE_PLACE, number(value)]
176
+ end
177
+
178
+ # A time as its seconds, exactly, and a date as its day number.
179
+ #: (untyped) -> Numeric
180
+ def number(value)
181
+ value = BOOLEAN_VALUE.fetch(value, value)
182
+ value = value.jd if value.respond_to?(:jd)
183
+ value.to_r
184
+ end
185
+
186
+ # The value the database sorts by, as the key's type casts it. An enum
187
+ # sorts by the integer it stores; other types are compared cast, since an
188
+ # adapter may serialize a time or date as a wrapper, as SQL Server does.
189
+ #: (String, Hash[String, untyped]) -> untyped
190
+ def stored(name, attributes)
191
+ type = @model_class.type_for_attribute(name)
192
+ value = type.cast(attributes[name])
193
+ ENUM_TYPE.eql?(type.class.name) ? type.serialize(value) : value
194
+ end
195
+ end
196
+ end
@@ -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,7 +16,8 @@ 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
  )
21
22
  @limit = limit
22
23
  @include_deleted = include_deleted