paper_trail_diff 0.15.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +724 -1
  3. data/README.md +43 -8
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +89 -32
  6. data/docs/reference.md +427 -96
  7. data/docs/testing.md +260 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +39 -6
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +8 -7
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +31 -36
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
  73. data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +99 -0
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +92 -32
  84. data/lib/paper_trail_diff/scope_ranking.rb +27 -34
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +40 -22
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +9 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +235 -75
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +41 -23
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +32 -44
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +31 -7
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -8,7 +8,9 @@ module PaperTrailDiff
8
8
  # a filter must never remove it.
9
9
  #
10
10
  # Both the single-record and the batched selectors resolve this here, because
11
- # the rule is subtle enough that two copies of it would drift apart.
11
+ # the rule is subtle enough that two copies of it would drift apart. Their
12
+ # versions are put in order here too, which refuses a sequence that cannot
13
+ # be ordered (see Support.chronological_sort) whichever selector read it.
12
14
  class RootVersionSelection
13
15
  # An error is a specification, so it names the way out as well as the wall.
14
16
  # A window ending at the present can never gain a later version, which makes
@@ -17,8 +19,13 @@ module PaperTrailDiff
17
19
  # this is raised only when there is none to read.
18
20
  INCOMPLETE: ::String
19
21
 
20
- # : (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
21
- def initialize: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
22
+ # `selected` is what a filter keeps of `in_range`; one that keeps every
23
+ # version is no filter. Activity on associations reports the changes a
24
+ # filter keeps on them wherever they fall in the range, so a `whole` plan
25
+ # replays every root version there, as one without a filter does, and the
26
+ # filter names only which of them are the root's own mutations.
27
+ # : (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?live_endpoint: untyped, ?whole: bool) -> void
28
+ def initialize: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?live_endpoint: untyped, ?whole: bool) -> void
22
29
 
23
30
  # : () -> RootVersionPlan
24
31
  def call: () -> RootVersionPlan
@@ -35,6 +42,8 @@ module PaperTrailDiff
35
42
 
36
43
  @live_endpoint: untyped
37
44
 
45
+ @reported: Array[untyped]
46
+
38
47
  @selected: Array[untyped]
39
48
 
40
49
  @windowed: bool
@@ -59,6 +68,7 @@ module PaperTrailDiff
59
68
  # : (untyped) -> RootVersionPlan
60
69
  def filtered_plan: (untyped) -> RootVersionPlan
61
70
 
71
+ # The steps run in order, and so do the versions they pass.
62
72
  # : (Array[[untyped, untyped]], untyped) -> RootVersionPlan
63
73
  def filtered_plan_for: (Array[[ untyped, untyped ]], untyped) -> RootVersionPlan
64
74
 
@@ -69,16 +79,20 @@ module PaperTrailDiff
69
79
  # : () -> Array[untyped]
70
80
  def closing_versions: () -> Array[untyped]
71
81
 
72
- # Everything the span passes through, filtered out or not. A replay that
73
- # skipped the excluded versions would carry a stale state into the next
74
- # reported step, so the two selected mutations either side of a gap would
75
- # disagree about what the record looked like between them.
76
- # : (Array[untyped]) -> Array[untyped]
77
- def spanned: (Array[untyped]) -> Array[untyped]
78
-
79
- # : (Array[untyped]) -> Array[untyped]
80
- def chronological: (Array[untyped]) -> Array[untyped]
81
-
82
+ # Everything the span passes through, filtered out or not, through the
83
+ # version that reveals the last selected mutation, which can lie after the
84
+ # range. A replay that skipped the excluded versions would carry a stale
85
+ # state into the next reported step, so the two selected mutations either
86
+ # side of a gap would disagree about what the record looked like between
87
+ # them. One that stopped before the revealing version would read what the
88
+ # last one produced from history that ends before it. Only the version
89
+ # that reveals the last can lie outside the range, and it comes after it.
90
+ # With no versions there is no span, and a plan replays its versions.
91
+ # : (Array[untyped]) -> Array[untyped]?
92
+ def spanned: (Array[untyped]) -> Array[untyped]?
93
+
94
+ # The versions in range are in order, so the first one after a version is
95
+ # found by a search rather than by passing every version before it.
82
96
  # : (untyped) -> untyped
83
97
  def immediate_successor: (untyped) -> untyped
84
98
 
@@ -26,8 +26,6 @@ module PaperTrailDiff
26
26
 
27
27
  BIND_PARAM: ::String
28
28
 
29
- ATTRIBUTE: ::String
30
-
31
29
  # Adapters that compare strings exactly by default. MySQL and SQL Server
32
30
  # ignore case and trailing spaces by default, which Ruby cannot follow.
33
31
  EXACT_TEXT_ADAPTERS: untyped
@@ -55,10 +53,15 @@ module PaperTrailDiff
55
53
  # limit, and offset choose a page of current rows rather than membership,
56
54
  # and loading or selecting columns changes neither, so they are left out.
57
55
  # A single-table subclass's type condition is left to the caller, as for
58
- # an association.
56
+ # an association. `none` selects nothing, whatever it is chained to.
59
57
  # : (untyped, untyped) -> ScopeCondition?
60
58
  def self.for_relation: (untyped, untyped) -> ScopeCondition?
61
59
 
60
+ # A relation `none` built, whose where clause is SQL text. A condition
61
+ # that matches nothing reads no attribute, so it names no model.
62
+ # : () -> ScopeCondition
63
+ def self.nothing: () -> ScopeCondition
64
+
62
65
  # nil when the relation picks its members by conditions alone.
63
66
  # : (untyped, untyped, untyped) -> ScopeRanking?
64
67
  def self.ranking: (untyped, untyped, untyped) -> ScopeRanking?
@@ -83,9 +86,9 @@ module PaperTrailDiff
83
86
  def self.scoped_relation: (untyped, untyped) -> untyped
84
87
 
85
88
  # Some parts, such as the having clause `or` sets, may be present but
86
- # empty.
87
- # : (untyped) -> bool
88
- def self.plain_relation?: (untyped) -> bool
89
+ # empty. `allowed` names the parts that may hold values.
90
+ # : (untyped, Array[Symbol]) -> bool
91
+ def self.plain_relation?: (untyped, Array[Symbol]) -> bool
89
92
 
90
93
  # : (untyped, Array[untyped], ?ScopeRanking?) -> void
91
94
  def initialize: (untyped, Array[untyped], ?ScopeRanking?) -> void
@@ -95,6 +98,10 @@ module PaperTrailDiff
95
98
  # : (Hash[String, untyped]) -> bool
96
99
  def matches?: (Hash[String, untyped]) -> bool
97
100
 
101
+ # Whether no record can match, as for a relation `none` built.
102
+ # : () -> bool
103
+ def none?: () -> bool
104
+
98
105
  # The members among records that are each the owner's by key: those that
99
106
  # meet the conditions, then ranked.
100
107
  # : (Array[untyped]) -> Array[untyped]
@@ -111,6 +118,9 @@ module PaperTrailDiff
111
118
  # unknown where false would become true.
112
119
  COMPARISONS: untyped
113
120
 
121
+ # Comparisons that order values, which read them as ScopeRanking sorts.
122
+ ORDERED: untyped
123
+
114
124
  private
115
125
 
116
126
  @model_class: untyped
@@ -134,9 +144,11 @@ module PaperTrailDiff
134
144
  # : (bool?) -> bool?
135
145
  def negate: (bool?) -> bool?
136
146
 
137
- # The form the database holds, as the scope's own values were cast.
138
- # : (String, Hash[String, untyped]) -> untyped
139
- def stored: (String, Hash[String, untyped]) -> untyped
147
+ # The form the database holds, as the scope's own values were cast. An
148
+ # order reads the value the database sorts by instead: SQL Server holds a
149
+ # time or date in a wrapper that only compares for equality.
150
+ # : (Symbol, String, Hash[String, untyped]) -> untyped
151
+ def stored: (Symbol, String, Hash[String, untyped]) -> untyped
140
152
 
141
153
  # Builds each reflection's condition once per target class.
142
154
  class Cache
@@ -174,6 +186,24 @@ module PaperTrailDiff
174
186
  # : (untyped) -> Array[untyped]
175
187
  def comparison: (untyped) -> Array[untyped]
176
188
 
189
+ RANGES: untyped
190
+
191
+ # A range, as `where(created_at: 1.day.ago..)` writes it, on a column
192
+ # whose values sort in Ruby as the database sorts them.
193
+ # : (untyped) -> Array[untyped]
194
+ def range: (untyped) -> Array[untyped]
195
+
196
+ # : (untyped) -> Array[untyped]
197
+ def between: (untyped) -> Array[untyped]
198
+
199
+ # : (Symbol, untyped, untyped) -> Array[untyped]
200
+ def bound: (Symbol, untyped, untyped) -> Array[untyped]
201
+
202
+ # A bound in the form the database holds, read back as the value the
203
+ # database sorts by. Reading it back unwraps what an adapter wraps.
204
+ # : (String, untyped) -> untyped
205
+ def sort_value: (String, untyped) -> untyped
206
+
177
207
  # Whether a value is NULL compares alike on every type.
178
208
  # : (Symbol, untyped) -> Array[untyped]
179
209
  def binary: (Symbol, untyped) -> Array[untyped]
@@ -54,11 +54,6 @@ module PaperTrailDiff
54
54
  # : (untyped) -> bool
55
55
  def self.own?: (untyped) -> bool
56
56
 
57
- # Active Record casts a limit to an integer but keeps an offset as given,
58
- # which may be a String or SQL.
59
- # : (untyped) -> bool
60
- def self.plain_offset?: (untyped) -> bool
61
-
62
57
  # The order's keys up to the primary key, which makes it total. Keys
63
58
  # after it never decide anything.
64
59
  # : (Array[untyped], untyped) -> Array[[String, bool]]?
@@ -68,8 +63,19 @@ module PaperTrailDiff
68
63
  # : (untyped, untyped) -> String?
69
64
  def self.column: (untyped, untyped) -> String?
70
65
 
71
- # : (untyped, String) -> bool
72
- def self.orderable?: (untyped, String) -> bool
66
+ # The name an Arel attribute gives a column of the model's own table, not
67
+ # of another table or an alias of its own; nil for anything else.
68
+ # : (untyped, untyped) -> String?
69
+ def self.own_column: (untyped, untyped) -> String?
70
+
71
+ # : (untyped, String?) -> bool
72
+ def self.orderable?: (untyped, String?) -> bool
73
+
74
+ # The value the database sorts by, as the column's type casts it. An enum
75
+ # sorts by the integer it stores; other types are compared cast, since an
76
+ # adapter may serialize a time or date as a wrapper, as SQL Server does.
77
+ # : (untyped, String, untyped) -> untyped
78
+ def self.sort_value: (untyped, String, untyped) -> untyped
73
79
 
74
80
  # The type of the value a column stores, under an enum or time zone wrapper.
75
81
  # : (untyped) -> untyped
@@ -82,8 +88,8 @@ module PaperTrailDiff
82
88
  # : (untyped, untyped) -> bool
83
89
  def self.exact_time?: (untyped, untyped) -> bool
84
90
 
85
- # : (untyped, Array[[String, bool]], bool, Integer?, Integer?) -> void
86
- def initialize: (untyped, Array[[ String, bool ]], bool, Integer?, Integer?) -> void
91
+ # : (untyped, Array[[String, bool]], bool, Integer?, Integer) -> void
92
+ def initialize: (untyped, Array[[ String, bool ]], bool, Integer?, Integer) -> void
87
93
 
88
94
  # The members among records that met the scope's conditions, in order.
89
95
  # : (Array[untyped]) -> Array[untyped]
@@ -99,7 +105,7 @@ module PaperTrailDiff
99
105
 
100
106
  @nulls_last: bool
101
107
 
102
- @offset: Integer?
108
+ @offset: Integer
103
109
 
104
110
  # Keys compare in turn, and the primary key always decides. A descending
105
111
  # key negates its places, which also moves NULL to the other end, as each
@@ -115,11 +121,5 @@ module PaperTrailDiff
115
121
  # A time as its seconds, exactly, and a date as its day number.
116
122
  # : (untyped) -> Numeric
117
123
  def number: (untyped) -> Numeric
118
-
119
- # The value the database sorts by, as the key's type casts it. An enum
120
- # sorts by the integer it stores; other types are compared cast, since an
121
- # adapter may serialize a time or date as a wrapper, as SQL Server does.
122
- # : (String, Hash[String, untyped]) -> untyped
123
- def stored: (String, Hash[String, untyped]) -> untyped
124
124
  end
125
125
  end
@@ -35,9 +35,28 @@ module PaperTrailDiff
35
35
  # : () -> Hash[Array[String], Array[ChangeRow]]
36
36
  def change_rows: () -> Hash[Array[String], Array[ChangeRow]]
37
37
 
38
+ # The analysis of one of `roots`, found from the record itself. The keys
39
+ # are its base class's name and its ID as a string, which a subclass or an
40
+ # integer ID gets wrong when built by hand. Raises KeyError for a record
41
+ # the selection did not load; a deleted root's analysis is in `deleted`.
42
+ # : (untyped) -> Analysis
43
+ def analysis_for: (untyped) -> Analysis
44
+
45
+ # Each root's net changes, keyed as `change_rows` is; the block picks the
46
+ # rows to keep, as for Analysis#net_changes.
47
+ # : () ?{ (ChangeRow) -> boolish } -> Hash[Array[String], Array[NetChange]]
48
+ def net_changes: () ?{ (ChangeRow) -> boolish } -> Hash[Array[String], Array[NetChange]]
49
+
38
50
  # Two elements, not three: `roots` is reached by name so that existing
39
51
  # destructuring keeps working.
40
52
  # : () -> [Hash[Array[String], Analysis], Array[Array[String]]]
41
53
  def to_ary: () -> [ Hash[Array[String], Analysis], Array[Array[String]] ]
54
+
55
+ private
56
+
57
+ # What the block makes of each root's analysis: the roots that still
58
+ # exist, then the deleted ones that have history to report.
59
+ # : [T] () { (Analysis) -> T } -> Hash[Array[String], T]
60
+ def each_root: [T] () { (Analysis) -> T } -> Hash[Array[String], T]
42
61
  end
43
62
  end
@@ -3,14 +3,19 @@
3
3
  module PaperTrailDiff
4
4
  # Selects both populations and checks their shared ceiling before analysis.
5
5
  class ScopedAnalysisBuilder
6
- # : (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?) -> void
7
- def initialize: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?) -> void
6
+ # : (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
7
+ def initialize: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
8
8
 
9
9
  # : () -> ScopedAnalysis
10
10
  def call: () -> ScopedAnalysis
11
11
 
12
12
  private
13
13
 
14
+ # Without the option, the deleted roots are still tested when the
15
+ # relation can be read, so that another selection's are not listed.
16
+ # : (untyped, bool) -> DeletedRootFilter?
17
+ def deleted_filter: (untyped, bool) -> DeletedRootFilter?
18
+
14
19
  # : (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
15
20
  def analysis: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
16
21
 
@@ -20,6 +25,8 @@ module PaperTrailDiff
20
25
 
21
26
  @deleted_filter: DeletedRootFilter?
22
27
 
28
+ @include_deleted: bool
29
+
23
30
  @limit: Integer
24
31
 
25
32
  @selection: ScopedRootSelection
@@ -25,7 +25,9 @@ module PaperTrailDiff
25
25
  # window. `where(status: 'published')` selects what is published now, which is
26
26
  # not the same set as what was published while the window was open.
27
27
  class ScopedRootSelection
28
- PAGE_SIZE: ::Integer
28
+ MIN_PAGE_SIZE: ::Integer
29
+
30
+ MAX_PAGE_SIZE: ::Integer
29
31
 
30
32
  # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
31
33
  # gem supports 3.1.
@@ -40,9 +42,11 @@ module PaperTrailDiff
40
42
 
41
43
  # `activity_tree` names the association paths whose changes also select a
42
44
  # root, as an activity analysis reports them. Without one, only a root's
43
- # own versions select it.
44
- # : (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
45
- def initialize: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
45
+ # own versions select it. `version_scope` narrows which of either count,
46
+ # as it narrows which are reported. `traversal` names the requested paths,
47
+ # which decide where a window's edges move (see TransactionCut).
48
+ # : (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
49
+ def initialize: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
46
50
 
47
51
  # : () -> Result
48
52
  def call: () -> Result
@@ -53,12 +57,16 @@ module PaperTrailDiff
53
57
 
54
58
  @limit: Integer
55
59
 
60
+ @path_types: Array[String]
61
+
56
62
  @related: AssociationActivitySelection?
57
63
 
58
64
  @scope: untyped
59
65
 
60
66
  @time_range: TimeRange?
61
67
 
68
+ @version_scope: untyped
69
+
62
70
  # Leaves the candidate set in the database. Plucking every root changed in
63
71
  # the window would cost memory and a statement proportional to all activity
64
72
  # in the window -- not to the relation or `limit:` -- so a report on one
@@ -80,6 +88,13 @@ module PaperTrailDiff
80
88
  # : (Array[String]) -> Result
81
89
  def plucked_selection: (Array[String]) -> Result
82
90
 
91
+ # The candidates the relation's conditions accept. A grouped relation's
92
+ # rows are groups, which a condition on one record cannot decide, and its
93
+ # aggregates read every candidate at once, so it keeps them all: the
94
+ # filter reads each, and the relation groups those that match.
95
+ # : (Array[String]) -> Array[String]
96
+ def relation_members: (Array[String]) -> Array[String]
97
+
83
98
  # Comparing the two columns in SQL needs them to share a type: PostgreSQL
84
99
  # rejects an integer key against a string item_id outright. A composite
85
100
  # key names no single attribute, so it has no type and never matches.
@@ -97,9 +112,17 @@ module PaperTrailDiff
97
112
  # : () -> Array[String]
98
113
  def missing_ids: () -> Array[String]
99
114
 
115
+ # Only the versions `version_scope` keeps select a root: one whose versions
116
+ # in the window it drops would have nothing to report. A version saved
117
+ # just before the window selects its root when TransactionCut moves the
118
+ # root's window back to take it in.
100
119
  # : () -> untyped
101
120
  def window_versions: () -> untyped
102
121
 
122
+ # The filter reads each candidate over the window its analysis will.
123
+ # : (untyped, Integer, AssociationTraversal?) -> HistoricalFilter?
124
+ def historical_filter_for: (untyped, Integer, AssociationTraversal?) -> HistoricalFilter?
125
+
103
126
  # Accepts a model class as readily as a relation: `Article` and
104
127
  # `Article.where(...)` both name a population, and `all` is what makes them
105
128
  # the same kind of thing.
@@ -130,29 +153,34 @@ module PaperTrailDiff
130
153
  # : (Array[untyped]) -> Array[untyped]
131
154
  def selected_records: (Array[untyped]) -> Array[untyped]
132
155
 
156
+ # Pages are read by offset, so under a total order.
133
157
  # : (Array[untyped]) -> untyped
134
158
  def candidate_relation: (Array[untyped]) -> untyped
135
159
 
136
160
  # : (untyped, Integer) -> Array[untyped]
137
161
  def record_page: (untyped, Integer) -> Array[untyped]
138
162
 
139
- # Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
140
- # even when the extra ordering would only have served as a tie-breaker.
141
- # : () -> untyped
142
- def ordered_scope: () -> untyped
143
-
144
163
  # : (Integer) -> Integer
145
164
  def page_limit: (Integer) -> Integer
146
165
 
166
+ # Every page repeats the candidates, a list of ids or the subqueries that
167
+ # find them, and skips the rows read before it, so pages much smaller than
168
+ # the selection read the candidates many times over. More roots than
169
+ # `limit:` raise, so a page never needs more than one past it. A page
170
+ # holds at least 250 rows, for a relation whose joins repeat a record,
171
+ # and at most 2,000: SQL Server compiles a statement with its ids written
172
+ # in, and one that listed 20,000 and returned them all outlasted the
173
+ # adapter's default timeout of 5 seconds.
174
+ # : () -> Integer
175
+ def page_size: () -> Integer
176
+
147
177
  # : (Integer) -> void
148
178
  def reject_oversized!: (Integer) -> void
149
179
 
180
+ # Keyed as Endpoint.identity keys the record, which the analyses use.
150
181
  # : (String) -> Array[String]
151
182
  def identity: (String) -> Array[String]
152
183
 
153
- # : () -> String
154
- def item_type: () -> String
155
-
156
184
  # A relation delegates class methods to its model, so every mutation here,
157
185
  # which drops `.model`, answers the same.
158
186
  # mutant:disable
@@ -41,11 +41,16 @@ module PaperTrailDiff
41
41
  def attributes_for: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
42
42
 
43
43
  # Same exclusions as AR normalization, applied to an already typed state.
44
+ # A state without associations is normalized once at each path: the
45
+ # same state is read again at every boundary it spans.
44
46
  # : (PreparedRecordState, tree: AssociationTree, path: String, ?incoming: untyped, ?associations: snapshot_associations) -> RecordSnapshot
45
47
  def from_state: (PreparedRecordState, tree: AssociationTree, path: String, ?incoming: untyped, ?associations: snapshot_associations) -> RecordSnapshot
46
48
 
47
49
  private
48
50
 
51
+ # : (PreparedRecordState, AssociationTree, String, untyped, snapshot_associations) -> RecordSnapshot
52
+ def snapshot_from_state: (PreparedRecordState, AssociationTree, String, untyped, snapshot_associations) -> RecordSnapshot
53
+
49
54
  # The id a live record of the same row reports: one value, or one per
50
55
  # column of a composite key.
51
56
  # : (untyped, PreparedRecordState) -> untyped
@@ -58,6 +63,8 @@ module PaperTrailDiff
58
63
 
59
64
  @ignore_policy: IgnorePolicy
60
65
 
66
+ @leaves: Hash[String, Hash[PreparedRecordState, RecordSnapshot]]
67
+
61
68
  @pool: SnapshotPool
62
69
 
63
70
  @structural_columns: Hash[String, Array[String]]
@@ -0,0 +1,35 @@
1
+ # Generated from lib/paper_trail_diff/stored_json_values.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Reads values in the form JSON history gives them back.
5
+ #
6
+ # A `json` or `jsonb` object column stores a record's attributes as they
7
+ # are, without PaperTrail's attribute serializer, so a `serialize`d value
8
+ # comes back as JSON writes it: keys as strings, and dates, times and
9
+ # symbols inside it as strings, which its type does not cast back.
10
+ # PaperTrail's JSON serializer stores a binary value as `{"value" => bytes}`,
11
+ # which its type does not cast back either. Compared as they are, the live
12
+ # row and every version would differ though nothing was edited. So every
13
+ # side is read in one form: a `serialize`d value as JSON writes it, and a
14
+ # binary value as its bytes. Both leave a value read from history as it is.
15
+ module StoredJsonValues
16
+ SERIALIZED_TYPE: ::String
17
+
18
+ BINARY_TYPE: ::String
19
+
20
+ BINARY_KEYS: untyped
21
+
22
+ # For a model whose history is JSON, which StoredTimePrecision.digits
23
+ # tells: a `json` or `jsonb` object column, or the JSON serializer.
24
+ # : (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
25
+ def self.apply: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
26
+
27
+ # The attributes with the value of each of this type converted. An
28
+ # adapter's type can be a subclass, as PostgreSQL's `bytea` is of binary.
29
+ # : (untyped, Hash[untyped, untyped], String) { (untyped) -> untyped } -> Hash[untyped, untyped]
30
+ def self.convert: (untyped, Hash[untyped, untyped], String) { (untyped) -> untyped } -> Hash[untyped, untyped]
31
+
32
+ # : (untyped) -> untyped
33
+ def self.bytes: (untyped) -> untyped
34
+ end
35
+ end
@@ -19,18 +19,32 @@ module PaperTrailDiff
19
19
  # Fractional digits a model's history keeps for times, or nil when the
20
20
  # history is stored losslessly.
21
21
  # : (untyped) -> Integer?
22
- def self?.digits: (untyped) -> Integer?
22
+ def self.digits: (untyped) -> Integer?
23
23
 
24
24
  # : (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
25
- def self?.apply: (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
25
+ def self.apply: (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
26
26
 
27
+ # From nine digits on, the step is one nanosecond or a fraction of one, so
28
+ # nothing is cut.
27
29
  # : (untyped, Integer) -> untyped
28
- def self?.truncate: (untyped, Integer) -> untyped
30
+ def self.truncate: (untyped, Integer) -> untyped
29
31
 
30
32
  # : (untyped) -> bool
31
- def self?.json_history?: (untyped) -> bool
33
+ def self.json_history?: (untyped) -> bool
32
34
 
35
+ # Whether the version table keeps this column as `json` or `jsonb`, which
36
+ # PaperTrail writes without its serializer.
37
+ # : (untyped, String) -> bool
38
+ def self.json_column?: (untyped, String) -> bool
39
+
40
+ # mutant:disable - Every mutation that survives here reads the same
41
+ # constant another way: from this module rather than Object, or with `::`.
42
+ # : () -> Integer
43
+ def self.json_time_precision: () -> Integer
44
+
45
+ # Whether PaperTrail writes history with its JSON serializer.
46
+ # mutant:disable - As for json_time_precision.
33
47
  # : () -> bool
34
- def self?.json_serializer?: () -> bool
48
+ def self.json_serializer?: () -> bool
35
49
  end
36
50
  end
@@ -0,0 +1,13 @@
1
+ # Generated from lib/paper_trail_diff/stored_values.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Reads a model's attribute values in the one form every account of them
5
+ # shares: a version decoded from history, the current row, and the changes
6
+ # a version recorded. Each would otherwise differ where nothing was edited.
7
+ # TimeOfDay puts a time of day on one date, and for JSON history,
8
+ # StoredJsonValues and StoredTimePrecision read values as JSON stored them.
9
+ module StoredValues
10
+ # : (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
11
+ def self.apply: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
12
+ end
13
+ end