paper_trail_diff 0.16.0 → 0.17.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 (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +581 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -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 +3 -13
  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 +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -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 +74 -40
  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 +194 -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 +19 -5
  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 +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  44. data/lib/paper_trail_diff/change_attribution.rb +329 -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 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  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 +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +197 -45
  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 +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  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 +41 -19
  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 +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  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 +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -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 +192 -91
  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 +27 -16
  105. data/lib/paper_trail_diff/version_boundary.rb +37 -21
  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 +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  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 +0 -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 +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -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 +36 -2
  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 +121 -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 +15 -6
  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 +9 -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 +11 -5
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +194 -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 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  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 +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +114 -14
  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 +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  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 +27 -8
  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 +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  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 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -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 +111 -52
  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 +10 -9
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -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 +13 -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 +28 -6
  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
@@ -0,0 +1,51 @@
1
+ # Generated from lib/paper_trail_diff/activity_scope_filter.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Which events a `version_scope:` reports in activity on associations.
5
+ #
6
+ # PT-AT reads a transaction's records as they stood before it began, so the
7
+ # changes a transaction saved surface together in its last step rather than
8
+ # each in the step of its own version (see ActivityTransactionGrouper). No
9
+ # step inside a transaction can be credited to one version of it, and
10
+ # leaving one out would lose the changes it carried. A transaction is
11
+ # therefore reported whole when the filter keeps any version saved in it, of
12
+ # whichever record, and a version saved outside a transaction when the
13
+ # filter keeps that version. Both are answered from the version tables, so
14
+ # every window and every way of asking reads the same transaction alike.
15
+ #
16
+ # One filter serves a request. It reads the answers for each history once,
17
+ # in one statement per version table and 500 transactions or versions, and
18
+ # the roots a batch prepared together share them.
19
+ class ActivityScopeFilter
20
+ # : (untyped) -> void
21
+ def initialize: (untyped) -> void
22
+
23
+ # Reads the answers for every version `history` holds, once for each
24
+ # history, and for those of `versions` it does not hold.
25
+ # : (PreparedHistory?, Array[untyped]) -> void
26
+ def prepare: (PreparedHistory?, Array[untyped]) -> void
27
+
28
+ # Whether the filter keeps a version of `version`'s transaction, or
29
+ # `version` itself when it was saved outside one. `prepare` reads it first.
30
+ # : (untyped) -> bool
31
+ def kept?: (untyped) -> bool
32
+
33
+ private
34
+
35
+ @histories: Set[PreparedHistory]
36
+
37
+ @scope: untyped
38
+
39
+ @transactions: Hash[Array[untyped], bool]
40
+
41
+ @versions: Hash[Array[untyped], bool]
42
+
43
+ # : (Array[untyped]) -> void
44
+ def read: (Array[untyped]) -> void
45
+
46
+ # Records which of the distinct `values` of `column` the filter keeps
47
+ # versions with.
48
+ # : (untyped, Hash[Array[untyped], bool], String, Array[untyped], Symbol) -> void
49
+ def read_kept: (untyped, Hash[Array[untyped], bool], String, Array[untyped], Symbol) -> void
50
+ end
51
+ end
@@ -15,6 +15,11 @@ module PaperTrailDiff
15
15
  # : (untyped) -> untyped
16
16
  def after_value: (untyped) -> untyped
17
17
 
18
+ # Compared as text, so an id read as a string matches one read as an
19
+ # integer.
20
+ # : (untyped) -> bool
21
+ def changed?: (untyped) -> bool
22
+
18
23
  # : (untyped) -> bool
19
24
  def relationship_changed?: (untyped) -> bool
20
25
 
@@ -24,9 +29,6 @@ module PaperTrailDiff
24
29
 
25
30
  @before_attributes: Hash[String, untyped]
26
31
 
27
- # : (Hash[untyped, untyped]) -> Hash[String, untyped]
28
- def normalize_hash: (Hash[untyped, untyped]) -> Hash[String, untyped]
29
-
30
32
  # : (untyped) -> Array[untyped]
31
33
  def relationship_keys: (untyped) -> Array[untyped]
32
34
  end
@@ -13,6 +13,8 @@ module PaperTrailDiff
13
13
  # share these snapshots too, and the caches their refresher builds. They
14
14
  # are the same for any root with that history, so reusing them depends on
15
15
  # nothing but the history.
16
+ #
17
+ # A `start_at` is a window's; a range of versions starts at its first.
16
18
  # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
17
19
  def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
18
20
 
@@ -40,6 +42,9 @@ module PaperTrailDiff
40
42
  # : () -> PreparedActivityIndex?
41
43
  def activity_index: () -> PreparedActivityIndex?
42
44
 
45
+ # : () -> Array[Array[untyped]]
46
+ def opening_transactions: () -> Array[Array[untyped]]
47
+
43
48
  # : (untyped, untyped) -> RecordSnapshot?
44
49
  def call: (untyped, untyped) -> RecordSnapshot?
45
50
 
@@ -53,6 +58,11 @@ module PaperTrailDiff
53
58
  # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
54
59
  def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
55
60
 
61
+ # The state this root's snapshot at an endpoint is built from, where
62
+ # prepared history builds it.
63
+ # : (untyped) -> PreparedRecordState?
64
+ def root_state: (untyped) -> PreparedRecordState?
65
+
56
66
  # : (untyped, habtm_version: untyped) -> untyped
57
67
  def association_reader: (untyped, habtm_version: untyped) -> untyped
58
68
 
@@ -74,9 +84,6 @@ module PaperTrailDiff
74
84
  # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped) -> void
75
85
  def initialize: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped) -> void
76
86
 
77
- # : () -> Array[RecordSnapshot?]
78
- def call: () -> Array[RecordSnapshot?]
79
-
80
87
  # : () { (ActivityEvent, RecordSnapshot?) -> void } -> void
81
88
  def each: () { (ActivityEvent, RecordSnapshot?) -> void } -> void
82
89
 
@@ -97,6 +104,17 @@ module PaperTrailDiff
97
104
  # : (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
98
105
  def transition_snapshot: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
99
106
 
107
+ # A transaction with a root event is read whole once it ends. Until then,
108
+ # PT-AT reads the records it saved as they stood before it began, so from
109
+ # one descendant's event to the next in the same transaction the snapshot
110
+ # is the same, and from the root's event to a descendant's only the root's
111
+ # own version applies, as when it is alone in its transaction. A create
112
+ # leaves nothing to advance. The root's version can record what the
113
+ # transaction changed, such as HABTM membership, so a snapshot at a root
114
+ # event is rebuilt.
115
+ # : (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
116
+ def rebuilt_snapshot: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
117
+
100
118
  # : (ActivityEvent) -> bool
101
119
  def incremental_root?: (ActivityEvent) -> bool
102
120
 
@@ -1,14 +1,13 @@
1
1
  # Generated from lib/paper_trail_diff/activity_target_candidate_loader.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Loads the `belongs_to` targets owners pointed at during one activity range:
5
- # at its start and after each change inside it.
4
+ # Loads the `belongs_to` targets owners pointed at from a start onward: at
5
+ # the start, after each change since, and in the live row.
6
6
  #
7
7
  # PT-AT records a version's foreign keys as they stood after its change, so
8
- # the target at the start comes from the latest version before it, and the
9
- # version a range ends at names a target only after the range. Reading only
10
- # the owners' versions inside the range misses a target whose owner did not
11
- # change there -- an author renamed under an article nobody edited.
8
+ # the target at the start comes from the latest version before it. Reading
9
+ # only the owners' versions after the start misses a target whose owner did
10
+ # not change there -- an author renamed under an article nobody edited.
12
11
  class ActivityTargetCandidateLoader
13
12
  # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
14
13
  # gem supports 3.1.
@@ -23,20 +22,15 @@ module PaperTrailDiff
23
22
 
24
23
  attr_reader event: String?
25
24
 
26
- attr_reader version_id: untyped
27
-
28
- # : (untyped, untyped, String?, ?untyped, ?String?, ?untyped) -> void
29
- def initialize: (untyped, untyped, String?, ?untyped, ?String?, ?untyped) -> void
25
+ # : (untyped, untyped, String?, ?untyped, ?String?) -> void
26
+ def initialize: (untyped, untyped, String?, ?untyped, ?String?) -> void
30
27
  end
31
28
 
32
- # : (untyped, Array[untyped], untyped, ActivityRange) -> void
33
- def initialize: (untyped, Array[untyped], untyped, ActivityRange) -> void
34
-
35
- # : () -> Array[Row]
36
- def call: () -> Array[Row]
29
+ # : (untyped, Array[untyped], untyped, untyped) -> void
30
+ def initialize: (untyped, Array[untyped], untyped, untyped) -> void
37
31
 
38
- # One shared query keeps the owner and timestamp needed to partition a
39
- # batch's candidates back into each root's exact activity range.
32
+ # Queries shared by a batch's roots keep the owner and timestamp needed to
33
+ # partition its candidates back into each root's exact activity range.
40
34
  # : () -> Array[Row]
41
35
  def historical_rows: () -> Array[Row]
42
36
 
@@ -50,12 +44,16 @@ module PaperTrailDiff
50
44
 
51
45
  @owner_ids: Array[untyped]
52
46
 
53
- @range: ActivityRange
54
-
55
47
  @reflection: untyped
56
48
 
57
- # : (untyped) -> untyped
58
- def historical_relation: (untyped) -> untyped
49
+ @start_at: untyped
50
+
51
+ # Each statement reads the targets of 500 owners.
52
+ # : () -> Enumerator[Array[untyped], untyped]
53
+ def owner_slices: () -> Enumerator[Array[untyped], untyped]
54
+
55
+ # : (untyped, Array[untyped]) -> untyped
56
+ def historical_relation: (untyped, Array[untyped]) -> untyped
59
57
 
60
58
  # : (untyped, untyped) -> Array[Array[untyped]]
61
59
  def historical_columns: (untyped, untyped) -> Array[Array[untyped]]
@@ -67,9 +65,6 @@ module PaperTrailDiff
67
65
  # : () -> Array[Array[untyped]]
68
66
  def live_rows: () -> Array[Array[untyped]]
69
67
 
70
- # : (untyped) -> VersionAssociationCandidateScope
71
- def candidate_scope: (untyped) -> VersionAssociationCandidateScope
72
-
73
68
  # : () -> untyped
74
69
  def association_class: () -> untyped
75
70
 
@@ -9,8 +9,11 @@ module PaperTrailDiff
9
9
  # window reports only the events inside it, and closes on a final destroy,
10
10
  # or on the live row when nothing recorded follows it.
11
11
  class ActivityTimelineBuilder
12
- # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, view: ActivityView) -> void
13
- def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, view: ActivityView) -> void
12
+ # `traversal` holds the tree and reads its reflections; the adapter passes
13
+ # the one it reads every root with, so they are resolved once for a call
14
+ # rather than once for each root.
15
+ # : (untyped, range: TimelineRange, snapshotter: untyped, view: ActivityView, traversal: AssociationTraversal) -> void
16
+ def initialize: (untyped, range: TimelineRange, snapshotter: untyped, view: ActivityView, traversal: AssociationTraversal) -> void
14
17
 
15
18
  # : () -> Array[ActivityStep]
16
19
  def build: () -> Array[ActivityStep]
@@ -26,6 +29,8 @@ module PaperTrailDiff
26
29
 
27
30
  private
28
31
 
32
+ @filter: ActivityScopeFilter?
33
+
29
34
  @range: TimelineRange
30
35
 
31
36
  @record: untyped
@@ -34,6 +39,8 @@ module PaperTrailDiff
34
39
 
35
40
  @to: untyped
36
41
 
42
+ @traversal: AssociationTraversal
43
+
37
44
  @tree: AssociationTree
38
45
 
39
46
  @view: ActivityView
@@ -41,42 +48,67 @@ module PaperTrailDiff
41
48
  # : () -> Array[ActivityStep]
42
49
  def no_steps: () -> Array[ActivityStep]
43
50
 
44
- # Every boundary in the span, filtered out or not. A filter narrows where the
45
- # span starts and ends, but the sequence inside it stays complete: dropping
46
- # boundaries would fold the changes they carried into a neighbouring step and
47
- # credit them to whoever made that one. A filter that keeps no version
48
- # leaves no span, as it does for a checkpoint timeline.
49
- # : () -> Array[ActivityStep]
50
- def build_between_versions: () -> Array[ActivityStep]
51
-
52
- # Activity from the first to the last of the root versions.
53
- # : (Array[untyped]) -> ActivityHistory
54
- def version_history: (Array[untyped]) -> ActivityHistory
55
-
56
- # : () -> Array[ActivityStep]
57
- def build_to_current: () -> Array[ActivityStep]
58
-
59
- # : () -> Analysis
60
- def analyze_current: () -> Analysis
51
+ # Each kind of range replays into the same things, or into nil when it
52
+ # reports no step: its plan and history, the steps it reports, ending with
53
+ # the one that closes the range after its last event, the state it ends
54
+ # at, and the live record's snapshot and when it was read, which the root
55
+ # timeline's closing step reads.
56
+ # : (RootVersionPlan, ActivityHistory, ActivityStep?, RecordSnapshot?, ?RecordSnapshot?, ?untyped) -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
57
+ def replayed: (RootVersionPlan, ActivityHistory, ActivityStep?, RecordSnapshot?, ?RecordSnapshot?, ?untyped) -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
58
+
59
+ # : ([RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?) -> Array[ActivityStep]
60
+ def steps_of: ([ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?) -> Array[ActivityStep]
61
+
62
+ # A range that reports no step is empty, whatever its replay read: a
63
+ # version filter may keep nothing in it, or only the version that ends it,
64
+ # which opens no step, and a range may run from a version to itself.
65
+ # : ([RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?) -> Analysis
66
+ def analysis: ([ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?) -> Analysis
67
+
68
+ # Every boundary between the endpoints, filtered out or not: dropping one
69
+ # would fold the change it carried into a neighbouring step and credit it
70
+ # to whoever made that one. A version filter decides only which of the
71
+ # steps are reported (see #reported?). Only the activity view gains the
72
+ # closing removal. The endpoint diff and the root timeline keep their
73
+ # `compare` and `timeline` semantics, under which the state at a destroy
74
+ # version is the state before the deletion.
75
+ # : () -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
76
+ def version_replay: () -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
77
+
78
+ # Activity replays every root version in the range, even those a version
79
+ # filter leaves out, so that each change it keeps is read as the whole
80
+ # history shows it. Only a window reads a context: an explicit range
81
+ # always holds a version.
82
+ # : () -> RootVersionPlan
83
+ def select_plan: () -> RootVersionPlan
84
+
85
+ # Whether the event's step is reported: it is inside the range, and a
86
+ # version filter keeps it. With associations the filter keeps whole
87
+ # transactions (see ActivityScopeFilter). On the root alone it keeps the
88
+ # root's versions, as `timeline` does, and so does a plan without one, but
89
+ # for the version it holds only to reveal the last change in it.
90
+ # : (ActivityEvent, RootVersionPlan) -> bool
91
+ def reported?: (ActivityEvent, RootVersionPlan) -> bool
61
92
 
62
93
  # The explicit live endpoint and a batch's live closing endpoint use the
63
- # same selected plan. A version filter can close earlier, on its successor.
64
- # : () -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
65
- def current_history: () -> [ RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary? ]
94
+ # same selected plan, which replays every version through to the current
95
+ # record, a version filter or not.
96
+ # : () -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
97
+ def current_replay: () -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
66
98
 
67
- # Events up to the instant the current record was read. A range that a
68
- # version filter closes earlier ends at that version, with no snapshot.
69
- # : (RootVersionPlan, RecordSnapshot?, untyped) -> ActivityHistory
70
- def history_until: (RootVersionPlan, RecordSnapshot?, untyped) -> ActivityHistory
99
+ # A range that closes after its last event ends at what closed it: the
100
+ # live row, or nothing after a destroy, where no live row is read. One
101
+ # that does not ends at the state its last reported step reached.
102
+ # : (RootVersionPlan, ActivityHistory, untyped, untyped, RecordSnapshot?) -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
103
+ def live_replay: (RootVersionPlan, ActivityHistory, untyped, untyped, RecordSnapshot?) -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
71
104
 
72
- # Without a closing boundary nothing reads the closing pair, so its
73
- # mutations cannot change an answer.
74
- # mutant:disable
75
- # : (RootVersionPlan) -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
76
- def empty_history: (RootVersionPlan) -> [ RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary? ]
105
+ # : (RootVersionPlan, ?RecordSnapshot?, ?untyped) -> ActivityHistory
106
+ def history_until: (RootVersionPlan, ?RecordSnapshot?, ?untyped) -> ActivityHistory
77
107
 
78
- # : (untyped) -> ActivityBoundary
79
- def current_boundary: (untyped) -> ActivityBoundary
108
+ # The range's events up to its last root version, or to the instant the
109
+ # live record it closes on was read, with the history they are read from.
110
+ # : (RootVersionPlan, untyped) -> [Array[ActivityEvent], untyped]
111
+ def range_events: (RootVersionPlan, untyped) -> [ Array[ActivityEvent], untyped ]
80
112
 
81
113
  # : () -> [RecordSnapshot?, untyped]
82
114
  def capture_current: () -> [ RecordSnapshot?, untyped ]
@@ -84,97 +116,54 @@ module PaperTrailDiff
84
116
  # : () -> void
85
117
  def validate_current_range!: () -> void
86
118
 
87
- # Appends the transition into an explicit closing boundary, which is either
88
- # a requested current record or the absence a final root destroy leaves.
89
- # Either follows the root versions, which are themselves events, so the
90
- # last boundary the history kept opens it.
91
- # : (ActivityHistory, ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
92
- def activity_steps: (ActivityHistory, ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
93
-
94
- # A destroyed root has no later version, but its own event states that
95
- # nothing follows it, so the removal can still close the timeline.
96
- # : (Array[untyped]) -> ActivityBoundary?
97
- def destroyed_boundary: (Array[untyped]) -> ActivityBoundary?
98
-
99
- # Only the activity view gains the closing removal. The endpoint diff and
100
- # the root timeline keep their `compare` and `timeline` semantics, under
101
- # which the state at a destroy version is the state before the deletion.
102
- # : (RootVersionPlan, ActivityHistory) -> Analysis
103
- def build_analysis: (RootVersionPlan, ActivityHistory) -> Analysis
104
-
105
- # : () -> Array[ActivityStep]
106
- def window_steps: () -> Array[ActivityStep]
107
-
108
- # : () -> Analysis
109
- def analyze_window: () -> Analysis
110
-
111
- # A window with a closing step ends at what closed it: the live row, or
112
- # nothing after a destroy, where no live row is read. One that ends before
113
- # a later event ends at the state that event found.
114
- # : (ActivityHistory, ActivityStep?, RecordSnapshot?) -> RecordSnapshot?
115
- def window_final_snapshot: (ActivityHistory, ActivityStep?, RecordSnapshot?) -> RecordSnapshot?
116
-
117
- # : () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
118
- def window_history: () -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
119
-
120
- # Nothing reads a window's closing step, live snapshot, or capture time
121
- # when it reported nothing, so mutations of those cannot change an answer.
122
- # mutant:disable
123
- # : (RootVersionPlan) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
124
- def empty_window: (RootVersionPlan) -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
125
-
126
- # A window with no selected event reports nothing. Any other has a
127
- # boundary after its last one: the plan refuses a window that has no later
128
- # version, ends on no destroy, and does not close on the live row.
129
- # : (RootVersionPlan, untyped) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
130
- def window_replay: (RootVersionPlan, untyped) -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
131
-
132
- # One live read serves both the closing activity step and the endpoint the
133
- # analysis reports, which would otherwise reconstruct the graph twice.
134
- # : (RootVersionPlan) -> RecordSnapshot?
135
- def window_live_snapshot: (RootVersionPlan) -> RecordSnapshot?
136
-
137
- # Root versions inside the window that the plan does not report are context
138
- # rather than mutations: the version appended to reveal the last selected
139
- # change, and anything a filter excluded but the replay still walks. Neither
140
- # may be counted as a selected mutation. Descendant events are not filtered,
141
- # so window membership is the whole test for them.
142
- # : (Array[ActivityEvent], RootVersionPlan) -> Array[ActivityEvent]
143
- def selected_events: (Array[ActivityEvent], RootVersionPlan) -> Array[ActivityEvent]
144
-
145
- # A window either closes on the absence its final destruction leaves, or on
146
- # current state when it reaches past everything recorded. Both are boundaries
147
- # no version can supply.
119
+ # A window with no selected event reports nothing, and so does one whose
120
+ # replay left out every event it selected, each of a record outside the
121
+ # tree throughout, such as a comment created outside a scope. Any other
122
+ # has a boundary after its last event: the plan refuses a window that has
123
+ # no later version, ends on no destroy, and does not close on the live row.
124
+ #
125
+ # A window closing on current state runs to the instant it is captured,
126
+ # not to the last root version, or descendants that moved after that
127
+ # version would be missing from a report that claims to reach now.
128
+ # : () -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
129
+ def window_replay: () -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
130
+
131
+ # The live record is read only once something in the window is reported.
132
+ # : (RootVersionPlan, untyped, untyped) -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
133
+ def window_activity: (RootVersionPlan, untyped, untyped) -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
134
+
135
+ # The step that closes the range after its last event, which is reported
136
+ # as that event's step would be. It runs from the last boundary the
137
+ # history kept into one no version can supply: the live record the range
138
+ # closes on, or the absence a final root destroy leaves.
148
139
  #
149
140
  # Everything recorded means on every requested path, not only the root's
150
- # own versions. When an association changed after the window, its last
151
- # step already ends at that change, at the state the window left; closing
152
- # on current state would add the later change to a window it was not in.
153
- # : (ActivityHistory, ActivityEvent, RootVersionPlan, untyped, RecordSnapshot?, Array[ActivityEvent]) -> ActivityStep?
154
- def window_closing: (ActivityHistory, ActivityEvent, RootVersionPlan, untyped, RecordSnapshot?, Array[ActivityEvent]) -> ActivityStep?
155
-
156
- # : (ActivityHistory, ActivityEvent) -> ActivityStep
157
- def window_destroyed_step: (ActivityHistory, ActivityEvent) -> ActivityStep
158
-
159
- # The last boundary reached is where current state is compared from, which
160
- # is the final event rather than the final root version once descendants
161
- # have moved since it. A selected event is a boundary the history kept.
162
- # : (ActivityHistory, untyped, untyped, RecordSnapshot?) -> ActivityStep
163
- def window_current_step: (ActivityHistory, untyped, untyped, RecordSnapshot?) -> ActivityStep
164
-
165
- # : (ActivityEvent) -> bool
166
- def terminal_destroy?: (ActivityEvent) -> bool
141
+ # own versions. When an association changed after a window, its last step
142
+ # already ends at that change, at the state the window left, and that
143
+ # change is the last kept event, outside the window; closing on current
144
+ # state would add it to a window it was not in. A plan that does not close
145
+ # on the current record holds a version after the window, which is such a
146
+ # change, or ends at a destruction.
147
+ # : (ActivityHistory, RootVersionPlan, ?untyped, ?untyped, ?RecordSnapshot?) -> ActivityStep?
148
+ def closing_step: (ActivityHistory, RootVersionPlan, ?untyped, ?untyped, ?RecordSnapshot?) -> ActivityStep?
149
+
150
+ # Without a live record to close on, a range closes only on the root's
151
+ # destruction, and its last event is then the root's own: the version
152
+ # that ends an explicit range, or a window's version after it, or the
153
+ # destroy nothing follows.
154
+ # : (ActivityEvent?, RootVersionPlan, untyped, untyped) -> ActivityBoundary?
155
+ def closing_boundary: (ActivityEvent?, RootVersionPlan, untyped, untyped) -> ActivityBoundary?
167
156
 
168
157
  # : () -> void
169
158
  def reject_live_habtm!: () -> void
170
159
 
171
- # : () -> Array[String]?
172
- def root_recorded: () -> Array[String]?
160
+ # : () -> RecordedChangesReader?
161
+ def root_recorded: () -> RecordedChangesReader?
173
162
 
174
163
  # A window prepares from its start, explicit endpoints from their first
175
164
  # version.
176
- # : (Array[untyped], ?end_at: untyped) -> untyped
177
- def prepare_history: (Array[untyped], ?end_at: untyped) -> untyped
165
+ # : (Array[untyped], end_at: untyped) -> untyped
166
+ def prepare_history: (Array[untyped], end_at: untyped) -> untyped
178
167
 
179
168
  # A window collects from its start, explicit endpoints from their first
180
169
  # version. Explicit endpoints also stop before the rest of the closing
@@ -183,21 +172,26 @@ module PaperTrailDiff
183
172
  # : (Array[untyped], untyped, range_end: untyped) -> Array[ActivityEvent]
184
173
  def collect_events: (Array[untyped], untyped, range_end: untyped) -> Array[ActivityEvent]
185
174
 
186
- # Events after the last root version read the root from the live record
187
- # when the range closes on it. Explicit endpoints report every step, as
188
- # their range includes every version.
189
- # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?closing: RecordSnapshot?) -> ActivityHistory
190
- def replay: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?closing: RecordSnapshot?) -> ActivityHistory
175
+ # A version filter reads its answers for a batch's history once, for the
176
+ # first root that history serves.
177
+ # : (untyped, Array[ActivityEvent]) -> void
178
+ def prepare_filter: (untyped, Array[ActivityEvent]) -> void
191
179
 
192
- # The step from the last boundary the history reached to one that closes
193
- # the range.
194
- # : (ActivityHistory, ActivityBoundary, ActivityBoundary, RecordSnapshot?) -> ActivityStep
195
- def step_from_last: (ActivityHistory, ActivityBoundary, ActivityBoundary, RecordSnapshot?) -> ActivityStep
180
+ # Events after the last root version read the root from the live record
181
+ # when the range closes on it. Explicit endpoints report every step their
182
+ # plan does, as their range includes every version.
183
+ # : (RootVersionPlan, Array[ActivityEvent], untyped, current: untyped, closing: RecordSnapshot?) -> ActivityHistory
184
+ def replay: (RootVersionPlan, Array[ActivityEvent], untyped, current: untyped, closing: RecordSnapshot?) -> ActivityHistory
185
+
186
+ # The root as a change row's `record` would name it. A root is a record,
187
+ # or a deleted one rebuilt from its destroy (see DeletedAnalysisBatch).
188
+ # A reference reads its type with `to_s`, so mutant cannot tell the class
189
+ # from its name here.
190
+ # mutant:disable
191
+ # : () -> RecordReference
192
+ def root_reference: () -> RecordReference
196
193
 
197
194
  # : (Array[ActivityStep]) -> Array[ActivityStep]
198
195
  def present: (Array[ActivityStep]) -> Array[ActivityStep]
199
-
200
- # : (RootVersionPlan, ActivityHistory, final: RecordSnapshot?, steps: Array[ActivityStep], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Analysis
201
- def analysis: (RootVersionPlan, ActivityHistory, final: RecordSnapshot?, steps: Array[ActivityStep], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Analysis
202
196
  end
203
197
  end
@@ -14,14 +14,28 @@ module PaperTrailDiff
14
14
  # PT-AT reads associations as they were before a transaction, so a record
15
15
  # is judged by two snapshots: the one at its transaction's first event, and
16
16
  # the one after its last, which is the next event's or what the range
17
- # closes on. A record in neither was outside the tree throughout.
17
+ # closes on. A root version inside the transaction is the exception: it
18
+ # reads the has_and_belongs_to_many members it records, including a record
19
+ # the transaction created before it, so the snapshots at the transaction's
20
+ # root events are read too. A tag created, attached and detached again
21
+ # before the next root version is in the tree only there. A record in none
22
+ # of these was outside the tree throughout.
18
23
  #
19
- # The root's own events are always kept, and so are the versions of a
20
- # through's join rows, which a snapshot does not hold, and an event whose
21
- # step is not reported, which only bounds one that is.
24
+ # The root's own events are always kept, and so is an event whose step is
25
+ # not reported, which only bounds one that is, unless its transaction has an
26
+ # event whose step is: the transaction crossed the window's end. A version
27
+ # it saved after the edge reads each record as it stood before the
28
+ # transaction, so a step ending there shows none of its changes. Judged
29
+ # like the rest, as the window after the edge judges it, the event bounds
30
+ # that step when the later window reports the transaction; left out, the
31
+ # step runs past it and reports the changes here instead (see
32
+ # ActivityHistoryBuilder#consume). A snapshot does not hold a through's join
33
+ # rows, so their versions are judged when they are collected, by the row's
34
+ # own state (PreparedActivityIndex#join_versions), and kept here.
22
35
  class ActivityTreeFilter
23
- # `closing` is the snapshot after the last event: the current record's,
24
- # or nil when nothing follows, as after the root's destruction.
36
+ # `reported` says whether an event's step is reported. `closing` is the
37
+ # snapshot after the last event: the current record's, or nil when
38
+ # nothing follows, as after the root's destruction.
25
39
  # : (Array[ActivityEvent], reported: untyped, closing: RecordSnapshot?) -> void
26
40
  def initialize: (Array[ActivityEvent], reported: untyped, closing: RecordSnapshot?) -> void
27
41
 
@@ -36,8 +50,14 @@ module PaperTrailDiff
36
50
 
37
51
  @ends: Array[Integer]
38
52
 
53
+ @judged: Set[Array[untyped] | Integer]
54
+
55
+ @keys: Array[Array[untyped] | Integer]
56
+
39
57
  @reported: untyped
40
58
 
59
+ @roots: Hash[Array[untyped] | Integer, Array[Integer]]
60
+
41
61
  @starts: Array[Integer]
42
62
 
43
63
  @types: Hash[String, Array[String?]]
@@ -45,14 +65,27 @@ module PaperTrailDiff
45
65
  # : (ActivityEvent, Integer, Array[[ActivityEvent, RecordSnapshot?]]) -> bool
46
66
  def keep?: (ActivityEvent, Integer, Array[[ ActivityEvent, RecordSnapshot? ]]) -> bool
47
67
 
68
+ # The snapshots at the first event and the root events of the event's
69
+ # transaction, and the one after its last event.
70
+ # : (Integer, Array[untyped] | Integer, Array[[ActivityEvent, RecordSnapshot?]]) -> Array[RecordSnapshot?]
71
+ def judged_by: (Integer, Array[untyped] | Integer, Array[[ ActivityEvent, RecordSnapshot? ]]) -> Array[RecordSnapshot?]
72
+
48
73
  # : (ActivityEvent) -> bool
49
74
  def reported?: (ActivityEvent) -> bool
50
75
 
51
76
  # Where each event's transaction starts, and the position just past its
52
77
  # last event. Two transactions can interleave, so a transaction's events
53
78
  # need not be adjacent.
54
- # : (Array[ActivityEvent]) -> [Array[Integer], Array[Integer]]
55
- def spans: (Array[ActivityEvent]) -> [ Array[Integer], Array[Integer] ]
79
+ # : (Array[Array[untyped] | Integer]) -> [Array[Integer], Array[Integer]]
80
+ def spans: (Array[Array[untyped] | Integer]) -> [ Array[Integer], Array[Integer] ]
81
+
82
+ # Where each transaction's root events are.
83
+ # : (Array[ActivityEvent]) -> Hash[Array[untyped] | Integer, Array[Integer]]
84
+ def root_positions: (Array[ActivityEvent]) -> Hash[Array[untyped] | Integer, Array[Integer]]
85
+
86
+ # The transactions that have an event whose step is reported.
87
+ # : (Array[ActivityEvent]) -> Set[Array[untyped] | Integer]
88
+ def reported_transactions: (Array[ActivityEvent]) -> Set[Array[untyped] | Integer]
56
89
 
57
90
  # A version saved outside a transaction is a transaction of its own,
58
91
  # keyed by its position.