paper_trail_diff 0.17.1 → 0.18.1

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 +661 -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 +195 -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 +126 -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
@@ -22,29 +22,23 @@ module PaperTrailDiff
22
22
  # before the next root version is in the tree only there. A record in none
23
23
  # of these was outside the tree throughout.
24
24
  #
25
- # The root's own events are always kept, and so is an event whose step is
26
- # not reported, which only bounds one that is, unless its transaction has an
27
- # event whose step is: the transaction crossed the window's end. A version
28
- # it saved after the edge reads each record as it stood before the
29
- # transaction, so a step ending there shows none of its changes. Judged
30
- # like the rest, as the window after the edge judges it, the event bounds
31
- # that step when the later window reports the transaction; left out, the
32
- # step runs past it and reports the changes here instead (see
33
- # ActivityHistoryBuilder#consume). A snapshot does not hold a through's join
25
+ # The root's own events are always kept. Every other event is judged,
26
+ # whether or not its step is reported: one left in only bounds a reported
27
+ # step, and which records' events a history holds depends on what else was
28
+ # read with it, so an event of a record outside the tree would bound a step
29
+ # in one read and not in another. A snapshot does not hold a through's join
34
30
  # rows, so their versions are judged when they are collected, by the row's
35
- # own state (PreparedActivityIndex#join_versions), and kept here.
31
+ # own state (PreparedActivityIndex#join_versions), and kept here where
32
+ # their transaction changed what the row's branches hold.
36
33
  class ActivityTreeFilter
37
- # `reported` says whether an event's step is reported. `closing` is the
38
- # snapshot after the last event: the current record's, or nil when
39
- # nothing follows, as after the root's destruction.
40
- #: (Array[ActivityEvent], reported: untyped, closing: RecordSnapshot?) -> void
41
- def initialize(events, reported:, closing:)
42
- @reported = reported
34
+ # `closing` is the snapshot after the last event: the current record's,
35
+ # or nil when nothing follows, as after the root's destruction.
36
+ #: (Array[ActivityEvent], closing: RecordSnapshot?) -> void
37
+ def initialize(events, closing:)
43
38
  @closing = closing
44
39
  @keys = transaction_keys(events)
45
40
  @starts, @ends = spans(@keys)
46
41
  @roots = root_positions(events)
47
- @judged = reported_transactions(events)
48
42
  @types = {} #: Hash[String, Array[String?]]
49
43
  end
50
44
 
@@ -53,42 +47,78 @@ module PaperTrailDiff
53
47
  #: (untyped) { (ActivityEvent, RecordSnapshot?, bool) -> void } -> void
54
48
  def call(sequence)
55
49
  pairs = sequence.to_enum.to_a #: Array[[ActivityEvent, RecordSnapshot?]]
56
- pairs.each_with_index do |(event, snapshot), index|
57
- yield event, snapshot, keep?(event, index, pairs)
58
- end
50
+ kept = kept(pairs)
51
+ pairs.each_with_index { |(event, snapshot), index| yield event, snapshot, kept.fetch(index) }
59
52
  end
60
53
 
61
54
  private
62
55
 
63
- # @rbs @reported: untyped
64
56
  # @rbs @closing: RecordSnapshot?
65
57
  # @rbs @keys: Array[Array[untyped] | Integer]
66
58
  # @rbs @starts: Array[Integer]
67
59
  # @rbs @ends: Array[Integer]
68
60
  # @rbs @roots: Hash[Array[untyped] | Integer, Array[Integer]]
69
- # @rbs @judged: Set[Array[untyped] | Integer]
70
61
  # @rbs @types: Hash[String, Array[String?]]
71
62
 
72
- #: (ActivityEvent, Integer, Array[[ActivityEvent, RecordSnapshot?]]) -> bool
73
- def keep?(event, index, pairs)
74
- key = @keys.fetch(index)
75
- return true if event.root? || event.join? || !@judged.include?(key)
63
+ # Whether to keep each event. The snapshots are gone through once, in
64
+ # order, each answering for the events it judges (see SnapshotMembers):
65
+ # looking through a snapshot for each event made a replay's time grow
66
+ # with its events times the records of the tree.
67
+ #: (Array[[ActivityEvent, RecordSnapshot?]]) -> Array[bool]
68
+ def kept(pairs)
69
+ snapshots = pairs.map(&:last) << @closing
70
+ kept = unjudged(pairs.map(&:first), snapshots)
71
+ members = SnapshotMembers.new
72
+ judged(pairs).zip(snapshots) do |indexes, snapshot|
73
+ members.move_to(snapshot)
74
+ indexes.each { |index| kept[index] ||= holds?(members, pairs.fetch(index).first) }
75
+ end
76
+ kept
77
+ end
78
+
79
+ # The root's own events are kept whatever else holds, and so is a join
80
+ # row whose transaction changed a branch it is a join row of. Its
81
+ # versions were judged when they were collected, by where the row leads,
82
+ # but a row can lead somewhere before the owner it joins is in the tree,
83
+ # or lead to records with nothing to show, and a row of a through that
84
+ # goes through another is on its path by rows further down, which its
85
+ # own state cannot show: its transaction then leaves those branches as
86
+ # it found them. Under any other branch the row is judged as any record.
87
+ #: (Array[ActivityEvent], Array[RecordSnapshot?]) -> Array[bool]
88
+ def unjudged(events, snapshots)
89
+ events.each_with_index.map do |event, index|
90
+ event.root? || changed?(snapshots, event.joins, index)
91
+ end
92
+ end
76
93
 
77
- judged_by(index, key, pairs).any? { |snapshot| holds?(snapshot, event) }
94
+ #: (Array[RecordSnapshot?], Array[String], Integer) -> bool
95
+ def changed?(snapshots, branches, index)
96
+ before = snapshots.fetch(@starts.fetch(index))
97
+ after = snapshots.fetch(@ends.fetch(index))
98
+ branches.any? { |name| !branch(before, name).eql?(branch(after, name)) }
78
99
  end
79
100
 
80
- # The snapshots at the first event and the root events of the event's
81
- # transaction, and the one after its last event.
82
- #: (Integer, Array[untyped] | Integer, Array[[ActivityEvent, RecordSnapshot?]]) -> Array[RecordSnapshot?]
83
- def judged_by(index, key, pairs)
84
- position = @ends.fetch(index)
85
- after = position < pairs.length ? pairs.fetch(position).last : @closing
86
- ([@starts.fetch(index)] + @roots.fetch(key, [])).map { |at| pairs.fetch(at).last } << after
101
+ # A missing snapshot, after the root's destruction, and a branch the
102
+ # snapshot does not hold, as before the root's creation, hold no records.
103
+ #: (RecordSnapshot?, String) -> Array[untyped]
104
+ def branch(snapshot, name)
105
+ association = snapshot&.associations&.[](name)
106
+ association ? association.to_h.fetch(:records) : []
87
107
  end
88
108
 
89
- #: (ActivityEvent) -> bool
90
- def reported?(event)
91
- @reported.call(event)
109
+ # The events each snapshot judges, by the snapshot's position, the one
110
+ # after the last event being what the range closes on: an event is judged
111
+ # by the snapshots at the first event and the root events of its
112
+ # transaction, and by the one after its last event. An event kept
113
+ # already is not asked about again (see #kept).
114
+ #: (Array[[ActivityEvent, RecordSnapshot?]]) -> Array[Array[Integer]]
115
+ def judged(pairs)
116
+ asked = Array.new(pairs.length.succ) { [] } #: Array[Array[Integer]]
117
+ pairs.each_index do |index|
118
+ positions = [@starts.fetch(index), *@roots[@keys.fetch(index)], @ends.fetch(index)]
119
+ positions.each { |position| asked.fetch(position) << index }
120
+ end
121
+ asked
92
122
  end
93
123
 
94
124
  # Where each event's transaction starts, and the position just past its
@@ -112,13 +142,6 @@ module PaperTrailDiff
112
142
  .group_by { |index| @keys.fetch(index) }
113
143
  end
114
144
 
115
- # The transactions that have an event whose step is reported.
116
- #: (Array[ActivityEvent]) -> Set[Array[untyped] | Integer]
117
- def reported_transactions(events)
118
- events.each_index.select { |index| reported?(events.fetch(index)) }
119
- .to_set { |index| @keys.fetch(index) }
120
- end
121
-
122
145
  # A version saved outside a transaction is a transaction of its own,
123
146
  # keyed by its position.
124
147
  #: (Array[ActivityEvent]) -> Array[Array[untyped] | Integer]
@@ -128,21 +151,11 @@ module PaperTrailDiff
128
151
  end
129
152
  end
130
153
 
131
- #: (RecordSnapshot?, ActivityEvent) -> bool
132
- def holds?(snapshot, event)
133
- return false unless snapshot
134
-
154
+ #: (SnapshotMembers, ActivityEvent) -> bool
155
+ def holds?(members, event)
135
156
  version = event.version
136
- types = types(version.item_type)
137
157
  branches = event.branches #: Array[String]
138
- branches.any? { |name| contains?(snapshot.associations.fetch(name), types, version.item_id) }
139
- end
140
-
141
- #: (AssociationSnapshot, Array[String?], untyped) -> bool
142
- def contains?(association, types, id)
143
- types.any? { |type| association.position(type, id) } || association.records.any? do |record|
144
- record.associations.each_value.any? { |nested| contains?(nested, types, id) }
145
- end
158
+ members.holds?(branches, types(version.item_type), version.item_id)
146
159
  end
147
160
 
148
161
  # A version names its record's base class, and a snapshot the record's
@@ -0,0 +1,76 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Says whether an event on a record of some model can be applied to the
6
+ # one place the record has in a snapshot.
7
+ #
8
+ # A path can lead to a record twice: an article read with `author.articles`
9
+ # is the root and one of its author's articles, and under
10
+ # `articles.comments.article` an article is a member of a collection and
11
+ # the target of a `belongs_to` below it. An event is applied to a snapshot
12
+ # in one way, as the root's, a collection member's, or a target's, so it
13
+ # reaches the places of that one kind and would leave the others as they
14
+ # were. Such an event has its branches, or for the root the whole snapshot,
15
+ # read again instead.
16
+ class ActivityTreePlaces
17
+ #: (AssociationTraversal) -> void
18
+ def initialize(traversal)
19
+ @traversal = traversal
20
+ @kinds = {} #: Hash[untyped, Hash[String, Array[Symbol]]]
21
+ @polymorphic = {} #: Hash[untyped, bool]
22
+ end
23
+
24
+ # Whether every place the tree gives records of the type is of one kind.
25
+ # A polymorphic `belongs_to` can point at a record of any model, so a
26
+ # tree with one gives every model a place there too.
27
+ #: (untyped, String) -> bool
28
+ def one_kind?(root_class, type)
29
+ kinds = kinds_for(root_class)
30
+ !@polymorphic.fetch(root_class) && kinds.fetch(type) { [] }.length <= 1
31
+ end
32
+
33
+ private
34
+
35
+ # @rbs @traversal: AssociationTraversal
36
+ # @rbs @kinds: Hash[untyped, Hash[String, Array[Symbol]]]
37
+ # @rbs @polymorphic: Hash[untyped, bool]
38
+
39
+ # The kinds of place each model has under this root, by base class name.
40
+ #: (untyped) -> Hash[String, Array[Symbol]]
41
+ def kinds_for(root_class)
42
+ @kinds.fetch(root_class) do
43
+ kinds = { root_class.base_class.name => [:root] } #: Hash[String, Array[Symbol]]
44
+ @polymorphic[root_class] = false
45
+ collect(root_class, root_class, @traversal.tree, '', kinds)
46
+ @kinds[root_class] = kinds
47
+ end
48
+ end
49
+
50
+ #: (untyped, untyped, AssociationTree, String, Hash[String, Array[Symbol]]) -> void
51
+ def collect(root_class, model_class, tree, path, kinds)
52
+ @traversal.reflections_for(model_class, tree, path: path).each do |reflection|
53
+ next @polymorphic[root_class] = true if reflection.polymorphic?
54
+
55
+ place(reflection, kinds)
56
+ subtree = tree.child(reflection.name) #: AssociationTree
57
+ next if subtree.empty?
58
+
59
+ collect(root_class, reflection.klass, subtree,
60
+ Support.association_path(path, reflection.name), kinds)
61
+ end
62
+ end
63
+
64
+ # A through holds its target, and the records it joins through decide
65
+ # what it holds, so each of them has a place of its own kind there.
66
+ #: (untyped, Hash[String, Array[Symbol]]) -> void
67
+ def place(reflection, kinds)
68
+ kind = reflection.through_reflection? ? :through : reflection.macro
69
+ models = reflection.through_reflection? ? reflection.chain.map(&:klass) : [reflection.klass]
70
+ models.each do |model|
71
+ name = model.base_class.name
72
+ kinds[name] = kinds.fetch(name) { [] } | [kind]
73
+ end
74
+ end
75
+ end
76
+ end
@@ -19,7 +19,8 @@ module PaperTrailDiff
19
19
  end
20
20
 
21
21
  # A tie between version tables, or between ids that do not count up,
22
- # raises rather than building a timeline in an arbitrary order.
22
+ # raises rather than building a timeline in an arbitrary order. The events
23
+ # are in the order their transactions end (see TransactionEnds).
23
24
  #: () -> Array[ActivityEvent]
24
25
  def call
25
26
  @registry.add(@root_versions)
@@ -27,11 +28,14 @@ module PaperTrailDiff
27
28
  unless tree.empty?
28
29
  collect_tree(group(@record.class, [@record.id]), tree, path: '', branch: nil)
29
30
  end
30
- events = @registry.to_a.sort_by { |event| Support.chronological_version_key(event.version) }
31
- pair = Support.ambiguous_pair(events.map(&:version))
32
- pair ? raise(AmbiguousVersionOrderError, Support.ambiguous_message(pair)) : events.freeze
31
+ ordered(@registry.to_a)
33
32
  end
34
33
 
34
+ # Where the transactions of the collected events take effect, once #call
35
+ # has ordered them by it.
36
+ #: () -> TransactionEnds?
37
+ attr_reader :ends
38
+
35
39
  private
36
40
 
37
41
  # @rbs @prepared: PreparedActivityIndex
@@ -40,6 +44,23 @@ module PaperTrailDiff
40
44
  # @rbs @traversal: AssociationTraversal
41
45
  # @rbs @range: ActivityRange
42
46
  # @rbs @registry: ActivityEventRegistry
47
+ # @rbs @ends: TransactionEnds?
48
+
49
+ #: (Array[ActivityEvent]) -> Array[ActivityEvent]
50
+ def ordered(events)
51
+ events = events.sort_by { |event| Support.chronological_version_key(event.version) }
52
+ pair = Support.ambiguous_pair(events.map(&:version))
53
+ raise(AmbiguousVersionOrderError, Support.ambiguous_message(pair)) if pair
54
+
55
+ ends = transaction_ends(events.map(&:version))
56
+ events.sort_by { |event| ends.sort_key(event.version) }.freeze
57
+ end
58
+
59
+ #: (Array[untyped]) -> TransactionEnds
60
+ def transaction_ends(versions)
61
+ prepared = @prepared #: PreparedActivityIndex?
62
+ @ends = prepared ? prepared.transaction_ends(versions) : TransactionEnds.new(versions)
63
+ end
43
64
 
44
65
  # Each event is credited to the top-level association it was reached
45
66
  # through.
@@ -66,11 +87,8 @@ module PaperTrailDiff
66
87
  def edge_groups(parent, reflection, branch)
67
88
  return through_groups(parent, reflection, branch) if reflection.through_reflection?
68
89
 
69
- case reflection.macro
70
- when :belongs_to
90
+ if reflection.belongs_to?
71
91
  belongs_to_groups(parent.fetch(:model), parent.fetch(:ids), reflection)
72
- when :has_and_belongs_to_many
73
- habtm_groups(parent.fetch(:model), parent.fetch(:versions), reflection)
74
92
  else
75
93
  direct_child_groups(parent.fetch(:model), parent.fetch(:ids), reflection)
76
94
  end
@@ -83,13 +101,23 @@ module PaperTrailDiff
83
101
  targets = edge_groups(parent, reflection.through_reflection, branch).flat_map do |group|
84
102
  joins = @prepared.join_versions(parent, group, reflection)
85
103
  @registry.add(joins, branch: branch, join: true)
86
- edge_groups(group, reflection.source_reflection, branch)
104
+ led(group, reflection, edge_groups(group, reflection.source_reflection, branch))
87
105
  end
88
106
  # Under `source_type:`, only targets of that type are members.
89
107
  type = reflection.options[:source_type]
90
108
  type ? targets.select { |group| type.to_s.eql?(group.fetch(:model).name) } : targets
91
109
  end
92
110
 
111
+ # The targets a through reaches by a `belongs_to` name the join rows that
112
+ # lead to them, which judge them as join rows of a through over this one
113
+ # (see PreparedActivityIndex#join_versions).
114
+ #: (Hash[Symbol, untyped], untyped, Array[Hash[Symbol, untyped]]) -> Array[Hash[Symbol, untyped]]
115
+ def led(rows, reflection, targets)
116
+ return targets unless reflection.source_reflection.belongs_to?
117
+
118
+ targets.map { |target| target.merge(leads: { group: rows, reflection: reflection }) }
119
+ end
120
+
93
121
  # Every target the owners pointed at in the range, not only those their own
94
122
  # changes there recorded: an author renamed under an article nobody edited
95
123
  # is still that article's activity. Prepared history holds every target its
@@ -97,38 +125,23 @@ module PaperTrailDiff
97
125
  # version -- has no state to compare.
98
126
  #: (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
99
127
  def belongs_to_groups(parent_class, parent_ids, reflection)
100
- rows = @prepared.target_rows(parent_class, parent_ids, reflection, @range)
101
- identity_groups(rows, reflection) { |model_class, id| @prepared.loaded?(model_class, id) }
102
- end
103
-
104
- # With no children, nothing below them is read: prepared history registers
105
- # only the classes it loaded records of.
106
- #: (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
107
- def direct_child_groups(parent_class, parent_ids, reflection)
108
- item_ids = @prepared.child_ids(parent_class, parent_ids, reflection, @range)
109
- item_ids.empty? ? [] : [group(reflection.klass, item_ids)]
110
- end
111
-
112
- #: (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
113
- def habtm_groups(parent_class, parent_versions, reflection)
114
- identity_groups(@prepared.habtm_rows(parent_class, parent_versions, reflection), reflection)
115
- end
116
-
117
- # A type a polymorphic row stored that names no class has no versions to
118
- # read.
119
- #: (Array[untyped], untyped) ?{ (untyped, untyped) -> bool } -> Array[Hash[Symbol, untyped]]
120
- def identity_groups(rows, reflection)
128
+ rows = @prepared.target_rows(parent_class, parent_ids, reflection)
121
129
  identities = rows.group_by do |row|
122
130
  AssociationTraversal.stored_target(reflection, row.foreign_type)
123
131
  end
124
132
  identities.filter_map do |model_class, class_rows|
125
133
  next unless model_class
126
134
 
127
- ids = target_ids(class_rows)
128
- group(model_class, block_given? ? ids.select { |id| yield(model_class, id) } : ids)
135
+ ids = target_ids(class_rows).select { |id| @prepared.loaded?(model_class, id) }
136
+ group(model_class, ids)
129
137
  end
130
138
  end
131
139
 
140
+ #: (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
141
+ def direct_child_groups(parent_class, parent_ids, reflection)
142
+ [group(reflection.klass, @prepared.child_ids(parent_class, parent_ids, reflection, @range))]
143
+ end
144
+
132
145
  # Each target once, however many rows name it, and none for a row that
133
146
  # names none. The registry keeps a version once, and a missing target has
134
147
  # no versions, so this only saves reading them again, which is why mutant
@@ -11,6 +11,8 @@ module PaperTrailDiff
11
11
  # Options only an activity view uses are refused without one.
12
12
  #: (activity: bool, snapshots: bool, group: Symbol?, recorded: IgnorePolicy?, ?version_scope: untyped) -> ActivityView
13
13
  def self.build(activity:, snapshots:, group:, recorded:, version_scope: nil)
14
+ Support.boolean!(:activity, activity)
15
+ Support.boolean!(:snapshots, snapshots)
14
16
  view = new(snapshots: snapshots, group: group, recorded: recorded,
15
17
  version_scope: version_scope)
16
18
  return view if activity
@@ -9,9 +9,9 @@ module PaperTrailDiff
9
9
  attr_reader :activity_timeline #: Array[ActivityStep]?
10
10
  attr_reader :from_snapshot #: RecordSnapshot?
11
11
  attr_reader :to_snapshot #: RecordSnapshot?
12
- # The time window the analysis covers, or nil without one; a report's has
13
- # no end. It is the window asked for unless a transaction crossed an edge,
14
- # which moves the edge back to where that transaction began.
12
+ # The time window asked for, or nil without one; a report's has no end.
13
+ # It does not move: a transaction that crossed an edge is reported in the
14
+ # window it ended in.
15
15
  attr_reader :window #: Range[Time?]?
16
16
 
17
17
  # The result for a record whose requested history contains no versions,
@@ -42,8 +42,9 @@ module PaperTrailDiff
42
42
  freeze
43
43
  end
44
44
 
45
- # The same result for the window it was read in, which the caller knows
46
- # once it has moved the window's edges to transactions.
45
+ # The same result for the window it was asked in. A batch reads a root
46
+ # over a wider range when a transaction was open at the window's start,
47
+ # and reports the window as asked.
47
48
  #: (TimeRange?) -> Analysis
48
49
  def with_window(range)
49
50
  self.class.new(
@@ -6,21 +6,19 @@ module PaperTrailDiff
6
6
  # versions and preparing their association history once for the whole batch
7
7
  # rather than once per root.
8
8
  class AnalysisBatch
9
- # `traversal` names the requested paths, which decide where a window's
10
- # edges move (see TransactionCut).
11
- #: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, version_scope: untyped, context_required: bool, traversal: AssociationTraversal?) -> void
9
+ #: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, version_scope: untyped, context_required: bool, reach: untyped) -> void
12
10
  def initialize( # rubocop:disable Metrics/ParameterLists
13
11
  records, time_range:, live_loader:, history_preparer:, analyzer:, version_scope:,
14
- context_required:, traversal:
12
+ context_required:, reach:
15
13
  )
16
14
  @records = records
17
- @traversal = traversal
18
15
  @context_required = context_required
19
16
  @time_range = time_range
20
17
  # Checked up front rather than failing partway through a batch.
21
- @version_scope = VersionScopeFilter.validated(version_scope)
18
+ @version_scope = version_scope
22
19
  @live_loader = live_loader
23
20
  @history_preparer = history_preparer
21
+ @reach = reach
24
22
  @analyzer = analyzer
25
23
  end
26
24
 
@@ -28,30 +26,36 @@ module PaperTrailDiff
28
26
  def call
29
27
  records = validated_records
30
28
  loaded = @live_loader.call(records)
31
- windows = TransactionCut.batch_windows(records, @time_range, traversal: @traversal)
32
- # Activity on associations both takes a context and replays whole plans.
33
- plans = BatchedRootVersions.new(
34
- records, time_range: @time_range, version_scope: @version_scope,
35
- live_endpoints: loaded, context_required: @context_required,
36
- whole: @context_required, windows: windows
37
- ).call
38
29
  BatchedRootAnalyses.new(
39
- time_range: @time_range, windows: windows, history_preparer: @history_preparer,
40
- analyzer: @analyzer
41
- ).call(records, plans, loaded: loaded).freeze
30
+ time_range: @time_range, planner: planner(loaded),
31
+ history_preparer: @history_preparer, analyzer: @analyzer,
32
+ activity: @context_required, reach: @reach
33
+ ).call(records, loaded: loaded).freeze
42
34
  end
43
35
 
44
36
  private
45
37
 
46
38
  # @rbs @records: Array[untyped]
47
- # @rbs @traversal: AssociationTraversal?
48
39
  # @rbs @time_range: TimeRange?
49
40
  # @rbs @version_scope: untyped
50
41
  # @rbs @context_required: bool
51
42
  # @rbs @live_loader: untyped
52
43
  # @rbs @history_preparer: untyped
44
+ # @rbs @reach: untyped
53
45
  # @rbs @analyzer: untyped
54
46
 
47
+ # Activity on associations both takes a context and replays whole plans.
48
+ #: (Hash[Array[String], untyped]) -> untyped
49
+ def planner(loaded)
50
+ lambda do |records, range|
51
+ BatchedRootVersions.new(
52
+ records, time_range: range, version_scope: @version_scope,
53
+ live_endpoints: loaded, context_required: @context_required,
54
+ whole: @context_required
55
+ ).call
56
+ end
57
+ end
58
+
55
59
  #: () -> Array[untyped]
56
60
  def validated_records
57
61
  raise ConfigurationError, 'records: must be an array' unless @records.is_a?(Array)