paper_trail_diff 0.17.1 → 0.18.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 (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +648 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +15 -23
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +194 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
@@ -7,25 +7,18 @@ module PaperTrailDiff
7
7
  # record's state there rather than by a query. A limit, offset or has_one
8
8
  # order then ranks the records that meet the conditions (ScopeRanking). It
9
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.
10
+ # per record. A scope it cannot read exactly builds no condition, and a
11
+ # request that names it is refused (UnreadablePaths).
12
12
  class ScopeCondition
13
- # Relation parts that leave membership to the where clause and the
14
- # ranking alone.
15
- RELATION_VALUES = %i[where order reordering limit offset readonly strict_loading
16
- extending].freeze
17
- # Relation parts that load or shape rows without choosing them.
18
- LOADING_VALUES = %i[includes preload select distinct].freeze
19
- # Types whose stored values compare in Ruby as the database compares them,
20
- # named rather than referenced so that loading needs no Active Model.
21
- VALUE_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
22
- ActiveModel::Type::ImmutableString].freeze
23
- TEXT_TYPE = 'ActiveModel::Type::ImmutableString'
24
- ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
13
+ # Relation parts that choose rows other than by the where clause and the
14
+ # ranking the reader follows. Any other part, such as a lock, a comment,
15
+ # a table named for a string order, or what to load, leaves membership
16
+ # alone; `reverse_order` is applied to the order at once.
17
+ ROW_CHOOSING_VALUES = %i[joins left_outer_joins from group having with].freeze
25
18
  BIND_PARAM = 'Arel::Nodes::BindParam'
26
- # Adapters that compare strings exactly by default. MySQL and SQL Server
27
- # ignore case and trailing spaces by default, which Ruby cannot follow.
28
- EXACT_TEXT_ADAPTERS = %w[sqlite3 postgresql].freeze
19
+ # Column kinds (ExactColumnType) whose values compare for equality in
20
+ # Ruby as the database compares them.
21
+ COMPARABLE_KINDS = %i[integer boolean text].freeze
29
22
 
30
23
  # Raised while reading a node that has no exact plain-Ruby reading.
31
24
  class Unreadable < StandardError; end
@@ -53,7 +46,7 @@ module PaperTrailDiff
53
46
  return if ranked && ranked_through?(reflection)
54
47
 
55
48
  relation = scoped_relation(reflection, model_class)
56
- return unless relation && plain_relation?(relation, RELATION_VALUES)
49
+ return unless relation && plain_relation?(relation)
57
50
 
58
51
  clause = relation.where_clause - model_class.unscoped.where_clause
59
52
  predicate = Reader.new(model_class).call(clause.ast)
@@ -72,14 +65,28 @@ module PaperTrailDiff
72
65
  def self.for_relation(relation, model_class)
73
66
  return nothing if relation.null_relation?
74
67
 
75
- return unless plain_relation?(relation, [*RELATION_VALUES, *LOADING_VALUES])
68
+ return unless plain_relation?(relation)
76
69
 
77
70
  clause = relation.where_clause - model_class.unscoped.where_clause
71
+ check_recorded!(clause - model_class.default_scoped.where_clause, model_class)
78
72
  new(model_class, Reader.new(model_class).call(clause.ast))
79
73
  rescue Unreadable
80
74
  nil
81
75
  end
82
76
 
77
+ # A destroyed record's state holds a column `has_paper_trail skip:`
78
+ # leaves out of history only as its default. A default scope is read
79
+ # with it so; a condition the caller wrote is refused. PaperTrail lists
80
+ # the skipped columns by name.
81
+ #: (untyped, untyped) -> void
82
+ def self.check_recorded!(clause, model_class)
83
+ return unless model_class.respond_to?(:paper_trail_options)
84
+
85
+ Reader.new(model_class,
86
+ refused: model_class.paper_trail_options.fetch(:skip)).call(clause.ast)
87
+ end
88
+ private_class_method :check_recorded!
89
+
83
90
  # A relation `none` built, whose where clause is SQL text. A condition
84
91
  # that matches nothing reads no attribute, so it names no model.
85
92
  #: () -> ScopeCondition
@@ -137,14 +144,26 @@ module PaperTrailDiff
137
144
  private_class_method :scoped_relation
138
145
 
139
146
  # Some parts, such as the having clause `or` sets, may be present but
140
- # empty. `allowed` names the parts that may hold values.
141
- #: (untyped, Array[Symbol]) -> bool
142
- def self.plain_relation?(relation, allowed)
143
- extra = relation.values.except(*allowed).values
144
- extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
147
+ # empty.
148
+ #: (untyped) -> bool
149
+ def self.plain_relation?(relation)
150
+ relation.values.slice(*ROW_CHOOSING_VALUES).values.all?(&:blank?)
145
151
  end
146
152
  private_class_method :plain_relation?
147
153
 
154
+ # Join rows in primary key order, the order whose first target an
155
+ # unordered has_one through reads (see #first). The block names a row's
156
+ # model; rows with no key yet come last, as given. Saved rows' keys
157
+ # differ.
158
+ #: (Array[untyped]) { (untyped) -> untyped } -> Array[untyped]
159
+ def self.in_key_order(rows)
160
+ keyed = rows.map do |row|
161
+ [Array(yield(row).primary_key).map { |key| row.attributes.fetch(key) }, row]
162
+ end
163
+ saved, unsaved = keyed.partition { |keys, _row| keys.none?(&:nil?) }
164
+ (saved.sort_by(&:first) + unsaved).map(&:last)
165
+ end
166
+
148
167
  #: (untyped, Array[untyped], ?ScopeRanking?) -> void
149
168
  def initialize(model_class, predicate, ranking = nil)
150
169
  @model_class = model_class
@@ -174,6 +193,24 @@ module PaperTrailDiff
174
193
  rank(records.select { |record| matches?(record.attributes) })
175
194
  end
176
195
 
196
+ # The one record a has_one reads of several that meet its conditions:
197
+ # the first as ranked, or without an order of its own, the one with the
198
+ # lowest primary key. Active Record reads an unordered has_one with
199
+ # LIMIT 1, which SQLite, MySQL and SQL Server answer in key order for a
200
+ # clustered or indexed key; reading any other row would differ from the
201
+ # current record where nothing changed. PostgreSQL promises no order. A
202
+ # has_one through gives its records in the order of its join rows, whose
203
+ # first target is the one Active Record reads (see AssociationTraversal.join_order?).
204
+ #: (Array[untyped], ?in_order: bool) -> Array[untyped]
205
+ def first(records, in_order: false)
206
+ return records.first(1) if @ranking || in_order
207
+
208
+ keys = Array(@model_class.primary_key)
209
+ records.min_by(1) do |record|
210
+ keys.map { |key| record.attributes.fetch(key) }
211
+ end
212
+ end
213
+
177
214
  # Records that meet the conditions, as ranked; unchanged without a
178
215
  # ranking.
179
216
  #: (Array[untyped]) -> Array[untyped]
@@ -198,10 +235,6 @@ module PaperTrailDiff
198
235
  }.freeze
199
236
  private_constant :COMPARISONS
200
237
 
201
- # Comparisons that order values, which read them as ScopeRanking sorts.
202
- ORDERED = %i[gt gteq lt lteq].freeze
203
- private_constant :ORDERED
204
-
205
238
  private
206
239
 
207
240
  # @rbs @model_class: untyped
@@ -216,7 +249,7 @@ module PaperTrailDiff
216
249
  when :and then all(first.map { |part| evaluate(part, attributes) })
217
250
  when :or then any(first.map { |part| evaluate(part, attributes) })
218
251
  when :not then negate(evaluate(first, attributes))
219
- else COMPARISONS.fetch(operator).call(stored(operator, first, attributes), second)
252
+ else COMPARISONS.fetch(operator).call(stored(first, attributes), second)
220
253
  end
221
254
  end
222
255
 
@@ -241,15 +274,13 @@ module PaperTrailDiff
241
274
  !value unless value.nil?
242
275
  end
243
276
 
244
- # The form the database holds, as the scope's own values were cast. An
245
- # order reads the value the database sorts by instead: SQL Server holds a
246
- # time or date in a wrapper that only compares for equality.
247
- #: (Symbol, String, Hash[String, untyped]) -> untyped
248
- def stored(operator, name, attributes)
249
- value = attributes[name]
250
- return ScopeRanking.sort_value(@model_class, name, value) if ORDERED.include?(operator)
251
-
252
- @model_class.type_for_attribute(name).serialize(value)
277
+ # The value the database compares and sorts by, as the scope's own
278
+ # values were read (see ScopeRanking.sort_value): SQL Server holds a time
279
+ # or date in a wrapper that only compares for equality, and history may
280
+ # hold either as text.
281
+ #: (String, Hash[String, untyped]) -> untyped
282
+ def stored(name, attributes)
283
+ ScopeRanking.sort_value(@model_class, name, attributes[name])
253
284
  end
254
285
 
255
286
  # Builds each reflection's condition once per target class.
@@ -268,22 +299,15 @@ module PaperTrailDiff
268
299
  @conditions[key] = ScopeCondition.build(reflection, model_class, ranked: ranked)
269
300
  end
270
301
 
271
- # The records the reflection's scope admits, as it ranks them. Its
272
- # condition must exist.
273
- #: (untyped, Array[untyped], ?untyped, ranked: bool) -> Array[untyped]
274
- def select(reflection, records, model_class = reflection.klass, ranked:)
275
- condition = call(reflection, model_class, ranked: ranked) #: ScopeCondition
276
- condition.members(records)
277
- end
278
-
279
302
  # @rbs @conditions: Hash[Array[untyped], ScopeCondition?]
280
303
  end
281
304
 
282
305
  # Compiles a where clause into nested arrays of plain comparisons.
283
306
  class Reader
284
- #: (untyped) -> void
285
- def initialize(model_class)
307
+ #: (untyped, ?refused: Array[String]) -> void
308
+ def initialize(model_class, refused: [])
286
309
  @model_class = model_class
310
+ @refused = refused
287
311
  end
288
312
 
289
313
  #: (untyped) -> Array[untyped]
@@ -343,7 +367,7 @@ module PaperTrailDiff
343
367
  #: (Symbol, untyped, untyped) -> Array[untyped]
344
368
  def bound(operator, attribute, node)
345
369
  name = column(attribute, null_test: true)
346
- boolean = :boolean.equal?(@model_class.type_for_attribute(name).type)
370
+ boolean = :boolean.equal?(ExactColumnType.kind(@model_class, name))
347
371
  raise Unreadable unless ScopeRanking.orderable?(@model_class, name) && !boolean
348
372
 
349
373
  expected = value(node)
@@ -354,17 +378,29 @@ module PaperTrailDiff
354
378
 
355
379
  # A bound in the form the database holds, read back as the value the
356
380
  # database sorts by. Reading it back unwraps what an adapter wraps.
381
+ # SQLite keeps a time as text and compares a date with it as text, so
382
+ # a date there is no midnight, and is left unread.
357
383
  #: (String, untyped) -> untyped
358
384
  def sort_value(name, stored)
385
+ raise Unreadable if text_date?(name, stored)
386
+
359
387
  read = @model_class.type_for_attribute(name).deserialize(stored)
360
388
  ScopeRanking.sort_value(@model_class, name, read)
361
389
  end
362
390
 
391
+ #: (String, untyped) -> bool
392
+ def text_date?(name, stored)
393
+ stored.instance_of?(Date) && :datetime.equal?(ExactColumnType.kind(@model_class, name)) &&
394
+ @model_class.connection_db_config.adapter == 'sqlite3'
395
+ end
396
+
363
397
  # Whether a value is NULL compares alike on every type.
364
398
  #: (Symbol, untyped) -> Array[untyped]
365
399
  def binary(operator, node)
366
400
  expected = value(node.right)
367
- [operator, column(node.left, null_test: expected.nil?), expected]
401
+ return [operator, column(node.left, null_test: true)] if expected.nil?
402
+
403
+ compared(operator, node.left, expected) { |name| sort_value(name, expected) }
368
404
  end
369
405
 
370
406
  #: (untyped) -> Array[untyped]
@@ -372,51 +408,55 @@ module PaperTrailDiff
372
408
  list(node.type == :in ? :in : :not_in, node.attribute, node.casted_values)
373
409
  end
374
410
 
375
- # Active Record writes an empty NOT IN as a condition that is always
376
- # true, and a NOT IN list holding NULL matches no row.
411
+ # Active Record writes an empty IN as a condition that is always false
412
+ # and an empty NOT IN as one that is always true, for a NULL as for any
413
+ # value, so neither is unknown under NOT. A NOT IN list holding NULL
414
+ # matches no row.
377
415
  #: (Symbol, untyped, Array[untyped]) -> Array[untyped]
378
416
  def list(operator, attribute, expected)
379
- name = column(attribute)
380
- return [operator, name, expected] if operator == :in
381
- return [:and, []] if expected.empty?
417
+ comparison = compared(operator, attribute, expected) do |name|
418
+ expected.map { |item| sort_value(name, item) }
419
+ end
420
+ return [operator == :in ? :or : :and, []] if expected.empty?
421
+ return comparison if operator == :in
422
+
423
+ expected.include?(nil) ? [:or, []] : comparison
424
+ end
382
425
 
383
- expected.include?(nil) ? [:or, []] : [operator, name, expected]
426
+ # A column that sorts in Ruby as in SQL (ScopeRanking) is compared as
427
+ # the value it sorts by, which the block reads from the expected one: a
428
+ # date, or a time history holds as it was stored, can be held as text.
429
+ #: (Symbol, untyped, untyped) { (String) -> untyped } -> Array[untyped]
430
+ def compared(operator, attribute, expected)
431
+ name = ScopeRanking.own_column(attribute, @model_class)
432
+ raise Unreadable if @refused.include?(name)
433
+
434
+ if ScopeRanking.orderable?(@model_class, name)
435
+ orderable = name #: String
436
+ [operator, orderable, yield(orderable)]
437
+ else
438
+ [operator, column(attribute), expected]
439
+ end
384
440
  end
385
441
 
386
442
  # Ruby comparison stands in for SQL only on the record's own column of
387
- # a type both compare alike. Whether a value is NULL, any column's
388
- # type compares alike.
443
+ # a type both compare alike (ExactColumnType). Whether a value is NULL,
444
+ # any column's type compares alike.
389
445
  #: (untyped, ?null_test: bool) -> String
390
446
  def column(attribute, null_test: false)
391
447
  # Nil for anything but a column of the model's own table, which finds
392
448
  # no column below.
393
449
  name = ScopeRanking.own_column(attribute, @model_class) #: String
394
- column = @model_class.columns_hash[name]
395
- raise Unreadable unless column && (null_test || comparable?(name, column))
450
+ exists = @model_class.columns_hash.key?(name)
451
+ raise Unreadable unless exists && (null_test || comparable?(name))
452
+ raise Unreadable if @refused.include?(name)
396
453
 
397
454
  name
398
455
  end
399
456
 
400
- #: (String, untyped) -> bool
401
- def comparable?(name, column)
402
- kinds = value_type(@model_class.type_for_attribute(name)).class.ancestors.map(&:name)
403
- return false unless VALUE_TYPES.intersect?(kinds)
404
-
405
- !kinds.include?(TEXT_TYPE) || exact_text?(column)
406
- end
407
-
408
- # PostgreSQL's citext is text that compares without regard to case.
409
- #: (untyped) -> bool
410
- def exact_text?(column)
411
- EXACT_TEXT_ADAPTERS.include?(@model_class.connection_db_config.adapter) &&
412
- column.collation.nil? && !column.sql_type.casecmp?('citext')
413
- end
414
-
415
- # An enum compares the values it stores, which its subtype describes. A
416
- # wrapper such as a serialized or encrypted type is none of these.
417
- #: (untyped) -> untyped
418
- def value_type(type)
419
- ENUM_TYPE.eql?(type.class.name) ? type.subtype : type
457
+ #: (String) -> bool
458
+ def comparable?(name)
459
+ COMPARABLE_KINDS.include?(ExactColumnType.kind(@model_class, name))
420
460
  end
421
461
 
422
462
  # A list that is not plain values, such as a subquery, is unreadable.
@@ -5,23 +5,15 @@ module PaperTrailDiff
5
5
  # The order, offset and limit by which a scope picks its members from the
6
6
  # records that meet its conditions, as the database would rank them. It is
7
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.
8
+ # compares it; otherwise build returns nil and the scope is unreadable
9
+ # (UnreadablePaths).
10
10
  class ScopeRanking
11
11
  DIRECTIONS = { 'Arel::Nodes::Ascending' => false, 'Arel::Nodes::Descending' => true }.freeze
12
12
  ATTRIBUTE = 'Arel::Attributes::Attribute'
13
- ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
14
- # Rails wraps a time-zone-aware attribute's type, by default every
15
- # datetime's, in this delegator; the time it stores is the wrapped type's.
16
- TIME_ZONE_TYPE = 'ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter'
17
- # Integers, booleans and dates sort alike everywhere. Strings follow a
18
- # collation, so they are not read.
19
- ORDER_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
20
- ActiveModel::Type::Date].freeze
21
- # Times sort alike only at the precision both the column and history
22
- # keep. A time of day is not read: in memory it keeps the date it was
23
- # given, which the database drops.
24
- DATETIME_TYPE = 'ActiveModel::Type::DateTime'
13
+ # Column kinds (ExactColumnType) that sort alike everywhere. Text follows
14
+ # a collation, so it is not read. Times sort alike only at the precision
15
+ # both the column and history keep.
16
+ ORDER_KINDS = %i[integer boolean date].freeze
25
17
  # Where each adapter sorts NULL in an ascending order by default; a
26
18
  # descending order reverses it. Another adapter's ranking is not read.
27
19
  NULLS_LAST = { 'postgresql' => true, 'sqlite3' => false, 'mysql2' => false,
@@ -104,12 +96,8 @@ module PaperTrailDiff
104
96
 
105
97
  #: (untyped, String?) -> bool
106
98
  def self.orderable?(model_class, name)
107
- return false unless model_class.columns_hash.key?(name)
108
-
109
- type = stored_type(model_class.type_for_attribute(name))
110
- kinds = type.class.ancestors.map(&:name)
111
- ORDER_TYPES.intersect?(kinds) ||
112
- (kinds.include?(DATETIME_TYPE) && exact_time?(model_class, type))
99
+ kind = ExactColumnType.kind(model_class, name)
100
+ ORDER_KINDS.include?(kind) || (kind == :datetime && exact_time?(model_class, name))
113
101
  end
114
102
 
115
103
  # The value the database sorts by, as the column's type casts it. An enum
@@ -119,23 +107,17 @@ module PaperTrailDiff
119
107
  def self.sort_value(model_class, name, value)
120
108
  type = model_class.type_for_attribute(name)
121
109
  cast = type.cast(value)
122
- ENUM_TYPE.eql?(type.class.name) ? type.serialize(cast) : cast
123
- end
124
-
125
- # The type of the value a column stores, under an enum or time zone wrapper.
126
- #: (untyped) -> untyped
127
- def self.stored_type(type)
128
- type = type.subtype if ENUM_TYPE.eql?(type.class.name)
129
- TIME_ZONE_TYPE.eql?(type.class.name) ? type.__getobj__ : type
110
+ Support::ENUM_TYPE.eql?(type.class.name) ? type.serialize(cast) : cast
130
111
  end
131
- private_class_method :stored_type
132
112
 
133
113
  # Active Record truncates a time to its column's precision before writing
134
114
  # it, so history holds the stored value when it keeps that many digits.
135
115
  # Times the type stores in UTC sort as the instants they name; local
136
- # times repeat an hour when clocks go back.
137
- #: (untyped, untyped) -> bool
138
- def self.exact_time?(model_class, type)
116
+ # times repeat an hour when clocks go back. A time-zone-aware type passes
117
+ # both questions to the time it wraps.
118
+ #: (untyped, String?) -> bool
119
+ def self.exact_time?(model_class, name)
120
+ type = model_class.type_for_attribute(name)
139
121
  precision = type.precision
140
122
  digits = StoredTimePrecision.digits(model_class)
141
123
  !precision.nil? && (digits.nil? || digits >= precision) && type.default_timezone == :utc
@@ -2,13 +2,13 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # What the relation form of `analyze_many` returns: the analyses, plus the
6
- # roots the relation could not reach.
5
+ # What `analyze_scope` and `report` return: the analyses, plus the roots the
6
+ # relation could not reach.
7
7
  #
8
8
  # `to_ary` is defined so the pair destructures, which keeps the common case
9
- # reading like the plain Hash the record form returns:
9
+ # reading like the plain Hash `analyze_many` returns:
10
10
  #
11
- # analyses, unreachable = PaperTrailDiff.analyze_many(scope: ..., limit: 500)
11
+ # analyses, unreachable = PaperTrailDiff.analyze_scope(Article.all, limit: 500)
12
12
  #
13
13
  # It deliberately does not pretend to be a Hash beyond that. Somebody
14
14
  # iterating this object should have to decide which half they meant.
@@ -23,9 +23,13 @@ module PaperTrailDiff
23
23
  # Requested missing-root analyses, kept separate because live SQL conditions
24
24
  # cannot prove which deleted rows matched. nil means no destroy history.
25
25
  attr_reader :deleted #: Hash[Array[String], Analysis?]
26
+ # How many existing records the relation selects before its own `limit`
27
+ # and `offset`, for a pager's "page 2 of 6". Without either, it is
28
+ # `roots.length`. Deleted records are not counted; they are not paged.
29
+ attr_reader :total #: Integer
26
30
 
27
- #: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]], ?roots: Array[untyped], ?deleted: Hash[Array[String], Analysis?]) -> void
28
- def initialize(analyses:, unreachable:, roots: [], deleted: {})
31
+ #: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]], ?roots: Array[untyped], ?deleted: Hash[Array[String], Analysis?], ?total: Integer?) -> void
32
+ def initialize(analyses:, unreachable:, roots: [], deleted: {}, total: nil)
29
33
  @analyses = analyses
30
34
  @unreachable = Support.immutable_copy(unreachable)
31
35
  # Not deep-copied: these are the caller's own model instances, and
@@ -33,6 +37,7 @@ module PaperTrailDiff
33
37
  # fail. The array itself is frozen so the collection cannot be reshaped.
34
38
  @roots = roots.dup.freeze
35
39
  @deleted = Support.immutable_copy(deleted)
40
+ @total = total || @roots.length
36
41
  freeze
37
42
  end
38
43
 
@@ -4,21 +4,18 @@
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?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
7
+ #: (untyped, limit: Integer?, within: untyped, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_traversal: AssociationTraversal?, ?version_scope: untyped) -> void
8
8
  def initialize( # rubocop:disable Metrics/ParameterLists
9
- scope, limit:, within:, historical_filter:, max_filter_versions:, include_deleted:,
10
- analyzer:, deleted_analyzer:, activity_tree: nil, version_scope: nil, traversal: nil
9
+ scope, limit:, within:, include_deleted:,
10
+ analyzer:, deleted_analyzer:, activity_traversal: nil, version_scope: nil
11
11
  )
12
12
  raise ConfigurationError, 'limit: is required when selecting roots by scope' if limit.nil?
13
- unless [true, false].include?(include_deleted)
14
- raise ConfigurationError, 'include_deleted: must be true or false'
15
- end
13
+
14
+ Support.boolean!(:include_deleted, include_deleted)
16
15
 
17
16
  @selection = ScopedRootSelection.new(
18
- scope, limit: limit, time_range: within.nil? ? nil : TimeRange.new(within),
19
- historical_filter: historical_filter, max_filter_versions: max_filter_versions,
20
- activity_tree: activity_tree, version_scope: version_scope,
21
- traversal: traversal
17
+ scope, limit: limit, time_range: time_range(within, scope),
18
+ activity_traversal: activity_traversal, version_scope: version_scope
22
19
  )
23
20
  @deleted_filter = deleted_filter(scope, include_deleted)
24
21
  @include_deleted = include_deleted
@@ -42,6 +39,15 @@ module PaperTrailDiff
42
39
 
43
40
  private
44
41
 
42
+ # The window as the relation's version table keeps times. Anything but a
43
+ # relation or a model is left for the selection to refuse.
44
+ #: (untyped, untyped) -> TimeRange?
45
+ def time_range(within, scope)
46
+ return if within.nil?
47
+
48
+ TimeRange.for(within, scope.respond_to?(:all) ? [scope.all.model] : [])
49
+ end
50
+
45
51
  # Without the option, the deleted roots are still tested when the
46
52
  # relation can be read, so that another selection's are not listed.
47
53
  #: (untyped, bool) -> DeletedRootFilter?
@@ -54,7 +60,7 @@ module PaperTrailDiff
54
60
  #: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
55
61
  def analysis(selection, unreachable, deleted)
56
62
  ScopedAnalysis.new(analyses: @analyzer.call(selection.records), roots: selection.records,
57
- unreachable: unreachable, deleted: deleted)
63
+ unreachable: unreachable, deleted: deleted, total: selection.total)
58
64
  end
59
65
 
60
66
  # @rbs @selection: ScopedRootSelection