paper_trail_diff 0.14.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -146,6 +146,13 @@ module PaperTrailDiff
146
146
  owners ? owners.fetch(owner.id.to_s, empty) : group.fetch(:ids)
147
147
  end
148
148
 
149
+ # PT-AT records a checkpoint's membership as it is when the checkpoint is
150
+ # saved, so a tag attached earlier in the checkpoint's own transaction is a
151
+ # member there, unlike other associations, which a version reads as they
152
+ # were before its transaction. A member created in that transaction has no
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.
149
156
  #: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
150
157
  def habtm_records(record, reflection, boundary, habtm_boundary, ranked)
151
158
  transaction_id = transaction_id_for(habtm_boundary)
@@ -155,10 +162,17 @@ module PaperTrailDiff
155
162
  ids = @habtm.fetch(edge_key(record.class, reflection), empty)[transaction_id.to_s]
156
163
  return unless ids
157
164
 
158
- members = ids.filter_map { |id| @records.record_before(reflection.klass, id, boundary) }
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) }
159
167
  @conditions.select(reflection, members, ranked: ranked)
160
168
  end
161
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
+
162
176
  # A has_many through reads its parts unranked, as its query does. Its own
163
177
  # scope applies to each row, and a ranked read then keeps a record reached
164
178
  # twice as one member.
@@ -21,10 +21,9 @@ module PaperTrailDiff
21
21
  @root_versions = root_versions
22
22
  @tree = tree
23
23
  @traversal = traversal
24
+ start_at = VersionBoundary.transaction_start(root_versions, start_at)
24
25
  @records = PreparedRecordIndex.new(start_at, end_at: end_at, live_records: live_records)
25
- @activity = PreparedActivityIndex.new(
26
- @records, root_versions, start_at: start_at, end_at: end_at || root_versions.last.created_at
27
- )
26
+ @activity = PreparedActivityIndex.new(@records, root_versions, start_at: start_at)
28
27
  @history = PreparedHistory.new(@records, activity_index: @activity)
29
28
  @edges = PreparedEdgeLoader.new(@records, root_versions, start_at: start_at)
30
29
  @prepared = {} #: Hash[untyped, Array[String]]
@@ -133,6 +133,21 @@ module PaperTrailDiff
133
133
  state_before(boundary)&.instantiate
134
134
  end
135
135
 
136
+ # A record created in the boundary's own transaction has no state before
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, at a boundary after
139
+ # its creation; before it, the record did not exist yet.
140
+ #: (untyped) -> untyped
141
+ def record_created_in(boundary)
142
+ index = transaction_index(boundary)
143
+ return unless index
144
+
145
+ version = versions.fetch(index)
146
+ return unless version.event == 'create' && !VersionBoundary.at_or_after?(version, boundary)
147
+
148
+ state_after(index)&.instantiate
149
+ end
150
+
136
151
  #: (untyped) -> PreparedRecordState?
137
152
  def state_before(boundary)
138
153
  index = boundary_index(boundary)
@@ -179,7 +194,7 @@ module PaperTrailDiff
179
194
  [state_for(version), state_after(index)].compact
180
195
  end
181
196
 
182
- #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
197
+ #: (untyped) -> [PreparedRecordState, PreparedRecordState]?
183
198
  def transition(version)
184
199
  index = @version_positions[version.id.to_s]
185
200
  return unless index
@@ -188,7 +203,7 @@ module PaperTrailDiff
188
203
  after = state_after(index)
189
204
  return unless before && after && before.model_class == after.model_class
190
205
 
191
- [before.attributes, after.attributes]
206
+ [before, after]
192
207
  end
193
208
 
194
209
  private
@@ -228,7 +243,7 @@ module PaperTrailDiff
228
243
 
229
244
  #: (untyped) -> Integer?
230
245
  def transaction_index(boundary)
231
- transaction_id = boundary.transaction_id if boundary.respond_to?(:transaction_id)
246
+ transaction_id = VersionBoundary.transaction_id(boundary)
232
247
  return unless transaction_id
233
248
 
234
249
  @transaction_positions[transaction_id]
@@ -238,9 +253,7 @@ module PaperTrailDiff
238
253
  def build_transaction_positions
239
254
  positions = {} #: Hash[untyped, Integer]
240
255
  @versions.each_with_index do |version, index|
241
- next unless version.respond_to?(:transaction_id)
242
-
243
- transaction_id = version.transaction_id
256
+ transaction_id = VersionBoundary.transaction_id(version)
244
257
  positions[transaction_id] ||= index if transaction_id
245
258
  end
246
259
  positions.freeze
@@ -304,6 +317,11 @@ module PaperTrailDiff
304
317
  @series.fetch(identity(model_class, id)).record_before(boundary)
305
318
  end
306
319
 
320
+ #: (untyped, untyped, untyped) -> untyped
321
+ def record_created_in(model_class, id, boundary)
322
+ @series.fetch(identity(model_class, id)).record_created_in(boundary)
323
+ end
324
+
307
325
  #: (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
308
326
  def snapshot_state_before(model_class, id, boundary)
309
327
  series = @series[identity(model_class, id)]
@@ -317,9 +335,15 @@ module PaperTrailDiff
317
335
  [!prepared.nil?, prepared]
318
336
  end
319
337
 
338
+ # Typed as a reified record's attributes are. A JSON or JSONB `object`
339
+ # column stores times and dates as strings, which PaperTrail does not cast
340
+ # back, and the transition is carried into snapshots built from records.
320
341
  #: (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
321
342
  def transition(model_class, id, version)
322
- @series[identity(model_class, id)]&.transition(version)
343
+ states = @series[identity(model_class, id)]&.transition(version)
344
+ return unless states
345
+
346
+ [typed_attributes(states.fetch(0)), typed_attributes(states.fetch(1))]
323
347
  end
324
348
 
325
349
  #: (untyped, untyped, untyped, ?direct: bool) -> [bool, untyped]
@@ -370,6 +394,17 @@ module PaperTrailDiff
370
394
 
371
395
  private
372
396
 
397
+ # A model whose records need their own initialization is cast by
398
+ # instantiating it, as reify does.
399
+ #: (PreparedRecordState) -> Hash[untyped, untyped]
400
+ def typed_attributes(state)
401
+ @direct_states[state] = @direct_loader.complete(state) unless @direct_states.key?(state)
402
+ typed = @direct_states[state]
403
+ return typed.attributes if typed
404
+
405
+ PreparedRecordState.new(state.instantiate).attributes
406
+ end
407
+
373
408
  #: (untyped, String) -> bool
374
409
  def generated_reader?(model, name)
375
410
  model.define_attribute_methods
@@ -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
@@ -14,9 +14,11 @@ module PaperTrailDiff
14
14
  # An error is a specification, so it names the way out as well as the wall.
15
15
  # A window ending at the present can never gain a later version, which makes
16
16
  # "write a checkpoint afterwards" impossible advice on its own.
17
+ # A window closes on the current record when it reaches the present, so
18
+ # this is raised only when there is none to read.
17
19
  INCOMPLETE = 'time range requires a later root version to reconstruct its ' \
18
- 'final change: pass close_on: :current to end at current state, ' \
19
- 'or narrow the window to end before the last recorded version'
20
+ 'final change, and there is no current record to end at: narrow ' \
21
+ 'the window to end before the last recorded version'
20
22
 
21
23
  #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
22
24
  def initialize( # rubocop:disable Metrics/ParameterLists
@@ -14,6 +14,8 @@ module PaperTrailDiff
14
14
  # ranking alone.
15
15
  RELATION_VALUES = %i[where order reordering limit offset readonly strict_loading
16
16
  extending].freeze
17
+ # Relation parts that load or shape rows without choosing them.
18
+ LOADING_VALUES = %i[includes preload select distinct].freeze
17
19
  # Types whose stored values compare in Ruby as the database compares them,
18
20
  # named rather than referenced so that loading needs no Active Model.
19
21
  VALUE_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
@@ -54,7 +56,7 @@ module PaperTrailDiff
54
56
  return if ranked && ranked_through?(reflection)
55
57
 
56
58
  relation = scoped_relation(reflection, model_class)
57
- return unless relation && plain_relation?(relation)
59
+ return unless relation && plain_relation?(relation, RELATION_VALUES)
58
60
 
59
61
  clause = relation.where_clause - model_class.unscoped.where_clause
60
62
  predicate = Reader.new(model_class).call(clause.ast)
@@ -63,6 +65,32 @@ module PaperTrailDiff
63
65
  nil
64
66
  end
65
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. `none` selects nothing, whatever it is chained to.
74
+ #: (untyped, untyped) -> ScopeCondition?
75
+ def self.for_relation(relation, model_class)
76
+ return nothing if relation.null_relation?
77
+
78
+ return unless plain_relation?(relation, [*RELATION_VALUES, *LOADING_VALUES])
79
+
80
+ clause = relation.where_clause - model_class.unscoped.where_clause
81
+ new(model_class, Reader.new(model_class).call(clause.ast))
82
+ rescue Unreadable
83
+ nil
84
+ end
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
+
66
94
  # nil when the relation picks its members by conditions alone.
67
95
  #: (untyped, untyped, untyped) -> ScopeRanking?
68
96
  def self.ranking(relation, reflection, model_class)
@@ -116,10 +144,10 @@ module PaperTrailDiff
116
144
  private_class_method :scoped_relation
117
145
 
118
146
  # 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
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
123
151
  extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
124
152
  end
125
153
  private_class_method :plain_relation?
@@ -132,9 +160,18 @@ module PaperTrailDiff
132
160
  freeze
133
161
  end
134
162
 
163
+ # SQL admits a row only when its condition is true, not when it is
164
+ # unknown.
135
165
  #: (Hash[String, untyped]) -> bool
136
166
  def matches?(attributes)
137
- evaluate(@predicate, attributes)
167
+ evaluate(@predicate, attributes) == true
168
+ end
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?
138
175
  end
139
176
 
140
177
  # The members among records that are each the owner's by key: those that
@@ -152,36 +189,74 @@ module PaperTrailDiff
152
189
  ranking ? ranking.call(records) : records
153
190
  end
154
191
 
155
- # SQL compares NULL with nothing, so only an IS NULL test, an equality
156
- # with nil, matches it.
192
+ # SQL's three values: a comparison with NULL is unknown (nil) rather than
193
+ # false, except an IS NULL or IS NOT NULL test, an equality with nil, which
194
+ # is always known. Unknown matters only under NOT, which leaves it
195
+ # unknown where false would become true.
157
196
  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) }
197
+ eq: ->(value, expected) { expected.nil? || !value.nil? ? value == expected : nil },
198
+ not_eq: ->(value, expected) { expected.nil? || !value.nil? ? value != expected : nil },
199
+ 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? }
162
205
  }.freeze
163
206
  private_constant :COMPARISONS
164
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
+
165
212
  private
166
213
 
167
214
  # @rbs @model_class: untyped
168
215
  # @rbs @predicate: Array[untyped]
169
216
  # @rbs @ranking: ScopeRanking?
170
217
 
171
- #: (Array[untyped], Hash[String, untyped]) -> bool
218
+ # true, false, or nil for unknown.
219
+ #: (Array[untyped], Hash[String, untyped]) -> bool?
172
220
  def evaluate(predicate, attributes)
173
221
  operator, first, second = predicate
174
222
  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)
223
+ when :and then all(first.map { |part| evaluate(part, attributes) })
224
+ when :or then any(first.map { |part| evaluate(part, attributes) })
225
+ when :not then negate(evaluate(first, attributes))
226
+ else COMPARISONS.fetch(operator).call(stored(operator, first, attributes), second)
178
227
  end
179
228
  end
180
229
 
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])
230
+ # False if any part is, otherwise unknown if any part is.
231
+ #: (Array[bool?]) -> bool?
232
+ def all(values)
233
+ return false if values.include?(false)
234
+
235
+ true unless values.include?(nil)
236
+ end
237
+
238
+ # True if any part is, otherwise unknown if any part is.
239
+ #: (Array[bool?]) -> bool?
240
+ def any(values)
241
+ return true if values.include?(true)
242
+
243
+ false unless values.include?(nil)
244
+ end
245
+
246
+ #: (bool?) -> bool?
247
+ def negate(value)
248
+ !value unless value.nil?
249
+ end
250
+
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)
185
260
  end
186
261
 
187
262
  # Builds each reflection's condition once per target class.
@@ -224,6 +299,7 @@ module PaperTrailDiff
224
299
  when 'Arel::Nodes::And' then [:and, node.children.map { |child| call(child) }]
225
300
  when 'Arel::Nodes::Or' then [:or, either(node).map { |child| call(child) }]
226
301
  when 'Arel::Nodes::Grouping' then call(node.expr)
302
+ when 'Arel::Nodes::Not' then [:not, call(node.expr)]
227
303
  else comparison(node)
228
304
  end
229
305
  end
@@ -246,13 +322,56 @@ module PaperTrailDiff
246
322
  when 'Arel::Nodes::HomogeneousIn' then homogeneous_in(node)
247
323
  when 'Arel::Nodes::In' then list(:in, node.left, values(node.right))
248
324
  when 'Arel::Nodes::NotIn' then list(:not_in, node.left, values(node.right))
249
- else raise Unreadable
325
+ else range(node)
250
326
  end
251
327
  end
252
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
+
370
+ # Whether a value is NULL compares alike on every type.
253
371
  #: (Symbol, untyped) -> Array[untyped]
254
372
  def binary(operator, node)
255
- [operator, column(node.left), value(node.right)]
373
+ expected = value(node.right)
374
+ [operator, column(node.left, null_test: expected.nil?), expected]
256
375
  end
257
376
 
258
377
  #: (untyped) -> Array[untyped]
@@ -272,29 +391,35 @@ module PaperTrailDiff
272
391
  end
273
392
 
274
393
  # 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)
394
+ # a type both compare alike. Whether a value is NULL, any column's
395
+ # type compares alike.
396
+ #: (untyped, ?null_test: bool) -> String
397
+ def column(attribute, null_test: false)
278
398
  raise Unreadable unless ATTRIBUTE.eql?(attribute.class.name)
279
399
 
280
400
  table = attribute.relation
281
401
  raise Unreadable unless table.name == @model_class.table_name && table.table_alias.nil?
282
402
 
283
403
  name = attribute.name
284
- raise Unreadable unless comparable?(name)
404
+ column = @model_class.columns_hash[name]
405
+ raise Unreadable unless column && (null_test || comparable?(name, column))
285
406
 
286
407
  name
287
408
  end
288
409
 
289
- #: (String) -> bool
290
- def comparable?(name)
291
- column = @model_class.columns_hash[name]
410
+ #: (String, untyped) -> bool
411
+ def comparable?(name, column)
292
412
  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)
413
+ return false unless VALUE_TYPES.intersect?(kinds)
414
+
415
+ !kinds.include?(TEXT_TYPE) || exact_text?(column)
416
+ end
295
417
 
418
+ # PostgreSQL's citext is text that compares without regard to case.
419
+ #: (untyped) -> bool
420
+ def exact_text?(column)
296
421
  EXACT_TEXT_ADAPTERS.include?(@model_class.connection_db_config.adapter) &&
297
- column.collation.nil?
422
+ column.collation.nil? && !column.sql_type.casecmp?('citext')
298
423
  end
299
424
 
300
425
  # An enum compares the values it stores, which its subtype describes. A
@@ -11,6 +11,9 @@ module PaperTrailDiff
11
11
  DIRECTIONS = { 'Arel::Nodes::Ascending' => false, 'Arel::Nodes::Descending' => true }.freeze
12
12
  ATTRIBUTE = 'Arel::Attributes::Attribute'
13
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'
14
17
  # Integers, booleans and dates sort alike everywhere. Strings follow a
15
18
  # collation, so they are not read.
16
19
  ORDER_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
@@ -107,13 +110,29 @@ module PaperTrailDiff
107
110
  def self.orderable?(model_class, name)
108
111
  return false unless model_class.columns_hash.key?(name)
109
112
 
110
- type = model_class.type_for_attribute(name)
111
- type = type.subtype if ENUM_TYPE.eql?(type.class.name)
113
+ type = stored_type(model_class.type_for_attribute(name))
112
114
  kinds = type.class.ancestors.map(&:name)
113
115
  ORDER_TYPES.intersect?(kinds) ||
114
116
  (kinds.include?(DATETIME_TYPE) && exact_time?(model_class, type))
115
117
  end
116
- 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
128
+
129
+ # The type of the value a column stores, under an enum or time zone wrapper.
130
+ #: (untyped) -> untyped
131
+ def self.stored_type(type)
132
+ type = type.subtype if ENUM_TYPE.eql?(type.class.name)
133
+ TIME_ZONE_TYPE.eql?(type.class.name) ? type.__getobj__ : type
134
+ end
135
+ private_class_method :stored_type
117
136
 
118
137
  # Active Record truncates a time to its column's precision before writing
119
138
  # it, so history holds the stored value when it keeps that many digits.
@@ -161,7 +180,7 @@ module PaperTrailDiff
161
180
  #: (Hash[String, untyped]) -> Array[Array[Numeric]]
162
181
  def sort_key(attributes)
163
182
  @keys.map do |name, descending|
164
- place = place(stored(name, attributes))
183
+ place = place(ScopeRanking.sort_value(@model_class, name, attributes[name]))
165
184
  descending ? place.map(&:-@) : place
166
185
  end
167
186
  end
@@ -182,15 +201,5 @@ module PaperTrailDiff
182
201
  value = value.jd if value.respond_to?(:jd)
183
202
  value.to_r
184
203
  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
204
  end
196
205
  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]]]