paper_trail_diff 0.17.0 → 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 +663 -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 +35 -28
  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 +235 -179
  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 +28 -4
  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 +21 -19
  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 +149 -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 +16 -2
  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
@@ -53,15 +53,10 @@ module PaperTrailDiff
53
53
  end
54
54
  private_class_method :through_models
55
55
 
56
- #: (traversal: AssociationTraversal, ?allow_approximate: bool) -> void
57
- def initialize(traversal:, allow_approximate: false)
58
- unless [true, false].include?(allow_approximate)
59
- raise ConfigurationError, 'allow_approximate: must be true or false'
60
- end
61
-
56
+ #: (traversal: AssociationTraversal) -> void
57
+ def initialize(traversal:)
62
58
  @tree = traversal.tree
63
59
  @traversal = traversal
64
- @allow_approximate = allow_approximate
65
60
  @refusals = {} #: Hash[Array[untyped], Array[Refusal]]
66
61
  end
67
62
 
@@ -85,7 +80,6 @@ module PaperTrailDiff
85
80
 
86
81
  # @rbs @tree: AssociationTree
87
82
  # @rbs @traversal: AssociationTraversal
88
- # @rbs @allow_approximate: bool
89
83
  # @rbs @refusals: Hash[Array[untyped], Array[Refusal]]
90
84
 
91
85
  #: (untyped, bool) -> Array[Refusal]
@@ -96,7 +90,7 @@ module PaperTrailDiff
96
90
  return found << unresolved if unresolved
97
91
  return found unless historical
98
92
 
99
- found.concat(unversioned_refusals(model_class), approximate_refusals(model_class))
93
+ found.concat(unversioned_refusals(model_class), unreadable_refusals(model_class))
100
94
  end
101
95
 
102
96
  #: (untyped) -> Refusal?
@@ -108,22 +102,16 @@ module PaperTrailDiff
108
102
  Refusal.new(e.class, code, e.message)
109
103
  end
110
104
 
111
- # A path prepared history cannot read is read with PT-AT, which rebuilds
112
- # an association from its current members, swapping in older versions of
113
- # them. A record that entered the association since, such as one moved
114
- # into a scope or restored from a soft delete, then reads as a member it
115
- # was not, and one that left reads as missing. Only a caller who accepts
116
- # that may read such a path.
105
+ # History tells who was in an association at a past point by testing each
106
+ # record's stored values against its scope, so it reads only a scope made
107
+ # of plain conditions on the target's own columns.
117
108
  #: (untyped) -> Array[Refusal]
118
- def approximate_refusals(model_class)
119
- return [] if @allow_approximate
120
-
121
- ApproximatePaths.call(@traversal, model_class).map do |path, reason|
122
- message = "association #{path} cannot be read exactly from history (#{reason}): " \
123
- 'PT-AT rebuilds it from its current members, so a record that entered or ' \
124
- 'left it since is reported wrongly; remove this path, make its scope plain ' \
125
- 'conditions on the target\'s own columns, or pass allow_approximate: true'
126
- Refusal.new(UnsupportedAssociationError, :approximate_association, message, path)
109
+ def unreadable_refusals(model_class)
110
+ UnreadablePaths.call(@traversal, model_class).map do |path, reason|
111
+ message = "association #{path} cannot be read from history (#{reason}): who was in " \
112
+ 'it at a past point cannot be told. Remove this path, or make its scope ' \
113
+ 'plain conditions on the target\'s own columns'
114
+ Refusal.new(UnsupportedAssociationError, :unreadable_association, message, path)
127
115
  end
128
116
  end
129
117
 
@@ -2,14 +2,13 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # The requested paths prepared history cannot read exactly, each with why.
6
- # PT-AT reads such a path instead, one record at a time, when the caller
7
- # passes `allow_approximate: true`.
8
- module ApproximatePaths
5
+ # The requested paths history cannot read, each with why: who was in one
6
+ # at a past point cannot be told, so a request that reads history refuses it.
7
+ module UnreadablePaths
9
8
  #: (AssociationTraversal, untyped) -> Array[[String, String]]
10
9
  def self.call(traversal, model)
11
10
  traversal.selected_reflections(model).filter_map do |path, reflection|
12
- reason = fallback_reason(reflection, ranked: true)
11
+ reason = path_reason(reflection)
13
12
  [path, reason] if reason
14
13
  end
15
14
  end
@@ -17,14 +16,14 @@ module PaperTrailDiff
17
16
  # A has_many through reads its parts' conditions only, at any depth. A
18
17
  # has_one through over a ranked part is refused whole, so its parts, too,
19
18
  # are checked for conditions alone.
20
- #: (untyped, ranked: bool) -> String?
21
- def self.fallback_reason(reflection, ranked:)
22
- reason_for(reflection, ranked) ||
19
+ #: (untyped) -> String?
20
+ def self.path_reason(reflection)
21
+ reason_for(reflection, true) ||
23
22
  AssociationTraversal.through_parts(reflection).filter_map do |part|
24
23
  reason_for(part, false)
25
24
  end.first
26
25
  end
27
- private_class_method :fallback_reason
26
+ private_class_method :path_reason
28
27
 
29
28
  # A scope prepared history can read as conditions on stored attributes
30
29
  # is batched like any other path. A polymorphic target's class, and so
@@ -55,13 +55,14 @@ module PaperTrailDiff
55
55
 
56
56
  # Elements of `left` with no counterpart left in `right`, matching by value
57
57
  # and respecting duplicates, so ["a", "a"] -> ["a"] reports one removal
58
- # rather than none.
58
+ # rather than none. Each element is counted rather than searched for, so
59
+ # the work grows with the arrays' length, not its square.
59
60
  #: (Array[untyped], Array[untyped]) -> Array[untyped]
60
61
  def self.surplus(left, right)
61
- pool = right.map { |item| NestedComparator.comparable(item) }
62
+ pool = right.map { |item| NestedComparator.countable(item) }.tally
62
63
  left.reject do |item|
63
- index = pool.index(NestedComparator.comparable(item))
64
- index ? pool.delete_at(index) || true : false
64
+ key = NestedComparator.countable(item)
65
+ pool.fetch(key, 0).positive? && (pool[key] -= 1)
65
66
  end
66
67
  end
67
68
 
@@ -72,10 +73,11 @@ module PaperTrailDiff
72
73
  added.empty? && removed.empty?
73
74
  end
74
75
 
75
- # The same elements in the same order, with keys read as strings.
76
+ # The same elements in the same order, with keys read as strings and
77
+ # every NaN alike.
76
78
  #: () -> bool
77
79
  def empty?
78
- NestedComparator.comparable(from) == NestedComparator.comparable(to)
80
+ NestedComparator.countable(from) == NestedComparator.countable(to)
79
81
  end
80
82
 
81
83
  #: () -> Hash[Symbol, untyped]
@@ -2,5 +2,5 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- VERSION = '0.17.0'
5
+ VERSION = '0.18.0'
6
6
  end
@@ -29,12 +29,27 @@ module PaperTrailDiff
29
29
  Support.with_connection(@version_class) { |connection| condition_sql(connection) }
30
30
  end
31
31
 
32
+ # A version saved before the start names the state there unless a later
33
+ # one saved before the start replaced it. PT-AT stores the keys a version
34
+ # saved, and a start inside a transaction reads each record as it stood
35
+ # before the transaction, so a later version that a transaction across
36
+ # the start saved before it replaced nothing yet. Without the version
37
+ # before it, a record that this transaction moved away is not found, nor
38
+ # is the transaction (see CrossingTransactions).
39
+ #
40
+ # The transaction crosses the start by a version of any record, not only
41
+ # of this one: one that moved a comment away before the start and saved
42
+ # only the comment's reply after it is found by the reply, which hangs
43
+ # under the comment as it stood before. A transaction that went on to
44
+ # save nothing in the tree brings a candidate the history loads and no
45
+ # snapshot holds (see PreparedActivityIndex#eligible_version?).
32
46
  #: (untyped) -> String
33
47
  def condition_sql(connection) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
34
48
  outer = connection.quote_table_name(@version_class.table_name)
35
49
  later = connection.quote_table_name('paper_trail_diff_later_versions')
50
+ crossing = connection.quote_table_name('paper_trail_diff_crossing_versions')
36
51
  start_at = quote_time(connection, @start_at)
37
- columns = quoted_columns(connection, outer, later)
52
+ columns = quoted_columns(connection, outer, later, crossing)
38
53
  compact_sql(<<~SQL)
39
54
  (
40
55
  #{activity_condition(columns, start_at, connection)}
@@ -48,14 +63,20 @@ module PaperTrailDiff
48
63
  AND #{columns.fetch(:later_item_id)} = #{columns.fetch(:outer_item_id)}
49
64
  AND #{columns.fetch(:later_created_at)} < #{start_at}
50
65
  AND #{columns.fetch(:later_created_at)} > #{columns.fetch(:outer_created_at)}
66
+ AND NOT EXISTS (
67
+ SELECT 1
68
+ FROM #{outer} #{crossing}
69
+ WHERE #{columns.fetch(:crossing_transaction_id)} = #{columns.fetch(:later_transaction_id)}
70
+ AND #{columns.fetch(:crossing_created_at)} >= #{start_at}
71
+ )
51
72
  )
52
73
  )
53
74
  )
54
75
  SQL
55
76
  end
56
77
 
57
- #: (untyped, String, String) -> Hash[Symbol, String]
58
- def quoted_columns(connection, outer, later)
78
+ #: (untyped, String, String, String) -> Hash[Symbol, String]
79
+ def quoted_columns(connection, outer, later, crossing)
59
80
  {
60
81
  outer_created_at: column(connection, outer, 'created_at'),
61
82
  outer_event: column(connection, outer, 'event'),
@@ -63,7 +84,10 @@ module PaperTrailDiff
63
84
  outer_item_id: column(connection, outer, 'item_id'),
64
85
  later_created_at: column(connection, later, 'created_at'),
65
86
  later_item_type: column(connection, later, 'item_type'),
66
- later_item_id: column(connection, later, 'item_id')
87
+ later_item_id: column(connection, later, 'item_id'),
88
+ later_transaction_id: column(connection, later, 'transaction_id'),
89
+ crossing_created_at: column(connection, crossing, 'created_at'),
90
+ crossing_transaction_id: column(connection, crossing, 'transaction_id')
67
91
  }
68
92
  end
69
93
 
@@ -29,34 +29,6 @@ module PaperTrailDiff
29
29
  Support.compare_versions(candidate, boundary).positive?
30
30
  end
31
31
 
32
- # A range starting at a version starts before that version's transaction,
33
- # as PT-AT reads associations there. A version saved earlier in the same
34
- # transaction, such as the child update behind a `touch: true` parent
35
- # version, can be recorded before the start, so the start moves back to
36
- # the earliest version of each root's first transaction in the range.
37
- # History loaded from the start alone would read that child after its
38
- # change. The transactions go 500 to a statement.
39
- #: (Array[untyped], untyped) -> untyped
40
- def self.transaction_start(root_versions, start_at)
41
- earliest = opening_transactions(root_versions, start_at)
42
- .each_slice(Support::IDS_PER_STATEMENT).filter_map do |slice|
43
- root_versions.first.class.where(transaction_id: slice).minimum(:created_at)
44
- end.min
45
- earliest && earliest < start_at ? earliest : start_at
46
- end
47
-
48
- # The transaction of each root's first version at or after the start.
49
- #: (Array[untyped], untyped) -> Array[untyped]
50
- def self.opening_transactions(root_versions, start_at)
51
- return [] unless start_at
52
-
53
- root_versions.reject { |version| version.created_at < start_at }
54
- .sort_by { |version| Support.chronological_version_key(version) }
55
- .uniq { |version| Endpoint.identity(version) }
56
- .filter_map { |version| transaction_id(version) }
57
- end
58
- private_class_method :opening_transactions
59
-
60
32
  # A custom version class need not carry the column, and PaperTrail leaves
61
33
  # it nil outside a transaction. Both read as "no transaction here", which
62
34
  # groups with nothing.
@@ -82,7 +54,6 @@ module PaperTrailDiff
82
54
  candidate.class.respond_to?(:table_name)
83
55
  end
84
56
  end
85
- private_class_method :version_record?
86
57
 
87
58
  # The same row of the same version table. A record or instant is never a
88
59
  # version.
@@ -27,6 +27,21 @@ module PaperTrailDiff
27
27
  for_model(model_class).where(item_id: ids)
28
28
  end
29
29
 
30
+ # The versions of the version's item saved after it, ids breaking a tie.
31
+ #: (untyped, untyped) -> untyped
32
+ def self.after(model_class, version)
33
+ saved = version.class.arel_table[:created_at]
34
+ at = version.created_at
35
+ later = saved.gt(at).or(saved.eq(at).and(later_id(version)))
36
+ for_items(model_class, version.item_id).where(later)
37
+ end
38
+
39
+ #: (untyped) -> untyped
40
+ def self.later_id(version)
41
+ version.class.arel_table[version.class.primary_key].gt(version.id)
42
+ end
43
+ private_class_method :later_id
44
+
30
45
  # Keeps each item's earliest version among those the block also accepts:
31
46
  # no other version of the same item that the block accepts is earlier. A
32
47
  # correlated NOT EXISTS stays portable where window functions are not.
@@ -40,9 +55,33 @@ module PaperTrailDiff
40
55
  #: (untyped) { (untyped) -> untyped } -> untyped
41
56
  def self.exists(table)
42
57
  other = other_versions(table)
43
- Support.arel::SelectManager.new.from(other).project('1').where(yield(other)).exists
58
+ any(other, yield(other))
59
+ end
60
+
61
+ # Whether the item's versions say it was created after `time`: a create
62
+ # saved after it that no version of the item precedes. An item with an
63
+ # earlier version was there before, whatever created it again, and one
64
+ # with no create may have been.
65
+ #: (untyped, untyped, untyped, untyped) -> untyped
66
+ def self.created_after(table, item_type, item_id, time)
67
+ created = created_versions(table)
68
+ item = created[:item_type].eq(item_type).and(created[:item_id].eq(item_id))
69
+ any(created, item.and(first_create_after(table, created, time)))
44
70
  end
45
71
 
72
+ #: (untyped, untyped, untyped) -> untyped
73
+ def self.first_create_after(table, created, time)
74
+ created[:event].eq('create').and(created[:created_at].gt(time))
75
+ .and(exists(table) { |other| earlier_version(created, other) }.not)
76
+ end
77
+ private_class_method :first_create_after
78
+
79
+ #: (untyped, untyped) -> untyped
80
+ def self.any(source, condition)
81
+ Support.arel::SelectManager.new.from(source).project('1').where(condition).exists
82
+ end
83
+ private_class_method :any
84
+
46
85
  #: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
47
86
  def self.earlier_version(table, other)
48
87
  same_item = other[:item_type].eq(table[:item_type])
@@ -61,5 +100,14 @@ module PaperTrailDiff
61
100
  table.alias('paper_trail_diff_other_versions')
62
101
  end
63
102
  private_class_method :other_versions
103
+
104
+ # The version table under a name of its own for `created_after`, beside
105
+ # `other_versions`. As for that, no spec can tell its mutations apart.
106
+ # mutant:disable
107
+ #: (untyped) -> untyped
108
+ def self.created_versions(table)
109
+ table.alias('paper_trail_diff_created_versions')
110
+ end
111
+ private_class_method :created_versions
64
112
  end
65
113
  end
@@ -7,17 +7,86 @@ module PaperTrailDiff
7
7
  # caller, because the one that reveals the last selected mutation is drawn
8
8
  # from them.
9
9
  class VersionScopeFilter
10
- # A filter is a callable that narrows the version relation.
10
+ # The filter, checked once where it is given: a callable that takes the
11
+ # version relation, and that wherever it is called returns it narrowed,
12
+ # or an array of its versions. A relation on another table would be read
13
+ # for its ids all the same, and choose the versions that happen to share
14
+ # them.
11
15
  #: (untyped) -> untyped
12
- def self.validated(scope)
13
- return scope if scope.nil? || scope.respond_to?(:call)
16
+ def self.checked(scope)
17
+ return if scope.nil?
18
+ unless scope.respond_to?(:call)
19
+ raise ConfigurationError,
20
+ 'version_scope: must respond to call'
21
+ end
22
+ unless takes_relation?(scope)
23
+ raise ConfigurationError,
24
+ 'version_scope: must take the version relation as its one argument'
25
+ end
14
26
 
15
- raise ConfigurationError, 'version_scope: must respond to call'
27
+ ->(relation) { narrowed(scope.call(relation), relation) }
16
28
  end
17
29
 
30
+ # A proc that is not a lambda takes any number of arguments.
31
+ #: (untyped) -> bool
32
+ def self.takes_relation?(scope)
33
+ return true if scope.is_a?(Proc) && !scope.lambda?
34
+
35
+ arity = (scope.respond_to?(:arity) ? scope : scope.public_method(:call)).arity
36
+ arity.negative? ? arity >= -2 : arity == 1
37
+ end
38
+ private_class_method :takes_relation?
39
+
40
+ #: (untyped, untyped) -> untyped
41
+ def self.narrowed(result, relation)
42
+ return result if versions?(result)
43
+ unless result.respond_to?(:table_name)
44
+ raise ConfigurationError, 'version_scope: must return the relation it is given, ' \
45
+ 'narrowed, or an array of its versions; it returned ' \
46
+ "#{result.class}"
47
+ end
48
+
49
+ given = relation.table_name
50
+ returned = result.table_name
51
+ return result if returned == given
52
+
53
+ raise ConfigurationError, 'version_scope: must return the relation it is given, ' \
54
+ "narrowed; it returned one on #{returned}, not #{given}"
55
+ end
56
+ private_class_method :narrowed
57
+
58
+ # The versions of `relation` that activity on associations reports under
59
+ # the filter (see ActivityScopeFilter): those it keeps, and those of a
60
+ # transaction it keeps a version of, of any record in their table. A
61
+ # table without transactions keeps each version alone.
62
+ #: (untyped, untyped) -> untyped
63
+ def self.whole_transactions(scope, relation)
64
+ return scope.call(relation) unless relation.column_names.include?('transaction_id')
65
+
66
+ saved = relation.klass.where(transaction_id: relation.select(:transaction_id))
67
+ kept = values(scope.call(saved), :transaction_id)
68
+ relation.where(transaction_id: kept).or(relation.where(id: values(scope.call(relation), :id)))
69
+ end
70
+
71
+ # A column of what the filter returned, read in the database where it
72
+ # returned a relation.
73
+ #: (untyped, Symbol) -> untyped
74
+ def self.values(result, column)
75
+ return result.map { |version| version[column] } if versions?(result)
76
+
77
+ result.unscope(:order).select(column)
78
+ end
79
+ private_class_method :values
80
+
81
+ #: (untyped) -> bool
82
+ def self.versions?(result)
83
+ result.instance_of?(Array) && result.all? { |version| Endpoint.version?(version) }
84
+ end
85
+ private_class_method :versions?
86
+
18
87
  #: (untyped) -> void
19
88
  def initialize(scope)
20
- @scope = self.class.validated(scope)
89
+ @scope = scope
21
90
  end
22
91
 
23
92
  #: (untyped, Array[untyped]) -> Array[untyped]
@@ -3,14 +3,13 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Checks the recorded sequence itself, before any question of association
6
- # setup: whether the versions can be ordered at all, and whether timestamps
7
- # they share hide changes from a path PT-AT reads.
6
+ # setup: whether the versions can be ordered at all, and whether they are
7
+ # dated in the order they were saved.
8
8
  class VersionSequenceDiagnostics
9
- #: (untyped, untyped, ?fallback_selected: bool) -> void
10
- def initialize(from_version, to_version, fallback_selected: false)
9
+ #: (untyped, untyped) -> void
10
+ def initialize(from_version, to_version)
11
11
  @from_version = from_version
12
12
  @to_version = to_version
13
- @fallback_selected = fallback_selected
14
13
  end
15
14
 
16
15
  # The read runs in a savepoint, so that a query that fails here leaves a
@@ -22,7 +21,6 @@ module PaperTrailDiff
22
21
  issues = [] #: Array[DiagnosticIssue?]
23
22
  issues << unorderable(versions)
24
23
  issues << inverted(versions)
25
- issues << tied_timestamps(versions) if @fallback_selected
26
24
  issues.compact
27
25
  rescue StandardError
28
26
  []
@@ -32,7 +30,6 @@ module PaperTrailDiff
32
30
 
33
31
  # @rbs @from_version: untyped
34
32
  # @rbs @to_version: untyped
35
- # @rbs @fallback_selected: bool
36
33
 
37
34
  # Ordering falls back to the id when timestamps tie, which only recovers the
38
35
  # real sequence for ids that increase with insertion. Reported before a run
@@ -81,30 +78,6 @@ module PaperTrailDiff
81
78
  'false and correct the stored created_at'
82
79
  end
83
80
 
84
- # Loaded history orders versions that share a timestamp by id, but PT-AT
85
- # places association changes by timestamp alone, so a path it reads loses
86
- # any change between such a pair. Unlike an unorderable sequence this is
87
- # not always wrong: if nothing that path reaches changed between them the
88
- # result is correct, and the gem cannot tell which it is, because not
89
- # seeing the change is the symptom. So it warns.
90
- #: (Array[untyped]) -> DiagnosticIssue?
91
- def tied_timestamps(versions)
92
- pair = Support.tied_timestamp_pair(versions)
93
- return unless pair
94
-
95
- left, right = pair
96
- DiagnosticIssue.new(
97
- severity: :warning,
98
- code: :tied_version_timestamps,
99
- message: "versions #{left.id.inspect} and #{right.id.inspect} share the timestamp " \
100
- "#{left.created_at.inspect}, and an association requested here is read with " \
101
- 'PT-AT, which places association changes by timestamp alone, so a change ' \
102
- 'between them can be missed; record versions at sub-second precision to ' \
103
- 'separate them',
104
- version_id: left.id
105
- )
106
- end
107
-
108
81
  #: () -> Array[untyped]
109
82
  def ordered_range_versions
110
83
  range = time_range
@@ -54,10 +54,17 @@ module PaperTrailDiff
54
54
  associations.joins(rows.join(table).on(table[:id].eq(rows[:version_id])).join_sources)
55
55
  end
56
56
 
57
+ # Without PT-AT loaded there are no version associations to name, and
58
+ # TraversalPreparer refuses history for that reason first, so only the
59
+ # versions' table is compared: a live comparison or association_paths
60
+ # still works.
57
61
  #: (untyped) -> String
58
62
  def self.tables(model)
59
63
  history = model.paper_trail
60
- "#{history.version_class.table_name} and #{history.version_association_class.table_name}"
64
+ versions = history.version_class.table_name
65
+ return versions unless history.respond_to?(:version_association_class)
66
+
67
+ "#{versions} and #{history.version_association_class.table_name}"
61
68
  end
62
69
  private_class_method :tables
63
70
  end