paper_trail_diff 0.17.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +648 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +15 -23
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +194 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
@@ -0,0 +1,28 @@
1
+ # Generated from lib/paper_trail_diff/activity_transaction_applier.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Applies the versions of one transaction to a snapshot, each to the record
5
+ # it saved, as a version alone in its transaction is applied. A transaction's
6
+ # changes appear together at the event after its last, so the snapshot there
7
+ # is the one before it with every one of its versions applied; reading the
8
+ # branches again instead costs every record in them.
9
+ class ActivityTransactionApplier
10
+ # : (ActivityEventSnapshotRefresher, ActivityRootSnapshotRefresher) -> void
11
+ def initialize: (ActivityEventSnapshotRefresher, ActivityRootSnapshotRefresher) -> void
12
+
13
+ # nil when any event cannot be applied to the snapshot alone. Applying
14
+ # only some would leave a record as no version left it.
15
+ # : (untyped, untyped, RecordSnapshot, Array[ActivityEvent]) -> RecordSnapshot?
16
+ def call: (untyped, untyped, RecordSnapshot, Array[ActivityEvent]) -> RecordSnapshot?
17
+
18
+ private
19
+
20
+ @event_refresher: ActivityEventSnapshotRefresher
21
+
22
+ @root_refresher: ActivityRootSnapshotRefresher
23
+
24
+ # A record on several branches is applied on each.
25
+ # : (untyped, untyped, RecordSnapshot, ActivityEvent) -> [bool, RecordSnapshot?]
26
+ def apply: (untyped, untyped, RecordSnapshot, ActivityEvent) -> [ bool, RecordSnapshot? ]
27
+ end
28
+ end
@@ -21,23 +21,19 @@ module PaperTrailDiff
21
21
  # before the next root version is in the tree only there. A record in none
22
22
  # of these was outside the tree throughout.
23
23
  #
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
24
+ # The root's own events are always kept. Every other event is judged,
25
+ # whether or not its step is reported: one left in only bounds a reported
26
+ # step, and which records' events a history holds depends on what else was
27
+ # read with it, so an event of a record outside the tree would bound a step
28
+ # in one read and not in another. A snapshot does not hold a through's join
33
29
  # rows, so their versions are judged when they are collected, by the row's
34
- # own state (PreparedActivityIndex#join_versions), and kept here.
30
+ # own state (PreparedActivityIndex#join_versions), and kept here where
31
+ # their transaction changed what the row's branches hold.
35
32
  class ActivityTreeFilter
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.
39
- # : (Array[ActivityEvent], reported: untyped, closing: RecordSnapshot?) -> void
40
- def initialize: (Array[ActivityEvent], reported: untyped, closing: RecordSnapshot?) -> void
33
+ # `closing` is the snapshot after the last event: the current record's,
34
+ # or nil when nothing follows, as after the root's destruction.
35
+ # : (Array[ActivityEvent], closing: RecordSnapshot?) -> void
36
+ def initialize: (Array[ActivityEvent], closing: RecordSnapshot?) -> void
41
37
 
42
38
  # Yields each event of the sequence with its snapshot, and whether to keep
43
39
  # it, in order.
@@ -50,28 +46,47 @@ module PaperTrailDiff
50
46
 
51
47
  @ends: Array[Integer]
52
48
 
53
- @judged: Set[Array[untyped] | Integer]
54
-
55
49
  @keys: Array[Array[untyped] | Integer]
56
50
 
57
- @reported: untyped
58
-
59
51
  @roots: Hash[Array[untyped] | Integer, Array[Integer]]
60
52
 
61
53
  @starts: Array[Integer]
62
54
 
63
55
  @types: Hash[String, Array[String?]]
64
56
 
65
- # : (ActivityEvent, Integer, Array[[ActivityEvent, RecordSnapshot?]]) -> bool
66
- def keep?: (ActivityEvent, Integer, Array[[ ActivityEvent, RecordSnapshot? ]]) -> bool
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
-
73
- # : (ActivityEvent) -> bool
74
- def reported?: (ActivityEvent) -> bool
57
+ # Whether to keep each event. The snapshots are gone through once, in
58
+ # order, each answering for the events it judges (see SnapshotMembers):
59
+ # looking through a snapshot for each event made a replay's time grow
60
+ # with its events times the records of the tree.
61
+ # : (Array[[ActivityEvent, RecordSnapshot?]]) -> Array[bool]
62
+ def kept: (Array[[ ActivityEvent, RecordSnapshot? ]]) -> Array[bool]
63
+
64
+ # The root's own events are kept whatever else holds, and so is a join
65
+ # row whose transaction changed a branch it is a join row of. Its
66
+ # versions were judged when they were collected, by where the row leads,
67
+ # but a row can lead somewhere before the owner it joins is in the tree,
68
+ # or lead to records with nothing to show, and a row of a through that
69
+ # goes through another is on its path by rows further down, which its
70
+ # own state cannot show: its transaction then leaves those branches as
71
+ # it found them. Under any other branch the row is judged as any record.
72
+ # : (Array[ActivityEvent], Array[RecordSnapshot?]) -> Array[bool]
73
+ def unjudged: (Array[ActivityEvent], Array[RecordSnapshot?]) -> Array[bool]
74
+
75
+ # : (Array[RecordSnapshot?], Array[String], Integer) -> bool
76
+ def changed?: (Array[RecordSnapshot?], Array[String], Integer) -> bool
77
+
78
+ # A missing snapshot, after the root's destruction, and a branch the
79
+ # snapshot does not hold, as before the root's creation, hold no records.
80
+ # : (RecordSnapshot?, String) -> Array[untyped]
81
+ def branch: (RecordSnapshot?, String) -> Array[untyped]
82
+
83
+ # The events each snapshot judges, by the snapshot's position, the one
84
+ # after the last event being what the range closes on: an event is judged
85
+ # by the snapshots at the first event and the root events of its
86
+ # transaction, and by the one after its last event. An event kept
87
+ # already is not asked about again (see #kept).
88
+ # : (Array[[ActivityEvent, RecordSnapshot?]]) -> Array[Array[Integer]]
89
+ def judged: (Array[[ ActivityEvent, RecordSnapshot? ]]) -> Array[Array[Integer]]
75
90
 
76
91
  # Where each event's transaction starts, and the position just past its
77
92
  # last event. Two transactions can interleave, so a transaction's events
@@ -83,20 +98,13 @@ module PaperTrailDiff
83
98
  # : (Array[ActivityEvent]) -> Hash[Array[untyped] | Integer, Array[Integer]]
84
99
  def root_positions: (Array[ActivityEvent]) -> Hash[Array[untyped] | Integer, Array[Integer]]
85
100
 
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]
89
-
90
101
  # A version saved outside a transaction is a transaction of its own,
91
102
  # keyed by its position.
92
103
  # : (Array[ActivityEvent]) -> Array[Array[untyped] | Integer]
93
104
  def transaction_keys: (Array[ActivityEvent]) -> Array[Array[untyped] | Integer]
94
105
 
95
- # : (RecordSnapshot?, ActivityEvent) -> bool
96
- def holds?: (RecordSnapshot?, ActivityEvent) -> bool
97
-
98
- # : (AssociationSnapshot, Array[String?], untyped) -> bool
99
- def contains?: (AssociationSnapshot, Array[String?], untyped) -> bool
106
+ # : (SnapshotMembers, ActivityEvent) -> bool
107
+ def holds?: (SnapshotMembers, ActivityEvent) -> bool
100
108
 
101
109
  # A version names its record's base class, and a snapshot the record's
102
110
  # own class, which may be any subclass of it.
@@ -0,0 +1,45 @@
1
+ # Generated from lib/paper_trail_diff/activity_tree_places.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Says whether an event on a record of some model can be applied to the
5
+ # one place the record has in a snapshot.
6
+ #
7
+ # A path can lead to a record twice: an article read with `author.articles`
8
+ # is the root and one of its author's articles, and under
9
+ # `articles.comments.article` an article is a member of a collection and
10
+ # the target of a `belongs_to` below it. An event is applied to a snapshot
11
+ # in one way, as the root's, a collection member's, or a target's, so it
12
+ # reaches the places of that one kind and would leave the others as they
13
+ # were. Such an event has its branches, or for the root the whole snapshot,
14
+ # read again instead.
15
+ class ActivityTreePlaces
16
+ # : (AssociationTraversal) -> void
17
+ def initialize: (AssociationTraversal) -> void
18
+
19
+ # Whether every place the tree gives records of the type is of one kind.
20
+ # A polymorphic `belongs_to` can point at a record of any model, so a
21
+ # tree with one gives every model a place there too.
22
+ # : (untyped, String) -> bool
23
+ def one_kind?: (untyped, String) -> bool
24
+
25
+ private
26
+
27
+ @kinds: Hash[untyped, Hash[String, Array[Symbol]]]
28
+
29
+ @polymorphic: Hash[untyped, bool]
30
+
31
+ @traversal: AssociationTraversal
32
+
33
+ # The kinds of place each model has under this root, by base class name.
34
+ # : (untyped) -> Hash[String, Array[Symbol]]
35
+ def kinds_for: (untyped) -> Hash[String, Array[Symbol]]
36
+
37
+ # : (untyped, untyped, AssociationTree, String, Hash[String, Array[Symbol]]) -> void
38
+ def collect: (untyped, untyped, AssociationTree, String, Hash[String, Array[Symbol]]) -> void
39
+
40
+ # A through holds its target, and the records it joins through decide
41
+ # what it holds, so each of them has a place of its own kind there.
42
+ # : (untyped, Hash[String, Array[Symbol]]) -> void
43
+ def place: (untyped, Hash[String, Array[Symbol]]) -> void
44
+ end
45
+ end
@@ -9,12 +9,20 @@ module PaperTrailDiff
9
9
  def initialize: (untyped, root_versions: Array[untyped], traversal: AssociationTraversal, range_start: untyped, range_end: untyped, prepared: PreparedActivityIndex?) -> void
10
10
 
11
11
  # A tie between version tables, or between ids that do not count up,
12
- # raises rather than building a timeline in an arbitrary order.
12
+ # raises rather than building a timeline in an arbitrary order. The events
13
+ # are in the order their transactions end (see TransactionEnds).
13
14
  # : () -> Array[ActivityEvent]
14
15
  def call: () -> Array[ActivityEvent]
15
16
 
17
+ # Where the transactions of the collected events take effect, once #call
18
+ # has ordered them by it.
19
+ # : () -> TransactionEnds?
20
+ attr_reader ends: untyped
21
+
16
22
  private
17
23
 
24
+ @ends: TransactionEnds?
25
+
18
26
  @prepared: PreparedActivityIndex
19
27
 
20
28
  @range: ActivityRange
@@ -27,6 +35,12 @@ module PaperTrailDiff
27
35
 
28
36
  @traversal: AssociationTraversal
29
37
 
38
+ # : (Array[ActivityEvent]) -> Array[ActivityEvent]
39
+ def ordered: (Array[ActivityEvent]) -> Array[ActivityEvent]
40
+
41
+ # : (Array[untyped]) -> TransactionEnds
42
+ def transaction_ends: (Array[untyped]) -> TransactionEnds
43
+
30
44
  # Each event is credited to the top-level association it was reached
31
45
  # through.
32
46
  # : (Hash[Symbol, untyped], AssociationTree, path: String, branch: String?) -> void
@@ -44,6 +58,12 @@ module PaperTrailDiff
44
58
  # : (Hash[Symbol, untyped], untyped, String) -> Array[Hash[Symbol, untyped]]
45
59
  def through_groups: (Hash[Symbol, untyped], untyped, String) -> Array[Hash[Symbol, untyped]]
46
60
 
61
+ # The targets a through reaches by a `belongs_to` name the join rows that
62
+ # lead to them, which judge them as join rows of a through over this one
63
+ # (see PreparedActivityIndex#join_versions).
64
+ # : (Hash[Symbol, untyped], untyped, Array[Hash[Symbol, untyped]]) -> Array[Hash[Symbol, untyped]]
65
+ def led: (Hash[Symbol, untyped], untyped, Array[Hash[Symbol, untyped]]) -> Array[Hash[Symbol, untyped]]
66
+
47
67
  # Every target the owners pointed at in the range, not only those their own
48
68
  # changes there recorded: an author renamed under an article nobody edited
49
69
  # is still that article's activity. Prepared history holds every target its
@@ -52,19 +72,9 @@ module PaperTrailDiff
52
72
  # : (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
53
73
  def belongs_to_groups: (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
54
74
 
55
- # With no children, nothing below them is read: prepared history registers
56
- # only the classes it loaded records of.
57
75
  # : (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
58
76
  def direct_child_groups: (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
59
77
 
60
- # : (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
61
- def habtm_groups: (untyped, Array[untyped], untyped) -> Array[Hash[Symbol, untyped]]
62
-
63
- # A type a polymorphic row stored that names no class has no versions to
64
- # read.
65
- # : (Array[untyped], untyped) ?{ (untyped, untyped) -> bool } -> Array[Hash[Symbol, untyped]]
66
- def identity_groups: (Array[untyped], untyped) ?{ (untyped, untyped) -> bool } -> Array[Hash[Symbol, untyped]]
67
-
68
78
  # Each target once, however many rows name it, and none for a row that
69
79
  # names none. The registry keeps a version once, and a missing target has
70
80
  # no versions, so this only saves reading them again, which is why mutant
@@ -13,9 +13,9 @@ module PaperTrailDiff
13
13
 
14
14
  attr_reader to_snapshot: RecordSnapshot?
15
15
 
16
- # The time window the analysis covers, or nil without one; a report's has
17
- # no end. It is the window asked for unless a transaction crossed an edge,
18
- # which moves the edge back to where that transaction began.
16
+ # The time window asked for, or nil without one; a report's has no end.
17
+ # It does not move: a transaction that crossed an edge is reported in the
18
+ # window it ended in.
19
19
  attr_reader window: Range[Time?]?
20
20
 
21
21
  # The result for a record whose requested history contains no versions,
@@ -32,8 +32,9 @@ module PaperTrailDiff
32
32
  # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?window: Range[Time?]?) -> void
33
33
  def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?window: Range[Time?]?) -> void
34
34
 
35
- # The same result for the window it was read in, which the caller knows
36
- # once it has moved the window's edges to transactions.
35
+ # The same result for the window it was asked in. A batch reads a root
36
+ # over a wider range when a transaction was open at the window's start,
37
+ # and reports the window as asked.
37
38
  # : (TimeRange?) -> Analysis
38
39
  def with_window: (TimeRange?) -> Analysis
39
40
 
@@ -5,10 +5,8 @@ module PaperTrailDiff
5
5
  # versions and preparing their association history once for the whole batch
6
6
  # rather than once per root.
7
7
  class AnalysisBatch
8
- # `traversal` names the requested paths, which decide where a window's
9
- # edges move (see TransactionCut).
10
- # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, version_scope: untyped, context_required: bool, traversal: AssociationTraversal?) -> void
11
- def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, version_scope: untyped, context_required: bool, traversal: AssociationTraversal?) -> void
8
+ # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, version_scope: untyped, context_required: bool, reach: untyped) -> void
9
+ def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, version_scope: untyped, context_required: bool, reach: untyped) -> void
12
10
 
13
11
  # : () -> Hash[identity, Analysis]
14
12
  def call: () -> Hash[identity, Analysis]
@@ -23,14 +21,18 @@ module PaperTrailDiff
23
21
 
24
22
  @live_loader: untyped
25
23
 
24
+ @reach: untyped
25
+
26
26
  @records: Array[untyped]
27
27
 
28
28
  @time_range: TimeRange?
29
29
 
30
- @traversal: AssociationTraversal?
31
-
32
30
  @version_scope: untyped
33
31
 
32
+ # Activity on associations both takes a context and replays whole plans.
33
+ # : (Hash[Array[String], untyped]) -> untyped
34
+ def planner: (Hash[Array[String], untyped]) -> untyped
35
+
34
36
  # : () -> Array[untyped]
35
37
  def validated_records: () -> Array[untyped]
36
38
  end
@@ -17,9 +17,6 @@ module PaperTrailDiff
17
17
  # : (untyped, TimeRange?) -> void
18
18
  def initialize: (untyped, TimeRange?) -> void
19
19
 
20
- # : () -> bool
21
- def available?: () -> bool
22
-
23
20
  # : (untyped) -> untyped
24
21
  def relation: (untyped) -> untyped
25
22
 
@@ -39,10 +36,6 @@ module PaperTrailDiff
39
36
  # : (untyped, String) -> Symbol?
40
37
  def column_type: (untyped, String) -> Symbol?
41
38
 
42
- # A relation is compared as its SQL; ids are compared as values.
43
- # : (untyped) -> untyped
44
- def arel_value: (untyped) -> untyped
45
-
46
39
  # The owners a child pointed at when the window opened or after a change
47
40
  # inside it, as PT-AT recorded them on the child's own versions.
48
41
  class Child < AssociationActivityEdge
@@ -62,74 +55,94 @@ module PaperTrailDiff
62
55
  def owner_types: () -> Array[String?]
63
56
  end
64
57
 
65
- # The owners that pointed at a target when the window opened or after a
66
- # change inside it, as PT-AT recorded them on the owners' versions.
67
- class BelongsTo < AssociationActivityEdge
68
- # : (untyped, TimeRange?, ?foreign_type: String?) -> void
69
- def initialize: (untyped, TimeRange?, ?foreign_type: String?) -> void
70
-
71
- # The types a polymorphic key's rows name, the only way to know its targets.
72
- # : () -> Array[String]
73
- def target_types: () -> Array[String]
74
-
75
- # The owners that pointed at a target of this edge's type when the window
76
- # opened or after a change inside it, whichever target that was.
77
- # : () -> untyped
78
- def typed_owners: () -> untyped
58
+ # The owners of children no version was ever saved for, such as rows from
59
+ # before PaperTrail: such a child has held its live key throughout, as an
60
+ # analysis reads it, and so leads to a change further down.
61
+ class Unversioned < AssociationActivityEdge
62
+ # : (untyped, TimeRange?) -> void
63
+ def initialize: (untyped, TimeRange?) -> void
79
64
 
80
65
  # : (untyped) -> untyped
81
66
  def relation: (untyped) -> untyped
82
67
 
83
68
  private
84
69
 
85
- @associations: untyped
70
+ @key: String
86
71
 
87
- @foreign_type: String?
72
+ @target: untyped
88
73
 
89
74
  @versions: untyped
90
75
 
91
- # : (Hash[Symbol, untyped]) -> untyped
92
- def owner_rows: (Hash[Symbol, untyped]) -> untyped
76
+ # A database compares the key with item_id only when they share a type.
77
+ # : () -> bool
78
+ def comparable?: () -> bool
79
+
80
+ # : () -> untyped
81
+ def versioned: () -> untyped
82
+
83
+ # The keys of the rows that have versions, read as values; a database
84
+ # casts them back to the key's type.
85
+ # : (untyped) -> Array[untyped]
86
+ def versioned_ids: (untyped) -> Array[untyped]
93
87
  end
94
88
 
95
- # The owners a HABTM join row links to a target now. A join table has no
96
- # model to type its columns, so the owner column is read by quoted name.
97
- class LiveHabtm < AssociationActivityEdge
89
+ # The owners of children whose first version since the window opened did
90
+ # not create them, such as rows from before PaperTrail that the window
91
+ # moves or detaches. PT-AT stores the keys a version saved, so the owner
92
+ # such a child held until that version is in no row, only in the
93
+ # version's stored state, as ActivityChildCandidateLoader reads it. One
94
+ # saved after the window's end holds the owner the child had there too.
95
+ class FirstVersion < AssociationActivityEdge
98
96
  # : (untyped, TimeRange?) -> void
99
97
  def initialize: (untyped, TimeRange?) -> void
100
98
 
99
+ # A create stores no state, so the first versions read are those that
100
+ # did not create their child.
101
101
  # : (untyped) -> untyped
102
102
  def relation: (untyped) -> untyped
103
103
 
104
- private
105
-
106
- @table: untyped
104
+ # The owners the first versions of the children `filter` selects name in
105
+ # their stored states. An `as:` child's type must name one of the
106
+ # owner's types, which take a child with no type, as any plain child has.
107
+ # A version with no state for the key names no owner.
108
+ # : (untyped) -> Array[untyped]
109
+ def owners: (untyped) -> Array[untyped]
107
110
 
108
- # : () -> Hash[String, Symbol?]
109
- def join_columns: () -> Hash[String, Symbol?]
111
+ # The same for children's ids read as values, in slices.
112
+ # : (Array[untyped]) -> Array[untyped]
113
+ def owners_of: (Array[untyped]) -> Array[untyped]
110
114
 
111
- # Some adapters take the quoted name as a plain string too, but a raw SQL
112
- # check may not, so it is marked as SQL; no SQLite spec can tell.
113
- # mutant:disable
114
- # : () -> untyped
115
- def quoted_owner_column: () -> untyped
115
+ @target: untyped
116
116
  end
117
117
 
118
- # The owners whose versions PT-AT recorded a HABTM target with, keyed by
119
- # the transaction each version was saved in.
120
- class RecordedHabtm < AssociationActivityEdge
121
- # : (untyped, TimeRange?) -> void
122
- def initialize: (untyped, TimeRange?) -> void
118
+ # The owners that pointed at a target when the window opened or after a
119
+ # change inside it, as PT-AT recorded them on the owners' versions.
120
+ class BelongsTo < AssociationActivityEdge
121
+ # : (untyped, TimeRange?, ?foreign_type: String?) -> void
122
+ def initialize: (untyped, TimeRange?, ?foreign_type: String?) -> void
123
123
 
124
- # : () -> bool
125
- def available?: () -> bool
124
+ # The types a polymorphic key's rows name, the only way to know its targets.
125
+ # : () -> Array[String]
126
+ def target_types: () -> Array[String]
127
+
128
+ # The owners that pointed at a target of this edge's type when the window
129
+ # opened or after a change inside it, whichever target that was.
130
+ # : () -> untyped
131
+ def typed_owners: () -> untyped
126
132
 
127
133
  # : (untyped) -> untyped
128
134
  def relation: (untyped) -> untyped
129
135
 
136
+ private
137
+
130
138
  @associations: untyped
131
139
 
140
+ @foreign_type: String?
141
+
132
142
  @versions: untyped
143
+
144
+ # : (Hash[Symbol, untyped]) -> untyped
145
+ def owner_rows: (Hash[Symbol, untyped]) -> untyped
133
146
  end
134
147
  end
135
148
  end
@@ -31,7 +31,11 @@ module PaperTrailDiff
31
31
  # : () -> Array[untyped]
32
32
  def values: () -> Array[untyped]
33
33
 
34
- # The ids with no match in `keys`, a subquery of the keys that exist.
34
+ # The ids no row of the model has for its key, whatever scope the model
35
+ # has by default. They are asked for with NOT EXISTS: PostgreSQL does
36
+ # not plan `NOT IN (SELECT ...)` as an anti-join, so it reads every key
37
+ # of the table for the statement, and again for each id once the keys
38
+ # outgrow its working memory. An empty key names no record.
35
39
  # : (untyped) -> Array[untyped]
36
40
  def missing: (untyped) -> Array[untyped]
37
41
  end
@@ -42,10 +46,17 @@ module PaperTrailDiff
42
46
  # : (Array[source]) -> Array[untyped]
43
47
  def self.values: (Array[source]) -> Array[untyped]
44
48
 
49
+ # The window roots are selected over: the one asked for, and with a tree,
50
+ # from where the earliest transaction open at its start began (see
51
+ # SelectionWindow). A window reports such a transaction, which may have
52
+ # saved a root's tree only before it.
53
+ # : (untyped, AssociationTraversal?, TimeRange?) -> TimeRange?
54
+ def self.window: (untyped, AssociationTraversal?, TimeRange?) -> TimeRange?
55
+
45
56
  # Only the versions `version_scope` keeps select a root, on its
46
57
  # associations as on its own versions.
47
- # : (untyped, tree: AssociationTree, time_range: TimeRange?, ?version_scope: untyped) -> void
48
- def initialize: (untyped, tree: AssociationTree, time_range: TimeRange?, ?version_scope: untyped) -> void
58
+ # : (untyped, traversal: AssociationTraversal, time_range: TimeRange?, ?version_scope: untyped) -> void
59
+ def initialize: (untyped, traversal: AssociationTraversal, time_range: TimeRange?, ?version_scope: untyped) -> void
49
60
 
50
61
  # The roots' ids, each source a subquery or an array of values.
51
62
  # : () -> Array[source]
@@ -69,6 +80,12 @@ module PaperTrailDiff
69
80
  # : (untyped, Array[source]) -> Array[source]
70
81
  def owners: (untyped, Array[source]) -> Array[source]
71
82
 
83
+ # The owners children held until a first version that did not create
84
+ # them, read from those versions' stored states (see
85
+ # AssociationActivityEdge::FirstVersion).
86
+ # : (untyped, Array[source]) -> Array[source]
87
+ def first_owners: (untyped, Array[source]) -> Array[source]
88
+
72
89
  # A join row that changes moves membership as surely as a target that does.
73
90
  # : (untyped, Array[source]) -> Array[source]
74
91
  def through_owners: (untyped, Array[source]) -> Array[source]
@@ -46,8 +46,8 @@ module PaperTrailDiff
46
46
  def descriptor_for: (untyped, String, untyped, bool) -> AssociationDescriptor
47
47
 
48
48
  # Only what a request accepts, so every listed path can be requested.
49
- # : (untyped, root: bool) -> Array[untyped]
50
- def supported_reflections: (untyped, root: bool) -> Array[untyped]
49
+ # : (untyped) -> Array[untyped]
50
+ def supported_reflections: (untyped) -> Array[untyped]
51
51
 
52
52
  # Every request that reads history refuses a path whose target, or a
53
53
  # model its has_many :through goes through, has no versions.
@@ -4,22 +4,13 @@ module PaperTrailDiff
4
4
  # PT-AT records which record a child pointed at by that record's id, and
5
5
  # history matches children to owners and targets by id. An association
6
6
  # keyed on another column (`primary_key:`) would read other records'
7
- # history, so it is refused.
7
+ # history, and one keyed on several columns has no single id to match, so
8
+ # both are refused.
8
9
  module AssociationKey
9
10
  # Why the association, or a part of a through, cannot be read by id.
10
11
  # : (untyped) -> String?
11
12
  def self.unsupported_reason: (untyped) -> String?
12
13
 
13
- # The association's foreign key column, or nil for a composite key, which
14
- # loaded history cannot index. Active Record names a column as a string.
15
- # : (untyped) -> String?
16
- def self.scalar_foreign_key: (untyped) -> String?
17
-
18
- # The reflection, or the first part of a through, keyed on a column other
19
- # than its owner's or target's primary key.
20
- # : (untyped) -> untyped
21
- def self.keyed_part: (untyped) -> untyped
22
-
23
14
  # A belongs_to names a key of its target; any other macro, one of its
24
15
  # owner. A polymorphic target has no single primary key to compare with.
25
16
  # : (untyped) -> bool