paper_trail_diff 0.15.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 (61) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +159 -1
  3. data/README.md +1 -1
  4. data/docs/performance.md +9 -0
  5. data/docs/reference.md +142 -28
  6. data/docs/testing.md +23 -3
  7. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  8. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  9. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  10. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  11. data/lib/paper_trail_diff/activity_timeline_builder.rb +6 -0
  12. data/lib/paper_trail_diff/analysis.rb +25 -6
  13. data/lib/paper_trail_diff/analysis_batch.rb +2 -2
  14. data/lib/paper_trail_diff/batched_root_analyzer.rb +6 -0
  15. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  16. data/lib/paper_trail_diff/deleted_analysis_batch.rb +7 -3
  17. data/lib/paper_trail_diff/deleted_root_filter.rb +30 -8
  18. data/lib/paper_trail_diff/diagnostics.rb +7 -5
  19. data/lib/paper_trail_diff/paper_trail_adapter.rb +96 -59
  20. data/lib/paper_trail_diff/prepared_activity_index.rb +16 -12
  21. data/lib/paper_trail_diff/prepared_history.rb +11 -5
  22. data/lib/paper_trail_diff/prepared_history_loader.rb +1 -3
  23. data/lib/paper_trail_diff/prepared_record_index.rb +6 -2
  24. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  25. data/lib/paper_trail_diff/scope_condition.rb +85 -15
  26. data/lib/paper_trail_diff/scope_ranking.rb +11 -12
  27. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -7
  28. data/lib/paper_trail_diff/scoped_root_selection.rb +11 -4
  29. data/lib/paper_trail_diff/time_range.rb +7 -6
  30. data/lib/paper_trail_diff/timeline_builder.rb +6 -0
  31. data/lib/paper_trail_diff/transaction_cut.rb +100 -41
  32. data/lib/paper_trail_diff/version.rb +1 -1
  33. data/lib/paper_trail_diff/version_boundary.rb +4 -2
  34. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -1
  35. data/lib/paper_trail_diff.rb +7 -5
  36. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  37. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  38. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  39. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  40. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +4 -0
  41. data/sig/generated/paper_trail_diff/analysis.rbs +17 -5
  42. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +4 -0
  43. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  44. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +3 -0
  45. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +11 -3
  46. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +10 -0
  47. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  48. data/sig/generated/paper_trail_diff/prepared_history.rbs +6 -1
  49. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +2 -1
  50. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  51. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -7
  52. data/sig/generated/paper_trail_diff/scope_ranking.rbs +6 -6
  53. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  54. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +8 -3
  55. data/sig/generated/paper_trail_diff/time_range.rbs +4 -3
  56. data/sig/generated/paper_trail_diff/timeline_builder.rbs +4 -0
  57. data/sig/generated/paper_trail_diff/transaction_cut.rbs +46 -14
  58. data/sig/generated/paper_trail_diff/version_boundary.rbs +2 -0
  59. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +3 -0
  60. data/sig/generated/paper_trail_diff.rbs +2 -2
  61. metadata +7 -5
@@ -3,11 +3,18 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Shares association event discovery across every root in a prepared graph.
6
+ #
7
+ # The candidates are the records the prepared snapshots can hold: those
8
+ # recorded under an owner from the start onward, and those under it now. A
9
+ # key changed without a version is recorded only by the record's next
10
+ # version, or by the current row, either of which can come after the range,
11
+ # and the snapshots read it from there. ActivityTreeFilter leaves out the
12
+ # events of a candidate that was outside the tree throughout.
6
13
  class PreparedActivityIndex
7
- #: (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
8
- def initialize(records, root_versions, start_at:, end_at:)
14
+ #: (PreparedRecordIndex, Array[untyped], start_at: untyped) -> void
15
+ def initialize(records, root_versions, start_at:)
9
16
  @records = records
10
- @range = ActivityRange.new(start_at, end_at)
17
+ @range = ActivityRange.new(start_at, nil)
11
18
  @roots = root_versions.group_by { |version| [version.item_type, version.item_id.to_s] }
12
19
  @nodes = {} #: Hash[String, Array[untyped]]
13
20
  # Rows are cached by reflection, which a subclass shares with its base.
@@ -73,17 +80,15 @@ module PaperTrailDiff
73
80
  historical, live = @children[reflection] ||= child_rows(model, reflection)
74
81
  empty = [] #: Array[untyped]
75
82
  selected = historical_ids(reflection.klass, ids, historical, range)
76
- selected |= ids.flat_map { |id| live.fetch(id.to_s, empty) } if range.current_end?
77
- selected.uniq
83
+ selected | ids.flat_map { |id| live.fetch(id.to_s, empty) }
78
84
  end
79
85
 
80
- # The `belongs_to` targets each owner pointed at in the range: at its start
81
- # and after each change inside it, plus the live row at a current end.
86
+ # The `belongs_to` targets each owner pointed at from the range's start
87
+ # onward, plus the live row.
82
88
  #: (untyped, Array[untyped], untyped, ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
83
89
  def target_rows(model, ids, reflection, range)
84
90
  historical, live = @targets[reflection] ||= target_candidates(model, reflection)
85
- rows = eligible_rows(model, rows_for(historical, ids), range)
86
- range.current_end? ? rows + rows_for(live, ids) : rows
91
+ eligible_rows(model, rows_for(historical, ids), range) + rows_for(live, ids)
87
92
  end
88
93
 
89
94
  #: (untyped, untyped) -> bool
@@ -153,8 +158,7 @@ module PaperTrailDiff
153
158
  #: (untyped, Array[ActivityTargetCandidateLoader::Row], ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
154
159
  def eligible_rows(model, rows, range)
155
160
  rows.select do |row|
156
- eligible_version?(model, row.owner_id, row.created_at, row.event, range) &&
157
- range.recorded_before_end?(row.created_at, row.version_id)
161
+ eligible_version?(model, row.owner_id, row.created_at, row.event, range)
158
162
  end
159
163
  end
160
164
 
@@ -170,7 +174,7 @@ module PaperTrailDiff
170
174
  # survive a later pre-window reassignment just because that owner is absent.
171
175
  #: (untyped, untyped, untyped, String?, ActivityRange) -> bool
172
176
  def eligible_version?(model, id, timestamp, event, range)
173
- return timestamp <= range.end_time if timestamp >= range.start_time
177
+ return true if timestamp >= range.start_time
174
178
  return false if event == 'destroy'
175
179
 
176
180
  later = @records.versions_for_id(model, id)
@@ -150,7 +150,9 @@ module PaperTrailDiff
150
150
  # saved, so a tag attached earlier in the checkpoint's own transaction is a
151
151
  # member there, unlike other associations, which a version reads as they
152
152
  # were before its transaction. A member created in that transaction has no
153
- # earlier state, so it is read as it was created.
153
+ # earlier state, so it is read as it was created, from its creation on.
154
+ # The checkpoint's membership also stands for earlier points, since the
155
+ # previous root version; the member did not exist at those yet.
154
156
  #: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
155
157
  def habtm_records(record, reflection, boundary, habtm_boundary, ranked)
156
158
  transaction_id = transaction_id_for(habtm_boundary)
@@ -160,13 +162,17 @@ module PaperTrailDiff
160
162
  ids = @habtm.fetch(edge_key(record.class, reflection), empty)[transaction_id.to_s]
161
163
  return unless ids
162
164
 
163
- members = ids.filter_map do |id|
164
- @records.record_before(reflection.klass, id, boundary) ||
165
- @records.record_created_in(reflection.klass, id, habtm_boundary)
166
- end
165
+ created = VersionBoundary.transaction_id(boundary).to_s == transaction_id.to_s
166
+ members = ids.filter_map { |id| habtm_member(reflection.klass, id, boundary, created) }
167
167
  @conditions.select(reflection, members, ranked: ranked)
168
168
  end
169
169
 
170
+ #: (untyped, untyped, untyped, bool) -> untyped
171
+ def habtm_member(model_class, id, boundary, created)
172
+ @records.record_before(model_class, id, boundary) ||
173
+ (@records.record_created_in(model_class, id, boundary) if created)
174
+ end
175
+
170
176
  # A has_many through reads its parts unranked, as its query does. Its own
171
177
  # scope applies to each row, and a ranked read then keeps a record reached
172
178
  # twice as one member.
@@ -23,9 +23,7 @@ module PaperTrailDiff
23
23
  @traversal = traversal
24
24
  start_at = VersionBoundary.transaction_start(root_versions, start_at)
25
25
  @records = PreparedRecordIndex.new(start_at, end_at: end_at, live_records: live_records)
26
- @activity = PreparedActivityIndex.new(
27
- @records, root_versions, start_at: start_at, end_at: end_at || root_versions.last.created_at
28
- )
26
+ @activity = PreparedActivityIndex.new(@records, root_versions, start_at: start_at)
29
27
  @history = PreparedHistory.new(@records, activity_index: @activity)
30
28
  @edges = PreparedEdgeLoader.new(@records, root_versions, start_at: start_at)
31
29
  @prepared = {} #: Hash[untyped, Array[String]]
@@ -135,11 +135,15 @@ module PaperTrailDiff
135
135
 
136
136
  # A record created in the boundary's own transaction has no state before
137
137
  # it, yet a HABTM checkpoint saved later in that transaction records it as
138
- # a member. Such a member is read as it was created.
138
+ # a member. Such a member is read as it was created, at a boundary after
139
+ # its creation; before it, the record did not exist yet.
139
140
  #: (untyped) -> untyped
140
141
  def record_created_in(boundary)
141
142
  index = transaction_index(boundary)
142
- return unless index && versions.fetch(index).event == 'create'
143
+ return unless index
144
+
145
+ version = versions.fetch(index)
146
+ return unless version.event == 'create' && !VersionBoundary.at_or_after?(version, boundary)
143
147
 
144
148
  state_after(index)&.instantiate
145
149
  end
@@ -0,0 +1,77 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Runs one read's statements inside one database snapshot. Without one, a row
6
+ # that commits between two statements of the read can be seen by one of them
7
+ # and missed by another: an activity read then found a comment whose versions
8
+ # it had not read yet, and raised `KeyError`.
9
+ #
10
+ # PostgreSQL and MySQL (through mysql2 or trilogy), and adapters built on
11
+ # them such as PostGIS, run the read at REPEATABLE READ, which gives every
12
+ # statement of the transaction the same view. Other adapters get no snapshot;
13
+ # docs/reference.md lists them under limitations.
14
+ module ReadSnapshot
15
+ # The adapters whose subclasses take a snapshot, by name, since an
16
+ # application loads only the adapters it uses.
17
+ SNAPSHOT_ADAPTERS = %w[
18
+ ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
19
+ ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter
20
+ ].freeze
21
+
22
+ module_function
23
+
24
+ # Yields once. Each connection the values read through gets a snapshot
25
+ # transaction first, unless that connection already has a transaction open:
26
+ # its isolation level belongs to the caller, and this gem cannot change it.
27
+ # A value may be a model class, a relation, a record, or a version. Any
28
+ # other value reads no table and is ignored.
29
+ #: (Array[untyped]) { () -> untyped } -> untyped
30
+ def call(values, &block)
31
+ classes = connection_classes(values)
32
+ classes.reverse_each.reduce(block) do |inner, klass|
33
+ connection = klass.connection
34
+ next inner if !snapshot?(connection) || connection.transaction_open?
35
+
36
+ -> { klass.transaction(isolation: :repeatable_read) { inner.call } }
37
+ end.call
38
+ end
39
+
40
+ #: (untyped) -> bool
41
+ def snapshot?(connection)
42
+ connection.class.ancestors.any? { |ancestor| SNAPSHOT_ADAPTERS.include?(ancestor.name) }
43
+ end
44
+
45
+ # One class per connection: each read model and its version class, with the
46
+ # repeats through a shared connection dropped. An associated model on
47
+ # another database is not among them, so it is read outside the snapshot.
48
+ #: (Array[untyped]) -> Array[untyped]
49
+ def connection_classes(values)
50
+ values.filter_map { |value| model_for(value) }
51
+ .flat_map { |model| [model, model.paper_trail.version_class] }
52
+ .uniq(&:connection)
53
+ end
54
+
55
+ # The versioned model a value reads from, or nil.
56
+ #: (untyped) -> untyped
57
+ def model_for(value)
58
+ active_record = Object.const_get(:ActiveRecord) #: untyped
59
+ model = case value
60
+ when active_record.const_get(:Relation) then value.klass
61
+ when Class then value
62
+ else endpoint_model(value)
63
+ end
64
+ model if model.is_a?(Class) && Support.versioned?(model)
65
+ end
66
+
67
+ # A version reads the model of its item; a record reads its own class.
68
+ #: (untyped) -> untyped
69
+ def endpoint_model(value)
70
+ return Endpoint.model_class(value) if Endpoint.version?(value)
71
+
72
+ value.class if Endpoint.record?(value)
73
+ end
74
+
75
+ private_class_method :snapshot?, :model_for, :endpoint_model
76
+ end
77
+ end
@@ -56,7 +56,7 @@ module PaperTrailDiff
56
56
  return if ranked && ranked_through?(reflection)
57
57
 
58
58
  relation = scoped_relation(reflection, model_class)
59
- return unless relation && plain_relation?(relation)
59
+ return unless relation && plain_relation?(relation, RELATION_VALUES)
60
60
 
61
61
  clause = relation.where_clause - model_class.unscoped.where_clause
62
62
  predicate = Reader.new(model_class).call(clause.ast)
@@ -70,11 +70,12 @@ module PaperTrailDiff
70
70
  # limit, and offset choose a page of current rows rather than membership,
71
71
  # and loading or selecting columns changes neither, so they are left out.
72
72
  # A single-table subclass's type condition is left to the caller, as for
73
- # an association.
73
+ # an association. `none` selects nothing, whatever it is chained to.
74
74
  #: (untyped, untyped) -> ScopeCondition?
75
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? }
76
+ return nothing if relation.null_relation?
77
+
78
+ return unless plain_relation?(relation, [*RELATION_VALUES, *LOADING_VALUES])
78
79
 
79
80
  clause = relation.where_clause - model_class.unscoped.where_clause
80
81
  new(model_class, Reader.new(model_class).call(clause.ast))
@@ -82,6 +83,14 @@ module PaperTrailDiff
82
83
  nil
83
84
  end
84
85
 
86
+ # A relation `none` built, whose where clause is SQL text. A condition
87
+ # that matches nothing reads no attribute, so it names no model.
88
+ #: () -> ScopeCondition
89
+ def self.nothing
90
+ new(nil, [:or, []])
91
+ end
92
+ private_class_method :nothing
93
+
85
94
  # nil when the relation picks its members by conditions alone.
86
95
  #: (untyped, untyped, untyped) -> ScopeRanking?
87
96
  def self.ranking(relation, reflection, model_class)
@@ -135,10 +144,10 @@ module PaperTrailDiff
135
144
  private_class_method :scoped_relation
136
145
 
137
146
  # 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
147
+ # empty. `allowed` names the parts that may hold values.
148
+ #: (untyped, Array[Symbol]) -> bool
149
+ def self.plain_relation?(relation, allowed)
150
+ extra = relation.values.except(*allowed).values
142
151
  extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
143
152
  end
144
153
  private_class_method :plain_relation?
@@ -158,6 +167,13 @@ module PaperTrailDiff
158
167
  evaluate(@predicate, attributes) == true
159
168
  end
160
169
 
170
+ # Whether no record can match, as for a relation `none` built.
171
+ #: () -> bool
172
+ def none?
173
+ operator, parts = @predicate
174
+ operator == :or && parts.empty?
175
+ end
176
+
161
177
  # The members among records that are each the owner's by key: those that
162
178
  # meet the conditions, then ranked.
163
179
  #: (Array[untyped]) -> Array[untyped]
@@ -181,10 +197,18 @@ module PaperTrailDiff
181
197
  eq: ->(value, expected) { expected.nil? || !value.nil? ? value == expected : nil },
182
198
  not_eq: ->(value, expected) { expected.nil? || !value.nil? ? value != expected : nil },
183
199
  in: ->(value, expected) { expected.include?(value) unless value.nil? },
184
- not_in: ->(value, expected) { !expected.include?(value) unless value.nil? }
200
+ not_in: ->(value, expected) { !expected.include?(value) unless value.nil? },
201
+ gt: ->(value, expected) { value > expected unless value.nil? },
202
+ gteq: ->(value, expected) { value >= expected unless value.nil? },
203
+ lt: ->(value, expected) { value < expected unless value.nil? },
204
+ lteq: ->(value, expected) { value <= expected unless value.nil? }
185
205
  }.freeze
186
206
  private_constant :COMPARISONS
187
207
 
208
+ # Comparisons that order values, which read them as ScopeRanking sorts.
209
+ ORDERED = %i[gt gteq lt lteq].freeze
210
+ private_constant :ORDERED
211
+
188
212
  private
189
213
 
190
214
  # @rbs @model_class: untyped
@@ -199,7 +223,7 @@ module PaperTrailDiff
199
223
  when :and then all(first.map { |part| evaluate(part, attributes) })
200
224
  when :or then any(first.map { |part| evaluate(part, attributes) })
201
225
  when :not then negate(evaluate(first, attributes))
202
- else COMPARISONS.fetch(operator).call(stored(first, attributes), second)
226
+ else COMPARISONS.fetch(operator).call(stored(operator, first, attributes), second)
203
227
  end
204
228
  end
205
229
 
@@ -224,10 +248,15 @@ module PaperTrailDiff
224
248
  !value unless value.nil?
225
249
  end
226
250
 
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])
251
+ # The form the database holds, as the scope's own values were cast. An
252
+ # order reads the value the database sorts by instead: SQL Server holds a
253
+ # time or date in a wrapper that only compares for equality.
254
+ #: (Symbol, String, Hash[String, untyped]) -> untyped
255
+ def stored(operator, name, attributes)
256
+ value = attributes[name]
257
+ return ScopeRanking.sort_value(@model_class, name, value) if ORDERED.include?(operator)
258
+
259
+ @model_class.type_for_attribute(name).serialize(value)
231
260
  end
232
261
 
233
262
  # Builds each reflection's condition once per target class.
@@ -293,10 +322,51 @@ module PaperTrailDiff
293
322
  when 'Arel::Nodes::HomogeneousIn' then homogeneous_in(node)
294
323
  when 'Arel::Nodes::In' then list(:in, node.left, values(node.right))
295
324
  when 'Arel::Nodes::NotIn' then list(:not_in, node.left, values(node.right))
296
- else raise Unreadable
325
+ else range(node)
297
326
  end
298
327
  end
299
328
 
329
+ RANGES = { 'Arel::Nodes::GreaterThan' => :gt, 'Arel::Nodes::GreaterThanOrEqual' => :gteq,
330
+ 'Arel::Nodes::LessThan' => :lt, 'Arel::Nodes::LessThanOrEqual' => :lteq }.freeze
331
+ private_constant :RANGES
332
+
333
+ # A range, as `where(created_at: 1.day.ago..)` writes it, on a column
334
+ # whose values sort in Ruby as the database sorts them.
335
+ #: (untyped) -> Array[untyped]
336
+ def range(node)
337
+ name = node.class.name
338
+ return between(node) if name == 'Arel::Nodes::Between'
339
+
340
+ operator = RANGES[name] or raise Unreadable
341
+ bound(operator, node.left, node.right)
342
+ end
343
+
344
+ #: (untyped) -> Array[untyped]
345
+ def between(node)
346
+ low, high = node.right.children
347
+ [:and, [bound(:gteq, node.left, low), bound(:lteq, node.left, high)]]
348
+ end
349
+
350
+ #: (Symbol, untyped, untyped) -> Array[untyped]
351
+ def bound(operator, attribute, node)
352
+ name = column(attribute, null_test: true)
353
+ boolean = :boolean.equal?(@model_class.type_for_attribute(name).type)
354
+ raise Unreadable unless ScopeRanking.orderable?(@model_class, name) && !boolean
355
+
356
+ expected = value(node)
357
+ raise Unreadable if expected.nil?
358
+
359
+ [operator, name, sort_value(name, expected)]
360
+ end
361
+
362
+ # A bound in the form the database holds, read back as the value the
363
+ # database sorts by. Reading it back unwraps what an adapter wraps.
364
+ #: (String, untyped) -> untyped
365
+ def sort_value(name, stored)
366
+ read = @model_class.type_for_attribute(name).deserialize(stored)
367
+ ScopeRanking.sort_value(@model_class, name, read)
368
+ end
369
+
300
370
  # Whether a value is NULL compares alike on every type.
301
371
  #: (Symbol, untyped) -> Array[untyped]
302
372
  def binary(operator, node)
@@ -115,7 +115,16 @@ module PaperTrailDiff
115
115
  ORDER_TYPES.intersect?(kinds) ||
116
116
  (kinds.include?(DATETIME_TYPE) && exact_time?(model_class, type))
117
117
  end
118
- private_class_method :orderable?
118
+
119
+ # The value the database sorts by, as the column's type casts it. An enum
120
+ # sorts by the integer it stores; other types are compared cast, since an
121
+ # adapter may serialize a time or date as a wrapper, as SQL Server does.
122
+ #: (untyped, String, untyped) -> untyped
123
+ def self.sort_value(model_class, name, value)
124
+ type = model_class.type_for_attribute(name)
125
+ cast = type.cast(value)
126
+ ENUM_TYPE.eql?(type.class.name) ? type.serialize(cast) : cast
127
+ end
119
128
 
120
129
  # The type of the value a column stores, under an enum or time zone wrapper.
121
130
  #: (untyped) -> untyped
@@ -171,7 +180,7 @@ module PaperTrailDiff
171
180
  #: (Hash[String, untyped]) -> Array[Array[Numeric]]
172
181
  def sort_key(attributes)
173
182
  @keys.map do |name, descending|
174
- place = place(stored(name, attributes))
183
+ place = place(ScopeRanking.sort_value(@model_class, name, attributes[name]))
175
184
  descending ? place.map(&:-@) : place
176
185
  end
177
186
  end
@@ -192,15 +201,5 @@ module PaperTrailDiff
192
201
  value = value.jd if value.respond_to?(:jd)
193
202
  value.to_r
194
203
  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
204
  end
206
205
  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, ?activity_tree: AssociationTree?) -> 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?, ?version_scope: untyped) -> 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:, activity_tree: nil
10
+ analyzer:, deleted_analyzer:, activity_tree: nil, version_scope: 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)
@@ -17,9 +17,10 @@ module PaperTrailDiff
17
17
  @selection = ScopedRootSelection.new(
18
18
  scope, limit: limit, time_range: within.nil? ? nil : TimeRange.new(within),
19
19
  historical_filter: historical_filter, max_filter_versions: max_filter_versions,
20
- activity_tree: activity_tree
20
+ activity_tree: activity_tree, version_scope: version_scope
21
21
  )
22
- @deleted_filter = DeletedRootFilter.new(scope.all) if include_deleted
22
+ @deleted_filter = deleted_filter(scope, include_deleted)
23
+ @include_deleted = include_deleted
23
24
  @limit = limit
24
25
  @analyzer = analyzer
25
26
  @deleted_analyzer = deleted_analyzer
@@ -28,10 +29,9 @@ module PaperTrailDiff
28
29
  #: () -> ScopedAnalysis
29
30
  def call
30
31
  selection = @selection.call
31
- deleted_filter = @deleted_filter
32
- return analysis(selection, selection.unreachable, {}) unless deleted_filter
32
+ unreachable = @deleted_filter&.call(selection.unreachable) || selection.unreachable
33
+ return analysis(selection, unreachable, {}) unless @include_deleted
33
34
 
34
- unreachable = deleted_filter.call(selection.unreachable)
35
35
  if selection.records.length + unreachable.length > @limit
36
36
  raise BatchLimitExceededError, 'include_deleted: live and missing roots exceed limit:'
37
37
  end
@@ -41,6 +41,15 @@ module PaperTrailDiff
41
41
 
42
42
  private
43
43
 
44
+ # Without the option, the deleted roots are still tested when the
45
+ # relation can be read, so that another selection's are not listed.
46
+ #: (untyped, bool) -> DeletedRootFilter?
47
+ def deleted_filter(scope, include_deleted)
48
+ return DeletedRootFilter.new(scope.all) if include_deleted
49
+
50
+ DeletedRootFilter.readable(scope.all)
51
+ end
52
+
44
53
  #: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
45
54
  def analysis(selection, unreachable, deleted)
46
55
  ScopedAnalysis.new(analyses: @analyzer.call(selection.records), roots: selection.records,
@@ -49,6 +58,7 @@ module PaperTrailDiff
49
58
 
50
59
  # @rbs @selection: ScopedRootSelection
51
60
  # @rbs @deleted_filter: DeletedRootFilter?
61
+ # @rbs @include_deleted: bool
52
62
  # @rbs @limit: Integer
53
63
  # @rbs @analyzer: untyped
54
64
  # @rbs @deleted_analyzer: untyped
@@ -45,13 +45,16 @@ module PaperTrailDiff
45
45
 
46
46
  # `activity_tree` names the association paths whose changes also select a
47
47
  # root, as an activity analysis reports them. Without one, only a root's
48
- # own versions select it.
49
- #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
48
+ # own versions select it. `version_scope` narrows which of those count,
49
+ # as it narrows which are reported.
50
+ #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
50
51
  def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
51
- max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil)
52
+ max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil,
53
+ version_scope: nil)
52
54
  @scope = normalize_scope(scope)
53
55
  reject_unversioned!
54
56
  @time_range = time_range
57
+ @version_scope = VersionScopeFilter.validated(version_scope)
55
58
  @limit = validate_limit(limit)
56
59
  @related = if activity_tree
57
60
  AssociationActivitySelection.new(model, tree: activity_tree,
@@ -80,6 +83,7 @@ module PaperTrailDiff
80
83
  # @rbs @limit: Integer
81
84
  # @rbs @historical_filter: untyped
82
85
  # @rbs @related: AssociationActivitySelection?
86
+ # @rbs @version_scope: untyped
83
87
 
84
88
  # Leaves the candidate set in the database. Plucking every root changed in
85
89
  # the window would cost memory and a statement proportional to all activity
@@ -150,11 +154,14 @@ module PaperTrailDiff
150
154
  window_versions.where.not(item_id: base_class.unscoped).distinct.pluck(:item_id).map(&:to_s)
151
155
  end
152
156
 
157
+ # Only the versions `version_scope` keeps select a root: one whose versions
158
+ # in the window it drops would have nothing to report.
153
159
  #: () -> untyped
154
160
  def window_versions
155
161
  relation = VersionQuery.for_model(model)
156
162
  range = @time_range
157
- range ? range.scope(relation) : relation
163
+ relation = range.scope(relation) if range
164
+ @version_scope ? @version_scope.call(relation) : relation
158
165
  end
159
166
 
160
167
  # Accepts a model class as readily as a relation: `Article` and
@@ -39,7 +39,13 @@ module PaperTrailDiff
39
39
 
40
40
  #: (untyped) -> untyped
41
41
  def scope(relation)
42
- relation.where(created_at: query_range)
42
+ relation.where(created_at: to_range)
43
+ end
44
+
45
+ # The window as a Ruby range, its end included or left out as given.
46
+ #: () -> Range[Time]
47
+ def to_range
48
+ exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
43
49
  end
44
50
 
45
51
  #: (untyped) -> untyped
@@ -71,11 +77,6 @@ module PaperTrailDiff
71
77
  exclude_end? ? column.gteq(end_time) : column.gt(end_time)
72
78
  end
73
79
 
74
- #: () -> Range[Time]
75
- def query_range
76
- exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
77
- end
78
-
79
80
  #: (untyped, boundary: Symbol) -> Time
80
81
  def coerce_time(value, boundary:)
81
82
  time_value(value).getutc.freeze
@@ -24,6 +24,12 @@ module PaperTrailDiff
24
24
  steps
25
25
  end
26
26
 
27
+ # The window the range covers once its edges have moved to transactions.
28
+ #: () -> TimeRange?
29
+ def window
30
+ @range.time_range
31
+ end
32
+
27
33
  #: () -> Analysis
28
34
  def analyze
29
35
  steps, first_snapshot, last_snapshot = compare_history(selected_versions)