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,276 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # One record's net change over the change rows a caller kept: its state
6
+ # before them, and that state with only the kept changes made. Built by
7
+ # Analysis#net_changes (see NetChanges).
8
+ class NetChange
9
+ attr_reader :association_path #: Array[String]
10
+ attr_reader :association_kind #: Symbol?
11
+ # The record, or nil for the root itself, as on a change row.
12
+ attr_reader :record #: RecordReference?
13
+ # The record's fields when the step holding its first kept change began,
14
+ # or nil where it was not there. The records it holds are left out: each
15
+ # has an entry of its own.
16
+ attr_reader :before #: RecordSnapshot?
17
+ # `before` with only the kept changes made, or nil where they removed the
18
+ # record.
19
+ attr_reader :after #: RecordSnapshot?
20
+ # `before` compared with `after`: the fields that differ, or the record's
21
+ # appearance or removal.
22
+ attr_reader :diff #: Diff
23
+ # The events that made the kept changes, in order, each once.
24
+ attr_reader :sources #: Array[ActivityBoundary]
25
+
26
+ #: (association_path: Array[String], association_kind: Symbol?, record: RecordReference?, before: RecordSnapshot?, after: RecordSnapshot?, sources: Array[ActivityBoundary]) -> void
27
+ def initialize( # rubocop:disable Metrics/ParameterLists
28
+ association_path:, association_kind:, record:, before:, after:, sources:
29
+ )
30
+ @association_path = association_path
31
+ @association_kind = association_kind
32
+ @record = record
33
+ @before = before
34
+ @after = after
35
+ @diff = Engine.compare(before, after)
36
+ @sources = sources.freeze
37
+ freeze
38
+ end
39
+
40
+ #: () -> bool
41
+ def root?
42
+ association_path.empty?
43
+ end
44
+
45
+ # Whether the record was not there before its first kept change.
46
+ #: () -> bool
47
+ def added?
48
+ before.nil?
49
+ end
50
+
51
+ # Whether the kept changes left the record gone.
52
+ #: () -> bool
53
+ def removed?
54
+ after.nil?
55
+ end
56
+
57
+ #: () -> Hash[Symbol, untyped]
58
+ def to_h
59
+ {
60
+ association_path: association_path, association_kind: association_kind,
61
+ record: record&.to_h, before: before&.to_h, after: after&.to_h, diff: diff.to_h,
62
+ sources: sources.map { |source| source.to_h(metadata: true) }
63
+ }
64
+ end
65
+ end
66
+
67
+ # Folds an activity timeline's change rows into one NetChange for each
68
+ # record a kept row is about, known by its association path and identity as
69
+ # the row names it.
70
+ #
71
+ # A record's `before` is its state in the snapshot that the step of its
72
+ # first kept row starts from. Each kept row then makes its change in time
73
+ # order: a field takes the row's new value, and a row about the whole record
74
+ # moves it in or out as the step's closing snapshot has it. A record that
75
+ # appears takes that snapshot's fields, so a field no kept row sets keeps
76
+ # the value it has there; the kept rows of its fields then replace any value
77
+ # a dropped row left.
78
+ class NetChanges
79
+ # What one record's kept rows have made of it so far.
80
+ class RecordFold
81
+ # The rows that set a field; a removed record's rows leave them be.
82
+ SETTING = %i[added changed].freeze
83
+ private_constant :SETTING
84
+
85
+ #: (ChangeRow, RecordSnapshot?) -> void
86
+ def initialize(row, before)
87
+ @row = row
88
+ @before = before
89
+ @read = before
90
+ @present = !before.nil?
91
+ @values = before ? before.attributes.dup : {} #: Hash[String, untyped]
92
+ @sources = [] #: Array[ActivityBoundary]
93
+ end
94
+
95
+ # Makes one step's kept rows of the record. The block finds the record
96
+ # in the step's closing snapshot, which only a row about the whole
97
+ # record needs.
98
+ #: (Array[ChangeRow]) { () -> RecordSnapshot? } -> void
99
+ def apply(rows)
100
+ whole = rows.reject(&:attribute)
101
+ move(whole, yield) unless whole.empty?
102
+ rows.each do |row|
103
+ attribute = row.attribute
104
+ @values[attribute] = row.to if attribute && SETTING.include?(row.change)
105
+ end
106
+ @sources.concat(rows.map(&:source))
107
+ end
108
+
109
+ #: () -> NetChange
110
+ def net_change
111
+ NetChange.new(
112
+ association_path: @row.association_path, association_kind: @row.association_kind,
113
+ record: @row.record, before: @before, after: after,
114
+ sources: @sources.uniq(&:version_id)
115
+ )
116
+ end
117
+
118
+ private
119
+
120
+ # @rbs @row: ChangeRow
121
+ # @rbs @before: RecordSnapshot?
122
+ # The record as last read, which names it.
123
+ # @rbs @read: RecordSnapshot?
124
+ # @rbs @present: bool
125
+ # @rbs @values: Hash[String, untyped]
126
+ # @rbs @sources: Array[ActivityBoundary]
127
+
128
+ # A record that appears, or moves between the records holding it, takes
129
+ # its fields from where it ends up, which an added row's step holds.
130
+ #: (Array[ChangeRow], RecordSnapshot?) -> void
131
+ def move(whole, state)
132
+ @present = !state.nil?
133
+ return unless whole.any? { |row| row.change == :added }
134
+
135
+ found = state #: RecordSnapshot
136
+ @values = found.attributes.dup
137
+ @read = found
138
+ end
139
+
140
+ # A record is there only once its own state was read, before its first
141
+ # kept row or where it appeared.
142
+ #: () -> RecordSnapshot?
143
+ def after
144
+ return unless @present
145
+
146
+ read = @read #: RecordSnapshot
147
+ RecordSnapshot.new(type: read.type, id: read.id, attributes: @values)
148
+ end
149
+ end
150
+
151
+ # `keep` picks the rows to make; without it, every row is made.
152
+ #: (Array[ActivityStep], (^(ChangeRow) -> boolish)?) -> Array[NetChange]
153
+ def self.call(steps, keep)
154
+ new(steps, keep).call
155
+ end
156
+
157
+ #: (Array[ActivityStep], (^(ChangeRow) -> boolish)?) -> void
158
+ def initialize(steps, keep)
159
+ @steps = steps
160
+ @keep = keep
161
+ @folds = {} #: Hash[Array[untyped], RecordFold]
162
+ @holders = {} #: Hash[[RecordSnapshot, Array[String]], Array[RecordSnapshot]]
163
+ end
164
+
165
+ #: () -> Array[NetChange]
166
+ def call
167
+ check_snapshots!
168
+ @steps.each do |step|
169
+ rows = kept(step)
170
+ next if rows.empty?
171
+
172
+ @opening_root ||= flat(step.from_snapshot || step.to_snapshot)
173
+ rows.group_by { |row| key(row) }.each { |key, record_rows| fold(key, step, record_rows) }
174
+ end
175
+ listed.freeze
176
+ end
177
+
178
+ private
179
+
180
+ # @rbs @steps: Array[ActivityStep]
181
+ # @rbs @keep: (^(ChangeRow) -> boolish)?
182
+ # @rbs @folds: Hash[Array[untyped], RecordFold]
183
+ # @rbs @holders: Hash[[RecordSnapshot, Array[String]], Array[RecordSnapshot]]
184
+ # @rbs @opening_root: RecordSnapshot?
185
+
186
+ # A step with a change has a state on at least one side, which it keeps
187
+ # only when asked to.
188
+ #: () -> void
189
+ def check_snapshots!
190
+ return if @steps.all? { |step| step.empty? || step.from_snapshot || step.to_snapshot }
191
+
192
+ raise ConfigurationError, 'net_changes requires snapshots: true'
193
+ end
194
+
195
+ #: (ActivityStep) -> Array[ChangeRow]
196
+ def kept(step)
197
+ keep = @keep
198
+ rows = step.change_rows
199
+ keep ? rows.select(&keep) : rows
200
+ end
201
+
202
+ #: (ChangeRow) -> Array[untyped]
203
+ def key(row)
204
+ record = row.record
205
+ [row.association_path, record&.type, record&.id]
206
+ end
207
+
208
+ #: (Array[untyped], ActivityStep, Array[ChangeRow]) -> void
209
+ def fold(key, step, rows)
210
+ row = rows.first #: ChangeRow
211
+ record = @folds[key] ||= RecordFold.new(row, flat(locate(step.from_snapshot, row)))
212
+ record.apply(rows) { locate(step.to_snapshot, row) }
213
+ end
214
+
215
+ # The root comes first whenever anything is listed, so a report has its
216
+ # fields when only the records it holds changed; then each record in the
217
+ # order of its first kept change. A record the kept changes left as it
218
+ # was is left out.
219
+ #: () -> Array[NetChange]
220
+ def listed
221
+ changes = @folds.values.map(&:net_change)
222
+ changed = changes.reject { |change| change.diff.empty? }
223
+ return changed if changed.empty?
224
+
225
+ [changes.find(&:root?) || unchanged_root, *changed.reject(&:root?)]
226
+ end
227
+
228
+ # The root, without a kept change of its own, as the first kept change
229
+ # found it.
230
+ #: () -> NetChange
231
+ def unchanged_root
232
+ state = @opening_root
233
+ NetChange.new(association_path: [], association_kind: nil, record: nil,
234
+ before: state, after: state, sources: [])
235
+ end
236
+
237
+ # The record a row is about in one of its step's snapshots, under any of
238
+ # the records along its path; nil where it is not there.
239
+ #: (RecordSnapshot?, ChangeRow) -> RecordSnapshot?
240
+ def locate(snapshot, row)
241
+ reference = row.record
242
+ return snapshot unless snapshot && reference
243
+
244
+ path = row.association_path
245
+ holders(snapshot, path.take(path.length - 1)).each do |holder|
246
+ association = holder.associations[path.fetch(-1)]
247
+ next unless association
248
+
249
+ position = association.position(reference.type, reference.id)
250
+ return association.records.fetch(position) if position
251
+ end
252
+ nil
253
+ end
254
+
255
+ # The records reached through `parents` from the root, read once for each
256
+ # snapshot.
257
+ #: (RecordSnapshot, Array[String]) -> Array[RecordSnapshot]
258
+ def holders(snapshot, parents)
259
+ @holders[[snapshot, parents]] ||= reach(snapshot, parents)
260
+ end
261
+
262
+ #: (RecordSnapshot, Array[String]) -> Array[RecordSnapshot]
263
+ def reach(snapshot, parents)
264
+ parents.reduce([snapshot]) do |records, name|
265
+ records.flat_map { |record| record.associations[name]&.records || [] }
266
+ end
267
+ end
268
+
269
+ # The record's own fields, without the records it holds.
270
+ #: (RecordSnapshot?) -> RecordSnapshot?
271
+ def flat(snapshot)
272
+ snapshot && RecordSnapshot.new(type: snapshot.type, id: snapshot.id,
273
+ attributes: snapshot.attributes)
274
+ end
275
+ end
276
+ end
@@ -0,0 +1,35 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Splits the versions read for a batch by each root's own window. A
6
+ # transaction that crosses an edge moves a root's window to start or end
7
+ # earlier (see TransactionCut), never later, so the versions read from the
8
+ # earliest start to the shared end hold each root's own, and the first left
9
+ # past an end that moved.
10
+ module OwnWindow
11
+ # From the earliest start to the shared end.
12
+ #: (TimeRange, Array[TimeRange]) -> TimeRange
13
+ def self.widest(range, windows)
14
+ start = [range.begin_time, *windows.map(&:begin_time)].min
15
+ TimeRange.new(range.exclude_end? ? (start...range.end_time) : (start..range.end_time))
16
+ end
17
+
18
+ # The versions inside `window`, and the first of the rest past its end.
19
+ # They are read in no order, so the first is found by time and id.
20
+ #: (TimeRange, Array[untyped]) -> [Array[untyped], untyped]
21
+ def self.split(window, loaded)
22
+ own, rest = loaded.partition { |version| window.include?(version.created_at) }
23
+ [own, first_past(rest, window.end_time)]
24
+ end
25
+
26
+ #: (Array[untyped], Time?) -> untyped
27
+ def self.first_past(versions, finish)
28
+ return unless finish
29
+
30
+ versions.select { |version| version.created_at >= finish }
31
+ .min_by { |version| Support.chronological_version_key(version) }
32
+ end
33
+ private_class_method :first_past
34
+ end
35
+ end
@@ -9,18 +9,16 @@ module PaperTrailDiff
9
9
  class PaperTrailAdapter # rubocop:disable Metrics/ClassLength
10
10
  # `recorded_changes:` reads what each activity boundary's version recorded.
11
11
  # `allow_approximate:` accepts association paths read with PT-AT.
12
- #: (associations: association_option, ignore: ignore_option, ?reload_live_endpoints: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> void
13
- def initialize(associations:, ignore:, reload_live_endpoints: true, recorded_changes: false, allow_approximate: false) # rubocop:disable Metrics/MethodLength, Layout/LineLength
12
+ #: (associations: association_option, ignore: ignore_option, ?recorded_changes: bool, ?allow_approximate: bool) -> void
13
+ def initialize(associations:, ignore:, recorded_changes: false, allow_approximate: false)
14
14
  @association_tree = AssociationTree.build(associations)
15
15
  @ignore_policy = IgnorePolicy.build(ignore, association_paths: @association_tree.paths)
16
16
  @recorded = (@ignore_policy if recorded_changes)
17
17
  @traversal = AssociationTraversal.new(@association_tree)
18
- @traversal_preparer = TraversalPreparer.new(tree: @association_tree, traversal: @traversal,
18
+ @traversal_preparer = TraversalPreparer.new(traversal: @traversal,
19
19
  allow_approximate: allow_approximate)
20
- @live_endpoints = LiveEndpointProvider.new(
21
- tree: @association_tree, traversal: @traversal, reload: reload_live_endpoints
22
- )
23
- @instrumentation_payload = @live_endpoints.comparison_payload
20
+ @live_endpoints = LiveEndpointProvider.new(tree: @association_tree)
21
+ @instrumentation_payload = { association_paths: @association_tree.paths }.freeze
24
22
  @snapshot_pool = SnapshotPool.new
25
23
  @normalizer = SnapshotNormalizer.new(
26
24
  tree: @association_tree, ignore_policy: @ignore_policy,
@@ -67,15 +65,8 @@ module PaperTrailDiff
67
65
  ReadSnapshot.call([record]) do
68
66
  @traversal_preparer.call(record.class, historical: true)
69
67
  from, to = default_range(record, from, to, within)
70
- TimelineBuilder.new(
71
- record,
72
- from: from,
73
- to: to,
74
- within: within,
75
- version_scope: version_scope,
76
- live_endpoint: live_endpoint_for(record, within),
77
- snapshotter: @timeline_snapshotter
78
- ).build
68
+ timeline_builder(record, from: from, to: to, within: within, version_scope: version_scope,
69
+ live_endpoint: live_endpoint_for(record, within)).build
79
70
  end
80
71
  end
81
72
 
@@ -87,10 +78,10 @@ module PaperTrailDiff
87
78
  steps = ReadSnapshot.call([record]) do
88
79
  @traversal_preparer.call(record.class, historical: true)
89
80
  from, to = default_range(record, from, to, within)
90
- live = live_endpoint_for(record, within)
81
+ view = activity_view(true, snapshots, group, version_scope)
91
82
  activity_builder(
92
83
  record, from: from, to: to, within: within, version_scope: version_scope,
93
- live_endpoint: live, view: activity_view(true, snapshots, group)
84
+ live_endpoint: live_endpoint_for(record, within), view: view
94
85
  ).build
95
86
  end
96
87
  payload[:step_count] = steps.length
@@ -100,7 +91,7 @@ module PaperTrailDiff
100
91
 
101
92
  #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
102
93
  def analyze(record, from:, to:, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
103
- view = activity_view(activity, snapshots, group)
94
+ view = activity_view(activity, snapshots, group, version_scope)
104
95
  Endpoint.validate_root!(record)
105
96
  ReadSnapshot.call([record]) do
106
97
  analyze_record(record, from: from, to: to, within: within, activity: activity,
@@ -113,7 +104,7 @@ module PaperTrailDiff
113
104
  def analyze_many(records, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
114
105
  ReadSnapshot.call(records.is_a?(Array) ? records : []) do
115
106
  analyze_batch(records, within: within, activity: activity, version_scope: version_scope,
116
- view: activity_view(activity, snapshots, group))
107
+ view: activity_view(activity, snapshots, group, version_scope))
117
108
  end
118
109
  end
119
110
 
@@ -123,7 +114,7 @@ module PaperTrailDiff
123
114
  # rather than dropped -- see `PaperTrailDiff.analyze_scope`.
124
115
  #: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
125
116
  def analyze_scope(scope, limit:, within:, activity: false, version_scope: nil, snapshots: false, group: nil, historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, include_deleted: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
126
- view = activity_view(activity, snapshots, group)
117
+ view = activity_view(activity, snapshots, group, version_scope)
127
118
  ReadSnapshot.call([scope]) do
128
119
  check_scope(scope)
129
120
  scoped_builder(scope, limit: limit, within: within, activity: activity,
@@ -135,10 +126,10 @@ module PaperTrailDiff
135
126
 
136
127
  private
137
128
 
138
- #: (bool, bool, Symbol?) -> ActivityView
139
- def activity_view(activity, snapshots, group)
129
+ #: (bool, bool, Symbol?, untyped) -> ActivityView
130
+ def activity_view(activity, snapshots, group, version_scope)
140
131
  ActivityView.build(activity: activity, snapshots: snapshots, group: group,
141
- recorded: @recorded)
132
+ recorded: @recorded, version_scope: version_scope)
142
133
  end
143
134
 
144
135
  #: (untyped) -> Hash[Symbol, untyped]
@@ -157,14 +148,21 @@ module PaperTrailDiff
157
148
  live_endpoint: live, view: view
158
149
  )
159
150
  else
160
- TimelineBuilder.new(
161
- record, from: from, to: to, within: within, version_scope: version_scope,
162
- live_endpoint: live, snapshotter: @timeline_snapshotter
163
- )
151
+ timeline_builder(record, from: from, to: to, within: within,
152
+ version_scope: version_scope, live_endpoint: live)
164
153
  end
165
154
  builder.analyze.with_window(builder.window)
166
155
  end
167
156
 
157
+ #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped) -> TimelineBuilder
158
+ def timeline_builder(record, from:, to:, within:, version_scope:, live_endpoint:) # rubocop:disable Metrics/ParameterLists
159
+ TimelineBuilder.new(
160
+ record, from: from, to: to, within: within, version_scope: version_scope,
161
+ live_endpoint: live_endpoint, snapshotter: @timeline_snapshotter,
162
+ traversal: @traversal
163
+ )
164
+ end
165
+
168
166
  #: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
169
167
  def analyze_batch(records, within:, activity:, version_scope:, view:)
170
168
  count = records.is_a?(Array) ? records.length : 0
@@ -173,10 +171,10 @@ module PaperTrailDiff
173
171
  AnalysisBatch.new(
174
172
  records,
175
173
  time_range: within.nil? ? nil : TimeRange.new(within), version_scope: version_scope,
176
- context_required: activity && !@association_tree.empty?,
174
+ context_required: activity && !@association_tree.empty?, traversal: @traversal,
177
175
  live_loader: method(:load_batch_endpoints),
178
176
  history_preparer: @historical_store.method(:prepare_batch),
179
- analyzer: batched_root_analyzer(activity, within: within, view: view)
177
+ analyzer: batched_root_analyzer(activity, view: view)
180
178
  ).call
181
179
  end
182
180
  end
@@ -220,13 +218,12 @@ module PaperTrailDiff
220
218
  #: (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
221
219
  def analyze_deleted(model, identities, options)
222
220
  within = options.fetch(:within)
223
- analyzer = batched_root_analyzer(options.fetch(:activity), within: within,
224
- view: options.fetch(:view))
221
+ analyzer = batched_root_analyzer(options.fetch(:activity), view: options.fetch(:view))
225
222
  DeletedAnalysisBatch.new(
226
223
  model, identities: identities, time_range: within.nil? ? nil : TimeRange.new(within),
227
224
  version_scope: options.fetch(:version_scope),
228
225
  history_preparer: @historical_store.method(:prepare_deleted_batch),
229
- analyzer: analyzer,
226
+ analyzer: analyzer, traversal: @traversal,
230
227
  context_required: options.fetch(:activity) && !@association_tree.empty?
231
228
  ).call
232
229
  end
@@ -247,7 +244,8 @@ module PaperTrailDiff
247
244
  },
248
245
  # Checkpoints compare a root's own versions, so only activity can
249
246
  # report a window in which just its associations changed.
250
- activity_tree: (@association_tree if activity), version_scope: version_scope
247
+ activity_tree: (@association_tree if activity), version_scope: version_scope,
248
+ traversal: @traversal
251
249
  )
252
250
  end
253
251
 
@@ -333,21 +331,19 @@ module PaperTrailDiff
333
331
  )
334
332
  end
335
333
 
336
- #: (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
337
- def batched_root_analyzer(activity, within:, view:)
334
+ #: (bool, view: ActivityView) -> BatchedRootAnalyzer
335
+ def batched_root_analyzer(activity, view:)
338
336
  BatchedRootAnalyzer.new(
339
- tree: @association_tree,
340
337
  timeline_snapshotter: @timeline_snapshotter,
341
338
  activity_snapshotter: @activity_snapshotter,
342
339
  preparer: @traversal_preparer.method(:call),
343
- activity: activity, within: within, view: view
340
+ activity: activity, view: view, traversal: @traversal
344
341
  )
345
342
  end
346
343
 
347
344
  #: () -> HistoricalSnapshotStore
348
345
  def build_historical_store
349
346
  HistoricalSnapshotStore.new(
350
- tree: @association_tree,
351
347
  traversal: @traversal,
352
348
  normalizer: @normalizer,
353
349
  preparer: @traversal_preparer.method(:call)
@@ -358,14 +354,14 @@ module PaperTrailDiff
358
354
  #: (PreparedActivitySnapshots) -> BranchSnapshotRefresher
359
355
  def branch_refresher(snapshots)
360
356
  BranchSnapshotRefresher.new(
361
- tree: @association_tree, ignore_policy: @ignore_policy,
362
- traversal: @traversal, pool: @snapshot_pool,
357
+ ignore_policy: @ignore_policy, traversal: @traversal, pool: @snapshot_pool,
363
358
  normalizer: @normalizer,
364
359
  full_snapshotter: snapshots.method(:call),
365
360
  partial_snapshotter: snapshots.method(:custom),
366
361
  association_reader: snapshots.method(:association_reader),
367
362
  record_transition: snapshots.method(:record_transition),
368
- prepared_record_after: snapshots.method(:record_after)
363
+ prepared_record_after: snapshots.method(:record_after),
364
+ root_state: snapshots.method(:root_state)
369
365
  )
370
366
  end
371
367
 
@@ -375,11 +371,10 @@ module PaperTrailDiff
375
371
  record,
376
372
  range: TimelineRange.new(
377
373
  record, from: from, to: to, within: within, version_scope: version_scope,
378
- live_endpoint: live_endpoint
374
+ live_endpoint: live_endpoint, traversal: @traversal
379
375
  ),
380
- tree: @association_tree,
381
376
  snapshotter: @activity_snapshotter,
382
- view: view
377
+ view: view, traversal: @traversal
383
378
  )
384
379
  end
385
380