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
@@ -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,
@@ -35,14 +33,16 @@ module PaperTrailDiff
35
33
  Instrumentation.instrument('compare', payload) do
36
34
  Endpoint.validate_pair!(from_endpoint, to_endpoint)
37
35
  notify_ambiguous_association_boundary(from_endpoint, to_endpoint)
38
- if @association_tree.empty?
39
- Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
40
- else
41
- # Prepared history orders versions that share a timestamp and finds
42
- # children that later moved away; reading associations straight from
43
- # PT-AT would resolve them by time alone and miss those children.
44
- comparison_batch([{ from: from_endpoint, to: to_endpoint }],
45
- preparer: @traversal_preparer.method(:call)).call.values.fetch(0)
36
+ ReadSnapshot.call([from_endpoint, to_endpoint]) do
37
+ if @association_tree.empty?
38
+ Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
39
+ else
40
+ # Prepared history orders versions that share a timestamp and finds
41
+ # children that later moved away; reading associations straight from
42
+ # PT-AT would resolve them by time alone and miss those children.
43
+ comparison_batch([{ from: from_endpoint, to: to_endpoint }],
44
+ preparer: @traversal_preparer.method(:call)).call.values.fetch(0)
45
+ end
46
46
  end
47
47
  end
48
48
  end
@@ -53,24 +53,21 @@ module PaperTrailDiff
53
53
  count = comparisons.is_a?(Array) ? comparisons.length : 0
54
54
  payload = @instrumentation_payload.merge(comparison_count: count)
55
55
  Instrumentation.instrument('compare_many', payload) do
56
- comparison_batch(comparisons, preparer: @traversal_preparer.method(:call)).call
56
+ ReadSnapshot.call(comparison_endpoints(comparisons)) do
57
+ comparison_batch(comparisons, preparer: @traversal_preparer.method(:call)).call
58
+ end
57
59
  end
58
60
  end
59
61
 
60
62
  #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
61
63
  def timeline(record, from:, to:, within:, version_scope: nil)
62
64
  Endpoint.validate_root!(record)
63
- @traversal_preparer.call(record.class, historical: true)
64
- from, to = default_range(record, from, to, within)
65
- TimelineBuilder.new(
66
- record,
67
- from: from,
68
- to: to,
69
- within: within,
70
- version_scope: version_scope,
71
- live_endpoint: live_endpoint_for(record, within),
72
- snapshotter: @timeline_snapshotter
73
- ).build
65
+ ReadSnapshot.call([record]) do
66
+ @traversal_preparer.call(record.class, historical: true)
67
+ from, to = default_range(record, from, to, within)
68
+ timeline_builder(record, from: from, to: to, within: within, version_scope: version_scope,
69
+ live_endpoint: live_endpoint_for(record, within)).build
70
+ end
74
71
  end
75
72
 
76
73
  #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
@@ -78,13 +75,15 @@ module PaperTrailDiff
78
75
  Endpoint.validate_root!(record)
79
76
  payload = model_payload(record)
80
77
  Instrumentation.instrument('activity_timeline', payload) do
81
- @traversal_preparer.call(record.class, historical: true)
82
- from, to = default_range(record, from, to, within)
83
- live = live_endpoint_for(record, within)
84
- steps = activity_builder(
85
- record, from: from, to: to, within: within, version_scope: version_scope,
86
- live_endpoint: live, view: activity_view(true, snapshots, group)
87
- ).build
78
+ steps = ReadSnapshot.call([record]) do
79
+ @traversal_preparer.call(record.class, historical: true)
80
+ from, to = default_range(record, from, to, within)
81
+ view = activity_view(true, snapshots, group, version_scope)
82
+ activity_builder(
83
+ record, from: from, to: to, within: within, version_scope: version_scope,
84
+ live_endpoint: live_endpoint_for(record, within), view: view
85
+ ).build
86
+ end
88
87
  payload[:step_count] = steps.length
89
88
  steps
90
89
  end
@@ -92,29 +91,21 @@ module PaperTrailDiff
92
91
 
93
92
  #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
94
93
  def analyze(record, from:, to:, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
95
- view = activity_view(activity, snapshots, group)
94
+ view = activity_view(activity, snapshots, group, version_scope)
96
95
  Endpoint.validate_root!(record)
97
- @traversal_preparer.call(record.class, historical: true)
98
- from, to = default_range(record, from, to, within)
99
- live = live_endpoint_for(record, within)
100
- if activity
101
- return activity_builder(
102
- record, from: from, to: to, within: within, version_scope: version_scope,
103
- live_endpoint: live, view: view
104
- ).analyze
96
+ ReadSnapshot.call([record]) do
97
+ analyze_record(record, from: from, to: to, within: within, activity: activity,
98
+ version_scope: version_scope, view: view)
105
99
  end
106
-
107
- TimelineBuilder.new(
108
- record, from: from, to: to, within: within, version_scope: version_scope,
109
- live_endpoint: live, snapshotter: @timeline_snapshotter
110
- ).analyze
111
100
  end
112
101
 
113
102
  # Analyzes many roots over one shared range, preparing their history once.
114
103
  #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
115
104
  def analyze_many(records, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
116
- analyze_batch(records, within: within, activity: activity, version_scope: version_scope,
117
- view: activity_view(activity, snapshots, group))
105
+ ReadSnapshot.call(records.is_a?(Array) ? records : []) do
106
+ analyze_batch(records, within: within, activity: activity, version_scope: version_scope,
107
+ view: activity_view(activity, snapshots, group, version_scope))
108
+ end
118
109
  end
119
110
 
120
111
  # Selects the roots from a relation before running the ordinary batch, so a
@@ -123,32 +114,22 @@ 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)
127
- check_scope(scope)
128
- # @type var options: report_options
129
- options = { within: within, activity: activity, version_scope: version_scope, view: view }
130
- ScopedAnalysisBuilder.new(
131
- scope, limit: limit, within: within, historical_filter: historical_filter,
132
- max_filter_versions: max_filter_versions, include_deleted: include_deleted,
133
- analyzer: lambda { |records|
134
- analyze_batch(records, within: within, activity: activity,
135
- version_scope: version_scope, view: view)
136
- },
137
- deleted_analyzer: lambda { |identities|
138
- analyze_deleted(scope.all.model, identities, options)
139
- },
140
- # Checkpoints compare a root's own versions, so only activity can
141
- # report a window in which just its associations changed.
142
- activity_tree: (@association_tree if activity)
143
- ).call
117
+ view = activity_view(activity, snapshots, group, version_scope)
118
+ ReadSnapshot.call([scope]) do
119
+ check_scope(scope)
120
+ scoped_builder(scope, limit: limit, within: within, activity: activity,
121
+ version_scope: version_scope, historical_filter: historical_filter,
122
+ max_filter_versions: max_filter_versions,
123
+ include_deleted: include_deleted, view: view).call
124
+ end
144
125
  end
145
126
 
146
127
  private
147
128
 
148
- #: (bool, bool, Symbol?) -> ActivityView
149
- def activity_view(activity, snapshots, group)
129
+ #: (bool, bool, Symbol?, untyped) -> ActivityView
130
+ def activity_view(activity, snapshots, group, version_scope)
150
131
  ActivityView.build(activity: activity, snapshots: snapshots, group: group,
151
- recorded: @recorded)
132
+ recorded: @recorded, version_scope: version_scope)
152
133
  end
153
134
 
154
135
  #: (untyped) -> Hash[Symbol, untyped]
@@ -156,6 +137,32 @@ module PaperTrailDiff
156
137
  @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
157
138
  end
158
139
 
140
+ #: (untyped, from: untyped, to: untyped, within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Analysis
141
+ def analyze_record(record, from:, to:, within:, activity:, version_scope:, view:) # rubocop:disable Metrics/ParameterLists
142
+ @traversal_preparer.call(record.class, historical: true)
143
+ from, to = default_range(record, from, to, within)
144
+ live = live_endpoint_for(record, within)
145
+ builder = if activity
146
+ activity_builder(
147
+ record, from: from, to: to, within: within, version_scope: version_scope,
148
+ live_endpoint: live, view: view
149
+ )
150
+ else
151
+ timeline_builder(record, from: from, to: to, within: within,
152
+ version_scope: version_scope, live_endpoint: live)
153
+ end
154
+ builder.analyze.with_window(builder.window)
155
+ end
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
+
159
166
  #: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
160
167
  def analyze_batch(records, within:, activity:, version_scope:, view:)
161
168
  count = records.is_a?(Array) ? records.length : 0
@@ -164,10 +171,10 @@ module PaperTrailDiff
164
171
  AnalysisBatch.new(
165
172
  records,
166
173
  time_range: within.nil? ? nil : TimeRange.new(within), version_scope: version_scope,
167
- context_required: activity && !@association_tree.empty?,
174
+ context_required: activity && !@association_tree.empty?, traversal: @traversal,
168
175
  live_loader: method(:load_batch_endpoints),
169
176
  history_preparer: @historical_store.method(:prepare_batch),
170
- analyzer: batched_root_analyzer(activity, within: within, view: view)
177
+ analyzer: batched_root_analyzer(activity, view: view)
171
178
  ).call
172
179
  end
173
180
  end
@@ -181,6 +188,14 @@ module PaperTrailDiff
181
188
  @traversal_preparer.call(scope.all.model, historical: true)
182
189
  end
183
190
 
191
+ # The endpoints of the hash comparisons. Anything else is left for the batch to refuse.
192
+ #: (untyped) -> Array[untyped]
193
+ def comparison_endpoints(comparisons)
194
+ return [] unless comparisons.is_a?(Array)
195
+
196
+ comparisons.grep(Hash).flat_map(&:values)
197
+ end
198
+
184
199
  #: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
185
200
  def comparison_batch(comparisons, preparer:)
186
201
  ComparisonBatch.new(
@@ -203,17 +218,37 @@ module PaperTrailDiff
203
218
  #: (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
204
219
  def analyze_deleted(model, identities, options)
205
220
  within = options.fetch(:within)
206
- analyzer = batched_root_analyzer(options.fetch(:activity), within: within,
207
- view: options.fetch(:view))
221
+ analyzer = batched_root_analyzer(options.fetch(:activity), view: options.fetch(:view))
208
222
  DeletedAnalysisBatch.new(
209
223
  model, identities: identities, time_range: within.nil? ? nil : TimeRange.new(within),
210
224
  version_scope: options.fetch(:version_scope),
211
225
  history_preparer: @historical_store.method(:prepare_deleted_batch),
212
- analyzer: analyzer,
226
+ analyzer: analyzer, traversal: @traversal,
213
227
  context_required: options.fetch(:activity) && !@association_tree.empty?
214
228
  ).call
215
229
  end
216
230
 
231
+ #: (untyped, limit: Integer?, within: untyped, activity: bool, version_scope: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, view: ActivityView) -> ScopedAnalysisBuilder
232
+ def scoped_builder(scope, limit:, within:, activity:, version_scope:, historical_filter:, max_filter_versions:, include_deleted:, view:) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
233
+ # @type var options: report_options
234
+ options = { within: within, activity: activity, version_scope: version_scope, view: view }
235
+ ScopedAnalysisBuilder.new(
236
+ scope, limit: limit, within: within, historical_filter: historical_filter,
237
+ max_filter_versions: max_filter_versions, include_deleted: include_deleted,
238
+ analyzer: lambda { |records|
239
+ analyze_batch(records, within: within, activity: activity,
240
+ version_scope: version_scope, view: view)
241
+ },
242
+ deleted_analyzer: lambda { |identities|
243
+ analyze_deleted(scope.all.model, identities, options)
244
+ },
245
+ # Checkpoints compare a root's own versions, so only activity can
246
+ # report a window in which just its associations changed.
247
+ activity_tree: (@association_tree if activity), version_scope: version_scope,
248
+ traversal: @traversal
249
+ )
250
+ end
251
+
217
252
  # @rbs @association_tree: AssociationTree
218
253
  # @rbs @live_endpoints: LiveEndpointProvider
219
254
  # @rbs @instrumentation_payload: Hash[Symbol, untyped]
@@ -296,21 +331,19 @@ module PaperTrailDiff
296
331
  )
297
332
  end
298
333
 
299
- #: (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
300
- def batched_root_analyzer(activity, within:, view:)
334
+ #: (bool, view: ActivityView) -> BatchedRootAnalyzer
335
+ def batched_root_analyzer(activity, view:)
301
336
  BatchedRootAnalyzer.new(
302
- tree: @association_tree,
303
337
  timeline_snapshotter: @timeline_snapshotter,
304
338
  activity_snapshotter: @activity_snapshotter,
305
339
  preparer: @traversal_preparer.method(:call),
306
- activity: activity, within: within, view: view
340
+ activity: activity, view: view, traversal: @traversal
307
341
  )
308
342
  end
309
343
 
310
344
  #: () -> HistoricalSnapshotStore
311
345
  def build_historical_store
312
346
  HistoricalSnapshotStore.new(
313
- tree: @association_tree,
314
347
  traversal: @traversal,
315
348
  normalizer: @normalizer,
316
349
  preparer: @traversal_preparer.method(:call)
@@ -321,14 +354,14 @@ module PaperTrailDiff
321
354
  #: (PreparedActivitySnapshots) -> BranchSnapshotRefresher
322
355
  def branch_refresher(snapshots)
323
356
  BranchSnapshotRefresher.new(
324
- tree: @association_tree, ignore_policy: @ignore_policy,
325
- traversal: @traversal, pool: @snapshot_pool,
357
+ ignore_policy: @ignore_policy, traversal: @traversal, pool: @snapshot_pool,
326
358
  normalizer: @normalizer,
327
359
  full_snapshotter: snapshots.method(:call),
328
360
  partial_snapshotter: snapshots.method(:custom),
329
361
  association_reader: snapshots.method(:association_reader),
330
362
  record_transition: snapshots.method(:record_transition),
331
- prepared_record_after: snapshots.method(:record_after)
363
+ prepared_record_after: snapshots.method(:record_after),
364
+ root_state: snapshots.method(:root_state)
332
365
  )
333
366
  end
334
367
 
@@ -338,11 +371,10 @@ module PaperTrailDiff
338
371
  record,
339
372
  range: TimelineRange.new(
340
373
  record, from: from, to: to, within: within, version_scope: version_scope,
341
- live_endpoint: live_endpoint
374
+ live_endpoint: live_endpoint, traversal: @traversal
342
375
  ),
343
- tree: @association_tree,
344
376
  snapshotter: @activity_snapshotter,
345
- view: view
377
+ view: view, traversal: @traversal
346
378
  )
347
379
  end
348
380