paper_trail_diff 0.15.0 → 0.17.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 (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +724 -1
  3. data/README.md +43 -8
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +89 -32
  6. data/docs/reference.md +427 -96
  7. data/docs/testing.md +260 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +39 -6
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +8 -7
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +31 -36
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
  73. data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +99 -0
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +92 -32
  84. data/lib/paper_trail_diff/scope_ranking.rb +27 -34
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +40 -22
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +9 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +235 -75
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +41 -23
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +32 -44
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +31 -7
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -2,24 +2,27 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Validates and applies a finite wall-clock range without loading model state.
5
+ # Validates and applies a wall-clock range without loading model state.
6
6
  #
7
7
  # A Date is a whole day and a String a local time, both in Time.zone, as
8
8
  # Rails reads them, or in UTC without one: never the server's own zone. An
9
- # inclusive Date end runs through that day.
9
+ # inclusive Date end runs through that day. An endless range has no end:
10
+ # it runs through every version saved since it began, whatever the clock
11
+ # that dated them read, as a report through the current state does.
10
12
  class TimeRange
11
13
  attr_reader :begin_time #: Time
12
- attr_reader :end_time #: Time
14
+ attr_reader :end_time #: Time?
13
15
 
14
16
  #: (untyped) -> void
15
17
  def initialize(value)
16
- unless value.is_a?(Range) && value.begin && value.end
17
- raise InvalidTimeRangeError, '`within` must be a finite Range'
18
+ unless value.is_a?(Range) && value.begin
19
+ raise InvalidTimeRangeError, '`within` must be a Range with a beginning'
18
20
  end
19
21
 
20
22
  @begin_time = coerce_time(value.begin, boundary: :begin)
21
- @exclude_end = value.exclude_end? || calendar_date?(value.end)
22
- @end_time = coerce_time(end_value(value), boundary: :end)
23
+ last = value.end
24
+ @exclude_end = !last.nil? && (value.exclude_end? || calendar_date?(last))
25
+ @end_time = (coerce_time(end_value(value), boundary: :end) unless last.nil?)
23
26
  validate_order!
24
27
  freeze
25
28
  end
@@ -34,17 +37,29 @@ module PaperTrailDiff
34
37
  timestamp = coerce_time(value, boundary: :timestamp)
35
38
  return false if timestamp < begin_time
36
39
 
37
- exclude_end? ? timestamp < end_time : timestamp <= end_time
40
+ finish = end_time
41
+ return true unless finish
42
+
43
+ exclude_end? ? timestamp < finish : timestamp <= finish
38
44
  end
39
45
 
40
46
  #: (untyped) -> untyped
41
47
  def scope(relation)
42
- relation.where(created_at: query_range)
48
+ relation.where(created_at: to_range)
43
49
  end
44
50
 
51
+ # The window as a Ruby range, its end included or left out as given, or
52
+ # endless.
53
+ #: () -> Range[Time?]
54
+ def to_range
55
+ exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
56
+ end
57
+
58
+ # The versions after the window; none follows an endless one.
45
59
  #: (untyped) -> untyped
46
60
  def trailing_scope(relation)
47
- relation.where(after_end(relation.arel_table[:created_at]))
61
+ finish = end_time
62
+ finish ? after(relation, finish) : relation.none
48
63
  end
49
64
 
50
65
  # Each item's earliest version after the range, keyed by item id. One row
@@ -52,12 +67,14 @@ module PaperTrailDiff
52
67
  # the query stays portable; a timestamp tie keeps the lower id.
53
68
  #: (untyped) -> Hash[String, untyped]
54
69
  def first_trailing_versions(relation)
55
- table = relation.arel_table
56
- first_after = VersionQuery.no_earlier_version(table) do |earlier|
57
- after_end(earlier[:created_at])
58
- end
59
- versions = VersionQuery.chronological(trailing_scope(relation).where(first_after))
70
+ finish = end_time
60
71
  first = {} #: Hash[String, untyped]
72
+ return first unless finish
73
+
74
+ first_after = VersionQuery.no_earlier_version(relation.arel_table) do |earlier|
75
+ after_end(earlier[:created_at], finish)
76
+ end
77
+ versions = VersionQuery.chronological(after(relation, finish).where(first_after))
61
78
  versions.each { |version| first[version.item_id.to_s] ||= version }
62
79
  first
63
80
  end
@@ -66,14 +83,14 @@ module PaperTrailDiff
66
83
 
67
84
  # @rbs @exclude_end: bool
68
85
 
69
- #: (untyped) -> untyped
70
- def after_end(column)
71
- exclude_end? ? column.gteq(end_time) : column.gt(end_time)
86
+ #: (untyped, Time) -> untyped
87
+ def after(relation, finish)
88
+ relation.where(after_end(relation.arel_table[:created_at], finish))
72
89
  end
73
90
 
74
- #: () -> Range[Time]
75
- def query_range
76
- exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
91
+ #: (untyped, Time) -> untyped
92
+ def after_end(column, finish)
93
+ exclude_end? ? column.gteq(finish) : column.gt(finish)
77
94
  end
78
95
 
79
96
  #: (untyped, boundary: Symbol) -> Time
@@ -115,7 +132,8 @@ module PaperTrailDiff
115
132
 
116
133
  #: () -> void
117
134
  def validate_order!
118
- return unless begin_time > end_time
135
+ finish = end_time
136
+ return unless finish && begin_time > finish
119
137
 
120
138
  raise InvalidTimeRangeError, '`within` beginning must not follow its end'
121
139
  end
@@ -12,10 +12,10 @@ module PaperTrailDiff
12
12
  @live_endpoint = live_endpoint
13
13
  end
14
14
 
15
- #: (context_required: bool) -> RootVersionPlan
16
- def select_plan(context_required:)
15
+ #: (context_required: bool, whole: bool) -> RootVersionPlan
16
+ def select_plan(context_required:, whole:)
17
17
  relation = Endpoint.versions(@record)
18
- in_range = ordered(@time_range.scope(relation))
18
+ in_range = @time_range.scope(relation)
19
19
  RootVersionSelection.new(
20
20
  in_range: in_range,
21
21
  selected: VersionScopeFilter.new(@version_scope).call(@time_range.scope(relation),
@@ -23,8 +23,8 @@ module PaperTrailDiff
23
23
  after_range: trailing_version(relation),
24
24
  windowed: true,
25
25
  context_required: context_required,
26
- filtered: !@version_scope.nil?,
27
- live_endpoint: @live_endpoint
26
+ live_endpoint: @live_endpoint,
27
+ whole: whole
28
28
  ).call
29
29
  end
30
30
 
@@ -39,10 +39,5 @@ module PaperTrailDiff
39
39
  def trailing_version(relation)
40
40
  VersionQuery.chronological(@time_range.trailing_scope(relation)).first
41
41
  end
42
-
43
- #: (Array[untyped]) -> Array[untyped]
44
- def ordered(versions)
45
- Support.chronological_sort(versions)
46
- end
47
42
  end
48
43
  end
@@ -4,16 +4,16 @@
4
4
  module PaperTrailDiff
5
5
  # Selects and compares a chronological slice of a record's version history.
6
6
  class TimelineBuilder
7
- #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
7
+ #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
8
8
  def initialize( # rubocop:disable Metrics/ParameterLists
9
9
  record, from:, to:, snapshotter:, within: nil, version_scope: nil, plan: nil,
10
- live_endpoint: nil
10
+ live_endpoint: nil, traversal: nil
11
11
  )
12
12
  @record = record
13
13
  @range = TimelineRange.new(
14
14
  record, from: from, to: to, within: within,
15
15
  version_scope: version_scope, plan: plan,
16
- live_endpoint: live_endpoint
16
+ live_endpoint: live_endpoint, traversal: traversal
17
17
  )
18
18
  @snapshotter = snapshotter
19
19
  end
@@ -24,6 +24,12 @@ module PaperTrailDiff
24
24
  steps
25
25
  end
26
26
 
27
+ # The window the range covers once its edges have moved to transactions.
28
+ #: () -> TimeRange?
29
+ def window
30
+ @range.time_range
31
+ end
32
+
27
33
  #: () -> Analysis
28
34
  def analyze
29
35
  steps, first_snapshot, last_snapshot = compare_history(selected_versions)
@@ -14,9 +14,12 @@ module PaperTrailDiff
14
14
  attr_reader :to #: untyped
15
15
  attr_reader :time_range #: TimeRange?
16
16
 
17
- #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
18
- def initialize(record, from:, to:, within:, version_scope: nil, plan: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists
17
+ # `traversal` names the requested paths, which decide where a window's
18
+ # edges move (see TransactionCut).
19
+ #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
20
+ def initialize(record, from:, to:, within:, version_scope: nil, plan: nil, live_endpoint: nil, traversal: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
19
21
  @record = record
22
+ @traversal = traversal
20
23
  @plan = plan
21
24
  @live_endpoint = live_endpoint
22
25
  @version_scope = version_scope
@@ -40,9 +43,10 @@ module PaperTrailDiff
40
43
  # A batch may have selected these versions already, in which case reselecting
41
44
  # them per record would undo the batching.
42
45
  # The plan says which pairs of versions become steps, which a filter can
43
- # make different from adjacent pairs of the selected versions.
44
- #: (?context_required: bool) -> RootVersionPlan
45
- def select_plan(context_required: false)
46
+ # make different from adjacent pairs of the selected versions. A `whole`
47
+ # plan replays every version in the range; see RootVersionSelection.
48
+ #: (?context_required: bool, ?whole: bool) -> RootVersionPlan
49
+ def select_plan(context_required: false, whole: false)
46
50
  preselected = @plan
47
51
  return preselected if preselected
48
52
 
@@ -51,9 +55,9 @@ module PaperTrailDiff
51
55
  return TimeVersionRange.new(
52
56
  @record, time_range: range, version_scope: @version_scope,
53
57
  live_endpoint: @live_endpoint
54
- ).select_plan(context_required: context_required)
58
+ ).select_plan(context_required: context_required, whole: whole)
55
59
  end
56
- explicit_plan
60
+ explicit_plan(whole)
57
61
  end
58
62
 
59
63
  #: () -> bool
@@ -75,6 +79,7 @@ module PaperTrailDiff
75
79
  private
76
80
 
77
81
  # @rbs @record: untyped
82
+ # @rbs @traversal: AssociationTraversal?
78
83
  # @rbs @plan: RootVersionPlan?
79
84
  # @rbs @version_scope: untyped
80
85
  # @rbs @live_endpoint: untyped
@@ -83,17 +88,17 @@ module PaperTrailDiff
83
88
  # @rbs @from: untyped
84
89
  # @rbs @to: untyped
85
90
 
86
- #: () -> RootVersionPlan
87
- def explicit_plan
91
+ #: (bool) -> RootVersionPlan
92
+ def explicit_plan(whole)
88
93
  return RootVersionPlan.empty if unresolved?
89
94
  if Endpoint.record?(@to)
90
95
  return VersionRange.new(@record, from: @from, to: @from, version_scope: @version_scope)
91
- .select_plan_through_current(@to)
96
+ .select_plan_through_current(@to, whole: whole)
92
97
  end
93
98
 
94
99
  VersionRange.new(
95
100
  @record, from: @from, to: @to, version_scope: @version_scope
96
- ).select_plan_for_range
101
+ ).select_plan_for_range(whole: whole)
97
102
  end
98
103
 
99
104
  #: (untyped) -> bool
@@ -132,7 +137,8 @@ module PaperTrailDiff
132
137
  range = TimeRange.new(within)
133
138
  return range unless Support.versioned?(@record.class)
134
139
 
135
- TransactionCut.windows(@record.class, [@record], range).fetch(@record.id.to_s, range)
140
+ TransactionCut.windows(@record.class, [@record], range, traversal: @traversal)
141
+ .fetch(@record.id.to_s, range)
136
142
  end
137
143
 
138
144
  #: () -> void
@@ -37,7 +37,7 @@ module PaperTrailDiff
37
37
  # version, which is the one endpoint no version history can reconstruct.
38
38
  #: (untyped) -> RecordSnapshot?
39
39
  def call(endpoint)
40
- key = [endpoint.class.name, endpoint.id]
40
+ key = Support.row_key(endpoint)
41
41
  return @snapshots[key] if @snapshots.key?(key)
42
42
 
43
43
  @snapshots[key] = if Endpoint.record?(endpoint)
@@ -0,0 +1,55 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # A relation's order, completed by its primary key. Reading a relation by
6
+ # offset holds only under a total order: a database may return rows that tie
7
+ # in a different order for each query, so that pages read some records twice
8
+ # and others never.
9
+ module TotalOrder
10
+ # The relation sorted by its key after its own order, unless that order
11
+ # already sorts by the key. Such an order is kept as given, since SQL
12
+ # Server rejects a column listed twice. So is the order of a relation
13
+ # grouped by anything but the key: each of its rows is a group, which a
14
+ # database sorts only by what it groups or aggregates. A relation answers
15
+ # for its model the key and table name read here.
16
+ #: (untyped) -> untyped
17
+ def self.apply(relation)
18
+ orders = relation.order_values
19
+ return relation if orders.any? { |order| key?(order, relation) }
20
+ return relation if !orders.empty? && grouped_by_other?(relation)
21
+
22
+ relation.order(relation.primary_key => :asc)
23
+ end
24
+
25
+ #: (untyped) -> bool
26
+ def self.grouped_by_other?(relation)
27
+ groups = relation.group_values
28
+ !groups.empty? && groups.none? { |group| key?(group, relation) }
29
+ end
30
+ private_class_method :grouped_by_other?
31
+
32
+ # An Arel order or group names its column; SQL text, or the name a group
33
+ # may be given as, is read by key_in_sql?.
34
+ #: (untyped, untyped) -> bool
35
+ def self.key?(term, relation)
36
+ term = term.expr if ScopeRanking::DIRECTIONS.key?(term.class.name)
37
+ return key_in_sql?(term.to_s, relation) if term.is_a?(String) || term.instance_of?(Symbol)
38
+
39
+ relation.primary_key.eql?(ScopeRanking.own_column(term, relation))
40
+ end
41
+ private_class_method :key?
42
+
43
+ # Whether SQL text names the key, alone or after its table's name. That
44
+ # also finds a key the text only uses, as in `LENGTH(id)`, which then goes
45
+ # without the tie-breaker, but it misses no sort by the key.
46
+ #: (String, untyped) -> bool
47
+ def self.key_in_sql?(sql, relation)
48
+ names = sql.scan(/(?:(\w+)\.)?(\w+)/) #: Array[[String?, String]]
49
+ names.any? do |table, column|
50
+ column.casecmp?(relation.primary_key) && (table.nil? || table.casecmp?(relation.table_name))
51
+ end
52
+ end
53
+ private_class_method :key_in_sql?
54
+ end
55
+ end