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,194 @@
1
+ # Generated from lib/paper_trail_diff/change_attribution.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Credits each change row to the version that made its change, which need
5
+ # not be its step's source: a transaction group starts at one record's
6
+ # event, and inside a transaction a record's change can surface at a later
7
+ # event than its own (see ActivityTransactionGrouper).
8
+ #
9
+ # The versions a record saved in the step's transaction, up to the step's
10
+ # last source, made its changes there. A field's change follows what they
11
+ # recorded of it: each run of recorded changes is credited to the version
12
+ # that ended it, or the whole change to the last of the record's versions
13
+ # when what they recorded was not read. A record that appeared or
14
+ # disappeared is credited to its own create or destroy. Any other row keeps
15
+ # the step's source: a record that joined a collection or became a to-one
16
+ # target through another record's change, for one.
17
+ #
18
+ # With recorded changes read, the part of a field's change that those
19
+ # versions did not record is split off and credited to an unversioned
20
+ # source. It was saved without a version, as with `update_columns`, and
21
+ # history reads it into the state the next version stores, or the current
22
+ # row, so it shows up beside the change before it. Only what the versions
23
+ # show is split off. The row stays whole where they cannot:
24
+ #
25
+ # - a version that recorded nothing, such as a `touch`, or a table without
26
+ # `object_changes`;
27
+ # - a column PaperTrail is told not to record (see RecordedColumns);
28
+ # - a field a create left out, which held its default when created;
29
+ # - the start of a transaction that began before the history's start (see
30
+ # PreparedHistoryLoader#reload), whose earlier versions were not read.
31
+ class ChangeAttribution
32
+ # A transaction's boundaries, in the order the history kept them. Every
33
+ # step the transaction opens shares the one list and reads the boundaries
34
+ # before its own sources, so a long transaction costs one list rather
35
+ # than one for each step. A record's boundaries are found through an
36
+ # index, built when rows are first read, once the history is complete.
37
+ # A step's own sources are kept the same way, so a transaction group's
38
+ # rows name each source's record once rather than once for each record.
39
+ class Transaction
40
+ # : (?Array[ActivityBoundary]) -> void
41
+ def initialize: (?Array[ActivityBoundary]) -> void
42
+
43
+ # : (ActivityBoundary) -> void
44
+ def add: (ActivityBoundary) -> void
45
+
46
+ # : () -> Integer
47
+ def length: () -> Integer
48
+
49
+ # Whether the boundary is one of these, not merely one like it.
50
+ # : (ActivityBoundary) -> bool
51
+ def holds?: (ActivityBoundary) -> bool
52
+
53
+ # The record's boundaries among the first `count`, in order. The block
54
+ # names a boundary's record. The index is built whole before it is
55
+ # kept, so readers on two threads build the same one.
56
+ # : (Array[String], Integer) { (ActivityBoundary) -> Array[String] } -> Array[ActivityBoundary]
57
+ def of: (Array[String], Integer) { (ActivityBoundary) -> Array[String] } -> Array[ActivityBoundary]
58
+
59
+ private
60
+
61
+ @boundaries: Array[ActivityBoundary]
62
+
63
+ @positions: Hash[Array[String], Array[Integer]]?
64
+
65
+ # : (^(ActivityBoundary) -> Array[String]) -> Hash[Array[String], Array[Integer]]
66
+ def index: (^(ActivityBoundary) -> Array[String]) -> Hash[Array[String], Array[Integer]]
67
+ end
68
+
69
+ # `root` is the record the timeline is about, which rows name by leaving
70
+ # `record` nil. `transaction` holds the boundaries of the step's
71
+ # transaction, of which the first `preceding` came before its sources;
72
+ # `complete` says whether the history holds every version that
73
+ # transaction saved before them.
74
+ # : (root: RecordReference, sources: Array[ActivityBoundary], complete: bool, transaction: Transaction, ?preceding: Integer) -> void
75
+ def initialize: (root: RecordReference, sources: Array[ActivityBoundary], complete: bool, transaction: Transaction, ?preceding: Integer) -> void
76
+
77
+ # The same transaction, read through a transaction group's sources.
78
+ # : (Array[ActivityBoundary]) -> ChangeAttribution
79
+ def with_sources: (Array[ActivityBoundary]) -> ChangeAttribution
80
+
81
+ # The row as the rows it splits into, each credited to its change's
82
+ # source: one row, unless part of its change was saved without a version.
83
+ # : (ChangeRow) -> Array[ChangeRow]
84
+ def call: (ChangeRow) -> Array[ChangeRow]
85
+
86
+ private
87
+
88
+ @complete: bool
89
+
90
+ @preceding: Integer
91
+
92
+ @root: RecordReference
93
+
94
+ @sources: Transaction
95
+
96
+ @transaction: Transaction
97
+
98
+ @versions: Hash[Array[String], Array[ActivityBoundary]]
99
+
100
+ # A field's change follows what the record's versions recorded of it,
101
+ # from the value the row starts at (see #relevant): each run of recorded
102
+ # changes is one row, credited to the version that ended it, and a value
103
+ # that moved where they do not meet was saved without a version. Where
104
+ # the row's start leads to no version, the move to the first of them is
105
+ # told apart only when the history holds the whole transaction.
106
+ # : (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
107
+ def changed: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
108
+
109
+ # The changes that make up the row's: from the last one that left the
110
+ # row's starting value; or else those after the last that reached it,
111
+ # which an earlier step reported; or else all of them, which for a root's
112
+ # own field are only the ones its sources saved. A step starts from the
113
+ # state before its source, and a root's fields are read at each of its
114
+ # versions, so the root versions its transaction saved before the sources
115
+ # are already in that state. A related record's fields are read as the
116
+ # transaction began, so those versions still count.
117
+ # : (Array[[ActivityBoundary, ValueChange]], ChangeRow) -> Array[[ActivityBoundary, ValueChange]]
118
+ def relevant: (Array[[ ActivityBoundary, ValueChange ]], ChangeRow) -> Array[[ ActivityBoundary, ValueChange ]]
119
+
120
+ # A field none of the versions recorded changed without one, when they
121
+ # record every change of it they make.
122
+ # : (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
123
+ def unrecorded: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
124
+
125
+ # Only a record's own create says what it was created with. A field the
126
+ # create left out held its default, which no version records, so a value
127
+ # there can be the default or a later write: the row stays whole, or runs
128
+ # from nothing to what the versions after the create recorded.
129
+ # : (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
130
+ def added: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
131
+
132
+ # The value's path from `start` to `finish` as links of [from, to,
133
+ # version], with nil for no version: each recorded change, and between
134
+ # them whatever moved without one. A first change that does not start
135
+ # where the row does joins the row's start unless `trusted`.
136
+ # : (untyped, untyped, Array[[ActivityBoundary, ValueChange]], bool) -> Array[[untyped, untyped, ActivityBoundary?]]
137
+ def chain: (untyped, untyped, Array[[ ActivityBoundary, ValueChange ]], bool) -> Array[[ untyped, untyped, ActivityBoundary? ]]
138
+
139
+ # A move from `value` to `to` that no version recorded, as a link; returns
140
+ # where it ends.
141
+ # : (Array[[untyped, untyped, ActivityBoundary?]], untyped, untyped) -> untyped
142
+ def bridge: (Array[[ untyped, untyped, ActivityBoundary? ]], untyped, untyped) -> untyped
143
+
144
+ # : (untyped, untyped, ActivityBoundary?) -> [untyped, untyped, ActivityBoundary?]
145
+ def link: (untyped, untyped, ActivityBoundary?) -> [ untyped, untyped, ActivityBoundary? ]
146
+
147
+ # Consecutive links of the same kind as one: recorded ones credited to the
148
+ # last of their versions.
149
+ # : (Array[[untyped, untyped, ActivityBoundary?]]) -> Array[[untyped, untyped, ActivityBoundary?]]
150
+ def merge: (Array[[ untyped, untyped, ActivityBoundary? ]]) -> Array[[ untyped, untyped, ActivityBoundary? ]]
151
+
152
+ # The first link keeps the row's own change, so an added field starts
153
+ # from nothing; its later values are changes to it.
154
+ # : (ChangeRow, Array[[untyped, untyped, ActivityBoundary?]], Symbol) -> Array[ChangeRow]
155
+ def rows_for: (ChangeRow, Array[[ untyped, untyped, ActivityBoundary? ]], Symbol) -> Array[ChangeRow]
156
+
157
+ # : (ChangeRow, Array[ActivityBoundary]) -> ChangeRow
158
+ def removed: (ChangeRow, Array[ActivityBoundary]) -> ChangeRow
159
+
160
+ # The changes the versions recorded of a field, each with its version:
161
+ # nil when one of them recorded nothing, or their changes were not read.
162
+ # : (Array[ActivityBoundary], String?) -> Array[[ActivityBoundary, ValueChange]]?
163
+ def recorded_changes: (Array[ActivityBoundary], String?) -> Array[[ ActivityBoundary, ValueChange ]]?
164
+
165
+ # A row about a whole record has no field name, which no version records.
166
+ # : (Array[ActivityBoundary]) -> Array[Hash[untyped, ValueChange]]?
167
+ def recorded: (Array[ActivityBoundary]) -> Array[Hash[untyped, ValueChange]]?
168
+
169
+ # : (ChangeRow) -> bool
170
+ def recorded_column?: (ChangeRow) -> bool
171
+
172
+ # The record's boundaries in the step's transaction, up to its last
173
+ # source, read once for each record.
174
+ # : (RecordReference) -> Array[ActivityBoundary]
175
+ def versions_of: (RecordReference) -> Array[ActivityBoundary]
176
+
177
+ # A record's base class and id, which name its row whichever subclass a
178
+ # snapshot or a version gives.
179
+ # : (RecordReference) -> Array[String]
180
+ def identity: (RecordReference) -> Array[String]
181
+
182
+ # : (String) -> String
183
+ def base_name: (String) -> String
184
+
185
+ # : (ChangeRow) -> ActivityBoundary
186
+ def unversioned: (ChangeRow) -> ActivityBoundary
187
+
188
+ # : (ChangeRow, ActivityBoundary) -> ChangeRow
189
+ def credit: (ChangeRow, ActivityBoundary) -> ChangeRow
190
+
191
+ # : (ChangeRow, source: ActivityBoundary, ?change: Symbol, ?from: untyped, ?to: untyped) -> ChangeRow
192
+ def copy: (ChangeRow, source: ActivityBoundary, ?change: Symbol, ?from: untyped, ?to: untyped) -> ChangeRow
193
+ end
194
+ end
@@ -21,12 +21,22 @@ module PaperTrailDiff
21
21
 
22
22
  attr_reader to: untyped
23
23
 
24
- # The step's source boundary: for a transaction group, its first event.
24
+ # The event that made the change: the version of the row's record that
25
+ # recorded it, or a source of kind `:unversioned` for a change saved
26
+ # without a version. A row the step's own events do not account for, such
27
+ # as a record joining a collection through another record's change, names
28
+ # the step's source boundary.
25
29
  attr_reader source: ActivityBoundary
26
30
 
27
31
  # : (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
28
32
  def initialize: (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
29
33
 
34
+ # Whether the change was saved without a version, such as with
35
+ # `update_columns`, which PaperTrail never recorded. Only told apart with
36
+ # `recorded_changes: true`.
37
+ # : () -> bool
38
+ def unversioned?: () -> bool
39
+
30
40
  # The source's identifying fields sit beside the change rather than nested,
31
41
  # so the hash is one row of a table as it stands.
32
42
  # : () -> Hash[Symbol, untyped]
@@ -50,23 +60,28 @@ module PaperTrailDiff
50
60
  #
51
61
  # Two kinds of entry add nothing a row would show. One that only groups
52
62
  # others (an edited record, an association, a relationship) is left out,
53
- # because the rows under it name the same record. A blank field of an added
63
+ # because the rows under it name the same record. A nil field of an added
54
64
  # or removed record is left out too, because the record's own row already
55
- # says it appeared or disappeared.
65
+ # says it appeared or disappeared; an empty string or false is a value.
56
66
  class ChangeRows
57
67
  RECORD_ENTRIES: untyped
58
68
 
59
- # : (Diff, source: ActivityBoundary) -> Array[ChangeRow]
60
- def self.call: (Diff, source: ActivityBoundary) -> Array[ChangeRow]
69
+ # `attribution` credits each row to the event that made its change, and
70
+ # can split one in two (see ChangeAttribution); without it, every row is
71
+ # credited to `source`.
72
+ # : (Diff, source: ActivityBoundary, ?attribution: ChangeAttribution?) -> Array[ChangeRow]
73
+ def self.call: (Diff, source: ActivityBoundary, ?attribution: ChangeAttribution?) -> Array[ChangeRow]
61
74
 
62
- # : (ActivityBoundary) -> void
63
- def initialize: (ActivityBoundary) -> void
75
+ # : (ActivityBoundary, ChangeAttribution?) -> void
76
+ def initialize: (ActivityBoundary, ChangeAttribution?) -> void
64
77
 
65
78
  # : (Diff) -> Array[ChangeRow]
66
79
  def call: (Diff) -> Array[ChangeRow]
67
80
 
68
81
  private
69
82
 
83
+ @attribution: ChangeAttribution?
84
+
70
85
  @source: ActivityBoundary
71
86
 
72
87
  # : (TraversalEntry) -> ChangeRow?
@@ -5,17 +5,16 @@ module PaperTrailDiff
5
5
  class DeletedAnalysisBatch
6
6
  # `context_required` reads a root that did not change in the window from
7
7
  # the version after it, so its associations' activity can be reported.
8
- # : (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool) -> void
9
- def initialize: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool) -> void
8
+ # `traversal` names the requested paths, which decide where a window's
9
+ # edges move (see TransactionCut).
10
+ # : (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool, traversal: AssociationTraversal?) -> void
11
+ def initialize: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool, traversal: AssociationTraversal?) -> void
10
12
 
11
13
  # : () -> Hash[Array[String], Analysis?]
12
14
  def call: () -> Hash[Array[String], Analysis?]
13
15
 
14
16
  private
15
17
 
16
- # : (untyped, RootVersionPlan, TimeRange?) -> Analysis
17
- def analysis_for: (untyped, RootVersionPlan, TimeRange?) -> Analysis
18
-
19
18
  # : (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
20
19
  def with_unavailable: (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
21
20
 
@@ -31,10 +30,15 @@ module PaperTrailDiff
31
30
 
32
31
  @time_range: TimeRange?
33
32
 
33
+ @traversal: AssociationTraversal?
34
+
34
35
  @version_scope: untyped
35
36
 
36
37
  # A root destroyed before the window had no state inside it to read, so
37
- # only the others take the version after the window as context.
38
+ # only the others take the version after the window as context. Every
39
+ # root replays the whole of its window for activity on associations: one
40
+ # whose destroy saved in a transaction that crossed the window's start
41
+ # has the destroy inside its moved window.
38
42
  # : (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
39
43
  def plans: (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
40
44
 
@@ -47,13 +51,8 @@ module PaperTrailDiff
47
51
  # : (Array[untyped]) -> Array[untyped]
48
52
  def historical_roots: (Array[untyped]) -> Array[untyped]
49
53
 
54
+ # Each statement reads the destroys of 500 records.
50
55
  # : () -> Array[untyped]
51
56
  def destroy_versions: () -> Array[untyped]
52
-
53
- # : (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
54
- def preparation_range: (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
55
-
56
- # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
57
- def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
58
57
  end
59
58
  end
@@ -6,8 +6,6 @@ module PaperTrailDiff
6
6
  # table, where a destroyed root has no row, so without this a report on one
7
7
  # account's records would include every account's deletions.
8
8
  class DeletedRootFilter
9
- SLICE: ::Integer
10
-
11
9
  # : (untyped) -> void
12
10
  def initialize: (untyped) -> void
13
11
 
@@ -1,35 +1,15 @@
1
1
  # Generated from lib/paper_trail_diff/deprecation.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Warns about options that do nothing any more and will be removed. In a
5
- # Rails app, register the deprecator to configure it with the app's own:
4
+ # Warns about options that are deprecated and will be removed. None is now,
5
+ # but the deprecator stays, so that an app that registered it still boots
6
+ # and hears of the next one. In a Rails app, register it to configure it
7
+ # with the app's own:
6
8
  #
7
9
  # Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator
8
10
  module Deprecation
9
- CLOSE_ON: ::String
10
-
11
- ALLOW_EXPENSIVE: ::String
12
-
13
- RELOAD_LIVE_ENDPOINTS: ::String
14
-
15
11
  # Required when first used, as the library loads nothing it does not need.
16
12
  # : () -> untyped
17
13
  def self.deprecator: () -> untyped
18
-
19
- # The one value close_on: took. It named what ends a wall-clock window,
20
- # so it was meaningless without one, and until it is removed it is still
21
- # checked as it was.
22
- CLOSE_ON_CURRENT: ::Symbol
23
-
24
- # : (Symbol?, untyped) -> void
25
- def self.close_on!: (Symbol?, untyped) -> void
26
-
27
- # : (untyped) -> void
28
- def self.allow_expensive!: (untyped) -> void
29
-
30
- # The value to use: the option still works until it is removed, and nil
31
- # stands for its old default.
32
- # : (untyped) -> untyped
33
- def self.reload_live_endpoints!: (untyped) -> untyped
34
14
  end
35
15
  end
@@ -7,6 +7,8 @@ module PaperTrailDiff
7
7
  # : () -> void
8
8
  def initialize: () -> void
9
9
 
10
+ # Each version is read once: activity reads a root's version again at
11
+ # every event it bounds, and decoding it is most of the cost.
10
12
  # : (untyped) -> PreparedRecordState?
11
13
  def call: (untyped) -> PreparedRecordState?
12
14
 
@@ -19,6 +21,8 @@ module PaperTrailDiff
19
21
 
20
22
  @loader: PreparedVersionStateLoader
21
23
 
24
+ @states: Hash[Array[untyped], PreparedRecordState?]
25
+
22
26
  @supported: Hash[untyped, bool]
23
27
 
24
28
  # : (untyped) -> bool
@@ -4,7 +4,7 @@ module PaperTrailDiff
4
4
  # Validates and describes explicit PaperTrail-version and live-record endpoints.
5
5
  module Endpoint
6
6
  # : (untyped, untyped) -> void
7
- def self?.validate_pair!: (untyped, untyped) -> void
7
+ def self.validate_pair!: (untyped, untyped) -> void
8
8
 
9
9
  # Two versions carry no visible cue about which is earlier, so transposing
10
10
  # them is easy to do by accident and impossible to detect afterwards: the
@@ -13,44 +13,68 @@ module PaperTrailDiff
13
13
  # change is `from`. A current-record endpoint is exempt: it is self-evidently
14
14
  # the live state, so putting it first is a deliberate reverse comparison.
15
15
  # : (untyped, untyped) -> void
16
- def self?.validate_order!: (untyped, untyped) -> void
16
+ def self.validate_order!: (untyped, untyped) -> void
17
17
 
18
18
  # : (untyped, untyped) -> bool
19
- def self?.reversed_versions?: (untyped, untyped) -> bool
19
+ def self.reversed_versions?: (untyped, untyped) -> bool
20
20
 
21
21
  # : (untyped) -> void
22
- def self?.validate!: (untyped) -> void
22
+ def self.validate!: (untyped) -> void
23
23
 
24
24
  # The record a method reads the history of: a record, saved or destroyed,
25
25
  # of a model PaperTrail versions.
26
26
  # : (untyped) -> void
27
- def self?.validate_root!: (untyped) -> void
27
+ def self.validate_root!: (untyped) -> void
28
28
 
29
- # A relation is named rather than inspected, which would load it.
30
- # : (untyped) -> String
31
- def self?.described: (untyped) -> String
29
+ # What a message names the value as. A relation is named rather than
30
+ # inspected, which would load it, and by the name Active Record gives its
31
+ # class. A class without a name is printed, as a class given itself is.
32
+ # : (untyped) -> (String | Module)
33
+ def self.described: (untyped) -> (String | Module)
32
34
 
33
35
  # : (untyped) -> bool
34
- def self?.version?: (untyped) -> bool
36
+ def self.version?: (untyped) -> bool
35
37
 
36
38
  # : (untyped) -> bool
37
- def self?.record?: (untyped) -> bool
39
+ def self.record?: (untyped) -> bool
38
40
 
39
41
  # : (untyped) -> Array[String]
40
- def self?.identity: (untyped) -> Array[String]
42
+ def self.identity: (untyped) -> Array[String]
41
43
 
42
44
  # : (untyped) -> untyped
43
- def self?.model_class: (untyped) -> untyped
45
+ def self.model_class: (untyped) -> untyped
46
+
47
+ # : (String) -> untyped
48
+ def self.model_named: (String) -> untyped
49
+
50
+ # Whether the version has an `item_subtype` to read. An Active Record
51
+ # version is asked whether it was read with the column, which costs less
52
+ # than respond_to? (see Support.per_model) and answers for this row: a
53
+ # version a caller read without the column has none.
54
+ # : (untyped) -> bool
55
+ def self.subtyped?: (untyped) -> bool
44
56
 
45
57
  # Every PaperTrail version of the record, whatever scope its versions
46
- # association has.
58
+ # association has. Active Record reads a record given as an item_id as its
59
+ # id, so mutant cannot tell `record` from `record.id` here.
60
+ # mutant:disable
47
61
  # : (untyped) -> untyped
48
- def self?.versions: (untyped) -> untyped
62
+ def self.versions: (untyped) -> untyped
49
63
 
50
64
  # : (untyped) -> untyped
51
- def self?.reload_record: (untyped) -> untyped
65
+ def self.reload_record: (untyped) -> untyped
52
66
 
53
67
  # : (untyped) -> void
54
- def self?.validate_record!: (untyped) -> void
68
+ def self.validate_record!: (untyped) -> void
69
+ end
70
+
71
+ # Whether a value is a version, a record, or neither, answered once for
72
+ # each Active Record class (see Support.per_model).
73
+ module EndpointKind
74
+ # : (untyped) -> Symbol
75
+ def self.call: (untyped) -> Symbol
76
+
77
+ # : (untyped) -> Symbol
78
+ def self.classify: (untyped) -> Symbol
55
79
  end
56
80
  end
@@ -25,15 +25,12 @@ module PaperTrailDiff
25
25
  class InvalidEndpointError < Error
26
26
  end
27
27
 
28
- # Raised when reload opt-out encounters an association that was not preloaded.
29
- class UnloadedAssociationError < InvalidEndpointError
30
- end
31
-
32
28
  # Raised when a timeline boundary is absent or the requested range is reversed.
33
29
  class InvalidTimelineRangeError < Error
34
30
  end
35
31
 
36
- # Raised when `within` is not a finite, chronological range of time-like values.
32
+ # Raised when `within` is not a chronological range of time-like values with
33
+ # a beginning.
37
34
  class InvalidTimeRangeError < InvalidTimelineRangeError
38
35
  end
39
36
 
@@ -54,12 +51,6 @@ module PaperTrailDiff
54
51
  class FilterLimitExceededError < Error
55
52
  end
56
53
 
57
- # No longer raised: `allow_approximate: true` alone accepts the paths it
58
- # refused. Kept until `allow_expensive:` is removed, so code that rescues it
59
- # still loads.
60
- class UnsupportedBatchPathError < ConfigurationError
61
- end
62
-
63
54
  # Raised when a requested ActiveRecord association does not exist.
64
55
  class UnknownAssociationError < Error
65
56
  end
@@ -10,7 +10,8 @@ module PaperTrailDiff
10
10
  def initialize: (untyped, untyped) -> void
11
11
 
12
12
  # The given transactions (one id or several) in which more than one
13
- # possible owner saved a version, as strings.
13
+ # possible owner saved a version, as strings. Each statement reads up to
14
+ # 500 of them.
14
15
  # : (untyped) -> Array[String]
15
16
  def shared: (untyped) -> Array[String]
16
17
 
@@ -8,13 +8,15 @@ module PaperTrailDiff
8
8
  # the window supply the state at its start and after every change but the
9
9
  # last. The state after the last change lives in the first version after
10
10
  # the window, or in the live row when nothing follows; a destroy leaves none.
11
+ #
12
+ # Each candidate is read over the window its analysis covers, which a
13
+ # transaction crossing an edge moves (see TransactionCut). `windows` gives
14
+ # the moved ones, keyed by id, for a slice of candidates and the window.
11
15
  class HistoricalFilter
12
16
  DEFAULT_VERSION_LIMIT: ::Integer
13
17
 
14
- CANDIDATE_BATCH: ::Integer
15
-
16
- # : (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
17
- def initialize: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
18
+ # : (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer, windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]) -> void
19
+ def initialize: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer, windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]) -> void
18
20
 
19
21
  # More matches than the limit raise, unless the caller does not count
20
22
  # them: candidates it only lists, such as deleted roots.
@@ -37,6 +39,8 @@ module PaperTrailDiff
37
39
 
38
40
  @time_range: TimeRange?
39
41
 
42
+ @windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]
43
+
40
44
  # : (untyped) -> untyped
41
45
  def validate_predicate: (untyped) -> untyped
42
46
 
@@ -51,15 +55,22 @@ module PaperTrailDiff
51
55
  # : (untyped) -> Integer
52
56
  def validate_budget: (untyped) -> Integer
53
57
 
54
- # : (Array[String]) -> Hash[String, Array[untyped]]
55
- def candidate_versions: (Array[String]) -> Hash[String, Array[untyped]]
58
+ # Each candidate's versions in its own window, read from the earliest
59
+ # moved start, and the first past each end that moved.
60
+ # : (Array[String]) -> [Hash[String, Array[untyped]], Hash[String, untyped]]
61
+ def own_versions: (Array[String]) -> [ Hash[String, Array[untyped]], Hash[String, untyped] ]
62
+
63
+ # : (Array[String], TimeRange?) -> Hash[String, Array[untyped]]
64
+ def candidate_versions: (Array[String], TimeRange?) -> Hash[String, Array[untyped]]
56
65
 
57
66
  # : (Array[untyped], untyped) -> boolish
58
67
  def held?: (Array[untyped], untyped) -> boolish
59
68
 
60
- # What each candidate held after its last change in the window.
61
- # : (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
62
- def closing_states: (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
69
+ # What each candidate held after its last change in the window: the
70
+ # first version past an end that moved, read already, or past the end as
71
+ # asked, or the live row.
72
+ # : (Array[String], Hash[String, Array[untyped]], Hash[String, untyped]) -> Hash[String, untyped]
73
+ def closing_states: (Array[String], Hash[String, Array[untyped]], Hash[String, untyped]) -> Hash[String, untyped]
63
74
 
64
75
  # : (Array[String]) -> Hash[String, untyped]
65
76
  def trailing_versions: (Array[String]) -> Hash[String, untyped]